# SUI

> SUI is a collection of composable React components built on Base UI and Tailwind CSS. These documents include complete examples from the workspace.

# CLI

Search, inspect, install, and update SUI source with shadcn.

Page: https://sui.draco.dev/docs/cli

SUI uses the shadcn CLI. Complete the [registry configuration](/docs/installation#prepare-the-consuming-application) in the consuming application, then run commands from that application's directory.

## Search and inspect

```bash
bunx --bun shadcn@latest search @sui -q input
bunx --bun shadcn@latest view @sui/sensitive-input
```

Search matches registry names and descriptions. View shows a manifest's files and dependencies before you install it. The [registry guide](/docs/registry) explains the catalog and item formats.

## Install source

```bash
bunx --bun shadcn@latest add @sui/button @sui/sensitive-input
bunx --bun shadcn@latest add @sui/data-table
```

The CLI copies required source files into your configured `ui`, `components`, `lib`, and `hooks` directories, installs package dependencies, and merges SUI styles into the CSS file in `components.json`. Files become part of your application and can be edited locally.

Each item carries its local dependency closure. Installing a component does not require first installing the entire library. Use `@sui/sui` for the complete collection, `@sui/sui-style` for shared CSS, or `@sui/sui-theme` for the theme helpers and styles.

Editor and the complete collection require the local Monaco worker setup described in [compatibility](/docs/compatibility#editor-workers).

## Review an update

```bash
bunx --bun shadcn@latest add @sui/button --dry-run
bunx --bun shadcn@latest add @sui/button --diff
```

An update can affect shared dependencies and CSS as well as the requested component. Compare changes with your local edits before accepting an overwrite. Installation is a source copy; installed files do not automatically follow future changes in the SUI repository.

## Common issues

| Symptom | Check |
| --- | --- |
| Unknown `@sui` registry | Run from the consuming application and check its `components.json`. |
| GitHub returns `404` | Check the configured URL and whether the requested item is available in the registry. |
| Import path differs from a docs example | Follow configured aliases, rather than workspace paths. See [import mapping](/docs/installation#import-installed-source). |
| Missing animation or theme styles | Confirm the configured CSS file is imported by the application. |
| Monaco worker import fails | Use a compatible `?worker` loader and include the installed declaration file. |

For installation through an assistant, see [MCP](/docs/mcp). For API and example text, see [LLMs](/docs/llms-txt).


---

# Compatibility

Application responsibilities, SSR, worker loading, and browser capabilities.

Page: https://sui.draco.dev/docs/compatibility

SUI targets React 19 and Tailwind CSS 4 with Base UI primitives. Source installation uses your application's aliases and CSS entrypoint; see [installation](/docs/installation). Modern CSS features, including OKLCH colors and backdrop filters, are part of the visual system.

## SSR and application state

The documentation site uses TanStack Start and SSR. Browser-dependent viewers and the editor initialize after mounting, with base content or skeletons while loading. In an application with server and client component boundaries, keep interactive components on the client side and preserve installed `use client` directives.

Theme persistence, language routing, validation, and business requests belong to the application. ThemeToggle and LocaleToggle receive controlled values and callbacks. Blocks provide English defaults and accept `labels`; pass translations from your application's locale system. Use [Field](/docs/components/field) to compose labels, descriptions, and validation messages.

## Editor workers

[Editor](/docs/components/editor) loads Monaco and its workers locally. Its installed source uses Vite-compatible `?worker` imports. A different bundler requires an equivalent worker integration; installing source does not configure that bundler automatically. Include the installed `worker.d.ts` in TypeScript's source paths.

CodeViewer and DiffViewer can still show and copy raw content if syntax highlighting fails. The editor and viewers share the Shiki-based highlighting infrastructure.

## Browser features

| Feature | Application consideration |
| --- | --- |
| Clipboard | Browser permissions and a secure context determine availability; the components provide failure feedback. |
| Fullscreen | Browser fullscreen is optional; permission or platform restrictions can prevent entry. |
| Glass | CSS + SVG is the default. Optional WebGPU enhancement falls back when capabilities or capture fail. |
| Theme transitions | The toggle respects reduced motion and can apply the theme without a view transition. |
| HTML preview | HtmlViewer defaults to a sandbox with scripts allowed and without same-origin permission. Editor's built-in HTML preview disables scripts. |

See [Glass limitations](/docs/components/glass#limits) for cross-origin images, frames, video, Canvas, and capture cadence. A transparent surface needs to remain readable over its actual background; use an ordinary or denser surface when needed.

## Accessibility and direction

Compose visible labels or accessible names for icon-only actions. Keep titles in dialogs, provide image descriptions, and use externally supplied labels for loading and feedback. Keyboard and focus behavior come from the underlying primitives; replacing native controls with custom markup can change those behaviors.

Use [Direction](/docs/components/direction) for RTL context and keep the application's `dir` attribute consistent. Loader and theme transitions honor reduced-motion preferences; custom animations added by the application need the same consideration.

## Verification

After installation, run the consuming application's type checks and production build. Test its keyboard flow, forms, overlays, copy feedback, themes, and translated labels. The SUI documentation examples exercise components locally; they do not verify your application's routing, persistence, API requests, or deployment.


---

# Design guidelines

Complete typography, spacing, surface, and interaction rules with recommended and avoid examples for every rule.

Page: https://sui.draco.dev/docs/design-guidelines

Apply all of these rules when composing application interfaces with SUI. Every rule includes a working visual comparison and copyable code. Styles in the avoid column are teaching examples and should not be used in product interfaces.

## Shared styles and semantic colors

Import `@workspace/ui/globals.css` and compose components from `@workspace/ui/components/*`. Style native text elements with Tailwind size and weight utilities. Use semantic tokens such as `bg-background`, `bg-card`, `text-foreground`, `text-muted-foreground`, `bg-primary`, `border-border`, and `ring-ring`; keep destructive actions on their independent `destructive` tokens.

The default appearance uses Apple-inspired neutral surfaces and a blue accent. Select shared palettes with `data-color`: `default`, `bamboo`, `mauve`, `mist`, `sand`, `pine`, or `rose`. Remove the attribute or select `default` to reset the appearance; use `dark` for dark mode. Accent, focus, and chart colors change together while backgrounds and body text remain neutral. See [Theming](/docs/theming) for configuration.

```css
@import "@workspace/ui/globals.css";
```

```html
<html data-color="pine" class="dark">
```

## Use 14px for content text

All content text—body, buttons, data, other interactables—must be 14px in size. 16px and above are restricted to headings and subheadings.

### Example: design-guidelines-content-text-size

```tsx
import { DesignComparison } from "../design-guidelines-comparison";
import type { ExampleProps } from "../types";

function RecommendedSample({ locale }: ExampleProps) {
  const zh = locale === "zh-CN";
  return <p className="text-sm">{zh ? "内容文字" : "Content text"}</p>;
}

function AvoidSample({ locale }: ExampleProps) {
  const zh = locale === "zh-CN";
  return <p className="text-base">{zh ? "内容文字" : "Content text"}</p>;
}

export default function Example({ locale }: ExampleProps) {
  return (
    <DesignComparison
      locale={locale}
      recommended={<RecommendedSample locale={locale} />}
      avoid={<AvoidSample locale={locale} />}
    />
  );
}
```

**Recommended**

```tsx
<p className="text-sm">Content text</p>;
```

**Avoid**

```tsx
<p className="text-base">Content text</p>;
```

## Always sentence case headings

Never capitalize or uppercase headings. Product names must be title-cased.

The avoid column shows both title case and an `uppercase` transformation.

### Example: design-guidelines-heading-case

```tsx
import { DesignComparison } from "../design-guidelines-comparison";
import type { ExampleProps } from "../types";

function RecommendedSample() {
  return <h2 className="font-semibold text-lg">Recent requests</h2>;
}

function AvoidSample() {
  return (
    <div className="grid gap-4">
      <h2 className="font-semibold text-lg">Recent Requests</h2>
      <h2 className="font-semibold text-lg uppercase">Recent requests</h2>
    </div>
  );
}

export default function Example({ locale }: ExampleProps) {
  return (
    <DesignComparison
      locale={locale}
      recommended={<RecommendedSample />}
      avoid={<AvoidSample />}
    />
  );
}
```

**Recommended**

```tsx
<h2 className="font-semibold text-lg">Recent requests</h2>;
```

**Avoid**

```tsx
<h2 className="font-semibold text-lg">Recent Requests</h2>;
```

```tsx
<h2 className="font-semibold text-lg uppercase">Recent requests</h2>;
```

## Never change the font’s tracking

Do not use the `tracking-*` classes to change the spacing between characters.

### Example: design-guidelines-font-tracking

```tsx
import { DesignComparison } from "../design-guidelines-comparison";
import type { ExampleProps } from "../types";

function RecommendedSample({ locale }: ExampleProps) {
  const zh = locale === "zh-CN";
  return (
    <h3 className="font-semibold text-lg">
      {zh ? "项目指标" : "Project metrics"}
    </h3>
  );
}

function AvoidSample({ locale }: ExampleProps) {
  const zh = locale === "zh-CN";
  return (
    <h3 className="font-semibold text-lg tracking-tight">
      {zh ? "项目指标" : "Project metrics"}
    </h3>
  );
}

export default function Example({ locale }: ExampleProps) {
  return (
    <DesignComparison
      locale={locale}
      recommended={<RecommendedSample locale={locale} />}
      avoid={<AvoidSample locale={locale} />}
    />
  );
}
```

**Recommended**

```tsx
<h3 className="font-semibold text-lg">Project metrics</h3>;
```

**Avoid**

```tsx
<h3 className="font-semibold text-lg tracking-tight">Project metrics</h3>;
```

## Never use font-bold

Use `font-semibold` for headings and `font-medium` for bold inline text. Never use `font-bold`.

### Example: design-guidelines-font-weight

```tsx
import { DesignComparison } from "../design-guidelines-comparison";
import type { ExampleProps } from "../types";

function RecommendedSample({ locale }: ExampleProps) {
  const zh = locale === "zh-CN";
  return (
    <>
      <h3 className="font-semibold text-lg">
        {zh ? "账户设置" : "Account settings"}
      </h3>
      <strong className="font-medium text-sm">
        {zh ? "必填" : "required"}
      </strong>
    </>
  );
}

function AvoidSample({ locale }: ExampleProps) {
  const zh = locale === "zh-CN";
  return (
    <>
      <h3 className="font-bold text-lg">
        {zh ? "账户设置" : "Account settings"}
      </h3>
      <strong className="font-bold text-sm">{zh ? "必填" : "required"}</strong>
    </>
  );
}

export default function Example({ locale }: ExampleProps) {
  return (
    <DesignComparison
      locale={locale}
      recommended={<RecommendedSample locale={locale} />}
      avoid={<AvoidSample locale={locale} />}
    />
  );
}
```

**Recommended**

```tsx
<>
  <h3 className="font-semibold text-lg">Account settings</h3>
  <strong className="font-medium text-sm">required</strong>
</>;
```

**Avoid**

```tsx
<>
  <h3 className="font-bold text-lg">Account settings</h3>
  <strong className="font-bold text-sm">required</strong>
</>;
```

## Put related text closer together

Related text should have smaller spacing around it than the content it belongs to.

### Example: design-guidelines-related-text-spacing

```tsx
import { Button } from "@workspace/ui/components/button";
import { DesignComparison } from "../design-guidelines-comparison";
import type { ExampleProps } from "../types";

function RecommendedSample({ locale }: ExampleProps) {
  const zh = locale === "zh-CN";
  return (
    <div className="grid gap-6">
      <div className="grid gap-1.5">
        <h3 className="font-semibold text-lg">
          {zh ? "网站分析" : "Web analytics"}
        </h3>
        <p className="text-sm">
          {zh
            ? "无需修改代码即可衡量网站访问量"
            : "Measure site traffic without changing your code."}
        </p>
      </div>
      <Button>{zh ? "配置" : "Configure"}</Button>
    </div>
  );
}

function AvoidSample({ locale }: ExampleProps) {
  const zh = locale === "zh-CN";
  return (
    <div className="grid gap-4">
      <h3 className="font-semibold text-lg">
        {zh ? "网站分析" : "Web analytics"}
      </h3>
      <p className="text-sm">
        {zh
          ? "无需修改代码即可衡量网站访问量"
          : "Measure site traffic without changing your code."}
      </p>
      <Button>{zh ? "配置" : "Configure"}</Button>
    </div>
  );
}

export default function Example({ locale }: ExampleProps) {
  return (
    <DesignComparison
      locale={locale}
      recommended={<RecommendedSample locale={locale} />}
      avoid={<AvoidSample locale={locale} />}
    />
  );
}
```

**Recommended**

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

<div className="grid gap-6">
  <div className="grid gap-1.5">
    <h3 className="font-semibold text-lg">Web analytics</h3>
    <p className="text-sm">Measure site traffic without changing your code.</p>
  </div>
  <Button>Configure</Button>
</div>;
```

**Avoid**

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

<div className="grid gap-4">
  <h3 className="font-semibold text-lg">Web analytics</h3>
  <p className="text-sm">Measure site traffic without changing your code.</p>
  <Button>Configure</Button>
</div>;
```

## Optically align spacing around text

Spacing around text should take into account its line height. Typically this means vertical spacing should be slightly smaller than horizontal.

### Example: design-guidelines-text-spacing

```tsx
import { Card } from "@workspace/ui/components/card";
import { DesignComparison } from "../design-guidelines-comparison";
import type { ExampleProps } from "../types";

function RecommendedSample({ locale }: ExampleProps) {
  const zh = locale === "zh-CN";
  return <Card className="px-5 py-4">{zh ? "内容文字" : "Content text"}</Card>;
}

function AvoidSample({ locale }: ExampleProps) {
  const zh = locale === "zh-CN";
  return <Card className="p-5">{zh ? "内容文字" : "Content text"}</Card>;
}

export default function Example({ locale }: ExampleProps) {
  return (
    <DesignComparison
      locale={locale}
      recommended={<RecommendedSample locale={locale} />}
      avoid={<AvoidSample locale={locale} />}
    />
  );
}
```

**Recommended**

```tsx
import { Card } from "@workspace/ui/components/card";

<Card className="px-5 py-4">Content text</Card>;
```

**Avoid**

```tsx
import { Card } from "@workspace/ui/components/card";

<Card className="p-5">Content text</Card>;
```

## Never transition colors for hover states

Color changes on hover must be immediate. Transitions on fast interactions make the UI feel sluggish.

Move the pointer between the two buttons to compare their response. SUI buttons can still transition `transform` and `box-shadow`; the hover color changes immediately.

### Example: design-guidelines-hover-color-transitions

```tsx
import { Button } from "@workspace/ui/components/button";
import { DesignComparison } from "../design-guidelines-comparison";
import type { ExampleProps } from "../types";

function RecommendedSample({ locale }: ExampleProps) {
  const zh = locale === "zh-CN";
  return (
    <Button variant="ghost" className="hover:bg-muted">
      {zh ? "悬停查看" : "Hover me"}
    </Button>
  );
}

function AvoidSample({ locale }: ExampleProps) {
  const zh = locale === "zh-CN";
  return (
    <Button
      variant="ghost"
      className="transition-colors duration-300 hover:bg-muted"
    >
      {zh ? "悬停查看" : "Hover me"}
    </Button>
  );
}

export default function Example({ locale }: ExampleProps) {
  return (
    <DesignComparison
      locale={locale}
      recommended={<RecommendedSample locale={locale} />}
      avoid={<AvoidSample locale={locale} />}
    />
  );
}
```

**Recommended**

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

<Button variant="ghost" className="hover:bg-muted">
  Hover me
</Button>;
```

**Avoid**

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

<Button
  variant="ghost"
  className="transition-colors duration-300 hover:bg-muted"
>
  Hover me
</Button>;
```

## Never use borders with drop shadows

Use `ring-1 ring-border` to create a transparent border that maintains sharp edges. Do not combine `border` with a drop shadow on the same surface.

SUI Card already supplies a shadow and a subtle ring. The avoid example disables that ring to show the border-and-shadow combination explicitly.

### Example: design-guidelines-shadow-borders

```tsx
import { Card } from "@workspace/ui/components/card";
import { DesignComparison } from "../design-guidelines-comparison";
import type { ExampleProps } from "../types";

function RecommendedSample({ locale }: ExampleProps) {
  const zh = locale === "zh-CN";
  return (
    <Card className="px-4 shadow-md ring-1 ring-border">
      {zh ? "内容文字" : "Content text"}
    </Card>
  );
}

function AvoidSample({ locale }: ExampleProps) {
  const zh = locale === "zh-CN";
  return (
    <Card className="border border-border px-4 shadow-md ring-0">
      {zh ? "内容文字" : "Content text"}
    </Card>
  );
}

export default function Example({ locale }: ExampleProps) {
  return (
    <DesignComparison
      locale={locale}
      recommended={<RecommendedSample locale={locale} />}
      avoid={<AvoidSample locale={locale} />}
    />
  );
}
```

**Recommended**

```tsx
import { Card } from "@workspace/ui/components/card";

<Card className="px-4 shadow-md ring-1 ring-border">Content text</Card>;
```

**Avoid**

```tsx
import { Card } from "@workspace/ui/components/card";

<Card className="border border-border px-4 shadow-md ring-0">
  Content text
</Card>;
```

## Use concentric border radii

When borders or rings are 8px or less apart, their corner radii must be mathematically concentric: outer radius = inner radius + padding.

At the default SUI radius, `rounded-lg` is 10px, `rounded-xl` is 14px, and `p-1` is 4px. The radius scale uses fixed offsets: `xl` adds `0.25rem`, `2xl` adds `0.5rem`, `3xl` adds `0.75rem`, and `4xl` adds `1rem` to the base radius. Changing `--radius` preserves those gaps. `sm` and `md` subtract `0.25rem` and `0.125rem`, clamped at zero.

Pair `rounded-xl` outside with `rounded-lg` inside and `p-1`; use `rounded-2xl` outside with `p-2`. For other padding values, calculate the outer radius as the inner radius plus that padding. The scale alone does not make arbitrary combinations concentric. Change the base radius below to compare the two examples.

If the outer container uses a `border`, include its width in the distance between the two boxes. A `ring` does not occupy layout space.

### Example: design-guidelines-concentric-border-radius

```tsx
import { DesignComparison } from "../design-guidelines-comparison";
import type { ExampleProps } from "../types";

function RecommendedSample({ locale }: ExampleProps) {
  const zh = locale === "zh-CN";
  return (
    <div className="rounded-xl bg-muted p-1 ring-1 ring-border">
      <div className="rounded-lg bg-background p-4 ring-1 ring-border">
        {zh ? "内容文字" : "Content text"}
      </div>
    </div>
  );
}

function AvoidSample({ locale }: ExampleProps) {
  const zh = locale === "zh-CN";
  return (
    <div className="rounded-xl bg-muted p-1 ring-1 ring-border">
      <div className="rounded-xl bg-background p-4 ring-1 ring-border">
        {zh ? "内容文字" : "Content text"}
      </div>
    </div>
  );
}

export default function Example({ locale }: ExampleProps) {
  const zh = locale === "zh-CN";
  const [radius, setRadius] = useState(10);
  return (
    <div
      className="w-full space-y-4"
      style={{ "--radius": `${radius}px` } as CSSProperties}
    >
      <fieldset className="flex flex-wrap items-center gap-2">
        <legend className="mb-2 text-sm">
          {zh ? "基准圆角" : "Base radius"}
        </legend>
        {[0, 4, 10, 16].map((value) => (
          <Button
            key={value}
            type="button"
            size="sm"
            variant={radius === value ? "default" : "outline"}
            aria-pressed={radius === value}
            onClick={() => setRadius(value)}
          >
            {value}px
          </Button>
        ))}
      </fieldset>
      <DesignComparison
        locale={locale}
        recommended={<RecommendedSample locale={locale} />}
        avoid={<AvoidSample locale={locale} />}
      />
    </div>
  );
}

import { Button } from "@workspace/ui/components/button";
import { type CSSProperties, useState } from "react";
```

**Recommended**

```tsx
<div className="rounded-xl bg-muted p-1 ring-1 ring-border">
  <div className="rounded-lg bg-background p-4 ring-1 ring-border">
    Content text
  </div>
</div>;
```

**Avoid**

```tsx
<div className="rounded-xl bg-muted p-1 ring-1 ring-border">
  <div className="rounded-xl bg-background p-4 ring-1 ring-border">
    Content text
  </div>
</div>;
```

## Align icons with the first line of text

Inline icons must be optically the same size as and be center-aligned with text. Use `h-lh flex items-center` for multi-line alignment.

The avoid column includes both a missing line-height wrapper and vertical centering against the entire paragraph. Decorative icons use `aria-hidden`; icon-only actions need an accessible name.

### Example: design-guidelines-icon-alignment

```tsx
import { InfoIcon } from "lucide-react";
import { DesignComparison } from "../design-guidelines-comparison";
import type { ExampleProps } from "../types";

function RecommendedSample({ locale }: ExampleProps) {
  const zh = locale === "zh-CN";
  return (
    <div className="flex items-start gap-2 text-sm leading-6">
      <span className="flex h-lh items-center">
        <InfoIcon className="size-4" aria-hidden="true" />
      </span>
      <p>
        {zh
          ? "这段文字可能会换行，但图标仍应与第一行保持对齐"
          : "Text that may wrap onto multiple lines and still align with the icon."}
      </p>
    </div>
  );
}

function AvoidSample({ locale }: ExampleProps) {
  const zh = locale === "zh-CN";
  return (
    <div className="grid gap-4">
      <div className="flex items-start gap-2 text-sm leading-6">
        <span className="flex items-center">
          <InfoIcon className="size-4" aria-hidden="true" />
        </span>
        <p>
          {zh
            ? "这段文字可能会换行，但图标仍应与第一行保持对齐"
            : "Text that may wrap onto multiple lines and still align with the icon."}
        </p>
      </div>
      <div className="flex items-center gap-2 text-sm leading-6">
        <InfoIcon className="size-4" aria-hidden="true" />
        <p>
          {zh
            ? "这段文字可能会换行，但图标仍应与第一行保持对齐"
            : "Text that may wrap onto multiple lines and still align with the icon."}
        </p>
      </div>
    </div>
  );
}

export default function Example({ locale }: ExampleProps) {
  return (
    <DesignComparison
      locale={locale}
      recommended={<RecommendedSample locale={locale} />}
      avoid={<AvoidSample locale={locale} />}
    />
  );
}
```

**Recommended**

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

<div className="flex items-start gap-2 text-sm leading-6">
  <span className="flex h-lh items-center">
    <InfoIcon className="size-4" aria-hidden="true" />
  </span>
  <p>Text that may wrap onto multiple lines and still align with the icon.</p>
</div>;
```

**Avoid**

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

<div className="flex items-start gap-2 text-sm leading-6">
  <span className="flex items-center">
    <InfoIcon className="size-4" aria-hidden="true" />
  </span>
  <p>Text that may wrap onto multiple lines and still align with the icon.</p>
</div>;
```

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

<div className="flex items-center gap-2 text-sm leading-6">
  <InfoIcon className="size-4" aria-hidden="true" />
  <p>Text that may wrap onto multiple lines and still align with the icon.</p>
</div>;
```

## Reduce the font size of inline monospaced text

Monospaced text should have a slightly smaller font size (~0.9em) when mixed with regular text.

### Example: design-guidelines-inline-monospace-size

```tsx
import { DesignComparison } from "../design-guidelines-comparison";
import type { ExampleProps } from "../types";

function RecommendedSample({ locale }: ExampleProps) {
  const zh = locale === "zh-CN";
  return (
    <p className="text-sm">
      {zh ? "编辑 " : "Edit "}
      <code className="font-mono text-[0.9em]">config.ts</code>
      {zh ? " 后继续" : " to continue."}
    </p>
  );
}

function AvoidSample({ locale }: ExampleProps) {
  const zh = locale === "zh-CN";
  return (
    <p className="text-sm">
      {zh ? "编辑 " : "Edit "}
      <code className="font-mono">config.ts</code>
      {zh ? " 后继续" : " to continue."}
    </p>
  );
}

export default function Example({ locale }: ExampleProps) {
  return (
    <DesignComparison
      locale={locale}
      recommended={<RecommendedSample locale={locale} />}
      avoid={<AvoidSample locale={locale} />}
    />
  );
}
```

**Recommended**

```tsx
<p className="text-sm">
  Edit <code className="font-mono text-[0.9em]">config.ts</code> to continue.
</p>;
```

**Avoid**

```tsx
<p className="text-sm">
  Edit <code className="font-mono">config.ts</code> to continue.
</p>;
```

## Use a border to separate sticky elements

Use `border` to separate sticky elements from the content.

Scroll each column to inspect the boundary under its sticky header. A separating border is appropriate here because the header has no drop shadow.

### Example: design-guidelines-sticky-borders

```tsx
import { DesignComparison } from "../design-guidelines-comparison";
import type { ExampleProps } from "../types";

function RecommendedSample({ locale }: ExampleProps) {
  const zh = locale === "zh-CN";
  return (
    <div className="h-40 overflow-y-auto rounded-xl bg-muted">
      <div className="sticky top-0 border-border border-b bg-background px-3 py-2">
        {zh ? "最近请求" : "Recent requests"}
      </div>
      <div className="grid gap-4 p-3">
        {Array.from({ length: 8 }, (_, index) => ({
          id: `request-${index + 1}`,
          number: index + 1,
        })).map((request) => (
          <p key={request.id}>
            {zh ? "请求" : "Request"} {request.number}
          </p>
        ))}
      </div>
    </div>
  );
}

function AvoidSample({ locale }: ExampleProps) {
  const zh = locale === "zh-CN";
  return (
    <div className="h-40 overflow-y-auto rounded-xl bg-muted">
      <div className="sticky top-0 bg-background px-3 py-2">
        {zh ? "最近请求" : "Recent requests"}
      </div>
      <div className="grid gap-4 p-3">
        {Array.from({ length: 8 }, (_, index) => ({
          id: `request-${index + 1}`,
          number: index + 1,
        })).map((request) => (
          <p key={request.id}>
            {zh ? "请求" : "Request"} {request.number}
          </p>
        ))}
      </div>
    </div>
  );
}

export default function Example({ locale }: ExampleProps) {
  return (
    <DesignComparison
      locale={locale}
      recommended={<RecommendedSample locale={locale} />}
      avoid={<AvoidSample locale={locale} />}
    />
  );
}
```

**Recommended**

```tsx
<div className="h-40 overflow-y-auto rounded-xl bg-muted">
  <div className="sticky top-0 border-b border-border bg-background px-3 py-2">
    Recent requests
  </div>
  <div className="grid gap-4 p-3">
    {Array.from({ length: 8 }, (_, index) => ({
      id: `request-${index + 1}`,
      number: index + 1,
    })).map((request) => (
      <p key={request.id}>Request {request.number}</p>
    ))}
  </div>
</div>;
```

**Avoid**

```tsx
<div className="h-40 overflow-y-auto rounded-xl bg-muted">
  <div className="sticky top-0 bg-background px-3 py-2">Recent requests</div>
  <div className="grid gap-4 p-3">
    {Array.from({ length: 8 }, (_, index) => ({
      id: `request-${index + 1}`,
      number: index + 1,
    })).map((request) => (
      <p key={request.id}>Request {request.number}</p>
    ))}
  </div>
</div>;
```

## Maintain content size during collapse animations

Collapsible content must maintain its content size while closing to avoid its content shifting during animations.

Toggle each panel and watch the paragraph. Animate the outer wrapper from 256px to 0 while keeping the recommended inner content at `w-64`; the avoid example shrinks the text container and changes its line breaks. Reduced motion removes the transition.

### Example: design-guidelines-collapse-content-size

```tsx
"use client";

import { Button } from "@workspace/ui/components/button";
import { useReducedMotion } from "@workspace/ui/hooks/use-reduced-motion";
import { motion } from "motion/react";
import { useState } from "react";
import { DesignComparison } from "../design-guidelines-comparison";
import type { ExampleProps } from "../types";

function RecommendedSample({ locale }: ExampleProps) {
  const zh = locale === "zh-CN";
  const [open, setOpen] = useState(true);
  const reduce = useReducedMotion();
  return (
    <div className="grid gap-4">
      <Button variant="outline" onClick={() => setOpen(!open)}>
        {zh ? "切换面板" : "Toggle panel"}
      </Button>
      <motion.div
        initial={false}
        animate={{ width: open ? 256 : 0 }}
        transition={{ duration: reduce ? 0 : 0.4 }}
        className="max-w-full overflow-hidden"
      >
        <div className="w-64 rounded-xl bg-muted p-3 text-sm">
          {zh
            ? "面板关闭时，这段文字应保持相同的换行，不要在动画过程中重新排版"
            : "Text should keep the same line breaks while this panel closes."}
        </div>
      </motion.div>
    </div>
  );
}

function AvoidSample({ locale }: ExampleProps) {
  const zh = locale === "zh-CN";
  const [open, setOpen] = useState(true);
  const reduce = useReducedMotion();
  return (
    <div className="grid gap-4">
      <Button variant="outline" onClick={() => setOpen(!open)}>
        {zh ? "切换面板" : "Toggle panel"}
      </Button>
      <motion.div
        initial={false}
        animate={{ width: open ? 256 : 0 }}
        transition={{ duration: reduce ? 0 : 0.4 }}
        className="max-w-full overflow-hidden"
      >
        <div className="w-full min-w-0 rounded-xl bg-muted p-3 text-sm">
          {zh
            ? "面板关闭时，这段文字应保持相同的换行，不要在动画过程中重新排版"
            : "Text should keep the same line breaks while this panel closes."}
        </div>
      </motion.div>
    </div>
  );
}

export default function Example({ locale }: ExampleProps) {
  return (
    <DesignComparison
      locale={locale}
      recommended={<RecommendedSample locale={locale} />}
      avoid={<AvoidSample locale={locale} />}
    />
  );
}
```

**Recommended**

```tsx
import { Button } from "@workspace/ui/components/button";
import { useReducedMotion } from "@workspace/ui/hooks/use-reduced-motion";
import { motion } from "motion/react";
import { useState } from "react";

export function RecommendedExample() {
  const [open, setOpen] = useState(true);
  const reduce = useReducedMotion();
  return (
    <div className="grid gap-4">
      <Button variant="outline" onClick={() => setOpen(!open)}>
        Toggle panel
      </Button>
      <motion.div
        initial={false}
        animate={{ width: open ? 256 : 0 }}
        transition={{ duration: reduce ? 0 : 0.4 }}
        className="max-w-full overflow-hidden"
      >
        <div className="w-64 rounded-xl bg-muted p-3 text-sm">
          Text should keep the same line breaks while this panel closes.
        </div>
      </motion.div>
    </div>
  );
}
```

**Avoid**

```tsx
import { Button } from "@workspace/ui/components/button";
import { useReducedMotion } from "@workspace/ui/hooks/use-reduced-motion";
import { motion } from "motion/react";
import { useState } from "react";

export function AvoidExample() {
  const [open, setOpen] = useState(true);
  const reduce = useReducedMotion();
  return (
    <div className="grid gap-4">
      <Button variant="outline" onClick={() => setOpen(!open)}>
        Toggle panel
      </Button>
      <motion.div
        initial={false}
        animate={{ width: open ? 256 : 0 }}
        transition={{ duration: reduce ? 0 : 0.4 }}
        className="max-w-full overflow-hidden"
      >
        <div className="w-full min-w-0 rounded-xl bg-muted p-3 text-sm">
          Text should keep the same line breaks while this panel closes.
        </div>
      </motion.div>
    </div>
  );
}
```

## Never stack elevated cards

Never stack elevated cards on top of one another.

Use a plain container, spacing, or separators to group content inside a card. The recommended heading sits outside the elevated surface.

### Example: design-guidelines-layer-card-nesting

```tsx
import { Card } from "@workspace/ui/components/card";
import { DesignComparison } from "../design-guidelines-comparison";
import type { ExampleProps } from "../types";

function RecommendedSample({ locale }: ExampleProps) {
  const zh = locale === "zh-CN";
  return (
    <div className="grid gap-3">
      <h3 className="font-semibold text-lg">
        {zh ? "最近请求" : "Recent requests"}
      </h3>
      <Card size="sm" className="px-4">
        {zh ? "请求数据" : "Request data"}
      </Card>
    </div>
  );
}

function AvoidSample({ locale }: ExampleProps) {
  const zh = locale === "zh-CN";
  return (
    <Card size="sm" className="px-4">
      <h3 className="font-semibold text-lg">
        {zh ? "最近请求" : "Recent requests"}
      </h3>
      <Card size="sm" className="px-4">
        {zh ? "请求数据" : "Request data"}
      </Card>
    </Card>
  );
}

export default function Example({ locale }: ExampleProps) {
  return (
    <DesignComparison
      locale={locale}
      recommended={<RecommendedSample locale={locale} />}
      avoid={<AvoidSample locale={locale} />}
    />
  );
}
```

**Recommended**

```tsx
import { Card } from "@workspace/ui/components/card";

<div className="grid gap-3">
  <h3 className="font-semibold text-lg">Recent requests</h3>
  <Card size="sm" className="px-4">
    Request data
  </Card>
</div>;
```

**Avoid**

```tsx
import { Card } from "@workspace/ui/components/card";

<Card size="sm" className="px-4">
  <h3 className="font-semibold text-lg">Recent requests</h3>
  <Card size="sm" className="px-4">
    Request data
  </Card>
</Card>;
```

## Never conditionally render dialogs

Conditionally rendering dialogs disables their open/close animation. Use the `open` prop to determine if a dialog should be visible or not.

Open and close both dialogs. The recommended `Dialog` remains in the React tree while Base UI manages the popup’s presence, exit animation, focus, and dismissal. In the avoid example, setting `open` to false immediately removes the entire dialog tree. Always include a title and description.

### Example: design-guidelines-dialog-rendering

```tsx
"use client";

import { Button } from "@workspace/ui/components/button";
import {
  Dialog,
  DialogClose,
  DialogContent,
  DialogDescription,
  DialogHeader,
  DialogTitle,
  DialogTrigger,
} from "@workspace/ui/components/dialog";
import { useState } from "react";
import { DesignComparison } from "../design-guidelines-comparison";
import type { ExampleProps } from "../types";

function RecommendedSample({ locale }: ExampleProps) {
  const zh = locale === "zh-CN";
  const [open, setOpen] = useState(false);
  return (
    <Dialog open={open} onOpenChange={setOpen}>
      <DialogTrigger render={<Button variant="outline" />}>
        {zh ? "打开弹窗" : "Open dialog"}
      </DialogTrigger>
      <DialogContent showCloseButton={false}>
        <DialogHeader>
          <DialogTitle className="font-semibold">
            {zh ? "编辑项目" : "Edit project"}
          </DialogTitle>
          <DialogDescription>
            {zh ? "更新此项目的设置" : "Update this project’s settings."}
          </DialogDescription>
        </DialogHeader>
        <DialogClose render={<Button variant="outline" />}>
          {zh ? "关闭" : "Close"}
        </DialogClose>
      </DialogContent>
    </Dialog>
  );
}

function AvoidSample({ locale }: ExampleProps) {
  const zh = locale === "zh-CN";
  const [open, setOpen] = useState(false);
  return (
    <>
      <Button variant="outline" onClick={() => setOpen(true)}>
        {zh ? "打开弹窗" : "Open dialog"}
      </Button>
      {open && (
        <Dialog open={open} onOpenChange={setOpen}>
          <DialogContent showCloseButton={false}>
            <DialogHeader>
              <DialogTitle className="font-semibold">
                {zh ? "编辑项目" : "Edit project"}
              </DialogTitle>
              <DialogDescription>
                {zh ? "更新此项目的设置" : "Update this project’s settings."}
              </DialogDescription>
            </DialogHeader>
            <DialogClose render={<Button variant="outline" />}>
              {zh ? "关闭" : "Close"}
            </DialogClose>
          </DialogContent>
        </Dialog>
      )}
    </>
  );
}

export default function Example({ locale }: ExampleProps) {
  return (
    <DesignComparison
      locale={locale}
      recommended={<RecommendedSample locale={locale} />}
      avoid={<AvoidSample locale={locale} />}
    />
  );
}
```

**Recommended**

```tsx
import { Button } from "@workspace/ui/components/button";
import {
  Dialog,
  DialogClose,
  DialogContent,
  DialogDescription,
  DialogHeader,
  DialogTitle,
  DialogTrigger,
} from "@workspace/ui/components/dialog";
import { useState } from "react";

export function RecommendedExample() {
  const [open, setOpen] = useState(false);
  return (
    <Dialog open={open} onOpenChange={setOpen}>
      <DialogTrigger render={<Button variant="outline" />}>
        Open dialog
      </DialogTrigger>
      <DialogContent showCloseButton={false}>
        <DialogHeader>
          <DialogTitle className="font-semibold">Edit project</DialogTitle>
          <DialogDescription>Update this project’s settings.</DialogDescription>
        </DialogHeader>
        <DialogClose render={<Button variant="outline" />}>Close</DialogClose>
      </DialogContent>
    </Dialog>
  );
}
```

**Avoid**

```tsx
import { Button } from "@workspace/ui/components/button";
import {
  Dialog,
  DialogClose,
  DialogContent,
  DialogDescription,
  DialogHeader,
  DialogTitle,
  DialogTrigger,
} from "@workspace/ui/components/dialog";
import { useState } from "react";

export function AvoidExample() {
  const [open, setOpen] = useState(false);
  return (
    <>
      <Button variant="outline" onClick={() => setOpen(true)}>
        Open dialog
      </Button>
      {open && (
        <Dialog open={open} onOpenChange={setOpen}>
          <DialogContent showCloseButton={false}>
            <DialogHeader>
              <DialogTitle className="font-semibold">Edit project</DialogTitle>
              <DialogDescription>
                Update this project’s settings.
              </DialogDescription>
            </DialogHeader>
            <DialogClose render={<Button variant="outline" />}>
              Close
            </DialogClose>
          </DialogContent>
        </Dialog>
      )}
    </>
  );
}
```


---

# Installation

Install editable SUI source with the shadcn CLI.

Page: https://sui.draco.dev/docs/installation

Install SUI source through its shadcn registry. Components, styles, and dependencies integrate with your application configuration.

## Install through the registry

### Prepare the consuming application

Use React 19, Tailwind CSS 4, and a shadcn project configured for Base UI. In an existing application that has not initialized shadcn, run:

```bash
bunx --bun shadcn@latest init --base base
```

Merge this entry into the application's existing `components.json`. Preserve its CSS path and aliases:

```json
{
  "registries": {
    "@sui": "https://raw.githubusercontent.com/draco-china/sui/main/registry/r/{name}.json"
  }
}
```

The catalog URL is `https://raw.githubusercontent.com/draco-china/sui/main/registry/r/registry.json`. Individual manifests use the same directory.

### Search, inspect, and install

Run the following commands from the consuming application directory:

```bash
bunx --bun shadcn@latest search @sui -q button
bunx --bun shadcn@latest view @sui/button
bunx --bun shadcn@latest add @sui/button @sui/editor
```

Install the business blocks by their registry names:

```bash
bunx --bun shadcn@latest add @sui/data-table @sui/delete-resource @sui/tanstack-form
```

To install the complete collection, including all components and blocks:

```bash
bunx --bun shadcn@latest add @sui/sui
```

Each manifest includes the item's local component dependencies, hooks, helpers, types, package dependencies, and SUI CSS and theme tokens. The CLI installs source into the directories configured by your aliases and merges styles into the configured Tailwind CSS file. Standalone entries `@sui/sui-style` and `@sui/sui-theme` provide the shared styles and theme helpers.

Review the generated files and CSS when adding SUI to an application that already has components with the same names or custom theme values. Preview an update before applying it:

```bash
bunx --bun shadcn@latest add @sui/button --dry-run
bunx --bun shadcn@latest add @sui/button --diff
```

Editor uses locally bundled Monaco workers and requires a Vite-compatible `?worker` loader. Keep the installed `worker.d.ts` in your TypeScript include paths. This also applies when installing the complete collection.

Blocks default to English. Pass labels from your application's locale configuration to customize their visible text; see the [Data Table](/docs/blocks/data-table), [Delete Resource](/docs/blocks/delete-resource), and [TanStack Form](/docs/blocks/tanstack-form) references.

### Import installed source

With the default shadcn aliases, import from your own application:

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

export function SaveButton() {
  return <Button>Save changes</Button>;
}
```

Use the actual aliases in your `components.json` if they differ. Examples throughout this reference use workspace imports such as `@workspace/ui/components/button`. For a registry installation, replace `@workspace/ui/components/*` with your `ui` alias, `@workspace/ui/blocks/*` with your `components` alias followed by `/blocks/*`, and hook or helper imports with your `hooks` or `lib` alias. For example, the default aliases use `@/components/ui/button`, `@/components/blocks/data-table`, and `@/hooks/use-mobile`. The CLI adapts imports inside the installed files automatically.

## Connect the shadcn MCP server

The [MCP guide](/docs/mcp) covers client configuration, project working directories, example requests, and troubleshooting. MCP shares this application's `@sui` registry configuration. For API documentation and complete example text, use [LLMs](/docs/llms-txt).

See [Theming](/docs/theming) for CSS tokens and [Compatibility](/docs/compatibility) for runtime requirements.


---

# Introduction

Start with a component. Build an interface that feels like yours.

Page: https://sui.draco.dev/docs

SUI is a collection of composable React components built with Base UI and Tailwind CSS 4. It brings form controls, navigation, feedback, and content viewers into one visual language. The source lives in `packages/ui`, where you can read it, change it, and compose it for your application.

## Start here

1. **Connect your application.** Follow [Installation](/docs/installation) to add the workspace dependency, load the shared styles, and configure Tailwind to scan the component source.
2. **Try a component.** Browse the [component directory](/docs/components). Each page pairs an interactive preview with the complete example source.
3. **Make it your own.** Use [Theming](/docs/theming) for colors and CSS tokens, and [Design guidelines](/docs/design-guidelines) for typography, spacing, surfaces, and motion.

SUI currently uses the private `@workspace/ui` package inside this Bun workspace. There is no published SUI registry or standalone install command. Start with the installation guide before copying an example.

## Your first component

Once your application is connected, import components from their individual modules:

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

export function SaveButton() {
  return <Button>Save changes</Button>;
}
```

The previews and your application use the same shared package. The code tab shows the full example file, including imports and composition; English and Chinese pages share the same examples.

## Find the right pieces

| What you are building | Start with |
| --- | --- |
| Forms and settings | [Field](/docs/components/field), [Input](/docs/components/input), [Select](/docs/components/select), [Switch](/docs/components/switch) |
| Navigation and feedback | [Tabs](/docs/components/tabs), [Dialog](/docs/components/dialog), [Toast](/docs/components/toast) |
| Content and conversations | [Message](/docs/components/message), [Markdown Viewer](/docs/components/markdown-viewer), [Code Viewer](/docs/components/code-viewer) |
| Optional glass surfaces | [Glass](/docs/components/glass) |

## Compose with intent

Components expose named parts. A dialog combines a trigger, content, title, description, and actions. A field combines a label, control, description, and error. Keep related parts together to preserve their behavior and give each interaction a clear purpose.

Base UI primitives provide keyboard interactions, focus management, and ARIA semantics. Your application still supplies meaningful labels, useful descriptions, and understandable feedback. Test custom compositions with a keyboard and assistive technology.

## Work with the source

- `packages/ui` contains components, shared hooks, CSS tokens, and accent themes.
- `apps/docs` contains the bilingual reference site and runnable examples.
- [CSS utilities](/docs/utils) cover shared effects such as Scroll Fade and Shimmer.

For coding assistants, [llms.txt](/llms.txt) provides the documentation index and [llms-full.txt](/llms-full.txt) includes the full reference and example source. Individual pages also offer Markdown through the page actions.


---

# LLMs

Read SUI documentation and complete examples as plain text.

Page: https://sui.draco.dev/docs/llms-txt

Use the LLM endpoints to give an assistant the current SUI APIs and examples. These endpoints read documentation. Use [MCP](/docs/mcp) or the [CLI](/docs/cli) when you want to install component source.

## Documentation endpoints

| Content | English | 简体中文 |
| --- | --- | --- |
| Index of pages | [`/llms.txt`](/llms.txt) | [`/zh-CN/llms.txt`](/zh-CN/llms.txt) |
| Complete reference | [`/llms-full.txt`](/llms-full.txt) | [`/zh-CN/llms-full.txt`](/zh-CN/llms-full.txt) |
| One component | [Button Markdown](/api/llms-markdown?locale=en-US&slug=components/button) | [Button Markdown](/api/llms-markdown?locale=zh-CN&slug=components/button) |

Use these paths on the current documentation origin. GitHub raw hosts the [registry](/docs/registry) JSON, while the documentation site supplies these text endpoints.

The index groups guides, components, Blocks, and utilities and links to their Markdown. Start with the index and read the relevant pages. The complete reference includes every page and can be much larger than one assistant request needs.

## Read one page

`/api/llms-markdown` accepts `locale` and `slug`:

| Parameter | Values | Default |
| --- | --- | --- |
| `locale` | `en-US`, `zh-CN` | `en-US` |
| `slug` | Document path without `/docs/`, such as `components/button`, `blocks/data-table`, or `theming` | Introduction when omitted |

Unknown locales and documents return `404`. An explicit `/en-US/llms.txt` or `/en-US/llms-full.txt` redirects to the corresponding English path without the prefix.

[Read Sensitive Input Markdown](/api/llms-markdown?locale=en-US&slug=components/sensitive-input)

The result includes the title, description, page URL, API text, and complete source for the page's shared examples. Preview and Code read the same example files, so the text reference stays aligned with the runnable documentation.

## Copy from a document

The page header provides **Copy Markdown** and **Open**. Copy Markdown returns the original MDX document; Open can supply the expanded LLM Markdown to an assistant. For programmatic use, `/api/markdown` returns the original document and `/api/llms-markdown` expands shared examples into code fences.

## Example request

```text
Read SUI's llms.txt, then the Field and Sensitive Input pages.
Compose a labeled secret input with an external validation message.
Keep validation and translated feedback in my application.
Use the import aliases from my components.json when installing source.
```

Examples use workspace imports such as `@workspace/ui/components/button`. After source installation, use your application's configured aliases; the [installation guide](/docs/installation#import-installed-source) explains the mapping. Reading documentation does not install files or configure your MCP client.


---

# MCP

Connect AI assistants to the SUI registry.

Page: https://sui.draco.dev/docs/mcp

Use the official [shadcn MCP server](https://ui.shadcn.com/docs/mcp) to browse the SUI registry from your AI assistant. The server runs locally over stdio and reads the consuming application's `components.json`. SUI supplies registry JSON files; the registry URL is an HTTP data source, not an MCP endpoint.

For API guidance and complete usage examples, provide the assistant with [LLMs documentation](/docs/llms-txt). MCP queries and inspects installable source. Its `get_add_command_for_items` tool returns a CLI command; the assistant then runs the command in your application to install the files.

## Configure the application

Prepare the consuming application using [Installation](/docs/installation). Merge this registry entry into its existing `components.json`, preserving the application's aliases and CSS configuration:

```json
{
  "registries": {
    "@sui": "https://raw.githubusercontent.com/draco-china/sui/main/registry/r/{name}.json"
  }
}
```

The catalog is `https://raw.githubusercontent.com/draco-china/sui/main/registry/r/registry.json`. CLI and MCP share this configuration.

Open the consuming application in your MCP client and start the server from the directory containing its `components.json`. In a monorepo, use the application directory rather than a root directory without that file. The same configuration works with the [CLI](/docs/cli).

## Configure the client

These examples use Bun to launch the official server:

```bash
bunx --bun shadcn@latest mcp
```

The MCP client starts this process and communicates over stdin/stdout. Merge the relevant configuration into your project's existing client file, then restart or enable the server. Bun must be available in the client process's environment.

### Claude Code

Use the project's `.mcp.json`:

```json
{
  "mcpServers": {
    "shadcn": {
      "command": "bunx",
      "args": ["--bun", "shadcn@latest", "mcp"]
    }
  }
}
```

Restart Claude Code and use `/mcp` to check the connection.

### Cursor

Use the project's `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "shadcn": {
      "command": "bunx",
      "args": ["--bun", "shadcn@latest", "mcp"]
    }
  }
}
```

Enable the shadcn server in Cursor's MCP settings and check that its tools are listed.

### VS Code

For GitHub Copilot, use the project's `.vscode/mcp.json`. VS Code uses the `servers` key:

```json
{
  "servers": {
    "shadcn": {
      "command": "bunx",
      "args": ["--bun", "shadcn@latest", "mcp"]
    }
  }
}
```

Open the file and start the server through VS Code's MCP controls. The client file locations and keys follow the [official shadcn configuration guide](https://ui.shadcn.com/docs/mcp#configuration).

### Codex

Merge this into the consuming application's `.codex/config.toml`. Replace the placeholder with the application's absolute directory:

```toml
[mcp_servers.shadcn]
command = "bunx"
args = ["--bun", "shadcn@latest", "mcp"]
cwd = "/absolute/path/to/app"
```

Codex loads project configuration for trusted projects. Open or restart the project after editing and verify that the server's tools are available. See the official OpenAI documentation for [project configuration](https://learn.chatgpt.com/docs/config-file/config-basic) and [MCP settings](https://learn.chatgpt.com/docs/extend/mcp?surface=cli).

## Browse, inspect, and install

Ask the assistant to use the `@sui` namespace explicitly:

> Search @sui for table components, inspect @sui/data-table and its dependencies, then install it in this application and adapt the documentation example to my aliases.

The server exposes these tools for the workflow:

| Tool | Purpose |
| --- | --- |
| `get_project_registries` | Confirm that the application has configured `@sui`. |
| `list_items_in_registries` | List entries in `@sui`. |
| `search_items_in_registries` | Search names and descriptions in `@sui`. |
| `view_items_in_registries` | Inspect an item's manifest and file contents. |
| `get_add_command_for_items` | Return the CLI command for the selected items. |

For example, search with `registries: ["@sui"]` and `query: "table"`, then inspect `items: ["@sui/data-table"]`. After obtaining the add command, the assistant runs it from the consuming application directory. With Bun, the equivalent command is:

```bash
bunx --bun shadcn@latest add @sui/data-table
```

Review the installed files, styles, and dependencies. See [CLI](/docs/cli) for previewing changes and [Compatibility](/docs/compatibility) for runtime requirements.

SUI's catalog currently contains installable components, blocks, styles, and helpers, without separate demo or example entries. Use [LLMs documentation](/docs/llms-txt) for complete examples and API guidance rather than expecting MCP's example search to return `@sui/*-demo` items.

## Troubleshooting

| Symptom | Check |
| --- | --- |
| GitHub registry returns 404 | Check the configured URL, access to the repository, and whether the requested item exists. |
| Unknown registry or missing `@sui` | Check the namespace in the consuming application's `components.json`, then call `get_project_registries`. |
| Server reads a different project | Check its working directory. It must point to the consuming application containing `components.json`; restart after changing it. |
| `bunx` is not found | Ensure the client process can find Bun in `PATH`, or use the absolute path to the `bunx` executable in its server configuration. |
| Tools appear but installation does not happen | `get_add_command_for_items` returns a command. The assistant still needs to execute it in the application. |

To isolate registry problems, run these commands from the same application directory as MCP:

```bash
bunx --bun shadcn@latest search @sui -q button
bunx --bun shadcn@latest view @sui/button
```

See [Registry](/docs/registry) for configuration and item contents, and [CLI](/docs/cli) for installation and updates.


---

# Registry

Understand SUI manifests, shared styles, and GitHub distribution.

Page: https://sui.draco.dev/docs/registry

The SUI registry distributes editable component source through the [CLI](/docs/cli) and [MCP](/docs/mcp). Configure the `@sui` namespace as described in [installation](/docs/installation).

## GitHub files

```json
{
  "registries": {
    "@sui": "https://raw.githubusercontent.com/draco-china/sui/main/registry/r/{name}.json"
  }
}
```

`registry/r/registry.json` is the searchable catalog. `registry/r/button.json`, for example, contains the installation payload for Button. Names do not have a locale prefix; installed components use English defaults and accept application-owned text.

| Item | Content |
| --- | --- |
| Component name, such as `button` | Component, transitive local files, dependencies, CSS, and theme tokens |
| `data-table`, `delete-resource`, `tanstack-form` | A Block and its required source and styles |
| `sui-style` | Shared theme and component CSS |
| `sui-theme` | Theme helpers and shared styles |
| `sui` | All components and Blocks |

## Files and dependencies

Manifests use shadcn's registry schema. `dependencies` and `devDependencies` declare package versions. `files` contains source and targets resolved against application aliases; `css` and `cssVars` merge into the configured stylesheet.

Each item is self-contained, including local hooks, helpers, declarations, and other components it imports. This avoids depending on a consumer's namespace or accidentally resolving a same-named component from another registry. The catalog describes items without duplicating their source; the individual payloads carry full content.

The CLI rewrites imports to your aliases. Workspace imports in documentation are explained in the [import mapping](/docs/installation#import-installed-source). Installed theme values and source are editable; review their differences when adding SUI to an existing design system.

## Update installed source

Preview changes with the [CLI](/docs/cli#review-an-update) before updating components and shared dependencies. Installation copies source; files do not automatically follow library changes. Keep your application's package-manager lockfile and review styles alongside local edits.

LLM documentation lives on the documentation site's [text endpoints](/docs/llms-txt). Registry JSON supplies installation data; an MCP client starts the shadcn stdio server separately.


---

# Theming

Semantic colors, light and dark surfaces, and reusable palettes.

Page: https://sui.draco.dev/docs/theming

SUI colors describe the role of an element. A card uses `card` and `card-foreground`; a primary action uses `primary` and `primary-foreground`. The same component adapts when its palette or appearance changes.

Shared CSS color variables use OKLCH, including the seven presets and custom palette output. These values preserve the existing colors. Custom input and preset seeds remain HEX, and contrast is measured using sRGB relative luminance. The shared package provides general semantic variables; this documentation app uses `accent-foreground` for links and `ring` for focus directly.

## Semantic usage

Choose a token by purpose, then keep the surface and its matching foreground together. Use the component's built-in variant when it already expresses that purpose.

**Recommended**

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

<div className="rounded-xl border border-border bg-card p-4 text-card-foreground">
  <p className="text-muted-foreground">Your changes are ready.</p>
  <Button>Save changes</Button>
</div>;
```

**Avoid for product UI**

```tsx
<div className="rounded-xl border border-gray-300 bg-white p-4 text-black">
  <p className="text-gray-500">Your changes are ready.</p>
  <button className="bg-blue-600 text-white">Save changes</button>
</div>;
```

Fixed colors can be appropriate for illustrations or external brand assets. Product surfaces, controls, and text should follow semantic tokens so they stay consistent across themes. SUI does not add a lint rule that forbids primitive colors.

## Surface hierarchy

Start with the page canvas and layer content using the surface that matches its role. The default theme uses an Apple-inspired gray canvas, white surfaces, and blue actions; dark mode uses deep gray surfaces and brighter blue accents. Inter remains the font.

| Role | Surface | Matching text | Typical use |
| --- | --- | --- | --- |
| Page | `bg-background` | `text-foreground` | Application canvas |
| Card | `bg-card` | `text-card-foreground` | Grouped content |
| Floating | `bg-popover` | `text-popover-foreground` | Menus and popovers |
| Secondary | `bg-secondary` | `text-secondary-foreground` | Secondary controls |
| Quiet | `bg-muted` | `text-muted-foreground` | Supporting content |
| Selected | `bg-accent` | `text-accent-foreground` | Selection and hover |

Surfaces express purpose rather than a fixed brightness ladder. `card` and `popover` may share a value while preserving different roles.

## Primary and status

Use `primary` for the main action and `primary-foreground` for its text. Use `accent` for selected or hovered items. Links use `accent-foreground`, which can differ from the primary seed to maintain text contrast on neutral surfaces.

Selection colors also apply to pressed Toggle and ToggleGroup items, Command highlights, current navigation links, selected options and menu items, selected table rows, choice cards, and calendar ranges. Filled selections, including Tabs, current pagination links, checkboxes, and radio buttons, use `primary` with `primary-foreground`. Focus indicators use `ring`.

Use `destructive` for destructive actions and invalid input. Its color remains independent of the selected accent. SUI does not define separate success, warning, or information color tokens; express those states with clear text and icons, or define application-specific semantic tokens.

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

<Button variant="destructive">Delete workspace</Button>;
```

## Text

Pair foreground tokens with their intended surfaces. `foreground` is the default body color; `muted-foreground` supports descriptions and secondary labels. A lighter shade alone should not communicate disabled, invalid, or selected state: retain accessible labels and the control's state attributes.

## Borders and focus

`border` separates surfaces. Existing Input uses `bg-input/50` for its fill. `ring` marks keyboard focus. Keep the outline visible when customizing interactive elements.

```tsx
<a
  href="#token-reference"
  className="rounded-md text-accent-foreground underline outline-offset-4 focus-visible:outline-2 focus-visible:outline-ring"
>
  Explore colors
</a>;
```

## Charts

Use `chart-1` through `chart-5` for data series. Every preset supplies five coordinated colors. These colors distinguish series; add legends, labels, or patterns instead of relying only on hue. Chart colors are not substitutes for text or status tokens.

## Token reference

Browse the actual default tokens by role. Each row shows its utility, its light and dark value, and buttons to copy the variable, utility, or value. The catalog reads `globals.css`; it does not maintain a separate color table.

### Example: theming-semantic-colors

```tsx
import { Button } from "@workspace/ui/components/button";
import { InlineCopyText } from "@workspace/ui/components/inline-copy-text";
import { useState } from "react";
import { previewTokens, tokenValue } from "../support/theming-tokens";
import type { ExampleProps } from "../types";

const groups = [
  {
    en: "Surfaces",
    zh: "表面",
    tokens: [
      ["background", "bg-background", "Page canvas", "页面画布"],
      ["card", "bg-card", "Card surface", "卡片表面"],
      ["popover", "bg-popover", "Floating surface", "浮层表面"],
      ["secondary", "bg-secondary", "Secondary control", "次要控件"],
      ["muted", "bg-muted", "Quiet surface", "低强调表面"],
      ["accent", "bg-accent", "Selection and hover", "选中与悬停"],
    ],
  },
  {
    en: "Text",
    zh: "正文",
    tokens: [
      ["foreground", "text-foreground", "Page text", "页面正文"],
      ["card-foreground", "text-card-foreground", "Text on card", "卡片正文"],
      [
        "popover-foreground",
        "text-popover-foreground",
        "Text on floating surface",
        "浮层正文",
      ],
      [
        "secondary-foreground",
        "text-secondary-foreground",
        "Text on secondary control",
        "次要控件正文",
      ],
      [
        "muted-foreground",
        "text-muted-foreground",
        "Supporting text",
        "辅助文字",
      ],
      [
        "accent-foreground",
        "text-accent-foreground",
        "Text on selection",
        "选中态正文",
      ],
    ],
  },
  {
    en: "Primary",
    zh: "主色",
    tokens: [
      ["primary", "bg-primary", "Primary action", "主要操作"],
      [
        "primary-foreground",
        "text-primary-foreground",
        "Text on primary action",
        "主要操作正文",
      ],
    ],
  },
  {
    en: "Borders and focus",
    zh: "边框与焦点",
    tokens: [
      ["border", "border-border", "Surface boundary", "表面边界"],
      ["input", "bg-input/50", "Input fill", "输入控件填充"],
      ["ring", "ring-ring", "Keyboard focus", "键盘焦点"],
    ],
  },
  {
    en: "Status",
    zh: "状态",
    tokens: [
      [
        "destructive",
        "text-destructive",
        "Destructive action or invalid input",
        "危险操作或无效输入",
      ],
    ],
  },
  {
    en: "Charts",
    zh: "图表",
    tokens: [1, 2, 3, 4, 5].map((index) => [
      `chart-${index}`,
      `fill-chart-${index}`,
      `Data series ${index}`,
      `数据系列 ${index}`,
    ]),
  },
  {
    en: "Sidebar",
    zh: "侧栏",
    tokens: [
      ["sidebar", "bg-sidebar", "Sidebar surface", "侧栏表面"],
      [
        "sidebar-foreground",
        "text-sidebar-foreground",
        "Sidebar text",
        "侧栏正文",
      ],
      [
        "sidebar-primary",
        "bg-sidebar-primary",
        "Sidebar primary action",
        "侧栏主要操作",
      ],
      [
        "sidebar-primary-foreground",
        "text-sidebar-primary-foreground",
        "Text on sidebar action",
        "侧栏主要操作正文",
      ],
      [
        "sidebar-accent",
        "bg-sidebar-accent",
        "Sidebar selected item",
        "侧栏选中项",
      ],
      [
        "sidebar-accent-foreground",
        "text-sidebar-accent-foreground",
        "Selected sidebar text",
        "侧栏选中项正文",
      ],
      [
        "sidebar-border",
        "border-sidebar-border",
        "Sidebar boundary",
        "侧栏边界",
      ],
      [
        "sidebar-ring",
        "ring-sidebar-ring",
        "Sidebar keyboard focus",
        "侧栏键盘焦点",
      ],
    ],
  },
];

export default function Example({ locale }: ExampleProps) {
  const zh = locale === "zh-CN";
  const stateLabels = zh
    ? {
        dark: "深色",
        light: "浅色",
      }
    : {
        dark: "Dark",
        light: "Light",
      };
  const [selected, setSelected] = useState(0);
  const group = groups[selected] ?? groups[0];
  const labels = {
    copy: zh ? "复制" : "Copy",
    copied: zh ? "已复制" : "Copied",
    failed: zh
      ? "复制失败，请手动复制"
      : "Copy failed. Copy the text manually.",
  };
  return (
    <div className="w-full space-y-4 text-sm">
      <fieldset className="flex min-w-0 flex-wrap gap-2">
        <legend className="sr-only">{zh ? "颜色用途" : "Color roles"}</legend>
        {groups.map((item, index) => (
          <Button
            key={item.en}
            type="button"
            size="sm"
            variant={index === selected ? "default" : "outline"}
            aria-pressed={index === selected}
            onClick={() => setSelected(index)}
          >
            {zh ? item.zh : item.en}
          </Button>
        ))}
      </fieldset>
      <ul className="divide-y divide-border rounded-2xl border border-border">
        {group?.tokens.map(([token, utility, en, cn]) => (
          <li key={token} className="grid gap-3 p-4 sm:grid-cols-2">
            <div className="min-w-0 space-y-1">
              <p className="font-semibold">{zh ? cn : en}</p>
              <InlineCopyText labels={labels}>{`--${token}`}</InlineCopyText>
              <div>
                <InlineCopyText labels={labels} variant="muted">
                  {utility ?? ""}
                </InlineCopyText>
              </div>
            </div>
            <div className="grid grid-cols-2 gap-3">
              {[false, true].map((dark) => {
                const value = tokenValue(
                  previewTokens("default", dark),
                  `--${token}`,
                );
                return (
                  <div key={String(dark)} className="min-w-0 space-y-2">
                    <div
                      aria-hidden="true"
                      className="h-12 rounded-lg border border-border"
                      style={{ background: value }}
                    />
                    <p className="text-muted-foreground">
                      {dark ? stateLabels.dark : stateLabels.light}
                    </p>
                    <InlineCopyText labels={labels}>{value}</InlineCopyText>
                  </div>
                );
              })}
            </div>
          </li>
        ))}
      </ul>
    </div>
  );
}
```

## Appearance

Set `dark` on a parent to use dark tokens. Without that class, the application uses light tokens. Mode and palette are separate choices: `dark` controls appearance, while `data-color` selects a palette.

```html
<html data-color="pine" class="dark">
```

The following two panels use the same SUI components with isolated default light and dark variables. Edit the field, toggle the switch, or save changes to try the controls.

### Example: theming-mode-comparison

```tsx
import { cn } from "cn";
import { ThemePreview } from "../support/theming-preview";
import { previewStyle } from "../support/theming-tokens";
import type { ExampleProps } from "../types";

export default function Example({ locale }: ExampleProps) {
  const zh = locale === "zh-CN";
  const stateLabels = zh
    ? {
        dark: "深色",
        light: "浅色",
      }
    : {
        dark: "Dark",
        light: "Light",
      };
  return (
    <div className="grid w-full gap-4 text-sm sm:grid-cols-2">
      {[false, true].map((dark) => (
        <section
          key={String(dark)}
          data-color="default"
          className={cn(
            "space-y-3 rounded-2xl border border-border bg-background p-4 text-foreground",
            dark && "dark",
          )}
          style={previewStyle("default", dark)}
        >
          <h3 className="font-semibold">
            {dark ? stateLabels.dark : stateLabels.light}
          </h3>
          <ThemePreview locale={locale} />
        </section>
      ))}
    </div>
  );
}
```

For the whole documentation site, open the appearance panel and choose **Light**, **Dark**, or **System**. System is the default and follows the device preference.

## Preset palettes

Choose **Default** or one of seven presets: Bamboo, Mauve, Mist, Sand, Pine, Rose, and Lime. Default uses the base tokens in `globals.css`. Each preset has a complete five-color palette, with the colors mapped in order to `chart-1` through `chart-5`. Its primary seed controls `primary` independently; it does not have to be the first chart color.

The cards below show the full five-color palette, copyable color values, and the same interactive component preview for every theme. Use the shared light/dark control to compare them under the same appearance. The default theme has its own complete card.

Surfaces, body text, and destructive colors keep their roles when the accent changes. Primary actions, selected states, focus rings, sidebar accents, and charts follow the palette. Accessible foreground and focus colors can differ from the seed to maintain contrast. These previews stay local and do not change the site theme or browser storage.

### Example: theming-palette-playground

```tsx
import { Button } from "@workspace/ui/components/button";
import { InlineCopyText } from "@workspace/ui/components/inline-copy-text";
import { themePresets } from "@workspace/ui/lib/theme/theme";
import { cn } from "cn";
import { useState } from "react";
import { ThemePreview } from "../support/theming-preview";
import {
  previewStyle,
  previewTokens,
  tokenValue,
} from "../support/theming-tokens";
import type { ExampleProps } from "../types";

const palettes = [
  { id: "default" as const, en: "Default", zh: "默认" },
  ...themePresets,
];

export default function Example({ locale }: ExampleProps) {
  const zh = locale === "zh-CN";
  const [dark, setDark] = useState(false);
  const mode = zh
    ? { dark: "深色预览", light: "浅色预览" }
    : { dark: "Dark preview", light: "Light preview" };
  return (
    <div className="w-full space-y-6 text-sm">
      <div className="flex items-center justify-between gap-4">
        <p className="text-muted-foreground">
          {zh
            ? "每套配色包含五个协调色"
            : "Each palette contains five coordinated colors"}
        </p>
        <Button
          type="button"
          variant="outline"
          size="sm"
          aria-pressed={dark}
          onClick={() => setDark(!dark)}
        >
          {dark ? mode.dark : mode.light}
        </Button>
      </div>
      <div className="grid gap-6 lg:grid-cols-2">
        {palettes.map((preset) => {
          const tokens = previewTokens(preset.id, dark);
          const colors =
            "palette" in preset
              ? preset.palette
              : [1, 2, 3, 4, 5].map((index) =>
                  tokenValue(tokens, `--chart-${index}`),
                );
          return (
            <section
              key={preset.id}
              data-color={preset.id}
              aria-label={zh ? preset.zh : preset.en}
              className={cn(
                "grid content-start gap-5 rounded-2xl border border-border bg-background p-4 text-foreground",
                dark && "dark",
              )}
              style={previewStyle(preset.id, dark)}
            >
              <div className="flex flex-wrap items-center justify-between gap-2">
                <h3 className="font-semibold text-base">
                  {zh ? preset.zh : preset.en}
                </h3>
                {"color" in preset && (
                  <InlineCopyText
                    className="text-muted-foreground text-xs"
                    aria-label={
                      zh
                        ? `复制主色 ${preset.color}`
                        : `Copy primary color ${preset.color}`
                    }
                  >
                    {preset.color}
                  </InlineCopyText>
                )}
              </div>
              <div className="grid grid-cols-5 gap-2">
                {colors.map((color, index) => (
                  <div key={color} className="grid min-w-0 gap-2">
                    <span
                      aria-hidden="true"
                      className="h-10 rounded-lg"
                      style={{ background: `var(--chart-${index + 1})` }}
                    />
                    <InlineCopyText
                      value={color}
                      truncate={false}
                      className="justify-center gap-1 text-[10px]"
                      aria-label={
                        zh ? `复制配色 ${color}` : `Copy color ${color}`
                      }
                    >
                      {"palette" in preset ? color : `chart-${index + 1}`}
                    </InlineCopyText>
                  </div>
                ))}
              </div>
              <ThemePreview locale={locale} />
            </section>
          );
        })}
      </div>
      <p className="text-muted-foreground">
        {zh
          ? "明暗切换仅作用于这些预览，不改变整站主题或浏览器存储"
          : "Appearance switches affect these previews without changing the site theme or browser storage."}
      </p>
    </div>
  );
}
```

Lime uses a bright `#D5F267` primary with black text. Accessible links and focus rings use deeper olive shades in light mode; dark mode keeps the lime accents bright against neutral dark surfaces. Choose **Lime** in the theme panel or set `data-color="lime"`.

## Custom HEX

The preview and the site theme panel accept three- or six-digit HEX values, with or without `#`. Shorthand expands to six digits. Invalid input displays an error and preserves the current valid theme.

The primary seed stays unchanged. The shared calculation chooses black or white primary text and adjusts links, selected text, and focus colors against the light and dark surfaces. It checks ordinary text at 4.5:1 and focus colors at 3:1. Use the matching foreground token rather than assuming white text works on every primary color.

### Example: theming-custom-color

```tsx
import { Button } from "@workspace/ui/components/button";
import { ColorPicker } from "@workspace/ui/components/color-picker";
import { Input } from "@workspace/ui/components/input";
import { Label } from "@workspace/ui/components/label";
import { normalizeHex } from "@workspace/ui/lib/theme/theme";
import { cn } from "cn";
import { useId, useState } from "react";
import { colorPickerLabels } from "../../lib/color-picker-labels";
import { ThemePreview } from "../support/theming-preview";
import { previewStyle } from "../support/theming-tokens";
import type { ExampleProps } from "../types";

export default function Example({ locale }: ExampleProps) {
  const zh = locale === "zh-CN";
  const id = useId();
  const [dark, setDark] = useState(false);
  const [input, setInput] = useState("#0066CC");
  const [custom, setCustom] = useState<string | null>("#0066CC");
  const [invalid, setInvalid] = useState(false);
  const mode = zh
    ? { dark: "深色预览", light: "浅色预览" }
    : { dark: "Dark preview", light: "Light preview" };
  return (
    <div className="w-full space-y-4 text-sm">
      <form
        className="flex flex-wrap items-end gap-2"
        onSubmit={(event) => {
          event.preventDefault();
          const next = normalizeHex(input);
          setInvalid(next === null);
          if (next) {
            setCustom(next);
            setInput(next);
          }
        }}
      >
        <div className="grid min-w-36 flex-1 gap-2">
          <Label htmlFor={id}>{zh ? "自定义 HEX" : "Custom HEX"}</Label>
          <Input
            id={id}
            value={input}
            onChange={(event) => setInput(event.target.value)}
            aria-invalid={invalid}
            aria-describedby={invalid ? `${id}-error` : undefined}
          />
        </div>
        <Button type="submit" variant="secondary">
          {zh ? "应用" : "Apply"}
        </Button>
        <ColorPicker
          value={custom ?? "#0066CC"}
          onValueChange={(next) => {
            setCustom(next);
            setInput(next);
            setInvalid(false);
          }}
          labels={colorPickerLabels(locale)}
        />
        <Button
          type="button"
          variant="outline"
          aria-pressed={dark}
          onClick={() => setDark(!dark)}
        >
          {dark ? mode.dark : mode.light}
        </Button>
      </form>
      {invalid && (
        <p id={`${id}-error`} role="alert" className="text-destructive">
          {zh
            ? "输入三位或六位 HEX；当前有效配色保持不变"
            : "Enter a three- or six-digit HEX. The current valid palette is unchanged."}
        </p>
      )}
      <section
        data-color="custom"
        className={cn(
          "rounded-2xl border border-border bg-background p-4 text-foreground",
          dark && "dark",
        )}
        style={previewStyle("default", dark, custom)}
      >
        <ThemePreview locale={locale} />
      </section>
    </div>
  );
}
```

## Shared theme files

Import the UI stylesheet to include the default tokens, component styles, and all seven presets:

```css
@import "@workspace/ui/globals.css";
```

The seven files live in `packages/ui/src/styles/themes`: `bamboo.css`, `mauve.css`, `mist.css`, `sand.css`, `pine.css`, `rose.css`, and `lime.css`. A setup that already loads SUI base tokens can import an individual preset:

```css
@import "@workspace/ui/themes/pine.css";
```

Select it on the root or a container with `data-color="pine"`. A dark ancestor enables its dark palette. To reset the root, use `data-color="default"` or remove the attribute and clear custom inline tokens. The default comes directly from `globals.css`; it has no separate theme file. A nested container without its own overrides inherits its parent's colors.

## Custom application themes

Use the shared helpers for custom input. Validate first, clear previous inline accent tokens, and calculate overrides only for a custom seed:

```tsx
import {
  createThemeTokens,
  getThemeId,
  normalizeHex,
  themeTokenNames,
} from "@workspace/ui/lib/theme/theme";

function applyTheme(input: string | null, dark: boolean) {
  const seed = input === null ? null : normalizeHex(input);
  if (input !== null && seed === null) return;
  const root = document.documentElement;
  root.classList.toggle("dark", dark);
  root.dataset.color = getThemeId(seed);
  for (const name of themeTokenNames) root.style.removeProperty(name);
  if (root.dataset.color === "custom") {
    for (const [name, value] of Object.entries(createThemeTokens(seed, dark))) {
      root.style.setProperty(name, value);
    }
  }
}
```

Pass `null` to restore Default. Recalculate custom overrides when appearance changes. The shared package supplies colors and calculation; your application owns mode selection, persistence, and initial restoration. Use `text-accent-foreground` for accessible links and `outline-ring` for focus. The documentation stylesheet maps Fumadocs's `--color-fd-*` variables to the shared semantic tokens; these framework aliases are not part of the shared theme files or `createThemeTokens` output.

## Creating a theme

For a reusable preset, add its stable ID, bilingual name, seed, and five chart colors to `themePresets` in `packages/ui/src/lib/theme/theme.ts`. The generator combines that definition with the current base semantic tokens in `globals.css`.

```sh
bun run --cwd packages/ui themes:generate
```

Import the resulting individual file in `globals.css`, then use its ID with `data-color`. Regenerate after changing a preset or the base tokens. Review both modes, matching foregrounds, keyboard focus, and chart legends before adopting a palette.

## Persistence

The header provides separate Appearance and Accent color controls. Appearance selects Light, Dark, or System; Accent color selects a preset palette or custom color. Changing the mode preserves the accent.

The documentation site saves its selected mode and accent in browser storage, restores them before the first paint, and responds to device changes while System is active. When storage is unavailable, it uses System and Default. The interactive examples on this page do not write those preferences.

## Right-to-left interfaces

Wrap the relevant subtree in `DirectionProvider` and prefer logical spacing utilities:

```tsx
import { DirectionProvider } from "@workspace/ui/components/direction";

<DirectionProvider direction="rtl">
  <YourApplication />
</DirectionProvider>;
```


---

# Components

Browse all 67 SUI components, listed alphabetically.

Page: https://sui.draco.dev/docs/components

Every preview runs the components in this workspace. Choose a component to find its import, composition, examples, and API.

- [Accordion](https://sui.draco.dev/api/llms-markdown?locale=en-US&slug=components%2Faccordion): A vertically stacked set of interactive headings that each reveal a section of content.
- [Alert](https://sui.draco.dev/api/llms-markdown?locale=en-US&slug=components%2Falert): Displays a callout for user attention.
- [Alert Dialog](https://sui.draco.dev/api/llms-markdown?locale=en-US&slug=components%2Falert-dialog): A modal dialog that interrupts the user with important content and expects a response.
- [Aspect Ratio](https://sui.draco.dev/api/llms-markdown?locale=en-US&slug=components%2Faspect-ratio): Displays content within a desired ratio.
- [Attachment](https://sui.draco.dev/api/llms-markdown?locale=en-US&slug=components%2Fattachment): Displays a file or image attachment with media, metadata, upload state, and actions.
- [Autocomplete](https://sui.draco.dev/api/llms-markdown?locale=en-US&slug=components%2Fautocomplete): Suggests matching options while keeping the input free to accept custom text.
- [Avatar](https://sui.draco.dev/api/llms-markdown?locale=en-US&slug=components%2Favatar): An image element with a fallback for representing the user.
- [Badge](https://sui.draco.dev/api/llms-markdown?locale=en-US&slug=components%2Fbadge): Displays a badge or a component that looks like a badge.
- [Breadcrumb](https://sui.draco.dev/api/llms-markdown?locale=en-US&slug=components%2Fbreadcrumb): Displays the path to the current resource using a hierarchy of links.
- [Bubble](https://sui.draco.dev/api/llms-markdown?locale=en-US&slug=components%2Fbubble): Displays conversational content in a message bubble. Supports variants, alignment, grouping, reactions, and collapsible content.
- [Button](https://sui.draco.dev/api/llms-markdown?locale=en-US&slug=components%2Fbutton): Displays a button or a component that looks like a button.
- [Button Group](https://sui.draco.dev/api/llms-markdown?locale=en-US&slug=components%2Fbutton-group): A container that groups related buttons together with consistent styling.
- [Calendar](https://sui.draco.dev/api/llms-markdown?locale=en-US&slug=components%2Fcalendar): A calendar component that allows users to select a date or a range of dates.
- [Card](https://sui.draco.dev/api/llms-markdown?locale=en-US&slug=components%2Fcard): Displays a card with header, content, and footer.
- [Carousel](https://sui.draco.dev/api/llms-markdown?locale=en-US&slug=components%2Fcarousel): A carousel with motion and swipe built using Embla.
- [Chart](https://sui.draco.dev/api/llms-markdown?locale=en-US&slug=components%2Fchart): Beautiful charts. Built using Recharts. Copy and paste into your apps.
- [Checkbox](https://sui.draco.dev/api/llms-markdown?locale=en-US&slug=components%2Fcheckbox): A control that allows the user to toggle between checked and not checked.
- [Clipboard Text](https://sui.draco.dev/api/llms-markdown?locale=en-US&slug=components%2Fclipboard-text): A selectable text field with a separate copy action and async feedback.
- [Code Viewer](https://sui.draco.dev/api/llms-markdown?locale=en-US&slug=components%2Fcode-viewer): Syntax-highlighted code with folding, line highlights, copying, and streaming feedback.
- [Collapsible](https://sui.draco.dev/api/llms-markdown?locale=en-US&slug=components%2Fcollapsible): An interactive component which expands/collapses a panel.
- [ColorPicker](https://sui.draco.dev/api/llms-markdown?locale=en-US&slug=components%2Fcolor-picker): Choose colors using a saturation area, hue and opacity sliders, editable values and preset swatches.
- [Combobox](https://sui.draco.dev/api/llms-markdown?locale=en-US&slug=components%2Fcombobox): Autocomplete input with a list of suggestions.
- [Command](https://sui.draco.dev/api/llms-markdown?locale=en-US&slug=components%2Fcommand): Command menu for search and quick actions.
- [Context Menu](https://sui.draco.dev/api/llms-markdown?locale=en-US&slug=components%2Fcontext-menu): Displays a menu of actions triggered by a right click.
- [Dialog](https://sui.draco.dev/api/llms-markdown?locale=en-US&slug=components%2Fdialog): A window overlaid on either the primary window or another dialog window, rendering the content underneath inert.
- [Diff Viewer](https://sui.draco.dev/api/llms-markdown?locale=en-US&slug=components%2Fdiff-viewer): A line-based code comparison with split and unified views.
- [Direction](https://sui.draco.dev/api/llms-markdown?locale=en-US&slug=components%2Fdirection): A provider component that sets the text direction for your application.
- [Drawer](https://sui.draco.dev/api/llms-markdown?locale=en-US&slug=components%2Fdrawer): A drawer component for React.
- [Dropdown Menu](https://sui.draco.dev/api/llms-markdown?locale=en-US&slug=components%2Fdropdown-menu): Displays a menu to the user — such as a set of actions or functions — triggered by a button.
- [Editor](https://sui.draco.dev/api/llms-markdown?locale=en-US&slug=components%2Feditor): A client-loaded code editor with preview, toolbar actions, and fullscreen modes.
- [Empty](https://sui.draco.dev/api/llms-markdown?locale=en-US&slug=components%2Fempty): Use the Empty component to display an empty state.
- [Field](https://sui.draco.dev/api/llms-markdown?locale=en-US&slug=components%2Ffield): Combine labels, controls, and help text to compose accessible form fields and grouped inputs.
- [Glass](https://sui.draco.dev/api/llms-markdown?locale=en-US&slug=components%2Fglass): SVG highlights and CSS frosted surfaces, progressively enhanced with WebGPU refraction.
- [Hover Card](https://sui.draco.dev/api/llms-markdown?locale=en-US&slug=components%2Fhover-card): For sighted users to preview content available behind a link.
- [HTML Viewer](https://sui.draco.dev/api/llms-markdown?locale=en-US&slug=components%2Fhtml-viewer): An isolated iframe preview for HTML content.
- [Image Viewer](https://sui.draco.dev/api/llms-markdown?locale=en-US&slug=components%2Fimage-viewer): A dialog image viewer with navigation, zoom, rotation, and panning.
- [Inline Copy Text](https://sui.draco.dev/api/llms-markdown?locale=en-US&slug=components%2Finline-copy-text): Inline code that stays readable and copies its value when activated.
- [Input](https://sui.draco.dev/api/llms-markdown?locale=en-US&slug=components%2Finput): A text input component for forms and user data entry with built-in styling and accessibility features.
- [Input Group](https://sui.draco.dev/api/llms-markdown?locale=en-US&slug=components%2Finput-group): Add addons, buttons, and helper content to inputs.
- [Input OTP](https://sui.draco.dev/api/llms-markdown?locale=en-US&slug=components%2Finput-otp): Individual code inputs with character filtering and asynchronous verification feedback
- [Item](https://sui.draco.dev/api/llms-markdown?locale=en-US&slug=components%2Fitem): A versatile component for displaying content with media, title, description, and actions.
- [Kbd](https://sui.draco.dev/api/llms-markdown?locale=en-US&slug=components%2Fkbd): Used to display textual user input from keyboard.
- [Label](https://sui.draco.dev/api/llms-markdown?locale=en-US&slug=components%2Flabel): Renders an accessible label associated with controls.
- [Loader](https://sui.draco.dev/api/llms-markdown?locale=en-US&slug=components%2Floader): Eighteen loading animations with accessible labels, adjustable speed, and reduced motion support.
- [Locale Toggle](https://sui.draco.dev/api/llms-markdown?locale=en-US&slug=components%2Flocale-toggle): A controlled language button or selector without routing or persistence assumptions.
- [LongText](https://sui.draco.dev/api/llms-markdown?locale=en-US&slug=components%2Flong-text): Truncated text with a full-text disclosure only when the content overflows.
- [Markdown Viewer](https://sui.draco.dev/api/llms-markdown?locale=en-US&slug=components%2Fmarkdown-viewer): Markdown rendering with tables, task lists, alerts, highlighted code, and sanitized HTML.
- [Marker](https://sui.draco.dev/api/llms-markdown?locale=en-US&slug=components%2Fmarker): Displays an inline status, system note, bordered row, or labeled separator in a conversation.
- [Menubar](https://sui.draco.dev/api/llms-markdown?locale=en-US&slug=components%2Fmenubar): A visually persistent menu common in desktop applications that provides quick access to a consistent set of commands.
- [Message](https://sui.draco.dev/api/llms-markdown?locale=en-US&slug=components%2Fmessage): Displays a message in a conversation, with optional avatar, header, footer, and alignment.
- [Message Scroller](https://sui.draco.dev/api/llms-markdown?locale=en-US&slug=components%2Fmessage-scroller): A chat scroll container that anchors turns, opens saved transcripts, follows streamed responses, loads history without jumping, and jumps to any message.
- [Native Select](https://sui.draco.dev/api/llms-markdown?locale=en-US&slug=components%2Fnative-select): A styled native HTML select element with consistent design system integration.
- [Navigation Menu](https://sui.draco.dev/api/llms-markdown?locale=en-US&slug=components%2Fnavigation-menu): A collection of links for navigating websites.
- [NavigationProgress](https://sui.draco.dev/api/llms-markdown?locale=en-US&slug=components%2Fnavigation-progress): A controlled navigation loading bar with delayed start and completion feedback.
- [Pagination](https://sui.draco.dev/api/llms-markdown?locale=en-US&slug=components%2Fpagination): Compact data pagination with range information, page navigation, and page-size selection.
- [Popover](https://sui.draco.dev/api/llms-markdown?locale=en-US&slug=components%2Fpopover): Displays rich content in a portal, triggered by a button.
- [Progress](https://sui.draco.dev/api/llms-markdown?locale=en-US&slug=components%2Fprogress): Displays an indicator showing the completion progress of a task, typically displayed as a progress bar.
- [QRCode](https://sui.draco.dev/api/llms-markdown?locale=en-US&slug=components%2Fqr-code): A theme-aware QR code with loading feedback and optional reveal animation.
- [Questionnaire](https://sui.draco.dev/api/llms-markdown?locale=en-US&slug=components%2Fquestionnaire): A multi-step questionnaire with single-choice, multiple-choice, freeform, and skippable questions.
- [Radio Group](https://sui.draco.dev/api/llms-markdown?locale=en-US&slug=components%2Fradio-group): A set of checkable buttons—known as radio buttons—where no more than one of the buttons can be checked at a time.
- [Resizable](https://sui.draco.dev/api/llms-markdown?locale=en-US&slug=components%2Fresizable): Accessible resizable panel groups and layouts with keyboard support.
- [Scroll Area](https://sui.draco.dev/api/llms-markdown?locale=en-US&slug=components%2Fscroll-area): Augments native scroll functionality for custom, cross-browser styling.
- [Select](https://sui.draco.dev/api/llms-markdown?locale=en-US&slug=components%2Fselect): Displays a list of options for the user to pick from—triggered by a button.
- [Sensitive Input](https://sui.draco.dev/api/llms-markdown?locale=en-US&slug=components%2Fsensitive-input): A sensitive-value input with a fixed mask, click-to-reveal interaction, and copy feedback.
- [Separator](https://sui.draco.dev/api/llms-markdown?locale=en-US&slug=components%2Fseparator): Visually or semantically separates content.
- [Sheet](https://sui.draco.dev/api/llms-markdown?locale=en-US&slug=components%2Fsheet): Extends the Dialog component to display content that complements the main content of the screen.
- [Sidebar](https://sui.draco.dev/api/llms-markdown?locale=en-US&slug=components%2Fsidebar): A composable, themeable and customizable sidebar component.
- [Skeleton](https://sui.draco.dev/api/llms-markdown?locale=en-US&slug=components%2Fskeleton): Use to show a placeholder while content is loading.
- [Slider](https://sui.draco.dev/api/llms-markdown?locale=en-US&slug=components%2Fslider): An input where the user selects a value from within a given range.
- [Switch](https://sui.draco.dev/api/llms-markdown?locale=en-US&slug=components%2Fswitch): A control that allows the user to toggle between checked and not checked.
- [TabBar](https://sui.draco.dev/api/llms-markdown?locale=en-US&slug=components%2Ftab-bar): Controlled application navigation with press-and-slide selection and optional glass material.
- [Table](https://sui.draco.dev/api/llms-markdown?locale=en-US&slug=components%2Ftable): A responsive table component.
- [Tabs](https://sui.draco.dev/api/llms-markdown?locale=en-US&slug=components%2Ftabs): A set of layered sections of content—known as tab panels—that are displayed one at a time.
- [Tag Input](https://sui.draco.dev/api/llms-markdown?locale=en-US&slug=components%2Ftag-input): A multi-value input with custom tags, suggestions, and keyboard-accessible chips.
- [Textarea](https://sui.draco.dev/api/llms-markdown?locale=en-US&slug=components%2Ftextarea): Displays a form textarea or a component that looks like a textarea.
- [Theme Toggle](https://sui.draco.dev/api/llms-markdown?locale=en-US&slug=components%2Ftheme-toggle): A controlled light/dark switch with optional view-transition effects.
- [Toast](https://sui.draco.dev/api/llms-markdown?locale=en-US&slug=components%2Ftoast): A succinct message that is displayed temporarily.
- [Toggle](https://sui.draco.dev/api/llms-markdown?locale=en-US&slug=components%2Ftoggle): A two-state button that can be either on or off.
- [Toggle Group](https://sui.draco.dev/api/llms-markdown?locale=en-US&slug=components%2Ftoggle-group): A set of two-state buttons that can be toggled on or off.
- [Toolbar](https://sui.draco.dev/api/llms-markdown?locale=en-US&slug=components%2Ftoolbar): Groups related commands and controls with arrow-key focus navigation.
- [Tooltip](https://sui.draco.dev/api/llms-markdown?locale=en-US&slug=components%2Ftooltip): A popup that displays information related to an element when the element receives keyboard focus or the mouse hovers over it.


---

# Accordion

A vertically stacked set of interactive headings that each reveal a section of content.

Page: https://sui.draco.dev/docs/components/accordion

### Example: accordion-demo

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

export default function AccordionDemo() {
  return (
    <Accordion defaultValue={["shipping"]} className="max-w-lg">
      <AccordionItem value="shipping">
        <AccordionTrigger>What are your shipping options?</AccordionTrigger>
        <AccordionContent>
          We offer standard (5-7 days), express (2-3 days), and overnight
          shipping. Free shipping on international orders.
        </AccordionContent>
      </AccordionItem>
      <AccordionItem value="returns">
        <AccordionTrigger>What is your return policy?</AccordionTrigger>
        <AccordionContent>
          Returns accepted within 30 days. Items must be unused and in original
          packaging. Refunds processed within 5-7 business days.
        </AccordionContent>
      </AccordionItem>
      <AccordionItem value="support">
        <AccordionTrigger>How can I contact customer support?</AccordionTrigger>
        <AccordionContent>
          Reach us via email, live chat, or phone. We respond within 24 hours
          during business days.
        </AccordionContent>
      </AccordionItem>
    </Accordion>
  );
}
```

## Installation

```bash
bunx --bun shadcn@latest add @sui/accordion
```

Install with the shadcn CLI or use the shared `@workspace/ui` package. Follow the [installation guide](/docs/installation) to configure the registry, load styles, and choose import aliases.

## Usage

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

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

## Composition

Use the following composition to build an `Accordion`:

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

## Basic

A basic accordion that shows one item at a time. The first item is open by default.

### Example: accordion-basic

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

const items = [
  {
    value: "item-1",
    trigger: "How do I reset my password?",
    content:
      "Click on 'Forgot Password' on the login page, enter your email address, and we'll send you a link to reset your password. The link will expire in 24 hours.",
  },
  {
    value: "item-2",
    trigger: "Can I change my subscription plan?",
    content:
      "Yes, you can upgrade or downgrade your plan at any time from your account settings. Changes will be reflected in your next billing cycle.",
  },
  {
    value: "item-3",
    trigger: "What payment methods do you accept?",
    content:
      "We accept all major credit cards, PayPal, and bank transfers. All payments are processed securely through our payment partners.",
  },
];

export function AccordionBasic() {
  return (
    <Accordion defaultValue={["item-1"]} className="max-w-lg">
      {items.map((item) => (
        <AccordionItem key={item.value} value={item.value}>
          <AccordionTrigger>{item.trigger}</AccordionTrigger>
          <AccordionContent>{item.content}</AccordionContent>
        </AccordionItem>
      ))}
    </Accordion>
  );
}

export default AccordionBasic;
```

## Multiple

Use the `multiple` prop to allow multiple items to be open at the same time.

### Example: accordion-multiple

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

const items = [
  {
    value: "notifications",
    trigger: "Notification Settings",
    content:
      "Manage how you receive notifications. You can enable email alerts for updates or push notifications for mobile devices.",
  },
  {
    value: "privacy",
    trigger: "Privacy & Security",
    content:
      "Control your privacy settings and security preferences. Enable two-factor authentication, manage connected devices, review active sessions, and configure data sharing preferences. You can also download your data or delete your account.",
  },
  {
    value: "billing",
    trigger: "Billing & Subscription",
    content:
      "View your current plan, payment history, and upcoming invoices. Update your payment method, change your subscription tier, or cancel your subscription.",
  },
];

export function AccordionMultiple() {
  return (
    <Accordion multiple className="max-w-lg" defaultValue={["notifications"]}>
      {items.map((item) => (
        <AccordionItem key={item.value} value={item.value}>
          <AccordionTrigger>{item.trigger}</AccordionTrigger>
          <AccordionContent>{item.content}</AccordionContent>
        </AccordionItem>
      ))}
    </Accordion>
  );
}

export default AccordionMultiple;
```

## Disabled

Use the `disabled` prop on `AccordionItem` to disable individual items.

### Example: accordion-disabled

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

export default function AccordionDisabled() {
  return (
    <Accordion className="w-full">
      <AccordionItem value="item-1">
        <AccordionTrigger>Can I access my account history?</AccordionTrigger>
        <AccordionContent>
          Yes, you can view your complete account history including all
          transactions, plan changes, and support tickets in the Account History
          section of your dashboard.
        </AccordionContent>
      </AccordionItem>
      <AccordionItem value="item-2" disabled>
        <AccordionTrigger>Premium feature information</AccordionTrigger>
        <AccordionContent>
          This section contains information about premium features. Upgrade your
          plan to access this content.
        </AccordionContent>
      </AccordionItem>
      <AccordionItem value="item-3">
        <AccordionTrigger>How do I update my email address?</AccordionTrigger>
        <AccordionContent>
          You can update your email address in your account settings.
          You&apos;ll receive a verification email at your new address to
          confirm the change.
        </AccordionContent>
      </AccordionItem>
    </Accordion>
  );
}
```

## Borders

Add `border` to the `Accordion` and `border-b last:border-b-0` to the `AccordionItem` to add borders to the items.

### Example: accordion-borders

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

const items = [
  {
    value: "billing",
    trigger: "How does billing work?",
    content:
      "We offer monthly and annual subscription plans. Billing is charged at the beginning of each cycle, and you can cancel anytime. All plans include automatic backups, 24/7 support, and unlimited team members.",
  },
  {
    value: "security",
    trigger: "Is my data secure?",
    content:
      "Yes. We use end-to-end encryption, SOC 2 Type II compliance, and regular third-party security audits. All data is encrypted at rest and in transit using industry-standard protocols.",
  },
  {
    value: "integration",
    trigger: "What integrations do you support?",
    content:
      "We integrate with 500+ popular tools including Slack, Zapier, Salesforce, HubSpot, and more. You can also build custom integrations using our REST API and webhooks.",
  },
];

export default function AccordionBorders() {
  return (
    <Accordion
      className="max-w-lg rounded-lg border"
      defaultValue={["billing"]}
    >
      {items.map((item) => (
        <AccordionItem
          key={item.value}
          value={item.value}
          className="border-b px-4 last:border-b-0"
        >
          <AccordionTrigger>{item.trigger}</AccordionTrigger>
          <AccordionContent>{item.content}</AccordionContent>
        </AccordionItem>
      ))}
    </Accordion>
  );
}
```

## Card

Wrap the `Accordion` in a `Card` component.

### Example: accordion-card

```tsx
import {
  Accordion,
  AccordionContent,
  AccordionItem,
  AccordionTrigger,
} from "@workspace/ui/components/accordion";
import {
  Card,
  CardContent,
  CardDescription,
  CardHeader,
  CardTitle,
} from "@workspace/ui/components/card";

const items = [
  {
    value: "plans",
    trigger: "What subscription plans do you offer?",
    content:
      "We offer three subscription tiers: Starter ($9/month), Professional ($29/month), and Enterprise ($99/month). Each plan includes increasing storage limits, API access, priority support, and team collaboration features.",
  },
  {
    value: "billing",
    trigger: "How does billing work?",
    content:
      "Billing occurs automatically at the start of each billing cycle. We accept all major credit cards, PayPal, and ACH transfers for enterprise customers. You'll receive an invoice via email after each payment.",
  },
  {
    value: "cancel",
    trigger: "How do I cancel my subscription?",
    content:
      "You can cancel your subscription anytime from your account settings. There are no cancellation fees or penalties. Your access will continue until the end of your current billing period.",
  },
];

export default function AccordionCard() {
  return (
    <Card className="w-full max-w-sm">
      <CardHeader>
        <CardTitle>Subscription & Billing</CardTitle>
        <CardDescription>
          Common questions about your account, plans, payments and
          cancellations.
        </CardDescription>
      </CardHeader>
      <CardContent>
        <Accordion defaultValue={["plans"]}>
          {items.map((item) => (
            <AccordionItem key={item.value} value={item.value}>
              <AccordionTrigger>{item.trigger}</AccordionTrigger>
              <AccordionContent>{item.content}</AccordionContent>
            </AccordionItem>
          ))}
        </Accordion>
      </CardContent>
    </Card>
  );
}
```

## RTL

To enable RTL support in shadcn/ui, see the [RTL configuration guide](https://ui.shadcn.com/docs/rtl).

### Example: accordion-rtl

```tsx
"use client";

import {
  Accordion,
  AccordionContent,
  AccordionItem,
  AccordionTrigger,
} from "@workspace/ui/components/accordion";
import { type Translations, useTranslation } from "./support";

const translations: Translations = {
  en: {
    dir: "ltr",
    values: {
      question1: "How do I reset my password?",
      answer1:
        "Click on 'Forgot Password' on the login page, enter your email address, and we'll send you a link to reset your password.",
      question2: "Can I change my subscription plan?",
      answer2:
        "Yes, you can upgrade or downgrade your plan at any time from your account settings. Changes will be reflected in your next billing cycle.",
      question3: "What payment methods do you accept?",
      answer3:
        "We accept all major credit cards, PayPal, and bank transfers. All payments are processed securely through our payment partners.",
    },
  },
  ar: {
    dir: "rtl",
    values: {
      question1: "كيف يمكنني إعادة تعيين كلمة المرور؟",
      answer1:
        "انقر على 'نسيت كلمة المرور' في صفحة تسجيل الدخول، أدخل عنوان بريدك الإلكتروني، وسنرسل لك رابطًا لإعادة تعيين كلمة المرور. سينتهي صلاحية الرابط خلال 24 ساعة.",
      question2: "هل يمكنني تغيير خطة الاشتراك الخاصة بي؟",
      answer2:
        "نعم، يمكنك ترقية أو تخفيض خطتك في أي وقت من إعدادات حسابك. ستظهر التغييرات في دورة الفوترة التالية.",
      question3: "ما هي طرق الدفع التي تقبلونها؟",
      answer3:
        "نقبل جميع بطاقات الائتمان الرئيسية و PayPal والتحويلات المصرفية. تتم معالجة جميع المدفوعات بأمان من خلال شركاء الدفع لدينا.",
    },
  },
  he: {
    dir: "rtl",
    values: {
      question1: "איך אני מאפס את הסיסמה שלי?",
      answer1:
        "לחץ על 'שכחתי סיסמה' בעמוד ההתחברות, הזן את כתובת האימייל שלך, ונשלח לך קישור לאיפוס הסיסמה. הקישור יפוג תוך 24 שעות.",
      question2: "האם אני יכול לשנות את תוכנית המנוי שלי?",
      answer2:
        "כן, אתה יכול לשדרג או להוריד את התוכנית שלך בכל עת מההגדרות של החשבון שלך. השינויים יבואו לידי ביטוי במחזור החיוב הבא.",
      question3: "אילו אמצעי תשלום אתם מקבלים?",
      answer3: "אנו מקבלים כרטיסי אשראי, PayPal והעברות בנקאיות.",
    },
  },
};

const items = [
  {
    value: "item-1",
    questionKey: "question1" as const,
    answerKey: "answer1" as const,
  },
  {
    value: "item-2",
    questionKey: "question2" as const,
    answerKey: "answer2" as const,
  },
  {
    value: "item-3",
    questionKey: "question3" as const,
    answerKey: "answer3" as const,
  },
] as const;

export function AccordionRtl() {
  const { t } = useTranslation(translations, "ar");

  return (
    <Accordion defaultValue={["item-1"]} className="max-w-md">
      {items.map((item) => (
        <AccordionItem key={item.value} value={item.value}>
          <AccordionTrigger>{t[item.questionKey]}</AccordionTrigger>
          <AccordionContent>{t[item.answerKey]}</AccordionContent>
        </AccordionItem>
      ))}
    </Accordion>
  );
}

export default AccordionRtl;
```

## API Reference

See the [Base UI](https://base-ui.com/react/components/accordion#api-reference) documentation for more information.

- [Documentation](https://base-ui.com/react/components/accordion)
- [API reference](https://base-ui.com/react/components/accordion#api-reference)


---

# Alert

Displays a callout for user attention.

Page: https://sui.draco.dev/docs/components/alert

### Example: alert-demo

```tsx
import {
  Alert,
  AlertDescription,
  AlertTitle,
} from "@workspace/ui/components/alert";
import { CheckCircle2Icon, InfoIcon } from "lucide-react";

export default function AlertDemo() {
  return (
    <div className="grid w-full max-w-md items-start gap-4">
      <Alert>
        <CheckCircle2Icon />
        <AlertTitle>Payment successful</AlertTitle>
        <AlertDescription>
          Your payment of $29.99 has been processed. A receipt has been sent to
          your email address.
        </AlertDescription>
      </Alert>
      <Alert>
        <InfoIcon />
        <AlertTitle>New feature available</AlertTitle>
        <AlertDescription>
          We&apos;ve added dark mode support. You can enable it in your account
          settings.
        </AlertDescription>
      </Alert>
    </div>
  );
}
```

## Installation

```bash
bunx --bun shadcn@latest add @sui/alert
```

Install with the shadcn CLI or use the shared `@workspace/ui` package. Follow the [installation guide](/docs/installation) to configure the registry, load styles, and choose import aliases.

## Usage

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

```tsx showLineNumbers
<Alert>
  <InfoIcon />
  <AlertTitle>Heads up!</AlertTitle>
  <AlertDescription>
    You can add components and dependencies to your app using the cli.
  </AlertDescription>
  <AlertAction>
    <Button variant="outline">Enable</Button>
  </AlertAction>
</Alert>
```

## Composition

Use the following composition to build an `Alert`:

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

## Basic

A basic alert with an icon, title and description.

### Example: alert-basic

```tsx
import {
  Alert,
  AlertDescription,
  AlertTitle,
} from "@workspace/ui/components/alert";
import { CheckCircle2Icon } from "lucide-react";

export default function AlertBasic() {
  return (
    <Alert className="max-w-md">
      <CheckCircle2Icon />
      <AlertTitle>Account updated successfully</AlertTitle>
      <AlertDescription>
        Your profile information has been saved. Changes will be reflected
        immediately.
      </AlertDescription>
    </Alert>
  );
}
```

## Destructive

Use `variant="destructive"` to create a destructive alert.

### Example: alert-destructive

```tsx
import {
  Alert,
  AlertDescription,
  AlertTitle,
} from "@workspace/ui/components/alert";
import { AlertCircleIcon } from "lucide-react";

export default function AlertDestructive() {
  return (
    <Alert variant="destructive" className="max-w-md">
      <AlertCircleIcon />
      <AlertTitle>Payment failed</AlertTitle>
      <AlertDescription>
        Your payment could not be processed. Please check your payment method
        and try again.
      </AlertDescription>
    </Alert>
  );
}
```

## Action

Use `AlertAction` to add a button or other action element to the alert.

### Example: alert-action

```tsx
import {
  Alert,
  AlertAction,
  AlertDescription,
  AlertTitle,
} from "@workspace/ui/components/alert";
import { Button } from "@workspace/ui/components/button";

export default function AlertActionExample() {
  return (
    <Alert className="max-w-md">
      <AlertTitle>Dark mode is now available</AlertTitle>
      <AlertDescription>
        Enable it under your profile settings to get started.
      </AlertDescription>
      <AlertAction>
        <Button size="xs" variant="default">
          Enable
        </Button>
      </AlertAction>
    </Alert>
  );
}
```

## Custom Colors

You can customize the alert colors by adding custom classes such as `bg-amber-50 dark:bg-amber-950` to the `Alert` component.

### Example: alert-colors

```tsx
import {
  Alert,
  AlertDescription,
  AlertTitle,
} from "@workspace/ui/components/alert";
import { AlertTriangleIcon } from "lucide-react";

export default function AlertColors() {
  return (
    <Alert className="max-w-md border-amber-200 bg-amber-50 text-amber-900 dark:border-amber-900 dark:bg-amber-950 dark:text-amber-50">
      <AlertTriangleIcon />
      <AlertTitle>Your subscription will expire in 3 days.</AlertTitle>
      <AlertDescription>
        Renew now to avoid service interruption or upgrade to a paid plan to
        continue using the service.
      </AlertDescription>
    </Alert>
  );
}
```

## RTL

To enable RTL support in shadcn/ui, see the [RTL configuration guide](https://ui.shadcn.com/docs/rtl).

### Example: alert-rtl

```tsx
"use client";

import {
  Alert,
  AlertDescription,
  AlertTitle,
} from "@workspace/ui/components/alert";
import { CheckCircle2Icon, InfoIcon } from "lucide-react";
import { type Translations, useTranslation } from "./support";

const translations: Translations = {
  en: {
    dir: "ltr",
    values: {
      paymentTitle: "Payment successful",
      paymentDescription:
        "Your payment of $29.99 has been processed. A receipt has been sent to your email address.",
      featureTitle: "New feature available",
      featureDescription:
        "We've added dark mode support. You can enable it in your account settings.",
    },
  },
  ar: {
    dir: "rtl",
    values: {
      paymentTitle: "تم الدفع بنجاح",
      paymentDescription:
        "تمت معالجة دفعتك البالغة 29.99 دولارًا. تم إرسال إيصال إلى عنوان بريدك الإلكتروني.",
      featureTitle: "ميزة جديدة متاحة",
      featureDescription:
        "لقد أضفنا دعم الوضع الداكن. يمكنك تفعيله في إعدادات حسابك.",
    },
  },
  he: {
    dir: "rtl",
    values: {
      paymentTitle: "התשלום בוצע בהצלחה",
      paymentDescription:
        "התשלום שלך בסך 29.99 דולר עובד. קבלה נשלחה לכתובת האימייל שלך.",
      featureTitle: "תכונה חדשה זמינה",
      featureDescription:
        "הוספנו תמיכה במצב כהה. אתה יכול להפעיל אותו בהגדרות החשבון שלך.",
    },
  },
};

const alerts = [
  {
    icon: CheckCircle2Icon,
    titleKey: "paymentTitle" as const,
    descriptionKey: "paymentDescription" as const,
  },
  {
    icon: InfoIcon,
    titleKey: "featureTitle" as const,
    descriptionKey: "featureDescription" as const,
  },
] as const;

export function AlertRtl() {
  const { dir, t } = useTranslation(translations, "ar");

  return (
    <div className="grid w-full max-w-md items-start gap-4" dir={dir}>
      {alerts.map((alert) => {
        const Icon = alert.icon;
        return (
          <Alert key={alert.titleKey}>
            <Icon />
            <AlertTitle>{t[alert.titleKey]}</AlertTitle>
            <AlertDescription>{t[alert.descriptionKey]}</AlertDescription>
          </Alert>
        );
      })}
    </div>
  );
}

export default AlertRtl;
```

## API Reference

### Alert

The `Alert` component displays a callout for user attention.

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

### AlertTitle

The `AlertTitle` component displays the title of the alert.

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` | -       |

### AlertDescription

The `AlertDescription` component displays the description or content of the alert.

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` | -       |

### AlertAction

The `AlertAction` component displays an action element (like a button) positioned absolutely in the top-right corner of the alert.

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` | -       |


---

# Alert Dialog

A modal dialog that interrupts the user with important content and expects a response.

Page: https://sui.draco.dev/docs/components/alert-dialog

### Example: alert-dialog-demo

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

export default function AlertDialogDemo() {
  return (
    <AlertDialog>
      <AlertDialogTrigger render={<Button variant="outline" />}>
        Show Dialog
      </AlertDialogTrigger>
      <AlertDialogContent>
        <AlertDialogHeader>
          <AlertDialogTitle>Are you absolutely sure?</AlertDialogTitle>
          <AlertDialogDescription>
            This action cannot be undone. This will permanently delete your
            account from our servers.
          </AlertDialogDescription>
        </AlertDialogHeader>
        <AlertDialogFooter>
          <AlertDialogCancel>Cancel</AlertDialogCancel>
          <AlertDialogAction>Continue</AlertDialogAction>
        </AlertDialogFooter>
      </AlertDialogContent>
    </AlertDialog>
  );
}
```

## Installation

```bash
bunx --bun shadcn@latest add @sui/alert-dialog
```

Install with the shadcn CLI or use the shared `@workspace/ui` package. Follow the [installation guide](/docs/installation) to configure the registry, load styles, and choose import aliases.

## Usage

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

```tsx showLineNumbers
<AlertDialog>
  <AlertDialogTrigger render={<Button variant="outline" />}>
    Show Dialog
  </AlertDialogTrigger>
  <AlertDialogContent>
    <AlertDialogHeader>
      <AlertDialogTitle>Are you absolutely sure?</AlertDialogTitle>
      <AlertDialogDescription>
        This action cannot be undone. This will permanently delete your account
        from our servers.
      </AlertDialogDescription>
    </AlertDialogHeader>
    <AlertDialogFooter>
      <AlertDialogCancel>Cancel</AlertDialogCancel>
      <AlertDialogAction>Continue</AlertDialogAction>
    </AlertDialogFooter>
  </AlertDialogContent>
</AlertDialog>
```

## Composition

Use the following composition to build an `AlertDialog`:

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

## Basic

A basic alert dialog with a title, description, and cancel and continue buttons.

### Example: alert-dialog-basic

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

export function AlertDialogBasic() {
  return (
    <AlertDialog>
      <AlertDialogTrigger
        render={<Button variant="outline">Show Dialog</Button>}
      />
      <AlertDialogContent>
        <AlertDialogHeader>
          <AlertDialogTitle>Are you absolutely sure?</AlertDialogTitle>
          <AlertDialogDescription>
            This action cannot be undone. This will permanently delete your
            account and remove your data from our servers.
          </AlertDialogDescription>
        </AlertDialogHeader>
        <AlertDialogFooter>
          <AlertDialogCancel>Cancel</AlertDialogCancel>
          <AlertDialogAction>Continue</AlertDialogAction>
        </AlertDialogFooter>
      </AlertDialogContent>
    </AlertDialog>
  );
}

export default AlertDialogBasic;
```

## Small

Use the `size="sm"` prop to make the alert dialog smaller.

### Example: alert-dialog-small

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

export function AlertDialogSmall() {
  return (
    <AlertDialog>
      <AlertDialogTrigger
        render={<Button variant="outline">Show Dialog</Button>}
      />
      <AlertDialogContent size="sm">
        <AlertDialogHeader>
          <AlertDialogTitle>Allow accessory to connect?</AlertDialogTitle>
          <AlertDialogDescription>
            Do you want to allow the USB accessory to connect to this device?
          </AlertDialogDescription>
        </AlertDialogHeader>
        <AlertDialogFooter>
          <AlertDialogCancel>Don&apos;t allow</AlertDialogCancel>
          <AlertDialogAction>Allow</AlertDialogAction>
        </AlertDialogFooter>
      </AlertDialogContent>
    </AlertDialog>
  );
}

export default AlertDialogSmall;
```

## Media

Use the `AlertDialogMedia` component to add a media element such as an icon or image to the alert dialog.

### Example: alert-dialog-media

```tsx
import {
  AlertDialog,
  AlertDialogAction,
  AlertDialogCancel,
  AlertDialogContent,
  AlertDialogDescription,
  AlertDialogFooter,
  AlertDialogHeader,
  AlertDialogMedia,
  AlertDialogTitle,
  AlertDialogTrigger,
} from "@workspace/ui/components/alert-dialog";
import { Button } from "@workspace/ui/components/button";
import { CircleFadingPlusIcon } from "lucide-react";

export function AlertDialogWithMedia() {
  return (
    <AlertDialog>
      <AlertDialogTrigger
        render={<Button variant="outline">Share Project</Button>}
      />
      <AlertDialogContent>
        <AlertDialogHeader>
          <AlertDialogMedia>
            <CircleFadingPlusIcon />
          </AlertDialogMedia>
          <AlertDialogTitle>Share this project?</AlertDialogTitle>
          <AlertDialogDescription>
            Anyone with the link will be able to view and edit this project.
          </AlertDialogDescription>
        </AlertDialogHeader>
        <AlertDialogFooter>
          <AlertDialogCancel>Cancel</AlertDialogCancel>
          <AlertDialogAction>Share</AlertDialogAction>
        </AlertDialogFooter>
      </AlertDialogContent>
    </AlertDialog>
  );
}

export default AlertDialogWithMedia;
```

## Small with Media

Use the `size="sm"` prop to make the alert dialog smaller and the `AlertDialogMedia` component to add a media element such as an icon or image to the alert dialog.

### Example: alert-dialog-small-media

```tsx
import {
  AlertDialog,
  AlertDialogAction,
  AlertDialogCancel,
  AlertDialogContent,
  AlertDialogDescription,
  AlertDialogFooter,
  AlertDialogHeader,
  AlertDialogMedia,
  AlertDialogTitle,
  AlertDialogTrigger,
} from "@workspace/ui/components/alert-dialog";
import { Button } from "@workspace/ui/components/button";
import { BluetoothIcon } from "lucide-react";

export function AlertDialogSmallWithMedia() {
  return (
    <AlertDialog>
      <AlertDialogTrigger
        render={<Button variant="outline">Show Dialog</Button>}
      />

      <AlertDialogContent size="sm">
        <AlertDialogHeader>
          <AlertDialogMedia>
            <BluetoothIcon />
          </AlertDialogMedia>
          <AlertDialogTitle>Allow accessory to connect?</AlertDialogTitle>
          <AlertDialogDescription>
            Do you want to allow the USB accessory to connect to this device?
          </AlertDialogDescription>
        </AlertDialogHeader>
        <AlertDialogFooter>
          <AlertDialogCancel>Don&apos;t allow</AlertDialogCancel>
          <AlertDialogAction>Allow</AlertDialogAction>
        </AlertDialogFooter>
      </AlertDialogContent>
    </AlertDialog>
  );
}

export default AlertDialogSmallWithMedia;
```

## Destructive

Use the `AlertDialogAction` component to add a destructive action button to the alert dialog.

### Example: alert-dialog-destructive

```tsx
import {
  AlertDialog,
  AlertDialogAction,
  AlertDialogCancel,
  AlertDialogContent,
  AlertDialogDescription,
  AlertDialogFooter,
  AlertDialogHeader,
  AlertDialogMedia,
  AlertDialogTitle,
  AlertDialogTrigger,
} from "@workspace/ui/components/alert-dialog";
import { Button } from "@workspace/ui/components/button";
import { Trash2Icon } from "lucide-react";

export function AlertDialogDestructive() {
  return (
    <AlertDialog>
      <AlertDialogTrigger
        render={<Button variant="destructive">Delete Chat</Button>}
      />
      <AlertDialogContent size="sm">
        <AlertDialogHeader>
          <AlertDialogMedia className="bg-destructive/10 text-destructive dark:bg-destructive/20 dark:text-destructive">
            <Trash2Icon />
          </AlertDialogMedia>
          <AlertDialogTitle>Delete chat?</AlertDialogTitle>
          <AlertDialogDescription>
            This will permanently delete this chat conversation. View{" "}
            <a href="/docs">Settings</a> delete any memories saved during this
            chat.
          </AlertDialogDescription>
        </AlertDialogHeader>
        <AlertDialogFooter>
          <AlertDialogCancel variant="outline">Cancel</AlertDialogCancel>
          <AlertDialogAction variant="destructive">Delete</AlertDialogAction>
        </AlertDialogFooter>
      </AlertDialogContent>
    </AlertDialog>
  );
}

export default AlertDialogDestructive;
```

## RTL

To enable RTL support in shadcn/ui, see the [RTL configuration guide](https://ui.shadcn.com/docs/rtl).

### Example: alert-dialog-rtl

```tsx
"use client";

import {
  AlertDialog,
  AlertDialogAction,
  AlertDialogCancel,
  AlertDialogContent,
  AlertDialogDescription,
  AlertDialogFooter,
  AlertDialogHeader,
  AlertDialogMedia,
  AlertDialogTitle,
  AlertDialogTrigger,
} from "@workspace/ui/components/alert-dialog";
import { Button } from "@workspace/ui/components/button";
import { BluetoothIcon } from "lucide-react";
import { type Translations, useTranslation } from "./support";

const translations: Translations = {
  en: {
    dir: "ltr",
    values: {
      showDialog: "Show Dialog",
      showDialogSm: "Show Dialog (sm)",
      title: "Are you absolutely sure?",
      description:
        "This action cannot be undone. This will permanently delete your account from our servers.",
      cancel: "Cancel",
      continue: "Continue",
      smallTitle: "Allow accessory to connect?",
      smallDescription:
        "Do you want to allow the USB accessory to connect to this device?",
      dontAllow: "Don't allow",
      allow: "Allow",
    },
  },
  ar: {
    dir: "rtl",
    values: {
      showDialog: "إظهار الحوار",
      showDialogSm: "إظهار الحوار (صغير)",
      title: "هل أنت متأكد تمامًا؟",
      description:
        "لا يمكن التراجع عن هذا الإجراء. سيؤدي هذا إلى حذف حسابك نهائيًا من خوادمنا.",
      cancel: "إلغاء",
      continue: "متابعة",
      smallTitle: "السماح للملحق بالاتصال؟",
      smallDescription: "هل تريد السماح لملحق USB بالاتصال بهذا الجهاز؟",
      dontAllow: "عدم السماح",
      allow: "السماح",
    },
  },
  he: {
    dir: "rtl",
    values: {
      showDialog: "הצג דיאלוג",
      showDialogSm: "הצג דיאלוג (קטן)",
      title: "האם אתה בטוח לחלוטין?",
      description:
        "פעולה זו לא ניתנת לביטול. זה ימחק לצמיתות את החשבון שלך מהשרתים שלנו.",
      cancel: "ביטול",
      continue: "המשך",
      smallTitle: "לאפשר להתקן להתחבר?",
      smallDescription: "האם אתה רוצה לאפשר להתקן USB להתחבר למכשיר זה?",
      dontAllow: "אל תאפשר",
      allow: "אפשר",
    },
  },
};

export function AlertDialogRtl() {
  const { dir, t, language } = useTranslation(translations, "ar");

  return (
    <div className="flex gap-4" dir={dir}>
      <AlertDialog>
        <AlertDialogTrigger render={<Button variant="outline" />}>
          {t.showDialog}
        </AlertDialogTrigger>
        <AlertDialogContent
          dir={dir}
          data-lang={dir === "rtl" ? language : undefined}
        >
          <AlertDialogHeader>
            <AlertDialogTitle>{t.title}</AlertDialogTitle>
            <AlertDialogDescription>{t.description}</AlertDialogDescription>
          </AlertDialogHeader>
          <AlertDialogFooter>
            <AlertDialogCancel>{t.cancel}</AlertDialogCancel>
            <AlertDialogAction>{t.continue}</AlertDialogAction>
          </AlertDialogFooter>
        </AlertDialogContent>
      </AlertDialog>
      <AlertDialog>
        <AlertDialogTrigger render={<Button variant="outline" />}>
          {t.showDialogSm}
        </AlertDialogTrigger>
        <AlertDialogContent
          size="sm"
          dir={dir}
          data-lang={dir === "rtl" ? language : undefined}
        >
          <AlertDialogHeader>
            <AlertDialogMedia>
              <BluetoothIcon />
            </AlertDialogMedia>
            <AlertDialogTitle>{t.smallTitle}</AlertDialogTitle>
            <AlertDialogDescription>
              {t.smallDescription}
            </AlertDialogDescription>
          </AlertDialogHeader>
          <AlertDialogFooter>
            <AlertDialogCancel>{t.dontAllow}</AlertDialogCancel>
            <AlertDialogAction>{t.allow}</AlertDialogAction>
          </AlertDialogFooter>
        </AlertDialogContent>
      </AlertDialog>
    </div>
  );
}

export default AlertDialogRtl;
```

## API Reference

### size

Use the `size` prop on the `AlertDialogContent` component to control the size of the alert dialog. It accepts the following values:

| Prop   | Type                | Default     |
| ------ | ------------------- | ----------- |
| `size` | `"default" \| "sm"` | `"default"` |

For more information about the other components and their props, see the [Base UI documentation](https://base-ui.com/react/components/alert-dialog#api-reference).

- [Documentation](https://base-ui.com/react/components/alert-dialog)
- [API reference](https://base-ui.com/react/components/alert-dialog#api-reference)


---

# Aspect Ratio

Displays content within a desired ratio.

Page: https://sui.draco.dev/docs/components/aspect-ratio

### Example: aspect-ratio-demo

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

export default function AspectRatioDemo() {
  return (
    <AspectRatio ratio={16 / 9} className="w-full max-w-sm rounded-lg bg-muted">
      <img
        src="https://avatar.vercel.sh/shadcn1"
        alt="Landscape"
        className="rounded-lg object-cover grayscale dark:brightness-20"
      />
    </AspectRatio>
  );
}
```

## Installation

```bash
bunx --bun shadcn@latest add @sui/aspect-ratio
```

Install with the shadcn CLI or use the shared `@workspace/ui` package. Follow the [installation guide](/docs/installation) to configure the registry, load styles, and choose import aliases.

## Usage

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

```tsx showLineNumbers
<AspectRatio ratio={16 / 9}>
  <Image src="..." alt="Image" className="rounded-md object-cover" />
</AspectRatio>
```

## Square

A square aspect ratio component using the `ratio={1 / 1}` prop. This is useful for displaying images in a square format.

### Example: aspect-ratio-square

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

export function AspectRatioSquare() {
  return (
    <AspectRatio
      ratio={1 / 1}
      className="w-full max-w-[12rem] rounded-lg bg-muted"
    >
      <img
        src="https://avatar.vercel.sh/shadcn1"
        alt="Landscape"
        className="rounded-lg object-cover grayscale dark:brightness-20"
      />
    </AspectRatio>
  );
}

export default AspectRatioSquare;
```

## Portrait

A portrait aspect ratio component using the `ratio={9 / 16}` prop. This is useful for displaying images in a portrait format.

### Example: aspect-ratio-portrait

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

export function AspectRatioPortrait() {
  return (
    <AspectRatio
      ratio={9 / 16}
      className="w-full max-w-[10rem] rounded-lg bg-muted"
    >
      <img
        src="https://avatar.vercel.sh/shadcn1"
        alt="Landscape"
        className="rounded-lg object-cover grayscale dark:brightness-20"
      />
    </AspectRatio>
  );
}

export default AspectRatioPortrait;
```

## RTL

To enable RTL support in shadcn/ui, see the [RTL configuration guide](https://ui.shadcn.com/docs/rtl).

### Example: aspect-ratio-rtl

```tsx
"use client";

import { AspectRatio } from "@workspace/ui/components/aspect-ratio";
import { type Translations, useTranslation } from "./support";

const translations: Translations = {
  en: {
    dir: "ltr",
    values: {
      caption: "Beautiful landscape",
    },
  },
  ar: {
    dir: "rtl",
    values: {
      caption: "منظر طبيعي جميل",
    },
  },
  he: {
    dir: "rtl",
    values: {
      caption: "נוף יפה",
    },
  },
};

export function AspectRatioRtl() {
  const { dir, t } = useTranslation(translations, "ar");

  return (
    <figure className="w-full max-w-sm" dir={dir}>
      <AspectRatio ratio={16 / 9} className="rounded-lg bg-muted">
        <img
          src="https://avatar.vercel.sh/shadcn1"
          alt="Landscape"
          className="rounded-lg object-cover grayscale dark:brightness-20"
        />
      </AspectRatio>
      <figcaption className="mt-2 text-center text-muted-foreground text-sm">
        {t.caption}
      </figcaption>
    </figure>
  );
}

export default AspectRatioRtl;
```

## API Reference

### AspectRatio

The `AspectRatio` component displays content within a desired ratio.

| Prop        | Type     | Default | Required |
| ----------- | -------- | ------- | -------- |
| `ratio`     | `number` | -       | Yes      |
| `className` | `string` | -       | No       |

For more information, see the [Base UI documentation](https://base-ui.com/react/components/aspect-ratio#api-reference).


---

# Attachment

Displays a file or image attachment with media, metadata, upload state, and actions.

Page: https://sui.draco.dev/docs/components/attachment

### Example: attachment-demo

```tsx
import {
  Attachment,
  AttachmentAction,
  AttachmentActions,
  AttachmentContent,
  AttachmentDescription,
  AttachmentGroup,
  AttachmentMedia,
  AttachmentTitle,
} from "@workspace/ui/components/attachment";
import { Loader } from "@workspace/ui/components/loader";
import { FileCodeIcon, XIcon } from "lucide-react";

const images = [
  {
    name: "workspace.png",
    meta: "PNG · 820 KB",
    src: "https://images.unsplash.com/photo-1497366754035-f200968a6e72?w=900&auto=format&fit=crop&q=80",
    alt: "Workspace",
  },
  {
    name: "desk-reference.jpg",
    meta: "JPG · 1.1 MB",
    src: "https://images.unsplash.com/photo-1497215728101-856f4ea42174?w=900&auto=format&fit=crop&q=80",
    alt: "Desk",
  },
  {
    name: "office-reference.jpg",
    meta: "JPG · 940 KB",
    src: "https://images.unsplash.com/photo-1497366811353-6870744d04b2?w=900&auto=format&fit=crop&q=80",
    alt: "Office",
  },
];

export function AttachmentDemo() {
  return (
    <div className="mx-auto flex w-full max-w-sm flex-col gap-3 py-12">
      <AttachmentGroup>
        {images.map((image) => (
          <Attachment key={image.name} orientation="vertical">
            <AttachmentMedia variant="image">
              <img src={image.src} alt={image.alt} />
            </AttachmentMedia>
            <AttachmentContent>
              <AttachmentTitle>{image.name}</AttachmentTitle>
              <AttachmentDescription>{image.meta}</AttachmentDescription>
            </AttachmentContent>
          </Attachment>
        ))}
      </AttachmentGroup>
      <Attachment state="uploading" className="w-full">
        <AttachmentMedia>
          <Loader size="sm" />
        </AttachmentMedia>
        <AttachmentContent>
          <AttachmentTitle>sales-dashboard.pdf</AttachmentTitle>
          <AttachmentDescription>Uploading · 64%</AttachmentDescription>
        </AttachmentContent>
        <AttachmentActions>
          <AttachmentAction aria-label="Cancel upload">
            <XIcon />
          </AttachmentAction>
        </AttachmentActions>
      </Attachment>
      <Attachment className="w-full">
        <AttachmentMedia>
          <FileCodeIcon />
        </AttachmentMedia>
        <AttachmentContent>
          <AttachmentTitle>message-renderer.tsx</AttachmentTitle>
          <AttachmentDescription>TypeScript · 12 KB</AttachmentDescription>
        </AttachmentContent>
        <AttachmentActions>
          <AttachmentAction aria-label="Remove message-renderer.tsx">
            <XIcon />
          </AttachmentAction>
        </AttachmentActions>
      </Attachment>
    </div>
  );
}

export default AttachmentDemo;
```

The `Attachment` component displays a file or image attachment, its media, name, and metadata, with optional actions and upload state. Use it for files and images in chat composers, message threads, and upload lists.

## Installation

```bash
bunx --bun shadcn@latest add @sui/attachment
```

Install with the shadcn CLI or use the shared `@workspace/ui` package. Follow the [installation guide](/docs/installation) to configure the registry, load styles, and choose import aliases.

## Usage

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

```tsx
<Attachment>
  <AttachmentMedia>
    <FileTextIcon />
  </AttachmentMedia>
  <AttachmentContent>
    <AttachmentTitle>sales-dashboard.pdf</AttachmentTitle>
    <AttachmentDescription>PDF · 2.4 MB</AttachmentDescription>
  </AttachmentContent>
  <AttachmentActions>
    <AttachmentAction aria-label="Remove sales-dashboard.pdf">
      <XIcon />
    </AttachmentAction>
  </AttachmentActions>
</Attachment>
```

## Composition

Use the following composition to build an attachment:

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

Use `AttachmentGroup` to lay out multiple attachments in a scrollable row:

```text
AttachmentGroup
├── Attachment
└── Attachment
```

## Features

- Icon and image media through `AttachmentMedia`
- Upload states: `idle`, `uploading`, `processing`, `error`, and `done` with built-in styling and a shimmer while in progress
- Three sizes and horizontal or vertical orientation
- A full-card `AttachmentTrigger` that opens a link or dialog while the actions stay independently clickable
- Scrollable, snapping `AttachmentGroup` with an edge fade
- Customizable styling through the `className` prop on every part

## Image

Set `variant="image"` on `AttachmentMedia` and render an `<img>` inside it. Use `orientation="vertical"` to stack the media above the content.

### Example: attachment-image

```tsx
import {
  Attachment,
  AttachmentAction,
  AttachmentActions,
  AttachmentContent,
  AttachmentDescription,
  AttachmentGroup,
  AttachmentMedia,
  AttachmentTitle,
  AttachmentTrigger,
} from "@workspace/ui/components/attachment";
import { XIcon } from "lucide-react";

const images = [
  {
    name: "workspace.png",
    meta: "PNG · 820 KB",
    src: "https://images.unsplash.com/photo-1497366754035-f200968a6e72?w=900&auto=format&fit=crop&q=80",
    alt: "Workspace",
  },
  {
    name: "desk-reference.jpg",
    meta: "JPG · 1.1 MB",
    src: "https://images.unsplash.com/photo-1497215728101-856f4ea42174?w=900&auto=format&fit=crop&q=80",
    alt: "Desk",
  },
  {
    name: "office-reference.jpg",
    meta: "JPG · 940 KB",
    src: "https://images.unsplash.com/photo-1497366811353-6870744d04b2?w=900&auto=format&fit=crop&q=80",
    alt: "Office",
  },
];

export function AttachmentImage() {
  return (
    <div className="mx-auto w-full max-w-sm py-12">
      <AttachmentGroup className="w-full">
        {images.map((image) => (
          <Attachment key={image.name} orientation="vertical">
            <AttachmentMedia variant="image">
              <img src={image.src} alt={image.alt} />
            </AttachmentMedia>
            <AttachmentContent>
              <AttachmentTitle>{image.name}</AttachmentTitle>
              <AttachmentDescription>{image.meta}</AttachmentDescription>
            </AttachmentContent>
            <AttachmentActions>
              <AttachmentAction aria-label={`Remove ${image.name}`}>
                <XIcon />
              </AttachmentAction>
            </AttachmentActions>
            <AttachmentTrigger
              render={
                <a
                  href={image.src}
                  target="_blank"
                  rel="noreferrer"
                  aria-label={`Open ${image.name}`}
                />
              }
            />
          </Attachment>
        ))}
      </AttachmentGroup>
    </div>
  );
}

export default AttachmentImage;
```

## States

Set `state` to reflect the upload lifecycle. `uploading` and `processing` shimmer the title, and `error` switches to a destructive treatment.

### Example: attachment-states

```tsx
import {
  Attachment,
  AttachmentAction,
  AttachmentActions,
  AttachmentContent,
  AttachmentDescription,
  AttachmentMedia,
  AttachmentTitle,
} from "@workspace/ui/components/attachment";
import { Loader } from "@workspace/ui/components/loader";
import {
  CheckIcon,
  ClockIcon,
  FileTextIcon,
  FileWarningIcon,
  RefreshCwIcon,
  XIcon,
} from "lucide-react";

export function AttachmentStates() {
  return (
    <div className="mx-auto flex w-full max-w-sm flex-col gap-2 py-12">
      <Attachment state="idle" className="w-full">
        <AttachmentMedia>
          <ClockIcon />
        </AttachmentMedia>
        <AttachmentContent>
          <AttachmentTitle>selected-file.pdf</AttachmentTitle>
          <AttachmentDescription>Ready to upload</AttachmentDescription>
        </AttachmentContent>
        <AttachmentActions>
          <AttachmentAction aria-label="Remove selected-file.pdf">
            <XIcon />
          </AttachmentAction>
        </AttachmentActions>
      </Attachment>
      <Attachment state="uploading" className="w-full">
        <AttachmentMedia>
          <Loader size="sm" />
        </AttachmentMedia>
        <AttachmentContent>
          <AttachmentTitle>design-system.zip</AttachmentTitle>
          <AttachmentDescription>Uploading · 64%</AttachmentDescription>
        </AttachmentContent>
        <AttachmentActions>
          <AttachmentAction aria-label="Cancel upload">
            <XIcon />
          </AttachmentAction>
        </AttachmentActions>
      </Attachment>
      <Attachment state="processing" className="w-full">
        <AttachmentMedia>
          <FileTextIcon />
        </AttachmentMedia>
        <AttachmentContent>
          <AttachmentTitle>market-research.pdf</AttachmentTitle>
          <AttachmentDescription>Processing document</AttachmentDescription>
        </AttachmentContent>
        <AttachmentActions>
          <AttachmentAction aria-label="Remove market-research.pdf">
            <XIcon />
          </AttachmentAction>
        </AttachmentActions>
      </Attachment>
      <Attachment state="error" className="w-full">
        <AttachmentMedia>
          <FileWarningIcon />
        </AttachmentMedia>
        <AttachmentContent>
          <AttachmentTitle>financial-model.xlsx</AttachmentTitle>
          <AttachmentDescription>
            Upload failed. Try again.
          </AttachmentDescription>
        </AttachmentContent>
        <AttachmentActions>
          <AttachmentAction aria-label="Retry upload">
            <RefreshCwIcon />
          </AttachmentAction>
          <AttachmentAction aria-label="Remove financial-model.xlsx">
            <XIcon />
          </AttachmentAction>
        </AttachmentActions>
      </Attachment>
      <Attachment state="done" className="w-full">
        <AttachmentMedia>
          <CheckIcon />
        </AttachmentMedia>
        <AttachmentContent>
          <AttachmentTitle>uploaded-report.pdf</AttachmentTitle>
          <AttachmentDescription>Uploaded · 1.8 MB</AttachmentDescription>
        </AttachmentContent>
        <AttachmentActions>
          <AttachmentAction aria-label="Remove uploaded-report.pdf">
            <XIcon />
          </AttachmentAction>
        </AttachmentActions>
      </Attachment>
    </div>
  );
}

export default AttachmentStates;
```

## Sizes

Use `size` to switch between `default`, `sm`, and `xs`.

### Example: attachment-sizes

```tsx
import {
  Attachment,
  AttachmentContent,
  AttachmentDescription,
  AttachmentMedia,
  AttachmentTitle,
} from "@workspace/ui/components/attachment";
import { FileTextIcon } from "lucide-react";

export function AttachmentSizes() {
  return (
    <div className="mx-auto flex w-full max-w-sm flex-col gap-3 py-12">
      <Attachment size="default" className="w-full">
        <AttachmentMedia>
          <FileTextIcon />
        </AttachmentMedia>
        <AttachmentContent>
          <AttachmentTitle>Default attachment</AttachmentTitle>
          <AttachmentDescription>PDF · 2.4 MB</AttachmentDescription>
        </AttachmentContent>
      </Attachment>
      <Attachment size="sm" className="w-full">
        <AttachmentMedia>
          <FileTextIcon />
        </AttachmentMedia>
        <AttachmentContent>
          <AttachmentTitle>Small attachment</AttachmentTitle>
          <AttachmentDescription>PDF · 2.4 MB</AttachmentDescription>
        </AttachmentContent>
      </Attachment>
      <Attachment size="xs" className="w-full">
        <AttachmentMedia>
          <FileTextIcon />
        </AttachmentMedia>
        <AttachmentContent>
          <AttachmentTitle>Extra small attachment</AttachmentTitle>
        </AttachmentContent>
      </Attachment>
    </div>
  );
}

export default AttachmentSizes;
```

## Group

Wrap attachments in `AttachmentGroup` to lay them out in a horizontally scrollable, snapping row with an edge fade.

### Example: attachment-group

```tsx
import {
  Attachment,
  AttachmentAction,
  AttachmentActions,
  AttachmentContent,
  AttachmentDescription,
  AttachmentGroup,
  AttachmentMedia,
  AttachmentTitle,
} from "@workspace/ui/components/attachment";
import {
  FileCodeIcon,
  FileTextIcon,
  type LucideIcon,
  TableIcon,
  XIcon,
} from "lucide-react";
import type { ReactNode } from "react";

type Item = {
  name: string;
  meta: string;
  icon?: LucideIcon;
  src?: string;
};

const items: Item[] = [
  { name: "briefing-notes.pdf", meta: "PDF · 1.4 MB", icon: FileTextIcon },
  {
    name: "workspace.png",
    meta: "PNG · 820 KB",
    src: "https://images.unsplash.com/photo-1497366754035-f200968a6e72?w=900&auto=format&fit=crop&q=80",
  },
  { name: "customers.csv", meta: "CSV · 18 KB", icon: TableIcon },
  { name: "renderer.tsx", meta: "TSX · 12 KB", icon: FileCodeIcon },
];

export function AttachmentGroupDemo() {
  return (
    <div className="mx-auto w-full max-w-sm py-12">
      <AttachmentGroup className="w-full">
        {items.map((item) => {
          const Icon = item.icon;
          let media: ReactNode = null;
          if (item.src) {
            media = (
              <AttachmentMedia variant="image">
                <img src={item.src} alt={item.name} />
              </AttachmentMedia>
            );
          } else if (Icon) {
            media = (
              <AttachmentMedia>
                <Icon />
              </AttachmentMedia>
            );
          }

          return (
            <Attachment key={item.name} className="w-64">
              {media}
              <AttachmentContent>
                <AttachmentTitle>{item.name}</AttachmentTitle>
                <AttachmentDescription>{item.meta}</AttachmentDescription>
              </AttachmentContent>
              <AttachmentActions>
                <AttachmentAction aria-label={`Remove ${item.name}`}>
                  <XIcon />
                </AttachmentAction>
              </AttachmentActions>
            </Attachment>
          );
        })}
      </AttachmentGroup>
    </div>
  );
}

export default AttachmentGroupDemo;
```

## Trigger

Add an `AttachmentTrigger` to make the whole card open a link or dialog. It fills the card behind the actions, so the actions stay clickable.

### Example: attachment-trigger

```tsx
import {
  Attachment,
  AttachmentAction,
  AttachmentActions,
  AttachmentContent,
  AttachmentDescription,
  AttachmentMedia,
  AttachmentTitle,
  AttachmentTrigger,
} from "@workspace/ui/components/attachment";
import {
  Dialog,
  DialogContent,
  DialogDescription,
  DialogHeader,
  DialogTitle,
  DialogTrigger,
} from "@workspace/ui/components/dialog";
import { CopyIcon, FileSearchIcon, XIcon } from "lucide-react";

export function AttachmentTriggerDemo() {
  return (
    <div className="mx-auto w-full max-w-sm py-12">
      <Dialog>
        <Attachment className="w-full">
          <AttachmentMedia>
            <FileSearchIcon />
          </AttachmentMedia>
          <AttachmentContent>
            <AttachmentTitle>research-summary.pdf</AttachmentTitle>
            <AttachmentDescription>Open preview dialog</AttachmentDescription>
          </AttachmentContent>
          <AttachmentActions>
            <AttachmentAction aria-label="Copy link">
              <CopyIcon />
            </AttachmentAction>
            <AttachmentAction aria-label="Remove research-summary.pdf">
              <XIcon />
            </AttachmentAction>
          </AttachmentActions>
          <DialogTrigger
            render={
              <AttachmentTrigger aria-label="Preview research-summary.pdf" />
            }
          />
        </Attachment>
        <DialogContent className="sm:max-w-md">
          <DialogHeader>
            <DialogTitle>research-summary.pdf</DialogTitle>
            <DialogDescription>
              The attachment trigger fills the card and opens the dialog, while
              the actions stay independently clickable above it.
            </DialogDescription>
          </DialogHeader>
        </DialogContent>
      </Dialog>
    </div>
  );
}

export default AttachmentTriggerDemo;
```

```tsx showLineNumbers
<Dialog>
  <Attachment>
    {/* media, content, actions */}
    <DialogTrigger
      render={<AttachmentTrigger aria-label="Preview research-summary.pdf" />}
    />
  </Attachment>
  <DialogContent>{/* ... */}</DialogContent>
</Dialog>
```

## Accessibility

`AttachmentAction` renders a `Button`, and `AttachmentTrigger` renders a real `<button>` (or your element via `render`). Follow the guidance below so both are operable and announced.

### Label icon-only actions

`AttachmentAction` is usually icon-only, so give each one an `aria-label` describing the action and its target.

```tsx showLineNumbers
<AttachmentAction aria-label="Remove sales-dashboard.pdf">
  <XIcon />
</AttachmentAction>
```

### Label the trigger

`AttachmentTrigger` covers the card with no text of its own, so give it an `aria-label` for what activating it does.

```tsx showLineNumbers
<AttachmentTrigger
  render={
    <a
      href={url}
      target="_blank"
      rel="noreferrer"
      aria-label="Open workspace.png"
    />
  }
/>
```

The trigger sits behind the actions in the stacking order, so an `AttachmentAction` and the `AttachmentTrigger` never trap each other — both remain separately focusable and clickable.

### Keyboard scrolling

An `AttachmentGroup` scrolls horizontally. When its attachments are interactive: a trigger or actions, keyboard users reach off-screen items by tabbing to them. For a row of presentational attachments, make the group itself focusable and scrollable by adding `tabIndex={0}`, `role="group"`, and an `aria-label`.

### Meaning beyond color

The `error` state uses a destructive color. Keep the failure reason in `AttachmentDescription` so the state is not conveyed by color alone.

## API Reference

### Attachment

The root attachment container.

| Prop          | Type                                                         | Default        | Description                                       |
| ------------- | ------------------------------------------------------------ | -------------- | ------------------------------------------------- |
| `state`       | `"idle" \| "uploading" \| "processing" \| "error" \| "done"` | `"done"`       | The upload state. Drives styling and the shimmer. |
| `size`        | `"default" \| "sm" \| "xs"`                                  | `"default"`    | The attachment size.                              |
| `orientation` | `"horizontal" \| "vertical"`                                 | `"horizontal"` | Lay the media beside or above the content.        |
| `className`   | `string`                                                     | -              | Additional classes to apply to the root element.  |

### AttachmentMedia

The media slot for an icon or image preview.

| Prop        | Type                | Default  | Description                                    |
| ----------- | ------------------- | -------- | ---------------------------------------------- |
| `variant`   | `"icon" \| "image"` | `"icon"` | Whether the media holds an icon or an `<img>`. |
| `className` | `string`            | -        | Additional classes to apply to the media slot. |

### AttachmentContent

Wraps the title and description.

| Prop        | Type     | Default | Description                                      |
| ----------- | -------- | ------- | ------------------------------------------------ |
| `className` | `string` | -       | Additional classes to apply to the content slot. |

### AttachmentTitle

The attachment name. Shimmers while the attachment is `uploading` or `processing`.

| Prop        | Type     | Default | Description                               |
| ----------- | -------- | ------- | ----------------------------------------- |
| `className` | `string` | -       | Additional classes to apply to the title. |

### AttachmentDescription

Secondary metadata such as the file type, size, or upload status.

| Prop        | Type     | Default | Description                                     |
| ----------- | -------- | ------- | ----------------------------------------------- |
| `className` | `string` | -       | Additional classes to apply to the description. |

### AttachmentActions

A container for one or more actions, aligned to the end of the attachment.

| Prop        | Type     | Default | Description                                 |
| ----------- | -------- | ------- | ------------------------------------------- |
| `className` | `string` | -       | Additional classes to apply to the actions. |

### AttachmentAction

An action button. Renders a [`Button`](/docs/components/button) and accepts all of its props.

| Prop       | Type                                  | Default     | Description                              |
| ---------- | ------------------------------------- | ----------- | ---------------------------------------- |
| `size`     | `Button["size"]`                      | `"icon-xs"` | The button size.                         |
| `...props` | `React.ComponentProps<typeof Button>` | -           | Props spread to the underlying `Button`. |

### AttachmentTrigger

A full-card overlay that activates the attachment. Renders a `<button>` by default.

| Prop       | Type                             | Default | Description                                    |
| ---------- | -------------------------------- | ------- | ---------------------------------------------- |
| `render`   | `ReactElement \| function`       | -       | Render as a different element, such as a link. |
| `...props` | `React.ComponentProps<"button">` | -       | Props spread to the trigger element.           |

### AttachmentGroup

Lays out attachments in a horizontally scrollable, snapping row.

| Prop        | Type     | Default | Description                               |
| ----------- | -------- | ------- | ----------------------------------------- |
| `className` | `string` | -       | Additional classes to apply to the group. |


---

# Autocomplete

Suggests matching options while keeping the input free to accept custom text.

Page: https://sui.draco.dev/docs/components/autocomplete

Autocomplete combines a text input with a filtered list of suggestions. Its value is the input text, so users can accept a suggestion or enter their own answer. For a selection that must stay within a list of options, use [Combobox](/docs/components/combobox).

### Example: autocomplete-demo

```tsx
import {
  Autocomplete,
  AutocompleteClear,
  AutocompleteContent,
  AutocompleteEmpty,
  AutocompleteInput,
  AutocompleteInputGroup,
  AutocompleteItem,
  AutocompleteList,
  AutocompleteTrigger,
} from "@workspace/ui/components/autocomplete";
import {
  Field,
  FieldDescription,
  FieldLabel,
} from "@workspace/ui/components/field";
import { InputGroupAddon } from "@workspace/ui/components/input-group";
import { useId, useState } from "react";
import type { ExampleProps } from "../types";

export default function AutocompleteDemo({ locale }: ExampleProps) {
  const chinese = locale === "zh-CN";
  const id = useId();
  const [query, setQuery] = useState("");
  const cities = chinese
    ? ["北京", "上海", "杭州", "成都", "深圳"]
    : ["Beijing", "Shanghai", "Hangzhou", "Chengdu", "Shenzhen"];

  return (
    <Field className="w-full max-w-sm">
      <FieldLabel htmlFor={id}>{chinese ? "目的地" : "Destination"}</FieldLabel>
      <Autocomplete
        items={cities}
        value={query}
        onValueChange={setQuery}
        openOnInputClick
      >
        <AutocompleteInputGroup>
          <AutocompleteInput
            id={id}
            placeholder={chinese ? "选择或输入城市" : "Choose or type a city"}
          />
          <InputGroupAddon align="inline-end">
            <AutocompleteClear
              aria-label={chinese ? "清空目的地" : "Clear destination"}
            />
            <AutocompleteTrigger
              aria-label={chinese ? "显示城市建议" : "Show city suggestions"}
            />
          </InputGroupAddon>
        </AutocompleteInputGroup>
        <AutocompleteContent>
          <AutocompleteEmpty>
            {chinese
              ? "没有匹配的城市，仍可使用你输入的名称"
              : "No matching cities. You can still use your own text."}
          </AutocompleteEmpty>
          <AutocompleteList>
            {(city: string) => (
              <AutocompleteItem key={city} value={city}>
                {city}
              </AutocompleteItem>
            )}
          </AutocompleteList>
        </AutocompleteContent>
      </Autocomplete>
      <FieldDescription>
        {chinese
          ? "城市建议不会限制自由输入。使用方向键浏览，Enter 采用建议，Escape 关闭"
          : "Suggestions do not restrict your input. Use arrow keys to browse, Enter to accept, and Escape to close."}
      </FieldDescription>
      <output className="text-muted-foreground text-sm" aria-live="polite">
        {chinese ? "当前输入" : "Current input"}: {query || "—"}
      </output>
    </Field>
  );
}
```

## Installation

```bash
bunx --bun shadcn@latest add @sui/autocomplete
```

Install with the shadcn CLI or use the shared `@workspace/ui` package. Follow the [installation guide](/docs/installation) to configure the registry, load styles, and choose import aliases.

## Usage

```tsx showLineNumbers
import {
  Autocomplete,
  AutocompleteContent,
  AutocompleteEmpty,
  AutocompleteInput,
  AutocompleteInputGroup,
  AutocompleteItem,
  AutocompleteList,
} from "@workspace/ui/components/autocomplete"
import { Field, FieldLabel } from "@workspace/ui/components/field"

const languages = ["TypeScript", "JavaScript", "Rust"]

<Field>
  <FieldLabel>Project language</FieldLabel>
  <Autocomplete items={languages} openOnInputClick>
    <AutocompleteInputGroup>
      <AutocompleteInput aria-label="Project language" placeholder="Choose or type a language" />
    </AutocompleteInputGroup>
    <AutocompleteContent>
      <AutocompleteEmpty>No suggestions found.</AutocompleteEmpty>
      <AutocompleteList>
        {(language: string) => (
          <AutocompleteItem key={language} value={language}>
            {language}
          </AutocompleteItem>
        )}
      </AutocompleteList>
    </AutocompleteContent>
  </Autocomplete>
</Field>
```

## Suggestions and clearing

Use `AutocompleteInputGroup` to anchor the popup to the complete input. Add `AutocompleteTrigger` and `AutocompleteClear` inside an `InputGroupAddon` when the field needs explicit suggestion and clear buttons. Give icon controls accessible labels.

Pass `value` and `onValueChange` to `Autocomplete` for a controlled text input. `openOnInputClick` also shows suggestions when the input is clicked. `autoHighlight` highlights the first match after typing; `mode="both"` enables inline completion alongside filtering.

## Grouped suggestions

Provide groups with an `items` array, render each group inside `AutocompleteList`, and use `AutocompleteCollection` to render its items. For object items, `itemToStringValue` defines the text placed in the input.

### Example: autocomplete-grouped

```tsx
import {
  Autocomplete,
  AutocompleteCollection,
  AutocompleteContent,
  AutocompleteEmpty,
  AutocompleteGroup,
  AutocompleteGroupLabel,
  AutocompleteInput,
  AutocompleteInputGroup,
  AutocompleteItem,
  AutocompleteList,
} from "@workspace/ui/components/autocomplete";
import { Field, FieldLabel } from "@workspace/ui/components/field";
import { useId } from "react";
import type { ExampleProps } from "../types";

interface Destination {
  id: string;
  label: string;
}
interface DestinationGroup {
  value: string;
  items: Destination[];
}

export default function AutocompleteGrouped({ locale }: ExampleProps) {
  const chinese = locale === "zh-CN";
  const id = useId();
  const groups: DestinationGroup[] = [
    {
      value: chinese ? "亚洲" : "Asia",
      items: [
        { id: "tokyo", label: chinese ? "东京" : "Tokyo" },
        { id: "singapore", label: chinese ? "新加坡" : "Singapore" },
      ],
    },
    {
      value: chinese ? "欧洲" : "Europe",
      items: [
        { id: "paris", label: chinese ? "巴黎" : "Paris" },
        { id: "london", label: chinese ? "伦敦" : "London" },
      ],
    },
  ];

  return (
    <Field className="w-full max-w-sm">
      <FieldLabel htmlFor={id}>
        {chinese ? "按地区浏览目的地" : "Browse destinations by region"}
      </FieldLabel>
      <Autocomplete
        items={groups}
        itemToStringValue={(item) => item.label}
        openOnInputClick
        autoHighlight
      >
        <AutocompleteInputGroup>
          <AutocompleteInput
            id={id}
            placeholder={chinese ? "搜索城市" : "Search cities"}
          />
        </AutocompleteInputGroup>
        <AutocompleteContent>
          <AutocompleteEmpty>
            {chinese ? "没有找到城市" : "No cities found."}
          </AutocompleteEmpty>
          <AutocompleteList>
            {(group: DestinationGroup) => (
              <AutocompleteGroup key={group.value} items={group.items}>
                <AutocompleteGroupLabel>{group.value}</AutocompleteGroupLabel>
                <AutocompleteCollection>
                  {(destination: Destination) => (
                    <AutocompleteItem key={destination.id} value={destination}>
                      {destination.label}
                    </AutocompleteItem>
                  )}
                </AutocompleteCollection>
              </AutocompleteGroup>
            )}
          </AutocompleteList>
        </AutocompleteContent>
      </Autocomplete>
    </Field>
  );
}
```

## Disabled controls and items

Set `disabled` on `Autocomplete` to disable the input and its controls. Set `disabled` on a particular `AutocompleteItem` to leave it visible without allowing interaction. Use the switch below to enable the field; the Go suggestion remains unavailable.

### Example: autocomplete-disabled

```tsx
import {
  Autocomplete,
  AutocompleteContent,
  AutocompleteEmpty,
  AutocompleteInput,
  AutocompleteInputGroup,
  AutocompleteItem,
  AutocompleteList,
  AutocompleteTrigger,
} from "@workspace/ui/components/autocomplete";
import {
  Field,
  FieldDescription,
  FieldGroup,
  FieldLabel,
} from "@workspace/ui/components/field";
import { InputGroupAddon } from "@workspace/ui/components/input-group";
import { Switch } from "@workspace/ui/components/switch";
import { useId, useState } from "react";
import type { ExampleProps } from "../types";

export default function AutocompleteDisabled({ locale }: ExampleProps) {
  const chinese = locale === "zh-CN";
  const unavailableLabel = chinese ? "（暂不可用）" : " (unavailable)";
  const id = useId();
  const switchId = useId();
  const [disabled, setDisabled] = useState(true);
  const languages = ["TypeScript", "JavaScript", "Rust", "Go"];

  return (
    <FieldGroup className="w-full max-w-sm">
      <Field orientation="horizontal">
        <Switch
          id={switchId}
          checked={disabled}
          onCheckedChange={setDisabled}
        />
        <FieldLabel htmlFor={switchId}>
          {chinese ? "禁用建议输入框" : "Disable autocomplete"}
        </FieldLabel>
      </Field>
      <Field data-disabled={disabled}>
        <FieldLabel htmlFor={id}>
          {chinese ? "项目语言" : "Project language"}
        </FieldLabel>
        <Autocomplete
          items={languages}
          disabled={disabled}
          defaultValue="TypeScript"
          openOnInputClick
        >
          <AutocompleteInputGroup>
            <AutocompleteInput id={id} />
            <InputGroupAddon align="inline-end">
              <AutocompleteTrigger
                aria-label={
                  chinese ? "显示语言建议" : "Show language suggestions"
                }
              />
            </InputGroupAddon>
          </AutocompleteInputGroup>
          <AutocompleteContent>
            <AutocompleteEmpty>
              {chinese ? "没有匹配的语言" : "No matching languages."}
            </AutocompleteEmpty>
            <AutocompleteList>
              {(language: string) => (
                <AutocompleteItem
                  key={language}
                  value={language}
                  disabled={language === "Go"}
                >
                  {language}
                  {language === "Go" ? unavailableLabel : ""}
                </AutocompleteItem>
              )}
            </AutocompleteList>
          </AutocompleteContent>
        </Autocomplete>
        <FieldDescription>
          {chinese
            ? "开启控件后可以输入和浏览建议。Go 选项保持禁用"
            : "Enable the control to type and browse suggestions. The Go option stays disabled."}
        </FieldDescription>
      </Field>
    </FieldGroup>
  );
}
```

## Accessibility and keyboard

Provide a visible `FieldLabel` or an `aria-label` for the input. When linking a label explicitly, use React `useId()` so examples and repeated fields keep independent IDs.

Type to filter suggestions. Arrow keys move the highlighted suggestion, Enter accepts it, and Escape closes the popup. A disabled suggestion cannot be accepted. Suggestions do not make custom text invalid; add application validation when the field needs it.

## API reference

| Part | Purpose |
| --- | --- |
| `Autocomplete` | Owns items, filtering, input `value`, `onValueChange`, `mode`, opening, and disabled state. |
| `AutocompleteInputGroup`, `AutocompleteInput` | Compose the styled input and its anchor. The input keeps standard input props and a React 19 `ref`. |
| `AutocompleteTrigger`, `AutocompleteClear` | Open the suggestion popup or clear the input. Both support `render` composition. |
| `AutocompleteContent` | Composes the portal and positioning. Defaults to bottom/start with a `sideOffset` of `6`; accepts `side`, `align`, offsets, and `anchor`. |
| `AutocompleteList`, `AutocompleteItem` | Render filtered suggestions with keyboard highlighting and per-item `disabled`. |
| `AutocompleteGroup`, `AutocompleteGroupLabel`, `AutocompleteCollection` | Render labeled groups and their filtered items. |
| `AutocompleteEmpty`, `AutocompleteStatus`, `AutocompleteSeparator` | Show empty results, accessible status, and visual separators. |
| `AutocompleteValue` | Render the current input text with a child render function. |
| `useAutocompleteFilter`, `useAutocompleteFilteredItems` | Reuse filtering helpers for custom matching or externally filtered lists. |

See the [Base UI Autocomplete API](https://base-ui.com/react/components/autocomplete#api-reference) for the primitive props and event details.


---

# Avatar

An image element with a fallback for representing the user.

Page: https://sui.draco.dev/docs/components/avatar

### Example: avatar-demo

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

export default function AvatarDemo() {
  return (
    <div className="flex flex-row flex-wrap items-center gap-6 md:gap-12">
      <Avatar>
        <AvatarImage
          src="https://github.com/shadcn.png"
          alt="@shadcn"
          className="grayscale"
        />
        <AvatarFallback>CN</AvatarFallback>
      </Avatar>
      <Avatar>
        <AvatarImage
          src="https://github.com/evilrabbit.png"
          alt="@evilrabbit"
        />
        <AvatarFallback>ER</AvatarFallback>
        <AvatarBadge className="bg-green-600 dark:bg-green-800" />
      </Avatar>
      <AvatarGroup className="grayscale">
        <Avatar>
          <AvatarImage src="https://github.com/shadcn.png" alt="@shadcn" />
          <AvatarFallback>CN</AvatarFallback>
        </Avatar>
        <Avatar>
          <AvatarImage
            src="https://github.com/maxleiter.png"
            alt="@maxleiter"
          />
          <AvatarFallback>LR</AvatarFallback>
        </Avatar>
        <Avatar>
          <AvatarImage
            src="https://github.com/evilrabbit.png"
            alt="@evilrabbit"
          />
          <AvatarFallback>ER</AvatarFallback>
        </Avatar>
        <AvatarGroupCount>+3</AvatarGroupCount>
      </AvatarGroup>
    </div>
  );
}
```

## Installation

```bash
bunx --bun shadcn@latest add @sui/avatar
```

Install with the shadcn CLI or use the shared `@workspace/ui` package. Follow the [installation guide](/docs/installation) to configure the registry, load styles, and choose import aliases.

## Usage

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

```tsx showLineNumbers
<Avatar>
  <AvatarImage src="https://github.com/shadcn.png" />
  <AvatarFallback>CN</AvatarFallback>
</Avatar>
```

## Composition

Use the following composition to build an `Avatar`:

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

Use the following composition to build an `AvatarGroup`:

```text
AvatarGroup
├── Avatar
│   ├── AvatarImage
│   ├── AvatarFallback
│   └── AvatarBadge
├── Avatar
│   ├── AvatarImage
│   ├── AvatarFallback
│   └── AvatarBadge
└── AvatarGroupCount
```

## Basic

A basic avatar component with an image and a fallback.

### Example: avatar-basic

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

export default function AvatarDemo() {
  return (
    <Avatar>
      <AvatarImage
        src="https://github.com/shadcn.png"
        alt="@shadcn"
        className="grayscale"
      />
      <AvatarFallback>CN</AvatarFallback>
    </Avatar>
  );
}
```

## Badge

Use the `AvatarBadge` component to add a badge to the avatar. The badge is positioned at the bottom right of the avatar.

### Example: avatar-badge

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

export function AvatarWithBadge() {
  return (
    <Avatar>
      <AvatarImage src="https://github.com/shadcn.png" alt="@shadcn" />
      <AvatarFallback>CN</AvatarFallback>
      <AvatarBadge className="bg-green-600 dark:bg-green-800" />
    </Avatar>
  );
}

export default AvatarWithBadge;
```

Use the `className` prop to add custom styles to the badge such as custom colors, sizes, etc.

```tsx showLineNumbers
<Avatar>
  <AvatarImage src="https://github.com/shadcn.png" alt="@shadcn" />
  <AvatarFallback>CN</AvatarFallback>
  <AvatarBadge className="bg-green-600 dark:bg-green-800" />
</Avatar>
```

## Badge with Icon

You can also use an icon inside `<AvatarBadge>`.

### Example: avatar-badge-icon

```tsx
import {
  Avatar,
  AvatarBadge,
  AvatarFallback,
  AvatarImage,
} from "@workspace/ui/components/avatar";
import { PlusIcon } from "lucide-react";

export function AvatarBadgeIconExample() {
  return (
    <Avatar className="grayscale">
      <AvatarImage src="https://github.com/pranathip.png" alt="@pranathip" />
      <AvatarFallback>PP</AvatarFallback>
      <AvatarBadge>
        <PlusIcon />
      </AvatarBadge>
    </Avatar>
  );
}

export default AvatarBadgeIconExample;
```

## Avatar Group

Use the `AvatarGroup` component to add a group of avatars.

### Example: avatar-group

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

export function AvatarGroupExample() {
  return (
    <AvatarGroup className="grayscale">
      <Avatar>
        <AvatarImage src="https://github.com/shadcn.png" alt="@shadcn" />
        <AvatarFallback>CN</AvatarFallback>
      </Avatar>
      <Avatar>
        <AvatarImage src="https://github.com/maxleiter.png" alt="@maxleiter" />
        <AvatarFallback>LR</AvatarFallback>
      </Avatar>
      <Avatar>
        <AvatarImage
          src="https://github.com/evilrabbit.png"
          alt="@evilrabbit"
        />
        <AvatarFallback>ER</AvatarFallback>
      </Avatar>
    </AvatarGroup>
  );
}

export default AvatarGroupExample;
```

## Avatar Group Count

Use `<AvatarGroupCount>` to add a count to the group.

### Example: avatar-group-count

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

export function AvatarGroupCountExample() {
  return (
    <AvatarGroup className="grayscale">
      <Avatar>
        <AvatarImage src="https://github.com/shadcn.png" alt="@shadcn" />
        <AvatarFallback>CN</AvatarFallback>
      </Avatar>
      <Avatar>
        <AvatarImage src="https://github.com/maxleiter.png" alt="@maxleiter" />
        <AvatarFallback>LR</AvatarFallback>
      </Avatar>
      <Avatar>
        <AvatarImage
          src="https://github.com/evilrabbit.png"
          alt="@evilrabbit"
        />
        <AvatarFallback>ER</AvatarFallback>
      </Avatar>
      <AvatarGroupCount>+3</AvatarGroupCount>
    </AvatarGroup>
  );
}

export default AvatarGroupCountExample;
```

## Avatar Group with Icon

You can also use an icon inside `<AvatarGroupCount>`.

### Example: avatar-group-count-icon

```tsx
import {
  Avatar,
  AvatarFallback,
  AvatarGroup,
  AvatarGroupCount,
  AvatarImage,
} from "@workspace/ui/components/avatar";
import { PlusIcon } from "lucide-react";

export function AvatarGroupCountIconExample() {
  return (
    <AvatarGroup className="grayscale">
      <Avatar>
        <AvatarImage src="https://github.com/shadcn.png" alt="@shadcn" />
        <AvatarFallback>CN</AvatarFallback>
      </Avatar>
      <Avatar>
        <AvatarImage src="https://github.com/maxleiter.png" alt="@maxleiter" />
        <AvatarFallback>LR</AvatarFallback>
      </Avatar>
      <Avatar>
        <AvatarImage
          src="https://github.com/evilrabbit.png"
          alt="@evilrabbit"
        />
        <AvatarFallback>ER</AvatarFallback>
      </Avatar>
      <AvatarGroupCount>
        <PlusIcon />
      </AvatarGroupCount>
    </AvatarGroup>
  );
}

export default AvatarGroupCountIconExample;
```

## Sizes

Use the `size` prop to change the size of the avatar.

### Example: avatar-size

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

export function AvatarSizeExample() {
  return (
    <div className="flex flex-wrap items-center gap-2 grayscale">
      <Avatar size="sm">
        <AvatarImage src="https://github.com/shadcn.png" alt="@shadcn" />
        <AvatarFallback>CN</AvatarFallback>
      </Avatar>
      <Avatar>
        <AvatarImage src="https://github.com/shadcn.png" alt="@shadcn" />
        <AvatarFallback>CN</AvatarFallback>
      </Avatar>
      <Avatar size="lg">
        <AvatarImage src="https://github.com/shadcn.png" alt="@shadcn" />
        <AvatarFallback>CN</AvatarFallback>
      </Avatar>
    </div>
  );
}

export default AvatarSizeExample;
```

## Dropdown

You can use the `Avatar` component as a trigger for a dropdown menu.

### Example: avatar-dropdown

```tsx
"use client";

import {
  Avatar,
  AvatarFallback,
  AvatarImage,
} from "@workspace/ui/components/avatar";
import { Button } from "@workspace/ui/components/button";
import {
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuGroup,
  DropdownMenuItem,
  DropdownMenuSeparator,
  DropdownMenuTrigger,
} from "@workspace/ui/components/dropdown-menu";

export function AvatarDropdown() {
  return (
    <DropdownMenu>
      <DropdownMenuTrigger
        render={<Button variant="ghost" size="icon" className="rounded-full" />}
      >
        <Avatar>
          <AvatarImage src="https://github.com/shadcn.png" alt="shadcn" />
          <AvatarFallback>CN</AvatarFallback>
        </Avatar>
      </DropdownMenuTrigger>
      <DropdownMenuContent className="w-32">
        <DropdownMenuGroup>
          <DropdownMenuItem>Profile</DropdownMenuItem>
          <DropdownMenuItem>Billing</DropdownMenuItem>
          <DropdownMenuItem>Settings</DropdownMenuItem>
        </DropdownMenuGroup>
        <DropdownMenuSeparator />
        <DropdownMenuGroup>
          <DropdownMenuItem variant="destructive">Log out</DropdownMenuItem>
        </DropdownMenuGroup>
      </DropdownMenuContent>
    </DropdownMenu>
  );
}

export default AvatarDropdown;
```

## RTL

To enable RTL support in shadcn/ui, see the [RTL configuration guide](https://ui.shadcn.com/docs/rtl).

### Example: avatar-rtl

```tsx
"use client";

import {
  Avatar,
  AvatarBadge,
  AvatarFallback,
  AvatarGroup,
  AvatarGroupCount,
  AvatarImage,
} from "@workspace/ui/components/avatar";
import { type Translations, useTranslation } from "./support";

const translations: Translations = {
  en: {
    dir: "ltr",
    values: {
      moreUsers: "+3",
    },
  },
  ar: {
    dir: "rtl",
    values: {
      moreUsers: "+٣",
    },
  },
  he: {
    dir: "rtl",
    values: {
      moreUsers: "+3",
    },
  },
};

export function AvatarRtl() {
  const { dir, t } = useTranslation(translations, "ar");

  return (
    <div
      className="flex flex-row flex-wrap items-center gap-6 md:gap-12"
      dir={dir}
    >
      <Avatar>
        <AvatarImage
          src="https://github.com/shadcn.png"
          alt="@shadcn"
          className="grayscale"
        />
        <AvatarFallback>CN</AvatarFallback>
      </Avatar>
      <Avatar>
        <AvatarImage
          src="https://github.com/evilrabbit.png"
          alt="@evilrabbit"
        />
        <AvatarFallback>ER</AvatarFallback>
        <AvatarBadge className="bg-green-600 dark:bg-green-800" />
      </Avatar>
      <AvatarGroup className="grayscale">
        <Avatar>
          <AvatarImage src="https://github.com/shadcn.png" alt="@shadcn" />
          <AvatarFallback>CN</AvatarFallback>
        </Avatar>
        <Avatar>
          <AvatarImage
            src="https://github.com/maxleiter.png"
            alt="@maxleiter"
          />
          <AvatarFallback>LR</AvatarFallback>
        </Avatar>
        <Avatar>
          <AvatarImage
            src="https://github.com/evilrabbit.png"
            alt="@evilrabbit"
          />
          <AvatarFallback>ER</AvatarFallback>
        </Avatar>
        <AvatarGroupCount>{t.moreUsers}</AvatarGroupCount>
      </AvatarGroup>
    </div>
  );
}

export default AvatarRtl;
```

## API Reference

### Avatar

The `Avatar` component is the root component that wraps the avatar image and fallback.

| Prop        | Type                        | Default     |
| ----------- | --------------------------- | ----------- |
| `size`      | `"default" \| "sm" \| "lg"` | `"default"` |
| `className` | `string`                    | -           |

### AvatarImage

The `AvatarImage` component displays the avatar image. It accepts all Base UI Avatar Image props.

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `src`       | `string` | -       |
| `alt`       | `string` | -       |
| `className` | `string` | -       |

### AvatarFallback

The `AvatarFallback` component displays a fallback when the image fails to load. It accepts all Base UI Avatar Fallback props.

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` | -       |

### AvatarBadge

The `AvatarBadge` component displays a badge indicator on the avatar, typically positioned at the bottom right.

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` | -       |

### AvatarGroup

The `AvatarGroup` component displays a group of avatars with overlapping styling.

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` | -       |

### AvatarGroupCount

The `AvatarGroupCount` component displays a count indicator in an avatar group, typically showing the number of additional avatars.

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` | -       |

For more information about Base UI Avatar props, see the [Base UI documentation](https://base-ui.com/react/components/avatar#api-reference).

- [Documentation](https://base-ui.com/react/components/avatar)
- [API reference](https://base-ui.com/react/components/avatar#api-reference)


---

# Badge

Displays a badge or a component that looks like a badge.

Page: https://sui.draco.dev/docs/components/badge

### Example: badge-demo

```tsx
import { Badge } from "@workspace/ui/components/badge";

export default function BadgeDemo() {
  return (
    <div className="flex w-full flex-wrap justify-center gap-2">
      <Badge>Badge</Badge>
      <Badge variant="secondary">Secondary</Badge>
      <Badge variant="destructive">Destructive</Badge>
      <Badge variant="outline">Outline</Badge>
    </div>
  );
}
```

## Installation

```bash
bunx --bun shadcn@latest add @sui/badge
```

Install with the shadcn CLI or use the shared `@workspace/ui` package. Follow the [installation guide](/docs/installation) to configure the registry, load styles, and choose import aliases.

## Usage

```tsx
import { Badge } from "@workspace/ui/components/badge"
```

```tsx
<Badge variant="default | outline | secondary | destructive">Badge</Badge>
```

## Variants

Use the `variant` prop to change the variant of the badge.

### Example: badge-variants

```tsx
import { Badge } from "@workspace/ui/components/badge";

export function BadgeVariants() {
  return (
    <div className="flex flex-wrap gap-2">
      <Badge>Default</Badge>
      <Badge variant="secondary">Secondary</Badge>
      <Badge variant="destructive">Destructive</Badge>
      <Badge variant="outline">Outline</Badge>
      <Badge variant="ghost">Ghost</Badge>
    </div>
  );
}

export default BadgeVariants;
```

## With Icon

You can render an icon inside the badge. Use `data-icon="inline-start"` to render the icon on the left and `data-icon="inline-end"` to render the icon on the right.

### Example: badge-icon

```tsx
import { Badge } from "@workspace/ui/components/badge";
import { BadgeCheck, BookmarkIcon } from "lucide-react";

export function BadgeWithIconLeft() {
  return (
    <div className="flex flex-wrap gap-2">
      <Badge variant="secondary">
        <BadgeCheck data-icon="inline-start" />
        Verified
      </Badge>
      <Badge variant="outline">
        Bookmark
        <BookmarkIcon data-icon="inline-end" />
      </Badge>
    </div>
  );
}

export default BadgeWithIconLeft;
```

## With Loader

You can render a spinner inside the badge. Remember to add the `data-icon="inline-start"` or `data-icon="inline-end"` prop to the spinner.

### Example: badge-loading

```tsx
import { Badge } from "@workspace/ui/components/badge";
import { Loader } from "@workspace/ui/components/loader";

export function BadgeWithLoader() {
  return (
    <div className="flex flex-wrap gap-2">
      <Badge variant="destructive">
        <Loader size="sm" data-icon="inline-start" />
        Deleting
      </Badge>
      <Badge variant="secondary">
        Generating
        <Loader size="sm" data-icon="inline-end" />
      </Badge>
    </div>
  );
}

export default BadgeWithLoader;
```

## Link

Use the `render` prop to render a link as a badge.

### Example: badge-link

```tsx
import { Badge } from "@workspace/ui/components/badge";
import { ArrowUpRightIcon } from "lucide-react";

export function BadgeAsLink() {
  return (
    <Badge render={<a href="#link" />}>
      Open Link <ArrowUpRightIcon data-icon="inline-end" />
    </Badge>
  );
}

export default BadgeAsLink;
```

## Custom Colors

You can customize the colors of a badge by adding custom classes such as `bg-green-50 dark:bg-green-800` to the `Badge` component.

### Example: badge-colors

```tsx
import { Badge } from "@workspace/ui/components/badge";

export function BadgeCustomColors() {
  return (
    <div className="flex flex-wrap gap-2">
      <Badge className="bg-blue-50 text-blue-700 dark:bg-blue-950 dark:text-blue-300">
        Blue
      </Badge>
      <Badge className="bg-green-50 text-green-700 dark:bg-green-950 dark:text-green-300">
        Green
      </Badge>
      <Badge className="bg-sky-50 text-sky-700 dark:bg-sky-950 dark:text-sky-300">
        Sky
      </Badge>
      <Badge className="bg-purple-50 text-purple-700 dark:bg-purple-950 dark:text-purple-300">
        Purple
      </Badge>
      <Badge className="bg-red-50 text-red-700 dark:bg-red-950 dark:text-red-300">
        Red
      </Badge>
    </div>
  );
}

export default BadgeCustomColors;
```

## RTL

To enable RTL support in shadcn/ui, see the [RTL configuration guide](https://ui.shadcn.com/docs/rtl).

### Example: badge-rtl

```tsx
"use client";

import { Badge } from "@workspace/ui/components/badge";
import { BadgeCheck, BookmarkIcon } from "lucide-react";
import { type Translations, useTranslation } from "./support";

const translations: Translations = {
  en: {
    dir: "ltr",
    values: {
      badge: "Badge",
      secondary: "Secondary",
      destructive: "Destructive",
      outline: "Outline",
      verified: "Verified",
      bookmark: "Bookmark",
    },
  },
  ar: {
    dir: "rtl",
    values: {
      badge: "شارة",
      secondary: "ثانوي",
      destructive: "مدمر",
      outline: "مخطط",
      verified: "متحقق",
      bookmark: "إشارة مرجعية",
    },
  },
  he: {
    dir: "rtl",
    values: {
      badge: "תג",
      secondary: "משני",
      destructive: "הרסני",
      outline: "קווי מתאר",
      verified: "מאומת",
      bookmark: "סימנייה",
    },
  },
};

export function BadgeRtl() {
  const { dir, t } = useTranslation(translations, "ar");

  return (
    <div className="flex w-full flex-wrap justify-center gap-2" dir={dir}>
      <Badge>{t.badge}</Badge>
      <Badge variant="secondary">{t.secondary}</Badge>
      <Badge variant="destructive">{t.destructive}</Badge>
      <Badge variant="outline">{t.outline}</Badge>
      <Badge variant="secondary">
        <BadgeCheck data-icon="inline-start" />
        {t.verified}
      </Badge>
      <Badge variant="outline">
        {t.bookmark}
        <BookmarkIcon data-icon="inline-end" />
      </Badge>
    </div>
  );
}

export default BadgeRtl;
```

## API Reference

### Badge

The `Badge` component displays a badge or a component that looks like a badge.

| Prop        | Type                                                                          | Default     |
| ----------- | ----------------------------------------------------------------------------- | ----------- |
| `variant`   | `"default" \| "secondary" \| "destructive" \| "outline" \| "ghost" \| "link"` | `"default"` |
| `className` | `string`                                                                      | -           |


---

# Breadcrumb

Displays the path to the current resource using a hierarchy of links.

Page: https://sui.draco.dev/docs/components/breadcrumb

### Example: breadcrumb-demo

```tsx
import {
  Breadcrumb,
  BreadcrumbEllipsis,
  BreadcrumbItem,
  BreadcrumbLink,
  BreadcrumbList,
  BreadcrumbPage,
  BreadcrumbSeparator,
} from "@workspace/ui/components/breadcrumb";
import { Button } from "@workspace/ui/components/button";
import {
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuGroup,
  DropdownMenuItem,
  DropdownMenuTrigger,
} from "@workspace/ui/components/dropdown-menu";

export function BreadcrumbDemo() {
  return (
    <Breadcrumb>
      <BreadcrumbList>
        <BreadcrumbItem>
          <BreadcrumbLink render={<a href="/docs" />}>Home</BreadcrumbLink>
        </BreadcrumbItem>
        <BreadcrumbSeparator />
        <BreadcrumbItem>
          <DropdownMenu>
            <DropdownMenuTrigger
              render={<Button size="icon-sm" variant="ghost" />}
            >
              <BreadcrumbEllipsis />
              <span className="sr-only">Toggle menu</span>
            </DropdownMenuTrigger>
            <DropdownMenuContent align="start">
              <DropdownMenuGroup>
                <DropdownMenuItem>Documentation</DropdownMenuItem>
                <DropdownMenuItem>Themes</DropdownMenuItem>
                <DropdownMenuItem>GitHub</DropdownMenuItem>
              </DropdownMenuGroup>
            </DropdownMenuContent>
          </DropdownMenu>
        </BreadcrumbItem>
        <BreadcrumbSeparator />
        <BreadcrumbItem>
          <BreadcrumbLink render={<a href="/docs" />}>
            Components
          </BreadcrumbLink>
        </BreadcrumbItem>
        <BreadcrumbSeparator />
        <BreadcrumbItem>
          <BreadcrumbPage>Breadcrumb</BreadcrumbPage>
        </BreadcrumbItem>
      </BreadcrumbList>
    </Breadcrumb>
  );
}

export default BreadcrumbDemo;
```

## Installation

```bash
bunx --bun shadcn@latest add @sui/breadcrumb
```

Install with the shadcn CLI or use the shared `@workspace/ui` package. Follow the [installation guide](/docs/installation) to configure the registry, load styles, and choose import aliases.

## Usage

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

```tsx showLineNumbers
<Breadcrumb>
  <BreadcrumbList>
    <BreadcrumbItem>
      <BreadcrumbLink render={<a href="/" />}>Home</BreadcrumbLink>
    </BreadcrumbItem>
    <BreadcrumbSeparator />
    <BreadcrumbItem>
      <BreadcrumbLink render={<a href="/components" />}>
        Components
      </BreadcrumbLink>
    </BreadcrumbItem>
    <BreadcrumbSeparator />
    <BreadcrumbItem>
      <BreadcrumbPage>Breadcrumb</BreadcrumbPage>
    </BreadcrumbItem>
  </BreadcrumbList>
</Breadcrumb>
```

## Composition

Use the following composition to build a `Breadcrumb`:

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

## Basic

A basic breadcrumb with a home link and a components link.

### Example: breadcrumb-basic

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

export function BreadcrumbBasic() {
  return (
    <Breadcrumb>
      <BreadcrumbList>
        <BreadcrumbItem>
          <BreadcrumbLink href="/docs">Home</BreadcrumbLink>
        </BreadcrumbItem>
        <BreadcrumbSeparator />
        <BreadcrumbItem>
          <BreadcrumbLink href="/docs">Components</BreadcrumbLink>
        </BreadcrumbItem>
        <BreadcrumbSeparator />
        <BreadcrumbItem>
          <BreadcrumbPage>Breadcrumb</BreadcrumbPage>
        </BreadcrumbItem>
      </BreadcrumbList>
    </Breadcrumb>
  );
}

export default BreadcrumbBasic;
```

## Custom separator

Use a custom component as `children` for `<BreadcrumbSeparator />` to create a custom separator.

### Example: breadcrumb-separator

```tsx
import {
  Breadcrumb,
  BreadcrumbItem,
  BreadcrumbLink,
  BreadcrumbList,
  BreadcrumbPage,
  BreadcrumbSeparator,
} from "@workspace/ui/components/breadcrumb";
import { DotIcon } from "lucide-react";

export function BreadcrumbSeparatorDemo() {
  return (
    <Breadcrumb>
      <BreadcrumbList>
        <BreadcrumbItem>
          <BreadcrumbLink render={<a href="/" />}>Home</BreadcrumbLink>
        </BreadcrumbItem>
        <BreadcrumbSeparator>
          <DotIcon />
        </BreadcrumbSeparator>
        <BreadcrumbItem>
          <BreadcrumbLink render={<a href="/components" />}>
            Components
          </BreadcrumbLink>
        </BreadcrumbItem>
        <BreadcrumbSeparator>
          <DotIcon />
        </BreadcrumbSeparator>
        <BreadcrumbItem>
          <BreadcrumbPage>Breadcrumb</BreadcrumbPage>
        </BreadcrumbItem>
      </BreadcrumbList>
    </Breadcrumb>
  );
}

export default BreadcrumbSeparatorDemo;
```

## Dropdown

You can compose `<BreadcrumbItem />` with a `<DropdownMenu />` to create a dropdown in the breadcrumb.

### Example: breadcrumb-dropdown

```tsx
import {
  Breadcrumb,
  BreadcrumbItem,
  BreadcrumbLink,
  BreadcrumbList,
  BreadcrumbPage,
  BreadcrumbSeparator,
} from "@workspace/ui/components/breadcrumb";
import {
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuGroup,
  DropdownMenuItem,
  DropdownMenuTrigger,
} from "@workspace/ui/components/dropdown-menu";
import { ChevronDownIcon, DotIcon } from "lucide-react";

export function BreadcrumbDropdown() {
  return (
    <Breadcrumb>
      <BreadcrumbList>
        <BreadcrumbItem>
          <BreadcrumbLink render={<a href="/" />}>Home</BreadcrumbLink>
        </BreadcrumbItem>
        <BreadcrumbSeparator>
          <DotIcon />
        </BreadcrumbSeparator>
        <BreadcrumbItem>
          <DropdownMenu>
            <DropdownMenuTrigger
              render={
                <button type="button" className="flex items-center gap-1" />
              }
            >
              Components
              <ChevronDownIcon data-icon="inline-end" className="size-3.5" />
            </DropdownMenuTrigger>
            <DropdownMenuContent align="start">
              <DropdownMenuGroup>
                <DropdownMenuItem>Documentation</DropdownMenuItem>
                <DropdownMenuItem>Themes</DropdownMenuItem>
                <DropdownMenuItem>GitHub</DropdownMenuItem>
              </DropdownMenuGroup>
            </DropdownMenuContent>
          </DropdownMenu>
        </BreadcrumbItem>
        <BreadcrumbSeparator>
          <DotIcon />
        </BreadcrumbSeparator>
        <BreadcrumbItem>
          <BreadcrumbPage>Breadcrumb</BreadcrumbPage>
        </BreadcrumbItem>
      </BreadcrumbList>
    </Breadcrumb>
  );
}

export default BreadcrumbDropdown;
```

## Collapsed

We provide a `<BreadcrumbEllipsis />` component to show a collapsed state when the breadcrumb is too long.

### Example: breadcrumb-ellipsis

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

export function BreadcrumbEllipsisDemo() {
  return (
    <Breadcrumb>
      <BreadcrumbList>
        <BreadcrumbItem>
          <BreadcrumbLink render={<a href="/" />}>Home</BreadcrumbLink>
        </BreadcrumbItem>
        <BreadcrumbSeparator />
        <BreadcrumbItem>
          <BreadcrumbEllipsis />
        </BreadcrumbItem>
        <BreadcrumbSeparator />
        <BreadcrumbItem>
          <BreadcrumbLink render={<a href="/docs/components" />}>
            Components
          </BreadcrumbLink>
        </BreadcrumbItem>
        <BreadcrumbSeparator />
        <BreadcrumbItem>
          <BreadcrumbPage>Breadcrumb</BreadcrumbPage>
        </BreadcrumbItem>
      </BreadcrumbList>
    </Breadcrumb>
  );
}

export default BreadcrumbEllipsisDemo;
```

## Link component

To use a custom link component from your routing library, you can use the `render` prop on `<BreadcrumbLink />`.

### Example: breadcrumb-link

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

export function BreadcrumbLinkDemo() {
  return (
    <Breadcrumb>
      <BreadcrumbList>
        <BreadcrumbItem>
          <BreadcrumbLink render={<a href="#link-component" />}>
            Home
          </BreadcrumbLink>
        </BreadcrumbItem>
        <BreadcrumbSeparator />
        <BreadcrumbItem>
          <BreadcrumbLink render={<a href="#link-component" />}>
            Components
          </BreadcrumbLink>
        </BreadcrumbItem>
        <BreadcrumbSeparator />
        <BreadcrumbItem>
          <BreadcrumbPage>Breadcrumb</BreadcrumbPage>
        </BreadcrumbItem>
      </BreadcrumbList>
    </Breadcrumb>
  );
}

export default BreadcrumbLinkDemo;
```

## RTL

To enable RTL support in shadcn/ui, see the [RTL configuration guide](https://ui.shadcn.com/docs/rtl).

### Example: breadcrumb-rtl

```tsx
"use client";

import {
  Breadcrumb,
  BreadcrumbItem,
  BreadcrumbLink,
  BreadcrumbList,
  BreadcrumbPage,
  BreadcrumbSeparator,
} from "@workspace/ui/components/breadcrumb";
import {
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuGroup,
  DropdownMenuItem,
  DropdownMenuTrigger,
} from "@workspace/ui/components/dropdown-menu";
import { ChevronDownIcon, DotIcon } from "lucide-react";
import { type Translations, useTranslation } from "./support";

const translations: Translations = {
  en: {
    dir: "ltr",
    values: {
      home: "Home",
      components: "Components",
      documentation: "Documentation",
      themes: "Themes",
      github: "GitHub",
      breadcrumb: "Breadcrumb",
    },
  },
  ar: {
    dir: "rtl",
    values: {
      home: "الرئيسية",
      components: "المكونات",
      documentation: "التوثيق",
      themes: "السمات",
      github: "جيت هاب",
      breadcrumb: "مسار التنقل",
    },
  },
  he: {
    dir: "rtl",
    values: {
      home: "בית",
      components: "רכיבים",
      documentation: "תיעוד",
      themes: "ערכות נושא",
      github: "גיטהאב",
      breadcrumb: "פירורי לחם",
    },
  },
};

export function BreadcrumbRtl() {
  const { dir, t, language } = useTranslation(translations, "ar");

  return (
    <Breadcrumb dir={dir}>
      <BreadcrumbList>
        <BreadcrumbItem>
          <BreadcrumbLink render={<a href="/" />}>{t.home}</BreadcrumbLink>
        </BreadcrumbItem>
        <BreadcrumbSeparator>
          <DotIcon />
        </BreadcrumbSeparator>
        <BreadcrumbItem>
          <DropdownMenu>
            <DropdownMenuTrigger
              render={
                <button type="button" className="flex items-center gap-1" />
              }
            >
              {t.components}
              <ChevronDownIcon data-icon="inline-end" className="size-3.5" />
            </DropdownMenuTrigger>
            <DropdownMenuContent
              align={dir === "rtl" ? "end" : "start"}
              data-lang={dir === "rtl" ? language : undefined}
              dir={dir}
            >
              <DropdownMenuGroup>
                <DropdownMenuItem>{t.documentation}</DropdownMenuItem>
                <DropdownMenuItem>{t.themes}</DropdownMenuItem>
                <DropdownMenuItem>{t.github}</DropdownMenuItem>
              </DropdownMenuGroup>
            </DropdownMenuContent>
          </DropdownMenu>
        </BreadcrumbItem>
        <BreadcrumbSeparator>
          <DotIcon />
        </BreadcrumbSeparator>
        <BreadcrumbItem>
          <BreadcrumbPage>{t.breadcrumb}</BreadcrumbPage>
        </BreadcrumbItem>
      </BreadcrumbList>
    </Breadcrumb>
  );
}

export default BreadcrumbRtl;
```

## API Reference

### Breadcrumb

The `Breadcrumb` component is the root navigation element that wraps all breadcrumb components.

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` | -       |

### BreadcrumbList

The `BreadcrumbList` component displays the ordered list of breadcrumb items.

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` | -       |

### BreadcrumbItem

The `BreadcrumbItem` component wraps individual breadcrumb items.

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` | -       |

### BreadcrumbLink

The `BreadcrumbLink` component displays a clickable link in the breadcrumb.

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` | -       |

### BreadcrumbPage

The `BreadcrumbPage` component displays the current page in the breadcrumb (non-clickable).

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` | -       |

### BreadcrumbSeparator

The `BreadcrumbSeparator` component displays a separator between breadcrumb items. You can pass custom children to override the default separator icon.

| Prop        | Type              | Default |
| ----------- | ----------------- | ------- |
| `children`  | `React.ReactNode` | -       |
| `className` | `string`          | -       |

### BreadcrumbEllipsis

The `BreadcrumbEllipsis` component displays an ellipsis indicator for collapsed breadcrumb items.

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` | -       |


---

# Bubble

Displays conversational content in a message bubble. Supports variants, alignment, grouping, reactions, and collapsible content.

Page: https://sui.draco.dev/docs/components/bubble

### Example: bubble-demo

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

export function BubbleDemo() {
  return (
    <div className="flex w-full max-w-sm flex-col gap-8 py-12">
      <Bubble align="end">
        <BubbleContent>Hey there! what&apos;s up?</BubbleContent>
      </Bubble>
      <BubbleGroup>
        <Bubble variant="muted">
          <BubbleContent>Hey! Want to see chat bubbles?</BubbleContent>
        </Bubble>
        <Bubble variant="muted">
          <BubbleContent>
            I can group messages, switch sides, and keep the whole thread easy
            to scan.
          </BubbleContent>
          <BubbleReactions role="img" aria-label="Reaction: thumbs up">
            <span>👍</span>
          </BubbleReactions>
        </Bubble>
      </BubbleGroup>
      <Bubble align="end">
        <BubbleContent>Sure. Hit me with your best demo.</BubbleContent>
      </Bubble>
      <Bubble variant="muted">
        <BubbleContent>
          Yes. You are reading a demo that is demoing itself. Very meta. Very
          on-brand.
        </BubbleContent>
        <BubbleReactions
          role="img"
          aria-label="Reactions: thumbs up, fire, eyes, and 2 more"
        >
          <span>👍</span>
          <span>🔥</span>
          <span>👀</span>
          <span>+2</span>
        </BubbleReactions>
      </Bubble>
    </div>
  );
}

export default BubbleDemo;
```

The `Bubble` component displays framed conversational content. Use it for chat text, short structured output, quoted replies, suggestions, and reactions.

For full-featured chat interfaces, use the [`Message`](/docs/components/message) component. `Bubble` is intentionally scoped to the bubble surface. Place avatars, names, timestamps, metadata, and message-level actions in [`Message`](/docs/components/message).

## Installation

```bash
bunx --bun shadcn@latest add @sui/bubble
```

Install with the shadcn CLI or use the shared `@workspace/ui` package. Follow the [installation guide](/docs/installation) to configure the registry, load styles, and choose import aliases.

## Usage

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

```tsx showLineNumbers
<Bubble>
  <BubbleContent>
    I checked the registry output and removed the stale route.
  </BubbleContent>
  <BubbleReactions>
    <span>👍</span>
  </BubbleReactions>
</Bubble>
```

## Composition

Use the following composition to build a bubble:

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

Use `BubbleGroup` to group consecutive bubbles from the same sender:

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

## Features

- Seven visual variants, from a strong primary bubble to unframed ghost content
- Start and end alignment for sender and receiver bubbles
- Reactions that anchor to the bubble edge with configurable side and alignment
- Bubbles size to their content, up to 80% of the container width
- Polymorphic content via `render` for link and button bubbles
- Customizable styling through the `className` prop on every part

## Variants

Use `variant` to change the visual treatment of the bubble.

### Example: bubble-variants

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

export function BubbleVariantsDemo() {
  return (
    <div className="flex w-full max-w-sm flex-col gap-12 py-12">
      <Bubble>
        <BubbleContent>This is the default primary bubble.</BubbleContent>
      </Bubble>
      <Bubble variant="secondary" align="end">
        <BubbleContent>This is the secondary variant.</BubbleContent>
      </Bubble>
      <Bubble variant="muted">
        <BubbleContent>
          This one is muted. It uses a lower emphasis color for the chat bubble.
        </BubbleContent>
        <BubbleReactions role="img" aria-label="Reaction: thumbs up">
          <span>👍</span>
        </BubbleReactions>
      </Bubble>
      <Bubble variant="tinted" align="end">
        <BubbleContent>
          This one is tinted. The tint is a softer color derived from the
          primary color.
        </BubbleContent>
      </Bubble>
      <Bubble variant="outline">
        <BubbleContent>We can also use an outlined variant.</BubbleContent>
      </Bubble>
      <Bubble variant="destructive" align="end">
        <BubbleContent>Or a destructive variant with a reaction.</BubbleContent>
        <BubbleReactions role="img" aria-label="Reaction: fire">
          <span>🔥</span>
        </BubbleReactions>
      </Bubble>
      <Bubble variant="ghost">
        <BubbleContent>
          <div>{`Ghost bubbles work for assistant text, **markdown**, and other content that should not be framed.

This is perfect for assistant messages that should not have a frame and can take the full width of the container. You can also render \`code\` in it.

Ghost bubbles are full width and can take the full width of the container.
`}</div>
        </BubbleContent>
      </Bubble>
    </div>
  );
}

export default BubbleVariantsDemo;
```

| Variant       | Description                                            |
| ------------- | ------------------------------------------------------ |
| `default`     | A strong primary bubble, usually for the current user. |
| `secondary`   | The standard neutral bubble for conversation content.  |
| `muted`       | A lower-emphasis bubble for quiet supporting content.  |
| `tinted`      | A subtle primary-tinted bubble.                        |
| `outline`     | A bordered bubble for secondary or rich content.       |
| `ghost`       | Unframed content for assistant text or rich content.   |
| `destructive` | A destructive bubble for error or failed actions.      |

A bubble sizes to its content, up to 80% of the container width. The `ghost` variant removes the max-width so assistant text and rich content can span the full row.

## Alignment

Use `align` on `Bubble` to align the bubble to the start or end of the conversation.

### Example: bubble-alignment

```tsx
import { Bubble, BubbleContent } from "@workspace/ui/components/bubble";

export function BubbleAlignmentDemo() {
  return (
    <div className="flex w-full max-w-sm flex-col gap-8 py-12">
      <Bubble variant="muted">
        <BubbleContent>
          This bubble is aligned to the start. This is the default alignment.
        </BubbleContent>
      </Bubble>
      <Bubble align="end">
        <BubbleContent>
          This bubble is aligned to the end. Use this for user messages.
        </BubbleContent>
      </Bubble>
    </div>
  );
}

export default BubbleAlignmentDemo;
```

| align   | Description                                        |
| ------- | -------------------------------------------------- |
| `start` | Align the bubble to the start of the conversation. |
| `end`   | Align the bubble to the end of the conversation.   |

**Note:** When building chat interfaces, you probably want to use alignment on the `Message` component itself, not the `Bubble` component. You can use the `align` prop on the `Message` component to automatically align the bubble to the start or end of the conversation.

## Bubble Group

Use `BubbleGroup` to group consecutive bubbles from the same sender. Note the `align` prop should be set on the `Bubble` component itself, not the `BubbleGroup` component.

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

### Example: bubble-group-demo

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

export function BubbleGroupDemo() {
  return (
    <div className="flex w-full max-w-sm flex-col gap-8 py-12">
      <Bubble variant="muted">
        <BubbleContent>Can you tell me what&apos;s the issue?</BubbleContent>
      </Bubble>
      <BubbleGroup>
        <Bubble align="end">
          <BubbleContent>You tell me!</BubbleContent>
        </Bubble>
        <Bubble align="end">
          <BubbleContent>It worked yesterday. You broke it!</BubbleContent>
        </Bubble>
        <Bubble align="end">
          <BubbleContent>Find the bug and fix it.</BubbleContent>
          <BubbleReactions aria-label="Reactions: eyes" align="start">
            <span>👀</span>
          </BubbleReactions>
        </Bubble>
      </BubbleGroup>
      <Bubble variant="muted">
        <BubbleContent>
          Want me to diff yesterday&apos;s you against today&apos;s you?
          It&apos;s a bit embarrassing.
        </BubbleContent>
      </Bubble>
    </div>
  );
}

export default BubbleGroupDemo;
```

## Links and Buttons

You can turn a bubble into a link or button by using the `render` prop on `BubbleContent`.

### Example: bubble-link-button

```tsx
"use client";

import {
  Bubble,
  BubbleContent,
  BubbleGroup,
} from "@workspace/ui/components/bubble";
import { toast } from "@workspace/ui/components/toast";

export function BubbleLinkButtonDemo() {
  return (
    <div className="flex w-full max-w-sm flex-col gap-8 py-12">
      <Bubble variant="muted">
        <BubbleContent>How can I help you today?</BubbleContent>
      </Bubble>
      <BubbleGroup>
        <Bubble variant="tinted" align="end">
          <BubbleContent
            render={
              <button
                type="button"
                onClick={() =>
                  toast.add({ title: "You clicked forgot password" })
                }
              />
            }
          >
            I forgot my password
          </BubbleContent>
        </Bubble>
        <Bubble variant="tinted" align="end">
          <BubbleContent
            render={
              <button
                type="button"
                onClick={() =>
                  toast.add({ title: "You clicked help with subscription" })
                }
              />
            }
          >
            I need help with my subscription
          </BubbleContent>
        </Bubble>
        <Bubble variant="tinted" align="end">
          <BubbleContent
            render={
              <button
                type="button"
                onClick={() =>
                  toast.add({
                    title: "You clicked something else. Talk to a human.",
                  })
                }
              />
            }
          >
            Something else. Talk to a human.
          </BubbleContent>
        </Bubble>
      </BubbleGroup>
    </div>
  );
}

export default BubbleLinkButtonDemo;
```

```tsx showLineNumbers
import { Bubble, BubbleContent } from "@workspace/ui/components/bubble"

export function BubbleLinkDemo() {
  return (
    <Bubble variant="muted">
      <BubbleContent render={<button />}>Click here</BubbleContent>
    </Bubble>
  )
}
```

## Reactions

Use `BubbleReactions` for bubble reactions. You can use it to display reactions or quick action buttons. Use `side` and `align` to position the row — `side="top"` anchors it to the upper edge. Reactions overlap the bubble edge, so leave vertical space between rows — the examples below use a larger `gap` for this reason.

### Example: bubble-reactions

```tsx
"use client";

import {
  Bubble,
  BubbleContent,
  BubbleReactions,
} from "@workspace/ui/components/bubble";
import { Button } from "@workspace/ui/components/button";
import { toast } from "@workspace/ui/components/toast";

export function BubbleReactionsDemo() {
  return (
    <div className="flex w-full max-w-sm flex-col gap-12 py-12">
      <Bubble variant="muted" align="end">
        <BubbleContent>
          I don&apos;t need tests, I know my code works.
        </BubbleContent>
        <BubbleReactions
          align="start"
          role="img"
          aria-label="Reactions: thumbs up, surprised"
        >
          <span>👍</span>
          <span>😮</span>
        </BubbleReactions>
      </Bubble>
      <Bubble variant="muted">
        <BubbleContent>
          Bold. Fine I&apos;ll add some tests. I&apos;ll let you know when
          they&apos;re done.
        </BubbleContent>
        <BubbleReactions
          role="img"
          aria-label="Reactions: eyes, rocket, and 2 more"
        >
          <span>👀</span>
          <span>🚀</span>
          <span>+2</span>
        </BubbleReactions>
      </Bubble>
      <Bubble variant="default" align="end">
        <BubbleContent>
          Tests passed on the first try. All 142 of them. Looking good!
        </BubbleContent>
        <BubbleReactions
          side="top"
          align="start"
          role="img"
          aria-label="Reactions: party popper, clapping hands"
        >
          <span>🎉</span>
          <span>👏</span>
        </BubbleReactions>
      </Bubble>
      <Bubble variant="destructive">
        <BubbleContent>Are you sure I can run this command?</BubbleContent>
        <BubbleReactions>
          <Button
            variant="ghost"
            size="xs"
            onClick={() =>
              toast.add({
                title: "You clicked yes, running command...",
                type: "success",
              })
            }
          >
            Yes, run it
          </Button>
        </BubbleReactions>
      </Bubble>
    </div>
  );
}

export default BubbleReactionsDemo;
```

## Show More / Collapsible

Long bubble content can be composed with [`Collapsible`](/docs/components/collapsible) to allow for a show more or show less interaction. Use the `CollapsibleTrigger` component to trigger the collapsible content.

### Example: bubble-collapsible

```tsx
"use client";

import { Bubble, BubbleContent } from "@workspace/ui/components/bubble";
import { Button } from "@workspace/ui/components/button";
import {
  Collapsible,
  CollapsibleTrigger,
} from "@workspace/ui/components/collapsible";
import { ChevronDownIcon } from "lucide-react";
import * as React from "react";

const text = `The accessibility review found two focus states that were visually too subtle in dark mode.

I checked the dialog, menu, and drawer paths because each one renders focusable controls inside a layered surface.

The dialog and drawer are fine. The menu needs the hover and focus tokens split so keyboard focus stays visible when the pointer is not involved.

I also recommend keeping the change in the style file instead of the primitive so the other themes can choose their own focus treatment later.`;

const previewLength = 180;

export function BubbleCollapsible() {
  const [open, setOpen] = React.useState(false);
  const isLong = text.length > previewLength;
  const preview = `${text.slice(0, previewLength)}...`;

  return (
    <div className="flex w-full max-w-sm flex-col gap-8 py-12">
      <Bubble variant="muted">
        <BubbleContent>How can I help you today?</BubbleContent>
      </Bubble>

      <Bubble variant="muted" align="end">
        <BubbleContent className="whitespace-pre-line">
          <Collapsible open={open} onOpenChange={setOpen}>
            <div>{open || !isLong ? text : preview}</div>
            {isLong ? (
              <CollapsibleTrigger
                render={
                  <Button
                    variant="link"
                    className="gap-1 p-0 text-muted-foreground"
                  />
                }
              >
                {open ? "Show less" : "Show more"}
                <ChevronDownIcon
                  data-icon="inline-end"
                  className="group-data-panel-open/button:rotate-180"
                />
              </CollapsibleTrigger>
            ) : null}
          </Collapsible>
        </BubbleContent>
      </Bubble>
    </div>
  );
}

export default BubbleCollapsible;
```

## Tooltip

Wrap a bubble in a [`Tooltip`](/docs/components/tooltip) to reveal metadata on hover, such as when a message was read.

### Example: bubble-tooltip

```tsx
import {
  Bubble,
  BubbleContent,
  BubbleReactions,
} from "@workspace/ui/components/bubble";
import { Button } from "@workspace/ui/components/button";
import {
  Tooltip,
  TooltipContent,
  TooltipTrigger,
} from "@workspace/ui/components/tooltip";
import { CheckIcon } from "lucide-react";

export function BubbleTooltipDemo() {
  return (
    <div className="flex w-full max-w-sm flex-col gap-4 py-12">
      <Bubble variant="secondary">
        <BubbleContent>Did you remove the stale route?</BubbleContent>
      </Bubble>
      <Bubble align="end">
        <BubbleContent>Yes, removed it from the registry.</BubbleContent>
        <BubbleReactions>
          <Tooltip>
            <TooltipTrigger render={<Button variant="ghost" size="icon-xs" />}>
              <CheckIcon />
            </TooltipTrigger>
            <TooltipContent>Read on Jan 5, 2026 at 4:32 PM</TooltipContent>
          </Tooltip>
        </BubbleReactions>
      </Bubble>
    </div>
  );
}

export default BubbleTooltipDemo;
```

## Popover

Pair a bubble with a [`Popover`](/docs/components/popover) to surface more information on demand, such as the full error message for a failed action.

### Example: bubble-popover

```tsx
import {
  Bubble,
  BubbleContent,
  BubbleReactions,
} from "@workspace/ui/components/bubble";
import { Button } from "@workspace/ui/components/button";
import {
  Popover,
  PopoverContent,
  PopoverDescription,
  PopoverHeader,
  PopoverTitle,
  PopoverTrigger,
} from "@workspace/ui/components/popover";
import { InfoIcon } from "lucide-react";

export function BubblePopoverDemo() {
  return (
    <div className="flex w-full max-w-sm flex-col gap-4 py-12">
      <Bubble align="end">
        <BubbleContent>Run the build script.</BubbleContent>
      </Bubble>
      <Bubble variant="destructive">
        <BubbleContent>Failed to run the command.</BubbleContent>
        <BubbleReactions>
          <Popover>
            <PopoverTrigger
              render={
                <Button
                  variant="ghost"
                  size="icon-xs"
                  aria-label="Show error details"
                  className="aria-expanded:text-destructive"
                />
              }
            >
              <InfoIcon />
            </PopoverTrigger>
            <PopoverContent>
              <PopoverHeader>
                <PopoverTitle className="text-sm">
                  Command failed with exit code 1
                </PopoverTitle>
                <PopoverDescription className="text-sm">
                  ENOENT: no such file or directory, open pnpm-lock.yaml
                </PopoverDescription>
              </PopoverHeader>
            </PopoverContent>
          </Popover>
        </BubbleReactions>
      </Bubble>
    </div>
  );
}

export default BubblePopoverDemo;
```

## Accessibility

`Bubble` renders the presentational message surface. Keep conversation-level semantics on the surrounding container and follow the guidelines below.

### Labeling Reactions

Reactions render as a row of emoji. A screen reader reads each glyph with no context, and counters like `+8` are announced as "plus eight". Group the row as a single image with a descriptive `aria-label` so it announces once. `role="img"` also hides the individual emoji from assistive tech, so no `aria-hidden` is needed.

```tsx showLineNumbers
<BubbleReactions role="img" aria-label="Reactions: thumbs up, fire, and 8 more">
  <span>👍</span>
  <span>🔥</span>
  <span>+8</span>
</BubbleReactions>
```

When reactions are interactive, render buttons instead and give icon-only buttons an `aria-label`.

```tsx showLineNumbers
<BubbleReactions>
  <Button aria-label="Thumbs up" variant="secondary" size="icon-xs">
    <ThumbsUpIcon />
  </Button>
</BubbleReactions>
```

### Interactive Bubbles

When a bubble is clickable, render it as a real `<button>` or `<a>` with the `render` prop so it is focusable and exposes the correct role. `BubbleContent` ships a visible focus ring for interactive elements, and the accessible name comes from the bubble text. No extra label is needed.

```tsx showLineNumbers
<Bubble variant="muted" align="end">
  <BubbleContent render={<button type="button" onClick={onReply} />}>
    I forgot my password
  </BubbleContent>
</Bubble>
```

### Meaning Beyond Color

Bubble variants signal role and tone with color. Pair them with text, alignment, or icons so meaning is not conveyed by color alone. For a `destructive` bubble, keep the error context in the message text rather than relying on the color treatment.

## API Reference

### Bubble

The root bubble wrapper.

| Prop        | Type                                                                                       | Default     | Description                                      |
| ----------- | ------------------------------------------------------------------------------------------ | ----------- | ------------------------------------------------ |
| `variant`   | `"default" \| "secondary" \| "muted" \| "tinted" \| "outline" \| "ghost" \| "destructive"` | `"default"` | The bubble visual treatment.                     |
| `align`     | `"start" \| "end"`                                                                         | `"start"`   | The inline alignment of the bubble.              |
| `className` | `string`                                                                                   | -           | Additional classes to apply to the root element. |

### BubbleContent

The bubble content wrapper.

| Prop        | Type                       | Default | Description                                               |
| ----------- | -------------------------- | ------- | --------------------------------------------------------- |
| `render`    | `ReactElement \| function` | -       | Render the content as a different element such as a link. |
| `className` | `string`                   | -       | Additional classes to apply to the content element.       |

### BubbleReactions

Displays overlapped reactions for a bubble.

| Prop        | Type                | Default    | Description                                      |
| ----------- | ------------------- | ---------- | ------------------------------------------------ |
| `side`      | `"top" \| "bottom"` | `"bottom"` | The side of the bubble to anchor the reactions.  |
| `align`     | `"start" \| "end"`  | `"end"`    | The inline alignment of the reactions.           |
| `className` | `string`            | -          | Additional classes to apply to the reaction row. |

### BubbleGroup

Groups consecutive bubbles from the same sender.

| Prop        | Type     | Default | Description                                    |
| ----------- | -------- | ------- | ---------------------------------------------- |
| `className` | `string` | -       | Additional classes to apply to the group root. |


---

# Button

Displays a button or a component that looks like a button.

Page: https://sui.draco.dev/docs/components/button

### Example: button-demo

```tsx
import { Button } from "@workspace/ui/components/button";
import { ArrowUpIcon } from "lucide-react";

export default function ButtonDemo() {
  return (
    <div className="flex flex-wrap items-center gap-2">
      <Button variant="outline">Button</Button>
      <Button variant="outline" size="icon" aria-label="Submit">
        <ArrowUpIcon />
      </Button>
    </div>
  );
}
```

## Installation

```bash
bunx --bun shadcn@latest add @sui/button
```

Install with the shadcn CLI or use the shared `@workspace/ui` package. Follow the [installation guide](/docs/installation) to configure the registry, load styles, and choose import aliases.

## Usage

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

```tsx
<Button variant="outline">Button</Button>
```

## Cursor

Tailwind v4 [switched](https://tailwindcss.com/docs/upgrade-guide#buttons-use-the-default-cursor) from `cursor: pointer` to `cursor: default` for the button component.

If you want to keep the `cursor: pointer` behavior, add the following code to your CSS file:

You can also enable this during project setup with `npx shadcn@latest init --pointer`.

```css showLineNumbers title="globals.css"
@layer base {
  button:not(:disabled),
  [role="button"]:not(:disabled) {
    cursor: pointer;
  }
}
```

## Size

Use the `size` prop to change the size of the button.

### Example: button-size

```tsx
import { Button } from "@workspace/ui/components/button";
import { ArrowUpRightIcon } from "lucide-react";

export default function ButtonSize() {
  return (
    <div className="flex flex-col items-start gap-8 sm:flex-row">
      <div className="flex items-start gap-2">
        <Button size="xs" variant="outline">
          Extra Small
        </Button>
        <Button size="icon-xs" aria-label="Submit" variant="outline">
          <ArrowUpRightIcon />
        </Button>
      </div>
      <div className="flex items-start gap-2">
        <Button size="sm" variant="outline">
          Small
        </Button>
        <Button size="icon-sm" aria-label="Submit" variant="outline">
          <ArrowUpRightIcon />
        </Button>
      </div>
      <div className="flex items-start gap-2">
        <Button variant="outline">Default</Button>
        <Button size="icon" aria-label="Submit" variant="outline">
          <ArrowUpRightIcon />
        </Button>
      </div>
      <div className="flex items-start gap-2">
        <Button variant="outline" size="lg">
          Large
        </Button>
        <Button size="icon-lg" aria-label="Submit" variant="outline">
          <ArrowUpRightIcon />
        </Button>
      </div>
    </div>
  );
}
```

## Default

### Example: button-default

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

export default function ButtonDefault() {
  return <Button>Button</Button>;
}
```

## Outline

### Example: button-outline

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

export default function ButtonOutline() {
  return <Button variant="outline">Outline</Button>;
}
```

## Secondary

### Example: button-secondary

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

export default function ButtonSecondary() {
  return <Button variant="secondary">Secondary</Button>;
}
```

## Ghost

### Example: button-ghost

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

export default function ButtonGhost() {
  return <Button variant="ghost">Ghost</Button>;
}
```

## Destructive

### Example: button-destructive

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

export default function ButtonDestructive() {
  return <Button variant="destructive">Destructive</Button>;
}
```

## Link

### Example: button-link

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

export default function ButtonLink() {
  return <Button variant="link">Link</Button>;
}
```

## Icon

### Example: button-icon

```tsx
import { Button } from "@workspace/ui/components/button";
import { CircleFadingArrowUpIcon } from "lucide-react";

export default function ButtonIcon() {
  return (
    <Button variant="outline" size="icon">
      <CircleFadingArrowUpIcon />
    </Button>
  );
}
```

## With Icon

Remember to add the `data-icon="inline-start"` or `data-icon="inline-end"` attribute to the icon for the correct spacing.

### Example: button-with-icon

```tsx
import { Button } from "@workspace/ui/components/button";
import { GitBranchIcon, GitForkIcon } from "lucide-react";

export default function ButtonWithIcon() {
  return (
    <div className="flex gap-2">
      <Button variant="outline">
        <GitBranchIcon data-icon="inline-start" /> New Branch
      </Button>
      <Button variant="outline">
        Fork
        <GitForkIcon data-icon="inline-end" />
      </Button>
    </div>
  );
}
```

## Rounded

Use the `rounded-full` class to make the button rounded.

### Example: button-rounded

```tsx
import { Button } from "@workspace/ui/components/button";
import { ArrowUpIcon } from "lucide-react";

export default function ButtonRounded() {
  return (
    <div className="flex gap-2">
      <Button className="rounded-full">Get Started</Button>
      <Button variant="outline" className="rounded-lg">
        Soft corners
      </Button>
      <Button
        variant="outline"
        size="icon"
        className="rounded-full"
        aria-label="Submit"
      >
        <ArrowUpIcon />
      </Button>
    </div>
  );
}
```

## Loader

Render a `<Loader size="sm" />` component inside the button to show a loading state. Remember to add the `data-icon="inline-start"` or `data-icon="inline-end"` attribute to the spinner for the correct spacing.

### Example: button-loading

```tsx
"use client";

import { Button } from "@workspace/ui/components/button";
import { Loader } from "@workspace/ui/components/loader";
import { useEffect, useRef, useState } from "react";
import type { ExampleProps } from "../types";

export default function ButtonLoading({ locale }: ExampleProps) {
  const zh = locale === "zh-CN";
  const stateLabels = zh
    ? {
        generating: "正在生成",
        generate: "生成",
        downloading: "正在下载",
        download: "下载",
        done: "演示完成，可以再次点击",
        idle: "点击按钮模拟加载状态",
      }
    : {
        generating: "Generating",
        generate: "Generate",
        downloading: "Downloading",
        download: "Download",
        done: "Demo complete. Try it again.",
        idle: "Click a button to simulate loading.",
      };
  const [status, setStatus] = useState<"idle" | "pending" | "done">("idle");
  const timer = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
  const pending = status === "pending";

  useEffect(() => () => clearTimeout(timer.current), []);

  function startDemo() {
    clearTimeout(timer.current);
    setStatus("pending");
    // Replace this delay with your application's async operation.
    timer.current = setTimeout(() => setStatus("done"), 1200);
  }

  return (
    <div className="flex flex-col gap-3">
      <div className="flex flex-wrap gap-2">
        <Button variant="outline" disabled={pending} onClick={startDemo}>
          {pending && <Loader size="sm" data-icon="inline-start" />}
          {pending ? stateLabels.generating : stateLabels.generate}
        </Button>
        <Button variant="secondary" disabled={pending} onClick={startDemo}>
          {pending ? stateLabels.downloading : stateLabels.download}
          {pending && <Loader size="sm" data-icon="inline-end" />}
        </Button>
      </div>
      <p role="status" className="text-muted-foreground text-sm">
        {status === "done" ? stateLabels.done : stateLabels.idle}
      </p>
    </div>
  );
}
```

## Button Group

To create a button group, use the `ButtonGroup` component. See the [Button Group](/docs/components/button-group) documentation for more details.

### Example: button-group-demo

```tsx
"use client";

import { Button } from "@workspace/ui/components/button";
import { ButtonGroup } from "@workspace/ui/components/button-group";
import {
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuGroup,
  DropdownMenuItem,
  DropdownMenuRadioGroup,
  DropdownMenuRadioItem,
  DropdownMenuSeparator,
  DropdownMenuSub,
  DropdownMenuSubContent,
  DropdownMenuSubTrigger,
  DropdownMenuTrigger,
} from "@workspace/ui/components/dropdown-menu";
import {
  ArchiveIcon,
  ArrowLeftIcon,
  CalendarPlusIcon,
  ClockIcon,
  ListFilterIcon,
  MailCheckIcon,
  MoreHorizontalIcon,
  TagIcon,
  Trash2Icon,
} from "lucide-react";
import * as React from "react";

export default function ButtonGroupDemo() {
  const [label, setLabel] = React.useState("personal");

  return (
    <ButtonGroup>
      <ButtonGroup className="hidden sm:flex">
        <Button variant="outline" size="icon" aria-label="Go Back">
          <ArrowLeftIcon />
        </Button>
      </ButtonGroup>
      <ButtonGroup>
        <Button variant="outline">Archive</Button>
        <Button variant="outline">Report</Button>
      </ButtonGroup>
      <ButtonGroup>
        <Button variant="outline">Snooze</Button>
        <DropdownMenu>
          <DropdownMenuTrigger
            render={
              <Button variant="outline" size="icon" aria-label="More Options" />
            }
          >
            <MoreHorizontalIcon />
          </DropdownMenuTrigger>
          <DropdownMenuContent align="end" className="w-40">
            <DropdownMenuGroup>
              <DropdownMenuItem>
                <MailCheckIcon />
                Mark as Read
              </DropdownMenuItem>
              <DropdownMenuItem>
                <ArchiveIcon />
                Archive
              </DropdownMenuItem>
            </DropdownMenuGroup>
            <DropdownMenuSeparator />
            <DropdownMenuGroup>
              <DropdownMenuItem>
                <ClockIcon />
                Snooze
              </DropdownMenuItem>
              <DropdownMenuItem>
                <CalendarPlusIcon />
                Add to Calendar
              </DropdownMenuItem>
              <DropdownMenuItem>
                <ListFilterIcon />
                Add to List
              </DropdownMenuItem>
              <DropdownMenuSub>
                <DropdownMenuSubTrigger>
                  <TagIcon />
                  Label As...
                </DropdownMenuSubTrigger>
                <DropdownMenuSubContent>
                  <DropdownMenuRadioGroup
                    value={label}
                    onValueChange={setLabel}
                  >
                    <DropdownMenuRadioItem value="personal">
                      Personal
                    </DropdownMenuRadioItem>
                    <DropdownMenuRadioItem value="work">
                      Work
                    </DropdownMenuRadioItem>
                    <DropdownMenuRadioItem value="other">
                      Other
                    </DropdownMenuRadioItem>
                  </DropdownMenuRadioGroup>
                </DropdownMenuSubContent>
              </DropdownMenuSub>
            </DropdownMenuGroup>
            <DropdownMenuSeparator />
            <DropdownMenuGroup>
              <DropdownMenuItem variant="destructive">
                <Trash2Icon />
                Trash
              </DropdownMenuItem>
            </DropdownMenuGroup>
          </DropdownMenuContent>
        </DropdownMenu>
      </ButtonGroup>
    </ButtonGroup>
  );
}
```

## As Link

You can use the `buttonVariants` helper to make a link look like a button.

**Do not use `<Button render={<a />} nativeButton={false} />` for links.** The Base UI `Button` component always applies `role="button"`, which overrides the semantic link role on `<a>` elements. Use `buttonVariants` with a plain `<a>` tag instead.

### Example: button-render

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

export default function ButtonRender() {
  return (
    <a
      href="/docs"
      className={buttonVariants({ variant: "secondary", size: "sm" })}
    >
      Login
    </a>
  );
}
```

## RTL

To enable RTL support in shadcn/ui, see the [RTL configuration guide](https://ui.shadcn.com/docs/rtl).

### Example: button-rtl

```tsx
"use client";

import { Button } from "@workspace/ui/components/button";
import { Loader } from "@workspace/ui/components/loader";
import { ArrowRightIcon, PlusIcon } from "lucide-react";
import { type Translations, useTranslation } from "./support";

const translations: Translations = {
  en: {
    dir: "ltr",
    values: {
      button: "Button",
      submit: "Submit",
      delete: "Delete",
      loading: "Loading",
    },
  },
  ar: {
    dir: "rtl",
    values: {
      button: "زر",
      submit: "إرسال",
      delete: "حذف",
      loading: "جاري التحميل",
    },
  },
  he: {
    dir: "rtl",
    values: {
      button: "כפתור",
      submit: "שלח",
      delete: "מחק",
      loading: "טוען",
    },
  },
};

export function ButtonRtl() {
  const { dir, t } = useTranslation(translations, "ar");

  return (
    <div className="flex flex-wrap items-center gap-2" dir={dir}>
      <Button variant="outline">{t.button}</Button>
      <Button variant="destructive">{t.delete}</Button>
      <Button variant="outline">
        {t.submit}{" "}
        <ArrowRightIcon className="rtl:rotate-180" data-icon="inline-end" />
      </Button>
      <Button variant="outline" size="icon" aria-label="Add">
        <PlusIcon />
      </Button>
      <Button variant="secondary" disabled>
        <Loader size="sm" data-icon="inline-start" /> {t.loading}
      </Button>
    </div>
  );
}

export default ButtonRtl;
```

## API Reference

### Button

The `Button` component is a wrapper around the `button` element that adds a variety of styles and functionality.

| Prop      | Type                                                                                 | Default     |
| --------- | ------------------------------------------------------------------------------------ | ----------- |
| `variant` | `"default" \| "outline" \| "ghost" \| "destructive" \| "secondary" \| "link"`        | `"default"` |
| `size`    | `"default" \| "xs" \| "sm" \| "lg" \| "icon" \| "icon-xs" \| "icon-sm" \| "icon-lg"` | `"default"` |


---

# Button Group

A container that groups related buttons together with consistent styling.

Page: https://sui.draco.dev/docs/components/button-group

### Example: button-group-demo

```tsx
"use client";

import { Button } from "@workspace/ui/components/button";
import { ButtonGroup } from "@workspace/ui/components/button-group";
import {
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuGroup,
  DropdownMenuItem,
  DropdownMenuRadioGroup,
  DropdownMenuRadioItem,
  DropdownMenuSeparator,
  DropdownMenuSub,
  DropdownMenuSubContent,
  DropdownMenuSubTrigger,
  DropdownMenuTrigger,
} from "@workspace/ui/components/dropdown-menu";
import {
  ArchiveIcon,
  ArrowLeftIcon,
  CalendarPlusIcon,
  ClockIcon,
  ListFilterIcon,
  MailCheckIcon,
  MoreHorizontalIcon,
  TagIcon,
  Trash2Icon,
} from "lucide-react";
import * as React from "react";

export default function ButtonGroupDemo() {
  const [label, setLabel] = React.useState("personal");

  return (
    <ButtonGroup>
      <ButtonGroup className="hidden sm:flex">
        <Button variant="outline" size="icon" aria-label="Go Back">
          <ArrowLeftIcon />
        </Button>
      </ButtonGroup>
      <ButtonGroup>
        <Button variant="outline">Archive</Button>
        <Button variant="outline">Report</Button>
      </ButtonGroup>
      <ButtonGroup>
        <Button variant="outline">Snooze</Button>
        <DropdownMenu>
          <DropdownMenuTrigger
            render={
              <Button variant="outline" size="icon" aria-label="More Options" />
            }
          >
            <MoreHorizontalIcon />
          </DropdownMenuTrigger>
          <DropdownMenuContent align="end" className="w-40">
            <DropdownMenuGroup>
              <DropdownMenuItem>
                <MailCheckIcon />
                Mark as Read
              </DropdownMenuItem>
              <DropdownMenuItem>
                <ArchiveIcon />
                Archive
              </DropdownMenuItem>
            </DropdownMenuGroup>
            <DropdownMenuSeparator />
            <DropdownMenuGroup>
              <DropdownMenuItem>
                <ClockIcon />
                Snooze
              </DropdownMenuItem>
              <DropdownMenuItem>
                <CalendarPlusIcon />
                Add to Calendar
              </DropdownMenuItem>
              <DropdownMenuItem>
                <ListFilterIcon />
                Add to List
              </DropdownMenuItem>
              <DropdownMenuSub>
                <DropdownMenuSubTrigger>
                  <TagIcon />
                  Label As...
                </DropdownMenuSubTrigger>
                <DropdownMenuSubContent>
                  <DropdownMenuRadioGroup
                    value={label}
                    onValueChange={setLabel}
                  >
                    <DropdownMenuRadioItem value="personal">
                      Personal
                    </DropdownMenuRadioItem>
                    <DropdownMenuRadioItem value="work">
                      Work
                    </DropdownMenuRadioItem>
                    <DropdownMenuRadioItem value="other">
                      Other
                    </DropdownMenuRadioItem>
                  </DropdownMenuRadioGroup>
                </DropdownMenuSubContent>
              </DropdownMenuSub>
            </DropdownMenuGroup>
            <DropdownMenuSeparator />
            <DropdownMenuGroup>
              <DropdownMenuItem variant="destructive">
                <Trash2Icon />
                Trash
              </DropdownMenuItem>
            </DropdownMenuGroup>
          </DropdownMenuContent>
        </DropdownMenu>
      </ButtonGroup>
    </ButtonGroup>
  );
}
```

## Installation

```bash
bunx --bun shadcn@latest add @sui/button-group
```

Install with the shadcn CLI or use the shared `@workspace/ui` package. Follow the [installation guide](/docs/installation) to configure the registry, load styles, and choose import aliases.

## Usage

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

```tsx
<ButtonGroup>
  <Button>Button 1</Button>
  <Button>Button 2</Button>
</ButtonGroup>
```

## Composition

Use the following composition to build a `ButtonGroup`:

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

## Accessibility

- The `ButtonGroup` component has the `role` attribute set to `group`.
- Use Tab

 to navigate between the buttons in the group.
- Use `aria-label` or `aria-labelledby` to label the button group.

```tsx showLineNumbers
<ButtonGroup aria-label="Button group">
  <Button>Button 1</Button>
  <Button>Button 2</Button>
</ButtonGroup>
```

## ButtonGroup vs ToggleGroup

- Use the `ButtonGroup` component when you want to group buttons that perform an action.
- Use the `ToggleGroup` component when you want to group buttons that toggle a state.

## Orientation

Set the `orientation` prop to change the button group layout.

### Example: button-group-orientation

```tsx
import { Button } from "@workspace/ui/components/button";
import { ButtonGroup } from "@workspace/ui/components/button-group";
import { MinusIcon, PlusIcon } from "lucide-react";

export default function ButtonGroupOrientation() {
  return (
    <ButtonGroup
      orientation="vertical"
      aria-label="Media controls"
      className="h-fit"
    >
      <Button variant="outline" size="icon">
        <PlusIcon />
      </Button>
      <Button variant="outline" size="icon">
        <MinusIcon />
      </Button>
    </ButtonGroup>
  );
}
```

## Size

Control the size of buttons using the `size` prop on individual buttons.

### Example: button-group-size

```tsx
import { Button } from "@workspace/ui/components/button";
import { ButtonGroup } from "@workspace/ui/components/button-group";
import { PlusIcon } from "lucide-react";

export default function ButtonGroupSize() {
  return (
    <div className="flex flex-col items-start gap-8">
      <ButtonGroup>
        <Button variant="outline" size="sm">
          Small
        </Button>
        <Button variant="outline" size="sm">
          Button
        </Button>
        <Button variant="outline" size="sm">
          Group
        </Button>
        <Button variant="outline" size="icon-sm">
          <PlusIcon />
        </Button>
      </ButtonGroup>
      <ButtonGroup>
        <Button variant="outline">Default</Button>
        <Button variant="outline">Button</Button>
        <Button variant="outline">Group</Button>
        <Button variant="outline" size="icon">
          <PlusIcon />
        </Button>
      </ButtonGroup>
      <ButtonGroup>
        <Button variant="outline" size="lg">
          Large
        </Button>
        <Button variant="outline" size="lg">
          Button
        </Button>
        <Button variant="outline" size="lg">
          Group
        </Button>
        <Button variant="outline" size="icon-lg">
          <PlusIcon />
        </Button>
      </ButtonGroup>
    </div>
  );
}
```

## Nested

Nest `<ButtonGroup>` components to create button groups with spacing.

### Example: button-group-nested

```tsx
import { Button } from "@workspace/ui/components/button";
import { ButtonGroup } from "@workspace/ui/components/button-group";
import {
  InputGroup,
  InputGroupAddon,
  InputGroupInput,
} from "@workspace/ui/components/input-group";
import {
  Tooltip,
  TooltipContent,
  TooltipTrigger,
} from "@workspace/ui/components/tooltip";
import { AudioLinesIcon, PlusIcon } from "lucide-react";

export function ButtonGroupNested() {
  return (
    <ButtonGroup>
      <ButtonGroup>
        <Button variant="outline" size="icon">
          <PlusIcon />
        </Button>
      </ButtonGroup>
      <ButtonGroup>
        <InputGroup>
          <InputGroupInput placeholder="Send a message..." />
          <Tooltip>
            <TooltipTrigger render={<InputGroupAddon align="inline-end" />}>
              <AudioLinesIcon />
            </TooltipTrigger>
            <TooltipContent>Voice Mode</TooltipContent>
          </Tooltip>
        </InputGroup>
      </ButtonGroup>
    </ButtonGroup>
  );
}

export default ButtonGroupNested;
```

## Separator

The `ButtonGroupSeparator` component visually divides buttons within a group.

Buttons with variant `outline` do not need a separator since they have a border. For other variants, a separator is recommended to improve the visual hierarchy.

### Example: button-group-separator

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

export default function ButtonGroupSeparatorDemo() {
  return (
    <ButtonGroup>
      <Button variant="secondary" size="sm">
        Copy
      </Button>
      <ButtonGroupSeparator />
      <Button variant="secondary" size="sm">
        Paste
      </Button>
    </ButtonGroup>
  );
}
```

## Split

Create a split button group by adding two buttons separated by a `ButtonGroupSeparator`.

### Example: button-group-split

```tsx
import { Button } from "@workspace/ui/components/button";
import {
  ButtonGroup,
  ButtonGroupSeparator,
} from "@workspace/ui/components/button-group";
import { PlusIcon } from "lucide-react";

export default function ButtonGroupSplit() {
  return (
    <ButtonGroup>
      <Button variant="secondary">Button</Button>
      <ButtonGroupSeparator />
      <Button size="icon" variant="secondary">
        <PlusIcon />
      </Button>
    </ButtonGroup>
  );
}
```

## Input

Wrap an `Input` component with buttons.

### Example: button-group-input

```tsx
import { Button } from "@workspace/ui/components/button";
import { ButtonGroup } from "@workspace/ui/components/button-group";
import { Input } from "@workspace/ui/components/input";
import { SearchIcon } from "lucide-react";

export default function ButtonGroupInput() {
  return (
    <ButtonGroup>
      <Input placeholder="Search..." />
      <Button variant="outline" aria-label="Search">
        <SearchIcon />
      </Button>
    </ButtonGroup>
  );
}
```

## Input Group

Wrap an `InputGroup` component to create complex input layouts.

### Example: button-group-input-group

```tsx
"use client";

import { Button } from "@workspace/ui/components/button";
import { ButtonGroup } from "@workspace/ui/components/button-group";
import {
  InputGroup,
  InputGroupAddon,
  InputGroupButton,
  InputGroupInput,
} from "@workspace/ui/components/input-group";
import {
  Tooltip,
  TooltipContent,
  TooltipTrigger,
} from "@workspace/ui/components/tooltip";
import { AudioLinesIcon, PlusIcon } from "lucide-react";
import * as React from "react";

export default function ButtonGroupInputGroup() {
  const [voiceEnabled, setVoiceEnabled] = React.useState(false);

  return (
    <ButtonGroup className="[--radius:9999rem]">
      <ButtonGroup>
        <Button variant="outline" size="icon">
          <PlusIcon />
        </Button>
      </ButtonGroup>
      <ButtonGroup>
        <InputGroup>
          <InputGroupInput
            placeholder={
              voiceEnabled ? "Record and send audio..." : "Send a message..."
            }
            disabled={voiceEnabled}
          />
          <InputGroupAddon align="inline-end">
            <Tooltip>
              <TooltipTrigger
                render={
                  <InputGroupButton
                    onClick={() => setVoiceEnabled(!voiceEnabled)}
                    size="icon-xs"
                    data-active={voiceEnabled}
                    className="data-[active=true]:bg-orange-100 data-[active=true]:text-orange-700 dark:data-[active=true]:bg-orange-800 dark:data-[active=true]:text-orange-100"
                    aria-pressed={voiceEnabled}
                  />
                }
              >
                <AudioLinesIcon />
              </TooltipTrigger>
              <TooltipContent>Voice Mode</TooltipContent>
            </Tooltip>
          </InputGroupAddon>
        </InputGroup>
      </ButtonGroup>
    </ButtonGroup>
  );
}
```

## Dropdown Menu

Create a split button group with a `DropdownMenu` component.

### Example: button-group-dropdown

```tsx
"use client";

import { Button } from "@workspace/ui/components/button";
import { ButtonGroup } from "@workspace/ui/components/button-group";
import {
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuGroup,
  DropdownMenuItem,
  DropdownMenuSeparator,
  DropdownMenuTrigger,
} from "@workspace/ui/components/dropdown-menu";
import {
  AlertTriangleIcon,
  CheckIcon,
  ChevronDownIcon,
  CopyIcon,
  ShareIcon,
  TrashIcon,
  UserRoundXIcon,
  VolumeOffIcon,
} from "lucide-react";

export default function ButtonGroupDropdown() {
  return (
    <ButtonGroup>
      <Button variant="outline">Follow</Button>
      <DropdownMenu>
        <DropdownMenuTrigger
          render={<Button variant="outline" className="pl-2!" />}
        >
          <ChevronDownIcon />
        </DropdownMenuTrigger>
        <DropdownMenuContent align="end" className="w-44">
          <DropdownMenuGroup>
            <DropdownMenuItem>
              <VolumeOffIcon />
              Mute Conversation
            </DropdownMenuItem>
            <DropdownMenuItem>
              <CheckIcon />
              Mark as Read
            </DropdownMenuItem>
            <DropdownMenuItem>
              <AlertTriangleIcon />
              Report Conversation
            </DropdownMenuItem>
            <DropdownMenuItem>
              <UserRoundXIcon />
              Block User
            </DropdownMenuItem>
            <DropdownMenuItem>
              <ShareIcon />
              Share Conversation
            </DropdownMenuItem>
            <DropdownMenuItem>
              <CopyIcon />
              Copy Conversation
            </DropdownMenuItem>
          </DropdownMenuGroup>
          <DropdownMenuSeparator />
          <DropdownMenuGroup>
            <DropdownMenuItem variant="destructive">
              <TrashIcon />
              Delete Conversation
            </DropdownMenuItem>
          </DropdownMenuGroup>
        </DropdownMenuContent>
      </DropdownMenu>
    </ButtonGroup>
  );
}
```

## Select

Pair with a `Select` component.

### Example: button-group-select

```tsx
"use client";

import { Button } from "@workspace/ui/components/button";
import { ButtonGroup } from "@workspace/ui/components/button-group";
import { Input } from "@workspace/ui/components/input";
import {
  Select,
  SelectContent,
  SelectGroup,
  SelectItem,
  SelectTrigger,
} from "@workspace/ui/components/select";
import { ArrowRightIcon } from "lucide-react";
import * as React from "react";

const CURRENCIES = [
  { label: "US Dollar", value: "$" },
  { label: "Euro", value: "€" },
  { label: "British Pound", value: "£" },
];

export default function ButtonGroupSelect() {
  const [currency, setCurrency] = React.useState("$");

  return (
    <ButtonGroup>
      <ButtonGroup>
        <Select
          items={CURRENCIES}
          value={currency}
          onValueChange={(value) => setCurrency(value as string)}
        >
          <SelectTrigger className="font-mono">{currency}</SelectTrigger>
          <SelectContent alignItemWithTrigger={false} align="start">
            <SelectGroup>
              {CURRENCIES.map((item) => (
                <SelectItem key={item.value} value={item.value}>
                  {item.value}{" "}
                  <span className="text-muted-foreground">{item.label}</span>
                </SelectItem>
              ))}
            </SelectGroup>
          </SelectContent>
        </Select>
        <Input placeholder="10.00" pattern="[0-9]*" />
      </ButtonGroup>
      <ButtonGroup>
        <Button aria-label="Send" size="icon" variant="outline">
          <ArrowRightIcon />
        </Button>
      </ButtonGroup>
    </ButtonGroup>
  );
}
```

## Popover

Use with a `Popover` component.

### Example: button-group-popover

```tsx
import { Button } from "@workspace/ui/components/button";
import { ButtonGroup } from "@workspace/ui/components/button-group";
import {
  Field,
  FieldDescription,
  FieldLabel,
} from "@workspace/ui/components/field";
import {
  Popover,
  PopoverContent,
  PopoverDescription,
  PopoverHeader,
  PopoverTitle,
  PopoverTrigger,
} from "@workspace/ui/components/popover";
import { Textarea } from "@workspace/ui/components/textarea";
import { BotIcon, ChevronDownIcon } from "lucide-react";
import { useId as usePreviewId } from "react";

export default function ButtonGroupPopover() {
  const previewId = usePreviewId();

  return (
    <ButtonGroup>
      <Button variant="outline">
        <BotIcon /> Copilot
      </Button>
      <Popover>
        <PopoverTrigger
          render={
            <Button variant="outline" size="icon" aria-label="Open Popover" />
          }
        >
          <ChevronDownIcon />
        </PopoverTrigger>
        <PopoverContent align="end" className="rounded-xl text-sm">
          <PopoverHeader>
            <PopoverTitle>Start a new task with Copilot</PopoverTitle>
            <PopoverDescription>
              Describe your task in natural language.
            </PopoverDescription>
          </PopoverHeader>
          <Field>
            <FieldLabel htmlFor={`${previewId}-task`} className="sr-only">
              Task Description
            </FieldLabel>
            <Textarea
              id={`${previewId}-task`}
              placeholder="I need to..."
              className="resize-none"
            />
            <FieldDescription>
              Copilot will open a pull request for review.
            </FieldDescription>
          </Field>
        </PopoverContent>
      </Popover>
    </ButtonGroup>
  );
}
```

## RTL

To enable RTL support in shadcn/ui, see the [RTL configuration guide](https://ui.shadcn.com/docs/rtl).

### Example: button-group-rtl

```tsx
"use client";

import { Button } from "@workspace/ui/components/button";
import { ButtonGroup } from "@workspace/ui/components/button-group";
import {
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuGroup,
  DropdownMenuItem,
  DropdownMenuRadioGroup,
  DropdownMenuRadioItem,
  DropdownMenuSeparator,
  DropdownMenuSub,
  DropdownMenuSubContent,
  DropdownMenuSubTrigger,
  DropdownMenuTrigger,
} from "@workspace/ui/components/dropdown-menu";
import {
  ArchiveIcon,
  ArrowLeftIcon,
  CalendarPlusIcon,
  ClockIcon,
  ListFilterIcon,
  MailCheckIcon,
  MoreHorizontalIcon,
  TagIcon,
  Trash2Icon,
} from "lucide-react";
import * as React from "react";
import { type Translations, useTranslation } from "./support";

const translations: Translations = {
  en: {
    dir: "ltr",
    values: {
      archive: "Archive",
      report: "Report",
      snooze: "Snooze",
      markAsRead: "Mark as Read",
      addToCalendar: "Add to Calendar",
      addToList: "Add to List",
      labelAs: "Label As...",
      personal: "Personal",
      work: "Work",
      other: "Other",
      trash: "Trash",
    },
  },
  ar: {
    dir: "rtl",
    values: {
      archive: "أرشفة",
      report: "تقرير",
      snooze: "تأجيل",
      markAsRead: "وضع علامة كمقروء",
      addToCalendar: "إضافة إلى التقويم",
      addToList: "إضافة إلى القائمة",
      labelAs: "تصنيف كـ...",
      personal: "شخصي",
      work: "عمل",
      other: "آخر",
      trash: "سلة المهملات",
    },
  },
  he: {
    dir: "rtl",
    values: {
      archive: "ארכיון",
      report: "דוח",
      snooze: "דחה",
      markAsRead: "סמן כנקרא",
      addToCalendar: "הוסף ליומן",
      addToList: "הוסף לרשימה",
      labelAs: "תייג כ...",
      personal: "אישי",
      work: "עבודה",
      other: "אחר",
      trash: "פח",
    },
  },
};

export function ButtonGroupRtl() {
  const { dir, t, language } = useTranslation(translations, "ar");
  const [label, setLabel] = React.useState("personal");

  return (
    <div dir={dir}>
      <ButtonGroup>
        <ButtonGroup className="hidden sm:flex">
          <Button variant="outline" size="icon" aria-label="Go Back">
            <ArrowLeftIcon className="rtl:rotate-180" />
          </Button>
        </ButtonGroup>
        <ButtonGroup>
          <Button variant="outline">{t.archive}</Button>
          <Button variant="outline">{t.report}</Button>
        </ButtonGroup>
        <ButtonGroup>
          <Button variant="outline">{t.snooze}</Button>
          <DropdownMenu>
            <DropdownMenuTrigger
              render={
                <Button
                  variant="outline"
                  size="icon"
                  aria-label="More Options"
                />
              }
            >
              <MoreHorizontalIcon />
            </DropdownMenuTrigger>
            <DropdownMenuContent
              align={dir === "rtl" ? "start" : "end"}
              data-lang={dir === "rtl" ? language : undefined}
              dir={dir}
              className="w-40"
            >
              <DropdownMenuGroup>
                <DropdownMenuItem>
                  <MailCheckIcon />
                  {t.markAsRead}
                </DropdownMenuItem>
                <DropdownMenuItem>
                  <ArchiveIcon />
                  {t.archive}
                </DropdownMenuItem>
              </DropdownMenuGroup>
              <DropdownMenuSeparator />
              <DropdownMenuGroup>
                <DropdownMenuItem>
                  <ClockIcon />
                  {t.snooze}
                </DropdownMenuItem>
                <DropdownMenuItem>
                  <CalendarPlusIcon />
                  {t.addToCalendar}
                </DropdownMenuItem>
                <DropdownMenuItem>
                  <ListFilterIcon />
                  {t.addToList}
                </DropdownMenuItem>
                <DropdownMenuSub>
                  <DropdownMenuSubTrigger>
                    <TagIcon />
                    {t.labelAs}
                  </DropdownMenuSubTrigger>
                  <DropdownMenuSubContent
                    dir={dir}
                    data-lang={dir === "rtl" ? language : undefined}
                  >
                    <DropdownMenuRadioGroup
                      value={label}
                      onValueChange={setLabel}
                    >
                      <DropdownMenuRadioItem value="personal">
                        {t.personal}
                      </DropdownMenuRadioItem>
                      <DropdownMenuRadioItem value="work">
                        {t.work}
                      </DropdownMenuRadioItem>
                      <DropdownMenuRadioItem value="other">
                        {t.other}
                      </DropdownMenuRadioItem>
                    </DropdownMenuRadioGroup>
                  </DropdownMenuSubContent>
                </DropdownMenuSub>
              </DropdownMenuGroup>
              <DropdownMenuSeparator />
              <DropdownMenuGroup>
                <DropdownMenuItem variant="destructive">
                  <Trash2Icon />
                  {t.trash}
                </DropdownMenuItem>
              </DropdownMenuGroup>
            </DropdownMenuContent>
          </DropdownMenu>
        </ButtonGroup>
      </ButtonGroup>
    </div>
  );
}

export default ButtonGroupRtl;
```

## API Reference

### ButtonGroup

The `ButtonGroup` component is a container that groups related buttons together with consistent styling.

| Prop          | Type                         | Default        |
| ------------- | ---------------------------- | -------------- |
| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` |

```tsx
<ButtonGroup>
  <Button>Button 1</Button>
  <Button>Button 2</Button>
</ButtonGroup>
```

Nest multiple button groups to create complex layouts with spacing. See the [nested](#nested) example for more details.

```tsx
<ButtonGroup>
  <ButtonGroup />
  <ButtonGroup />
</ButtonGroup>
```

### ButtonGroupSeparator

The `ButtonGroupSeparator` component visually divides buttons within a group.

| Prop          | Type                         | Default      |
| ------------- | ---------------------------- | ------------ |
| `orientation` | `"horizontal" \| "vertical"` | `"vertical"` |

```tsx
<ButtonGroup>
  <Button>Button 1</Button>
  <ButtonGroupSeparator />
  <Button>Button 2</Button>
</ButtonGroup>
```

### ButtonGroupText

Use this component to display text within a button group.

| Prop     | Type                 | Default |
| -------- | -------------------- | ------- |
| `render` | `React.ReactElement` |         |

```tsx
<ButtonGroup>
  <ButtonGroupText>Text</ButtonGroupText>
  <Button>Button</Button>
</ButtonGroup>
```

Use the `render` prop to render a custom component as the text, for example a label.

```tsx showLineNumbers
import { ButtonGroupText } from "@workspace/ui/components/button-group"
import { Label } from "@workspace/ui/components/label"

export function ButtonGroupTextDemo() {
  return (
    <ButtonGroup>
      <ButtonGroupText render={<Label htmlFor="name" />}>Text</ButtonGroupText>
      <Input placeholder="Type something here..." id="name" />
    </ButtonGroup>
  )
}
```


---

# Calendar

A calendar component that allows users to select a date or a range of dates.

Page: https://sui.draco.dev/docs/components/calendar

### Example: calendar-demo

```tsx
"use client";

import { Calendar } from "@workspace/ui/components/calendar";
import * as React from "react";

export default function CalendarDemo() {
  const [date, setDate] = React.useState<Date | undefined>(
    new Date(2025, 5, 12),
  );

  return (
    <Calendar
      mode="single"
      selected={date}
      onSelect={setDate}
      className="rounded-lg border"
      captionLayout="dropdown"
    />
  );
}
```

## Installation

```bash
bunx --bun shadcn@latest add @sui/calendar
```

Install with the shadcn CLI or use the shared `@workspace/ui` package. Follow the [installation guide](/docs/installation) to configure the registry, load styles, and choose import aliases.

## Usage

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

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

return (
  <Calendar
    mode="single"
    selected={date}
    onSelect={setDate}
    className="rounded-lg border"
  />
)
```

See the [React DayPicker](https://react-day-picker.js.org) documentation for more information.

## About

The `Calendar` component is built on top of [React DayPicker](https://react-day-picker.js.org).

## Date Picker

You can use the `<Calendar>` component to build a date picker. See the [Date Picker](https://ui.shadcn.com/docs/components/base/date-picker) page for more information.

## Persian / Hijri / Jalali Calendar

To use the Persian calendar, edit `packages/ui/src/components/calendar.tsx` and replace `react-day-picker` with `@daypicker/persian`.

```diff
- import { DayPicker } from "react-day-picker"
+ import { DayPicker } from "@daypicker/persian"
```

The upstream example is named Hijri, but implements the Persian/Jalali calendar. With React DayPicker v10, use the `@daypicker/persian` addon.

### Example: calendar-hijri

```tsx
"use client";

// DayPicker v10 publishes the original Persian calendar in @daypicker/persian.

import { DayPicker } from "@daypicker/persian";
import { Button, buttonVariants } from "@workspace/ui/components/button";
import { cn } from "cn";
import {
  ChevronDownIcon,
  ChevronLeftIcon,
  ChevronRightIcon,
} from "lucide-react";
import * as React from "react";
import { type DayButton, getDefaultClassNames } from "react-day-picker";

export default function CalendarHijri() {
  const [date, setDate] = React.useState<Date | undefined>(
    new Date(2025, 5, 12),
  );

  return (
    <div className="font-sans">
      <Calendar
        mode="single"
        defaultMonth={date}
        selected={date}
        onSelect={setDate}
        className="rounded-lg border"
      />
    </div>
  );
}

// ----------------------------------------------------------------------------
// The code below is for this example only.
// For your own calendar, you would edit the calendar.tsx component directly.
// ----------------------------------------------------------------------------
function Calendar({
  className,
  classNames,
  showOutsideDays = true,
  captionLayout = "label",
  buttonVariant = "ghost",
  formatters,
  components,
  ...props
}: React.ComponentProps<typeof DayPicker> & {
  buttonVariant?: React.ComponentProps<typeof Button>["variant"];
}) {
  const defaultClassNames = getDefaultClassNames();

  return (
    <DayPicker
      showOutsideDays={showOutsideDays}
      className={cn(
        "group/calendar bg-background p-3 [--cell-size:--spacing(8)] [[data-slot=card-content]_&]:bg-transparent [[data-slot=popover-content]_&]:bg-transparent",
        String.raw`rtl:**:[.rdp-button\_next>svg]:rotate-180`,
        String.raw`rtl:**:[.rdp-button\_previous>svg]:rotate-180`,
        className,
      )}
      captionLayout={captionLayout}
      formatters={{
        formatMonthDropdown: (date) =>
          date.toLocaleString("default", { month: "short" }),
        ...formatters,
      }}
      classNames={{
        root: cn("w-fit", defaultClassNames.root),
        months: cn(
          "relative flex flex-col gap-4 md:flex-row",
          defaultClassNames.months,
        ),
        month: cn("flex w-full flex-col gap-4", defaultClassNames.month),
        nav: cn(
          "absolute inset-x-0 top-0 flex w-full items-center justify-between gap-1",
          defaultClassNames.nav,
        ),
        button_previous: cn(
          buttonVariants({ variant: buttonVariant }),
          "size-(--cell-size) select-none p-0 aria-disabled:opacity-50",
          defaultClassNames.button_previous,
        ),
        button_next: cn(
          buttonVariants({ variant: buttonVariant }),
          "size-(--cell-size) select-none p-0 aria-disabled:opacity-50",
          defaultClassNames.button_next,
        ),
        month_caption: cn(
          "flex h-(--cell-size) w-full items-center justify-center px-(--cell-size)",
          defaultClassNames.month_caption,
        ),
        dropdowns: cn(
          "flex h-(--cell-size) w-full items-center justify-center gap-1.5 font-medium text-sm",
          defaultClassNames.dropdowns,
        ),
        dropdown_root: cn(
          "relative rounded-md border border-input shadow-xs has-focus:border-ring has-focus:ring-[3px] has-focus:ring-ring/50",
          defaultClassNames.dropdown_root,
        ),
        dropdown: cn("absolute inset-0 opacity-0", defaultClassNames.dropdown),
        caption_label: cn(
          "select-none font-medium",
          captionLayout === "label"
            ? "text-sm"
            : "flex h-8 items-center gap-1 rounded-md pr-1 pl-2 text-sm [&>svg]:size-3.5 [&>svg]:text-muted-foreground",
          defaultClassNames.caption_label,
        ),
        month_grid: cn("w-full border-collapse", defaultClassNames.month_grid),
        weekdays: cn("flex", defaultClassNames.weekdays),
        weekday: cn(
          "flex-1 select-none rounded-md font-normal text-[0.8rem] text-muted-foreground",
          defaultClassNames.weekday,
        ),
        week: cn("mt-2 flex w-full", defaultClassNames.week),
        week_number_header: cn(
          "w-(--cell-size) select-none",
          defaultClassNames.week_number_header,
        ),
        week_number: cn(
          "select-none text-[0.8rem] text-muted-foreground",
          defaultClassNames.week_number,
        ),
        day: cn(
          "group/day relative aspect-square h-full w-full select-none p-0 text-center [&:first-child[data-selected=true]_button]:rounded-l-md [&:last-child[data-selected=true]_button]:rounded-r-md",
          defaultClassNames.day,
        ),
        range_start: cn(
          "rounded-l-md bg-accent",
          defaultClassNames.range_start,
        ),
        range_middle: cn("rounded-none", defaultClassNames.range_middle),
        range_end: cn("rounded-r-md bg-accent", defaultClassNames.range_end),
        today: cn(
          "rounded-md bg-accent text-accent-foreground data-[selected=true]:rounded-none",
          defaultClassNames.today,
        ),
        outside: cn(
          "text-muted-foreground aria-selected:text-muted-foreground",
          defaultClassNames.outside,
        ),
        disabled: cn(
          "text-muted-foreground opacity-50",
          defaultClassNames.disabled,
        ),
        hidden: cn("invisible", defaultClassNames.hidden),
        ...classNames,
      }}
      components={{
        Root: ({ className, rootRef, ...props }) => {
          return (
            <div
              data-slot="calendar"
              ref={rootRef}
              className={cn(className)}
              {...props}
            />
          );
        },
        Chevron: ({ className, orientation, ...props }) => {
          if (orientation === "left") {
            return (
              <ChevronLeftIcon className={cn("size-4", className)} {...props} />
            );
          }

          if (orientation === "right") {
            return (
              <ChevronRightIcon
                className={cn("size-4", className)}
                {...props}
              />
            );
          }

          return (
            <ChevronDownIcon className={cn("size-4", className)} {...props} />
          );
        },
        DayButton: CalendarDayButton,
        WeekNumber: ({ children, ...props }) => {
          return (
            <td {...props}>
              <div className="flex size-(--cell-size) items-center justify-center text-center">
                {children}
              </div>
            </td>
          );
        },
        ...components,
      }}
      {...props}
    />
  );
}

function CalendarDayButton({
  className,
  day,
  modifiers,
  ...props
}: React.ComponentProps<typeof DayButton>) {
  const defaultClassNames = getDefaultClassNames();

  const ref = React.useRef<HTMLButtonElement>(null);
  React.useEffect(() => {
    if (modifiers.focused) ref.current?.focus();
  }, [modifiers.focused]);

  return (
    <Button
      variant="ghost"
      size="icon"
      data-day={day.date.toLocaleDateString()}
      data-selected-single={
        modifiers.selected &&
        !modifiers.range_start &&
        !modifiers.range_end &&
        !modifiers.range_middle
      }
      data-range-start={modifiers.range_start}
      data-range-end={modifiers.range_end}
      data-range-middle={modifiers.range_middle}
      className={cn(
        "flex aspect-square size-auto w-full min-w-(--cell-size) flex-col gap-1 font-normal leading-none data-[range-end=true]:rounded-md data-[range-middle=true]:rounded-none data-[range-start=true]:rounded-md data-[range-end=true]:rounded-r-md data-[range-start=true]:rounded-l-md data-[range-end=true]:bg-primary data-[range-middle=true]:bg-accent data-[range-start=true]:bg-primary data-[selected-single=true]:bg-primary data-[range-end=true]:text-primary-foreground data-[range-middle=true]:text-accent-foreground data-[range-start=true]:text-primary-foreground data-[selected-single=true]:text-primary-foreground group-data-[focused=true]/day:relative group-data-[focused=true]/day:z-10 group-data-[focused=true]/day:border-ring group-data-[focused=true]/day:ring-[3px] group-data-[focused=true]/day:ring-ring/50 dark:hover:text-accent-foreground [&>span]:text-xs [&>span]:opacity-70",
        defaultClassNames.day,
        className,
      )}
      {...props}
    />
  );
}
```

## Selected Date (With TimeZone)

The Calendar component accepts a `timeZone` prop to ensure dates are displayed and selected in the user's local timezone.

```tsx showLineNumbers
export function CalendarWithTimezone() {
  const [date, setDate] = React.useState<Date | undefined>(undefined)
  const [timeZone, setTimeZone] = React.useState<string | undefined>(undefined)

  React.useEffect(() => {
    setTimeZone(Intl.DateTimeFormat().resolvedOptions().timeZone)
  }, [])

  return (
    <Calendar
      mode="single"
      selected={date}
      onSelect={setDate}
      timeZone={timeZone}
    />
  )
}
```

**Note:** If you notice a selected date offset (for example, selecting the 20th highlights the 19th), make sure the `timeZone` prop is set to the user's local timezone.

**Why client-side?** The timezone is detected using `Intl.DateTimeFormat().resolvedOptions().timeZone` inside a `useEffect` to ensure compatibility with server-side rendering. Detecting the timezone during render would cause hydration mismatches, as the server and client may be in different timezones.

## Basic

A basic calendar component. We used `className="rounded-lg border"` to style the calendar.

### Example: calendar-basic

```tsx
"use client";

import { Calendar } from "@workspace/ui/components/calendar";

export default function CalendarBasic() {
  return <Calendar mode="single" className="rounded-lg border" />;
}
```

## Range Calendar

Use the `mode="range"` prop to enable range selection.

### Example: calendar-range

```tsx
"use client";

import { Calendar } from "@workspace/ui/components/calendar";
import { addDays } from "date-fns";
import * as React from "react";
import type { DateRange } from "react-day-picker";

export function CalendarRange() {
  const [dateRange, setDateRange] = React.useState<DateRange | undefined>({
    from: new Date(2025, 0, 12),
    to: addDays(new Date(2025, 0, 12), 30),
  });

  return (
    <Calendar
      mode="range"
      defaultMonth={dateRange?.from}
      selected={dateRange}
      onSelect={setDateRange}
      numberOfMonths={2}
      className="rounded-lg border"
    />
  );
}

export default CalendarRange;
```

## Month and Year Selector

Use `captionLayout="dropdown"` to show month and year dropdowns.

### Example: calendar-caption

```tsx
"use client";

import { Calendar } from "@workspace/ui/components/calendar";

export function CalendarCaption() {
  return (
    <Calendar
      mode="single"
      captionLayout="dropdown"
      className="rounded-lg border"
    />
  );
}

export default CalendarCaption;
```

## Presets

### Example: calendar-presets

```tsx
"use client";

import { Button } from "@workspace/ui/components/button";
import { Calendar } from "@workspace/ui/components/calendar";
import { Card, CardContent, CardFooter } from "@workspace/ui/components/card";
import { addDays } from "date-fns";
import * as React from "react";

export function CalendarWithPresets() {
  const [date, setDate] = React.useState<Date | undefined>(
    new Date(2025, 1, 12),
  );
  const [currentMonth, setCurrentMonth] = React.useState<Date>(
    new Date(
      new Date(2025, 5, 12).getFullYear(),
      new Date(2025, 5, 12).getMonth(),
      1,
    ),
  );

  return (
    <Card className="mx-auto w-fit max-w-[300px]" size="sm">
      <CardContent>
        <Calendar
          mode="single"
          selected={date}
          onSelect={setDate}
          month={currentMonth}
          onMonthChange={setCurrentMonth}
          fixedWeeks
          className="p-0 [--cell-size:--spacing(9.5)]"
        />
      </CardContent>
      <CardFooter className="flex flex-wrap gap-2 border-t">
        {[
          { label: "Today", value: 0 },
          { label: "Tomorrow", value: 1 },
          { label: "In 3 days", value: 3 },
          { label: "In a week", value: 7 },
          { label: "In 2 weeks", value: 14 },
        ].map((preset) => (
          <Button
            key={preset.value}
            variant="outline"
            size="sm"
            className="flex-1"
            onClick={() => {
              const newDate = addDays(new Date(2025, 5, 12), preset.value);
              setDate(newDate);
              setCurrentMonth(
                new Date(newDate.getFullYear(), newDate.getMonth(), 1),
              );
            }}
          >
            {preset.label}
          </Button>
        ))}
      </CardFooter>
    </Card>
  );
}

export default CalendarWithPresets;
```

## Date and Time Picker

### Example: calendar-time

```tsx
"use client";

import { Calendar } from "@workspace/ui/components/calendar";
import { Card, CardContent, CardFooter } from "@workspace/ui/components/card";
import { Field, FieldGroup, FieldLabel } from "@workspace/ui/components/field";
import {
  InputGroup,
  InputGroupAddon,
  InputGroupInput,
} from "@workspace/ui/components/input-group";
import { Clock2Icon } from "lucide-react";
import * as React from "react";
import { useId as usePreviewId } from "react";

export function CalendarWithTime() {
  const previewId = usePreviewId();

  const [date, setDate] = React.useState<Date | undefined>(
    new Date(
      new Date(2025, 5, 12).getFullYear(),
      new Date(2025, 5, 12).getMonth(),
      12,
    ),
  );

  return (
    <Card size="sm" className="mx-auto w-fit">
      <CardContent>
        <Calendar
          mode="single"
          selected={date}
          onSelect={setDate}
          className="p-0"
        />
      </CardContent>
      <CardFooter className="border-t bg-card">
        <FieldGroup>
          <Field>
            <FieldLabel htmlFor={`${previewId}-time-from`}>
              Start Time
            </FieldLabel>
            <InputGroup>
              <InputGroupInput
                id={`${previewId}-time-from`}
                type="time"
                step="1"
                defaultValue="10:30:00"
                className="appearance-none [&::-webkit-calendar-picker-indicator]:hidden [&::-webkit-calendar-picker-indicator]:appearance-none"
              />
              <InputGroupAddon>
                <Clock2Icon className="text-muted-foreground" />
              </InputGroupAddon>
            </InputGroup>
          </Field>
          <Field>
            <FieldLabel htmlFor={`${previewId}-time-to`}>End Time</FieldLabel>
            <InputGroup>
              <InputGroupInput
                id={`${previewId}-time-to`}
                type="time"
                step="1"
                defaultValue="12:30:00"
                className="appearance-none [&::-webkit-calendar-picker-indicator]:hidden [&::-webkit-calendar-picker-indicator]:appearance-none"
              />
              <InputGroupAddon>
                <Clock2Icon className="text-muted-foreground" />
              </InputGroupAddon>
            </InputGroup>
          </Field>
        </FieldGroup>
      </CardFooter>
    </Card>
  );
}

export default CalendarWithTime;
```

## Booked dates

### Example: calendar-booked-dates

```tsx
"use client";

import { Calendar } from "@workspace/ui/components/calendar";
import { Card, CardContent } from "@workspace/ui/components/card";
import * as React from "react";

export function CalendarBookedDates() {
  const [date, setDate] = React.useState<Date | undefined>(
    new Date(2025, 0, 6),
  );
  const bookedDates = Array.from(
    { length: 15 },
    (_, i) => new Date(2025, 0, 12 + i),
  );

  return (
    <Card className="mx-auto w-fit p-0">
      <CardContent className="p-0">
        <Calendar
          mode="single"
          defaultMonth={date}
          selected={date}
          onSelect={setDate}
          disabled={bookedDates}
          modifiers={{
            booked: bookedDates,
          }}
          modifiersClassNames={{
            booked: "[&>button]:line-through opacity-100",
          }}
        />
      </CardContent>
    </Card>
  );
}

export default CalendarBookedDates;
```

## Custom Cell Size

### Example: calendar-custom-days

```tsx
"use client";

import { Calendar, CalendarDayButton } from "@workspace/ui/components/calendar";
import { Card, CardContent } from "@workspace/ui/components/card";
import { addDays } from "date-fns";
import * as React from "react";
import type { DateRange } from "react-day-picker";

export function CalendarCustomDays() {
  const [range, setRange] = React.useState<DateRange | undefined>({
    from: new Date(2025, 11, 8),
    to: addDays(new Date(2025, 11, 8), 10),
  });

  return (
    <Card className="mx-auto w-fit p-0">
      <CardContent className="p-0">
        <Calendar
          mode="range"
          defaultMonth={range?.from}
          selected={range}
          onSelect={setRange}
          numberOfMonths={1}
          captionLayout="dropdown"
          className="[--cell-size:--spacing(10)] md:[--cell-size:--spacing(12)]"
          formatters={{
            formatMonthDropdown: (date) => {
              return date.toLocaleString("default", { month: "long" });
            },
          }}
          components={{
            DayButton: ({ children, modifiers, day, ...props }) => {
              const isWeekend =
                day.date.getDay() === 0 || day.date.getDay() === 6;

              return (
                <CalendarDayButton day={day} modifiers={modifiers} {...props}>
                  {children}
                  {!modifiers.outside && (
                    <span>{isWeekend ? "$120" : "$100"}</span>
                  )}
                </CalendarDayButton>
              );
            },
          }}
        />
      </CardContent>
    </Card>
  );
}

export default CalendarCustomDays;
```

You can customize the size of calendar cells using the `--cell-size` CSS variable. You can also make it responsive by using breakpoint-specific values:

```tsx showLineNumbers
<Calendar
  mode="single"
  selected={date}
  onSelect={setDate}
  className="rounded-lg border [--cell-size:--spacing(11)] md:[--cell-size:--spacing(12)]"
/>
```

Or use fixed values:

```tsx showLineNumbers
<Calendar
  mode="single"
  selected={date}
  onSelect={setDate}
  className="rounded-lg border [--cell-size:2.75rem] md:[--cell-size:3rem]"
/>
```

## Week Numbers

Use `showWeekNumber` to show week numbers.

### Example: calendar-week-numbers

```tsx
"use client";

import { Calendar } from "@workspace/ui/components/calendar";
import { Card, CardContent } from "@workspace/ui/components/card";
import * as React from "react";

export function CalendarWeekNumbers() {
  const [date, setDate] = React.useState<Date | undefined>(
    new Date(2025, 0, 12),
  );

  return (
    <Card className="mx-auto w-fit p-0">
      <CardContent className="p-0">
        <Calendar
          mode="single"
          defaultMonth={date}
          selected={date}
          onSelect={setDate}
          showWeekNumber
        />
      </CardContent>
    </Card>
  );
}

export default CalendarWeekNumbers;
```

## RTL

To enable RTL support in shadcn/ui, see the [RTL configuration guide](https://ui.shadcn.com/docs/rtl).

See also the [Hijri Guide](#persian--hijri--jalali-calendar) for enabling the Persian / Hijri / Jalali calendar.

### Example: calendar-rtl

```tsx
"use client";

import { Calendar } from "@workspace/ui/components/calendar";
import * as React from "react";
import { arSA, he } from "react-day-picker/locale";
import { type Translations, useTranslation } from "./support";

const translations: Translations = {
  en: {
    dir: "ltr",
    values: {},
  },
  ar: {
    dir: "rtl",
    values: {},
  },
  he: {
    dir: "rtl",
    values: {},
  },
};

const locales = {
  ar: arSA,
  he: he,
} as const;

export function CalendarRtl() {
  const { dir, language } = useTranslation(translations, "ar");
  const [date, setDate] = React.useState<Date | undefined>(
    new Date(2025, 5, 12),
  );

  return (
    <Calendar
      mode="single"
      selected={date}
      onSelect={setDate}
      className="rounded-lg border [--cell-size:--spacing(9)]"
      captionLayout="dropdown"
      dir={dir}
      locale={
        dir === "rtl" ? locales[language as keyof typeof locales] : undefined
      }
    />
  );
}

export default CalendarRtl;
```

When using RTL, import the locale from `react-day-picker/locale` and pass both the `locale` and `dir` props to the Calendar component:

```tsx showLineNumbers
import { arSA } from "react-day-picker/locale"

;<Calendar
  mode="single"
  selected={date}
  onSelect={setDate}
  locale={arSA}
  dir="rtl"
/>
```

## API Reference

See the [React DayPicker](https://react-day-picker.js.org) documentation for more information on the `Calendar` component.

## Changelog

### RTL Support

If you're upgrading from a previous version of the `Calendar` component, you'll need to apply the following updates to add locale support:

### Import the `Locale` type.

Add `Locale` to your imports from `react-day-picker`:

```diff
  import {
    DayPicker,
    getDefaultClassNames,
    type DayButton,
+   type Locale,
  } from "react-day-picker"
```

### Add `locale` prop to the Calendar component.

Add the `locale` prop to the component's props:

```diff
  function Calendar({
    className,
    classNames,
    showOutsideDays = true,
    captionLayout = "label",
    buttonVariant = "ghost",
+   locale,
    formatters,
    components,
    ...props
  }: React.ComponentProps<typeof DayPicker> & {
    buttonVariant?: React.ComponentProps<typeof Button>["variant"]
  }) {
```

### Pass `locale` to DayPicker.

Pass the `locale` prop to the `DayPicker` component:

```diff
    <DayPicker
      showOutsideDays={showOutsideDays}
      className={cn(...)}
      captionLayout={captionLayout}
+     locale={locale}
      formatters={{
        formatMonthDropdown: (date) =>
-         date.toLocaleString("default", { month: "short" }),
+         date.toLocaleString(locale?.code, { month: "short" }),
        ...formatters,
      }}
```

### Update CalendarDayButton to accept locale.

Update the `CalendarDayButton` component signature and pass `locale`:

```diff
  function CalendarDayButton({
    className,
    day,
    modifiers,
+   locale,
    ...props
- }: React.ComponentProps<typeof DayButton>) {
+ }: React.ComponentProps<typeof DayButton> & { locale?: Partial<Locale> }) {
```

### Update date formatting in CalendarDayButton.

Use `locale?.code` in the date formatting:

```diff
    <Button
      variant="ghost"
      size="icon"
-     data-day={day.date.toLocaleDateString()}
+     data-day={day.date.toLocaleDateString(locale?.code)}
      ...
    />
```

### Pass locale to DayButton component.

Update the `DayButton` component usage to pass the `locale` prop:

```diff
      components={{
        ...
-       DayButton: CalendarDayButton,
+       DayButton: ({ ...props }) => (
+         <CalendarDayButton locale={locale} {...props} />
+       ),
        ...
      }}
```

### Update RTL-aware CSS classes.

Replace directional classes with logical properties for better RTL support:

```diff
  // In the day classNames:
- [&:last-child[data-selected=true]_button]:rounded-r-(--cell-radius)
+ [&:last-child[data-selected=true]_button]:rounded-e-(--cell-radius)
- [&:nth-child(2)[data-selected=true]_button]:rounded-l-(--cell-radius)
+ [&:nth-child(2)[data-selected=true]_button]:rounded-s-(--cell-radius)
- [&:first-child[data-selected=true]_button]:rounded-l-(--cell-radius)
+ [&:first-child[data-selected=true]_button]:rounded-s-(--cell-radius)

  // In range_start classNames:
- rounded-l-(--cell-radius) ... after:right-0
+ rounded-s-(--cell-radius) ... after:end-0

  // In range_end classNames:
- rounded-r-(--cell-radius) ... after:left-0
+ rounded-e-(--cell-radius) ... after:start-0

  // In CalendarDayButton className:
- data-[range-end=true]:rounded-r-(--cell-radius)
+ data-[range-end=true]:rounded-e-(--cell-radius)
- data-[range-start=true]:rounded-l-(--cell-radius)
+ data-[range-start=true]:rounded-s-(--cell-radius)
```

After applying these changes, you can use the `locale` prop to provide locale-specific formatting:

```tsx
import { enUS } from "react-day-picker/locale"

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

- [Documentation](https://react-day-picker.js.org)


---

# Card

Displays a card with header, content, and footer.

Page: https://sui.draco.dev/docs/components/card

### Example: card-demo

```tsx
import { Button } from "@workspace/ui/components/button";
import {
  Card,
  CardAction,
  CardContent,
  CardDescription,
  CardFooter,
  CardHeader,
  CardTitle,
} from "@workspace/ui/components/card";
import { Input } from "@workspace/ui/components/input";
import { Label } from "@workspace/ui/components/label";
import { useId as usePreviewId } from "react";

export default function CardDemo() {
  const previewId = usePreviewId();

  return (
    <Card className="w-full max-w-sm">
      <CardHeader>
        <CardTitle>Login to your account</CardTitle>
        <CardDescription>
          Enter your email below to login to your account
        </CardDescription>
        <CardAction>
          <Button variant="link">Sign Up</Button>
        </CardAction>
      </CardHeader>
      <CardContent>
        <form>
          <div className="flex flex-col gap-6">
            <div className="grid gap-2">
              <Label htmlFor={`${previewId}-email`}>Email</Label>
              <Input
                id={`${previewId}-email`}
                type="email"
                placeholder="m@example.com"
                required
              />
            </div>
            <div className="grid gap-2">
              <div className="flex items-center">
                <Label htmlFor={`${previewId}-password`}>Password</Label>
                <a
                  href="/docs"
                  className="ml-auto inline-block text-sm underline-offset-4 hover:underline"
                >
                  Forgot your password?
                </a>
              </div>
              <Input id={`${previewId}-password`} type="password" required />
            </div>
          </div>
        </form>
      </CardContent>
      <CardFooter className="flex-col gap-2">
        <Button type="submit" className="w-full">
          Login
        </Button>
        <Button variant="outline" className="w-full">
          Login with Google
        </Button>
      </CardFooter>
    </Card>
  );
}
```

## Installation

```bash
bunx --bun shadcn@latest add @sui/card
```

Install with the shadcn CLI or use the shared `@workspace/ui` package. Follow the [installation guide](/docs/installation) to configure the registry, load styles, and choose import aliases.

## Usage

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

```tsx showLineNumbers
<Card>
  <CardHeader>
    <CardTitle>Card Title</CardTitle>
    <CardDescription>Card Description</CardDescription>
    <CardAction>Card Action</CardAction>
  </CardHeader>
  <CardContent>
    <p>Card Content</p>
  </CardContent>
  <CardFooter>
    <p>Card Footer</p>
  </CardFooter>
</Card>
```

## Composition

Use the following composition to build a `Card`:

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

## Size

Use the `size="sm"` prop to set the size of the card to small. The small size variant uses smaller spacing.

### Example: card-small

```tsx
import { Button } from "@workspace/ui/components/button";
import {
  Card,
  CardContent,
  CardDescription,
  CardFooter,
  CardHeader,
  CardTitle,
} from "@workspace/ui/components/card";
import { ChevronRightIcon } from "lucide-react";

export function CardSmall() {
  const featureName = "Scheduled reports";

  return (
    <Card size="sm" className="mx-auto w-full max-w-xs">
      <CardHeader>
        <CardTitle>{featureName}</CardTitle>
        <CardDescription>
          Weekly snapshots. No more manual exports.
        </CardDescription>
      </CardHeader>
      <CardContent>
        <ul className="grid gap-2 py-2 text-sm">
          <li className="flex gap-2">
            <ChevronRightIcon className="mt-0.5 size-4 shrink-0 text-muted-foreground" />
            <span>Choose a schedule (daily, or weekly).</span>
          </li>
          <li className="flex gap-2">
            <ChevronRightIcon className="mt-0.5 size-4 shrink-0 text-muted-foreground" />
            <span>Send to channels or specific teammates.</span>
          </li>
          <li className="flex gap-2">
            <ChevronRightIcon className="mt-0.5 size-4 shrink-0 text-muted-foreground" />
            <span>Include charts, tables, and key metrics.</span>
          </li>
        </ul>
      </CardContent>
      <CardFooter className="flex-col gap-2">
        <Button size="sm" className="w-full">
          Set up scheduled reports
        </Button>
        <Button variant="outline" size="sm" className="w-full">
          See what&apos;s new
        </Button>
      </CardFooter>
    </Card>
  );
}

export default CardSmall;
```

## Spacing

In addition to the `size` prop, you can use the `--card-spacing` CSS variable to control the spacing between sections and the inset of card parts.

### Example: card-spacing

```tsx
"use client";

import { Button } from "@workspace/ui/components/button";
import {
  Card,
  CardAction,
  CardContent,
  CardDescription,
  CardFooter,
  CardHeader,
  CardTitle,
} from "@workspace/ui/components/card";
import { Input } from "@workspace/ui/components/input";
import { Label } from "@workspace/ui/components/label";
import {
  ToggleGroup,
  ToggleGroupItem,
} from "@workspace/ui/components/toggle-group";
import * as React from "react";
import { useId as usePreviewId } from "react";

const spacingOptions = [
  {
    className: "[--card-spacing:--spacing(4)]",
    label: "16px",
    value: "4",
  },
  {
    className: "[--card-spacing:--spacing(5)]",
    label: "20px",
    value: "5",
  },
  {
    className: "[--card-spacing:--spacing(6)]",
    label: "24px",
    value: "6",
  },
  {
    className: "[--card-spacing:--spacing(8)]",
    label: "32px",
    value: "8",
  },
];

export function CardSpacing() {
  const previewId = usePreviewId();

  const [spacing, setSpacing] = React.useState("4");
  const selectedSpacing = spacingOptions.find(
    (option) => option.value === spacing,
  );

  return (
    <div className="mx-auto grid w-full max-w-sm gap-4">
      <ToggleGroup
        value={[spacing]}
        onValueChange={(value) => {
          if (value[0]) {
            setSpacing(value[0]);
          }
        }}
        variant="outline"
        size="sm"
        className="justify-center"
      >
        {spacingOptions.map((option) => (
          <ToggleGroupItem key={option.value} value={option.value}>
            {option.label}
          </ToggleGroupItem>
        ))}
      </ToggleGroup>
      <Card className={selectedSpacing?.className}>
        <CardHeader>
          <CardTitle>Login to your account</CardTitle>
          <CardDescription>
            Enter your email below to login to your account
          </CardDescription>
          <CardAction>
            <Button variant="link">Sign Up</Button>
          </CardAction>
        </CardHeader>
        <CardContent>
          <form>
            <div className="flex flex-col gap-6">
              <div className="grid gap-2">
                <Label htmlFor={`${previewId}-email-spacing`}>Email</Label>
                <Input
                  id={`${previewId}-email-spacing`}
                  type="email"
                  placeholder="m@example.com"
                  required
                />
              </div>
              <div className="grid gap-2">
                <div className="flex items-center">
                  <Label htmlFor={`${previewId}-password-spacing`}>
                    Password
                  </Label>
                  <a
                    href="/docs"
                    className="ml-auto inline-block text-sm underline-offset-4 hover:underline"
                  >
                    Forgot your password?
                  </a>
                </div>
                <Input
                  id={`${previewId}-password-spacing`}
                  type="password"
                  required
                />
              </div>
            </div>
          </form>
        </CardContent>
        <CardFooter className="flex-col gap-2">
          <Button type="submit" className="w-full">
            Login
          </Button>
          <Button variant="outline" className="w-full">
            Login with Google
          </Button>
        </CardFooter>
      </Card>
    </div>
  );
}

export default CardSpacing;
```

Use negative margins with `-mx-(--card-spacing)` to make content go edge to edge while keeping it aligned with the card inset. When the edge-to-edge content sits above a footer, use `-mb-(--card-spacing)` on `CardContent` to remove the section gap.

### Example: card-edge-to-edge

```tsx
import { Button } from "@workspace/ui/components/button";
import {
  Card,
  CardContent,
  CardDescription,
  CardFooter,
  CardHeader,
  CardTitle,
} from "@workspace/ui/components/card";

export function CardEdgeToEdge() {
  return (
    <Card className="mx-auto w-full max-w-sm">
      <CardHeader>
        <CardTitle>Terms of Service</CardTitle>
        <CardDescription>
          Review the terms before accepting the agreement.
        </CardDescription>
      </CardHeader>
      <CardContent className="-mb-(--card-spacing)">
        <div className="-mx-(--card-spacing) max-h-48 space-y-4 overflow-y-scroll border-t bg-muted/50 px-(--card-spacing) py-4 text-sm leading-relaxed">
          <p>
            These terms govern your use of the workspace, including access to
            shared documents, project files, and collaboration tools.
          </p>
          <p>
            You are responsible for the content you upload and for ensuring that
            your team has the appropriate permissions to view or edit it.
          </p>
          <p>
            We may update features or limits as the service evolves. When those
            changes materially affect your workflow, we will notify your
            workspace administrators.
          </p>
          <p>
            By continuing, you agree to keep your account credentials secure and
            to follow your organization&apos;s acceptable use policies.
          </p>
        </div>
      </CardContent>
      <CardFooter className="justify-end gap-2">
        <Button variant="outline">Decline</Button>
        <Button>Accept</Button>
      </CardFooter>
    </Card>
  );
}

export default CardEdgeToEdge;
```

## Image

Add an image before the card header to create a card with an image.

### Example: card-image

```tsx
import { Badge } from "@workspace/ui/components/badge";
import { Button } from "@workspace/ui/components/button";
import {
  Card,
  CardAction,
  CardDescription,
  CardFooter,
  CardHeader,
  CardTitle,
} from "@workspace/ui/components/card";

export function CardImage() {
  return (
    <Card className="relative mx-auto w-full max-w-sm pt-0">
      <div className="absolute inset-0 z-30 aspect-video bg-black/35" />
      <img
        src="https://avatar.vercel.sh/shadcn1"
        alt="Event cover"
        className="relative z-20 aspect-video w-full object-cover brightness-60 grayscale dark:brightness-40"
      />
      <CardHeader>
        <CardAction>
          <Badge variant="secondary">Featured</Badge>
        </CardAction>
        <CardTitle>Design systems meetup</CardTitle>
        <CardDescription>
          A practical talk on component APIs, accessibility, and shipping
          faster.
        </CardDescription>
      </CardHeader>
      <CardFooter>
        <Button className="w-full">View Event</Button>
      </CardFooter>
    </Card>
  );
}

export default CardImage;
```

## RTL

To enable RTL support in shadcn/ui, see the [RTL configuration guide](https://ui.shadcn.com/docs/rtl).

### Example: card-rtl

```tsx
"use client";

import { Button } from "@workspace/ui/components/button";
import {
  Card,
  CardAction,
  CardContent,
  CardDescription,
  CardFooter,
  CardHeader,
  CardTitle,
} from "@workspace/ui/components/card";
import { Input } from "@workspace/ui/components/input";
import { Label } from "@workspace/ui/components/label";
import { useId as usePreviewId } from "react";
import { type Translations, useTranslation } from "./support";

const translations: Translations = {
  en: {
    dir: "ltr",
    values: {
      title: "Login to your account",
      description: "Enter your email below to login to your account",
      signUp: "Sign Up",
      email: "Email",
      emailPlaceholder: "m@example.com",
      password: "Password",
      forgotPassword: "Forgot your password?",
      login: "Login",
      loginWithGoogle: "Login with Google",
    },
  },
  ar: {
    dir: "rtl",
    values: {
      title: "تسجيل الدخول إلى حسابك",
      description: "أدخل بريدك الإلكتروني أدناه لتسجيل الدخول إلى حسابك",
      signUp: "إنشاء حساب",
      email: "البريد الإلكتروني",
      emailPlaceholder: "m@example.com",
      password: "كلمة المرور",
      forgotPassword: "نسيت كلمة المرور؟",
      login: "تسجيل الدخول",
      loginWithGoogle: "تسجيل الدخول باستخدام Google",
    },
  },
  he: {
    dir: "rtl",
    values: {
      title: "התחבר לחשבון שלך",
      description: "הזן את האימייל שלך למטה כדי להתחבר לחשבון שלך",
      signUp: "הירשם",
      email: "אימייל",
      emailPlaceholder: "m@example.com",
      password: "סיסמה",
      forgotPassword: "שכחת את הסיסמה?",
      login: "התחבר",
      loginWithGoogle: "התחבר עם Google",
    },
  },
};

export function CardRtl() {
  const previewId = usePreviewId();

  const { dir, t } = useTranslation(translations, "ar");

  return (
    <Card className="w-full max-w-sm" dir={dir}>
      <CardHeader>
        <CardTitle>{t.title}</CardTitle>
        <CardDescription>{t.description}</CardDescription>
        <CardAction>
          <Button variant="link">{t.signUp}</Button>
        </CardAction>
      </CardHeader>
      <CardContent>
        <form>
          <div className="flex flex-col gap-6">
            <div className="grid gap-2">
              <Label htmlFor={`${previewId}-email-rtl`}>{t.email}</Label>
              <Input
                id={`${previewId}-email-rtl`}
                type="email"
                placeholder={t.emailPlaceholder}
                required
              />
            </div>
            <div className="grid gap-2">
              <div className="flex items-center">
                <Label htmlFor={`${previewId}-password-rtl`}>
                  {t.password}
                </Label>
                <a
                  href="/docs"
                  className="ms-auto inline-block text-sm underline-offset-4 hover:underline"
                >
                  {t.forgotPassword}
                </a>
              </div>
              <Input
                id={`${previewId}-password-rtl`}
                type="password"
                required
              />
            </div>
          </div>
        </form>
      </CardContent>
      <CardFooter className="flex-col gap-2">
        <Button type="submit" className="w-full">
          {t.login}
        </Button>
        <Button variant="outline" className="w-full">
          {t.loginWithGoogle}
        </Button>
      </CardFooter>
    </Card>
  );
}

export default CardRtl;
```

## API Reference

### Card

The `Card` component is the root container for card content.

| Prop        | Type                | Default     |
| ----------- | ------------------- | ----------- |
| `size`      | `"default" \| "sm"` | `"default"` |
| `className` | `string`            | -           |

### CardHeader

The `CardHeader` component is used for a title, description, and optional action.

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` | -       |

### CardTitle

The `CardTitle` component is used for the card title.

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` | -       |

### CardDescription

The `CardDescription` component is used for helper text under the title.

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` | -       |

### CardAction

The `CardAction` component places content in the top-right of the header (for example, a button or a badge).

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` | -       |

### CardContent

The `CardContent` component is used for the main card body.

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` | -       |

### CardFooter

The `CardFooter` component is used for actions and secondary content at the bottom of the card.

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` | -       |

## Changelog

### Spacing Variable

If you're upgrading from a previous version of the `Card` component, you'll need to apply the following updates to use the `--card-spacing` variable:

### Update the Card root spacing classes.

Replace the hard-coded gap and vertical padding with `--card-spacing`, and set the default and small size values on the root:

```diff
  className={cn(
-   "group/card flex flex-col gap-4 overflow-hidden rounded-xl bg-card py-4 text-sm text-card-foreground ring-1 ring-foreground/10 has-data-[slot=card-footer]:pb-0 has-[>img:first-child]:pt-0 data-[size=sm]:gap-3 data-[size=sm]:py-3 data-[size=sm]:has-data-[slot=card-footer]:pb-0 *:[img:first-child]:rounded-t-xl *:[img:last-child]:rounded-b-xl",
+   "group/card flex flex-col gap-(--card-spacing) overflow-hidden rounded-xl bg-card py-(--card-spacing) text-sm text-card-foreground ring-1 ring-foreground/10 [--card-spacing:--spacing(4)] has-data-[slot=card-footer]:pb-0 has-[>img:first-child]:pt-0 data-[size=sm]:[--card-spacing:--spacing(3)] data-[size=sm]:has-data-[slot=card-footer]:pb-0 *:[img:first-child]:rounded-t-xl *:[img:last-child]:rounded-b-xl",
    className
  )}
```

### Update CardHeader spacing classes.

Replace the horizontal padding and border spacing with the shared variable:

```diff
  className={cn(
-   "group/card-header @container/card-header grid auto-rows-min items-start gap-1 rounded-t-xl px-4 group-data-[size=sm]/card:px-3 has-data-[slot=card-action]:grid-cols-[1fr_auto] has-data-[slot=card-description]:grid-rows-[auto_auto] [.border-b]:pb-4 group-data-[size=sm]/card:[.border-b]:pb-3",
+   "group/card-header @container/card-header grid auto-rows-min items-start gap-1 rounded-t-xl px-(--card-spacing) has-data-[slot=card-action]:grid-cols-[1fr_auto] has-data-[slot=card-description]:grid-rows-[auto_auto] [.border-b]:pb-(--card-spacing)",
    className
  )}
```

### Update CardContent and CardFooter spacing classes.

Use `--card-spacing` for the content inset and footer padding:

```diff
  function CardContent({ className, ...props }: React.ComponentProps<"div">) {
    return (
      <div
        data-slot="card-content"
-       className={cn("px-4 group-data-[size=sm]/card:px-3", className)}
+       className={cn("px-(--card-spacing)", className)}
        {...props}
      />
    )
  }
```

```diff
  className={cn(
-   "flex items-center rounded-b-xl border-t bg-muted/50 p-4 group-data-[size=sm]/card:p-3",
+   "flex items-center rounded-b-xl border-t bg-muted/50 p-(--card-spacing)",
    className
  )}
```

After applying these changes, you can customize card spacing by setting `--card-spacing` on the `Card` with an arbitrary property class:

```tsx
function Example() {
  return <Card className="[--card-spacing:--spacing(6)]">...</Card>
}
```


---

# Carousel

A carousel with motion and swipe built using Embla.

Page: https://sui.draco.dev/docs/components/carousel

### Example: carousel-demo

```tsx
// biome-ignore-all lint/suspicious/noArrayIndexKey: The upstream gallery uses fixed positional fixtures that never reorder.

import { Card, CardContent } from "@workspace/ui/components/card";
import {
  Carousel,
  CarouselContent,
  CarouselItem,
  CarouselNext,
  CarouselPrevious,
} from "@workspace/ui/components/carousel";

export default function CarouselDemo() {
  return (
    <Carousel className="w-full max-w-[12rem] sm:max-w-xs">
      <CarouselContent>
        {Array.from({ length: 5 }).map((_, index) => (
          <CarouselItem key={index}>
            <div className="p-1">
              <Card>
                <CardContent className="flex aspect-square items-center justify-center p-6">
                  <span className="font-semibold text-4xl">{index + 1}</span>
                </CardContent>
              </Card>
            </div>
          </CarouselItem>
        ))}
      </CarouselContent>
      <CarouselPrevious />
      <CarouselNext />
    </Carousel>
  );
}
```

## About

The carousel component is built using the [Embla Carousel](https://www.embla-carousel.com/) library.

## Installation

```bash
bunx --bun shadcn@latest add @sui/carousel
```

Install with the shadcn CLI or use the shared `@workspace/ui` package. Follow the [installation guide](/docs/installation) to configure the registry, load styles, and choose import aliases.

## Usage

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

```tsx showLineNumbers
<Carousel>
  <CarouselContent>
    <CarouselItem>...</CarouselItem>
    <CarouselItem>...</CarouselItem>
    <CarouselItem>...</CarouselItem>
  </CarouselContent>
  <CarouselPrevious />
  <CarouselNext />
</Carousel>
```

## Composition

Use the following composition to build a `Carousel`:

```text
Carousel
├── CarouselContent
│   ├── CarouselItem
│   └── CarouselItem
├── CarouselPrevious
└── CarouselNext
```

## Sizes

To set the size of the items, you can use the `basis` utility class on the `<CarouselItem />`.

### Example: carousel-size

```tsx
// biome-ignore-all lint/suspicious/noArrayIndexKey: The upstream gallery uses fixed positional fixtures that never reorder.

import { Card, CardContent } from "@workspace/ui/components/card";
import {
  Carousel,
  CarouselContent,
  CarouselItem,
  CarouselNext,
  CarouselPrevious,
} from "@workspace/ui/components/carousel";

export default function CarouselSize() {
  return (
    <Carousel
      opts={{
        align: "start",
      }}
      className="w-full max-w-[12rem] sm:max-w-xs md:max-w-sm"
    >
      <CarouselContent>
        {Array.from({ length: 5 }).map((_, index) => (
          <CarouselItem key={index} className="basis-1/2 lg:basis-1/3">
            <div className="p-1">
              <Card>
                <CardContent className="flex aspect-square items-center justify-center p-6">
                  <span className="font-semibold text-3xl">{index + 1}</span>
                </CardContent>
              </Card>
            </div>
          </CarouselItem>
        ))}
      </CarouselContent>
      <CarouselPrevious />
      <CarouselNext />
    </Carousel>
  );
}
```

```tsx showLineNumbers {4-6}
// 33% of the carousel width.
<Carousel>
  <CarouselContent>
    <CarouselItem className="basis-1/3">...</CarouselItem>
    <CarouselItem className="basis-1/3">...</CarouselItem>
    <CarouselItem className="basis-1/3">...</CarouselItem>
  </CarouselContent>
</Carousel>
```

```tsx showLineNumbers {4-6}
// 50% on small screens and 33% on larger screens.
<Carousel>
  <CarouselContent>
    <CarouselItem className="md:basis-1/2 lg:basis-1/3">...</CarouselItem>
    <CarouselItem className="md:basis-1/2 lg:basis-1/3">...</CarouselItem>
    <CarouselItem className="md:basis-1/2 lg:basis-1/3">...</CarouselItem>
  </CarouselContent>
</Carousel>
```

## Spacing

To set the spacing between the items, we use a `pl-[VALUE]` utility on the `<CarouselItem />` and a negative `-ml-[VALUE]` on the `<CarouselContent />`.

### Example: carousel-spacing

```tsx
// biome-ignore-all lint/suspicious/noArrayIndexKey: The upstream gallery uses fixed positional fixtures that never reorder.

import { Card, CardContent } from "@workspace/ui/components/card";
import {
  Carousel,
  CarouselContent,
  CarouselItem,
  CarouselNext,
  CarouselPrevious,
} from "@workspace/ui/components/carousel";

export default function CarouselSpacing() {
  return (
    <Carousel className="w-full max-w-[12rem] sm:max-w-xs md:max-w-sm">
      <CarouselContent className="-ml-1">
        {Array.from({ length: 5 }).map((_, index) => (
          <CarouselItem key={index} className="basis-1/2 pl-1 lg:basis-1/3">
            <div className="p-1">
              <Card>
                <CardContent className="flex aspect-square items-center justify-center p-6">
                  <span className="font-semibold text-2xl">{index + 1}</span>
                </CardContent>
              </Card>
            </div>
          </CarouselItem>
        ))}
      </CarouselContent>
      <CarouselPrevious />
      <CarouselNext />
    </Carousel>
  );
}
```

```tsx showLineNumbers /-ml-4/ /pl-4/
<Carousel>
  <CarouselContent className="-ml-4">
    <CarouselItem className="pl-4">...</CarouselItem>
    <CarouselItem className="pl-4">...</CarouselItem>
    <CarouselItem className="pl-4">...</CarouselItem>
  </CarouselContent>
</Carousel>
```

```tsx showLineNumbers /-ml-2/ /pl-2/ /md:-ml-4/ /md:pl-4/
<Carousel>
  <CarouselContent className="-ml-2 md:-ml-4">
    <CarouselItem className="pl-2 md:pl-4">...</CarouselItem>
    <CarouselItem className="pl-2 md:pl-4">...</CarouselItem>
    <CarouselItem className="pl-2 md:pl-4">...</CarouselItem>
  </CarouselContent>
</Carousel>
```

## Orientation

Use the `orientation` prop to set the orientation of the carousel.

### Example: carousel-orientation

```tsx
// biome-ignore-all lint/suspicious/noArrayIndexKey: The upstream gallery uses fixed positional fixtures that never reorder.

import { Card, CardContent } from "@workspace/ui/components/card";
import {
  Carousel,
  CarouselContent,
  CarouselItem,
  CarouselNext,
  CarouselPrevious,
} from "@workspace/ui/components/carousel";

export default function CarouselOrientation() {
  return (
    <Carousel
      opts={{
        align: "start",
      }}
      orientation="vertical"
      className="w-full max-w-xs"
    >
      <CarouselContent className="-mt-1 h-[270px]">
        {Array.from({ length: 5 }).map((_, index) => (
          <CarouselItem key={index} className="basis-1/2 pt-1">
            <div className="p-1">
              <Card>
                <CardContent className="flex items-center justify-center p-6">
                  <span className="font-semibold text-3xl">{index + 1}</span>
                </CardContent>
              </Card>
            </div>
          </CarouselItem>
        ))}
      </CarouselContent>
      <CarouselPrevious />
      <CarouselNext />
    </Carousel>
  );
}
```

```tsx showLineNumbers /vertical | horizontal/
<Carousel orientation="vertical | horizontal">
  <CarouselContent>
    <CarouselItem>...</CarouselItem>
    <CarouselItem>...</CarouselItem>
    <CarouselItem>...</CarouselItem>
  </CarouselContent>
</Carousel>
```

## Options

You can pass options to the carousel using the `opts` prop. See the [Embla Carousel docs](https://www.embla-carousel.com/api/options/) for more information.

```tsx showLineNumbers {2-5}
<Carousel
  opts={{
    align: "start",
    loop: true,
  }}
>
  <CarouselContent>
    <CarouselItem>...</CarouselItem>
    <CarouselItem>...</CarouselItem>
    <CarouselItem>...</CarouselItem>
  </CarouselContent>
</Carousel>
```

## API

Use a state and the `setApi` prop to get an instance of the carousel API.

### Example: carousel-api

```tsx
// biome-ignore-all lint/suspicious/noArrayIndexKey: The upstream gallery uses fixed positional fixtures that never reorder.

"use client";

import { Card, CardContent } from "@workspace/ui/components/card";
import {
  Carousel,
  type CarouselApi,
  CarouselContent,
  CarouselItem,
  CarouselNext,
  CarouselPrevious,
} from "@workspace/ui/components/carousel";
import * as React from "react";

export default function CarouselDApiDemo() {
  const [api, setApi] = React.useState<CarouselApi>();
  const [current, setCurrent] = React.useState(0);
  const [count, setCount] = React.useState(0);

  React.useEffect(() => {
    if (!api) {
      return;
    }

    setCount(api.scrollSnapList().length);
    setCurrent(api.selectedScrollSnap() + 1);

    api.on("select", () => {
      setCurrent(api.selectedScrollSnap() + 1);
    });
  }, [api]);

  return (
    <div className="mx-auto max-w-[10rem] sm:max-w-xs">
      <Carousel setApi={setApi} className="w-full max-w-xs">
        <CarouselContent>
          {Array.from({ length: 5 }).map((_, index) => (
            <CarouselItem key={index}>
              <Card className="m-px">
                <CardContent className="flex aspect-square items-center justify-center p-6">
                  <span className="font-semibold text-4xl">{index + 1}</span>
                </CardContent>
              </Card>
            </CarouselItem>
          ))}
        </CarouselContent>
        <CarouselPrevious />
        <CarouselNext />
      </Carousel>
      <div className="py-2 text-center text-muted-foreground text-sm">
        Slide {current} of {count}
      </div>
    </div>
  );
}
```

```tsx showLineNumbers {1,4,22}
import { type CarouselApi } from "@workspace/ui/components/carousel"

export function Example() {
  const [api, setApi] = React.useState<CarouselApi>()
  const [current, setCurrent] = React.useState(0)
  const [count, setCount] = React.useState(0)

  React.useEffect(() => {
    if (!api) {
      return
    }

    setCount(api.scrollSnapList().length)
    setCurrent(api.selectedScrollSnap() + 1)

    api.on("select", () => {
      setCurrent(api.selectedScrollSnap() + 1)
    })
  }, [api])

  return (
    <Carousel setApi={setApi}>
      <CarouselContent>
        <CarouselItem>...</CarouselItem>
        <CarouselItem>...</CarouselItem>
        <CarouselItem>...</CarouselItem>
      </CarouselContent>
    </Carousel>
  )
}
```

## Events

You can listen to events using the api instance from `setApi`.

```tsx showLineNumbers {1,4-14,16}
import { type CarouselApi } from "@workspace/ui/components/carousel"

export function Example() {
  const [api, setApi] = React.useState<CarouselApi>()

  React.useEffect(() => {
    if (!api) {
      return
    }

    api.on("select", () => {
      // Do something on select.
    })
  }, [api])

  return (
    <Carousel setApi={setApi}>
      <CarouselContent>
        <CarouselItem>...</CarouselItem>
        <CarouselItem>...</CarouselItem>
        <CarouselItem>...</CarouselItem>
      </CarouselContent>
    </Carousel>
  )
}
```

See the [Embla Carousel docs](https://www.embla-carousel.com/api/events/) for more information on using events.

## Plugins

You can use the `plugins` prop to add plugins to the carousel.

```ts showLineNumbers {1,6-10}
import Autoplay from "embla-carousel-autoplay"

export function Example() {
  return (
    <Carousel
      plugins={[
        Autoplay({
          delay: 2000,
        }),
      ]}
    >
      // ...
    </Carousel>
  )
}
```

### Example: carousel-plugin

```tsx
// biome-ignore-all lint/suspicious/noArrayIndexKey: The upstream gallery uses fixed positional fixtures that never reorder.

"use client";

import { Card, CardContent } from "@workspace/ui/components/card";
import {
  Carousel,
  CarouselContent,
  CarouselItem,
  CarouselNext,
  CarouselPrevious,
} from "@workspace/ui/components/carousel";
import Autoplay from "embla-carousel-autoplay";
import * as React from "react";

export default function CarouselPlugin() {
  const plugin = React.useRef(
    Autoplay({ delay: 2000, stopOnInteraction: true }),
  );

  return (
    <Carousel
      plugins={[plugin.current]}
      className="w-full max-w-[10rem] sm:max-w-xs"
      onMouseEnter={plugin.current.stop}
      onMouseLeave={plugin.current.reset}
    >
      <CarouselContent>
        {Array.from({ length: 5 }).map((_, index) => (
          <CarouselItem key={index}>
            <div className="p-1">
              <Card>
                <CardContent className="flex aspect-square items-center justify-center p-6">
                  <span className="font-semibold text-4xl">{index + 1}</span>
                </CardContent>
              </Card>
            </div>
          </CarouselItem>
        ))}
      </CarouselContent>
      <CarouselPrevious />
      <CarouselNext />
    </Carousel>
  );
}
```

## RTL

To enable RTL support in shadcn/ui, see the [RTL configuration guide](https://ui.shadcn.com/docs/rtl).

### Example: carousel-rtl

```tsx
// biome-ignore-all lint/suspicious/noArrayIndexKey: The upstream gallery uses fixed positional fixtures that never reorder.

"use client";

import { Card, CardContent } from "@workspace/ui/components/card";
import {
  Carousel,
  CarouselContent,
  CarouselItem,
  CarouselNext,
  CarouselPrevious,
} from "@workspace/ui/components/carousel";
import { type Translations, useTranslation } from "./support";

const translations: Translations = {
  en: {
    dir: "ltr",
    values: {},
  },
  ar: {
    dir: "rtl",
    values: {},
  },
  he: {
    dir: "rtl",
    values: {},
  },
};

function toArabicNumerals(num: number): string {
  const arabicNumerals = ["٠", "١", "٢", "٣", "٤", "٥", "٦", "٧", "٨", "٩"];
  return num
    .toString()
    .split("")
    .map((digit) => arabicNumerals[parseInt(digit, 10)])
    .join("");
}

export function CarouselRtl() {
  const { dir, language } = useTranslation(translations, "ar");

  const formatNumber = (num: number): string => {
    if (language === "ar") {
      return toArabicNumerals(num);
    }
    return num.toString();
  };

  return (
    <Carousel
      dir={dir}
      className="w-full max-w-[12rem] sm:max-w-xs"
      opts={{
        direction: dir,
      }}
    >
      <CarouselContent>
        {Array.from({ length: 5 }).map((_, index) => (
          <CarouselItem key={index}>
            <div className="p-1">
              <Card>
                <CardContent className="flex aspect-square items-center justify-center p-6">
                  <span className="font-semibold text-4xl">
                    {formatNumber(index + 1)}
                  </span>
                </CardContent>
              </Card>
            </div>
          </CarouselItem>
        ))}
      </CarouselContent>
      <CarouselPrevious />
      <CarouselNext />
    </Carousel>
  );
}

export default CarouselRtl;
```

When localizing the carousel for RTL languages, you need to set the `direction` option in the `opts` prop to match the text direction. This ensures the carousel scrolls in the correct direction.

```tsx showLineNumbers {2-5}
<Carousel
  dir={dir}
  opts={{
    direction: dir,
  }}
>
  <CarouselContent>
    <CarouselItem>...</CarouselItem>
    <CarouselItem>...</CarouselItem>
    <CarouselItem>...</CarouselItem>
  </CarouselContent>
  <CarouselPrevious className="rtl:rotate-180" />
  <CarouselNext className="rtl:rotate-180" />
</Carousel>
```

The `direction` option accepts `"ltr"` or `"rtl"` and should match the `dir` prop value. You may also want to rotate the navigation buttons using the `rtl:rotate-180` class to ensure they point in the correct direction.

## API Reference

See the [Embla Carousel docs](https://www.embla-carousel.com/api/) for more information on props and plugins.

- [Documentation](https://www.embla-carousel.com/get-started/react)
- [API reference](https://www.embla-carousel.com/api)


---

# Chart

Beautiful charts. Built using Recharts. Copy and paste into your apps.

Page: https://sui.draco.dev/docs/components/chart

**Updated:** The `chart` component now uses Recharts v3. If you're upgrading existing chart code, see [Updating to Recharts v3](#updating-to-recharts-v3).

### Example: chart-demo

```tsx
"use client";

import {
  Card,
  CardContent,
  CardDescription,
  CardHeader,
  CardTitle,
} from "@workspace/ui/components/card";
import {
  type ChartConfig,
  ChartContainer,
  ChartTooltip,
  ChartTooltipContent,
} from "@workspace/ui/components/chart";
import * as React from "react";
import { Bar, BarChart, CartesianGrid, XAxis } from "recharts";

export const description = "An interactive bar chart";

const chartData = [
  { date: "2024-04-01", desktop: 222, mobile: 150 },
  { date: "2024-04-02", desktop: 97, mobile: 180 },
  { date: "2024-04-03", desktop: 167, mobile: 120 },
  { date: "2024-04-04", desktop: 242, mobile: 260 },
  { date: "2024-04-05", desktop: 373, mobile: 290 },
  { date: "2024-04-06", desktop: 301, mobile: 340 },
  { date: "2024-04-07", desktop: 245, mobile: 180 },
  { date: "2024-04-08", desktop: 409, mobile: 320 },
  { date: "2024-04-09", desktop: 59, mobile: 110 },
  { date: "2024-04-10", desktop: 261, mobile: 190 },
  { date: "2024-04-11", desktop: 327, mobile: 350 },
  { date: "2024-04-12", desktop: 292, mobile: 210 },
  { date: "2024-04-13", desktop: 342, mobile: 380 },
  { date: "2024-04-14", desktop: 137, mobile: 220 },
  { date: "2024-04-15", desktop: 120, mobile: 170 },
  { date: "2024-04-16", desktop: 138, mobile: 190 },
  { date: "2024-04-17", desktop: 446, mobile: 360 },
  { date: "2024-04-18", desktop: 364, mobile: 410 },
  { date: "2024-04-19", desktop: 243, mobile: 180 },
  { date: "2024-04-20", desktop: 89, mobile: 150 },
  { date: "2024-04-21", desktop: 137, mobile: 200 },
  { date: "2024-04-22", desktop: 224, mobile: 170 },
  { date: "2024-04-23", desktop: 138, mobile: 230 },
  { date: "2024-04-24", desktop: 387, mobile: 290 },
  { date: "2024-04-25", desktop: 215, mobile: 250 },
  { date: "2024-04-26", desktop: 75, mobile: 130 },
  { date: "2024-04-27", desktop: 383, mobile: 420 },
  { date: "2024-04-28", desktop: 122, mobile: 180 },
  { date: "2024-04-29", desktop: 315, mobile: 240 },
  { date: "2024-04-30", desktop: 454, mobile: 380 },
];

const chartConfig = {
  views: {
    label: "Page Views",
  },
  desktop: {
    label: "Desktop",
    color: "var(--chart-2)",
  },
  mobile: {
    label: "Mobile",
    color: "var(--chart-1)",
  },
} satisfies ChartConfig;

export function ChartDemo() {
  const [activeChart, setActiveChart] =
    React.useState<keyof typeof chartConfig>("desktop");

  const total = React.useMemo(
    () => ({
      desktop: chartData.reduce((acc, curr) => acc + curr.desktop, 0),
      mobile: chartData.reduce((acc, curr) => acc + curr.mobile, 0),
    }),
    [],
  );

  return (
    <Card className="py-0 pb-4">
      <CardHeader className="flex flex-col items-stretch border-b p-0! sm:flex-row">
        <div className="flex flex-1 flex-col justify-center gap-1 px-6 pt-4 pb-3 sm:py-0!">
          <CardTitle>Bar Chart - Interactive</CardTitle>
          <CardDescription>
            Showing total visitors for the last 3 months
          </CardDescription>
        </div>
        <div className="flex">
          {["desktop", "mobile"].map((key) => {
            const chart = key as keyof typeof chartConfig;
            return (
              <button
                type="button"
                key={chart}
                data-active={activeChart === chart}
                className="relative z-30 flex flex-1 flex-col justify-center gap-1 border-t px-6 py-4 text-left even:border-l data-[active=true]:bg-muted/50 sm:border-t-0 sm:border-l sm:px-8 sm:py-6"
                onClick={() => setActiveChart(chart)}
              >
                <span className="text-muted-foreground text-xs">
                  {chartConfig[chart].label}
                </span>
                <span className="font-bold text-lg leading-none sm:text-3xl">
                  {total[key as keyof typeof total].toLocaleString()}
                </span>
              </button>
            );
          })}
        </div>
      </CardHeader>
      <CardContent className="px-2 sm:p-6">
        <ChartContainer
          config={chartConfig}
          className="aspect-auto h-[250px] w-full"
        >
          <BarChart
            accessibilityLayer
            data={chartData}
            margin={{
              left: 12,
              right: 12,
            }}
          >
            <CartesianGrid vertical={false} />
            <XAxis
              dataKey="date"
              tickLine={false}
              axisLine={false}
              tickMargin={8}
              minTickGap={32}
              tickFormatter={(value) => {
                const date = new Date(value);
                return date.toLocaleDateString("en-US", {
                  month: "short",
                  day: "numeric",
                });
              }}
            />
            <ChartTooltip
              content={
                <ChartTooltipContent
                  className="w-[150px]"
                  nameKey="views"
                  labelFormatter={(value) => {
                    return new Date(value).toLocaleDateString("en-US", {
                      month: "short",
                      day: "numeric",
                      year: "numeric",
                    });
                  }}
                />
              }
            />
            <Bar dataKey={activeChart} fill={`var(--color-${activeChart})`} />
          </BarChart>
        </ChartContainer>
      </CardContent>
    </Card>
  );
}

export default ChartDemo;
```

Introducing **Charts**. A collection of chart components that you can copy and paste into your apps.

Charts are designed to look great out of the box. They work well with the other components and are fully customizable to fit your project.

[Browse the Charts Library](https://ui.shadcn.com/charts).

## Component

We use [Recharts](https://recharts.org/) under the hood.

We designed the `chart` component with composition in mind. **You build your charts using Recharts components and only bring in custom components, such as `ChartTooltip`, when and where you need it**.

```tsx showLineNumbers /ChartContainer/ /ChartTooltipContent/
import { Bar, BarChart } from "recharts"

import { ChartContainer, ChartTooltipContent } from "@workspace/ui/components/chart"

export function MyChart() {
  return (
    <ChartContainer>
      <BarChart data={data}>
        <Bar dataKey="value" />
        <ChartTooltip content={<ChartTooltipContent />} />
      </BarChart>
    </ChartContainer>
  )
}
```

We do not wrap Recharts. This means you're not locked into an abstraction. When a new Recharts version is released, you can follow the official upgrade path to upgrade your charts.

**The components are yours**.

## Updating to Recharts v3

If you're updating older chart code to Recharts v3:

- Use `var(--chart-1)` instead of `hsl(var(--chart-1))` when you reference chart tokens from your CSS variables.
- Use `ChartTooltip.defaultIndex` for initial tooltip state only. Keep persistent active shapes in your own chart state.
- Remove `layout` from `<Bar>` when the parent `<BarChart>` already defines it.
- Keep a height, `min-h-*`, or `aspect-*` on `ChartContainer` so `ResponsiveContainer` can measure on first render.

## Installation

```bash
bunx --bun shadcn@latest add @sui/chart
```

Install with the shadcn CLI or use the shared `@workspace/ui` package. Follow the [installation guide](/docs/installation) to configure the registry, load styles, and choose import aliases.

## Your First Chart

Let's build your first chart. We'll build a bar chart, add a grid, axis, tooltip and legend.

### Start by defining your data

The following data represents the number of desktop and mobile users for each month.

**Note:** Your data can be in any shape. You are not limited to the shape of the data below. Use the `dataKey` prop to map your data to the chart.

```tsx title="components/example-chart.tsx" showLineNumbers
const chartData = [
  { 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 },
]
```

### Define your chart config

The chart config holds configuration for the chart. This is where you place human-readable strings, such as labels, icons and color tokens for theming.

```tsx title="components/example-chart.tsx" showLineNumbers
import { type ChartConfig } from "@workspace/ui/components/chart"

const chartConfig = {
  desktop: {
    label: "Desktop",
    color: "#2563eb",
  },
  mobile: {
    label: "Mobile",
    color: "#60a5fa",
  },
} satisfies ChartConfig
```

### Build your chart

You can now build your chart using Recharts components.

**Important:** Remember to set a `min-h-[VALUE]` on the `ChartContainer` component. This is required for the chart to be responsive.

### Example: chart-example

```tsx
"use client";

import {
  type ChartConfig,
  ChartContainer,
} from "@workspace/ui/components/chart";
import { Bar, BarChart } from "recharts";

const chartData = [
  { 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 chartConfig = {
  desktop: {
    label: "Desktop",
    color: "#2563eb",
  },
  mobile: {
    label: "Mobile",
    color: "#60a5fa",
  },
} satisfies ChartConfig;

export function ChartExample() {
  return (
    <ChartContainer config={chartConfig} className="min-h-[200px] w-full">
      <BarChart accessibilityLayer data={chartData}>
        <Bar dataKey="desktop" fill="var(--color-desktop)" radius={4} />
        <Bar dataKey="mobile" fill="var(--color-mobile)" radius={4} />
      </BarChart>
    </ChartContainer>
  );
}

export default ChartExample;
```

### Add a Grid

Let's add a grid to the chart.

### Import the `CartesianGrid` component.

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

### Add the `CartesianGrid` component to your chart.

```tsx showLineNumbers {3}
<ChartContainer config={chartConfig} className="min-h-[200px] w-full">
  <BarChart accessibilityLayer data={chartData}>
    <CartesianGrid vertical={false} />
    <Bar dataKey="desktop" fill="var(--color-desktop)" radius={4} />
    <Bar dataKey="mobile" fill="var(--color-mobile)" radius={4} />
  </BarChart>
</ChartContainer>
```

### Example: chart-example-grid

```tsx
"use client";

import {
  type ChartConfig,
  ChartContainer,
} from "@workspace/ui/components/chart";
import { Bar, BarChart, CartesianGrid } from "recharts";

const chartData = [
  { 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 chartConfig = {
  desktop: {
    label: "Desktop",
    color: "#2563eb",
  },
  mobile: {
    label: "Mobile",
    color: "#60a5fa",
  },
} satisfies ChartConfig;

export function ChartBarDemoGrid() {
  return (
    <ChartContainer config={chartConfig} className="min-h-[200px] w-full">
      <BarChart accessibilityLayer data={chartData}>
        <CartesianGrid vertical={false} />
        <Bar dataKey="desktop" fill="var(--color-desktop)" radius={4} />
        <Bar dataKey="mobile" fill="var(--color-mobile)" radius={4} />
      </BarChart>
    </ChartContainer>
  );
}

export default ChartBarDemoGrid;
```

### Add an Axis

To add an x-axis to the chart, we'll use the `XAxis` component.

### Import the `XAxis` component.

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

### Add the `XAxis` component to your chart.

```tsx showLineNumbers {4-10}
<ChartContainer config={chartConfig} className="h-[200px] w-full">
  <BarChart accessibilityLayer data={chartData}>
    <CartesianGrid vertical={false} />
    <XAxis
      dataKey="month"
      tickLine={false}
      tickMargin={10}
      axisLine={false}
      tickFormatter={(value) => value.slice(0, 3)}
    />
    <Bar dataKey="desktop" fill="var(--color-desktop)" radius={4} />
    <Bar dataKey="mobile" fill="var(--color-mobile)" radius={4} />
  </BarChart>
</ChartContainer>
```

### Example: chart-example-axis

```tsx
"use client";

import {
  type ChartConfig,
  ChartContainer,
} from "@workspace/ui/components/chart";
import { Bar, BarChart, CartesianGrid, XAxis } from "recharts";

const chartData = [
  { 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 chartConfig = {
  desktop: {
    label: "Desktop",
    color: "#2563eb",
  },
  mobile: {
    label: "Mobile",
    color: "#60a5fa",
  },
} satisfies ChartConfig;

export function ChartBarDemoAxis() {
  return (
    <ChartContainer config={chartConfig} className="min-h-[200px] w-full">
      <BarChart accessibilityLayer data={chartData}>
        <CartesianGrid vertical={false} />
        <XAxis
          dataKey="month"
          tickLine={false}
          tickMargin={10}
          axisLine={false}
          tickFormatter={(value) => value.slice(0, 3)}
        />
        <Bar dataKey="desktop" fill="var(--color-desktop)" radius={4} />
        <Bar dataKey="mobile" fill="var(--color-mobile)" radius={4} />
      </BarChart>
    </ChartContainer>
  );
}

export default ChartBarDemoAxis;
```

### Add Tooltip

So far we've only used components from Recharts. They look great out of the box thanks to some customization in the `chart` component.

To add a tooltip, we'll use the custom `ChartTooltip` and `ChartTooltipContent` components from `chart`.

### Import the `ChartTooltip` and `ChartTooltipContent` components.

```tsx
import { ChartTooltip, ChartTooltipContent } from "@workspace/ui/components/chart"
```

### Add the components to your chart.

```tsx showLineNumbers {11}
<ChartContainer config={chartConfig} className="h-[200px] w-full">
  <BarChart accessibilityLayer data={chartData}>
    <CartesianGrid vertical={false} />
    <XAxis
      dataKey="month"
      tickLine={false}
      tickMargin={10}
      axisLine={false}
      tickFormatter={(value) => value.slice(0, 3)}
    />
    <ChartTooltip content={<ChartTooltipContent />} />
    <Bar dataKey="desktop" fill="var(--color-desktop)" radius={4} />
    <Bar dataKey="mobile" fill="var(--color-mobile)" radius={4} />
  </BarChart>
</ChartContainer>
```

### Example: chart-example-tooltip

```tsx
"use client";

import {
  type ChartConfig,
  ChartContainer,
  ChartTooltip,
  ChartTooltipContent,
} from "@workspace/ui/components/chart";
import { Bar, BarChart, CartesianGrid, XAxis } from "recharts";

const chartData = [
  { 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 chartConfig = {
  desktop: {
    label: "Desktop",
    color: "#2563eb",
  },
  mobile: {
    label: "Mobile",
    color: "#60a5fa",
  },
} satisfies ChartConfig;

export function ChartBarDemoTooltip() {
  return (
    <ChartContainer config={chartConfig} className="min-h-[200px] w-full">
      <BarChart accessibilityLayer data={chartData}>
        <CartesianGrid vertical={false} />
        <XAxis
          dataKey="month"
          tickLine={false}
          tickMargin={10}
          axisLine={false}
          tickFormatter={(value) => value.slice(0, 3)}
        />
        <ChartTooltip content={<ChartTooltipContent />} />
        <Bar dataKey="desktop" fill="var(--color-desktop)" radius={4} />
        <Bar dataKey="mobile" fill="var(--color-mobile)" radius={4} />
      </BarChart>
    </ChartContainer>
  );
}

export default ChartBarDemoTooltip;
```

Hover to see the tooltips. Easy, right? Two components, and we've got a beautiful tooltip.

### Add Legend

We'll do the same for the legend. We'll use the `ChartLegend` and `ChartLegendContent` components from `chart`.

### Import the `ChartLegend` and `ChartLegendContent` components.

```tsx
import { ChartLegend, ChartLegendContent } from "@workspace/ui/components/chart"
```

### Add the components to your chart.

```tsx showLineNumbers {12}
<ChartContainer config={chartConfig} className="h-[200px] w-full">
  <BarChart accessibilityLayer data={chartData}>
    <CartesianGrid vertical={false} />
    <XAxis
      dataKey="month"
      tickLine={false}
      tickMargin={10}
      axisLine={false}
      tickFormatter={(value) => value.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>
```

### Example: chart-example-legend

```tsx
"use client";

import {
  type ChartConfig,
  ChartContainer,
  ChartLegend,
  ChartLegendContent,
  ChartTooltip,
  ChartTooltipContent,
} from "@workspace/ui/components/chart";
import { Bar, BarChart, CartesianGrid, XAxis } from "recharts";

const chartData = [
  { 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 chartConfig = {
  desktop: {
    label: "Desktop",
    color: "#2563eb",
  },
  mobile: {
    label: "Mobile",
    color: "#60a5fa",
  },
} satisfies ChartConfig;

export function ChartBarDemoLegend() {
  return (
    <ChartContainer config={chartConfig} className="min-h-[200px] w-full">
      <BarChart accessibilityLayer data={chartData}>
        <CartesianGrid vertical={false} />
        <XAxis
          dataKey="month"
          tickLine={false}
          tickMargin={10}
          axisLine={false}
          tickFormatter={(value) => value.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>
  );
}

export default ChartBarDemoLegend;
```

Done. You've built your first chart! What's next?

- [Themes and Colors](/docs/components/chart#theming)
- [Tooltip](/docs/components/chart#tooltip)
- [Legend](/docs/components/chart#legend)

## Chart Config

The chart config is where you define the labels, icons and colors for a chart.

It is intentionally decoupled from chart data.

This allows you to share config and color tokens between charts. It can also work independently for cases where your data or color tokens live remotely or in a different format.

```tsx showLineNumbers /ChartConfig/
import { Monitor } from "lucide-react"

import { type ChartConfig } from "@workspace/ui/components/chart"

const chartConfig = {
  desktop: {
    label: "Desktop",
    icon: Monitor,
    // A color like 'hsl(220, 98%, 61%)' or 'var(--color-name)'
    color: "#2563eb",
    // OR a theme object with 'light' and 'dark' keys
    theme: {
      light: "#2563eb",
      dark: "#dc2626",
    },
  },
} satisfies ChartConfig
```

## Theming

Charts have built-in support for theming. You can use css variables (recommended) or color values in any color format, such as hex, hsl or oklch.

### CSS Variables

### Define your colors in your css file

```css title="app/globals.css" showLineNumbers
@layer base {
  :root {
    --chart-1: oklch(0.646 0.222 41.116);
    --chart-2: oklch(0.6 0.118 184.704);
  }

  .dark {
    --chart-1: oklch(0.488 0.243 264.376);
    --chart-2: oklch(0.696 0.17 162.48);
  }
}
```

### Add the color to your `chartConfig`

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

### hex, hsl or oklch

You can also define your colors directly in the chart config. Use the color format you prefer.

```tsx title="components/example-chart.tsx" showLineNumbers
const chartConfig = {
  desktop: {
    label: "Desktop",
    color: "#2563eb",
  },
  mobile: {
    label: "Mobile",
    color: "hsl(220, 98%, 61%)",
  },
  tablet: {
    label: "Tablet",
    color: "oklch(0.5 0.2 240)",
  },
  laptop: {
    label: "Laptop",
    color: "var(--chart-2)",
  },
} satisfies ChartConfig
```

### Using Colors

To use the theme colors in your chart, reference the colors using the format `var(--color-KEY)`.

#### Components

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

#### Chart Data

```tsx title="components/example-chart.tsx" showLineNumbers
const chartData = [
  { browser: "chrome", visitors: 275, fill: "var(--color-chrome)" },
  { browser: "safari", visitors: 200, fill: "var(--color-safari)" },
]
```

#### Tailwind

```tsx title="components/example-chart.tsx"
<LabelList className="fill-(--color-desktop)" />
```

## Tooltip

A chart tooltip contains a label, name, indicator and value. You can use a combination of these to customize your tooltip.

### Example: chart-tooltip

```tsx
"use client";

import { cn } from "cn";
import type * as React from "react";
import { useId as usePreviewId } from "react";

export function ChartTooltipDemo() {
  const previewId = usePreviewId();

  return (
    <div className="grid aspect-video w-full max-w-md justify-center text-foreground md:grid-cols-2 [&>div]:relative [&>div]:flex [&>div]:h-[137px] [&>div]:w-[224px] [&>div]:items-center [&>div]:justify-center [&>div]:p-4">
      <div>
        <div className="absolute top-[45px] left-[-35px] z-10 font-medium text-sm">
          Label
        </div>
        <svg
          aria-hidden="true"
          xmlns="http://www.w3.org/2000/svg"
          viewBox="0 0 193 40"
          width="50"
          height="12"
          fill="none"
          className="absolute top-[50px] left-[5px] z-10"
        >
          <g clipPath="url(#a)">
            <path
              fill="currentColor"
              d="M173.928 21.13C115.811 44.938 58.751 45.773 0 26.141c4.227-4.386 7.82-2.715 10.567-1.88 21.133 5.64 42.9 6.266 64.457 7.101 31.066 1.253 60.441-5.848 89.183-17.335 1.268-.418 2.325-1.253 4.861-2.924-14.582-2.924-29.165 2.089-41.845-3.76.212-.835.212-1.879.423-2.714 9.51-.627 19.231-1.253 28.742-2.089 9.51-.835 18.808-1.88 28.318-2.506 6.974-.418 9.933 2.924 7.397 9.19-3.17 8.145-7.608 15.664-11.623 23.391-.423.836-1.057 1.88-1.902 2.298-2.325.835-4.65 1.044-7.186 1.67-.422-2.088-1.479-4.386-1.268-6.265.423-2.506 1.902-4.595 3.804-9.19Z"
            />
          </g>
          <defs>
            <clipPath id={`${previewId}-a`}>
              <path fill="currentColor" d="M0 0h193v40H0z" />
            </clipPath>
          </defs>
        </svg>
        <TooltipDemo
          label="Page Views"
          payload={[
            { name: "Desktop", value: 186, fill: "var(--chart-1)" },
            { name: "Mobile", value: 80, fill: "var(--chart-2)" },
          ]}
          className="w-[8rem]"
        />
      </div>
      <div className="items-end">
        <div className="absolute top-[0px] left-[122px] z-10 font-medium text-sm">
          Name
        </div>
        <svg
          aria-hidden="true"
          xmlns="http://www.w3.org/2000/svg"
          width="35"
          height="42"
          fill="none"
          viewBox="0 0 122 148"
          className="absolute top-[10px] left-[85px] z-10 -scale-x-100"
        >
          <g clipPath="url(#ab)">
            <path
              fill="currentColor"
              d="M0 2.65c6.15-4.024 12.299-2.753 17.812-.847a115.56 115.56 0 0 1 21.84 10.59C70.4 32.727 88.849 61.744 96.483 97.54c1.908 9.108 2.544 18.639 3.817 29.017 8.481-4.871 12.934-14.402 21.416-19.909 1.061 4.236-1.06 6.989-2.756 9.319-6.998 9.531-14.207 19.062-21.63 28.382-3.604 4.448-6.36 4.871-10.177 1.059-8.058-7.837-12.935-17.368-14.42-28.382 0-.424.636-1.059 1.485-2.118 9.118 2.33 6.997 13.979 14.843 18.215 3.393-14.614.848-28.593-2.969-42.149-4.029-14.19-9.33-27.746-17.812-39.82-8.27-11.86-18.66-21.392-30.11-30.287C26.93 11.758 14.207 6.039 0 2.65Z"
            />
          </g>
          <defs>
            <clipPath id={`${previewId}-ab`}>
              <path fill="currentColor" d="M0 0h122v148H0z" />
            </clipPath>
          </defs>
        </svg>
        <TooltipDemo
          label="Browser"
          hideLabel
          payload={[
            { name: "Chrome", value: 1286, fill: "var(--chart-3)" },
            { name: "Firefox", value: 1000, fill: "var(--chart-4)" },
          ]}
          indicator="dashed"
          className="w-[8rem]"
        />
      </div>
      <div className="hidden! md:flex!">
        <TooltipDemo
          label="Page Views"
          payload={[{ name: "Desktop", value: 12486, fill: "var(--chart-3)" }]}
          className="w-[9rem]"
          indicator="line"
        />
      </div>
      <div className="items-start! justify-start!">
        <div className="absolute top-[60px] left-[50px] z-10 font-medium text-sm">
          Indicator
        </div>
        <TooltipDemo
          label="Browser"
          hideLabel
          payload={[{ name: "Chrome", value: 1286, fill: "var(--chart-1)" }]}
          indicator="dot"
          className="w-[8rem]"
        />
        <svg
          aria-hidden="true"
          xmlns="http://www.w3.org/2000/svg"
          width="15"
          height="34"
          fill="none"
          viewBox="0 0 75 175"
          className="absolute top-[38px] left-[30px] z-10 rotate-[-40deg]"
        >
          <g clipPath="url(#abc)">
            <path
              fill="currentColor"
              d="M20.187 175c-4.439-2.109-7.186-2.531-8.032-4.008-3.17-5.484-6.763-10.968-8.454-17.084-5.073-16.242-4.439-32.694-1.057-49.146 5.707-28.053 18.388-52.942 34.24-76.565 1.692-2.531 3.171-5.063 4.862-7.805 0-.21-.211-.632-.634-1.265-4.65 1.265-9.511 2.53-14.161 3.585-2.537.422-5.496.422-8.032-.421-1.48-.422-3.593-2.742-3.593-4.219 0-1.898 1.48-4.218 2.747-5.906 1.057-1.054 2.96-1.265 4.65-1.687C35.406 7.315 48.088 3.729 60.98.776c10.99-2.53 14.584 1.055 13.95 11.812-.634 11.18-.846 22.358-1.268 33.326-.212 3.375-.846 6.96-1.268 10.757-8.878-4.007-8.878-4.007-12.048-38.177C47.03 33.259 38.153 49.289 29.91 65.741 21.667 82.193 16.17 99.49 13.212 117.84c-2.959 18.984.634 36.912 6.975 57.161Z"
            />
          </g>
          <defs>
            <clipPath id={`${previewId}-abc`}>
              <path fill="currentColor" d="M0 0h75v175H0z" />
            </clipPath>
          </defs>
        </svg>
      </div>
    </div>
  );
}

function TooltipDemo({
  indicator = "dot",
  label,
  payload,
  hideLabel,
  hideIndicator,
  className,
}: {
  label: string;
  hideLabel?: boolean;
  hideIndicator?: boolean;
  indicator?: "line" | "dot" | "dashed";
  payload: {
    name: string;
    value: number;
    fill: string;
  }[];
  nameKey?: string;
  labelKey?: string;
} & React.ComponentProps<"div">) {
  const tooltipLabel = hideLabel ? null : (
    <div className="font-medium">{label}</div>
  );

  if (!payload?.length) {
    return null;
  }

  const nestLabel = payload.length === 1 && indicator !== "dot";

  return (
    <div
      className={cn(
        "grid min-w-[8rem] items-start gap-1.5 rounded-lg border border-border/50 bg-background px-2.5 py-1.5 text-xs shadow-xl transition-all ease-in-out hover:-translate-y-0.5",
        className,
      )}
    >
      {!nestLabel ? tooltipLabel : null}
      <div className="grid gap-1.5">
        {payload.map((item) => {
          const indicatorColor = item.fill;

          return (
            <div
              key={item.name}
              className={cn(
                "flex w-full items-stretch gap-2 [&>svg]:h-2.5 [&>svg]:w-2.5 [&>svg]:text-muted-foreground",
                indicator === "dot" && "items-center",
              )}
            >
              {!hideIndicator && (
                <div
                  className={cn(
                    "shrink-0 rounded-[2px] border-(--color-border) bg-(--color-bg)",
                    {
                      "h-2.5 w-2.5": indicator === "dot",
                      "w-1": indicator === "line",
                      "w-0 border-[1.5px] border-dashed bg-transparent":
                        indicator === "dashed",
                      "my-0.5": nestLabel && indicator === "dashed",
                    },
                  )}
                  style={
                    {
                      "--color-bg": indicatorColor,
                      "--color-border": indicatorColor,
                    } as React.CSSProperties
                  }
                />
              )}
              <div
                className={cn(
                  "flex flex-1 justify-between leading-none",
                  nestLabel ? "items-end" : "items-center",
                )}
              >
                <div className="grid gap-1.5">
                  {nestLabel ? tooltipLabel : null}
                  <span className="text-muted-foreground">{item.name}</span>
                </div>
                <span className="font-medium font-mono text-foreground tabular-nums">
                  {item.value.toLocaleString()}
                </span>
              </div>
            </div>
          );
        })}
      </div>
    </div>
  );
}

export default ChartTooltipDemo;
```

You can turn on/off any of these using the `hideLabel`, `hideIndicator` props and customize the indicator style using the `indicator` prop.

Use `labelKey` and `nameKey` to use a custom key for the tooltip label and name.

Chart comes with the `<ChartTooltip>` and `<ChartTooltipContent>` components. You can use these two components to add custom tooltips to your chart.

```tsx title="components/example-chart.tsx"
import { ChartTooltip, ChartTooltipContent } from "@workspace/ui/components/chart"
```

```tsx title="components/example-chart.tsx"
<ChartTooltip content={<ChartTooltipContent />} />
```

### Props

Use the following props to customize the tooltip.

| Prop            | Type                     | Description                                  |
| :-------------- | :----------------------- | :------------------------------------------- |
| `labelKey`      | string                   | The config or data key to use for the label. |
| `nameKey`       | string                   | The config or data key to use for the name.  |
| `indicator`     | `dot` `line` or `dashed` | The indicator style for the tooltip.         |
| `hideLabel`     | boolean                  | Whether to hide the label.                   |
| `hideIndicator` | boolean                  | Whether to hide the indicator.               |

### Colors

Colors are automatically referenced from the chart config.

### Custom

To use a custom key for tooltip label and names, use the `labelKey` and `nameKey` props.

```tsx showLineNumbers /browser/
const chartData = [
  { browser: "chrome", visitors: 187, fill: "var(--color-chrome)" },
  { browser: "safari", visitors: 200, fill: "var(--color-safari)" },
]

const chartConfig = {
  visitors: {
    label: "Total Visitors",
  },
  chrome: {
    label: "Chrome",
    color: "var(--chart-1)",
  },
  safari: {
    label: "Safari",
    color: "var(--chart-2)",
  },
} satisfies ChartConfig
```

```tsx title="components/example-chart.tsx"
<ChartTooltip
  content={<ChartTooltipContent labelKey="visitors" nameKey="browser" />}
/>
```

This will use `Total Visitors` for label and `Chrome` and `Safari` for the tooltip names.

## Legend

You can use the custom `<ChartLegend>` and `<ChartLegendContent>` components to add a legend to your chart.

```tsx title="components/example-chart.tsx"
import { ChartLegend, ChartLegendContent } from "@workspace/ui/components/chart"
```

```tsx title="components/example-chart.tsx"
<ChartLegend content={<ChartLegendContent />} />
```

### Colors

Colors are automatically referenced from the chart config.

### Custom

To use a custom key for legend names, use the `nameKey` prop.

```tsx showLineNumbers /browser/
const chartData = [
  { browser: "chrome", visitors: 187, fill: "var(--color-chrome)" },
  { browser: "safari", visitors: 200, fill: "var(--color-safari)" },
]

const chartConfig = {
  chrome: {
    label: "Chrome",
    color: "var(--chart-1)",
  },
  safari: {
    label: "Safari",
    color: "var(--chart-2)",
  },
} satisfies ChartConfig
```

```tsx title="components/example-chart.tsx"
<ChartLegend content={<ChartLegendContent nameKey="browser" />} />
```

This will use `Chrome` and `Safari` for the legend names.

## Accessibility

You can turn on the `accessibilityLayer` prop to add an accessible layer to your chart.

This prop adds keyboard access and screen reader support to your charts.

```tsx title="components/example-chart.tsx"
<LineChart accessibilityLayer />
```

## RTL

To enable RTL support in shadcn/ui, see the [RTL configuration guide](https://ui.shadcn.com/docs/rtl).

### Example: chart-rtl

```tsx
"use client";

import {
  type ChartConfig,
  ChartContainer,
  ChartLegend,
  ChartLegendContent,
  ChartTooltip,
  ChartTooltipContent,
} from "@workspace/ui/components/chart";
import { Bar, BarChart, CartesianGrid, XAxis } from "recharts";
import { type Translations, useTranslation } from "./support";

const translations: Translations = {
  en: {
    dir: "ltr",
    values: {
      january: "January",
      february: "February",
      march: "March",
      april: "April",
      may: "May",
      june: "June",
      desktop: "Desktop",
      mobile: "Mobile",
    },
  },
  ar: {
    dir: "rtl",
    values: {
      january: "يناير",
      february: "فبراير",
      march: "مارس",
      april: "أبريل",
      may: "مايو",
      june: "يونيو",
      desktop: "سطح المكتب",
      mobile: "الجوال",
    },
  },
  he: {
    dir: "rtl",
    values: {
      january: "ינואר",
      february: "פברואר",
      march: "מרץ",
      april: "אפריל",
      may: "מאי",
      june: "יוני",
      desktop: "מחשב",
      mobile: "נייד",
    },
  },
};

const chartData = [
  { 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 },
];

export function ChartRtl() {
  const { t, dir } = useTranslation(translations, "ar");

  const chartConfig = {
    desktop: {
      label: t.desktop,
      color: "var(--chart-2)",
    },
    mobile: {
      label: t.mobile,
      color: "var(--chart-1)",
    },
  } satisfies ChartConfig;

  return (
    <ChartContainer config={chartConfig} className="min-h-[200px] w-full">
      <BarChart accessibilityLayer data={chartData}>
        <CartesianGrid
          vertical={false}
          orientation={dir === "rtl" ? "right" : "left"}
        />
        <XAxis
          dataKey="month"
          tickLine={false}
          tickMargin={10}
          axisLine={false}
          tickFormatter={(value) =>
            (t[value as keyof typeof t] as string).slice(0, 3)
          }
          reversed={dir === "rtl"}
        />
        <ChartTooltip
          content={
            <ChartTooltipContent
              labelFormatter={(value) => t[value as keyof typeof t] as string}
            />
          }
          labelClassName="w-32"
        />
        <ChartLegend content={<ChartLegendContent />} />
        <Bar dataKey="desktop" fill="var(--color-desktop)" radius={4} />
        <Bar dataKey="mobile" fill="var(--color-mobile)" radius={4} />
      </BarChart>
    </ChartContainer>
  );
}

export default ChartRtl;
```


---

# Checkbox

A control that allows the user to toggle between checked and not checked.

Page: https://sui.draco.dev/docs/components/checkbox

### Example: checkbox-demo

```tsx
"use client";

import { Checkbox } from "@workspace/ui/components/checkbox";
import {
  Field,
  FieldContent,
  FieldDescription,
  FieldGroup,
  FieldLabel,
  FieldTitle,
} from "@workspace/ui/components/field";
import { Label } from "@workspace/ui/components/label";
import { useId as usePreviewId } from "react";

export default function CheckboxDemo() {
  const previewId = usePreviewId();

  return (
    <FieldGroup className="max-w-sm">
      <Field orientation="horizontal">
        <Checkbox id={`${previewId}-terms-checkbox`} name="terms-checkbox" />
        <Label htmlFor={`${previewId}-terms-checkbox`}>
          Accept terms and conditions
        </Label>
      </Field>
      <Field orientation="horizontal">
        <Checkbox
          id={`${previewId}-terms-checkbox-2`}
          name="terms-checkbox-2"
          defaultChecked
        />
        <FieldContent>
          <FieldLabel htmlFor={`${previewId}-terms-checkbox-2`}>
            Accept terms and conditions
          </FieldLabel>
          <FieldDescription>
            By clicking this checkbox, you agree to the terms.
          </FieldDescription>
        </FieldContent>
      </Field>
      <Field orientation="horizontal" data-disabled>
        <Checkbox
          id={`${previewId}-toggle-checkbox`}
          name="toggle-checkbox"
          disabled
        />
        <FieldLabel htmlFor={`${previewId}-toggle-checkbox`}>
          Enable notifications
        </FieldLabel>
      </Field>
      <FieldLabel>
        <Field orientation="horizontal">
          <Checkbox
            id={`${previewId}-toggle-checkbox-2`}
            name="toggle-checkbox-2"
          />
          <FieldContent>
            <FieldTitle>Enable notifications</FieldTitle>
            <FieldDescription>
              You can enable or disable notifications at any time.
            </FieldDescription>
          </FieldContent>
        </Field>
      </FieldLabel>
    </FieldGroup>
  );
}
```

## Installation

```bash
bunx --bun shadcn@latest add @sui/checkbox
```

Install with the shadcn CLI or use the shared `@workspace/ui` package. Follow the [installation guide](/docs/installation) to configure the registry, load styles, and choose import aliases.

## Usage

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

```tsx
<Checkbox />
```

## Checked State

Use `defaultChecked` for uncontrolled checkboxes, or `checked` and
`onCheckedChange` to control the state.

```tsx showLineNumbers
import * as React from "react"

export function Example() {
  const [checked, setChecked] = React.useState(false)

  return <Checkbox checked={checked} onCheckedChange={setChecked} />
}
```

## Invalid State

Set `aria-invalid` on the checkbox and `data-invalid` on the field wrapper to
show the invalid styles.

### Example: checkbox-invalid

```tsx
import { Checkbox } from "@workspace/ui/components/checkbox";
import { Field, FieldGroup, FieldLabel } from "@workspace/ui/components/field";
import { useId as usePreviewId } from "react";

export function CheckboxInvalid() {
  const previewId = usePreviewId();

  return (
    <FieldGroup className="mx-auto w-56">
      <Field orientation="horizontal" data-invalid>
        <Checkbox
          id={`${previewId}-terms-checkbox-invalid`}
          name="terms-checkbox-invalid"
          aria-invalid
        />
        <FieldLabel htmlFor={`${previewId}-terms-checkbox-invalid`}>
          Accept terms and conditions
        </FieldLabel>
      </Field>
    </FieldGroup>
  );
}

export default CheckboxInvalid;
```

## Basic

Pair the checkbox with `Field` and `FieldLabel` for proper layout and labeling.

### Example: checkbox-basic

```tsx
import { Checkbox } from "@workspace/ui/components/checkbox";
import { Field, FieldGroup, FieldLabel } from "@workspace/ui/components/field";
import { useId as usePreviewId } from "react";

export function CheckboxBasic() {
  const previewId = usePreviewId();

  return (
    <FieldGroup className="mx-auto w-56">
      <Field orientation="horizontal">
        <Checkbox
          id={`${previewId}-terms-checkbox-basic`}
          name="terms-checkbox-basic"
        />
        <FieldLabel htmlFor={`${previewId}-terms-checkbox-basic`}>
          Accept terms and conditions
        </FieldLabel>
      </Field>
    </FieldGroup>
  );
}

export default CheckboxBasic;
```

## Description

Use `FieldContent` and `FieldDescription` for helper text.

### Example: checkbox-description

```tsx
import { Checkbox } from "@workspace/ui/components/checkbox";
import {
  Field,
  FieldContent,
  FieldDescription,
  FieldGroup,
  FieldLabel,
} from "@workspace/ui/components/field";
import { useId as usePreviewId } from "react";

export function CheckboxDescription() {
  const previewId = usePreviewId();

  return (
    <FieldGroup className="mx-auto w-72">
      <Field orientation="horizontal">
        <Checkbox
          id={`${previewId}-terms-checkbox-desc`}
          name="terms-checkbox-desc"
          defaultChecked
        />
        <FieldContent>
          <FieldLabel htmlFor={`${previewId}-terms-checkbox-desc`}>
            Accept terms and conditions
          </FieldLabel>
          <FieldDescription>
            By clicking this checkbox, you agree to the terms and conditions.
          </FieldDescription>
        </FieldContent>
      </Field>
    </FieldGroup>
  );
}

export default CheckboxDescription;
```

## Disabled

Use the `disabled` prop to prevent interaction and add the `data-disabled` attribute to the `<Field>` component for disabled styles.

### Example: checkbox-disabled

```tsx
import { Checkbox } from "@workspace/ui/components/checkbox";
import { Field, FieldGroup, FieldLabel } from "@workspace/ui/components/field";
import { useId as usePreviewId } from "react";

export function CheckboxDisabled() {
  const previewId = usePreviewId();

  return (
    <FieldGroup className="mx-auto w-56">
      <Field orientation="horizontal" data-disabled>
        <Checkbox
          id={`${previewId}-toggle-checkbox-disabled`}
          name="toggle-checkbox-disabled"
          disabled
        />
        <FieldLabel htmlFor={`${previewId}-toggle-checkbox-disabled`}>
          Enable notifications
        </FieldLabel>
      </Field>
    </FieldGroup>
  );
}

export default CheckboxDisabled;
```

## Group

Use multiple fields to create a checkbox list.

### Example: checkbox-group

```tsx
import { Checkbox } from "@workspace/ui/components/checkbox";
import {
  Field,
  FieldDescription,
  FieldGroup,
  FieldLabel,
  FieldLegend,
  FieldSet,
} from "@workspace/ui/components/field";
import { useId as usePreviewId } from "react";

export function CheckboxGroup() {
  const previewId = usePreviewId();

  return (
    <FieldSet>
      <FieldLegend variant="label">
        Show these items on the desktop:
      </FieldLegend>
      <FieldDescription>
        Select the items you want to show on the desktop.
      </FieldDescription>
      <FieldGroup className="gap-3">
        <Field orientation="horizontal">
          <Checkbox
            id={`${previewId}-finder-pref-9k2-hard-disks-ljj-checkbox`}
            name="finder-pref-9k2-hard-disks-ljj-checkbox"
            defaultChecked
          />
          <FieldLabel
            htmlFor={`${previewId}-finder-pref-9k2-hard-disks-ljj-checkbox`}
            className="font-normal"
          >
            Hard disks
          </FieldLabel>
        </Field>
        <Field orientation="horizontal">
          <Checkbox
            id={`${previewId}-finder-pref-9k2-external-disks-1yg-checkbox`}
            name="finder-pref-9k2-external-disks-1yg-checkbox"
            defaultChecked
          />
          <FieldLabel
            htmlFor={`${previewId}-finder-pref-9k2-external-disks-1yg-checkbox`}
            className="font-normal"
          >
            External disks
          </FieldLabel>
        </Field>
        <Field orientation="horizontal">
          <Checkbox
            id={`${previewId}-finder-pref-9k2-cds-dvds-fzt-checkbox`}
            name="finder-pref-9k2-cds-dvds-fzt-checkbox"
          />
          <FieldLabel
            htmlFor={`${previewId}-finder-pref-9k2-cds-dvds-fzt-checkbox`}
            className="font-normal"
          >
            CDs, DVDs, and iPods
          </FieldLabel>
        </Field>
        <Field orientation="horizontal">
          <Checkbox
            id={`${previewId}-finder-pref-9k2-connected-servers-6l2-checkbox`}
            name="finder-pref-9k2-connected-servers-6l2-checkbox"
          />
          <FieldLabel
            htmlFor={`${previewId}-finder-pref-9k2-connected-servers-6l2-checkbox`}
            className="font-normal"
          >
            Connected servers
          </FieldLabel>
        </Field>
      </FieldGroup>
    </FieldSet>
  );
}

export default CheckboxGroup;
```

## Table

### Example: checkbox-table

```tsx
"use client";

import { Checkbox } from "@workspace/ui/components/checkbox";
import {
  Table,
  TableBody,
  TableCell,
  TableHead,
  TableHeader,
  TableRow,
} from "@workspace/ui/components/table";
import * as React from "react";
import { useId as usePreviewId } from "react";

const tableData = [
  {
    id: "1",
    name: "Sarah Chen",
    email: "sarah.chen@example.com",
    role: "Admin",
  },
  {
    id: "2",
    name: "Marcus Rodriguez",
    email: "marcus.rodriguez@example.com",
    role: "User",
  },
  {
    id: "3",
    name: "Priya Patel",
    email: "priya.patel@example.com",
    role: "User",
  },
  {
    id: "4",
    name: "David Kim",
    email: "david.kim@example.com",
    role: "Editor",
  },
];

export function CheckboxInTable() {
  const previewId = usePreviewId();

  const [selectedRows, setSelectedRows] = React.useState<Set<string>>(
    new Set(["1"]),
  );

  const selectAll = selectedRows.size === tableData.length;

  const handleSelectAll = (checked: boolean) => {
    if (checked) {
      setSelectedRows(new Set(tableData.map((row) => row.id)));
    } else {
      setSelectedRows(new Set());
    }
  };

  const handleSelectRow = (id: string, checked: boolean) => {
    const newSelected = new Set(selectedRows);
    if (checked) {
      newSelected.add(id);
    } else {
      newSelected.delete(id);
    }
    setSelectedRows(newSelected);
  };

  return (
    <Table>
      <TableHeader>
        <TableRow>
          <TableHead className="w-8">
            <Checkbox
              id={`${previewId}-select-all-checkbox`}
              name="select-all-checkbox"
              checked={selectAll}
              onCheckedChange={handleSelectAll}
            />
          </TableHead>
          <TableHead>Name</TableHead>
          <TableHead>Email</TableHead>
          <TableHead>Role</TableHead>
        </TableRow>
      </TableHeader>
      <TableBody>
        {tableData.map((row) => (
          <TableRow
            key={row.id}
            data-state={selectedRows.has(row.id) ? "selected" : undefined}
          >
            <TableCell>
              <Checkbox
                id={`row-${row.id}-checkbox`}
                name={`row-${row.id}-checkbox`}
                checked={selectedRows.has(row.id)}
                onCheckedChange={(checked) =>
                  handleSelectRow(row.id, checked === true)
                }
              />
            </TableCell>
            <TableCell className="font-medium">{row.name}</TableCell>
            <TableCell>{row.email}</TableCell>
            <TableCell>{row.role}</TableCell>
          </TableRow>
        ))}
      </TableBody>
    </Table>
  );
}

export default CheckboxInTable;
```

## RTL

To enable RTL support in shadcn/ui, see the [RTL configuration guide](https://ui.shadcn.com/docs/rtl).

### Example: checkbox-rtl

```tsx
"use client";

import { Checkbox } from "@workspace/ui/components/checkbox";
import {
  Field,
  FieldContent,
  FieldDescription,
  FieldGroup,
  FieldLabel,
  FieldTitle,
} from "@workspace/ui/components/field";
import { Label } from "@workspace/ui/components/label";
import { useId as usePreviewId } from "react";
import { type Translations, useTranslation } from "./support";

const translations: Translations = {
  en: {
    dir: "ltr",
    values: {
      acceptTerms: "Accept terms and conditions",
      acceptTermsDescription:
        "By clicking this checkbox, you agree to the terms.",
      enableNotifications: "Enable notifications",
      enableNotificationsDescription:
        "You can enable or disable notifications at any time.",
    },
  },
  ar: {
    dir: "rtl",
    values: {
      acceptTerms: "قبول الشروط والأحكام",
      acceptTermsDescription: "بالنقر على هذا المربع، فإنك توافق على الشروط.",
      enableNotifications: "تفعيل الإشعارات",
      enableNotificationsDescription:
        "يمكنك تفعيل أو إلغاء تفعيل الإشعارات في أي وقت.",
    },
  },
  he: {
    dir: "rtl",
    values: {
      acceptTerms: "קבל תנאים והגבלות",
      acceptTermsDescription:
        "על ידי לחיצה על תיבת הסימון הזו, אתה מסכים לתנאים.",
      enableNotifications: "הפעל התראות",
      enableNotificationsDescription:
        "אתה יכול להפעיל או להשבית התראות בכל עת.",
    },
  },
};

export function CheckboxRtl() {
  const previewId = usePreviewId();

  const { dir, t } = useTranslation(translations, "ar");

  return (
    <FieldGroup className="max-w-sm" dir={dir}>
      <Field orientation="horizontal">
        <Checkbox
          id={`${previewId}-terms-checkbox-rtl`}
          name="terms-checkbox"
        />
        <Label htmlFor={`${previewId}-terms-checkbox-rtl`}>
          {t.acceptTerms}
        </Label>
      </Field>
      <Field orientation="horizontal">
        <Checkbox
          id={`${previewId}-terms-checkbox-2-rtl`}
          name="terms-checkbox-2"
          defaultChecked
        />
        <FieldContent>
          <FieldLabel htmlFor={`${previewId}-terms-checkbox-2-rtl`}>
            {t.acceptTerms}
          </FieldLabel>
          <FieldDescription>{t.acceptTermsDescription}</FieldDescription>
        </FieldContent>
      </Field>
      <Field orientation="horizontal" data-disabled>
        <Checkbox
          id={`${previewId}-toggle-checkbox-rtl`}
          name="toggle-checkbox"
          disabled
        />
        <FieldLabel htmlFor={`${previewId}-toggle-checkbox-rtl`}>
          {t.enableNotifications}
        </FieldLabel>
      </Field>
      <FieldLabel>
        <Field orientation="horizontal">
          <Checkbox
            id={`${previewId}-toggle-checkbox-2`}
            name="toggle-checkbox-2"
          />
          <FieldContent>
            <FieldTitle>{t.enableNotifications}</FieldTitle>
            <FieldDescription>
              {t.enableNotificationsDescription}
            </FieldDescription>
          </FieldContent>
        </Field>
      </FieldLabel>
    </FieldGroup>
  );
}

export default CheckboxRtl;
```

## API Reference

See the [Base UI](https://base-ui.com/react/components/checkbox#api-reference) documentation for more information.

- [Documentation](https://base-ui.com/react/components/checkbox)
- [API reference](https://base-ui.com/react/components/checkbox#api-reference)


---

# Clipboard Text

A selectable text field with a separate copy action and async feedback.

Page: https://sui.draco.dev/docs/components/clipboard-text

### Example: clipboard-text-demo

```tsx
import { ClipboardText } from "@workspace/ui/components/clipboard-text";
import type { ExampleProps } from "../types";
export default function Example({ locale }: ExampleProps) {
  const zh = locale === "zh-CN";
  return (
    <div className="w-full max-w-md">
      <ClipboardText
        text="bun add @workspace/ui"
        labels={{
          copy: zh ? "复制安装命令" : "Copy install command",
          copied: zh ? "已复制" : "Copied",
          failed: zh ? "复制失败，请手动复制" : "Copy failed. Copy manually.",
        }}
      />
    </div>
  );
}
```

## Installation

```bash
bunx --bun shadcn@latest add @sui/clipboard-text
```

Install with the shadcn CLI or use the shared `@workspace/ui` package. Follow the [installation guide](/docs/installation) to configure the registry, load styles, and choose import aliases.

```tsx
import { ClipboardText } from "@workspace/ui/components/clipboard-text";
```

## Usage

```tsx
<ClipboardText text="bun run dev" />
```

The displayed text remains selectable. A long value truncates visually; its full value is available on hover and the copy action always copies the complete value.

## Display and copy different values

Use `textToCopy` for a full address while showing a shorter label. `size` accepts `sm`, `default`, and `lg`.

### Example: clipboard-text-display-value

```tsx
import { ClipboardText } from "@workspace/ui/components/clipboard-text";
import type { ExampleProps } from "../types";
export default function Example({ locale }: ExampleProps) {
  const zh = locale === "zh-CN";
  return (
    <div className="grid w-full max-w-md gap-3">
      <ClipboardText
        text="/api/components"
        textToCopy="https://api.example.com/v1/components"
        size="sm"
        labels={{ copy: zh ? "复制完整 API 地址" : "Copy full API URL" }}
      />
      <ClipboardText
        text="https://api.example.com/v1/components?workspace=design-system&include=properties"
        size="lg"
        labels={{ copy: zh ? "复制地址" : "Copy URL" }}
      />
      <p className="text-muted-foreground text-sm">
        {zh
          ? "显示简短路径，复制完整地址；长文本可选择或悬停查看"
          : "Show a short path while copying the full URL. Long text can be selected or inspected on hover."}
      </p>
    </div>
  );
}
```

## Feedback and disabled state

`onCopy` receives the copied string only after the clipboard write succeeds. Handle `onCopyError` to provide a visible fallback. `labels` localizes the action and screen reader feedback. A pending write disables the copy button; a disabled field cannot start a write.

### Example: clipboard-text-feedback

```tsx
import { ClipboardText } from "@workspace/ui/components/clipboard-text";
import { Switch } from "@workspace/ui/components/switch";
import { useId, useState } from "react";
import type { ExampleProps } from "../types";
export default function Example({ locale }: ExampleProps) {
  const zh = locale === "zh-CN";
  const [enabled, setEnabled] = useState(true);
  const [notice, setNotice] = useState("");
  const id = useId();
  return (
    <div className="grid w-full max-w-md gap-4">
      <div className="flex items-center gap-2">
        <Switch id={id} checked={enabled} onCheckedChange={setEnabled} />
        <label htmlFor={id}>{zh ? "允许复制" : "Enable copying"}</label>
      </div>
      <ClipboardText
        text="workspace_72c31"
        disabled={!enabled}
        onCopy={() =>
          setNotice(zh ? "工作区 ID 已复制" : "Workspace ID copied.")
        }
        onCopyError={() =>
          setNotice(
            zh
              ? "浏览器无法访问剪贴板，请选择文本后手动复制"
              : "Clipboard access failed. Select the text and copy it manually.",
          )
        }
        labels={{
          copy: zh ? "复制工作区 ID" : "Copy workspace ID",
          copied: zh ? "已复制" : "Copied",
          failed: zh
            ? "无法复制，请手动复制"
            : "Copy unavailable. Copy manually.",
        }}
      />
      <p className="min-h-5 text-muted-foreground text-sm" role="status">
        {notice}
      </p>
    </div>
  );
}
```

The component uses the browser Clipboard API. If it is unavailable or permission is denied, it announces failure and calls `onCopyError`; users can select the text and copy it manually. It does not request clipboard access while rendering.

## API

| Prop | Type | Default |
| --- | --- | --- |
| `text` | `string` | Required |
| `textToCopy` | `string` | `text` |
| `size` | `"sm" \| "default" \| "lg"` | `"default"` |
| `disabled` | `boolean` | `false` |
| `resetDelay` | `number`, milliseconds | `1500` |
| `onCopy` | `(value: string) => void` | — |
| `onCopyError` | `(error: Error) => void` | — |
| `labels` | `{ copy?, pending?, copied?, failed? }` | English labels |
| `render` | React element or render function | `InputGroup` |

Standard root `div` props and refs are supported. Customize the root with `className` or Base UI's `render` composition. The copy control uses SUI [Input Group](/docs/components/input-group) and [Tooltip](/docs/components/tooltip); async state is exposed through `data-copy-status="idle|pending|copied|error"`. See the [Base UI composition API](https://base-ui.com/react/handbook/composition) for render and ref behavior.


---

# Code Viewer

Syntax-highlighted code with folding, line highlights, copying, and streaming feedback.

Page: https://sui.draco.dev/docs/components/code-viewer

### Example: code-viewer-demo

```tsx
"use client";
import { CodeViewer } from "@workspace/ui/components/code-viewer";
import type { ExampleProps } from "../types";

const code =
  'const colors = ["bamboo", "mauve", "mist"];\n\nexport function getTheme(name: string) {\n  if (colors.includes(name)) {\n    return { name, active: true };\n  }\n  return { name: "default", active: false };\n}';
export default function Example({ locale }: ExampleProps) {
  const chinese = locale === "zh-CN";
  return (
    <CodeViewer
      code={code}
      lang="typescript"
      title="theme.ts"
      highlightLines={[4, 5]}
      maxHeight={240}
      labels={
        chinese
          ? {
              copy: "复制代码",
              loading: "正在高亮",
              error: "无法高亮代码",
              empty: "没有代码",
              expand: "展开",
              collapse: "折叠",
              writing: "正在编写",
              ready: "就绪",
              copied: "已复制",
              copyFailed: "复制失败",
            }
          : undefined
      }
    />
  );
}
```

## Installation

```bash
bunx --bun shadcn@latest add @sui/code-viewer
```

Install with the shadcn CLI or use the shared `@workspace/ui` package. Follow the [installation guide](/docs/installation) to configure the registry, load styles, and choose import aliases.

## Usage

```tsx
import { CodeViewer } from "@workspace/ui/components/code-viewer";

<CodeViewer code={'const theme = "bamboo";'} lang="typescript" title="theme.ts" />;
```

## Lines, folding, and layout

Line numbers are shown by default. `highlightLines` uses one-based line numbers. Indented blocks following `{`, `[`, or `(` can be folded with the gutter controls; changing `code` resets folding. This is an indentation-based view, not a syntax-aware code editor.

Set `wrap` for long lines or change `maxHeight` to limit the scrolling viewport. Use `showLineNumbers={false}` for compact snippets. The viewport is reachable with Tab and supports keyboard scrolling with a visible theme-colored focus ring.

## Streaming content

Pass `status="streaming"` while appending code, then switch to `"complete"`. The viewer displays status feedback and follows content near the bottom. Scrolling more than 32px away pauses following; returning to the bottom resumes it. Starting a new streaming session restores following by default. The example replays a local sequence and cleans up its timer on unmount.

### Example: code-viewer-streaming

```tsx
"use client";
import { Button } from "@workspace/ui/components/button";
import { CodeViewer } from "@workspace/ui/components/code-viewer";
import { useEffect, useState } from "react";
import type { ExampleProps } from "../types";

const lines = [
  'const colors = ["bamboo", "mauve", "mist"];',
  "",
  "export function getTheme(name: string) {",
  "  if (colors.includes(name)) {",
  "    return { name, active: true };",
  "  }",
  '  return { name: "default", active: false };',
  "}",
  "",
  "export const settings = {",
  '  theme: "bamboo",',
  "  palettes: [",
  '    "bamboo",',
  '    "mauve",',
  '    "mist",',
  '    "sand",',
  '    "pine",',
  '    "rose",',
  "  ],",
  "  layout: {",
  '    density: "comfortable",',
  '    width: "content",',
  "  },",
  "};",
];
export default function Example({ locale }: ExampleProps) {
  const chinese = locale === "zh-CN";
  const [count, setCount] = useState(lines.length);
  const streaming = count < lines.length;
  useEffect(() => {
    if (!streaming) return;
    const timer = setTimeout(() => setCount(count + 1), 240);
    return () => clearTimeout(timer);
  }, [streaming, count]);
  return (
    <div className="grid w-full gap-3">
      <Button
        type="button"
        variant="outline"
        className="justify-self-start"
        disabled={streaming}
        onClick={() => setCount(1)}
      >
        {chinese ? "重新播放流式输入" : "Replay streaming input"}
      </Button>
      <CodeViewer
        code={lines.slice(0, count).join("\n")}
        status={streaming ? "streaming" : "complete"}
        lang="typescript"
        title="theme.ts"
        wrap
        showLineNumbers={false}
        maxHeight={180}
        labels={
          chinese
            ? {
                copy: "复制代码",
                loading: "正在高亮",
                error: "无法高亮代码",
                empty: "没有代码",
                expand: "展开",
                collapse: "折叠",
                writing: "正在编写",
                ready: "就绪",
                copied: "已复制",
                copyFailed: "复制失败",
              }
            : undefined
        }
      />
    </div>
  );
}
```

## Copy and theme behavior

Copy writes the original complete code, including folded lines, and provides success or failure feedback. Set `copyable={false}` to remove the action. Highlighting loads asynchronously with a bounded skeleton; streaming updates keep incoming text visible while tokens are prepared. If loading is pending, the complete source remains available to copy and to assistive technology; if highlighting fails, readable plain code remains available. An empty string displays the empty-state label.

The viewer follows the surrounding light or dark theme unless `theme` is supplied. Translate `labels` for copy, loading, empty, folding, writing, ready, copied, and copy failure.

## Plain style and highlighting configuration

`variant="plain"` removes the outer frame and title bar while retaining the code and copy action. Override `--code-highlight-bg` to customize highlighted-line backgrounds.

An optional `ShikiProvider` shares highlighting configuration across its viewers and editors. `themes` provides light and dark themes, and `languages` preloads requested languages. Highlighting works without a provider; recognized languages and aliases load on demand, while unknown languages fall back to plain text.

### Example: code-viewer-plain

```tsx
"use client";
import {
  CodeViewer,
  ShikiProvider,
} from "@workspace/ui/components/code-viewer";
import type { ExampleProps } from "../types";

const themes = { light: "github-light", dark: "github-dark" } as const;
const languages = ["python", "sql"] as const;
const code =
  'def greeting(name: str):\n    return f"Hello, {name}"\n\nprint(greeting("SUI"))';
export default function Example({ locale }: ExampleProps) {
  const chinese = locale === "zh-CN";
  return (
    <ShikiProvider themes={themes} languages={languages}>
      <div className="w-full rounded-xl bg-muted p-4">
        <CodeViewer
          code={code}
          lang="python"
          variant="plain"
          highlightLines={[2]}
          className="[--code-highlight-bg:var(--accent)]"
          labels={
            chinese
              ? {
                  copy: "复制代码",
                  copied: "已复制",
                  copyFailed: "复制失败",
                  loading: "正在高亮",
                  error: "无法高亮代码",
                  empty: "没有代码",
                  expand: "展开",
                  collapse: "折叠",
                  writing: "正在编写",
                  ready: "就绪",
                }
              : undefined
          }
        />
      </div>
    </ShikiProvider>
  );
}
```

```tsx
import { CodeViewer, ShikiProvider } from "@workspace/ui/components/code-viewer";

<ShikiProvider
  themes={{ light: "github-light", dark: "github-dark" }}
  languages={["python", "sql"]}
>
  <CodeViewer
    code={code}
    lang="python"
    variant="plain"
    highlightLines={[2]}
    className="[--code-highlight-bg:var(--accent)]"
  />
</ShikiProvider>;
```

## API reference

| Prop | Type | Default / behavior |
| --- | --- | --- |
| `variant` | `"default" \| "plain"` | `"default"`. |
| `code` | `string` | Required source text. |
| `lang` | `string` | `"typescript"`. |
| `theme` | `"light" \| "dark"` | Follows surrounding theme. |
| `title` | `ReactNode` | Optional header title. |
| `status` | `"streaming" \| "complete"` | `"complete"`. |
| `showLineNumbers` | `boolean` | `true`. |
| `highlightLines` | `number[]` | `[]`; one-based. |
| `maxHeight` | `number` | `280` pixels. |
| `wrap` | `boolean` | `false`. |
| `copyable` | `boolean` | `true`. |
| `labels` | `Partial<CodeViewerLabels>` | English labels. |
| `glass` | `boolean` | `false`. |

The module exports `CodeViewerProps` and `CodeViewerLabels`. Highlighting uses [Shiki](https://shiki.style/guide/). To edit instead of view, use [Editor](/docs/components/editor).

`ShikiProviderProps` is also exported from this module; theme names use Shiki bundled themes.

### ShikiProvider

| Prop | Type | Default / behavior |
| --- | --- | --- |
| `themes` | `{ light: BundledTheme; dark: BundledTheme }` | `one-light` and `one-dark-pro`. |
| `languages` | `readonly string[]` | Optional languages to preload. |
| `onError` | `(error: unknown) => void` | Reports preload failure without changing the plain-text fallback. |

Keep static `themes` and `languages` outside the component to avoid restarting preloads.


---

# Collapsible

An interactive component which expands/collapses a panel.

Page: https://sui.draco.dev/docs/components/collapsible

### Example: collapsible-demo

```tsx
"use client";

import { Button } from "@workspace/ui/components/button";
import {
  Collapsible,
  CollapsibleContent,
  CollapsibleTrigger,
} from "@workspace/ui/components/collapsible";
import { ChevronsUpDown } from "lucide-react";
import * as React from "react";

export default function CollapsibleDemo() {
  const [isOpen, setIsOpen] = React.useState(false);

  return (
    <Collapsible
      open={isOpen}
      onOpenChange={setIsOpen}
      className="flex w-[350px] flex-col gap-2"
    >
      <div className="flex items-center justify-between gap-4 px-4">
        <h4 className="font-semibold text-sm">Order #4189</h4>
        <CollapsibleTrigger
          render={<Button variant="ghost" size="icon" className="size-8" />}
        >
          <ChevronsUpDown />
          <span className="sr-only">Toggle details</span>
        </CollapsibleTrigger>
      </div>
      <div className="flex items-center justify-between rounded-md border px-4 py-2 text-sm">
        <span className="text-muted-foreground">Status</span>
        <span className="font-medium">Shipped</span>
      </div>
      <CollapsibleContent className="flex flex-col gap-2">
        <div className="rounded-md border px-4 py-2 text-sm">
          <p className="font-medium">Shipping address</p>
          <p className="text-muted-foreground">100 Market St, San Francisco</p>
        </div>
        <div className="rounded-md border px-4 py-2 text-sm">
          <p className="font-medium">Items</p>
          <p className="text-muted-foreground">2x Studio Headphones</p>
        </div>
      </CollapsibleContent>
    </Collapsible>
  );
}
```

## Installation

```bash
bunx --bun shadcn@latest add @sui/collapsible
```

Install with the shadcn CLI or use the shared `@workspace/ui` package. Follow the [installation guide](/docs/installation) to configure the registry, load styles, and choose import aliases.

## Usage

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

```tsx showLineNumbers
<Collapsible>
  <CollapsibleTrigger>Can I use this in my project?</CollapsibleTrigger>
  <CollapsibleContent>
    Yes. Free to use for personal and commercial projects. No attribution
    required.
  </CollapsibleContent>
</Collapsible>
```

## Composition

Use the following composition to build a `Collapsible`:

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

## Controlled State

Use the `open` and `onOpenChange` props to control the state.

```tsx showLineNumbers
import * as React from "react"

export function Example() {
  const [open, setOpen] = React.useState(false)

  return (
    <Collapsible open={open} onOpenChange={setOpen}>
      <CollapsibleTrigger>Toggle</CollapsibleTrigger>
      <CollapsibleContent>Content</CollapsibleContent>
    </Collapsible>
  )
}
```

## Basic

### Example: collapsible-basic

```tsx
import { Button } from "@workspace/ui/components/button";
import { Card, CardContent } from "@workspace/ui/components/card";
import {
  Collapsible,
  CollapsibleContent,
  CollapsibleTrigger,
} from "@workspace/ui/components/collapsible";
import { ChevronDownIcon } from "lucide-react";

export function CollapsibleBasic() {
  return (
    <Card className="mx-auto w-full max-w-sm">
      <CardContent>
        <Collapsible className="rounded-md data-open:bg-muted">
          <CollapsibleTrigger
            render={<Button variant="ghost" className="w-full" />}
          >
            Product details
            <ChevronDownIcon className="ml-auto group-data-panel-open/button:rotate-180" />
          </CollapsibleTrigger>
          <CollapsibleContent className="flex flex-col items-start gap-2 p-2.5 pt-0 text-sm">
            <div>
              This panel can be expanded or collapsed to reveal additional
              content.
            </div>
            <Button size="xs">Learn More</Button>
          </CollapsibleContent>
        </Collapsible>
      </CardContent>
    </Card>
  );
}

export default CollapsibleBasic;
```

## Settings Panel

Use a trigger button to reveal additional settings.

### Example: collapsible-settings

```tsx
"use client";

import { Button } from "@workspace/ui/components/button";
import {
  Card,
  CardContent,
  CardDescription,
  CardHeader,
  CardTitle,
} from "@workspace/ui/components/card";
import {
  Collapsible,
  CollapsibleContent,
  CollapsibleTrigger,
} from "@workspace/ui/components/collapsible";
import { Field, FieldGroup, FieldLabel } from "@workspace/ui/components/field";
import { Input } from "@workspace/ui/components/input";
import { MaximizeIcon, MinimizeIcon } from "lucide-react";
import * as React from "react";
import { useId as usePreviewId } from "react";

export function CollapsibleSettings() {
  const previewId = usePreviewId();

  const [isOpen, setIsOpen] = React.useState(false);

  return (
    <Card className="mx-auto w-full max-w-xs" size="sm">
      <CardHeader>
        <CardTitle>Radius</CardTitle>
        <CardDescription>Set the corner radius of the element.</CardDescription>
      </CardHeader>
      <CardContent>
        <Collapsible
          open={isOpen}
          onOpenChange={setIsOpen}
          className="flex items-start gap-2"
        >
          <FieldGroup className="grid w-full grid-cols-2 gap-2">
            <Field>
              <FieldLabel htmlFor={`${previewId}-radius-x`} className="sr-only">
                Radius X
              </FieldLabel>
              <Input
                id={`${previewId}-radius-x`}
                placeholder="0"
                defaultValue={0}
              />
            </Field>
            <Field>
              <FieldLabel htmlFor={`${previewId}-radius-y`} className="sr-only">
                Radius Y
              </FieldLabel>
              <Input
                id={`${previewId}-radius-y`}
                placeholder="0"
                defaultValue={0}
              />
            </Field>
            <CollapsibleContent className="col-span-full grid grid-cols-subgrid gap-2">
              <Field>
                <FieldLabel
                  htmlFor={`${previewId}-radius-expanded-x`}
                  className="sr-only"
                >
                  Radius X
                </FieldLabel>
                <Input
                  id={`${previewId}-radius-expanded-x`}
                  placeholder="0"
                  defaultValue={0}
                />
              </Field>
              <Field>
                <FieldLabel
                  htmlFor={`${previewId}-radius-expanded-y`}
                  className="sr-only"
                >
                  Radius Y
                </FieldLabel>
                <Input
                  id={`${previewId}-radius-expanded-y`}
                  placeholder="0"
                  defaultValue={0}
                />
              </Field>
            </CollapsibleContent>
          </FieldGroup>
          <CollapsibleTrigger render={<Button variant="outline" size="icon" />}>
            {isOpen ? <MinimizeIcon /> : <MaximizeIcon />}
          </CollapsibleTrigger>
        </Collapsible>
      </CardContent>
    </Card>
  );
}

export default CollapsibleSettings;
```

## File Tree

Use nested collapsibles to build a file tree.

### Example: collapsible-file-tree

```tsx
import { Button } from "@workspace/ui/components/button";
import { Card, CardContent, CardHeader } from "@workspace/ui/components/card";
import {
  Collapsible,
  CollapsibleContent,
  CollapsibleTrigger,
} from "@workspace/ui/components/collapsible";
import { Tabs, TabsList, TabsTrigger } from "@workspace/ui/components/tabs";
import { ChevronRightIcon, FileIcon, FolderIcon } from "lucide-react";

type FileTreeItem = { name: string } | { name: string; items: FileTreeItem[] };

export function CollapsibleFileTree() {
  const fileTree: FileTreeItem[] = [
    {
      name: "components",
      items: [
        {
          name: "ui",
          items: [
            { name: "button.tsx" },
            { name: "card.tsx" },
            { name: "dialog.tsx" },
            { name: "input.tsx" },
            { name: "select.tsx" },
            { name: "table.tsx" },
          ],
        },
        { name: "login-form.tsx" },
        { name: "register-form.tsx" },
      ],
    },
    {
      name: "lib",
      items: [{ name: "utils.ts" }, { name: "cn.ts" }, { name: "api.ts" }],
    },
    {
      name: "hooks",
      items: [
        { name: "use-media-query.ts" },
        { name: "use-debounce.ts" },
        { name: "use-local-storage.ts" },
      ],
    },
    {
      name: "types",
      items: [{ name: "index.d.ts" }, { name: "api.d.ts" }],
    },
    {
      name: "public",
      items: [
        { name: "favicon.ico" },
        { name: "logo.svg" },
        { name: "images" },
      ],
    },
    { name: "app.tsx" },
    { name: "layout.tsx" },
    { name: "globals.css" },
    { name: "package.json" },
    { name: "tsconfig.json" },
    { name: "README.md" },
    { name: ".gitignore" },
  ];

  const renderItem = (fileItem: FileTreeItem) => {
    if ("items" in fileItem) {
      return (
        <Collapsible key={fileItem.name}>
          <CollapsibleTrigger
            render={
              <Button
                variant="ghost"
                size="sm"
                className="group w-full justify-start transition-none hover:bg-accent hover:text-accent-foreground"
              />
            }
          >
            <ChevronRightIcon className="transition-transform group-data-[state=open]:rotate-90" />
            <FolderIcon />
            {fileItem.name}
          </CollapsibleTrigger>
          <CollapsibleContent className="mt-1 ml-5 style-lyra:ml-4">
            <div className="flex flex-col gap-1">
              {fileItem.items.map((child) => renderItem(child))}
            </div>
          </CollapsibleContent>
        </Collapsible>
      );
    }
    return (
      <Button
        key={fileItem.name}
        variant="link"
        size="sm"
        className="w-full justify-start gap-2 text-foreground"
      >
        <FileIcon />
        <span>{fileItem.name}</span>
      </Button>
    );
  };

  return (
    <Card className="mx-auto w-full max-w-[16rem] gap-2" size="sm">
      <CardHeader>
        <Tabs defaultValue="explorer">
          <TabsList className="w-full">
            <TabsTrigger value="explorer">Explorer</TabsTrigger>
            <TabsTrigger value="settings">Outline</TabsTrigger>
          </TabsList>
        </Tabs>
      </CardHeader>
      <CardContent>
        <div className="flex flex-col gap-1">
          {fileTree.map((item) => renderItem(item))}
        </div>
      </CardContent>
    </Card>
  );
}

export default CollapsibleFileTree;
```

## RTL

To enable RTL support in shadcn/ui, see the [RTL configuration guide](https://ui.shadcn.com/docs/rtl).

### Example: collapsible-rtl

```tsx
"use client";

import { Button } from "@workspace/ui/components/button";
import {
  Collapsible,
  CollapsibleContent,
  CollapsibleTrigger,
} from "@workspace/ui/components/collapsible";
import { ChevronsUpDown } from "lucide-react";
import * as React from "react";
import { type Translations, useTranslation } from "./support";

const translations: Translations = {
  en: {
    dir: "ltr",
    values: {
      orderNumber: "Order #4189",
      status: "Status",
      shipped: "Shipped",
      shippingAddress: "Shipping address",
      address: "100 Market St, San Francisco",
      items: "Items",
      itemsDescription: "2x Studio Headphones",
    },
  },
  ar: {
    dir: "rtl",
    values: {
      orderNumber: "الطلب #4189",
      status: "الحالة",
      shipped: "تم الشحن",
      shippingAddress: "عنوان الشحن",
      address: "100 Market St, San Francisco",
      items: "العناصر",
      itemsDescription: "2x سماعات الاستوديو",
    },
  },
  he: {
    dir: "rtl",
    values: {
      orderNumber: "הזמנה #4189",
      status: "סטטוס",
      shipped: "נשלח",
      shippingAddress: "כתובת משלוח",
      address: "100 Market St, San Francisco",
      items: "פריטים",
      itemsDescription: "2x אוזניות סטודיו",
    },
  },
};

export function CollapsibleRtl() {
  const { dir, t } = useTranslation(translations, "ar");
  const [isOpen, setIsOpen] = React.useState(false);

  return (
    <Collapsible
      open={isOpen}
      onOpenChange={setIsOpen}
      className="flex w-[350px] flex-col gap-2"
      dir={dir}
    >
      <div className="flex items-center justify-between gap-4 px-4">
        <h4 className="font-semibold text-sm">{t.orderNumber}</h4>
        <CollapsibleTrigger
          render={<Button variant="ghost" size="icon" className="size-8" />}
        >
          <ChevronsUpDown />
          <span className="sr-only">Toggle details</span>
        </CollapsibleTrigger>
      </div>
      <div className="flex items-center justify-between rounded-md border px-4 py-2 text-sm">
        <span className="text-muted-foreground">{t.status}</span>
        <span className="font-medium">{t.shipped}</span>
      </div>
      <CollapsibleContent className="flex flex-col gap-2">
        <div className="rounded-md border px-4 py-2 text-sm">
          <p className="font-medium">{t.shippingAddress}</p>
          <p className="text-muted-foreground">{t.address}</p>
        </div>
        <div className="rounded-md border px-4 py-2 text-sm">
          <p className="font-medium">{t.items}</p>
          <p className="text-muted-foreground">{t.itemsDescription}</p>
        </div>
      </CollapsibleContent>
    </Collapsible>
  );
}

export default CollapsibleRtl;
```

## API Reference

See the [Base UI](https://base-ui.com/react/components/collapsible#api-reference) documentation for more information.

- [Documentation](https://base-ui.com/react/components/collapsible)
- [API reference](https://base-ui.com/react/components/collapsible#api-reference)


---

# ColorPicker

Choose colors using a saturation area, hue and opacity sliders, editable values and preset swatches.

Page: https://sui.draco.dev/docs/components/color-picker

### Example: color-picker-demo

```tsx
"use client";
import { ColorPicker } from "@workspace/ui/components/color-picker";
import { useState } from "react";
import type { ExampleProps } from "../types";

export const chineseLabels = {
  trigger: "选择颜色",
  saturation: "饱和度和亮度",
  hue: "色相",
  alpha: "不透明度",
  hex: "HEX 颜色",
  format: "颜色格式",
  color: "颜色值",
  invalid: "请输入有效的颜色值",
  eyeDropper: "拾取屏幕颜色",
  eyeDropperFailed: "无法拾取屏幕颜色",
  swatches: "预设颜色",
};
export default function Example({ locale }: ExampleProps) {
  const [value, setValue] = useState("#007AFF");
  return (
    <div className="grid justify-items-start gap-4">
      <ColorPicker
        value={value}
        onValueChange={setValue}
        labels={locale === "zh-CN" ? chineseLabels : undefined}
      />
      <output className="text-muted-foreground text-sm">{value}</output>
      <ColorPicker
        disabled
        defaultValue="#70866A"
        labels={locale === "zh-CN" ? chineseLabels : undefined}
      />
    </div>
  );
}
```

## Installation

```bash
bunx --bun shadcn@latest add @sui/color-picker
```

Install with the shadcn CLI or use the shared `@workspace/ui` package. Follow the [installation guide](/docs/installation) to configure the registry, load styles, and choose import aliases.

## Usage

```tsx
import { ColorPicker } from "@workspace/ui/components/color-picker";
import { useState } from "react";

export function AccentColor() {
  const [color, setColor] = useState("#007AFF");
  return <ColorPicker value={color} onValueChange={setColor} />;
}
```

`value` and `onValueChange` make the picker controlled. Use `defaultValue` for local state. Values accept HEX with three or six digits, with or without `#`. With `alpha`, four and eight digits also encode opacity. Changes return normalized uppercase six-digit HEX, or eight digits with alpha enabled. Invalid input remains editable and shows feedback without changing the selected color.

## Editing formats

The format selector offers HEX, RGB, HSL, HSB and OKLCH. RGB accepts `rgb(0 122 255)`; HSL and HSB use percentages, for example `hsl(211 100% 50%)`. With opacity enabled, use `/ 0.5` or `/ 50%`. Changing the editing format preserves the color; output values remain HEX.

OKLCH accepts values such as `oklch(62.8% 0.2577 29.23 / 50%)`. Lightness accepts percentages or 0–1; chroma accepts numbers or percentages (100% equals 0.4); hue accepts unitless degrees, `deg`, `rad`, `grad`, or `turn`. Output remains sRGB HEX. Colors outside sRGB are mapped by reducing chroma while preserving lightness and hue, then quantized to eight-bit channels; the original wide-gamut value is not retained. Inputs require explicit numbers, without `none`, `calc()`, or relative color syntax. Lightness and opacity must be in range, and chroma must be nonnegative

## Opacity and inline controls

`inline` renders the controls directly. The checkerboard distinguishes transparency from white and black. Opacity changes return an eight-digit HEX value. The color picker does not change your application theme or persist a preference.

### Example: color-picker-alpha

```tsx
"use client";
import { ColorPicker } from "@workspace/ui/components/color-picker";
import { useState } from "react";
import type { ExampleProps } from "../types";
import { chineseLabels } from "./color-picker-demo";

export default function Example({ locale }: ExampleProps) {
  const [value, setValue] = useState("#007AFF80");
  return (
    <div className="grid w-full max-w-72 gap-4">
      <ColorPicker
        inline
        alpha
        value={value}
        onValueChange={setValue}
        labels={locale === "zh-CN" ? chineseLabels : undefined}
      />
      <output className="text-muted-foreground text-sm">{value}</output>
    </div>
  );
}
```

## Swatches and glass

Provide `swatches` as HEX values. Invalid and duplicate normalized colors are excluded. `glass` applies to the popup surface; the saturation field and sliders keep their color encoding, and individual swatches do not create nested glass surfaces.

### Example: color-picker-swatches

```tsx
"use client";
import { ColorPicker } from "@workspace/ui/components/color-picker";
import type { ExampleProps } from "../types";
import { chineseLabels } from "./color-picker-demo";

const swatches = [
  "#007AFF",
  "#70866A",
  "#8D739C",
  "#648493",
  "#AE916B",
  "#3E806E",
  "#BC6C73",
];
export default function Example({ locale }: ExampleProps) {
  return (
    <div className="flex gap-4">
      <ColorPicker
        defaultValue="#70866A"
        swatches={swatches}
        labels={locale === "zh-CN" ? chineseLabels : undefined}
      />
      <ColorPicker
        glass
        defaultValue="#8D739C"
        swatches={swatches}
        labels={
          locale === "zh-CN"
            ? { ...chineseLabels, trigger: "玻璃颜色选择器" }
            : { trigger: "Glass color picker" }
        }
      />
    </div>
  );
}
```

## Keyboard and screen color

Focus the saturation area: Left/Right change saturation, Up/Down change brightness, and Shift increases the step. Home/End set saturation to its minimum/maximum. Hue and opacity sliders use the shared Slider keyboard interactions. Tab moves between controls; Escape closes the popup and returns focus to its trigger. Every button uses `type="button"` and does not submit its surrounding form.

The optional screen eyedropper appears only in secure contexts with browser support. Cancelling keeps the current value, and an active request is cancelled when the picker unmounts. Set `eyeDropper={false}` to hide it. Translate `labels` for your interface. Trigger props such as `id`, `aria-describedby`, `ref`, `size` and `variant` are forwarded to the native trigger button. `inline` has no trigger and therefore does not use these trigger props.

## Composition

The same module exports `ColorPickerArea`, `ColorPickerSlider` and `ColorPickerSwatches`. Area and Slider receive `color: HSVColor` and `onColorChange(color)`; Slider adds `channel="hue" | "alpha"`. Swatches receive `value`, `swatches` and `onValueChange(value)`. Share one HSV state between these controls. Pure conversions are available from `@workspace/ui/lib/color/model`: `parseHexColor`, `colorToHex`, `parseColor`, `formatColor` and `colorToCSS`.

## API reference

| Prop | Type | Default / behavior |
| --- | --- | --- |
| `value` | `string` | Controlled HEX color |
| `defaultValue` | `string` | `"#0088FF"` |
| `onValueChange` | `(value: string) => void` | Called when the normalized color changes |
| `alpha` | `boolean` | `false`; enables opacity and eight-digit output |
| `swatches` | `readonly string[]` | `[]` |
| `disabled` | `boolean` | Disables all interactions |
| `inline` | `boolean` | `false`; renders controls without popup |
| `glass` | `boolean` | `false`; popup material |
| `eyeDropper` | `boolean` | `true`; depends on browser support |
| `labels` | `Partial<ColorPickerLabels>` | Accessible labels and feedback |
| `contentClassName` | `string` | Popup classes |

The module also exports prop types for the picker and its controls. Popup and sliders use the [Base UI Popover](https://base-ui.com/react/components/popover) and [Slider](https://base-ui.com/react/components/slider) APIs.


---

# Combobox

Autocomplete input with a list of suggestions.

Page: https://sui.draco.dev/docs/components/combobox

### Example: combobox-demo

```tsx
"use client";

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

const frameworks = [
  "Next.js",
  "SvelteKit",
  "Nuxt.js",
  "Remix",
  "Astro",
] as const;

export default function ComboboxBasic() {
  return (
    <Combobox items={frameworks}>
      <ComboboxInput placeholder="Select a framework" />
      <ComboboxContent>
        <ComboboxEmpty>No items found.</ComboboxEmpty>
        <ComboboxList>
          {(item) => (
            <ComboboxItem key={item} value={item}>
              {item}
            </ComboboxItem>
          )}
        </ComboboxList>
      </ComboboxContent>
    </Combobox>
  );
}
```

## Installation

```bash
bunx --bun shadcn@latest add @sui/combobox
```

Install with the shadcn CLI or use the shared `@workspace/ui` package. Follow the [installation guide](/docs/installation) to configure the registry, load styles, and choose import aliases.

## Usage

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

```tsx showLineNumbers
const frameworks = ["Next.js", "SvelteKit", "Nuxt.js", "Remix", "Astro"]

export function ExampleCombobox() {
  return (
    <Combobox items={frameworks}>
      <ComboboxInput placeholder="Select a framework" />
      <ComboboxContent>
        <ComboboxEmpty>No items found.</ComboboxEmpty>
        <ComboboxList>
          {(item) => (
            <ComboboxItem key={item} value={item}>
              {item}
            </ComboboxItem>
          )}
        </ComboboxList>
      </ComboboxContent>
    </Combobox>
  )
}
```

## Composition

### Simple

A single-line input and a flat list (see [Basic](#basic)).

```text
Combobox
├── ComboboxInput
└── ComboboxContent
    ├── ComboboxEmpty
    └── ComboboxList
        ├── ComboboxItem
        └── ComboboxItem
```

### With chips

Multi-select with `multiple`, chips, and a chips input (see [Multiple](#multiple)).

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

### With groups and collection

Nested items per group using `ComboboxCollection` inside each `ComboboxGroup`, with a separator between groups (see [Groups](#groups)).

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

## Custom Items

Use `itemToStringValue` when your items are objects.

```tsx showLineNumbers
import * as React from "react"

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

type Framework = {
  label: string
  value: string
}

const frameworks: Framework[] = [
  { label: "Next.js", value: "next" },
  { label: "SvelteKit", value: "sveltekit" },
  { label: "Nuxt", value: "nuxt" },
]

export function ExampleComboboxCustomItems() {
  return (
    <Combobox
      items={frameworks}
      itemToStringValue={(framework) => framework.label}
    >
      <ComboboxInput placeholder="Select a framework" />
      <ComboboxContent>
        <ComboboxEmpty>No items found.</ComboboxEmpty>
        <ComboboxList>
          {(framework) => (
            <ComboboxItem key={framework.value} value={framework}>
              {framework.label}
            </ComboboxItem>
          )}
        </ComboboxList>
      </ComboboxContent>
    </Combobox>
  )
}
```

## Multiple Selection

Use `multiple` with chips for multi-select behavior.

```tsx showLineNumbers
import * as React from "react"

import {
  Combobox,
  ComboboxChip,
  ComboboxChips,
  ComboboxChipsInput,
  ComboboxContent,
  ComboboxEmpty,
  ComboboxInput,
  ComboboxItem,
  ComboboxList,
  ComboboxValue,
} from "@workspace/ui/components/combobox"

const frameworks = ["Next.js", "SvelteKit", "Nuxt.js", "Remix", "Astro"]

export function ExampleComboboxMultiple() {
  const [value, setValue] = React.useState<string[]>([])

  return (
    <Combobox
      items={frameworks}
      multiple
      value={value}
      onValueChange={setValue}
    >
      <ComboboxChips>
        <ComboboxValue>
          {value.map((item) => (
            <ComboboxChip key={item}>{item}</ComboboxChip>
          ))}
        </ComboboxValue>
        <ComboboxChipsInput placeholder="Add framework" />
      </ComboboxChips>
      <ComboboxContent>
        <ComboboxEmpty>No items found.</ComboboxEmpty>
        <ComboboxList>
          {(item) => (
            <ComboboxItem key={item} value={item}>
              {item}
            </ComboboxItem>
          )}
        </ComboboxList>
      </ComboboxContent>
    </Combobox>
  )
}
```

## Basic

A simple combobox with a list of frameworks.

### Example: combobox-basic

```tsx
"use client";

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

const frameworks = [
  "Next.js",
  "SvelteKit",
  "Nuxt.js",
  "Remix",
  "Astro",
] as const;

export default function ComboboxBasic() {
  return (
    <Combobox items={frameworks}>
      <ComboboxInput placeholder="Select a framework" />
      <ComboboxContent>
        <ComboboxEmpty>No items found.</ComboboxEmpty>
        <ComboboxList>
          {(item) => (
            <ComboboxItem key={item} value={item}>
              {item}
            </ComboboxItem>
          )}
        </ComboboxList>
      </ComboboxContent>
    </Combobox>
  );
}
```

## Multiple

A combobox with multiple selection using `multiple` and `ComboboxChips`.

### Example: combobox-multiple

```tsx
"use client";

import {
  Combobox,
  ComboboxChip,
  ComboboxChips,
  ComboboxChipsInput,
  ComboboxContent,
  ComboboxEmpty,
  ComboboxItem,
  ComboboxList,
  ComboboxValue,
  useComboboxAnchor,
} from "@workspace/ui/components/combobox";
import * as React from "react";

const frameworks = [
  "Next.js",
  "SvelteKit",
  "Nuxt.js",
  "Remix",
  "Astro",
] as const;

export function ComboboxMultiple() {
  const anchor = useComboboxAnchor();

  return (
    <Combobox
      multiple
      autoHighlight
      items={frameworks}
      defaultValue={[frameworks[0]]}
    >
      <ComboboxChips ref={anchor} className="w-full max-w-xs">
        <ComboboxValue>
          {(values) => (
            <React.Fragment>
              {values.map((value: string) => (
                <ComboboxChip key={value}>{value}</ComboboxChip>
              ))}
              <ComboboxChipsInput />
            </React.Fragment>
          )}
        </ComboboxValue>
      </ComboboxChips>
      <ComboboxContent anchor={anchor}>
        <ComboboxEmpty>No items found.</ComboboxEmpty>
        <ComboboxList>
          {(item) => (
            <ComboboxItem key={item} value={item}>
              {item}
            </ComboboxItem>
          )}
        </ComboboxList>
      </ComboboxContent>
    </Combobox>
  );
}

export default ComboboxMultiple;
```

## Clear Button

Use the `showClear` prop to show a clear button.

### Example: combobox-clear

```tsx
"use client";

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

const frameworks = [
  "Next.js",
  "SvelteKit",
  "Nuxt.js",
  "Remix",
  "Astro",
] as const;

export function ComboboxWithClear() {
  return (
    <Combobox items={frameworks} defaultValue={frameworks[0]}>
      <ComboboxInput placeholder="Select a framework" showClear />
      <ComboboxContent>
        <ComboboxEmpty>No items found.</ComboboxEmpty>
        <ComboboxList>
          {(item) => (
            <ComboboxItem key={item} value={item}>
              {item}
            </ComboboxItem>
          )}
        </ComboboxList>
      </ComboboxContent>
    </Combobox>
  );
}

export default ComboboxWithClear;
```

## Groups

Use `ComboboxGroup` and `ComboboxSeparator` to group items.

### Example: combobox-groups

```tsx
"use client";

import {
  Combobox,
  ComboboxCollection,
  ComboboxContent,
  ComboboxEmpty,
  ComboboxGroup,
  ComboboxInput,
  ComboboxItem,
  ComboboxLabel,
  ComboboxList,
  ComboboxSeparator,
} from "@workspace/ui/components/combobox";

const timezones = [
  {
    value: "Americas",
    items: [
      "(GMT-5) New York",
      "(GMT-8) Los Angeles",
      "(GMT-6) Chicago",
      "(GMT-5) Toronto",
      "(GMT-8) Vancouver",
      "(GMT-3) São Paulo",
    ],
  },
  {
    value: "Europe",
    items: [
      "(GMT+0) London",
      "(GMT+1) Paris",
      "(GMT+1) Berlin",
      "(GMT+1) Rome",
      "(GMT+1) Madrid",
      "(GMT+1) Amsterdam",
    ],
  },
  {
    value: "Asia/Pacific",
    items: [
      "(GMT+9) Tokyo",
      "(GMT+8) Shanghai",
      "(GMT+8) Singapore",
      "(GMT+4) Dubai",
      "(GMT+11) Sydney",
      "(GMT+9) Seoul",
    ],
  },
] as const;

export function ComboboxWithGroupsAndSeparator() {
  return (
    <Combobox items={timezones}>
      <ComboboxInput placeholder="Select a timezone" />
      <ComboboxContent>
        <ComboboxEmpty>No timezones found.</ComboboxEmpty>
        <ComboboxList>
          {(group, index) => (
            <ComboboxGroup key={group.value} items={group.items}>
              <ComboboxLabel>{group.value}</ComboboxLabel>
              <ComboboxCollection>
                {(item) => (
                  <ComboboxItem key={item} value={item}>
                    {item}
                  </ComboboxItem>
                )}
              </ComboboxCollection>
              {index < timezones.length - 1 && <ComboboxSeparator />}
            </ComboboxGroup>
          )}
        </ComboboxList>
      </ComboboxContent>
    </Combobox>
  );
}

export default ComboboxWithGroupsAndSeparator;
```

## Custom Items

You can render a custom component inside `ComboboxItem`.

### Example: combobox-custom

```tsx
"use client";

import {
  Combobox,
  ComboboxContent,
  ComboboxEmpty,
  ComboboxInput,
  ComboboxItem,
  ComboboxList,
} from "@workspace/ui/components/combobox";
import {
  Item,
  ItemContent,
  ItemDescription,
  ItemTitle,
} from "@workspace/ui/components/item";

const countries = [
  { code: "", value: "", continent: "", label: "Select country" },
  {
    code: "ar",
    value: "argentina",
    label: "Argentina",
    continent: "South America",
  },
  { code: "au", value: "australia", label: "Australia", continent: "Oceania" },
  { code: "br", value: "brazil", label: "Brazil", continent: "South America" },
  { code: "ca", value: "canada", label: "Canada", continent: "North America" },
  { code: "cn", value: "china", label: "China", continent: "Asia" },
  {
    code: "co",
    value: "colombia",
    label: "Colombia",
    continent: "South America",
  },
  { code: "eg", value: "egypt", label: "Egypt", continent: "Africa" },
  { code: "fr", value: "france", label: "France", continent: "Europe" },
  { code: "de", value: "germany", label: "Germany", continent: "Europe" },
  { code: "it", value: "italy", label: "Italy", continent: "Europe" },
  { code: "jp", value: "japan", label: "Japan", continent: "Asia" },
  { code: "ke", value: "kenya", label: "Kenya", continent: "Africa" },
  { code: "mx", value: "mexico", label: "Mexico", continent: "North America" },
  {
    code: "nz",
    value: "new-zealand",
    label: "New Zealand",
    continent: "Oceania",
  },
  { code: "ng", value: "nigeria", label: "Nigeria", continent: "Africa" },
  {
    code: "za",
    value: "south-africa",
    label: "South Africa",
    continent: "Africa",
  },
  { code: "kr", value: "south-korea", label: "South Korea", continent: "Asia" },
  {
    code: "gb",
    value: "united-kingdom",
    label: "United Kingdom",
    continent: "Europe",
  },
  {
    code: "us",
    value: "united-states",
    label: "United States",
    continent: "North America",
  },
];

export function ComboboxWithCustomItems() {
  return (
    <Combobox
      items={countries.filter((country) => country.code !== "")}
      itemToStringValue={(country: (typeof countries)[number]) => country.label}
    >
      <ComboboxInput placeholder="Search countries..." />
      <ComboboxContent>
        <ComboboxEmpty>No countries found.</ComboboxEmpty>
        <ComboboxList>
          {(country) => (
            <ComboboxItem key={country.code} value={country}>
              <Item size="xs" className="p-0">
                <ItemContent>
                  <ItemTitle className="whitespace-nowrap">
                    {country.label}
                  </ItemTitle>
                  <ItemDescription>
                    {country.continent} ({country.code})
                  </ItemDescription>
                </ItemContent>
              </Item>
            </ComboboxItem>
          )}
        </ComboboxList>
      </ComboboxContent>
    </Combobox>
  );
}

export default ComboboxWithCustomItems;
```

## Invalid

Use the `aria-invalid` prop to make the combobox invalid.

### Example: combobox-invalid

```tsx
"use client";

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

const frameworks = [
  "Next.js",
  "SvelteKit",
  "Nuxt.js",
  "Remix",
  "Astro",
] as const;

export function ComboboxInvalid() {
  return (
    <Combobox items={frameworks}>
      <ComboboxInput placeholder="Select a framework" aria-invalid="true" />
      <ComboboxContent>
        <ComboboxEmpty>No items found.</ComboboxEmpty>
        <ComboboxList>
          {(item) => (
            <ComboboxItem key={item} value={item}>
              {item}
            </ComboboxItem>
          )}
        </ComboboxList>
      </ComboboxContent>
    </Combobox>
  );
}

export default ComboboxInvalid;
```

## Disabled

Use the `disabled` prop to disable the combobox.

### Example: combobox-disabled

```tsx
"use client";

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

const frameworks = [
  "Next.js",
  "SvelteKit",
  "Nuxt.js",
  "Remix",
  "Astro",
] as const;

export function ComboboxDisabled() {
  return (
    <Combobox items={frameworks}>
      <ComboboxInput placeholder="Select a framework" disabled />
      <ComboboxContent>
        <ComboboxEmpty>No items found.</ComboboxEmpty>
        <ComboboxList>
          {(item) => (
            <ComboboxItem key={item} value={item}>
              {item}
            </ComboboxItem>
          )}
        </ComboboxList>
      </ComboboxContent>
    </Combobox>
  );
}

export default ComboboxDisabled;
```

## Auto Highlight

Use the `autoHighlight` prop to automatically highlight the first item on filter.

### Example: combobox-auto-highlight

```tsx
"use client";

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

const frameworks = [
  "Next.js",
  "SvelteKit",
  "Nuxt.js",
  "Remix",
  "Astro",
] as const;

export function ComboboxAutoHighlight() {
  return (
    <Combobox items={frameworks} autoHighlight>
      <ComboboxInput placeholder="Select a framework" />
      <ComboboxContent>
        <ComboboxEmpty>No items found.</ComboboxEmpty>
        <ComboboxList>
          {(item) => (
            <ComboboxItem key={item} value={item}>
              {item}
            </ComboboxItem>
          )}
        </ComboboxList>
      </ComboboxContent>
    </Combobox>
  );
}

export default ComboboxAutoHighlight;
```

## Popup

You can trigger the combobox from a button or any other component by using the `render` prop. Move the `ComboboxInput` inside the `ComboboxContent`.

### Example: combobox-popup

```tsx
"use client";

import { Button } from "@workspace/ui/components/button";
import {
  Combobox,
  ComboboxContent,
  ComboboxEmpty,
  ComboboxInput,
  ComboboxItem,
  ComboboxList,
  ComboboxTrigger,
  ComboboxValue,
} from "@workspace/ui/components/combobox";

const countries = [
  { code: "", value: "", continent: "", label: "Select country" },
  {
    code: "ar",
    value: "argentina",
    label: "Argentina",
    continent: "South America",
  },
  { code: "au", value: "australia", label: "Australia", continent: "Oceania" },
  { code: "br", value: "brazil", label: "Brazil", continent: "South America" },
  { code: "ca", value: "canada", label: "Canada", continent: "North America" },
  { code: "cn", value: "china", label: "China", continent: "Asia" },
  {
    code: "co",
    value: "colombia",
    label: "Colombia",
    continent: "South America",
  },
  { code: "eg", value: "egypt", label: "Egypt", continent: "Africa" },
  { code: "fr", value: "france", label: "France", continent: "Europe" },
  { code: "de", value: "germany", label: "Germany", continent: "Europe" },
  { code: "it", value: "italy", label: "Italy", continent: "Europe" },
  { code: "jp", value: "japan", label: "Japan", continent: "Asia" },
  { code: "ke", value: "kenya", label: "Kenya", continent: "Africa" },
  { code: "mx", value: "mexico", label: "Mexico", continent: "North America" },
  {
    code: "nz",
    value: "new-zealand",
    label: "New Zealand",
    continent: "Oceania",
  },
  { code: "ng", value: "nigeria", label: "Nigeria", continent: "Africa" },
  {
    code: "za",
    value: "south-africa",
    label: "South Africa",
    continent: "Africa",
  },
  { code: "kr", value: "south-korea", label: "South Korea", continent: "Asia" },
  {
    code: "gb",
    value: "united-kingdom",
    label: "United Kingdom",
    continent: "Europe",
  },
  {
    code: "us",
    value: "united-states",
    label: "United States",
    continent: "North America",
  },
];

export function ComboboxPopup() {
  return (
    <Combobox items={countries} defaultValue={countries[0]}>
      <ComboboxTrigger
        render={
          <Button
            variant="outline"
            className="w-64 justify-between font-normal"
          />
        }
      >
        <ComboboxValue />
      </ComboboxTrigger>
      <ComboboxContent>
        <ComboboxInput showTrigger={false} placeholder="Search" />
        <ComboboxEmpty>No items found.</ComboboxEmpty>
        <ComboboxList>
          {(item) => (
            <ComboboxItem key={item.code} value={item}>
              {item.label}
            </ComboboxItem>
          )}
        </ComboboxList>
      </ComboboxContent>
    </Combobox>
  );
}

export default ComboboxPopup;
```

## Input Group

You can add an addon to the combobox by using the `InputGroupAddon` component inside the `ComboboxInput`.

### Example: combobox-input-group

```tsx
"use client";

import {
  Combobox,
  ComboboxCollection,
  ComboboxContent,
  ComboboxEmpty,
  ComboboxGroup,
  ComboboxInput,
  ComboboxItem,
  ComboboxLabel,
  ComboboxList,
} from "@workspace/ui/components/combobox";
import { InputGroupAddon } from "@workspace/ui/components/input-group";
import { GlobeIcon } from "lucide-react";

const timezones = [
  {
    value: "Americas",
    items: [
      "(GMT-5) New York",
      "(GMT-8) Los Angeles",
      "(GMT-6) Chicago",
      "(GMT-5) Toronto",
      "(GMT-8) Vancouver",
      "(GMT-3) São Paulo",
    ],
  },
  {
    value: "Europe",
    items: [
      "(GMT+0) London",
      "(GMT+1) Paris",
      "(GMT+1) Berlin",
      "(GMT+1) Rome",
      "(GMT+1) Madrid",
      "(GMT+1) Amsterdam",
    ],
  },
  {
    value: "Asia/Pacific",
    items: [
      "(GMT+9) Tokyo",
      "(GMT+8) Shanghai",
      "(GMT+8) Singapore",
      "(GMT+4) Dubai",
      "(GMT+11) Sydney",
      "(GMT+9) Seoul",
    ],
  },
] as const;

export function ComboxboxInputGroup() {
  return (
    <Combobox items={timezones}>
      <ComboboxInput placeholder="Select a timezone">
        <InputGroupAddon>
          <GlobeIcon />
        </InputGroupAddon>
      </ComboboxInput>
      <ComboboxContent alignOffset={-28} className="w-60">
        <ComboboxEmpty>No timezones found.</ComboboxEmpty>
        <ComboboxList>
          {(group) => (
            <ComboboxGroup key={group.value} items={group.items}>
              <ComboboxLabel>{group.value}</ComboboxLabel>
              <ComboboxCollection>
                {(item) => (
                  <ComboboxItem key={item} value={item}>
                    {item}
                  </ComboboxItem>
                )}
              </ComboboxCollection>
            </ComboboxGroup>
          )}
        </ComboboxList>
      </ComboboxContent>
    </Combobox>
  );
}

export default ComboxboxInputGroup;
```

## RTL

To enable RTL support in shadcn/ui, see the [RTL configuration guide](https://ui.shadcn.com/docs/rtl).

### Example: combobox-rtl

```tsx
"use client";

import {
  Combobox,
  ComboboxChip,
  ComboboxChips,
  ComboboxChipsInput,
  ComboboxContent,
  ComboboxEmpty,
  ComboboxItem,
  ComboboxList,
  ComboboxValue,
  useComboboxAnchor,
} from "@workspace/ui/components/combobox";
import { Field, FieldLabel } from "@workspace/ui/components/field";
import * as React from "react";
import { type Translations, useTranslation } from "./support";

const categories = [
  "technology",
  "design",
  "business",
  "marketing",
  "education",
  "health",
] as const;

const translations: Translations = {
  en: {
    dir: "ltr",
    values: {
      label: "Categories",
      placeholder: "Add categories",
      empty: "No categories found.",
      technology: "Technology",
      design: "Design",
      business: "Business",
      marketing: "Marketing",
      education: "Education",
      health: "Health",
    },
  },
  ar: {
    dir: "rtl",
    values: {
      label: "الفئات",
      placeholder: "أضف فئات",
      empty: "لم يتم العثور على فئات.",
      technology: "التكنولوجيا",
      design: "التصميم",
      business: "الأعمال",
      marketing: "التسويق",
      education: "التعليم",
      health: "الصحة",
    },
  },
  he: {
    dir: "rtl",
    values: {
      label: "קטגוריות",
      placeholder: "הוסף קטגוריות",
      empty: "לא נמצאו קטגוריות.",
      technology: "טכנולוגיה",
      design: "עיצוב",
      business: "עסקים",
      marketing: "שיווק",
      education: "חינוך",
      health: "בריאות",
    },
  },
};

export function ComboboxRtl() {
  const { dir, t, language } = useTranslation(translations, "ar");
  const anchor = useComboboxAnchor();

  const categoryLabels: Record<string, string> = {
    technology: t.technology,
    design: t.design,
    business: t.business,
    marketing: t.marketing,
    education: t.education,
    health: t.health,
  };

  return (
    <Field className="mx-auto w-full max-w-xs">
      <FieldLabel>{t.label}</FieldLabel>
      <Combobox
        multiple
        autoHighlight
        items={categories}
        defaultValue={[categories[0]]}
        itemToStringValue={(item: (typeof categories)[number]) =>
          categoryLabels[item] || item
        }
      >
        <ComboboxChips ref={anchor}>
          <ComboboxValue>
            {(values) => (
              <React.Fragment>
                {values.map((value: string) => (
                  <ComboboxChip key={value}>
                    {categoryLabels[value] || value}
                  </ComboboxChip>
                ))}
                <ComboboxChipsInput placeholder={t.placeholder} />
              </React.Fragment>
            )}
          </ComboboxValue>
        </ComboboxChips>
        <ComboboxContent
          anchor={anchor}
          dir={dir}
          data-lang={dir === "rtl" ? language : undefined}
        >
          <ComboboxEmpty>{t.empty}</ComboboxEmpty>
          <ComboboxList>
            {(item) => (
              <ComboboxItem key={item} value={item}>
                {categoryLabels[item] || item}
              </ComboboxItem>
            )}
          </ComboboxList>
        </ComboboxContent>
      </Combobox>
    </Field>
  );
}

export default ComboboxRtl;
```

## API Reference

See the [Base UI](https://base-ui.com/react/components/combobox#api-reference) documentation for more information.

- [Documentation](https://base-ui.com/react/components/combobox)
- [API reference](https://base-ui.com/react/components/combobox#api-reference)


---

# Command

Command menu for search and quick actions.

Page: https://sui.draco.dev/docs/components/command

### Example: command-demo

```tsx
import {
  Command,
  CommandEmpty,
  CommandGroup,
  CommandInput,
  CommandItem,
  CommandList,
  CommandSeparator,
  CommandShortcut,
} from "@workspace/ui/components/command";
import {
  Calculator,
  Calendar,
  CreditCard,
  Settings,
  Smile,
  User,
} from "lucide-react";

export function CommandDemo() {
  return (
    <Command className="max-w-sm rounded-lg border">
      <CommandInput placeholder="Type a command or search..." />
      <CommandList>
        <CommandEmpty>No results found.</CommandEmpty>
        <CommandGroup heading="Suggestions">
          <CommandItem>
            <Calendar />
            <span>Calendar</span>
          </CommandItem>
          <CommandItem>
            <Smile />
            <span>Search Emoji</span>
          </CommandItem>
          <CommandItem disabled>
            <Calculator />
            <span>Calculator</span>
          </CommandItem>
        </CommandGroup>
        <CommandSeparator />
        <CommandGroup heading="Settings">
          <CommandItem>
            <User />
            <span>Profile</span>
            <CommandShortcut>⌘P</CommandShortcut>
          </CommandItem>
          <CommandItem>
            <CreditCard />
            <span>Billing</span>
            <CommandShortcut>⌘B</CommandShortcut>
          </CommandItem>
          <CommandItem>
            <Settings />
            <span>Settings</span>
            <CommandShortcut>⌘S</CommandShortcut>
          </CommandItem>
        </CommandGroup>
      </CommandList>
    </Command>
  );
}

export default CommandDemo;
```

## About

The `<Command />` component uses the [`cmdk`](https://github.com/dip/cmdk) component by [Dip](https://www.dip.org/).

## Installation

```bash
bunx --bun shadcn@latest add @sui/command
```

Install with the shadcn CLI or use the shared `@workspace/ui` package. Follow the [installation guide](/docs/installation) to configure the registry, load styles, and choose import aliases.

## Usage

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

```tsx showLineNumbers
<Command className="max-w-sm rounded-lg border">
  <CommandInput placeholder="Type a command or search..." />
  <CommandList>
    <CommandEmpty>No results found.</CommandEmpty>
    <CommandGroup heading="Suggestions">
      <CommandItem>Calendar</CommandItem>
      <CommandItem>Search Emoji</CommandItem>
      <CommandItem>Calculator</CommandItem>
    </CommandGroup>
    <CommandSeparator />
    <CommandGroup heading="Settings">
      <CommandItem>Profile</CommandItem>
      <CommandItem>Billing</CommandItem>
      <CommandItem>Settings</CommandItem>
    </CommandGroup>
  </CommandList>
</Command>
```

## Composition

Use the following composition to build a `Command`:

```text
Command
├── CommandInput
└── CommandList
    ├── CommandEmpty
    ├── CommandGroup
    │   ├── CommandItem
    │   └── CommandItem
    ├── CommandSeparator
    └── CommandGroup
        ├── CommandItem
        └── CommandItem
```

## Basic

A simple command menu in a dialog.

### Example: command-basic

```tsx
"use client";

import { Button } from "@workspace/ui/components/button";
import {
  Command,
  CommandDialog,
  CommandEmpty,
  CommandGroup,
  CommandInput,
  CommandItem,
  CommandList,
} from "@workspace/ui/components/command";
import * as React from "react";

export function CommandBasic() {
  const [open, setOpen] = React.useState(false);

  return (
    <div className="flex flex-col gap-4">
      <Button onClick={() => setOpen(true)} variant="outline" className="w-fit">
        Open Menu
      </Button>
      <CommandDialog open={open} onOpenChange={setOpen}>
        <Command>
          <CommandInput placeholder="Type a command or search..." />
          <CommandList>
            <CommandEmpty>No results found.</CommandEmpty>
            <CommandGroup heading="Suggestions">
              <CommandItem>Calendar</CommandItem>
              <CommandItem>Search Emoji</CommandItem>
              <CommandItem>Calculator</CommandItem>
            </CommandGroup>
          </CommandList>
        </Command>
      </CommandDialog>
    </div>
  );
}

export default CommandBasic;
```

## Shortcuts

### Example: command-shortcuts

```tsx
"use client";

import { Button } from "@workspace/ui/components/button";
import {
  Command,
  CommandDialog,
  CommandEmpty,
  CommandGroup,
  CommandInput,
  CommandItem,
  CommandList,
  CommandShortcut,
} from "@workspace/ui/components/command";
import { CreditCardIcon, SettingsIcon, UserIcon } from "lucide-react";
import * as React from "react";

export function CommandWithShortcuts() {
  const [open, setOpen] = React.useState(false);

  return (
    <div className="flex flex-col gap-4">
      <Button onClick={() => setOpen(true)} variant="outline" className="w-fit">
        Open Menu
      </Button>
      <CommandDialog open={open} onOpenChange={setOpen}>
        <Command>
          <CommandInput placeholder="Type a command or search..." />
          <CommandList>
            <CommandEmpty>No results found.</CommandEmpty>
            <CommandGroup heading="Settings">
              <CommandItem>
                <UserIcon />
                <span>Profile</span>
                <CommandShortcut>⌘P</CommandShortcut>
              </CommandItem>
              <CommandItem>
                <CreditCardIcon />
                <span>Billing</span>
                <CommandShortcut>⌘B</CommandShortcut>
              </CommandItem>
              <CommandItem>
                <SettingsIcon />
                <span>Settings</span>
                <CommandShortcut>⌘S</CommandShortcut>
              </CommandItem>
            </CommandGroup>
          </CommandList>
        </Command>
      </CommandDialog>
    </div>
  );
}

export default CommandWithShortcuts;
```

## Groups

A command menu with groups, icons and separators.

### Example: command-groups

```tsx
"use client";

import { Button } from "@workspace/ui/components/button";
import {
  Command,
  CommandDialog,
  CommandEmpty,
  CommandGroup,
  CommandInput,
  CommandItem,
  CommandList,
  CommandSeparator,
  CommandShortcut,
} from "@workspace/ui/components/command";
import {
  CalculatorIcon,
  CalendarIcon,
  CreditCardIcon,
  SettingsIcon,
  SmileIcon,
  UserIcon,
} from "lucide-react";
import * as React from "react";

export function CommandWithGroups() {
  const [open, setOpen] = React.useState(false);

  return (
    <div className="flex flex-col gap-4">
      <Button onClick={() => setOpen(true)} variant="outline" className="w-fit">
        Open Menu
      </Button>
      <CommandDialog open={open} onOpenChange={setOpen}>
        <Command>
          <CommandInput placeholder="Type a command or search..." />
          <CommandList>
            <CommandEmpty>No results found.</CommandEmpty>
            <CommandGroup heading="Suggestions">
              <CommandItem>
                <CalendarIcon />
                <span>Calendar</span>
              </CommandItem>
              <CommandItem>
                <SmileIcon />
                <span>Search Emoji</span>
              </CommandItem>
              <CommandItem>
                <CalculatorIcon />
                <span>Calculator</span>
              </CommandItem>
            </CommandGroup>
            <CommandSeparator />
            <CommandGroup heading="Settings">
              <CommandItem>
                <UserIcon />
                <span>Profile</span>
                <CommandShortcut>⌘P</CommandShortcut>
              </CommandItem>
              <CommandItem>
                <CreditCardIcon />
                <span>Billing</span>
                <CommandShortcut>⌘B</CommandShortcut>
              </CommandItem>
              <CommandItem>
                <SettingsIcon />
                <span>Settings</span>
                <CommandShortcut>⌘S</CommandShortcut>
              </CommandItem>
            </CommandGroup>
          </CommandList>
        </Command>
      </CommandDialog>
    </div>
  );
}

export default CommandWithGroups;
```

## Scrollable

Scrollable command menu with multiple items.

### Example: command-scrollable

```tsx
"use client";

import { Button } from "@workspace/ui/components/button";
import {
  Command,
  CommandDialog,
  CommandEmpty,
  CommandGroup,
  CommandInput,
  CommandItem,
  CommandList,
  CommandSeparator,
  CommandShortcut,
} from "@workspace/ui/components/command";
import {
  BellIcon,
  CalculatorIcon,
  CalendarIcon,
  ClipboardPasteIcon,
  CodeIcon,
  CopyIcon,
  CreditCardIcon,
  FileTextIcon,
  FolderIcon,
  FolderPlusIcon,
  HelpCircleIcon,
  HomeIcon,
  ImageIcon,
  InboxIcon,
  LayoutGridIcon,
  ListIcon,
  PlusIcon,
  ScissorsIcon,
  SettingsIcon,
  TrashIcon,
  UserIcon,
  ZoomInIcon,
  ZoomOutIcon,
} from "lucide-react";
import * as React from "react";

export function CommandManyItems() {
  const [open, setOpen] = React.useState(false);

  return (
    <div className="flex flex-col gap-4">
      <Button onClick={() => setOpen(true)} variant="outline" className="w-fit">
        Open Menu
      </Button>
      <CommandDialog open={open} onOpenChange={setOpen}>
        <Command>
          <CommandInput placeholder="Type a command or search..." />
          <CommandList>
            <CommandEmpty>No results found.</CommandEmpty>
            <CommandGroup heading="Navigation">
              <CommandItem>
                <HomeIcon />
                <span>Home</span>
                <CommandShortcut>⌘H</CommandShortcut>
              </CommandItem>
              <CommandItem>
                <InboxIcon />
                <span>Inbox</span>
                <CommandShortcut>⌘I</CommandShortcut>
              </CommandItem>
              <CommandItem>
                <FileTextIcon />
                <span>Documents</span>
                <CommandShortcut>⌘D</CommandShortcut>
              </CommandItem>
              <CommandItem>
                <FolderIcon />
                <span>Folders</span>
                <CommandShortcut>⌘F</CommandShortcut>
              </CommandItem>
            </CommandGroup>
            <CommandSeparator />
            <CommandGroup heading="Actions">
              <CommandItem>
                <PlusIcon />
                <span>New File</span>
                <CommandShortcut>⌘N</CommandShortcut>
              </CommandItem>
              <CommandItem>
                <FolderPlusIcon />
                <span>New Folder</span>
                <CommandShortcut>⇧⌘N</CommandShortcut>
              </CommandItem>
              <CommandItem>
                <CopyIcon />
                <span>Copy</span>
                <CommandShortcut>⌘C</CommandShortcut>
              </CommandItem>
              <CommandItem>
                <ScissorsIcon />
                <span>Cut</span>
                <CommandShortcut>⌘X</CommandShortcut>
              </CommandItem>
              <CommandItem>
                <ClipboardPasteIcon />
                <span>Paste</span>
                <CommandShortcut>⌘V</CommandShortcut>
              </CommandItem>
              <CommandItem>
                <TrashIcon />
                <span>Delete</span>
                <CommandShortcut>⌫</CommandShortcut>
              </CommandItem>
            </CommandGroup>
            <CommandSeparator />
            <CommandGroup heading="View">
              <CommandItem>
                <LayoutGridIcon />
                <span>Grid View</span>
              </CommandItem>
              <CommandItem>
                <ListIcon />
                <span>List View</span>
              </CommandItem>
              <CommandItem>
                <ZoomInIcon />
                <span>Zoom In</span>
                <CommandShortcut>⌘+</CommandShortcut>
              </CommandItem>
              <CommandItem>
                <ZoomOutIcon />
                <span>Zoom Out</span>
                <CommandShortcut>⌘-</CommandShortcut>
              </CommandItem>
            </CommandGroup>
            <CommandSeparator />
            <CommandGroup heading="Account">
              <CommandItem>
                <UserIcon />
                <span>Profile</span>
                <CommandShortcut>⌘P</CommandShortcut>
              </CommandItem>
              <CommandItem>
                <CreditCardIcon />
                <span>Billing</span>
                <CommandShortcut>⌘B</CommandShortcut>
              </CommandItem>
              <CommandItem>
                <SettingsIcon />
                <span>Settings</span>
                <CommandShortcut>⌘S</CommandShortcut>
              </CommandItem>
              <CommandItem>
                <BellIcon />
                <span>Notifications</span>
              </CommandItem>
              <CommandItem>
                <HelpCircleIcon />
                <span>Help & Support</span>
              </CommandItem>
            </CommandGroup>
            <CommandSeparator />
            <CommandGroup heading="Tools">
              <CommandItem>
                <CalculatorIcon />
                <span>Calculator</span>
              </CommandItem>
              <CommandItem>
                <CalendarIcon />
                <span>Calendar</span>
              </CommandItem>
              <CommandItem>
                <ImageIcon />
                <span>Image Editor</span>
              </CommandItem>
              <CommandItem>
                <CodeIcon />
                <span>Code Editor</span>
              </CommandItem>
            </CommandGroup>
          </CommandList>
        </Command>
      </CommandDialog>
    </div>
  );
}

export default CommandManyItems;
```

## RTL

To enable RTL support in shadcn/ui, see the [RTL configuration guide](https://ui.shadcn.com/docs/rtl).

### Example: command-rtl

```tsx
"use client";

import {
  Command,
  CommandEmpty,
  CommandGroup,
  CommandInput,
  CommandItem,
  CommandList,
  CommandSeparator,
  CommandShortcut,
} from "@workspace/ui/components/command";
import {
  Calculator,
  Calendar,
  CreditCard,
  Settings,
  Smile,
  User,
} from "lucide-react";
import { type Translations, useTranslation } from "./support";

const translations: Translations = {
  en: {
    dir: "ltr",
    values: {
      placeholder: "Type a command or search...",
      empty: "No results found.",
      suggestions: "Suggestions",
      calendar: "Calendar",
      searchEmoji: "Search Emoji",
      calculator: "Calculator",
      settings: "Settings",
      profile: "Profile",
      billing: "Billing",
    },
  },
  ar: {
    dir: "rtl",
    values: {
      placeholder: "اكتب أمرًا أو ابحث...",
      empty: "لم يتم العثور على نتائج.",
      suggestions: "اقتراحات",
      calendar: "التقويم",
      searchEmoji: "البحث عن الرموز التعبيرية",
      calculator: "الآلة الحاسبة",
      settings: "الإعدادات",
      profile: "الملف الشخصي",
      billing: "الفوترة",
    },
  },
  he: {
    dir: "rtl",
    values: {
      placeholder: "הקלד פקודה או חפש...",
      empty: "לא נמצאו תוצאות.",
      suggestions: "הצעות",
      calendar: "לוח שנה",
      searchEmoji: "חפש אמוג'י",
      calculator: "מחשבון",
      settings: "הגדרות",
      profile: "פרופיל",
      billing: "חיוב",
    },
  },
};

export function CommandRtl() {
  const { dir, t } = useTranslation(translations, "ar");

  return (
    <Command className="max-w-sm rounded-lg border" dir={dir}>
      <CommandInput placeholder={t.placeholder} dir={dir} />
      <CommandList>
        <CommandEmpty>{t.empty}</CommandEmpty>
        <CommandGroup heading={t.suggestions}>
          <CommandItem>
            <Calendar />
            <span>{t.calendar}</span>
          </CommandItem>
          <CommandItem>
            <Smile />
            <span>{t.searchEmoji}</span>
          </CommandItem>
          <CommandItem disabled>
            <Calculator />
            <span>{t.calculator}</span>
          </CommandItem>
        </CommandGroup>
        <CommandSeparator />
        <CommandGroup heading={t.settings}>
          <CommandItem>
            <User />
            <span>{t.profile}</span>
            <CommandShortcut>⌘P</CommandShortcut>
          </CommandItem>
          <CommandItem>
            <CreditCard />
            <span>{t.billing}</span>
            <CommandShortcut>⌘B</CommandShortcut>
          </CommandItem>
          <CommandItem>
            <Settings />
            <span>{t.settings}</span>
            <CommandShortcut>⌘S</CommandShortcut>
          </CommandItem>
        </CommandGroup>
      </CommandList>
    </Command>
  );
}

export default CommandRtl;
```

## API Reference

See the [cmdk](https://github.com/dip/cmdk) documentation for more information.

- [Documentation](https://github.com/dip/cmdk)


---

# Context Menu

Displays a menu of actions triggered by a right click.

Page: https://sui.draco.dev/docs/components/context-menu

### Example: context-menu-demo

```tsx
import {
  ContextMenu,
  ContextMenuCheckboxItem,
  ContextMenuContent,
  ContextMenuGroup,
  ContextMenuItem,
  ContextMenuLabel,
  ContextMenuRadioGroup,
  ContextMenuRadioItem,
  ContextMenuSeparator,
  ContextMenuShortcut,
  ContextMenuSub,
  ContextMenuSubContent,
  ContextMenuSubTrigger,
  ContextMenuTrigger,
} from "@workspace/ui/components/context-menu";

export function ContextMenuDemo() {
  return (
    <ContextMenu>
      <ContextMenuTrigger className="flex aspect-video w-full max-w-xs items-center justify-center rounded-xl border border-dashed text-sm">
        <span className="pointer-fine:inline-block hidden">
          Right click here
        </span>
        <span className="pointer-coarse:inline-block hidden">
          Long press here
        </span>
      </ContextMenuTrigger>
      <ContextMenuContent className="w-48">
        <ContextMenuGroup>
          <ContextMenuItem>
            Back
            <ContextMenuShortcut>⌘[</ContextMenuShortcut>
          </ContextMenuItem>
          <ContextMenuItem disabled>
            Forward
            <ContextMenuShortcut>⌘]</ContextMenuShortcut>
          </ContextMenuItem>
          <ContextMenuItem>
            Reload
            <ContextMenuShortcut>⌘R</ContextMenuShortcut>
          </ContextMenuItem>
          <ContextMenuSub>
            <ContextMenuSubTrigger>More Tools</ContextMenuSubTrigger>
            <ContextMenuSubContent className="w-44">
              <ContextMenuGroup>
                <ContextMenuItem>Save Page...</ContextMenuItem>
                <ContextMenuItem>Create Shortcut...</ContextMenuItem>
                <ContextMenuItem>Name Window...</ContextMenuItem>
              </ContextMenuGroup>
              <ContextMenuSeparator />
              <ContextMenuGroup>
                <ContextMenuItem>Developer Tools</ContextMenuItem>
              </ContextMenuGroup>
              <ContextMenuSeparator />
              <ContextMenuGroup>
                <ContextMenuItem variant="destructive">Delete</ContextMenuItem>
              </ContextMenuGroup>
            </ContextMenuSubContent>
          </ContextMenuSub>
        </ContextMenuGroup>
        <ContextMenuSeparator />
        <ContextMenuGroup>
          <ContextMenuCheckboxItem checked>
            Show Bookmarks
          </ContextMenuCheckboxItem>
          <ContextMenuCheckboxItem>Show Full URLs</ContextMenuCheckboxItem>
        </ContextMenuGroup>
        <ContextMenuSeparator />
        <ContextMenuGroup>
          <ContextMenuRadioGroup value="pedro">
            <ContextMenuLabel>People</ContextMenuLabel>
            <ContextMenuRadioItem value="pedro">
              Pedro Duarte
            </ContextMenuRadioItem>
            <ContextMenuRadioItem value="colm">Colm Tuite</ContextMenuRadioItem>
          </ContextMenuRadioGroup>
        </ContextMenuGroup>
      </ContextMenuContent>
    </ContextMenu>
  );
}

export default ContextMenuDemo;
```

## Installation

```bash
bunx --bun shadcn@latest add @sui/context-menu
```

Install with the shadcn CLI or use the shared `@workspace/ui` package. Follow the [installation guide](/docs/installation) to configure the registry, load styles, and choose import aliases.

## Usage

```tsx showLineNumbers
import {
  ContextMenu,
  ContextMenuContent,
  ContextMenuItem,
  ContextMenuTrigger,
} from "@workspace/ui/components/context-menu"
```

```tsx showLineNumbers
<ContextMenu>
  <ContextMenuTrigger>Right click here</ContextMenuTrigger>
  <ContextMenuContent>
    <ContextMenuItem>Profile</ContextMenuItem>
    <ContextMenuItem>Billing</ContextMenuItem>
    <ContextMenuItem>Team</ContextMenuItem>
    <ContextMenuItem>Subscription</ContextMenuItem>
  </ContextMenuContent>
</ContextMenu>
```

## Composition

Use the following composition to build a `ContextMenu`:

```text
ContextMenu
├── ContextMenuTrigger
└── ContextMenuContent
    ├── ContextMenuGroup
    │   ├── ContextMenuLabel
    │   ├── ContextMenuItem
    │   └── ContextMenuItem
    ├── ContextMenuSeparator
    ├── ContextMenuGroup
    │   ├── ContextMenuLabel
    │   ├── ContextMenuCheckboxItem
    │   └── ContextMenuCheckboxItem
    ├── ContextMenuSeparator
    ├── ContextMenuGroup
    │   ├── ContextMenuLabel
    │   └── ContextMenuRadioGroup
    │       ├── ContextMenuRadioItem
    │       └── ContextMenuRadioItem
    └── ContextMenuSub
        ├── ContextMenuSubTrigger
        └── ContextMenuSubContent
            └── ContextMenuGroup
                ├── ContextMenuItem
                └── ContextMenuItem
```

## Basic

A simple context menu with a few actions.

### Example: context-menu-basic

```tsx
import {
  ContextMenu,
  ContextMenuContent,
  ContextMenuGroup,
  ContextMenuItem,
  ContextMenuTrigger,
} from "@workspace/ui/components/context-menu";

export function ContextMenuBasic() {
  return (
    <ContextMenu>
      <ContextMenuTrigger className="flex aspect-video w-full max-w-xs items-center justify-center rounded-xl border border-dashed text-sm">
        <span className="pointer-fine:inline-block hidden">
          Right click here
        </span>
        <span className="pointer-coarse:inline-block hidden">
          Long press here
        </span>
      </ContextMenuTrigger>
      <ContextMenuContent>
        <ContextMenuGroup>
          <ContextMenuItem>Back</ContextMenuItem>
          <ContextMenuItem disabled>Forward</ContextMenuItem>
          <ContextMenuItem>Reload</ContextMenuItem>
        </ContextMenuGroup>
      </ContextMenuContent>
    </ContextMenu>
  );
}

export default ContextMenuBasic;
```

## Submenu

Use `ContextMenuSub` to nest secondary actions.

### Example: context-menu-submenu

```tsx
import {
  ContextMenu,
  ContextMenuContent,
  ContextMenuGroup,
  ContextMenuItem,
  ContextMenuSeparator,
  ContextMenuShortcut,
  ContextMenuSub,
  ContextMenuSubContent,
  ContextMenuSubTrigger,
  ContextMenuTrigger,
} from "@workspace/ui/components/context-menu";

export function ContextMenuSubmenu() {
  return (
    <ContextMenu>
      <ContextMenuTrigger className="flex aspect-video w-full max-w-xs items-center justify-center rounded-xl border border-dashed text-sm">
        <span className="pointer-fine:inline-block hidden">
          Right click here
        </span>
        <span className="pointer-coarse:inline-block hidden">
          Long press here
        </span>
      </ContextMenuTrigger>
      <ContextMenuContent>
        <ContextMenuGroup>
          <ContextMenuItem>
            Copy
            <ContextMenuShortcut>⌘C</ContextMenuShortcut>
          </ContextMenuItem>
          <ContextMenuItem>
            Cut
            <ContextMenuShortcut>⌘X</ContextMenuShortcut>
          </ContextMenuItem>
        </ContextMenuGroup>
        <ContextMenuSub>
          <ContextMenuSubTrigger>More Tools</ContextMenuSubTrigger>
          <ContextMenuSubContent>
            <ContextMenuGroup>
              <ContextMenuItem>Save Page...</ContextMenuItem>
              <ContextMenuItem>Create Shortcut...</ContextMenuItem>
              <ContextMenuItem>Name Window...</ContextMenuItem>
            </ContextMenuGroup>
            <ContextMenuSeparator />
            <ContextMenuGroup>
              <ContextMenuItem>Developer Tools</ContextMenuItem>
            </ContextMenuGroup>
            <ContextMenuSeparator />
            <ContextMenuGroup>
              <ContextMenuItem variant="destructive">Delete</ContextMenuItem>
            </ContextMenuGroup>
          </ContextMenuSubContent>
        </ContextMenuSub>
      </ContextMenuContent>
    </ContextMenu>
  );
}

export default ContextMenuSubmenu;
```

## Shortcuts

Add `ContextMenuShortcut` to show keyboard hints.

### Example: context-menu-shortcuts

```tsx
import {
  ContextMenu,
  ContextMenuContent,
  ContextMenuGroup,
  ContextMenuItem,
  ContextMenuSeparator,
  ContextMenuShortcut,
  ContextMenuTrigger,
} from "@workspace/ui/components/context-menu";

export function ContextMenuShortcuts() {
  return (
    <ContextMenu>
      <ContextMenuTrigger className="flex aspect-video w-full max-w-xs items-center justify-center rounded-xl border border-dashed text-sm">
        <span className="pointer-fine:inline-block hidden">
          Right click here
        </span>
        <span className="pointer-coarse:inline-block hidden">
          Long press here
        </span>
      </ContextMenuTrigger>
      <ContextMenuContent>
        <ContextMenuGroup>
          <ContextMenuItem>
            Back
            <ContextMenuShortcut>⌘[</ContextMenuShortcut>
          </ContextMenuItem>
          <ContextMenuItem disabled>
            Forward
            <ContextMenuShortcut>⌘]</ContextMenuShortcut>
          </ContextMenuItem>
          <ContextMenuItem>
            Reload
            <ContextMenuShortcut>⌘R</ContextMenuShortcut>
          </ContextMenuItem>
        </ContextMenuGroup>
        <ContextMenuSeparator />
        <ContextMenuGroup>
          <ContextMenuItem>
            Save
            <ContextMenuShortcut>⌘S</ContextMenuShortcut>
          </ContextMenuItem>
          <ContextMenuItem>
            Save As...
            <ContextMenuShortcut>⇧⌘S</ContextMenuShortcut>
          </ContextMenuItem>
        </ContextMenuGroup>
      </ContextMenuContent>
    </ContextMenu>
  );
}

export default ContextMenuShortcuts;
```

## Groups

Group related actions and separate them with dividers.

### Example: context-menu-groups

```tsx
import {
  ContextMenu,
  ContextMenuContent,
  ContextMenuGroup,
  ContextMenuItem,
  ContextMenuLabel,
  ContextMenuSeparator,
  ContextMenuShortcut,
  ContextMenuTrigger,
} from "@workspace/ui/components/context-menu";

export function ContextMenuGroups() {
  return (
    <ContextMenu>
      <ContextMenuTrigger className="flex aspect-video w-full max-w-xs items-center justify-center rounded-xl border border-dashed text-sm">
        <span className="pointer-fine:inline-block hidden">
          Right click here
        </span>
        <span className="pointer-coarse:inline-block hidden">
          Long press here
        </span>
      </ContextMenuTrigger>
      <ContextMenuContent>
        <ContextMenuGroup>
          <ContextMenuLabel>File</ContextMenuLabel>
          <ContextMenuItem>
            New File
            <ContextMenuShortcut>⌘N</ContextMenuShortcut>
          </ContextMenuItem>
          <ContextMenuItem>
            Open File
            <ContextMenuShortcut>⌘O</ContextMenuShortcut>
          </ContextMenuItem>
          <ContextMenuItem>
            Save
            <ContextMenuShortcut>⌘S</ContextMenuShortcut>
          </ContextMenuItem>
        </ContextMenuGroup>
        <ContextMenuSeparator />
        <ContextMenuGroup>
          <ContextMenuLabel>Edit</ContextMenuLabel>
          <ContextMenuItem>
            Undo
            <ContextMenuShortcut>⌘Z</ContextMenuShortcut>
          </ContextMenuItem>
          <ContextMenuItem>
            Redo
            <ContextMenuShortcut>⇧⌘Z</ContextMenuShortcut>
          </ContextMenuItem>
        </ContextMenuGroup>
        <ContextMenuSeparator />
        <ContextMenuGroup>
          <ContextMenuItem>
            Cut
            <ContextMenuShortcut>⌘X</ContextMenuShortcut>
          </ContextMenuItem>
          <ContextMenuItem>
            Copy
            <ContextMenuShortcut>⌘C</ContextMenuShortcut>
          </ContextMenuItem>
          <ContextMenuItem>
            Paste
            <ContextMenuShortcut>⌘V</ContextMenuShortcut>
          </ContextMenuItem>
        </ContextMenuGroup>
        <ContextMenuSeparator />
        <ContextMenuGroup>
          <ContextMenuItem variant="destructive">
            Delete
            <ContextMenuShortcut>⌫</ContextMenuShortcut>
          </ContextMenuItem>
        </ContextMenuGroup>
      </ContextMenuContent>
    </ContextMenu>
  );
}

export default ContextMenuGroups;
```

## Icons

Combine icons with labels for quick scanning.

### Example: context-menu-icons

```tsx
import {
  ContextMenu,
  ContextMenuContent,
  ContextMenuGroup,
  ContextMenuItem,
  ContextMenuSeparator,
  ContextMenuTrigger,
} from "@workspace/ui/components/context-menu";
import {
  ClipboardPasteIcon,
  CopyIcon,
  ScissorsIcon,
  TrashIcon,
} from "lucide-react";

export function ContextMenuIcons() {
  return (
    <ContextMenu>
      <ContextMenuTrigger className="flex aspect-video w-full max-w-xs items-center justify-center rounded-xl border border-dashed text-sm">
        <span className="pointer-fine:inline-block hidden">
          Right click here
        </span>
        <span className="pointer-coarse:inline-block hidden">
          Long press here
        </span>
      </ContextMenuTrigger>
      <ContextMenuContent>
        <ContextMenuGroup>
          <ContextMenuItem>
            <CopyIcon />
            Copy
          </ContextMenuItem>
          <ContextMenuItem>
            <ScissorsIcon />
            Cut
          </ContextMenuItem>
          <ContextMenuItem>
            <ClipboardPasteIcon />
            Paste
          </ContextMenuItem>
        </ContextMenuGroup>
        <ContextMenuSeparator />
        <ContextMenuGroup>
          <ContextMenuItem variant="destructive">
            <TrashIcon />
            Delete
          </ContextMenuItem>
        </ContextMenuGroup>
      </ContextMenuContent>
    </ContextMenu>
  );
}

export default ContextMenuIcons;
```

## Checkboxes

Use `ContextMenuCheckboxItem` for toggles.

### Example: context-menu-checkboxes

```tsx
import {
  ContextMenu,
  ContextMenuCheckboxItem,
  ContextMenuContent,
  ContextMenuGroup,
  ContextMenuTrigger,
} from "@workspace/ui/components/context-menu";

export function ContextMenuCheckboxes() {
  return (
    <ContextMenu>
      <ContextMenuTrigger className="flex aspect-video w-full max-w-xs items-center justify-center rounded-xl border border-dashed text-sm">
        <span className="pointer-fine:inline-block hidden">
          Right click here
        </span>
        <span className="pointer-coarse:inline-block hidden">
          Long press here
        </span>
      </ContextMenuTrigger>
      <ContextMenuContent>
        <ContextMenuGroup>
          <ContextMenuCheckboxItem defaultChecked>
            Show Bookmarks Bar
          </ContextMenuCheckboxItem>
          <ContextMenuCheckboxItem>Show Full URLs</ContextMenuCheckboxItem>
          <ContextMenuCheckboxItem defaultChecked>
            Show Developer Tools
          </ContextMenuCheckboxItem>
        </ContextMenuGroup>
      </ContextMenuContent>
    </ContextMenu>
  );
}

export default ContextMenuCheckboxes;
```

## Radio

Use `ContextMenuRadioItem` for exclusive choices.

### Example: context-menu-radio

```tsx
"use client";

import {
  ContextMenu,
  ContextMenuContent,
  ContextMenuGroup,
  ContextMenuLabel,
  ContextMenuRadioGroup,
  ContextMenuRadioItem,
  ContextMenuSeparator,
  ContextMenuTrigger,
} from "@workspace/ui/components/context-menu";
import * as React from "react";

export function ContextMenuRadio() {
  const [user, setUser] = React.useState("pedro");
  const [theme, setTheme] = React.useState("light");

  return (
    <ContextMenu>
      <ContextMenuTrigger className="flex aspect-video w-full max-w-xs items-center justify-center rounded-xl border border-dashed text-sm">
        <span className="pointer-fine:inline-block hidden">
          Right click here
        </span>
        <span className="pointer-coarse:inline-block hidden">
          Long press here
        </span>
      </ContextMenuTrigger>
      <ContextMenuContent>
        <ContextMenuGroup>
          <ContextMenuLabel>People</ContextMenuLabel>
          <ContextMenuRadioGroup value={user} onValueChange={setUser}>
            <ContextMenuRadioItem value="pedro">
              Pedro Duarte
            </ContextMenuRadioItem>
            <ContextMenuRadioItem value="colm">Colm Tuite</ContextMenuRadioItem>
          </ContextMenuRadioGroup>
        </ContextMenuGroup>
        <ContextMenuSeparator />
        <ContextMenuGroup>
          <ContextMenuLabel>Theme</ContextMenuLabel>
          <ContextMenuRadioGroup value={theme} onValueChange={setTheme}>
            <ContextMenuRadioItem value="light">Light</ContextMenuRadioItem>
            <ContextMenuRadioItem value="dark">Dark</ContextMenuRadioItem>
            <ContextMenuRadioItem value="system">System</ContextMenuRadioItem>
          </ContextMenuRadioGroup>
        </ContextMenuGroup>
      </ContextMenuContent>
    </ContextMenu>
  );
}

export default ContextMenuRadio;
```

## Destructive

Use `variant="destructive"` to style the menu item as destructive.

### Example: context-menu-destructive

```tsx
import {
  ContextMenu,
  ContextMenuContent,
  ContextMenuGroup,
  ContextMenuItem,
  ContextMenuSeparator,
  ContextMenuTrigger,
} from "@workspace/ui/components/context-menu";
import { PencilIcon, ShareIcon, TrashIcon } from "lucide-react";

export function ContextMenuDestructive() {
  return (
    <ContextMenu>
      <ContextMenuTrigger className="flex aspect-video w-full max-w-xs items-center justify-center rounded-xl border border-dashed text-sm">
        <span className="pointer-fine:inline-block hidden">
          Right click here
        </span>
        <span className="pointer-coarse:inline-block hidden">
          Long press here
        </span>
      </ContextMenuTrigger>
      <ContextMenuContent>
        <ContextMenuGroup>
          <ContextMenuItem>
            <PencilIcon />
            Edit
          </ContextMenuItem>
          <ContextMenuItem>
            <ShareIcon />
            Share
          </ContextMenuItem>
        </ContextMenuGroup>
        <ContextMenuSeparator />
        <ContextMenuGroup>
          <ContextMenuItem variant="destructive">
            <TrashIcon />
            Delete
          </ContextMenuItem>
        </ContextMenuGroup>
      </ContextMenuContent>
    </ContextMenu>
  );
}

export default ContextMenuDestructive;
```

## Sides

Control submenu placement with side and align props.

### Example: context-menu-sides

```tsx
import {
  ContextMenu,
  ContextMenuContent,
  ContextMenuGroup,
  ContextMenuItem,
  ContextMenuTrigger,
} from "@workspace/ui/components/context-menu";

export function ContextMenuSides() {
  return (
    <div className="grid w-full max-w-sm grid-cols-2 gap-4">
      <ContextMenu>
        <ContextMenuTrigger className="flex aspect-video w-full max-w-xs items-center justify-center rounded-xl border border-dashed text-sm">
          <span className="pointer-fine:inline-block hidden">
            Right click (top)
          </span>
          <span className="pointer-coarse:inline-block hidden">
            Long press (top)
          </span>
        </ContextMenuTrigger>
        <ContextMenuContent side="top">
          <ContextMenuGroup>
            <ContextMenuItem>Back</ContextMenuItem>
            <ContextMenuItem>Forward</ContextMenuItem>
            <ContextMenuItem>Reload</ContextMenuItem>
          </ContextMenuGroup>
        </ContextMenuContent>
      </ContextMenu>
      <ContextMenu>
        <ContextMenuTrigger className="flex aspect-video w-full max-w-xs items-center justify-center rounded-xl border border-dashed text-sm">
          <span className="pointer-fine:inline-block hidden">
            Right click (right)
          </span>
          <span className="pointer-coarse:inline-block hidden">
            Long press (right)
          </span>
        </ContextMenuTrigger>
        <ContextMenuContent side="right">
          <ContextMenuGroup>
            <ContextMenuItem>Back</ContextMenuItem>
            <ContextMenuItem>Forward</ContextMenuItem>
            <ContextMenuItem>Reload</ContextMenuItem>
          </ContextMenuGroup>
        </ContextMenuContent>
      </ContextMenu>
      <ContextMenu>
        <ContextMenuTrigger className="flex aspect-video w-full max-w-xs items-center justify-center rounded-xl border border-dashed text-sm">
          <span className="pointer-fine:inline-block hidden">
            Right click (bottom)
          </span>
          <span className="pointer-coarse:inline-block hidden">
            Long press (bottom)
          </span>
        </ContextMenuTrigger>
        <ContextMenuContent side="bottom">
          <ContextMenuGroup>
            <ContextMenuItem>Back</ContextMenuItem>
            <ContextMenuItem>Forward</ContextMenuItem>
            <ContextMenuItem>Reload</ContextMenuItem>
          </ContextMenuGroup>
        </ContextMenuContent>
      </ContextMenu>
      <ContextMenu>
        <ContextMenuTrigger className="flex aspect-video w-full max-w-xs items-center justify-center rounded-xl border border-dashed text-sm">
          <span className="pointer-fine:inline-block hidden">
            Right click (left)
          </span>
          <span className="pointer-coarse:inline-block hidden">
            Long press (left)
          </span>
        </ContextMenuTrigger>
        <ContextMenuContent side="left">
          <ContextMenuGroup>
            <ContextMenuItem>Back</ContextMenuItem>
            <ContextMenuItem>Forward</ContextMenuItem>
            <ContextMenuItem>Reload</ContextMenuItem>
          </ContextMenuGroup>
        </ContextMenuContent>
      </ContextMenu>
    </div>
  );
}

export default ContextMenuSides;
```

## RTL

To enable RTL support in shadcn/ui, see the [RTL configuration guide](https://ui.shadcn.com/docs/rtl).

### Example: context-menu-rtl

```tsx
"use client";

import {
  ContextMenu,
  ContextMenuCheckboxItem,
  ContextMenuContent,
  ContextMenuGroup,
  ContextMenuItem,
  ContextMenuLabel,
  ContextMenuRadioGroup,
  ContextMenuRadioItem,
  ContextMenuSeparator,
  ContextMenuShortcut,
  ContextMenuSub,
  ContextMenuSubContent,
  ContextMenuSubTrigger,
  ContextMenuTrigger,
} from "@workspace/ui/components/context-menu";
import { ArrowLeftIcon, ArrowRightIcon, RotateCwIcon } from "lucide-react";
import * as React from "react";
import { type Translations, useTranslation } from "./support";

const translations: Translations = {
  en: {
    dir: "ltr",
    values: {
      rightClick: "Right click here",
      longPress: "Long press here",
      navigation: "Navigation",
      back: "Back",
      forward: "Forward",
      reload: "Reload",
      moreTools: "More Tools",
      savePage: "Save Page...",
      createShortcut: "Create Shortcut...",
      nameWindow: "Name Window...",
      developerTools: "Developer Tools",
      delete: "Delete",
      showBookmarks: "Show Bookmarks",
      showFullUrls: "Show Full URLs",
      people: "People",
      pedro: "Pedro Duarte",
      colm: "Colm Tuite",
    },
  },
  ar: {
    dir: "rtl",
    values: {
      rightClick: "انقر بزر الماوس الأيمن هنا",
      longPress: "اضغط مطولاً هنا",
      navigation: "التنقل",
      back: "رجوع",
      forward: "تقدم",
      reload: "إعادة تحميل",
      moreTools: "المزيد من الأدوات",
      savePage: "حفظ الصفحة...",
      createShortcut: "إنشاء اختصار...",
      nameWindow: "تسمية النافذة...",
      developerTools: "أدوات المطور",
      delete: "حذف",
      showBookmarks: "إظهار الإشارات المرجعية",
      showFullUrls: "إظهار عناوين URL الكاملة",
      people: "الأشخاص",
      pedro: "Pedro Duarte",
      colm: "Colm Tuite",
    },
  },
  he: {
    dir: "rtl",
    values: {
      rightClick: "לחץ לחיצה ימנית כאן",
      longPress: "לחץ לחיצה ארוכה כאן",
      navigation: "ניווט",
      back: "חזור",
      forward: "קדימה",
      reload: "רענן",
      moreTools: "כלים נוספים",
      savePage: "שמור עמוד...",
      createShortcut: "צור קיצור דרך...",
      nameWindow: "שם חלון...",
      developerTools: "כלי מפתח",
      delete: "מחק",
      showBookmarks: "הצג סימניות",
      showFullUrls: "הצג כתובות URL מלאות",
      people: "אנשים",
      pedro: "Pedro Duarte",
      colm: "Colm Tuite",
    },
  },
};

export function ContextMenuRtl() {
  const { dir, t, language } = useTranslation(translations, "ar");
  const [people, setPeople] = React.useState("pedro");

  return (
    <ContextMenu>
      <ContextMenuTrigger className="flex aspect-video w-full max-w-xs items-center justify-center rounded-xl border border-dashed text-sm">
        <span className="pointer-fine:inline-block hidden">{t.rightClick}</span>
        <span className="pointer-coarse:inline-block hidden">
          {t.longPress}
        </span>
      </ContextMenuTrigger>
      <ContextMenuContent
        className="w-48"
        dir={dir}
        data-lang={dir === "rtl" ? language : undefined}
      >
        <ContextMenuGroup>
          <ContextMenuSub>
            <ContextMenuSubTrigger>{t.navigation}</ContextMenuSubTrigger>
            <ContextMenuSubContent
              className="w-44"
              dir={dir}
              data-lang={dir === "rtl" ? language : undefined}
            >
              <ContextMenuGroup>
                <ContextMenuItem>
                  <ArrowLeftIcon />
                  {t.back}
                  <ContextMenuShortcut>⌘[</ContextMenuShortcut>
                </ContextMenuItem>
                <ContextMenuItem disabled>
                  <ArrowRightIcon />
                  {t.forward}
                  <ContextMenuShortcut>⌘]</ContextMenuShortcut>
                </ContextMenuItem>
                <ContextMenuItem>
                  <RotateCwIcon />
                  {t.reload}
                  <ContextMenuShortcut>⌘R</ContextMenuShortcut>
                </ContextMenuItem>
              </ContextMenuGroup>
            </ContextMenuSubContent>
          </ContextMenuSub>
          <ContextMenuSub>
            <ContextMenuSubTrigger>{t.moreTools}</ContextMenuSubTrigger>
            <ContextMenuSubContent
              className="w-44"
              dir={dir}
              data-lang={dir === "rtl" ? language : undefined}
            >
              <ContextMenuGroup>
                <ContextMenuItem>{t.savePage}</ContextMenuItem>
                <ContextMenuItem>{t.createShortcut}</ContextMenuItem>
                <ContextMenuItem>{t.nameWindow}</ContextMenuItem>
              </ContextMenuGroup>
              <ContextMenuSeparator />
              <ContextMenuGroup>
                <ContextMenuItem>{t.developerTools}</ContextMenuItem>
              </ContextMenuGroup>
              <ContextMenuSeparator />
              <ContextMenuGroup>
                <ContextMenuItem variant="destructive">
                  {t.delete}
                </ContextMenuItem>
              </ContextMenuGroup>
            </ContextMenuSubContent>
          </ContextMenuSub>
        </ContextMenuGroup>
        <ContextMenuSeparator />
        <ContextMenuGroup>
          <ContextMenuCheckboxItem checked>
            {t.showBookmarks}
          </ContextMenuCheckboxItem>
          <ContextMenuCheckboxItem>{t.showFullUrls}</ContextMenuCheckboxItem>
        </ContextMenuGroup>
        <ContextMenuSeparator />
        <ContextMenuGroup>
          <ContextMenuRadioGroup value={people} onValueChange={setPeople}>
            <ContextMenuLabel>{t.people}</ContextMenuLabel>
            <ContextMenuRadioItem value="pedro">{t.pedro}</ContextMenuRadioItem>
            <ContextMenuRadioItem value="colm">{t.colm}</ContextMenuRadioItem>
          </ContextMenuRadioGroup>
        </ContextMenuGroup>
      </ContextMenuContent>
    </ContextMenu>
  );
}

export default ContextMenuRtl;
```

Use `side="inline-end"` to place the menu on the logical right side of the trigger.

```tsx showLineNumbers
<ContextMenu>
  <ContextMenuTrigger>Right click here</ContextMenuTrigger>
  <ContextMenuContent side="inline-end">
    <ContextMenuItem>Profile</ContextMenuItem>
    <ContextMenuItem>Billing</ContextMenuItem>
    <ContextMenuItem>Team</ContextMenuItem>
    <ContextMenuItem>Subscription</ContextMenuItem>
  </ContextMenuContent>
</ContextMenu>
```

## API Reference

See the [Base UI](https://base-ui.com/react/components/context-menu#api-reference) documentation for more information.

- [Documentation](https://base-ui.com/react/components/context-menu)
- [API reference](https://base-ui.com/react/components/context-menu#api-reference)


---

# Dialog

A window overlaid on either the primary window or another dialog window, rendering the content underneath inert.

Page: https://sui.draco.dev/docs/components/dialog

### Example: dialog-demo

```tsx
import { Button } from "@workspace/ui/components/button";
import {
  Dialog,
  DialogClose,
  DialogContent,
  DialogDescription,
  DialogFooter,
  DialogHeader,
  DialogTitle,
  DialogTrigger,
} from "@workspace/ui/components/dialog";
import { Field, FieldGroup } from "@workspace/ui/components/field";
import { Input } from "@workspace/ui/components/input";
import { Label } from "@workspace/ui/components/label";
import { useId as usePreviewId } from "react";

export function DialogDemo() {
  const previewId = usePreviewId();

  return (
    <Dialog>
      <form>
        <DialogTrigger render={<Button variant="outline" />}>
          Open Dialog
        </DialogTrigger>
        <DialogContent className="sm:max-w-sm">
          <DialogHeader>
            <DialogTitle>Edit profile</DialogTitle>
            <DialogDescription>
              Make changes to your profile here. Click save when you&apos;re
              done.
            </DialogDescription>
          </DialogHeader>
          <FieldGroup>
            <Field>
              <Label htmlFor={`${previewId}-name-1`}>Name</Label>
              <Input
                id={`${previewId}-name-1`}
                name="name"
                defaultValue="Pedro Duarte"
              />
            </Field>
            <Field>
              <Label htmlFor={`${previewId}-username-1`}>Username</Label>
              <Input
                id={`${previewId}-username-1`}
                name="username"
                defaultValue="@peduarte"
              />
            </Field>
          </FieldGroup>
          <DialogFooter>
            <DialogClose render={<Button variant="outline" />}>
              Cancel
            </DialogClose>
            <Button type="submit">Save changes</Button>
          </DialogFooter>
        </DialogContent>
      </form>
    </Dialog>
  );
}

export default DialogDemo;
```

## Installation

```bash
bunx --bun shadcn@latest add @sui/dialog
```

Install with the shadcn CLI or use the shared `@workspace/ui` package. Follow the [installation guide](/docs/installation) to configure the registry, load styles, and choose import aliases.

## Usage

```tsx showLineNumbers
import {
  Dialog,
  DialogContent,
  DialogDescription,
  DialogHeader,
  DialogTitle,
  DialogTrigger,
} from "@workspace/ui/components/dialog"
```

```tsx showLineNumbers
<Dialog>
  <DialogTrigger>Open</DialogTrigger>
  <DialogContent>
    <DialogHeader>
      <DialogTitle>Are you absolutely sure?</DialogTitle>
      <DialogDescription>
        This action cannot be undone. This will permanently delete your account
        and remove your data from our servers.
      </DialogDescription>
    </DialogHeader>
  </DialogContent>
</Dialog>
```

## Composition

Use the following composition to build a `Dialog`:

```text
Dialog
├── DialogTrigger
└── DialogContent
    ├── DialogHeader
    │   ├── DialogTitle
    │   └── DialogDescription
    └── DialogFooter
```

## Custom Close Button

Replace the default close control with your own button.

### Example: dialog-close-button

```tsx
import { Button } from "@workspace/ui/components/button";
import {
  Dialog,
  DialogClose,
  DialogContent,
  DialogDescription,
  DialogFooter,
  DialogHeader,
  DialogTitle,
  DialogTrigger,
} from "@workspace/ui/components/dialog";
import { Input } from "@workspace/ui/components/input";
import { Label } from "@workspace/ui/components/label";
import { useId as usePreviewId } from "react";

export function DialogCloseButton() {
  const previewId = usePreviewId();

  return (
    <Dialog>
      <DialogTrigger render={<Button variant="outline" />}>Share</DialogTrigger>
      <DialogContent className="sm:max-w-md">
        <DialogHeader>
          <DialogTitle>Share link</DialogTitle>
          <DialogDescription>
            Anyone who has this link will be able to view this.
          </DialogDescription>
        </DialogHeader>
        <div className="flex items-center gap-2">
          <div className="grid flex-1 gap-2">
            <Label htmlFor={`${previewId}-link`} className="sr-only">
              Link
            </Label>
            <Input
              id={`${previewId}-link`}
              defaultValue="https://ui.shadcn.com/docs/installation"
              readOnly
            />
          </div>
        </div>
        <DialogFooter className="sm:justify-start">
          <DialogClose render={<Button type="button" />}>Close</DialogClose>
        </DialogFooter>
      </DialogContent>
    </Dialog>
  );
}

export default DialogCloseButton;
```

## No Close Button

Use `showCloseButton={false}` to hide the close button.

### Example: dialog-no-close-button

```tsx
import { Button } from "@workspace/ui/components/button";
import {
  Dialog,
  DialogContent,
  DialogDescription,
  DialogHeader,
  DialogTitle,
  DialogTrigger,
} from "@workspace/ui/components/dialog";

export function DialogNoCloseButton() {
  return (
    <Dialog>
      <DialogTrigger render={<Button variant="outline" />}>
        No Close Button
      </DialogTrigger>
      <DialogContent showCloseButton={false}>
        <DialogHeader>
          <DialogTitle>No Close Button</DialogTitle>
          <DialogDescription>
            This dialog doesn&apos;t have a close button in the top-right
            corner.
          </DialogDescription>
        </DialogHeader>
      </DialogContent>
    </Dialog>
  );
}

export default DialogNoCloseButton;
```

## Sticky Footer

Keep actions visible while the content scrolls.

### Example: dialog-sticky-footer

```tsx
// biome-ignore-all lint/suspicious/noArrayIndexKey: The upstream gallery uses fixed positional fixtures that never reorder.

import { Button } from "@workspace/ui/components/button";
import {
  Dialog,
  DialogClose,
  DialogContent,
  DialogDescription,
  DialogFooter,
  DialogHeader,
  DialogTitle,
  DialogTrigger,
} from "@workspace/ui/components/dialog";

export function DialogStickyFooter() {
  return (
    <Dialog>
      <DialogTrigger render={<Button variant="outline" />}>
        Sticky Footer
      </DialogTrigger>
      <DialogContent>
        <DialogHeader>
          <DialogTitle>Sticky Footer</DialogTitle>
          <DialogDescription>
            This dialog has a sticky footer that stays visible while the content
            scrolls.
          </DialogDescription>
        </DialogHeader>
        <div className="no-scrollbar -mx-4 max-h-[50vh] overflow-y-auto px-4">
          {Array.from({ length: 10 }).map((_, index) => (
            <p key={index} className="mb-4 leading-normal">
              Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do
              eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut
              enim ad minim veniam, quis nostrud exercitation ullamco laboris
              nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in
              reprehenderit in voluptate velit esse cillum dolore eu fugiat
              nulla pariatur. Excepteur sint occaecat cupidatat non proident,
              sunt in culpa qui officia deserunt mollit anim id est laborum.
            </p>
          ))}
        </div>
        <DialogFooter>
          <DialogClose render={<Button variant="outline" />}>Close</DialogClose>
        </DialogFooter>
      </DialogContent>
    </Dialog>
  );
}

export default DialogStickyFooter;
```

## Scrollable Content

Long content can scroll while the header stays in view.

### Example: dialog-scrollable-content

```tsx
// biome-ignore-all lint/suspicious/noArrayIndexKey: The upstream gallery uses fixed positional fixtures that never reorder.

import { Button } from "@workspace/ui/components/button";
import {
  Dialog,
  DialogContent,
  DialogDescription,
  DialogHeader,
  DialogTitle,
  DialogTrigger,
} from "@workspace/ui/components/dialog";

export function DialogScrollableContent() {
  return (
    <Dialog>
      <DialogTrigger render={<Button variant="outline" />}>
        Scrollable Content
      </DialogTrigger>
      <DialogContent>
        <DialogHeader>
          <DialogTitle>Scrollable Content</DialogTitle>
          <DialogDescription>
            This is a dialog with scrollable content.
          </DialogDescription>
        </DialogHeader>
        <div className="no-scrollbar -mx-4 max-h-[50vh] overflow-y-auto px-4">
          {Array.from({ length: 10 }).map((_, index) => (
            <p key={index} className="mb-4 leading-normal">
              Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do
              eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut
              enim ad minim veniam, quis nostrud exercitation ullamco laboris
              nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in
              reprehenderit in voluptate velit esse cillum dolore eu fugiat
              nulla pariatur. Excepteur sint occaecat cupidatat non proident,
              sunt in culpa qui officia deserunt mollit anim id est laborum.
            </p>
          ))}
        </div>
      </DialogContent>
    </Dialog>
  );
}

export default DialogScrollableContent;
```

## RTL

To enable RTL support in shadcn/ui, see the [RTL configuration guide](https://ui.shadcn.com/docs/rtl).

### Example: dialog-rtl

```tsx
"use client";

import { Button } from "@workspace/ui/components/button";
import {
  Dialog,
  DialogClose,
  DialogContent,
  DialogDescription,
  DialogFooter,
  DialogHeader,
  DialogTitle,
  DialogTrigger,
} from "@workspace/ui/components/dialog";
import { Field, FieldGroup } from "@workspace/ui/components/field";
import { Input } from "@workspace/ui/components/input";
import { Label } from "@workspace/ui/components/label";
import { useId as usePreviewId } from "react";
import { type Translations, useTranslation } from "./support";

const translations: Translations = {
  en: {
    dir: "ltr",
    values: {
      openDialog: "Open Dialog",
      editProfile: "Edit profile",
      description:
        "Make changes to your profile here. Click save when you're done.",
      name: "Name",
      username: "Username",
      cancel: "Cancel",
      saveChanges: "Save changes",
    },
  },
  ar: {
    dir: "rtl",
    values: {
      openDialog: "فتح الحوار",
      editProfile: "تعديل الملف الشخصي",
      description:
        "قم بإجراء تغييرات على ملفك الشخصي هنا. انقر فوق حفظ عند الانتهاء.",
      name: "الاسم",
      username: "اسم المستخدم",
      cancel: "إلغاء",
      saveChanges: "حفظ التغييرات",
    },
  },
  he: {
    dir: "rtl",
    values: {
      openDialog: "פתח דיאלוג",
      editProfile: "ערוך פרופיל",
      description: "בצע שינויים בפרופיל שלך כאן. לחץ על שמור כשתסיים.",
      name: "שם",
      username: "שם משתמש",
      cancel: "בטל",
      saveChanges: "שמור שינויים",
    },
  },
};

export function DialogRtl() {
  const previewId = usePreviewId();

  const { dir, t, language } = useTranslation(translations, "ar");

  return (
    <Dialog>
      <form>
        <DialogTrigger render={<Button variant="outline" />}>
          {t.openDialog}
        </DialogTrigger>
        <DialogContent
          className="sm:max-w-sm"
          dir={dir}
          data-lang={dir === "rtl" ? language : undefined}
        >
          <DialogHeader>
            <DialogTitle>{t.editProfile}</DialogTitle>
            <DialogDescription>{t.description}</DialogDescription>
          </DialogHeader>
          <FieldGroup>
            <Field>
              <Label htmlFor={`${previewId}-name-1`}>{t.name}</Label>
              <Input
                id={`${previewId}-name-1`}
                name="name"
                defaultValue="Pedro Duarte"
              />
            </Field>
            <Field>
              <Label htmlFor={`${previewId}-username-1`}>{t.username}</Label>
              <Input
                id={`${previewId}-username-1`}
                name="username"
                defaultValue="@peduarte"
              />
            </Field>
          </FieldGroup>
          <DialogFooter>
            <DialogClose render={<Button variant="outline" />}>
              {t.cancel}
            </DialogClose>
            <Button type="submit">{t.saveChanges}</Button>
          </DialogFooter>
        </DialogContent>
      </form>
    </Dialog>
  );
}

export default DialogRtl;
```

## API Reference

See the [Base UI](https://base-ui.com/react/components/dialog#api-reference) documentation for more information.

- [Documentation](https://base-ui.com/react/components/dialog)
- [API reference](https://base-ui.com/react/components/dialog#api-reference)


---

# Diff Viewer

A line-based code comparison with split and unified views.

Page: https://sui.draco.dev/docs/components/diff-viewer

### Example: diff-viewer-demo

```tsx
"use client";
import { Button } from "@workspace/ui/components/button";
import { DiffViewer } from "@workspace/ui/components/diff-viewer";
import { useState } from "react";
import type { ExampleProps } from "../types";

const oldCode =
  'export const theme = {\n  name: "default",\n  contrast: 4.5,\n};';
const revisedCode =
  'export const theme = {\n  name: "bamboo",\n  contrast: 4.5,\n  focusContrast: 3,\n};';
export default function Example({ locale }: ExampleProps) {
  const chinese = locale === "zh-CN";
  const stateLabels = chinese
    ? {
        identical: "查看相同内容",
        changes: "查看修改",
      }
    : {
        identical: "Show identical content",
        changes: "Show changes",
      };
  const [changed, setChanged] = useState(true);
  return (
    <div className="grid w-full gap-3">
      <Button
        type="button"
        variant="outline"
        className="justify-self-start"
        onClick={() => setChanged((current) => !current)}
      >
        {changed ? stateLabels.identical : stateLabels.changes}
      </Button>
      <DiffViewer
        oldCode={oldCode}
        newCode={changed ? revisedCode : oldCode}
        filename="theme.ts"
        oldTitle={
          chinese
            ? "原版本：设计令牌配置与完整的历史配色说明"
            : "Original: complete design token configuration and historical palette notes"
        }
        newTitle={chinese ? "新版本" : "Updated"}
        lang="typescript"
        labels={
          chinese
            ? {
                before: "修改前",
                after: "修改后",
                viewMode: "差异视图",
                split: "并排",
                unified: "合并",
                writing: "正在编写",
                loading: "正在高亮",
                ready: "就绪",
                error: "无法高亮差异",
                copy: "复制修改后的代码",
                copied: "已复制",
                copyFailed: "复制失败",
              }
            : undefined
        }
      />
    </div>
  );
}
```

## Installation

```bash
bunx --bun shadcn@latest add @sui/diff-viewer
```

Install with the shadcn CLI or use the shared `@workspace/ui` package. Follow the [installation guide](/docs/installation) to configure the registry, load styles, and choose import aliases.

## Usage

```tsx
import { DiffViewer } from "@workspace/ui/components/diff-viewer";

<DiffViewer
  oldCode={'const enabled = false;'}
  newCode={'const enabled = true;'}
  filename="settings.ts"
  lang="typescript"
/>;
```

## Split and unified views

The viewer starts with old and new code in side-by-side panes. Its view controls switch to a unified list. Added and removed lines retain distinct colors and line numbers. `oldTitle`, `newTitle`, and `filename` customize the headings. The comparison operates on lines rather than individual character changes.

Old and new sources are highlighted independently so multiline strings and comments keep each version's own syntax context. Unified unchanged lines use the new source context; split columns retain their respective source context.

Split headings stay on one line and truncate long titles, with the full text available on hover, so unequal headings cannot shift code rows. The first example pairs a long and short heading for narrow-screen comparison.

Use `maxHeight` to limit the scrolling viewport. The viewport is reachable with Tab and supports keyboard scrolling with a visible theme-colored focus ring.

## Streaming revisions

Use `status="streaming"` while `newCode` is being assembled and `"complete"` when it finishes. It follows content near the bottom, pauses after you scroll away, and resumes when you return. The example appends a local JSON revision. Copying is disabled in this example with `copyable={false}`.

### Example: diff-viewer-streaming

```tsx
"use client";
import { Button } from "@workspace/ui/components/button";
import { DiffViewer } from "@workspace/ui/components/diff-viewer";
import { useEffect, useState } from "react";
import type { ExampleProps } from "../types";

const oldCode = '{\n  "name": "default",\n  "enabled": false\n}';
const newLines = [
  "{",
  '  "name": "rose",',
  '  "enabled": true,',
  ...Array.from(
    { length: 12 },
    (_, index) => `  "item${index + 1}": ${index + 1},`,
  ),
  '  "version": 2',
  "}",
];
export default function Example({ locale }: ExampleProps) {
  const chinese = locale === "zh-CN";
  const [count, setCount] = useState(newLines.length);
  const streaming = count < newLines.length;
  useEffect(() => {
    if (!streaming) return;
    const timer = setTimeout(() => setCount(count + 1), 350);
    return () => clearTimeout(timer);
  }, [streaming, count]);
  return (
    <div className="grid w-full gap-3">
      <Button
        type="button"
        variant="outline"
        className="justify-self-start"
        disabled={streaming}
        onClick={() => setCount(1)}
      >
        {chinese ? "重新播放修改" : "Replay changes"}
      </Button>
      <DiffViewer
        oldCode={oldCode}
        newCode={newLines.slice(0, count).join("\n")}
        lang="json"
        status={streaming ? "streaming" : "complete"}
        filename="settings.json"
        maxHeight={180}
        copyable={false}
        labels={
          chinese
            ? {
                before: "修改前",
                after: "修改后",
                viewMode: "差异视图",
                split: "并排",
                unified: "合并",
                writing: "正在编写",
                loading: "正在高亮",
                ready: "就绪",
                error: "无法高亮差异",
                copy: "复制修改后的代码",
                copied: "已复制",
                copyFailed: "复制失败",
              }
            : undefined
        }
      />
    </div>
  );
}
```

## Copying and localization

The copy action copies `newCode`, not a patch or the old version. Highlighting is asynchronous and falls back to plain readable lines when it fails. The surrounding theme is used unless `theme` is provided. Translate `labels` for the two versions, view controls, status, and copy feedback.

## API reference

| Prop | Type | Default / behavior |
| --- | --- | --- |
| `oldCode`, `newCode` | `string` | Required source versions. |
| `oldTitle`, `newTitle` | `string` | Optional version headings. |
| `filename` | `ReactNode` | Optional file heading. |
| `lang` | `string` | `"typescript"`. |
| `theme` | `"light" \| "dark"` | Follows surrounding theme. |
| `status` | `"streaming" \| "complete"` | `"complete"`. |
| `maxHeight` | `number` | `280` pixels. |
| `copyable` | `boolean` | `true`; copies new code. |
| `labels` | `Partial<DiffViewerLabels>` | English labels. |
| `glass` | `boolean` | `false`. |

The module exports `DiffViewerProps` and `DiffViewerLabels`. The line comparison uses [jsdiff](https://github.com/kpdecker/jsdiff).


---

# Direction

A provider component that sets the text direction for your application.

Page: https://sui.draco.dev/docs/components/direction

The `DirectionProvider` component is used to set the text direction (`ltr` or `rtl`) for your application. This is essential for supporting right-to-left languages like Arabic, Hebrew, and Persian.

Here's a preview of the component in RTL mode. Use the language selector to switch the language. To see more examples, look for the RTL section on components pages.

### Example: card-rtl

```tsx
"use client";

import { Button } from "@workspace/ui/components/button";
import {
  Card,
  CardAction,
  CardContent,
  CardDescription,
  CardFooter,
  CardHeader,
  CardTitle,
} from "@workspace/ui/components/card";
import { Input } from "@workspace/ui/components/input";
import { Label } from "@workspace/ui/components/label";
import { useId as usePreviewId } from "react";
import { type Translations, useTranslation } from "./support";

const translations: Translations = {
  en: {
    dir: "ltr",
    values: {
      title: "Login to your account",
      description: "Enter your email below to login to your account",
      signUp: "Sign Up",
      email: "Email",
      emailPlaceholder: "m@example.com",
      password: "Password",
      forgotPassword: "Forgot your password?",
      login: "Login",
      loginWithGoogle: "Login with Google",
    },
  },
  ar: {
    dir: "rtl",
    values: {
      title: "تسجيل الدخول إلى حسابك",
      description: "أدخل بريدك الإلكتروني أدناه لتسجيل الدخول إلى حسابك",
      signUp: "إنشاء حساب",
      email: "البريد الإلكتروني",
      emailPlaceholder: "m@example.com",
      password: "كلمة المرور",
      forgotPassword: "نسيت كلمة المرور؟",
      login: "تسجيل الدخول",
      loginWithGoogle: "تسجيل الدخول باستخدام Google",
    },
  },
  he: {
    dir: "rtl",
    values: {
      title: "התחבר לחשבון שלך",
      description: "הזן את האימייל שלך למטה כדי להתחבר לחשבון שלך",
      signUp: "הירשם",
      email: "אימייל",
      emailPlaceholder: "m@example.com",
      password: "סיסמה",
      forgotPassword: "שכחת את הסיסמה?",
      login: "התחבר",
      loginWithGoogle: "התחבר עם Google",
    },
  },
};

export function CardRtl() {
  const previewId = usePreviewId();

  const { dir, t } = useTranslation(translations, "ar");

  return (
    <Card className="w-full max-w-sm" dir={dir}>
      <CardHeader>
        <CardTitle>{t.title}</CardTitle>
        <CardDescription>{t.description}</CardDescription>
        <CardAction>
          <Button variant="link">{t.signUp}</Button>
        </CardAction>
      </CardHeader>
      <CardContent>
        <form>
          <div className="flex flex-col gap-6">
            <div className="grid gap-2">
              <Label htmlFor={`${previewId}-email-rtl`}>{t.email}</Label>
              <Input
                id={`${previewId}-email-rtl`}
                type="email"
                placeholder={t.emailPlaceholder}
                required
              />
            </div>
            <div className="grid gap-2">
              <div className="flex items-center">
                <Label htmlFor={`${previewId}-password-rtl`}>
                  {t.password}
                </Label>
                <a
                  href="/docs"
                  className="ms-auto inline-block text-sm underline-offset-4 hover:underline"
                >
                  {t.forgotPassword}
                </a>
              </div>
              <Input
                id={`${previewId}-password-rtl`}
                type="password"
                required
              />
            </div>
          </div>
        </form>
      </CardContent>
      <CardFooter className="flex-col gap-2">
        <Button type="submit" className="w-full">
          {t.login}
        </Button>
        <Button variant="outline" className="w-full">
          {t.loginWithGoogle}
        </Button>
      </CardFooter>
    </Card>
  );
}

export default CardRtl;
```

## Installation

```bash
bunx --bun shadcn@latest add @sui/direction
```

Install with the shadcn CLI or use the shared `@workspace/ui` package. Follow the [installation guide](/docs/installation) to configure the registry, load styles, and choose import aliases.

## Usage

```tsx showLineNumbers
import { DirectionProvider } from "@workspace/ui/components/direction"
```

```tsx showLineNumbers
<html dir="rtl">
  <body>
    <DirectionProvider direction="rtl">
      {/* Your app content */}
    </DirectionProvider>
  </body>
</html>
```

## useDirection

The `useDirection` hook is used to get the current direction of the application.

```tsx showLineNumbers
import { useDirection } from "@workspace/ui/components/direction"

function MyComponent() {
  const direction = useDirection()
  return <div>Current direction: {direction}</div>
}
```

- [Documentation](https://base-ui.com/react/utils/direction-provider)
- [API reference](https://base-ui.com/react/utils/direction-provider#api-reference)


---

# Drawer

A drawer component for React.

Page: https://sui.draco.dev/docs/components/drawer

### Example: drawer-demo

```tsx
"use client";

import { Badge } from "@workspace/ui/components/badge";
import { Button } from "@workspace/ui/components/button";
import {
  Drawer,
  DrawerClose,
  DrawerContent,
  DrawerDescription,
  DrawerFooter,
  DrawerHeader,
  DrawerTitle,
  DrawerTrigger,
} from "@workspace/ui/components/drawer";
import {
  Field,
  FieldContent,
  FieldDescription,
  FieldLabel,
  FieldTitle,
} from "@workspace/ui/components/field";
import {
  RadioGroup,
  RadioGroupItem,
} from "@workspace/ui/components/radio-group";
import { toast } from "@workspace/ui/components/toast";
import { useIsMobile } from "@workspace/ui/hooks/use-mobile";
import * as React from "react";

const deliveryTimes = [
  {
    value: "asap",
    id: "delivery-asap",
    label: "Standard delivery",
    description: "25–35 min · Driver assigned now",
    badge: "Fastest",
  },
  {
    value: "5-00",
    id: "delivery-5-00",
    label: "5:00 PM – 5:15 PM",
    description: "Prep starts at 4:45 PM",
  },
  {
    value: "5-30",
    id: "delivery-5-30",
    label: "5:30 PM – 5:45 PM",
    description: "Good if you're heading home",
  },
  {
    value: "6-00",
    id: "delivery-6-00",
    label: "6:00 PM – 6:15 PM",
    description: "Most popular · High demand",
  },
  {
    value: "6-30",
    id: "delivery-6-30",
    label: "6:30 PM – 6:45 PM",
    description: "Last slot before kitchen closes",
  },
];

export function DrawerDemo() {
  const [open, setOpen] = React.useState(false);
  const [deliveryTime, setDeliveryTime] = React.useState("asap");
  const isMobile = useIsMobile();

  function handleConfirm() {
    const selected = deliveryTimes.find((time) => time.value === deliveryTime);

    if (!selected) {
      return;
    }

    setOpen(false);
    toast.add({
      title: "Delivery time confirmed",
      ...{
        description: selected.label,
      },
    });
  }

  return (
    <Drawer
      open={open}
      onOpenChange={setOpen}
      showSwipeHandle={isMobile}
      swipeDirection={isMobile ? "down" : "right"}
    >
      <DrawerTrigger render={<Button variant="secondary" />}>
        Open Drawer
      </DrawerTrigger>
      <DrawerContent>
        <DrawerHeader>
          <DrawerTitle>Pick a delivery time</DrawerTitle>
          <DrawerDescription>
            We&apos;ll prepare your order as soon as possible.
          </DrawerDescription>
        </DrawerHeader>
        <div className="scroll-fade flex-1 overflow-y-auto p-4">
          <RadioGroup
            value={deliveryTime}
            onValueChange={setDeliveryTime}
            className="gap-2"
          >
            {deliveryTimes.map((time) => (
              <FieldLabel key={time.value} htmlFor={time.id}>
                <Field orientation="horizontal">
                  <FieldContent>
                    <FieldTitle className="flex items-center gap-2">
                      {time.label}
                      {time.badge ? (
                        <Badge variant="secondary">{time.badge}</Badge>
                      ) : null}
                    </FieldTitle>
                    <FieldDescription>{time.description}</FieldDescription>
                  </FieldContent>
                  <RadioGroupItem value={time.value} id={time.id} />
                </Field>
              </FieldLabel>
            ))}
          </RadioGroup>
        </div>
        <DrawerFooter>
          <Button onClick={handleConfirm} className="h-[34px]">
            Confirm Delivery Time
          </Button>
          <DrawerClose render={<Button variant="outline" />}>
            Cancel
          </DrawerClose>
        </DrawerFooter>
      </DrawerContent>
    </Drawer>
  );
}

export default DrawerDemo;
```

  The drawer component now uses [Base
  UI](https://base-ui.com/react/components/drawer) instead of Vaul. If you
  installed the previous version, see the [migration
  guide](#migrating-from-vaul).

## Installation

```bash
bunx --bun shadcn@latest add @sui/drawer
```

Install with the shadcn CLI or use the shared `@workspace/ui` package. Follow the [installation guide](/docs/installation) to configure the registry, load styles, and choose import aliases.

## Usage

```tsx showLineNumbers
import {
  Drawer,
  DrawerClose,
  DrawerContent,
  DrawerDescription,
  DrawerFooter,
  DrawerHeader,
  DrawerTitle,
  DrawerTrigger,
} from "@workspace/ui/components/drawer"
```

```tsx showLineNumbers
<Drawer>
  <DrawerTrigger render={<Button variant="outline" />}>Open</DrawerTrigger>
  <DrawerContent>
    <DrawerHeader>
      <DrawerTitle>Are you absolutely sure?</DrawerTitle>
      <DrawerDescription>This action cannot be undone.</DrawerDescription>
    </DrawerHeader>
    <div className="p-4">{/* Content here */}</div>
    <DrawerFooter>
      <Button>Submit</Button>
      <DrawerClose render={<Button variant="outline" />}>Cancel</DrawerClose>
    </DrawerFooter>
  </DrawerContent>
</Drawer>
```

## Composition

Use the following composition to build a `Drawer`:

```text
Drawer
├── DrawerTrigger
└── DrawerContent
    ├── DrawerHeader
    │   ├── DrawerTitle
    │   └── DrawerDescription
    └── DrawerFooter
```

`DrawerContent` composes the portal, overlay, viewport, and popup from Base UI. For lower-level control, `DrawerPortal`, `DrawerOverlay`, and `DrawerSwipeHandle` are also exported.

## Custom Sizes

A vertical drawer sizes itself to its content and is capped at `calc(100dvh - 6rem)` by default. A side drawer spans `75%` of the viewport width, or `24rem` on larger screens.

To customize the height of a vertical drawer, use the `h-*` and `max-h-*` utilities on `DrawerContent`.

```tsx
<DrawerContent className="h-[50vh]">
```

To customize the width of a side drawer, use the `w-*` and `max-w-*` utilities on `DrawerContent`.

```tsx
<DrawerContent className="w-96">
```

When the same component renders in multiple directions, scope an override to one axis using the `data-[swipe-axis=*]` variants.

```tsx
<DrawerContent className="data-[swipe-axis=y]:max-h-[50vh] data-[swipe-axis=x]:w-96">
```

To make a region of the drawer scrollable, make the scroll container a flex item. Avoid `h-full`, which does not resolve inside a content-sized drawer.

```tsx
<DrawerContent>
  <DrawerHeader>...</DrawerHeader>
  <div className="flex-1 overflow-y-auto p-4">{/* Scrollable content */}</div>
  <DrawerFooter>...</DrawerFooter>
</DrawerContent>
```

## Styling

The drawer exposes CSS variables for style-level customization. Set the sizing variables on `DrawerContent`. Set the overlay variable on `[data-slot=drawer-overlay]` in your CSS.

| Variable                       | Default                | Description                                                             |
| ------------------------------ | ---------------------- | ----------------------------------------------------------------------- |
| `--drawer-inset`               | `0px`                  | Floats the drawer from the viewport edges.                              |
| `--drawer-bleed-background`    | `var(--color-popover)` | Fills the gap behind the drawer on swipe overshoot.                     |
| `--drawer-overlay-min-opacity` | `0`                    | Minimum overlay opacity. Defaults to `0.5` when snap points are active. |

The drawer also sets data attributes you can target with variants such as `data-[swipe-direction=down]:` on `DrawerContent`, or `group-data-[swipe-axis=y]/drawer-popup:` on its descendants.

| Attribute                 | Values                        | Set when                              |
| ------------------------- | ----------------------------- | ------------------------------------- |
| `data-swipe-direction`    | `up`, `right`, `down`, `left` | Always.                               |
| `data-swipe-axis`         | `x`, `y`                      | Always.                               |
| `data-snap-points`        | Present                       | The drawer has snap points.           |
| `data-expanded`           | Present                       | The drawer is at the full snap point. |
| `data-swiping`            | Present                       | A swipe is in progress.               |
| `data-nested-drawer-open` | Present                       | A nested drawer is open on top.       |

## Position

Use the `swipeDirection` prop to set the side of the drawer.

Available options are `up`, `right`, `down`, and `left`.

### Example: drawer-sides

```tsx
import { Button } from "@workspace/ui/components/button";
import {
  Drawer,
  DrawerClose,
  DrawerContent,
  DrawerDescription,
  DrawerFooter,
  DrawerHeader,
  DrawerTitle,
  DrawerTrigger,
} from "@workspace/ui/components/drawer";

export function DrawerWithSides() {
  return (
    <Drawer swipeDirection="left">
      <DrawerTrigger render={<Button variant="secondary" />}>
        Open Left Drawer
      </DrawerTrigger>
      <DrawerContent>
        <DrawerHeader>
          <DrawerTitle>Move Goal</DrawerTitle>
          <DrawerDescription>Set your daily activity goal.</DrawerDescription>
        </DrawerHeader>
        <div className="flex-1 p-4">
          <div className="size-full rounded-2xl bg-muted" />
        </div>
        <DrawerFooter>
          <DrawerClose render={<Button />}>Close</DrawerClose>
        </DrawerFooter>
      </DrawerContent>
    </Drawer>
  );
}

export default DrawerWithSides;
```

## Swipe Handle

Use `showSwipeHandle` on `Drawer` to render a swipe handle.

### Example: drawer-swipe-handle

```tsx
"use client";

import { Button } from "@workspace/ui/components/button";
import {
  Drawer,
  DrawerClose,
  DrawerContent,
  DrawerDescription,
  DrawerFooter,
  DrawerHeader,
  DrawerTitle,
  DrawerTrigger,
} from "@workspace/ui/components/drawer";

export function DrawerSwipeHandle() {
  return (
    <Drawer showSwipeHandle>
      <DrawerTrigger render={<Button variant="secondary" />}>
        Open Drawer
      </DrawerTrigger>
      <DrawerContent>
        <DrawerHeader>
          <DrawerTitle>Drawer</DrawerTitle>
          <DrawerDescription>Drawer with a swipe handle.</DrawerDescription>
        </DrawerHeader>
        <div className="flex-1 p-4">
          <div className="rounded-2xl bg-muted group-data-[swipe-axis=x]/drawer-popup:size-full group-data-[swipe-axis=y]/drawer-popup:h-80 group-data-[swipe-axis=y]/drawer-popup:w-full" />
        </div>
        <DrawerFooter>
          <DrawerClose render={<Button />}>Close</DrawerClose>
        </DrawerFooter>
      </DrawerContent>
    </Drawer>
  );
}

export default DrawerSwipeHandle;
```

## Nested

Open drawers from inside another drawer. Parent drawers stay mounted and stack behind the frontmost drawer.

### Example: drawer-nested

```tsx
"use client";

import { Button } from "@workspace/ui/components/button";
import {
  Drawer,
  DrawerClose,
  DrawerContent,
  DrawerDescription,
  DrawerFooter,
  DrawerHeader,
  DrawerTitle,
  DrawerTrigger,
} from "@workspace/ui/components/drawer";
import { useIsMobile } from "@workspace/ui/hooks/use-mobile";

export function DrawerNested() {
  const isMobile = useIsMobile();

  const swipeDirection = isMobile ? "down" : "right";

  return (
    <Drawer showSwipeHandle={isMobile} swipeDirection={swipeDirection}>
      <DrawerTrigger render={<Button variant="secondary" />}>
        Open Drawer
      </DrawerTrigger>
      <DrawerContent>
        <DrawerHeader>
          <DrawerTitle>Drawer</DrawerTitle>
          <DrawerDescription>
            Open another drawer from the same direction.
          </DrawerDescription>
        </DrawerHeader>
        <div className="flex-1 p-4">
          <div className="bg-muted group-data-[swipe-axis=y]/drawer-popup:aspect-video group-data-[swipe-axis=x]/drawer-popup:size-full group-data-[swipe-axis=y]/drawer-popup:w-full" />
        </div>
        <DrawerFooter>
          <Drawer showSwipeHandle={isMobile} swipeDirection={swipeDirection}>
            <DrawerTrigger render={<Button variant="outline" />}>
              Open Nested Drawer
            </DrawerTrigger>
            <DrawerContent>
              <DrawerHeader>
                <DrawerTitle>Nested Drawer</DrawerTitle>
                <DrawerDescription>
                  The parent drawer stays mounted behind this one.
                </DrawerDescription>
              </DrawerHeader>
              <div className="flex-1 p-4">
                <div className="bg-muted group-data-[swipe-axis=y]/drawer-popup:aspect-video group-data-[swipe-axis=x]/drawer-popup:size-full group-data-[swipe-axis=y]/drawer-popup:w-full" />
              </div>
              <DrawerFooter>
                <Drawer
                  showSwipeHandle={isMobile}
                  swipeDirection={swipeDirection}
                >
                  <DrawerTrigger render={<Button variant="outline" />}>
                    Open Third Drawer
                  </DrawerTrigger>
                  <DrawerContent>
                    <DrawerHeader>
                      <DrawerTitle>Third Drawer</DrawerTitle>
                      <DrawerDescription>
                        Two drawers are stacked behind this one.
                      </DrawerDescription>
                    </DrawerHeader>
                    <div className="flex-1 p-4">
                      <div className="bg-muted group-data-[swipe-axis=y]/drawer-popup:aspect-video group-data-[swipe-axis=x]/drawer-popup:size-full group-data-[swipe-axis=y]/drawer-popup:w-full" />
                    </div>
                    <DrawerFooter>
                      <Drawer
                        showSwipeHandle={isMobile}
                        swipeDirection={swipeDirection}
                      >
                        <DrawerTrigger render={<Button variant="outline" />}>
                          Open Fourth Drawer
                        </DrawerTrigger>
                        <DrawerContent>
                          <DrawerHeader>
                            <DrawerTitle>Fourth Drawer</DrawerTitle>
                            <DrawerDescription>
                              This is the frontmost drawer in the stack.
                            </DrawerDescription>
                          </DrawerHeader>
                          <div className="flex-1 p-4">
                            <div className="bg-muted group-data-[swipe-axis=y]/drawer-popup:aspect-video group-data-[swipe-axis=x]/drawer-popup:size-full group-data-[swipe-axis=y]/drawer-popup:w-full" />
                          </div>
                          <DrawerFooter>
                            <DrawerClose render={<Button variant="outline" />}>
                              Close
                            </DrawerClose>
                          </DrawerFooter>
                        </DrawerContent>
                      </Drawer>
                      <DrawerClose render={<Button variant="outline" />}>
                        Close
                      </DrawerClose>
                    </DrawerFooter>
                  </DrawerContent>
                </Drawer>
                <DrawerClose render={<Button variant="outline" />}>
                  Close
                </DrawerClose>
              </DrawerFooter>
            </DrawerContent>
          </Drawer>
          <DrawerClose render={<Button variant="outline" />}>Close</DrawerClose>
        </DrawerFooter>
      </DrawerContent>
    </Drawer>
  );
}

export default DrawerNested;
```

## Non Modal

Set `modal={false}` to allow interaction with the rest of the page while the drawer is open. Combine with `disablePointerDismissal` to prevent the drawer from closing on outside presses. Use `modal="trap-focus"` to keep focus inside the drawer while leaving scroll and pointer interaction unrestricted.

### Example: drawer-non-modal

```tsx
import { Button } from "@workspace/ui/components/button";
import {
  Drawer,
  DrawerClose,
  DrawerContent,
  DrawerFooter,
  DrawerHeader,
  DrawerTitle,
  DrawerTrigger,
} from "@workspace/ui/components/drawer";

export function DrawerNonModal() {
  return (
    <Drawer modal={false} disablePointerDismissal swipeDirection="right">
      <DrawerTrigger render={<Button variant="outline" />}>
        Non Modal
      </DrawerTrigger>
      <DrawerContent>
        <DrawerHeader>
          <DrawerTitle>Non Modal Drawer</DrawerTitle>
        </DrawerHeader>
        <div className="flex-1 p-4">
          <div className="rounded-2xl bg-muted group-data-[swipe-axis=x]/drawer-popup:size-full group-data-[swipe-axis=y]/drawer-popup:h-80 group-data-[swipe-axis=y]/drawer-popup:w-full" />
        </div>
        <DrawerFooter>
          <DrawerClose render={<Button />}>Close</DrawerClose>
        </DrawerFooter>
      </DrawerContent>
    </Drawer>
  );
}

export default DrawerNonModal;
```

## Snap Points

Use `snapPoints` to snap a drawer to preset heights. Numbers between `0` and `1` represent fractions of the viewport. Numbers greater than `1` are treated as pixel values. String values support `px` and `rem` units. Snap points apply to vertical drawers.

Track the active snap point with the controlled `snapPoint` and `onSnapPointChange` props. At the full snap point, the drawer gets a `data-expanded` attribute you can style with the `data-expanded:` variant.

### Example: drawer-snap-points

```tsx
"use client";

import { Button } from "@workspace/ui/components/button";
import {
  Drawer,
  DrawerClose,
  DrawerContent,
  DrawerDescription,
  DrawerFooter,
  DrawerHeader,
  DrawerTitle,
  DrawerTrigger,
} from "@workspace/ui/components/drawer";

const SNAP_POINTS = ["31rem", 1];

export function DrawerSnapPoints() {
  return (
    <Drawer snapPoints={SNAP_POINTS} showSwipeHandle>
      <DrawerTrigger render={<Button variant="outline" />}>
        Open Snap Drawer
      </DrawerTrigger>
      <DrawerContent>
        <DrawerHeader>
          <DrawerTitle>Snap points</DrawerTitle>
          <DrawerDescription>
            Drag the drawer to snap between a compact peek and a near
            full-height view.
          </DrawerDescription>
        </DrawerHeader>
        <div className="flex-1 p-4">
          <div className="rounded-2xl bg-muted group-data-[swipe-axis=x]/drawer-popup:size-full group-data-[swipe-axis=y]/drawer-popup:h-80 group-data-[swipe-axis=y]/drawer-popup:w-full" />
        </div>
        <DrawerFooter>
          <DrawerClose render={<Button />}>Close</DrawerClose>
        </DrawerFooter>
      </DrawerContent>
    </Drawer>
  );
}

export default DrawerSnapPoints;
```

## Responsive

You can combine the `Dialog` and `Drawer` components to create a responsive dialog. This renders a `Dialog` component on desktop and a `Drawer` on mobile.

### Example: drawer-dialog

```tsx
"use client";

import { Button } from "@workspace/ui/components/button";
import {
  Dialog,
  DialogContent,
  DialogDescription,
  DialogHeader,
  DialogTitle,
  DialogTrigger,
} from "@workspace/ui/components/dialog";
import {
  Drawer,
  DrawerContent,
  DrawerDescription,
  DrawerHeader,
  DrawerTitle,
  DrawerTrigger,
} from "@workspace/ui/components/drawer";
import { Input } from "@workspace/ui/components/input";
import { Label } from "@workspace/ui/components/label";
import { cn } from "cn";
import * as React from "react";
import { useId as usePreviewId } from "react";
import { useMediaQuery } from "./support";

export function DrawerDialogDemo() {
  const [open, setOpen] = React.useState(false);
  const isDesktop = useMediaQuery("(min-width: 768px)");

  if (isDesktop) {
    return (
      <Dialog open={open} onOpenChange={setOpen}>
        <DialogTrigger render={<Button variant="outline" />}>
          Edit Profile
        </DialogTrigger>
        <DialogContent className="sm:max-w-[425px]">
          <DialogHeader>
            <DialogTitle>Edit profile</DialogTitle>
            <DialogDescription>
              Make changes to your profile here. Click save when you&apos;re
              done.
            </DialogDescription>
          </DialogHeader>
          <ProfileForm />
        </DialogContent>
      </Dialog>
    );
  }

  return (
    <Drawer open={open} onOpenChange={setOpen}>
      <DrawerTrigger render={<Button variant="outline" />}>
        Edit Profile
      </DrawerTrigger>
      <DrawerContent>
        <DrawerHeader className="text-left">
          <DrawerTitle>Edit profile</DrawerTitle>
          <DrawerDescription>
            Make changes to your profile here. Click save when you&apos;re done.
          </DrawerDescription>
        </DrawerHeader>
        <ProfileForm className="p-4" />
      </DrawerContent>
    </Drawer>
  );
}

function ProfileForm({ className }: React.ComponentProps<"form">) {
  const previewId = usePreviewId();

  return (
    <form className={cn("grid items-start gap-6", className)}>
      <div className="grid gap-3">
        <Label htmlFor={`${previewId}-email`}>Email</Label>
        <Input
          type="email"
          id={`${previewId}-email`}
          defaultValue="shadcn@example.com"
        />
      </div>
      <div className="grid gap-3">
        <Label htmlFor={`${previewId}-username`}>Username</Label>
        <Input id={`${previewId}-username`} defaultValue="@shadcn" />
      </div>
      <Button type="submit">Save changes</Button>
    </form>
  );
}

export default DrawerDialogDemo;
```

## Migrating from Vaul

The base drawer now uses [Base UI](https://base-ui.com/react/components/drawer)
instead of Vaul. If you installed the previous base drawer, update your usage
to the Base UI API.

### Update the dependency.

```diff
- npm install vaul
+ npm install @base-ui/react
```

### Replace `direction` with `swipeDirection`.

Use `down` instead of `bottom`, and `up` instead of `top`. `left` and `right`
stay the same.

```diff
- <Drawer direction="bottom">
+ <Drawer swipeDirection="down">
```

### Replace `asChild` with `render`.

For `DrawerTrigger`, pass the trigger element to the `render` prop.

```diff
- <DrawerTrigger asChild>
-   <Button variant="outline">Open</Button>
- </DrawerTrigger>
+ <DrawerTrigger render={<Button variant="outline" />}>
+   Open
+ </DrawerTrigger>
```

For `DrawerClose`, pass the close element to the `render` prop.

```diff
- <DrawerClose asChild>
-   <Button variant="outline">Cancel</Button>
- </DrawerClose>
+ <DrawerClose render={<Button variant="outline" />}>
+   Cancel
+ </DrawerClose>
```

### Update snap point props.

If you use snap points, rename the controlled snap point props and the sequential
snap point prop.

```diff
  <Drawer
    snapPoints={[0.25, 0.5, 1]}
-   activeSnapPoint={snapPoint}
-   setActiveSnapPoint={setSnapPoint}
-   snapToSequentialPoint
+   snapPoint={snapPoint}
+   onSnapPointChange={setSnapPoint}
+   snapToSequentialPoints
  >
```

### Update animation and focus props.

```diff
- <Drawer onAnimationEnd={(open) => setDone(open)}>
+ <Drawer onOpenChangeComplete={(open) => setDone(open)}>
```

```diff
- <DrawerContent onOpenAutoFocus={(event) => event.preventDefault()}>
+ <DrawerContent initialFocus={false}>
```

### Review Vaul-only props.

Vaul props like `handleOnly`, `repositionInputs`, and
`shouldScaleBackground` do not have one-to-one replacements in the base drawer
API. Use Base UI props such as `disablePointerDismissal`, `modal`, `snapPoints`,
or controlled `open` state for the behavior you need.

```diff
- <Drawer handleOnly repositionInputs={false} shouldScaleBackground>
+ <Drawer>
```

```diff
- <Drawer dismissible={false}>
+ <Drawer disablePointerDismissal>
```

### Update custom data attribute selectors.

Replace Vaul's `data-vaul-drawer-direction` selectors with Base UI's
`data-swipe-direction` selectors.

```diff
- <DrawerContent className="data-[vaul-drawer-direction=bottom]:max-h-[50vh]">
+ <DrawerContent className="data-[swipe-direction=down]:max-h-[50vh]">
```

Base UI also exposes attributes like `data-swiping`, `data-starting-style`, and
`data-ending-style` for swipe and transition states. Descendants inside
`DrawerContent` can use `group-data-[swipe-axis=x]/drawer-popup` and
`group-data-[swipe-axis=y]/drawer-popup` for axis-specific styling.

## API Reference

See the [Base UI documentation](https://base-ui.com/react/components/drawer) for the full API reference.

- [Documentation](https://base-ui.com/react/components/drawer)
- [API reference](https://base-ui.com/react/components/drawer#api-reference)


---

# Dropdown Menu

Displays a menu to the user — such as a set of actions or functions — triggered by a button.

Page: https://sui.draco.dev/docs/components/dropdown-menu

### Example: dropdown-menu-demo

```tsx
"use client";

import { Button } from "@workspace/ui/components/button";
import {
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuGroup,
  DropdownMenuItem,
  DropdownMenuLabel,
  DropdownMenuPortal,
  DropdownMenuSeparator,
  DropdownMenuShortcut,
  DropdownMenuSub,
  DropdownMenuSubContent,
  DropdownMenuSubTrigger,
  DropdownMenuTrigger,
} from "@workspace/ui/components/dropdown-menu";

export function DropdownMenuDemo() {
  return (
    <DropdownMenu>
      <DropdownMenuTrigger render={<Button variant="outline" />}>
        Open
      </DropdownMenuTrigger>
      <DropdownMenuContent className="w-40" align="start">
        <DropdownMenuGroup>
          <DropdownMenuLabel>My Account</DropdownMenuLabel>
          <DropdownMenuItem>
            Profile
            <DropdownMenuShortcut>⇧⌘P</DropdownMenuShortcut>
          </DropdownMenuItem>
          <DropdownMenuItem>
            Billing
            <DropdownMenuShortcut>⌘B</DropdownMenuShortcut>
          </DropdownMenuItem>
          <DropdownMenuItem>
            Settings
            <DropdownMenuShortcut>⌘S</DropdownMenuShortcut>
          </DropdownMenuItem>
        </DropdownMenuGroup>
        <DropdownMenuSeparator />
        <DropdownMenuGroup>
          <DropdownMenuItem>Team</DropdownMenuItem>
          <DropdownMenuSub>
            <DropdownMenuSubTrigger>Invite users</DropdownMenuSubTrigger>
            <DropdownMenuPortal>
              <DropdownMenuSubContent>
                <DropdownMenuItem>Email</DropdownMenuItem>
                <DropdownMenuItem>Message</DropdownMenuItem>
                <DropdownMenuSeparator />
                <DropdownMenuItem>More...</DropdownMenuItem>
              </DropdownMenuSubContent>
            </DropdownMenuPortal>
          </DropdownMenuSub>
          <DropdownMenuItem>
            New Team
            <DropdownMenuShortcut>⌘+T</DropdownMenuShortcut>
          </DropdownMenuItem>
        </DropdownMenuGroup>
        <DropdownMenuSeparator />
        <DropdownMenuGroup>
          <DropdownMenuItem>GitHub</DropdownMenuItem>
          <DropdownMenuItem>Support</DropdownMenuItem>
          <DropdownMenuItem disabled>API</DropdownMenuItem>
        </DropdownMenuGroup>
        <DropdownMenuSeparator />
        <DropdownMenuGroup>
          <DropdownMenuItem>
            Log out
            <DropdownMenuShortcut>⇧⌘Q</DropdownMenuShortcut>
          </DropdownMenuItem>
        </DropdownMenuGroup>
      </DropdownMenuContent>
    </DropdownMenu>
  );
}

export default DropdownMenuDemo;
```

## Installation

```bash
bunx --bun shadcn@latest add @sui/dropdown-menu
```

Install with the shadcn CLI or use the shared `@workspace/ui` package. Follow the [installation guide](/docs/installation) to configure the registry, load styles, and choose import aliases.

## Usage

```tsx showLineNumbers
import { Button } from "@workspace/ui/components/button"
import {
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuGroup,
  DropdownMenuItem,
  DropdownMenuLabel,
  DropdownMenuSeparator,
  DropdownMenuTrigger,
} from "@workspace/ui/components/dropdown-menu"
```

```tsx showLineNumbers
<DropdownMenu>
  <DropdownMenuTrigger render={<Button variant="outline" />}>
    Open
  </DropdownMenuTrigger>
  <DropdownMenuContent>
    <DropdownMenuGroup>
      <DropdownMenuLabel>My Account</DropdownMenuLabel>
      <DropdownMenuItem>Profile</DropdownMenuItem>
      <DropdownMenuItem>Billing</DropdownMenuItem>
    </DropdownMenuGroup>
    <DropdownMenuSeparator />
    <DropdownMenuGroup>
      <DropdownMenuItem>Team</DropdownMenuItem>
      <DropdownMenuItem>Subscription</DropdownMenuItem>
    </DropdownMenuGroup>
  </DropdownMenuContent>
</DropdownMenu>
```

## Composition

Use the following composition to build a `DropdownMenu`:

```text
DropdownMenu
├── DropdownMenuTrigger
└── DropdownMenuContent
    ├── DropdownMenuGroup
    │   ├── DropdownMenuLabel
    │   ├── DropdownMenuItem
    │   └── DropdownMenuItem
    ├── DropdownMenuSeparator
    ├── DropdownMenuGroup
    │   ├── DropdownMenuLabel
    │   ├── DropdownMenuCheckboxItem
    │   └── DropdownMenuCheckboxItem
    ├── DropdownMenuSeparator
    ├── DropdownMenuGroup
    │   ├── DropdownMenuLabel
    │   └── DropdownMenuRadioGroup
    │       ├── DropdownMenuRadioItem
    │       └── DropdownMenuRadioItem
    └── DropdownMenuSub
        ├── DropdownMenuSubTrigger
        └── DropdownMenuSubContent
            └── DropdownMenuGroup
                ├── DropdownMenuLabel
                ├── DropdownMenuItem
                └── DropdownMenuItem
```

## Basic

A basic dropdown menu with labels and separators.

### Example: dropdown-menu-basic

```tsx
"use client";

import { Button } from "@workspace/ui/components/button";
import {
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuGroup,
  DropdownMenuItem,
  DropdownMenuLabel,
  DropdownMenuSeparator,
  DropdownMenuTrigger,
} from "@workspace/ui/components/dropdown-menu";

export function DropdownMenuBasic() {
  return (
    <DropdownMenu>
      <DropdownMenuTrigger render={<Button variant="outline" />}>
        Open
      </DropdownMenuTrigger>
      <DropdownMenuContent>
        <DropdownMenuGroup>
          <DropdownMenuLabel>My Account</DropdownMenuLabel>
          <DropdownMenuItem>Profile</DropdownMenuItem>
          <DropdownMenuItem>Billing</DropdownMenuItem>
          <DropdownMenuItem>Settings</DropdownMenuItem>
        </DropdownMenuGroup>
        <DropdownMenuSeparator />
        <DropdownMenuItem>GitHub</DropdownMenuItem>
        <DropdownMenuItem>Support</DropdownMenuItem>
        <DropdownMenuItem disabled>API</DropdownMenuItem>
      </DropdownMenuContent>
    </DropdownMenu>
  );
}

export default DropdownMenuBasic;
```

## Submenu

Use `DropdownMenuSub` to nest secondary actions.

### Example: dropdown-menu-submenu

```tsx
"use client";

import { Button } from "@workspace/ui/components/button";
import {
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuGroup,
  DropdownMenuItem,
  DropdownMenuPortal,
  DropdownMenuSeparator,
  DropdownMenuShortcut,
  DropdownMenuSub,
  DropdownMenuSubContent,
  DropdownMenuSubTrigger,
  DropdownMenuTrigger,
} from "@workspace/ui/components/dropdown-menu";

export function DropdownMenuSubmenu() {
  return (
    <DropdownMenu>
      <DropdownMenuTrigger render={<Button variant="outline" />}>
        Open
      </DropdownMenuTrigger>
      <DropdownMenuContent>
        <DropdownMenuGroup>
          <DropdownMenuItem>Team</DropdownMenuItem>
          <DropdownMenuSub>
            <DropdownMenuSubTrigger>Invite users</DropdownMenuSubTrigger>
            <DropdownMenuPortal>
              <DropdownMenuSubContent>
                <DropdownMenuItem>Email</DropdownMenuItem>
                <DropdownMenuItem>Message</DropdownMenuItem>
                <DropdownMenuSub>
                  <DropdownMenuSubTrigger>More options</DropdownMenuSubTrigger>
                  <DropdownMenuPortal>
                    <DropdownMenuSubContent>
                      <DropdownMenuItem>Calendly</DropdownMenuItem>
                      <DropdownMenuItem>Slack</DropdownMenuItem>
                      <DropdownMenuSeparator />
                      <DropdownMenuItem>Webhook</DropdownMenuItem>
                    </DropdownMenuSubContent>
                  </DropdownMenuPortal>
                </DropdownMenuSub>
                <DropdownMenuSeparator />
                <DropdownMenuItem>Advanced...</DropdownMenuItem>
              </DropdownMenuSubContent>
            </DropdownMenuPortal>
          </DropdownMenuSub>
          <DropdownMenuItem>
            New Team
            <DropdownMenuShortcut>⌘+T</DropdownMenuShortcut>
          </DropdownMenuItem>
        </DropdownMenuGroup>
      </DropdownMenuContent>
    </DropdownMenu>
  );
}

export default DropdownMenuSubmenu;
```

## Shortcuts

Add `DropdownMenuShortcut` to show keyboard hints.

### Example: dropdown-menu-shortcuts

```tsx
"use client";

import { Button } from "@workspace/ui/components/button";
import {
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuGroup,
  DropdownMenuItem,
  DropdownMenuLabel,
  DropdownMenuSeparator,
  DropdownMenuShortcut,
  DropdownMenuTrigger,
} from "@workspace/ui/components/dropdown-menu";

export function DropdownMenuShortcuts() {
  return (
    <DropdownMenu>
      <DropdownMenuTrigger render={<Button variant="outline" />}>
        Open
      </DropdownMenuTrigger>
      <DropdownMenuContent>
        <DropdownMenuGroup>
          <DropdownMenuLabel>My Account</DropdownMenuLabel>
          <DropdownMenuItem>
            Profile
            <DropdownMenuShortcut>⇧⌘P</DropdownMenuShortcut>
          </DropdownMenuItem>
          <DropdownMenuItem>
            Billing
            <DropdownMenuShortcut>⌘B</DropdownMenuShortcut>
          </DropdownMenuItem>
          <DropdownMenuItem>
            Settings
            <DropdownMenuShortcut>⌘S</DropdownMenuShortcut>
          </DropdownMenuItem>
        </DropdownMenuGroup>
        <DropdownMenuSeparator />
        <DropdownMenuItem>
          Log out
          <DropdownMenuShortcut>⇧⌘Q</DropdownMenuShortcut>
        </DropdownMenuItem>
      </DropdownMenuContent>
    </DropdownMenu>
  );
}

export default DropdownMenuShortcuts;
```

## Icons

Combine icons with labels for quick scanning.

### Example: dropdown-menu-icons

```tsx
"use client";

import { Button } from "@workspace/ui/components/button";
import {
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuItem,
  DropdownMenuSeparator,
  DropdownMenuTrigger,
} from "@workspace/ui/components/dropdown-menu";
import {
  CreditCardIcon,
  LogOutIcon,
  SettingsIcon,
  UserIcon,
} from "lucide-react";

export function DropdownMenuIcons() {
  return (
    <DropdownMenu>
      <DropdownMenuTrigger render={<Button variant="outline" />}>
        Open
      </DropdownMenuTrigger>
      <DropdownMenuContent>
        <DropdownMenuItem>
          <UserIcon />
          Profile
        </DropdownMenuItem>
        <DropdownMenuItem>
          <CreditCardIcon />
          Billing
        </DropdownMenuItem>
        <DropdownMenuItem>
          <SettingsIcon />
          Settings
        </DropdownMenuItem>
        <DropdownMenuSeparator />
        <DropdownMenuItem variant="destructive">
          <LogOutIcon />
          Log out
        </DropdownMenuItem>
      </DropdownMenuContent>
    </DropdownMenu>
  );
}

export default DropdownMenuIcons;
```

## Checkboxes

Use `DropdownMenuCheckboxItem` for toggles.

### Example: dropdown-menu-checkboxes

```tsx
"use client";

import { Button } from "@workspace/ui/components/button";
import {
  DropdownMenu,
  DropdownMenuCheckboxItem,
  DropdownMenuContent,
  DropdownMenuGroup,
  DropdownMenuLabel,
  DropdownMenuTrigger,
} from "@workspace/ui/components/dropdown-menu";
import * as React from "react";

export function DropdownMenuCheckboxes() {
  const [showStatusBar, setShowStatusBar] = React.useState(true);
  const [showActivityBar, setShowActivityBar] = React.useState(false);
  const [showPanel, setShowPanel] = React.useState(false);

  return (
    <DropdownMenu>
      <DropdownMenuTrigger render={<Button variant="outline" />}>
        Open
      </DropdownMenuTrigger>
      <DropdownMenuContent className="w-40">
        <DropdownMenuGroup>
          <DropdownMenuLabel>Appearance</DropdownMenuLabel>
          <DropdownMenuCheckboxItem
            checked={showStatusBar ?? false}
            onCheckedChange={setShowStatusBar}
          >
            Status Bar
          </DropdownMenuCheckboxItem>
          <DropdownMenuCheckboxItem
            checked={showActivityBar}
            onCheckedChange={setShowActivityBar}
            disabled
          >
            Activity Bar
          </DropdownMenuCheckboxItem>
          <DropdownMenuCheckboxItem
            checked={showPanel}
            onCheckedChange={setShowPanel}
          >
            Panel
          </DropdownMenuCheckboxItem>
        </DropdownMenuGroup>
      </DropdownMenuContent>
    </DropdownMenu>
  );
}

export default DropdownMenuCheckboxes;
```

## Checkboxes Icons

Add icons to checkbox items.

### Example: dropdown-menu-checkboxes-icons

```tsx
"use client";

import { Button } from "@workspace/ui/components/button";
import {
  DropdownMenu,
  DropdownMenuCheckboxItem,
  DropdownMenuContent,
  DropdownMenuGroup,
  DropdownMenuLabel,
  DropdownMenuTrigger,
} from "@workspace/ui/components/dropdown-menu";
import { BellIcon, MailIcon, MessageSquareIcon } from "lucide-react";
import * as React from "react";

export function DropdownMenuCheckboxesIcons() {
  const [notifications, setNotifications] = React.useState({
    email: true,
    sms: false,
    push: true,
  });

  return (
    <DropdownMenu>
      <DropdownMenuTrigger render={<Button variant="outline" />}>
        Notifications
      </DropdownMenuTrigger>
      <DropdownMenuContent className="w-48">
        <DropdownMenuGroup>
          <DropdownMenuLabel>Notification Preferences</DropdownMenuLabel>
          <DropdownMenuCheckboxItem
            checked={notifications.email}
            onCheckedChange={(checked) =>
              setNotifications({ ...notifications, email: checked === true })
            }
          >
            <MailIcon />
            Email notifications
          </DropdownMenuCheckboxItem>
          <DropdownMenuCheckboxItem
            checked={notifications.sms}
            onCheckedChange={(checked) =>
              setNotifications({ ...notifications, sms: checked === true })
            }
          >
            <MessageSquareIcon />
            SMS notifications
          </DropdownMenuCheckboxItem>
          <DropdownMenuCheckboxItem
            checked={notifications.push}
            onCheckedChange={(checked) =>
              setNotifications({ ...notifications, push: checked === true })
            }
          >
            <BellIcon />
            Push notifications
          </DropdownMenuCheckboxItem>
        </DropdownMenuGroup>
      </DropdownMenuContent>
    </DropdownMenu>
  );
}

export default DropdownMenuCheckboxesIcons;
```

## Radio Group

Use `DropdownMenuRadioGroup` for exclusive choices.

### Example: dropdown-menu-radio-group

```tsx
"use client";

import { Button } from "@workspace/ui/components/button";
import {
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuGroup,
  DropdownMenuLabel,
  DropdownMenuRadioGroup,
  DropdownMenuRadioItem,
  DropdownMenuTrigger,
} from "@workspace/ui/components/dropdown-menu";
import * as React from "react";

export function DropdownMenuRadioGroupDemo() {
  const [position, setPosition] = React.useState("bottom");

  return (
    <DropdownMenu>
      <DropdownMenuTrigger render={<Button variant="outline" />}>
        Open
      </DropdownMenuTrigger>
      <DropdownMenuContent className="w-32">
        <DropdownMenuGroup>
          <DropdownMenuLabel>Panel Position</DropdownMenuLabel>
          <DropdownMenuRadioGroup value={position} onValueChange={setPosition}>
            <DropdownMenuRadioItem value="top">Top</DropdownMenuRadioItem>
            <DropdownMenuRadioItem value="bottom">Bottom</DropdownMenuRadioItem>
            <DropdownMenuRadioItem value="right">Right</DropdownMenuRadioItem>
          </DropdownMenuRadioGroup>
        </DropdownMenuGroup>
      </DropdownMenuContent>
    </DropdownMenu>
  );
}

export default DropdownMenuRadioGroupDemo;
```

## Radio Icons

Show radio options with icons.

### Example: dropdown-menu-radio-icons

```tsx
"use client";

import { Button } from "@workspace/ui/components/button";
import {
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuGroup,
  DropdownMenuLabel,
  DropdownMenuRadioGroup,
  DropdownMenuRadioItem,
  DropdownMenuTrigger,
} from "@workspace/ui/components/dropdown-menu";
import { Building2Icon, CreditCardIcon, WalletIcon } from "lucide-react";
import * as React from "react";

export function DropdownMenuRadioIcons() {
  const [paymentMethod, setPaymentMethod] = React.useState("card");

  return (
    <DropdownMenu>
      <DropdownMenuTrigger render={<Button variant="outline" />}>
        Payment Method
      </DropdownMenuTrigger>
      <DropdownMenuContent className="min-w-56">
        <DropdownMenuGroup>
          <DropdownMenuLabel>Select Payment Method</DropdownMenuLabel>
          <DropdownMenuRadioGroup
            value={paymentMethod}
            onValueChange={setPaymentMethod}
          >
            <DropdownMenuRadioItem value="card">
              <CreditCardIcon />
              Credit Card
            </DropdownMenuRadioItem>
            <DropdownMenuRadioItem value="paypal">
              <WalletIcon />
              PayPal
            </DropdownMenuRadioItem>
            <DropdownMenuRadioItem value="bank">
              <Building2Icon />
              Bank Transfer
            </DropdownMenuRadioItem>
          </DropdownMenuRadioGroup>
        </DropdownMenuGroup>
      </DropdownMenuContent>
    </DropdownMenu>
  );
}

export default DropdownMenuRadioIcons;
```

## Destructive

Use `variant="destructive"` for irreversible actions.

### Example: dropdown-menu-destructive

```tsx
"use client";

import { Button } from "@workspace/ui/components/button";
import {
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuGroup,
  DropdownMenuItem,
  DropdownMenuSeparator,
  DropdownMenuTrigger,
} from "@workspace/ui/components/dropdown-menu";
import { PencilIcon, ShareIcon, TrashIcon } from "lucide-react";

export function DropdownMenuDestructive() {
  return (
    <DropdownMenu>
      <DropdownMenuTrigger render={<Button variant="outline" />}>
        Actions
      </DropdownMenuTrigger>
      <DropdownMenuContent>
        <DropdownMenuGroup>
          <DropdownMenuItem>
            <PencilIcon />
            Edit
          </DropdownMenuItem>
          <DropdownMenuItem>
            <ShareIcon />
            Share
          </DropdownMenuItem>
        </DropdownMenuGroup>
        <DropdownMenuSeparator />
        <DropdownMenuGroup>
          <DropdownMenuItem variant="destructive">
            <TrashIcon />
            Delete
          </DropdownMenuItem>
        </DropdownMenuGroup>
      </DropdownMenuContent>
    </DropdownMenu>
  );
}

export default DropdownMenuDestructive;
```

## Avatar

An account switcher dropdown triggered by an avatar.

### Example: dropdown-menu-avatar

```tsx
"use client";

import {
  Avatar,
  AvatarFallback,
  AvatarImage,
} from "@workspace/ui/components/avatar";
import { Button } from "@workspace/ui/components/button";
import {
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuGroup,
  DropdownMenuItem,
  DropdownMenuSeparator,
  DropdownMenuTrigger,
} from "@workspace/ui/components/dropdown-menu";
import {
  BadgeCheckIcon,
  BellIcon,
  CreditCardIcon,
  LogOutIcon,
} from "lucide-react";

export function DropdownMenuAvatar() {
  return (
    <DropdownMenu>
      <DropdownMenuTrigger
        render={<Button variant="ghost" size="icon" className="rounded-full" />}
      >
        <Avatar>
          <AvatarImage src="https://github.com/shadcn.png" alt="shadcn" />
          <AvatarFallback>LR</AvatarFallback>
        </Avatar>
      </DropdownMenuTrigger>
      <DropdownMenuContent align="end">
        <DropdownMenuGroup>
          <DropdownMenuItem>
            <BadgeCheckIcon />
            Account
          </DropdownMenuItem>
          <DropdownMenuItem>
            <CreditCardIcon />
            Billing
          </DropdownMenuItem>
          <DropdownMenuItem>
            <BellIcon />
            Notifications
          </DropdownMenuItem>
        </DropdownMenuGroup>
        <DropdownMenuSeparator />
        <DropdownMenuItem>
          <LogOutIcon />
          Sign Out
        </DropdownMenuItem>
      </DropdownMenuContent>
    </DropdownMenu>
  );
}

export default DropdownMenuAvatar;
```

## Complex

A richer example combining groups, icons, and submenus.

### Example: dropdown-menu-complex

```tsx
"use client";

import { Button } from "@workspace/ui/components/button";
import {
  DropdownMenu,
  DropdownMenuCheckboxItem,
  DropdownMenuContent,
  DropdownMenuGroup,
  DropdownMenuItem,
  DropdownMenuLabel,
  DropdownMenuPortal,
  DropdownMenuRadioGroup,
  DropdownMenuRadioItem,
  DropdownMenuSeparator,
  DropdownMenuShortcut,
  DropdownMenuSub,
  DropdownMenuSubContent,
  DropdownMenuSubTrigger,
  DropdownMenuTrigger,
} from "@workspace/ui/components/dropdown-menu";
import {
  BellIcon,
  CreditCardIcon,
  DownloadIcon,
  EyeIcon,
  FileCodeIcon,
  FileIcon,
  FileTextIcon,
  FolderIcon,
  FolderOpenIcon,
  FolderSearchIcon,
  HelpCircleIcon,
  KeyboardIcon,
  LanguagesIcon,
  LayoutIcon,
  LogOutIcon,
  MailIcon,
  MonitorIcon,
  MoonIcon,
  MoreHorizontalIcon,
  PaletteIcon,
  SaveIcon,
  SettingsIcon,
  ShieldIcon,
  SunIcon,
  UserIcon,
} from "lucide-react";
import * as React from "react";

export function DropdownMenuComplex() {
  const [notifications, setNotifications] = React.useState({
    email: true,
    sms: false,
    push: true,
  });
  const [theme, setTheme] = React.useState("light");

  return (
    <DropdownMenu>
      <DropdownMenuTrigger render={<Button variant="outline" />}>
        Complex Menu
      </DropdownMenuTrigger>
      <DropdownMenuContent className="w-44">
        <DropdownMenuGroup>
          <DropdownMenuLabel>File</DropdownMenuLabel>
          <DropdownMenuItem>
            <FileIcon />
            New File
            <DropdownMenuShortcut>⌘N</DropdownMenuShortcut>
          </DropdownMenuItem>
          <DropdownMenuItem>
            <FolderIcon />
            New Folder
            <DropdownMenuShortcut>⇧⌘N</DropdownMenuShortcut>
          </DropdownMenuItem>
          <DropdownMenuSub>
            <DropdownMenuSubTrigger>
              <FolderOpenIcon />
              Open Recent
            </DropdownMenuSubTrigger>
            <DropdownMenuPortal>
              <DropdownMenuSubContent>
                <DropdownMenuGroup>
                  <DropdownMenuLabel>Recent Projects</DropdownMenuLabel>
                  <DropdownMenuItem>
                    <FileCodeIcon />
                    Project Alpha
                  </DropdownMenuItem>
                  <DropdownMenuItem>
                    <FileCodeIcon />
                    Project Beta
                  </DropdownMenuItem>
                  <DropdownMenuSub>
                    <DropdownMenuSubTrigger>
                      <MoreHorizontalIcon />
                      More Projects
                    </DropdownMenuSubTrigger>
                    <DropdownMenuPortal>
                      <DropdownMenuSubContent>
                        <DropdownMenuItem>
                          <FileCodeIcon />
                          Project Gamma
                        </DropdownMenuItem>
                        <DropdownMenuItem>
                          <FileCodeIcon />
                          Project Delta
                        </DropdownMenuItem>
                      </DropdownMenuSubContent>
                    </DropdownMenuPortal>
                  </DropdownMenuSub>
                </DropdownMenuGroup>
                <DropdownMenuSeparator />
                <DropdownMenuGroup>
                  <DropdownMenuItem>
                    <FolderSearchIcon />
                    Browse...
                  </DropdownMenuItem>
                </DropdownMenuGroup>
              </DropdownMenuSubContent>
            </DropdownMenuPortal>
          </DropdownMenuSub>
          <DropdownMenuSeparator />
          <DropdownMenuItem>
            <SaveIcon />
            Save
            <DropdownMenuShortcut>⌘S</DropdownMenuShortcut>
          </DropdownMenuItem>
          <DropdownMenuItem>
            <DownloadIcon />
            Export
            <DropdownMenuShortcut>⇧⌘E</DropdownMenuShortcut>
          </DropdownMenuItem>
        </DropdownMenuGroup>
        <DropdownMenuSeparator />
        <DropdownMenuGroup>
          <DropdownMenuLabel>View</DropdownMenuLabel>
          <DropdownMenuCheckboxItem
            checked={notifications.email}
            onCheckedChange={(checked) =>
              setNotifications({ ...notifications, email: checked === true })
            }
          >
            <EyeIcon />
            Show Sidebar
          </DropdownMenuCheckboxItem>
          <DropdownMenuCheckboxItem
            checked={notifications.sms}
            onCheckedChange={(checked) =>
              setNotifications({ ...notifications, sms: checked === true })
            }
          >
            <LayoutIcon />
            Show Status Bar
          </DropdownMenuCheckboxItem>
          <DropdownMenuSub>
            <DropdownMenuSubTrigger>
              <PaletteIcon />
              Theme
            </DropdownMenuSubTrigger>
            <DropdownMenuPortal>
              <DropdownMenuSubContent>
                <DropdownMenuGroup>
                  <DropdownMenuLabel>Appearance</DropdownMenuLabel>
                  <DropdownMenuRadioGroup
                    value={theme}
                    onValueChange={setTheme}
                  >
                    <DropdownMenuRadioItem value="light">
                      <SunIcon />
                      Light
                    </DropdownMenuRadioItem>
                    <DropdownMenuRadioItem value="dark">
                      <MoonIcon />
                      Dark
                    </DropdownMenuRadioItem>
                    <DropdownMenuRadioItem value="system">
                      <MonitorIcon />
                      System
                    </DropdownMenuRadioItem>
                  </DropdownMenuRadioGroup>
                </DropdownMenuGroup>
              </DropdownMenuSubContent>
            </DropdownMenuPortal>
          </DropdownMenuSub>
        </DropdownMenuGroup>
        <DropdownMenuSeparator />
        <DropdownMenuGroup>
          <DropdownMenuLabel>Account</DropdownMenuLabel>
          <DropdownMenuItem>
            <UserIcon />
            Profile
            <DropdownMenuShortcut>⇧⌘P</DropdownMenuShortcut>
          </DropdownMenuItem>
          <DropdownMenuItem>
            <CreditCardIcon />
            Billing
          </DropdownMenuItem>
          <DropdownMenuSub>
            <DropdownMenuSubTrigger>
              <SettingsIcon />
              Settings
            </DropdownMenuSubTrigger>
            <DropdownMenuPortal>
              <DropdownMenuSubContent>
                <DropdownMenuGroup>
                  <DropdownMenuLabel>Preferences</DropdownMenuLabel>
                  <DropdownMenuItem>
                    <KeyboardIcon />
                    Keyboard Shortcuts
                  </DropdownMenuItem>
                  <DropdownMenuItem>
                    <LanguagesIcon />
                    Language
                  </DropdownMenuItem>
                  <DropdownMenuSub>
                    <DropdownMenuSubTrigger>
                      <BellIcon />
                      Notifications
                    </DropdownMenuSubTrigger>
                    <DropdownMenuPortal>
                      <DropdownMenuSubContent>
                        <DropdownMenuGroup>
                          <DropdownMenuLabel>
                            Notification Types
                          </DropdownMenuLabel>
                          <DropdownMenuCheckboxItem
                            checked={notifications.push}
                            onCheckedChange={(checked) =>
                              setNotifications({
                                ...notifications,
                                push: checked === true,
                              })
                            }
                          >
                            <BellIcon />
                            Push Notifications
                          </DropdownMenuCheckboxItem>
                          <DropdownMenuCheckboxItem
                            checked={notifications.email}
                            onCheckedChange={(checked) =>
                              setNotifications({
                                ...notifications,
                                email: checked === true,
                              })
                            }
                          >
                            <MailIcon />
                            Email Notifications
                          </DropdownMenuCheckboxItem>
                        </DropdownMenuGroup>
                      </DropdownMenuSubContent>
                    </DropdownMenuPortal>
                  </DropdownMenuSub>
                </DropdownMenuGroup>
                <DropdownMenuSeparator />
                <DropdownMenuGroup>
                  <DropdownMenuItem>
                    <ShieldIcon />
                    Privacy & Security
                  </DropdownMenuItem>
                </DropdownMenuGroup>
              </DropdownMenuSubContent>
            </DropdownMenuPortal>
          </DropdownMenuSub>
        </DropdownMenuGroup>
        <DropdownMenuSeparator />
        <DropdownMenuGroup>
          <DropdownMenuItem>
            <HelpCircleIcon />
            Help & Support
          </DropdownMenuItem>
          <DropdownMenuItem>
            <FileTextIcon />
            Documentation
          </DropdownMenuItem>
        </DropdownMenuGroup>
        <DropdownMenuSeparator />
        <DropdownMenuGroup>
          <DropdownMenuItem variant="destructive">
            <LogOutIcon />
            Sign Out
            <DropdownMenuShortcut>⇧⌘Q</DropdownMenuShortcut>
          </DropdownMenuItem>
        </DropdownMenuGroup>
      </DropdownMenuContent>
    </DropdownMenu>
  );
}

export default DropdownMenuComplex;
```

## RTL

To enable RTL support in shadcn/ui, see the [RTL configuration guide](https://ui.shadcn.com/docs/rtl).

### Example: dropdown-menu-rtl

```tsx
"use client";

import { Button } from "@workspace/ui/components/button";
import {
  DropdownMenu,
  DropdownMenuCheckboxItem,
  DropdownMenuContent,
  DropdownMenuGroup,
  DropdownMenuItem,
  DropdownMenuLabel,
  DropdownMenuPortal,
  DropdownMenuRadioGroup,
  DropdownMenuRadioItem,
  DropdownMenuSeparator,
  DropdownMenuShortcut,
  DropdownMenuSub,
  DropdownMenuSubContent,
  DropdownMenuSubTrigger,
  DropdownMenuTrigger,
} from "@workspace/ui/components/dropdown-menu";
import { CreditCardIcon, SettingsIcon, UserIcon } from "lucide-react";
import * as React from "react";
import { type Translations, useTranslation } from "./support";

const translations: Translations = {
  en: {
    dir: "ltr",
    values: {
      open: "Open",
      account: "Account",
      profile: "Profile",
      billing: "Billing",
      settings: "Settings",
      logout: "Log out",
      team: "Team",
      inviteUsers: "Invite users",
      email: "Email",
      message: "Message",
      more: "More",
      calendar: "Calendar",
      chat: "Chat",
      webhook: "Webhook",
      advanced: "Advanced...",
      newTeam: "New Team",
      view: "View",
      statusBar: "Status Bar",
      activityBar: "Activity Bar",
      panel: "Panel",
      position: "Position",
      top: "Top",
      bottom: "Bottom",
      right: "Right",
      left: "Left",
    },
  },
  ar: {
    dir: "rtl",
    values: {
      open: "افتح القائمة",
      account: "الحساب",
      profile: "الملف الشخصي",
      billing: "الفوترة",
      settings: "الإعدادات",
      logout: "تسجيل الخروج",
      team: "الفريق",
      inviteUsers: "دعوة المستخدمين",
      email: "البريد الإلكتروني",
      message: "رسالة",
      more: "المزيد",
      calendar: "تقويم",
      chat: "دردشة",
      webhook: "خطاف ويب",
      advanced: "متقدم...",
      newTeam: "فريق جديد",
      view: "عرض",
      statusBar: "شريط الحالة",
      activityBar: "شريط النشاط",
      panel: "اللوحة",
      position: "الموضع",
      top: "أعلى",
      bottom: "أسفل",
      right: "يمين",
      left: "يسار",
    },
  },
  he: {
    dir: "rtl",
    values: {
      open: "פתח תפריט",
      account: "חשבון",
      profile: "פרופיל",
      billing: "חיוב",
      settings: "הגדרות",
      logout: "התנתק",
      team: "הצוות",
      inviteUsers: "הזמן משתמשים",
      email: "אימייל",
      message: "הודעה",
      more: "עוד",
      calendar: "יומן",
      chat: "צ'אט",
      webhook: "Webhook",
      advanced: "מתקדם...",
      newTeam: "צוות חדש",
      view: "תצוגה",
      statusBar: "שורת סטטוס",
      activityBar: "שורת פעילות",
      panel: "לוח",
      position: "מיקום",
      top: "למעלה",
      bottom: "למטה",
      right: "ימין",
      left: "שמאל",
    },
  },
};

export function DropdownMenuRtl() {
  const { dir, language, t } = useTranslation(translations, "ar");
  const [showStatusBar, setShowStatusBar] = React.useState(true);
  const [showActivityBar, setShowActivityBar] = React.useState(false);
  const [showPanel, setShowPanel] = React.useState(false);
  const [position, setPosition] = React.useState("bottom");

  return (
    <DropdownMenu>
      <DropdownMenuTrigger render={<Button variant="outline" />}>
        {t.open}
      </DropdownMenuTrigger>
      <DropdownMenuContent
        align={dir === "rtl" ? "end" : "start"}
        dir={dir}
        className="w-36"
        data-lang={dir === "rtl" ? language : undefined}
      >
        <DropdownMenuGroup>
          <DropdownMenuSub>
            <DropdownMenuSubTrigger>{t.account}</DropdownMenuSubTrigger>
            <DropdownMenuPortal>
              <DropdownMenuSubContent
                dir={dir}
                data-lang={dir === "rtl" ? language : undefined}
              >
                <DropdownMenuGroup>
                  <DropdownMenuItem>
                    <UserIcon />
                    {t.profile}
                  </DropdownMenuItem>
                  <DropdownMenuItem>
                    <CreditCardIcon />
                    {t.billing}
                  </DropdownMenuItem>
                  <DropdownMenuItem>
                    <SettingsIcon />
                    {t.settings}
                  </DropdownMenuItem>
                </DropdownMenuGroup>
              </DropdownMenuSubContent>
            </DropdownMenuPortal>
          </DropdownMenuSub>
        </DropdownMenuGroup>
        <DropdownMenuSeparator />
        <DropdownMenuGroup>
          <DropdownMenuLabel>{t.team}</DropdownMenuLabel>
          <DropdownMenuItem>{t.team}</DropdownMenuItem>
          <DropdownMenuSub>
            <DropdownMenuSubTrigger>{t.inviteUsers}</DropdownMenuSubTrigger>
            <DropdownMenuPortal>
              <DropdownMenuSubContent
                dir={dir}
                data-lang={dir === "rtl" ? language : undefined}
              >
                <DropdownMenuItem>{t.email}</DropdownMenuItem>
                <DropdownMenuItem>{t.message}</DropdownMenuItem>
                <DropdownMenuSub>
                  <DropdownMenuSubTrigger>{t.more}</DropdownMenuSubTrigger>
                  <DropdownMenuPortal>
                    <DropdownMenuSubContent
                      dir={dir}
                      data-lang={dir === "rtl" ? language : undefined}
                    >
                      <DropdownMenuItem>{t.calendar}</DropdownMenuItem>
                      <DropdownMenuItem>{t.chat}</DropdownMenuItem>
                      <DropdownMenuSeparator />
                      <DropdownMenuItem>{t.webhook}</DropdownMenuItem>
                    </DropdownMenuSubContent>
                  </DropdownMenuPortal>
                </DropdownMenuSub>
                <DropdownMenuSeparator />
                <DropdownMenuItem>{t.advanced}</DropdownMenuItem>
              </DropdownMenuSubContent>
            </DropdownMenuPortal>
          </DropdownMenuSub>
          <DropdownMenuItem>
            {t.newTeam}
            <DropdownMenuShortcut>⌘+T</DropdownMenuShortcut>
          </DropdownMenuItem>
        </DropdownMenuGroup>
        <DropdownMenuSeparator />
        <DropdownMenuGroup>
          <DropdownMenuLabel>{t.view}</DropdownMenuLabel>
          <DropdownMenuCheckboxItem
            checked={showStatusBar}
            onCheckedChange={setShowStatusBar}
          >
            {t.statusBar}
          </DropdownMenuCheckboxItem>
          <DropdownMenuCheckboxItem
            checked={showActivityBar}
            onCheckedChange={setShowActivityBar}
          >
            {t.activityBar}
          </DropdownMenuCheckboxItem>
          <DropdownMenuCheckboxItem
            checked={showPanel}
            onCheckedChange={setShowPanel}
          >
            {t.panel}
          </DropdownMenuCheckboxItem>
        </DropdownMenuGroup>
        <DropdownMenuSeparator />
        <DropdownMenuGroup>
          <DropdownMenuLabel>{t.position}</DropdownMenuLabel>
          <DropdownMenuRadioGroup value={position} onValueChange={setPosition}>
            <DropdownMenuRadioItem value="top">{t.top}</DropdownMenuRadioItem>
            <DropdownMenuRadioItem value="bottom">
              {t.bottom}
            </DropdownMenuRadioItem>
            <DropdownMenuRadioItem value="right">
              {t.right}
            </DropdownMenuRadioItem>
            <DropdownMenuRadioItem value="left">{t.left}</DropdownMenuRadioItem>
          </DropdownMenuRadioGroup>
        </DropdownMenuGroup>
        <DropdownMenuSeparator />
        <DropdownMenuGroup>
          <DropdownMenuItem variant="destructive">{t.logout}</DropdownMenuItem>
        </DropdownMenuGroup>
      </DropdownMenuContent>
    </DropdownMenu>
  );
}

export default DropdownMenuRtl;
```

## API Reference

See the [Base UI documentation](https://base-ui.com/react/components/menu) for the full API reference.

- [Documentation](https://base-ui.com/react/components/menu)
- [API reference](https://base-ui.com/react/components/menu#api-reference)


---

# Editor

A client-loaded code editor with preview, toolbar actions, and fullscreen modes.

Page: https://sui.draco.dev/docs/components/editor

### Example: editor-demo

```tsx
"use client";
import { Editor } from "@workspace/ui/components/editor";
import { useState } from "react";
import type { ExampleProps } from "../types";
export default function Example({ locale }: ExampleProps) {
  const chinese = locale === "zh-CN";
  const [language, setLanguage] = useState("markdown");
  const [value, setValue] = useState(
    chinese
      ? "# 项目说明\n\n编辑这里的 **Markdown**，然后切换预览。\n\n- [x] 双语文档\n- [ ] 下一次发布"
      : "# Project notes\n\nEdit this **Markdown**, then switch to preview.\n\n- [x] Bilingual docs\n- [ ] Next release",
  );
  return (
    <Editor
      value={value}
      onChange={setValue}
      language={language}
      onLanguageChange={setLanguage}
      languages={[
        { value: "markdown", label: "Markdown" },
        { value: "html", label: "HTML" },
        { value: "typescript", label: "TypeScript" },
        { value: "tsx", label: "TSX" },
        { value: "json", label: "JSON" },
      ]}
      height={320}
      toolbarTitle={chinese ? "项目说明" : "Project notes"}
      labels={
        chinese
          ? {
              copied: "已复制",
              copyFailed: "复制失败",
              loading: "正在加载编辑器",
              loadingPreview: "正在加载预览",
              language: "语言",
              error: "无法加载编辑器",
              preview: "预览",
              hidePreview: "隐藏预览",
              split: "并排",
              copy: "复制",
              fullscreen: "全屏",
              exitFullscreen: "退出全屏",
            }
          : undefined
      }
    />
  );
}
```

## Installation

```bash
bunx --bun shadcn@latest add @sui/editor
```

Install with the shadcn CLI or use the shared `@workspace/ui` package. Follow the [installation guide](/docs/installation) to configure the registry, load styles, and choose import aliases.

## Usage

```tsx
import { Editor } from "@workspace/ui/components/editor";
import { useState } from "react";

export function NotesEditor() {
  const [value, setValue] = useState("# Project notes");
  return <Editor value={value} onChange={setValue} language="markdown" height={320} />;
}
```

## Editing and value state

Use `value` and `onChange` for controlled editing. For internal state, omit `value` and supply `defaultValue`; `onChange` still reports edits. `disabled` makes the editor read-only. The editor is loaded in the client, with a loading placeholder during SSR and hydration. Switching language recreates the editor bridge and releases its previous model while retaining the current document value. Language services and workers load as needed. Workers are shared between mounted editors, stop after the last editor and all models are released, and are recreated when editing resumes. Editing does not execute the supplied code.

## Language selection

Supply `language` and `onLanguageChange` to show the shared Select language picker in the toolbar. Customize the candidates with `languages`, or use the common languages provided by default; the current value stays visible even when absent from that list. The caller controls the selected language, and selection preserves the document content. Set `toolbarLanguage={false}` to hide the picker. Without a callback it is hidden, and `disabled` disables selection. Language IDs are trimmed and lowercased; `ts`, `js`, `md`, and `text` normalize to `typescript`, `javascript`, `markdown`, and `plaintext`.

The first example switches between Markdown, HTML, TypeScript, TSX, and JSON. HTML and Markdown have built-in previews; the other languages retain editing mode.

## Preview modes

Markdown and HTML have built-in previews and start in `edit` mode. Toolbar actions switch between `edit`, `preview`, and `split`. The built-in HTML preview disables scripts with `sandbox="allow-same-origin"` and uses the isolated [Html Viewer](/docs/components/html-viewer), while Markdown uses [Markdown Viewer](/docs/components/markdown-viewer).

Provide `preview.component` for another renderer. It receives `content`, `language`, `scrollContainerRef`, and `onScroll`. Use `preview.defaultMode` for the initial mode, or `preview.mode` and `preview.onModeChange` for controlled mode selection. Custom previews default to split mode.

### Scroll synchronization

In split mode, scrolling either pane synchronizes the other by relative scroll progress, rather than source-line positions. Custom previews must attach `scrollContainerRef` and `onScroll` to the actual scrolling div. The built-in Markdown preview uses its outer scrolling container. The built-in HTML preview permits same-origin DOM access while keeping scripts disabled; the parent synchronizes its document scrolling container after each frame load and removes listeners on replacement or unmount.

The example supplies a long document, a custom scrolling preview, controlled preview mode, and browser fullscreen.

### Example: editor-preview

```tsx
"use client";

import {
  Editor,
  type EditorProps,
  type EditorViewMode,
} from "@workspace/ui/components/editor";
import { MarkdownViewer } from "@workspace/ui/components/markdown-viewer";
import {
  type ComponentProps,
  createContext,
  useContext,
  useState,
} from "react";
import type { ExampleProps } from "../types";

type PreviewProps = ComponentProps<
  NonNullable<EditorProps["preview"]>["component"]
>;
const PreviewLocale = createContext(false);
const sections = Array.from({ length: 24 }, (_, index) => index + 1);
function Preview({ content, scrollContainerRef, onScroll }: PreviewProps) {
  const chinese = useContext(PreviewLocale);
  return (
    <div
      ref={scrollContainerRef}
      onScroll={onScroll}
      className="h-full overflow-auto p-4"
    >
      <MarkdownViewer
        content={content}
        labels={chinese ? { empty: "没有预览内容" } : undefined}
      />
    </div>
  );
}
export default function Example({ locale }: ExampleProps) {
  const chinese = locale === "zh-CN";
  const [mode, setMode] = useState<EditorViewMode>("split");
  const [value, setValue] = useState(() =>
    sections
      .map((section) =>
        chinese
          ? `## 第 ${section} 节\n\n在编辑区和预览区分别滚动，另一区域按可滚动距离的比例跟随。\n\n这一段用于产生真实的长内容。\n`
          : `## Section ${section}\n\nScroll either pane to synchronize its relative position with the other pane.\n\nThis paragraph creates real long-form content.\n`,
      )
      .join("\n"),
  );
  return (
    <PreviewLocale.Provider value={chinese}>
      <div className="grid w-full gap-3">
        <Editor
          value={value}
          onChange={setValue}
          language="markdown"
          height={360}
          toolbarTitle={chinese ? "自定义滚动预览" : "Custom scrolling preview"}
          preview={{ component: Preview, mode, onModeChange: setMode }}
          fullscreen={{ mode: "screen" }}
          labels={
            chinese
              ? {
                  copied: "已复制",
                  copyFailed: "复制失败",
                  loading: "正在加载编辑器",
                  loadingPreview: "正在加载预览",
                  error: "无法加载编辑器",
                  preview: "预览",
                  hidePreview: "隐藏预览",
                  split: "并排",
                  copy: "复制",
                  fullscreen: "全屏",
                  exitFullscreen: "退出全屏",
                }
              : undefined
          }
        />
        <output className="text-muted-foreground text-sm" aria-live="polite">
          {chinese ? "受控模式" : "Controlled mode"}: {mode}
        </output>
      </div>
    </PreviewLocale.Provider>
  );
}
```

## Toolbar and read-only editing

`toolbarTitle` and `toolbar` accept a React node or a render function. The render function receives `EditorToolbarActionContext`, including the current value, language, theme, disabled state, Monaco instance, `format()`, `setMode()`, and `setFullscreen()`. `toolbar={false}` hides the entire toolbar.

`EditorToolbarButton` is available for custom icon actions. The example adds formatting and reset actions, and lets you enable or disable editing. Formatting depends on the formatter registered for the current language.

### Example: editor-toolbar

```tsx
"use client";
import { Button } from "@workspace/ui/components/button";
import { Editor } from "@workspace/ui/components/editor";
import { useState } from "react";
import type { ExampleProps } from "../types";

const initialValue = 'export const theme = { name: "bamboo", enabled: true };';
export default function Example({ locale }: ExampleProps) {
  const chinese = locale === "zh-CN";
  const stateLabels = chinese
    ? {
        enable: "允许编辑",
        readOnly: "设为只读",
      }
    : {
        enable: "Enable editing",
        readOnly: "Make read-only",
      };
  const [value, setValue] = useState(initialValue);
  const [disabled, setDisabled] = useState(false);
  return (
    <div className="grid w-full gap-4">
      <Button
        variant="outline"
        className="justify-self-start"
        type="button"
        onClick={() => setDisabled((current) => !current)}
      >
        {disabled ? stateLabels.enable : stateLabels.readOnly}
      </Button>
      <Editor
        value={value}
        onChange={setValue}
        disabled={disabled}
        language="typescript"
        height={260}
        toolbarTitle="theme.ts"
        toolbarMode={false}
        fullscreen={{ mode: "fixed" }}
        toolbar={({ format, disabled }) => (
          <div className="flex gap-2">
            <Button
              type="button"
              size="sm"
              variant="ghost"
              disabled={disabled}
              onClick={format}
            >
              {chinese ? "格式化" : "Format"}
            </Button>
            <Button
              type="button"
              size="sm"
              variant="ghost"
              disabled={disabled}
              onClick={() => setValue(initialValue)}
            >
              {chinese ? "恢复示例" : "Reset example"}
            </Button>
          </div>
        )}
        labels={
          chinese
            ? {
                copied: "已复制",
                copyFailed: "复制失败",
                loading: "正在加载编辑器",
                loadingPreview: "正在加载预览",
                error: "无法加载编辑器",
                preview: "预览",
                hidePreview: "隐藏预览",
                split: "并排",
                copy: "复制",
                fullscreen: "全屏",
                exitFullscreen: "退出全屏",
              }
            : undefined
        }
      />
    </div>
  );
}
```

## Fullscreen and localization

Fullscreen defaults to a fixed viewport overlay. Use `fullscreen={{ mode: "screen" }}` for the browser Fullscreen API, or `fullscreen={false}` to hide the action. `value`, `defaultValue`, and `onChange` inside the fullscreen options support controlled or uncontrolled fullscreen state. Browser fullscreen requires API support and permission; a failed request returns to the non-fullscreen state. The fixed overlay supports Escape, contains keyboard focus, and restores focus on exit. Accessible same-origin iframe controls participate in the focus cycle in DOM order; Escape inside the built-in HTML preview also exits. Frame loading and preview-mode changes refresh keyboard bindings. A cross-origin or opaque custom iframe is treated as one focus entry: the parent cannot intercept keys inside its inaccessible document, so retain an outer exit control.

Translate the `labels` for preview, split view, copy, fullscreen, loading, and failure messages. The examples keep user content in local component state; the component does not save documents or preferences for you. Monaco theme settings are shared within a page; keep multiple Editors on a consistent theme rather than relying on isolated light and dark instances.

## API reference

| Prop | Type | Default / behavior |
| --- | --- | --- |
| `value` / `defaultValue` | `string` | Controlled / initial internal content. |
| `onChange` | `(value: string) => void` | Reports content changes. |
| `language` | `string` | `"plaintext"`. |
| `onLanguageChange` | `(language: string) => void` | Requests selection; the caller updates `language`. |
| `languages` | `readonly EditorLanguageOption[]` | Common languages; each item has `value` and `label`. |
| `toolbarLanguage` | `boolean` | `true`; shows the picker when a callback is supplied. |
| `height` | `string \| number` | Controls editing area height; numbers are pixels. |
| `disabled` | `boolean` | `false`; read-only editing. |
| `toolbar`, `toolbarTitle` | `ReactNode \| render function` | Custom actions and heading; toolbar also accepts `false`. |
| `toolbarMode`, `toolbarCopy` | `boolean` | Both `true`. |
| `preview` | Preview options | Custom renderer, mode and mode-change callback. |
| `fullscreen` | `false \| object` | Fixed overlay by default. |
| `size` | Button size | `"icon-sm"` for toolbar actions. |
| `labels` | `Partial<EditorLabels>` | English feedback and action names. |
| `glass` | `boolean` | `false`; opt-in glass surface. |

`EditorProps`, `EditorLanguageOption`, `EditorLabels`, `EditorViewMode`, `EditorFullscreenMode`, and `EditorToolbarActionContext` are exported. The editor uses Monaco; see the [Monaco API](https://microsoft.github.io/monaco-editor/docs.html). For glass setup, see [Glass](/docs/components/glass).


---

# Empty

Use the Empty component to display an empty state.

Page: https://sui.draco.dev/docs/components/empty

### Example: empty-demo

```tsx
import { Button } from "@workspace/ui/components/button";
import {
  Empty,
  EmptyContent,
  EmptyDescription,
  EmptyHeader,
  EmptyMedia,
  EmptyTitle,
} from "@workspace/ui/components/empty";
import { ArrowUpRightIcon, FolderCodeIcon } from "lucide-react";

export default function EmptyDemo() {
  return (
    <Empty>
      <EmptyHeader>
        <EmptyMedia variant="icon">
          <FolderCodeIcon />
        </EmptyMedia>
        <EmptyTitle>No Projects Yet</EmptyTitle>
        <EmptyDescription>
          You haven&apos;t created any projects yet. Get started by creating
          your first project.
        </EmptyDescription>
      </EmptyHeader>
      <EmptyContent className="flex-row justify-center gap-2">
        <Button>Create Project</Button>
        <Button variant="outline">Import Project</Button>
      </EmptyContent>
      <Button
        variant="link"
        render={<a href="/docs" />}
        className="text-muted-foreground"
        size="sm"
        nativeButton={false}
      >
        Learn More <ArrowUpRightIcon />
      </Button>
    </Empty>
  );
}
```

## Installation

```bash
bunx --bun shadcn@latest add @sui/empty
```

Install with the shadcn CLI or use the shared `@workspace/ui` package. Follow the [installation guide](/docs/installation) to configure the registry, load styles, and choose import aliases.

## Usage

```tsx
import {
  Empty,
  EmptyContent,
  EmptyDescription,
  EmptyHeader,
  EmptyMedia,
  EmptyTitle,
} from "@workspace/ui/components/empty"
```

```tsx
<Empty>
  <EmptyHeader>
    <EmptyMedia variant="icon">
      <Icon />
    </EmptyMedia>
    <EmptyTitle>No data</EmptyTitle>
    <EmptyDescription>No data found</EmptyDescription>
  </EmptyHeader>
  <EmptyContent>
    <Button>Add data</Button>
  </EmptyContent>
</Empty>
```

## Composition

Use the following composition to build an `Empty` state:

```text
Empty
├── EmptyHeader
│   ├── EmptyMedia
│   ├── EmptyTitle
│   └── EmptyDescription
└── EmptyContent
```

## Outline

Use the `border` utility class to create an outline empty state.

### Example: empty-outline

```tsx
import { Button } from "@workspace/ui/components/button";
import {
  Empty,
  EmptyContent,
  EmptyDescription,
  EmptyHeader,
  EmptyMedia,
  EmptyTitle,
} from "@workspace/ui/components/empty";
import { CloudIcon } from "lucide-react";

export default function EmptyOutline() {
  return (
    <Empty className="border border-dashed">
      <EmptyHeader>
        <EmptyMedia variant="icon">
          <CloudIcon />
        </EmptyMedia>
        <EmptyTitle>Cloud Storage Empty</EmptyTitle>
        <EmptyDescription>
          Upload files to your cloud storage to access them anywhere.
        </EmptyDescription>
      </EmptyHeader>
      <EmptyContent>
        <Button variant="outline" size="sm">
          Upload Files
        </Button>
      </EmptyContent>
    </Empty>
  );
}
```

## Background

Use the `bg-*` and `bg-gradient-*` utilities to add a background to the empty state.

### Example: empty-background

```tsx
import { Button } from "@workspace/ui/components/button";
import {
  Empty,
  EmptyContent,
  EmptyDescription,
  EmptyHeader,
  EmptyMedia,
  EmptyTitle,
} from "@workspace/ui/components/empty";
import { BellIcon, RefreshCcwIcon } from "lucide-react";

export function EmptyMuted() {
  return (
    <Empty className="h-full bg-muted/30">
      <EmptyHeader>
        <EmptyMedia variant="icon">
          <BellIcon />
        </EmptyMedia>
        <EmptyTitle>No Notifications</EmptyTitle>
        <EmptyDescription className="max-w-xs text-pretty">
          You&apos;re all caught up. New notifications will appear here.
        </EmptyDescription>
      </EmptyHeader>
      <EmptyContent>
        <Button variant="outline">
          <RefreshCcwIcon data-icon="inline-start" />
          Refresh
        </Button>
      </EmptyContent>
    </Empty>
  );
}

export default EmptyMuted;
```

## Avatar

Use the `EmptyMedia` component to display an avatar in the empty state.

### Example: empty-avatar

```tsx
import {
  Avatar,
  AvatarFallback,
  AvatarImage,
} from "@workspace/ui/components/avatar";
import { Button } from "@workspace/ui/components/button";
import {
  Empty,
  EmptyContent,
  EmptyDescription,
  EmptyHeader,
  EmptyMedia,
  EmptyTitle,
} from "@workspace/ui/components/empty";

export default function EmptyAvatar() {
  return (
    <Empty>
      <EmptyHeader>
        <EmptyMedia variant="default">
          <Avatar className="size-12">
            <AvatarImage
              src="https://github.com/shadcn.png"
              className="grayscale"
            />
            <AvatarFallback>LR</AvatarFallback>
          </Avatar>
        </EmptyMedia>
        <EmptyTitle>User Offline</EmptyTitle>
        <EmptyDescription>
          This user is currently offline. You can leave a message to notify them
          or try again later.
        </EmptyDescription>
      </EmptyHeader>
      <EmptyContent>
        <Button size="sm">Leave Message</Button>
      </EmptyContent>
    </Empty>
  );
}
```

## Avatar Group

Use the `EmptyMedia` component to display an avatar group in the empty state.

### Example: empty-avatar-group

```tsx
import {
  Avatar,
  AvatarFallback,
  AvatarImage,
} from "@workspace/ui/components/avatar";
import { Button } from "@workspace/ui/components/button";
import {
  Empty,
  EmptyContent,
  EmptyDescription,
  EmptyHeader,
  EmptyMedia,
  EmptyTitle,
} from "@workspace/ui/components/empty";
import { PlusIcon } from "lucide-react";

export default function EmptyAvatarGroup() {
  return (
    <Empty>
      <EmptyHeader>
        <EmptyMedia>
          <div className="flex -space-x-2 *:data-[slot=avatar]:size-12 *:data-[slot=avatar]:ring-2 *:data-[slot=avatar]:ring-background *:data-[slot=avatar]:grayscale">
            <Avatar>
              <AvatarImage src="https://github.com/shadcn.png" alt="@shadcn" />
              <AvatarFallback>CN</AvatarFallback>
            </Avatar>
            <Avatar>
              <AvatarImage
                src="https://github.com/maxleiter.png"
                alt="@maxleiter"
              />
              <AvatarFallback>LR</AvatarFallback>
            </Avatar>
            <Avatar>
              <AvatarImage
                src="https://github.com/evilrabbit.png"
                alt="@evilrabbit"
              />
              <AvatarFallback>ER</AvatarFallback>
            </Avatar>
          </div>
        </EmptyMedia>
        <EmptyTitle>No Team Members</EmptyTitle>
        <EmptyDescription>
          Invite your team to collaborate on this project.
        </EmptyDescription>
      </EmptyHeader>
      <EmptyContent>
        <Button size="sm">
          <PlusIcon />
          Invite Members
        </Button>
      </EmptyContent>
    </Empty>
  );
}
```

## InputGroup

You can add an `InputGroup` component to the `EmptyContent` component.

### Example: empty-input-group

```tsx
import {
  Empty,
  EmptyContent,
  EmptyDescription,
  EmptyHeader,
  EmptyTitle,
} from "@workspace/ui/components/empty";
import {
  InputGroup,
  InputGroupAddon,
  InputGroupInput,
} from "@workspace/ui/components/input-group";
import { Kbd } from "@workspace/ui/components/kbd";
import { SearchIcon } from "lucide-react";

export default function EmptyInputGroup() {
  return (
    <Empty>
      <EmptyHeader>
        <EmptyTitle>404 - Not Found</EmptyTitle>
        <EmptyDescription>
          The page you&apos;re looking for doesn&apos;t exist. Try searching for
          what you need below.
        </EmptyDescription>
      </EmptyHeader>
      <EmptyContent>
        <InputGroup className="sm:w-3/4">
          <InputGroupInput placeholder="Try searching for pages..." />
          <InputGroupAddon>
            <SearchIcon />
          </InputGroupAddon>
          <InputGroupAddon align="inline-end">
            <Kbd>/</Kbd>
          </InputGroupAddon>
        </InputGroup>
        <EmptyDescription>
          Need help? <a href="/docs">Contact support</a>
        </EmptyDescription>
      </EmptyContent>
    </Empty>
  );
}
```

## RTL

To enable RTL support in shadcn/ui, see the [RTL configuration guide](https://ui.shadcn.com/docs/rtl).

### Example: empty-rtl

```tsx
"use client";

import { Button } from "@workspace/ui/components/button";
import {
  Empty,
  EmptyContent,
  EmptyDescription,
  EmptyHeader,
  EmptyMedia,
  EmptyTitle,
} from "@workspace/ui/components/empty";
import { ArrowUpRightIcon, FolderCodeIcon } from "lucide-react";
import { type Translations, useTranslation } from "./support";

const translations: Translations = {
  en: {
    dir: "ltr",
    values: {
      title: "No Projects Yet",
      description:
        "You haven't created any projects yet. Get started by creating your first project.",
      createProject: "Create Project",
      importProject: "Import Project",
      learnMore: "Learn More",
    },
  },
  ar: {
    dir: "rtl",
    values: {
      title: "لا توجد مشاريع بعد",
      description: "لم تقم بإنشاء أي مشاريع بعد. ابدأ بإنشاء مشروعك الأول.",
      createProject: "إنشاء مشروع",
      importProject: "استيراد مشروع",
      learnMore: "تعرف على المزيد",
    },
  },
  he: {
    dir: "rtl",
    values: {
      title: "אין פרויקטים עדיין",
      description:
        "עדיין לא יצרת פרויקטים. התחל על ידי יצירת הפרויקט הראשון שלך.",
      createProject: "צור פרויקט",
      importProject: "ייבא פרויקט",
      learnMore: "למד עוד",
    },
  },
};

export function EmptyRtl() {
  const { dir, t } = useTranslation(translations, "ar");

  return (
    <Empty dir={dir}>
      <EmptyHeader>
        <EmptyMedia variant="icon">
          <FolderCodeIcon />
        </EmptyMedia>
        <EmptyTitle>{t.title}</EmptyTitle>
        <EmptyDescription>{t.description}</EmptyDescription>
      </EmptyHeader>
      <EmptyContent className="flex-row justify-center gap-2">
        <Button>{t.createProject}</Button>
        <Button variant="outline">{t.importProject}</Button>
      </EmptyContent>
      <Button
        variant="link"
        render={<a href="/docs" />}
        className="text-muted-foreground"
        size="sm"
        nativeButton={false}
      >
        {t.learnMore}{" "}
        <ArrowUpRightIcon className="rtl:rotate-270" data-icon="inline-end" />
      </Button>
    </Empty>
  );
}

export default EmptyRtl;
```

## API Reference

### Empty

The main component of the empty state. Wraps the `EmptyHeader` and `EmptyContent` components.

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` |         |

```tsx
<Empty>
  <EmptyHeader />
  <EmptyContent />
</Empty>
```

### EmptyHeader

The `EmptyHeader` component wraps the empty media, title, and description.

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` |         |

```tsx
<EmptyHeader>
  <EmptyMedia />
  <EmptyTitle />
  <EmptyDescription />
</EmptyHeader>
```

### EmptyMedia

Use the `EmptyMedia` component to display the media of the empty state such as an icon or an image. You can also use it to display other components such as an avatar.

| Prop        | Type                  | Default   |
| ----------- | --------------------- | --------- |
| `variant`   | `"default" \| "icon"` | `default` |
| `className` | `string`              |           |

```tsx
<EmptyMedia variant="icon">
  <Icon />
</EmptyMedia>
```

```tsx
<EmptyMedia>
  <Avatar>
    <AvatarImage src="..." />
    <AvatarFallback>CN</AvatarFallback>
  </Avatar>
</EmptyMedia>
```

### EmptyTitle

Use the `EmptyTitle` component to display the title of the empty state.

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` |         |

```tsx
<EmptyTitle>No data</EmptyTitle>
```

### EmptyDescription

Use the `EmptyDescription` component to display the description of the empty state.

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` |         |

```tsx
<EmptyDescription>You do not have any notifications.</EmptyDescription>
```

### EmptyContent

Use the `EmptyContent` component to display the content of the empty state such as a button, input or a link.

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` |         |

```tsx
<EmptyContent>
  <Button>Add Project</Button>
</EmptyContent>
```


---

# Field

Combine labels, controls, and help text to compose accessible form fields and grouped inputs.

Page: https://sui.draco.dev/docs/components/field

### Example: field-demo

```tsx
import { Button } from "@workspace/ui/components/button";
import { Checkbox } from "@workspace/ui/components/checkbox";
import {
  Field,
  FieldDescription,
  FieldGroup,
  FieldLabel,
  FieldLegend,
  FieldSeparator,
  FieldSet,
} from "@workspace/ui/components/field";
import { Input } from "@workspace/ui/components/input";
import {
  Select,
  SelectContent,
  SelectGroup,
  SelectItem,
  SelectTrigger,
  SelectValue,
} from "@workspace/ui/components/select";
import { Textarea } from "@workspace/ui/components/textarea";
import { useId as usePreviewId } from "react";

const months = [
  { label: "MM", value: null },
  { label: "01", value: "01" },
  { label: "02", value: "02" },
  { label: "03", value: "03" },
  { label: "04", value: "04" },
  { label: "05", value: "05" },
  { label: "06", value: "06" },
  { label: "07", value: "07" },
  { label: "08", value: "08" },
  { label: "09", value: "09" },
  { label: "10", value: "10" },
  { label: "11", value: "11" },
  { label: "12", value: "12" },
];

const years = [
  { label: "YYYY", value: null },
  { label: "2024", value: "2024" },
  { label: "2025", value: "2025" },
  { label: "2026", value: "2026" },
  { label: "2027", value: "2027" },
  { label: "2028", value: "2028" },
  { label: "2029", value: "2029" },
];

export default function FieldDemo() {
  const previewId = usePreviewId();

  return (
    <div className="w-full max-w-md">
      <form>
        <FieldGroup>
          <FieldSet>
            <FieldLegend>Payment Method</FieldLegend>
            <FieldDescription>
              All transactions are secure and encrypted
            </FieldDescription>
            <FieldGroup>
              <Field>
                <FieldLabel htmlFor={`${previewId}-checkout-7j9-card-name-43j`}>
                  Name on Card
                </FieldLabel>
                <Input
                  id={`${previewId}-checkout-7j9-card-name-43j`}
                  placeholder="Evil Rabbit"
                  required
                />
              </Field>
              <Field>
                <FieldLabel
                  htmlFor={`${previewId}-checkout-7j9-card-number-uw1`}
                >
                  Card Number
                </FieldLabel>
                <Input
                  id={`${previewId}-checkout-7j9-card-number-uw1`}
                  placeholder="1234 5678 9012 3456"
                  required
                />
                <FieldDescription>
                  Enter your 16-digit card number
                </FieldDescription>
              </Field>
              <div className="grid grid-cols-3 gap-4">
                <Field>
                  <FieldLabel htmlFor={`${previewId}-checkout-exp-month-ts6`}>
                    Month
                  </FieldLabel>
                  <Select items={months}>
                    <SelectTrigger id={`${previewId}-checkout-exp-month-ts6`}>
                      <SelectValue />
                    </SelectTrigger>
                    <SelectContent>
                      <SelectGroup>
                        {months.map((item) => (
                          <SelectItem key={item.value} value={item.value}>
                            {item.label}
                          </SelectItem>
                        ))}
                      </SelectGroup>
                    </SelectContent>
                  </Select>
                </Field>
                <Field>
                  <FieldLabel
                    htmlFor={`${previewId}-checkout-7j9-exp-year-f59`}
                  >
                    Year
                  </FieldLabel>
                  <Select items={years}>
                    <SelectTrigger
                      id={`${previewId}-checkout-7j9-exp-year-f59`}
                    >
                      <SelectValue />
                    </SelectTrigger>
                    <SelectContent>
                      <SelectGroup>
                        {years.map((item) => (
                          <SelectItem key={item.value} value={item.value}>
                            {item.label}
                          </SelectItem>
                        ))}
                      </SelectGroup>
                    </SelectContent>
                  </Select>
                </Field>
                <Field>
                  <FieldLabel htmlFor={`${previewId}-checkout-7j9-cvv`}>
                    CVV
                  </FieldLabel>
                  <Input
                    id={`${previewId}-checkout-7j9-cvv`}
                    placeholder="123"
                    required
                  />
                </Field>
              </div>
            </FieldGroup>
          </FieldSet>
          <FieldSeparator />
          <FieldSet>
            <FieldLegend>Billing Address</FieldLegend>
            <FieldDescription>
              The billing address associated with your payment method
            </FieldDescription>
            <FieldGroup>
              <Field orientation="horizontal">
                <Checkbox
                  id={`${previewId}-checkout-7j9-same-as-shipping-wgm`}
                  defaultChecked
                />
                <FieldLabel
                  htmlFor={`${previewId}-checkout-7j9-same-as-shipping-wgm`}
                  className="font-normal"
                >
                  Same as shipping address
                </FieldLabel>
              </Field>
            </FieldGroup>
          </FieldSet>
          <FieldSet>
            <FieldGroup>
              <Field>
                <FieldLabel
                  htmlFor={`${previewId}-checkout-7j9-optional-comments`}
                >
                  Comments
                </FieldLabel>
                <Textarea
                  id={`${previewId}-checkout-7j9-optional-comments`}
                  placeholder="Add any additional comments"
                  className="resize-none"
                />
              </Field>
            </FieldGroup>
          </FieldSet>
          <Field orientation="horizontal">
            <Button type="submit">Submit</Button>
            <Button variant="outline" type="button">
              Cancel
            </Button>
          </Field>
        </FieldGroup>
      </form>
    </div>
  );
}
```

## Installation

```bash
bunx --bun shadcn@latest add @sui/field
```

Install with the shadcn CLI or use the shared `@workspace/ui` package. Follow the [installation guide](/docs/installation) to configure the registry, load styles, and choose import aliases.

## Usage

```tsx showLineNumbers
import {
  Field,
  FieldContent,
  FieldDescription,
  FieldError,
  FieldGroup,
  FieldLabel,
  FieldLegend,
  FieldSeparator,
  FieldSet,
  FieldTitle,
} from "@workspace/ui/components/field"
```

```tsx showLineNumbers
<FieldSet>
  <FieldLegend>Profile</FieldLegend>
  <FieldDescription>This appears on invoices and emails.</FieldDescription>
  <FieldGroup>
    <Field>
      <FieldLabel htmlFor="name">Full name</FieldLabel>
      <Input id="name" autoComplete="off" placeholder="Evil Rabbit" />
      <FieldDescription>This appears on invoices and emails.</FieldDescription>
    </Field>
    <Field>
      <FieldLabel htmlFor="username">Username</FieldLabel>
      <Input id="username" autoComplete="off" aria-invalid />
      <FieldError>Choose another username.</FieldError>
    </Field>
    <Field orientation="horizontal">
      <Switch id="newsletter" />
      <FieldLabel htmlFor="newsletter">Subscribe to the newsletter</FieldLabel>
    </Field>
  </FieldGroup>
</FieldSet>
```

## Composition

### Field

A single control with label, helper text, and validation.

```text
Field
├── FieldLabel
├── Input / Textarea / Switch / Select
├── FieldDescription
└── FieldError
```

### FieldGroup

Related fields in one group. Use `FieldSeparator` between sections when needed.

```text
FieldGroup
├── Field
│   ├── FieldLabel
│   ├── Input / Textarea / Switch / Select
│   ├── FieldDescription
│   └── FieldError
├── FieldSeparator
└── Field
    ├── FieldLabel
    └── Input / Textarea / Switch / Select
```

### FieldSet

Semantic grouping with a legend and description, usually containing a `FieldGroup`.

```text
FieldSet
├── FieldLegend
├── FieldDescription
└── FieldGroup
    ├── Field
    │   ├── FieldLabel
    │   ├── Input / Textarea / Switch / Select
    │   ├── FieldDescription
    │   └── FieldError
    └── Field
        ├── FieldLabel
        └── Input / Textarea / Switch / Select
```

## Anatomy

The `Field` family is designed for composing accessible forms. A typical field is structured as follows:

```tsx showLineNumbers
<Field>
  <FieldLabel htmlFor="input-id">Label</FieldLabel>
  {/* Input, Select, Switch, etc. */}
  <FieldDescription>Optional helper text.</FieldDescription>
  <FieldError>Validation message.</FieldError>
</Field>
```

- `Field` is the core wrapper for a single field.
- `FieldContent` is a flex column that groups label and description. Not required if you have no description.
- Wrap related fields with `FieldGroup`, and use `FieldSet` with `FieldLegend` for semantic grouping.

## Form

See the [Form](https://ui.shadcn.com/docs/forms) documentation for building forms with the `Field` component and [React Hook Form](https://ui.shadcn.com/docs/forms/react-hook-form), [Tanstack Form](https://ui.shadcn.com/docs/forms/tanstack-form), or [Formisch](https://ui.shadcn.com/docs/forms/formisch).

## Input

### Example: field-input

```tsx
import {
  Field,
  FieldDescription,
  FieldGroup,
  FieldLabel,
  FieldSet,
} from "@workspace/ui/components/field";
import { Input } from "@workspace/ui/components/input";
import { useId as usePreviewId } from "react";

export default function FieldInput() {
  const previewId = usePreviewId();

  return (
    <FieldSet className="w-full max-w-xs">
      <FieldGroup>
        <Field>
          <FieldLabel htmlFor={`${previewId}-username`}>Username</FieldLabel>
          <Input
            id={`${previewId}-username`}
            type="text"
            placeholder="Max Leiter"
          />
          <FieldDescription>
            Choose a unique username for your account.
          </FieldDescription>
        </Field>
        <Field>
          <FieldLabel htmlFor={`${previewId}-password`}>Password</FieldLabel>
          <FieldDescription>
            Must be at least 8 characters long.
          </FieldDescription>
          <Input
            id={`${previewId}-password`}
            type="password"
            placeholder="••••••••"
          />
        </Field>
      </FieldGroup>
    </FieldSet>
  );
}
```

## Textarea

### Example: field-textarea

```tsx
import {
  Field,
  FieldDescription,
  FieldGroup,
  FieldLabel,
  FieldSet,
} from "@workspace/ui/components/field";
import { Textarea } from "@workspace/ui/components/textarea";
import { useId as usePreviewId } from "react";

export default function FieldTextarea() {
  const previewId = usePreviewId();

  return (
    <FieldSet className="w-full max-w-xs">
      <FieldGroup>
        <Field>
          <FieldLabel htmlFor={`${previewId}-feedback`}>Feedback</FieldLabel>
          <Textarea
            id={`${previewId}-feedback`}
            placeholder="Your feedback helps us improve..."
            rows={4}
          />
          <FieldDescription>
            Share your thoughts about our service.
          </FieldDescription>
        </Field>
      </FieldGroup>
    </FieldSet>
  );
}
```

## Select

### Example: field-select

```tsx
import {
  Field,
  FieldDescription,
  FieldLabel,
} from "@workspace/ui/components/field";
import {
  Select,
  SelectContent,
  SelectGroup,
  SelectItem,
  SelectTrigger,
  SelectValue,
} from "@workspace/ui/components/select";

const items = [
  { label: "Choose department", value: null },
  { label: "Engineering", value: "engineering" },
  { label: "Design", value: "design" },
  { label: "Marketing", value: "marketing" },
  { label: "Sales", value: "sales" },
  { label: "Customer Support", value: "support" },
  { label: "Human Resources", value: "hr" },
  { label: "Finance", value: "finance" },
  { label: "Operations", value: "operations" },
];

export default function FieldSelect() {
  return (
    <Field className="w-full max-w-xs">
      <FieldLabel>Department</FieldLabel>
      <Select items={items}>
        <SelectTrigger>
          <SelectValue />
        </SelectTrigger>
        <SelectContent>
          <SelectGroup>
            {items.map((item) => (
              <SelectItem key={item.value} value={item.value}>
                {item.label}
              </SelectItem>
            ))}
          </SelectGroup>
        </SelectContent>
      </Select>
      <FieldDescription>
        Select your department or area of work.
      </FieldDescription>
    </Field>
  );
}
```

## Slider

### Example: field-slider

```tsx
"use client";

import {
  Field,
  FieldDescription,
  FieldTitle,
} from "@workspace/ui/components/field";
import { Slider } from "@workspace/ui/components/slider";
import * as React from "react";

export default function FieldSlider() {
  const [value, setValue] = React.useState([200, 800]);

  return (
    <Field className="w-full max-w-xs">
      <FieldTitle>Price Range</FieldTitle>
      <FieldDescription>
        Set your budget range ($
        <span className="font-medium tabular-nums">{value[0]}</span> -{" "}
        <span className="font-medium tabular-nums">{value[1]}</span>).
      </FieldDescription>
      <Slider
        value={value}
        onValueChange={(value) => setValue(value as [number, number])}
        max={1000}
        min={0}
        step={10}
        className="mt-2 w-full"
        aria-label="Price Range"
      />
    </Field>
  );
}
```

## Fieldset

### Example: field-fieldset

```tsx
import {
  Field,
  FieldDescription,
  FieldGroup,
  FieldLabel,
  FieldLegend,
  FieldSet,
} from "@workspace/ui/components/field";
import { Input } from "@workspace/ui/components/input";
import { useId as usePreviewId } from "react";

export function FieldFieldset() {
  const previewId = usePreviewId();

  return (
    <FieldSet className="w-full max-w-sm">
      <FieldLegend>Address Information</FieldLegend>
      <FieldDescription>
        We need your address to deliver your order.
      </FieldDescription>
      <FieldGroup>
        <Field>
          <FieldLabel htmlFor={`${previewId}-street`}>
            Street Address
          </FieldLabel>
          <Input
            id={`${previewId}-street`}
            type="text"
            placeholder="123 Main St"
          />
        </Field>
        <div className="grid grid-cols-2 gap-4">
          <Field>
            <FieldLabel htmlFor={`${previewId}-city`}>City</FieldLabel>
            <Input
              id={`${previewId}-city`}
              type="text"
              placeholder="New York"
            />
          </Field>
          <Field>
            <FieldLabel htmlFor={`${previewId}-zip`}>Postal Code</FieldLabel>
            <Input id={`${previewId}-zip`} type="text" placeholder="90502" />
          </Field>
        </div>
      </FieldGroup>
    </FieldSet>
  );
}

export default FieldFieldset;
```

## Checkbox

### Example: field-checkbox

```tsx
import { Checkbox } from "@workspace/ui/components/checkbox";
import {
  Field,
  FieldContent,
  FieldDescription,
  FieldGroup,
  FieldLabel,
  FieldLegend,
  FieldSeparator,
  FieldSet,
} from "@workspace/ui/components/field";
import { useId as usePreviewId } from "react";

export function FieldCheckbox() {
  const previewId = usePreviewId();

  return (
    <FieldGroup className="w-full max-w-xs">
      <FieldSet>
        <FieldLegend variant="label">
          Show these items on the desktop
        </FieldLegend>
        <FieldDescription>
          Select the items you want to show on the desktop.
        </FieldDescription>
        <FieldGroup className="gap-3">
          <Field orientation="horizontal">
            <Checkbox id={`${previewId}-finder-pref-9k2-hard-disks-ljj`} />
            <FieldLabel
              htmlFor={`${previewId}-finder-pref-9k2-hard-disks-ljj`}
              className="font-normal"
              defaultChecked
            >
              Hard disks
            </FieldLabel>
          </Field>
          <Field orientation="horizontal">
            <Checkbox id={`${previewId}-finder-pref-9k2-external-disks-1yg`} />
            <FieldLabel
              htmlFor={`${previewId}-finder-pref-9k2-external-disks-1yg`}
              className="font-normal"
            >
              External disks
            </FieldLabel>
          </Field>
          <Field orientation="horizontal">
            <Checkbox id={`${previewId}-finder-pref-9k2-cds-dvds-fzt`} />
            <FieldLabel
              htmlFor={`${previewId}-finder-pref-9k2-cds-dvds-fzt`}
              className="font-normal"
            >
              CDs, DVDs, and iPods
            </FieldLabel>
          </Field>
          <Field orientation="horizontal">
            <Checkbox
              id={`${previewId}-finder-pref-9k2-connected-servers-6l2`}
            />
            <FieldLabel
              htmlFor={`${previewId}-finder-pref-9k2-connected-servers-6l2`}
              className="font-normal"
            >
              Connected servers
            </FieldLabel>
          </Field>
        </FieldGroup>
      </FieldSet>
      <FieldSeparator />
      <Field orientation="horizontal">
        <Checkbox
          id={`${previewId}-finder-pref-9k2-sync-folders-nep`}
          defaultChecked
        />
        <FieldContent>
          <FieldLabel htmlFor={`${previewId}-finder-pref-9k2-sync-folders-nep`}>
            Sync Desktop & Documents folders
          </FieldLabel>
          <FieldDescription>
            Your Desktop & Documents folders are being synced with iCloud Drive.
            You can access them from other devices.
          </FieldDescription>
        </FieldContent>
      </Field>
    </FieldGroup>
  );
}

export default FieldCheckbox;
```

## Radio

### Example: field-radio

```tsx
import {
  Field,
  FieldDescription,
  FieldLabel,
  FieldLegend,
  FieldSet,
} from "@workspace/ui/components/field";
import {
  RadioGroup,
  RadioGroupItem,
} from "@workspace/ui/components/radio-group";
import { useId as usePreviewId } from "react";

export function FieldRadio() {
  const previewId = usePreviewId();

  return (
    <FieldSet className="w-full max-w-xs">
      <FieldLegend variant="label">Subscription Plan</FieldLegend>
      <FieldDescription>
        Yearly and lifetime plans offer significant savings.
      </FieldDescription>
      <RadioGroup defaultValue="monthly">
        <Field orientation="horizontal">
          <RadioGroupItem value="monthly" id={`${previewId}-plan-monthly`} />
          <FieldLabel
            htmlFor={`${previewId}-plan-monthly`}
            className="font-normal"
          >
            Monthly ($9.99/month)
          </FieldLabel>
        </Field>
        <Field orientation="horizontal">
          <RadioGroupItem value="yearly" id={`${previewId}-plan-yearly`} />
          <FieldLabel
            htmlFor={`${previewId}-plan-yearly`}
            className="font-normal"
          >
            Yearly ($99.99/year)
          </FieldLabel>
        </Field>
        <Field orientation="horizontal">
          <RadioGroupItem value="lifetime" id={`${previewId}-plan-lifetime`} />
          <FieldLabel
            htmlFor={`${previewId}-plan-lifetime`}
            className="font-normal"
          >
            Lifetime ($299.99)
          </FieldLabel>
        </Field>
      </RadioGroup>
    </FieldSet>
  );
}

export default FieldRadio;
```

## Switch

### Example: field-switch

```tsx
import { Field, FieldLabel } from "@workspace/ui/components/field";
import { Switch } from "@workspace/ui/components/switch";
import { useId as usePreviewId } from "react";

export default function FieldSwitch() {
  const previewId = usePreviewId();

  return (
    <Field orientation="horizontal" className="w-fit">
      <FieldLabel htmlFor={`${previewId}-2fa`}>
        Multi-factor authentication
      </FieldLabel>
      <Switch id={`${previewId}-2fa`} />
    </Field>
  );
}
```

## Choice Card

Wrap `Field` components inside `FieldLabel` to create selectable field groups. This works with `RadioItem`, `Checkbox` and `Switch` components.

### Example: field-choice-card

```tsx
import {
  Field,
  FieldContent,
  FieldDescription,
  FieldGroup,
  FieldLabel,
  FieldLegend,
  FieldSet,
  FieldTitle,
} from "@workspace/ui/components/field";
import {
  RadioGroup,
  RadioGroupItem,
} from "@workspace/ui/components/radio-group";
import { useId as usePreviewId } from "react";

export default function FieldChoiceCard() {
  const previewId = usePreviewId();

  return (
    <FieldGroup className="w-full max-w-xs">
      <FieldSet>
        <FieldLegend variant="label">Compute Environment</FieldLegend>
        <FieldDescription>
          Select the compute environment for your cluster.
        </FieldDescription>
        <RadioGroup defaultValue="kubernetes">
          <FieldLabel htmlFor={`${previewId}-kubernetes-r2h`}>
            <Field orientation="horizontal">
              <FieldContent>
                <FieldTitle>Kubernetes</FieldTitle>
                <FieldDescription>
                  Run GPU workloads on a K8s cluster.
                </FieldDescription>
              </FieldContent>
              <RadioGroupItem
                value="kubernetes"
                id={`${previewId}-kubernetes-r2h`}
              />
            </Field>
          </FieldLabel>
          <FieldLabel htmlFor={`${previewId}-vm-z4k`}>
            <Field orientation="horizontal">
              <FieldContent>
                <FieldTitle>Virtual Machine</FieldTitle>
                <FieldDescription>
                  Access a cluster to run GPU workloads.
                </FieldDescription>
              </FieldContent>
              <RadioGroupItem value="vm" id={`${previewId}-vm-z4k`} />
            </Field>
          </FieldLabel>
        </RadioGroup>
      </FieldSet>
    </FieldGroup>
  );
}
```

## Field Group

Stack `Field` components with `FieldGroup`. Add `FieldSeparator` to divide them.

### Example: field-group

```tsx
import { Checkbox } from "@workspace/ui/components/checkbox";
import {
  Field,
  FieldDescription,
  FieldGroup,
  FieldLabel,
  FieldSeparator,
  FieldSet,
} from "@workspace/ui/components/field";
import { useId as usePreviewId } from "react";

export default function FieldGroupExample() {
  const previewId = usePreviewId();

  return (
    <FieldGroup className="w-full max-w-xs">
      <FieldSet>
        <FieldLabel>Responses</FieldLabel>
        <FieldDescription>
          Get notified when ChatGPT responds to requests that take time, like
          research or image generation.
        </FieldDescription>
        <FieldGroup data-slot="checkbox-group">
          <Field orientation="horizontal">
            <Checkbox id={`${previewId}-push`} defaultChecked disabled />
            <FieldLabel htmlFor={`${previewId}-push`} className="font-normal">
              Push notifications
            </FieldLabel>
          </Field>
        </FieldGroup>
      </FieldSet>
      <FieldSeparator />
      <FieldSet>
        <FieldLabel>Tasks</FieldLabel>
        <FieldDescription>
          Get notified when tasks you&apos;ve created have updates.{" "}
          <a href="/docs">Manage tasks</a>
        </FieldDescription>
        <FieldGroup data-slot="checkbox-group">
          <Field orientation="horizontal">
            <Checkbox id={`${previewId}-push-tasks`} />
            <FieldLabel
              htmlFor={`${previewId}-push-tasks`}
              className="font-normal"
            >
              Push notifications
            </FieldLabel>
          </Field>
          <Field orientation="horizontal">
            <Checkbox id={`${previewId}-email-tasks`} />
            <FieldLabel
              htmlFor={`${previewId}-email-tasks`}
              className="font-normal"
            >
              Email notifications
            </FieldLabel>
          </Field>
        </FieldGroup>
      </FieldSet>
    </FieldGroup>
  );
}
```

## RTL

To enable RTL support in shadcn/ui, see the [RTL configuration guide](https://ui.shadcn.com/docs/rtl).

### Example: field-rtl

```tsx
"use client";

import { Button } from "@workspace/ui/components/button";
import { Checkbox } from "@workspace/ui/components/checkbox";
import {
  Field,
  FieldDescription,
  FieldGroup,
  FieldLabel,
  FieldLegend,
  FieldSeparator,
  FieldSet,
} from "@workspace/ui/components/field";
import { Input } from "@workspace/ui/components/input";
import {
  Select,
  SelectContent,
  SelectGroup,
  SelectItem,
  SelectTrigger,
  SelectValue,
} from "@workspace/ui/components/select";
import { Textarea } from "@workspace/ui/components/textarea";
import { useId as usePreviewId } from "react";
import { type Translations, useTranslation } from "./support";

const months = [
  { label: "MM", value: null },
  { label: "01", value: "01" },
  { label: "02", value: "02" },
  { label: "03", value: "03" },
  { label: "04", value: "04" },
  { label: "05", value: "05" },
  { label: "06", value: "06" },
  { label: "07", value: "07" },
  { label: "08", value: "08" },
  { label: "09", value: "09" },
  { label: "10", value: "10" },
  { label: "11", value: "11" },
  { label: "12", value: "12" },
];

const years = [
  { label: "YYYY", value: null },
  { label: "2024", value: "2024" },
  { label: "2025", value: "2025" },
  { label: "2026", value: "2026" },
  { label: "2027", value: "2027" },
  { label: "2028", value: "2028" },
  { label: "2029", value: "2029" },
];

const translations: Translations = {
  en: {
    dir: "ltr",
    values: {
      paymentMethod: "Payment Method",
      secureTransactions: "All transactions are secure and encrypted",
      nameOnCard: "Name on Card",
      cardNumber: "Card Number",
      cardNumberDescription: "Enter your 16-digit card number",
      month: "Month",
      year: "Year",
      cvv: "CVV",
      monthPlaceholder: "MM",
      month01: "01",
      month02: "02",
      month03: "03",
      month04: "04",
      month05: "05",
      month06: "06",
      month07: "07",
      month08: "08",
      month09: "09",
      month10: "10",
      month11: "11",
      month12: "12",
      billingAddress: "Billing Address",
      billingAddressDescription:
        "The billing address associated with your payment method",
      sameAsShipping: "Same as shipping address",
      comments: "Comments",
      commentsPlaceholder: "Add any additional comments",
      submit: "Submit",
      cancel: "Cancel",
    },
  },
  ar: {
    dir: "rtl",
    values: {
      paymentMethod: "طريقة الدفع",
      secureTransactions: "جميع المعاملات آمنة ومشفرة",
      nameOnCard: "الاسم على البطاقة",
      cardNumber: "رقم البطاقة",
      cardNumberDescription: "أدخل رقم البطاقة المكون من 16 رقمًا",
      month: "الشهر",
      year: "السنة",
      cvv: "CVV",
      monthPlaceholder: "ش.ش",
      month01: "٠١",
      month02: "٠٢",
      month03: "٠٣",
      month04: "٠٤",
      month05: "٠٥",
      month06: "٠٦",
      month07: "٠٧",
      month08: "٠٨",
      month09: "٠٩",
      month10: "١٠",
      month11: "١١",
      month12: "١٢",
      billingAddress: "عنوان الفوترة",
      billingAddressDescription: "عنوان الفوترة المرتبط بطريقة الدفع الخاصة بك",
      sameAsShipping: "نفس عنوان الشحن",
      comments: "تعليقات",
      commentsPlaceholder: "أضف أي تعليقات إضافية",
      submit: "إرسال",
      cancel: "إلغاء",
    },
  },
  he: {
    dir: "rtl",
    values: {
      paymentMethod: "אמצעי תשלום",
      secureTransactions: "כל העסקאות מאובטחות ומוצפנות",
      nameOnCard: "שם על הכרטיס",
      cardNumber: "מספר כרטיס",
      cardNumberDescription: "הזן את מספר הכרטיס בן 16 הספרות שלך",
      month: "חודש",
      year: "שנה",
      cvv: "CVV",
      monthPlaceholder: "MM",
      month01: "01",
      month02: "02",
      month03: "03",
      month04: "04",
      month05: "05",
      month06: "06",
      month07: "07",
      month08: "08",
      month09: "09",
      month10: "10",
      month11: "11",
      month12: "12",
      billingAddress: "כתובת חיוב",
      billingAddressDescription: "כתובת החיוב המשויכת לאמצעי התשלום שלך",
      sameAsShipping: "זהה לכתובת המשלוח",
      comments: "הערות",
      commentsPlaceholder: "הוסף הערות נוספות",
      submit: "שלח",
      cancel: "בטל",
    },
  },
};

export function FieldRtl() {
  const previewId = usePreviewId();

  const { dir, t } = useTranslation(translations, "ar");

  const getMonthLabel = (value: string | null): string => {
    if (value === null) return t.monthPlaceholder;
    const monthKey = `month${value}` as keyof typeof t;
    return t[monthKey] || value;
  };

  return (
    <div className="w-full max-w-md py-6" dir={dir}>
      <form>
        <FieldGroup>
          <FieldSet>
            <FieldLegend>{t.paymentMethod}</FieldLegend>
            <FieldDescription>{t.secureTransactions}</FieldDescription>
            <FieldGroup>
              <Field>
                <FieldLabel
                  htmlFor={`${previewId}-checkout-7j9-card-name-43j-rtl`}
                >
                  {t.nameOnCard}
                </FieldLabel>
                <Input
                  id={`${previewId}-checkout-7j9-card-name-43j-rtl`}
                  placeholder="Evil Rabbit"
                  required
                />
              </Field>
              <Field>
                <FieldLabel
                  htmlFor={`${previewId}-checkout-7j9-card-number-uw1-rtl`}
                >
                  {t.cardNumber}
                </FieldLabel>
                <Input
                  id={`${previewId}-checkout-7j9-card-number-uw1-rtl`}
                  placeholder="1234 5678 9012 3456"
                  required
                />
                <FieldDescription>{t.cardNumberDescription}</FieldDescription>
              </Field>
              <div className="grid grid-cols-3 gap-4">
                <Field>
                  <FieldLabel
                    htmlFor={`${previewId}-checkout-exp-month-ts6-rtl`}
                  >
                    {t.month}
                  </FieldLabel>
                  <Select items={months}>
                    <SelectTrigger
                      id={`${previewId}-checkout-exp-month-ts6-rtl`}
                    >
                      <SelectValue />
                    </SelectTrigger>
                    <SelectContent dir={dir}>
                      <SelectGroup>
                        {months.map((item) => (
                          <SelectItem key={item.value} value={item.value}>
                            {getMonthLabel(item.value)}
                          </SelectItem>
                        ))}
                      </SelectGroup>
                    </SelectContent>
                  </Select>
                </Field>
                <Field>
                  <FieldLabel
                    htmlFor={`${previewId}-checkout-7j9-exp-year-f59-rtl`}
                  >
                    {t.year}
                  </FieldLabel>
                  <Select items={years}>
                    <SelectTrigger
                      id={`${previewId}-checkout-7j9-exp-year-f59-rtl`}
                    >
                      <SelectValue />
                    </SelectTrigger>
                    <SelectContent dir={dir}>
                      <SelectGroup>
                        {years.map((item) => (
                          <SelectItem key={item.value} value={item.value}>
                            {item.label}
                          </SelectItem>
                        ))}
                      </SelectGroup>
                    </SelectContent>
                  </Select>
                </Field>
                <Field>
                  <FieldLabel htmlFor={`${previewId}-checkout-7j9-cvv-rtl`}>
                    {t.cvv}
                  </FieldLabel>
                  <Input
                    id={`${previewId}-checkout-7j9-cvv-rtl`}
                    placeholder="123"
                    required
                  />
                </Field>
              </div>
            </FieldGroup>
          </FieldSet>
          <FieldSeparator />
          <FieldSet>
            <FieldLegend>{t.billingAddress}</FieldLegend>
            <FieldDescription>{t.billingAddressDescription}</FieldDescription>
            <FieldGroup>
              <Field orientation="horizontal">
                <Checkbox
                  id={`${previewId}-checkout-7j9-same-as-shipping-wgm-rtl`}
                  defaultChecked
                />
                <FieldLabel
                  htmlFor={`${previewId}-checkout-7j9-same-as-shipping-wgm-rtl`}
                  className="font-normal"
                >
                  {t.sameAsShipping}
                </FieldLabel>
              </Field>
            </FieldGroup>
          </FieldSet>
          <FieldSet>
            <FieldGroup>
              <Field>
                <FieldLabel
                  htmlFor={`${previewId}-checkout-7j9-optional-comments-rtl`}
                >
                  {t.comments}
                </FieldLabel>
                <Textarea
                  id={`${previewId}-checkout-7j9-optional-comments-rtl`}
                  placeholder={t.commentsPlaceholder}
                  className="resize-none"
                />
              </Field>
            </FieldGroup>
          </FieldSet>
          <Field orientation="horizontal">
            <Button type="submit">{t.submit}</Button>
            <Button variant="outline" type="button">
              {t.cancel}
            </Button>
          </Field>
        </FieldGroup>
      </form>
    </div>
  );
}

export default FieldRtl;
```

## Responsive Layout

- **Vertical fields:** Default orientation stacks label, control, and helper text—ideal for mobile-first layouts.
- **Horizontal fields:** Set `orientation="horizontal"` on `Field` to align the label and control side-by-side. Pair with `FieldContent` to keep descriptions aligned.
- **Responsive fields:** Set `orientation="responsive"` for automatic column layouts inside container-aware parents. Apply `@container/field-group` classes on `FieldGroup` to switch orientations at specific breakpoints.

### Example: field-responsive

```tsx
import { Button } from "@workspace/ui/components/button";
import {
  Field,
  FieldContent,
  FieldDescription,
  FieldGroup,
  FieldLabel,
  FieldLegend,
  FieldSet,
} from "@workspace/ui/components/field";
import { Input } from "@workspace/ui/components/input";
import { useId as usePreviewId } from "react";

export function FieldResponsive() {
  const previewId = usePreviewId();

  return (
    <div className="w-full max-w-lg">
      <form>
        <FieldSet>
          <FieldLegend>Profile</FieldLegend>
          <FieldDescription>Fill in your profile information.</FieldDescription>
          <FieldGroup>
            <Field orientation="responsive">
              <FieldContent>
                <FieldLabel htmlFor={`${previewId}-name`}>Name</FieldLabel>
                <FieldDescription>
                  Provide your full name for identification
                </FieldDescription>
              </FieldContent>
              <Input
                id={`${previewId}-name`}
                placeholder="Evil Rabbit"
                required
              />
            </Field>
            <Field orientation="responsive">
              <Button type="submit">Submit</Button>
              <Button type="button" variant="outline">
                Cancel
              </Button>
            </Field>
          </FieldGroup>
        </FieldSet>
      </form>
    </div>
  );
}

export default FieldResponsive;
```

## Validation and Errors

- Add `data-invalid` to `Field` to switch the entire block into an error state.
- Add `aria-invalid` on the input itself for assistive technologies.
- Render `FieldError` immediately after the control or inside `FieldContent` to keep error messages aligned with the field.

```tsx showLineNumbers /data-invalid/ /aria-invalid/
<Field data-invalid>
  <FieldLabel htmlFor="email">Email</FieldLabel>
  <Input id="email" type="email" aria-invalid />
  <FieldError>Enter a valid email address.</FieldError>
</Field>
```

## Accessibility

- `FieldSet` and `FieldLegend` keep related controls grouped for keyboard and assistive tech users.
- `Field` outputs `role="group"` so nested controls inherit labeling from `FieldLabel` and `FieldLegend` when combined.
- Apply `FieldSeparator` sparingly to ensure screen readers encounter clear section boundaries.

## API Reference

### FieldSet

Container that renders a semantic `fieldset` with spacing presets.

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` |         |

```tsx
<FieldSet>
  <FieldLegend>Delivery</FieldLegend>
  <FieldGroup>{/* Fields */}</FieldGroup>
</FieldSet>
```

### FieldLegend

Legend element for a `FieldSet`. Switch to the `label` variant to align with label sizing.

| Prop        | Type                  | Default    |
| ----------- | --------------------- | ---------- |
| `variant`   | `"legend" \| "label"` | `"legend"` |
| `className` | `string`              |            |

```tsx
<FieldLegend variant="label">Notification Preferences</FieldLegend>
```

The `FieldLegend` has two variants: `legend` and `label`. The `label` variant applies label sizing and alignment. Handy if you have nested `FieldSet`.

### FieldGroup

Layout wrapper that stacks `Field` components and enables container queries for responsive orientations.

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` |         |

```tsx
<FieldGroup className="@container/field-group flex flex-col gap-6">
  <Field>{/* ... */}</Field>
  <Field>{/* ... */}</Field>
</FieldGroup>
```

### Field

The core wrapper for a single field. Provides orientation control, invalid state styling, and spacing.

| Prop           | Type                                         | Default      |
| -------------- | -------------------------------------------- | ------------ |
| `orientation`  | `"vertical" \| "horizontal" \| "responsive"` | `"vertical"` |
| `className`    | `string`                                     |              |
| `data-invalid` | `boolean`                                    |              |

```tsx
<Field orientation="horizontal">
  <FieldLabel htmlFor="remember">Remember me</FieldLabel>
  <Switch id="remember" />
</Field>
```

### FieldContent

Flex column that groups control and descriptions when the label sits beside the control. Not required if you have no description.

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` |         |

```tsx
<Field>
  <Checkbox id="notifications" />
  <FieldContent>
    <FieldLabel htmlFor="notifications">Notifications</FieldLabel>
    <FieldDescription>Email, SMS, and push options.</FieldDescription>
  </FieldContent>
</Field>
```

### FieldLabel

Label styled for both direct inputs and nested `Field` children.

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` |         |

```tsx
<FieldLabel htmlFor="email">Email</FieldLabel>
```

### FieldTitle

Renders a title with label styling inside `FieldContent`.

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` |         |

```tsx
<FieldContent>
  <FieldTitle>Enable Touch ID</FieldTitle>
  <FieldDescription>Unlock your device faster.</FieldDescription>
</FieldContent>
```

### FieldDescription

Helper text slot that automatically balances long lines in horizontal layouts.

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` |         |

```tsx
<FieldDescription>We never share your email with anyone.</FieldDescription>
```

### FieldSeparator

Visual divider to separate sections inside a `FieldGroup`. Accepts optional inline content.

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` |         |

```tsx
<FieldSeparator>Or continue with</FieldSeparator>
```

### FieldError

Accessible error container that accepts children or an `errors` array (e.g., from `react-hook-form`).

| Prop        | Type                                       | Default |
| ----------- | ------------------------------------------ | ------- |
| `errors`    | `Array<{ message?: string } \| undefined>` |         |
| `className` | `string`                                   |         |

```tsx
<FieldError errors={errors.username} />
```

When the `errors` array contains multiple messages, the component renders a list automatically.

`FieldError` also accepts issues produced by any validator that implements [Standard Schema](https://standardschema.dev/), including Zod, Valibot, and ArkType. Pass the `issues` array from the schema result directly to render a unified error list across libraries.


---

# Glass

SVG highlights and CSS frosted surfaces, progressively enhanced with WebGPU refraction.

Page: https://sui.draco.dev/docs/components/glass

## CSS + SVG

CSS Gaussian backdrop blur and SVG edge highlights, without initializing WebGPU or capturing the background. Clear and frosted surfaces use the current theme background, while text keeps its semantic color. Switch the site appearance to compare light and dark modes.

### Example: glass-demo

```tsx
"use client";
import { GlassProvider, GlassSurface } from "@workspace/ui/components/glass";
import { useRef } from "react";
import type { ExampleProps } from "../types";

const tiles = [
  "bg-blue-500",
  "bg-emerald-500",
  "bg-amber-400",
  "bg-rose-500",
  "bg-violet-500",
  "bg-cyan-500",
];
export default function Example({ locale }: ExampleProps) {
  const chinese = locale === "zh-CN";
  const scene = useRef<HTMLDivElement>(null);
  return (
    <GlassProvider mode="css" captureTarget={scene}>
      <div
        ref={scene}
        className="relative isolate grid min-h-80 w-full items-center gap-4 overflow-hidden rounded-2xl p-6 lg:grid-cols-3"
      >
        <div
          className="absolute inset-0 -z-10 grid grid-cols-3 gap-2 bg-muted p-2"
          aria-hidden="true"
        >
          {tiles.map((tile) => (
            <div key={tile} className={`${tile} rounded-xl`} />
          ))}
        </div>
        <GlassSurface
          glass={false}
          className="rounded-2xl border bg-background p-6 text-foreground"
        >
          <h3>{chinese ? "普通表面" : "Standard surface"}</h3>
          <p className="mt-2 text-muted-foreground text-sm">
            {chinese
              ? "不采样背景，保持默认外观"
              : "Keeps the default appearance without sampling the background."}
          </p>
        </GlassSurface>
        <GlassSurface
          material="clear"
          className="rounded-2xl bg-background p-6 text-foreground"
        >
          <h3>{chinese ? "清透玻璃" : "Clear glass"}</h3>
          <p className="mt-2 text-muted-foreground text-sm">
            {chinese
              ? "轻度模糊与柔和边缘高光，保持背景可辨"
              : "A light blur and soft edge highlights keep the background recognizable."}
          </p>
        </GlassSurface>
        <GlassSurface
          material="frosted"
          className="rounded-2xl bg-background p-6 text-foreground"
        >
          <h3>{chinese ? "磨砂玻璃" : "Frosted glass"}</h3>
          <p className="mt-2 text-muted-foreground text-sm">
            {chinese
              ? "更强的模糊和色调遮罩，适合承载正文。无需截图或 GPU"
              : "A stronger blur and tint support readable content. No snapshot or GPU is needed."}
          </p>
        </GlassSurface>
      </div>
    </GlassProvider>
  );
}
```

## Installation

```bash
bunx --bun shadcn@latest add @sui/glass
```

Install with the shadcn CLI or use the shared `@workspace/ui` package. Follow the [installation guide](/docs/installation) to configure the registry, load styles, and choose import aliases.

## Usage

```tsx
import { GlassProvider, GlassSurface } from "@workspace/ui/components/glass";
import { useRef } from "react";

export function GlassPanel() {
  const sceneRef = useRef<HTMLDivElement>(null);
  return (
    <GlassProvider mode="css" material="frosted" captureTarget={sceneRef}>
      <div ref={sceneRef} className="relative rounded-2xl bg-muted p-6">
        <GlassSurface className="rounded-2xl bg-background p-6">
          A glass surface
        </GlassSurface>
      </div>
    </GlassProvider>
  );
}
```

## How the surface is rendered

Glass starts with directional SVG edge highlights and a CSS backdrop blur. This base appearance is available without a GPU renderer. Server rendering does not depend on a GPU, and the component keeps its ordinary DOM structure and refs.

The provider defaults to `mode="css"`: it does not request a GPU or capture the document. Opt into `mode="auto"` to attempt WebGPU enhancement. When `navigator.gpu` is available and device initialization and background capture both succeed, WebGPU adds real refraction from a DOM snapshot. The presence of `navigator.gpu` alone does not guarantee enhancement. If initialization, sampling, or rendering fails, the SVG and CSS appearance remains in place.

The default treatment adds no border or decorative outer ring: the soft SVG edge defines the outline. Interactive controls retain their keyboard focus rings.

Glass is opt-in: ordinary components keep `glass={false}` by default. `GlassSurface` itself defaults to `glass={true}` and can be disabled for a direct comparison.

The provider shares background capture and rendering settings across its descendants. `captureTarget` can be an element or an element ref; scope it to the visual region you need instead of capturing an unnecessarily large document. In auto mode, instances with the same actual capture target, scene revision, and occlusion set share one background snapshot and one uploaded GPU texture. Each surface uses its own sampling coordinates and rounded outline. Moving a surface updates coordinates without recapturing an unchanged background. Background changes invalidate the snapshot. Portal overlays require another snapshot only when their background or occlusion set differs. Capture uses `html-to-image`; enhancement uses native WebGPU. The Glass runtime uses a static import; the capture dependency and WebGPU renderer load only when enhancement needs them.

CSS, fallback, and enhanced modes share one continuous SVG edge-lighting layer. The GPU handles background refraction and blur without adding a second rim. New frames replace the previous frame only after image decoding completes.

## WebGPU enhancement

The CSS backdrop responds to the underlying page directly. When WebGPU enhancement is active, text changes, ordinary images, grids, resizing, and scrolling can update its background snapshot. Ordinary captures are capped at 5Hz and scrolling captures at 10Hz, with captures serialized through a shared queue, so there is a short delay between a background change and its refracted appearance. This is not a live video feed. Use the provider ref’s `refresh()` when your application needs to request another snapshot.

This demonstration is separate from the CSS + SVG example above. Its status reports the actual rendering mode. The example enables `mode="auto"`, changes background text, and provides refraction, blur, and edge-highlight sliders. Its two independent surfaces share a scene. Scroll the exposed background around the surfaces. Setting strength to `0` lets you compare the captured background with its refracted version when enhancement is active; an unsupported device continues to show the CSS and SVG material.

### Example: glass-dynamic

```tsx
"use client";
import { Button } from "@workspace/ui/components/button";
import {
  type GlassHandle,
  GlassProvider,
  GlassSurface,
} from "@workspace/ui/components/glass";
import { Input } from "@workspace/ui/components/input";
import { Label } from "@workspace/ui/components/label";
import { ScrollArea } from "@workspace/ui/components/scroll-area";
import { useEffect, useId, useRef, useState } from "react";
import type { ExampleProps } from "../types";

const illustration =
  "data:image/svg+xml," +
  encodeURIComponent(
    '<svg xmlns="http://www.w3.org/2000/svg" width="600" height="180" viewBox="0 0 600 180"><defs><pattern id="grid" width="24" height="24" patternUnits="userSpaceOnUse"><path d="M24 0H0V24" fill="none" stroke="#fff" stroke-opacity=".65" stroke-width="1.5"/></pattern></defs><rect width="600" height="180" fill="#648493"/><circle cx="120" cy="80" r="90" fill="#AE916B"/><circle cx="360" cy="140" r="130" fill="#70866A"/><path d="M0 140L600 20" stroke="#BC6C73" stroke-width="24"/><rect width="600" height="180" fill="url(#grid)"/></svg>',
  );
const rows = Array.from({ length: 16 }, (_, index) => index + 1);
export default function Example({ locale }: ExampleProps) {
  const chinese = locale === "zh-CN";
  const stateLabels = chinese
    ? {
        ready: "当前渲染：WebGPU 增强 + SVG 高光",
        fallback: "当前渲染：CSS + SVG（增强不可用）",
        loading: "当前渲染：CSS + SVG（等待增强）",
      }
    : {
        ready: "Rendering: WebGPU enhancement + SVG highlights",
        fallback: "Rendering: CSS + SVG (enhancement unavailable)",
        loading: "Rendering: CSS + SVG (awaiting enhancement)",
      };
  const id = useId();
  const scene = useRef<HTMLDivElement>(null);
  const controller = useRef<GlassHandle>(null);
  const [rendering, setRendering] = useState<"ready" | "fallback" | "loading">(
    "loading",
  );
  useEffect(() => {
    const target = scene.current;
    if (!target) return;
    const update = () => {
      const states = [...target.querySelectorAll('[data-glass="true"]')].map(
        (element) => element.getAttribute("data-glass-state"),
      );
      let next: "ready" | "fallback" | "loading" = "loading";
      if (states.length && states.every((state) => state === "ready"))
        next = "ready";
      else if (states.includes("fallback")) next = "fallback";
      setRendering(next);
    };
    const observer = new MutationObserver(update);
    observer.observe(target, {
      subtree: true,
      attributes: true,
      attributeFilter: ["data-glass-state"],
    });
    update();
    return () => observer.disconnect();
  }, []);
  const [text, setText] = useState("SUI / REFRACTION");
  const [strength, setStrength] = useState(22);
  const [blur, setBlur] = useState(8);
  const [highlight, setHighlight] = useState(0.3);
  const controls = [
    {
      key: "strength",
      label: chinese ? "折射强度" : "Refraction strength",
      value: strength,
      max: 64,
      step: 1,
      change: setStrength,
    },
    {
      key: "blur",
      label: chinese ? "模糊" : "Blur",
      value: blur,
      max: 24,
      step: 1,
      change: setBlur,
    },
    {
      key: "highlight",
      label: chinese ? "边缘高光" : "Edge highlight",
      value: highlight,
      max: 1,
      step: 0.05,
      change: setHighlight,
    },
  ];
  return (
    <div className="grid w-full gap-4">
      <p role="status" className="text-muted-foreground text-sm">
        {stateLabels[rendering]}
      </p>
      <div className="flex flex-wrap items-end gap-3">
        <div className="grid flex-1 gap-2">
          <Label htmlFor={id}>{chinese ? "背景文字" : "Background text"}</Label>
          <Input
            id={id}
            value={text}
            onChange={(event) => setText(event.target.value)}
          />
        </div>
        <Button
          variant="outline"
          type="button"
          onClick={() => controller.current?.refresh()}
        >
          {chinese ? "刷新快照" : "Refresh snapshot"}
        </Button>
      </div>
      <div className="grid gap-4 sm:grid-cols-3">
        {controls.map(({ key, label, value, max, step, change }) => (
          <div key={key} className="grid gap-2">
            <Label htmlFor={`${id}-${key}`}>
              {label}: <output htmlFor={`${id}-${key}`}>{value}</output>
            </Label>
            <input
              id={`${id}-${key}`}
              type="range"
              min={0}
              max={max}
              step={step}
              value={value}
              onInput={(event) => change(Number(event.currentTarget.value))}
              className="w-full accent-primary"
            />
          </div>
        ))}
      </div>
      <GlassProvider
        mode="auto"
        ref={controller}
        captureTarget={scene}
        options={{ strength, blur, highlight }}
      >
        <div
          ref={scene}
          className="relative isolate h-96 overflow-hidden rounded-2xl border bg-muted"
        >
          <ScrollArea
            role="region"
            className="absolute inset-0"
            aria-label={chinese ? "可滚动的背景" : "Scrollable background"}
          >
            <img
              src={illustration}
              alt={
                chinese
                  ? "由圆形和斜线组成的彩色图案"
                  : "Colorful circles and a diagonal stripe"
              }
              className="h-44 w-full object-cover"
            />
            <div className="grid grid-cols-2 gap-2 p-4 sm:grid-cols-4">
              {rows.map((row) => (
                <div
                  key={row}
                  className="grid min-h-24 content-center gap-1 rounded-xl bg-background p-3"
                >
                  <p className="text-primary text-sm">{text}</p>
                  <p className="text-muted-foreground text-xs">
                    {chinese ? "网格" : "Grid"} {row}
                  </p>
                </div>
              ))}
            </div>
          </ScrollArea>
          <GlassSurface
            material="clear"
            className="absolute top-20 left-6 w-[calc(50%-2rem)] rounded-2xl bg-background p-4 text-foreground"
          >
            <p>{chinese ? "文字与图片背景" : "Text and image background"}</p>
            <p className="mt-2 text-muted-foreground text-sm">
              {chinese
                ? "调整滑块或滚动背景，比较折射与原始快照"
                : "Adjust the sliders or scroll to compare refraction with the original snapshot."}
            </p>
          </GlassSurface>
          <GlassSurface
            material="clear"
            className="absolute top-20 right-6 w-[calc(50%-2rem)] rounded-2xl bg-background p-4 text-foreground"
          >
            <p>
              {chinese ? "同一场景，独立表面" : "One scene, separate surfaces"}
            </p>
            <p className="mt-2 text-muted-foreground text-sm">
              {chinese
                ? "同场景共用截图与纹理，独立更新坐标"
                : "Matching scenes share a snapshot and texture, with separate sampling coordinates."}
            </p>
          </GlassSurface>
        </div>
      </GlassProvider>
    </div>
  );
}
```

## Inputs, viewers, overlays

Pass `glass` to supported shared components rather than replacing their native controls. Inputs retain their original DOM node, ref, form behavior, and focus ring. Independent buttons, inputs, choice controls, and toolbar actions inherit glass inside a glass container. Layout wrappers, content, and the native input inside an InputGroup reuse their owning surface. An explicit `glass={false}` disables a control or scope. The example uses an ordinary parent surface with independent glass controls, avoiding nested material sampling.

The example combines an editable input, a popover, a dialog, Editor, and Code Viewer. Ordinary content avoids repeated material layers. The dialog input is an independent interactive control and inherits glass, demonstrating nested glass while retaining its native focus ring. Keyboard, focus, copy, and editing behavior remains available.

### Example: glass-composition

```tsx
"use client";
import { Button } from "@workspace/ui/components/button";
import { CodeViewer } from "@workspace/ui/components/code-viewer";
import {
  Dialog,
  DialogContent,
  DialogDescription,
  DialogHeader,
  DialogTitle,
  DialogTrigger,
} from "@workspace/ui/components/dialog";
import { Editor } from "@workspace/ui/components/editor";
import { GlassProvider } from "@workspace/ui/components/glass";
import { Input } from "@workspace/ui/components/input";
import { Label } from "@workspace/ui/components/label";
import {
  Popover,
  PopoverContent,
  PopoverTrigger,
} from "@workspace/ui/components/popover";
import { useId, useRef, useState } from "react";
import type { ExampleProps } from "../types";
export default function Example({ locale }: ExampleProps) {
  const chinese = locale === "zh-CN";
  const id = useId();
  const scene = useRef<HTMLDivElement>(null);
  const [code, setCode] = useState('const theme = "bamboo";');
  return (
    <GlassProvider mode="css" captureTarget={scene}>
      <div
        ref={scene}
        className="relative isolate grid w-full gap-4 overflow-hidden rounded-2xl bg-muted p-5"
      >
        <div
          className="absolute inset-0 -z-10 grid grid-cols-3 gap-3 p-3"
          aria-hidden="true"
        >
          <div className="rounded-2xl bg-emerald-400/70" />
          <div className="rounded-2xl bg-blue-400/70" />
          <div className="rounded-2xl bg-rose-400/70" />
        </div>
        <div className="grid gap-4 rounded-2xl border bg-background p-5">
          <div className="grid gap-2">
            <Label htmlFor={id}>
              {chinese
                ? "原生输入仍可交互"
                : "The native input stays interactive"}
            </Label>
            <Input
              id={id}
              glass
              placeholder={chinese ? "输入一些文字" : "Type something"}
            />
          </div>
          <div className="flex flex-wrap gap-2">
            <Popover>
              <PopoverTrigger render={<Button variant="outline" glass />}>
                {chinese ? "玻璃浮层" : "Glass popover"}
              </PopoverTrigger>
              <PopoverContent glass>
                <p className="text-sm">
                  {chinese
                    ? "浮层保留 SVG 高光与 CSS 磨砂，内容维持清晰"
                    : "The popover keeps SVG highlights and CSS frosting while its content stays clear."}
                </p>
              </PopoverContent>
            </Popover>
            <Dialog>
              <DialogTrigger render={<Button variant="outline" glass />}>
                {chinese ? "打开对话框" : "Open dialog"}
              </DialogTrigger>
              <DialogContent glass>
                <DialogHeader>
                  <DialogTitle>
                    {chinese ? "玻璃对话框" : "Glass dialog"}
                  </DialogTitle>
                  <DialogDescription>
                    {chinese
                      ? "保留焦点管理、键盘和关闭行为"
                      : "Focus management, keyboard access, and dismissal are preserved."}
                  </DialogDescription>
                </DialogHeader>
                <Input
                  aria-label={chinese ? "对话框输入" : "Dialog input"}
                  placeholder={chinese ? "仍可输入" : "Still editable"}
                />
              </DialogContent>
            </Dialog>
          </div>
        </div>
        <Editor
          value={code}
          onChange={setCode}
          language="typescript"
          height={180}
          glass
          labels={
            chinese
              ? {
                  copied: "已复制",
                  copyFailed: "复制失败",
                  loading: "正在加载编辑器",
                  loadingPreview: "正在加载预览",
                  error: "无法加载编辑器",
                  preview: "预览",
                  hidePreview: "隐藏预览",
                  split: "并排",
                  copy: "复制",
                  fullscreen: "全屏",
                  exitFullscreen: "退出全屏",
                }
              : undefined
          }
          toolbarCopy={false}
          toolbarMode={false}
          fullscreen={false}
        />
        <CodeViewer
          code={code}
          lang="typescript"
          glass
          title={chinese ? "当前代码" : "Current code"}
          maxHeight={160}
          labels={
            chinese
              ? {
                  copy: "复制代码",
                  copied: "已复制",
                  copyFailed: "复制失败",
                  loading: "正在高亮",
                  error: "无法高亮代码",
                  empty: "没有代码",
                  expand: "展开",
                  collapse: "折叠",
                  writing: "正在编写",
                  ready: "就绪",
                }
              : undefined
          }
        />
      </div>
    </GlassProvider>
  );
}
```

[TabBar](/docs/components/tab-bar) provides independent application navigation with a moving glass lens. It shares the same provider and material foundation while keeping routing under application control.

## Materials

Choose `material="clear"` for a more transparent surface or `material="frosted"` for stronger frosting and a denser tint. Clear uses a `6px` blur and a `0.60` CSS tint opacity; frosted uses `8px` and `0.78`. The provider defaults to `frosted`; `GlassSurface` can override the inherited material for one surface. An explicit `options.blur` overrides the material blur. The default demonstration uses CSS and SVG only, with ordinary, clear, and frosted surfaces side by side.

## Themes and fallback

The default tint comes from the current surface background token. It follows light, dark, and accent themes while preserving primary and danger colors. Adjust `strength`, `blur`, `tint`, `tintOpacity`, and `highlight` on the provider for a shared treatment. Soft SVG highlights are confined to the surface edge; `highlight` controls their intensity. The default SVG and CSS appearance retains these edge-light details; both `highlight` and `blur` continue to apply without WebGPU.

When WebGPU or background capture is unavailable, the default frosted surface remains visible. Controls remain usable. The glass effect should improve a surface visually without being required to understand it.

Glass strengthens neutral secondary text and placeholders locally, while preserving the theme's primary, destructive, and focus colors. Check text against the actual background when choosing clear glass or overriding tint opacity; transparency alone cannot guarantee readable contrast over every background. Use a denser tint or an ordinary surface when the underlying content makes text difficult to read.

WebGPU enhancement checks the actual colors of text and input placeholders belonging to the surface, including their alpha, and adjusts the captured background toward a shared tint that supports at least 4.5:1 contrast. Independently painted children and nested glass surfaces handle their own backgrounds. If the collected colors cannot share a readable background, enhancement falls back to CSS and SVG. CSS fallback, generated or SVG text, custom blending, filters, and outer opacity still require checking against the rendered scene.

## Snapshot limitations

The WebGPU enhancement uses DOM capture, which is not a browser compositor screenshot. Cross-origin images need suitable CORS permission; cross-origin iframes cannot be read. Embedded iframe documents, video frames, tainted canvases, and other browser-managed surfaces may be absent or inaccurate in the snapshot. Canvas and other GPU-rendered content are not guaranteed to be captured.

Rapid animation can outpace the capture limit. Use ordinary surfaces or the frosted fallback when accurate live media is important, and keep the capture area modest on mobile devices.

Positive horizontal and vertical scaling preserves the original layout while mapping the snapshot and corner radii to the viewport. Rotation, skew, perspective, and mirrored transforms use the CSS + SVG fallback instead of displaying a misaligned snapshot.

## API reference

| Prop | Type | Default / behavior |
| --- | --- | --- |
| Provider `mode` | `"css" \| "auto"` | `"css"`; `"auto"` attempts WebGPU refraction. |
| Provider `material` | `"clear" \| "frosted"` | `"frosted"`; shared material. |
| Provider `options` | `GlassOptions` | Shared rendering settings. |
| Provider `captureTarget` | `HTMLElement \| null \| RefObject<HTMLElement \| null>` | Optional scoped DOM capture target. |
| Provider `ref` | `Ref<GlassHandle>` | `refresh(): void` requests a snapshot. |
| Options `strength` | `number` | `22`; WebGPU refraction strength. |
| Options `blur` | `number` | Material default; an explicit value overrides CSS and enhanced blur. |
| Options `tint` | `string` | Current surface background color. |
| Options `tintOpacity` | `number` | CSS and enhancement share the material default; an explicit value overrides both. |
| Options `highlight` | `number` | `0.3`. |
| Surface `glass` | `boolean` | `true`; ordinary component props default to `false`. |
| Surface `material` | `"clear" \| "frosted"` | Inherits the provider material. |
| Surface other props | Native div props | Includes `className`, `style`, and `ref`. |

The module exports `GlassProvider`, `GlassSurface`, `GlassOptions`, `GlassCaptureTarget`, `GlassProviderProps`, `GlassMode`, `GlassMaterial`, and `GlassHandle`. SVG and CSS provide the default surface; the optional enhancement uses [WebGPU](https://developer.mozilla.org/en-US/docs/Web/API/WebGPU_API). The public SUI props above govern component integration.


---

# Hover Card

For sighted users to preview content available behind a link.

Page: https://sui.draco.dev/docs/components/hover-card

### Example: hover-card-demo

```tsx
import { Button } from "@workspace/ui/components/button";
import {
  HoverCard,
  HoverCardContent,
  HoverCardTrigger,
} from "@workspace/ui/components/hover-card";

export default function HoverCardDemo() {
  return (
    <HoverCard>
      <HoverCardTrigger
        delay={10}
        closeDelay={100}
        render={<Button variant="link" />}
      >
        Hover Here
      </HoverCardTrigger>
      <HoverCardContent className="flex w-64 flex-col gap-0.5">
        <div className="font-semibold">@nextjs</div>
        <div>The React Framework – created and maintained by @vercel.</div>
        <div className="mt-1 text-muted-foreground text-xs">
          Joined December 2021
        </div>
      </HoverCardContent>
    </HoverCard>
  );
}
```

## Installation

```bash
bunx --bun shadcn@latest add @sui/hover-card
```

Install with the shadcn CLI or use the shared `@workspace/ui` package. Follow the [installation guide](/docs/installation) to configure the registry, load styles, and choose import aliases.

## Usage

```tsx showLineNumbers
import {
  HoverCard,
  HoverCardContent,
  HoverCardTrigger,
} from "@workspace/ui/components/hover-card"
```

```tsx showLineNumbers
<HoverCard>
  <HoverCardTrigger>Hover</HoverCardTrigger>
  <HoverCardContent>
    The React Framework – created and maintained by @vercel.
  </HoverCardContent>
</HoverCard>
```

## Composition

Use the following composition to build a `HoverCard`:

```text
HoverCard
├── HoverCardTrigger
└── HoverCardContent
```

## Trigger Delays

Use `delay` and `closeDelay` on the trigger to control when the card opens and
closes.

```tsx showLineNumbers
<HoverCard>
  <HoverCardTrigger delay={100} closeDelay={200}>
    Hover
  </HoverCardTrigger>
  <HoverCardContent>Content</HoverCardContent>
</HoverCard>
```

## Positioning

Use the `side` and `align` props on `HoverCardContent` to control placement.

```tsx showLineNumbers
<HoverCard>
  <HoverCardTrigger>Hover</HoverCardTrigger>
  <HoverCardContent side="top" align="start">
    Content
  </HoverCardContent>
</HoverCard>
```

## Basic

### Example: hover-card-demo

```tsx
import { Button } from "@workspace/ui/components/button";
import {
  HoverCard,
  HoverCardContent,
  HoverCardTrigger,
} from "@workspace/ui/components/hover-card";

export default function HoverCardDemo() {
  return (
    <HoverCard>
      <HoverCardTrigger
        delay={10}
        closeDelay={100}
        render={<Button variant="link" />}
      >
        Hover Here
      </HoverCardTrigger>
      <HoverCardContent className="flex w-64 flex-col gap-0.5">
        <div className="font-semibold">@nextjs</div>
        <div>The React Framework – created and maintained by @vercel.</div>
        <div className="mt-1 text-muted-foreground text-xs">
          Joined December 2021
        </div>
      </HoverCardContent>
    </HoverCard>
  );
}
```

## Sides

### Example: hover-card-sides

```tsx
import { Button } from "@workspace/ui/components/button";
import {
  HoverCard,
  HoverCardContent,
  HoverCardTrigger,
} from "@workspace/ui/components/hover-card";

const HOVER_CARD_SIDES = ["left", "top", "bottom", "right"] as const;

export function HoverCardSides() {
  return (
    <div className="flex flex-wrap justify-center gap-2">
      {HOVER_CARD_SIDES.map((side) => (
        <HoverCard key={side}>
          <HoverCardTrigger
            delay={100}
            closeDelay={100}
            render={<Button variant="outline" className="capitalize" />}
          >
            {side}
          </HoverCardTrigger>
          <HoverCardContent side={side}>
            <div className="flex flex-col gap-1">
              <h4 className="font-medium">Hover Card</h4>
              <p>This hover card appears on the {side} side of the trigger.</p>
            </div>
          </HoverCardContent>
        </HoverCard>
      ))}
    </div>
  );
}

export default HoverCardSides;
```

## RTL

To enable RTL support in shadcn/ui, see the [RTL configuration guide](https://ui.shadcn.com/docs/rtl).

### Example: hover-card-rtl

```tsx
"use client";

import { Button } from "@workspace/ui/components/button";
import {
  HoverCard,
  HoverCardContent,
  HoverCardTrigger,
} from "@workspace/ui/components/hover-card";
import { type Translations, useTranslation } from "./support";

const translations: Translations = {
  en: {
    dir: "ltr",
    values: {
      trigger: "Wireless Headphones",
      name: "Wireless Headphones",
      price: "$99.99",
      "inline-start": "Inline Start",
      left: "Left",
      top: "Top",
      bottom: "Bottom",
      right: "Right",
      "inline-end": "Inline End",
    },
  },
  ar: {
    dir: "rtl",
    values: {
      trigger: "سماعات لاسلكية",
      name: "سماعات لاسلكية",
      price: "٩٩.٩٩ $",
      "inline-start": "بداية السطر",
      left: "يسار",
      top: "أعلى",
      bottom: "أسفل",
      right: "يمين",
      "inline-end": "نهاية السطر",
    },
  },
  he: {
    dir: "rtl",
    values: {
      trigger: "אוזניות אלחוטיות",
      name: "אוזניות אלחוטיות",
      price: "99.99 $",
      "inline-start": "תחילת השורה",
      left: "שמאל",
      top: "למעלה",
      bottom: "למטה",
      right: "ימין",
      "inline-end": "סוף השורה",
    },
  },
};

const physicalSides = ["left", "top", "bottom", "right"] as const;
const logicalSides = ["inline-start", "inline-end"] as const;

export function HoverCardRtl() {
  const { dir, t } = useTranslation(translations, "ar");

  return (
    <div className="grid gap-4">
      <div className="flex flex-wrap justify-center gap-2">
        {physicalSides.map((side) => (
          <HoverCard key={side}>
            <HoverCardTrigger
              delay={10}
              closeDelay={100}
              render={<Button variant="outline" />}
            >
              {t[side]}
            </HoverCardTrigger>
            <HoverCardContent
              side={side}
              className="flex w-64 flex-col gap-1"
              dir={dir}
            >
              <div className="font-semibold">{t.name}</div>
              <div className="text-muted-foreground text-sm">{t.price}</div>
            </HoverCardContent>
          </HoverCard>
        ))}
      </div>
      <div className="flex flex-wrap justify-center gap-2">
        {logicalSides.map((side) => (
          <HoverCard key={side}>
            <HoverCardTrigger
              delay={10}
              closeDelay={100}
              render={<Button variant="outline" />}
            >
              {t[side]}
            </HoverCardTrigger>
            <HoverCardContent
              side={side}
              className="flex w-64 flex-col gap-1"
              dir={dir}
            >
              <div className="font-semibold">{t.name}</div>
              <div className="text-muted-foreground text-sm">{t.price}</div>
            </HoverCardContent>
          </HoverCard>
        ))}
      </div>
    </div>
  );
}

export default HoverCardRtl;
```

## API Reference

See the [Base UI](https://base-ui.com/react/components/hover-card#api-reference) documentation for more information.

- [Documentation](https://base-ui.com/react/components/hover-card)
- [API reference](https://base-ui.com/react/components/hover-card#api-reference)


---

# HTML Viewer

An isolated iframe preview for HTML content.

Page: https://sui.draco.dev/docs/components/html-viewer

### Example: html-viewer-demo

```tsx
"use client";
import { HtmlViewer } from "@workspace/ui/components/html-viewer";
import type { ExampleProps } from "../types";
export default function Example({ locale }: ExampleProps) {
  const chinese = locale === "zh-CN";
  const content = `<!doctype html><html lang="${chinese ? "zh-CN" : "en-US"}"><head><meta charset="utf-8"><style>body{font:14px system-ui;margin:24px;color:#202020;background:#f5f5f7}button{font:inherit;padding:8px 12px;border:1px solid #ccc;border-radius:12px;background:white}p{line-height:1.6}</style></head><body><h2>${chinese ? "隔离的 HTML 预览" : "Isolated HTML preview"}</h2><p>${chinese ? "此按钮仅改变 iframe 内的文字" : "This button changes text only inside the iframe."}</p><button onclick="this.textContent='${chinese ? "脚本已运行" : "Script ran"}'">${chinese ? "测试沙箱脚本" : "Test sandboxed script"}</button></body></html>`;
  return (
    <HtmlViewer
      content={content}
      title={chinese ? "交互式 HTML 示例" : "Interactive HTML example"}
      className="h-64 w-full rounded-xl border"
    />
  );
}
```

## Installation

```bash
bunx --bun shadcn@latest add @sui/html-viewer
```

Install with the shadcn CLI or use the shared `@workspace/ui` package. Follow the [installation guide](/docs/installation) to configure the registry, load styles, and choose import aliases.

## Usage

```tsx
import { HtmlViewer } from "@workspace/ui/components/html-viewer";

<HtmlViewer
  content="<h2>Hello</h2><p>Isolated HTML content.</p>"
  title="HTML content preview"
  className="h-64 w-full rounded-xl border"
/>;
```

## Iframe isolation

The component writes `content` to the iframe `srcDoc`. Styles inside the HTML document do not affect the surrounding application, and the application theme is not automatically injected into the document. Include the document styles you want to preview. Give the iframe a descriptive `title`, or translate `labels.preview`.

The default sandbox is `"allow-scripts"`, permitting scripts inside an opaque-origin frame without granting `allow-same-origin`. The first example demonstrates a button that changes only the iframe content.

## Restricting scripts

Set `sandbox=""` for a static preview without script execution. Pass other native iframe attributes, such as `allow`, `loading`, and `ref`, when needed. Changing sandbox permissions changes the capabilities of the content; keep permissions limited to what your preview requires.

### Example: html-viewer-sandbox

```tsx
"use client";
import { HtmlViewer } from "@workspace/ui/components/html-viewer";
import { Label } from "@workspace/ui/components/label";
import { Textarea } from "@workspace/ui/components/textarea";
import { useId, useState } from "react";
import type { ExampleProps } from "../types";
export default function Example({ locale }: ExampleProps) {
  const chinese = locale === "zh-CN";
  const id = useId();
  const [content, setContent] = useState(
    chinese
      ? "<h2>静态 HTML</h2><p>没有脚本权限的预览。</p>"
      : "<h2>Static HTML</h2><p>A preview without script permission.</p>",
  );
  return (
    <div className="grid w-full gap-3">
      <Label htmlFor={id}>{chinese ? "HTML 源码" : "HTML source"}</Label>
      <Textarea
        id={id}
        value={content}
        onChange={(event) => setContent(event.target.value)}
        rows={3}
      />
      <HtmlViewer
        content={content}
        sandbox=""
        title={
          chinese
            ? "禁止脚本的 HTML 预览"
            : "HTML preview with scripts disabled"
        }
        className="h-48 w-full rounded-xl border"
      />
    </div>
  );
}
```

## Layout and glass

The iframe defaults to filling its container. Set an explicit height on the component or its parent. `glass` styles the outer surface; it does not refract, capture, or theme the separate iframe document. Glass background snapshots cannot reliably include iframe contents.

## API reference

| Prop | Type | Default / behavior |
| --- | --- | --- |
| `content` | `string` | Required HTML source; mapped to `srcDoc`. |
| `sandbox` | Native iframe sandbox | `"allow-scripts"`. |
| `title` | `string` | `labels.preview` or `"HTML preview"`. |
| `labels` | `{ preview?: string }` | Fallback accessible title. |
| `glass` | `boolean` | `false`. |
| Other props | Native iframe props | Forwarded, including `className`, `ref`, and `loading`. |

The module exports `HtmlViewerProps`. See the [iframe element documentation](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe) for sandbox permissions. For source editing with preview, use [Editor](/docs/components/editor).


---

# Image Viewer

A dialog image viewer with navigation, zoom, rotation, and panning.

Page: https://sui.draco.dev/docs/components/image-viewer

### Example: image-viewer-demo

```tsx
"use client";
import { Button } from "@workspace/ui/components/button";
import { ImageViewer } from "@workspace/ui/components/image-viewer";
import { useState } from "react";
import type { ExampleProps } from "../types";

const colors = ["#70866A", "#648493", "#BC6C73"];
const images = colors.map(
  (color, index) =>
    "data:image/svg+xml," +
    encodeURIComponent(
      `<svg xmlns="http://www.w3.org/2000/svg" width="960" height="640" viewBox="0 0 960 640"><rect width="960" height="640" fill="${color}"/><circle cx="${240 + index * 100}" cy="240" r="180" fill="#ffffff" opacity=".4"/><path d="M0 560L960 180" stroke="#ffffff" stroke-width="40" opacity=".6"/><text x="60" y="600" font-family="sans-serif" font-size="56" fill="white">SUI ${index + 1}</text></svg>`,
    ),
);
export default function Example({ locale }: ExampleProps) {
  const chinese = locale === "zh-CN";
  const [open, setOpen] = useState(false);
  const [initialIndex, setInitialIndex] = useState(0);
  return (
    <div className="grid w-full gap-4">
      <div className="grid grid-cols-3 gap-3">
        {images.map((image, index) => (
          <Button
            key={image}
            type="button"
            variant="ghost"
            className="h-auto w-full overflow-hidden rounded-xl p-0"
            aria-label={
              chinese
                ? `查看示例图案 ${index + 1}`
                : `View example pattern ${index + 1}`
            }
            onClick={() => {
              setInitialIndex(index);
              setOpen(true);
            }}
          >
            <img
              src={image}
              alt={
                chinese
                  ? `示例图案 ${index + 1}`
                  : `Example pattern ${index + 1}`
              }
              className="aspect-[3/2] w-full object-cover"
            />
          </Button>
        ))}
      </div>
      <ImageViewer
        images={images}
        open={open}
        initialIndex={initialIndex}
        onClose={() => setOpen(false)}
        alt={chinese ? "示例图案" : "Example pattern"}
        labels={
          chinese
            ? {
                defaultAlt: "图片",
                loading: "正在加载图片",
                error: "无法加载图片",
                retry: "重试",
                viewer: "图片查看器",
                zoomOut: "缩小",
                zoomIn: "放大",
                rotateCounterclockwise: "逆时针旋转",
                rotateClockwise: "顺时针旋转",
                reset: "重置图片",
                close: "关闭图片查看器",
                previous: "上一张",
                next: "下一张",
                imageAlt: (alt, index) => `${alt} ${index}`,
                open: (alt, index) => `打开${alt} ${index}`,
                thumbnail: (alt, index) => `${alt}缩略图 ${index}`,
                position: (index, total) => `第 ${index} 张，共 ${total} 张`,
              }
            : undefined
        }
      />
    </div>
  );
}
```

## Installation

```bash
bunx --bun shadcn@latest add @sui/image-viewer
```

Install with the shadcn CLI or use the shared `@workspace/ui` package. Follow the [installation guide](/docs/installation) to configure the registry, load styles, and choose import aliases.

## Usage

```tsx
import { Button } from "@workspace/ui/components/button";
import { ImageViewer } from "@workspace/ui/components/image-viewer";
import { useState } from "react";

const images = ["/photos/first.jpg", "/photos/second.jpg"];

export function Gallery() {
  const [open, setOpen] = useState(false);
  const [initialIndex, setInitialIndex] = useState(0);
  return (
    <>
      {images.map((src, index) => (
        <Button
          key={src}
          type="button"
          variant="ghost"
          className="h-auto overflow-hidden rounded-xl p-0"
          onClick={() => {
            setInitialIndex(index);
            setOpen(true);
          }}
        >
          <img src={src} alt={`Photo ${index + 1}`} />
        </Button>
      ))}
      <ImageViewer
        images={images}
        initialIndex={initialIndex}
        open={open}
        onClose={() => setOpen(false)}
        alt="Photo gallery"
      />
    </>
  );
}
```

## Opening and navigation

Opening is controlled through `open` and `onClose`. Supply one image URL or an array. With multiple images, navigation controls and thumbnails let the reader switch images. Zoom, rotation, reset, and panning actions are available inside the viewer. Empty image arrays render nothing. Wheel and pinch gestures zoom, and dragging pans. Arrow keys navigate, `+`/`-` zoom, and `0` resets the transform. Loading failures provide a retry action. Replace the image paths in the snippet with your own assets.

## Controlled image index

`initialIndex` sets the initial uncontrolled image, using zero-based indexes. For external selection, pass `index` and update it in `onIndexChange`. Selecting another image resets its transform. Reset is enabled only after zooming, rotating, or panning changes the image. The example opens a specific image and displays the selected zero-based index. Opening an uncontrolled viewer restores `initialIndex`; changing `initialIndex` while open also updates the selection.

### Example: image-viewer-controlled

```tsx
"use client";
import { Button } from "@workspace/ui/components/button";
import { ImageViewer } from "@workspace/ui/components/image-viewer";
import { useState } from "react";
import type { ExampleProps } from "../types";

const colors = ["#70866A", "#648493", "#BC6C73"];
const images = colors.map(
  (color, index) =>
    "data:image/svg+xml," +
    encodeURIComponent(
      `<svg xmlns="http://www.w3.org/2000/svg" width="960" height="640" viewBox="0 0 960 640"><rect width="960" height="640" fill="${color}"/><circle cx="${240 + index * 100}" cy="240" r="180" fill="#ffffff" opacity=".4"/><path d="M0 560L960 180" stroke="#ffffff" stroke-width="40" opacity=".6"/><text x="60" y="600" font-family="sans-serif" font-size="56" fill="white">SUI ${index + 1}</text></svg>`,
    ),
);
export default function Example({ locale }: ExampleProps) {
  const chinese = locale === "zh-CN";
  const [open, setOpen] = useState(false);
  const [index, setIndex] = useState(0);
  return (
    <div className="grid w-full gap-4">
      <div className="grid grid-cols-3 gap-3">
        {images.map((image, imageIndex) => (
          <Button
            key={image}
            variant="ghost"
            type="button"
            className="h-auto w-full overflow-hidden rounded-xl p-0"
            aria-label={
              chinese
                ? `查看几何图案 ${imageIndex + 1}`
                : `View geometric pattern ${imageIndex + 1}`
            }
            onClick={() => {
              setIndex(imageIndex);
              setOpen(true);
            }}
          >
            <img
              src={image}
              alt={
                chinese
                  ? `几何图案 ${imageIndex + 1}`
                  : `Geometric pattern ${imageIndex + 1}`
              }
              className="aspect-[3/2] w-full object-cover"
            />
          </Button>
        ))}
      </div>
      <output className="text-muted-foreground text-sm" aria-live="polite">
        {chinese
          ? `选中索引：${index}（从 0 开始）`
          : `Selected index: ${index} (zero-based)`}
      </output>
      <ImageViewer
        images={images}
        open={open}
        onClose={() => setOpen(false)}
        index={index}
        onIndexChange={setIndex}
        alt={chinese ? "几何图案" : "Geometric pattern"}
        labels={
          chinese
            ? {
                defaultAlt: "图片",
                loading: "正在加载图片",
                error: "无法加载图片",
                retry: "重试",
                viewer: "图片查看器",
                zoomOut: "缩小",
                zoomIn: "放大",
                rotateCounterclockwise: "逆时针旋转",
                rotateClockwise: "顺时针旋转",
                reset: "重置图片",
                close: "关闭图片查看器",
                previous: "上一张",
                next: "下一张",
                imageAlt: (alt, index) => `${alt} ${index}`,
                open: (alt, index) => `打开${alt} ${index}`,
                thumbnail: (alt, index) => `${alt}缩略图 ${index}`,
                position: (index, total) => `第 ${index} 张，共 ${total} 张`,
              }
            : undefined
        }
      />
    </div>
  );
}
```

## Labels, focus, and portal container

The viewer uses the shared [Dialog](/docs/components/dialog) for modal focus management and dismissal. `alt` describes the images, and `labels` customizes dialog, navigation, zoom, rotation, thumbnail, and position announcements. Function labels receive one-based image positions, while `index` and `onIndexChange` use zero-based indexes.

Use `container` to choose a Portal container when embedding the viewer in a local themed region. The glass effect applies to its surrounding dialog surface; the image itself remains clear.

## API reference

| Prop | Type | Default / behavior |
| --- | --- | --- |
| `images` | `string \| string[]` | Required image URL(s). |
| `open` | `boolean` | Required controlled dialog state. |
| `onClose` | `() => void` | Required close callback. |
| `index` | `number` | Controlled zero-based image index. |
| `initialIndex` | `number` | `0`; initial uncontrolled image. |
| `onIndexChange` | `(index: number) => void` | Reports selected zero-based index. |
| `alt` | `string` | `labels.defaultAlt` or `"Image"`. |
| `container` | `HTMLElement \| ShadowRoot \| RefObject<HTMLElement \| ShadowRoot \| null> \| null` | Optional Portal container. |
| `labels` | `Partial<ImageViewerLabels>` | English action and image labels. |
| `glass` | `boolean` | `false`. |

The module exports `ImageViewerProps` and `ImageViewerLabels`. The underlying modal behavior is documented in the [Base UI Dialog API](https://base-ui.com/react/components/dialog).


---

# Inline Copy Text

Inline code that stays readable and copies its value when activated.

Page: https://sui.draco.dev/docs/components/inline-copy-text

### Example: inline-copy-text-demo

```tsx
import { InlineCopyText } from "@workspace/ui/components/inline-copy-text";
import type { ExampleProps } from "../types";
export default function Example({ locale }: ExampleProps) {
  const zh = locale === "zh-CN";
  return (
    <p className="text-sm">
      {zh ? "在终端运行 " : "Run "}
      <InlineCopyText
        labels={{
          copy: zh ? "复制命令" : "Copy command",
          copied: zh ? "已复制" : "Copied",
          failed: zh ? "无法复制，请手动复制" : "Copy failed. Copy manually.",
        }}
      >
        bun run dev
      </InlineCopyText>
      {zh
        ? " 启动开发服务"
        : " in your terminal to start the development server."}
    </p>
  );
}
```

## Installation

```bash
bunx --bun shadcn@latest add @sui/inline-copy-text
```

Install with the shadcn CLI or use the shared `@workspace/ui` package. Follow the [installation guide](/docs/installation) to configure the registry, load styles, and choose import aliases.

```tsx
import { InlineCopyText } from "@workspace/ui/components/inline-copy-text";
```

## Usage

```tsx
<p>Run <InlineCopyText>bun run dev</InlineCopyText> to start.</p>
```

This is a compact, borderless inline code button with keyboard support. It does not submit a surrounding form. Pressing it does not scale or move the text; copy, success, and failure icons share a fixed position so feedback does not change its width. The check mark appears after the asynchronous write succeeds; failure is announced and sent to `onCopyError`.

## Custom display content

Set `value` whenever `children` is a React element rather than a string. The displayed content and copied plain text can differ. `variant="muted"` blends the control into surrounding prose.

### Example: inline-copy-text-custom-value

```tsx
import { InlineCopyText } from "@workspace/ui/components/inline-copy-text";
import type { ExampleProps } from "../types";
export default function Example({ locale }: ExampleProps) {
  const zh = locale === "zh-CN";
  return (
    <div className="grid w-full max-w-xl gap-3 text-sm">
      <div className="group flex min-w-0 items-center justify-between gap-4 rounded-xl border border-border bg-card p-4 text-card-foreground">
        <span className="min-w-0 truncate">
          {zh ? "工作区路径" : "Workspace path"}
        </span>
        <InlineCopyText
          value="/workspace/projects/sui/packages/ui/src/components"
          variant="muted"
          className="max-w-[60%]"
          labels={{
            copy: zh ? "复制完整路径" : "Copy full path",
            copied: zh ? "完整路径已复制" : "Full path copied",
            failed: zh ? "无法复制，请手动复制" : "Copy failed. Copy manually.",
          }}
        >
          <span>packages/ui/…</span>
        </InlineCopyText>
      </div>
      <p className="text-muted-foreground text-sm">
        {zh
          ? "悬停整行或用键盘聚焦即可显示图标；value 指定完整复制值"
          : "Hover the row or focus the control to reveal its icon. The value prop supplies the full path."}
      </p>
    </div>
  );
}
```

## Resource row

Add an unnamed `group` to the enclosing row to reveal the copy icon when the row is hovered or receives focus within. The icon always reserves its space and changes only visibility; it remains visible on touch devices. A successful checkmark remains until the feedback timer resets.

```tsx
<div className="group flex items-center justify-between gap-4 rounded-xl border border-border bg-card p-4 text-card-foreground">
  <span className="min-w-0 truncate text-sm">Production database</span>
  <InlineCopyText labels={{ copy: "Copy database ID", copied: "Database ID copied" }}>
    database_72c31
  </InlineCopyText>
</div>;
```

## Size and disabled state

Use `size="sm"` for compact text, `truncate={false}` to show the complete visible content, or `disabled` to prevent copying.

### Example: inline-copy-text-disabled

```tsx
import { InlineCopyText } from "@workspace/ui/components/inline-copy-text";
import type { ExampleProps } from "../types";
export default function Example({ locale }: ExampleProps) {
  const zh = locale === "zh-CN";
  return (
    <div className="grid w-full max-w-xs gap-4">
      <InlineCopyText
        size="sm"
        labels={{ copy: zh ? "复制路径" : "Copy path" }}
      >
        packages/ui/src/components/inline-copy-text.tsx
      </InlineCopyText>
      <InlineCopyText disabled>
        {zh ? "暂不可复制" : "Copying unavailable"}
      </InlineCopyText>
    </div>
  );
}
```

## Feedback

```tsx
<InlineCopyText
  value="workspace_72c31"
  labels={{ copy: "Copy workspace ID", copied: "Copied", failed: "Copy failed" }}
  onCopy={(value) => console.log(value)}
  onCopyError={(error) => console.error(error)}
>
  Workspace ID
</InlineCopyText>
```

Clipboard access is requested only on activation. If Clipboard API access is unavailable, select and copy the text manually. Pending writes cannot overlap; stale writes cannot overwrite feedback for a changed value or an unmounted control.

## API

| Prop | Type | Default |
| --- | --- | --- |
| `children` | `ReactNode` | Required |
| `value` | `string` | String children |
| `variant` | `"default" \| "muted"` | `"default"` |
| `size` | `"sm" \| "default"` | `"default"` |
| `truncate` | `boolean` | `true` |
| `iconVisibility` | `"hover"` (default) or `"always"`; controls whether the idle copy icon stays visible. |
| `disabled` | `boolean` | `false` |
| `resetDelay` | `number`, milliseconds | `1500` |
| `onCopy` | `(value: string) => void` | — |
| `onCopyError` | `(error: Error) => void` | — |
| `labels` | `{ copy?, pending?, copied?, failed? }` | English labels |

Uses the Base UI Button primitive and supports `ref`, `render`, `onClick`, and `className`. Its inline styling does not inherit the regular Button press movement. Calling `event.preventDefault()` in `onClick` cancels copying. `data-copy-status` exposes `idle`, `pending`, `copied`, or `error`. See [Base UI Button](https://base-ui.com/react/components/button) for composition.

## Icon motion

The copy icon morphs into the success checkmark on the same SVG path, keeps a fixed size, and respects reduced motion. Pending and error states retain their feedback. Import the generic `MorphIcon` from `@workspace/ui/components/morph-icon`: it accepts an `IconNode` or path string, animates changes to `icon`, and defaults to `spring="snappy"` and `reducedMotion="user"`. Size, stroke width, and animation options can be overridden. The `CopyIcon` adapter at `@workspace/ui/components/copy-icon` accepts `status` or the `copied`, `pending`, and `error` flags.


---

# Input

A text input component for forms and user data entry with built-in styling and accessibility features.

Page: https://sui.draco.dev/docs/components/input

### Example: input-demo

```tsx
import {
  Field,
  FieldDescription,
  FieldLabel,
} from "@workspace/ui/components/field";
import { Input } from "@workspace/ui/components/input";
import { useId as usePreviewId } from "react";

export function InputDemo() {
  const previewId = usePreviewId();

  return (
    <Field>
      <FieldLabel htmlFor={`${previewId}-input-demo-api-key`}>
        API Key
      </FieldLabel>
      <Input
        id={`${previewId}-input-demo-api-key`}
        type="password"
        placeholder="sk-..."
      />
      <FieldDescription>
        Your API key is encrypted and stored securely.
      </FieldDescription>
    </Field>
  );
}

export default InputDemo;
```

## Installation

```bash
bunx --bun shadcn@latest add @sui/input
```

Install with the shadcn CLI or use the shared `@workspace/ui` package. Follow the [installation guide](/docs/installation) to configure the registry, load styles, and choose import aliases.

## Usage

```tsx
import { Input } from "@workspace/ui/components/input"
```

```tsx
<Input />
```

## Basic

### Example: input-basic

```tsx
import { Input } from "@workspace/ui/components/input";

export function InputBasic() {
  return <Input placeholder="Enter text" />;
}

export default InputBasic;
```

## Field

Use `Field`, `FieldLabel`, and `FieldDescription` to create an input with a
label and description.

### Example: input-field

```tsx
import {
  Field,
  FieldDescription,
  FieldLabel,
} from "@workspace/ui/components/field";
import { Input } from "@workspace/ui/components/input";
import { useId as usePreviewId } from "react";

export function InputField() {
  const previewId = usePreviewId();

  return (
    <Field>
      <FieldLabel htmlFor={`${previewId}-input-field-username`}>
        Username
      </FieldLabel>
      <Input
        id={`${previewId}-input-field-username`}
        type="text"
        placeholder="Enter your username"
      />
      <FieldDescription>
        Choose a unique username for your account.
      </FieldDescription>
    </Field>
  );
}

export default InputField;
```

## Field Group

Use `FieldGroup` to show multiple `Field` blocks and to build forms.

### Example: input-fieldgroup

```tsx
import { Button } from "@workspace/ui/components/button";
import {
  Field,
  FieldDescription,
  FieldGroup,
  FieldLabel,
} from "@workspace/ui/components/field";
import { Input } from "@workspace/ui/components/input";
import { useId as usePreviewId } from "react";

export function InputFieldgroup() {
  const previewId = usePreviewId();

  return (
    <FieldGroup>
      <Field>
        <FieldLabel htmlFor={`${previewId}-fieldgroup-name`}>Name</FieldLabel>
        <Input id={`${previewId}-fieldgroup-name`} placeholder="Jordan Lee" />
      </Field>
      <Field>
        <FieldLabel htmlFor={`${previewId}-fieldgroup-email`}>Email</FieldLabel>
        <Input
          id={`${previewId}-fieldgroup-email`}
          type="email"
          placeholder="name@example.com"
        />
        <FieldDescription>
          We&apos;ll send updates to this address.
        </FieldDescription>
      </Field>
      <Field orientation="horizontal">
        <Button type="reset" variant="outline">
          Reset
        </Button>
        <Button type="submit">Submit</Button>
      </Field>
    </FieldGroup>
  );
}

export default InputFieldgroup;
```

## Disabled

Use the `disabled` prop to disable the input. To style the disabled state, add the `data-disabled` attribute to the `Field` component.

### Example: input-disabled

```tsx
import {
  Field,
  FieldDescription,
  FieldLabel,
} from "@workspace/ui/components/field";
import { Input } from "@workspace/ui/components/input";
import { useId as usePreviewId } from "react";

export function InputDisabled() {
  const previewId = usePreviewId();

  return (
    <Field data-disabled>
      <FieldLabel htmlFor={`${previewId}-input-demo-disabled`}>
        Email
      </FieldLabel>
      <Input
        id={`${previewId}-input-demo-disabled`}
        type="email"
        placeholder="Email"
        disabled
      />
      <FieldDescription>This field is currently disabled.</FieldDescription>
    </Field>
  );
}

export default InputDisabled;
```

## Invalid

Use the `aria-invalid` prop to mark the input as invalid. To style the invalid state, add the `data-invalid` attribute to the `Field` component.

### Example: input-invalid

```tsx
import {
  Field,
  FieldDescription,
  FieldLabel,
} from "@workspace/ui/components/field";
import { Input } from "@workspace/ui/components/input";
import { useId as usePreviewId } from "react";

export function InputInvalid() {
  const previewId = usePreviewId();

  return (
    <Field data-invalid>
      <FieldLabel htmlFor={`${previewId}-input-invalid`}>
        Invalid Input
      </FieldLabel>
      <Input
        id={`${previewId}-input-invalid`}
        placeholder="Error"
        aria-invalid
      />
      <FieldDescription>
        This field contains validation errors.
      </FieldDescription>
    </Field>
  );
}

export default InputInvalid;
```

## File

Use the `type="file"` prop to create a file input.

### Example: input-file

```tsx
import {
  Field,
  FieldDescription,
  FieldLabel,
} from "@workspace/ui/components/field";
import { Input } from "@workspace/ui/components/input";
import { useId as usePreviewId } from "react";

export function InputFile() {
  const previewId = usePreviewId();

  return (
    <Field>
      <FieldLabel htmlFor={`${previewId}-picture`}>Picture</FieldLabel>
      <Input id={`${previewId}-picture`} type="file" />
      <FieldDescription>Select a picture to upload.</FieldDescription>
    </Field>
  );
}

export default InputFile;
```

## Inline

Use `Field` with `orientation="horizontal"` to create an inline input.
Pair with `Button` to create a search input with a button.

### Example: input-inline

```tsx
import { Button } from "@workspace/ui/components/button";
import { Field } from "@workspace/ui/components/field";
import { Input } from "@workspace/ui/components/input";

export function InputInline() {
  return (
    <Field orientation="horizontal">
      <Input type="search" placeholder="Search..." />
      <Button>Search</Button>
    </Field>
  );
}

export default InputInline;
```

## Grid

Use a grid layout to place multiple inputs side by side.

### Example: input-grid

```tsx
import { Field, FieldGroup, FieldLabel } from "@workspace/ui/components/field";
import { Input } from "@workspace/ui/components/input";
import { useId as usePreviewId } from "react";

export function InputGrid() {
  const previewId = usePreviewId();

  return (
    <FieldGroup className="grid max-w-sm grid-cols-2">
      <Field>
        <FieldLabel htmlFor={`${previewId}-first-name`}>First Name</FieldLabel>
        <Input id={`${previewId}-first-name`} placeholder="Jordan" />
      </Field>
      <Field>
        <FieldLabel htmlFor={`${previewId}-last-name`}>Last Name</FieldLabel>
        <Input id={`${previewId}-last-name`} placeholder="Lee" />
      </Field>
    </FieldGroup>
  );
}

export default InputGrid;
```

## Required

Use the `required` attribute to indicate required inputs.

### Example: input-required

```tsx
import {
  Field,
  FieldDescription,
  FieldLabel,
} from "@workspace/ui/components/field";
import { Input } from "@workspace/ui/components/input";
import { useId as usePreviewId } from "react";

export function InputRequired() {
  const previewId = usePreviewId();

  return (
    <Field>
      <FieldLabel htmlFor={`${previewId}-input-required`}>
        Required Field <span className="text-destructive">*</span>
      </FieldLabel>
      <Input
        id={`${previewId}-input-required`}
        placeholder="This field is required"
        required
      />
      <FieldDescription>This field must be filled out.</FieldDescription>
    </Field>
  );
}

export default InputRequired;
```

## Badge

Use `Badge` in the label to highlight a recommended field.

### Example: input-badge

```tsx
import { Badge } from "@workspace/ui/components/badge";
import { Field, FieldLabel } from "@workspace/ui/components/field";
import { Input } from "@workspace/ui/components/input";
import { useId as usePreviewId } from "react";

export function InputBadge() {
  const previewId = usePreviewId();

  return (
    <Field>
      <FieldLabel htmlFor={`${previewId}-input-badge`}>
        Webhook URL{" "}
        <Badge variant="secondary" className="ml-auto">
          Beta
        </Badge>
      </FieldLabel>
      <Input
        id={`${previewId}-input-badge`}
        type="url"
        placeholder="https://api.example.com/webhook"
      />
    </Field>
  );
}

export default InputBadge;
```

## Input Group

To add icons, text, or buttons inside an input, use the `InputGroup` component. See the [Input Group](/docs/components/input-group) component for more examples.

### Example: input-input-group

```tsx
import { Field, FieldLabel } from "@workspace/ui/components/field";
import {
  InputGroup,
  InputGroupAddon,
  InputGroupInput,
  InputGroupText,
} from "@workspace/ui/components/input-group";
import { InfoIcon } from "lucide-react";
import { useId as usePreviewId } from "react";

export function InputInputGroup() {
  const previewId = usePreviewId();

  return (
    <Field>
      <FieldLabel htmlFor={`${previewId}-input-group-url`}>
        Website URL
      </FieldLabel>
      <InputGroup>
        <InputGroupInput
          id={`${previewId}-input-group-url`}
          placeholder="example.com"
        />
        <InputGroupAddon>
          <InputGroupText>https://</InputGroupText>
        </InputGroupAddon>
        <InputGroupAddon align="inline-end">
          <InfoIcon />
        </InputGroupAddon>
      </InputGroup>
    </Field>
  );
}

export default InputInputGroup;
```

## Button Group

To add buttons to an input, use the `ButtonGroup` component. See the [Button Group](/docs/components/button-group) component for more examples.

### Example: input-button-group

```tsx
import { Button } from "@workspace/ui/components/button";
import { ButtonGroup } from "@workspace/ui/components/button-group";
import { Field, FieldLabel } from "@workspace/ui/components/field";
import { Input } from "@workspace/ui/components/input";
import { useId as usePreviewId } from "react";

export function InputButtonGroup() {
  const previewId = usePreviewId();

  return (
    <Field>
      <FieldLabel htmlFor={`${previewId}-input-button-group`}>
        Search
      </FieldLabel>
      <ButtonGroup>
        <Input
          id={`${previewId}-input-button-group`}
          placeholder="Type to search..."
        />
        <Button variant="outline">Search</Button>
      </ButtonGroup>
    </Field>
  );
}

export default InputButtonGroup;
```

## Form

A full form example with multiple inputs, a select, and a button.

### Example: input-form

```tsx
import { Button } from "@workspace/ui/components/button";
import {
  Field,
  FieldDescription,
  FieldGroup,
  FieldLabel,
} from "@workspace/ui/components/field";
import { Input } from "@workspace/ui/components/input";
import {
  Select,
  SelectContent,
  SelectGroup,
  SelectItem,
  SelectTrigger,
  SelectValue,
} from "@workspace/ui/components/select";
import { useId as usePreviewId } from "react";

export function InputForm() {
  const previewId = usePreviewId();

  const countries = [
    { label: "United States", value: "us" },
    { label: "United Kingdom", value: "uk" },
    { label: "Canada", value: "ca" },
  ];
  return (
    <form className="w-full max-w-sm">
      <FieldGroup>
        <Field>
          <FieldLabel htmlFor={`${previewId}-form-name`}>Name</FieldLabel>
          <Input
            id={`${previewId}-form-name`}
            type="text"
            placeholder="Evil Rabbit"
            required
          />
        </Field>
        <Field>
          <FieldLabel htmlFor={`${previewId}-form-email`}>Email</FieldLabel>
          <Input
            id={`${previewId}-form-email`}
            type="email"
            placeholder="john@example.com"
          />
          <FieldDescription>
            We&apos;ll never share your email with anyone.
          </FieldDescription>
        </Field>
        <div className="grid grid-cols-2 gap-4">
          <Field>
            <FieldLabel htmlFor={`${previewId}-form-phone`}>Phone</FieldLabel>
            <Input
              id={`${previewId}-form-phone`}
              type="tel"
              placeholder="+1 (555) 123-4567"
            />
          </Field>
          <Field>
            <FieldLabel htmlFor={`${previewId}-form-country`}>
              Country
            </FieldLabel>
            <Select items={countries} defaultValue="us">
              <SelectTrigger id={`${previewId}-form-country`}>
                <SelectValue />
              </SelectTrigger>
              <SelectContent>
                <SelectGroup>
                  {countries.map((country) => (
                    <SelectItem key={country.value} value={country.value}>
                      {country.label}
                    </SelectItem>
                  ))}
                </SelectGroup>
              </SelectContent>
            </Select>
          </Field>
        </div>
        <Field>
          <FieldLabel htmlFor={`${previewId}-form-address`}>Address</FieldLabel>
          <Input
            id={`${previewId}-form-address`}
            type="text"
            placeholder="123 Main St"
          />
        </Field>
        <Field orientation="horizontal">
          <Button type="button" variant="outline">
            Cancel
          </Button>
          <Button type="submit">Submit</Button>
        </Field>
      </FieldGroup>
    </form>
  );
}

export default InputForm;
```

## RTL

To enable RTL support in shadcn/ui, see the [RTL configuration guide](https://ui.shadcn.com/docs/rtl).

### Example: input-rtl

```tsx
"use client";

import {
  Field,
  FieldDescription,
  FieldLabel,
} from "@workspace/ui/components/field";
import { Input } from "@workspace/ui/components/input";
import { useId as usePreviewId } from "react";
import { type Translations, useTranslation } from "./support";

const translations: Translations = {
  en: {
    dir: "ltr",
    values: {
      apiKey: "API Key",
      placeholder: "sk-...",
      description: "Your API key is encrypted and stored securely.",
    },
  },
  ar: {
    dir: "rtl",
    values: {
      apiKey: "مفتاح API",
      placeholder: "sk-...",
      description: "مفتاح API الخاص بك مشفر ومخزن بأمان.",
    },
  },
  he: {
    dir: "rtl",
    values: {
      apiKey: "מפתח API",
      placeholder: "sk-...",
      description: "מפתח ה-API שלך מוצפן ונשמר בצורה מאובטחת.",
    },
  },
};

export function InputRtl() {
  const previewId = usePreviewId();

  const { dir, t } = useTranslation(translations, "ar");

  return (
    <Field dir={dir}>
      <FieldLabel htmlFor={`${previewId}-input-rtl-api-key`}>
        {t.apiKey}
      </FieldLabel>
      <Input
        id={`${previewId}-input-rtl-api-key`}
        type="password"
        placeholder={t.placeholder}
        dir={dir}
      />
      <FieldDescription>{t.description}</FieldDescription>
    </Field>
  );
}

export default InputRtl;
```


---

# Input Group

Add addons, buttons, and helper content to inputs.

Page: https://sui.draco.dev/docs/components/input-group

### Example: input-group-demo

```tsx
import {
  InputGroup,
  InputGroupAddon,
  InputGroupInput,
} from "@workspace/ui/components/input-group";
import { Search } from "lucide-react";

export function InputGroupDemo() {
  return (
    <InputGroup className="max-w-xs">
      <InputGroupInput placeholder="Search..." />
      <InputGroupAddon>
        <Search />
      </InputGroupAddon>
      <InputGroupAddon align="inline-end">12 results</InputGroupAddon>
    </InputGroup>
  );
}

export default InputGroupDemo;
```

## Installation

```bash
bunx --bun shadcn@latest add @sui/input-group
```

Install with the shadcn CLI or use the shared `@workspace/ui` package. Follow the [installation guide](/docs/installation) to configure the registry, load styles, and choose import aliases.

## Usage

```tsx showLineNumbers
import {
  InputGroup,
  InputGroupAddon,
  InputGroupButton,
  InputGroupInput,
  InputGroupText,
  InputGroupTextarea,
} from "@workspace/ui/components/input-group"
```

```tsx showLineNumbers
<InputGroup>
  <InputGroupInput placeholder="Search..." />
  <InputGroupAddon>
    <SearchIcon />
  </InputGroupAddon>
</InputGroup>
```

## Composition

Use the following composition to build an `InputGroup`:

```text
InputGroup
├── InputGroupInput or InputGroupTextarea
├── InputGroupAddon
├── InputGroupButton
└── InputGroupText
```

## Align

Use the `align` prop on `InputGroupAddon` to position the addon relative to the input.

  For proper focus management, `InputGroupAddon` should always be placed after
  `InputGroupInput` or `InputGroupTextarea` in the DOM. Use the `align` prop to
  visually position the addon.

### inline-start

Use `align="inline-start"` to position the addon at the start of the input. This is the default.

### Example: input-group-inline-start

```tsx
import {
  Field,
  FieldDescription,
  FieldLabel,
} from "@workspace/ui/components/field";
import {
  InputGroup,
  InputGroupAddon,
  InputGroupInput,
} from "@workspace/ui/components/input-group";
import { SearchIcon } from "lucide-react";
import { useId as usePreviewId } from "react";

export function InputGroupInlineStart() {
  const previewId = usePreviewId();

  return (
    <Field className="max-w-sm">
      <FieldLabel htmlFor={`${previewId}-inline-start-input`}>Input</FieldLabel>
      <InputGroup>
        <InputGroupInput
          id={`${previewId}-inline-start-input`}
          placeholder="Search..."
        />
        <InputGroupAddon align="inline-start">
          <SearchIcon className="text-muted-foreground" />
        </InputGroupAddon>
      </InputGroup>
      <FieldDescription>Icon positioned at the start.</FieldDescription>
    </Field>
  );
}

export default InputGroupInlineStart;
```

### inline-end

Use `align="inline-end"` to position the addon at the end of the input.

### Example: input-group-inline-end

```tsx
import {
  Field,
  FieldDescription,
  FieldLabel,
} from "@workspace/ui/components/field";
import {
  InputGroup,
  InputGroupAddon,
  InputGroupInput,
} from "@workspace/ui/components/input-group";
import { EyeOffIcon } from "lucide-react";
import { useId as usePreviewId } from "react";

export function InputGroupInlineEnd() {
  const previewId = usePreviewId();

  return (
    <Field className="max-w-sm">
      <FieldLabel htmlFor={`${previewId}-inline-end-input`}>Input</FieldLabel>
      <InputGroup>
        <InputGroupInput
          id={`${previewId}-inline-end-input`}
          type="password"
          placeholder="Enter password"
        />
        <InputGroupAddon align="inline-end">
          <EyeOffIcon />
        </InputGroupAddon>
      </InputGroup>
      <FieldDescription>Icon positioned at the end.</FieldDescription>
    </Field>
  );
}

export default InputGroupInlineEnd;
```

### block-start

Use `align="block-start"` to position the addon above the input.

### Example: input-group-block-start

```tsx
import {
  Field,
  FieldDescription,
  FieldGroup,
  FieldLabel,
} from "@workspace/ui/components/field";
import {
  InputGroup,
  InputGroupAddon,
  InputGroupButton,
  InputGroupInput,
  InputGroupText,
  InputGroupTextarea,
} from "@workspace/ui/components/input-group";
import { CopyIcon, FileCodeIcon } from "lucide-react";
import { useId as usePreviewId } from "react";

export function InputGroupBlockStart() {
  const previewId = usePreviewId();

  return (
    <FieldGroup className="max-w-sm">
      <Field>
        <FieldLabel htmlFor={`${previewId}-block-start-input`}>
          Input
        </FieldLabel>
        <InputGroup className="h-auto">
          <InputGroupInput
            id={`${previewId}-block-start-input`}
            placeholder="Enter your name"
          />
          <InputGroupAddon align="block-start">
            <InputGroupText>Full Name</InputGroupText>
          </InputGroupAddon>
        </InputGroup>
        <FieldDescription>Header positioned above the input.</FieldDescription>
      </Field>
      <Field>
        <FieldLabel htmlFor={`${previewId}-block-start-textarea`}>
          Textarea
        </FieldLabel>
        <InputGroup>
          <InputGroupTextarea
            id={`${previewId}-block-start-textarea`}
            placeholder="console.log('Hello, world!');"
            className="font-mono text-sm"
          />
          <InputGroupAddon align="block-start">
            <FileCodeIcon className="text-muted-foreground" />
            <InputGroupText className="font-mono">script.js</InputGroupText>
            <InputGroupButton size="icon-xs" className="ml-auto">
              <CopyIcon />
              <span className="sr-only">Copy</span>
            </InputGroupButton>
          </InputGroupAddon>
        </InputGroup>
        <FieldDescription>
          Header positioned above the textarea.
        </FieldDescription>
      </Field>
    </FieldGroup>
  );
}

export default InputGroupBlockStart;
```

### block-end

Use `align="block-end"` to position the addon below the input.

### Example: input-group-block-end

```tsx
import {
  Field,
  FieldDescription,
  FieldGroup,
  FieldLabel,
} from "@workspace/ui/components/field";
import {
  InputGroup,
  InputGroupAddon,
  InputGroupButton,
  InputGroupInput,
  InputGroupText,
  InputGroupTextarea,
} from "@workspace/ui/components/input-group";
import { useId as usePreviewId } from "react";

export function InputGroupBlockEnd() {
  const previewId = usePreviewId();

  return (
    <FieldGroup className="max-w-sm">
      <Field>
        <FieldLabel htmlFor={`${previewId}-block-end-input`}>Input</FieldLabel>
        <InputGroup className="h-auto">
          <InputGroupInput
            id={`${previewId}-block-end-input`}
            placeholder="Enter amount"
          />
          <InputGroupAddon align="block-end">
            <InputGroupText>USD</InputGroupText>
          </InputGroupAddon>
        </InputGroup>
        <FieldDescription>Footer positioned below the input.</FieldDescription>
      </Field>
      <Field>
        <FieldLabel htmlFor={`${previewId}-block-end-textarea`}>
          Textarea
        </FieldLabel>
        <InputGroup>
          <InputGroupTextarea
            id={`${previewId}-block-end-textarea`}
            placeholder="Write a comment..."
          />
          <InputGroupAddon align="block-end">
            <InputGroupText>0/280</InputGroupText>
            <InputGroupButton variant="default" size="sm" className="ml-auto">
              Post
            </InputGroupButton>
          </InputGroupAddon>
        </InputGroup>
        <FieldDescription>
          Footer positioned below the textarea.
        </FieldDescription>
      </Field>
    </FieldGroup>
  );
}

export default InputGroupBlockEnd;
```

## Icon

### Example: input-group-icon

```tsx
import {
  InputGroup,
  InputGroupAddon,
  InputGroupInput,
} from "@workspace/ui/components/input-group";
import {
  CheckIcon,
  CreditCardIcon,
  InfoIcon,
  MailIcon,
  SearchIcon,
  StarIcon,
} from "lucide-react";

export default function InputGroupIcon() {
  return (
    <div className="grid w-full max-w-sm gap-6">
      <InputGroup>
        <InputGroupInput placeholder="Search..." />
        <InputGroupAddon>
          <SearchIcon />
        </InputGroupAddon>
      </InputGroup>
      <InputGroup>
        <InputGroupInput type="email" placeholder="Enter your email" />
        <InputGroupAddon>
          <MailIcon />
        </InputGroupAddon>
      </InputGroup>
      <InputGroup>
        <InputGroupInput placeholder="Card number" />
        <InputGroupAddon>
          <CreditCardIcon />
        </InputGroupAddon>
        <InputGroupAddon align="inline-end">
          <CheckIcon />
        </InputGroupAddon>
      </InputGroup>
      <InputGroup>
        <InputGroupInput placeholder="Card number" />
        <InputGroupAddon align="inline-end">
          <StarIcon />
          <InfoIcon />
        </InputGroupAddon>
      </InputGroup>
    </div>
  );
}
```

## Text

### Example: input-group-text

```tsx
import {
  InputGroup,
  InputGroupAddon,
  InputGroupInput,
  InputGroupText,
  InputGroupTextarea,
} from "@workspace/ui/components/input-group";

export default function InputGroupTextExample() {
  return (
    <div className="grid w-full max-w-sm gap-6">
      <InputGroup>
        <InputGroupAddon>
          <InputGroupText>$</InputGroupText>
        </InputGroupAddon>
        <InputGroupInput placeholder="0.00" />
        <InputGroupAddon align="inline-end">
          <InputGroupText>USD</InputGroupText>
        </InputGroupAddon>
      </InputGroup>
      <InputGroup>
        <InputGroupAddon>
          <InputGroupText>https://</InputGroupText>
        </InputGroupAddon>
        <InputGroupInput placeholder="example.com" className="pl-0.5!" />
        <InputGroupAddon align="inline-end">
          <InputGroupText>.com</InputGroupText>
        </InputGroupAddon>
      </InputGroup>
      <InputGroup>
        <InputGroupInput placeholder="Enter your username" />
        <InputGroupAddon align="inline-end">
          <InputGroupText>@company.com</InputGroupText>
        </InputGroupAddon>
      </InputGroup>
      <InputGroup>
        <InputGroupTextarea placeholder="Enter your message" />
        <InputGroupAddon align="block-end">
          <InputGroupText className="text-muted-foreground text-xs">
            120 characters left
          </InputGroupText>
        </InputGroupAddon>
      </InputGroup>
    </div>
  );
}
```

## Button

### Example: input-group-button

```tsx
"use client";
import { CopyIcon } from "@workspace/ui/components/copy-icon";

import {
  InputGroup,
  InputGroupAddon,
  InputGroupButton,
  InputGroupInput,
} from "@workspace/ui/components/input-group";
import {
  Popover,
  PopoverContent,
  PopoverTrigger,
} from "@workspace/ui/components/popover";
import { useClipboard } from "@workspace/ui/hooks/use-clipboard";
import { InfoIcon, StarIcon } from "lucide-react";
import { useId, useState } from "react";

const profileUrl = "https://x.com/shadcn";

export default function InputGroupButtonExample() {
  const addressId = useId();
  const { copy, status } = useClipboard(profileUrl);
  const [favorite, setFavorite] = useState(false);
  const [query, setQuery] = useState("");
  const [message, setMessage] = useState("");

  return (
    <div className="grid w-full max-w-sm gap-6">
      <div className="flex flex-col gap-2">
        <InputGroup>
          <InputGroupInput
            value={profileUrl}
            aria-label="Profile URL"
            readOnly
          />
          <InputGroupAddon align="inline-end">
            <InputGroupButton
              aria-label={status === "copied" ? "Copied" : "Copy"}
              size="icon-xs"
              disabled={status === "pending"}
              onClick={() => copy()}
            >
              <CopyIcon status={status} />
            </InputGroupButton>
          </InputGroupAddon>
        </InputGroup>
        {status === "error" && (
          <p role="status" className="text-destructive text-sm">
            Copy failed. Select the link and copy it manually.
          </p>
        )}
      </div>
      <InputGroup className="[--radius:9999px]">
        <InputGroupInput
          id={addressId}
          aria-label="Website address"
          defaultValue="example.com"
        />
        <InputGroupAddon>
          <Popover>
            <PopoverTrigger
              render={
                <InputGroupButton
                  variant="secondary"
                  size="icon-xs"
                  aria-label="URL details"
                />
              }
            >
              <InfoIcon />
            </PopoverTrigger>
            <PopoverContent
              align="start"
              className="flex flex-col gap-1 rounded-xl text-sm"
            >
              <p className="font-medium">URL details</p>
              <p>
                This example uses HTTPS. Edit the address to try another URL.
              </p>
            </PopoverContent>
          </Popover>
        </InputGroupAddon>
        <InputGroupAddon className="ps-1.5 text-muted-foreground">
          https://
        </InputGroupAddon>
        <InputGroupAddon align="inline-end">
          <InputGroupButton
            aria-label="Toggle favorite"
            aria-pressed={favorite}
            onClick={() => setFavorite((value) => !value)}
            size="icon-xs"
          >
            <StarIcon
              data-favorite={favorite}
              className="data-[favorite=true]:fill-primary data-[favorite=true]:stroke-primary"
            />
          </InputGroupButton>
        </InputGroupAddon>
      </InputGroup>
      <form
        onSubmit={(event) => {
          event.preventDefault();
          setMessage(
            query.trim()
              ? `Search preview: ${query.trim()}`
              : "Enter a search term first.",
          );
        }}
        className="flex flex-col gap-2"
      >
        <InputGroup>
          <InputGroupInput
            aria-label="Search term"
            placeholder="Type to search..."
            value={query}
            onChange={(event) => setQuery(event.target.value)}
          />
          <InputGroupAddon align="inline-end">
            <InputGroupButton type="submit" variant="secondary">
              Search
            </InputGroupButton>
          </InputGroupAddon>
        </InputGroup>
        <p role="status" className="text-muted-foreground text-sm">
          {message}
        </p>
      </form>
    </div>
  );
}
```

## Kbd

### Example: input-group-kbd

```tsx
import {
  InputGroup,
  InputGroupAddon,
  InputGroupInput,
} from "@workspace/ui/components/input-group";
import { Kbd } from "@workspace/ui/components/kbd";
import { SearchIcon } from "lucide-react";

export function InputGroupKbd() {
  return (
    <InputGroup className="max-w-sm">
      <InputGroupInput placeholder="Search..." />
      <InputGroupAddon>
        <SearchIcon className="text-muted-foreground" />
      </InputGroupAddon>
      <InputGroupAddon align="inline-end">
        <Kbd>⌘K</Kbd>
      </InputGroupAddon>
    </InputGroup>
  );
}

export default InputGroupKbd;
```

## Dropdown

### Example: input-group-dropdown

```tsx
"use client";

import {
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuGroup,
  DropdownMenuItem,
  DropdownMenuTrigger,
} from "@workspace/ui/components/dropdown-menu";
import {
  InputGroup,
  InputGroupAddon,
  InputGroupButton,
  InputGroupInput,
} from "@workspace/ui/components/input-group";
import { ChevronDownIcon, MoreHorizontal } from "lucide-react";

export function InputGroupDropdown() {
  return (
    <div className="grid w-full max-w-sm gap-4">
      <InputGroup>
        <InputGroupInput placeholder="Enter file name" />
        <InputGroupAddon align="inline-end">
          <DropdownMenu>
            <DropdownMenuTrigger
              render={
                <InputGroupButton
                  variant="ghost"
                  aria-label="More"
                  size="icon-xs"
                />
              }
            >
              <MoreHorizontal />
            </DropdownMenuTrigger>
            <DropdownMenuContent align="end" sideOffset={8} alignOffset={-4}>
              <DropdownMenuGroup>
                <DropdownMenuItem>Settings</DropdownMenuItem>
                <DropdownMenuItem>Copy path</DropdownMenuItem>
                <DropdownMenuItem>Open location</DropdownMenuItem>
              </DropdownMenuGroup>
            </DropdownMenuContent>
          </DropdownMenu>
        </InputGroupAddon>
      </InputGroup>
      <InputGroup>
        <InputGroupInput placeholder="Enter search query" />
        <InputGroupAddon align="inline-end">
          <DropdownMenu>
            <DropdownMenuTrigger
              render={
                <InputGroupButton variant="ghost" className="pr-1.5! text-xs" />
              }
            >
              Search In... <ChevronDownIcon className="size-3" />
            </DropdownMenuTrigger>
            <DropdownMenuContent align="end" sideOffset={8} alignOffset={-4}>
              <DropdownMenuGroup>
                <DropdownMenuItem>Documentation</DropdownMenuItem>
                <DropdownMenuItem>Blog Posts</DropdownMenuItem>
                <DropdownMenuItem>Changelog</DropdownMenuItem>
              </DropdownMenuGroup>
            </DropdownMenuContent>
          </DropdownMenu>
        </InputGroupAddon>
      </InputGroup>
    </div>
  );
}

export default InputGroupDropdown;
```

## Loader

### Example: input-group-loading

```tsx
import {
  InputGroup,
  InputGroupAddon,
  InputGroupInput,
  InputGroupText,
} from "@workspace/ui/components/input-group";
import { Loader } from "@workspace/ui/components/loader";

export default function InputGroupLoading() {
  return (
    <div className="grid w-full max-w-sm gap-4">
      <InputGroup>
        <InputGroupInput placeholder="Searching..." />
        <InputGroupAddon align="inline-end">
          <Loader size="sm" />
        </InputGroupAddon>
      </InputGroup>
      <InputGroup>
        <InputGroupInput placeholder="Processing..." />
        <InputGroupAddon>
          <Loader size="sm" />
        </InputGroupAddon>
      </InputGroup>
      <InputGroup>
        <InputGroupInput placeholder="Saving changes..." />
        <InputGroupAddon align="inline-end">
          <InputGroupText>Saving...</InputGroupText>
          <Loader size="sm" />
        </InputGroupAddon>
      </InputGroup>
      <InputGroup>
        <InputGroupInput placeholder="Refreshing data..." />
        <InputGroupAddon>
          <Loader size="sm" variant="dash-ring" />
        </InputGroupAddon>
        <InputGroupAddon align="inline-end">
          <InputGroupText className="text-muted-foreground">
            Please wait...
          </InputGroupText>
        </InputGroupAddon>
      </InputGroup>
    </div>
  );
}
```

## Textarea

### Example: input-group-textarea

```tsx
"use client";
import { CopyIcon } from "@workspace/ui/components/copy-icon";

import {
  InputGroup,
  InputGroupAddon,
  InputGroupButton,
  InputGroupText,
  InputGroupTextarea,
} from "@workspace/ui/components/input-group";
import { toast } from "@workspace/ui/components/toast";
import { useClipboard } from "@workspace/ui/hooks/use-clipboard";
import { CornerDownLeftIcon, FileCodeIcon, RefreshCwIcon } from "lucide-react";
import { useId, useState } from "react";

const initialCode = "console.log('Hello, world!');";

export default function InputGroupTextareaExample() {
  const sourceId = useId();
  const [code, setCode] = useState(initialCode);
  const [preview, setPreview] = useState("");
  const { copy, status } = useClipboard(code, {
    onCopyError: () =>
      toast.add({
        title: "Copy failed",
        description: "Select the code and copy it manually.",
      }),
  });

  return (
    <div className="grid w-full max-w-md gap-4">
      <InputGroup>
        <InputGroupTextarea
          id={sourceId}
          aria-label="Script source"
          value={code}
          onChange={(event) => setCode(event.target.value)}
          className="min-h-[200px]"
        />
        <InputGroupAddon align="block-start" className="border-b">
          <InputGroupText className="font-medium font-mono">
            <FileCodeIcon /> script.js
          </InputGroupText>
          <InputGroupButton
            className="ms-auto"
            size="icon-xs"
            aria-label="Reset code"
            onClick={() => {
              setCode(initialCode);
              setPreview("");
            }}
          >
            <RefreshCwIcon />
          </InputGroupButton>
          <InputGroupButton
            variant="ghost"
            size="icon-xs"
            aria-label={status === "copied" ? "Copied code" : "Copy code"}
            disabled={status === "pending"}
            onClick={() => copy()}
          >
            <CopyIcon status={status} />
          </InputGroupButton>
        </InputGroupAddon>
        <InputGroupAddon align="block-end" className="border-t">
          <InputGroupText>{code.split("\n").length} lines</InputGroupText>
          <InputGroupButton
            size="sm"
            className="ms-auto"
            variant="default"
            onClick={() => setPreview(code)}
            disabled={!code.trim()}
          >
            Preview <CornerDownLeftIcon data-icon="inline-end" />
          </InputGroupButton>
        </InputGroupAddon>
      </InputGroup>
      {preview && (
        <pre className="overflow-x-auto rounded-lg bg-muted p-3 text-sm">
          <code>{preview}</code>
        </pre>
      )}
    </div>
  );
}
```

## Custom Input

Add the `data-slot="input-group-control"` attribute to your custom input for automatic focus state handling.

Here's an example of a custom resizable textarea from a third-party library.

### Example: input-group-custom

```tsx
"use client";

import {
  InputGroup,
  InputGroupAddon,
  InputGroupButton,
} from "@workspace/ui/components/input-group";
import TextareaAutosize from "react-textarea-autosize";

export default function InputGroupCustom() {
  return (
    <div className="grid w-full max-w-sm gap-6">
      <InputGroup>
        <TextareaAutosize
          data-slot="input-group-control"
          className="field-sizing-content flex min-h-16 w-full resize-none rounded-md bg-transparent px-3 py-2.5 text-base outline-none transition-[color,box-shadow] md:text-sm"
          placeholder="Autoresize textarea..."
        />
        <InputGroupAddon align="block-end">
          <InputGroupButton className="ml-auto" size="sm" variant="default">
            Submit
          </InputGroupButton>
        </InputGroupAddon>
      </InputGroup>
    </div>
  );
}
```

## RTL

To enable RTL support in shadcn/ui, see the [RTL configuration guide](https://ui.shadcn.com/docs/rtl).

### Example: input-group-rtl

```tsx
"use client";

import {
  Field,
  FieldDescription,
  FieldGroup,
  FieldLabel,
} from "@workspace/ui/components/field";
import {
  InputGroup,
  InputGroupAddon,
  InputGroupButton,
  InputGroupInput,
  InputGroupText,
  InputGroupTextarea,
} from "@workspace/ui/components/input-group";
import { Loader } from "@workspace/ui/components/loader";
import { Search } from "lucide-react";
import { useId as usePreviewId } from "react";
import { type Translations, useTranslation } from "./support";

const translations: Translations = {
  en: {
    dir: "ltr",
    values: {
      placeholder: "Search...",
      results: "12 results",
      searching: "Searching...",
      saving: "Saving...",
      savingChanges: "Saving changes...",
      textareaLabel: "Textarea",
      textareaPlaceholder: "Write a comment...",
      characterCount: "0/280",
      post: "Post",
      textareaDescription: "Footer positioned below the textarea.",
    },
  },
  ar: {
    dir: "rtl",
    values: {
      placeholder: "بحث...",
      results: "١٢ نتيجة",
      searching: "جاري البحث...",
      saving: "جاري الحفظ...",
      savingChanges: "جاري حفظ التغييرات...",
      textareaLabel: "منطقة النص",
      textareaPlaceholder: "اكتب تعليقًا...",
      characterCount: "٠/٢٨٠",
      post: "نشر",
      textareaDescription: "تذييل موضع أسفل منطقة النص.",
    },
  },
  he: {
    dir: "rtl",
    values: {
      placeholder: "חפש...",
      results: "12 תוצאות",
      searching: "מחפש...",
      saving: "שומר...",
      savingChanges: "שומר שינויים...",
      textareaLabel: "אזור טקסט",
      textareaPlaceholder: "כתוב תגובה...",
      characterCount: "0/280",
      post: "פרסם",
      textareaDescription: "כותרת תחתונה ממוקמת מתחת לאזור הטקסט.",
    },
  },
};

export function InputGroupRtl() {
  const previewId = usePreviewId();

  const { t } = useTranslation(translations, "ar");

  return (
    <div className="grid w-full max-w-sm gap-6">
      <InputGroup className="max-w-xs">
        <InputGroupInput placeholder={t.placeholder} />
        <InputGroupAddon>
          <Search />
        </InputGroupAddon>
        <InputGroupAddon align="inline-end">{t.results}</InputGroupAddon>
      </InputGroup>
      <InputGroup>
        <InputGroupInput placeholder={t.searching} />
        <InputGroupAddon align="inline-end">
          <Loader size="sm" />
        </InputGroupAddon>
      </InputGroup>
      <InputGroup>
        <InputGroupInput placeholder={t.savingChanges} />
        <InputGroupAddon align="inline-end">
          <InputGroupText>{t.saving}</InputGroupText>
          <Loader size="sm" />
        </InputGroupAddon>
      </InputGroup>
      <FieldGroup className="max-w-sm">
        <Field>
          <FieldLabel htmlFor={`${previewId}-rtl-textarea`}>
            {t.textareaLabel}
          </FieldLabel>
          <InputGroup>
            <InputGroupTextarea
              id={`${previewId}-rtl-textarea`}
              placeholder={t.textareaPlaceholder}
            />
            <InputGroupAddon align="block-end">
              <InputGroupText>{t.characterCount}</InputGroupText>
              <InputGroupButton variant="default" size="sm" className="ms-auto">
                {t.post}
              </InputGroupButton>
            </InputGroupAddon>
          </InputGroup>
          <FieldDescription>{t.textareaDescription}</FieldDescription>
        </Field>
      </FieldGroup>
    </div>
  );
}

export default InputGroupRtl;
```

## API Reference

### InputGroup

The main component that wraps inputs and addons.

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` |         |

```tsx
<InputGroup>
  <InputGroupInput />
  <InputGroupAddon />
</InputGroup>
```

### InputGroupAddon

Displays icons, text, buttons, or other content alongside inputs.

**Focus Navigation**

  For proper focus navigation, the `InputGroupAddon` component should be placed
  after the input. Set the `align` prop to position the addon.

| Prop        | Type                                                             | Default          |
| ----------- | ---------------------------------------------------------------- | ---------------- |
| `align`     | `"inline-start" \| "inline-end" \| "block-start" \| "block-end"` | `"inline-start"` |
| `className` | `string`                                                         |                  |

```tsx
<InputGroupAddon align="inline-end">
  <SearchIcon />
</InputGroupAddon>
```

**For `<InputGroupInput />`, use the `inline-start` or `inline-end` alignment. For `<InputGroupTextarea />`, use the `block-start` or `block-end` alignment.**

The `InputGroupAddon` component can have multiple `InputGroupButton` components and icons.

```tsx
<InputGroupAddon>
  <InputGroupButton>Button</InputGroupButton>
  <InputGroupButton>Button</InputGroupButton>
</InputGroupAddon>
```

### InputGroupButton

Displays buttons within input groups.

| Prop        | Type                                                                          | Default   |
| ----------- | ----------------------------------------------------------------------------- | --------- |
| `size`      | `"xs" \| "icon-xs" \| "sm" \| "icon-sm"`                                      | `"xs"`    |
| `variant`   | `"default" \| "destructive" \| "outline" \| "secondary" \| "ghost" \| "link"` | `"ghost"` |
| `className` | `string`                                                                      |           |

```tsx
<InputGroupButton>Button</InputGroupButton>
<InputGroupButton size="icon-xs" aria-label="Copy">
  <CopyIcon />
</InputGroupButton>
```

### InputGroupInput

Replacement for `<Input />` when building input groups. This component has the input group styles pre-applied and uses the unified `data-slot="input-group-control"` for focus state handling.

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` |         |

All other props are passed through to the underlying `<Input />` component.

```tsx
<InputGroup>
  <InputGroupInput placeholder="Enter text..." />
  <InputGroupAddon>
    <SearchIcon />
  </InputGroupAddon>
</InputGroup>
```

### InputGroupTextarea

Replacement for `<Textarea />` when building input groups. This component has the textarea group styles pre-applied and uses the unified `data-slot="input-group-control"` for focus state handling.

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` |         |

All other props are passed through to the underlying `<Textarea />` component.

```tsx
<InputGroup>
  <InputGroupTextarea placeholder="Enter message..." />
  <InputGroupAddon align="block-end">
    <InputGroupButton>Send</InputGroupButton>
  </InputGroupAddon>
</InputGroup>
```


---

# Input OTP

Individual code inputs with character filtering and asynchronous verification feedback

Page: https://sui.draco.dev/docs/components/input-otp

### Example: input-otp-demo

```tsx
"use client";

import { Button } from "@workspace/ui/components/button";
import {
  InputOTP,
  InputOTPGroup,
  InputOTPSlot,
  type InputOTPStatus,
} from "@workspace/ui/components/input-otp";
import { Label } from "@workspace/ui/components/label";
import { useEffect, useId, useRef, useState } from "react";
import type { ExampleProps } from "../types";

export default function Example({
  locale,
  mask = false,
}: ExampleProps & { mask?: boolean }) {
  const chinese = locale === "zh-CN";
  const id = useId();
  const [value, setValue] = useState("");
  const [status, setStatus] = useState<InputOTPStatus>("idle");
  const [result, setResult] = useState("");
  const inputRef = useRef<HTMLInputElement>(null);
  const request = useRef(0);
  const timer = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
  useEffect(
    () => () => {
      request.current++;
      clearTimeout(timer.current);
    },
    [],
  );
  function verify(code: string) {
    const run = ++request.current;
    clearTimeout(timer.current);
    setStatus("loading");
    setResult(chinese ? "正在验证" : "Verifying code");
    const verification = new Promise<boolean>((resolve) => {
      timer.current = setTimeout(() => resolve(code === "123456"), 1100);
    });
    void verification.then((valid) => {
      if (request.current !== run) return;
      setStatus(valid ? "success" : "error");
      const messages = chinese
        ? {
            success: "验证成功",
            error: "验证失败，输入已保留，可修改或重新输入",
          }
        : {
            success: "Verified",
            error:
              "Verification failed. Your code is preserved for editing or retry.",
          };
      setResult(messages[valid ? "success" : "error"]);
    });
  }
  return (
    <div className="grid w-full max-w-sm justify-items-center gap-4">
      <p className="text-center text-muted-foreground text-sm">
        {chinese
          ? "输入 123456 查看成功效果，其他六位数字显示失败"
          : "Enter 123456 to succeed; any other six digits show the error feedback."}
      </p>
      <Label htmlFor={id} className="sr-only">
        {chinese ? "验证码" : "Verification code"}
      </Label>
      <InputOTP
        id={id}
        length={6}
        mask={mask}
        value={value}
        onValueChange={(value) => {
          setValue(value);
          setResult("");
        }}
        onValueComplete={verify}
        status={status}
        onStatusChange={setStatus}
      >
        <InputOTPGroup>
          {[0, 1, 2, 3, 4, 5].map((index) => (
            <InputOTPSlot
              key={index}
              ref={index === 0 ? inputRef : undefined}
              className="size-10 text-lg"
            />
          ))}
        </InputOTPGroup>
      </InputOTP>
      <p
        role="status"
        className="min-h-5 text-center text-muted-foreground text-sm"
      >
        {result}
      </p>
      <div className="flex gap-2">
        <Button
          type="button"
          variant="outline"
          size="sm"
          disabled={status === "loading" || status === "error"}
          onClick={() => {
            request.current++;
            clearTimeout(timer.current);
            setValue("");
            setStatus("idle");
            setResult("");
            inputRef.current?.focus();
          }}
        >
          {chinese ? "重新输入" : "Enter again"}
        </Button>
        <Button
          type="button"
          variant="secondary"
          size="sm"
          disabled={status !== "idle" || value.length !== 6}
          onClick={() => {
            inputRef.current?.focus();
            verify(value);
          }}
        >
          {chinese ? "重试验证" : "Retry verification"}
        </Button>
      </div>
    </div>
  );
}
```

Input OTP combines real character inputs with paste, autofill, keyboard navigation, and verification feedback. The first example accepts `123456` as a successful verification and keeps the check visible. Other six-digit codes show failure, then unfold back into editable inputs with the entered value preserved.

## Installation

```bash
bunx --bun shadcn@latest add @sui/input-otp
```

Install with the shadcn CLI or use the shared `@workspace/ui` package. Follow the [installation guide](/docs/installation) to configure the registry, load styles, and choose import aliases. The component uses Base UI OTP Field.

## Usage

```tsx
import {
  Field,
  FieldDescription,
  FieldLabel,
} from "@workspace/ui/components/field";
import {
  InputOTP,
  InputOTPGroup,
  InputOTPSeparator,
  InputOTPSlot,
} from "@workspace/ui/components/input-otp";
import { useId } from "react";

function VerificationCode() {
  const id = useId();

  return (
    <Field>
      <FieldLabel htmlFor={id}>Verification code</FieldLabel>
      <InputOTP id={id} length={6} aria-describedby={`${id}-description`}>
        <InputOTPGroup>
          <InputOTPSlot />
          <InputOTPSlot />
          <InputOTPSlot />
        </InputOTPGroup>
        <InputOTPSeparator />
        <InputOTPGroup>
          <InputOTPSlot />
          <InputOTPSlot />
          <InputOTPSlot />
        </InputOTPGroup>
      </InputOTP>
      <FieldDescription id={`${id}-description`}>
        Enter the six-digit verification code you received.
      </FieldDescription>
    </Field>
  );
}
```

Render one `InputOTPSlot` per character in `length`. Slots register in DOM order, including across groups. `InputOTPGroup` arranges slots and `InputOTPSeparator` provides a visual divider; neither consumes a character.

## Values and completion

Use `value` and `onValueChange` for a controlled value, or `defaultValue` for internal state. `onValueComplete` reports a completed code so the application can verify it. Completion means every character is entered; it does not prove that the code is valid and does not automatically enable success feedback.

```tsx
const [value, setValue] = useState("");

<InputOTP
  length={6}
  value={value}
  onValueChange={setValue}
  onValueComplete={(code) => verifyCode(code)}
>
  <InputOTPGroup>
    {[0, 1, 2, 3, 4, 5].map((position) => (
      <InputOTPSlot key={position} />
    ))}
  </InputOTPGroup>
</InputOTP>;
```

The standard change and completion callbacks receive the value and Base UI event details. A complete pasted code can trigger completion again, allowing verification to retry.

### Example: input-otp-controlled

```tsx
"use client";

import { Field, FieldLabel } from "@workspace/ui/components/field";
import {
  InputOTP,
  InputOTPGroup,
  InputOTPSlot,
} from "@workspace/ui/components/input-otp";
import * as React from "react";

export default function InputOTPControlled() {
  const [value, setValue] = React.useState("");
  const id = React.useId();

  return (
    <Field className="w-fit gap-2">
      <FieldLabel htmlFor={id}>One-time password</FieldLabel>
      <InputOTP id={id} length={6} value={value} onValueChange={setValue}>
        <InputOTPGroup>
          <InputOTPSlot />
          <InputOTPSlot />
          <InputOTPSlot />
          <InputOTPSlot />
          <InputOTPSlot />
          <InputOTPSlot />
        </InputOTPGroup>
      </InputOTP>
      <output className="block text-center text-sm" aria-live="polite">
        {value === "" ? (
          <>Enter your one-time password.</>
        ) : (
          <>You entered: {value}</>
        )}
      </output>
    </Field>
  );
}
```

## Verification feedback

The application controls `status` and owns the verification request:

| Status | Behavior |
| --- | --- |
| `idle` | Editable inputs; filling them does not mark verification successful |
| `loading` | Inputs become read-only and collapse into a spinning indicator while the request runs |
| `success` | The indicator morphs into a check with a halo and particles; the check stays visible and inputs remain collapsed |
| `error` | The indicator morphs into an X, then fades out as the inputs unfold back to their original positions |

After your request resolves, set `success` or `error`. Success remains displayed until your application explicitly sets `status="idle"`, such as when the user chooses to enter a new code.

Error holds the X for `feedbackDuration`, then fades it out while the slots move back out to their original positions over about `380` milliseconds. The field stays read-only during this reverse transition. Once it finishes, editing and eligible focus are restored without changing the value or mask setting. `onStatusChange` requests `idle` only after error restoration. Connect it to your status setter so retry controls become available too.

```tsx
const id = useId();
const [status, setStatus] = useState<InputOTPStatus>("idle");
const feedback = {
  idle: "Enter your verification code",
  loading: "Verifying code",
  success: "Code verified",
  error: "Verification failed. Try again",
};

<Field>
  <FieldLabel htmlFor={id}>Verification code</FieldLabel>
  <InputOTP
    id={id}
    length={6}
    value={value}
    onValueChange={setValue}
    status={status}
    onStatusChange={setStatus}
    onValueComplete={async (code) => {
      setStatus("loading");
      try {
        const valid = await verifyCode(code);
        setStatus(valid ? "success" : "error");
      } catch {
        setStatus("error");
      }
    }}
  >
    {slots}
  </InputOTP>
  <FieldDescription role="status" aria-live="polite">
    {feedback[status]}
  </FieldDescription>
</Field>;
```

Import `InputOTPStatus` from the same component module. Keep request cancellation and stale-response handling in the application; the live example cancels its local timer on unmount and ignores superseded requests.

`feedbackDuration` defaults to `1250` milliseconds for the error result hold and does not time out `loading`. Error unfolds after that hold; success keeps its check until your application resets the status.

Reduced motion disables movement and particles while preserving the result hold. Error then returns to inputs without the animated transition; success still keeps its check. Timers complete the lifecycle when animation styles are unavailable. Zero duration skips the result hold. Restoration respects explicit `disabled` and `readOnly` settings. After an error, focus returns to the first slot when the field owned focus before feedback and the user has not moved focus elsewhere.

## Character filtering

`validationType` controls accepted characters. `numeric` is the default; use `alpha` for ASCII letters, `alphanumeric` for ASCII letters and digits, or `none` for custom rules. Spaces are removed and the result is limited to `length`.

Use `normalizeValue` for transformations such as uppercasing. It runs after built-in filtering, and the returned result is filtered again. Keep it idempotent. With `validationType="none"`, it can supply the custom filtering rule. `onValueInvalid` reports rejected typed or pasted characters; `inputMode` supplies a keyboard hint, not a verification result.

```tsx
<InputOTP
  length={6}
  validationType="alphanumeric"
  normalizeValue={(value) => value.toUpperCase()}
>
  {slots}
</InputOTP>;
```

### Example: input-otp-pattern

```tsx
"use client";

import { Field, FieldLabel } from "@workspace/ui/components/field";
import {
  InputOTP,
  InputOTPGroup,
  InputOTPSlot,
} from "@workspace/ui/components/input-otp";
import { useId as usePreviewId } from "react";

export function InputOTPPattern() {
  const previewId = usePreviewId();

  return (
    <Field className="w-fit">
      <FieldLabel htmlFor={`${previewId}-digits-only`}>Digits Only</FieldLabel>
      <InputOTP
        id={`${previewId}-digits-only`}
        length={6}
        validationType="numeric"
      >
        <InputOTPGroup>
          <InputOTPSlot />
          <InputOTPSlot />
          <InputOTPSlot />
          <InputOTPSlot />
          <InputOTPSlot />
          <InputOTPSlot />
        </InputOTPGroup>
      </InputOTP>
    </Field>
  );
}

export default InputOTPPattern;
```

## Groups and separators

Divide a code into readable groups while keeping the same total slot count.

### Example: input-otp-separator

```tsx
import { Field, FieldLabel } from "@workspace/ui/components/field";
import {
  InputOTP,
  InputOTPGroup,
  InputOTPSeparator,
  InputOTPSlot,
} from "@workspace/ui/components/input-otp";
import { useId } from "react";

export default function InputOTPWithSeparator() {
  const id = useId();
  return (
    <Field className="w-fit">
      <FieldLabel htmlFor={id}>Verification code</FieldLabel>
      <InputOTP id={id} length={6}>
        <InputOTPGroup>
          <InputOTPSlot />
          <InputOTPSlot />
        </InputOTPGroup>
        <InputOTPSeparator />
        <InputOTPGroup>
          <InputOTPSlot />
          <InputOTPSlot />
        </InputOTPGroup>
        <InputOTPSeparator />
        <InputOTPGroup>
          <InputOTPSlot />
          <InputOTPSlot />
        </InputOTPGroup>
      </InputOTP>
    </Field>
  );
}
```

## Disabled and read-only

`disabled` blocks interaction. `readOnly` prevents editing while preserving the current value. Loading and result feedback make the field read-only without clearing its value. Success stays collapsed until the application explicitly resets its status.

### Example: input-otp-disabled

```tsx
import { Field, FieldLabel } from "@workspace/ui/components/field";
import {
  InputOTP,
  InputOTPGroup,
  InputOTPSeparator,
  InputOTPSlot,
} from "@workspace/ui/components/input-otp";
import { useId } from "react";

export function InputOTPDisabled() {
  const id = useId();
  return (
    <Field className="w-fit">
      <FieldLabel htmlFor={id}>Disabled verification code</FieldLabel>
      <InputOTP id={id} length={6} disabled value="123456">
        <InputOTPGroup>
          <InputOTPSlot />
          <InputOTPSlot />
          <InputOTPSlot />
        </InputOTPGroup>
        <InputOTPSeparator />
        <InputOTPGroup>
          <InputOTPSlot />
          <InputOTPSlot />
          <InputOTPSlot />
        </InputOTPGroup>
      </InputOTP>
    </Field>
  );
}

export default InputOTPDisabled;
```

## Invalid fields

Use `aria-invalid` on the slots and `data-invalid` on the shared `Field` for persistent invalid styling. The shared `Field` handles layout and labels; use the underlying Base UI Field API when you need its form validation context. `status="error"` controls temporary verification feedback and does not replace the form's invalid state.

### Example: input-otp-invalid

```tsx
"use client";

import {
  Field,
  FieldDescription,
  FieldLabel,
} from "@workspace/ui/components/field";
import {
  InputOTP,
  InputOTPGroup,
  InputOTPSeparator,
  InputOTPSlot,
} from "@workspace/ui/components/input-otp";
import * as React from "react";

export function InputOTPInvalid() {
  const [value, setValue] = React.useState("000000");
  const id = React.useId();

  return (
    <Field data-invalid className="w-fit">
      <FieldLabel htmlFor={id}>Verification code</FieldLabel>
      <InputOTP id={id} length={6} value={value} onValueChange={setValue}>
        <InputOTPGroup>
          <InputOTPSlot aria-invalid aria-describedby={`${id}-error`} />
          <InputOTPSlot aria-invalid aria-describedby={`${id}-error`} />
        </InputOTPGroup>
        <InputOTPSeparator />
        <InputOTPGroup>
          <InputOTPSlot aria-invalid aria-describedby={`${id}-error`} />
          <InputOTPSlot aria-invalid aria-describedby={`${id}-error`} />
        </InputOTPGroup>
        <InputOTPSeparator />
        <InputOTPGroup>
          <InputOTPSlot aria-invalid aria-describedby={`${id}-error`} />
          <InputOTPSlot aria-invalid aria-describedby={`${id}-error`} />
        </InputOTPGroup>
      </InputOTP>
      <FieldDescription id={`${id}-error`}>
        The verification code is invalid. Try another code.
      </FieldDescription>
    </Field>
  );
}

export default InputOTPInvalid;
```

## Four digits

Use `length={4}` and four slots for a numeric PIN.

### Example: input-otp-four-digits

```tsx
"use client";

import { Field, FieldLabel } from "@workspace/ui/components/field";
import {
  InputOTP,
  InputOTPGroup,
  InputOTPSlot,
} from "@workspace/ui/components/input-otp";
import { useId } from "react";

export function InputOTPFourDigits() {
  const id = useId();
  return (
    <Field className="w-fit">
      <FieldLabel htmlFor={id}>Four-digit PIN</FieldLabel>
      <InputOTP id={id} length={4} validationType="numeric">
        <InputOTPGroup>
          <InputOTPSlot />
          <InputOTPSlot />
          <InputOTPSlot />
          <InputOTPSlot />
        </InputOTPGroup>
      </InputOTP>
    </Field>
  );
}

export default InputOTPFourDigits;
```

## Alphanumeric codes

Use `validationType="alphanumeric"` for codes containing letters and digits.

### Example: input-otp-alphanumeric

```tsx
"use client";

import { Field, FieldLabel } from "@workspace/ui/components/field";
import {
  InputOTP,
  InputOTPGroup,
  InputOTPSeparator,
  InputOTPSlot,
} from "@workspace/ui/components/input-otp";
import { useId } from "react";

export function InputOTPAlphanumeric() {
  const id = useId();
  return (
    <Field className="w-fit">
      <FieldLabel htmlFor={id}>Alphanumeric verification code</FieldLabel>
      <InputOTP id={id} length={6} validationType="alphanumeric">
        <InputOTPGroup>
          <InputOTPSlot />
          <InputOTPSlot />
          <InputOTPSlot />
        </InputOTPGroup>
        <InputOTPSeparator />
        <InputOTPGroup>
          <InputOTPSlot />
          <InputOTPSlot />
          <InputOTPSlot />
        </InputOTPGroup>
      </InputOTP>
    </Field>
  );
}

export default InputOTPAlphanumeric;
```

## Masked entry

Set `mask` to use Base UI's native password presentation for the character inputs. This hides the displayed characters; the controlled value, callbacks, and submitted form value still contain the real code. Masking does not encrypt it.

The masked example runs the same verification flow. A successful check stays visible; after an error, the restored inputs retain their code and continue displaying masked characters.

### Example: input-otp-masked

```tsx
"use client";

import type { ExampleProps } from "../types";
import InputOTPExample from "./input-otp-demo";

export default function Example(props: ExampleProps) {
  return <InputOTPExample {...props} mask />;
}
```

## Forms

`name` submits the combined code through Base UI's hidden validation input. Use `required` for required entry. `autoSubmit` defaults to `false`; enabling it requests submission of the owning form on completion, independently of whether server verification succeeds.

### Example: input-otp-form

```tsx
"use client";

import { Button } from "@workspace/ui/components/button";
import {
  Card,
  CardContent,
  CardDescription,
  CardFooter,
  CardHeader,
  CardTitle,
} from "@workspace/ui/components/card";
import {
  Field,
  FieldDescription,
  FieldLabel,
} from "@workspace/ui/components/field";
import {
  InputOTP,
  InputOTPGroup,
  InputOTPSeparator,
  InputOTPSlot,
} from "@workspace/ui/components/input-otp";
import { RefreshCwIcon } from "lucide-react";
import { useId, useRef, useState } from "react";
import type { ExampleProps } from "../types";

export function InputOTPForm({ locale }: ExampleProps) {
  const id = useId();
  const chinese = locale === "zh-CN";
  const [value, setValue] = useState("");
  const [submitted, setSubmitted] = useState<string | null>(null);
  const firstInput = useRef<HTMLInputElement>(null);

  return (
    <form
      className="mx-auto w-full max-w-md"
      onSubmit={(event) => {
        event.preventDefault();
        const code = new FormData(event.currentTarget).get("verification-code");
        setSubmitted(String(code ?? ""));
      }}
    >
      <Card>
        <CardHeader>
          <CardTitle>{chinese ? "验证登录" : "Verify your login"}</CardTitle>
          <CardDescription>
            {chinese
              ? "输入发送至以下邮箱的验证码："
              : "Enter the verification code sent to your email address: "}
            <span className="font-medium">m@example.com</span>.
          </CardDescription>
        </CardHeader>
        <CardContent>
          <Field>
            <div className="flex items-center justify-between">
              <FieldLabel htmlFor={id}>
                {chinese ? "验证码" : "Verification code"}
              </FieldLabel>
              <Button
                type="button"
                variant="outline"
                size="xs"
                onClick={() => {
                  setValue("");
                  setSubmitted(null);
                  firstInput.current?.focus();
                }}
              >
                <RefreshCwIcon />
                {chinese ? "重新输入" : "Enter again"}
              </Button>
            </div>
            <InputOTP
              id={id}
              length={6}
              name="verification-code"
              required
              validationType="numeric"
              value={value}
              onValueChange={(next) => {
                setValue(next);
                setSubmitted(null);
              }}
            >
              <InputOTPGroup className="*:data-[slot=input-otp-slot]:h-12 *:data-[slot=input-otp-slot]:w-11 *:data-[slot=input-otp-slot]:text-xl">
                <InputOTPSlot ref={firstInput} />
                <InputOTPSlot />
                <InputOTPSlot />
              </InputOTPGroup>
              <InputOTPSeparator className="mx-2" />
              <InputOTPGroup className="*:data-[slot=input-otp-slot]:h-12 *:data-[slot=input-otp-slot]:w-11 *:data-[slot=input-otp-slot]:text-xl">
                <InputOTPSlot />
                <InputOTPSlot />
                <InputOTPSlot />
              </InputOTPGroup>
            </InputOTP>
            <FieldDescription>
              {chinese
                ? "填写全部六位数字后提交。验证码通过原生表单字段提交"
                : "Complete all six digits before submitting. The code is submitted as a native form field."}
            </FieldDescription>
          </Field>
        </CardContent>
        <CardFooter>
          <Field>
            <Button type="submit" className="w-full">
              {chinese ? "提交验证码" : "Submit code"}
            </Button>
            <output
              aria-live="polite"
              className="min-h-5 text-center text-muted-foreground text-sm"
            >
              {submitted !== null &&
                `${chinese ? "已提交验证码：" : "Submitted code: "}${submitted}`}
            </output>
          </Field>
        </CardFooter>
      </Card>
    </form>
  );
}

export default InputOTPForm;
```

## Labels, refs, and direction

`InputOTP` renders a `div`; its `ref` points to that root. Each `InputOTPSlot` renders a real `input` and accepts an `HTMLInputElement` ref, native input attributes, and Base UI input state styling. Use a slot ref to focus or inspect a character input.

Compose a visible label with the shared `Field`, `FieldLabel`, and `useId`, as in the usage example. Alternatively, import `Label` from `@workspace/ui/components/label` and associate its `htmlFor` with the `InputOTP` `id`. The shared `Field` provides layout and label composition; it is distinct from Base UI Field's validation context. Slots preserve Base UI position semantics and native ARIA attributes. The component does not generate labels or status text. Loading sets `aria-busy`; the application displays and announces feedback through `FieldDescription`, `FieldError`, or `role="status"`, as in the verification example.

Use the shared `DirectionProvider` from `@workspace/ui/components/direction` with `direction="rtl"` for right-to-left navigation and layout.

### Example: input-otp-rtl

```tsx
"use client";

import { DirectionProvider } from "@workspace/ui/components/direction";
import { Field, FieldLabel } from "@workspace/ui/components/field";
import {
  InputOTP,
  InputOTPGroup,
  InputOTPSlot,
} from "@workspace/ui/components/input-otp";
import { useId as usePreviewId } from "react";
import { type Translations, useTranslation } from "./support";

const translations: Translations = {
  en: {
    dir: "ltr",
    values: {
      verificationCode: "Verification code",
    },
  },
  ar: {
    dir: "rtl",
    values: {
      verificationCode: "رمز التحقق",
    },
  },
  he: {
    dir: "rtl",
    values: {
      verificationCode: "קוד אימות",
    },
  },
};

export function InputOTPRtl() {
  const previewId = usePreviewId();

  const { dir, t } = useTranslation(translations, "ar");

  return (
    <DirectionProvider direction={dir}>
      <Field className="mx-auto max-w-xs" dir={dir}>
        <FieldLabel htmlFor={`${previewId}-input-otp-rtl`}>
          {t.verificationCode}
        </FieldLabel>
        <InputOTP length={6} dir={dir} id={`${previewId}-input-otp-rtl`}>
          <InputOTPGroup>
            <InputOTPSlot />
            <InputOTPSlot />
            <InputOTPSlot />
            <InputOTPSlot />
            <InputOTPSlot />
            <InputOTPSlot />
          </InputOTPGroup>
        </InputOTP>
      </Field>
    </DirectionProvider>
  );
}

export default InputOTPRtl;
```

## API reference

### InputOTP

| Prop | Type | Default / behavior |
| --- | --- | --- |
| `length` | `number` | `6`; number of character slots |
| `value`, `defaultValue` | `string` | Controlled value or initial internal value |
| `onValueChange` | `(value, details) => void` | Base UI value change callback |
| `onValueComplete` | `(value, details) => void` | Reports completed entry; does not verify it |
| `status` | `InputOTPStatus` | `"idle"`; controlled verification feedback |
| `onStatusChange` | `(status: InputOTPStatus) => void` | Requests `"idle"` after error restoration |
| `feedbackDuration` | `number` | `1250` ms; error result hold before unfolding |
| `mask` | `boolean` | `false`; hides characters without changing the real value |
| `glass` | `boolean` | `false`; enables the shared material for slots |

`InputOTPGroup` accepts div props. `InputOTPSeparator` accepts Base UI separator props. `InputOTPSlot` accepts Base UI OTP input props and an `HTMLInputElement` ref. Slot order determines position.

The module exports `InputOTPProps` and `InputOTPStatus`. Character filtering, form options, native input attributes, state styling, and event detail types follow the [Base UI OTP Field API](https://base-ui.com/react/components/otp-field#api-reference).

- [Documentation](https://base-ui.com/react/components/otp-field)


---

# Item

A versatile component for displaying content with media, title, description, and actions.

Page: https://sui.draco.dev/docs/components/item

### Example: item-demo

```tsx
import { Button } from "@workspace/ui/components/button";
import {
  Item,
  ItemActions,
  ItemContent,
  ItemDescription,
  ItemMedia,
  ItemTitle,
} from "@workspace/ui/components/item";
import { BadgeCheckIcon, ChevronRightIcon } from "lucide-react";

export function ItemDemo() {
  return (
    <div className="flex w-full max-w-md flex-col gap-6">
      <Item variant="outline">
        <ItemContent>
          <ItemTitle>Basic Item</ItemTitle>
          <ItemDescription>
            A simple item with title and description.
          </ItemDescription>
        </ItemContent>
        <ItemActions>
          <Button variant="outline" size="sm">
            Action
          </Button>
        </ItemActions>
      </Item>
      <Item variant="outline" size="sm" render={<a href="/docs" />}>
        <ItemMedia>
          <BadgeCheckIcon className="size-5" />
        </ItemMedia>
        <ItemContent>
          <ItemTitle>Your profile has been verified.</ItemTitle>
        </ItemContent>
        <ItemActions>
          <ChevronRightIcon className="size-4" />
        </ItemActions>
      </Item>
    </div>
  );
}

export default ItemDemo;
```

The `Item` component is a straightforward flex container that can house nearly any type of content. Use it to display a title, description, and actions. Group it with the `ItemGroup` component to create a list of items.

## Installation

```bash
bunx --bun shadcn@latest add @sui/item
```

Install with the shadcn CLI or use the shared `@workspace/ui` package. Follow the [installation guide](/docs/installation) to configure the registry, load styles, and choose import aliases.

## Usage

```tsx showLineNumbers
import {
  Item,
  ItemActions,
  ItemContent,
  ItemDescription,
  ItemMedia,
  ItemTitle,
} from "@workspace/ui/components/item"
```

```tsx showLineNumbers
<Item>
  <ItemMedia variant="icon">
    <Icon />
  </ItemMedia>
  <ItemContent>
    <ItemTitle>Title</ItemTitle>
    <ItemDescription>Description</ItemDescription>
  </ItemContent>
  <ItemActions>
    <Button>Action</Button>
  </ItemActions>
</Item>
```

## Composition

Use the following composition to build an `Item`:

```text
ItemGroup
└── Item
    ├── ItemHeader
    ├── ItemMedia
    ├── ItemContent
    │   ├── ItemTitle
    │   └── ItemDescription
    ├── ItemActions
    └── ItemFooter
```

## Item vs Field

Use `Field` if you need to display a form input such as a checkbox, input, radio, or select.

If you only need to display content such as a title, description, and actions, use `Item`.

## Variant

Use the `variant` prop to change the visual style of the item.

### Example: item-variant

```tsx
import {
  Item,
  ItemContent,
  ItemDescription,
  ItemMedia,
  ItemTitle,
} from "@workspace/ui/components/item";
import { InboxIcon } from "lucide-react";

export function ItemVariant() {
  return (
    <div className="flex w-full max-w-md flex-col gap-6">
      <Item>
        <ItemMedia variant="icon">
          <InboxIcon />
        </ItemMedia>
        <ItemContent>
          <ItemTitle>Default Variant</ItemTitle>
          <ItemDescription>
            Transparent background with no border.
          </ItemDescription>
        </ItemContent>
      </Item>
      <Item variant="outline">
        <ItemMedia variant="icon">
          <InboxIcon />
        </ItemMedia>
        <ItemContent>
          <ItemTitle>Outline Variant</ItemTitle>
          <ItemDescription>
            Outlined style with a visible border.
          </ItemDescription>
        </ItemContent>
      </Item>
      <Item variant="muted">
        <ItemMedia variant="icon">
          <InboxIcon />
        </ItemMedia>
        <ItemContent>
          <ItemTitle>Muted Variant</ItemTitle>
          <ItemDescription>
            Muted background for secondary content.
          </ItemDescription>
        </ItemContent>
      </Item>
    </div>
  );
}

export default ItemVariant;
```

## Size

Use the `size` prop to change the size of the item. Available sizes are `default`, `sm`, and `xs`.

### Example: item-size

```tsx
import {
  Item,
  ItemContent,
  ItemDescription,
  ItemMedia,
  ItemTitle,
} from "@workspace/ui/components/item";
import { InboxIcon } from "lucide-react";

export function ItemSizeDemo() {
  return (
    <div className="flex w-full max-w-md flex-col gap-6">
      <Item variant="outline">
        <ItemMedia variant="icon">
          <InboxIcon />
        </ItemMedia>
        <ItemContent>
          <ItemTitle>Default Size</ItemTitle>
          <ItemDescription>
            The standard size for most use cases.
          </ItemDescription>
        </ItemContent>
      </Item>
      <Item variant="outline" size="sm">
        <ItemMedia variant="icon">
          <InboxIcon />
        </ItemMedia>
        <ItemContent>
          <ItemTitle>Small Size</ItemTitle>
          <ItemDescription>A compact size for dense layouts.</ItemDescription>
        </ItemContent>
      </Item>
      <Item variant="outline" size="xs">
        <ItemMedia variant="icon">
          <InboxIcon />
        </ItemMedia>
        <ItemContent>
          <ItemTitle>Extra Small Size</ItemTitle>
          <ItemDescription>The most compact size available.</ItemDescription>
        </ItemContent>
      </Item>
    </div>
  );
}

export default ItemSizeDemo;
```

## Icon

Use `ItemMedia` with `variant="icon"` to display an icon.

### Example: item-icon

```tsx
import { Button } from "@workspace/ui/components/button";
import {
  Item,
  ItemActions,
  ItemContent,
  ItemDescription,
  ItemMedia,
  ItemTitle,
} from "@workspace/ui/components/item";
import { ShieldAlertIcon } from "lucide-react";

export function ItemIcon() {
  return (
    <div className="flex w-full max-w-lg flex-col gap-6">
      <Item variant="outline">
        <ItemMedia variant="icon">
          <ShieldAlertIcon />
        </ItemMedia>
        <ItemContent>
          <ItemTitle>Security Alert</ItemTitle>
          <ItemDescription>
            New login detected from unknown device.
          </ItemDescription>
        </ItemContent>
        <ItemActions>
          <Button size="sm" variant="outline">
            Review
          </Button>
        </ItemActions>
      </Item>
    </div>
  );
}

export default ItemIcon;
```

## Avatar

You can use `ItemMedia` with `variant="avatar"` to display an avatar.

### Example: item-avatar

```tsx
import {
  Avatar,
  AvatarFallback,
  AvatarImage,
} from "@workspace/ui/components/avatar";
import { Button } from "@workspace/ui/components/button";
import {
  Item,
  ItemActions,
  ItemContent,
  ItemDescription,
  ItemMedia,
  ItemTitle,
} from "@workspace/ui/components/item";
import { Plus } from "lucide-react";

export function ItemAvatar() {
  return (
    <div className="flex w-full max-w-lg flex-col gap-6">
      <Item variant="outline">
        <ItemMedia>
          <Avatar className="size-10">
            <AvatarImage src="https://github.com/evilrabbit.png" />
            <AvatarFallback>ER</AvatarFallback>
          </Avatar>
        </ItemMedia>
        <ItemContent>
          <ItemTitle>Evil Rabbit</ItemTitle>
          <ItemDescription>Last seen 5 months ago</ItemDescription>
        </ItemContent>
        <ItemActions>
          <Button
            size="icon-sm"
            variant="outline"
            className="rounded-full"
            aria-label="Invite"
          >
            <Plus />
          </Button>
        </ItemActions>
      </Item>
      <Item variant="outline">
        <ItemMedia>
          <div className="flex -space-x-2 *:data-[slot=avatar]:ring-2 *:data-[slot=avatar]:ring-background *:data-[slot=avatar]:grayscale">
            <Avatar className="hidden sm:flex">
              <AvatarImage src="https://github.com/shadcn.png" alt="@shadcn" />
              <AvatarFallback>CN</AvatarFallback>
            </Avatar>
            <Avatar className="hidden sm:flex">
              <AvatarImage
                src="https://github.com/maxleiter.png"
                alt="@maxleiter"
              />
              <AvatarFallback>LR</AvatarFallback>
            </Avatar>
            <Avatar>
              <AvatarImage
                src="https://github.com/evilrabbit.png"
                alt="@evilrabbit"
              />
              <AvatarFallback>ER</AvatarFallback>
            </Avatar>
          </div>
        </ItemMedia>
        <ItemContent>
          <ItemTitle>No Team Members</ItemTitle>
          <ItemDescription>
            Invite your team to collaborate on this project.
          </ItemDescription>
        </ItemContent>
        <ItemActions>
          <Button size="sm" variant="outline">
            Invite
          </Button>
        </ItemActions>
      </Item>
    </div>
  );
}

export default ItemAvatar;
```

## Image

Use `ItemMedia` with `variant="image"` to display an image.

### Example: item-image

```tsx
import {
  Item,
  ItemContent,
  ItemDescription,
  ItemGroup,
  ItemMedia,
  ItemTitle,
} from "@workspace/ui/components/item";

const music = [
  {
    title: "Midnight City Lights",
    artist: "Neon Dreams",
    album: "Electric Nights",
    duration: "3:45",
  },
  {
    title: "Coffee Shop Conversations",
    artist: "The Morning Brew",
    album: "Urban Stories",
    duration: "4:05",
  },
  {
    title: "Digital Rain",
    artist: "Cyber Symphony",
    album: "Binary Beats",
    duration: "3:30",
  },
];

export function ItemImage() {
  return (
    <div className="flex w-full max-w-md flex-col gap-6">
      <ItemGroup className="gap-4">
        {music.map((song) => (
          <Item
            key={song.title}
            variant="outline"
            render={<a href="/docs" />}
            role="listitem"
          >
            <ItemMedia variant="image">
              <img
                src={`https://avatar.vercel.sh/${song.title}`}
                alt={song.title}
                width={32}
                height={32}
                className="object-cover grayscale"
              />
            </ItemMedia>
            <ItemContent>
              <ItemTitle className="line-clamp-1">
                {song.title} -{" "}
                <span className="text-muted-foreground">{song.album}</span>
              </ItemTitle>
              <ItemDescription>{song.artist}</ItemDescription>
            </ItemContent>
            <ItemContent className="flex-none text-center">
              <ItemDescription>{song.duration}</ItemDescription>
            </ItemContent>
          </Item>
        ))}
      </ItemGroup>
    </div>
  );
}

export default ItemImage;
```

## Group

Use `ItemGroup` to group related items together.

### Example: item-group

```tsx
import {
  Avatar,
  AvatarFallback,
  AvatarImage,
} from "@workspace/ui/components/avatar";
import { Button } from "@workspace/ui/components/button";
import {
  Item,
  ItemActions,
  ItemContent,
  ItemDescription,
  ItemGroup,
  ItemMedia,
  ItemTitle,
} from "@workspace/ui/components/item";
import { PlusIcon } from "lucide-react";

const people = [
  {
    username: "shadcn",
    avatar: "https://github.com/shadcn.png",
    email: "shadcn@vercel.com",
  },
  {
    username: "maxleiter",
    avatar: "https://github.com/maxleiter.png",
    email: "maxleiter@vercel.com",
  },
  {
    username: "evilrabbit",
    avatar: "https://github.com/evilrabbit.png",
    email: "evilrabbit@vercel.com",
  },
];

export function ItemGroupExample() {
  return (
    <ItemGroup className="max-w-sm">
      {people.map((person, _index) => (
        <Item key={person.username} variant="outline">
          <ItemMedia>
            <Avatar>
              <AvatarImage src={person.avatar} className="grayscale" />
              <AvatarFallback>{person.username.charAt(0)}</AvatarFallback>
            </Avatar>
          </ItemMedia>
          <ItemContent className="gap-1">
            <ItemTitle>{person.username}</ItemTitle>
            <ItemDescription>{person.email}</ItemDescription>
          </ItemContent>
          <ItemActions>
            <Button variant="ghost" size="icon" className="rounded-full">
              <PlusIcon />
            </Button>
          </ItemActions>
        </Item>
      ))}
    </ItemGroup>
  );
}

export default ItemGroupExample;
```

## Header

Use `ItemHeader` to add a header above the item content.

### Example: item-header

```tsx
import {
  Item,
  ItemContent,
  ItemDescription,
  ItemGroup,
  ItemHeader,
  ItemTitle,
} from "@workspace/ui/components/item";

const models = [
  {
    name: "v0-1.5-sm",
    description: "Everyday tasks and UI generation.",
    image:
      "https://images.unsplash.com/photo-1650804068570-7fb2e3dbf888?q=80&w=640&auto=format&fit=crop",
    credit: "Valeria Reverdo on Unsplash",
  },
  {
    name: "v0-1.5-lg",
    description: "Advanced thinking or reasoning.",
    image:
      "https://images.unsplash.com/photo-1610280777472-54133d004c8c?q=80&w=640&auto=format&fit=crop",
    credit: "Michael Oeser on Unsplash",
  },
  {
    name: "v0-2.0-mini",
    description: "Open Source model for everyone.",
    image:
      "https://images.unsplash.com/photo-1602146057681-08560aee8cde?q=80&w=640&auto=format&fit=crop",
    credit: "Cherry Laithang on Unsplash",
  },
];

export function ItemHeaderDemo() {
  return (
    <div className="flex w-full max-w-xl flex-col gap-6">
      <ItemGroup className="grid grid-cols-3 gap-4">
        {models.map((model) => (
          <Item key={model.name} variant="outline">
            <ItemHeader>
              <img
                src={model.image}
                alt={model.name}
                width={128}
                height={128}
                className="aspect-square w-full rounded-sm object-cover"
              />
            </ItemHeader>
            <ItemContent>
              <ItemTitle>{model.name}</ItemTitle>
              <ItemDescription>{model.description}</ItemDescription>
            </ItemContent>
          </Item>
        ))}
      </ItemGroup>
    </div>
  );
}

export default ItemHeaderDemo;
```

## Link

Use the `render` prop to render the item as a link. The hover and focus states will be applied to the anchor element.

### Example: item-link

```tsx
import {
  Item,
  ItemActions,
  ItemContent,
  ItemDescription,
  ItemTitle,
} from "@workspace/ui/components/item";
import { ChevronRightIcon, ExternalLinkIcon } from "lucide-react";

export function ItemLink() {
  return (
    <div className="flex w-full max-w-md flex-col gap-4">
      <Item render={<a href="/docs" />}>
        <ItemContent>
          <ItemTitle>Visit our documentation</ItemTitle>
          <ItemDescription>
            Learn how to get started with our components.
          </ItemDescription>
        </ItemContent>
        <ItemActions>
          <ChevronRightIcon className="size-4" />
        </ItemActions>
      </Item>
      <Item
        variant="outline"
        render={<a href="/docs" target="_blank" rel="noopener noreferrer" />}
      >
        <ItemContent>
          <ItemTitle>External resource</ItemTitle>
          <ItemDescription>
            Opens in a new tab with security attributes.
          </ItemDescription>
        </ItemContent>
        <ItemActions>
          <ExternalLinkIcon className="size-4" />
        </ItemActions>
      </Item>
    </div>
  );
}

export default ItemLink;
```

```tsx showLineNumbers
<Item render={<a href="/dashboard" />}>
  <ItemMedia variant="icon">
    <HomeIcon />
  </ItemMedia>
  <ItemContent>
    <ItemTitle>Dashboard</ItemTitle>
    <ItemDescription>Overview of your account and activity.</ItemDescription>
  </ItemContent>
</Item>
```

## Dropdown

### Example: item-dropdown

```tsx
"use client";

import {
  Avatar,
  AvatarFallback,
  AvatarImage,
} from "@workspace/ui/components/avatar";
import { Button } from "@workspace/ui/components/button";
import {
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuGroup,
  DropdownMenuItem,
  DropdownMenuTrigger,
} from "@workspace/ui/components/dropdown-menu";
import {
  Item,
  ItemContent,
  ItemDescription,
  ItemMedia,
  ItemTitle,
} from "@workspace/ui/components/item";
import { ChevronDownIcon } from "lucide-react";

const people = [
  {
    username: "shadcn",
    avatar: "https://github.com/shadcn.png",
    email: "shadcn@vercel.com",
  },
  {
    username: "maxleiter",
    avatar: "https://github.com/maxleiter.png",
    email: "maxleiter@vercel.com",
  },
  {
    username: "evilrabbit",
    avatar: "https://github.com/evilrabbit.png",
    email: "evilrabbit@vercel.com",
  },
];

export function ItemDropdown() {
  return (
    <DropdownMenu>
      <DropdownMenuTrigger render={<Button variant="outline" />}>
        Select <ChevronDownIcon />
      </DropdownMenuTrigger>
      <DropdownMenuContent className="w-48" align="end">
        <DropdownMenuGroup>
          {people.map((person) => (
            <DropdownMenuItem key={person.username}>
              <Item size="xs" className="w-full p-2">
                <ItemMedia>
                  <Avatar className="size-[--spacing(6.5)]">
                    <AvatarImage src={person.avatar} className="grayscale" />
                    <AvatarFallback>{person.username.charAt(0)}</AvatarFallback>
                  </Avatar>
                </ItemMedia>
                <ItemContent className="gap-0">
                  <ItemTitle>{person.username}</ItemTitle>
                  <ItemDescription className="leading-none">
                    {person.email}
                  </ItemDescription>
                </ItemContent>
              </Item>
            </DropdownMenuItem>
          ))}
        </DropdownMenuGroup>
      </DropdownMenuContent>
    </DropdownMenu>
  );
}

export default ItemDropdown;
```

## RTL

To enable RTL support in shadcn/ui, see the [RTL configuration guide](https://ui.shadcn.com/docs/rtl).

### Example: item-rtl

```tsx
"use client";

import { Button } from "@workspace/ui/components/button";
import {
  Item,
  ItemActions,
  ItemContent,
  ItemDescription,
  ItemMedia,
  ItemTitle,
} from "@workspace/ui/components/item";
import { BadgeCheckIcon, ChevronRightIcon } from "lucide-react";
import { type Translations, useTranslation } from "./support";

const translations: Translations = {
  en: {
    dir: "ltr",
    values: {
      basicItem: "Basic Item",
      basicItemDesc: "A simple item with title and description.",
      action: "Action",
      verifiedTitle: "Your profile has been verified.",
    },
  },
  ar: {
    dir: "rtl",
    values: {
      basicItem: "عنصر أساسي",
      basicItemDesc: "عنصر بسيط يحتوي على عنوان ووصف.",
      action: "إجراء",
      verifiedTitle: "تم التحقق من ملفك الشخصي.",
    },
  },
  he: {
    dir: "rtl",
    values: {
      basicItem: "פריט בסיסי",
      basicItemDesc: "פריט פשוט עם כותרת ותיאור.",
      action: "פעולה",
      verifiedTitle: "הפרופיל שלך אומת.",
    },
  },
};

export function ItemRtl() {
  const { dir, t } = useTranslation(translations, "ar");

  return (
    <div className="flex w-full max-w-md flex-col gap-6" dir={dir}>
      <Item variant="outline" dir={dir}>
        <ItemContent>
          <ItemTitle>{t.basicItem}</ItemTitle>
          <ItemDescription>{t.basicItemDesc}</ItemDescription>
        </ItemContent>
        <ItemActions>
          <Button variant="outline" size="sm">
            {t.action}
          </Button>
        </ItemActions>
      </Item>
      <Item variant="outline" size="sm" render={<a href="/docs" />} dir={dir}>
        <ItemMedia>
          <BadgeCheckIcon className="size-5" />
        </ItemMedia>
        <ItemContent>
          <ItemTitle>{t.verifiedTitle}</ItemTitle>
        </ItemContent>
        <ItemActions>
          <ChevronRightIcon className="size-4" />
        </ItemActions>
      </Item>
    </div>
  );
}

export default ItemRtl;
```

## API Reference

### Item

The main component for displaying content with media, title, description, and actions.

| Prop      | Type                                | Default     |
| --------- | ----------------------------------- | ----------- |
| `variant` | `"default" \| "outline" \| "muted"` | `"default"` |
| `size`    | `"default" \| "sm" \| "xs"`         | `"default"` |
| `render`  | `React.ReactElement`                |             |

### ItemGroup

A container that groups related items together with consistent styling.

```tsx
<ItemGroup>
  <Item />
  <Item />
</ItemGroup>
```

### ItemSeparator

A separator between items in a group.

```tsx
<ItemGroup>
  <Item />
  <ItemSeparator />
  <Item />
</ItemGroup>
```

### ItemMedia

Use `ItemMedia` to display media content such as icons, images, or avatars.

| Prop      | Type                             | Default     |
| --------- | -------------------------------- | ----------- |
| `variant` | `"default" \| "icon" \| "image"` | `"default"` |

```tsx
<ItemMedia variant="icon">
  <Icon />
</ItemMedia>
```

```tsx
<ItemMedia variant="image">
  <img src="..." alt="..." />
</ItemMedia>
```

### ItemContent

Wraps the title and description of the item.

```tsx
<ItemContent>
  <ItemTitle>Title</ItemTitle>
  <ItemDescription>Description</ItemDescription>
</ItemContent>
```

### ItemTitle

Displays the title of the item.

```tsx
<ItemTitle>Item Title</ItemTitle>
```

### ItemDescription

Displays the description of the item.

```tsx
<ItemDescription>Item description</ItemDescription>
```

### ItemActions

Container for action buttons or other interactive elements.

```tsx
<ItemActions>
  <Button>Action</Button>
</ItemActions>
```

### ItemHeader

Displays a header above the item content.

```tsx
<Item>
  <ItemHeader>Header</ItemHeader>
  <ItemContent>...</ItemContent>
</Item>
```

### ItemFooter

Displays a footer below the item content.

```tsx
<Item>
  <ItemContent>...</ItemContent>
  <ItemFooter>Footer</ItemFooter>
</Item>
```


---

# Kbd

Used to display textual user input from keyboard.

Page: https://sui.draco.dev/docs/components/kbd

### Example: kbd-demo

```tsx
import { Kbd, KbdGroup } from "@workspace/ui/components/kbd";

export default function KbdDemo() {
  return (
    <div className="flex flex-col items-center gap-4">
      <KbdGroup>
        <Kbd>⌘</Kbd>
        <Kbd>⇧</Kbd>
        <Kbd>⌥</Kbd>
        <Kbd>⌃</Kbd>
      </KbdGroup>
      <KbdGroup>
        <Kbd>Ctrl</Kbd>
        <span>+</span>
        <Kbd>B</Kbd>
      </KbdGroup>
    </div>
  );
}
```

## Installation

```bash
bunx --bun shadcn@latest add @sui/kbd
```

Install with the shadcn CLI or use the shared `@workspace/ui` package. Follow the [installation guide](/docs/installation) to configure the registry, load styles, and choose import aliases.

## Usage

```tsx
import { Kbd } from "@workspace/ui/components/kbd"
```

```tsx
<Kbd>Ctrl</Kbd>
```

## Composition

Use the following composition to build `Kbd` and `KbdGroup`:

```text
Kbd
KbdGroup
├── Kbd
└── Kbd
```

## Group

Use the `KbdGroup` component to group keyboard keys together.

### Example: kbd-group

```tsx
import { Kbd, KbdGroup } from "@workspace/ui/components/kbd";

export default function KbdGroupExample() {
  return (
    <div className="flex flex-col items-center gap-4">
      <p className="text-muted-foreground text-sm">
        Use{" "}
        <KbdGroup>
          <Kbd>Ctrl + B</Kbd>
          <Kbd>Ctrl + K</Kbd>
        </KbdGroup>{" "}
        to open the command palette
      </p>
    </div>
  );
}
```

## Button

Use the `Kbd` component inside a `Button` component to display a keyboard key inside a button.

### Example: kbd-button

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

export default function KbdButton() {
  return (
    <Button variant="outline">
      Accept{" "}
      <Kbd data-icon="inline-end" className="translate-x-0.5">
        ⏎
      </Kbd>
    </Button>
  );
}
```

## Tooltip

You can use the `Kbd` component inside a `Tooltip` component to display a tooltip with a keyboard key.

### Example: kbd-tooltip

```tsx
import { Button } from "@workspace/ui/components/button";
import { ButtonGroup } from "@workspace/ui/components/button-group";
import { Kbd, KbdGroup } from "@workspace/ui/components/kbd";
import {
  Tooltip,
  TooltipContent,
  TooltipTrigger,
} from "@workspace/ui/components/tooltip";

export default function KbdTooltip() {
  return (
    <div className="flex flex-wrap gap-4">
      <ButtonGroup>
        <Tooltip>
          <TooltipTrigger render={<Button variant="outline" />}>
            Save
          </TooltipTrigger>
          <TooltipContent>
            Save Changes <Kbd>S</Kbd>
          </TooltipContent>
        </Tooltip>
        <Tooltip>
          <TooltipTrigger render={<Button variant="outline" />}>
            Print
          </TooltipTrigger>
          <TooltipContent>
            Print Document{" "}
            <KbdGroup>
              <Kbd>Ctrl</Kbd>
              <Kbd>P</Kbd>
            </KbdGroup>
          </TooltipContent>
        </Tooltip>
      </ButtonGroup>
    </div>
  );
}
```

## Input Group

You can use the `Kbd` component inside a `InputGroupAddon` component to display a keyboard key inside an input group.

### Example: kbd-input-group

```tsx
import {
  InputGroup,
  InputGroupAddon,
  InputGroupInput,
} from "@workspace/ui/components/input-group";
import { Kbd } from "@workspace/ui/components/kbd";
import { SearchIcon } from "lucide-react";

export default function KbdInputGroup() {
  return (
    <div className="flex w-full max-w-xs flex-col gap-6">
      <InputGroup>
        <InputGroupInput placeholder="Search..." />
        <InputGroupAddon>
          <SearchIcon />
        </InputGroupAddon>
        <InputGroupAddon align="inline-end">
          <Kbd>⌘</Kbd>
          <Kbd>K</Kbd>
        </InputGroupAddon>
      </InputGroup>
    </div>
  );
}
```

## RTL

To enable RTL support in shadcn/ui, see the [RTL configuration guide](https://ui.shadcn.com/docs/rtl).

### Example: kbd-rtl

```tsx
"use client";

import { Kbd, KbdGroup } from "@workspace/ui/components/kbd";
import { type Translations, useTranslation } from "./support";

const translations: Translations = {
  en: {
    dir: "ltr",
    values: {},
  },
  ar: {
    dir: "rtl",
    values: {},
  },
  he: {
    dir: "rtl",
    values: {},
  },
};

export function KbdRtl() {
  const { dir } = useTranslation(translations, "ar");

  return (
    <div className="flex flex-col items-center gap-4" dir={dir}>
      <KbdGroup>
        <Kbd>⌘</Kbd>
        <Kbd>⇧</Kbd>
        <Kbd>⌥</Kbd>
        <Kbd>⌃</Kbd>
      </KbdGroup>
      <KbdGroup>
        <Kbd>Ctrl</Kbd>
        <span>+</span>
        <Kbd>B</Kbd>
      </KbdGroup>
    </div>
  );
}

export default KbdRtl;
```

## API Reference

### Kbd

Use the `Kbd` component to display a keyboard key.

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` | ``      |

4

### KbdGroup

Use the `KbdGroup` component to group `Kbd` components together.

| Prop        | Type     | Default |
| ----------- | -------- | ------- |
| `className` | `string` | ``      |

```tsx
<KbdGroup>
  <Kbd>Ctrl</Kbd>
  <Kbd>B</Kbd>
</KbdGroup>
```


---

# Label

Renders an accessible label associated with controls.

Page: https://sui.draco.dev/docs/components/label

### Example: label-demo

```tsx
import { Checkbox } from "@workspace/ui/components/checkbox";
import { Label } from "@workspace/ui/components/label";
import { useId as usePreviewId } from "react";

export default function LabelDemo() {
  const previewId = usePreviewId();

  return (
    <div className="flex gap-2">
      <Checkbox id={`${previewId}-terms`} />
      <Label htmlFor={`${previewId}-terms`}>Accept terms and conditions</Label>
    </div>
  );
}
```

  For form fields, use the [Field](/docs/components/field) component which
  includes built-in label, description, and error handling.

## Installation

```bash
bunx --bun shadcn@latest add @sui/label
```

Install with the shadcn CLI or use the shared `@workspace/ui` package. Follow the [installation guide](/docs/installation) to configure the registry, load styles, and choose import aliases.

## Usage

```tsx
import { Label } from "@workspace/ui/components/label"
```

```tsx
<Label htmlFor="email">Your email address</Label>
```

## Label in Field

For form fields, use the [Field](/docs/components/field) component which
includes built-in `FieldLabel`, `FieldDescription`, and `FieldError` components.

```tsx
<Field>
  <FieldLabel htmlFor="email">Your email address</FieldLabel>
  <Input id="email" />
</Field>
```

### Example: field-demo

```tsx
import { Button } from "@workspace/ui/components/button";
import { Checkbox } from "@workspace/ui/components/checkbox";
import {
  Field,
  FieldDescription,
  FieldGroup,
  FieldLabel,
  FieldLegend,
  FieldSeparator,
  FieldSet,
} from "@workspace/ui/components/field";
import { Input } from "@workspace/ui/components/input";
import {
  Select,
  SelectContent,
  SelectGroup,
  SelectItem,
  SelectTrigger,
  SelectValue,
} from "@workspace/ui/components/select";
import { Textarea } from "@workspace/ui/components/textarea";
import { useId as usePreviewId } from "react";

const months = [
  { label: "MM", value: null },
  { label: "01", value: "01" },
  { label: "02", value: "02" },
  { label: "03", value: "03" },
  { label: "04", value: "04" },
  { label: "05", value: "05" },
  { label: "06", value: "06" },
  { label: "07", value: "07" },
  { label: "08", value: "08" },
  { label: "09", value: "09" },
  { label: "10", value: "10" },
  { label: "11", value: "11" },
  { label: "12", value: "12" },
];

const years = [
  { label: "YYYY", value: null },
  { label: "2024", value: "2024" },
  { label: "2025", value: "2025" },
  { label: "2026", value: "2026" },
  { label: "2027", value: "2027" },
  { label: "2028", value: "2028" },
  { label: "2029", value: "2029" },
];

export default function FieldDemo() {
  const previewId = usePreviewId();

  return (
    <div className="w-full max-w-md">
      <form>
        <FieldGroup>
          <FieldSet>
            <FieldLegend>Payment Method</FieldLegend>
            <FieldDescription>
              All transactions are secure and encrypted
            </FieldDescription>
            <FieldGroup>
              <Field>
                <FieldLabel htmlFor={`${previewId}-checkout-7j9-card-name-43j`}>
                  Name on Card
                </FieldLabel>
                <Input
                  id={`${previewId}-checkout-7j9-card-name-43j`}
                  placeholder="Evil Rabbit"
                  required
                />
              </Field>
              <Field>
                <FieldLabel
                  htmlFor={`${previewId}-checkout-7j9-card-number-uw1`}
                >
                  Card Number
                </FieldLabel>
                <Input
                  id={`${previewId}-checkout-7j9-card-number-uw1`}
                  placeholder="1234 5678 9012 3456"
                  required
                />
                <FieldDescription>
                  Enter your 16-digit card number
                </FieldDescription>
              </Field>
              <div className="grid grid-cols-3 gap-4">
                <Field>
                  <FieldLabel htmlFor={`${previewId}-checkout-exp-month-ts6`}>
                    Month
                  </FieldLabel>
                  <Select items={months}>
                    <SelectTrigger id={`${previewId}-checkout-exp-month-ts6`}>
                      <SelectValue />
                    </SelectTrigger>
                    <SelectContent>
                      <SelectGroup>
                        {months.map((item) => (
                          <SelectItem key={item.value} value={item.value}>
                            {item.label}
                          </SelectItem>
                        ))}
                      </SelectGroup>
                    </SelectContent>
                  </Select>
                </Field>
                <Field>
                  <FieldLabel
                    htmlFor={`${previewId}-checkout-7j9-exp-year-f59`}
                  >
                    Year
                  </FieldLabel>
                  <Select items={years}>
                    <SelectTrigger
                      id={`${previewId}-checkout-7j9-exp-year-f59`}
                    >
                      <SelectValue />
                    </SelectTrigger>
                    <SelectContent>
                      <SelectGroup>
                        {years.map((item) => (
                          <SelectItem key={item.value} value={item.value}>
                            {item.label}
                          </SelectItem>
                        ))}
                      </SelectGroup>
                    </SelectContent>
                  </Select>
                </Field>
                <Field>
                  <FieldLabel htmlFor={`${previewId}-checkout-7j9-cvv`}>
                    CVV
                  </FieldLabel>
                  <Input
                    id={`${previewId}-checkout-7j9-cvv`}
                    placeholder="123"
                    required
                  />
                </Field>
              </div>
            </FieldGroup>
          </FieldSet>
          <FieldSeparator />
          <FieldSet>
            <FieldLegend>Billing Address</FieldLegend>
            <FieldDescription>
              The billing address associated with your payment method
            </FieldDescription>
            <FieldGroup>
              <Field orientation="horizontal">
                <Checkbox
                  id={`${previewId}-checkout-7j9-same-as-shipping-wgm`}
                  defaultChecked
                />
                <FieldLabel
                  htmlFor={`${previewId}-checkout-7j9-same-as-shipping-wgm`}
                  className="font-normal"
                >
                  Same as shipping address
                </FieldLabel>
              </Field>
            </FieldGroup>
          </FieldSet>
          <FieldSet>
            <FieldGroup>
              <Field>
                <FieldLabel
                  htmlFor={`${previewId}-checkout-7j9-optional-comments`}
                >
                  Comments
                </FieldLabel>
                <Textarea
                  id={`${previewId}-checkout-7j9-optional-comments`}
                  placeholder="Add any additional comments"
                  className="resize-none"
                />
              </Field>
            </FieldGroup>
          </FieldSet>
          <Field orientation="horizontal">
            <Button type="submit">Submit</Button>
            <Button variant="outline" type="button">
              Cancel
            </Button>
          </Field>
        </FieldGroup>
      </form>
    </div>
  );
}
```

## RTL

To enable RTL support in shadcn/ui, see the [RTL configuration guide](https://ui.shadcn.com/docs/rtl).

### Example: label-rtl

```tsx
"use client";

import { Checkbox } from "@workspace/ui/components/checkbox";
import { Label } from "@workspace/ui/components/label";
import { useId as usePreviewId } from "react";
import { type Translations, useTranslation } from "./support";

const translations: Translations = {
  en: {
    dir: "ltr",
    values: {
      label: "Accept terms and conditions",
    },
  },
  ar: {
    dir: "rtl",
    values: {
      label: "قبول الشروط والأحكام",
    },
  },
  he: {
    dir: "rtl",
    values: {
      label: "קבל תנאים והגבלות",
    },
  },
};

export function LabelRtl() {
  const previewId = usePreviewId();

  const { dir, t } = useTranslation(translations, "ar");

  return (
    <div className="flex gap-2" dir={dir}>
      <Checkbox id={`${previewId}-terms-rtl`} dir={dir} />
      <Label htmlFor={`${previewId}-terms-rtl`} dir={dir}>
        {t.label}
      </Label>
    </div>
  );
}

export default LabelRtl;
```

## API Reference

See the [Base UI Label](https://base-ui.com/react/components/label#api-reference) documentation for more information.

- [Documentation](https://base-ui.com/react/components/label)
- [API reference](https://base-ui.com/react/components/label#api-reference)


---

# Loader

Eighteen loading animations with accessible labels, adjustable speed, and reduced motion support.

Page: https://sui.draco.dev/docs/components/loader

### Example: loader-demo

```tsx
import { Loader, loaderVariantNames } from "@workspace/ui/components/loader";
import type { ExampleProps } from "../types";
export default function Example({ locale }: ExampleProps) {
  const zh = locale === "zh-CN";
  return (
    <div className="grid w-full grid-cols-2 gap-3 sm:grid-cols-3 xl:grid-cols-6">
      {loaderVariantNames.map((variant) => (
        <div
          key={variant}
          className="flex min-h-24 flex-col items-center justify-center gap-4 rounded-xl border bg-background p-3"
        >
          <Loader
            variant={variant}
            size={32}
            label={zh ? "正在加载" : "Loading"}
          />
          <span className="text-center font-mono text-muted-foreground text-sm">
            {variant}
          </span>
        </div>
      ))}
    </div>
  );
}
```

## Installation

```bash
bunx --bun shadcn@latest add @sui/loader
```

Install with the shadcn CLI or use the shared `@workspace/ui` package. Follow the [installation guide](/docs/installation) to configure the registry, load styles, and choose import aliases.

```tsx
import { Loader } from "@workspace/ui/components/loader";
```

## Usage

```tsx
<Loader variant="dots" label="Loading messages" />
```

`Loader` provides eighteen distinct loading animations, all using the current text color. The root exposes `role="status"` and a loading label while decorative visuals remain hidden from assistive technology. Reduced motion changes stop CSS animations and character timers immediately, leaving a static indicator. Timers and media listeners are cleaned up on unmount. Server rendering uses static character frames to avoid hydration differences.

## Variants

| Variant | Animation |
| --- | --- |
| `spinner` | Rotating arc over a circular track |
| `dash-ring` | Stretching arc that travels smoothly around a rotating ring |
| `dots` | Three staggered bouncing dots |
| `bars` | Four staggered scaling bars |
| `dot-matrix` | A rippling 3 × 3 dot matrix |
| `dither` | A patterned 4 × 4 blinking square matrix |
| `ascii` | Rotating character frames |
| `ascii-line` | Rotating line character frames |
| `ascii-braille` | Braille ring character frames |
| `ascii-blocks` | Rising and falling block characters |
| `ascii-bounce` | Bouncing dot character frames |
| `morph` | Rotating circle, square, triangle, and hexagon morphs |
| `comet` | Rotating comet with a fading trail |
| `scramble` | Scrambled characters resolving to LOADING |
| `metaballs` | Two merging circular blobs |
| `newton` | Alternating end swings of a Newton cradle |
| `helix` | Opposing strands of oscillating dots |
| `percent` | Decorative looping percentage and short bar |

`percent` is a looping loading motif, not measured task progress. Use [Progress](/docs/components/progress) for actual progress.

## Sizes and colors

Use `sm` (16px), `default` (20px), `lg` (28px), or a numeric pixel size. Numeric sizes are clamped to 8–4096px; non-finite values use 20px. Set `className="text-primary"` to use the active theme color.

### Example: loader-size

```tsx
import { Loader } from "@workspace/ui/components/loader";
import type { ExampleProps } from "../types";
export default function Example({ locale }: ExampleProps) {
  const zh = locale === "zh-CN";
  return (
    <div className="grid gap-6 text-primary">
      {(["spinner", "dash-ring"] as const).map((variant) => (
        <div key={variant} className="grid gap-3">
          <span className="font-mono text-muted-foreground text-sm">
            {variant}
          </span>
          <div className="flex items-center gap-6">
            {(["sm", "default", "lg", 40] as const).map((size) => (
              <div key={size} className="grid justify-items-center gap-3">
                <Loader
                  variant={variant}
                  size={size}
                  label={zh ? "正在加载" : "Loading"}
                />
                <span className="font-mono text-muted-foreground text-sm">
                  {typeof size === "number" ? `${size}px` : size}
                </span>
              </div>
            ))}
          </div>
        </div>
      ))}
      <div className="flex items-center justify-center gap-10">
        {[0.6, 2].map((speed) => (
          <div key={speed} className="grid justify-items-center gap-3">
            <Loader
              variant="dots"
              size={28}
              speed={speed}
              label={zh ? "正在加载" : "Loading"}
            />
            <span className="text-muted-foreground text-sm">{speed}s</span>
          </div>
        ))}
      </div>
    </div>
  );
}
```

## Animation speed

`speed` controls the base cycle in seconds and defaults to `1`. Smaller values are faster; values are clamped to `0.1`–`86400` and non-finite values fall back to `1`. Character timers have a minimum interval of 10 milliseconds. Complex animations use fixed multiples of the base cycle.

```tsx
<Loader variant="dots" speed={0.6} label="Loading" />
<Loader variant="metaballs" speed={2} label="Loading" />
```

## Button loading state

Render the loader only while work is in progress and disable repeated submissions. This example simulates a local save and cleans up its timer on unmount.

### Example: loader-button

```tsx
import { Button } from "@workspace/ui/components/button";
import { Loader } from "@workspace/ui/components/loader";
import { useEffect, useRef, useState } from "react";
import type { ExampleProps } from "../types";
export default function Example({ locale }: ExampleProps) {
  const zh = locale === "zh-CN";
  const stateLabels = zh
    ? {
        saving: "正在保存…",
        save: "保存设置",
        saved: "预览设置已保存",
      }
    : {
        saving: "Saving…",
        save: "Save settings",
        saved: "Preview settings saved.",
      };
  const [loading, setLoading] = useState(false);
  const [saved, setSaved] = useState(false);
  const timer = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
  useEffect(
    () => () => {
      if (timer.current !== undefined) clearTimeout(timer.current);
    },
    [],
  );
  return (
    <div className="grid justify-items-center gap-3">
      <Button
        disabled={loading}
        onClick={() => {
          setLoading(true);
          setSaved(false);
          timer.current = setTimeout(() => {
            setLoading(false);
            setSaved(true);
          }, 1200);
        }}
      >
        {loading ? (
          <Loader
            size="sm"
            variant="spinner"
            label={zh ? "正在保存" : "Saving"}
          />
        ) : null}
        {loading ? stateLabels.saving : stateLabels.save}
      </Button>
      <span role="status" className="min-h-5 text-muted-foreground text-sm">
        {saved ? stateLabels.saved : ""}
      </span>
    </div>
  );
}
```

## API

| Prop | Type | Default |
| --- | --- | --- |
| `variant` | `LoaderVariant`, see all eighteen variants above | `"spinner"` |
| `size` | `"sm" \| "default" \| "lg" \| number` | `"default"` |
| `speed` | `number`, base cycle in seconds | `1` |
| `label` | `string` | `"Loading"` |
| `render` | React element or render function | `span` |

Standard `span` props, refs, styles, and `className` are supported. The root exposes `data-slot="loader"` and `data-variant`. Labels describe actual activity; the percentage motif is decorative and does not expose progress values to assistive technology. See [Base UI composition](https://base-ui.com/react/handbook/composition) for `render` and ref behavior.


---

# Locale Toggle

A controlled language button or selector without routing or persistence assumptions.

Page: https://sui.draco.dev/docs/components/locale-toggle

### Example: locale-toggle-demo

```tsx
"use client";
import { LocaleToggle } from "@workspace/ui/components/locale-toggle";
import { useState } from "react";
import type { ExampleProps } from "../types";

const options = [
  { value: "en-US", label: "English" },
  { value: "zh-CN", label: "简体中文" },
];
export default function Example({ locale }: ExampleProps) {
  const [value, setValue] = useState<string>(locale ?? "en-US");
  const chinese = locale === "zh-CN";
  return (
    <div className="grid w-full justify-items-start gap-4">
      <LocaleToggle
        value={value}
        onValueChange={setValue}
        options={options}
        label={chinese ? "示例语言" : "Example language"}
      />
      <output className="rounded-xl bg-muted p-4 text-sm" aria-live="polite">
        {value === "zh-CN" ? "你好，欢迎使用 SUI" : "Hello, welcome to SUI."}
      </output>
      <p className="text-muted-foreground text-sm">
        {chinese
          ? "此示例只修改本地状态，不改变文档语言或保存偏好"
          : "This example changes only local state, without changing the documentation language or saving preferences."}
      </p>
    </div>
  );
}
```

## Installation

```bash
bunx --bun shadcn@latest add @sui/locale-toggle
```

Install with the shadcn CLI or use the shared `@workspace/ui` package. Follow the [installation guide](/docs/installation) to configure the registry, load styles, and choose import aliases.

## Usage

```tsx
import { LocaleToggle } from "@workspace/ui/components/locale-toggle";
import { useState } from "react";

const options = [
  { value: "en-US", label: "English" },
  { value: "zh-CN", label: "简体中文" },
];

export function Language() {
  const [value, setValue] = useState("en-US");
  return <LocaleToggle value={value} onValueChange={setValue} options={options} />;
}
```

## Toggle and select modes

In `auto` mode, up to two distinct options use a button that cycles to the next language; more options use the shared Select. Set `mode="toggle"` or `mode="select"` to choose explicitly. A button with fewer than two distinct options is disabled. Duplicate option values are removed.

### Example: locale-toggle-select

```tsx
"use client";
import { LocaleToggle } from "@workspace/ui/components/locale-toggle";
import { useState } from "react";
import type { ExampleProps } from "../types";

const options = [
  { value: "en-US", label: "English" },
  { value: "zh-CN", label: "简体中文" },
  { value: "ja-JP", label: "日本語" },
];
export default function Example({ locale }: ExampleProps) {
  const [value, setValue] = useState<string>(locale ?? "en-US");
  const chinese = locale === "zh-CN";
  return (
    <div className="flex flex-wrap items-center gap-4">
      <LocaleToggle
        value={value}
        onValueChange={setValue}
        options={options}
        mode="select"
        label={chinese ? "选择示例语言" : "Choose example language"}
      />
      <output className="text-muted-foreground text-sm" aria-live="polite">
        {value}
      </output>
      <LocaleToggle
        value={value}
        onValueChange={setValue}
        options={options}
        mode="select"
        disabled
        label={chinese ? "禁用的语言选择器" : "Disabled language selector"}
      />
    </div>
  );
}
```

## Integrating routing and content

`onValueChange` reports a locale value after the indicator reaches its new shape. Your application updates content, router state, and any persisted preference. The control locks immediately and keeps `aria-busy` during the morph and any promise returned by the callback. Repeated clicks share the pending request. Reduced motion or a hidden page completes the shape immediately. Rejection releases the pending state and restores the controlled locale indicator; the application callback handles error reporting. Unmounting before the animation ends cancels the callback. The selected locale remains controlled by `value`. No router, translation provider, or storage API is required by the component. The examples keep the selection local and do not navigate the documentation.

For this documentation’s language routes, switching preserves the page path, query, and hash. That behavior belongs to the application’s route integration, not to the shared toggle component.

## Option indicators and labels

Every option has a full locale `value` and readable `label`. The ghost button has a tooltip and a 16px SVG indicator with 2px strokes. ZH and EN use compact stroke lettering with a snappy spring path morph. Common language prefixes have built-in indicators; reduced motion swaps the shape directly. `indicatorPath` overrides its SVG path, while unknown prefixes use the generic language icon. Translate the control `label` and use readable option names. Native button props include `disabled`, `ref`, and `render`.

## API reference

| Prop | Type | Default / behavior |
| --- | --- | --- |
| `value` | `string` | Required selected locale. |
| `onValueChange` | `(value: string) => void \| Promise<void>` | Required selection callback. |
| `options` | `readonly LocaleOption[]` | Required options: `value`, `label`, optional `indicatorPath`. |
| `mode` | `"auto" \| "toggle" \| "select"` | `"auto"`. |
| `label` | `string` | `"Change language"`. |
| `glass` | `boolean` | `false`. |

The module exports `LocaleToggleProps` and `LocaleOption`. The multi-language selector uses the [Base UI Select API](https://base-ui.com/react/components/select).


---

# LongText

Truncated text with a full-text disclosure only when the content overflows.

Page: https://sui.draco.dev/docs/components/long-text

### Example: long-text-demo

```tsx
import { Input } from "@workspace/ui/components/input";
import { LongText } from "@workspace/ui/components/long-text";
import { useState } from "react";
import type { ExampleProps } from "../types";

export default function LongTextDemo({ locale }: ExampleProps) {
  const zh = locale === "zh-CN";
  const [text, setText] = useState(
    "production-api-gateway.asia-east-1.example.com",
  );
  return (
    <div className="flex w-full max-w-sm flex-col gap-4">
      <Input
        aria-label={zh ? "编辑文本" : "Edit text"}
        value={text}
        onChange={(event) => setText(event.target.value)}
      />
      <div className="flex items-center justify-between gap-4 rounded-2xl border p-4">
        <span className="text-muted-foreground text-sm">
          {zh ? "域名" : "Domain"}
        </span>
        <LongText
          className="w-44"
          label={zh ? "显示完整域名" : "Show full domain"}
        >
          {text}
        </LongText>
      </div>
      <p className="text-muted-foreground text-sm">
        {zh
          ? "悬停或键盘聚焦查看全文，触屏点击展开。短文本不会启用浮层。"
          : "Hover or focus to see the full text; tap on touch devices. Short text needs no overlay."}
      </p>
    </div>
  );
}
```

## Installation

```bash
bunx --bun shadcn@latest add @sui/long-text
```

Install with the shadcn CLI or use the shared `@workspace/ui` package. Follow the [installation guide](/docs/installation) to configure the registry, load styles, and choose import aliases.

```tsx
import { LongText } from "@workspace/ui/components/long-text"
```

## Usage

```tsx
<LongText className="max-w-48" label="Show full resource name">
  production-api-gateway.asia-east-1.example.com
</LongText>
```

Give the component a constrained width. Overflowing text becomes a keyboard-focusable trigger. Pointer devices show SUI Tooltip on hover or focus; coarse pointers show SUI Popover on tap. Short text remains plain text. Measurements update when content, layout, fonts, or pointer capabilities change.

## Table cells

Use a fixed table layout or constrain the cell width so ellipsis has a boundary.

### Example: long-text-table

```tsx
import { LongText } from "@workspace/ui/components/long-text";
import {
  Table,
  TableBody,
  TableCell,
  TableHead,
  TableHeader,
  TableRow,
} from "@workspace/ui/components/table";
import type { ExampleProps } from "../types";

export default function LongTextTable({ locale }: ExampleProps) {
  const zh = locale === "zh-CN";
  return (
    <Table className="table-fixed">
      <TableHeader>
        <TableRow>
          <TableHead className="w-20">ID</TableHead>
          <TableHead>{zh ? "名称" : "Name"}</TableHead>
        </TableRow>
      </TableHeader>
      <TableBody>
        {["sui", "production-api-gateway.asia-east-1.example.com"].map(
          (name, index) => (
            <TableRow key={name}>
              <TableCell>{index + 1}</TableCell>
              <TableCell>
                <LongText label={zh ? "显示完整名称" : "Show full name"}>
                  {name}
                </LongText>
              </TableCell>
            </TableRow>
          ),
        )}
      </TableBody>
    </Table>
  );
}
```

## API

| Prop | Description |
| --- | --- |
| `children` | Displayed content, repeated in the disclosure. Use text or noninteractive inline content. |
| `className` | Width and layout classes on the outer container. |
| `contentClassName` | Layout classes on the full-text surface. |
| `label` | Optional accessible trigger name. Defaults to the displayed text. |

The pattern is inspired by [shadcn-admin LongText](https://github.com/satnaing/shadcn-admin/blob/main/src/components/long-text.tsx), with SUI Base UI composition and resize-aware overflow detection.


---

# Markdown Viewer

Markdown rendering with tables, task lists, alerts, highlighted code, and sanitized HTML.

Page: https://sui.draco.dev/docs/components/markdown-viewer

### Example: markdown-viewer-demo

````tsx
"use client";
import { MarkdownViewer } from "@workspace/ui/components/markdown-viewer";
import type { ExampleProps } from "../types";
export default function Example({ locale }: ExampleProps) {
  const chinese = locale === "zh-CN";
  const content = chinese
    ? '# 发布说明\n\n支持 **Markdown**、表格和任务列表。\n\n> [!TIP]\n> 使用语义颜色构建一致的界面。\n\n| 组件 | 状态 |\n| --- | --- |\n| Editor | 就绪 |\n| Markdown Viewer | 就绪 |\n\n- [x] 双语文档\n- [ ] 发布\n\n```tsx\nconst theme = "bamboo";\n```'
    : '# Release notes\n\nSupports **Markdown**, tables, and task lists.\n\n> [!TIP]\n> Use semantic colors to keep interfaces consistent.\n\n| Component | Status |\n| --- | --- |\n| Editor | Ready |\n| Markdown Viewer | Ready |\n\n- [x] Bilingual docs\n- [ ] Release\n\n```tsx\nconst theme = "bamboo";\n```';
  return (
    <MarkdownViewer
      content={content}
      className="w-full"
      labels={
        chinese
          ? {
              empty: "没有 Markdown 内容",
              note: "备注",
              tip: "提示",
              important: "重要",
              warning: "警告",
              caution: "注意",
              code: {
                copy: "复制代码",
                copied: "已复制",
                copyFailed: "复制失败",
                loading: "正在加载",
                error: "无法高亮代码",
                empty: "没有代码",
                expand: "展开",
                collapse: "收起",
                writing: "正在生成",
                ready: "就绪",
              },
            }
          : undefined
      }
    />
  );
}
````

## Installation

```bash
bunx --bun shadcn@latest add @sui/markdown-viewer
```

Install with the shadcn CLI or use the shared `@workspace/ui` package. Follow the [installation guide](/docs/installation) to configure the registry, load styles, and choose import aliases.

## Usage

```tsx
import { MarkdownViewer } from "@workspace/ui/components/markdown-viewer";

<MarkdownViewer content="# Release notes\n\nA **Markdown** document." />;
```

## Supported formatting

Supports headings, links, tables, task lists, strikethrough, line breaks, and fenced code. Fenced code, including blocks without a language, and indented code use [Code Viewer](/docs/components/code-viewer). Blocks without a language render as plain text and retain copying and line breaks. Inline code remains inline. GitHub-style `[!NOTE]`, `[!TIP]`, `[!IMPORTANT]`, `[!WARNING]`, and `[!CAUTION]` blocks have semantic visual treatments.

Heading anchors are scoped to each viewer instance. A Contents, Table of Contents, or TOC heading can generate a table of contents. Math syntax is parsed, but this component does not load a dedicated mathematical typesetting engine.

## HTML and editable content

Embedded HTML is parsed and sanitized before rendering. Common safe formatting, including `details` and `summary`, is retained; scripts and event-handler attributes are removed. The example lets you edit Markdown containing a disclosure and a script that is not executed. Unlike [Html Viewer](/docs/components/html-viewer), this component does not execute HTML scripts.

### Example: markdown-viewer-sanitized

```tsx
"use client";
import { Label } from "@workspace/ui/components/label";
import { MarkdownViewer } from "@workspace/ui/components/markdown-viewer";
import { Textarea } from "@workspace/ui/components/textarea";
import { useId, useState } from "react";
import type { ExampleProps } from "../types";
export default function Example({ locale }: ExampleProps) {
  const chinese = locale === "zh-CN";
  const id = useId();
  const [content, setContent] = useState(
    chinese
      ? '## 可编辑的内容\n\n<details><summary>展开详情</summary>允许的 HTML 会保留。</details>\n\n<script>alert("removed")</script>'
      : '## Editable content\n\n<details><summary>Show details</summary>Allowed HTML is preserved.</details>\n\n<script>alert("removed")</script>',
  );
  return (
    <div className="grid w-full gap-4">
      <Label htmlFor={id}>
        {chinese ? "Markdown 源码" : "Markdown source"}
      </Label>
      <Textarea
        id={id}
        rows={5}
        value={content}
        onChange={(event) => setContent(event.target.value)}
      />
      <MarkdownViewer
        content={content}
        labels={
          chinese
            ? {
                empty: "没有 Markdown 内容",
                note: "备注",
                tip: "提示",
                important: "重要",
                warning: "警告",
                caution: "注意",
                code: {
                  copy: "复制代码",
                  copied: "已复制",
                  copyFailed: "复制失败",
                  loading: "正在加载",
                  error: "无法高亮代码",
                  empty: "没有代码",
                  expand: "展开",
                  collapse: "收起",
                  writing: "正在生成",
                  ready: "就绪",
                },
              }
            : undefined
        }
      />
    </div>
  );
}
```

## Theme and localization

The content follows the surrounding theme unless `theme` is supplied. Use `className` for container layout. `labels.empty` customizes the empty state, while `note`, `tip`, `important`, `warning`, and `caution` translate alert headings. `labels.code` accepts [CodeViewer labels](/docs/components/code-viewer#api-reference) for embedded code blocks, including copy, loading, and failure feedback. Markdown content itself is provided by your application and is not translated automatically.

## API reference

| Prop | Type | Default / behavior |
| --- | --- | --- |
| `content` | `string` | Required Markdown source. |
| `theme` | `"light" \| "dark"` | Follows surrounding theme. |
| `className` | `string` | Container layout classes. |
| `labels` | `Partial<MarkdownViewerLabels>` | Empty and alert labels; `code` translates embedded CodeViewer feedback. Defaults to English. |
| `glass` | `boolean` | `false`. |

The module exports `MarkdownViewerProps` and `MarkdownViewerLabels`. Rendering uses [react-markdown](https://github.com/remarkjs/react-markdown).


---

# Marker

Displays an inline status, system note, bordered row, or labeled separator in a conversation.

Page: https://sui.draco.dev/docs/components/marker

### Example: marker-demo

```tsx
import { Loader } from "@workspace/ui/components/loader";
import {
  Marker,
  MarkerContent,
  MarkerIcon,
} from "@workspace/ui/components/marker";
import { GitBranchIcon, SearchIcon } from "lucide-react";

export function MarkerDemo() {
  return (
    <div className="flex w-full max-w-sm flex-col gap-8 py-12">
      <Marker>
        <MarkerIcon>
          <GitBranchIcon />
        </MarkerIcon>
        <MarkerContent>Switched to a new branch</MarkerContent>
      </Marker>
      <Marker role="status">
        <MarkerIcon>
          <Loader size="sm" />
        </MarkerIcon>
        <MarkerContent className="shimmer">Thinking...</MarkerContent>
      </Marker>
      <Marker variant="separator">
        <MarkerContent>Conversation compacted</MarkerContent>
      </Marker>
      <Marker>
        <MarkerIcon>
          <SearchIcon />
        </MarkerIcon>
        <MarkerContent>Explored 4 files</MarkerContent>
      </Marker>
    </div>
  );
}

export default MarkerDemo;
```

The `Marker` component displays inline conversation markers such as status updates, system notes, bordered rows, and labeled separators. Compose it with [`Message`](/docs/components/message) in a conversation thread.

## Installation

```bash
bunx --bun shadcn@latest add @sui/marker
```

Install with the shadcn CLI or use the shared `@workspace/ui` package. Follow the [installation guide](/docs/installation) to configure the registry, load styles, and choose import aliases.

## Usage

```tsx showLineNumbers
import { Marker, MarkerContent, MarkerIcon } from "@workspace/ui/components/marker"
```

```tsx showLineNumbers
<Marker>
  <MarkerIcon>
    <CheckIcon />
  </MarkerIcon>
  <MarkerContent>Explored 4 files</MarkerContent>
</Marker>
```

## Composition

Use the following composition to build a marker:

```text
Marker
├── MarkerIcon
└── MarkerContent
```

## Features

- Inline marker, bordered row, and labeled separator variants
- Decorative icon slot that is hidden from assistive tech
- Polymorphic root via `render` for link and button markers
- Pairs with the [`shimmer`](https://ui.shadcn.com/docs/utils/shimmer) utility for streaming status text
- Customizable styling through the `className` prop on every part

## Variants

Use `variant` to switch between an inline marker, bordered row, and labeled separator.

### Example: marker-variants

```tsx
import { Marker, MarkerContent } from "@workspace/ui/components/marker";

export function MarkerVariantsDemo() {
  return (
    <div className="flex w-full max-w-sm flex-col gap-8 py-12">
      <Marker>
        <MarkerContent>A default marker for inline notes.</MarkerContent>
      </Marker>
      <Marker variant="separator">
        <MarkerContent>A separator marker</MarkerContent>
      </Marker>
      <Marker variant="border">
        <MarkerContent>A border marker for row boundaries.</MarkerContent>
      </Marker>
    </div>
  );
}

export default MarkerVariantsDemo;
```

| Variant     | Description                                          |
| ----------- | ---------------------------------------------------- |
| `default`   | An inline marker for status, notes, and actions.     |
| `border`    | A default marker with a bottom border under the row. |
| `separator` | A centered label with divider lines on each side.    |

## Status

Set `role="status"` and include a [`Loader`](/docs/components/loader) for streaming or in-progress markers so updates are announced.

### Example: marker-status

```tsx
import { Loader } from "@workspace/ui/components/loader";
import {
  Marker,
  MarkerContent,
  MarkerIcon,
} from "@workspace/ui/components/marker";

export function MarkerStatusDemo() {
  return (
    <div className="flex w-full max-w-sm flex-col gap-8 py-12">
      <Marker role="status">
        <MarkerIcon>
          <Loader size="sm" />
        </MarkerIcon>
        <MarkerContent>Compacting conversation</MarkerContent>
      </Marker>
      <Marker variant="separator" role="status">
        <MarkerIcon>
          <Loader size="sm" />
        </MarkerIcon>
        <MarkerContent>Running tests</MarkerContent>
      </Marker>
    </div>
  );
}

export default MarkerStatusDemo;
```

## Shimmer

Add the [`shimmer`](https://ui.shadcn.com/docs/utils/shimmer) utility class to `MarkerContent` for an animated streaming-text effect. The utility ships with the `shadcn` package — see the shimmer docs for installation.

### Example: marker-shimmer

```tsx
import { Marker, MarkerContent } from "@workspace/ui/components/marker";

export function MarkerShimmerDemo() {
  return (
    <div className="flex w-full max-w-sm flex-col gap-8 py-12">
      <Marker role="status">
        <MarkerContent className="shimmer">Thinking...</MarkerContent>
      </Marker>
      <Marker variant="separator" role="status">
        <MarkerContent className="shimmer">Reading 4 files</MarkerContent>
      </Marker>
    </div>
  );
}

export default MarkerShimmerDemo;
```

## Separator

Use the `separator` variant for labeled dividers, such as dates or section breaks, in a conversation.

### Example: marker-separator

```tsx
import { Marker, MarkerContent } from "@workspace/ui/components/marker";

export function MarkerSeparatorDemo() {
  return (
    <div className="flex w-full max-w-sm flex-col gap-8 py-12">
      <Marker variant="separator">
        <MarkerContent>Today</MarkerContent>
      </Marker>
      <Marker variant="separator">
        <MarkerContent>Worked for 42s</MarkerContent>
      </Marker>
      <Marker variant="separator">
        <MarkerContent>Conversation compacted</MarkerContent>
      </Marker>
    </div>
  );
}

export default MarkerSeparatorDemo;
```

## Border

Use the `border` variant for status rows that should keep the default marker alignment while separating the next row.

### Example: marker-border

```tsx
import {
  Marker,
  MarkerContent,
  MarkerIcon,
} from "@workspace/ui/components/marker";
import { FileTextIcon, GitBranchIcon, SearchIcon } from "lucide-react";

export function MarkerBorderDemo() {
  return (
    <div className="flex w-full max-w-sm flex-col gap-3 py-12">
      <Marker variant="border">
        <MarkerIcon>
          <GitBranchIcon />
        </MarkerIcon>
        <MarkerContent>Switched to release-candidate</MarkerContent>
      </Marker>
      <Marker variant="border">
        <MarkerIcon>
          <SearchIcon />
        </MarkerIcon>
        <MarkerContent>Reviewed 8 related files</MarkerContent>
      </Marker>
      <Marker variant="border">
        <MarkerIcon>
          <FileTextIcon />
        </MarkerIcon>
        <MarkerContent>Opened implementation notes</MarkerContent>
      </Marker>
    </div>
  );
}

export default MarkerBorderDemo;
```

## With Icon

Use `MarkerIcon` to render an icon alongside the content. Use `flex-col` to stack the icon above the content.

### Example: marker-icon

```tsx
import {
  Marker,
  MarkerContent,
  MarkerIcon,
} from "@workspace/ui/components/marker";
import { BookOpenCheck, GitBranchIcon, SearchIcon } from "lucide-react";

export function MarkerIconDemo() {
  return (
    <div className="flex w-full max-w-sm flex-col gap-12 py-12">
      <Marker>
        <MarkerIcon>
          <GitBranchIcon />
        </MarkerIcon>
        <MarkerContent>Switched to a new branch</MarkerContent>
      </Marker>
      <Marker variant="separator">
        <MarkerIcon>
          <SearchIcon />
        </MarkerIcon>
        <MarkerContent>Explored 4 files</MarkerContent>
      </Marker>
      <Marker className="flex-col">
        <MarkerIcon>
          <BookOpenCheck />
        </MarkerIcon>
        <MarkerContent>Syncing completed</MarkerContent>
      </Marker>
    </div>
  );
}

export default MarkerIconDemo;
```

## Links and Buttons

Turn a marker into a link or button with the `render` prop on `Marker`.

### Example: marker-link-button

```tsx
"use client";

import {
  Marker,
  MarkerContent,
  MarkerIcon,
} from "@workspace/ui/components/marker";
import { toast } from "@workspace/ui/components/toast";
import { GitBranchIcon, RotateCcwIcon } from "lucide-react";

export function MarkerLinkButtonDemo() {
  return (
    <div className="flex w-full max-w-sm flex-col gap-8 py-12">
      <Marker render={<a href="#links-and-buttons" />}>
        <MarkerIcon>
          <GitBranchIcon />
        </MarkerIcon>
        <MarkerContent>View the pull request</MarkerContent>
      </Marker>
      <Marker
        render={
          <button
            type="button"
            className="transition-colors hover:text-foreground"
            onClick={() =>
              toast.add({ title: "You clicked the revert button" })
            }
          />
        }
      >
        <MarkerIcon>
          <RotateCcwIcon />
        </MarkerIcon>
        <MarkerContent>Revert this change</MarkerContent>
      </Marker>
    </div>
  );
}

export default MarkerLinkButtonDemo;
```

```tsx showLineNumbers
import { Marker, MarkerContent } from "@workspace/ui/components/marker"

export function MarkerLinkDemo() {
  return (
    <Marker render={<a href="#" />}>
      <MarkerContent>View the pull request</MarkerContent>
    </Marker>
  )
}
```

## Accessibility

`Marker` is presentational by default. The correct semantics depend on how you use it, so choose the role based on intent rather than relying on a single default.

### Status and Progress

For streaming or progress markers such as "Thinking..." or a running tool, set `role="status"` so assistive tech announces the update as it appears. `Marker` forwards `role` to the underlying element.

```tsx showLineNumbers
<Marker role="status">
  <MarkerIcon>
    <Loader size="sm" />
  </MarkerIcon>
  <MarkerContent>Compacting conversation</MarkerContent>
</Marker>
```

### Labeled Separators

A separator that carries text, such as a date or a section label, needs no role. The divider lines are decorative CSS pseudo-elements, and the text is announced as ordinary content.

```tsx showLineNumbers
<Marker variant="separator">
  <MarkerContent>Today</MarkerContent>
</Marker>
```

  **Note:** Do not add `role="separator"` to a labeled divider. A separator
  takes its accessible name from `aria-label`, not from its text, and its
  contents are treated as presentational, so the visible label would not be
  announced. Reserve `role="separator"` for a divider with no meaningful text.

### Bordered Markers

A bordered marker keeps the same semantics as the default marker. The bottom border is decorative, so choose `role="status"`, `render`, or no role based on the marker's purpose.

```tsx showLineNumbers
<Marker variant="border">
  <MarkerIcon>
    <FileTextIcon />
  </MarkerIcon>
  <MarkerContent>Opened implementation notes</MarkerContent>
</Marker>
```

### Decorative Icons

`MarkerIcon` is decorative and hidden from assistive tech with `aria-hidden`, so the adjacent `MarkerContent` carries the meaning. For an icon-only marker, provide an `aria-label` or visible text so it is not announced as empty.

```tsx showLineNumbers
<Marker aria-label="Synced">
  <MarkerIcon>
    <CheckIcon />
  </MarkerIcon>
</Marker>
```

### Interactive Markers

When a marker links or triggers an action, render it as a real `<button>` or `<a>` with the `render` prop so it is focusable and exposes the correct role. The accessible name comes from the marker text.

```tsx showLineNumbers
<Marker render={<a href="/files" />}>
  <MarkerIcon>
    <FileTextIcon />
  </MarkerIcon>
  <MarkerContent>Explored 4 files</MarkerContent>
</Marker>
```

## API Reference

### Marker

The root marker element. The file also exports `markerVariants` for composing the marker styles into custom components.

| Prop        | Type                                   | Default     | Description                                      |
| ----------- | -------------------------------------- | ----------- | ------------------------------------------------ |
| `variant`   | `"default" \| "border" \| "separator"` | `"default"` | The marker layout.                               |
| `render`    | `ReactElement \| function`             | -           | Render as a different element, such as a link.   |
| `className` | `string`                               | -           | Additional classes to apply to the root element. |

### MarkerIcon

A decorative icon slot. Hidden from assistive tech with `aria-hidden`.

| Prop        | Type     | Default | Description                                   |
| ----------- | -------- | ------- | --------------------------------------------- |
| `className` | `string` | -       | Additional classes to apply to the icon slot. |

### MarkerContent

The marker text content.

| Prop        | Type     | Default | Description                                      |
| ----------- | -------- | ------- | ------------------------------------------------ |
| `className` | `string` | -       | Additional classes to apply to the content slot. |


---

# Menubar

A visually persistent menu common in desktop applications that provides quick access to a consistent set of commands.

Page: https://sui.draco.dev/docs/components/menubar

### Example: menubar-demo

```tsx
import {
  Menubar,
  MenubarCheckboxItem,
  MenubarContent,
  MenubarGroup,
  MenubarItem,
  MenubarMenu,
  MenubarRadioGroup,
  MenubarRadioItem,
  MenubarSeparator,
  MenubarShortcut,
  MenubarSub,
  MenubarSubContent,
  MenubarSubTrigger,
  MenubarTrigger,
} from "@workspace/ui/components/menubar";

export default function MenubarDemo() {
  return (
    <Menubar className="w-72">
      <MenubarMenu>
        <MenubarTrigger>File</MenubarTrigger>
        <MenubarContent>
          <MenubarGroup>
            <MenubarItem>
              New Tab <MenubarShortcut>⌘T</MenubarShortcut>
            </MenubarItem>
            <MenubarItem>
              New Window <MenubarShortcut>⌘N</MenubarShortcut>
            </MenubarItem>
            <MenubarItem disabled>New Incognito Window</MenubarItem>
          </MenubarGroup>
          <MenubarSeparator />
          <MenubarGroup>
            <MenubarSub>
              <MenubarSubTrigger>Share</MenubarSubTrigger>
              <MenubarSubContent>
                <MenubarGroup>
                  <MenubarItem>Email link</MenubarItem>
                  <MenubarItem>Messages</MenubarItem>
                  <MenubarItem>Notes</MenubarItem>
                </MenubarGroup>
              </MenubarSubContent>
            </MenubarSub>
          </MenubarGroup>
          <MenubarSeparator />
          <MenubarGroup>
            <MenubarItem>
              Print... <MenubarShortcut>⌘P</MenubarShortcut>
            </MenubarItem>
          </MenubarGroup>
        </MenubarContent>
      </MenubarMenu>
      <MenubarMenu>
        <MenubarTrigger>Edit</MenubarTrigger>
        <MenubarContent>
          <MenubarGroup>
            <MenubarItem>
              Undo <MenubarShortcut>⌘Z</MenubarShortcut>
            </MenubarItem>
            <MenubarItem>
              Redo <MenubarShortcut>⇧⌘Z</MenubarShortcut>
            </MenubarItem>
          </MenubarGroup>
          <MenubarSeparator />
          <MenubarGroup>
            <MenubarSub>
              <MenubarSubTrigger>Find</MenubarSubTrigger>
              <MenubarSubContent>
                <MenubarGroup>
                  <MenubarItem>Search the web</MenubarItem>
                </MenubarGroup>
                <MenubarSeparator />
                <MenubarGroup>
                  <MenubarItem>Find...</MenubarItem>
                  <MenubarItem>Find Next</MenubarItem>
                  <MenubarItem>Find Previous</MenubarItem>
                </MenubarGroup>
              </MenubarSubContent>
            </MenubarSub>
          </MenubarGroup>
          <MenubarSeparator />
          <MenubarGroup>
            <MenubarItem>Cut</MenubarItem>
            <MenubarItem>Copy</MenubarItem>
            <MenubarItem>Paste</MenubarItem>
          </MenubarGroup>
        </MenubarContent>
      </MenubarMenu>
      <MenubarMenu>
        <MenubarTrigger>View</MenubarTrigger>
        <MenubarContent className="w-44">
          <MenubarGroup>
            <MenubarCheckboxItem>Bookmarks Bar</MenubarCheckboxItem>
            <MenubarCheckboxItem checked>Full URLs</MenubarCheckboxItem>
          </MenubarGroup>
          <MenubarSeparator />
          <MenubarGroup>
            <MenubarItem inset>
              Reload <MenubarShortcut>⌘R</MenubarShortcut>
            </MenubarItem>
            <MenubarItem disabled inset>
              Force Reload <MenubarShortcut>⇧⌘R</MenubarShortcut>
            </MenubarItem>
          </MenubarGroup>
          <MenubarSeparator />
          <MenubarGroup>
            <MenubarItem inset>Toggle Fullscreen</MenubarItem>
          </MenubarGroup>
          <MenubarSeparator />
          <MenubarGroup>
            <MenubarItem inset>Hide Sidebar</MenubarItem>
          </MenubarGroup>
        </MenubarContent>
      </MenubarMenu>
      <MenubarMenu>
        <MenubarTrigger>Profiles</MenubarTrigger>
        <MenubarContent>
          <MenubarRadioGroup value="benoit">
            <MenubarRadioItem value="andy">Andy</MenubarRadioItem>
            <MenubarRadioItem value="benoit">Benoit</MenubarRadioItem>
            <MenubarRadioItem value="Luis">Luis</MenubarRadioItem>
          </MenubarRadioGroup>
          <MenubarSeparator />
          <MenubarGroup>
            <MenubarItem inset>Edit...</MenubarItem>
          </MenubarGroup>
          <MenubarSeparator />
          <MenubarGroup>
            <MenubarItem inset>Add Profile...</MenubarItem>
          </MenubarGroup>
        </MenubarContent>
      </MenubarMenu>
    </Menubar>
  );
}
```

## Installation

```bash
bunx --bun shadcn@latest add @sui/menubar
```

Install with the shadcn CLI or use the shared `@workspace/ui` package. Follow the [installation guide](/docs/installation) to configure the registry, load styles, and choose import aliases.

## Usage

```tsx showLineNumbers
import {
  Menubar,
  MenubarContent,
  MenubarGroup,
  MenubarItem,
  MenubarMenu,
  MenubarSeparator,
  MenubarShortcut,
  MenubarTrigger,
} from "@workspace/ui/components/menubar"
```

```tsx showLineNumbers
<Menubar>
  <MenubarMenu>
    <MenubarTrigger>File</MenubarTrigger>
    <MenubarContent>
      <MenubarGroup>
        <MenubarItem>
          New Tab <MenubarShortcut>⌘T</MenubarShortcut>
        </MenubarItem>
        <MenubarItem>New Window</MenubarItem>
      </MenubarGroup>
      <MenubarSeparator />
      <MenubarGroup>
        <MenubarItem>Share</MenubarItem>
        <MenubarItem>Print</MenubarItem>
      </MenubarGroup>
    </MenubarContent>
  </MenubarMenu>
</Menubar>
```

## Composition

Use the following composition to build a `Menubar`:

```text
Menubar
├── MenubarMenu
│   ├── MenubarTrigger
│   └── MenubarContent
│       ├── MenubarGroup
│       │   ├── MenubarLabel
│       │   ├── MenubarItem
│       │   └── MenubarItem
│       ├── MenubarSeparator
│       ├── MenubarGroup
│       │   ├── MenubarLabel
│       │   ├── MenubarCheckboxItem
│       │   └── MenubarCheckboxItem
│       ├── MenubarSeparator
│       ├── MenubarGroup
│       │   ├── MenubarLabel
│       │   └── MenubarRadioGroup
│       │       ├── MenubarRadioItem
│       │       └── MenubarRadioItem
│       └── MenubarSub
│           ├── MenubarSubTrigger
│           └── MenubarSubContent
│               └── MenubarGroup
│                   ├── MenubarLabel
│                   ├── MenubarItem
│                   └── MenubarItem
└── MenubarMenu
    ├── MenubarTrigger
    └── MenubarContent
        └── MenubarGroup
            ├── MenubarLabel
            ├── MenubarItem
            └── MenubarItem
```

## Checkbox

Use `MenubarCheckboxItem` for toggleable options.

### Example: menubar-checkbox

```tsx
import {
  Menubar,
  MenubarCheckboxItem,
  MenubarContent,
  MenubarItem,
  MenubarMenu,
  MenubarSeparator,
  MenubarShortcut,
  MenubarTrigger,
} from "@workspace/ui/components/menubar";

export function MenubarCheckbox() {
  return (
    <Menubar className="w-72">
      <MenubarMenu>
        <MenubarTrigger>View</MenubarTrigger>
        <MenubarContent className="w-64">
          <MenubarCheckboxItem>Always Show Bookmarks Bar</MenubarCheckboxItem>
          <MenubarCheckboxItem checked>
            Always Show Full URLs
          </MenubarCheckboxItem>
          <MenubarSeparator />
          <MenubarItem inset>
            Reload <MenubarShortcut>⌘R</MenubarShortcut>
          </MenubarItem>
          <MenubarItem disabled inset>
            Force Reload <MenubarShortcut>⇧⌘R</MenubarShortcut>
          </MenubarItem>
        </MenubarContent>
      </MenubarMenu>
      <MenubarMenu>
        <MenubarTrigger>Format</MenubarTrigger>
        <MenubarContent>
          <MenubarCheckboxItem checked>Strikethrough</MenubarCheckboxItem>
          <MenubarCheckboxItem>Code</MenubarCheckboxItem>
          <MenubarCheckboxItem>Superscript</MenubarCheckboxItem>
        </MenubarContent>
      </MenubarMenu>
    </Menubar>
  );
}

export default MenubarCheckbox;
```

## Radio

Use `MenubarRadioGroup` and `MenubarRadioItem` for single-select options.

### Example: menubar-radio

```tsx
"use client";

import {
  Menubar,
  MenubarContent,
  MenubarItem,
  MenubarMenu,
  MenubarRadioGroup,
  MenubarRadioItem,
  MenubarSeparator,
  MenubarTrigger,
} from "@workspace/ui/components/menubar";
import * as React from "react";

export function MenubarRadio() {
  const [user, setUser] = React.useState("benoit");
  const [theme, setTheme] = React.useState("system");

  return (
    <Menubar className="w-72">
      <MenubarMenu>
        <MenubarTrigger>Profiles</MenubarTrigger>
        <MenubarContent>
          <MenubarRadioGroup value={user} onValueChange={setUser}>
            <MenubarRadioItem value="andy">Andy</MenubarRadioItem>
            <MenubarRadioItem value="benoit">Benoit</MenubarRadioItem>
            <MenubarRadioItem value="luis">Luis</MenubarRadioItem>
          </MenubarRadioGroup>
          <MenubarSeparator />
          <MenubarItem inset>Edit...</MenubarItem>
          <MenubarItem inset>Add Profile...</MenubarItem>
        </MenubarContent>
      </MenubarMenu>
      <MenubarMenu>
        <MenubarTrigger>Theme</MenubarTrigger>
        <MenubarContent>
          <MenubarRadioGroup value={theme} onValueChange={setTheme}>
            <MenubarRadioItem value="light">Light</MenubarRadioItem>
            <MenubarRadioItem value="dark">Dark</MenubarRadioItem>
            <MenubarRadioItem value="system">System</MenubarRadioItem>
          </MenubarRadioGroup>
        </MenubarContent>
      </MenubarMenu>
    </Menubar>
  );
}

export default MenubarRadio;
```

## Submenu

Use `MenubarSub`, `MenubarSubTrigger`, and `MenubarSubContent` for nested menus.

### Example: menubar-submenu

```tsx
import {
  Menubar,
  MenubarContent,
  MenubarItem,
  MenubarMenu,
  MenubarSeparator,
  MenubarShortcut,
  MenubarSub,
  MenubarSubContent,
  MenubarSubTrigger,
  MenubarTrigger,
} from "@workspace/ui/components/menubar";

export function MenubarSubmenu() {
  return (
    <Menubar className="w-72">
      <MenubarMenu>
        <MenubarTrigger>File</MenubarTrigger>
        <MenubarContent>
          <MenubarSub>
            <MenubarSubTrigger>Share</MenubarSubTrigger>
            <MenubarSubContent>
              <MenubarItem>Email link</MenubarItem>
              <MenubarItem>Messages</MenubarItem>
              <MenubarItem>Notes</MenubarItem>
            </MenubarSubContent>
          </MenubarSub>
          <MenubarSeparator />
          <MenubarItem>
            Print... <MenubarShortcut>⌘P</MenubarShortcut>
          </MenubarItem>
        </MenubarContent>
      </MenubarMenu>
      <MenubarMenu>
        <MenubarTrigger>Edit</MenubarTrigger>
        <MenubarContent>
          <MenubarItem>
            Undo <MenubarShortcut>⌘Z</MenubarShortcut>
          </MenubarItem>
          <MenubarItem>
            Redo <MenubarShortcut>⇧⌘Z</MenubarShortcut>
          </MenubarItem>
          <MenubarSeparator />
          <MenubarSub>
            <MenubarSubTrigger>Find</MenubarSubTrigger>
            <MenubarSubContent>
              <MenubarItem>Find...</MenubarItem>
              <MenubarItem>Find Next</MenubarItem>
              <MenubarItem>Find Previous</MenubarItem>
            </MenubarSubContent>
          </MenubarSub>
          <MenubarSeparator />
          <MenubarItem>Cut</MenubarItem>
          <MenubarItem>Copy</MenubarItem>
          <MenubarItem>Paste</MenubarItem>
        </MenubarContent>
      </MenubarMenu>
    </Menubar>
  );
}

export default MenubarSubmenu;
```

## With Icons

### Example: menubar-icons

```tsx
import {
  Menubar,
  MenubarContent,
  MenubarGroup,
  MenubarItem,
  MenubarMenu,
  MenubarSeparator,
  MenubarShortcut,
  MenubarTrigger,
} from "@workspace/ui/components/menubar";
import {
  FileIcon,
  FolderIcon,
  HelpCircleIcon,
  SaveIcon,
  SettingsIcon,
  TrashIcon,
} from "lucide-react";

export function MenubarIcons() {
  return (
    <Menubar className="w-72">
      <MenubarMenu>
        <MenubarTrigger>File</MenubarTrigger>
        <MenubarContent>
          <MenubarItem>
            <FileIcon />
            New File <MenubarShortcut>⌘N</MenubarShortcut>
          </MenubarItem>
          <MenubarItem>
            <FolderIcon />
            Open Folder
          </MenubarItem>
          <MenubarSeparator />
          <MenubarItem>
            <SaveIcon />
            Save <MenubarShortcut>⌘S</MenubarShortcut>
          </MenubarItem>
        </MenubarContent>
      </MenubarMenu>
      <MenubarMenu>
        <MenubarTrigger>More</MenubarTrigger>
        <MenubarContent>
          <MenubarGroup>
            <MenubarItem>
              <SettingsIcon />
              Settings
            </MenubarItem>
            <MenubarItem>
              <HelpCircleIcon />
              Help
            </MenubarItem>
            <MenubarSeparator />
            <MenubarItem variant="destructive">
              <TrashIcon />
              Delete
            </MenubarItem>
          </MenubarGroup>
        </MenubarContent>
      </MenubarMenu>
    </Menubar>
  );
}

export default MenubarIcons;
```

## RTL

To enable RTL support in shadcn/ui, see the [RTL configuration guide](https://ui.shadcn.com/docs/rtl).

### Example: menubar-rtl

```tsx
"use client";

import {
  Menubar,
  MenubarCheckboxItem,
  MenubarContent,
  MenubarGroup,
  MenubarItem,
  MenubarMenu,
  MenubarRadioGroup,
  MenubarRadioItem,
  MenubarSeparator,
  MenubarShortcut,
  MenubarSub,
  MenubarSubContent,
  MenubarSubTrigger,
  MenubarTrigger,
} from "@workspace/ui/components/menubar";
import * as React from "react";
import { type Translations, useTranslation } from "./support";

const translations: Translations = {
  en: {
    dir: "ltr",
    values: {
      file: "File",
      newTab: "New Tab",
      newWindow: "New Window",
      newIncognitoWindow: "New Incognito Window",
      share: "Share",
      emailLink: "Email link",
      messages: "Messages",
      notes: "Notes",
      print: "Print...",
      edit: "Edit",
      undo: "Undo",
      redo: "Redo",
      find: "Find",
      searchTheWeb: "Search the web",
      findItem: "Find...",
      findNext: "Find Next",
      findPrevious: "Find Previous",
      cut: "Cut",
      copy: "Copy",
      paste: "Paste",
      view: "View",
      bookmarksBar: "Bookmarks Bar",
      fullUrls: "Full URLs",
      reload: "Reload",
      forceReload: "Force Reload",
      toggleFullscreen: "Toggle Fullscreen",
      hideSidebar: "Hide Sidebar",
      profiles: "Profiles",
      andy: "Andy",
      benoit: "Benoit",
      luis: "Luis",
      editProfile: "Edit...",
      addProfile: "Add Profile...",
    },
  },
  ar: {
    dir: "rtl",
    values: {
      file: "ملف",
      newTab: "علامة تبويب جديدة",
      newWindow: "نافذة جديدة",
      newIncognitoWindow: "نافذة التصفح المتخفي الجديدة",
      share: "مشاركة",
      emailLink: "رابط البريد الإلكتروني",
      messages: "الرسائل",
      notes: "الملاحظات",
      print: "طباعة...",
      edit: "تعديل",
      undo: "تراجع",
      redo: "إعادة",
      find: "بحث",
      searchTheWeb: "البحث على الويب",
      findItem: "بحث...",
      findNext: "البحث التالي",
      findPrevious: "البحث السابق",
      cut: "قص",
      copy: "نسخ",
      paste: "لصق",
      view: "عرض",
      bookmarksBar: "شريط الإشارات المرجعية",
      fullUrls: "عناوين URL الكاملة",
      reload: "إعادة تحميل",
      forceReload: "إعادة تحميل قسري",
      toggleFullscreen: "تبديل وضع ملء الشاشة",
      hideSidebar: "إخفاء الشريط الجانبي",
      profiles: "الملفات الشخصية",
      andy: "Andy",
      benoit: "Benoit",
      luis: "Luis",
      editProfile: "تعديل...",
      addProfile: "إضافة ملف شخصي...",
    },
  },
  he: {
    dir: "rtl",
    values: {
      file: "קובץ",
      newTab: "כרטיסייה חדשה",
      newWindow: "חלון חדש",
      newIncognitoWindow: "חלון גלישה בסתר חדש",
      share: "שתף",
      emailLink: "קישור אימייל",
      messages: "הודעות",
      notes: "הערות",
      print: "הדפס...",
      edit: "ערוך",
      undo: "בטל",
      redo: "בצע שוב",
      find: "מצא",
      searchTheWeb: "חפש באינטרנט",
      findItem: "מצא...",
      findNext: "מצא הבא",
      findPrevious: "מצא הקודם",
      cut: "גזור",
      copy: "העתק",
      paste: "הדבק",
      view: "תצוגה",
      bookmarksBar: "סרגל סימניות",
      fullUrls: "כתובות URL מלאות",
      reload: "רענן",
      forceReload: "רענן בכוח",
      toggleFullscreen: "החלף מסך מלא",
      hideSidebar: "הסתר סרגל צד",
      profiles: "פרופילים",
      andy: "Andy",
      benoit: "Benoit",
      luis: "Luis",
      editProfile: "ערוך...",
      addProfile: "הוסף פרופיל...",
    },
  },
};

export function MenubarRtl() {
  const { dir, t, language } = useTranslation(translations, "ar");
  const [profile, setProfile] = React.useState("benoit");

  return (
    <Menubar className="w-72" dir={dir}>
      <MenubarMenu>
        <MenubarTrigger>{t.file}</MenubarTrigger>
        <MenubarContent dir={dir} align={dir === "rtl" ? "end" : "start"}>
          <MenubarGroup>
            <MenubarItem>
              {t.newTab} <MenubarShortcut>⌘T</MenubarShortcut>
            </MenubarItem>
            <MenubarItem>
              {t.newWindow} <MenubarShortcut>⌘N</MenubarShortcut>
            </MenubarItem>
            <MenubarItem disabled>{t.newIncognitoWindow}</MenubarItem>
          </MenubarGroup>
          <MenubarSeparator />
          <MenubarGroup>
            <MenubarSub>
              <MenubarSubTrigger>{t.share}</MenubarSubTrigger>
              <MenubarSubContent
                dir={dir}
                data-lang={dir === "rtl" ? language : undefined}
              >
                <MenubarGroup>
                  <MenubarItem>{t.emailLink}</MenubarItem>
                  <MenubarItem>{t.messages}</MenubarItem>
                  <MenubarItem>{t.notes}</MenubarItem>
                </MenubarGroup>
              </MenubarSubContent>
            </MenubarSub>
          </MenubarGroup>
          <MenubarSeparator />
          <MenubarGroup>
            <MenubarItem>
              {t.print} <MenubarShortcut>⌘P</MenubarShortcut>
            </MenubarItem>
          </MenubarGroup>
        </MenubarContent>
      </MenubarMenu>
      <MenubarMenu>
        <MenubarTrigger>{t.edit}</MenubarTrigger>
        <MenubarContent
          dir={dir}
          align={dir === "rtl" ? "end" : "start"}
          data-lang={dir === "rtl" ? language : undefined}
        >
          <MenubarGroup>
            <MenubarItem>
              {t.undo} <MenubarShortcut>⌘Z</MenubarShortcut>
            </MenubarItem>
            <MenubarItem>
              {t.redo} <MenubarShortcut>⇧⌘Z</MenubarShortcut>
            </MenubarItem>
          </MenubarGroup>
          <MenubarSeparator />
          <MenubarGroup>
            <MenubarSub>
              <MenubarSubTrigger>{t.find}</MenubarSubTrigger>
              <MenubarSubContent
                dir={dir}
                data-lang={dir === "rtl" ? language : undefined}
              >
                <MenubarGroup>
                  <MenubarItem>{t.searchTheWeb}</MenubarItem>
                </MenubarGroup>
                <MenubarSeparator />
                <MenubarGroup>
                  <MenubarItem>{t.findItem}</MenubarItem>
                  <MenubarItem>{t.findNext}</MenubarItem>
                  <MenubarItem>{t.findPrevious}</MenubarItem>
                </MenubarGroup>
              </MenubarSubContent>
            </MenubarSub>
          </MenubarGroup>
          <MenubarSeparator />
          <MenubarGroup>
            <MenubarItem>{t.cut}</MenubarItem>
            <MenubarItem>{t.copy}</MenubarItem>
            <MenubarItem>{t.paste}</MenubarItem>
          </MenubarGroup>
        </MenubarContent>
      </MenubarMenu>
      <MenubarMenu>
        <MenubarTrigger>{t.view}</MenubarTrigger>
        <MenubarContent
          className="w-44"
          dir={dir}
          align={dir === "rtl" ? "end" : "start"}
          data-lang={dir === "rtl" ? language : undefined}
        >
          <MenubarGroup>
            <MenubarCheckboxItem>{t.bookmarksBar}</MenubarCheckboxItem>
            <MenubarCheckboxItem checked>{t.fullUrls}</MenubarCheckboxItem>
          </MenubarGroup>
          <MenubarSeparator />
          <MenubarGroup>
            <MenubarItem inset>
              {t.reload} <MenubarShortcut>⌘R</MenubarShortcut>
            </MenubarItem>
            <MenubarItem disabled inset>
              {t.forceReload} <MenubarShortcut>⇧⌘R</MenubarShortcut>
            </MenubarItem>
          </MenubarGroup>
          <MenubarSeparator />
          <MenubarGroup>
            <MenubarItem inset>{t.toggleFullscreen}</MenubarItem>
          </MenubarGroup>
          <MenubarSeparator />
          <MenubarGroup>
            <MenubarItem inset>{t.hideSidebar}</MenubarItem>
          </MenubarGroup>
        </MenubarContent>
      </MenubarMenu>
      <MenubarMenu>
        <MenubarTrigger>{t.profiles}</MenubarTrigger>
        <MenubarContent
          dir={dir}
          align={dir === "rtl" ? "end" : "start"}
          data-lang={dir === "rtl" ? language : undefined}
        >
          <MenubarRadioGroup value={profile} onValueChange={setProfile}>
            <MenubarRadioItem value="andy">{t.andy}</MenubarRadioItem>
            <MenubarRadioItem value="benoit">{t.benoit}</MenubarRadioItem>
            <MenubarRadioItem value="Luis">{t.luis}</MenubarRadioItem>
          </MenubarRadioGroup>
          <MenubarSeparator />
          <MenubarGroup>
            <MenubarItem inset>{t.editProfile}</MenubarItem>
          </MenubarGroup>
          <MenubarSeparator />
          <MenubarGroup>
            <MenubarItem inset>{t.addProfile}</MenubarItem>
          </MenubarGroup>
        </MenubarContent>
      </MenubarMenu>
    </Menubar>
  );
}

export default MenubarRtl;
```

## API Reference

See the [Base UI Menubar](https://base-ui.com/react/components/menubar#api-reference) documentation.

- [Documentation](https://base-ui.com/react/components/menubar)
- [API reference](https://base-ui.com/react/components/menubar#api-reference)


---

# Message

Displays a message in a conversation, with optional avatar, header, footer, and alignment.

Page: https://sui.draco.dev/docs/components/message

### Example: message-demo

```tsx
import {
  Avatar,
  AvatarFallback,
  AvatarImage,
} from "@workspace/ui/components/avatar";
import {
  Bubble,
  BubbleContent,
  BubbleGroup,
  BubbleReactions,
} from "@workspace/ui/components/bubble";
import { Marker, MarkerContent } from "@workspace/ui/components/marker";
import {
  Message,
  MessageAvatar,
  MessageContent,
  MessageFooter,
} from "@workspace/ui/components/message";

export function MessageDemo() {
  return (
    <div className="flex w-full max-w-sm flex-col gap-6 py-12">
      <Message align="end">
        <MessageAvatar>
          <Avatar>
            <AvatarImage src="/avatars/10.png" alt="@me" />
            <AvatarFallback>ME</AvatarFallback>
          </Avatar>
        </MessageAvatar>
        <MessageContent>
          <Bubble>
            <BubbleContent>Deploying to prod real quick.</BubbleContent>
          </Bubble>
        </MessageContent>
      </Message>
      <Message>
        <MessageAvatar>
          <Avatar>
            <AvatarImage src="/avatars/02.png" alt="@rabbit" />
            <AvatarFallback>R</AvatarFallback>
          </Avatar>
        </MessageAvatar>
        <MessageContent>
          <Bubble variant="muted">
            <BubbleContent>It&apos;s 4:55 PM. On a Friday.</BubbleContent>
          </Bubble>
        </MessageContent>
      </Message>
      <Message align="end">
        <MessageAvatar>
          <Avatar>
            <AvatarImage src="/avatars/10.png" alt="@me" />
            <AvatarFallback>ME</AvatarFallback>
          </Avatar>
        </MessageAvatar>
        <MessageContent>
          <Bubble>
            <BubbleContent>It&apos;s a one-line change.</BubbleContent>
          </Bubble>
          <MessageFooter>Delivered</MessageFooter>
        </MessageContent>
      </Message>
      <Message>
        <MessageAvatar>
          <Avatar>
            <AvatarImage src="/avatars/02.png" alt="@rabbit" />
            <AvatarFallback>R</AvatarFallback>
          </Avatar>
        </MessageAvatar>
        <MessageContent>
          <BubbleGroup>
            <Bubble variant="muted">
              <BubbleContent>
                It&apos;s always a one-line change 😭.
              </BubbleContent>
            </Bubble>
            <Bubble variant="muted">
              <BubbleContent>Alright, let me take a look.</BubbleContent>
              <BubbleReactions aria-label="Reactions: thumbs up">
                <span>👍</span>
              </BubbleReactions>
            </Bubble>
          </BubbleGroup>
        </MessageContent>
      </Message>
      <Marker role="status">
        <MarkerContent className="shimmer">
          <span className="font-medium">Oliver</span> is typing...
        </MarkerContent>
      </Marker>
    </div>
  );
}

export default MessageDemo;
```

The `Message` component lays out a single message in a conversation. It handles the avatar, alignment, header, and footer around the message surface.

For AI apps, you can render reasoning steps, tool calls and assistant messages using the `Message` component.

## Installation

```bash
bunx --bun shadcn@latest add @sui/message
```

Install with the shadcn CLI or use the shared `@workspace/ui` package. Follow the [installation guide](/docs/installation) to configure the registry, load styles, and choose import aliases.

## Usage

```tsx showLineNumbers
import { Avatar, AvatarFallback, AvatarImage } from "@workspace/ui/components/avatar"
import { Bubble, BubbleContent } from "@workspace/ui/components/bubble"
import { Message, MessageAvatar, MessageContent } from "@workspace/ui/components/message"
```

```tsx showLineNumbers
<Message>
  <MessageAvatar>
    <Avatar>
      <AvatarImage src="https://github.com/shadcn.png" alt="@shadcn" />
      <AvatarFallback>CN</AvatarFallback>
    </Avatar>
  </MessageAvatar>
  <MessageContent>
    <Bubble>
      <BubbleContent>How can I help you today?</BubbleContent>
    </Bubble>
  </MessageContent>
</Message>
```

**Note:** `Message` owns the row layout—avatar, alignment, header, and footer.
Render the visible message surface inside it with
[`Bubble`](/docs/components/bubble). For the scroll container around a
conversation, use [`MessageScroller`](/docs/components/message-scroller).

## Composition

Use the following composition to build a message:

```text
Message
├── MessageAvatar
└── MessageContent
    ├── MessageHeader
    ├── Bubble
    └── MessageFooter
```

Use `MessageGroup` to stack consecutive messages from the same sender:

```text
MessageGroup
├── Message
└── Message
```

## Features

- Start and end alignment for sender and receiver rows via the `align` prop
- Avatar slot that anchors to the bottom of the message and stays clear of the footer
- Header and footer slots for sender names, status, and message actions
- Footer follows the message side; actions stay aligned on `align="end"` rows
- Group wrapper for stacking consecutive messages from the same sender
- Customizable styling through the `className` prop on every part

## Avatar

Use `MessageAvatar` to render an avatar next to the message. Set `align="end"` on the message to align the avatar to the end of the message.

### Example: message-avatar

```tsx
import {
  Avatar,
  AvatarFallback,
  AvatarImage,
} from "@workspace/ui/components/avatar";
import {
  Bubble,
  BubbleContent,
  BubbleGroup,
} from "@workspace/ui/components/bubble";
import {
  Message,
  MessageAvatar,
  MessageContent,
} from "@workspace/ui/components/message";

export function MessageAvatarDemo() {
  return (
    <div className="flex w-full max-w-sm flex-col gap-6 py-12">
      <Message>
        <MessageAvatar>
          <Avatar>
            <AvatarImage src="/avatars/03.png" alt="@avatar" />
            <AvatarFallback>R</AvatarFallback>
          </Avatar>
        </MessageAvatar>
        <MessageContent>
          <Bubble variant="muted">
            <BubbleContent>
              The build failed during dependency installation.
            </BubbleContent>
          </Bubble>
        </MessageContent>
      </Message>
      <Message align="end">
        <MessageAvatar>
          <Avatar>
            <AvatarImage src="/avatars/10.png" alt="@avatar" />
            <AvatarFallback>R</AvatarFallback>
          </Avatar>
        </MessageAvatar>
        <MessageContent>
          <Bubble>
            <BubbleContent>Can you share the exact error?</BubbleContent>
          </Bubble>
        </MessageContent>
      </Message>
      <Message>
        <MessageAvatar>
          <Avatar>
            <AvatarImage src="/avatars/03.png" alt="@avatar" />
            <AvatarFallback>R</AvatarFallback>
          </Avatar>
        </MessageAvatar>
        <MessageContent>
          <BubbleGroup>
            <Bubble variant="muted">
              <BubbleContent>Here&apos;s the error from the logs</BubbleContent>
            </Bubble>
            <Bubble variant="muted">
              <BubbleContent>
                Something went wrong with the build. The libraries are not
                installed correctly. Try running the build again.
              </BubbleContent>
            </Bubble>
          </BubbleGroup>
        </MessageContent>
      </Message>
    </div>
  );
}

export default MessageAvatarDemo;
```

| align   | Description                                         |
| ------- | --------------------------------------------------- |
| `start` | Align the message to the start of the conversation. |
| `end`   | Align the message to the end of the conversation.   |

## Group

Use `MessageGroup` to stack consecutive messages from the same sender. Render an empty `MessageAvatar` on the earlier messages to keep them aligned with the avatar on the last one.

### Example: message-group

```tsx
import {
  Avatar,
  AvatarFallback,
  AvatarImage,
} from "@workspace/ui/components/avatar";
import { Bubble, BubbleContent } from "@workspace/ui/components/bubble";
import {
  Message,
  MessageAvatar,
  MessageContent,
  MessageGroup,
} from "@workspace/ui/components/message";

export function MessageGroupDemo() {
  return (
    <div className="flex w-full max-w-sm flex-col gap-6 py-12">
      <MessageGroup>
        <Message>
          <MessageAvatar />
          <MessageContent>
            <Bubble variant="muted">
              <BubbleContent>I checked the registry addresses.</BubbleContent>
            </Bubble>
          </MessageContent>
        </Message>
        <Message>
          <MessageAvatar>
            <Avatar>
              <AvatarImage src="/avatars/02.png" alt="@avatar" />
              <AvatarFallback>CN</AvatarFallback>
            </Avatar>
          </MessageAvatar>
          <MessageContent>
            <Bubble variant="muted">
              <BubbleContent>
                The component and example JSON now live under the UI registry.
              </BubbleContent>
            </Bubble>
          </MessageContent>
        </Message>
      </MessageGroup>
    </div>
  );
}

export default MessageGroupDemo;
```

## Header and Footer

Use `MessageHeader` for a sender name and `MessageFooter` for metadata such as a delivery or read status.

### Example: message-header-footer

```tsx
import { Bubble, BubbleContent } from "@workspace/ui/components/bubble";
import {
  Message,
  MessageContent,
  MessageFooter,
  MessageHeader,
} from "@workspace/ui/components/message";

export function MessageHeaderFooterDemo() {
  return (
    <div className="flex w-full max-w-sm flex-col gap-8 py-12">
      <Message>
        <MessageContent>
          <MessageHeader>Olivia</MessageHeader>
          <Bubble variant="muted">
            <BubbleContent>I already checked the logs.</BubbleContent>
          </Bubble>
        </MessageContent>
      </Message>
      <Message align="end">
        <MessageContent>
          <Bubble>
            <BubbleContent>
              Send the report to the team. Ping @shadcn if you need help.
            </BubbleContent>
          </Bubble>
          <MessageFooter>
            <div>
              Read <span className="font-normal">Yesterday</span>
            </div>
          </MessageFooter>
        </MessageContent>
      </Message>
    </div>
  );
}

export default MessageHeaderFooterDemo;
```

## Actions

Place message-level actions in `MessageFooter`, such as copy, retry, or feedback buttons.

### Example: message-actions

```tsx
import { Bubble, BubbleContent } from "@workspace/ui/components/bubble";
import { Button } from "@workspace/ui/components/button";
import {
  Message,
  MessageContent,
  MessageFooter,
} from "@workspace/ui/components/message";
import {
  CopyIcon,
  RefreshCcwIcon,
  ThumbsDownIcon,
  ThumbsUpIcon,
} from "lucide-react";

export function MessageActionsDemo() {
  return (
    <div className="flex w-full max-w-sm flex-col gap-8 py-12">
      <Message>
        <MessageContent>
          <Bubble variant="muted">
            <BubbleContent>
              The install failure is coming from the workspace package.
            </BubbleContent>
          </Bubble>
          <MessageFooter>
            <Button variant="ghost" size="icon" aria-label="Copy" title="Copy">
              <CopyIcon />
            </Button>
            <Button variant="ghost" size="icon" aria-label="Like" title="Like">
              <ThumbsUpIcon />
            </Button>
            <Button
              variant="ghost"
              size="icon"
              aria-label="Dislike"
              title="Dislike"
            >
              <ThumbsDownIcon />
            </Button>
          </MessageFooter>
        </MessageContent>
      </Message>
      <Message align="end">
        <MessageContent>
          <Bubble>
            <BubbleContent>Okay drop me a link. Taking a look...</BubbleContent>
          </Bubble>
          <MessageFooter className="gap-2">
            <span className="font-normal text-destructive">Failed to send</span>
            <Button
              variant="ghost"
              size="icon-xs"
              title="Retry"
              aria-label="Retry"
            >
              <RefreshCcwIcon />
            </Button>
          </MessageFooter>
        </MessageContent>
      </Message>
    </div>
  );
}

export default MessageActionsDemo;
```

## Attachment

### Example: message-attachment

```tsx
"use client";

import {
  Attachment,
  AttachmentAction,
  AttachmentActions,
  AttachmentContent,
  AttachmentDescription,
  AttachmentMedia,
  AttachmentTitle,
} from "@workspace/ui/components/attachment";
import { Bubble, BubbleContent } from "@workspace/ui/components/bubble";
import { Message, MessageContent } from "@workspace/ui/components/message";
import { DownloadIcon, FileTextIcon } from "lucide-react";

export function MessageAttachmentDemo() {
  return (
    <div className="flex w-full max-w-sm flex-col gap-8 py-12">
      <Message align="end">
        <MessageContent>
          <Attachment orientation="vertical">
            <AttachmentMedia variant="image">
              <img
                src="https://images.unsplash.com/photo-1497366754035-f200968a6e72?w=900&auto=format&fit=crop&q=80"
                alt="Workspace"
              />
            </AttachmentMedia>
          </Attachment>
          <Bubble>
            <BubbleContent>
              Here&apos;s the image. Can you add it to the PDF? Use it for the
              cover page.
            </BubbleContent>
          </Bubble>
        </MessageContent>
      </Message>
      <Message>
        <MessageContent>
          <Bubble variant="muted">
            <BubbleContent>
              Done. Here&apos;s the PDF with the image added as the cover page.
            </BubbleContent>
          </Bubble>
          <Attachment>
            <AttachmentMedia>
              <FileTextIcon />
            </AttachmentMedia>
            <AttachmentContent>
              <AttachmentTitle>sales-dashboard.pdf</AttachmentTitle>
              <AttachmentDescription>PDF · 2.4 MB</AttachmentDescription>
            </AttachmentContent>
            <AttachmentActions>
              <AttachmentAction
                type="button"
                title="Download"
                aria-label="Download"
                size="icon-sm"
                variant="secondary"
              >
                <DownloadIcon />
              </AttachmentAction>
            </AttachmentActions>
          </Attachment>
        </MessageContent>
      </Message>
      <Message align="end">
        <MessageContent>
          <Bubble>
            <BubbleContent>Thanks. Looks good.</BubbleContent>
          </Bubble>
        </MessageContent>
      </Message>
    </div>
  );
}

export default MessageAttachmentDemo;
```

## Accessibility

`Message` is a presentational layout wrapper. Accessibility comes from the content you place inside it.

### Label icon-only actions

Action buttons in `MessageFooter` are usually icon-only, so give each one an `aria-label`.

```tsx showLineNumbers
<MessageFooter>
  <Button variant="ghost" size="icon" aria-label="Copy">
    <CopyIcon />
  </Button>
</MessageFooter>
```

### Status updates

For in-progress messages, use a [`Marker`](/docs/components/marker) with `role="status"` so assistive tech announces the update as it appears.

```tsx showLineNumbers
<Message>
  <Marker role="status">
    <MarkerIcon>
      <Loader size="sm" />
    </MarkerIcon>
    <MarkerContent>Checking the logs...</MarkerContent>
  </Marker>
</Message>
```

## API Reference

### Message

The message row wrapper.

| Prop        | Type               | Default   | Description                                       |
| ----------- | ------------------ | --------- | ------------------------------------------------- |
| `align`     | `"start" \| "end"` | `"start"` | The alignment of the message in the conversation. |
| `className` | `string`           | -         | Additional classes to apply to the row.           |

### MessageGroup

Groups consecutive messages from the same sender.

| Prop        | Type     | Default | Description                                    |
| ----------- | -------- | ------- | ---------------------------------------------- |
| `className` | `string` | -       | Additional classes to apply to the group root. |

### MessageAvatar

The avatar slot, aligned to the bottom of the message. When the message has a `MessageFooter`, the avatar shifts up to stay aligned with the message surface instead of the footer.

| Prop        | Type     | Default | Description                                     |
| ----------- | -------- | ------- | ----------------------------------------------- |
| `className` | `string` | -       | Additional classes to apply to the avatar slot. |

### MessageContent

Wraps the header, message surface, and footer.

| Prop        | Type     | Default | Description                                      |
| ----------- | -------- | ------- | ------------------------------------------------ |
| `className` | `string` | -       | Additional classes to apply to the content slot. |

### MessageHeader

Displays content above the message, such as a sender name. Stays aligned to the start regardless of `align`.

| Prop        | Type     | Default | Description                                |
| ----------- | -------- | ------- | ------------------------------------------ |
| `className` | `string` | -       | Additional classes to apply to the header. |

### MessageFooter

Displays content below the message, such as status or actions. Aligns to the message side.

| Prop        | Type     | Default | Description                                |
| ----------- | -------- | ------- | ------------------------------------------ |
| `className` | `string` | -       | Additional classes to apply to the footer. |


---

# Message Scroller

A chat scroll container that anchors turns, opens saved transcripts, follows streamed responses, loads history without jumping, and jumps to any message.

Page: https://sui.draco.dev/docs/components/message-scroller

### Example: message-scroller-demo

```tsx
"use client";

import { useChat } from "@ai-sdk/react";
import { Button } from "@workspace/ui/components/button";
import {
  Card,
  CardAction,
  CardContent,
  CardDescription,
  CardFooter,
  CardHeader,
  CardTitle,
} from "@workspace/ui/components/card";
import {
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuItem,
  DropdownMenuSeparator,
  DropdownMenuTrigger,
} from "@workspace/ui/components/dropdown-menu";
import {
  Empty,
  EmptyDescription,
  EmptyHeader,
  EmptyMedia,
  EmptyTitle,
} from "@workspace/ui/components/empty";
import {
  InputGroup,
  InputGroupAddon,
  InputGroupButton,
} from "@workspace/ui/components/input-group";
import {
  MessageScroller,
  MessageScrollerButton,
  MessageScrollerContent,
  MessageScrollerProvider,
  MessageScrollerViewport,
} from "@workspace/ui/components/message-scroller";
import {
  Tooltip,
  TooltipContent,
  TooltipTrigger,
} from "@workspace/ui/components/tooltip";
import {
  ArrowUpIcon,
  GlobeIcon,
  ImageIcon,
  MessageCircleDashedIcon,
  PaperclipIcon,
  PlusIcon,
  RotateCwIcon,
  TelescopeIcon,
} from "lucide-react";
import { createChat, getMessageText } from "../support/ai";
import { MessageAnimated } from "../support/message-animated";

const chat = createChat()
  .user(
    "I'm building a chat for our app and the scroll behavior is driving me nuts. Every time the AI streams a reply, the whole thread jumps around.",
  )
  .sleep(1000)
  .assistant(
    "That's the classic streaming scroll problem. Wrap your message list in `MessageScroller` and turn on `autoScroll` — the viewport pins to the bottom as tokens arrive, so users always see the latest text land in place.\n\nThe important part: it only auto-scrolls while the reader is already at the bottom. The moment they scroll up to read something earlier, auto-scroll backs off and their position is preserved. You get smooth streaming without fighting the user's intent.",
  )
  .user(
    "Okay, but when someone sends a new message the view still feels jarring — like the whole conversation reloads from the top.",
  )
  .sleep(1000)
  .assistant(
    "MessageScrollerItem fixes that with turn anchoring. Set `scrollAnchor` on the turn that should settle near the top instead of blindly snapping to the document bottom.\n\nIt also leaves a small peek of the previous exchange visible above the anchor, so context isn't lost. The reply starts in view without that disorienting jump you get from a plain overflow container.",
  )
  .user(
    "And if they've scrolled up to re-read an older answer? I don't want to yank them back down.",
  )
  .sleep(1000)
  .assistant(
    "You won't. Auto-scroll only runs when the viewport is already pinned to the bottom, so scrolling up is a deliberate opt-out — their place in the thread stays put even as new tokens keep arriving below.\n\nWhen there is content they haven't seen yet, `MessageScrollerButton` appears at the bottom of the viewport. One tap jumps them back to the newest message and re-engages auto-scroll. Same pattern as Slack or iMessage: quiet when you're caught up, helpful when you're not.",
  )
  .user("Last one — does this work with assistive tech?")
  .sleep(1000)
  .assistant(
    '`MessageScrollerContent` sets `role="log"` and `aria-relevant="additions"` by default, so screen readers announce new messages as they stream in.\n\nThe scroll button is a real `<button>` with an sr-only label, and it\'s removed from the tab order when you\'re already at the bottom — no ghost focus stops.',
  );
const initialMessages = chat.get(0);
const transport = chat.transport({ delayMs: 20 });

export function MessageScrollerDemo() {
  const { messages, sendMessage, status, setMessages } = useChat({
    messages: initialMessages,
    transport,
  });
  const nextMessage = chat.next(messages);
  const isBusy = status === "submitted" || status === "streaming";

  return (
    <MessageScrollerProvider>
      <div className="relative flex flex-col gap-4">
        <Card className="mx-auto h-140 w-full max-w-sm gap-0">
          <CardHeader className="gap-1 border-b">
            <CardTitle>New Chat</CardTitle>
            <CardDescription>How can I help you today?</CardDescription>
            <CardAction>
              <Tooltip>
                <TooltipTrigger
                  render={
                    <Button
                      variant="outline"
                      size="icon"
                      aria-label="Reset conversation"
                      onClick={() => setMessages(initialMessages)}
                      disabled={isBusy}
                    />
                  }
                >
                  <RotateCwIcon />
                </TooltipTrigger>
                <TooltipContent>
                  <p>Reset</p>
                </TooltipContent>
              </Tooltip>
            </CardAction>
          </CardHeader>
          <CardContent className="flex-1 overflow-hidden p-0">
            {messages.length === 0 ? (
              <Empty className="h-full">
                <EmptyHeader>
                  <EmptyMedia variant="icon">
                    <MessageCircleDashedIcon />
                  </EmptyMedia>
                  <EmptyTitle>Morning, shadcn!</EmptyTitle>
                  <EmptyDescription>
                    What are we working on today? Press send to start a new
                    conversation
                  </EmptyDescription>
                </EmptyHeader>
              </Empty>
            ) : (
              <MessageScroller>
                <MessageScrollerViewport>
                  <MessageScrollerContent
                    aria-busy={isBusy}
                    className="p-(--card-spacing)"
                  >
                    {messages.map((message) => (
                      <MessageAnimated
                        key={message.id}
                        message={message}
                        scrollAnchor={message.role === "user"}
                      />
                    ))}
                  </MessageScrollerContent>
                </MessageScrollerViewport>
                <MessageScrollerButton />
              </MessageScroller>
            )}
          </CardContent>
          <CardFooter className="flex-col gap-2">
            <form
              onSubmit={(e) => {
                e.preventDefault();
                if (!nextMessage || isBusy) {
                  return;
                }
                void sendMessage(nextMessage);
              }}
              className="w-full"
            >
              <InputGroup>
                <div className="h-14 w-full px-3 py-2.5">
                  <span
                    className="line-clamp-2 opacity-60 data-[status=ready]:opacity-100"
                    data-status={status}
                  >
                    {nextMessage ? (
                      getMessageText(nextMessage)
                    ) : (
                      <span className="text-muted-foreground">
                        No messages queued. Reset the conversation.
                      </span>
                    )}
                  </span>
                </div>
                <InputGroupAddon align="block-end" className="pt-1">
                  <DropdownMenu>
                    <DropdownMenuTrigger
                      render={
                        <InputGroupButton
                          aria-label="Add files"
                          type="button"
                          size="icon-sm"
                          variant="outline"
                        />
                      }
                    >
                      <PlusIcon />
                    </DropdownMenuTrigger>
                    <DropdownMenuContent
                      align="start"
                      side="top"
                      className="w-44"
                    >
                      <DropdownMenuItem>
                        <PaperclipIcon />
                        Add Photos & Files
                      </DropdownMenuItem>
                      <DropdownMenuSeparator />
                      <DropdownMenuItem>
                        <ImageIcon />
                        Create Image
                      </DropdownMenuItem>
                      <DropdownMenuItem>
                        <TelescopeIcon />
                        Deep Research
                      </DropdownMenuItem>
                      <DropdownMenuItem>
                        <GlobeIcon />
                        Web Search
                      </DropdownMenuItem>
                    </DropdownMenuContent>
                  </DropdownMenu>
                  <InputGroupButton
                    type="submit"
                    variant="default"
                    size="icon-sm"
                    disabled={!nextMessage || isBusy}
                    className="ml-auto"
                  >
                    <ArrowUpIcon />
                    <span className="sr-only">Send</span>
                  </InputGroupButton>
                </InputGroupAddon>
              </InputGroup>
            </form>
          </CardFooter>
        </Card>
        <div className="px-0.5 text-center text-muted-foreground text-xs">
          Demo is read only. Press send to send messages.
        </div>
      </div>
    </MessageScrollerProvider>
  );
}

export default MessageScrollerDemo;
```

## What Makes a Great Streaming Chat Experience

Building a chat interface used to be simple. You create an inverted list with
an input. Type a message, it appends at the bottom. When a reply comes in, the
list grows and scrolls. Done.

Streaming breaks that model. Messages arrive in chunks while you may still be
reading, scrolling, or looking somewhere else entirely.

Now the challenge is preserving the reader's place while the conversation keeps
changing. Get that wrong and the experience feels jumpy: people are pulled to
the bottom, lose context, and have to find their way back.

In practice, this comes down to scroll: when to follow, when to hold, and when
to let the reader decide. A great streaming chat should:

1. **Move only when the reader asked to move.** If someone is reading, don’t pull them somewhere else. Auto-scroll should never be the default.
2. **Follow only while they’re following.** If they’re at the live edge, keep the stream in view. If they scroll away, leave them there.
3. **Every interaction is a signal.** Scrolling is not the only one. Selecting text, using the keyboard, opening a link, or searching should all stop the interface from moving.
4. **Start a new turn near the top of the viewport.** This gives the new turn somewhere it can be read from the beginning.
5. **Then stream in the answer.** The answer should grow into the screen, not immediately push everything away.
6. **Keep part of the previous conversation in context.** The prompt and reply should stay visually connected, and enough of the previous turn should remain visible so the reader knows where they are.
7. **Let new content arrive offscreen.** The conversation can keep streaming without changing what the reader is looking at.
8. **Show what’s happening out of view.** Make it clear when a response is still streaming or when new messages have arrived.
9. **Make it easy to return to the latest reply.** A “Jump to latest” action should bring the reader back and resume following.
10. **Let people jump anywhere in the conversation.** Long threads need message links, search, unread markers, and direct navigation.
11. **Reopen where the reader left off.** A saved conversation should open at the last meaningful turn. Often this is the last user message. Not the absolute bottom.
12. **Keep the reader’s place when layout changes.** Images load. Markdown expands. Code blocks render. Older messages appear above. None of that should make the reader lose their place.
13. **Handle interruptions without stealing position.** Stopping, retrying, regenerating, branching, or errors should not unexpectedly move the conversation.
14. **Stay responsive in long threads.** Streaming text, markdown, code, images, and long history should still feel responsive.
15. **Be accessible without the noise.** Keep the transcript navigable, preserve keyboard focus, and announce important events at a comfortable pace.

**Never move the reader against their intent.**

## MessageScroller

MessageScroller is a chat transcript scroller built for these behaviors.
`MessageScrollerProvider` owns the scroll state and transcript-row behavior:
opening position, streamed output, new-turn anchoring, prepended history,
visibility, and scroll controls. `MessageScroller` is the styled frame that
renders inside it.

MessageScroller is scoped to the scroll viewport. It does not own messages, AI state,
transport, persistence, branching, or model state. Your product code stays
focused on composing messages, markers, tools, attachments, and prompt inputs.

It gives you the scroll behavior that chat needs, without taking over the rest
of the chat UI. And it stays fast, even in long conversations with rich
markdown.

## Installation

```bash
bunx --bun shadcn@latest add @sui/message-scroller
```

Install with the shadcn CLI or use the shared `@workspace/ui` package. Follow the [installation guide](/docs/installation) to configure the registry, load styles, and choose import aliases.

## Usage

```tsx
import { Message } from "@workspace/ui/components/message"
import {
  MessageScroller,
  MessageScrollerButton,
  MessageScrollerContent,
  MessageScrollerItem,
  MessageScrollerProvider,
  MessageScrollerViewport,
} from "@workspace/ui/components/message-scroller"
```

```tsx
<MessageScrollerProvider>
  <MessageScroller>
    <MessageScrollerViewport>
      <MessageScrollerContent>
        {messages.map((message) => (
          <MessageScrollerItem
            key={message.id}
            messageId={message.id}
            scrollAnchor={message.role === "user"}
          >
            <Message />
          </MessageScrollerItem>
        ))}
      </MessageScrollerContent>
    </MessageScrollerViewport>
    <MessageScrollerButton />
  </MessageScroller>
</MessageScrollerProvider>
```

`MessageScroller` fills its parent, so place it inside a height-constrained
container.

```tsx
<div className="flex h-screen flex-col">
  <MessageScrollerProvider>
    <MessageScroller className="flex-1">{/* transcript */}</MessageScroller>
  </MessageScrollerProvider>
</div>
```

## Composition

```tsx
<MessageScrollerProvider>
  <MessageScroller>
    <MessageScrollerViewport>
      <MessageScrollerContent>
        <MessageScrollerItem>
          {/* a message, marker, or row */}
        </MessageScrollerItem>
        <MessageScrollerItem />
        <MessageScrollerItem />
      </MessageScrollerContent>
    </MessageScrollerViewport>
    <MessageScrollerButton />
  </MessageScroller>
</MessageScrollerProvider>
```

- **`MessageScrollerProvider`** — the headless root. Owns scroll state and the
  behavior props for opening position, auto-scroll, anchoring, scroll commands,
  and visibility tracking.
- **`MessageScroller`** — the styled frame. Lays out the viewport, content, and
  controls inside the provider.
- **`MessageScrollerViewport`** — the scrollable element. Receives native scroll
  events and preserves the visible row when older messages are prepended.
- **`MessageScrollerContent`** — the transcript container. Holds the rows and
  provides the live-region defaults for new messages.
- **`MessageScrollerItem`** — the transcript row boundary. Wrap every direct
  child of the content so the scroller can measure, anchor, preserve position,
  track visibility, and jump to it. An item can be a message, marker, typing
  indicator, separator, join/leave event, or "load earlier" row.
- **`MessageScrollerButton`** — the scroll control. Scrolls to the start or end of the transcript and is inert until there is content in its direction.

## Core Concepts

### Anchoring Turns

A turn is the part of the conversation that starts a new exchange. In a simple
AI chat, that is usually the user's message and the assistant reply that follows.

An anchor is the row the viewport should treat as the start of that turn. Mark
that row with `scrollAnchor`. When a new anchor is appended, the viewport moves
it near the top and keeps a peek of the previous item above it, so the new turn
does not feel detached from its context.

```tsx
// This tells the scroller to anchor the user's message for the next turn.
<MessageScrollerItem
  messageId={message.id}
  scrollAnchor={message.role === "user"}
/>
```

Scroll anchors are not tied to message role. You can turn any row into an anchor:
a user message, a system marker, a handoff event, or anything else that starts a
meaningful turn. `MessageScroller` only needs to know which row should anchor the
viewport.

In the following example, the user's message is anchored. When you send a new message, the viewport anchors it near the top and appends the assistant reply below it. Toggle the anchor to the assistant's message to see the difference.

### Example: message-scroller-anchoring

```tsx
"use client";

import { Button } from "@workspace/ui/components/button";
import {
  Card,
  CardAction,
  CardContent,
  CardDescription,
  CardFooter,
  CardHeader,
  CardTitle,
} from "@workspace/ui/components/card";
import {
  Empty,
  EmptyDescription,
  EmptyHeader,
  EmptyMedia,
  EmptyTitle,
} from "@workspace/ui/components/empty";
import {
  MessageScroller,
  MessageScrollerButton,
  MessageScrollerContent,
  MessageScrollerProvider,
  MessageScrollerViewport,
} from "@workspace/ui/components/message-scroller";
import {
  ToggleGroup,
  ToggleGroupItem,
} from "@workspace/ui/components/toggle-group";
import {
  ArrowUpIcon,
  MessageCircleDashedIcon,
  RotateCwIcon,
} from "lucide-react";
import * as React from "react";
import { MessageAnimated } from "../support/message-animated";

type AnchorRole = "user" | "assistant";

type ChatMessage = {
  id: string;
  role: AnchorRole;
  text: string;
};

const scriptedMessages: ChatMessage[] = [
  {
    id: "anchor-1-user",
    role: "user",
    text: "Can you show me how anchoring behaves when a new prompt starts the turn?",
  },
  {
    id: "anchor-1-assistant",
    role: "assistant",
    text: "Append the user prompt first, then append the assistant response. With User selected, the prompt settles near the top and the assistant response fills in below it.",
  },
  {
    id: "anchor-2-user",
    role: "user",
    text: "What changes when assistant messages are the anchor?",
  },
  {
    id: "anchor-2-assistant",
    role: "assistant",
    text: "Now each assistant response is the item `MessageScroller` keeps in view. This is useful when the reply is the moment you want readers to land on after each turn.",
  },
  {
    id: "anchor-3-user",
    role: "user",
    text: "Can I switch roles and keep adding turns?",
  },
  {
    id: "anchor-3-assistant",
    role: "assistant",
    text: "Yes. The next appended message with the selected role becomes the anchor, so you can compare user and assistant anchoring without resetting the demo.",
  },
];

export function MessageScrollerAnchoring() {
  const [anchorRole, setAnchorRole] = React.useState<AnchorRole>("user");
  const [messages, setMessages] = React.useState<ChatMessage[]>([]);
  const [messageIndex, setMessageIndex] = React.useState(0);
  const nextMessage = scriptedMessages[messageIndex];

  return (
    <div className="relative flex flex-col gap-4">
      <Card className="mx-auto h-140 w-full max-w-sm gap-0">
        <CardHeader className="border-b">
          <CardTitle>Anchoring Turns</CardTitle>
          <CardDescription>
            Choose which role settles near the top edge.
          </CardDescription>
          <CardAction>
            <Button
              type="button"
              variant="outline"
              size="icon"
              aria-label="Reset anchored turns"
              disabled={messages.length === 0}
              onClick={() => {
                setMessages([]);
                setMessageIndex(0);
              }}
            >
              <RotateCwIcon />
            </Button>
          </CardAction>
        </CardHeader>
        <CardContent className="min-h-0 flex-1 overflow-hidden p-0">
          {messages.length === 0 ? (
            <Empty className="h-full">
              <EmptyHeader>
                <EmptyMedia variant="icon">
                  <MessageCircleDashedIcon />
                </EmptyMedia>
                <EmptyTitle>No anchored messages yet</EmptyTitle>
                <EmptyDescription>
                  Send the first message to see the selected role anchor.
                </EmptyDescription>
              </EmptyHeader>
            </Empty>
          ) : (
            <MessageScrollerProvider>
              <MessageScroller>
                <MessageScrollerViewport>
                  <MessageScrollerContent className="p-(--card-spacing)">
                    {messages.map((message) => (
                      <MessageAnimated
                        key={message.id}
                        message={message}
                        scrollAnchor={message.role === anchorRole}
                        userVariant="muted"
                        assistantVariant="ghost"
                      />
                    ))}
                  </MessageScrollerContent>
                </MessageScrollerViewport>
                <MessageScrollerButton />
              </MessageScroller>
            </MessageScrollerProvider>
          )}
        </CardContent>
        <CardFooter>
          <ToggleGroup
            aria-label="Select scroll anchor role"
            value={[anchorRole]}
            onValueChange={(value) => {
              const nextValue = value[0];

              if (nextValue === "user" || nextValue === "assistant") {
                setAnchorRole(nextValue);
                setMessages([]);
                setMessageIndex(0);
              }
            }}
          >
            <ToggleGroupItem value="user" aria-label="Anchor user messages">
              User
            </ToggleGroupItem>
            <ToggleGroupItem
              value="assistant"
              aria-label="Anchor assistant messages"
            >
              Assistant
            </ToggleGroupItem>
          </ToggleGroup>
          <Button
            type="button"
            size="icon"
            className="ml-auto"
            disabled={!nextMessage}
            onClick={() => {
              if (!nextMessage) {
                return;
              }

              setMessages((messages) => [...messages, nextMessage]);
              setMessageIndex((index) => index + 1);
            }}
          >
            <ArrowUpIcon />
            <span className="sr-only">Send Message</span>
          </Button>
        </CardFooter>
      </Card>
      <div className="mx-auto max-w-xs px-0.5 text-center text-muted-foreground text-xs">
        Toggle the anchor role, then send messages to compare where turns
        settle.
      </div>
    </div>
  );
}

export default MessageScrollerAnchoring;
```

### Group Chat

In a group chat, the turn boundary is more specific than "the user message". It is often
the message that asks the model to respond, or a marker like "Marcus joined the
chat". Typing indicators and history controls usually should not anchor.

Because anchoring is role-independent, you can anchor a marker just as easily as
a message.

```tsx
<MessageScrollerItem messageId="marcus-joined" scrollAnchor>
  <Marker variant="separator">
    <MarkerContent>Marcus joined the chat</MarkerContent>
  </Marker>
</MessageScrollerItem>
```

### Example: message-scroller-group-chat

```tsx
"use client";

import { Bubble, BubbleContent } from "@workspace/ui/components/bubble";
import { Button } from "@workspace/ui/components/button";
import {
  Card,
  CardAction,
  CardContent,
  CardDescription,
  CardFooter,
  CardHeader,
  CardTitle,
} from "@workspace/ui/components/card";
import { Marker, MarkerContent } from "@workspace/ui/components/marker";
import {
  Message,
  MessageContent,
  MessageHeader,
} from "@workspace/ui/components/message";
import {
  MessageScroller,
  MessageScrollerButton,
  MessageScrollerContent,
  MessageScrollerItem,
  MessageScrollerProvider,
  MessageScrollerViewport,
} from "@workspace/ui/components/message-scroller";
import {
  Tooltip,
  TooltipContent,
  TooltipTrigger,
} from "@workspace/ui/components/tooltip";
import { RotateCwIcon } from "lucide-react";
import * as React from "react";

const currentUser = "Grace";

const initialItems = [
  {
    id: "group-1",
    type: "message",
    sender: "Grace",
    role: "participant",
    text: "@mary, the astrophage line keeps matching Venus energy output. Can you check my math?",
  },
  {
    id: "group-2",
    type: "message",
    sender: "Mary (Agent)",
    role: "assistant",
    text: "Yes. Confirmed. The curve points to a microorganism harvesting stellar energy and breeding near carbon dioxide. If @rocky agrees, this is the clue we need.",
  },
  {
    id: "group-3",
    type: "message",
    sender: "Grace",
    role: "participant",
    text: "ping @rocky",
    scrollAnchor: true,
  },
] satisfies GroupChatItem[];

const rockyMarker = {
  id: "group-4",
  type: "event",
  text: "Rocky has joined the chat",
  scrollAnchor: true,
} satisfies GroupChatItem;

const rockyMessage = {
  id: "group-5",
  type: "message",
  sender: "Rocky",
  role: "participant",
  text: "Amaze. Astrophage eats light, makes heat, goes to carbon dioxide. Rocky has fuel model. Grace is smart.",
} satisfies GroupChatItem;

type GroupChatItem =
  | {
      id: string;
      type: "event";
      text: string;
      scrollAnchor?: boolean;
    }
  | {
      id: string;
      type: "message";
      sender: string;
      role: "assistant" | "participant";
      text: string;
      scrollAnchor?: boolean;
    };

export function MessageScrollerGroupChat() {
  const [demoKey, setDemoKey] = React.useState(0);
  const [rockyTurn, setRockyTurn] = React.useState<
    "idle" | "marker" | "message"
  >("idle");
  let items: GroupChatItem[] = initialItems;
  if (rockyTurn === "message")
    items = [...initialItems, rockyMarker, rockyMessage];
  else if (rockyTurn === "marker") items = [...initialItems, rockyMarker];
  const buttonLabel =
    rockyTurn === "idle" ? "Add Rocky" : "Send Message as Rocky";
  const isComplete = rockyTurn === "message";

  return (
    <MessageScrollerProvider>
      <div className="relative flex flex-col gap-4">
        <Card className="mx-auto h-140 w-full max-w-sm gap-0">
          <CardHeader className="gap-1 border-b">
            <CardTitle>Group Chat</CardTitle>
            <CardDescription>
              A group chat with several participants and an assistant. The
              Marker is marked as a turn.
            </CardDescription>
            <CardAction>
              <Tooltip>
                <TooltipTrigger
                  render={
                    <Button
                      type="button"
                      variant="outline"
                      size="icon"
                      aria-label="Reset conversation"
                      disabled={rockyTurn === "idle"}
                      onClick={() => {
                        setRockyTurn("idle");
                        setDemoKey((key) => key + 1);
                      }}
                    />
                  }
                >
                  <RotateCwIcon />
                </TooltipTrigger>
                <TooltipContent>
                  <p>Reset</p>
                </TooltipContent>
              </Tooltip>
            </CardAction>
          </CardHeader>
          <CardContent className="min-h-0 flex-1 p-0">
            <MessageScrollerProvider>
              <MessageScroller key={demoKey}>
                <MessageScrollerViewport>
                  <MessageScrollerContent className="p-(--card-spacing)">
                    {items.map((item) =>
                      item.type === "message" ? (
                        <GroupChatMessage key={item.id} item={item} />
                      ) : (
                        <GroupChatMarker
                          key={item.id}
                          item={item}
                          scrollAnchor={item.scrollAnchor}
                        />
                      ),
                    )}
                  </MessageScrollerContent>
                </MessageScrollerViewport>
                <MessageScrollerButton />
              </MessageScroller>
            </MessageScrollerProvider>
          </CardContent>
          <CardFooter className="flex flex-col items-center gap-2 border-t">
            <Button
              type="button"
              disabled={isComplete}
              onClick={() =>
                setRockyTurn((turn) => (turn === "idle" ? "marker" : "message"))
              }
              className="w-full"
              variant="secondary"
            >
              {buttonLabel}
            </Button>
            <p className="text-muted-foreground text-xs">
              {rockyTurn === "idle"
                ? "This will create a marker and make it the anchor"
                : "Now send Rocky's reply into the conversation"}
            </p>
          </CardFooter>
        </Card>
        <div className="mx-auto max-w-sm text-balance px-0.5 text-center text-muted-foreground text-xs">
          When a user joins, a marker is created. scrollAnchor on the marker
          marks it as the next turn
        </div>
      </div>
    </MessageScrollerProvider>
  );
}

function GroupChatMessage({
  item,
}: {
  item: Extract<GroupChatItem, { type: "message" }>;
}) {
  const isCurrentUser = item.sender === currentUser;
  const roleVariant = item.role === "assistant" ? "ghost" : "tinted";
  const variant = isCurrentUser ? "muted" : roleVariant;

  return (
    <MessageScrollerItem messageId={item.id} scrollAnchor={item.scrollAnchor}>
      <Message align={isCurrentUser ? "end" : "start"}>
        <MessageContent>
          {!isCurrentUser && <MessageHeader>{item.sender}</MessageHeader>}
          <Bubble variant={variant}>
            <BubbleContent>{item.text}</BubbleContent>
          </Bubble>
        </MessageContent>
      </Message>
    </MessageScrollerItem>
  );
}

function GroupChatMarker({
  item,
  scrollAnchor = false,
}: {
  item: Extract<GroupChatItem, { type: "event" }>;
  scrollAnchor?: boolean;
}) {
  return (
    <MessageScrollerItem scrollAnchor={scrollAnchor}>
      <Marker variant="separator">
        <MarkerContent>{item.text}</MarkerContent>
      </Marker>
    </MessageScrollerItem>
  );
}

export default MessageScrollerGroupChat;
```

### Keeping Context Visible

When a new turn starts, it should still feel like part of the same continuous
thread. `scrollPreviousItemPeek` keeps a slice of the previous item visible
above the anchor, so the reader keeps their context instead of feeling like the
conversation restarted on a blank page.

```tsx
// Keep 64px of the previous turn visible above the newly anchored row.
<MessageScrollerProvider scrollPreviousItemPeek={64}>
  <MessageScroller>{/* anchored turns */}</MessageScroller>
</MessageScrollerProvider>
```

Adjust the peek amount in the example below to see how it affects the conversation.

### Example: message-scroller-previous-context

```tsx
"use client";

import { useChat } from "@ai-sdk/react";
import { Button } from "@workspace/ui/components/button";
import {
  Card,
  CardAction,
  CardContent,
  CardDescription,
  CardFooter,
  CardHeader,
  CardTitle,
} from "@workspace/ui/components/card";
import {
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuItem,
  DropdownMenuSeparator,
  DropdownMenuTrigger,
} from "@workspace/ui/components/dropdown-menu";
import {
  InputGroup,
  InputGroupAddon,
  InputGroupButton,
} from "@workspace/ui/components/input-group";
import {
  MessageScroller,
  MessageScrollerButton,
  MessageScrollerContent,
  MessageScrollerProvider,
  MessageScrollerViewport,
} from "@workspace/ui/components/message-scroller";
import { Slider } from "@workspace/ui/components/slider";
import {
  Tooltip,
  TooltipContent,
  TooltipTrigger,
} from "@workspace/ui/components/tooltip";
import {
  ArrowUpIcon,
  GlobeIcon,
  ImageIcon,
  PaperclipIcon,
  PlusIcon,
  RotateCwIcon,
  TelescopeIcon,
} from "lucide-react";
import * as React from "react";
import { createChat, getMessageText } from "../support/ai";
import { MessageAnimated } from "../support/message-animated";

const DEFAULT_PEEK = 64;

const chat = createChat()
  .user(
    "I'm building a chat for our app and the scroll behavior is driving me nuts. Every time the AI streams a reply, the whole thread jumps around.",
  )
  .sleep(1000)
  .assistant(
    "That's the classic streaming scroll problem. Wrap your message list in `MessageScroller` and turn on `autoScroll` — the viewport pins to the bottom as tokens arrive, so users always see the latest text land in place.\n\nThe important part: it only auto-scrolls while the reader is already at the bottom. The moment they scroll up to read something earlier, auto-scroll backs off and their position is preserved. You get smooth streaming without fighting the user's intent.",
  )
  .user(
    "Okay, but when someone sends a new message the view still feels jarring — like the whole conversation reloads from the top.",
  )
  .sleep(1000)
  .assistant(
    "MessageScrollerItem fixes that with turn anchoring. Set `scrollAnchor` on the turn that should settle near the top instead of blindly snapping to the document bottom.\n\nIt also leaves a small peek of the previous exchange visible above the anchor, so context isn't lost. The reply starts in view without that disorienting jump you get from a plain overflow container.",
  )
  .user(
    "And if they've scrolled up to re-read an older answer? I don't want to yank them back down.",
  )
  .sleep(1000)
  .assistant(
    "You won't. Auto-scroll only runs when the viewport is already pinned to the bottom, so scrolling up is a deliberate opt-out — their place in the thread stays put even as new tokens keep arriving below.\n\nWhen there is content they haven't seen yet, `MessageScrollerButton` appears at the bottom of the viewport. One tap jumps them back to the newest message and re-engages auto-scroll. Same pattern as Slack or iMessage: quiet when you're caught up, helpful when you're not.",
  )
  .user("Last one — does this work with assistive tech?")
  .sleep(1000)
  .assistant(
    '`MessageScrollerContent` sets `role="log"` and `aria-relevant="additions"` by default, so screen readers announce new messages as they stream in.\n\nThe scroll button is a real `<button>` with an sr-only label, and it\'s removed from the tab order when you\'re already at the bottom — no ghost focus stops.',
  );
const initialMessages = chat.get(2);
const transport = chat.transport({ delayMs: 35 });

export function MessageScrollerPreviousContext() {
  const [demoKey, setDemoKey] = React.useState(0);
  const [peek, setPeek] = React.useState(DEFAULT_PEEK);
  const { messages, sendMessage, setMessages, status } = useChat({
    messages: initialMessages,
    transport,
  });
  const nextMessage = chat.next(messages);
  const isBusy = status === "submitted" || status === "streaming";

  return (
    <MessageScrollerProvider
      key={demoKey}
      scrollMargin={24}
      scrollPreviousItemPeek={peek}
    >
      <div className="relative flex flex-col gap-4">
        <Card className="mx-auto h-140 w-full max-w-sm gap-0">
          <CardHeader className="gap-1 border-b">
            <CardTitle>Keeping Context Visible</CardTitle>
            <CardDescription>
              New turns keep part of the previous reply in view.
            </CardDescription>
            <CardAction>
              <Tooltip>
                <TooltipTrigger
                  render={
                    <Button
                      variant="outline"
                      size="icon"
                      aria-label="Reset context example"
                      disabled={isBusy}
                      onClick={() => {
                        setMessages(initialMessages);
                        setPeek(DEFAULT_PEEK);
                        setDemoKey((key) => key + 1);
                      }}
                    />
                  }
                >
                  <RotateCwIcon />
                </TooltipTrigger>
                <TooltipContent>
                  <p>Reset</p>
                </TooltipContent>
              </Tooltip>
            </CardAction>
          </CardHeader>
          <CardContent className="flex-1 overflow-hidden p-0">
            <MessageScroller>
              <MessageScrollerViewport>
                <MessageScrollerContent
                  aria-busy={isBusy}
                  className="p-(--card-spacing)"
                >
                  {messages.map((message) => (
                    <MessageAnimated
                      key={message.id}
                      message={message}
                      scrollAnchor={message.role === "user"}
                    />
                  ))}
                </MessageScrollerContent>
              </MessageScrollerViewport>
              <MessageScrollerButton />
            </MessageScroller>
          </CardContent>
          <CardFooter className="flex-col gap-2">
            <form
              onSubmit={(e) => {
                e.preventDefault();
                if (!nextMessage || isBusy) {
                  return;
                }
                void sendMessage(nextMessage);
              }}
              className="w-full"
            >
              <InputGroup>
                <div className="h-14 w-full px-3 py-2.5">
                  <span
                    className="line-clamp-2 opacity-60 data-[status=ready]:opacity-100"
                    data-status={status}
                  >
                    {nextMessage ? (
                      getMessageText(nextMessage)
                    ) : (
                      <span className="text-muted-foreground">
                        No messages queued. Reset the context.
                      </span>
                    )}
                  </span>
                </div>
                <InputGroupAddon align="block-end" className="pt-1">
                  <DropdownMenu>
                    <DropdownMenuTrigger
                      render={
                        <InputGroupButton
                          aria-label="Add files"
                          type="button"
                          size="icon-sm"
                          variant="outline"
                        />
                      }
                    >
                      <PlusIcon />
                    </DropdownMenuTrigger>
                    <DropdownMenuContent
                      align="start"
                      side="top"
                      className="w-44"
                    >
                      <DropdownMenuItem>
                        <PaperclipIcon />
                        Add Photos & Files
                      </DropdownMenuItem>
                      <DropdownMenuSeparator />
                      <DropdownMenuItem>
                        <ImageIcon />
                        Create Image
                      </DropdownMenuItem>
                      <DropdownMenuItem>
                        <TelescopeIcon />
                        Deep Research
                      </DropdownMenuItem>
                      <DropdownMenuItem>
                        <GlobeIcon />
                        Web Search
                      </DropdownMenuItem>
                    </DropdownMenuContent>
                  </DropdownMenu>
                  <div className="flex w-28 items-center gap-2">
                    <span className="text-muted-foreground text-xs tabular-nums">
                      {peek}px
                    </span>
                    <Slider
                      aria-label="Previous context peek"
                      value={[peek]}
                      min={64}
                      max={128}
                      step={1}
                      disabled={isBusy}
                      onValueChange={(value) => {
                        const nextValue = Array.isArray(value)
                          ? value[0]
                          : value;

                        setPeek(nextValue ?? DEFAULT_PEEK);
                      }}
                    />
                  </div>
                  <InputGroupButton
                    type="submit"
                    variant="default"
                    size="icon-sm"
                    disabled={!nextMessage || isBusy}
                    className="ml-auto"
                  >
                    <ArrowUpIcon />
                    <span className="sr-only">Send</span>
                  </InputGroupButton>
                </InputGroupAddon>
              </InputGroup>
            </form>
          </CardFooter>
        </Card>
        <div className="px-0.5 text-center text-muted-foreground text-xs">
          Adjust the slider and send. Observe the previous message peak
        </div>
      </div>
    </MessageScrollerProvider>
  );
}

export default MessageScrollerPreviousContext;
```

### Following the Live Edge

When the reader is at the live edge, either because they stayed there or
returned there, `autoScroll` keeps streamed replies in view as they grow.
Scrolling away from the live edge releases the view, whether by wheel, touch,
keyboard scroll keys, or dragging the scrollbar. An explicit message jump
releases it too. New chunks can then arrive without moving the reader.

`autoScroll` composes with turn anchoring. When a new turn anchors near the
top, the view stays put while the reply streams into the room below it. Once
the reply fills the viewport, the reader is back at the live edge and
follow-output takes over from the anchor.

```tsx
<MessageScrollerProvider autoScroll>
  <MessageScroller>{/* streamed turns */}</MessageScroller>
</MessageScrollerProvider>
```

### Example: message-scroller-streaming

```tsx
"use client";

import { useChat } from "@ai-sdk/react";
import { Button } from "@workspace/ui/components/button";
import {
  Card,
  CardAction,
  CardContent,
  CardDescription,
  CardFooter,
  CardHeader,
  CardTitle,
} from "@workspace/ui/components/card";
import {
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuItem,
  DropdownMenuSeparator,
  DropdownMenuTrigger,
} from "@workspace/ui/components/dropdown-menu";
import {
  Empty,
  EmptyDescription,
  EmptyHeader,
  EmptyMedia,
  EmptyTitle,
} from "@workspace/ui/components/empty";
import {
  InputGroup,
  InputGroupAddon,
  InputGroupButton,
} from "@workspace/ui/components/input-group";
import {
  MessageScroller,
  MessageScrollerButton,
  MessageScrollerContent,
  MessageScrollerProvider,
  MessageScrollerViewport,
} from "@workspace/ui/components/message-scroller";
import {
  Tooltip,
  TooltipContent,
  TooltipTrigger,
} from "@workspace/ui/components/tooltip";
import {
  ArrowUpIcon,
  GlobeIcon,
  ImageIcon,
  MessageCircleDashedIcon,
  PaperclipIcon,
  PlusIcon,
  RotateCwIcon,
  TelescopeIcon,
} from "lucide-react";
import { createChat, getMessageText } from "../support/ai";
import { MessageAnimated } from "../support/message-animated";

const chat = createChat()
  .user(
    "I'm building a chat for our app and the scroll behavior is driving me nuts. Every time the AI streams a reply, the whole thread jumps around.",
  )
  .sleep(1000)
  .assistant(
    "That's the classic streaming scroll problem. Wrap your message list in `MessageScroller` and turn on `autoScroll` — the viewport pins to the bottom as tokens arrive, so users always see the latest text land in place.\n\nThe important part: it only auto-scrolls while the reader is already at the bottom. The moment they scroll up to read something earlier, auto-scroll backs off and their position is preserved. You get smooth streaming without fighting the user's intent.",
  )
  .user(
    "Okay, but when someone sends a new message the view still feels jarring — like the whole conversation reloads from the top.",
  )
  .sleep(1000)
  .assistant(
    "MessageScrollerItem fixes that with turn anchoring. Set `scrollAnchor` on the turn that should settle near the top instead of blindly snapping to the document bottom.\n\nIt also leaves a small peek of the previous exchange visible above the anchor, so context isn't lost. The reply starts in view without that disorienting jump you get from a plain overflow container.",
  )
  .user(
    "And if they've scrolled up to re-read an older answer? I don't want to yank them back down.",
  )
  .sleep(1000)
  .assistant(
    "You won't. Auto-scroll only runs when the viewport is already pinned to the bottom, so scrolling up is a deliberate opt-out — their place in the thread stays put even as new tokens keep arriving below.\n\nWhen there is content they haven't seen yet, `MessageScrollerButton` appears at the bottom of the viewport. One tap jumps them back to the newest message and re-engages auto-scroll. Same pattern as Slack or iMessage: quiet when you're caught up, helpful when you're not.",
  )
  .user("Last one — does this work with assistive tech?")
  .sleep(1000)
  .assistant(
    '`MessageScrollerContent` sets `role="log"` and `aria-relevant="additions"` by default, so screen readers announce new messages as they stream in.\n\nThe scroll button is a real `<button>` with an sr-only label, and it\'s removed from the tab order when you\'re already at the bottom — no ghost focus stops.',
  );
const initialMessages = chat.get(0);
const transport = chat.transport({ delayMs: 20 });

export function MessageScrollerStreaming() {
  const { messages, sendMessage, setMessages, status } = useChat({
    messages: initialMessages,
    transport,
  });
  const nextMessage = chat.next(messages);
  const isBusy = status === "submitted" || status === "streaming";

  return (
    <MessageScrollerProvider autoScroll>
      <div className="relative flex flex-col gap-4">
        <Card className="mx-auto h-140 w-full max-w-sm gap-0">
          <CardHeader className="gap-1 border-b">
            <CardTitle>Streaming Messages</CardTitle>
            <CardDescription>
              Auto-scroll follows the live edge of the conversation.
            </CardDescription>
            <CardAction>
              <Tooltip>
                <TooltipTrigger
                  render={
                    <Button
                      variant="outline"
                      size="icon"
                      aria-label="Reset stream"
                      onClick={() => setMessages(initialMessages)}
                      disabled={messages.length === 0 || isBusy}
                    />
                  }
                >
                  <RotateCwIcon />
                </TooltipTrigger>
                <TooltipContent>
                  <p>Reset</p>
                </TooltipContent>
              </Tooltip>
            </CardAction>
          </CardHeader>
          <CardContent className="flex-1 overflow-hidden p-0">
            {messages.length === 0 ? (
              <Empty className="h-full">
                <EmptyHeader>
                  <EmptyMedia variant="icon">
                    <MessageCircleDashedIcon />
                  </EmptyMedia>
                  <EmptyTitle>Ready to Stream</EmptyTitle>
                  <EmptyDescription>
                    Press send to stream a scripted launch summary.
                  </EmptyDescription>
                </EmptyHeader>
              </Empty>
            ) : (
              <MessageScroller>
                <MessageScrollerViewport>
                  <MessageScrollerContent
                    aria-busy={isBusy}
                    className="p-(--card-spacing)"
                  >
                    {messages.map((message) => (
                      <MessageAnimated
                        key={message.id}
                        message={message}
                        scrollAnchor={message.role === "user"}
                      />
                    ))}
                  </MessageScrollerContent>
                </MessageScrollerViewport>
                <MessageScrollerButton />
              </MessageScroller>
            )}
          </CardContent>
          <CardFooter className="flex-col gap-2">
            <form
              onSubmit={(e) => {
                e.preventDefault();
                if (!nextMessage || isBusy) {
                  return;
                }
                void sendMessage(nextMessage);
              }}
              className="w-full"
            >
              <InputGroup>
                <div className="h-14 w-full px-3 py-2.5">
                  <span
                    className="line-clamp-2 opacity-60 data-[status=ready]:opacity-100"
                    data-status={status}
                  >
                    {nextMessage ? (
                      getMessageText(nextMessage)
                    ) : (
                      <span className="text-muted-foreground">
                        No messages queued. Reset the stream.
                      </span>
                    )}
                  </span>
                </div>
                <InputGroupAddon align="block-end" className="pt-1">
                  <DropdownMenu>
                    <DropdownMenuTrigger
                      render={
                        <InputGroupButton
                          aria-label="Add files"
                          type="button"
                          size="icon-sm"
                          variant="outline"
                        />
                      }
                    >
                      <PlusIcon />
                    </DropdownMenuTrigger>
                    <DropdownMenuContent
                      align="start"
                      side="top"
                      className="w-44"
                    >
                      <DropdownMenuItem>
                        <PaperclipIcon />
                        Add Photos & Files
                      </DropdownMenuItem>
                      <DropdownMenuSeparator />
                      <DropdownMenuItem>
                        <ImageIcon />
                        Create Image
                      </DropdownMenuItem>
                      <DropdownMenuItem>
                        <TelescopeIcon />
                        Deep Research
                      </DropdownMenuItem>
                      <DropdownMenuItem>
                        <GlobeIcon />
                        Web Search
                      </DropdownMenuItem>
                    </DropdownMenuContent>
                  </DropdownMenu>
                  <InputGroupButton
                    type="submit"
                    variant="default"
                    size="icon-sm"
                    disabled={!nextMessage || isBusy}
                    className="ml-auto"
                  >
                    <ArrowUpIcon />
                    <span className="sr-only">Send</span>
                  </InputGroupButton>
                </InputGroupAddon>
              </InputGroup>
            </form>
          </CardFooter>
        </Card>
        <div className="px-0.5 text-center text-muted-foreground text-xs">
          Streaming is simulated. `autoScroll` is enabled.
        </div>
      </div>
    </MessageScrollerProvider>
  );
}

export default MessageScrollerStreaming;
```

Calling `scrollToEnd`, or pressing `MessageScrollerButton`, re-engages
follow-output when `autoScroll` is enabled, so a reader who scrolled away can
return to the live edge and keep following. The root and viewport expose
`data-autoscrolling` while that programmatic scroll to the latest message runs,
so you can conditionally apply styles during the transition.

### Opening Saved Threads

It can seem reasonable to reopen a saved thread at the absolute end of the
transcript, but that often drops the reader into the conversation without enough
context. A better default is `"last-anchor"`: show the last meaningful turn,
like the user's latest message, with the reply below it.

That gives the reader an immediate place in the thread. They can see what they
asked, where the answer starts, and continue from there without reconstructing
the conversation from the bottom edge.

```tsx
<MessageScrollerProvider defaultScrollPosition="last-anchor">
  <MessageScroller>{/* transcript */}</MessageScroller>
</MessageScrollerProvider>
```

### Example: message-scroller-opening-position

```tsx
// biome-ignore-all lint/suspicious/noArrayIndexKey: The upstream gallery uses fixed positional fixtures that never reorder.

"use client";

import { Bubble, BubbleContent } from "@workspace/ui/components/bubble";
import {
  Card,
  CardContent,
  CardDescription,
  CardFooter,
  CardHeader,
  CardTitle,
} from "@workspace/ui/components/card";
import { Message, MessageContent } from "@workspace/ui/components/message";
import {
  MessageScroller,
  MessageScrollerButton,
  MessageScrollerContent,
  MessageScrollerItem,
  MessageScrollerProvider,
  MessageScrollerViewport,
  useMessageScroller,
} from "@workspace/ui/components/message-scroller";
import { Tabs, TabsList, TabsTrigger } from "@workspace/ui/components/tabs";
import * as React from "react";

const messages = [
  {
    id: "open-1",
    role: "user",
    text: "This is the first message the user sent in the conversation.",
  },
  {
    id: "open-2",
    role: "assistant",
    text: "Workspace creation rose 8%, but first invite completion only rose 2%.",
  },
  {
    id: "open-3",
    role: "user",
    text: "This is the last message the user sent in the conversation.",
  },
  {
    id: "open-4",
    role: "assistant",
    text: "Start with the invite step. Teams are creating workspaces but waiting to add collaborators.\n\nRecommended follow-up:\n\n1. Compare invite drop-off by account size.\n2. Check whether users who skip invites still return within 24 hours.\n3. Review the empty-state copy on the first project screen.\n4. Segment activation by template, since template users may not need invites right away.\n\nIf that pattern holds, the next experiment should make collaboration useful earlier instead of prompting for invites harder.",
  },
] satisfies Array<{
  id: string;
  role: "user" | "assistant";
  text: string;
}>;

const positions = [
  { value: "start", label: "start" },
  { value: "end", label: "end" },
  { value: "last-anchor", label: "last-anchor" },
] satisfies Array<{
  value: "start" | "end" | "last-anchor";
  label: string;
}>;

export function MessageScrollerOpeningPosition() {
  const [positionKey, setPositionKey] = React.useState(0);
  const [position, setPosition] = React.useState<
    "start" | "end" | "last-anchor"
  >("last-anchor");

  return (
    <div className="relative flex flex-col gap-4">
      <Card className="mx-auto h-140 w-full max-w-sm gap-0">
        <CardHeader className="gap-1 border-b">
          <CardTitle>Opening Position</CardTitle>
          <CardDescription>
            Choose where a saved transcript opens.
          </CardDescription>
        </CardHeader>
        <CardContent className="flex-1 overflow-hidden p-0">
          <MessageScrollerProvider>
            <OpeningPositionScroller
              position={position}
              positionKey={positionKey}
            />
          </MessageScrollerProvider>
        </CardContent>
        <CardFooter className="flex items-center justify-center border-t">
          <Tabs
            value={position}
            onValueChange={(value) => {
              if (
                value === "start" ||
                value === "end" ||
                value === "last-anchor"
              ) {
                setPosition(value);
                setPositionKey((key) => key + 1);
              }
            }}
            className="w-full"
          >
            <TabsList className="w-full">
              {positions.map((option) => (
                <TabsTrigger key={option.value} value={option.value}>
                  {option.label}
                </TabsTrigger>
              ))}
            </TabsList>
          </Tabs>
        </CardFooter>
      </Card>
      <div className="mx-auto max-w-sm px-0.5 text-center text-muted-foreground text-xs">
        Toggle the defaultScrollPosition to see where the transcript starts when
        you open the thread
      </div>
    </div>
  );
}

function OpeningPositionScroller({
  position,
  positionKey,
}: {
  position: "start" | "end" | "last-anchor";
  positionKey: number;
}) {
  const { scrollToEnd, scrollToMessage, scrollToStart } = useMessageScroller();

  React.useLayoutEffect(() => {
    // The replay key intentionally restarts the same opening scroll position.
    void positionKey;
    const frame = requestAnimationFrame(() => {
      if (position === "start") {
        scrollToStart({ behavior: "auto" });
        return;
      }

      if (position === "end") {
        scrollToEnd({ behavior: "auto" });
        return;
      }

      scrollToMessage("open-3", {
        align: "start",
        behavior: "auto",
        scrollMargin: 64,
      });
    });

    return () => {
      cancelAnimationFrame(frame);
    };
  }, [position, positionKey, scrollToEnd, scrollToMessage, scrollToStart]);

  return (
    <MessageScroller>
      <MessageScrollerViewport>
        <MessageScrollerContent className="p-(--card-spacing)">
          {messages.map((message) => {
            const isUserMessage = message.role === "user";

            return (
              <MessageScrollerItem
                key={message.id}
                messageId={message.id}
                scrollAnchor={isUserMessage}
              >
                <Message align={isUserMessage ? "end" : "start"}>
                  <MessageContent>
                    <Bubble variant={isUserMessage ? "muted" : "ghost"}>
                      <BubbleContent className="space-y-2">
                        {message.text
                          .split(/\n\s*\n/)
                          .map((paragraph) => paragraph.trim())
                          .filter(Boolean)
                          .map((paragraph, index) => (
                            <p key={index} className="whitespace-pre-wrap">
                              {paragraph}
                            </p>
                          ))}
                      </BubbleContent>
                    </Bubble>
                  </MessageContent>
                </Message>
              </MessageScrollerItem>
            );
          })}
        </MessageScrollerContent>
      </MessageScrollerViewport>
      <MessageScrollerButton />
    </MessageScroller>
  );
}

export default MessageScrollerOpeningPosition;
```

`"last-anchor"` is keyed on `scrollAnchor`, not message role. If no anchor
exists, or the last anchored turn already fits in the viewport, it falls back to
`"end"`.

Use `"start"` when you want to resume at the beginning of a conversation, or
`"end"` when the absolute latest message is the right place to land.

### Avoiding a Flash on Reload

A scroll container always opens at the top. HTML has no way to set `scrollTop`,
so a server-rendered transcript shows the oldest messages first. After
JavaScript runs, `defaultScrollPosition` moves the view, and you see a jump.

When `defaultScrollPosition` is `"end"` or `"last-anchor"`, the viewport has
`data-pending-scroll` until that position is applied. The styled viewport stays
hidden while the attribute is present, so you see the frame instead of the jump.
`"start"` does not need this.

If you want `"end"` visible on first paint, add an inline script right after the
viewport. Give the viewport an `id`, scroll it to the bottom, and remove
`data-pending-scroll`.

```tsx
const scrollToEndScript = `(function () {
  var viewport = document.getElementById("messages")
  if (!viewport) {
    return
  }
  viewport.scrollTop = viewport.scrollHeight
  viewport.removeAttribute("data-pending-scroll")
})()`

<MessageScroller>
  <MessageScrollerViewport id="messages" suppressHydrationWarning>
    <MessageScrollerContent>{/* transcript */}</MessageScrollerContent>
  </MessageScrollerViewport>
  <script dangerouslySetInnerHTML={{ __html: scrollToEndScript }} />
  <MessageScrollerButton />
</MessageScroller>
```

Put the script in your page, not in the scroller. It only works for `"end"`, and
only when the messages are already in the HTML. Add `suppressHydrationWarning` on
the viewport. If you use a Content Security Policy, pass a `nonce`.

Do not use this script with `"last-anchor"`. Skip it when messages load on the
client.

### Loading Earlier Messages

Loading earlier messages should not move the conversation the reader is already
looking at. When older rows are prepended above the current transcript,
`MessageScrollerViewport` preserves the visible row so the reader stays in the
same place while history loads above them.

This is enabled by default through `preserveScrollOnPrepend`.

### Example: message-scroller-load-history

```tsx
// biome-ignore-all lint/suspicious/noArrayIndexKey: The upstream gallery uses append-only positional paragraph fixtures.

"use client";

import { Bubble, BubbleContent } from "@workspace/ui/components/bubble";
import { Button } from "@workspace/ui/components/button";
import {
  Card,
  CardAction,
  CardContent,
  CardDescription,
  CardFooter,
  CardHeader,
  CardTitle,
} from "@workspace/ui/components/card";
import { Marker, MarkerContent } from "@workspace/ui/components/marker";
import { Message, MessageContent } from "@workspace/ui/components/message";
import {
  MessageScroller,
  MessageScrollerButton,
  MessageScrollerContent,
  MessageScrollerItem,
  MessageScrollerProvider,
  MessageScrollerViewport,
} from "@workspace/ui/components/message-scroller";
import { toast } from "@workspace/ui/components/toast";
import {
  Tooltip,
  TooltipContent,
  TooltipTrigger,
} from "@workspace/ui/components/tooltip";
import { RotateCwIcon } from "lucide-react";
import * as React from "react";
import { createChat, getMessageText } from "../support/ai";

const chat = createChat()
  .user("Can you summarize the incident channel?")
  .assistant(
    "The first alert was a delayed export job. It started backing up around 09:42 UTC and triggered the warning once the retry queue crossed the threshold.\n\nNo customer-facing checkout paths were affected, but exports for larger workspaces were running about 12 minutes behind.",
  )
  .user("Was checkout affected?")
  .assistant(
    "No checkout errors were reported. Payment authorization, order creation, and confirmation emails stayed inside their normal latency bands.\n\nThe only elevated metric was export queue depth, which maps to analytics downloads instead of checkout.",
  )
  .user("What changed in the last deploy?")
  .assistant(
    "Only the export queue worker changed. The deploy moved large CSV jobs onto the shared retry policy, which made each failed attempt hold a worker slot longer than before.\n\nThe app deploy did not include checkout, pricing, or billing API changes.",
  )
  .user("Do we need to roll back?")
  .assistant(
    "Not yet. Queue depth is recovering after we reduced retry concurrency, and the oldest pending job is now under five minutes old.\n\nKeep rollback ready if the queue starts climbing again, but the current trend points toward recovery.",
  )
  .user("Keep watching for customer-visible issues.")
  .assistant(
    "I will watch the queue and support tags for another 15 minutes. I am tracking export failures, delayed download requests, and any support thread that mentions missing reports.\n\nIf those stay quiet through the next batch window, we can close this as an internal degradation.",
  );

const history = chat.get();
const INITIAL_VISIBLE_COUNT = 5;

export function MessageScrollerLoadHistory() {
  const [demoKey, setDemoKey] = React.useState(0);
  const [visibleCount, setVisibleCount] = React.useState(INITIAL_VISIBLE_COUNT);
  const visibleMessages = history.slice(-visibleCount);
  const canLoadHistory = visibleCount < history.length;

  return (
    <MessageScrollerProvider>
      <div className="relative flex flex-col gap-4">
        <Card className="mx-auto h-140 w-full max-w-sm gap-0">
          <CardHeader className="gap-1 border-b">
            <CardTitle>Load History</CardTitle>
            <CardDescription>
              Prepended messages keep your place.
            </CardDescription>
            <CardAction>
              <Tooltip>
                <TooltipTrigger
                  render={
                    <Button
                      type="button"
                      variant="outline"
                      size="icon"
                      aria-label="Reset loaded messages"
                      disabled={visibleCount === INITIAL_VISIBLE_COUNT}
                      onClick={() => {
                        setVisibleCount(INITIAL_VISIBLE_COUNT);
                        setDemoKey((key) => key + 1);
                      }}
                    />
                  }
                >
                  <RotateCwIcon />
                </TooltipTrigger>
                <TooltipContent>
                  <p>Reset</p>
                </TooltipContent>
              </Tooltip>
            </CardAction>
          </CardHeader>
          <CardContent className="flex-1 overflow-hidden p-0">
            <MessageScroller key={demoKey}>
              <MessageScrollerViewport>
                <MessageScrollerContent className="p-(--card-spacing)">
                  {visibleMessages.map((message) => {
                    const isUserMessage = message.role === "user";

                    return (
                      <MessageScrollerItem
                        key={message.id}
                        messageId={message.id}
                      >
                        <Message align={isUserMessage ? "end" : "start"}>
                          <MessageContent>
                            <Bubble variant={isUserMessage ? "muted" : "ghost"}>
                              <BubbleContent className="space-y-2">
                                {getMessageText(message)
                                  .split(/\n\s*\n/)
                                  .map((paragraph) => paragraph.trim())
                                  .filter(Boolean)
                                  .map((paragraph, index) => (
                                    <p
                                      key={index}
                                      className="whitespace-pre-wrap"
                                    >
                                      {paragraph}
                                    </p>
                                  ))}
                              </BubbleContent>
                            </Bubble>
                          </MessageContent>
                        </Message>
                      </MessageScrollerItem>
                    );
                  })}
                  <MessageScrollerItem scrollAnchor={false}>
                    <Marker variant="separator">
                      <MarkerContent>End of Conversation</MarkerContent>
                    </Marker>
                  </MessageScrollerItem>
                </MessageScrollerContent>
              </MessageScrollerViewport>
              <MessageScrollerButton />
            </MessageScroller>
          </CardContent>
          <CardFooter className="flex flex-col items-center gap-2 border-t">
            <Button
              type="button"
              disabled={!canLoadHistory}
              onClick={() => {
                setVisibleCount(history.length);
                toast.add({
                  title: "History loaded",
                  ...{
                    description: "Scroll up to see earlier messages.",
                  },
                });
              }}
              className="w-full"
              variant="secondary"
            >
              {canLoadHistory ? "Load History" : "History Loaded"}
            </Button>
            <p className="text-muted-foreground text-xs">
              Restore earlier messages while keeping your place.
            </p>
          </CardFooter>
        </Card>
        <div className="mx-auto max-w-sm text-balance px-0.5 text-center text-muted-foreground text-xs">
          Click Load History to load the entire conversation
        </div>
      </div>
    </MessageScrollerProvider>
  );
}

export default MessageScrollerLoadHistory;
```

Use stable `messageId` values for message rows. That gives the scroller a
specific row to preserve instead of guessing from whichever pixel happens to sit
at the viewport edge.

### Animating New Messages

`MessageScrollerItem` can be animated directly. Create a motion version of the
item, keep `messageId` and `scrollAnchor` on it, and use transform and opacity
for the entrance.

A common chat pattern is to animate the user's message when it is sent, then let
the assistant reply stream into a regular row below it. Start the user row below
its final position so it feels like it rises from the live edge of the viewport.

```tsx
const MotionMessageScrollerItem = motion.create(MessageScrollerItem)
```

### Example: message-scroller-animation

```tsx
"use client";

import { useChat } from "@ai-sdk/react";
import { Button } from "@workspace/ui/components/button";
import {
  Card,
  CardAction,
  CardContent,
  CardDescription,
  CardFooter,
  CardHeader,
  CardTitle,
} from "@workspace/ui/components/card";
import {
  Empty,
  EmptyDescription,
  EmptyHeader,
  EmptyMedia,
  EmptyTitle,
} from "@workspace/ui/components/empty";
import {
  MessageScroller,
  MessageScrollerButton,
  MessageScrollerContent,
  MessageScrollerProvider,
  MessageScrollerViewport,
} from "@workspace/ui/components/message-scroller";
import {
  Select,
  SelectContent,
  SelectGroup,
  SelectItem,
  SelectTrigger,
  SelectValue,
} from "@workspace/ui/components/select";
import {
  ArrowUpIcon,
  MessageCircleDashedIcon,
  RotateCwIcon,
} from "lucide-react";
import * as React from "react";
import { createChat } from "../support/ai";
import { MessageAnimated } from "../support/message-animated";
import {
  MESSAGE_ANIMATIONS,
  type MessageAnimationId,
} from "../support/message-animations";

const chat = createChat()
  .user("Can user messages pop in like iMessage without breaking anchoring?")
  .sleep(1000)
  .assistant(
    "Yes. Animate the user row with transform and opacity, and let the assistant response stream normally below it.\n\nThat keeps the row measurement predictable while still giving the newly sent bubble a more tactile entrance.",
  )
  .user("What makes the animation feel more like iMessage?")
  .sleep(1000)
  .assistant(
    "Use a quick spring from the trailing edge: a little scale, a small upward move, and no layout animation.\n\nThe bubble feels tactile, but the measured row stays predictable, so anchoring and auto-scroll do not have to fight a changing layout.",
  )
  .user("Can I switch between presets while testing the same thread?")
  .sleep(1000)
  .assistant(
    "Yes. Keep the conversation in place while you change the preset, then send the next message to compare the new entrance against the same context.\n\nThat makes it easier to judge the difference between a subtle fade, a snappy pop, and a more dramatic 3D tilt without rebuilding the scenario each time.",
  );

const initialMessages = chat.get(0);
const transport = chat.transport({ delayMs: 15 });

export function MessageScrollerAnimation() {
  const { messages, sendMessage, setMessages, status } = useChat({
    messages: initialMessages,
    transport,
  });
  const [presetId, setPresetId] = React.useState<MessageAnimationId>("fade");
  const nextMessage = chat.next(messages);
  const isBusy = status === "submitted" || status === "streaming";
  const preset = MESSAGE_ANIMATIONS[presetId as MessageAnimationId];

  return (
    <div className="relative flex flex-col gap-4">
      <Card className="mx-auto h-140 w-full max-w-sm gap-0">
        <CardHeader className="border-b">
          <CardTitle>Animation</CardTitle>
          <CardDescription>
            Choose how user messages are animated when they are added to the
            conversation.
          </CardDescription>
          <CardAction className="flex items-center gap-2">
            <Button
              type="button"
              variant="outline"
              size="icon"
              aria-label="Reset animated messages"
              disabled={messages.length === 0 || isBusy}
              onClick={() => setMessages(initialMessages)}
            >
              <RotateCwIcon />
            </Button>
          </CardAction>
        </CardHeader>
        <CardContent className="min-h-0 flex-1 overflow-hidden p-0">
          {messages.length === 0 ? (
            <Empty className="h-full">
              <EmptyHeader>
                <EmptyMedia variant="icon">
                  <MessageCircleDashedIcon />
                </EmptyMedia>
                <EmptyTitle>No Messages Yet</EmptyTitle>
                <EmptyDescription>
                  Click the button below to send the first message.
                </EmptyDescription>
              </EmptyHeader>
            </Empty>
          ) : (
            <MessageScrollerProvider>
              <MessageScroller>
                <MessageScrollerViewport>
                  <MessageScrollerContent
                    aria-busy={isBusy}
                    className="p-(--card-spacing)"
                  >
                    {messages.map((message) => (
                      <MessageAnimated
                        key={message.id}
                        message={message}
                        animationPreset={preset}
                        userVariant="muted"
                        assistantVariant="ghost"
                      />
                    ))}
                  </MessageScrollerContent>
                </MessageScrollerViewport>
                <MessageScrollerButton />
              </MessageScroller>
            </MessageScrollerProvider>
          )}
        </CardContent>
        <CardFooter className="border-t">
          <Select
            value={presetId}
            onValueChange={(value) => {
              setPresetId(value as MessageAnimationId);
            }}
          >
            <SelectTrigger aria-label="Animation preset">
              <SelectValue>{preset.name}</SelectValue>
            </SelectTrigger>
            <SelectContent align="start" side="top">
              <SelectGroup>
                {Object.values(MESSAGE_ANIMATIONS).map((animation) => (
                  <SelectItem key={animation.id} value={animation.id}>
                    {animation.name}
                  </SelectItem>
                ))}
              </SelectGroup>
            </SelectContent>
          </Select>
          <Button
            type="button"
            size="icon"
            className="ml-auto"
            disabled={!nextMessage || isBusy}
            onClick={() => {
              if (!nextMessage || isBusy) {
                return;
              }

              void sendMessage(nextMessage);
            }}
          >
            <ArrowUpIcon />
            <span className="sr-only">Send Message</span>
          </Button>
        </CardFooter>
      </Card>
      <div className="mx-auto max-w-sm text-balance px-0.5 text-center text-muted-foreground text-xs">
        Select an animation then click send to see it in action.
      </div>
    </div>
  );
}

export default MessageScrollerAnimation;
```

Avoid animating height, margin, or padding for row entrances; those changes can
fight the scroller's positioning work. If the reader prefers reduced motion,
skip the entrance animation and keep the scroll behavior the same.

### Jumping to Messages

Search results, permalinks, outline items, and toolbar buttons often need to
drive the transcript from outside the message list. Use `useMessageScroller` for
those controls. Because the hooks read from `MessageScrollerProvider`, they work
in any component inside the provider, including controls rendered outside the
`MessageScroller` frame.

```tsx
import { useMessageScroller } from "@workspace/ui/components/message-scroller"
```

```tsx
const { scrollToMessage, scrollToEnd, scrollToStart } = useMessageScroller()
```

### Example: message-scroller-commands

```tsx
// biome-ignore-all lint/suspicious/noArrayIndexKey: The upstream gallery uses append-only positional paragraph fixtures.

"use client";

import { Bubble, BubbleContent } from "@workspace/ui/components/bubble";
import { Button } from "@workspace/ui/components/button";
import {
  Card,
  CardAction,
  CardContent,
  CardDescription,
  CardHeader,
  CardTitle,
} from "@workspace/ui/components/card";
import {
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuGroup,
  DropdownMenuItem,
  DropdownMenuLabel,
  DropdownMenuTrigger,
} from "@workspace/ui/components/dropdown-menu";
import { Message, MessageContent } from "@workspace/ui/components/message";
import {
  MessageScroller,
  MessageScrollerButton,
  MessageScrollerContent,
  MessageScrollerItem,
  MessageScrollerProvider,
  MessageScrollerViewport,
  useMessageScroller,
} from "@workspace/ui/components/message-scroller";
import { createChat, getMessageText } from "../support/ai";

const chat = createChat()
  .user(
    "We're seeing activation dip after workspace creation. Can you help me find the likely step?",
    { id: "command-activation" },
  )
  .assistant(
    "The sharpest drop is between creating the workspace and inviting the first teammate.\n\nWorkspace creation is still healthy, but the invite step is where users pause. That suggests the product is asking for collaboration before the user has enough confidence in the workspace.",
  )
  .user("What should I compare before we change the onboarding flow?", {
    id: "command-compare",
  })
  .assistant(
    "Compare three cohorts:\n\n1. Users who choose a template before inviting teammates.\n2. Users who start from a blank workspace.\n3. Users who skip invites and return within 24 hours.\n\nIf template users invite faster, the fix is probably better first-run guidance rather than a louder invite prompt.",
  )
  .user("Can you turn that into an experiment?", {
    id: "command-experiment",
  })
  .assistant(
    "Yes. Create a variant that shows a short checklist after workspace creation:\n\n- Pick a template.\n- Add one project detail.\n- Invite a teammate when the workspace has context.\n\nMeasure first invite completion, 24-hour return rate, and whether teams create a second project.",
  )
  .user("What's the risk if we delay the invite prompt?", {
    id: "command-risk",
  })
  .assistant(
    "The main risk is reducing team creation for accounts that already know who they want to invite.\n\nTo protect that path, keep the invite action visible in the header and only change the primary empty-state guidance. That gives confident teams a direct route without forcing uncertain users through the invite step too early.",
  );

const messages = chat.get();
const userMessages = messages.filter((message) => message.role === "user");

export function MessageScrollerCommands() {
  return (
    <MessageScrollerProvider defaultScrollPosition="end">
      <div className="relative flex flex-col gap-4">
        <Card className="mx-auto h-140 w-full max-w-sm gap-0">
          <CardHeader className="gap-1 border-b">
            <CardTitle>Commands</CardTitle>
            <CardDescription>
              Drive the transcript from outside.
            </CardDescription>
            <CardAction>
              <CommandMenu />
            </CardAction>
          </CardHeader>
          <CardContent className="flex-1 overflow-hidden p-0">
            <MessageScroller>
              <MessageScrollerViewport>
                <MessageScrollerContent className="p-(--card-spacing)">
                  {messages.map((message) => {
                    const isUserMessage = message.role === "user";
                    const text = getMessageText(message);

                    return (
                      <MessageScrollerItem
                        key={message.id}
                        messageId={message.id}
                        scrollAnchor={isUserMessage}
                      >
                        <Message align={isUserMessage ? "end" : "start"}>
                          <MessageContent>
                            <Bubble variant={isUserMessage ? "muted" : "ghost"}>
                              <BubbleContent className="space-y-2">
                                {text
                                  .split(/\n\s*\n/)
                                  .map((paragraph) => paragraph.trim())
                                  .filter(Boolean)
                                  .map((paragraph, index) => (
                                    <p
                                      key={index}
                                      className="whitespace-pre-wrap"
                                    >
                                      {paragraph}
                                    </p>
                                  ))}
                              </BubbleContent>
                            </Bubble>
                          </MessageContent>
                        </Message>
                      </MessageScrollerItem>
                    );
                  })}
                </MessageScrollerContent>
              </MessageScrollerViewport>
              <MessageScrollerButton />
            </MessageScroller>
          </CardContent>
        </Card>
        <div className="mx-auto max-w-sm text-balance px-0.5 text-center text-muted-foreground text-xs">
          Use the controls to jump to any message in the conversation.
        </div>
      </div>
    </MessageScrollerProvider>
  );
}

function CommandMenu() {
  const { scrollToMessage } = useMessageScroller();

  return (
    <DropdownMenu>
      <DropdownMenuTrigger
        render={<Button type="button" variant="secondary" />}
      >
        Jump to...
      </DropdownMenuTrigger>
      <DropdownMenuContent align="end" side="bottom" className="w-64">
        <DropdownMenuGroup>
          <DropdownMenuLabel>Conversations</DropdownMenuLabel>
          {userMessages.map((message) => (
            <DropdownMenuItem
              key={message.id}
              onClick={() =>
                scrollToMessage(message.id, {
                  align: "start",
                  behavior: "smooth",
                })
              }
            >
              <span className="line-clamp-1 min-w-0">
                {getTrimmedMessageText(message)}
              </span>
            </DropdownMenuItem>
          ))}
        </DropdownMenuGroup>
      </DropdownMenuContent>
    </DropdownMenu>
  );
}

function getTrimmedMessageText(message: (typeof userMessages)[number]) {
  const text = getMessageText(message);

  return text.length > 42 ? `${text.slice(0, 39)}...` : text;
}

export default MessageScrollerCommands;
```

`scrollToMessage` targets the `messageId` on `MessageScrollerItem`, so rows that
need to be addressable should have stable ids. `scrollToMessage` returns `false`
when the target is not mounted and cannot be queued.

`scrollToMessage` can queue a target before items exist, which covers
client-resolved permalinks while the transcript mounts. After rows have mounted,
a missing id returns `false` instead of starting a guessed retry loop. A `true`
result means the scroll ran or was queued, not that the row is already in view.

### Tracking the Reader's Position

Use `useMessageScrollerVisibility` to track the reader's position in the
conversation. A common example is a table-of-contents or a jump menu that
highlights the current anchored turn.

```tsx
import { useMessageScrollerVisibility } from "@workspace/ui/components/message-scroller"
```

```tsx
const { currentAnchorId, visibleMessageIds } = useMessageScrollerVisibility()
```

### Example: message-scroller-visibility

```tsx
// biome-ignore-all lint/suspicious/noArrayIndexKey: The upstream gallery uses append-only positional paragraph fixtures.

"use client";

import { Bubble, BubbleContent } from "@workspace/ui/components/bubble";
import {
  Card,
  CardContent,
  CardDescription,
  CardHeader,
  CardTitle,
} from "@workspace/ui/components/card";
import {
  HoverCard,
  HoverCardContent,
  HoverCardTrigger,
} from "@workspace/ui/components/hover-card";
import { Message, MessageContent } from "@workspace/ui/components/message";
import {
  MessageScroller,
  MessageScrollerButton,
  MessageScrollerContent,
  MessageScrollerItem,
  MessageScrollerProvider,
  MessageScrollerViewport,
  useMessageScroller,
  useMessageScrollerVisibility,
} from "@workspace/ui/components/message-scroller";
import { createChat, getMessageText } from "../support/ai";

const chat = createChat()
  .user("Review the incident handoff and tell me what to read first.", {
    id: "vis-brief",
  })
  .assistant(
    "Start with the summary and the impact section. The regression affected the upload queue, but the recovery path completed for every queued job.",
  )
  .user("What was the customer impact?", {
    id: "vis-impact",
  })
  .assistant(
    "Impact was limited to delayed processing.\n\nNo records were dropped, and the reconciliation worker confirmed each retry batch. Support saw confusion from two customers, but there were no checkout or billing errors.",
  )
  .user("What actions are open?", {
    id: "vis-actions",
  })
  .assistant(
    "Keep the retry window enabled until the next deploy, then add a queue-depth alert as the long-term fix.\n\nThe alert should fire on sustained queue growth, not a single short spike.",
  )
  .user("Give me the follow-up checklist.", {
    id: "vis-checklist",
  })
  .assistant(
    "After that, compare the queue recovery graph with the deploy timeline so the handoff shows exactly when processing returned to baseline. That makes it easier for support and engineering to answer the same customer questions without re-reading the whole incident thread.\n\nI would also add a short owner note beside each follow-up item. The checklist is small, but ownership keeps the retry-window decision, alert tuning, and support macro from drifting into separate follow-up conversations.\n\nKeep the retry window enabled until the next deploy, then add a queue-depth alert as the long-term fix.\n\nThe alert should fire on sustained queue growth, not a single short spike.",
  );

const messages = chat.get();
const userMessages = messages.filter((message) => message.role === "user");

export function MessageScrollerVisibility() {
  return (
    <MessageScrollerProvider scrollMargin={12}>
      <div className="relative flex flex-col gap-4">
        <div className="relative mx-auto w-full max-w-sm">
          <Card className="h-140 w-full gap-0">
            <CardHeader className="gap-1 border-b">
              <CardTitle>Transcript Outline</CardTitle>
              <CardDescription>
                Track the current anchored turn.
              </CardDescription>
            </CardHeader>
            <CardContent className="flex-1 overflow-hidden p-0">
              <MessageScroller>
                <MessageScrollerViewport>
                  <MessageScrollerContent className="p-(--card-spacing)">
                    {messages.map((message) => {
                      const isUserMessage = message.role === "user";
                      const text = getMessageText(message);

                      return (
                        <MessageScrollerItem
                          key={message.id}
                          messageId={message.id}
                          scrollAnchor={isUserMessage}
                        >
                          <Message align={isUserMessage ? "end" : "start"}>
                            <MessageContent>
                              <Bubble
                                variant={isUserMessage ? "muted" : "ghost"}
                              >
                                <BubbleContent className="space-y-2">
                                  {text
                                    .split(/\n\s*\n/)
                                    .map((paragraph) => paragraph.trim())
                                    .filter(Boolean)
                                    .map((paragraph, index) => (
                                      <p
                                        key={index}
                                        className="whitespace-pre-wrap"
                                      >
                                        {paragraph}
                                      </p>
                                    ))}
                                </BubbleContent>
                              </Bubble>
                            </MessageContent>
                          </Message>
                        </MessageScrollerItem>
                      );
                    })}
                  </MessageScrollerContent>
                </MessageScrollerViewport>
                <MessageScrollerButton />
              </MessageScroller>
            </CardContent>
          </Card>
          <div className="absolute top-1/2 -right-12 -translate-y-1/2">
            <TranscriptOutline />
          </div>
        </div>
        <div className="mx-auto max-w-sm px-0.5 text-center text-muted-foreground text-xs">
          Open the outline to jump between anchored turns as you read.
        </div>
      </div>
    </MessageScrollerProvider>
  );
}

function TranscriptOutline() {
  const { scrollToMessage } = useMessageScroller();
  const { currentAnchorId } = useMessageScrollerVisibility();

  return (
    <HoverCard>
      <HoverCardTrigger
        render={
          <button
            type="button"
            aria-label="Open transcript outline"
            className="flex h-9 w-9 flex-col items-center justify-center gap-1 rounded-md outline-none transition-colors focus-visible:ring-3 focus-visible:ring-ring/50"
          />
        }
      >
        {userMessages.map((message) => (
          <span
            key={message.id}
            data-current={message.id === currentAnchorId}
            className="h-0.5 w-4 rounded-full bg-muted-foreground/40 data-[current=true]:bg-foreground"
          />
        ))}
      </HoverCardTrigger>
      <HoverCardContent
        align="center"
        side="left"
        sideOffset={-28}
        className="flex w-64 flex-col gap-1 rounded-2xl p-1"
      >
        {userMessages.map((message) => (
          <button
            key={message.id}
            type="button"
            aria-current={
              currentAnchorId === message.id ? "location" : undefined
            }
            className="flex min-h-7 items-center rounded-xl px-2 py-1.5 text-left text-sm outline-none transition-colors hover:bg-accent hover:text-accent-foreground focus-visible:bg-accent focus-visible:text-accent-foreground aria-current:bg-accent aria-current:text-accent-foreground"
            onClick={() =>
              scrollToMessage(message.id, {
                align: "start",
                behavior: "smooth",
              })
            }
          >
            <span className="line-clamp-1 min-w-0">
              {getTrimmedMessageText(message)}
            </span>
          </button>
        ))}
      </HoverCardContent>
    </HoverCard>
  );
}

function getTrimmedMessageText(message: (typeof userMessages)[number]) {
  const text = getMessageText(message);

  return text.length > 42 ? `${text.slice(0, 39)}...` : text;
}

export default MessageScrollerVisibility;
```

`currentAnchorId` answers "where am I" by reporting the current anchored turn,
and it stays set after that anchor scrolls above the viewport. `visibleMessageIds`
answers "what is on screen", in document order.

Visibility is pay-for-what-you-use. Tracking only runs while something
subscribes to `useMessageScrollerVisibility`, and rows need a `messageId` to
participate.

### Reading Scroll State

Use `useMessageScrollerScrollable` when you need scroll state in JavaScript, such
as a status indicator or a custom "jump to latest" control. It reports which
edges the viewport can still scroll toward; "at the start/end" is the negation
(`!start` / `!end`), and "scrollable at all" is `start || end`. For styling the
scroller itself, prefer the `data-scrollable` attribute.

```tsx
import { useMessageScrollerScrollable } from "@workspace/ui/components/message-scroller"
```

```tsx
const { start, end } = useMessageScrollerScrollable()
```

### Example: message-scroller-scrollable

```tsx
"use client";

import {
  Card,
  CardContent,
  CardDescription,
  CardFooter,
  CardHeader,
  CardTitle,
} from "@workspace/ui/components/card";
import {
  MessageScroller,
  MessageScrollerButton,
  MessageScrollerContent,
  MessageScrollerProvider,
  MessageScrollerViewport,
  useMessageScrollerScrollable,
} from "@workspace/ui/components/message-scroller";
import { MessageAnimated } from "../support/message-animated";

const messages = Array.from({ length: 12 }, (_, index) => ({
  id: `scrollable-${index + 1}`,
  role: index % 2 === 0 ? "user" : "assistant",
  text:
    index % 2 === 0
      ? `Review scroll checkpoint ${index + 1}.`
      : `Checkpoint ${index + 1} is synced. The scrollable hook updates as the viewport moves.\n\nWhen the reader is at the first message, the footer should only point them down. Once they move into the middle of the transcript, it should explain that both directions are available.\n\nAt the latest message, the footer should switch again and only point them back up.`,
})) satisfies Array<{
  id: string;
  role: "user" | "assistant";
  text: string;
}>;

export function MessageScrollerScrollable() {
  return (
    <div className="mx-auto flex w-full max-w-sm flex-col gap-4">
      <Card className="h-140 w-full gap-0 overflow-hidden">
        <CardHeader className="gap-1 border-b">
          <CardTitle>Scroll Status</CardTitle>
          <CardDescription>
            Where the reader can go scroll to based on current scroll position.
          </CardDescription>
        </CardHeader>
        <MessageScrollerProvider defaultScrollPosition="start">
          <CardContent className="flex-1 overflow-hidden p-0">
            <MessageScroller>
              <MessageScrollerViewport>
                <MessageScrollerContent className="gap-4 p-(--card-spacing)">
                  <Transcript />
                </MessageScrollerContent>
              </MessageScrollerViewport>
              <MessageScrollerButton />
            </MessageScroller>
          </CardContent>
          <ScrollStateFooter />
        </MessageScrollerProvider>
      </Card>
      <div className="px-0.5 text-center text-muted-foreground text-xs">
        Scroll the transcript to see the footer update.
      </div>
    </div>
  );
}

function Transcript() {
  return messages.map((message) => (
    <MessageAnimated
      key={message.id}
      message={message}
      scrollAnchor={message.role === "user"}
      userVariant="muted"
      assistantVariant="ghost"
    />
  ));
}

function ScrollStateFooter() {
  const { start, end } = useMessageScrollerScrollable();

  const status = getScrollStatus({ start, end });

  return (
    <CardFooter className="justify-center border-t text-center text-muted-foreground text-sm">
      {status}
    </CardFooter>
  );
}

function getScrollStatus({ start, end }: { start: boolean; end: boolean }) {
  if (start && end) {
    return "You can scroll both ways.";
  }

  if (end) {
    return "You are at the top. You can only scroll down.";
  }

  if (start) {
    return "You are at the bottom. You can only scroll up.";
  }

  return "All messages fit in the viewport.";
}

export default MessageScrollerScrollable;
```

## Performance

`MessageScroller` is benchmarked against large transcripts with markdown and
composed message rows.

Our performance goal for `MessageScroller` is to keep the scroll hot path outside of React state: no React rerenders for
transcript rows, no forced layout on every scroll, and as little off-screen paint
work as the browser can avoid.

Scroll position, anchoring, and follow-output are tracked imperatively and mirrored onto the root and viewport through `data-*` attributes, so scrolling and streaming do not rerender transcript rows.

The styled `MessageScrollerItem` also ships with `content-visibility: auto` and
`contain-intrinsic-size`. Rows stay in the DOM for selection, copy,
find-in-page, SSR, and assistive tech, but the browser can skip rendering work
for rows far outside the viewport.

Visibility tracking is pay-for-what-you-use. A jump menu or active
turn indicator costs nothing until something subscribes to
`useMessageScrollerVisibility`.

This is comfortable for the expected range of a chat transcript: hundreds to low
thousands of turns, including messages with markdown and composed components.

## Virtualization

Virtualization is intentionally left outside the primitive. `MessageScroller`
renders real DOM rows and stays fast well into the thousands of turns (see
[Performance](#performance)), so most transcripts never need it.

When a transcript is large enough to need virtualization, use
`MessageScrollerViewport` as the scroll element and let the virtualizer own the
rows.

```tsx showLineNumbers
import * as React from "react"
import { useVirtualizer } from "@tanstack/react-virtual"

function VirtualizedTranscript({
  messages,
}: {
  messages: Array<{ id: string; content: React.ReactNode }>
}) {
  const viewportRef = React.useRef<HTMLDivElement>(null)

  const virtualizer = useVirtualizer({
    count: messages.length,
    getScrollElement: () => viewportRef.current,
    estimateSize: () => 86,
    getItemKey: (index) => messages[index]?.id ?? index,
    overscan: 8,
  })

  return (
    <MessageScrollerProvider>
      <MessageScroller>
        <MessageScrollerViewport ref={viewportRef}>
          <MessageScrollerContent className="block min-h-full">
            <div
              className="relative w-full"
              style={{ height: virtualizer.getTotalSize() }}
            >
              {virtualizer.getVirtualItems().map((virtualItem) => {
                const message = messages[virtualItem.index]

                if (!message) {
                  return null
                }

                return (
                  <div
                    key={virtualItem.key}
                    ref={virtualizer.measureElement}
                    data-index={virtualItem.index}
                    className="absolute start-0 top-0 w-full"
                    style={{
                      transform: `translateY(${virtualItem.start}px)`,
                    }}
                  >
                    <Message>{message.content}</Message>
                  </div>
                )
              })}
            </div>
          </MessageScrollerContent>
        </MessageScrollerViewport>
        <MessageScrollerButton />
      </MessageScroller>
    </MessageScrollerProvider>
  )
}
```

## Accessibility

`MessageScroller` keeps the scroll container keyboard reachable and the
transcript announceable without forcing a specific message UI.

`MessageScrollerViewport` is a labelled, keyboard-focusable scroll region by
default. It uses `role="region"`, `aria-label="Messages"`, and `tabIndex={0}`,
so keyboard users can focus the transcript and scroll it directly.

`MessageScrollerContent` marks the transcript as a live region with
`role="log"` and `aria-relevant="additions"`. New rows can be announced, but
streamed text mutations do not have to be announced token by token.

```tsx
<MessageScrollerContent aria-busy={status === "streaming"}>
  {/* messages */}
</MessageScrollerContent>
```

Pass `aria-busy` while a turn streams if announcements should wait for the
completed message row.

`MessageScrollerButton` renders a real button. When there is nothing to scroll
toward, it sets `inert`, uses `tabIndex={-1}`, and exposes `data-active="false"`
so inactive scroll controls do not create extra focus stops.

## Unstyled

The behavior in `MessageScroller` comes from the `@shadcn/react` package. To use
it directly with your own markup and styles, see
[Message Scroller](https://ui.shadcn.com/docs/react/message-scroller) under @shadcn/react.

## API Reference

The props, data attributes, and hooks for every part are documented on the
[@shadcn/react Message Scroller](https://ui.shadcn.com/docs/react/message-scroller#api-reference) page.
They are identical for the styled component and the unstyled parts.


---

# Native Select

A styled native HTML select element with consistent design system integration.

Page: https://sui.draco.dev/docs/components/native-select

For a styled select component, see the [Select](/docs/components/select)
  component.

### Example: native-select-demo

```tsx
import {
  NativeSelect,
  NativeSelectOption,
} from "@workspace/ui/components/native-select";

export default function NativeSelectDemo() {
  return (
    <NativeSelect>
      <NativeSelectOption value="">Select status</NativeSelectOption>
      <NativeSelectOption value="todo">Todo</NativeSelectOption>
      <NativeSelectOption value="in-progress">In Progress</NativeSelectOption>
      <NativeSelectOption value="done">Done</NativeSelectOption>
      <NativeSelectOption value="cancelled">Cancelled</NativeSelectOption>
    </NativeSelect>
  );
}
```

## Installation

```bash
bunx --bun shadcn@latest add @sui/native-select
```

Install with the shadcn CLI or use the shared `@workspace/ui` package. Follow the [installation guide](/docs/installation) to configure the registry, load styles, and choose import aliases.

## Usage

```tsx showLineNumbers
import {
  NativeSelect,
  NativeSelectOptGroup,
  NativeSelectOption,
} from "@workspace/ui/components/native-select"
```

```tsx showLineNumbers
<NativeSelect>
  <NativeSelectOption value="">Select a fruit</NativeSelectOption>
  <NativeSelectOption value="apple">Apple</NativeSelectOption>
  <NativeSelectOption value="banana">Banana</NativeSelectOption>
  <NativeSelectOption value="blueberry">Blueberry</NativeSelectOption>
  <NativeSelectOption value="pineapple">Pineapple</NativeSelectOption>
</NativeSelect>
```

## Composition

### Simple

Options placed directly under `NativeSelect` (no `NativeSelectOptGroup`).

```text
NativeSelect
├── NativeSelectOption
├── NativeSelectOption
├── NativeSelectOption
└── NativeSelectOption
```

### With groups

Use `NativeSelectOptGroup` to organize options into categories.

```text
NativeSelect
├── NativeSelectOptGroup
│   ├── NativeSelectOption
│   └── NativeSelectOption
└── NativeSelectOptGroup
    ├── NativeSelectOption
    └── NativeSelectOption
```

## Groups

Use `NativeSelectOptGroup` to organize options into categories.

### Example: native-select-groups

```tsx
import {
  NativeSelect,
  NativeSelectOptGroup,
  NativeSelectOption,
} from "@workspace/ui/components/native-select";

export default function NativeSelectGroups() {
  return (
    <NativeSelect>
      <NativeSelectOption value="">Select department</NativeSelectOption>
      <NativeSelectOptGroup label="Engineering">
        <NativeSelectOption value="frontend">Frontend</NativeSelectOption>
        <NativeSelectOption value="backend">Backend</NativeSelectOption>
        <NativeSelectOption value="devops">DevOps</NativeSelectOption>
      </NativeSelectOptGroup>
      <NativeSelectOptGroup label="Sales">
        <NativeSelectOption value="sales-rep">Sales Rep</NativeSelectOption>
        <NativeSelectOption value="account-manager">
          Account Manager
        </NativeSelectOption>
        <NativeSelectOption value="sales-director">
          Sales Director
        </NativeSelectOption>
      </NativeSelectOptGroup>
      <NativeSelectOptGroup label="Operations">
        <NativeSelectOption value="support">
          Customer Support
        </NativeSelectOption>
        <NativeSelectOption value="product-manager">
          Product Manager
        </NativeSelectOption>
        <NativeSelectOption value="ops-manager">
          Operations Manager
        </NativeSelectOption>
      </NativeSelectOptGroup>
    </NativeSelect>
  );
}
```

## Disabled

Add the `disabled` prop to the `NativeSelect` component to disable the select.

### Example: native-select-disabled

```tsx
import {
  NativeSelect,
  NativeSelectOption,
} from "@workspace/ui/components/native-select";

export function NativeSelectDisabled() {
  return (
    <NativeSelect disabled>
      <NativeSelectOption value="">Disabled</NativeSelectOption>
      <NativeSelectOption value="apple">Apple</NativeSelectOption>
      <NativeSelectOption value="banana">Banana</NativeSelectOption>
      <NativeSelectOption value="blueberry">Blueberry</NativeSelectOption>
    </NativeSelect>
  );
}

export default NativeSelectDisabled;
```

## Invalid

Use `aria-invalid` to show validation errors and the `data-invalid` attribute to the `Field` component for styling.

### Example: native-select-invalid

```tsx
import {
  NativeSelect,
  NativeSelectOption,
} from "@workspace/ui/components/native-select";

export function NativeSelectInvalid() {
  return (
    <NativeSelect aria-invalid="true">
      <NativeSelectOption value="">Error state</NativeSelectOption>
      <NativeSelectOption value="apple">Apple</NativeSelectOption>
      <NativeSelectOption value="banana">Banana</NativeSelectOption>
      <NativeSelectOption value="blueberry">Blueberry</NativeSelectOption>
    </NativeSelect>
  );
}

export default NativeSelectInvalid;
```

## Native Select vs Select

- Use `NativeSelect` for native browser behavior, better performance, or mobile-optimized dropdowns.
- Use `Select` for custom styling, animations, or complex interactions.

## RTL

To enable RTL support in shadcn/ui, see the [RTL configuration guide](https://ui.shadcn.com/docs/rtl).

### Example: native-select-rtl

```tsx
"use client";

import {
  NativeSelect,
  NativeSelectOption,
} from "@workspace/ui/components/native-select";
import { type Translations, useTranslation } from "./support";

const translations: Translations = {
  en: {
    dir: "ltr",
    values: {
      placeholder: "Select status",
      todo: "Todo",
      inProgress: "In Progress",
      done: "Done",
      cancelled: "Cancelled",
    },
  },
  ar: {
    dir: "rtl",
    values: {
      placeholder: "اختر الحالة",
      todo: "مهام",
      inProgress: "قيد التنفيذ",
      done: "منجز",
      cancelled: "ملغي",
    },
  },
  he: {
    dir: "rtl",
    values: {
      placeholder: "בחר סטטוס",
      todo: "לעשות",
      inProgress: "בתהליך",
      done: "הושלם",
      cancelled: "בוטל",
    },
  },
};

export function NativeSelectRtl() {
  const { dir, t } = useTranslation(translations, "ar");

  return (
    <NativeSelect dir={dir}>
      <NativeSelectOption value="">{t.placeholder}</NativeSelectOption>
      <NativeSelectOption value="todo">{t.todo}</NativeSelectOption>
      <NativeSelectOption value="in-progress">
        {t.inProgress}
      </NativeSelectOption>
      <NativeSelectOption value="done">{t.done}</NativeSelectOption>
      <NativeSelectOption value="cancelled">{t.cancelled}</NativeSelectOption>
    </NativeSelect>
  );
}

export default NativeSelectRtl;
```

## API Reference

### NativeSelect

The main select component that wraps the native HTML select element.

```tsx
<NativeSelect>
  <NativeSelectOption value="option1">Option 1</NativeSelectOption>
  <NativeSelectOption value="option2">Option 2</NativeSelectOption>
</NativeSelect>
```

### NativeSelectOption

Represents an individual option within the select.

| Prop       | Type      | Default |
| ---------- | --------- | ------- |
| `value`    | `string`  |         |
| `disabled` | `boolean` | `false` |

### NativeSelectOptGroup

Groups related options together for better organization.

| Prop       | Type      | Default |
| ---------- | --------- | ------- |
| `label`    | `string`  |         |
| `disabled` | `boolean` | `false` |

```tsx
<NativeSelectOptGroup label="Fruits">
  <NativeSelectOption value="apple">Apple</NativeSelectOption>
  <NativeSelectOption value="banana">Banana</NativeSelectOption>
</NativeSelectOptGroup>
```


---

# Navigation Menu

A collection of links for navigating websites.

Page: https://sui.draco.dev/docs/components/navigation-menu

### Example: navigation-menu-demo

```tsx
"use client";

import {
  NavigationMenu,
  NavigationMenuContent,
  NavigationMenuItem,
  NavigationMenuLink,
  NavigationMenuList,
  NavigationMenuTrigger,
  navigationMenuTriggerStyle,
} from "@workspace/ui/components/navigation-menu";
import {
  CircleAlertIcon,
  CircleCheckIcon,
  CircleDashedIcon,
} from "lucide-react";
import type * as React from "react";

const components: { title: string; href: string; description: string }[] = [
  {
    title: "Alert Dialog",
    href: "/docs/primitives/alert-dialog",
    description:
      "A modal dialog that interrupts the user with important content and expects a response.",
  },
  {
    title: "Hover Card",
    href: "/docs/primitives/hover-card",
    description:
      "For sighted users to preview content available behind a link.",
  },
  {
    title: "Progress",
    href: "/docs/primitives/progress",
    description:
      "Displays an indicator showing the completion progress of a task, typically displayed as a progress bar.",
  },
  {
    title: "Scroll-area",
    href: "/docs/primitives/scroll-area",
    description: "Visually or semantically separates content.",
  },
  {
    title: "Tabs",
    href: "/docs/primitives/tabs",
    description:
      "A set of layered sections of content—known as tab panels—that are displayed one at a time.",
  },
  {
    title: "Tooltip",
    href: "/docs/primitives/tooltip",
    description:
      "A popup that displays information related to an element when the element receives keyboard focus or the mouse hovers over it.",
  },
];

export default function NavigationMenuDemo() {
  return (
    <NavigationMenu>
      <NavigationMenuList>
        <NavigationMenuItem>
          <NavigationMenuTrigger>Getting started</NavigationMenuTrigger>
          <NavigationMenuContent>
            <ul className="w-96">
              <ListItem href="/docs" title="Introduction">
                Re-usable components built with Tailwind CSS.
              </ListItem>
              <ListItem href="/docs/installation" title="Installation">
                How to install dependencies and structure your app.
              </ListItem>
              <ListItem href="/docs/primitives/typography" title="Typography">
                Styles for headings, paragraphs, lists...etc
              </ListItem>
            </ul>
          </NavigationMenuContent>
        </NavigationMenuItem>
        <NavigationMenuItem className="hidden md:flex">
          <NavigationMenuTrigger>Components</NavigationMenuTrigger>
          <NavigationMenuContent>
            <ul className="grid w-[400px] gap-2 md:w-[500px] md:grid-cols-2 lg:w-[600px]">
              {components.map((component) => (
                <ListItem
                  key={component.title}
                  title={component.title}
                  href={component.href}
                >
                  {component.description}
                </ListItem>
              ))}
            </ul>
          </NavigationMenuContent>
        </NavigationMenuItem>
        <NavigationMenuItem>
          <NavigationMenuTrigger>With Icon</NavigationMenuTrigger>
          <NavigationMenuContent>
            <ul className="grid w-[200px]">
              <li>
                <NavigationMenuLink
                  render={
                    <a href="/docs" className="flex-row items-center gap-2" />
                  }
                >
                  <CircleAlertIcon />
                  Backlog
                </NavigationMenuLink>
                <NavigationMenuLink
                  render={
                    <a href="/docs" className="flex-row items-center gap-2" />
                  }
                >
                  <CircleDashedIcon />
                  To Do
                </NavigationMenuLink>
                <NavigationMenuLink
                  render={
                    <a href="/docs" className="flex-row items-center gap-2" />
                  }
                >
                  <CircleCheckIcon />
                  Done
                </NavigationMenuLink>
              </li>
            </ul>
          </NavigationMenuContent>
        </NavigationMenuItem>
        <NavigationMenuItem>
          <NavigationMenuLink
            render={<a href="/docs" />}
            className={navigationMenuTriggerStyle()}
          >
            Docs
          </NavigationMenuLink>
        </NavigationMenuItem>
      </NavigationMenuList>
    </NavigationMenu>
  );
}

function ListItem({
  title,
  children,
  href,
  ...props
}: React.ComponentPropsWithoutRef<"li"> & { href: string }) {
  return (
    <li {...props}>
      <NavigationMenuLink render={<a href={href} />}>
        <div className="flex flex-col gap-1 text-sm">
          <div className="font-medium leading-none">{title}</div>
          <div className="line-clamp-2 text-muted-foreground">{children}</div>
        </div>
      </NavigationMenuLink>
    </li>
  );
}
```

## Installation

```bash
bunx --bun shadcn@latest add @sui/navigation-menu
```

Install with the shadcn CLI or use the shared `@workspace/ui` package. Follow the [installation guide](/docs/installation) to configure the registry, load styles, and choose import aliases.

## Usage

```tsx showLineNumbers
import {
  NavigationMenu,
  NavigationMenuContent,
  NavigationMenuItem,
  NavigationMenuLink,
  NavigationMenuList,
  NavigationMenuTrigger,
} from "@workspace/ui/components/navigation-menu"
```

```tsx showLineNumbers
<NavigationMenu>
  <NavigationMenuList>
    <NavigationMenuItem>
      <NavigationMenuTrigger>Item One</NavigationMenuTrigger>
      <NavigationMenuContent>
        <NavigationMenuLink>Link</NavigationMenuLink>
      </NavigationMenuContent>
    </NavigationMenuItem>
  </NavigationMenuList>
</NavigationMenu>
```

## Composition

Use the following composition to build a `NavigationMenu`:

```text
NavigationMenu
├── NavigationMenuList
│   ├── NavigationMenuItem
│   │   ├── NavigationMenuTrigger
│   │   └── NavigationMenuContent
│   │       ├── NavigationMenuLink
│   │       └── NavigationMenuLink
│   └── NavigationMenuItem
│       └── NavigationMenuLink
└── NavigationMenuIndicator
```

## Link Component

Use the `render` prop to compose a custom link component such as Next.js `Link`.

```tsx showLineNumbers
import Link from "next/link"

import {
  NavigationMenuItem,
  NavigationMenuLink,
  navigationMenuTriggerStyle,
} from "@workspace/ui/components/navigation-menu"

export function NavigationMenuDemo() {
  return (
    <NavigationMenuItem>
      <NavigationMenuLink
        render={<Link href="/docs" />}
        className={navigationMenuTriggerStyle()}
      >
        Documentation
      </NavigationMenuLink>
    </NavigationMenuItem>
  )
}
```

## RTL

To enable RTL support in shadcn/ui, see the [RTL configuration guide](https://ui.shadcn.com/docs/rtl).

### Example: navigation-menu-rtl

```tsx
"use client";

import {
  NavigationMenu,
  NavigationMenuContent,
  NavigationMenuItem,
  NavigationMenuLink,
  NavigationMenuList,
  NavigationMenuTrigger,
  navigationMenuTriggerStyle,
} from "@workspace/ui/components/navigation-menu";
import {
  CircleAlertIcon,
  CircleCheckIcon,
  CircleDashedIcon,
} from "lucide-react";
import type * as React from "react";
import { type Translations, useTranslation } from "./support";

const translations: Translations = {
  en: {
    dir: "ltr",
    values: {
      gettingStarted: "Getting started",
      introduction: "Introduction",
      introductionDesc: "Re-usable components built with Tailwind CSS.",
      installation: "Installation",
      installationDesc: "How to install dependencies and structure your app.",
      typography: "Typography",
      typographyDesc: "Styles for headings, paragraphs, lists...etc",
      components: "Components",
      alertDialog: "Alert Dialog",
      alertDialogDesc:
        "A modal dialog that interrupts the user with important content and expects a response.",
      hoverCard: "Hover Card",
      hoverCardDesc:
        "For sighted users to preview content available behind a link.",
      progress: "Progress",
      progressDesc:
        "Displays an indicator showing the completion progress of a task, typically displayed as a progress bar.",
      scrollArea: "Scroll-area",
      scrollAreaDesc: "Visually or semantically separates content.",
      tabs: "Tabs",
      tabsDesc:
        "A set of layered sections of content—known as tab panels—that are displayed one at a time.",
      tooltip: "Tooltip",
      tooltipDesc:
        "A popup that displays information related to an element when the element receives keyboard focus or the mouse hovers over it.",
      withIcon: "With Icon",
      backlog: "Backlog",
      toDo: "To Do",
      done: "Done",
      docs: "Docs",
    },
  },
  ar: {
    dir: "rtl",
    values: {
      gettingStarted: "البدء",
      introduction: "مقدمة",
      introductionDesc:
        "مكونات قابلة لإعادة الاستخدام مبنية باستخدام Tailwind CSS.",
      installation: "التثبيت",
      installationDesc: "كيفية تثبيت التبعيات وتنظيم تطبيقك.",
      typography: "الطباعة",
      typographyDesc: "أنماط للعناوين والفقرات والقوائم...إلخ",
      components: "المكونات",
      alertDialog: "حوار التنبيه",
      alertDialogDesc: "حوار نافذة يقطع المستخدم بمحتوى مهم ويتوقع استجابة.",
      hoverCard: "بطاقة التحويم",
      hoverCardDesc: "للمستخدمين المبصرين لمعاينة المحتوى المتاح خلف الرابط.",
      progress: "التقدم",
      progressDesc:
        "يعرض مؤشرًا يوضح تقدم إتمام المهمة، عادةً يتم عرضه كشريط تقدم.",
      scrollArea: "منطقة التمرير",
      scrollAreaDesc: "يفصل المحتوى بصريًا أو دلاليًا.",
      tabs: "التبويبات",
      tabsDesc:
        "مجموعة من أقسام المحتوى المتعددة الطبقات—المعروفة بألواح التبويب—التي يتم عرضها واحدة في كل مرة.",
      tooltip: "تلميح",
      tooltipDesc:
        "نافذة منبثقة تعرض معلومات متعلقة بعنصر عندما يتلقى العنصر التركيز على لوحة المفاتيح أو عند تحويم الماوس فوقه.",
      withIcon: "مع أيقونة",
      backlog: "قائمة الانتظار",
      toDo: "المهام",
      done: "منجز",
      docs: "الوثائق",
    },
  },
  he: {
    dir: "rtl",
    values: {
      gettingStarted: "התחלה",
      introduction: "הקדמה",
      introductionDesc: "רכיבים לשימוש חוזר שנבנו עם Tailwind CSS.",
      installation: "התקנה",
      installationDesc: "כיצד להתקין תלויות ולבנות את האפליקציה שלך.",
      typography: "טיפוגרפיה",
      typographyDesc: "סגנונות לכותרות, פסקאות, רשימות...וכו'",
      components: "רכיבים",
      alertDialog: "דיאלוג התראה",
      alertDialogDesc: "דיאלוג מודאלי שמפריע למשתמש עם תוכן חשוב ומצפה לתגובה.",
      hoverCard: "כרטיס ריחוף",
      hoverCardDesc:
        "למשתמשים רואים כדי להציג תצוגה מקדימה של תוכן זמין מאחורי קישור.",
      progress: "התקדמות",
      progressDesc:
        "מציג אינדיקטור המציג את התקדמות ההשלמה של משימה, בדרך כלל מוצג כסרגל התקדמות.",
      scrollArea: "אזור גלילה",
      scrollAreaDesc: "מפריד תוכן חזותית או סמנטית.",
      tabs: "כרטיסיות",
      tabsDesc:
        "קבוצה של חלקי תוכן מרובדים—המכונים לוחות כרטיסיות—המוצגים אחד בכל פעם.",
      tooltip: "טולטיפ",
      tooltipDesc:
        "חלון קופץ המציג מידע הקשור לאלמנט כאשר האלמנט מקבל מיקוד מקלדת או כאשר העכבר מרחף מעליו.",
      withIcon: "עם אייקון",
      backlog: "רשימת המתנה",
      toDo: "לעשות",
      done: "הושלם",
      docs: "תיעוד",
    },
  },
};

const components = [
  {
    titleKey: "alertDialog" as const,
    descriptionKey: "alertDialogDesc" as const,
    href: "/docs/primitives/alert-dialog",
  },
  {
    titleKey: "hoverCard" as const,
    descriptionKey: "hoverCardDesc" as const,
    href: "/docs/primitives/hover-card",
  },
  {
    titleKey: "progress" as const,
    descriptionKey: "progressDesc" as const,
    href: "/docs/primitives/progress",
  },
  {
    titleKey: "scrollArea" as const,
    descriptionKey: "scrollAreaDesc" as const,
    href: "/docs/primitives/scroll-area",
  },
  {
    titleKey: "tabs" as const,
    descriptionKey: "tabsDesc" as const,
    href: "/docs/primitives/tabs",
  },
  {
    titleKey: "tooltip" as const,
    descriptionKey: "tooltipDesc" as const,
    href: "/docs/primitives/tooltip",
  },
] as const;

export function NavigationMenuRtl() {
  const { dir, t, language } = useTranslation(translations, "ar");

  return (
    <NavigationMenu dir={dir} align={dir === "rtl" ? "end" : "start"}>
      <NavigationMenuList>
        <NavigationMenuItem>
          <NavigationMenuTrigger>{t.gettingStarted}</NavigationMenuTrigger>
          <NavigationMenuContent
            dir={dir}
            data-lang={dir === "rtl" ? language : undefined}
          >
            <ul className="w-96">
              <ListItem href="/docs" title={t.introduction}>
                {t.introductionDesc}
              </ListItem>
              <ListItem href="/docs/installation" title={t.installation}>
                {t.installationDesc}
              </ListItem>
              <ListItem href="/docs/primitives/typography" title={t.typography}>
                {t.typographyDesc}
              </ListItem>
            </ul>
          </NavigationMenuContent>
        </NavigationMenuItem>
        <NavigationMenuItem className="hidden md:flex">
          <NavigationMenuTrigger>{t.components}</NavigationMenuTrigger>
          <NavigationMenuContent
            dir={dir}
            data-lang={dir === "rtl" ? language : undefined}
          >
            <ul className="grid w-[400px] gap-2 md:w-[500px] md:grid-cols-2 lg:w-[600px]">
              {components.map((component) => (
                <ListItem
                  key={component.titleKey}
                  title={t[component.titleKey]}
                  href={component.href}
                >
                  {t[component.descriptionKey]}
                </ListItem>
              ))}
            </ul>
          </NavigationMenuContent>
        </NavigationMenuItem>
        <NavigationMenuItem>
          <NavigationMenuTrigger>{t.withIcon}</NavigationMenuTrigger>
          <NavigationMenuContent
            dir={dir}
            data-lang={dir === "rtl" ? language : undefined}
          >
            <ul className="grid w-[200px]">
              <li>
                <NavigationMenuLink
                  render={
                    <a href="/docs" className="flex-row items-center gap-2" />
                  }
                >
                  <CircleAlertIcon />
                  {t.backlog}
                </NavigationMenuLink>
                <NavigationMenuLink
                  render={
                    <a href="/docs" className="flex-row items-center gap-2" />
                  }
                >
                  <CircleDashedIcon />
                  {t.toDo}
                </NavigationMenuLink>
                <NavigationMenuLink
                  render={
                    <a href="/docs" className="flex-row items-center gap-2" />
                  }
                >
                  <CircleCheckIcon />
                  {t.done}
                </NavigationMenuLink>
              </li>
            </ul>
          </NavigationMenuContent>
        </NavigationMenuItem>
        <NavigationMenuItem>
          <NavigationMenuLink
            render={<a href="/docs" />}
            className={navigationMenuTriggerStyle()}
            data-lang={dir === "rtl" ? language : undefined}
          >
            {t.docs}
          </NavigationMenuLink>
        </NavigationMenuItem>
      </NavigationMenuList>
    </NavigationMenu>
  );
}

function ListItem({
  title,
  children,
  href,
  ...props
}: React.ComponentPropsWithoutRef<"li"> & { href: string }) {
  return (
    <li {...props}>
      <NavigationMenuLink render={<a href={href} />}>
        <div className="flex flex-col gap-1 text-sm">
          <div className="font-medium leading-none">{title}</div>
          <div className="line-clamp-2 text-muted-foreground">{children}</div>
        </div>
      </NavigationMenuLink>
    </li>
  );
}

export default NavigationMenuRtl;
```

## API Reference

See the [Base UI Navigation Menu](https://base-ui.com/react/components/navigation-menu#api-reference) documentation for more information.

- [Documentation](https://base-ui.com/react/components/navigation-menu)
- [API reference](https://base-ui.com/react/components/navigation-menu#api-reference)


---

# NavigationProgress

A controlled navigation loading bar with delayed start and completion feedback.

Page: https://sui.draco.dev/docs/components/navigation-progress

### Example: navigation-progress-demo

```tsx
import { Button } from "@workspace/ui/components/button";
import { NavigationProgress } from "@workspace/ui/components/navigation-progress";
import { useState } from "react";
import type { ExampleProps } from "../types";

export default function NavigationProgressDemo({ locale }: ExampleProps) {
  const zh = locale === "zh-CN";
  const stateLabels = zh
    ? {
        navigating: "页面切换中…",
        ready: "页面已就绪",
      }
    : {
        navigating: "Navigating…",
        ready: "Page ready",
      };
  const [active, setActive] = useState(false);
  return (
    <div className="relative flex w-full max-w-md flex-col gap-4 overflow-hidden rounded-2xl border p-6">
      <NavigationProgress
        active={active}
        position="absolute"
        label={zh ? "正在加载页面" : "Loading page"}
      />
      <p className="text-muted-foreground text-sm" role="status">
        {active ? stateLabels.navigating : stateLabels.ready}
      </p>
      <div className="flex gap-2">
        <Button onClick={() => setActive(true)} disabled={active}>
          {zh ? "开始导航" : "Start navigation"}
        </Button>
        <Button
          variant="outline"
          onClick={() => setActive(false)}
          disabled={!active}
        >
          {zh ? "完成" : "Complete"}
        </Button>
      </div>
    </div>
  );
}
```

## Installation

```bash
bunx --bun shadcn@latest add @sui/navigation-progress
```

Install with the shadcn CLI or use the shared `@workspace/ui` package. Follow the [installation guide](/docs/installation) to configure the registry, load styles, and choose import aliases.

```tsx
import { NavigationProgress } from "@workspace/ui/components/navigation-progress"
```

## Router integration

The shared UI component accepts loading state from any router. The documentation application connects it to TanStack Router:

```tsx
import { useRouterState } from "@tanstack/react-router"
import { NavigationProgress } from "@workspace/ui/components/navigation-progress"

function RouterProgress() {
  const active = useRouterState({ select: (state) => state.status === "pending" })
  return <NavigationProgress active={active} />
}
```

The bar waits before appearing, advances toward a capped estimate, completes when `active` becomes false, then hides. Quick transitions that finish before `delay` produce no flash. The displayed length is an estimate; the accessible progress state remains indeterminate during loading. Reduced-motion preferences disable transition animation.

## API

| Prop | Default | Description |
| --- | --- | --- |
| `active` | Required | Whether navigation is pending. |
| `delay` | `120` | Delay before showing the bar, in milliseconds. |
| `finishDelay` | `180` | Time to show completion before hiding. |
| `position` | `fixed` | `fixed` for the page top, `absolute` within a positioned container. |
| `label` | `Loading page` | Accessible progress name. |
| `className` | — | Placement and layout classes. |

Inspired by [shadcn-admin NavigationProgress](https://github.com/satnaing/shadcn-admin/blob/main/src/components/navigation-progress.tsx). This implementation uses the existing Base UI dependency, SUI semantic tokens, and React timers, with no `react-top-loading-bar` or router dependency in the UI package.


---

# Pagination

Compact data pagination with range information, page navigation, and page-size selection.

Page: https://sui.draco.dev/docs/components/pagination

`Pagination` combines a range summary and compact navigation controls. Use it for data tables, lists, or sequential API results. The component manages navigation state; your application supplies and renders the data for the selected page.

### Example: pagination-demo

```tsx
"use client";

import {
  Pagination,
  type PaginationRangeInfo,
} from "@workspace/ui/components/pagination";
import { useState } from "react";
import type { ExampleProps } from "../types";

const records = Array.from({ length: 100 }, (_, index) => ({
  id: `request-${index + 1}`,
  number: index + 1,
}));
export default function Example({ locale }: ExampleProps) {
  const chinese = locale === "zh-CN";
  const labels = chinese
    ? {
        navigation: "分页",
        firstPage: "首页",
        previousPage: "上一页",
        nextPage: "下一页",
        lastPage: "末页",
        pageNumber: "页码",
        pageSize: "每页条数",
        range: ({ page, totalCount, from, to }: PaginationRangeInfo) =>
          totalCount === undefined
            ? `第 ${page} 页`
            : `显示第 ${from}–${to} 条，共 ${totalCount} 条`,
      }
    : undefined;
  const [page, setPage] = useState(1);
  return (
    <div className="grid w-full gap-4">
      <ul
        aria-label={chinese ? "当前页请求" : "Requests on this page"}
        className="grid grid-cols-2 gap-2 rounded-xl bg-muted p-3 text-sm sm:grid-cols-5"
      >
        {records.slice((page - 1) * 10, page * 10).map((record) => (
          <li key={record.id}>
            {chinese ? "请求" : "Request"} {record.number}
          </li>
        ))}
      </ul>
      <Pagination
        page={page}
        onPageChange={setPage}
        perPage={10}
        totalCount={records.length}
        labels={labels}
      />
    </div>
  );
}
```

## Installation

```bash
bunx --bun shadcn@latest add @sui/pagination
```

Install with the shadcn CLI or use the shared `@workspace/ui` package. Follow the [installation guide](/docs/installation) to configure the registry, load styles, and choose import aliases.

## Usage

When `children` is omitted, `Pagination` renders `PaginationInfo` and `PaginationControls` automatically. Provide `totalCount` to enable first, previous, page input, next, and last controls.

```tsx
import { Pagination } from "@workspace/ui/components/pagination";
import { useState } from "react";

export function ResultsPagination() {
  const [page, setPage] = useState(1);

  return (
    <Pagination
      page={page}
      onPageChange={setPage}
      perPage={10}
      totalCount={100}
    />
  );
}
```

Pages start at `1`. Omit `page` for internal page state, starting at page `1`; `onPageChange` still reports changes. With a controlled `page`, update it in `onPageChange`. Use the current page and page size to slice local data or request the corresponding server results.

For known totals, the page input commits on Enter or blur. Whole-number input is clamped to the available page range; empty, fractional, or nonnumeric input restores the current page. Escape cancels editing. Enter does not submit an enclosing form.

## Simple

Set `controls="simple"` to retain the range summary and show only previous and next buttons. The first and last buttons and page selector are hidden.

### Example: pagination-simple

```tsx
"use client";

import {
  Pagination,
  type PaginationRangeInfo,
} from "@workspace/ui/components/pagination";
import { useState } from "react";
import type { ExampleProps } from "../types";

export default function Example({ locale }: ExampleProps) {
  const chinese = locale === "zh-CN";
  const labels = chinese
    ? {
        navigation: "分页",
        firstPage: "首页",
        previousPage: "上一页",
        nextPage: "下一页",
        lastPage: "末页",
        pageNumber: "页码",
        pageSize: "每页条数",
        range: ({ page, totalCount, from, to }: PaginationRangeInfo) =>
          totalCount === undefined
            ? `第 ${page} 页`
            : `显示第 ${from}–${to} 条，共 ${totalCount} 条`,
      }
    : undefined;
  const [page, setPage] = useState(1);
  return (
    <div className="grid w-full gap-4">
      <Pagination
        page={page}
        onPageChange={setPage}
        totalCount={100}
        controls="simple"
        labels={labels}
      />
      <output className="text-muted-foreground text-sm" aria-live="polite">
        {chinese ? `当前页：${page}` : `Current page: ${page}`}
      </output>
    </div>
  );
}
```

```tsx
<Pagination
  page={page}
  onPageChange={setPage}
  perPage={10}
  totalCount={100}
  controls="simple"
/>
```

## Unknown totals

Omit `totalCount` for APIs that only indicate whether another page exists. Set `hasNextPage` from the response. Unknown totals always use sequential previous and next controls, even when `controls="full"`; there is no first, last, or arbitrary-page selector.

The default summary is `Page N`. `PaginationInfo` can render a custom summary. Its `from` and `to` values are inferred from the page size when the total is unknown; they do not describe the actual number of items returned by the server.

### Example: pagination-unknown-total

```tsx
"use client";

import {
  Pagination,
  PaginationControls,
  PaginationInfo,
  type PaginationRangeInfo,
} from "@workspace/ui/components/pagination";
import { useState } from "react";
import type { ExampleProps } from "../types";

const batches = [
  ["evt-101", "evt-102", "evt-103"],
  ["evt-201", "evt-202", "evt-203"],
  ["evt-301", "evt-302"],
];
export default function Example({ locale }: ExampleProps) {
  const chinese = locale === "zh-CN";
  const labels = chinese
    ? {
        navigation: "分页",
        firstPage: "首页",
        previousPage: "上一页",
        nextPage: "下一页",
        lastPage: "末页",
        pageNumber: "页码",
        pageSize: "每页条数",
        range: ({ page, totalCount, from, to }: PaginationRangeInfo) =>
          totalCount === undefined
            ? `第 ${page} 页`
            : `显示第 ${from}–${to} 条，共 ${totalCount} 条`,
      }
    : undefined;
  const [page, setPage] = useState(1);
  return (
    <div className="grid w-full gap-4">
      <ul
        aria-label={chinese ? "当前批次事件" : "Events in this batch"}
        className="grid gap-2 rounded-xl bg-muted p-3 text-sm"
      >
        {batches[page - 1]?.map((event) => (
          <li key={event}>
            {chinese ? "事件" : "Event"} {event}
          </li>
        ))}
      </ul>
      <Pagination
        page={page}
        onPageChange={setPage}
        perPage={3}
        hasNextPage={page < batches.length}
        labels={labels}
      >
        <PaginationInfo>
          {({ page: currentPage }) =>
            chinese ? `第 ${currentPage} 批` : `Batch ${currentPage}`
          }
        </PaginationInfo>
        <PaginationControls />
      </Pagination>
      <p className="text-muted-foreground text-sm">
        {chinese
          ? "此模拟接口只返回下一批是否存在，不提供总数；第 3 批没有下一批"
          : "This simulated response reports only whether another batch exists. Batch 3 has no next page."}
      </p>
    </div>
  );
}
```

```tsx
<Pagination
  page={page}
  onPageChange={setPage}
  perPage={20}
  hasNextPage={response.hasNextPage}
/>
```

Without `hasNextPage={true}`, the next button is disabled. Previous navigation remains available after the first page.

## States

Known totals work with middle pages and large datasets. `totalCount={0}` displays `Showing 0–0 of 0` and disables navigation. Root `disabled` also disables the page selector, navigation buttons, and nested page-size selector.

### Example: pagination-states

```tsx
"use client";

import {
  Pagination,
  PaginationControls,
  PaginationInfo,
  PaginationPageSize,
  type PaginationRangeInfo,
} from "@workspace/ui/components/pagination";
import { useState } from "react";
import type { ExampleProps } from "../types";

export default function Example({ locale }: ExampleProps) {
  const chinese = locale === "zh-CN";
  const labels = chinese
    ? {
        navigation: "分页",
        firstPage: "首页",
        previousPage: "上一页",
        nextPage: "下一页",
        lastPage: "末页",
        pageNumber: "页码",
        pageSize: "每页条数",
        range: ({ page, totalCount, from, to }: PaginationRangeInfo) =>
          totalCount === undefined
            ? `第 ${page} 页`
            : `显示第 ${from}–${to} 条，共 ${totalCount} 条`,
      }
    : undefined;
  const [middlePage, setMiddlePage] = useState(5);
  const [largePage, setLargePage] = useState(1);
  const [disabledPage, setDisabledPage] = useState(3);
  const [disabledSize, setDisabledSize] = useState(10);
  return (
    <div className="grid w-full gap-6">
      <div className="grid gap-2">
        <h3 className="font-medium text-sm">
          {chinese ? "中间页" : "Middle page"}
        </h3>
        <Pagination
          page={middlePage}
          onPageChange={setMiddlePage}
          perPage={10}
          totalCount={100}
          labels={labels}
        />
      </div>
      <div className="grid gap-2">
        <h3 className="font-medium text-sm">
          {chinese ? "大数据集" : "Large dataset"}
        </h3>
        <Pagination
          page={largePage}
          onPageChange={setLargePage}
          perPage={25}
          totalCount={1250}
          labels={labels}
        />
      </div>
      <div className="grid gap-2">
        <h3 className="font-medium text-sm">
          {chinese ? "没有结果" : "No results"}
        </h3>
        <Pagination totalCount={0} labels={labels} />
      </div>
      <div className="grid gap-2">
        <h3 className="font-medium text-sm">
          {chinese ? "禁用状态" : "Disabled"}
        </h3>
        <Pagination
          page={disabledPage}
          onPageChange={setDisabledPage}
          perPage={disabledSize}
          totalCount={100}
          disabled
          labels={labels}
        >
          <PaginationInfo />
          <div className="flex flex-wrap items-center gap-3">
            <PaginationPageSize
              value={disabledSize}
              onValueChange={setDisabledSize}
              label={chinese ? "每页条数" : "Rows per page"}
            />
            <PaginationControls />
          </div>
        </Pagination>
      </div>
    </div>
  );
}
```

If the total or page size changes and the requested page is outside the new range, the UI immediately displays the nearest valid page and reports that correction through `onPageChange`.

## Composition

Pass children to arrange the summary, controls, and page-size selector yourself. `PaginationInfo`, `PaginationControls`, and `PaginationPageSize` read shared state from the parent `Pagination`. Passing `children={null}` intentionally renders no default content.

```tsx
import {
  Pagination,
  PaginationControls,
  PaginationInfo,
  PaginationPageSize,
  PaginationSeparator,
} from "@workspace/ui/components/pagination";
```

```text
Pagination
├── PaginationInfo
└── div
    ├── PaginationPageSize
    ├── PaginationSeparator
    └── PaginationControls
```

### Page sizes and custom summaries

`PaginationPageSize` is controlled independently. Keep its `value` synchronized with root `perPage`, and usually return to page `1` when the size changes. Its options default to `[10, 20, 50, 100]`; invalid or repeated options are removed, and the current value is included automatically.

Use a render function in `PaginationInfo` to customize the summary. Alternatively, set `labels.range` once on the root to customize every default `PaginationInfo` summary.

### Example: pagination-custom

```tsx
"use client";

import {
  Pagination,
  PaginationControls,
  PaginationInfo,
  PaginationPageSize,
  type PaginationRangeInfo,
  PaginationSeparator,
} from "@workspace/ui/components/pagination";
import { useState } from "react";
import type { ExampleProps } from "../types";

export default function Example({ locale }: ExampleProps) {
  const chinese = locale === "zh-CN";
  const labels = chinese
    ? {
        navigation: "分页",
        firstPage: "首页",
        previousPage: "上一页",
        nextPage: "下一页",
        lastPage: "末页",
        pageNumber: "页码",
        pageSize: "每页条数",
        range: ({ page, totalCount, from, to }: PaginationRangeInfo) =>
          totalCount === undefined
            ? `第 ${page} 页`
            : `显示第 ${from}–${to} 条，共 ${totalCount} 条`,
      }
    : undefined;
  const [page, setPage] = useState(1);
  const [perPage, setPerPage] = useState(20);
  return (
    <Pagination
      page={page}
      onPageChange={setPage}
      perPage={perPage}
      totalCount={205}
      labels={labels}
    >
      <PaginationInfo>
        {({ page: currentPage, pageCount, perPage: size }) =>
          chinese
            ? `第 ${currentPage} 页／共 ${pageCount} 页，每页 ${size} 条`
            : `Page ${currentPage} of ${pageCount}, ${size} rows per page`
        }
      </PaginationInfo>
      <div className="flex flex-wrap items-center gap-3">
        <PaginationPageSize
          value={perPage}
          onValueChange={(size) => {
            setPerPage(size);
            setPage(1);
          }}
          options={[10, 20, 50]}
          label={chinese ? "每页条数" : "Rows per page"}
        />
        <PaginationSeparator className="h-5" />
        <PaginationControls />
      </div>
    </Pagination>
  );
}
```

```tsx
<Pagination
  page={page}
  onPageChange={setPage}
  perPage={perPage}
  totalCount={205}
>
  <PaginationInfo>
    {({ page, pageCount, perPage }) =>
      `Page ${page} of ${pageCount}, ${perPage} rows per page`
    }
  </PaginationInfo>
  <div className="flex flex-wrap items-center gap-3">
    <PaginationPageSize
      value={perPage}
      onValueChange={(size) => {
        setPerPage(size);
        setPage(1);
      }}
      options={[10, 20, 50]}
      label="Rows per page"
    />
    <PaginationSeparator />
    <PaginationControls />
  </div>
</Pagination>
```

### Dropdown page selector

Set `pageSelector="dropdown"` on `PaginationControls` to select a page from a menu. This applies to full controls with a known total. Above 200 pages, it automatically falls back to the numeric input to keep the menu bounded.

### Example: pagination-dropdown

```tsx
"use client";

import {
  Pagination,
  PaginationControls,
  PaginationInfo,
  PaginationPageSize,
  type PaginationRangeInfo,
  PaginationSeparator,
} from "@workspace/ui/components/pagination";
import { useState } from "react";
import type { ExampleProps } from "../types";

export default function Example({ locale }: ExampleProps) {
  const chinese = locale === "zh-CN";
  const labels = chinese
    ? {
        navigation: "分页",
        firstPage: "首页",
        previousPage: "上一页",
        nextPage: "下一页",
        lastPage: "末页",
        pageNumber: "页码",
        pageSize: "每页条数",
        range: ({ page, totalCount, from, to }: PaginationRangeInfo) =>
          totalCount === undefined
            ? `第 ${page} 页`
            : `显示第 ${from}–${to} 条，共 ${totalCount} 条`,
      }
    : undefined;
  const [page, setPage] = useState(1);
  const [perPage, setPerPage] = useState(25);
  return (
    <Pagination
      page={page}
      onPageChange={setPage}
      perPage={perPage}
      totalCount={500}
      labels={labels}
    >
      <PaginationInfo />
      <div className="flex flex-wrap items-center gap-3">
        <PaginationControls pageSelector="dropdown" />
        <PaginationSeparator className="h-5" />
        <PaginationPageSize
          value={perPage}
          onValueChange={(size) => {
            setPerPage(size);
            setPage(1);
          }}
          options={[10, 25, 50]}
          label={chinese ? "每页条数" : "Rows per page"}
        />
      </div>
    </Pagination>
  );
}
```

```tsx
<Pagination page={page} onPageChange={setPage} perPage={25} totalCount={500}>
  <PaginationInfo />
  <PaginationControls pageSelector="dropdown" />
</Pagination>
```

## Icons only

Combine simple controls with a page-size selector for a compact table footer. The navigation buttons use icons with accessible labels.

### Example: pagination-icons-only

```tsx
"use client";

import {
  Pagination,
  PaginationControls,
  PaginationInfo,
  PaginationPageSize,
  type PaginationRangeInfo,
  PaginationSeparator,
} from "@workspace/ui/components/pagination";
import { useState } from "react";
import type { ExampleProps } from "../types";

export default function Example({ locale }: ExampleProps) {
  const chinese = locale === "zh-CN";
  const labels = chinese
    ? {
        navigation: "分页",
        firstPage: "首页",
        previousPage: "上一页",
        nextPage: "下一页",
        lastPage: "末页",
        pageNumber: "页码",
        pageSize: "每页条数",
        range: ({ page, totalCount, from, to }: PaginationRangeInfo) =>
          totalCount === undefined
            ? `第 ${page} 页`
            : `显示第 ${from}–${to} 条，共 ${totalCount} 条`,
      }
    : undefined;
  const [page, setPage] = useState(1);
  const [perPage, setPerPage] = useState(25);
  return (
    <Pagination
      page={page}
      onPageChange={setPage}
      perPage={perPage}
      totalCount={150}
      controls="simple"
      labels={labels}
    >
      <PaginationInfo />
      <div className="flex flex-wrap items-center gap-3">
        <PaginationPageSize
          value={perPage}
          onValueChange={(size) => {
            setPerPage(size);
            setPage(1);
          }}
          options={[10, 25, 50]}
          label={chinese ? "每页条数" : "Rows per page"}
        />
        <PaginationSeparator className="h-5" />
        <PaginationControls />
      </div>
    </Pagination>
  );
}
```

## Traditional numbered links

The existing `PaginationContent`, `PaginationItem`, `PaginationLink`, `PaginationPrevious`, `PaginationNext`, and `PaginationEllipsis` components remain available for URL-based navigation. They do not automatically update root page state or generate page numbers; supply the links, current page, and disabled boundaries yourself.

`PaginationLink` renders an anchor and uses `isActive` to set `aria-current="page"`. Disabled links have no `href`, are removed from the Tab order, and ignore click handlers. The example uses meaningful `?page=N` destinations and handles navigation locally so the preview stays on the documentation page.

### Example: pagination-links

```tsx
"use client";

import {
  Pagination,
  PaginationContent,
  PaginationItem,
  PaginationLink,
  PaginationNext,
  PaginationPrevious,
} from "@workspace/ui/components/pagination";
import { useState } from "react";
import type { ExampleProps } from "../types";

const pageNumbers = [1, 2, 3, 4, 5];
export default function Example({ locale }: ExampleProps) {
  const chinese = locale === "zh-CN";
  const [page, setPage] = useState(2);
  return (
    <div className="grid w-full gap-4">
      <Pagination
        aria-label={chinese ? "数字链接分页" : "Numbered pagination links"}
      >
        <PaginationContent>
          <PaginationItem>
            <PaginationPrevious
              href={`?page=${Math.max(1, page - 1)}`}
              disabled={page === 1}
              text={chinese ? "上一页" : "Previous"}
              aria-label={chinese ? "上一页" : "Previous page"}
              onClick={(event) => {
                event.preventDefault();
                setPage(Math.max(1, page - 1));
              }}
            />
          </PaginationItem>
          {pageNumbers.map((number) => (
            <PaginationItem key={number}>
              <PaginationLink
                href={`?page=${number}`}
                isActive={page === number}
                aria-label={chinese ? `第 ${number} 页` : `Page ${number}`}
                onClick={(event) => {
                  event.preventDefault();
                  setPage(number);
                }}
              >
                {number}
              </PaginationLink>
            </PaginationItem>
          ))}
          <PaginationItem>
            <PaginationNext
              href={`?page=${Math.min(5, page + 1)}`}
              disabled={page === 5}
              text={chinese ? "下一页" : "Next"}
              aria-label={chinese ? "下一页" : "Next page"}
              onClick={(event) => {
                event.preventDefault();
                setPage(Math.min(5, page + 1));
              }}
            />
          </PaginationItem>
        </PaginationContent>
      </Pagination>
      <output className="text-muted-foreground text-sm" aria-live="polite">
        {chinese ? `当前页：${page}` : `Current page: ${page}`}
      </output>
    </div>
  );
}
```

```tsx
import {
  Pagination,
  PaginationContent,
  PaginationEllipsis,
  PaginationItem,
  PaginationLink,
  PaginationNext,
  PaginationPrevious,
} from "@workspace/ui/components/pagination";
```

```tsx
<Pagination>
  <PaginationContent>
    <PaginationItem>
      <PaginationPrevious href="?page=1" text="Previous" />
    </PaginationItem>
    <PaginationItem>
      <PaginationLink href="?page=1">1</PaginationLink>
    </PaginationItem>
    <PaginationItem>
      <PaginationLink href="?page=2" isActive>2</PaginationLink>
    </PaginationItem>
    <PaginationItem>
      <PaginationEllipsis />
    </PaginationItem>
    <PaginationItem>
      <PaginationNext href="?page=3" text="Next" />
    </PaginationItem>
  </PaginationContent>
</Pagination>
```

## RTL

Wrap right-to-left interfaces in the shared `DirectionProvider` and set `dir="rtl"` on the relevant container. Navigation icons mirror automatically. Pass translated `labels` and a localized `range` formatter separately; direction does not select a language.

### Example: pagination-rtl

```tsx
"use client";

import { DirectionProvider } from "@workspace/ui/components/direction";
import {
  Pagination,
  type PaginationRangeInfo,
} from "@workspace/ui/components/pagination";
import { useState } from "react";
import type { ExampleProps } from "../types";

export default function Example({ locale }: ExampleProps) {
  const chinese = locale === "zh-CN";
  const labels = chinese
    ? {
        navigation: "分页",
        firstPage: "首页",
        previousPage: "上一页",
        nextPage: "下一页",
        lastPage: "末页",
        pageNumber: "页码",
        pageSize: "每页条数",
        range: ({ page, totalCount, from, to }: PaginationRangeInfo) =>
          totalCount === undefined
            ? `第 ${page} 页`
            : `显示第 ${from}–${to} 条，共 ${totalCount} 条`,
      }
    : undefined;
  const [page, setPage] = useState(5);
  return (
    <DirectionProvider direction="rtl">
      <div dir="rtl" className="w-full">
        <Pagination
          page={page}
          onPageChange={setPage}
          perPage={10}
          totalCount={100}
          labels={labels}
        />
      </div>
    </DirectionProvider>
  );
}
```

## Accessibility and localization

The root is a labeled `nav`. Every icon button and selector has an accessible name from `labels`; `PaginationInfo` announces summary changes politely. All data-navigation buttons use `type="button"`.

The page input supports keyboard editing, Enter to commit, and Escape to restore the current page. The dropdown selectors use the shared [Select](/docs/components/select) component and its keyboard behavior.

Translate `navigation`, `firstPage`, `previousPage`, `nextPage`, `lastPage`, `pageNumber`, `pageSize`, and `range`. For traditional links, also translate the visible `text` on `PaginationPrevious` and `PaginationNext`, and provide meaningful labels for numbered links. Set the `PaginationPageSize` visible `label` explicitly when localizing it.

## API reference

### Pagination

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `page` | `number` | Internal state, initially `1` | Controlled one-based page. |
| `onPageChange` | `(page: number) => void` | — | Reports navigation and corrections after range changes. |
| `perPage` | `number` | `10` | Items per page. |
| `totalCount` | `number` | — | Total items; omit for unknown totals. |
| `hasNextPage` | `boolean` | — | Enables the next page when the total is unknown. |
| `controls` | `"full" \| "simple"` | `"full"` | Default controls mode. |
| `disabled` | `boolean` | `false` | Disables nested navigation and selectors. |
| `labels` | `PaginationLabels` | English labels | Accessible names and summary formatter. |
| `children` | `ReactNode` | Info + controls | Custom composition; `null` suppresses the default layout. |

Other native `nav` props, including `className`, `aria-label`, and `ref`, are forwarded.

### Parts

| Component | Additional props | Behavior |
| --- | --- | --- |
| `PaginationInfo` | `children?: ReactNode \| ((info: PaginationRangeInfo) => ReactNode)` | Custom content or summary render function. |
| `PaginationControls` | `controls?: "full" \| "simple"`, `pageSelector?: "input" \| "dropdown"` | Inherits root mode; selector defaults to `"input"`. |
| `PaginationPageSize` | `value: number`, `onValueChange: (value: number) => void`, `options?: readonly number[]`, `label?: ReactNode`, `disabled?: boolean` | Controlled size selector; visible label defaults to `"Rows per page"`; `label={null}` hides it. |
| `PaginationSeparator` | [Separator props](/docs/components/separator) | Vertical by default. |
| `PaginationLink` | `isActive?: boolean`, `disabled?: boolean`, `size` | Native anchor props plus active and disabled states. |
| `PaginationPrevious`, `PaginationNext` | Link props, `text?: string` | Previous/next links; visible text defaults to `"Previous"`/`"Next"`. |

`PaginationInfo`, `PaginationControls`, and `PaginationPageSize` forward native `div` props. `PaginationRangeInfo` contains `page`, `perPage`, `from`, `to`, and optional `totalCount` and `pageCount`. Empty known totals produce `from=0`, `to=0`, and `pageCount=1`.

The range, labels, and component prop types are exported from `@workspace/ui/components/pagination`. The composed selectors use the shared Select wrapper; see the [Base UI Select API](https://base-ui.com/react/components/select) for its underlying behavior.


---

# Popover

Displays rich content in a portal, triggered by a button.

Page: https://sui.draco.dev/docs/components/popover

### Example: popover-demo

```tsx
import { Button } from "@workspace/ui/components/button";
import { Input } from "@workspace/ui/components/input";
import { Label } from "@workspace/ui/components/label";
import {
  Popover,
  PopoverContent,
  PopoverTrigger,
} from "@workspace/ui/components/popover";
import { useId as usePreviewId } from "react";

export default function PopoverDemo() {
  const previewId = usePreviewId();

  return (
    <Popover>
      <PopoverTrigger render={<Button variant="outline" />}>
        Open popover
      </PopoverTrigger>
      <PopoverContent className="w-80">
        <div className="grid gap-4">
          <div className="space-y-2">
            <h4 className="font-medium leading-none">Dimensions</h4>
            <p className="text-muted-foreground text-sm">
              Set the dimensions for the layer.
            </p>
          </div>
          <div className="grid gap-2">
            <div className="grid grid-cols-3 items-center gap-4">
              <Label htmlFor={`${previewId}-width`}>Width</Label>
              <Input
                id={`${previewId}-width`}
                defaultValue="100%"
                className="col-span-2 h-8"
              />
            </div>
            <div className="grid grid-cols-3 items-center gap-4">
              <Label htmlFor={`${previewId}-maxWidth`}>Max. width</Label>
              <Input
                id={`${previewId}-maxWidth`}
                defaultValue="300px"
                className="col-span-2 h-8"
              />
            </div>
            <div className="grid grid-cols-3 items-center gap-4">
              <Label htmlFor={`${previewId}-height`}>Height</Label>
              <Input
                id={`${previewId}-height`}
                defaultValue="25px"
                className="col-span-2 h-8"
              />
            </div>
            <div className="grid grid-cols-3 items-center gap-4">
              <Label htmlFor={`${previewId}-maxHeight`}>Max. height</Label>
              <Input
                id={`${previewId}-maxHeight`}
                defaultValue="none"
                className="col-span-2 h-8"
              />
            </div>
          </div>
        </div>
      </PopoverContent>
    </Popover>
  );
}
```

## Installation

```bash
bunx --bun shadcn@latest add @sui/popover
```

Install with the shadcn CLI or use the shared `@workspace/ui` package. Follow the [installation guide](/docs/installation) to configure the registry, load styles, and choose import aliases.

## Usage

```tsx showLineNumbers
import {
  Popover,
  PopoverContent,
  PopoverDescription,
  PopoverHeader,
  PopoverTitle,
  PopoverTrigger,
} from "@workspace/ui/components/popover"
```

```tsx showLineNumbers
<Popover>
  <PopoverTrigger render={<Button variant="outline" />}>
    Open Popover
  </PopoverTrigger>
  <PopoverContent>
    <PopoverHeader>
      <PopoverTitle>Title</PopoverTitle>
      <PopoverDescription>Description text here.</PopoverDescription>
    </PopoverHeader>
  </PopoverContent>
</Popover>
```

## Composition

Use the following composition to build a `Popover`:

```text
Popover
├── PopoverTrigger
└── PopoverContent
```

## Basic

A simple popover with a header, title, and description.

### Example: popover-basic

```tsx
import { Button } from "@workspace/ui/components/button";
import {
  Popover,
  PopoverContent,
  PopoverDescription,
  PopoverHeader,
  PopoverTitle,
  PopoverTrigger,
} from "@workspace/ui/components/popover";

export function PopoverBasic() {
  return (
    <Popover>
      <PopoverTrigger render={<Button variant="outline" className="w-fit" />}>
        Open Popover
      </PopoverTrigger>
      <PopoverContent align="start">
        <PopoverHeader>
          <PopoverTitle>Dimensions</PopoverTitle>
          <PopoverDescription>
            Set the dimensions for the layer.
          </PopoverDescription>
        </PopoverHeader>
      </PopoverContent>
    </Popover>
  );
}

export default PopoverBasic;
```

## Align

Use the `align` prop on `PopoverContent` to control the horizontal alignment.

### Example: popover-alignments

```tsx
import { Button } from "@workspace/ui/components/button";
import {
  Popover,
  PopoverContent,
  PopoverTrigger,
} from "@workspace/ui/components/popover";

export function PopoverAlignments() {
  return (
    <div className="flex gap-6">
      <Popover>
        <PopoverTrigger render={<Button variant="outline" size="sm" />}>
          Start
        </PopoverTrigger>
        <PopoverContent align="start" className="w-40">
          Aligned to start
        </PopoverContent>
      </Popover>
      <Popover>
        <PopoverTrigger render={<Button variant="outline" size="sm" />}>
          Center
        </PopoverTrigger>
        <PopoverContent align="center" className="w-40">
          Aligned to center
        </PopoverContent>
      </Popover>
      <Popover>
        <PopoverTrigger render={<Button variant="outline" size="sm" />}>
          End
        </PopoverTrigger>
        <PopoverContent align="end" className="w-40">
          Aligned to end
        </PopoverContent>
      </Popover>
    </div>
  );
}

export default PopoverAlignments;
```

## With Form

A popover with form fields inside.

### Example: popover-form

```tsx
import { Button } from "@workspace/ui/components/button";
import { Field, FieldGroup, FieldLabel } from "@workspace/ui/components/field";
import { Input } from "@workspace/ui/components/input";
import {
  Popover,
  PopoverContent,
  PopoverDescription,
  PopoverHeader,
  PopoverTitle,
  PopoverTrigger,
} from "@workspace/ui/components/popover";
import { useId as usePreviewId } from "react";

export function PopoverForm() {
  const previewId = usePreviewId();

  return (
    <Popover>
      <PopoverTrigger render={<Button variant="outline" />}>
        Open Popover
      </PopoverTrigger>
      <PopoverContent className="w-64" align="start">
        <PopoverHeader>
          <PopoverTitle>Dimensions</PopoverTitle>
          <PopoverDescription>
            Set the dimensions for the layer.
          </PopoverDescription>
        </PopoverHeader>
        <FieldGroup className="gap-4">
          <Field orientation="horizontal">
            <FieldLabel htmlFor={`${previewId}-width`} className="w-1/2">
              Width
            </FieldLabel>
            <Input id={`${previewId}-width`} defaultValue="100%" />
          </Field>
          <Field orientation="horizontal">
            <FieldLabel htmlFor={`${previewId}-height`} className="w-1/2">
              Height
            </FieldLabel>
            <Input id={`${previewId}-height`} defaultValue="25px" />
          </Field>
        </FieldGroup>
      </PopoverContent>
    </Popover>
  );
}

export default PopoverForm;
```

## RTL

To enable RTL support in shadcn/ui, see the [RTL configuration guide](https://ui.shadcn.com/docs/rtl).

### Example: popover-rtl

```tsx
"use client";

import { Button } from "@workspace/ui/components/button";
import {
  Popover,
  PopoverContent,
  PopoverDescription,
  PopoverHeader,
  PopoverTitle,
  PopoverTrigger,
} from "@workspace/ui/components/popover";
import { type Translations, useTranslation } from "./support";

const translations: Translations = {
  en: {
    dir: "ltr",
    values: {
      title: "Dimensions",
      description: "Set the dimensions for the layer.",
      "inline-start": "Inline Start",
      left: "Left",
      top: "Top",
      bottom: "Bottom",
      right: "Right",
      "inline-end": "Inline End",
    },
  },
  ar: {
    dir: "rtl",
    values: {
      title: "الأبعاد",
      description: "تعيين الأبعاد للطبقة.",
      "inline-start": "بداية السطر",
      left: "يسار",
      top: "أعلى",
      bottom: "أسفل",
      right: "يمين",
      "inline-end": "نهاية السطر",
    },
  },
  he: {
    dir: "rtl",
    values: {
      title: "מימדים",
      description: "הגדר את המימדים לשכבה.",
      "inline-start": "תחילת השורה",
      left: "שמאל",
      top: "למעלה",
      bottom: "למטה",
      right: "ימין",
      "inline-end": "סוף השורה",
    },
  },
};

const physicalSides = ["left", "top", "bottom", "right"] as const;
const logicalSides = ["inline-start", "inline-end"] as const;

export function PopoverRtl() {
  const { dir, t } = useTranslation(translations, "ar");

  return (
    <div className="grid gap-4">
      <div className="flex flex-wrap justify-center gap-2">
        {physicalSides.map((side) => (
          <Popover key={side}>
            <PopoverTrigger render={<Button variant="outline" />}>
              {t[side]}
            </PopoverTrigger>
            <PopoverContent side={side} dir={dir}>
              <PopoverHeader>
                <PopoverTitle>{t.title}</PopoverTitle>
                <PopoverDescription>{t.description}</PopoverDescription>
              </PopoverHeader>
            </PopoverContent>
          </Popover>
        ))}
      </div>
      <div className="flex flex-wrap justify-center gap-2">
        {logicalSides.map((side) => (
          <Popover key={side}>
            <PopoverTrigger render={<Button variant="outline" />}>
              {t[side]}
            </PopoverTrigger>
            <PopoverContent side={side} dir={dir}>
              <PopoverHeader>
                <PopoverTitle>{t.title}</PopoverTitle>
                <PopoverDescription>{t.description}</PopoverDescription>
              </PopoverHeader>
            </PopoverContent>
          </Popover>
        ))}
      </div>
    </div>
  );
}

export default PopoverRtl;
```

## API Reference

See the [Base UI Popover](https://base-ui.com/react/components/popover#api-reference) documentation.

- [Documentation](https://base-ui.com/react/components/popover)
- [API reference](https://base-ui.com/react/components/popover#api-reference)


---

# Progress

Displays an indicator showing the completion progress of a task, typically displayed as a progress bar.

Page: https://sui.draco.dev/docs/components/progress

### Example: progress-demo

```tsx
"use client";

import { Progress } from "@workspace/ui/components/progress";
import * as React from "react";

export default function ProgressDemo() {
  const [progress, setProgress] = React.useState(13);

  React.useEffect(() => {
    const timer = setTimeout(() => setProgress(66), 500);
    return () => clearTimeout(timer);
  }, []);

  return <Progress value={progress} className="w-[60%]" />;
}
```

## Installation

```bash
bunx --bun shadcn@latest add @sui/progress
```

Install with the shadcn CLI or use the shared `@workspace/ui` package. Follow the [installation guide](/docs/installation) to configure the registry, load styles, and choose import aliases.

## Usage

```tsx showLineNumbers
import { Progress } from "@workspace/ui/components/progress"
```

```tsx showLineNumbers
<Progress value={33} />
```

## Composition

### With label and value

Use `ProgressLabel` and `ProgressValue` to add a label and value display.

```tsx showLineNumbers
import {
  Progress,
  ProgressLabel,
  ProgressValue,
} from "@workspace/ui/components/progress"

;<Progress value={56} className="w-full max-w-sm">
  <ProgressLabel>Upload progress</ProgressLabel>
  <ProgressValue />
</Progress>
```

```text
Progress
├── ProgressLabel
├── ProgressValue
└── ProgressTrack
    └── ProgressIndicator
```

## Label

Use `ProgressLabel` and `ProgressValue` to add a label and value display.

### Example: progress-label

```tsx
import {
  Progress,
  ProgressLabel,
  ProgressValue,
} from "@workspace/ui/components/progress";

export function ProgressWithLabel() {
  return (
    <Progress value={56} className="w-full max-w-sm">
      <ProgressLabel>Upload progress</ProgressLabel>
      <ProgressValue />
    </Progress>
  );
}

export default ProgressWithLabel;
```

## Controlled

A progress bar that can be controlled by a slider.

### Example: progress-controlled

```tsx
"use client";

import { Progress } from "@workspace/ui/components/progress";
import { Slider } from "@workspace/ui/components/slider";
import * as React from "react";

export function ProgressControlled() {
  const [value, setValue] = React.useState(50);

  return (
    <div className="flex w-full max-w-sm flex-col gap-4">
      <Progress value={value} className="w-full" />
      <Slider
        value={value}
        onValueChange={(value) => setValue(value as number)}
        min={0}
        max={100}
        step={1}
      />
    </div>
  );
}

export default ProgressControlled;
```

## RTL

To enable RTL support in shadcn/ui, see the [RTL configuration guide](https://ui.shadcn.com/docs/rtl).

### Example: progress-rtl

```tsx
"use client";

import {
  Progress,
  ProgressLabel,
  ProgressValue,
} from "@workspace/ui/components/progress";
import { type Translations, useTranslation } from "./support";

const translations: Translations = {
  en: {
    dir: "ltr",
    values: {
      label: "Upload progress",
    },
  },
  ar: {
    dir: "rtl",
    values: {
      label: "تقدم الرفع",
    },
  },
  he: {
    dir: "rtl",
    values: {
      label: "התקדמות העלאה",
    },
  },
};

function toArabicNumerals(num: number): string {
  const arabicNumerals = ["٠", "١", "٢", "٣", "٤", "٥", "٦", "٧", "٨", "٩"];
  return num
    .toString()
    .split("")
    .map((digit) => arabicNumerals[parseInt(digit, 10)])
    .join("");
}

export function ProgressRtl() {
  const { dir, t, language } = useTranslation(translations, "ar");

  const formatNumber = (num: number): string => {
    if (language === "ar") {
      return toArabicNumerals(num);
    }
    return num.toString();
  };

  return (
    <Progress value={56} className="w-full max-w-sm" dir={dir}>
      <ProgressLabel>{t.label}</ProgressLabel>
      <ProgressValue>
        {(value) => (
          <span className="ms-auto">
            {formatNumber(parseFloat(value ?? "0"))}%
          </span>
        )}
      </ProgressValue>
    </Progress>
  );
}

export default ProgressRtl;
```

## API Reference

See the [Base UI Progress](https://base-ui.com/react/components/progress#api-reference) documentation.

- [Documentation](https://base-ui.com/react/components/progress)
- [API reference](https://base-ui.com/react/components/progress#api-reference)


---

# QRCode

A theme-aware QR code with loading feedback and optional reveal animation.

Page: https://sui.draco.dev/docs/components/qr-code

### Example: qr-code-demo

```tsx
"use client";
import { Input } from "@workspace/ui/components/input";
import { Label } from "@workspace/ui/components/label";
import { QRCode } from "@workspace/ui/components/qr-code";
import { useId, useState } from "react";
import type { ExampleProps } from "../types";
export default function Example({ locale }: ExampleProps) {
  const chinese = locale === "zh-CN";
  const id = useId();
  const [value, setValue] = useState("https://example.com/");
  return (
    <div className="grid w-full gap-4 sm:grid-cols-[1fr_auto]">
      <div className="grid content-start gap-2">
        <Label htmlFor={id}>{chinese ? "编码内容" : "Content to encode"}</Label>
        <Input
          id={id}
          value={value}
          onChange={(event) => setValue(event.target.value)}
        />
        <p className="text-muted-foreground text-sm">
          {chinese
            ? "编辑内容后二维码会更新。空值显示占位内容"
            : "Edit the content to regenerate the code. An empty value shows a placeholder."}
        </p>
      </div>
      <QRCode
        value={value}
        size={180}
        label={
          chinese ? "当前输入内容的二维码" : "QR code for the current input"
        }
      />
    </div>
  );
}
```

## Installation

```bash
bunx --bun shadcn@latest add @sui/qr-code
```

Install with the shadcn CLI or use the shared `@workspace/ui` package. Follow the [installation guide](/docs/installation) to configure the registry, load styles, and choose import aliases.

## Usage

```tsx
import { QRCode } from "@workspace/ui/components/qr-code";

<QRCode value="https://example.com/" label="Example website QR code" size={220} />;
```

## Loading and empty states

Generation loads on demand in the client. The server renders a stable loading placeholder. Changing `value` generates a fresh code and discards the previous request result. `loading` keeps the placeholder visible even if generation has completed. An absent or empty value keeps the loading placeholder rather than generating an invalid code.

By default, the code uses the neutral `--foreground` color on a solid `--card` surface. It follows light and dark modes without inheriting the accent color. Theme changes recolor the existing code without generating it again. The basic code appears as soon as its image loads. Loading and empty states use independently pulsing dots with a roughly 800ms blur entrance and no visible text. Generation failures show an error icon. The loading dots, error icon, and logo surface follow the same neutral theme. The logo appears only when the code is ready.

### Example: qr-code-states

```tsx
"use client";
import { QRCode } from "@workspace/ui/components/qr-code";
import type { ExampleProps } from "../types";
export default function Example({ locale }: ExampleProps) {
  const chinese = locale === "zh-CN";
  return (
    <div className="grid w-full gap-4 sm:grid-cols-3">
      <div className="grid content-start justify-items-center gap-3">
        <span className="text-sm">
          {chinese ? "基础二维码" : "Basic QR code"}
        </span>
        <QRCode
          value="SUI"
          size={144}
          label={chinese ? "包含 SUI 文字的二维码" : "QR code containing SUI"}
        />
      </div>
      <div className="grid content-start justify-items-center gap-3">
        <span className="text-sm">{chinese ? "加载中" : "Loading"}</span>
        <QRCode value="SUI" loading size={144} />
      </div>
      <div className="grid content-start justify-items-center gap-3">
        <span className="text-sm">{chinese ? "尚无内容" : "No content"}</span>
        <QRCode
          size={144}
          label={chinese ? "尚无二维码内容" : "No QR code content yet"}
        />
      </div>
    </div>
  );
}
```

## Optional animation

Enable `animated` for a roughly 750ms reveal. Both modes use the dot-matrix skeleton while loading. Reduced motion freezes the dots and skips the reveal. The basic version displays the result directly.

### Example: qr-code-animated

```tsx
"use client";
import { QRCode } from "@workspace/ui/components/qr-code";
import type { ExampleProps } from "../types";

export default function Example({ locale }: ExampleProps) {
  const chinese = locale === "zh-CN";
  return (
    <QRCode
      value="https://example.com/"
      animated
      size={220}
      label={chinese ? "动画二维码" : "Animated QR code"}
    />
  );
}
```

## Margin and finder patterns

`margin` controls the quiet space around the code in CSS pixels at the requested `size`, defaulting to `16`. Set it to `0` to supply your own solid-color quiet zone. It scales with the code in smaller containers. Negative values become zero, excessive values are limited to `size / 2 - 4`, and non-finite values use the default.

Finder patterns use concentric rounded outer rings and rounded solid centers. Their outer edge, inner edge, and center have corner radii of `2.5`, `1.5`, and `0.5` modules, preserving the same corner centers as each edge moves inward. Insufficient quiet space, small sizes, and busy backgrounds reduce scan reliability. Verify scanning at the actual display size.

### Example: qr-code-margin

```tsx
"use client";

import { QRCode } from "@workspace/ui/components/qr-code";
import type { ExampleProps } from "../types";

export default function Example({ locale }: ExampleProps) {
  const chinese = locale === "zh-CN";
  return (
    <div className="grid w-full gap-6 sm:grid-cols-3">
      {[0, 16, 24].map((margin) => (
        <div key={margin} className="grid justify-items-center gap-3">
          <QRCode
            value="https://example.com/"
            size={160}
            margin={margin}
            label={chinese ? "示例链接二维码" : "Example link QR code"}
          />
          <span className="text-muted-foreground text-sm">margin={margin}</span>
        </div>
      ))}
    </div>
  );
}
```

## Logo and scan reliability

`logo` places a small React node over the center. The generator uses high error correction and retains the surrounding quiet zone. Keep the logo small, preserve the quiet zone, and verify scanning at the size and background where the code will be used. A logo can still reduce scan reliability even with error correction.

`QRCode` renders only the code. Compose your own layout or caption when needed. The code stays sharp while its neutral foreground and default solid background follow the theme. Test both light and dark modes with the scanners your application supports.

### Example: qr-code-logo

```tsx
"use client";
import { QRCode } from "@workspace/ui/components/qr-code";
import type { ExampleProps } from "../types";
export default function Example({ locale }: ExampleProps) {
  const chinese = locale === "zh-CN";
  return (
    <QRCode
      value="https://example.com/"
      size={220}
      label={chinese ? "示例链接二维码" : "Example link QR code"}
      logo={
        <span
          className="grid size-7 place-items-center rounded-md bg-black text-white text-xs"
          aria-hidden="true"
        >
          S
        </span>
      }
    />
  );
}
```

## Glass mode

Enable `glass` to use the shared glass material across the entire background, and configure its material and rendering mode with `GlassProvider`. The code fills the surface without a separate rim or solid inner panel. Its `--foreground` modules remain sharp SVG content over the transparent code layer; the small logo surface remains solid. Switching the theme or glass material preserves the encoded content. `glassMaterial` overrides the provider material for this instance.

The background behind the glass changes the visible contrast and quiet zone. Test scanning on the actual background, in both appearance modes and at the final display size. Glass does not guarantee the contrast of the default solid surface.

### Example: qr-code-glass

```tsx
"use client";

import { GlassProvider } from "@workspace/ui/components/glass";
import { QRCode } from "@workspace/ui/components/qr-code";
import type { ExampleProps } from "../types";

export default function Example({ locale }: ExampleProps) {
  const chinese = locale === "zh-CN";
  const defaultLabel = chinese ? "默认" : "Default";
  return (
    <GlassProvider mode="css" material="clear">
      <div className="grid w-full gap-6 rounded-2xl bg-[linear-gradient(135deg,var(--primary),var(--background)_45%,var(--primary))] p-8 sm:grid-cols-2">
        {[false, true].map((glass) => (
          <div key={String(glass)} className="grid justify-items-center gap-3">
            <QRCode
              value="https://example.com/"
              size={200}
              glass={glass}
              label={chinese ? "示例链接二维码" : "Example link QR code"}
            />
            <span className="text-sm">{glass ? "glass" : defaultLabel}</span>
          </div>
        ))}
      </div>
    </GlassProvider>
  );
}
```

## API reference

| Prop | Type | Default / behavior |
| --- | --- | --- |
| `value` | `string` | Content to encode; empty keeps placeholder. |
| `loading` | `boolean` | `false`. |
| `animated` | `boolean` | `false`; optional reveal animation. |
| `size` | `number` | `256`; requested width, bounded to 64–1024 pixels and constrained by the container. |
| `label` | `string` | `"QR code"`; accessible description. |
| `margin` | `number` | `16`; quiet space in CSS pixels at the requested size. |
| `glass` | `boolean` | Off by default; uses glass across the code background. |
| `glassMaterial` | `"clear" \| "frosted"` | Overrides the provider material. |
| `logo` | `ReactNode` | Optional center overlay. |
| `render`, `ref`, other props | Div / useRender props | Forwarded to the root. |

The module exports `QRCode`, `QRCodeProps`, and `qrCodeVariants`. Generation uses [qr-code-styling](https://github.com/kozakdenys/qr-code-styling).


---

# Questionnaire

A multi-step questionnaire with single-choice, multiple-choice, freeform, and skippable questions.

Page: https://sui.draco.dev/docs/components/questionnaire

### Example: questionnaire-demo

```tsx
"use client";

import {
  Questionnaire,
  QuestionnaireActions,
  QuestionnaireChoice,
  QuestionnaireChoices,
  QuestionnaireDescription,
  QuestionnaireError,
  QuestionnaireInput,
  QuestionnaireItem,
  QuestionnaireNext,
  QuestionnairePrevious,
  QuestionnaireProgress,
  QuestionnaireSkip,
  QuestionnaireSubmit,
  QuestionnaireTitle,
} from "@workspace/ui/components/questionnaire";
import { toast } from "@workspace/ui/components/toast";
import type * as React from "react";

const questionnaireItems = [
  {
    choices: [
      {
        description: "Show what the agent ran and what came back.",
        label: "Tool call timeline",
        value: "tool-calls",
      },
      {
        description: "Ask before sensitive or destructive actions.",
        label: "Approval checkpoints",
        value: "approvals",
      },
      {
        description: "Make delegated work and results easier to follow.",
        label: "Sub-agent handoffs",
        value: "handoffs",
      },
    ],
    description: "Choose a direction or describe another task.",
    input: {
      label: "Another agent feature",
      placeholder: "Describe another feature…",
    },
    name: "direction",
    required: true,
    title: "What should the agent build next?",
  },
  {
    choices: [
      { label: "Progress", value: "progress" },
      { label: "Decisions", value: "decisions" },
      { label: "Risks", value: "risks" },
      { label: "Next step", value: "next-step" },
    ],
    description: "Select all that apply, or skip this question.",
    multiple: true,
    name: "signals",
    required: false,
    title: "What should every progress update include?",
  },
  {
    choices: [
      { label: "Start now", value: "now" },
      { label: "Next development cycle", value: "next-cycle" },
      { label: "Add it to the backlog", value: "backlog" },
    ],
    description: "Choose when the agent should begin the work.",
    name: "timing",
    required: true,
    title: "When should work begin?",
  },
] as const;

export function QuestionnaireDemo() {
  function handleSubmit(event: React.FormEvent<HTMLFormElement>) {
    event.preventDefault();

    const formData = new FormData(event.currentTarget);
    const answers = {
      direction: formData.get("direction"),
      signals: formData.getAll("signals"),
      timing: formData.get("timing"),
    };

    toast.add({
      title: "Agent plan saved",
      ...{
        description: `Direction: ${answers.direction ?? "None"} · Progress signals: ${answers.signals.join(", ") || "None"} · Timing: ${answers.timing ?? "None"}`,
      },
    });
  }

  return (
    <Questionnaire
      className="mx-auto max-w-md"
      defaultItem="direction"
      items={questionnaireItems}
      shortcuts="letters"
      onSubmit={handleSubmit}
    >
      <QuestionnaireProgress />
      {questionnaireItems.map((question) => (
        <QuestionnaireItem
          key={question.name}
          multiple={"multiple" in question && question.multiple}
          name={question.name}
          required={question.required}
        >
          <QuestionnaireTitle>{question.title}</QuestionnaireTitle>
          <QuestionnaireDescription>
            {question.description}
          </QuestionnaireDescription>
          <QuestionnaireChoices>
            {question.choices.map((choice) => (
              <QuestionnaireChoice key={choice.value} value={choice.value}>
                <span className="font-medium">{choice.label}</span>
                {"description" in choice ? (
                  <span className="text-muted-foreground">
                    {choice.description}
                  </span>
                ) : null}
              </QuestionnaireChoice>
            ))}
            {"input" in question ? (
              <QuestionnaireInput
                aria-label={question.input.label}
                placeholder={question.input.placeholder}
              />
            ) : null}
          </QuestionnaireChoices>
          <QuestionnaireError />
        </QuestionnaireItem>
      ))}
      <QuestionnaireActions>
        <QuestionnairePrevious />
        <QuestionnaireSkip />
        <QuestionnaireNext>Next</QuestionnaireNext>
        <QuestionnaireSubmit>Save plan</QuestionnaireSubmit>
      </QuestionnaireActions>
    </Questionnaire>
  );
}

export default QuestionnaireDemo;
```

## Installation

```bash
bunx --bun shadcn@latest add @sui/questionnaire
```

Install with the shadcn CLI or use the shared `@workspace/ui` package. Follow the [installation guide](/docs/installation) to configure the registry, load styles, and choose import aliases.

## Usage

```tsx
import {
  Questionnaire,
  QuestionnaireActions,
  QuestionnaireChoice,
  QuestionnaireChoices,
  QuestionnaireDescription,
  QuestionnaireError,
  QuestionnaireInput,
  QuestionnaireItem,
  QuestionnaireNext,
  QuestionnairePrevious,
  QuestionnaireProgress,
  QuestionnaireSkip,
  QuestionnaireSubmit,
  QuestionnaireTitle,
} from "@workspace/ui/components/questionnaire"
```

```tsx
const items = [
  {
    name: "direction",
    required: true,
    prompt: "What should we prototype next?",
    description: "Choose a direction or write your own.",
    choices: [
      {
        value: "delegation",
        label: "Delegation",
        description: "Show how work moves to a specialist.",
      },
      {
        value: "questions",
        label: "Question prompts",
        description: "Show choices while the interface waits.",
      },
      { value: "both", label: "Both together" },
    ],
    input: { label: "Another answer", placeholder: "Type another answer…" },
  },
  {
    name: "detail",
    required: false,
    prompt: "How much detail should it include?",
    description: "Skip this if you are not sure yet.",
    choices: [
      { value: "focused", label: "Focused" },
      { value: "complete", label: "Complete flow" },
    ],
  },
] as const
```

Define the collection once: pass it to `Questionnaire` for server-rendered
progress, actions, and shortcuts, then map it into the parts.

```tsx
<Questionnaire items={items} onSubmit={handleSubmit}>
  <QuestionnaireProgress />
  {items.map((question) => (
    <QuestionnaireItem
      key={question.name}
      name={question.name}
      required={question.required}
    >
      <QuestionnaireTitle>{question.prompt}</QuestionnaireTitle>
      <QuestionnaireDescription>
        {question.description}
      </QuestionnaireDescription>
      <QuestionnaireChoices>
        {question.choices.map((choice) => (
          <QuestionnaireChoice key={choice.value} value={choice.value}>
            <span className="font-medium">{choice.label}</span>
            {"description" in choice ? (
              <span className="text-muted-foreground">
                {choice.description}
              </span>
            ) : null}
          </QuestionnaireChoice>
        ))}
        {"input" in question ? (
          <QuestionnaireInput
            aria-label={question.input.label}
            placeholder={question.input.placeholder}
          />
        ) : null}
      </QuestionnaireChoices>
      <QuestionnaireError />
    </QuestionnaireItem>
  ))}
  <QuestionnaireActions>
    <QuestionnairePrevious />
    <QuestionnaireSkip />
    <QuestionnaireNext />
    <QuestionnaireSubmit />
  </QuestionnaireActions>
</Questionnaire>
```

```tsx
function handleSubmit(event: React.FormEvent<HTMLFormElement>) {
  event.preventDefault()
  const answers = new FormData(event.currentTarget)
  // answers.get("direction"), answers.getAll(...) for multiple items.
}
```

## Composition

```text
Questionnaire
├── QuestionnaireProgress
├── QuestionnaireItem
│   ├── QuestionnaireTitle
│   ├── QuestionnaireDescription
│   ├── QuestionnaireChoices
│   │   ├── QuestionnaireChoice
│   │   └── QuestionnaireInput
│   └── QuestionnaireError
└── QuestionnaireActions
    ├── QuestionnairePrevious
    ├── QuestionnaireSkip
    ├── QuestionnaireNext
    └── QuestionnaireSubmit
```

Questionnaire owns the ordered items, active item, answer state, validation,
progress, and navigation. The containing page, card, dialog, or drawer owns
close and cancellation behavior, persistence, transport, and branching.

## Server Rendering

Pass `items` to server-render the active item, progress, actions, and answer
shortcuts. See the
[headless Questionnaire](https://ui.shadcn.com/docs/react/questionnaire) for the complete behavior.

## Multiple Selection

Use `multiple` for an item that accepts more than one fixed answer.

### Example: questionnaire-multiple

```tsx
"use client";

import {
  Questionnaire,
  QuestionnaireActions,
  QuestionnaireChoice,
  QuestionnaireChoices,
  QuestionnaireDescription,
  QuestionnaireError,
  QuestionnaireItem,
  QuestionnaireSubmit,
  QuestionnaireTitle,
} from "@workspace/ui/components/questionnaire";
import { toast } from "@workspace/ui/components/toast";
import type * as React from "react";

const items = [
  {
    choices: [
      { value: "source" },
      { value: "tests" },
      { value: "docs" },
      { value: "history" },
    ],
    name: "context",
    required: true,
  },
] as const;

export function QuestionnaireMultiple() {
  function handleSubmit(event: React.FormEvent<HTMLFormElement>) {
    event.preventDefault();

    const context = new FormData(event.currentTarget).getAll("context");

    toast.add({
      title: "Context selected",
      ...{
        description: `Context: ${context.join(", ") || "None"}`,
      },
    });
  }

  return (
    <Questionnaire
      className="mx-auto max-w-md"
      items={items}
      shortcuts="letters"
      onSubmit={handleSubmit}
    >
      <QuestionnaireItem name="context" multiple required>
        <QuestionnaireTitle>
          What context should the agent inspect?
        </QuestionnaireTitle>
        <QuestionnaireDescription>
          Select every source that may affect the implementation.
        </QuestionnaireDescription>
        <QuestionnaireChoices>
          <QuestionnaireChoice value="source">
            Relevant source files
          </QuestionnaireChoice>
          <QuestionnaireChoice value="tests">
            Existing tests
          </QuestionnaireChoice>
          <QuestionnaireChoice value="docs">
            Architecture documentation
          </QuestionnaireChoice>
          <QuestionnaireChoice value="history">
            Recent commit history
          </QuestionnaireChoice>
        </QuestionnaireChoices>
        <QuestionnaireError />
      </QuestionnaireItem>

      <QuestionnaireActions>
        <QuestionnaireSubmit>Share context</QuestionnaireSubmit>
      </QuestionnaireActions>
    </Questionnaire>
  );
}

export default QuestionnaireMultiple;
```

## Freeform Answer

Compose `QuestionnaireInput` with fixed choices when the user can provide another answer.

### Example: questionnaire-freeform

```tsx
"use client";

import {
  Questionnaire,
  QuestionnaireActions,
  QuestionnaireChoice,
  QuestionnaireChoices,
  QuestionnaireDescription,
  QuestionnaireError,
  QuestionnaireInput,
  QuestionnaireItem,
  QuestionnaireSubmit,
  QuestionnaireTitle,
} from "@workspace/ui/components/questionnaire";
import { toast } from "@workspace/ui/components/toast";
import type * as React from "react";

const items = [
  {
    choices: [
      { value: "incremental" },
      { value: "module" },
      { value: "rewrite" },
    ],
    name: "approach",
    required: true,
  },
] as const;

export function QuestionnaireFreeform() {
  function handleSubmit(event: React.FormEvent<HTMLFormElement>) {
    event.preventDefault();

    const approach = new FormData(event.currentTarget).get("approach");

    toast.add({
      title: "Approach selected",
      ...{
        description: `Approach: ${approach ?? "None"}`,
      },
    });
  }

  return (
    <Questionnaire
      className="mx-auto max-w-md"
      items={items}
      shortcuts="letters"
      onSubmit={handleSubmit}
    >
      <QuestionnaireItem name="approach" required>
        <QuestionnaireTitle>
          How should the agent approach this refactor?
        </QuestionnaireTitle>
        <QuestionnaireDescription>
          Choose a strategy or write a more specific instruction.
        </QuestionnaireDescription>
        <QuestionnaireChoices>
          <QuestionnaireChoice value="incremental">
            Make the smallest safe change
          </QuestionnaireChoice>
          <QuestionnaireChoice value="module">
            Refactor one module at a time
          </QuestionnaireChoice>
          <QuestionnaireChoice value="rewrite">
            Replace the implementation completely
          </QuestionnaireChoice>
          <QuestionnaireInput
            aria-label="Another refactoring approach"
            placeholder="Describe another approach…"
          />
        </QuestionnaireChoices>
        <QuestionnaireError />
      </QuestionnaireItem>

      <QuestionnaireActions>
        <QuestionnaireSubmit>Use this approach</QuestionnaireSubmit>
      </QuestionnaireActions>
    </Questionnaire>
  );
}

export default QuestionnaireFreeform;
```

## Explicit Skip

Add `QuestionnaireSkip` when an optional item may be intentionally left unanswered.

### Example: questionnaire-skip

```tsx
"use client";

import type { QuestionnaireItemStatus } from "@shadcn/react/questionnaire";
import {
  Questionnaire,
  QuestionnaireActions,
  QuestionnaireChoice,
  QuestionnaireChoices,
  QuestionnaireDescription,
  QuestionnaireError,
  QuestionnaireInput,
  QuestionnaireItem,
  QuestionnaireNext,
  QuestionnairePrevious,
  QuestionnaireProgress,
  QuestionnaireSkip,
  QuestionnaireSubmit,
  QuestionnaireTitle,
} from "@workspace/ui/components/questionnaire";
import { toast } from "@workspace/ui/components/toast";
import * as React from "react";

const items = [
  { name: "task", required: true },
  { name: "constraints" },
  { name: "review", required: true },
] as const;

export function QuestionnaireSkipExample() {
  const [constraintStatus, setConstraintStatus] =
    React.useState<QuestionnaireItemStatus>("unanswered");

  function handleSubmit(event: React.FormEvent<HTMLFormElement>) {
    event.preventDefault();

    const formData = new FormData(event.currentTarget);
    const answers = {
      task: formData.get("task"),
      constraints: formData.get("constraints"),
      constraintStatus,
      review: formData.get("review"),
    };

    toast.add({
      title: "Agent brief submitted",
      ...{
        description: `Task: ${answers.task ?? "None"} · Constraints: ${
          answers.constraintStatus === "skipped"
            ? "Skipped"
            : (answers.constraints ?? "None")
        } · Review: ${answers.review ?? "None"}`,
      },
    });
  }

  return (
    <Questionnaire
      className="mx-auto max-w-md"
      defaultItem="task"
      items={items}
      onSubmit={handleSubmit}
    >
      <QuestionnaireProgress />

      <QuestionnaireItem name="task" required>
        <QuestionnaireTitle>What kind of change is this?</QuestionnaireTitle>
        <QuestionnaireDescription>
          Choose the category that best describes the work.
        </QuestionnaireDescription>
        <QuestionnaireChoices>
          <QuestionnaireChoice value="feature">New feature</QuestionnaireChoice>
          <QuestionnaireChoice value="fix">Bug fix</QuestionnaireChoice>
          <QuestionnaireChoice value="refactor">Refactor</QuestionnaireChoice>
        </QuestionnaireChoices>
        <QuestionnaireError />
      </QuestionnaireItem>

      <QuestionnaireItem
        name="constraints"
        onStatusChange={setConstraintStatus}
      >
        <QuestionnaireTitle>
          Are there any implementation constraints?
        </QuestionnaireTitle>
        <QuestionnaireDescription>
          Answer if needed, or intentionally skip this question.
        </QuestionnaireDescription>
        <QuestionnaireChoices>
          <QuestionnaireChoice value="no-dependencies">
            Do not add dependencies
          </QuestionnaireChoice>
          <QuestionnaireChoice value="no-migrations">
            Do not change the database
          </QuestionnaireChoice>
          <QuestionnaireChoice value="preserve-api">
            Preserve the public API
          </QuestionnaireChoice>
          <QuestionnaireInput
            aria-label="Another implementation constraint"
            placeholder="Describe another constraint…"
          />
        </QuestionnaireChoices>
      </QuestionnaireItem>

      <QuestionnaireItem name="review" required>
        <QuestionnaireTitle>
          How should the work be reviewed?
        </QuestionnaireTitle>
        <QuestionnaireDescription>
          Choose the checks the agent should complete before handoff.
        </QuestionnaireDescription>
        <QuestionnaireChoices>
          <QuestionnaireChoice value="tests">
            Run the test suite
          </QuestionnaireChoice>
          <QuestionnaireChoice value="diff">
            Review the final diff
          </QuestionnaireChoice>
          <QuestionnaireChoice value="both">
            Tests and diff review
          </QuestionnaireChoice>
        </QuestionnaireChoices>
        <QuestionnaireError />
      </QuestionnaireItem>

      <QuestionnaireActions>
        <QuestionnairePrevious />
        <QuestionnaireSkip />
        <QuestionnaireNext>Next</QuestionnaireNext>
        <QuestionnaireSubmit>Submit brief</QuestionnaireSubmit>
      </QuestionnaireActions>
    </Questionnaire>
  );
}

export default QuestionnaireSkipExample;
```

## Shortcuts

Assign a letter or number key to each answer with `shortcuts`.

### Example: questionnaire-shortcuts

```tsx
"use client";

import {
  NativeSelect,
  NativeSelectOption,
} from "@workspace/ui/components/native-select";
import {
  Questionnaire,
  QuestionnaireActions,
  QuestionnaireChoice,
  QuestionnaireChoices,
  QuestionnaireDescription,
  QuestionnaireError,
  QuestionnaireItem,
  QuestionnaireSubmit,
  QuestionnaireTitle,
} from "@workspace/ui/components/questionnaire";
import { toast } from "@workspace/ui/components/toast";
import * as React from "react";

const items = [
  {
    choices: [{ value: "inspect" }, { value: "tests" }, { value: "patch" }],
    name: "action",
    required: true,
  },
] as const;

type ShortcutMode = React.ComponentProps<typeof Questionnaire>["shortcuts"];

export function QuestionnaireShortcuts() {
  const [shortcuts, setShortcuts] = React.useState<ShortcutMode>("letters");

  function handleSubmit(event: React.FormEvent<HTMLFormElement>) {
    event.preventDefault();

    const action = new FormData(event.currentTarget).get("action");

    toast.add({
      title: "Next action selected",
      ...{
        description: `Action: ${action ?? "None"} · Shortcuts: ${shortcuts ?? "none"}`,
      },
    });
  }

  return (
    <div className="relative mx-auto flex h-full w-full max-w-md flex-col">
      <NativeSelect
        aria-label="Shortcut style"
        className="absolute end-0 top-0"
        value={shortcuts ?? "none"}
        onChange={(event) => {
          const value = event.target.value;
          setShortcuts(
            value === "letters" || value === "numbers" ? value : undefined,
          );
        }}
      >
        <NativeSelectOption value="none">No shortcuts</NativeSelectOption>
        <NativeSelectOption value="letters">Letters</NativeSelectOption>
        <NativeSelectOption value="numbers">Numbers</NativeSelectOption>
      </NativeSelect>

      <Questionnaire
        className="mt-auto"
        items={items}
        shortcuts={shortcuts}
        onSubmit={handleSubmit}
      >
        <QuestionnaireItem name="action" required>
          <QuestionnaireTitle>
            What should the agent do next?
          </QuestionnaireTitle>
          <QuestionnaireDescription>
            Use the displayed shortcut or navigate with the keyboard.
          </QuestionnaireDescription>
          <QuestionnaireChoices>
            <QuestionnaireChoice value="inspect">
              Inspect the implementation
            </QuestionnaireChoice>
            <QuestionnaireChoice value="tests">
              Run the relevant tests
            </QuestionnaireChoice>
            <QuestionnaireChoice value="patch">
              Prepare the patch
            </QuestionnaireChoice>
          </QuestionnaireChoices>
          <QuestionnaireError />
        </QuestionnaireItem>

        <QuestionnaireActions>
          <QuestionnaireSubmit>Confirm action</QuestionnaireSubmit>
        </QuestionnaireActions>
      </Questionnaire>
    </div>
  );
}

export default QuestionnaireShortcuts;
```

## Custom Validation

Combine controlled navigation with an external schema such as Zod to return to an invalid item and present its error.

### Example: questionnaire-validation

```tsx
"use client";

import {
  Card,
  CardAction,
  CardContent,
  CardFooter,
  CardHeader,
} from "@workspace/ui/components/card";
import {
  Questionnaire,
  QuestionnaireActions,
  QuestionnaireChoice,
  QuestionnaireChoices,
  QuestionnaireDescription,
  QuestionnaireError,
  QuestionnaireItem,
  QuestionnaireNext,
  QuestionnairePrevious,
  QuestionnaireProgress,
  QuestionnaireSubmit,
  QuestionnaireTitle,
} from "@workspace/ui/components/questionnaire";
import { toast } from "@workspace/ui/components/toast";
import * as React from "react";
import { z } from "zod";

const items = [
  { name: "detail", required: true },
  { name: "audience", required: true },
] as const;

const questionnaireSchema = z
  .object({
    detail: z.enum(["summary", "complete"]),
    audience: z.enum(["team", "public"]),
  })
  .superRefine((answers, context) => {
    if (answers.audience === "public" && answers.detail === "summary") {
      context.addIssue({
        code: z.ZodIssueCode.custom,
        message:
          "Public answers need enough context. Choose a complete answer.",
        path: ["detail"],
      });
    }
  });

type QuestionnaireItemName = keyof z.infer<typeof questionnaireSchema>;
type QuestionnaireErrors = Partial<Record<QuestionnaireItemName, string>>;

function ValidationProgress() {
  return (
    <QuestionnaireProgress
      className="min-w-0"
      render={(props, state) => (
        <div {...props}>
          {state.current} / {state.total}
        </div>
      )}
    />
  );
}

export function QuestionnaireValidation() {
  const [item, setItem] = React.useState("detail");
  const [errors, setErrors] = React.useState<QuestionnaireErrors>({});

  function clearError(name: QuestionnaireItemName) {
    setErrors((currentErrors) => {
      if (!currentErrors[name]) {
        return currentErrors;
      }

      const nextErrors = { ...currentErrors };
      delete nextErrors[name];
      return nextErrors;
    });
  }

  function handleSubmit(event: React.FormEvent<HTMLFormElement>) {
    event.preventDefault();

    const result = questionnaireSchema.safeParse(
      Object.fromEntries(new FormData(event.currentTarget)),
    );

    if (result.success) {
      setErrors({});
      toast.add({
        title: "Agent response configured",
        ...{
          description: `Detail: ${result.data.detail} · Audience: ${result.data.audience}`,
        },
      });
      return;
    }

    const nextErrors: QuestionnaireErrors = {};

    for (const issue of result.error.issues) {
      const name = issue.path[0];

      if ((name === "detail" || name === "audience") && !nextErrors[name]) {
        nextErrors[name] = issue.message;
      }
    }

    const firstInvalidItem = result.error.issues[0]?.path[0];

    setErrors(nextErrors);

    if (firstInvalidItem === "detail" || firstInvalidItem === "audience") {
      setItem(firstInvalidItem);
    }
  }

  return (
    <Questionnaire
      className="mx-auto max-w-md"
      item={item}
      items={items}
      onItemChange={setItem}
      onSubmit={handleSubmit}
    >
      <Card className="w-full">
        <QuestionnaireItem
          invalid={Boolean(errors.detail)}
          name="detail"
          required
        >
          <CardHeader>
            <QuestionnaireTitle>
              How much detail should the answer include?
            </QuestionnaireTitle>
            <QuestionnaireDescription>
              Choose the response depth.
            </QuestionnaireDescription>
            <CardAction>
              <ValidationProgress />
            </CardAction>
          </CardHeader>
          <CardContent>
            <QuestionnaireChoices>
              <QuestionnaireChoice
                value="summary"
                onChange={() => clearError("detail")}
              >
                Concise summary
              </QuestionnaireChoice>
              <QuestionnaireChoice
                value="complete"
                onChange={() => clearError("detail")}
              >
                Complete answer
              </QuestionnaireChoice>
            </QuestionnaireChoices>
            <QuestionnaireError>{errors.detail}</QuestionnaireError>
          </CardContent>
        </QuestionnaireItem>

        <QuestionnaireItem
          invalid={Boolean(errors.audience)}
          name="audience"
          required
        >
          <CardHeader>
            <QuestionnaireTitle>Who will read the answer?</QuestionnaireTitle>
            <QuestionnaireDescription>
              Public answers require complete context.
            </QuestionnaireDescription>
            <CardAction>
              <ValidationProgress />
            </CardAction>
          </CardHeader>
          <CardContent>
            <QuestionnaireChoices>
              <QuestionnaireChoice
                value="team"
                onChange={() => clearError("audience")}
              >
                My team
              </QuestionnaireChoice>
              <QuestionnaireChoice
                value="public"
                onChange={() => clearError("audience")}
              >
                Public audience
              </QuestionnaireChoice>
            </QuestionnaireChoices>
            <QuestionnaireError>{errors.audience}</QuestionnaireError>
          </CardContent>
        </QuestionnaireItem>

        <CardFooter>
          <QuestionnaireActions>
            <QuestionnairePrevious />
            <QuestionnaireNext>Next</QuestionnaireNext>
            <QuestionnaireSubmit>Validate answers</QuestionnaireSubmit>
          </QuestionnaireActions>
        </CardFooter>
      </Card>
    </Questionnaire>
  );
}

export default QuestionnaireValidation;
```

## Controlled

Control the active item from host state, such as returning to an invalid step.

### Example: questionnaire-controlled

```tsx
"use client";

import {
  Questionnaire,
  QuestionnaireActions,
  QuestionnaireChoice,
  QuestionnaireChoices,
  QuestionnaireDescription,
  QuestionnaireError,
  QuestionnaireItem,
  QuestionnaireNext,
  QuestionnairePrevious,
  QuestionnaireProgress,
  QuestionnaireSubmit,
  QuestionnaireTitle,
} from "@workspace/ui/components/questionnaire";
import { toast } from "@workspace/ui/components/toast";
import * as React from "react";

const items = [
  { name: "scope", required: true },
  { name: "checks", required: true },
  { name: "output", required: true },
] as const;

const itemLabels: Record<string, string> = {
  scope: "Change scope",
  checks: "Verification",
  output: "Final output",
};

export function QuestionnaireControlled() {
  const [item, setItem] = React.useState("scope");

  function handleSubmit(event: React.FormEvent<HTMLFormElement>) {
    event.preventDefault();

    const formData = new FormData(event.currentTarget);

    toast.add({
      title: "Agent workflow configured",
      ...{
        description: `Scope: ${formData.get("scope") ?? "None"} · Verification: ${formData.get("checks") ?? "None"} · Output: ${formData.get("output") ?? "None"}`,
      },
    });
  }

  return (
    <div className="relative mx-auto flex h-full w-full max-w-md flex-col">
      <p
        className="absolute end-0 top-0 text-muted-foreground text-sm"
        role="status"
      >
        Current checkpoint: {itemLabels[item]}
      </p>

      <Questionnaire
        className="mt-auto"
        item={item}
        items={items}
        onItemChange={setItem}
        onSubmit={handleSubmit}
      >
        <QuestionnaireProgress />

        <QuestionnaireItem name="scope" required>
          <QuestionnaireTitle>What may the agent change?</QuestionnaireTitle>
          <QuestionnaireDescription>
            The host stores the active checkpoint while Questionnaire navigates.
          </QuestionnaireDescription>
          <QuestionnaireChoices>
            <QuestionnaireChoice value="component">
              Only the target component
            </QuestionnaireChoice>
            <QuestionnaireChoice value="tests">
              Component and related tests
            </QuestionnaireChoice>
            <QuestionnaireChoice value="feature">
              The complete feature area
            </QuestionnaireChoice>
          </QuestionnaireChoices>
          <QuestionnaireError />
        </QuestionnaireItem>

        <QuestionnaireItem name="checks" required>
          <QuestionnaireTitle>
            Which verification level should it use?
          </QuestionnaireTitle>
          <QuestionnaireChoices>
            <QuestionnaireChoice value="targeted">
              Targeted tests
            </QuestionnaireChoice>
            <QuestionnaireChoice value="package">
              Package tests and typecheck
            </QuestionnaireChoice>
            <QuestionnaireChoice value="full">
              Full workspace verification
            </QuestionnaireChoice>
          </QuestionnaireChoices>
          <QuestionnaireError />
        </QuestionnaireItem>

        <QuestionnaireItem name="output" required>
          <QuestionnaireTitle>
            What should the agent return when finished?
          </QuestionnaireTitle>
          <QuestionnaireChoices>
            <QuestionnaireChoice value="summary">
              Concise summary
            </QuestionnaireChoice>
            <QuestionnaireChoice value="diff">
              Summary with changed files
            </QuestionnaireChoice>
            <QuestionnaireChoice value="handoff">
              Detailed implementation handoff
            </QuestionnaireChoice>
          </QuestionnaireChoices>
          <QuestionnaireError />
        </QuestionnaireItem>

        <QuestionnaireActions>
          <QuestionnairePrevious />
          <QuestionnaireNext>Next</QuestionnaireNext>
          <QuestionnaireSubmit>Save workflow</QuestionnaireSubmit>
        </QuestionnaireActions>
      </Questionnaire>
    </div>
  );
}

export default QuestionnaireControlled;
```

## Resume

Restore a saved active item and default answers, then reset changes back to that saved state.

### Example: questionnaire-resume

```tsx
"use client";

import { Button } from "@workspace/ui/components/button";
import {
  Questionnaire,
  QuestionnaireActions,
  QuestionnaireChoice,
  QuestionnaireChoices,
  QuestionnaireDescription,
  QuestionnaireError,
  QuestionnaireInput,
  QuestionnaireItem,
  QuestionnaireNext,
  QuestionnairePrevious,
  QuestionnaireProgress,
  QuestionnaireSubmit,
  QuestionnaireTitle,
} from "@workspace/ui/components/questionnaire";
import { toast } from "@workspace/ui/components/toast";
import type * as React from "react";

const items = [
  { name: "change", required: true },
  { name: "verification", required: true },
  { name: "notes" },
] as const;

export function QuestionnaireResume() {
  function handleSubmit(event: React.FormEvent<HTMLFormElement>) {
    event.preventDefault();

    const formData = new FormData(event.currentTarget);
    const answers = {
      change: formData.get("change"),
      verification: formData.getAll("verification"),
      notes: formData.get("notes"),
    };

    toast.add({
      title: "Draft updated",
      ...{
        description: `Migration: ${answers.change ?? "None"} · Verification: ${answers.verification.join(", ") || "None"} · Notes: ${answers.notes || "None"}`,
      },
    });
  }

  return (
    <Questionnaire
      className="mx-auto max-w-md"
      defaultItem="verification"
      items={items}
      onReset={() => toast.add({ title: "Saved answers restored" })}
      onSubmit={handleSubmit}
    >
      <QuestionnaireProgress />

      <QuestionnaireItem name="change" required>
        <QuestionnaireTitle>What kind of migration is this?</QuestionnaireTitle>
        <QuestionnaireDescription>
          This answer was saved during the previous session.
        </QuestionnaireDescription>
        <QuestionnaireChoices>
          <QuestionnaireChoice value="incremental" defaultChecked>
            Incremental migration
          </QuestionnaireChoice>
          <QuestionnaireChoice value="cutover">
            Single cutover
          </QuestionnaireChoice>
        </QuestionnaireChoices>
        <QuestionnaireError />
      </QuestionnaireItem>

      <QuestionnaireItem name="verification" multiple required>
        <QuestionnaireTitle>
          How should the migration be verified?
        </QuestionnaireTitle>
        <QuestionnaireDescription>
          These checks were selected during the previous session.
        </QuestionnaireDescription>
        <QuestionnaireChoices>
          <QuestionnaireChoice value="tests" defaultChecked>
            Run migration tests
          </QuestionnaireChoice>
          <QuestionnaireChoice value="typecheck" defaultChecked>
            Run the typecheck
          </QuestionnaireChoice>
          <QuestionnaireChoice value="manual">
            Perform a manual smoke test
          </QuestionnaireChoice>
        </QuestionnaireChoices>
        <QuestionnaireError />
      </QuestionnaireItem>

      <QuestionnaireItem name="notes">
        <QuestionnaireTitle>
          Anything else the agent should remember?
        </QuestionnaireTitle>
        <QuestionnaireDescription>
          This note was saved with the draft.
        </QuestionnaireDescription>
        <QuestionnaireInput
          aria-label="Saved migration note"
          defaultValue="Keep the existing public API stable."
        />
      </QuestionnaireItem>

      <QuestionnaireActions>
        <Button type="reset" variant="outline">
          Reset changes
        </Button>
        <QuestionnairePrevious />
        <QuestionnaireNext>Next</QuestionnaireNext>
        <QuestionnaireSubmit>Update draft</QuestionnaireSubmit>
      </QuestionnaireActions>
    </Questionnaire>
  );
}

export default QuestionnaireResume;
```

## Conditional Items

Disable items that do not apply to the user's earlier answers.

### Example: questionnaire-conditional

```tsx
"use client";

import {
  Questionnaire,
  QuestionnaireActions,
  QuestionnaireChoice,
  QuestionnaireChoices,
  QuestionnaireDescription,
  QuestionnaireError,
  QuestionnaireItem,
  QuestionnaireNext,
  QuestionnairePrevious,
  QuestionnaireProgress,
  QuestionnaireSubmit,
  QuestionnaireTitle,
} from "@workspace/ui/components/questionnaire";
import { toast } from "@workspace/ui/components/toast";
import * as React from "react";

export function QuestionnaireConditional() {
  const [runtime, setRuntime] = React.useState("local");
  const items = React.useMemo(
    () => [
      { name: "runtime", required: true },
      {
        disabled: runtime !== "cloud",
        name: "environment",
        required: true,
      },
      { name: "approval", required: true },
    ],
    [runtime],
  );

  function handleSubmit(event: React.FormEvent<HTMLFormElement>) {
    event.preventDefault();

    const formData = new FormData(event.currentTarget);

    toast.add({
      title: "Execution plan saved",
      ...{
        description: `Runtime: ${formData.get("runtime") ?? "None"} · Environment: ${formData.get("environment") ?? "Not applicable"} · Approval: ${formData.get("approval") ?? "None"}`,
      },
    });
  }

  return (
    <Questionnaire
      className="mx-auto max-w-md"
      defaultItem="runtime"
      items={items}
      onSubmit={handleSubmit}
    >
      <QuestionnaireProgress />

      <QuestionnaireItem name="runtime" required>
        <QuestionnaireTitle>Where should the agent run?</QuestionnaireTitle>
        <QuestionnaireDescription>
          Cloud runs add an environment question to this flow.
        </QuestionnaireDescription>
        <QuestionnaireChoices>
          <QuestionnaireChoice
            checked={runtime === "local"}
            value="local"
            onChange={() => setRuntime("local")}
          >
            Local workspace
          </QuestionnaireChoice>
          <QuestionnaireChoice
            checked={runtime === "cloud"}
            value="cloud"
            onChange={() => setRuntime("cloud")}
          >
            Cloud workspace
          </QuestionnaireChoice>
        </QuestionnaireChoices>
        <QuestionnaireError />
      </QuestionnaireItem>

      <QuestionnaireItem
        disabled={runtime !== "cloud"}
        name="environment"
        required
      >
        <QuestionnaireTitle>
          Which cloud environment should it use?
        </QuestionnaireTitle>
        <QuestionnaireChoices>
          <QuestionnaireChoice value="preview">Preview</QuestionnaireChoice>
          <QuestionnaireChoice value="staging">Staging</QuestionnaireChoice>
          <QuestionnaireChoice value="isolated">
            Isolated sandbox
          </QuestionnaireChoice>
        </QuestionnaireChoices>
        <QuestionnaireError />
      </QuestionnaireItem>

      <QuestionnaireItem name="approval" required>
        <QuestionnaireTitle>
          When should the agent request approval?
        </QuestionnaireTitle>
        <QuestionnaireChoices>
          <QuestionnaireChoice value="writes">
            Before writing files
          </QuestionnaireChoice>
          <QuestionnaireChoice value="commands">
            Before running commands
          </QuestionnaireChoice>
          <QuestionnaireChoice value="sensitive">
            Only for sensitive actions
          </QuestionnaireChoice>
        </QuestionnaireChoices>
        <QuestionnaireError />
      </QuestionnaireItem>

      <QuestionnaireActions>
        <QuestionnairePrevious />
        <QuestionnaireNext>Next</QuestionnaireNext>
        <QuestionnaireSubmit>Save execution plan</QuestionnaireSubmit>
      </QuestionnaireActions>
    </Questionnaire>
  );
}

export default QuestionnaireConditional;
```

## Navigation State

Read item status to opt into disabled navigation and custom action styling.

### Example: questionnaire-navigation-state

```tsx
"use client";

import type { QuestionnaireItemStatus } from "@shadcn/react/questionnaire";
import {
  Questionnaire,
  QuestionnaireActions,
  QuestionnaireChoice,
  QuestionnaireChoices,
  QuestionnaireDescription,
  QuestionnaireError,
  QuestionnaireItem,
  QuestionnaireNext,
  QuestionnairePrevious,
  QuestionnaireProgress,
  QuestionnaireSubmit,
  QuestionnaireTitle,
} from "@workspace/ui/components/questionnaire";
import { toast } from "@workspace/ui/components/toast";
import * as React from "react";

const items = [
  { name: "permission", required: true },
  { name: "verification", required: true },
] as const;

type ItemName = "permission" | "verification";

export function QuestionnaireNavigationState() {
  const [item, setItem] = React.useState<ItemName>("permission");
  const [statuses, setStatuses] = React.useState<
    Record<ItemName, QuestionnaireItemStatus>
  >({
    permission: "unanswered",
    verification: "unanswered",
  });
  const unanswered = statuses[item] === "unanswered";

  function setStatus(name: ItemName, status: QuestionnaireItemStatus) {
    setStatuses((current) => ({ ...current, [name]: status }));
  }

  function handleSubmit(event: React.FormEvent<HTMLFormElement>) {
    event.preventDefault();

    const formData = new FormData(event.currentTarget);

    toast.add({
      title: "Permissions saved",
      ...{
        description: `Permission: ${formData.get("permission") ?? "None"} · Verification: ${formData.get("verification") ?? "None"}`,
      },
    });
  }

  return (
    <Questionnaire
      className="mx-auto max-w-md"
      item={item}
      items={items}
      onItemChange={(nextItem) => setItem(nextItem as ItemName)}
      onSubmit={handleSubmit}
    >
      <QuestionnaireProgress />

      <QuestionnaireItem
        name="permission"
        required
        onStatusChange={(status) => setStatus("permission", status)}
      >
        <QuestionnaireTitle>What may the agent modify?</QuestionnaireTitle>
        <QuestionnaireDescription>
          Next is intentionally disabled until an answer is selected.
        </QuestionnaireDescription>
        <QuestionnaireChoices>
          <QuestionnaireChoice value="files">Project files</QuestionnaireChoice>
          <QuestionnaireChoice value="tests">
            Project files and tests
          </QuestionnaireChoice>
          <QuestionnaireChoice value="config">
            Files, tests, and configuration
          </QuestionnaireChoice>
        </QuestionnaireChoices>
        <QuestionnaireError />
      </QuestionnaireItem>

      <QuestionnaireItem
        name="verification"
        required
        onStatusChange={(status) => setStatus("verification", status)}
      >
        <QuestionnaireTitle>
          What must pass before completion?
        </QuestionnaireTitle>
        <QuestionnaireChoices>
          <QuestionnaireChoice value="tests">Tests</QuestionnaireChoice>
          <QuestionnaireChoice value="types">
            Tests and types
          </QuestionnaireChoice>
          <QuestionnaireChoice value="all">
            Tests, types, and visual QA
          </QuestionnaireChoice>
        </QuestionnaireChoices>
        <QuestionnaireError />
      </QuestionnaireItem>

      <QuestionnaireActions>
        <QuestionnairePrevious />
        <QuestionnaireNext
          className="data-[status=unanswered]:opacity-50"
          disabled={unanswered}
          variant="secondary"
        >
          Next
        </QuestionnaireNext>
        <QuestionnaireSubmit disabled={unanswered}>
          Save permissions
        </QuestionnaireSubmit>
      </QuestionnaireActions>
    </Questionnaire>
  );
}

export default QuestionnaireNavigationState;
```

## Custom Progress

Use the Progress render state to build a custom progress indicator.

### Example: questionnaire-progress

```tsx
// biome-ignore-all lint/suspicious/noArrayIndexKey: The upstream gallery uses fixed positional fixtures that never reorder.

"use client";

import {
  Questionnaire,
  QuestionnaireActions,
  QuestionnaireChoice,
  QuestionnaireChoices,
  QuestionnaireError,
  QuestionnaireItem,
  QuestionnaireNext,
  QuestionnairePrevious,
  QuestionnaireProgress,
  QuestionnaireSubmit,
  QuestionnaireTitle,
} from "@workspace/ui/components/questionnaire";
import { toast } from "@workspace/ui/components/toast";
import type * as React from "react";

const items = [
  { name: "scope", required: true },
  { name: "strategy", required: true },
  { name: "tests", required: true },
  { name: "delivery", required: true },
] as const;

export function QuestionnaireProgressExample() {
  function handleSubmit(event: React.FormEvent<HTMLFormElement>) {
    event.preventDefault();

    const formData = new FormData(event.currentTarget);

    toast.add({
      title: "Pull request plan ready",
      ...{
        description: `Scope: ${formData.get("scope") ?? "None"} · Commits: ${formData.get("strategy") ?? "None"} · Tests: ${formData.get("tests") ?? "None"} · Delivery: ${formData.get("delivery") ?? "None"}`,
      },
    });
  }

  return (
    <Questionnaire
      className="mx-auto max-w-md"
      defaultItem="scope"
      items={items}
      onSubmit={handleSubmit}
    >
      <QuestionnaireProgress
        className="w-full"
        render={(props, state) => (
          <div {...props}>
            <div className="mb-2 flex gap-1.5" aria-hidden="true">
              {Array.from({ length: state.total }, (_, index) => (
                <span
                  key={index}
                  className={
                    index < state.current
                      ? "h-1.5 flex-1 rounded-full bg-primary"
                      : "h-1.5 flex-1 rounded-full bg-muted"
                  }
                />
              ))}
            </div>
            <span>
              Checkpoint {state.current} of {state.total}
            </span>
          </div>
        )}
      />

      <QuestionnaireItem name="scope" required>
        <QuestionnaireTitle>How large is the change?</QuestionnaireTitle>
        <QuestionnaireChoices>
          <QuestionnaireChoice value="small">Small patch</QuestionnaireChoice>
          <QuestionnaireChoice value="medium">
            Feature-sized change
          </QuestionnaireChoice>
          <QuestionnaireChoice value="large">
            Cross-package change
          </QuestionnaireChoice>
        </QuestionnaireChoices>
        <QuestionnaireError />
      </QuestionnaireItem>

      <QuestionnaireItem name="strategy" required>
        <QuestionnaireTitle>
          How should commits be organized?
        </QuestionnaireTitle>
        <QuestionnaireChoices>
          <QuestionnaireChoice value="single">
            Single commit
          </QuestionnaireChoice>
          <QuestionnaireChoice value="logical">
            Logical commits
          </QuestionnaireChoice>
          <QuestionnaireChoice value="squash">
            Squash before review
          </QuestionnaireChoice>
        </QuestionnaireChoices>
        <QuestionnaireError />
      </QuestionnaireItem>

      <QuestionnaireItem name="tests" required>
        <QuestionnaireTitle>Which tests should run?</QuestionnaireTitle>
        <QuestionnaireChoices>
          <QuestionnaireChoice value="targeted">
            Targeted tests
          </QuestionnaireChoice>
          <QuestionnaireChoice value="package">
            Package suite
          </QuestionnaireChoice>
          <QuestionnaireChoice value="workspace">
            Full workspace
          </QuestionnaireChoice>
        </QuestionnaireChoices>
        <QuestionnaireError />
      </QuestionnaireItem>

      <QuestionnaireItem name="delivery" required>
        <QuestionnaireTitle>
          How should the work be delivered?
        </QuestionnaireTitle>
        <QuestionnaireChoices>
          <QuestionnaireChoice value="patch">Patch only</QuestionnaireChoice>
          <QuestionnaireChoice value="commit">
            Committed locally
          </QuestionnaireChoice>
          <QuestionnaireChoice value="branch">
            Push a review branch
          </QuestionnaireChoice>
        </QuestionnaireChoices>
        <QuestionnaireError />
      </QuestionnaireItem>

      <QuestionnaireActions>
        <QuestionnairePrevious />
        <QuestionnaireNext>Next</QuestionnaireNext>
        <QuestionnaireSubmit>Finish plan</QuestionnaireSubmit>
      </QuestionnaireActions>
    </Questionnaire>
  );
}

export default QuestionnaireProgressExample;
```

## Animated Items

Animate the active item while keeping progress and navigation stationary.

### Example: questionnaire-animated

```tsx
"use client";

import {
  Questionnaire,
  QuestionnaireActions,
  QuestionnaireChoice,
  QuestionnaireChoices,
  QuestionnaireDescription,
  QuestionnaireError,
  QuestionnaireItem,
  QuestionnaireNext,
  QuestionnairePrevious,
  QuestionnaireProgress,
  QuestionnaireSubmit,
  QuestionnaireTitle,
} from "@workspace/ui/components/questionnaire";
import { toast } from "@workspace/ui/components/toast";
import type * as React from "react";

const items = [
  { name: "task", required: true },
  { name: "review", required: true },
  { name: "delivery", required: true },
] as const;

const itemClassName =
  "data-active:animate-in data-active:fade-in-0 data-active:slide-in-from-bottom-2 data-active:duration-300 motion-reduce:animate-none";

export function QuestionnaireAnimated() {
  function handleSubmit(event: React.FormEvent<HTMLFormElement>) {
    event.preventDefault();

    const formData = new FormData(event.currentTarget);

    toast.add({
      title: "Agent workflow saved",
      ...{
        description: `Task: ${formData.get("task") ?? "None"} · Review: ${formData.get("review") ?? "None"} · Delivery: ${formData.get("delivery") ?? "None"}`,
      },
    });
  }

  return (
    <Questionnaire
      className="mx-auto max-w-md"
      defaultItem="task"
      items={items}
      onSubmit={handleSubmit}
    >
      <QuestionnaireProgress />

      <QuestionnaireItem className={itemClassName} name="task" required>
        <QuestionnaireTitle>What should the agent do?</QuestionnaireTitle>
        <QuestionnaireDescription>
          Choose the task for this run.
        </QuestionnaireDescription>
        <QuestionnaireChoices>
          <QuestionnaireChoice value="implement">
            Implement the requested change
          </QuestionnaireChoice>
          <QuestionnaireChoice value="debug">
            Debug the current behavior
          </QuestionnaireChoice>
          <QuestionnaireChoice value="review">
            Review the implementation
          </QuestionnaireChoice>
        </QuestionnaireChoices>
        <QuestionnaireError />
      </QuestionnaireItem>

      <QuestionnaireItem className={itemClassName} name="review" required>
        <QuestionnaireTitle>
          How should the work be reviewed?
        </QuestionnaireTitle>
        <QuestionnaireDescription>
          Select the verification depth.
        </QuestionnaireDescription>
        <QuestionnaireChoices>
          <QuestionnaireChoice value="targeted">
            Targeted checks
          </QuestionnaireChoice>
          <QuestionnaireChoice value="complete">
            Complete test suite
          </QuestionnaireChoice>
          <QuestionnaireChoice value="manual">
            Tests and manual QA
          </QuestionnaireChoice>
        </QuestionnaireChoices>
        <QuestionnaireError />
      </QuestionnaireItem>

      <QuestionnaireItem className={itemClassName} name="delivery" required>
        <QuestionnaireTitle>
          How should the result be delivered?
        </QuestionnaireTitle>
        <QuestionnaireDescription>
          Choose the final handoff format.
        </QuestionnaireDescription>
        <QuestionnaireChoices>
          <QuestionnaireChoice value="summary">
            Concise summary
          </QuestionnaireChoice>
          <QuestionnaireChoice value="diff">
            Summary and changed files
          </QuestionnaireChoice>
          <QuestionnaireChoice value="handoff">
            Detailed review handoff
          </QuestionnaireChoice>
        </QuestionnaireChoices>
        <QuestionnaireError />
      </QuestionnaireItem>

      <QuestionnaireActions>
        <QuestionnairePrevious />
        <QuestionnaireNext>Next</QuestionnaireNext>
        <QuestionnaireSubmit>Save workflow</QuestionnaireSubmit>
      </QuestionnaireActions>
    </Questionnaire>
  );
}

export default QuestionnaireAnimated;
```

## Card

Compose Questionnaire with Card slots while keeping the question title and description semantic.

### Example: questionnaire-card

```tsx
"use client";

import {
  Card,
  CardAction,
  CardContent,
  CardDescription,
  CardFooter,
  CardHeader,
  CardTitle,
} from "@workspace/ui/components/card";
import {
  Questionnaire,
  QuestionnaireActions,
  QuestionnaireChoice,
  QuestionnaireChoices,
  QuestionnaireDescription,
  QuestionnaireError,
  QuestionnaireItem,
  QuestionnaireNext,
  QuestionnairePrevious,
  QuestionnaireProgress,
  QuestionnaireSubmit,
  QuestionnaireTitle,
} from "@workspace/ui/components/questionnaire";
import { toast } from "@workspace/ui/components/toast";
import * as React from "react";

const items = [
  {
    choices: [{ value: "fix" }, { value: "refactor" }, { value: "docs" }],
    name: "task",
    required: true,
  },
  {
    choices: [{ value: "summary" }, { value: "files" }, { value: "review" }],
    name: "output",
    required: true,
  },
] as const;

export function QuestionnaireCard() {
  const taskTitleId = React.useId();
  const outputTitleId = React.useId();

  function handleSubmit(event: React.FormEvent<HTMLFormElement>) {
    event.preventDefault();

    const formData = new FormData(event.currentTarget);

    toast.add({
      title: "Agent task created",
      ...{
        description: `Task: ${formData.get("task") ?? "None"} · Handoff: ${formData.get("output") ?? "None"}`,
      },
    });
  }

  return (
    <Questionnaire
      className="mx-auto max-w-md"
      defaultItem="task"
      items={items}
      shortcuts="numbers"
      onSubmit={handleSubmit}
    >
      <Card>
        <QuestionnaireItem aria-labelledby={taskTitleId} name="task" required>
          <CardHeader>
            <QuestionnaireTitle id={taskTitleId} render={<CardTitle />}>
              What should the agent work on?
            </QuestionnaireTitle>
            <QuestionnaireDescription render={<CardDescription />}>
              Choose the task that should be handled next.
            </QuestionnaireDescription>
            <CardAction>
              <QuestionnaireProgress />
            </CardAction>
          </CardHeader>
          <CardContent>
            <QuestionnaireChoices>
              <QuestionnaireChoice value="fix">
                Fix the failing tests
              </QuestionnaireChoice>
              <QuestionnaireChoice value="refactor">
                Refactor the data layer
              </QuestionnaireChoice>
              <QuestionnaireChoice value="docs">
                Update the integration guide
              </QuestionnaireChoice>
            </QuestionnaireChoices>
            <QuestionnaireError />
          </CardContent>
        </QuestionnaireItem>

        <QuestionnaireItem
          aria-labelledby={outputTitleId}
          name="output"
          required
        >
          <CardHeader>
            <QuestionnaireTitle id={outputTitleId} render={<CardTitle />}>
              What should the final handoff include?
            </QuestionnaireTitle>
            <QuestionnaireDescription render={<CardDescription />}>
              Pick the level of detail needed for review.
            </QuestionnaireDescription>
            <CardAction>
              <QuestionnaireProgress />
            </CardAction>
          </CardHeader>
          <CardContent>
            <QuestionnaireChoices>
              <QuestionnaireChoice value="summary">
                Summary only
              </QuestionnaireChoice>
              <QuestionnaireChoice value="files">
                Summary and changed files
              </QuestionnaireChoice>
              <QuestionnaireChoice value="review">
                Full review handoff
              </QuestionnaireChoice>
            </QuestionnaireChoices>
            <QuestionnaireError />
          </CardContent>
        </QuestionnaireItem>

        <CardFooter>
          <QuestionnaireActions className="w-full">
            <QuestionnairePrevious />
            <QuestionnaireNext>Next</QuestionnaireNext>
            <QuestionnaireSubmit>Create task</QuestionnaireSubmit>
          </QuestionnaireActions>
        </CardFooter>
      </Card>
    </Questionnaire>
  );
}

export default QuestionnaireCard;
```

## Dialog

Compose Questionnaire inside a Dialog while keeping cancellation and dismissal host-owned.

### Example: questionnaire-dialog

```tsx
"use client";

import { Button } from "@workspace/ui/components/button";
import {
  Dialog,
  DialogClose,
  DialogContent,
  DialogDescription,
  DialogFooter,
  DialogHeader,
  DialogTitle,
  DialogTrigger,
} from "@workspace/ui/components/dialog";
import {
  Questionnaire,
  QuestionnaireActions,
  QuestionnaireChoice,
  QuestionnaireChoices,
  QuestionnaireDescription,
  QuestionnaireError,
  QuestionnaireItem,
  QuestionnaireNext,
  QuestionnairePrevious,
  QuestionnaireProgress,
  QuestionnaireSubmit,
  QuestionnaireTitle,
} from "@workspace/ui/components/questionnaire";
import { toast } from "@workspace/ui/components/toast";
import * as React from "react";

const items = [
  { name: "scope", required: true },
  { name: "tests", required: true },
] as const;

export function QuestionnaireDialog() {
  const [open, setOpen] = React.useState(false);

  function handleSubmit(event: React.FormEvent<HTMLFormElement>) {
    event.preventDefault();

    const formData = new FormData(event.currentTarget);

    setOpen(false);
    toast.add({
      title: "Clarification sent",
      ...{
        description: `Scope: ${formData.get("scope") ?? "None"} · Verification: ${formData.get("tests") ?? "None"}`,
      },
    });
  }

  return (
    <Dialog open={open} onOpenChange={setOpen}>
      <DialogTrigger render={<Button variant="outline" />}>
        Open clarification
      </DialogTrigger>
      <DialogContent>
        <Questionnaire
          defaultItem="scope"
          items={items}
          onSubmit={handleSubmit}
        >
          <QuestionnaireItem name="scope" required>
            <DialogHeader>
              <QuestionnaireProgress />
              <QuestionnaireTitle render={<DialogTitle />}>
                Which files are in scope?
              </QuestionnaireTitle>
              <QuestionnaireDescription render={<DialogDescription />}>
                Choose how broadly the agent can update the workspace.
              </QuestionnaireDescription>
            </DialogHeader>
            <QuestionnaireChoices>
              <QuestionnaireChoice value="component">
                Component only
              </QuestionnaireChoice>
              <QuestionnaireChoice value="feature">
                Complete feature directory
              </QuestionnaireChoice>
              <QuestionnaireChoice value="workspace">
                Any related workspace file
              </QuestionnaireChoice>
            </QuestionnaireChoices>
            <QuestionnaireError />
          </QuestionnaireItem>

          <QuestionnaireItem name="tests" required>
            <DialogHeader>
              <QuestionnaireProgress />
              <QuestionnaireTitle render={<DialogTitle />}>
                How much verification is needed?
              </QuestionnaireTitle>
              <QuestionnaireDescription render={<DialogDescription />}>
                Choose the checks the agent should run before handoff.
              </QuestionnaireDescription>
            </DialogHeader>
            <QuestionnaireChoices>
              <QuestionnaireChoice value="targeted">
                Targeted tests
              </QuestionnaireChoice>
              <QuestionnaireChoice value="package">
                Package tests
              </QuestionnaireChoice>
              <QuestionnaireChoice value="full">
                Full workspace verification
              </QuestionnaireChoice>
            </QuestionnaireChoices>
            <QuestionnaireError />
          </QuestionnaireItem>

          <DialogFooter>
            <DialogClose render={<Button type="button" variant="outline" />}>
              Cancel
            </DialogClose>
            <QuestionnaireActions>
              <QuestionnairePrevious />
              <QuestionnaireNext>Next</QuestionnaireNext>
              <QuestionnaireSubmit>Send answer</QuestionnaireSubmit>
            </QuestionnaireActions>
          </DialogFooter>
        </Questionnaire>
      </DialogContent>
    </Dialog>
  );
}

export default QuestionnaireDialog;
```

## Accessibility

`QuestionnaireItem` renders a `fieldset`, and `QuestionnaireTitle` renders its
`legend`. Descriptions and active errors are associated with the current item,
and invalid items and answer controls expose `aria-invalid`.

Fixed choices preserve native radio and checkbox behavior. Progress is exposed
as a named progressbar, navigation uses real buttons, and inactive items and
actions are hidden and inert. Successful navigation focuses the newly active
item; failed validation focuses an available answer control.

Always give `QuestionnaireInput` an accessible name with a visible label,
`aria-label`, or `aria-labelledby`. A placeholder is not a label. See the
[Questionnaire accessibility guide](https://ui.shadcn.com/docs/react/questionnaire#accessibility)
for labeling custom compositions and the complete keyboard behavior.

## Unstyled

The behavior in `Questionnaire` comes from the `@shadcn/react` package. To use
it directly with your own markup and styles, see
[Questionnaire](https://ui.shadcn.com/docs/react/questionnaire) under @shadcn/react.

## API Reference

The props, data attributes, and render states for every part are documented on
the [@shadcn/react Questionnaire](https://ui.shadcn.com/docs/react/questionnaire#api-reference) page.
The styled components inherit the corresponding unstyled props. Navigation
components also accept Button `size` and `variant` props, and
`QuestionnaireActions` is a styled-only layout helper.


---

# Radio Group

A set of checkable buttons—known as radio buttons—where no more than one of the buttons can be checked at a time.

Page: https://sui.draco.dev/docs/components/radio-group

### Example: radio-group-demo

```tsx
import { Label } from "@workspace/ui/components/label";
import {
  RadioGroup,
  RadioGroupItem,
} from "@workspace/ui/components/radio-group";
import { useId as usePreviewId } from "react";

export function RadioGroupDemo() {
  const previewId = usePreviewId();

  return (
    <RadioGroup defaultValue="comfortable" className="w-fit">
      <div className="flex items-center gap-3">
        <RadioGroupItem value="default" id={`${previewId}-r1`} />
        <Label htmlFor={`${previewId}-r1`}>Default</Label>
      </div>
      <div className="flex items-center gap-3">
        <RadioGroupItem value="comfortable" id={`${previewId}-r2`} />
        <Label htmlFor={`${previewId}-r2`}>Comfortable</Label>
      </div>
      <div className="flex items-center gap-3">
        <RadioGroupItem value="compact" id={`${previewId}-r3`} />
        <Label htmlFor={`${previewId}-r3`}>Compact</Label>
      </div>
    </RadioGroup>
  );
}

export default RadioGroupDemo;
```

## Installation

```bash
bunx --bun shadcn@latest add @sui/radio-group
```

Install with the shadcn CLI or use the shared `@workspace/ui` package. Follow the [installation guide](/docs/installation) to configure the registry, load styles, and choose import aliases.

## Usage

```tsx showLineNumbers
import { Label } from "@workspace/ui/components/label"
import { RadioGroup, RadioGroupItem } from "@workspace/ui/components/radio-group"
```

```tsx showLineNumbers
<RadioGroup defaultValue="option-one">
  <div className="flex items-center gap-3">
    <RadioGroupItem value="option-one" id="option-one" />
    <Label htmlFor="option-one">Option One</Label>
  </div>
  <div className="flex items-center gap-3">
    <RadioGroupItem value="option-two" id="option-two" />
    <Label htmlFor="option-two">Option Two</Label>
  </div>
</RadioGroup>
```

## Composition

Use the following composition to build a `RadioGroup`:

```text
RadioGroup
├── RadioGroupItem
└── RadioGroupItem
```

## Description

Radio group items with a description using the `Field` component.

### Example: radio-group-description

```tsx
import {
  Field,
  FieldContent,
  FieldDescription,
  FieldLabel,
} from "@workspace/ui/components/field";
import {
  RadioGroup,
  RadioGroupItem,
} from "@workspace/ui/components/radio-group";
import { useId as usePreviewId } from "react";

export function RadioGroupDescription() {
  const previewId = usePreviewId();

  return (
    <RadioGroup defaultValue="comfortable" className="w-fit">
      <Field orientation="horizontal">
        <RadioGroupItem value="default" id={`${previewId}-desc-r1`} />
        <FieldContent>
          <FieldLabel htmlFor={`${previewId}-desc-r1`}>Default</FieldLabel>
          <FieldDescription>
            Standard spacing for most use cases.
          </FieldDescription>
        </FieldContent>
      </Field>
      <Field orientation="horizontal">
        <RadioGroupItem value="comfortable" id={`${previewId}-desc-r2`} />
        <FieldContent>
          <FieldLabel htmlFor={`${previewId}-desc-r2`}>Comfortable</FieldLabel>
          <FieldDescription>More space between elements.</FieldDescription>
        </FieldContent>
      </Field>
      <Field orientation="horizontal">
        <RadioGroupItem value="compact" id={`${previewId}-desc-r3`} />
        <FieldContent>
          <FieldLabel htmlFor={`${previewId}-desc-r3`}>Compact</FieldLabel>
          <FieldDescription>
            Minimal spacing for dense layouts.
          </FieldDescription>
        </FieldContent>
      </Field>
    </RadioGroup>
  );
}

export default RadioGroupDescription;
```

## Choice Card

Use `FieldLabel` to wrap the entire `Field` for a clickable card-style selection.

### Example: radio-group-choice-card

```tsx
import {
  Field,
  FieldContent,
  FieldDescription,
  FieldLabel,
  FieldTitle,
} from "@workspace/ui/components/field";
import {
  RadioGroup,
  RadioGroupItem,
} from "@workspace/ui/components/radio-group";
import { useId as usePreviewId } from "react";

export function RadioGroupChoiceCard() {
  const previewId = usePreviewId();

  return (
    <RadioGroup defaultValue="plus" className="max-w-sm">
      <FieldLabel htmlFor={`${previewId}-plus-plan`}>
        <Field orientation="horizontal">
          <FieldContent>
            <FieldTitle>Plus</FieldTitle>
            <FieldDescription>
              For individuals and small teams.
            </FieldDescription>
          </FieldContent>
          <RadioGroupItem value="plus" id={`${previewId}-plus-plan`} />
        </Field>
      </FieldLabel>
      <FieldLabel htmlFor={`${previewId}-pro-plan`}>
        <Field orientation="horizontal">
          <FieldContent>
            <FieldTitle>Pro</FieldTitle>
            <FieldDescription>For growing businesses.</FieldDescription>
          </FieldContent>
          <RadioGroupItem value="pro" id={`${previewId}-pro-plan`} />
        </Field>
      </FieldLabel>
      <FieldLabel htmlFor={`${previewId}-enterprise-plan`}>
        <Field orientation="horizontal">
          <FieldContent>
            <FieldTitle>Enterprise</FieldTitle>
            <FieldDescription>
              For large teams and enterprises.
            </FieldDescription>
          </FieldContent>
          <RadioGroupItem
            value="enterprise"
            id={`${previewId}-enterprise-plan`}
          />
        </Field>
      </FieldLabel>
    </RadioGroup>
  );
}

export default RadioGroupChoiceCard;
```

## Fieldset

Use `FieldSet` and `FieldLegend` to group radio items with a label and description.

### Example: radio-group-fieldset

```tsx
import {
  Field,
  FieldDescription,
  FieldLabel,
  FieldLegend,
  FieldSet,
} from "@workspace/ui/components/field";
import {
  RadioGroup,
  RadioGroupItem,
} from "@workspace/ui/components/radio-group";
import { useId as usePreviewId } from "react";

export function RadioGroupFieldset() {
  const previewId = usePreviewId();

  return (
    <FieldSet className="w-full max-w-xs">
      <FieldLegend variant="label">Subscription Plan</FieldLegend>
      <FieldDescription>
        Yearly and lifetime plans offer significant savings.
      </FieldDescription>
      <RadioGroup defaultValue="monthly">
        <Field orientation="horizontal">
          <RadioGroupItem value="monthly" id={`${previewId}-plan-monthly`} />
          <FieldLabel
            htmlFor={`${previewId}-plan-monthly`}
            className="font-normal"
          >
            Monthly ($9.99/month)
          </FieldLabel>
        </Field>
        <Field orientation="horizontal">
          <RadioGroupItem value="yearly" id={`${previewId}-plan-yearly`} />
          <FieldLabel
            htmlFor={`${previewId}-plan-yearly`}
            className="font-normal"
          >
            Yearly ($99.99/year)
          </FieldLabel>
        </Field>
        <Field orientation="horizontal">
          <RadioGroupItem value="lifetime" id={`${previewId}-plan-lifetime`} />
          <FieldLabel
            htmlFor={`${previewId}-plan-lifetime`}
            className="font-normal"
          >
            Lifetime ($299.99)
          </FieldLabel>
        </Field>
      </RadioGroup>
    </FieldSet>
  );
}

export default RadioGroupFieldset;
```

## Disabled

Use the `disabled` prop on `RadioGroup` to disable all items.

### Example: radio-group-disabled

```tsx
import { Field, FieldLabel } from "@workspace/ui/components/field";
import {
  RadioGroup,
  RadioGroupItem,
} from "@workspace/ui/components/radio-group";
import { useId as usePreviewId } from "react";

export function RadioGroupDisabled() {
  const previewId = usePreviewId();

  return (
    <RadioGroup defaultValue="option2" className="w-fit">
      <Field orientation="horizontal" data-disabled>
        <RadioGroupItem
          value="option1"
          id={`${previewId}-disabled-1`}
          disabled
        />
        <FieldLabel htmlFor={`${previewId}-disabled-1`} className="font-normal">
          Disabled
        </FieldLabel>
      </Field>
      <Field orientation="horizontal">
        <RadioGroupItem value="option2" id={`${previewId}-disabled-2`} />
        <FieldLabel htmlFor={`${previewId}-disabled-2`} className="font-normal">
          Option 2
        </FieldLabel>
      </Field>
      <Field orientation="horizontal">
        <RadioGroupItem value="option3" id={`${previewId}-disabled-3`} />
        <FieldLabel htmlFor={`${previewId}-disabled-3`} className="font-normal">
          Option 3
        </FieldLabel>
      </Field>
    </RadioGroup>
  );
}

export default RadioGroupDisabled;
```

## Invalid

Use `aria-invalid` on `RadioGroupItem` and `data-invalid` on `Field` to show validation errors.

### Example: radio-group-invalid

```tsx
import {
  Field,
  FieldDescription,
  FieldLabel,
  FieldLegend,
  FieldSet,
} from "@workspace/ui/components/field";
import {
  RadioGroup,
  RadioGroupItem,
} from "@workspace/ui/components/radio-group";
import { useId as usePreviewId } from "react";

export function RadioGroupInvalid() {
  const previewId = usePreviewId();

  return (
    <FieldSet className="w-full max-w-xs">
      <FieldLegend variant="label">Notification Preferences</FieldLegend>
      <FieldDescription>
        Choose how you want to receive notifications.
      </FieldDescription>
      <RadioGroup defaultValue="email">
        <Field orientation="horizontal" data-invalid>
          <RadioGroupItem
            value="email"
            id={`${previewId}-invalid-email`}
            aria-invalid
          />
          <FieldLabel
            htmlFor={`${previewId}-invalid-email`}
            className="font-normal"
          >
            Email only
          </FieldLabel>
        </Field>
        <Field orientation="horizontal" data-invalid>
          <RadioGroupItem
            value="sms"
            id={`${previewId}-invalid-sms`}
            aria-invalid
          />
          <FieldLabel
            htmlFor={`${previewId}-invalid-sms`}
            className="font-normal"
          >
            SMS only
          </FieldLabel>
        </Field>
        <Field orientation="horizontal" data-invalid>
          <RadioGroupItem
            value="both"
            id={`${previewId}-invalid-both`}
            aria-invalid
          />
          <FieldLabel
            htmlFor={`${previewId}-invalid-both`}
            className="font-normal"
          >
            Both Email & SMS
          </FieldLabel>
        </Field>
      </RadioGroup>
    </FieldSet>
  );
}

export default RadioGroupInvalid;
```

## RTL

To enable RTL support in shadcn/ui, see the [RTL configuration guide](https://ui.shadcn.com/docs/rtl).

### Example: radio-group-rtl

```tsx
"use client";

import {
  Field,
  FieldContent,
  FieldDescription,
  FieldLabel,
} from "@workspace/ui/components/field";
import {
  RadioGroup,
  RadioGroupItem,
} from "@workspace/ui/components/radio-group";
import { useId as usePreviewId } from "react";
import { type Translations, useTranslation } from "./support";

const translations: Translations = {
  en: {
    dir: "ltr",
    values: {
      default: "Default",
      defaultDescription: "Standard spacing for most use cases.",
      comfortable: "Comfortable",
      comfortableDescription: "More space between elements.",
      compact: "Compact",
      compactDescription: "Minimal spacing for dense layouts.",
    },
  },
  ar: {
    dir: "rtl",
    values: {
      default: "افتراضي",
      defaultDescription: "تباعد قياسي لمعظم حالات الاستخدام.",
      comfortable: "مريح",
      comfortableDescription: "مساحة أكبر بين العناصر.",
      compact: "مضغوط",
      compactDescription: "تباعد أدنى للتخطيطات الكثيفة.",
    },
  },
  he: {
    dir: "rtl",
    values: {
      default: "ברירת מחדל",
      defaultDescription: "ריווח סטנדרטי לרוב מקרי השימוש.",
      comfortable: "נוח",
      comfortableDescription: "יותר מקום בין האלמנטים.",
      compact: "קומפקטי",
      compactDescription: "ריווח מינימלי לפריסות צפופות.",
    },
  },
};

export function RadioGroupRtl() {
  const previewId = usePreviewId();

  const { dir, t } = useTranslation(translations, "ar");

  return (
    <RadioGroup defaultValue="comfortable" className="w-fit" dir={dir}>
      <Field orientation="horizontal">
        <RadioGroupItem value="default" id={`${previewId}-r1-rtl`} dir={dir} />
        <FieldContent>
          <FieldLabel htmlFor={`${previewId}-r1-rtl`} dir={dir}>
            {t.default}
          </FieldLabel>
          <FieldDescription dir={dir}>{t.defaultDescription}</FieldDescription>
        </FieldContent>
      </Field>
      <Field orientation="horizontal">
        <RadioGroupItem
          value="comfortable"
          id={`${previewId}-r2-rtl`}
          dir={dir}
        />
        <FieldContent>
          <FieldLabel htmlFor={`${previewId}-r2-rtl`} dir={dir}>
            {t.comfortable}
          </FieldLabel>
          <FieldDescription dir={dir}>
            {t.comfortableDescription}
          </FieldDescription>
        </FieldContent>
      </Field>
      <Field orientation="horizontal">
        <RadioGroupItem value="compact" id={`${previewId}-r3-rtl`} dir={dir} />
        <FieldContent>
          <FieldLabel htmlFor={`${previewId}-r3-rtl`} dir={dir}>
            {t.compact}
          </FieldLabel>
          <FieldDescription dir={dir}>{t.compactDescription}</FieldDescription>
        </FieldContent>
      </Field>
    </RadioGroup>
  );
}

export default RadioGroupRtl;
```

## API Reference

See the [Base UI Radio Group](https://base-ui.com/react/components/radio-group#api-reference) documentation.

- [Documentation](https://base-ui.com/react/components/radio-group)
- [API reference](https://base-ui.com/react/components/radio-group#api-reference)


---

# Resizable

Accessible resizable panel groups and layouts with keyboard support.

Page: https://sui.draco.dev/docs/components/resizable

### Example: resizable-demo

```tsx
import {
  ResizableHandle,
  ResizablePanel,
  ResizablePanelGroup,
} from "@workspace/ui/components/resizable";

export default function ResizableDemo() {
  return (
    <ResizablePanelGroup
      orientation="horizontal"
      className="max-w-sm rounded-lg border"
    >
      <ResizablePanel defaultSize="50%">
        <div className="flex h-[200px] items-center justify-center p-6">
          <span className="font-semibold">One</span>
        </div>
      </ResizablePanel>
      <ResizableHandle withHandle />
      <ResizablePanel defaultSize="50%">
        <ResizablePanelGroup orientation="vertical">
          <ResizablePanel defaultSize="25%">
            <div className="flex h-full items-center justify-center p-6">
              <span className="font-semibold">Two</span>
            </div>
          </ResizablePanel>
          <ResizableHandle withHandle />
          <ResizablePanel defaultSize="75%">
            <div className="flex h-full items-center justify-center p-6">
              <span className="font-semibold">Three</span>
            </div>
          </ResizablePanel>
        </ResizablePanelGroup>
      </ResizablePanel>
    </ResizablePanelGroup>
  );
}
```

## About

The `Resizable` component is built on top of [react-resizable-panels](https://github.com/bvaughn/react-resizable-panels) by [bvaughn](https://github.com/bvaughn).

## Installation

```bash
bunx --bun shadcn@latest add @sui/resizable
```

Install with the shadcn CLI or use the shared `@workspace/ui` package. Follow the [installation guide](/docs/installation) to configure the registry, load styles, and choose import aliases.

## Usage

```tsx showLineNumbers
import {
  ResizableHandle,
  ResizablePanel,
  ResizablePanelGroup,
} from "@workspace/ui/components/resizable"
```

```tsx showLineNumbers
<ResizablePanelGroup orientation="horizontal">
  <ResizablePanel>One</ResizablePanel>
  <ResizableHandle />
  <ResizablePanel>Two</ResizablePanel>
</ResizablePanelGroup>
```

## Composition

Use the following composition to build a `ResizablePanelGroup`:

```text
ResizablePanelGroup
├── ResizablePanel
├── ResizableHandle
└── ResizablePanel
```

## Vertical

Use `orientation="vertical"` for vertical resizing.

### Example: resizable-vertical

```tsx
import {
  ResizableHandle,
  ResizablePanel,
  ResizablePanelGroup,
} from "@workspace/ui/components/resizable";

export function ResizableVertical() {
  return (
    <ResizablePanelGroup
      orientation="vertical"
      className="min-h-[200px] max-w-sm rounded-lg border"
    >
      <ResizablePanel defaultSize="25%">
        <div className="flex h-full items-center justify-center p-6">
          <span className="font-semibold">Header</span>
        </div>
      </ResizablePanel>
      <ResizableHandle />
      <ResizablePanel defaultSize="75%">
        <div className="flex h-full items-center justify-center p-6">
          <span className="font-semibold">Content</span>
        </div>
      </ResizablePanel>
    </ResizablePanelGroup>
  );
}

export default ResizableVertical;
```

## Handle

Use the `withHandle` prop on `ResizableHandle` to show a visible handle.

### Example: resizable-handle

```tsx
import {
  ResizableHandle,
  ResizablePanel,
  ResizablePanelGroup,
} from "@workspace/ui/components/resizable";

export default function ResizableHandleDemo() {
  return (
    <ResizablePanelGroup
      orientation="horizontal"
      className="min-h-[200px] max-w-sm rounded-lg border"
    >
      <ResizablePanel defaultSize="25%">
        <div className="flex h-full items-center justify-center p-6">
          <span className="font-semibold">Sidebar</span>
        </div>
      </ResizablePanel>
      <ResizableHandle withHandle />
      <ResizablePanel defaultSize="75%">
        <div className="flex h-full items-center justify-center p-6">
          <span className="font-semibold">Content</span>
        </div>
      </ResizablePanel>
    </ResizablePanelGroup>
  );
}
```

## RTL

To enable RTL support in shadcn/ui, see the [RTL configuration guide](https://ui.shadcn.com/docs/rtl).

### Example: resizable-rtl

```tsx
"use client";

import {
  ResizableHandle,
  ResizablePanel,
  ResizablePanelGroup,
} from "@workspace/ui/components/resizable";
import { type Translations, useTranslation } from "./support";

const translations: Translations = {
  en: {
    dir: "ltr",
    values: {
      one: "One",
      two: "Two",
      three: "Three",
    },
  },
  ar: {
    dir: "rtl",
    values: {
      one: "واحد",
      two: "اثنان",
      three: "ثلاثة",
    },
  },
  he: {
    dir: "rtl",
    values: {
      one: "אחד",
      two: "שניים",
      three: "שלושה",
    },
  },
};

export function ResizableRtl() {
  const { dir, t } = useTranslation(translations, "ar");

  return (
    <ResizablePanelGroup
      orientation="horizontal"
      className="max-w-sm rounded-lg border"
      dir={dir}
    >
      <ResizablePanel defaultSize="50%">
        <div className="flex h-[200px] items-center justify-center p-6">
          <span className="font-semibold">{t.one}</span>
        </div>
      </ResizablePanel>
      <ResizableHandle withHandle />
      <ResizablePanel defaultSize="50%">
        <ResizablePanelGroup orientation="vertical" dir={dir}>
          <ResizablePanel defaultSize="25%">
            <div className="flex h-full items-center justify-center p-6">
              <span className="font-semibold">{t.two}</span>
            </div>
          </ResizablePanel>
          <ResizableHandle withHandle />
          <ResizablePanel defaultSize="75%">
            <div className="flex h-full items-center justify-center p-6">
              <span className="font-semibold">{t.three}</span>
            </div>
          </ResizablePanel>
        </ResizablePanelGroup>
      </ResizablePanel>
    </ResizablePanelGroup>
  );
}

export default ResizableRtl;
```

## API Reference

See the [react-resizable-panels](https://github.com/bvaughn/react-resizable-panels/tree/main/packages/react-resizable-panels) documentation.

## Changelog

### 2025-02-02 `react-resizable-panels` v4

Updated to `react-resizable-panels` v4. See the [v4.0.0 release notes](https://github.com/bvaughn/react-resizable-panels/releases/tag/4.0.0) for full details.

If you're using `react-resizable-panels` primitives directly, note the following changes:

| v3                           | v4                      |
| ---------------------------- | ----------------------- |
| `PanelGroup`                 | `Group`                 |
| `PanelResizeHandle`          | `Separator`             |
| `direction` prop             | `orientation` prop      |
| `defaultSize={50}`           | `defaultSize="50%"`     |
| `onLayout`                   | `onLayoutChange`        |
| `ImperativePanelHandle`      | `PanelImperativeHandle` |
| `ref` prop on Panel          | `panelRef` prop         |
| `data-panel-group-direction` | `aria-orientation`      |

  The shadcn/ui wrapper components (`ResizablePanelGroup`, `ResizablePanel`,
  `ResizableHandle`) remain unchanged.

- [Documentation](https://github.com/bvaughn/react-resizable-panels)
- [API reference](https://github.com/bvaughn/react-resizable-panels/tree/main/packages/react-resizable-panels)


---

# Scroll Area

Augments native scroll functionality for custom, cross-browser styling.

Page: https://sui.draco.dev/docs/components/scroll-area

### Example: scroll-area-demo

```tsx
import { ScrollArea } from "@workspace/ui/components/scroll-area";
import { Separator } from "@workspace/ui/components/separator";
import * as React from "react";

const tags = Array.from({ length: 50 }).map(
  (_, i, a) => `v1.2.0-beta.${a.length - i}`,
);

export function ScrollAreaDemo() {
  return (
    <ScrollArea className="h-72 w-48 rounded-md border">
      <div className="p-4">
        <h4 className="mb-4 font-medium text-sm leading-none">Tags</h4>
        {tags.map((tag) => (
          <React.Fragment key={tag}>
            <div className="text-sm">{tag}</div>
            <Separator className="my-2" />
          </React.Fragment>
        ))}
      </div>
    </ScrollArea>
  );
}

export default ScrollAreaDemo;
```

## Installation

```bash
bunx --bun shadcn@latest add @sui/scroll-area
```

Install with the shadcn CLI or use the shared `@workspace/ui` package. Follow the [installation guide](/docs/installation) to configure the registry, load styles, and choose import aliases.

## Usage

```tsx showLineNumbers
import { ScrollArea, ScrollBar } from "@workspace/ui/components/scroll-area"
```

```tsx showLineNumbers
<ScrollArea className="h-[200px] w-[350px] rounded-md border p-4">
  Your scrollable content here.
</ScrollArea>
```

## Composition

Use the following composition to build a `ScrollArea`:

```text
ScrollArea
└── ScrollBar
```

## Horizontal

Use `ScrollBar` with `orientation="horizontal"` for horizontal scrolling.

### Example: scroll-area-horizontal-demo

```tsx
import { ScrollArea, ScrollBar } from "@workspace/ui/components/scroll-area";

export interface Artwork {
  artist: string;
  art: string;
}

export const works: Artwork[] = [
  {
    artist: "Ornella Binni",
    art: "https://images.unsplash.com/photo-1465869185982-5a1a7522cbcb?auto=format&fit=crop&w=300&q=80",
  },
  {
    artist: "Tom Byrom",
    art: "https://images.unsplash.com/photo-1548516173-3cabfa4607e9?auto=format&fit=crop&w=300&q=80",
  },
  {
    artist: "Vladimir Malyavko",
    art: "https://images.unsplash.com/photo-1494337480532-3725c85fd2ab?auto=format&fit=crop&w=300&q=80",
  },
];

export function ScrollAreaHorizontalDemo() {
  return (
    <ScrollArea className="w-96 whitespace-nowrap rounded-md border">
      <div className="flex w-max space-x-4 p-4">
        {works.map((artwork) => (
          <figure key={artwork.artist} className="shrink-0">
            <div className="overflow-hidden rounded-md">
              <img
                src={artwork.art}
                alt={`Artwork by ${artwork.artist}`}
                className="aspect-[3/4] h-fit w-fit object-cover"
                width={300}
                height={400}
              />
            </div>
            <figcaption className="pt-2 text-muted-foreground text-xs">
              Photo by{" "}
              <span className="font-semibold text-foreground">
                {artwork.artist}
              </span>
            </figcaption>
          </figure>
        ))}
      </div>
      <ScrollBar orientation="horizontal" />
    </ScrollArea>
  );
}

export default ScrollAreaHorizontalDemo;
```

## RTL

To enable RTL support in shadcn/ui, see the [RTL configuration guide](https://ui.shadcn.com/docs/rtl).

### Example: scroll-area-rtl

```tsx
"use client";

import { ScrollArea } from "@workspace/ui/components/scroll-area";
import { Separator } from "@workspace/ui/components/separator";
import * as React from "react";
import { type Translations, useTranslation } from "./support";

const tags = Array.from({ length: 50 }).map(
  (_, i, a) => `v1.2.0-beta.${a.length - i}`,
);

const translations: Translations = {
  en: {
    dir: "ltr",
    values: {
      tags: "Tags",
    },
  },
  ar: {
    dir: "rtl",
    values: {
      tags: "العلامات",
    },
  },
  he: {
    dir: "rtl",
    values: {
      tags: "תגיות",
    },
  },
};

export function ScrollAreaRtl() {
  const { dir, t } = useTranslation(translations, "ar");

  return (
    <ScrollArea className="h-72 w-48 rounded-md border" dir={dir}>
      <div className="p-4">
        <h4 className="mb-4 font-medium text-sm leading-none">{t.tags}</h4>
        {tags.map((tag) => (
          <React.Fragment key={tag}>
            <div className="text-sm">{tag}</div>
            <Separator className="my-2" />
          </React.Fragment>
        ))}
      </div>
    </ScrollArea>
  );
}

export default ScrollAreaRtl;
```

## API Reference

See the [Base UI Scroll Area](https://base-ui.com/react/components/scroll-area#api-reference) documentation.

- [Documentation](https://base-ui.com/react/components/scroll-area)
- [API reference](https://base-ui.com/react/components/scroll-area#api-reference)


---

# Select

Displays a list of options for the user to pick from—triggered by a button.

Page: https://sui.draco.dev/docs/components/select

### Example: select-demo

```tsx
import {
  Select,
  SelectContent,
  SelectGroup,
  SelectItem,
  SelectLabel,
  SelectTrigger,
  SelectValue,
} from "@workspace/ui/components/select";

const items = [
  { label: "Select a fruit", value: null },
  { label: "Apple", value: "apple" },
  { label: "Banana", value: "banana" },
  { label: "Blueberry", value: "blueberry" },
  { label: "Grapes", value: "grapes" },
  { label: "Pineapple", value: "pineapple" },
];

export function SelectDemo() {
  return (
    <Select items={items}>
      <SelectTrigger className="w-full max-w-48">
        <SelectValue />
      </SelectTrigger>
      <SelectContent>
        <SelectGroup>
          <SelectLabel>Fruits</SelectLabel>
          {items.map((item) => (
            <SelectItem key={item.value} value={item.value}>
              {item.label}
            </SelectItem>
          ))}
        </SelectGroup>
      </SelectContent>
    </Select>
  );
}

export default SelectDemo;
```

## Installation

```bash
bunx --bun shadcn@latest add @sui/select
```

Install with the shadcn CLI or use the shared `@workspace/ui` package. Follow the [installation guide](/docs/installation) to configure the registry, load styles, and choose import aliases.

## Usage

```tsx showLineNumbers
import {
  Select,
  SelectContent,
  SelectGroup,
  SelectItem,
  SelectTrigger,
  SelectValue,
} from "@workspace/ui/components/select"
```

```tsx showLineNumbers
const items = [
  { label: "Light", value: "light" },
  { label: "Dark", value: "dark" },
  { label: "System", value: "system" },
]

<Select items={items}>
  <SelectTrigger className="w-[180px]">
    <SelectValue placeholder="Theme" />
  </SelectTrigger>
  <SelectContent>
    <SelectGroup>
      {items.map((item) => (
        <SelectItem key={item.value} value={item.value}>
          {item.label}
        </SelectItem>
      ))}
    </SelectGroup>
  </SelectContent>
</Select>
```

## Composition

Use the following composition to build a `Select`:

```text
Select
├── SelectTrigger
│   └── SelectValue
└── SelectContent
    ├── SelectGroup
    │   ├── SelectLabel
    │   ├── SelectItem
    │   └── SelectItem
    ├── SelectSeparator
    └── SelectGroup
        ├── SelectLabel
        ├── SelectItem
        └── SelectItem
```

## Align Item With Trigger

Use `alignItemWithTrigger` on `SelectContent` to control whether the selected item aligns with the trigger. When `true` (default), the popup positions so the selected item appears over the trigger. When `false`, the popup aligns to the trigger edge.

### Example: select-align-item

```tsx
"use client";

import {
  Field,
  FieldContent,
  FieldDescription,
  FieldGroup,
  FieldLabel,
} from "@workspace/ui/components/field";
import {
  Select,
  SelectContent,
  SelectGroup,
  SelectItem,
  SelectTrigger,
  SelectValue,
} from "@workspace/ui/components/select";
import { Switch } from "@workspace/ui/components/switch";
import * as React from "react";
import { useId as usePreviewId } from "react";

const items = [
  { label: "Select a fruit", value: null },
  { label: "Apple", value: "apple" },
  { label: "Banana", value: "banana" },
  { label: "Blueberry", value: "blueberry" },
  { label: "Grapes", value: "grapes" },
  { label: "Pineapple", value: "pineapple" },
];

export function SelectAlignItem() {
  const previewId = usePreviewId();

  const [alignItemWithTrigger, setAlignItemWithTrigger] = React.useState(true);

  return (
    <FieldGroup className="w-full max-w-xs">
      <Field orientation="horizontal">
        <FieldContent>
          <FieldLabel htmlFor={`${previewId}-align-item`}>
            Align Item
          </FieldLabel>
          <FieldDescription>
            Toggle to align the item with the trigger.
          </FieldDescription>
        </FieldContent>
        <Switch
          id={`${previewId}-align-item`}
          checked={alignItemWithTrigger}
          onCheckedChange={setAlignItemWithTrigger}
        />
      </Field>
      <Field>
        <Select items={items} defaultValue="banana">
          <SelectTrigger>
            <SelectValue />
          </SelectTrigger>
          <SelectContent alignItemWithTrigger={alignItemWithTrigger}>
            <SelectGroup>
              {items.map((item) => (
                <SelectItem key={item.value} value={item.value}>
                  {item.label}
                </SelectItem>
              ))}
            </SelectGroup>
          </SelectContent>
        </Select>
      </Field>
    </FieldGroup>
  );
}

export default SelectAlignItem;
```

## Groups

Use `SelectGroup`, `SelectLabel`, and `SelectSeparator` to organize items.

### Example: select-groups

```tsx
import {
  Select,
  SelectContent,
  SelectGroup,
  SelectItem,
  SelectLabel,
  SelectSeparator,
  SelectTrigger,
  SelectValue,
} from "@workspace/ui/components/select";

export function SelectGroups() {
  const fruits = [
    { label: "Apple", value: "apple" },
    { label: "Banana", value: "banana" },
    { label: "Blueberry", value: "blueberry" },
  ];
  const vegetables = [
    { label: "Carrot", value: "carrot" },
    { label: "Broccoli", value: "broccoli" },
    { label: "Spinach", value: "spinach" },
  ];
  const allItems = [
    { label: "Select a fruit", value: null },
    ...fruits,
    ...vegetables,
  ];
  return (
    <Select items={allItems}>
      <SelectTrigger className="w-full max-w-48">
        <SelectValue />
      </SelectTrigger>
      <SelectContent>
        <SelectGroup>
          <SelectLabel>Fruits</SelectLabel>
          {fruits.map((item) => (
            <SelectItem key={item.value} value={item.value}>
              {item.label}
            </SelectItem>
          ))}
        </SelectGroup>
        <SelectSeparator />
        <SelectGroup>
          <SelectLabel>Vegetables</SelectLabel>
          {vegetables.map((item) => (
            <SelectItem key={item.value} value={item.value}>
              {item.label}
            </SelectItem>
          ))}
        </SelectGroup>
      </SelectContent>
    </Select>
  );
}

export default SelectGroups;
```

## Scrollable

A select with many items that scrolls.

### Example: select-scrollable

```tsx
import {
  Select,
  SelectContent,
  SelectGroup,
  SelectItem,
  SelectLabel,
  SelectTrigger,
  SelectValue,
} from "@workspace/ui/components/select";

const northAmerica = [
  { label: "Eastern Standard Time", value: "est" },
  { label: "Central Standard Time", value: "cst" },
  { label: "Mountain Standard Time", value: "mst" },
  { label: "Pacific Standard Time", value: "pst" },
  { label: "Alaska Standard Time", value: "akst" },
  { label: "Hawaii Standard Time", value: "hst" },
];

const europeAfrica = [
  { label: "Greenwich Mean Time", value: "gmt" },
  { label: "Central European Time", value: "cet" },
  { label: "Eastern European Time", value: "eet" },
  { label: "Western European Summer Time", value: "west" },
  { label: "Central Africa Time", value: "cat" },
  { label: "East Africa Time", value: "eat" },
];

const asia = [
  { label: "Moscow Time", value: "msk" },
  { label: "India Standard Time", value: "ist" },
  { label: "China Standard Time", value: "cst_china" },
  { label: "Japan Standard Time", value: "jst" },
  { label: "Korea Standard Time", value: "kst" },
  { label: "Indonesia Central Standard Time", value: "ist_indonesia" },
];

const australiaPacific = [
  { label: "Australian Western Standard Time", value: "awst" },
  { label: "Australian Central Standard Time", value: "acst" },
  { label: "Australian Eastern Standard Time", value: "aest" },
  { label: "New Zealand Standard Time", value: "nzst" },
  { label: "Fiji Time", value: "fjt" },
];

const southAmerica = [
  { label: "Argentina Time", value: "art" },
  { label: "Bolivia Time", value: "bot" },
  { label: "Brasilia Time", value: "brt" },
  { label: "Chile Standard Time", value: "clt" },
];

const items = [
  { label: "Select a timezone", value: null },
  ...northAmerica,
  ...europeAfrica,
  ...asia,
  ...australiaPacific,
  ...southAmerica,
];

export function SelectScrollable() {
  return (
    <Select items={items}>
      <SelectTrigger className="w-full max-w-64">
        <SelectValue />
      </SelectTrigger>
      <SelectContent>
        <SelectGroup>
          <SelectLabel>North America</SelectLabel>
          {northAmerica.map((item) => (
            <SelectItem key={item.value} value={item.value}>
              {item.label}
            </SelectItem>
          ))}
        </SelectGroup>
        <SelectGroup>
          <SelectLabel>Europe & Africa</SelectLabel>
          {europeAfrica.map((item) => (
            <SelectItem key={item.value} value={item.value}>
              {item.label}
            </SelectItem>
          ))}
        </SelectGroup>
        <SelectGroup>
          <SelectLabel>Asia</SelectLabel>
          {asia.map((item) => (
            <SelectItem key={item.value} value={item.value}>
              {item.label}
            </SelectItem>
          ))}
        </SelectGroup>
        <SelectGroup>
          <SelectLabel>Australia & Pacific</SelectLabel>
          {australiaPacific.map((item) => (
            <SelectItem key={item.value} value={item.value}>
              {item.label}
            </SelectItem>
          ))}
        </SelectGroup>
        <SelectGroup>
          <SelectLabel>South America</SelectLabel>
          {southAmerica.map((item) => (
            <SelectItem key={item.value} value={item.value}>
              {item.label}
            </SelectItem>
          ))}
        </SelectGroup>
      </SelectContent>
    </Select>
  );
}

export default SelectScrollable;
```

## Disabled

### Example: select-disabled

```tsx
import {
  Select,
  SelectContent,
  SelectGroup,
  SelectItem,
  SelectTrigger,
  SelectValue,
} from "@workspace/ui/components/select";

export function SelectDisabled() {
  const items = [
    { label: "Select a fruit", value: null },
    { label: "Apple", value: "apple" },
    { label: "Banana", value: "banana" },
    { label: "Blueberry", value: "blueberry" },
    { label: "Grapes", value: "grapes", disabled: true },
    { label: "Pineapple", value: "pineapple" },
  ];
  return (
    <Select items={items} disabled>
      <SelectTrigger className="w-full max-w-48">
        <SelectValue />
      </SelectTrigger>
      <SelectContent>
        <SelectGroup>
          {items.map((item) => (
            <SelectItem
              key={item.value}
              value={item.value}
              disabled={item.disabled}
            >
              {item.label}
            </SelectItem>
          ))}
        </SelectGroup>
      </SelectContent>
    </Select>
  );
}

export default SelectDisabled;
```

## Invalid

Add the `data-invalid` attribute to the `Field` component and the `aria-invalid` attribute to the `SelectTrigger` component to show an error state.

```tsx showLineNumbers /data-invalid/ /aria-invalid/
<Field data-invalid>
  <FieldLabel>Fruit</FieldLabel>
  <SelectTrigger aria-invalid>
    <SelectValue />
  </SelectTrigger>
</Field>
```

### Example: select-invalid

```tsx
import { Field, FieldError, FieldLabel } from "@workspace/ui/components/field";
import {
  Select,
  SelectContent,
  SelectGroup,
  SelectItem,
  SelectTrigger,
  SelectValue,
} from "@workspace/ui/components/select";

const items = [
  { label: "Select a fruit", value: null },
  { label: "Apple", value: "apple" },
  { label: "Banana", value: "banana" },
  { label: "Blueberry", value: "blueberry" },
];

export function SelectInvalid() {
  return (
    <Field data-invalid className="w-full max-w-48">
      <FieldLabel>Fruit</FieldLabel>
      <Select items={items}>
        <SelectTrigger aria-invalid>
          <SelectValue />
        </SelectTrigger>
        <SelectContent>
          <SelectGroup>
            {items.map((item) => (
              <SelectItem key={item.value} value={item.value}>
                {item.label}
              </SelectItem>
            ))}
          </SelectGroup>
        </SelectContent>
      </Select>
      <FieldError>Please select a fruit.</FieldError>
    </Field>
  );
}

export default SelectInvalid;
```

## RTL

To enable RTL support in shadcn/ui, see the [RTL configuration guide](https://ui.shadcn.com/docs/rtl).

### Example: select-rtl

```tsx
"use client";

import {
  Select,
  SelectContent,
  SelectGroup,
  SelectItem,
  SelectLabel,
  SelectSeparator,
  SelectTrigger,
  SelectValue,
} from "@workspace/ui/components/select";
import * as React from "react";
import { type Translations, useTranslation } from "./support";

const translations: Translations = {
  en: {
    dir: "ltr",
    values: {
      selectFruit: "Select a fruit",
      fruits: "Fruits",
      apple: "Apple",
      banana: "Banana",
      blueberry: "Blueberry",
      grapes: "Grapes",
      pineapple: "Pineapple",
      vegetables: "Vegetables",
      carrot: "Carrot",
      broccoli: "Broccoli",
      spinach: "Spinach",
    },
  },
  ar: {
    dir: "rtl",
    values: {
      selectFruit: "اختر فاكهة",
      fruits: "الفواكه",
      apple: "تفاح",
      banana: "موز",
      blueberry: "توت أزرق",
      grapes: "عنب",
      pineapple: "أناناس",
      vegetables: "الخضروات",
      carrot: "جزر",
      broccoli: "بروكلي",
      spinach: "سبانخ",
    },
  },
  he: {
    dir: "rtl",
    values: {
      selectFruit: "בחר פרי",
      fruits: "פירות",
      apple: "תפוח",
      banana: "בננה",
      blueberry: "אוכמניה",
      grapes: "ענבים",
      pineapple: "אננס",
      vegetables: "ירקות",
      carrot: "גזר",
      broccoli: "ברוקולי",
      spinach: "תרד",
    },
  },
};

export function SelectRtl() {
  const { dir, t, language } = useTranslation(translations, "ar");
  const [selectedFruit, setSelectedFruit] = React.useState<string | null>(null);

  const fruits = [
    { label: t.apple, value: "apple" },
    { label: t.banana, value: "banana" },
    { label: t.blueberry, value: "blueberry" },
    { label: t.grapes, value: "grapes" },
    { label: t.pineapple, value: "pineapple" },
  ];

  const vegetables = [
    { label: t.carrot, value: "carrot" },
    { label: t.broccoli, value: "broccoli" },
    { label: t.spinach, value: "spinach" },
  ];

  const allItems = [
    { label: t.selectFruit, value: null },
    ...fruits,
    ...vegetables,
  ];

  return (
    <Select
      items={allItems}
      value={selectedFruit}
      onValueChange={setSelectedFruit}
    >
      <SelectTrigger className="w-32" dir={dir}>
        <SelectValue />
      </SelectTrigger>
      <SelectContent dir={dir} data-lang={dir === "rtl" ? language : undefined}>
        <SelectGroup>
          <SelectLabel>{t.fruits}</SelectLabel>
          {fruits.map((item) => (
            <SelectItem key={item.value} value={item.value}>
              {item.label}
            </SelectItem>
          ))}
        </SelectGroup>
        <SelectSeparator />
        <SelectGroup>
          <SelectLabel>{t.vegetables}</SelectLabel>
          {vegetables.map((item) => (
            <SelectItem key={item.value} value={item.value}>
              {item.label}
            </SelectItem>
          ))}
        </SelectGroup>
      </SelectContent>
    </Select>
  );
}

export default SelectRtl;
```

## API Reference

See the [Base UI Select](https://base-ui.com/react/components/select#api-reference) documentation.

- [Documentation](https://base-ui.com/react/components/select)
- [API reference](https://base-ui.com/react/components/select#api-reference)


---

# Sensitive Input

A sensitive-value input with a fixed mask, click-to-reveal interaction, and copy feedback.

Page: https://sui.draco.dev/docs/components/sensitive-input

### Example: sensitive-input-demo

```tsx
"use client";

import { Button } from "@workspace/ui/components/button";
import {
  Field,
  FieldDescription,
  FieldLabel,
} from "@workspace/ui/components/field";
import { SensitiveInput } from "@workspace/ui/components/sensitive-input";
import { useId, useRef, useState } from "react";
import type { ExampleProps } from "../types";

const defaultPassword = "a-private-example";

export default function SensitiveInputDemo({ locale }: ExampleProps) {
  const id = useId();
  const inputRef = useRef<HTMLInputElement>(null);
  const [copyResult, setCopyResult] = useState<
    "matched" | "mismatched" | "failed" | null
  >(null);
  const [matchesDefault, setMatchesDefault] = useState<boolean | null>(null);
  const [submitted, setSubmitted] = useState<boolean | null>(null);
  const [submissions, setSubmissions] = useState(0);
  const chinese = locale === "zh-CN";
  const stateLabels = chinese
    ? {
        idle: "尚未复制",
        failed: "复制失败，请重试",
        matched: "复制值与当前输入匹配",
        mismatched: "复制值与当前输入不匹配",
        defaultMatched: "复制值与初始默认值匹配",
        defaultMismatched: "复制值与初始默认值不匹配",
        submittedMatched: "；提交值与当前输入匹配",
        submittedMismatched: "；提交值与当前输入不匹配",
      }
    : {
        idle: "Not copied yet",
        failed: "Copy failed. Try again.",
        matched: "Copied value matches the current input.",
        mismatched: "Copied value does not match the current input.",
        defaultMatched: "Copied value matches the original default.",
        defaultMismatched: "Copied value does not match the original default.",
        submittedMatched: "; submitted value matches the current input.",
        submittedMismatched:
          "; submitted value does not match the current input.",
      };

  return (
    <form
      className="grid w-full max-w-sm gap-4"
      onSubmit={(event) => {
        event.preventDefault();
        setSubmitted(
          new FormData(event.currentTarget).get("password") ===
            inputRef.current?.value,
        );
        setSubmissions((count) => count + 1);
      }}
      onReset={() => {
        setCopyResult(null);
        setMatchesDefault(null);
        setSubmitted(null);
        setSubmissions(0);
      }}
    >
      <Field>
        <FieldLabel htmlFor={id}>{chinese ? "密码" : "Password"}</FieldLabel>
        <SensitiveInput
          ref={inputRef}
          id={id}
          name="password"
          required
          defaultValue={defaultPassword}
          onChange={() => {
            setCopyResult(null);
            setMatchesDefault(null);
          }}
          autoComplete="current-password"
          aria-describedby={`${id}-description`}
          onCopySuccess={(value) => {
            setCopyResult(
              value === inputRef.current?.value ? "matched" : "mismatched",
            );
            setMatchesDefault(value === defaultPassword);
          }}
          onCopyError={() => {
            setCopyResult("failed");
            setMatchesDefault(null);
          }}
          labels={
            chinese
              ? {
                  reveal: "点击显示",
                  instruction: "点击或按 Enter 显示内容",
                  hidden: "内容已隐藏",
                  show: "显示密码",
                  hide: "隐藏密码",
                  copy: "复制密码",
                  pending: "正在复制密码…",
                  copied: "已复制密码",
                  failed: "复制失败，请重试",
                }
              : undefined
          }
        />
        <FieldDescription id={`${id}-description`}>
          {chinese
            ? "点击遮罩或按 Enter 显示后编辑。修改并复制，再重置并复制，核对是否恢复初始默认值"
            : "Click the mask or press Enter to reveal and edit. Copy an edit, then reset and copy again to verify the original default is restored."}
        </FieldDescription>
      </Field>
      <div className="flex gap-2">
        <Button type="submit">{chinese ? "提交" : "Submit"}</Button>
        <Button type="reset" variant="outline">
          {chinese ? "重置" : "Reset"}
        </Button>
      </div>
      <output
        className="grid gap-1 text-muted-foreground text-sm"
        aria-live="polite"
      >
        <span>{stateLabels[copyResult ?? "idle"]}</span>
        {matchesDefault !== null && (
          <span>
            {matchesDefault
              ? stateLabels.defaultMatched
              : stateLabels.defaultMismatched}
          </span>
        )}
        <span>
          {chinese ? `提交次数：${submissions}` : `Submissions: ${submissions}`}
          {submitted !== null &&
            (submitted
              ? stateLabels.submittedMatched
              : stateLabels.submittedMismatched)}
        </span>
      </output>
    </form>
  );
}
```

## Installation

```bash
bunx --bun shadcn@latest add @sui/sensitive-input
```

Install with the shadcn CLI or use the shared `@workspace/ui` package. Follow the [installation guide](/docs/installation) to configure the registry, load styles, and choose import aliases.

## Usage

```tsx
import { SensitiveInput } from "@workspace/ui/components/sensitive-input";

<SensitiveInput
  aria-label="Password"
  autoComplete="current-password"
  defaultValue="example-password"
/>;
```

A nonempty hidden value is covered by a fixed `••••••••` mask, regardless of its length. The native input stays mounted underneath, but editing begins after revealing the value. Hovering or focusing the control shows “Click to reveal” without changing its layout.

Click the mask, or focus its reveal button and press Enter or Space, to reveal the actual input and focus it. The revealed input uses `type="text"`; its eye button hides the value again. Escape returns to the mask and focuses the reveal button. All reveal, hide, and copy actions are `type="button"` controls and do not submit their containing form.

An empty value has no mask and can be edited directly. The first input requests revealing the value. When focus leaves the entire group, a nonempty value is masked again. Moving focus between the input and its internal copy or eye buttons keeps the current state.

## Copying the current value

`copyable` defaults to `true`. The built-in button reads the native input's actual `value` when clicked, including uncontrolled edits and the value restored by a form reset. It does not copy a stale initial value. Copying works while the value is hidden or read-only and does not change visibility.

The copy control is a text tab above the top-right edge, shown on hover or focus within the group. Its width is reserved for pending, copied, and failed feedback so state changes do not shift the layout. The copy button remains available for empty values and can copy an empty string.

The button reports a pending state while the clipboard write is in progress and prevents repeated attempts. It only reports success after the write completes. Successful feedback resets after `resetDelay` milliseconds, with a default of `1500`. A failed attempt provides generic feedback and can be retried; feedback never includes the sensitive value.

`onCopySuccess` receives the successfully written value. `onCopyError` receives an `Error` when writing fails. Use the callbacks for state updates without rendering or logging the sensitive value. For example, compare against the current input through its native ref and display only whether the values match:

```tsx
import { SensitiveInput } from "@workspace/ui/components/sensitive-input";
import { useRef, useState } from "react";

export function CopyVerification() {
  const inputRef = useRef<HTMLInputElement>(null);
  const [matches, setMatches] = useState<boolean | null>(null);
  const [failed, setFailed] = useState(false);

  return (
    <>
      <SensitiveInput
        ref={inputRef}
        aria-label="API key"
        defaultValue="example-api-key"
        onCopySuccess={(value) => {
          setFailed(false);
          setMatches(value === inputRef.current?.value);
        }}
        onCopyError={() => {
          setFailed(true);
          setMatches(null);
        }}
      />
      <output aria-live="polite">
        {failed && "Copy failed. Try again."}
        {!failed && matches === null && "Not copied yet"}
        {!failed && matches !== null && (
          matches
            ? "Copied value matches the current input."
            : "Copied value does not match the current input."
        )}
      </output>
    </>
  );
}
```

The input's native `onCopy` remains a clipboard event handler for selection-based copying. The built-in button uses `onCopySuccess` for its asynchronous result instead.

## Controlled state

Control the input value with native `value` and `onChange`. Visibility is independent: use `visible` and `onVisibleChange`, or set `defaultVisible` for an uncontrolled input.

Controlled `visible` remains authoritative. Clicks, keyboard actions, first input into an empty field, and leaving the group request changes through `onVisibleChange`; update `visible` in that callback to accept them. Copying always reads the current native value and never requests a visibility change.

This example verifies the copied value through `ref`, exposes the native `onCopy` event count, and keeps all sensitive content out of its feedback.

### Example: sensitive-input-controlled

```tsx
"use client";

import { Button } from "@workspace/ui/components/button";
import {
  Field,
  FieldDescription,
  FieldLabel,
} from "@workspace/ui/components/field";
import { SensitiveInput } from "@workspace/ui/components/sensitive-input";
import { useId, useRef, useState } from "react";
import type { ExampleProps } from "../types";

export default function SensitiveInputControlled({ locale }: ExampleProps) {
  const id = useId();
  const inputRef = useRef<HTMLInputElement>(null);
  const [value, setValue] = useState("example-api-key");
  const [visible, setVisible] = useState(false);
  const [copyMatchesInput, setCopyMatchesInput] = useState<boolean | null>(
    null,
  );
  const [copyFailed, setCopyFailed] = useState(false);
  const [nativeCopyEvents, setNativeCopyEvents] = useState(0);
  const chinese = locale === "zh-CN";
  const stateLabels = chinese
    ? {
        idle: "尚未复制",
        failed: "复制失败，请重试",
        matched: "复制值与当前输入匹配",
        mismatched: "复制值与当前输入不匹配",
      }
    : {
        idle: "Not copied yet",
        failed: "Copy failed. Try again.",
        matched: "Copied value matches the current input.",
        mismatched: "Copied value does not match the current input.",
      };

  let copyFeedback = stateLabels.idle;
  if (copyFailed) copyFeedback = stateLabels.failed;
  else if (copyMatchesInput !== null)
    copyFeedback = copyMatchesInput
      ? stateLabels.matched
      : stateLabels.mismatched;

  return (
    <div className="grid w-full max-w-sm gap-4">
      <Field>
        <FieldLabel htmlFor={id}>{chinese ? "API 密钥" : "API key"}</FieldLabel>
        <SensitiveInput
          ref={inputRef}
          id={id}
          value={value}
          onChange={(event) => {
            setValue(event.target.value);
            setCopyMatchesInput(null);
            setCopyFailed(false);
          }}
          visible={visible}
          onVisibleChange={setVisible}
          onCopy={() => setNativeCopyEvents((count) => count + 1)}
          onCopySuccess={(copiedValue) => {
            setCopyFailed(false);
            setCopyMatchesInput(copiedValue === inputRef.current?.value);
          }}
          onCopyError={() => {
            setCopyFailed(true);
            setCopyMatchesInput(null);
          }}
          resetDelay={1500}
          autoComplete="off"
          aria-describedby={`${id}-description`}
          labels={
            chinese
              ? {
                  reveal: "点击显示",
                  instruction: "点击或按 Enter 显示内容",
                  hidden: "内容已隐藏",
                  show: "显示密钥",
                  hide: "隐藏密钥",
                  copy: "复制密钥",
                  pending: "正在复制密钥…",
                  copied: "已复制密钥",
                  failed: "复制失败，请重试",
                }
              : undefined
          }
        />
        <FieldDescription id={`${id}-description`}>
          {chinese
            ? "点击遮罩或按 Enter 显示。Escape 或离开输入组会请求隐藏；受控 visible 决定最终状态。选中显示的文字后复制，可观察原生 onCopy 事件"
            : "Click the mask or press Enter to reveal. Escape or leaving the group requests hiding; controlled visible remains authoritative. Select revealed text to exercise native onCopy."}
        </FieldDescription>
      </Field>
      <Button type="button" variant="outline" onClick={() => setVisible(false)}>
        {chinese ? "从外部隐藏" : "Hide from outside"}
      </Button>
      <output
        className="grid gap-1 text-muted-foreground text-sm"
        aria-live="polite"
      >
        <span>{copyFeedback}</span>
        <span>
          {chinese
            ? `原生复制事件：${nativeCopyEvents}`
            : `Native copy events: ${nativeCopyEvents}`}
        </span>
      </output>
    </div>
  );
}
```

## Read-only and disabled

`readOnly` prevents editing while keeping pointer and keyboard revealing, hiding, and copying available. `disabled` prohibits input, revealing, hiding, and copying. Set `copyable={false}` to remove only the built-in copy button; revealing, editing, and native input events remain available.

The example also includes an empty field: type into it directly, then move focus outside the group to see its nonempty value become masked.

### Example: sensitive-input-states

```tsx
"use client";

import {
  Field,
  FieldDescription,
  FieldLabel,
} from "@workspace/ui/components/field";
import { SensitiveInput } from "@workspace/ui/components/sensitive-input";
import { useId, useRef, useState } from "react";
import type { ExampleProps } from "../types";

export default function SensitiveInputStates({ locale }: ExampleProps) {
  const id = useId();
  const readOnlyRef = useRef<HTMLInputElement>(null);
  const [copyResult, setCopyResult] = useState<
    "matched" | "mismatched" | "failed" | null
  >(null);
  const chinese = locale === "zh-CN";
  const stateLabels = chinese
    ? {
        idle: "尚未复制",
        failed: "复制失败，请重试",
        matched: "复制值与只读输入匹配",
        mismatched: "复制值与只读输入不匹配",
      }
    : {
        idle: "Not copied yet",
        failed: "Copy failed. Try again.",
        matched: "Copied value matches the read-only input.",
        mismatched: "Copied value does not match the read-only input.",
      };
  const labels = chinese
    ? {
        reveal: "点击显示",
        instruction: "点击或按 Enter 显示内容",
        hidden: "内容已隐藏",
        show: "显示内容",
        hide: "隐藏内容",
        copy: "复制内容",
        pending: "正在复制内容…",
        copied: "已复制内容",
        failed: "复制失败，请重试",
      }
    : undefined;

  return (
    <div className="grid w-full max-w-sm gap-5">
      <Field>
        <FieldLabel htmlFor={`${id}-empty`}>
          {chinese ? "空值" : "Empty value"}
        </FieldLabel>
        <SensitiveInput
          id={`${id}-empty`}
          defaultValue=""
          placeholder={chinese ? "输入内容" : "Enter a value"}
          labels={labels}
        />
        <FieldDescription>
          {chinese
            ? "空值没有遮罩，可直接编辑；首次输入后显示内容，离开控件后重新遮罩。空值也可复制"
            : "An empty value can be edited directly. Typing reveals the value; leaving the group masks it again. Empty values can also be copied."}
        </FieldDescription>
      </Field>
      <Field>
        <FieldLabel htmlFor={`${id}-readonly`}>
          {chinese ? "只读密钥" : "Read-only key"}
        </FieldLabel>
        <SensitiveInput
          ref={readOnlyRef}
          id={`${id}-readonly`}
          defaultValue="read-only-example"
          readOnly
          labels={labels}
          onCopySuccess={(value) =>
            setCopyResult(
              value === readOnlyRef.current?.value ? "matched" : "mismatched",
            )
          }
          onCopyError={() => setCopyResult("failed")}
        />
        <FieldDescription>
          {chinese
            ? "只读内容可以点击或用键盘揭示，也可以复制，但不能编辑"
            : "Read-only values can be revealed by pointer or keyboard and copied, but cannot be edited."}
        </FieldDescription>
        <output className="text-muted-foreground text-sm" aria-live="polite">
          {stateLabels[copyResult ?? "idle"]}
        </output>
      </Field>
      <Field>
        <FieldLabel htmlFor={`${id}-disabled`}>
          {chinese ? "禁用" : "Disabled"}
        </FieldLabel>
        <SensitiveInput
          id={`${id}-disabled`}
          defaultValue="disabled-example"
          disabled
          labels={labels}
        />
        <FieldDescription>
          {chinese
            ? "输入、显隐和复制操作均被禁用"
            : "Input, visibility, and copy actions are disabled."}
        </FieldDescription>
      </Field>
      <Field>
        <FieldLabel htmlFor={`${id}-no-copy`}>
          {chinese ? "不提供复制按钮" : "Without a copy button"}
        </FieldLabel>
        <SensitiveInput
          id={`${id}-no-copy`}
          defaultValue="manual-entry-example"
          copyable={false}
          labels={labels}
        />
        <FieldDescription>
          {chinese
            ? "copyable=false 隐藏内置复制按钮，保留编辑与显隐"
            : "copyable=false hides the built-in copy action while retaining editing and visibility."}
        </FieldDescription>
      </Field>
    </div>
  );
}
```

## Composition and forms

Sensitive Input composes `InputGroup`, `InputGroupInput`, `InputGroupAddon`, and `InputGroupButton`. Use the normal `Field`, `FieldLabel`, and `FieldDescription` components around it; the visible label should reference the input's `id`.

`className` styles the group; `inputClassName` styles the input. A `ref` points to the native input, and native attributes such as `name`, `form`, `required`, `autoComplete`, and `aria-describedby` pass through to it.

The first example is an uncontrolled form with explicit Submit and Reset actions. Copying and toggling visibility leave its submission count unchanged. Submit verifies `FormData` against the current native input without displaying the value; Reset restores `defaultValue` and clears feedback. After editing and copying, reset and copy again: the separate boolean feedback verifies whether the copied value matches the original default. Neither feedback area displays the value. In controlled mode, reset the application-owned value in your form's `onReset` handler.

## Accessibility

Provide a visible associated label or an `aria-label` for the input. The mask has a native reveal button that can be reached with Tab and activated with Enter or Space. Instructions explain how to reveal the value, and a status message announces when it is hidden. The underlying masked input stays mounted for native refs and form data.

The revealed input accepts normal keyboard editing. Escape returns focus to the reveal button; leaving the group requests masking, while internal focus movement preserves the state. Visibility actions reference the input with `aria-controls`, and the eye icon is decorative. The copy button references the same input and reports its pending state with `aria-busy`; copy feedback is announced through a status region.

Localize the visible reveal hint with `labels.reveal`, its keyboard instructions with `labels.instruction`, and the hidden-state announcement with `labels.hidden`. Use `labels.show` and `labels.hide` for action names, and `labels.copy`, `labels.pending`, `labels.copied`, and `labels.failed` for copy feedback. Failure labels should explain a useful next step without including sensitive data.

## API Reference

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `visible` | `boolean` | — | Controlled visibility. |
| `defaultVisible` | `boolean` | `false` | Initial uncontrolled visibility. |
| `onVisibleChange` | `(visible: boolean) => void` | — | Called when pointer, keyboard, first input, or group blur requests a visibility change. |
| `copyable` | `boolean` | `true` | Include the built-in copy action. |
| `onCopySuccess` | `(value: string) => void` | — | Called after the current value is successfully written. |
| `onCopyError` | `(error: Error) => void` | — | Called when the clipboard write fails. |
| `resetDelay` | `number` | `1500` | Successful copy feedback duration in milliseconds. |
| `labels` | `{ reveal?: string; instruction?: string; hidden?: string; show?: string; hide?: string; copy?: string; pending?: string; copied?: string; failed?: string }` | English labels | Reveal hint, keyboard instructions, hidden announcement, action names, and copy feedback. |
| `className` | `string` | — | Additional group classes. |
| `inputClassName` | `string` | — | Additional input classes. |
| `...props` | Native input props, excluding `type` | — | Includes `value`, `defaultValue`, `onChange`, native `onCopy`, `ref`, `disabled`, and `readOnly`. |

The underlying input behavior follows the [Base UI Input API](https://base-ui.com/react/components/input#api-reference).

- [Documentation](https://base-ui.com/react/components/input)
- [API reference](https://base-ui.com/react/components/input#api-reference)


---

# Separator

Visually or semantically separates content.

Page: https://sui.draco.dev/docs/components/separator

### Example: separator-demo

```tsx
import { Separator } from "@workspace/ui/components/separator";

export default function SeparatorDemo() {
  return (
    <div className="flex max-w-sm flex-col gap-4 text-sm">
      <div className="flex flex-col gap-1.5">
        <div className="font-medium leading-none">shadcn/ui</div>
        <div className="text-muted-foreground">
          The Foundation for your Design System
        </div>
      </div>
      <Separator />
      <div>
        A set of beautifully designed components that you can customize, extend,
        and build on.
      </div>
    </div>
  );
}
```

## Installation

```bash
bunx --bun shadcn@latest add @sui/separator
```

Install with the shadcn CLI or use the shared `@workspace/ui` package. Follow the [installation guide](/docs/installation) to configure the registry, load styles, and choose import aliases.

## Usage

```tsx showLineNumbers
import { Separator } from "@workspace/ui/components/separator"
```

```tsx showLineNumbers
<Separator />
```

## Vertical

Use `orientation="vertical"` for a vertical separator.

### Example: separator-vertical

```tsx
import { Separator } from "@workspace/ui/components/separator";

export function SeparatorVertical() {
  return (
    <div className="flex h-5 items-center gap-4 text-sm">
      <div>Blog</div>
      <Separator orientation="vertical" />
      <div>Docs</div>
      <Separator orientation="vertical" />
      <div>Source</div>
    </div>
  );
}

export default SeparatorVertical;
```

## Menu

Vertical separators between menu items with descriptions.

### Example: separator-menu

```tsx
import { Separator } from "@workspace/ui/components/separator";

export function SeparatorMenu() {
  return (
    <div className="flex items-center gap-2 text-sm md:gap-4">
      <div className="flex flex-col gap-1">
        <span className="font-medium">Settings</span>
        <span className="text-muted-foreground text-xs">
          Manage preferences
        </span>
      </div>
      <Separator orientation="vertical" />
      <div className="flex flex-col gap-1">
        <span className="font-medium">Account</span>
        <span className="text-muted-foreground text-xs">
          Profile & security
        </span>
      </div>
      <Separator orientation="vertical" className="hidden md:block" />
      <div className="hidden flex-col gap-1 md:flex">
        <span className="font-medium">Help</span>
        <span className="text-muted-foreground text-xs">Support & docs</span>
      </div>
    </div>
  );
}

export default SeparatorMenu;
```

## List

Horizontal separators between list items.

### Example: separator-list

```tsx
import { Separator } from "@workspace/ui/components/separator";

export function SeparatorList() {
  return (
    <div className="flex w-full max-w-sm flex-col gap-2 text-sm">
      <dl className="flex items-center justify-between">
        <dt>Item 1</dt>
        <dd className="text-muted-foreground">Value 1</dd>
      </dl>
      <Separator />
      <dl className="flex items-center justify-between">
        <dt>Item 2</dt>
        <dd className="text-muted-foreground">Value 2</dd>
      </dl>
      <Separator />
      <dl className="flex items-center justify-between">
        <dt>Item 3</dt>
        <dd className="text-muted-foreground">Value 3</dd>
      </dl>
    </div>
  );
}

export default SeparatorList;
```

## RTL

To enable RTL support in shadcn/ui, see the [RTL configuration guide](https://ui.shadcn.com/docs/rtl).

### Example: separator-rtl

```tsx
"use client";

import { Separator } from "@workspace/ui/components/separator";
import { type Translations, useTranslation } from "./support";

const translations: Translations = {
  en: {
    dir: "ltr",
    values: {
      title: "shadcn/ui",
      subtitle: "The Foundation for your Design System",
      description:
        "A set of beautifully designed components that you can customize, extend, and build on.",
    },
  },
  ar: {
    dir: "rtl",
    values: {
      title: "shadcn/ui",
      subtitle: "الأساس لنظام التصميم الخاص بك",
      description:
        "مجموعة من المكونات المصممة بشكل جميل يمكنك تخصيصها وتوسيعها والبناء عليها.",
    },
  },
  he: {
    dir: "rtl",
    values: {
      title: "shadcn/ui",
      subtitle: "הבסיס למערכת העיצוב שלך",
      description:
        "סט של רכיבים מעוצבים בצורה יפה שאתה יכול להתאים אישית, להרחיב ולבנות עליהם.",
    },
  },
};

export function SeparatorRtl() {
  const { dir, t } = useTranslation(translations, "ar");

  return (
    <div className="flex max-w-sm flex-col gap-4 text-sm" dir={dir}>
      <div className="flex flex-col gap-1.5">
        <div className="font-medium leading-none">{t.title}</div>
        <div className="text-muted-foreground">{t.subtitle}</div>
      </div>
      <Separator />
      <div>{t.description}</div>
    </div>
  );
}

export default SeparatorRtl;
```

## API Reference

See the [Base UI Separator](https://base-ui.com/react/components/separator#api-reference) documentation.

- [Documentation](https://base-ui.com/react/components/separator)
- [API reference](https://base-ui.com/react/components/separator#api-reference)


---

# Sheet

Extends the Dialog component to display content that complements the main content of the screen.

Page: https://sui.draco.dev/docs/components/sheet

### Example: sheet-demo

```tsx
import { Button } from "@workspace/ui/components/button";
import { Input } from "@workspace/ui/components/input";
import { Label } from "@workspace/ui/components/label";
import {
  Sheet,
  SheetClose,
  SheetContent,
  SheetDescription,
  SheetFooter,
  SheetHeader,
  SheetTitle,
  SheetTrigger,
} from "@workspace/ui/components/sheet";
import { useId as usePreviewId } from "react";

export default function SheetDemo() {
  const previewId = usePreviewId();

  return (
    <Sheet>
      <SheetTrigger render={<Button variant="outline" />}>Open</SheetTrigger>
      <SheetContent>
        <SheetHeader>
          <SheetTitle>Edit profile</SheetTitle>
          <SheetDescription>
            Make changes to your profile here. Click save when you&apos;re done.
          </SheetDescription>
        </SheetHeader>
        <div className="grid flex-1 auto-rows-min gap-6 px-4">
          <div className="grid gap-3">
            <Label htmlFor={`${previewId}-sheet-demo-name`}>Name</Label>
            <Input
              id={`${previewId}-sheet-demo-name`}
              defaultValue="Pedro Duarte"
            />
          </div>
          <div className="grid gap-3">
            <Label htmlFor={`${previewId}-sheet-demo-username`}>Username</Label>
            <Input
              id={`${previewId}-sheet-demo-username`}
              defaultValue="@peduarte"
            />
          </div>
        </div>
        <SheetFooter>
          <Button type="submit">Save changes</Button>
          <SheetClose render={<Button variant="outline" />}>Close</SheetClose>
        </SheetFooter>
      </SheetContent>
    </Sheet>
  );
}
```

## Installation

```bash
bunx --bun shadcn@latest add @sui/sheet
```

Install with the shadcn CLI or use the shared `@workspace/ui` package. Follow the [installation guide](/docs/installation) to configure the registry, load styles, and choose import aliases.

## Usage

```tsx showLineNumbers
import {
  Sheet,
  SheetClose,
  SheetContent,
  SheetDescription,
  SheetFooter,
  SheetHeader,
  SheetTitle,
  SheetTrigger,
} from "@workspace/ui/components/sheet"
```

```tsx showLineNumbers
<Sheet>
  <SheetTrigger>Open</SheetTrigger>
  <SheetContent>
    <SheetHeader>
      <SheetTitle>Are you absolutely sure?</SheetTitle>
      <SheetDescription>This action cannot be undone.</SheetDescription>
    </SheetHeader>
  </SheetContent>
</Sheet>
```

## Composition

Use the following composition to build a `Sheet`:

```text
Sheet
├── SheetTrigger
└── SheetContent
    ├── SheetHeader
    │   ├── SheetTitle
    │   └── SheetDescription
    └── SheetFooter
```

## Side

Use the `side` prop on `SheetContent` to set the edge of the screen where the sheet appears. Values are `top`, `right`, `bottom`, or `left`.

### Example: sheet-side

```tsx
// biome-ignore-all lint/suspicious/noArrayIndexKey: The upstream gallery uses fixed positional fixtures that never reorder.

import { Button } from "@workspace/ui/components/button";
import {
  Sheet,
  SheetClose,
  SheetContent,
  SheetDescription,
  SheetFooter,
  SheetHeader,
  SheetTitle,
  SheetTrigger,
} from "@workspace/ui/components/sheet";

const SHEET_SIDES = ["top", "right", "bottom", "left"] as const;

export default function SheetSide() {
  return (
    <div className="flex flex-wrap gap-2">
      {SHEET_SIDES.map((side) => (
        <Sheet key={side}>
          <SheetTrigger
            render={<Button variant="outline" className="capitalize" />}
          >
            {side}
          </SheetTrigger>
          <SheetContent
            side={side}
            className="data-[side=bottom]:max-h-[50vh] data-[side=top]:max-h-[50vh]"
          >
            <SheetHeader>
              <SheetTitle>Edit profile</SheetTitle>
              <SheetDescription>
                Make changes to your profile here. Click save when you&apos;re
                done.
              </SheetDescription>
            </SheetHeader>
            <div className="no-scrollbar overflow-y-auto px-4">
              {Array.from({ length: 10 }).map((_, index) => (
                <p key={index} className="mb-2 leading-relaxed">
                  Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed
                  do eiusmod tempor incididunt ut labore et dolore magna aliqua.
                  Ut enim ad minim veniam, quis nostrud exercitation ullamco
                  laboris nisi ut aliquip ex ea commodo consequat. Duis aute
                  irure dolor in reprehenderit in voluptate velit esse cillum
                  dolore eu fugiat nulla pariatur. Excepteur sint occaecat
                  cupidatat non proident, sunt in culpa qui officia deserunt
                  mollit anim id est laborum.
                </p>
              ))}
            </div>
            <SheetFooter>
              <Button type="submit">Save changes</Button>
              <SheetClose render={<Button variant="outline" />}>
                Cancel
              </SheetClose>
            </SheetFooter>
          </SheetContent>
        </Sheet>
      ))}
    </div>
  );
}
```

## No Close Button

Use `showCloseButton={false}` on `SheetContent` to hide the close button.

### Example: sheet-no-close-button

```tsx
import { Button } from "@workspace/ui/components/button";
import {
  Sheet,
  SheetContent,
  SheetDescription,
  SheetHeader,
  SheetTitle,
  SheetTrigger,
} from "@workspace/ui/components/sheet";

export default function SheetNoCloseButton() {
  return (
    <Sheet>
      <SheetTrigger render={<Button variant="outline" />}>
        Open Sheet
      </SheetTrigger>
      <SheetContent showCloseButton={false}>
        <SheetHeader>
          <SheetTitle>No Close Button</SheetTitle>
          <SheetDescription>
            This sheet doesn&apos;t have a close button in the top-right corner.
            Click outside to close.
          </SheetDescription>
        </SheetHeader>
      </SheetContent>
    </Sheet>
  );
}
```

## RTL

To enable RTL support in shadcn/ui, see the [RTL configuration guide](https://ui.shadcn.com/docs/rtl).

### Example: sheet-rtl

```tsx
"use client";

import { Button } from "@workspace/ui/components/button";
import { Field, FieldGroup, FieldLabel } from "@workspace/ui/components/field";
import { Input } from "@workspace/ui/components/input";
import {
  Sheet,
  SheetClose,
  SheetContent,
  SheetDescription,
  SheetFooter,
  SheetHeader,
  SheetTitle,
  SheetTrigger,
} from "@workspace/ui/components/sheet";
import { useId as usePreviewId } from "react";
import { type Translations, useTranslation } from "./support";

const translations: Translations = {
  en: {
    dir: "ltr",
    values: {
      open: "Open",
      editProfile: "Edit profile",
      description:
        "Make changes to your profile here. Click save when you're done.",
      name: "Name",
      username: "Username",
      save: "Save changes",
      close: "Close",
    },
  },
  ar: {
    dir: "rtl",
    values: {
      open: "فتح",
      editProfile: "تعديل الملف الشخصي",
      description:
        "قم بإجراء تغييرات على ملفك الشخصي هنا. انقر حفظ عند الانتهاء.",
      name: "الاسم",
      username: "اسم المستخدم",
      save: "حفظ التغييرات",
      close: "إغلاق",
    },
  },
  he: {
    dir: "rtl",
    values: {
      open: "פתח",
      editProfile: "עריכת פרופיל",
      description: "בצע שינויים בפרופיל שלך כאן. לחץ שמור כשתסיים.",
      name: "שם",
      username: "שם משתמש",
      save: "שמור שינויים",
      close: "סגור",
    },
  },
};

export function SheetRtl() {
  const previewId = usePreviewId();

  const { dir, t, language } = useTranslation(translations, "ar");

  return (
    <Sheet>
      <SheetTrigger render={<Button variant="outline" />}>
        {t.open}
      </SheetTrigger>
      <SheetContent
        dir={dir}
        side={dir === "rtl" ? "left" : "right"}
        data-lang={dir === "rtl" ? language : undefined}
      >
        <SheetHeader>
          <SheetTitle>{t.editProfile}</SheetTitle>
          <SheetDescription>{t.description}</SheetDescription>
        </SheetHeader>
        <FieldGroup className="px-4">
          <Field>
            <FieldLabel htmlFor={`${previewId}-sheet-rtl-name`}>
              {t.name}
            </FieldLabel>
            <Input
              id={`${previewId}-sheet-rtl-name`}
              defaultValue="Pedro Duarte"
            />
          </Field>
          <Field>
            <FieldLabel htmlFor={`${previewId}-sheet-rtl-username`}>
              {t.username}
            </FieldLabel>
            <Input
              id={`${previewId}-sheet-rtl-username`}
              defaultValue="peduarte"
            />
          </Field>
        </FieldGroup>
        <SheetFooter>
          <Button type="submit">{t.save}</Button>
          <SheetClose render={<Button variant="outline" />}>
            {t.close}
          </SheetClose>
        </SheetFooter>
      </SheetContent>
    </Sheet>
  );
}

export default SheetRtl;
```

## API Reference

See the [Base UI Dialog](https://base-ui.com/react/components/dialog#api-reference) documentation.

- [Documentation](https://base-ui.com/react/components/dialog)
- [API reference](https://base-ui.com/react/components/dialog#api-reference)


---

# Sidebar

A composable, themeable and customizable sidebar component.

Page: https://sui.draco.dev/docs/components/sidebar

### Example: sidebar-demo

```tsx
"use client";

import {
  Avatar,
  AvatarFallback,
  AvatarImage,
} from "@workspace/ui/components/avatar";
import {
  Collapsible,
  CollapsibleContent,
  CollapsibleTrigger,
} from "@workspace/ui/components/collapsible";
import {
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuGroup,
  DropdownMenuItem,
  DropdownMenuLabel,
  DropdownMenuSeparator,
  DropdownMenuShortcut,
  DropdownMenuTrigger,
} from "@workspace/ui/components/dropdown-menu";
import {
  Sidebar,
  SidebarContent,
  SidebarFooter,
  SidebarGroup,
  SidebarGroupLabel,
  SidebarHeader,
  SidebarInset,
  SidebarMenu,
  SidebarMenuAction,
  SidebarMenuButton,
  SidebarMenuItem,
  SidebarMenuSub,
  SidebarMenuSubButton,
  SidebarMenuSubItem,
  SidebarProvider,
  SidebarRail,
  SidebarTrigger,
  useSidebar,
} from "@workspace/ui/components/sidebar";
import {
  AudioWaveform,
  BadgeCheck,
  Bell,
  BookOpen,
  Bot,
  ChevronRight,
  ChevronsUpDown,
  Command,
  CreditCard,
  Folder,
  Forward,
  Frame,
  GalleryVerticalEnd,
  LogOut,
  Map as MapIcon,
  MoreHorizontal,
  PieChart,
  Plus,
  Settings2,
  Sparkles,
  SquareTerminal,
  Trash2,
} from "lucide-react";
import * as React from "react";

// This is sample data.
const data = {
  user: {
    name: "shadcn",
    email: "m@example.com",
    avatar: "/avatars/shadcn.jpg",
  },
  teams: [
    {
      name: "Acme Inc",
      logo: GalleryVerticalEnd,
      plan: "Enterprise",
    },
    {
      name: "Acme Corp.",
      logo: AudioWaveform,
      plan: "Startup",
    },
    {
      name: "Evil Corp.",
      logo: Command,
      plan: "Free",
    },
  ],
  navMain: [
    {
      title: "Playground",
      url: "#",
      icon: SquareTerminal,
      isActive: true,
      items: [
        {
          title: "History",
          url: "#",
        },
        {
          title: "Starred",
          url: "#",
        },
        {
          title: "Settings",
          url: "#",
        },
      ],
    },
    {
      title: "Models",
      url: "#",
      icon: Bot,
      items: [
        {
          title: "Genesis",
          url: "#",
        },
        {
          title: "Explorer",
          url: "#",
        },
        {
          title: "Quantum",
          url: "#",
        },
      ],
    },
    {
      title: "Documentation",
      url: "#",
      icon: BookOpen,
      items: [
        {
          title: "Introduction",
          url: "#",
        },
        {
          title: "Get Started",
          url: "#",
        },
        {
          title: "Tutorials",
          url: "#",
        },
        {
          title: "Changelog",
          url: "#",
        },
      ],
    },
    {
      title: "Settings",
      url: "#",
      icon: Settings2,
      items: [
        {
          title: "General",
          url: "#",
        },
        {
          title: "Team",
          url: "#",
        },
        {
          title: "Billing",
          url: "#",
        },
        {
          title: "Limits",
          url: "#",
        },
      ],
    },
  ],
  projects: [
    {
      name: "Design Engineering",
      url: "#",
      icon: Frame,
    },
    {
      name: "Sales & Marketing",
      url: "#",
      icon: PieChart,
    },
    {
      name: "Travel",
      url: "#",
      icon: MapIcon,
    },
  ],
};

function TeamSwitcher({
  teams,
}: {
  teams: {
    name: string;
    logo: React.ElementType;
    plan: string;
  }[];
}) {
  const { isMobile } = useSidebar();
  const [activeTeam, setActiveTeam] = React.useState(teams[0]);

  if (!activeTeam) {
    return null;
  }

  return (
    <SidebarMenu>
      <SidebarMenuItem>
        <DropdownMenu>
          <DropdownMenuTrigger
            render={
              <SidebarMenuButton
                size="lg"
                className="data-[state=open]:bg-sidebar-accent data-[state=open]:text-sidebar-accent-foreground"
              />
            }
          >
            <div className="flex aspect-square size-8 items-center justify-center rounded-lg bg-sidebar-primary text-sidebar-primary-foreground">
              <activeTeam.logo className="size-4" />
            </div>
            <div className="grid flex-1 text-left text-sm leading-tight">
              <span className="truncate font-medium">{activeTeam.name}</span>
              <span className="truncate text-xs">{activeTeam.plan}</span>
            </div>
            <ChevronsUpDown className="ml-auto" />
          </DropdownMenuTrigger>
          <DropdownMenuContent
            className="w-(--radix-dropdown-menu-trigger-width) min-w-56 rounded-lg"
            align="start"
            side={isMobile ? "bottom" : "right"}
            sideOffset={4}
          >
            <DropdownMenuGroup>
              <DropdownMenuLabel className="text-muted-foreground text-xs">
                Teams
              </DropdownMenuLabel>
              {teams.map((team, index) => (
                <DropdownMenuItem
                  key={team.name}
                  onClick={() => setActiveTeam(team)}
                  className="gap-2 p-2"
                >
                  <div className="flex size-6 items-center justify-center rounded-md border">
                    <team.logo className="size-3.5 shrink-0" />
                  </div>
                  {team.name}
                  <DropdownMenuShortcut>⌘{index + 1}</DropdownMenuShortcut>
                </DropdownMenuItem>
              ))}
            </DropdownMenuGroup>
            <DropdownMenuSeparator />
            <DropdownMenuGroup>
              <DropdownMenuItem className="gap-2 p-2">
                <div className="flex size-6 items-center justify-center rounded-md border bg-transparent">
                  <Plus className="size-4" />
                </div>
                <div className="font-medium text-muted-foreground">
                  Add team
                </div>
              </DropdownMenuItem>
            </DropdownMenuGroup>
          </DropdownMenuContent>
        </DropdownMenu>
      </SidebarMenuItem>
    </SidebarMenu>
  );
}

function NavMain({
  items,
}: {
  items: {
    title: string;
    url: string;
    icon?: React.ElementType;
    isActive?: boolean;
    items?: {
      title: string;
      url: string;
    }[];
  }[];
}) {
  return (
    <SidebarGroup>
      <SidebarGroupLabel>Platform</SidebarGroupLabel>
      <SidebarMenu>
        {items.map((item) => (
          <Collapsible
            key={item.title}
            defaultOpen={item.isActive}
            className="group/collapsible"
          >
            <SidebarMenuItem>
              <CollapsibleTrigger
                render={<SidebarMenuButton tooltip={item.title} />}
              >
                {item.icon && <item.icon />}
                <span>{item.title}</span>
                <ChevronRight className="ml-auto transition-transform duration-200 group-data-[state=open]/collapsible:rotate-90" />
              </CollapsibleTrigger>
              <CollapsibleContent>
                <SidebarMenuSub>
                  {item.items?.map((subItem) => (
                    <SidebarMenuSubItem key={subItem.title}>
                      <SidebarMenuSubButton render={<a href={subItem.url} />}>
                        <span>{subItem.title}</span>
                      </SidebarMenuSubButton>
                    </SidebarMenuSubItem>
                  ))}
                </SidebarMenuSub>
              </CollapsibleContent>
            </SidebarMenuItem>
          </Collapsible>
        ))}
      </SidebarMenu>
    </SidebarGroup>
  );
}

function NavProjects({
  projects,
}: {
  projects: {
    name: string;
    url: string;
    icon: React.ElementType;
  }[];
}) {
  const { isMobile } = useSidebar();

  return (
    <SidebarGroup className="group-data-[collapsible=icon]:hidden">
      <SidebarGroupLabel>Projects</SidebarGroupLabel>
      <SidebarMenu>
        {projects.map((item) => (
          <SidebarMenuItem key={item.name}>
            <SidebarMenuButton render={<a href={item.url} />}>
              <item.icon />
              <span>{item.name}</span>
            </SidebarMenuButton>
            <DropdownMenu>
              <DropdownMenuTrigger render={<SidebarMenuAction showOnHover />}>
                <MoreHorizontal />
                <span className="sr-only">More</span>
              </DropdownMenuTrigger>
              <DropdownMenuContent
                className="w-48 rounded-lg"
                side={isMobile ? "bottom" : "right"}
                align={isMobile ? "end" : "start"}
              >
                <DropdownMenuItem>
                  <Folder className="text-muted-foreground" />
                  <span>View Project</span>
                </DropdownMenuItem>
                <DropdownMenuItem>
                  <Forward className="text-muted-foreground" />
                  <span>Share Project</span>
                </DropdownMenuItem>
                <DropdownMenuSeparator />
                <DropdownMenuItem>
                  <Trash2 className="text-muted-foreground" />
                  <span>Delete Project</span>
                </DropdownMenuItem>
              </DropdownMenuContent>
            </DropdownMenu>
          </SidebarMenuItem>
        ))}
        <SidebarMenuItem>
          <SidebarMenuButton className="text-sidebar-foreground/70">
            <MoreHorizontal className="text-sidebar-foreground/70" />
            <span>More</span>
          </SidebarMenuButton>
        </SidebarMenuItem>
      </SidebarMenu>
    </SidebarGroup>
  );
}

function NavUser({
  user,
}: {
  user: {
    name: string;
    email: string;
    avatar: string;
  };
}) {
  const { isMobile } = useSidebar();

  return (
    <SidebarMenu>
      <SidebarMenuItem>
        <DropdownMenu>
          <DropdownMenuTrigger
            render={
              <SidebarMenuButton
                size="lg"
                className="data-[state=open]:bg-sidebar-accent data-[state=open]:text-sidebar-accent-foreground"
              />
            }
          >
            <Avatar className="h-8 w-8 rounded-lg">
              <AvatarImage src={user.avatar} alt={user.name} />
              <AvatarFallback className="rounded-lg">CN</AvatarFallback>
            </Avatar>
            <div className="grid flex-1 text-left text-sm leading-tight">
              <span className="truncate font-medium">{user.name}</span>
              <span className="truncate text-xs">{user.email}</span>
            </div>
            <ChevronsUpDown className="ml-auto size-4" />
          </DropdownMenuTrigger>
          <DropdownMenuContent
            className="w-(--radix-dropdown-menu-trigger-width) min-w-56 rounded-lg"
            side={isMobile ? "bottom" : "right"}
            align="end"
            sideOffset={4}
          >
            <DropdownMenuGroup>
              <DropdownMenuLabel className="p-0 font-normal">
                <div className="flex items-center gap-2 px-1 py-1.5 text-left text-sm">
                  <Avatar className="h-8 w-8 rounded-lg">
                    <AvatarImage src={user.avatar} alt={user.name} />
                    <AvatarFallback className="rounded-lg">CN</AvatarFallback>
                  </Avatar>
                  <div className="grid flex-1 text-left text-sm leading-tight">
                    <span className="truncate font-medium">{user.name}</span>
                    <span className="truncate text-xs">{user.email}</span>
                  </div>
                </div>
              </DropdownMenuLabel>
            </DropdownMenuGroup>
            <DropdownMenuSeparator />
            <DropdownMenuGroup>
              <DropdownMenuItem>
                <Sparkles />
                Upgrade to Pro
              </DropdownMenuItem>
            </DropdownMenuGroup>
            <DropdownMenuSeparator />
            <DropdownMenuGroup>
              <DropdownMenuItem>
                <BadgeCheck />
                Account
              </DropdownMenuItem>
              <DropdownMenuItem>
                <CreditCard />
                Billing
              </DropdownMenuItem>
              <DropdownMenuItem>
                <Bell />
                Notifications
              </DropdownMenuItem>
            </DropdownMenuGroup>
            <DropdownMenuSeparator />
            <DropdownMenuGroup>
              <DropdownMenuItem>
                <LogOut />
                Log out
              </DropdownMenuItem>
            </DropdownMenuGroup>
          </DropdownMenuContent>
        </DropdownMenu>
      </SidebarMenuItem>
    </SidebarMenu>
  );
}

function AppSidebar({ ...props }: React.ComponentProps<typeof Sidebar>) {
  return (
    <SidebarProvider className="relative isolate h-96 min-h-0 w-full overflow-hidden rounded-xl border">
      <Sidebar
        collapsible="icon"
        className="absolute! inset-y-0! h-full!"
        {...props}
      >
        <SidebarHeader>
          <TeamSwitcher teams={data.teams} />
        </SidebarHeader>
        <SidebarContent>
          <NavMain items={data.navMain} />
          <NavProjects projects={data.projects} />
        </SidebarContent>
        <SidebarFooter>
          <NavUser user={data.user} />
        </SidebarFooter>
        <SidebarRail />
      </Sidebar>
      <SidebarInset>
        <header className="flex h-16 shrink-0 items-center gap-2 transition-[width,height] ease-linear group-has-data-[collapsible=icon]/sidebar-wrapper:h-12">
          <div className="flex items-center gap-2 px-4">
            <SidebarTrigger className="-ml-1" />
          </div>
        </header>
      </SidebarInset>
    </SidebarProvider>
  );
}

export default function Preview() {
  return <AppSidebar />;
}
```

  

    A sidebar that collapses to icons.
  

Sidebars are one of the most complex components to build. They are central
to any application and often contain a lot of moving parts.

We now have a solid foundation to build on top of. Composable. Themeable.
Customizable.

[Browse the Blocks Library](https://ui.shadcn.com/blocks).

## Installation

```bash
bunx --bun shadcn@latest add @sui/sidebar
```

Install with the shadcn CLI or use the shared `@workspace/ui` package. Follow the [installation guide](/docs/installation) to configure the registry, load styles, and choose import aliases.

## Usage

```tsx showLineNumbers title="app/layout.tsx"
import { SidebarProvider, SidebarTrigger } from "@workspace/ui/components/sidebar"
import { AppSidebar } from "@/components/app-sidebar"

export default function Layout({ children }: { children: React.ReactNode }) {
  return (
    <SidebarProvider>
      <AppSidebar />
      <main>
        <SidebarTrigger />
        {children}
      </main>
    </SidebarProvider>
  )
}
```

```tsx showLineNumbers title="components/app-sidebar.tsx"
import {
  Sidebar,
  SidebarContent,
  SidebarFooter,
  SidebarGroup,
  SidebarHeader,
} from "@workspace/ui/components/sidebar"

export function AppSidebar() {
  return (
    <Sidebar>
      <SidebarHeader />
      <SidebarContent>
        <SidebarGroup />
        <SidebarGroup />
      </SidebarContent>
      <SidebarFooter />
    </Sidebar>
  )
}
```

## Composition

Use the following composition to build a `Sidebar` layout:

```text
SidebarProvider
├── Sidebar
│   ├── SidebarHeader
│   ├── SidebarContent
│   │   ├── SidebarGroup
│   │   │   ├── SidebarGroupLabel
│   │   │   ├── SidebarGroupAction
│   │   │   ├── SidebarGroupContent
│   │   │   └── SidebarMenu
│   │   │       ├── SidebarMenuItem
│   │   │       │   ├── SidebarMenuButton
│   │   │       │   ├── SidebarMenuAction
│   │   │       │   └── SidebarMenuBadge
│   │   │       └── SidebarMenuItem
│   │   │           ├── SidebarMenuButton
│   │   │           └── SidebarMenuSub
│   │   │               ├── SidebarMenuSubItem
│   │   │               └── SidebarMenuSubItem
│   │   └── SidebarGroup
│   │       └── SidebarMenu
│   │           ├── SidebarMenuItem
│   │           └── SidebarMenuItem
│   ├── SidebarFooter
│   └── SidebarRail
├── SidebarInset
└── SidebarTrigger
```

## Structure

- **SidebarProvider** — Handles collapsible state and provides sidebar context to child components.
- **Sidebar** — The main collapsible sidebar panel.
- **SidebarHeader** — Sticky at the top; use for branding, titles, or workspace switchers.
- **SidebarFooter** — Sticky at the bottom; use for user menus, settings, or actions.
- **SidebarContent** — Scrollable region between the header and footer.
- **SidebarGroup** — Groups related navigation with optional label, action, and content areas.
- **SidebarMenu** / **SidebarMenuItem** — Menu structure for links, badges, actions, and nested submenus.
- **SidebarRail** — Resize handle for adjusting sidebar width when applicable.
- **SidebarInset** — Wraps main content when using the `inset` variant.
- **SidebarTrigger** — Control that toggles the sidebar open or collapsed.

![Sidebar Structure](https://ui.shadcn.com/images/sidebar-structure.png)
![Sidebar Structure](https://ui.shadcn.com/images/sidebar-structure-dark.png)

## SidebarProvider

The `SidebarProvider` component is used to provide the sidebar context to the `Sidebar` component. You should always wrap your application in a `SidebarProvider` component.

### Props

| Name           | Type                      | Description                                  |
| -------------- | ------------------------- | -------------------------------------------- |
| `defaultOpen`  | `boolean`                 | Default open state of the sidebar.           |
| `open`         | `boolean`                 | Open state of the sidebar (controlled).      |
| `onOpenChange` | `(open: boolean) => void` | Sets open state of the sidebar (controlled). |

### Width

If you have a single sidebar in your application, you can use the `SIDEBAR_WIDTH` and `SIDEBAR_WIDTH_MOBILE` variables in `sidebar.tsx` to set the width of the sidebar.

```tsx showLineNumbers title="packages/ui/src/components/sidebar.tsx"
const SIDEBAR_WIDTH = "16rem"
const SIDEBAR_WIDTH_MOBILE = "18rem"
```

For multiple sidebars in your application, you can use the `--sidebar-width` and `--sidebar-width-mobile` CSS variables in the `style` prop.

```tsx showLineNumbers
<SidebarProvider
  style={
    {
      "--sidebar-width": "20rem",
      "--sidebar-width-mobile": "20rem",
    } as React.CSSProperties
  }
>
  <Sidebar />
</SidebarProvider>
```

### Keyboard Shortcut

To trigger the sidebar, you use the `cmd+b` keyboard shortcut on Mac and `ctrl+b` on Windows.

```tsx showLineNumbers title="packages/ui/src/components/sidebar.tsx"
const SIDEBAR_KEYBOARD_SHORTCUT = "b"
```

## Sidebar

The main `Sidebar` component used to render a collapsible sidebar.

### Props

| Property      | Type                              | Description                       |
| ------------- | --------------------------------- | --------------------------------- |
| `side`        | `left` or `right`                 | The side of the sidebar.          |
| `variant`     | `sidebar`, `floating`, or `inset` | The variant of the sidebar.       |
| `collapsible` | `offcanvas`, `icon`, or `none`    | Collapsible state of the sidebar. |

| Prop        | Description                                                  |
| ----------- | ------------------------------------------------------------ |
| `offcanvas` | A collapsible sidebar that slides in from the left or right. |
| `icon`      | A sidebar that collapses to icons.                           |
| `none`      | A non-collapsible sidebar.                                   |

  **Note:** If you use the `inset` variant, remember to wrap your main content
  in a `SidebarInset` component.

```tsx showLineNumbers
<SidebarProvider>
  <Sidebar variant="inset" />
  <SidebarInset>
    <main>{children}</main>
  </SidebarInset>
</SidebarProvider>
```

## useSidebar

The `useSidebar` hook is used to control the sidebar.

```tsx showLineNumbers
import { useSidebar } from "@workspace/ui/components/sidebar"

export function AppSidebar() {
  const {
    state,
    open,
    setOpen,
    openMobile,
    setOpenMobile,
    isMobile,
    toggleSidebar,
  } = useSidebar()
}
```

| Property        | Type                      | Description                                   |
| --------------- | ------------------------- | --------------------------------------------- |
| `state`         | `expanded` or `collapsed` | The current state of the sidebar.             |
| `open`          | `boolean`                 | Whether the sidebar is open.                  |
| `setOpen`       | `(open: boolean) => void` | Sets the open state of the sidebar.           |
| `openMobile`    | `boolean`                 | Whether the sidebar is open on mobile.        |
| `setOpenMobile` | `(open: boolean) => void` | Sets the open state of the sidebar on mobile. |
| `isMobile`      | `boolean`                 | Whether the sidebar is on mobile.             |
| `toggleSidebar` | `() => void`              | Toggles the sidebar. Desktop and mobile.      |

## SidebarHeader

Use the `SidebarHeader` component to add a sticky header to the sidebar.

```tsx showLineNumbers title="components/app-sidebar.tsx"
<Sidebar>
  <SidebarHeader>
    <SidebarMenu>
      <SidebarMenuItem>
        <DropdownMenu>
          <DropdownMenuTrigger render={<SidebarMenuButton />}>
            Select Workspace
            <ChevronDown className="ml-auto" />
          </DropdownMenuTrigger>
          <DropdownMenuContent>
            <DropdownMenuItem>
              <span>Acme Inc</span>
            </DropdownMenuItem>
          </DropdownMenuContent>
        </DropdownMenu>
      </SidebarMenuItem>
    </SidebarMenu>
  </SidebarHeader>
</Sidebar>
```

## SidebarFooter

Use the `SidebarFooter` component to add a sticky footer to the sidebar.

```tsx showLineNumbers
<Sidebar>
  <SidebarFooter>
    <SidebarMenu>
      <SidebarMenuItem>
        <SidebarMenuButton>
          <User2 /> Username
        </SidebarMenuButton>
      </SidebarMenuItem>
    </SidebarMenu>
  </SidebarFooter>
</Sidebar>
```

## SidebarContent

The `SidebarContent` component is used to wrap the content of the sidebar. This is where you add your `SidebarGroup` components. It is scrollable.

```tsx showLineNumbers
<Sidebar>
  <SidebarContent>
    <SidebarGroup />
    <SidebarGroup />
  </SidebarContent>
</Sidebar>
```

## SidebarGroup

Use the `SidebarGroup` component to create a section within the sidebar.

A `SidebarGroup` has a `SidebarGroupLabel`, a `SidebarGroupContent` and an optional `SidebarGroupAction`.

```tsx showLineNumbers
<SidebarGroup>
  <SidebarGroupLabel>Application</SidebarGroupLabel>
  <SidebarGroupAction>
    <Plus /> <span className="sr-only">Add Project</span>
  </SidebarGroupAction>
  <SidebarGroupContent></SidebarGroupContent>
</SidebarGroup>
```

To make a `SidebarGroup` collapsible, wrap it in a `Collapsible`.

```tsx showLineNumbers
<Collapsible defaultOpen className="group/collapsible">
  <SidebarGroup>
    <SidebarGroupLabel render={<CollapsibleTrigger />}>
      Help
      <ChevronDown className="ml-auto transition-transform group-data-open/collapsible:rotate-180" />
    </SidebarGroupLabel>
    <CollapsibleContent>
      <SidebarGroupContent />
    </CollapsibleContent>
  </SidebarGroup>
</Collapsible>
```

## SidebarMenu

The `SidebarMenu` component is used for building a menu within a `SidebarGroup`.

![Sidebar Menu](https://ui.shadcn.com/images/sidebar-menu.png)
![Sidebar Menu](https://ui.shadcn.com/images/sidebar-menu-dark.png)

```tsx showLineNumbers
<SidebarMenu>
  {projects.map((project) => (
    <SidebarMenuItem key={project.name}>
      <SidebarMenuButton render={<a href={project.url} />}>
        <project.icon />
        <span>{project.name}</span>
      </SidebarMenuButton>
    </SidebarMenuItem>
  ))}
</SidebarMenu>
```

## SidebarMenuButton

The `SidebarMenuButton` component is used to render a menu button within a `SidebarMenuItem`.

By default, the `SidebarMenuButton` renders a button but you can use the `render` prop to render a different component such as a `Link` or an `a` tag.

Use the `isActive` prop to mark a menu item as active.

```tsx showLineNumbers
<SidebarMenuButton render={<a href="#" />} isActive>
  Home
</SidebarMenuButton>
```

## SidebarMenuAction

The `SidebarMenuAction` component is used to render a menu action within a `SidebarMenuItem`.

```tsx showLineNumbers
<SidebarMenuItem>
  <SidebarMenuButton render={<a href="#" />}>
    <Home />
    <span>Home</span>
  </SidebarMenuButton>
  <SidebarMenuAction>
    <Plus /> <span className="sr-only">Add Project</span>
  </SidebarMenuAction>
</SidebarMenuItem>
```

## SidebarMenuSub

The `SidebarMenuSub` component is used to render a submenu within a `SidebarMenu`.

```tsx showLineNumbers
<SidebarMenuItem>
  <SidebarMenuButton />
  <SidebarMenuSub>
    <SidebarMenuSubItem>
      <SidebarMenuSubButton />
    </SidebarMenuSubItem>
  </SidebarMenuSub>
</SidebarMenuItem>
```

## SidebarMenuBadge

The `SidebarMenuBadge` component is used to render a badge within a `SidebarMenuItem`.

```tsx showLineNumbers
<SidebarMenuItem>
  <SidebarMenuButton />
  <SidebarMenuBadge>24</SidebarMenuBadge>
</SidebarMenuItem>
```

## SidebarMenuSkeleton

The `SidebarMenuSkeleton` component is used to render a skeleton for a `SidebarMenu`.

```tsx showLineNumbers
<SidebarMenu>
  {Array.from({ length: 5 }).map((_, index) => (
    <SidebarMenuItem key={index}>
      <SidebarMenuSkeleton />
    </SidebarMenuItem>
  ))}
</SidebarMenu>
```

## SidebarTrigger

Use the `SidebarTrigger` component to render a button that toggles the sidebar.

```tsx showLineNumbers
import { useSidebar } from "@workspace/ui/components/sidebar"

export function CustomTrigger() {
  const { toggleSidebar } = useSidebar()

  return <button onClick={toggleSidebar}>Toggle Sidebar</button>
}
```

## SidebarRail

The `SidebarRail` component is used to render a rail within a `Sidebar`. This rail can be used to toggle the sidebar.

```tsx showLineNumbers
<Sidebar>
  <SidebarHeader />
  <SidebarContent>
    <SidebarGroup />
  </SidebarContent>
  <SidebarFooter />
  <SidebarRail />
</Sidebar>
```

## Controlled Sidebar

Use the `open` and `onOpenChange` props to control the sidebar.

```tsx showLineNumbers
export function AppSidebar() {
  const [open, setOpen] = React.useState(false)

  return (
    <SidebarProvider open={open} onOpenChange={setOpen}>
      <Sidebar />
    </SidebarProvider>
  )
}
```

## Theming

We use the following CSS variables to theme the sidebar.

```css
@layer base {
  :root {
    --sidebar-background: 0 0% 98%;
    --sidebar-foreground: 240 5.3% 26.1%;
    --sidebar-primary: 240 5.9% 10%;
    --sidebar-primary-foreground: 0 0% 98%;
    --sidebar-accent: 240 4.8% 95.9%;
    --sidebar-accent-foreground: 240 5.9% 10%;
    --sidebar-border: 220 13% 91%;
    --sidebar-ring: 217.2 91.2% 59.8%;
  }

  .dark {
    --sidebar-background: 240 5.9% 10%;
    --sidebar-foreground: 240 4.8% 95.9%;
    --sidebar-primary: 0 0% 98%;
    --sidebar-primary-foreground: 240 5.9% 10%;
    --sidebar-accent: 240 3.7% 15.9%;
    --sidebar-accent-foreground: 240 4.8% 95.9%;
    --sidebar-border: 240 3.7% 15.9%;
    --sidebar-ring: 217.2 91.2% 59.8%;
  }
}
```

## Styling

Here are some tips for styling the sidebar based on different states.

```tsx
<Sidebar collapsible="icon">
  <SidebarContent>
    <SidebarGroup className="group-data-[collapsible=icon]:hidden" />
  </SidebarContent>
</Sidebar>
```

```tsx
<SidebarMenuItem>
  <SidebarMenuButton />
  <SidebarMenuAction className="peer-data-[active=true]/menu-button:opacity-100" />
</SidebarMenuItem>
```

## RTL

To enable RTL support in shadcn/ui, see the [RTL configuration guide](https://ui.shadcn.com/docs/rtl).

[View RTL Sidebar ↗](https://ui.shadcn.com/view/base-nova/sidebar-rtl)

## Changelog

### RTL Support

If you're upgrading from a previous version of the `Sidebar` component, you'll need to apply the following updates to add RTL support:

### Add `dir` prop to Sidebar component.

Add `dir` to the destructured props and pass it to `SheetContent` for mobile:

```diff
  function Sidebar({
    side = "left",
    variant = "sidebar",
    collapsible = "offcanvas",
    className,
    children,
+   dir,
    ...props
  }: React.ComponentProps<"div"> & {
    side?: "left" | "right"
    variant?: "sidebar" | "floating" | "inset"
    collapsible?: "offcanvas" | "icon" | "none"
  }) {
```

Then pass it to `SheetContent` in the mobile view:

```diff
  <Sheet open={openMobile} onOpenChange={setOpenMobile} {...props}>
    <SheetContent
+     dir={dir}
      data-sidebar="sidebar"
      data-slot="sidebar"
      data-mobile="true"
```

### Add `data-side` attribute to sidebar container.

Add `data-side={side}` to the sidebar container element:

```diff
  <div
    data-slot="sidebar-container"
+   data-side={side}
    className={cn(
```

### Update sidebar container positioning classes.

Replace JavaScript ternary conditional classes with CSS data attribute selectors:

```diff
  className={cn(
-   "fixed inset-y-0 z-10 hidden h-svh w-(--sidebar-width) transition-[left,right,width] duration-200 ease-linear md:flex",
-   side === "left"
-     ? "left-0 group-data-[collapsible=offcanvas]:left-[calc(var(--sidebar-width)*-1)]"
-     : "right-0 group-data-[collapsible=offcanvas]:right-[calc(var(--sidebar-width)*-1)]",
+   "fixed inset-y-0 z-10 hidden h-svh w-(--sidebar-width) transition-[left,right,width] duration-200 ease-linear md:flex data-[side=left]:left-0 data-[side=right]:right-0 data-[side=left]:group-data-[collapsible=offcanvas]:left-[calc(var(--sidebar-width)*-1)] data-[side=right]:group-data-[collapsible=offcanvas]:right-[calc(var(--sidebar-width)*-1)]",
```

### Update SidebarRail positioning classes.

Update the `SidebarRail` component to use physical positioning for the rail:

```diff
  className={cn(
-   "hover:after:bg-sidebar-border absolute inset-y-0 z-20 hidden w-4 -translate-x-1/2 transition-all ease-linear group-data-[side=left]:-end-4 group-data-[side=right]:start-0 after:absolute after:inset-y-0 after:start-1/2 after:w-[2px] sm:flex",
+   "hover:after:bg-sidebar-border absolute inset-y-0 z-20 hidden w-4 ltr:-translate-x-1/2 rtl:-translate-x-1/2 transition-all ease-linear group-data-[side=left]:-right-4 group-data-[side=right]:left-0 after:absolute after:inset-y-0 after:start-1/2 after:w-[2px] sm:flex",
```

### Add RTL flip to SidebarTrigger icon.

Add `className="rtl:rotate-180"` to the icon in `SidebarTrigger` to flip it in RTL mode:

```diff
  <Button ...>
-   <PanelLeftIcon />
+   <PanelLeftIcon className="rtl:rotate-180" />
    <span className="sr-only">Toggle Sidebar</span>
  </Button>
```

After applying these changes, you can use the `dir` prop to set the direction:

```tsx
<Sidebar dir="rtl" side="right">
  {/* ... */}
</Sidebar>
```

The sidebar will correctly position itself and handle interactions in both LTR and RTL layouts.


---

# Skeleton

Use to show a placeholder while content is loading.

Page: https://sui.draco.dev/docs/components/skeleton

### Example: skeleton-demo

```tsx
import { Skeleton } from "@workspace/ui/components/skeleton";

export function SkeletonDemo() {
  return (
    <div className="flex items-center gap-4">
      <Skeleton className="h-12 w-12 rounded-full" />
      <div className="space-y-2">
        <Skeleton className="h-4 w-[250px]" />
        <Skeleton className="h-4 w-[200px]" />
      </div>
    </div>
  );
}

export default SkeletonDemo;
```

## Installation

```bash
bunx --bun shadcn@latest add @sui/skeleton
```

Install with the shadcn CLI or use the shared `@workspace/ui` package. Follow the [installation guide](/docs/installation) to configure the registry, load styles, and choose import aliases.

## Usage

```tsx
import { Skeleton } from "@workspace/ui/components/skeleton"
```

```tsx
<Skeleton className="h-[20px] w-[100px] rounded-full" />
```

## Avatar

### Example: skeleton-avatar

```tsx
import { Skeleton } from "@workspace/ui/components/skeleton";

export function SkeletonAvatar() {
  return (
    <div className="flex w-fit items-center gap-4">
      <Skeleton className="size-10 shrink-0 rounded-full" />
      <div className="grid gap-2">
        <Skeleton className="h-4 w-[150px]" />
        <Skeleton className="h-4 w-[100px]" />
      </div>
    </div>
  );
}

export default SkeletonAvatar;
```

## Card

### Example: skeleton-card

```tsx
import { Card, CardContent, CardHeader } from "@workspace/ui/components/card";
import { Skeleton } from "@workspace/ui/components/skeleton";

export function SkeletonCard() {
  return (
    <Card className="w-full max-w-xs">
      <CardHeader>
        <Skeleton className="h-4 w-2/3" />
        <Skeleton className="h-4 w-1/2" />
      </CardHeader>
      <CardContent>
        <Skeleton className="aspect-video w-full" />
      </CardContent>
    </Card>
  );
}

export default SkeletonCard;
```

## Text

### Example: skeleton-text

```tsx
import { Skeleton } from "@workspace/ui/components/skeleton";

export function SkeletonText() {
  return (
    <div className="flex w-full max-w-xs flex-col gap-2">
      <Skeleton className="h-4 w-full" />
      <Skeleton className="h-4 w-full" />
      <Skeleton className="h-4 w-3/4" />
    </div>
  );
}

export default SkeletonText;
```

## Form

### Example: skeleton-form

```tsx
import { Skeleton } from "@workspace/ui/components/skeleton";

export function SkeletonForm() {
  return (
    <div className="flex w-full max-w-xs flex-col gap-7">
      <div className="flex flex-col gap-3">
        <Skeleton className="h-4 w-20" />
        <Skeleton className="h-8 w-full" />
      </div>
      <div className="flex flex-col gap-3">
        <Skeleton className="h-4 w-24" />
        <Skeleton className="h-8 w-full" />
      </div>
      <Skeleton className="h-8 w-24" />
    </div>
  );
}

export default SkeletonForm;
```

## Table

### Example: skeleton-table

```tsx
// biome-ignore-all lint/suspicious/noArrayIndexKey: The upstream gallery uses fixed positional fixtures that never reorder.

import { Skeleton } from "@workspace/ui/components/skeleton";

export function SkeletonTable() {
  return (
    <div className="flex w-full max-w-sm flex-col gap-2">
      {Array.from({ length: 5 }).map((_, index) => (
        <div className="flex gap-4" key={index}>
          <Skeleton className="h-4 flex-1" />
          <Skeleton className="h-4 w-24" />
          <Skeleton className="h-4 w-20" />
        </div>
      ))}
    </div>
  );
}

export default SkeletonTable;
```

## RTL

To enable RTL support in shadcn/ui, see the [RTL configuration guide](https://ui.shadcn.com/docs/rtl).

### Example: skeleton-rtl

```tsx
"use client";

import { Skeleton } from "@workspace/ui/components/skeleton";
import { type Translations, useTranslation } from "./support";

const translations: Translations = {
  en: {
    dir: "ltr",
    values: {},
  },
  ar: {
    dir: "rtl",
    values: {},
  },
  he: {
    dir: "rtl",
    values: {},
  },
};

export function SkeletonRtl() {
  const { dir } = useTranslation(translations, "ar");

  return (
    <div className="flex items-center gap-4" dir={dir}>
      <Skeleton className="h-12 w-12 rounded-full" />
      <div className="space-y-2">
        <Skeleton className="h-4 w-[250px]" />
        <Skeleton className="h-4 w-[200px]" />
      </div>
    </div>
  );
}

export default SkeletonRtl;
```


---

# Slider

An input where the user selects a value from within a given range.

Page: https://sui.draco.dev/docs/components/slider

### Example: slider-demo

```tsx
import { Slider } from "@workspace/ui/components/slider";

export function SliderDemo() {
  return (
    <Slider
      defaultValue={[75]}
      max={100}
      step={1}
      className="mx-auto w-full max-w-xs"
    />
  );
}

export default SliderDemo;
```

## Installation

```bash
bunx --bun shadcn@latest add @sui/slider
```

Install with the shadcn CLI or use the shared `@workspace/ui` package. Follow the [installation guide](/docs/installation) to configure the registry, load styles, and choose import aliases.

## Usage

```tsx
import { Slider } from "@workspace/ui/components/slider"
```

```tsx
<Slider defaultValue={[33]} max={100} step={1} />
```

## Range

Use an array with two values for a range slider.

### Example: slider-range

```tsx
import { Slider } from "@workspace/ui/components/slider";

export function SliderRange() {
  return (
    <Slider
      defaultValue={[25, 50]}
      max={100}
      step={5}
      className="mx-auto w-full max-w-xs"
    />
  );
}

export default SliderRange;
```

## Multiple Thumbs

Use an array with multiple values for multiple thumbs.

### Example: slider-multiple

```tsx
import { Slider } from "@workspace/ui/components/slider";

export function SliderMultiple() {
  return (
    <Slider
      defaultValue={[10, 20, 70]}
      max={100}
      step={10}
      className="mx-auto w-full max-w-xs"
    />
  );
}

export default SliderMultiple;
```

## Vertical

Use `orientation="vertical"` for a vertical slider.

### Example: slider-vertical

```tsx
import { Slider } from "@workspace/ui/components/slider";

export function SliderVertical() {
  return (
    <div className="mx-auto flex w-full max-w-xs items-center justify-center gap-6">
      <Slider
        defaultValue={[50]}
        max={100}
        step={1}
        orientation="vertical"
        className="h-40"
      />
      <Slider
        defaultValue={[25]}
        max={100}
        step={1}
        orientation="vertical"
        className="h-40"
      />
    </div>
  );
}

export default SliderVertical;
```

## Controlled

### Example: slider-controlled

```tsx
"use client";

import { Label } from "@workspace/ui/components/label";
import { Slider } from "@workspace/ui/components/slider";
import * as React from "react";
import { useId as usePreviewId } from "react";

export function SliderControlled() {
  const previewId = usePreviewId();

  const [value, setValue] = React.useState([0.3, 0.7]);

  return (
    <div className="mx-auto grid w-full max-w-xs gap-3">
      <div className="flex items-center justify-between gap-2">
        <Label htmlFor={`${previewId}-slider-demo-temperature`}>
          Temperature
        </Label>
        <span className="text-muted-foreground text-sm">
          {value.join(", ")}
        </span>
      </div>
      <Slider
        id={`${previewId}-slider-demo-temperature`}
        value={value}
        onValueChange={(value) => setValue(value as number[])}
        min={0}
        max={1}
        step={0.1}
      />
    </div>
  );
}

export default SliderControlled;
```

## Disabled

Use the `disabled` prop to disable the slider.

### Example: slider-disabled

```tsx
import { Slider } from "@workspace/ui/components/slider";

export function SliderDisabled() {
  return (
    <Slider
      defaultValue={[50]}
      max={100}
      step={1}
      disabled
      className="mx-auto w-full max-w-xs"
    />
  );
}

export default SliderDisabled;
```

## RTL

To enable RTL support in shadcn/ui, see the [RTL configuration guide](https://ui.shadcn.com/docs/rtl).

### Example: slider-rtl

```tsx
"use client";

import { Slider } from "@workspace/ui/components/slider";
import { type Translations, useTranslation } from "./support";

const translations: Translations = {
  en: {
    dir: "ltr",
    values: {},
  },
  ar: {
    dir: "rtl",
    values: {},
  },
  he: {
    dir: "rtl",
    values: {},
  },
};

export function SliderRtl() {
  const { dir } = useTranslation(translations, "ar");

  return (
    <Slider
      defaultValue={[75]}
      max={100}
      step={1}
      className="mx-auto w-full max-w-xs"
      dir={dir}
    />
  );
}

export default SliderRtl;
```

## API Reference

See the [Base UI Slider](https://base-ui.com/react/components/slider#api-reference) documentation.

- [Documentation](https://base-ui.com/react/components/slider)
- [API reference](https://base-ui.com/react/components/slider#api-reference)


---

# Switch

A control that allows the user to toggle between checked and not checked.

Page: https://sui.draco.dev/docs/components/switch

### Example: switch-demo

```tsx
import { Label } from "@workspace/ui/components/label";
import { Switch } from "@workspace/ui/components/switch";
import { useId as usePreviewId } from "react";

export function SwitchDemo() {
  const previewId = usePreviewId();

  return (
    <div className="flex items-center space-x-2">
      <Switch id={`${previewId}-airplane-mode`} />
      <Label htmlFor={`${previewId}-airplane-mode`}>Airplane Mode</Label>
    </div>
  );
}

export default SwitchDemo;
```

## Installation

```bash
bunx --bun shadcn@latest add @sui/switch
```

Install with the shadcn CLI or use the shared `@workspace/ui` package. Follow the [installation guide](/docs/installation) to configure the registry, load styles, and choose import aliases.

## Usage

```tsx
import { Switch } from "@workspace/ui/components/switch"
```

```tsx
<Switch />
```

## Description

### Example: switch-description

```tsx
import {
  Field,
  FieldContent,
  FieldDescription,
  FieldLabel,
} from "@workspace/ui/components/field";
import { Switch } from "@workspace/ui/components/switch";
import { useId as usePreviewId } from "react";

export function SwitchDescription() {
  const previewId = usePreviewId();

  return (
    <Field orientation="horizontal" className="max-w-sm">
      <FieldContent>
        <FieldLabel htmlFor={`${previewId}-switch-focus-mode`}>
          Share across devices
        </FieldLabel>
        <FieldDescription>
          Focus is shared across devices, and turns off when you leave the app.
        </FieldDescription>
      </FieldContent>
      <Switch id={`${previewId}-switch-focus-mode`} />
    </Field>
  );
}

export default SwitchDescription;
```

## Choice Card

Card-style selection where `FieldLabel` wraps the entire `Field` for a clickable card pattern.

### Example: switch-choice-card

```tsx
import {
  Field,
  FieldContent,
  FieldDescription,
  FieldGroup,
  FieldLabel,
  FieldTitle,
} from "@workspace/ui/components/field";
import { Switch } from "@workspace/ui/components/switch";
import { useId as usePreviewId } from "react";

export function SwitchChoiceCard() {
  const previewId = usePreviewId();

  return (
    <FieldGroup className="w-full max-w-sm">
      <FieldLabel htmlFor={`${previewId}-switch-share`}>
        <Field orientation="horizontal">
          <FieldContent>
            <FieldTitle>Share across devices</FieldTitle>
            <FieldDescription>
              Focus is shared across devices, and turns off when you leave the
              app.
            </FieldDescription>
          </FieldContent>
          <Switch id={`${previewId}-switch-share`} />
        </Field>
      </FieldLabel>
      <FieldLabel htmlFor={`${previewId}-switch-notifications`}>
        <Field orientation="horizontal">
          <FieldContent>
            <FieldTitle>Enable notifications</FieldTitle>
            <FieldDescription>
              Receive notifications when focus mode is enabled or disabled.
            </FieldDescription>
          </FieldContent>
          <Switch id={`${previewId}-switch-notifications`} defaultChecked />
        </Field>
      </FieldLabel>
    </FieldGroup>
  );
}

export default SwitchChoiceCard;
```

## Disabled

Add the `disabled` prop to the `Switch` component to disable the switch. Add the `data-disabled` prop to the `Field` component for styling.

### Example: switch-disabled

```tsx
import { Field, FieldLabel } from "@workspace/ui/components/field";
import { Switch } from "@workspace/ui/components/switch";
import { useId as usePreviewId } from "react";

export function SwitchDisabled() {
  const previewId = usePreviewId();

  return (
    <Field orientation="horizontal" data-disabled className="w-fit">
      <Switch id={`${previewId}-switch-disabled-unchecked`} disabled />
      <FieldLabel htmlFor={`${previewId}-switch-disabled-unchecked`}>
        Disabled
      </FieldLabel>
    </Field>
  );
}

export default SwitchDisabled;
```

## Invalid

Add the `aria-invalid` prop to the `Switch` component to indicate an invalid state. Add the `data-invalid` prop to the `Field` component for styling.

### Example: switch-invalid

```tsx
import {
  Field,
  FieldContent,
  FieldDescription,
  FieldLabel,
} from "@workspace/ui/components/field";
import { Switch } from "@workspace/ui/components/switch";
import { useId as usePreviewId } from "react";

export function SwitchInvalid() {
  const previewId = usePreviewId();

  return (
    <Field orientation="horizontal" className="max-w-sm" data-invalid>
      <FieldContent>
        <FieldLabel htmlFor={`${previewId}-switch-terms`}>
          Accept terms and conditions
        </FieldLabel>
        <FieldDescription>
          You must accept the terms and conditions to continue.
        </FieldDescription>
      </FieldContent>
      <Switch id={`${previewId}-switch-terms`} aria-invalid />
    </Field>
  );
}

export default SwitchInvalid;
```

## Size

Use the `size` prop to change the size of the switch.

### Example: switch-sizes

```tsx
import { Field, FieldGroup, FieldLabel } from "@workspace/ui/components/field";
import { Switch } from "@workspace/ui/components/switch";
import { useId as usePreviewId } from "react";

export function SwitchSizes() {
  const previewId = usePreviewId();

  return (
    <FieldGroup className="w-full max-w-[10rem]">
      <Field orientation="horizontal">
        <Switch id={`${previewId}-switch-size-sm`} size="sm" />
        <FieldLabel htmlFor={`${previewId}-switch-size-sm`}>Small</FieldLabel>
      </Field>
      <Field orientation="horizontal">
        <Switch id={`${previewId}-switch-size-default`} size="default" />
        <FieldLabel htmlFor={`${previewId}-switch-size-default`}>
          Default
        </FieldLabel>
      </Field>
    </FieldGroup>
  );
}

export default SwitchSizes;
```

## RTL

To enable RTL support in shadcn/ui, see the [RTL configuration guide](https://ui.shadcn.com/docs/rtl).

### Example: switch-rtl

```tsx
"use client";

import {
  Field,
  FieldContent,
  FieldDescription,
  FieldLabel,
} from "@workspace/ui/components/field";
import { Switch } from "@workspace/ui/components/switch";
import { useId as usePreviewId } from "react";
import { type Translations, useTranslation } from "./support";

const translations: Translations = {
  en: {
    dir: "ltr",
    values: {
      label: "Share across devices",
      description:
        "Focus is shared across devices, and turns off when you leave the app.",
    },
  },
  ar: {
    dir: "rtl",
    values: {
      label: "المشاركة عبر الأجهزة",
      description:
        "يتم مشاركة التركيز عبر الأجهزة، ويتم إيقاف تشغيله عند مغادرة التطبيق.",
    },
  },
  he: {
    dir: "rtl",
    values: {
      label: "שיתוף בין מכשירים",
      description: "המיקוד משותף בין מכשירים, וכבה כשאתה עוזב את האפליקציה.",
    },
  },
};

export function SwitchRtl() {
  const previewId = usePreviewId();

  const { dir, t } = useTranslation(translations, "ar");

  return (
    <Field orientation="horizontal" className="max-w-sm" dir={dir}>
      <FieldContent>
        <FieldLabel htmlFor={`${previewId}-switch-focus-mode-rtl`} dir={dir}>
          {t.label}
        </FieldLabel>
        <FieldDescription dir={dir}>{t.description}</FieldDescription>
      </FieldContent>
      <Switch id={`${previewId}-switch-focus-mode-rtl`} dir={dir} />
    </Field>
  );
}

export default SwitchRtl;
```

## API Reference

See the [Base UI Switch](https://base-ui.com/react/components/switch#api-reference) documentation.

- [Documentation](https://base-ui.com/react/components/switch)
- [API reference](https://base-ui.com/react/components/switch#api-reference)


---

# TabBar

Controlled application navigation with press-and-slide selection and optional glass material.

Page: https://sui.draco.dev/docs/components/tab-bar

TabBar presents the primary destinations of an application with labels and optional icons. Its selected indicator follows the current UI style and uses CSS Gaussian blur in `glass` mode, while only the outer bar receives glass material; content and routing remain under application control.

### Example: tab-bar-demo

```tsx
"use client";
import { GlassProvider } from "@workspace/ui/components/glass";
import { TabBar } from "@workspace/ui/components/tab-bar";
import { BellIcon, HomeIcon, SearchIcon, SettingsIcon } from "lucide-react";
import { useRef, useState } from "react";
import type { ExampleProps } from "../types";

export default function Example({ locale }: ExampleProps) {
  const chinese = locale === "zh-CN";
  const scene = useRef<HTMLDivElement>(null);
  const [value, setValue] = useState("home");
  const items = [
    { value: "home", label: chinese ? "首页" : "Home", icon: <HomeIcon /> },
    {
      value: "search",
      label: chinese ? "搜索" : "Search",
      icon: <SearchIcon />,
    },
    {
      value: "activity",
      label: chinese ? "动态" : "Activity",
      icon: <BellIcon />,
    },
    {
      value: "settings",
      label: chinese ? "设置" : "Settings",
      icon: <SettingsIcon />,
    },
  ];
  const current = items.find((item) => item.value === value);
  return (
    <GlassProvider mode="auto" material="clear" captureTarget={scene}>
      <div
        ref={scene}
        className="relative isolate flex min-h-80 w-full flex-col justify-between overflow-hidden rounded-2xl bg-muted p-6"
      >
        <div
          className="absolute inset-0 -z-10 grid grid-cols-3 gap-3 p-3"
          aria-hidden="true"
        >
          <div className="rounded-2xl bg-blue-400/60" />
          <div className="rounded-2xl bg-emerald-400/60" />
          <div className="rounded-2xl bg-rose-400/60" />
        </div>
        <p className="text-center text-sm" aria-live="polite">
          {chinese ? "当前目的地：" : "Current destination: "}
          {current?.label}
        </p>
        <div className="grid gap-6">
          <div className="grid gap-2">
            <p className="text-center text-sm">
              {chinese ? "默认外观" : "Default appearance"}
            </p>
            <TabBar
              aria-label={
                chinese ? "默认应用导航" : "Default application navigation"
              }
              items={items}
              value={value}
              onValueChange={setValue}
              className="mx-auto w-full max-w-md"
            />
          </div>
          <div className="grid gap-2">
            <p className="text-center text-sm">
              {chinese ? "玻璃模式" : "Glass mode"}
            </p>
            <TabBar
              glass
              aria-label={
                chinese ? "玻璃应用导航" : "Glass application navigation"
              }
              items={items}
              value={value}
              onValueChange={setValue}
              className="mx-auto w-full max-w-md"
            />
          </div>
        </div>
      </div>
    </GlassProvider>
  );
}
```

## Installation

```bash
bunx --bun shadcn@latest add @sui/tab-bar
```

Install with the shadcn CLI or use the shared `@workspace/ui` package. Follow the [installation guide](/docs/installation) to configure the registry, load styles, and choose import aliases.

## Usage

```tsx
import { TabBar } from "@workspace/ui/components/tab-bar";
import { useState } from "react";

export function ApplicationNavigation() {
  const [value, setValue] = useState("home");
  return (
    <TabBar
      aria-label="Application navigation"
      value={value}
      onValueChange={setValue}
      items={[
        { value: "home", label: "Home" },
        { value: "search", label: "Search" },
        { value: "activity", label: "Activity" },
      ]}
    />
  );
}
```

## Navigation and selection

`value` identifies the current destination. `onValueChange` asks the application to select another destination, so it can update a router, preserve a query or anchor, or display its own view. Items must have unique values. A disabled item cannot be selected.

TabBar renders a navigation landmark with buttons and exposes the current destination through `aria-current`. Give the landmark an `aria-label` and each item a clear text label; decorative icons are optional. It does not render content panels. Use [Tabs](/docs/components/tabs) when selecting among panels within a page.

## Keyboard and layout

Arrow keys move among enabled destinations in the bar's orientation. Home and End focus the first and last enabled destinations. Moving focus does not change the current destination; Enter or Space activates the focused button. The current destination participates in the Tab sequence; keyboard activation follows the same change callback as pointer activation. Horizontal layout follows the document direction, including RTL.

The bar can scroll when destinations exceed its available space. Set `orientation="vertical"` to arrange destinations vertically. The moving selection background follows the selected button's current bounds after layout, resizing, or scrolling. Reduced-motion preferences disable animated movement while keeping selection visible.

## Material

TabBar defaults to the existing UI appearance with `glass={false}`. Pass `glass` to apply shared glass material to the outer bar, inheriting [GlassProvider](/docs/components/glass) rendering and material settings. Both modes use a theme-colored selection background; glass mode adds approximately `7px` of CSS Gaussian blur, with icons and labels in the theme primary color. A floating glass lens appears only while holding, reusing the shared material and background capture.

Keep the surrounding container ordinary to avoid nested glass. The example compares both modes using the same controlled destinations and background.

## Press and slide

Hold an enabled item for 250ms or drag beyond 6px to expand the selection into a floating lens and gently enlarge its icon and label. In glass mode the lens uses clear glass with very little tint and approximately `0.6px` blur; otherwise it keeps the theme selection background. Slide while holding to continuously move the lens and position the lens over other enabled items. The resting selection background is hidden while holding. The current item’s theme color and `aria-current` remain unchanged until releasing commits the new selection and restores its background. Releasing outside the bar, cancelling the pointer, or losing window focus restores the original selection. Short clicks and keyboard activation keep their usual behavior, and disabled items remain unavailable. Reduced-motion preferences disable scaling and animated movement.

## API reference

| Prop | Type | Default / behavior |
| --- | --- | --- |
| `items` | `readonly TabBarItem[]` | Destination list. |
| Item `value` | `string` | Unique destination identifier. |
| Item `label` | `string` | Visible destination label. |
| Item `icon` | `ReactNode` | Optional decorative icon. |
| Item `disabled` | `boolean` | Prevents selection. |
| `value` | `string` | Controlled current destination. |
| `onValueChange` | `(value: string) => void` | Called when selecting an enabled destination. |
| `glass` | `boolean` | `false`; optional glass treatment. |
| `size` | `"sm" \| "default" \| "lg"` | `"default"`. |
| `onItemActivate` | `(value: string) => void` | Optional activation notification. |
| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"`. |
| Other props | Native nav props | Includes `aria-label`, `className`, `style`, and `ref`. |

The module exports `TabBar` and its public props and item types. Application routing remains outside the component.


---

# Table

A responsive table component.

Page: https://sui.draco.dev/docs/components/table

### Example: table-demo

```tsx
import {
  Table,
  TableBody,
  TableCaption,
  TableCell,
  TableFooter,
  TableHead,
  TableHeader,
  TableRow,
} from "@workspace/ui/components/table";

const invoices = [
  {
    invoice: "INV001",
    paymentStatus: "Paid",
    totalAmount: "$250.00",
    paymentMethod: "Credit Card",
  },
  {
    invoice: "INV002",
    paymentStatus: "Pending",
    totalAmount: "$150.00",
    paymentMethod: "PayPal",
  },
  {
    invoice: "INV003",
    paymentStatus: "Unpaid",
    totalAmount: "$350.00",
    paymentMethod: "Bank Transfer",
  },
  {
    invoice: "INV004",
    paymentStatus: "Paid",
    totalAmount: "$450.00",
    paymentMethod: "Credit Card",
  },
  {
    invoice: "INV005",
    paymentStatus: "Paid",
    totalAmount: "$550.00",
    paymentMethod: "PayPal",
  },
  {
    invoice: "INV006",
    paymentStatus: "Pending",
    totalAmount: "$200.00",
    paymentMethod: "Bank Transfer",
  },
  {
    invoice: "INV007",
    paymentStatus: "Unpaid",
    totalAmount: "$300.00",
    paymentMethod: "Credit Card",
  },
];

export function TableDemo() {
  return (
    <Table>
      <TableCaption>A list of your recent invoices.</TableCaption>
      <TableHeader>
        <TableRow>
          <TableHead className="w-[100px]">Invoice</TableHead>
          <TableHead>Status</TableHead>
          <TableHead>Method</TableHead>
          <TableHead className="text-right">Amount</TableHead>
        </TableRow>
      </TableHeader>
      <TableBody>
        {invoices.map((invoice) => (
          <TableRow key={invoice.invoice}>
            <TableCell className="font-medium">{invoice.invoice}</TableCell>
            <TableCell>{invoice.paymentStatus}</TableCell>
            <TableCell>{invoice.paymentMethod}</TableCell>
            <TableCell className="text-right">{invoice.totalAmount}</TableCell>
          </TableRow>
        ))}
      </TableBody>
      <TableFooter>
        <TableRow>
          <TableCell colSpan={3}>Total</TableCell>
          <TableCell className="text-right">$2,500.00</TableCell>
        </TableRow>
      </TableFooter>
    </Table>
  );
}

export default TableDemo;
```

## Installation

```bash
bunx --bun shadcn@latest add @sui/table
```

Install with the shadcn CLI or use the shared `@workspace/ui` package. Follow the [installation guide](/docs/installation) to configure the registry, load styles, and choose import aliases.

## Usage

```tsx showLineNumbers
import {
  Table,
  TableBody,
  TableCaption,
  TableCell,
  TableHead,
  TableHeader,
  TableRow,
} from "@workspace/ui/components/table"
```

```tsx showLineNumbers
<Table>
  <TableCaption>A list of your recent invoices.</TableCaption>
  <TableHeader>
    <TableRow>
      <TableHead className="w-[100px]">Invoice</TableHead>
      <TableHead>Status</TableHead>
      <TableHead>Method</TableHead>
      <TableHead className="text-right">Amount</TableHead>
    </TableRow>
  </TableHeader>
  <TableBody>
    <TableRow>
      <TableCell className="font-medium">INV001</TableCell>
      <TableCell>Paid</TableCell>
      <TableCell>Credit Card</TableCell>
      <TableCell className="text-right">$250.00</TableCell>
    </TableRow>
  </TableBody>
</Table>
```

## Composition

Use the following composition to build a `Table`:

```text
Table
├── TableCaption
├── TableHeader
│   └── TableRow
│       ├── TableHead
│       ├── TableHead
│       ├── TableHead
│       └── TableHead
├── TableBody
│   ├── TableRow
│   │   ├── TableCell
│   │   ├── TableCell
│   │   ├── TableCell
│   │   └── TableCell
│   └── TableRow
│       ├── TableCell
│       ├── TableCell
│       ├── TableCell
│       └── TableCell
└── TableFooter
```

## Footer

Use the `<TableFooter />` component to add a footer to the table.

### Example: table-footer

```tsx
import {
  Table,
  TableBody,
  TableCaption,
  TableCell,
  TableFooter,
  TableHead,
  TableHeader,
  TableRow,
} from "@workspace/ui/components/table";

const invoices = [
  {
    invoice: "INV001",
    paymentStatus: "Paid",
    totalAmount: "$250.00",
    paymentMethod: "Credit Card",
  },
  {
    invoice: "INV002",
    paymentStatus: "Pending",
    totalAmount: "$150.00",
    paymentMethod: "PayPal",
  },
  {
    invoice: "INV003",
    paymentStatus: "Unpaid",
    totalAmount: "$350.00",
    paymentMethod: "Bank Transfer",
  },
  {
    invoice: "INV004",
    paymentStatus: "Paid",
    totalAmount: "$450.00",
    paymentMethod: "Credit Card",
  },
  {
    invoice: "INV005",
    paymentStatus: "Paid",
    totalAmount: "$550.00",
    paymentMethod: "PayPal",
  },
  {
    invoice: "INV006",
    paymentStatus: "Pending",
    totalAmount: "$200.00",
    paymentMethod: "Bank Transfer",
  },
  {
    invoice: "INV007",
    paymentStatus: "Unpaid",
    totalAmount: "$300.00",
    paymentMethod: "Credit Card",
  },
];

export function TableFooterExample() {
  return (
    <Table>
      <TableCaption>A list of your recent invoices.</TableCaption>
      <TableHeader>
        <TableRow>
          <TableHead className="w-[100px]">Invoice</TableHead>
          <TableHead>Status</TableHead>
          <TableHead>Method</TableHead>
          <TableHead className="text-right">Amount</TableHead>
        </TableRow>
      </TableHeader>
      <TableBody>
        {invoices.slice(0, 3).map((invoice) => (
          <TableRow key={invoice.invoice}>
            <TableCell className="font-medium">{invoice.invoice}</TableCell>
            <TableCell>{invoice.paymentStatus}</TableCell>
            <TableCell>{invoice.paymentMethod}</TableCell>
            <TableCell className="text-right">{invoice.totalAmount}</TableCell>
          </TableRow>
        ))}
      </TableBody>
      <TableFooter>
        <TableRow>
          <TableCell colSpan={3}>Total</TableCell>
          <TableCell className="text-right">$2,500.00</TableCell>
        </TableRow>
      </TableFooter>
    </Table>
  );
}

export default TableFooterExample;
```

## Actions

A table showing actions for each row using a `<DropdownMenu />` component.

### Example: table-actions

```tsx
import { Button } from "@workspace/ui/components/button";
import {
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuItem,
  DropdownMenuSeparator,
  DropdownMenuTrigger,
} from "@workspace/ui/components/dropdown-menu";
import {
  Table,
  TableBody,
  TableCell,
  TableHead,
  TableHeader,
  TableRow,
} from "@workspace/ui/components/table";
import { MoreHorizontalIcon } from "lucide-react";

export function TableActions() {
  return (
    <Table>
      <TableHeader>
        <TableRow>
          <TableHead>Product</TableHead>
          <TableHead>Price</TableHead>
          <TableHead className="text-right">Actions</TableHead>
        </TableRow>
      </TableHeader>
      <TableBody>
        <TableRow>
          <TableCell className="font-medium">Wireless Mouse</TableCell>
          <TableCell>$29.99</TableCell>
          <TableCell className="text-right">
            <DropdownMenu>
              <DropdownMenuTrigger
                render={
                  <Button variant="ghost" size="icon" className="size-8" />
                }
              >
                <MoreHorizontalIcon />
                <span className="sr-only">Open menu</span>
              </DropdownMenuTrigger>
              <DropdownMenuContent align="end">
                <DropdownMenuItem>Edit</DropdownMenuItem>
                <DropdownMenuItem>Duplicate</DropdownMenuItem>
                <DropdownMenuSeparator />
                <DropdownMenuItem variant="destructive">
                  Delete
                </DropdownMenuItem>
              </DropdownMenuContent>
            </DropdownMenu>
          </TableCell>
        </TableRow>
        <TableRow>
          <TableCell className="font-medium">Mechanical Keyboard</TableCell>
          <TableCell>$129.99</TableCell>
          <TableCell className="text-right">
            <DropdownMenu>
              <DropdownMenuTrigger
                render={
                  <Button variant="ghost" size="icon" className="size-8" />
                }
              >
                <MoreHorizontalIcon />
                <span className="sr-only">Open menu</span>
              </DropdownMenuTrigger>
              <DropdownMenuContent align="end">
                <DropdownMenuItem>Edit</DropdownMenuItem>
                <DropdownMenuItem>Duplicate</DropdownMenuItem>
                <DropdownMenuSeparator />
                <DropdownMenuItem variant="destructive">
                  Delete
                </DropdownMenuItem>
              </DropdownMenuContent>
            </DropdownMenu>
          </TableCell>
        </TableRow>
        <TableRow>
          <TableCell className="font-medium">USB-C Hub</TableCell>
          <TableCell>$49.99</TableCell>
          <TableCell className="text-right">
            <DropdownMenu>
              <DropdownMenuTrigger
                render={
                  <Button variant="ghost" size="icon" className="size-8" />
                }
              >
                <MoreHorizontalIcon />
                <span className="sr-only">Open menu</span>
              </DropdownMenuTrigger>
              <DropdownMenuContent align="end">
                <DropdownMenuItem>Edit</DropdownMenuItem>
                <DropdownMenuItem>Duplicate</DropdownMenuItem>
                <DropdownMenuSeparator />
                <DropdownMenuItem variant="destructive">
                  Delete
                </DropdownMenuItem>
              </DropdownMenuContent>
            </DropdownMenu>
          </TableCell>
        </TableRow>
      </TableBody>
    </Table>
  );
}

export default TableActions;
```

## Data Table

Use the shared [Data Table block](/docs/blocks/data-table) for search, filters, sorting, pagination, selection, bulk actions, and drag ordering. Import it from `@workspace/ui/blocks/data-table`.

## RTL

To enable RTL support in shadcn/ui, see the [RTL configuration guide](https://ui.shadcn.com/docs/rtl).

### Example: table-rtl

```tsx
"use client";

import {
  Table,
  TableBody,
  TableCaption,
  TableCell,
  TableFooter,
  TableHead,
  TableHeader,
  TableRow,
} from "@workspace/ui/components/table";
import { type Translations, useTranslation } from "./support";

const translations: Translations = {
  en: {
    dir: "ltr",
    values: {
      caption: "A list of your recent invoices.",
      invoice: "Invoice",
      status: "Status",
      method: "Method",
      amount: "Amount",
      paid: "Paid",
      pending: "Pending",
      unpaid: "Unpaid",
      creditCard: "Credit Card",
      paypal: "PayPal",
      bankTransfer: "Bank Transfer",
      total: "Total",
    },
  },
  ar: {
    dir: "rtl",
    values: {
      caption: "قائمة بفواتيرك الأخيرة.",
      invoice: "الفاتورة",
      status: "الحالة",
      method: "الطريقة",
      amount: "المبلغ",
      paid: "مدفوع",
      pending: "قيد الانتظار",
      unpaid: "غير مدفوع",
      creditCard: "بطاقة ائتمانية",
      paypal: "PayPal",
      bankTransfer: "تحويل بنكي",
      total: "المجموع",
    },
  },
  he: {
    dir: "rtl",
    values: {
      caption: "רשימת החשבוניות האחרונות שלך.",
      invoice: "חשבונית",
      status: "סטטוס",
      method: "שיטה",
      amount: "סכום",
      paid: "שולם",
      pending: "ממתין",
      unpaid: "לא שולם",
      creditCard: "כרטיס אשראי",
      paypal: "PayPal",
      bankTransfer: "העברה בנקאית",
      total: 'סה"כ',
    },
  },
};

const invoices = [
  {
    invoice: "INV001",
    paymentStatus: "paid" as const,
    totalAmount: "$250.00",
    paymentMethod: "creditCard" as const,
  },
  {
    invoice: "INV002",
    paymentStatus: "pending" as const,
    totalAmount: "$150.00",
    paymentMethod: "paypal" as const,
  },
  {
    invoice: "INV003",
    paymentStatus: "unpaid" as const,
    totalAmount: "$350.00",
    paymentMethod: "bankTransfer" as const,
  },
  {
    invoice: "INV004",
    paymentStatus: "paid" as const,
    totalAmount: "$450.00",
    paymentMethod: "creditCard" as const,
  },
  {
    invoice: "INV005",
    paymentStatus: "paid" as const,
    totalAmount: "$550.00",
    paymentMethod: "paypal" as const,
  },
  {
    invoice: "INV006",
    paymentStatus: "pending" as const,
    totalAmount: "$200.00",
    paymentMethod: "bankTransfer" as const,
  },
  {
    invoice: "INV007",
    paymentStatus: "unpaid" as const,
    totalAmount: "$300.00",
    paymentMethod: "creditCard" as const,
  },
];

export function TableRtl() {
  const { dir, t } = useTranslation(translations, "ar");

  return (
    <Table dir={dir}>
      <TableCaption>{t.caption}</TableCaption>
      <TableHeader>
        <TableRow>
          <TableHead className="w-[100px]">{t.invoice}</TableHead>
          <TableHead>{t.status}</TableHead>
          <TableHead>{t.method}</TableHead>
          <TableHead className="text-right">{t.amount}</TableHead>
        </TableRow>
      </TableHeader>
      <TableBody>
        {invoices.map((invoice) => (
          <TableRow key={invoice.invoice}>
            <TableCell className="font-medium">{invoice.invoice}</TableCell>
            <TableCell>{t[invoice.paymentStatus]}</TableCell>
            <TableCell>{t[invoice.paymentMethod]}</TableCell>
            <TableCell className="text-right">{invoice.totalAmount}</TableCell>
          </TableRow>
        ))}
      </TableBody>
      <TableFooter>
        <TableRow>
          <TableCell colSpan={3}>{t.total}</TableCell>
          <TableCell className="text-right">$2,500.00</TableCell>
        </TableRow>
      </TableFooter>
    </Table>
  );
}

export default TableRtl;
```


---

# Tabs

A set of layered sections of content—known as tab panels—that are displayed one at a time.

Page: https://sui.draco.dev/docs/components/tabs

### Example: tabs-demo

```tsx
import {
  Card,
  CardContent,
  CardDescription,
  CardHeader,
  CardTitle,
} from "@workspace/ui/components/card";
import {
  Tabs,
  TabsContent,
  TabsList,
  TabsTrigger,
} from "@workspace/ui/components/tabs";

export function TabsDemo() {
  return (
    <Tabs defaultValue="overview" className="w-[400px] max-w-full">
      <TabsList>
        <TabsTrigger value="overview">Overview</TabsTrigger>
        <TabsTrigger value="analytics">Analytics</TabsTrigger>
        <TabsTrigger value="reports">Reports</TabsTrigger>
        <TabsTrigger value="settings">Settings</TabsTrigger>
      </TabsList>
      <TabsContent value="overview">
        <Card>
          <CardHeader>
            <CardTitle>Overview</CardTitle>
            <CardDescription>
              View your key metrics and recent project activity. Track progress
              across all your active projects.
            </CardDescription>
          </CardHeader>
          <CardContent className="text-muted-foreground text-sm">
            You have 12 active projects and 3 pending tasks.
          </CardContent>
        </Card>
      </TabsContent>
      <TabsContent value="analytics">
        <Card>
          <CardHeader>
            <CardTitle>Analytics</CardTitle>
            <CardDescription>
              Track performance and user engagement metrics. Monitor trends and
              identify growth opportunities.
            </CardDescription>
          </CardHeader>
          <CardContent className="text-muted-foreground text-sm">
            Page views are up 25% compared to last month.
          </CardContent>
        </Card>
      </TabsContent>
      <TabsContent value="reports">
        <Card>
          <CardHeader>
            <CardTitle>Reports</CardTitle>
            <CardDescription>
              Generate and download your detailed reports. Export data in
              multiple formats for analysis.
            </CardDescription>
          </CardHeader>
          <CardContent className="text-muted-foreground text-sm">
            You have 5 reports ready and available to export.
          </CardContent>
        </Card>
      </TabsContent>
      <TabsContent value="settings">
        <Card>
          <CardHeader>
            <CardTitle>Settings</CardTitle>
            <CardDescription>
              Manage your account preferences and options. Customize your
              experience to fit your needs.
            </CardDescription>
          </CardHeader>
          <CardContent className="text-muted-foreground text-sm">
            Configure notifications, security, and themes.
          </CardContent>
        </Card>
      </TabsContent>
    </Tabs>
  );
}

export default TabsDemo;
```

## Installation

```bash
bunx --bun shadcn@latest add @sui/tabs
```

Install with the shadcn CLI or use the shared `@workspace/ui` package. Follow the [installation guide](/docs/installation) to configure the registry, load styles, and choose import aliases.

## Usage

```tsx showLineNumbers
import { Tabs, TabsContent, TabsList, TabsTrigger } from "@workspace/ui/components/tabs"
```

```tsx showLineNumbers
<Tabs defaultValue="account" className="w-[400px] max-w-full">
  <TabsList>
    <TabsTrigger value="account">Account</TabsTrigger>
    <TabsTrigger value="password">Password</TabsTrigger>
  </TabsList>
  <TabsContent value="account">Make changes to your account here.</TabsContent>
  <TabsContent value="password">Change your password here.</TabsContent>
</Tabs>
```

## Composition

Use the following composition to build `Tabs`:

```text
Tabs
├── TabsList
│   ├── TabsTrigger
│   └── TabsTrigger
├── TabsContent
└── TabsContent
```

## Line

Use the `variant="line"` prop on `TabsList` for a line style.

### Example: tabs-line

```tsx
import { Tabs, TabsList, TabsTrigger } from "@workspace/ui/components/tabs";

export function TabsLine() {
  return (
    <Tabs defaultValue="overview">
      <TabsList variant="line">
        <TabsTrigger value="overview">Overview</TabsTrigger>
        <TabsTrigger value="analytics">Analytics</TabsTrigger>
        <TabsTrigger value="reports">Reports</TabsTrigger>
      </TabsList>
    </Tabs>
  );
}

export default TabsLine;
```

## Segment

Use the `variant="segment"` prop on `TabsList` for a compact segmented control. Use `wrapperClassName="w-full"` to fill the available width.

### Example: tabs-segment

```tsx
import {
  Tabs,
  TabsContent,
  TabsList,
  TabsTrigger,
} from "@workspace/ui/components/tabs";

export function TabsSegment() {
  return (
    <Tabs defaultValue="week" className="w-full max-w-xs">
      <TabsList variant="segment" wrapperClassName="w-full">
        <TabsTrigger value="day">Day</TabsTrigger>
        <TabsTrigger value="week">Week</TabsTrigger>
        <TabsTrigger value="month">Month</TabsTrigger>
      </TabsList>
      <TabsContent value="day">View today's activity.</TabsContent>
      <TabsContent value="week">View this week's activity.</TabsContent>
      <TabsContent value="month">View this month's activity.</TabsContent>
    </Tabs>
  );
}

export default function Preview() {
  return (
    <div className="flex w-full justify-center">
      <TabsSegment />
    </div>
  );
}
```

## Overflow

Tab lists scroll automatically when they exceed the available space. Arrow controls and faded edges indicate more tabs. Selected and focused tabs scroll into view within the list, including vertical and RTL layouts.

### Example: tabs-overflow

```tsx
import {
  Tabs,
  TabsContent,
  TabsList,
  TabsTrigger,
} from "@workspace/ui/components/tabs";

const tabs = [
  "Overview",
  "Activity",
  "Analytics",
  "Members",
  "Billing",
  "Settings",
];

export function TabsOverflow() {
  return (
    <Tabs defaultValue="Overview" className="w-full max-w-xs">
      <TabsList>
        {tabs.map((tab) => (
          <TabsTrigger key={tab} value={tab}>
            {tab}
          </TabsTrigger>
        ))}
      </TabsList>
      {tabs.map((tab) => (
        <TabsContent key={tab} value={tab}>
          Manage your project's {tab.toLowerCase()}.
        </TabsContent>
      ))}
    </Tabs>
  );
}

export default function Preview() {
  return (
    <div className="flex w-full justify-center">
      <TabsOverflow />
    </div>
  );
}
```

## Vertical

Use `orientation="vertical"` for vertical tabs.

### Example: tabs-vertical

```tsx
import {
  Card,
  CardContent,
  CardHeader,
  CardTitle,
} from "@workspace/ui/components/card";
import {
  Tabs,
  TabsContent,
  TabsList,
  TabsTrigger,
} from "@workspace/ui/components/tabs";
import type { ExampleProps } from "../types";

export function TabsVertical({ locale }: ExampleProps = {}) {
  const chinese = locale === "zh-CN";
  return (
    <Tabs
      defaultValue="account"
      orientation="vertical"
      className="w-full max-w-md gap-4"
    >
      <TabsList aria-label={chinese ? "账户设置" : "Account settings"}>
        <TabsTrigger value="account">
          {chinese ? "账户" : "Account"}
        </TabsTrigger>
        <TabsTrigger value="password">
          {chinese ? "密码" : "Password"}
        </TabsTrigger>
        <TabsTrigger value="notifications">
          {chinese ? "通知" : "Notifications"}
        </TabsTrigger>
      </TabsList>
      <TabsContent value="account" className="min-w-0">
        <Card>
          <CardHeader>
            <CardTitle>{chinese ? "账户" : "Account"}</CardTitle>
          </CardHeader>
          <CardContent className="text-muted-foreground text-sm">
            {chinese
              ? "在此查看你的个人资料与账户偏好"
              : "View your profile and account preferences here."}
          </CardContent>
        </Card>
      </TabsContent>
      <TabsContent value="password" className="min-w-0">
        <Card>
          <CardHeader>
            <CardTitle>{chinese ? "密码" : "Password"}</CardTitle>
          </CardHeader>
          <CardContent className="text-muted-foreground text-sm">
            {chinese
              ? "使用唯一密码并启用双重验证以保护账户"
              : "Protect your account with a unique password and two-factor authentication."}
          </CardContent>
        </Card>
      </TabsContent>
      <TabsContent value="notifications" className="min-w-0">
        <Card>
          <CardHeader>
            <CardTitle>{chinese ? "通知" : "Notifications"}</CardTitle>
          </CardHeader>
          <CardContent className="text-muted-foreground text-sm">
            {chinese
              ? "项目更新与账户提醒将发送到你的邮箱"
              : "Project updates and account alerts are delivered to your inbox."}
          </CardContent>
        </Card>
      </TabsContent>
    </Tabs>
  );
}

export default TabsVertical;
```

## Disabled

### Example: tabs-disabled

```tsx
import { Tabs, TabsList, TabsTrigger } from "@workspace/ui/components/tabs";

export function TabsDisabled() {
  return (
    <Tabs defaultValue="home">
      <TabsList>
        <TabsTrigger value="home">Home</TabsTrigger>
        <TabsTrigger value="settings" disabled>
          Disabled
        </TabsTrigger>
      </TabsList>
    </Tabs>
  );
}

export default TabsDisabled;
```

## Icons

### Example: tabs-icons

```tsx
import { Tabs, TabsList, TabsTrigger } from "@workspace/ui/components/tabs";
import { AppWindowIcon, CodeIcon } from "lucide-react";

export function TabsIcons() {
  return (
    <Tabs defaultValue="preview">
      <TabsList>
        <TabsTrigger value="preview">
          <AppWindowIcon />
          Preview
        </TabsTrigger>
        <TabsTrigger value="code">
          <CodeIcon />
          Code
        </TabsTrigger>
      </TabsList>
    </Tabs>
  );
}

export default TabsIcons;
```

## RTL

To enable RTL support in shadcn/ui, see the [RTL configuration guide](https://ui.shadcn.com/docs/rtl).

### Example: tabs-rtl

```tsx
"use client";

import {
  Card,
  CardContent,
  CardDescription,
  CardHeader,
  CardTitle,
} from "@workspace/ui/components/card";
import {
  Tabs,
  TabsContent,
  TabsList,
  TabsTrigger,
} from "@workspace/ui/components/tabs";
import { type Translations, useTranslation } from "./support";

const translations: Translations = {
  en: {
    dir: "ltr",
    values: {
      overview: "Overview",
      analytics: "Analytics",
      reports: "Reports",
      settings: "Settings",
      overviewTitle: "Overview",
      overviewDesc:
        "View your key metrics and recent project activity. Track progress across all your active projects.",
      overviewContent: "You have 12 active projects and 3 pending tasks.",
      analyticsTitle: "Analytics",
      analyticsDesc:
        "Track performance and user engagement metrics. Monitor trends and identify growth opportunities.",
      analyticsContent: "Page views are up 25% compared to last month.",
      reportsTitle: "Reports",
      reportsDesc:
        "Generate and download your detailed reports. Export data in multiple formats for analysis.",
      reportsContent: "You have 5 reports ready and available to export.",
      settingsTitle: "Settings",
      settingsDesc:
        "Manage your account preferences and options. Customize your experience to fit your needs.",
      settingsContent: "Configure notifications, security, and themes.",
    },
  },
  ar: {
    dir: "rtl",
    values: {
      overview: "نظرة عامة",
      analytics: "التحليلات",
      reports: "التقارير",
      settings: "الإعدادات",
      overviewTitle: "نظرة عامة",
      overviewDesc:
        "عرض مقاييسك الرئيسية وأنشطة المشروع الأخيرة. تتبع التقدم عبر جميع مشاريعك النشطة.",
      overviewContent: "لديك ١٢ مشروعًا نشطًا و٣ مهام معلقة.",
      analyticsTitle: "التحليلات",
      analyticsDesc:
        "تتبع مقاييس الأداء ومشاركة المستخدمين. راقب الاتجاهات وحدد فرص النمو.",
      analyticsContent: "زادت مشاهدات الصفحة بنسبة ٢٥٪ مقارنة بالشهر الماضي.",
      reportsTitle: "التقارير",
      reportsDesc:
        "إنشاء وتنزيل تقاريرك التفصيلية. تصدير البيانات بتنسيقات متعددة للتحليل.",
      reportsContent: "لديك ٥ تقارير جاهزة ومتاحة للتصدير.",
      settingsTitle: "الإعدادات",
      settingsDesc:
        "إدارة تفضيلات حسابك وخياراته. تخصيص تجربتك لتناسب احتياجاتك.",
      settingsContent: "تكوين الإشعارات والأمان والسمات.",
    },
  },
  he: {
    dir: "rtl",
    values: {
      overview: "סקירה כללית",
      analytics: "אנליטיקה",
      reports: "דוחות",
      settings: "הגדרות",
      overviewTitle: "סקירה כללית",
      overviewDesc:
        "הצג את המדדים העיקריים שלך ופעילות הפרויקט האחרונה. עקוב אחר התקדמות בכל הפרויקטים הפעילים שלך.",
      overviewContent: "יש לך 12 פרויקטים פעילים ו-3 משימות ממתינות.",
      analyticsTitle: "אנליטיקה",
      analyticsDesc:
        "עקוב אחר ביצועים ומדדי מעורבות משתמשים. עקוב אחר מגמות וזהה הזדמנויות צמיחה.",
      analyticsContent: "צפיות בדף עלו ב-25% בהשוואה לחודש שעבר.",
      reportsTitle: "דוחות",
      reportsDesc:
        "צור והורד את הדוחות המפורטים שלך. ייצא נתונים בפורמטים מרובים לניתוח.",
      reportsContent: "יש לך 5 דוחות מוכנים וזמינים לייצוא.",
      settingsTitle: "הגדרות",
      settingsDesc:
        "נהל את העדפות החשבון והאפשרויות שלך. התאם אישית את החוויה שלך כך שתתאים לצרכים שלך.",
      settingsContent: "הגדר התראות, אבטחה וערכות נושא.",
    },
  },
};

export function TabsRtl() {
  const { dir, t } = useTranslation(translations, "ar");

  return (
    <Tabs defaultValue="overview" className="w-full max-w-sm" dir={dir}>
      <TabsList dir={dir}>
        <TabsTrigger value="overview">{t.overview}</TabsTrigger>
        <TabsTrigger value="analytics">{t.analytics}</TabsTrigger>
        <TabsTrigger value="reports">{t.reports}</TabsTrigger>
        <TabsTrigger value="settings">{t.settings}</TabsTrigger>
      </TabsList>
      <TabsContent value="overview">
        <Card dir={dir}>
          <CardHeader>
            <CardTitle>{t.overviewTitle}</CardTitle>
            <CardDescription>{t.overviewDesc}</CardDescription>
          </CardHeader>
          <CardContent className="text-muted-foreground text-sm">
            {t.overviewContent}
          </CardContent>
        </Card>
      </TabsContent>
      <TabsContent value="analytics">
        <Card dir={dir}>
          <CardHeader>
            <CardTitle>{t.analyticsTitle}</CardTitle>
            <CardDescription>{t.analyticsDesc}</CardDescription>
          </CardHeader>
          <CardContent className="text-muted-foreground text-sm">
            {t.analyticsContent}
          </CardContent>
        </Card>
      </TabsContent>
      <TabsContent value="reports">
        <Card dir={dir}>
          <CardHeader>
            <CardTitle>{t.reportsTitle}</CardTitle>
            <CardDescription>{t.reportsDesc}</CardDescription>
          </CardHeader>
          <CardContent className="text-muted-foreground text-sm">
            {t.reportsContent}
          </CardContent>
        </Card>
      </TabsContent>
      <TabsContent value="settings">
        <Card dir={dir}>
          <CardHeader>
            <CardTitle>{t.settingsTitle}</CardTitle>
            <CardDescription>{t.settingsDesc}</CardDescription>
          </CardHeader>
          <CardContent className="text-muted-foreground text-sm">
            {t.settingsContent}
          </CardContent>
        </Card>
      </TabsContent>
    </Tabs>
  );
}

export default TabsRtl;
```

## Animation

The selected indicator and panel use the same 250ms easing. Content fades in from an 8px offset on the side of the newly selected tab: left or right for horizontal tabs, up or down for vertical tabs. Base UI derives the direction from the actual tab positions, including RTL. The initial panel appears without an entrance animation; inactive panels leave the layout immediately and cannot receive focus. Reduced motion disables the transition and offset. Selected tabs use the theme's `primary` and `primary-foreground` colors; the line variant uses `primary` for its indicator and selected label.

Use `indicatorClassName` on `TabsList` to customize the indicator and `wrapperClassName` for the outer container's layout. `className`, `ref`, and `render` continue to apply to the Base UI list. `TabsContent` retains Base UI's `keepMounted` behavior.

## API Reference

See the [Base UI Tabs](https://base-ui.com/react/components/tabs#api-reference) documentation.

- [Documentation](https://base-ui.com/react/components/tabs)
- [API reference](https://base-ui.com/react/components/tabs#api-reference)


---

# Tag Input

A multi-value input with custom tags, suggestions, and keyboard-accessible chips.

Page: https://sui.draco.dev/docs/components/tag-input

### Example: tag-input-demo

```tsx
"use client";

import {
  Field,
  FieldDescription,
  FieldLabel,
} from "@workspace/ui/components/field";
import { TagInput } from "@workspace/ui/components/tag-input";
import { useId } from "react";
import type { ExampleProps } from "../types";

export default function TagInputDemo({ locale }: ExampleProps) {
  const id = useId();
  const chinese = locale === "zh-CN";

  return (
    <Field className="w-full max-w-sm">
      <FieldLabel htmlFor={id}>
        {chinese ? "项目标签" : "Project tags"}
      </FieldLabel>
      <TagInput
        id={id}
        defaultValue={["design", "engineering"]}
        placeholder={chinese ? "添加标签…" : "Add a tag…"}
        labels={
          chinese
            ? {
                input: "项目标签",
                createValue: (value) => `添加“${value}”`,
                removeValue: (value) => `移除 ${value}`,
                empty: "没有建议选项",
              }
            : undefined
        }
      />
      <FieldDescription>
        {chinese
          ? "输入后按 Enter、逗号或 Tab 添加。支持中文输入法"
          : "Add with Enter, comma, or Tab. IME composition stays in the input."}
      </FieldDescription>
    </Field>
  );
}
```

## Installation

```bash
bunx --bun shadcn@latest add @sui/tag-input
```

Install with the shadcn CLI or use the shared `@workspace/ui` package. Follow the [installation guide](/docs/installation) to configure the registry, load styles, and choose import aliases.

## Usage

```tsx
import { TagInput } from "@workspace/ui/components/tag-input";

<TagInput aria-label="Project tags" defaultValue={["design"]} />;
```

Type a tag and press Enter, comma, or Tab. Tags are trimmed; empty values and exact duplicates are ignored. Comparison is case-sensitive. Pasting comma-separated values or multiple lines adds them in order.

The component uses Base UI Combobox's multi-select chips for keyboard navigation and removal. During IME composition, Enter and comma stay with the input method and do not create a tag. With an empty draft, Backspace removes the last tag; arrow keys navigate suggestions and chips.

## Suggestions and controlled values

Supply `suggestions` to offer existing values. Users may still create their own tags by default; set `allowCustom={false}` to restrict new values to the suggestions. A highlighted suggestion is selected with Enter.

Use `value` and `onValueChange` to control the selected array, or `defaultValue` for an uncontrolled input. The draft can also be controlled independently with `inputValue` and `onInputValueChange`.

### Example: tag-input-suggestions

```tsx
"use client";

import {
  Field,
  FieldDescription,
  FieldLabel,
} from "@workspace/ui/components/field";
import { TagInput } from "@workspace/ui/components/tag-input";
import { useId, useState } from "react";
import type { ExampleProps } from "../types";

const suggestions = [
  "React",
  "TypeScript",
  "Fumadocs",
  "TanStack Start",
  "Base UI",
];

export default function TagInputSuggestions({ locale }: ExampleProps) {
  const id = useId();
  const [values, setValues] = useState(["React"]);
  const chinese = locale === "zh-CN";

  return (
    <Field className="w-full max-w-sm">
      <FieldLabel htmlFor={id}>{chinese ? "技术栈" : "Tech stack"}</FieldLabel>
      <TagInput
        id={id}
        value={values}
        onValueChange={setValues}
        suggestions={suggestions}
        placeholder={chinese ? "选择或添加…" : "Choose or add…"}
        labels={
          chinese
            ? {
                input: "技术栈",
                createValue: (value) => `添加“${value}”`,
                removeValue: (value) => `移除 ${value}`,
                empty: "没有匹配的技术",
              }
            : undefined
        }
      />
      <FieldDescription>
        {chinese
          ? "用方向键选择建议，也可以创建自己的标签"
          : "Choose a suggestion with the arrow keys or create your own tag."}
      </FieldDescription>
    </Field>
  );
}
```

## Validation and disabled state

`maxValues` limits the number of tags. `validateValue` checks each new value and receives the values already accepted. Existing tags can always be removed, even when the limit has been reached.

Rejected input remains in the draft and its error is announced. Tab still moves focus out of the input when validation fails; Shift+Tab moves backward without committing the draft. In a batch paste, valid tags before the first rejected value are added, while the remaining values stay in the draft.

`disabled` and `readOnly` prevent changes and disable removal controls.

### Example: tag-input-validation

```tsx
"use client";

import {
  Field,
  FieldDescription,
  FieldLabel,
} from "@workspace/ui/components/field";
import { TagInput } from "@workspace/ui/components/tag-input";
import { useId } from "react";
import type { ExampleProps } from "../types";

export default function TagInputValidation({ locale }: ExampleProps) {
  const id = useId();
  const chinese = locale === "zh-CN";
  const labels = chinese
    ? {
        createValue: (value: string) => `添加“${value}”`,
        removeValue: (value: string) => `移除 ${value}`,
        invalidValue: (value: string) => `“${value}”只能包含字母或数字`,
        maxValuesReached: (limit: number) => `最多添加 ${limit} 个标签`,
        empty: "没有建议选项",
      }
    : undefined;

  return (
    <div className="grid w-full max-w-sm gap-5">
      <Field>
        <FieldLabel htmlFor={`${id}-validated`}>
          {chinese ? "最多 3 个标签" : "Up to 3 tags"}
        </FieldLabel>
        <TagInput
          id={`${id}-validated`}
          defaultValue={["design"]}
          maxValues={3}
          validateValue={(value) => /^[a-z0-9]+$/i.test(value)}
          labels={labels}
          placeholder={chinese ? "添加字母或数字…" : "Letters or numbers…"}
        />
        <FieldDescription>
          {chinese
            ? "错误会保留草稿，移除标签后可继续添加"
            : "Invalid input stays in the draft. Remove a tag to make room."}
        </FieldDescription>
      </Field>
      <Field>
        <FieldLabel htmlFor={`${id}-disabled`}>
          {chinese ? "禁用标签" : "Disabled tags"}
        </FieldLabel>
        <TagInput
          id={`${id}-disabled`}
          defaultValue={["React", "Base UI"]}
          disabled
          labels={labels}
        />
      </Field>
    </div>
  );
}
```

## Composition and forms

Tag Input composes Combobox's root, chips, input, list, and items. Use the standard `Field` components for labels and descriptions. `className` styles the chips container, `inputClassName` styles the draft input, and `ref` points to the native draft input.

Pass `name` to submit each selected tag as a separate form value with the same name. Draft text is not submitted. `required` validates the selected tags, so an existing tag satisfies the requirement even when the draft is empty. Disabled tags are omitted from form data.

Native form reset restores `defaultValue` and `defaultInputValue` in uncontrolled mode. Canceling the reset with `event.preventDefault()` preserves the selected tags and draft. Controlled values remain owned by the application.

### Example: tag-input-form

```tsx
"use client";

import { Button } from "@workspace/ui/components/button";
import { Checkbox } from "@workspace/ui/components/checkbox";
import {
  Field,
  FieldDescription,
  FieldLabel,
} from "@workspace/ui/components/field";
import { TagInput } from "@workspace/ui/components/tag-input";
import { useId, useState } from "react";
import type { ExampleProps } from "../types";

const defaultTags = ["design"];

export default function TagInputForm({ locale }: ExampleProps) {
  const id = useId();
  const [submitted, setSubmitted] = useState<string[] | null>(null);
  const [keepTags, setKeepTags] = useState(false);
  const chinese = locale === "zh-CN";
  const notSubmittedLabel = chinese ? "尚未提交" : "Not submitted";

  return (
    <form
      className="grid w-full max-w-sm gap-4"
      onSubmit={(event) => {
        event.preventDefault();
        const data = new FormData(event.currentTarget);
        setSubmitted(data.getAll("tags").map(String));
      }}
      onReset={(event) => {
        if (keepTags) event.preventDefault();
        else setSubmitted(null);
      }}
    >
      <Field>
        <FieldLabel htmlFor={id}>
          {chinese ? "项目标签" : "Project tags"}
        </FieldLabel>
        <TagInput
          id={id}
          name="tags"
          required
          defaultValue={defaultTags}
          placeholder={chinese ? "添加标签…" : "Add a tag…"}
          labels={
            chinese
              ? {
                  createValue: (value) => `添加“${value}”`,
                  removeValue: (value) => `移除 ${value}`,
                  empty: "没有建议选项",
                }
              : undefined
          }
        />
        <FieldDescription>
          {chinese
            ? "至少选择一个标签。重置会恢复 design；草稿不会进入提交数据"
            : "Choose at least one tag. Reset restores design; draft text is not submitted."}
        </FieldDescription>
      </Field>
      <Field orientation="horizontal">
        <Checkbox
          id={`${id}-keep`}
          checked={keepTags}
          onCheckedChange={setKeepTags}
        />
        <FieldLabel htmlFor={`${id}-keep`}>
          {chinese ? "阻止表单重置" : "Prevent form reset"}
        </FieldLabel>
      </Field>
      <div className="flex gap-2">
        <Button type="submit">{chinese ? "提交" : "Submit"}</Button>
        <Button type="reset" variant="outline">
          {chinese ? "重置" : "Reset"}
        </Button>
      </div>
      <output
        className="rounded-2xl bg-muted px-3 py-2 font-mono text-sm"
        aria-live="polite"
      >
        {submitted === null ? notSubmittedLabel : JSON.stringify(submitted)}
      </output>
    </form>
  );
}
```

## Accessibility

Associate `FieldLabel` with the input's `id`, or provide `aria-label`. Without an `id` or a custom name, the default input name is “Add tag”. Removal buttons have names that include their tag. Validation messages use a status region and are associated with the input.

Localize `labels.input`, `labels.removeValue`, `labels.createValue`, `labels.empty`, `labels.invalidValue`, and `labels.maxValuesReached`. Prefer the same input name as the visible field label.

## API Reference

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `string[]` | — | Controlled selected tags. |
| `defaultValue` | `string[]` | `[]` | Initial uncontrolled tags. |
| `onValueChange` | `(values: string[]) => void` | — | Called when selected tags change. |
| `suggestions` | `readonly string[]` | `[]` | Suggested tags. |
| `allowCustom` | `boolean` | `true` | Allow new values outside suggestions. |
| `maxValues` | `number` | — | Maximum tag count. |
| `validateValue` | `(value: string, values: string[]) => boolean` | — | Validate a new tag. |
| `inputValue` | `string` | — | Controlled draft text. |
| `defaultInputValue` | `string` | `""` | Initial uncontrolled draft text. |
| `onInputValueChange` | `(value: string) => void` | — | Called when the draft changes. |
| `labels` | `TagInputLabels` | English labels | Input, action, and validation text. |
| `inputClassName` | `string` | — | Additional draft input classes. |
| `...props` | Native input props, excluding `value`, `defaultValue`, `type`, and `size` | — | Includes `id`, `ref`, `name`, `form`, `required`, `disabled`, and `readOnly`. |

Keyboard and chip behavior follow the [Base UI Combobox API](https://base-ui.com/react/components/combobox#api-reference).

- [Documentation](https://base-ui.com/react/components/combobox)
- [API reference](https://base-ui.com/react/components/combobox#api-reference)


---

# Textarea

Displays a form textarea or a component that looks like a textarea.

Page: https://sui.draco.dev/docs/components/textarea

### Example: textarea-demo

```tsx
import { Textarea } from "@workspace/ui/components/textarea";

export default function TextareaDemo() {
  return <Textarea placeholder="Type your message here." />;
}
```

## Installation

```bash
bunx --bun shadcn@latest add @sui/textarea
```

Install with the shadcn CLI or use the shared `@workspace/ui` package. Follow the [installation guide](/docs/installation) to configure the registry, load styles, and choose import aliases.

## Usage

```tsx
import { Textarea } from "@workspace/ui/components/textarea"
```

```tsx
<Textarea />
```

## Field

Use `Field`, `FieldLabel`, and `FieldDescription` to create a textarea with a label and description.

### Example: textarea-field

```tsx
import {
  Field,
  FieldDescription,
  FieldLabel,
} from "@workspace/ui/components/field";
import { Textarea } from "@workspace/ui/components/textarea";
import { useId as usePreviewId } from "react";

export function TextareaField() {
  const previewId = usePreviewId();

  return (
    <Field>
      <FieldLabel htmlFor={`${previewId}-textarea-message`}>Message</FieldLabel>
      <FieldDescription>Enter your message below.</FieldDescription>
      <Textarea
        id={`${previewId}-textarea-message`}
        placeholder="Type your message here."
      />
    </Field>
  );
}

export default TextareaField;
```

## Disabled

Use the `disabled` prop to disable the textarea. To style the disabled state, add the `data-disabled` attribute to the `Field` component.

### Example: textarea-disabled

```tsx
import { Field, FieldLabel } from "@workspace/ui/components/field";
import { Textarea } from "@workspace/ui/components/textarea";
import { useId as usePreviewId } from "react";

export function TextareaDisabled() {
  const previewId = usePreviewId();

  return (
    <Field data-disabled>
      <FieldLabel htmlFor={`${previewId}-textarea-disabled`}>
        Message
      </FieldLabel>
      <Textarea
        id={`${previewId}-textarea-disabled`}
        placeholder="Type your message here."
        disabled
      />
    </Field>
  );
}

export default TextareaDisabled;
```

## Invalid

Use the `aria-invalid` prop to mark the textarea as invalid. To style the invalid state, add the `data-invalid` attribute to the `Field` component.

### Example: textarea-invalid

```tsx
import {
  Field,
  FieldDescription,
  FieldLabel,
} from "@workspace/ui/components/field";
import { Textarea } from "@workspace/ui/components/textarea";
import { useId as usePreviewId } from "react";

export function TextareaInvalid() {
  const previewId = usePreviewId();

  return (
    <Field data-invalid>
      <FieldLabel htmlFor={`${previewId}-textarea-invalid`}>Message</FieldLabel>
      <Textarea
        id={`${previewId}-textarea-invalid`}
        placeholder="Type your message here."
        aria-invalid
      />
      <FieldDescription>Please enter a valid message.</FieldDescription>
    </Field>
  );
}

export default TextareaInvalid;
```

## Button

Pair with `Button` to create a textarea with a submit button.

### Example: textarea-button

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

export function TextareaButton() {
  return (
    <div className="grid w-full gap-2">
      <Textarea placeholder="Type your message here." />
      <Button>Send message</Button>
    </div>
  );
}

export default TextareaButton;
```

## RTL

To enable RTL support in shadcn/ui, see the [RTL configuration guide](https://ui.shadcn.com/docs/rtl).

### Example: textarea-rtl

```tsx
"use client";

import {
  Field,
  FieldDescription,
  FieldLabel,
} from "@workspace/ui/components/field";
import { Textarea } from "@workspace/ui/components/textarea";
import { useId as usePreviewId } from "react";
import { type Translations, useTranslation } from "./support";

const translations: Translations = {
  en: {
    dir: "ltr",
    values: {
      label: "Feedback",
      placeholder: "Your feedback helps us improve...",
      description: "Share your thoughts about our service.",
    },
  },
  ar: {
    dir: "rtl",
    values: {
      label: "التعليقات",
      placeholder: "تعليقاتك تساعدنا على التحسين...",
      description: "شاركنا أفكارك حول خدمتنا.",
    },
  },
  he: {
    dir: "rtl",
    values: {
      label: "משוב",
      placeholder: "המשוב שלך עוזר לנו להשתפר...",
      description: "שתף את מחשבותיך על השירות שלנו.",
    },
  },
};

export default function TextareaRtl() {
  const previewId = usePreviewId();

  const { dir, t } = useTranslation(translations, "ar");

  return (
    <Field className="w-full max-w-xs" dir={dir}>
      <FieldLabel htmlFor={`${previewId}-feedback`} dir={dir}>
        {t.label}
      </FieldLabel>
      <Textarea
        id={`${previewId}-feedback`}
        placeholder={t.placeholder}
        dir={dir}
        rows={4}
      />
      <FieldDescription dir={dir}>{t.description}</FieldDescription>
    </Field>
  );
}
```


---

# Theme Toggle

A controlled light/dark switch with optional view-transition effects.

Page: https://sui.draco.dev/docs/components/theme-toggle

### Example: theme-toggle-demo

```tsx
"use client";
import { ThemeToggle } from "@workspace/ui/components/theme-toggle";
import { useTheme } from "next-themes";
import { useEffect, useState } from "react";
import { applyAccent, normalizeHex, themePresets } from "../../lib/theme";
import type { ExampleProps } from "../types";

export default function Example({ locale }: ExampleProps) {
  const chinese = locale === "zh-CN";
  const themeLabels = chinese
    ? { light: "浅色", dark: "深色" }
    : { light: "Light", dark: "Dark" };
  const { resolvedTheme, setTheme } = useTheme();
  const [mounted, setMounted] = useState(false);
  useEffect(() => setMounted(true), []);
  const theme = mounted && resolvedTheme === "dark" ? "dark" : "light";
  const changeTheme = (next: "light" | "dark") => {
    const root = document.documentElement;
    const accent =
      root.dataset.color === "custom"
        ? normalizeHex(root.dataset.colorSeed ?? "")
        : (themePresets.find((preset) => preset.id === root.dataset.color)
            ?.color ?? null);
    root.classList.toggle("dark", next === "dark");
    root.style.colorScheme = next;
    applyAccent(accent, next === "dark");
    setTheme(next);
  };
  return (
    <div className="w-full">
      <div className="flex items-center justify-between gap-4 rounded-xl border bg-background p-6 text-foreground">
        <div className="grid gap-1">
          <p>{chinese ? "文档站主题" : "Documentation appearance"}</p>
          <output className="text-muted-foreground text-sm" aria-live="polite">
            {themeLabels[theme]}
          </output>
        </div>
        <ThemeToggle
          theme={theme}
          onThemeChange={changeTheme}
          disabled={!mounted}
          lightLabel={chinese ? "切换为浅色模式" : "Switch to light mode"}
          darkLabel={chinese ? "切换为深色模式" : "Switch to dark mode"}
        />
      </div>
      <p className="mt-3 text-muted-foreground text-sm">
        {chinese
          ? "此示例切换文档站主题并保存偏好，可在顶栏选择跟随系统或调整配色"
          : "This example switches the documentation theme and saves the preference. The header provides System mode and accent settings."}
      </p>
    </div>
  );
}
```

## Installation

```bash
bunx --bun shadcn@latest add @sui/theme-toggle
```

Install with the shadcn CLI or use the shared `@workspace/ui` package. Follow the [installation guide](/docs/installation) to configure the registry, load styles, and choose import aliases.

## Usage

```tsx
import { ThemeToggle } from "@workspace/ui/components/theme-toggle";
import { useState } from "react";

export function Appearance() {
  const [theme, setTheme] = useState<"light" | "dark">("light");
  return <ThemeToggle theme={theme} onThemeChange={setTheme} />;
}
```

## Controlled appearance

`theme` is the current resolved light or dark theme. `onThemeChange` requests the other theme. Apply the new theme to your application in this callback; the component does not set a provider, save preferences, or implement a System preference. The live examples use the documentation’s `next-themes` provider and change the whole site appearance, saving the selected mode while retaining its accent color. The header still offers System mode and accent settings.

For a System setting, resolve it in your application and pass the effective light or dark theme here. Keep your application’s preference controls separate when System must remain selectable.

## Transition variants

Choose `rectangle`, `circle`, `circle-blur`, or `blinds`. The `start` option selects an origin such as the clicked button, a corner, the center, or a bottom-up transition. These effects use the browser View Transition API. Without support, or with reduced motion, the component changes the theme directly.

### Example: theme-toggle-variants

```tsx
"use client";
import { ThemeToggle } from "@workspace/ui/components/theme-toggle";
import { useTheme } from "next-themes";
import { useEffect, useState } from "react";
import { applyAccent, normalizeHex, themePresets } from "../../lib/theme";
import type { ExampleProps } from "../types";

const variants = ["rectangle", "circle", "circle-blur", "blinds"] as const;
export default function Example({ locale }: ExampleProps) {
  const chinese = locale === "zh-CN";
  const { resolvedTheme, setTheme } = useTheme();
  const [mounted, setMounted] = useState(false);
  useEffect(() => setMounted(true), []);
  const theme = mounted && resolvedTheme === "dark" ? "dark" : "light";
  const changeTheme = (next: "light" | "dark") => {
    const root = document.documentElement;
    const accent =
      root.dataset.color === "custom"
        ? normalizeHex(root.dataset.colorSeed ?? "")
        : (themePresets.find((preset) => preset.id === root.dataset.color)
            ?.color ?? null);
    root.classList.toggle("dark", next === "dark");
    root.style.colorScheme = next;
    applyAccent(accent, next === "dark");
    setTheme(next);
  };
  return (
    <div className="w-full">
      <div className="grid grid-cols-2 gap-4 rounded-xl border bg-background p-5 text-foreground sm:grid-cols-4">
        {variants.map((variant) => (
          <div key={variant} className="grid justify-items-center gap-2">
            <ThemeToggle
              theme={theme}
              onThemeChange={changeTheme}
              disabled={!mounted}
              variant={variant}
              start="button"
              lightLabel={chinese ? "切换为浅色模式" : "Switch to light mode"}
              darkLabel={chinese ? "切换为深色模式" : "Switch to dark mode"}
            />
            <span className="text-muted-foreground text-xs">{variant}</span>
          </div>
        ))}
      </div>
    </div>
  );
}
```

## Labels and icons

`lightLabel` and `darkLabel` describe the action to switch to each theme and supply the tooltip text. The default ghost button uses a 16px Sun/Moon SVG with 2px strokes and a snappy spring geometry morph. Reduced motion swaps the shape directly. Customize `lightIcon`, `darkIcon`, and `iconClassName` when needed; arbitrary React icons switch directly rather than undergoing a path morph. Native button props, including `disabled`, `ref`, and `render`, are supported. The switch does not submit a surrounding form.

## API reference

| Prop | Type | Default / behavior |
| --- | --- | --- |
| `theme` | `"light" \| "dark"` | Required resolved theme. |
| `onThemeChange` | `(theme: "light" \| "dark") => void` | Required theme update callback. |
| `variant` | `"rectangle" \| "circle" \| "circle-blur" \| "blinds"` | `"rectangle"`. |
| `start` | `"button" \| "top-left" \| "top-right" \| "bottom-left" \| "bottom-right" \| "center" \| "bottom-up"` | `"bottom-up"`. |
| `lightLabel`, `darkLabel` | `string` | English switch-action labels. |
| `lightIcon`, `darkIcon` | `ReactNode` | Default theme icons. |
| `iconClassName` | `string` | Optional icon styling. |
| `glass` | `boolean` | `false`. |

The module exports `ThemeToggleProps`. See [View Transition API](https://developer.mozilla.org/en-US/docs/Web/API/View_Transition_API) for browser transition behavior.


---

# Toast

A succinct message that is displayed temporarily.

Page: https://sui.draco.dev/docs/components/toast

### Example: toast-demo

```tsx
"use client";

import { Button } from "@workspace/ui/components/button";
import { toast } from "@workspace/ui/components/toast";

export function ToastDemo() {
  function showToast() {
    const id = toast.add({
      title: "Event created",
      description: "Sunday, December 3 at 9:00 AM",
      actionProps: {
        children: "Undo",
        onClick() {
          toast.close(id);
        },
      },
    });
  }

  return (
    <Button variant="outline" onClick={showToast}>
      Show Toast
    </Button>
  );
}

export default ToastDemo;
```

## Installation

```bash
bunx --bun shadcn@latest add @sui/toast
```

Install with the shadcn CLI or use the shared `@workspace/ui` package. Follow the [installation guide](/docs/installation) to configure the registry, load styles, and choose import aliases.

## Usage

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

```tsx
toast.add({
  title: "Event created",
  description: "Sunday, December 3 at 9:00 AM",
})
```

## Types

Set the `type` option to render a status icon. The built-in renderer recognizes
`success`, `info`, `warning`, `error`, and `loading`.

### Example: toast-types

```tsx
"use client";

import { Button } from "@workspace/ui/components/button";
import { toast } from "@workspace/ui/components/toast";

export function ToastTypes() {
  return (
    <div className="flex flex-wrap gap-2">
      <Button
        variant="outline"
        onClick={() => toast.add({ description: "Event has been created." })}
      >
        Default
      </Button>
      <Button
        variant="outline"
        onClick={() =>
          toast.add({
            type: "success",
            description: "Event has been created.",
          })
        }
      >
        Success
      </Button>
      <Button
        variant="outline"
        onClick={() =>
          toast.add({
            type: "info",
            description: "Arrive 10 minutes before the event.",
          })
        }
      >
        Info
      </Button>
      <Button
        variant="outline"
        onClick={() =>
          toast.add({
            type: "warning",
            description: "The event cannot start before 8:00 AM.",
          })
        }
      >
        Warning
      </Button>
      <Button
        variant="outline"
        onClick={() =>
          toast.add({
            type: "error",
            description: "The event could not be created.",
            priority: "high",
          })
        }
      >
        Error
      </Button>
    </div>
  );
}

export default ToastTypes;
```

## Action

Pass button props with `actionProps` to render an action.

```tsx
const id = toast.add({
  title: "Event created",
  actionProps: {
    children: "Undo",
    onClick() {
      toast.close(id)
    },
  },
})
```

## Promise

Use `toast.promise` to update one toast as an asynchronous task moves through
loading, success, and error states.

### Example: toast-promise

```tsx
"use client";

import { Button } from "@workspace/ui/components/button";
import { toast } from "@workspace/ui/components/toast";

export function ToastPromise() {
  function showToast() {
    toast.promise(
      new Promise<{ name: string }>((resolve) => {
        window.setTimeout(() => resolve({ name: "Event" }), 2000);
      }),
      {
        loading: "Creating event…",
        success: (data) => `${data.name} created.`,
        error: "Could not create event.",
      },
    );
  }

  return (
    <Button variant="outline" onClick={showToast}>
      Create Event
    </Button>
  );
}

export default ToastPromise;
```

## API Reference

See the [Base UI Toast documentation](https://base-ui.com/react/components/toast)
for details about manager options, stacking, swipe dismissal, and the primitive
API.

- [Documentation](https://base-ui.com/react/components/toast)
- [API reference](https://base-ui.com/react/components/toast#api-reference)


---

# Toggle

A two-state button that can be either on or off.

Page: https://sui.draco.dev/docs/components/toggle

### Example: toggle-demo

```tsx
import { Toggle } from "@workspace/ui/components/toggle";
import { BookmarkIcon } from "lucide-react";

export function ToggleDemo() {
  return (
    <Toggle aria-label="Toggle bookmark" size="sm" variant="outline">
      <BookmarkIcon className="group-aria-pressed/toggle:fill-current" />
      Bookmark
    </Toggle>
  );
}

export default ToggleDemo;
```

## Installation

```bash
bunx --bun shadcn@latest add @sui/toggle
```

Install with the shadcn CLI or use the shared `@workspace/ui` package. Follow the [installation guide](/docs/installation) to configure the registry, load styles, and choose import aliases.

## Usage

```tsx
import { Toggle } from "@workspace/ui/components/toggle"
```

```tsx
<Toggle>Toggle</Toggle>
```

## Outline

Use `variant="outline"` for an outline style.

### Example: toggle-outline

```tsx
import { Toggle } from "@workspace/ui/components/toggle";
import { BoldIcon, ItalicIcon } from "lucide-react";

export function ToggleOutline() {
  return (
    <div className="flex flex-wrap items-center gap-2">
      <Toggle variant="outline" aria-label="Toggle italic">
        <ItalicIcon />
        Italic
      </Toggle>
      <Toggle variant="outline" aria-label="Toggle bold">
        <BoldIcon />
        Bold
      </Toggle>
    </div>
  );
}

export default ToggleOutline;
```

## With Text

### Example: toggle-text

```tsx
import { Toggle } from "@workspace/ui/components/toggle";
import { ItalicIcon } from "lucide-react";

export function ToggleText() {
  return (
    <Toggle aria-label="Toggle italic">
      <ItalicIcon />
      Italic
    </Toggle>
  );
}

export default ToggleText;
```

## Size

Use the `size` prop to change the size of the toggle.

### Example: toggle-sizes

```tsx
import { Toggle } from "@workspace/ui/components/toggle";

export function ToggleSizes() {
  return (
    <div className="flex flex-wrap items-center gap-2">
      <Toggle variant="outline" aria-label="Toggle small" size="sm">
        Small
      </Toggle>
      <Toggle variant="outline" aria-label="Toggle default" size="default">
        Default
      </Toggle>
      <Toggle variant="outline" aria-label="Toggle large" size="lg">
        Large
      </Toggle>
    </div>
  );
}

export default ToggleSizes;
```

## Disabled

### Example: toggle-disabled

```tsx
import { Toggle } from "@workspace/ui/components/toggle";

export function ToggleDisabled() {
  return (
    <div className="flex flex-wrap items-center gap-2">
      <Toggle aria-label="Toggle disabled" disabled>
        Disabled
      </Toggle>
      <Toggle variant="outline" aria-label="Toggle disabled outline" disabled>
        Disabled
      </Toggle>
    </div>
  );
}

export default ToggleDisabled;
```

## RTL

To enable RTL support in shadcn/ui, see the [RTL configuration guide](https://ui.shadcn.com/docs/rtl).

### Example: toggle-rtl

```tsx
"use client";

import { Toggle } from "@workspace/ui/components/toggle";
import { BookmarkIcon } from "lucide-react";
import { type Translations, useTranslation } from "./support";

const translations: Translations = {
  en: {
    dir: "ltr",
    values: {
      label: "Bookmark",
    },
  },
  ar: {
    dir: "rtl",
    values: {
      label: "إشارة مرجعية",
    },
  },
  he: {
    dir: "rtl",
    values: {
      label: "סימנייה",
    },
  },
};

export function ToggleRtl() {
  const { dir, t } = useTranslation(translations, "ar");

  return (
    <Toggle aria-label="Toggle bookmark" size="sm" variant="outline" dir={dir}>
      <BookmarkIcon className="group-aria-pressed/toggle:fill-current" />
      {t.label}
    </Toggle>
  );
}

export default ToggleRtl;
```

## API Reference

See the [Base UI Toggle](https://base-ui.com/react/components/toggle#api-reference) documentation.

- [Documentation](https://base-ui.com/react/components/toggle)
- [API reference](https://base-ui.com/react/components/toggle#api-reference)


---

# Toggle Group

A set of two-state buttons that can be toggled on or off.

Page: https://sui.draco.dev/docs/components/toggle-group

### Example: toggle-group-demo

```tsx
import {
  ToggleGroup,
  ToggleGroupItem,
} from "@workspace/ui/components/toggle-group";
import { Bold, Italic, Underline } from "lucide-react";

export function ToggleGroupDemo() {
  return (
    <ToggleGroup variant="outline" multiple>
      <ToggleGroupItem value="bold" aria-label="Toggle bold">
        <Bold />
      </ToggleGroupItem>
      <ToggleGroupItem value="italic" aria-label="Toggle italic">
        <Italic />
      </ToggleGroupItem>
      <ToggleGroupItem value="strikethrough" aria-label="Toggle strikethrough">
        <Underline />
      </ToggleGroupItem>
    </ToggleGroup>
  );
}

export default ToggleGroupDemo;
```

## Installation

```bash
bunx --bun shadcn@latest add @sui/toggle-group
```

Install with the shadcn CLI or use the shared `@workspace/ui` package. Follow the [installation guide](/docs/installation) to configure the registry, load styles, and choose import aliases.

## Usage

```tsx
import { ToggleGroup, ToggleGroupItem } from "@workspace/ui/components/toggle-group"
```

```tsx
<ToggleGroup type="single">
  <ToggleGroupItem value="a">A</ToggleGroupItem>
  <ToggleGroupItem value="b">B</ToggleGroupItem>
  <ToggleGroupItem value="c">C</ToggleGroupItem>
</ToggleGroup>
```

## Composition

Use the following composition to build a `ToggleGroup`:

```text
ToggleGroup
├── ToggleGroupItem
└── ToggleGroupItem
```

## Outline

Use `variant="outline"` for an outline style.

### Example: toggle-group-outline

```tsx
import {
  ToggleGroup,
  ToggleGroupItem,
} from "@workspace/ui/components/toggle-group";

export function ToggleGroupOutline() {
  return (
    <ToggleGroup variant="outline" defaultValue={["all"]}>
      <ToggleGroupItem value="all" aria-label="Toggle all">
        All
      </ToggleGroupItem>
      <ToggleGroupItem value="missed" aria-label="Toggle missed">
        Missed
      </ToggleGroupItem>
    </ToggleGroup>
  );
}

export default ToggleGroupOutline;
```

## Size

Use the `size` prop to change the size of the toggle group.

### Example: toggle-group-sizes

```tsx
import {
  ToggleGroup,
  ToggleGroupItem,
} from "@workspace/ui/components/toggle-group";

export function ToggleGroupSizes() {
  return (
    <div className="flex flex-col gap-4">
      <ToggleGroup size="sm" defaultValue={["top"]} variant="outline">
        <ToggleGroupItem value="top" aria-label="Toggle top">
          Top
        </ToggleGroupItem>
        <ToggleGroupItem value="bottom" aria-label="Toggle bottom">
          Bottom
        </ToggleGroupItem>
        <ToggleGroupItem value="left" aria-label="Toggle left">
          Left
        </ToggleGroupItem>
        <ToggleGroupItem value="right" aria-label="Toggle right">
          Right
        </ToggleGroupItem>
      </ToggleGroup>
      <ToggleGroup defaultValue={["top"]} variant="outline">
        <ToggleGroupItem value="top" aria-label="Toggle top">
          Top
        </ToggleGroupItem>
        <ToggleGroupItem value="bottom" aria-label="Toggle bottom">
          Bottom
        </ToggleGroupItem>
        <ToggleGroupItem value="left" aria-label="Toggle left">
          Left
        </ToggleGroupItem>
        <ToggleGroupItem value="right" aria-label="Toggle right">
          Right
        </ToggleGroupItem>
      </ToggleGroup>
    </div>
  );
}

export default ToggleGroupSizes;
```

## Spacing

Use `spacing` to add spacing between toggle group items.

### Example: toggle-group-spacing

```tsx
import {
  ToggleGroup,
  ToggleGroupItem,
} from "@workspace/ui/components/toggle-group";

export function ToggleGroupSpacing() {
  return (
    <ToggleGroup size="sm" defaultValue={["top"]} variant="outline" spacing={2}>
      <ToggleGroupItem value="top" aria-label="Toggle top">
        Top
      </ToggleGroupItem>
      <ToggleGroupItem value="bottom" aria-label="Toggle bottom">
        Bottom
      </ToggleGroupItem>
      <ToggleGroupItem value="left" aria-label="Toggle left">
        Left
      </ToggleGroupItem>
      <ToggleGroupItem value="right" aria-label="Toggle right">
        Right
      </ToggleGroupItem>
    </ToggleGroup>
  );
}

export default ToggleGroupSpacing;
```

## Vertical

Use `orientation="vertical"` for vertical toggle groups.

### Example: toggle-group-vertical

```tsx
import {
  ToggleGroup,
  ToggleGroupItem,
} from "@workspace/ui/components/toggle-group";
import { BoldIcon, ItalicIcon, UnderlineIcon } from "lucide-react";

export function ToggleGroupVertical() {
  return (
    <ToggleGroup
      multiple
      orientation="vertical"
      spacing={1}
      defaultValue={["bold", "italic"]}
    >
      <ToggleGroupItem value="bold" aria-label="Toggle bold">
        <BoldIcon />
      </ToggleGroupItem>
      <ToggleGroupItem value="italic" aria-label="Toggle italic">
        <ItalicIcon />
      </ToggleGroupItem>
      <ToggleGroupItem value="underline" aria-label="Toggle underline">
        <UnderlineIcon />
      </ToggleGroupItem>
    </ToggleGroup>
  );
}

export default ToggleGroupVertical;
```

## Disabled

### Example: toggle-group-disabled

```tsx
import {
  ToggleGroup,
  ToggleGroupItem,
} from "@workspace/ui/components/toggle-group";
import { Bold, Italic, Underline } from "lucide-react";

export function ToggleGroupDisabled() {
  return (
    <ToggleGroup disabled>
      <ToggleGroupItem value="bold" aria-label="Toggle bold">
        <Bold />
      </ToggleGroupItem>
      <ToggleGroupItem value="italic" aria-label="Toggle italic">
        <Italic />
      </ToggleGroupItem>
      <ToggleGroupItem value="strikethrough" aria-label="Toggle strikethrough">
        <Underline />
      </ToggleGroupItem>
    </ToggleGroup>
  );
}

export default ToggleGroupDisabled;
```

## Custom

A custom toggle group example.

### Example: toggle-group-font-weight-selector

```tsx
"use client";

import {
  Field,
  FieldDescription,
  FieldLabel,
} from "@workspace/ui/components/field";
import {
  ToggleGroup,
  ToggleGroupItem,
} from "@workspace/ui/components/toggle-group";
import * as React from "react";

export function ToggleGroupFontWeightSelector() {
  const [fontWeight, setFontWeight] = React.useState("normal");
  return (
    <Field>
      <FieldLabel>Font Weight</FieldLabel>
      <ToggleGroup
        value={[fontWeight]}
        onValueChange={(value) => setFontWeight(value[0])}
        variant="outline"
        spacing={2}
        size="lg"
      >
        <ToggleGroupItem
          value="light"
          aria-label="Light"
          className="flex size-16 flex-col items-center justify-center rounded-xl"
        >
          <span className="font-light text-2xl leading-none">Aa</span>
          <span className="text-muted-foreground text-xs">Light</span>
        </ToggleGroupItem>
        <ToggleGroupItem
          value="normal"
          aria-label="Normal"
          className="flex size-16 flex-col items-center justify-center rounded-xl"
        >
          <span className="font-normal text-2xl leading-none">Aa</span>
          <span className="text-muted-foreground text-xs">Normal</span>
        </ToggleGroupItem>
        <ToggleGroupItem
          value="medium"
          aria-label="Medium"
          className="flex size-16 flex-col items-center justify-center rounded-xl"
        >
          <span className="font-medium text-2xl leading-none">Aa</span>
          <span className="text-muted-foreground text-xs">Medium</span>
        </ToggleGroupItem>
        <ToggleGroupItem
          value="bold"
          aria-label="Bold"
          className="flex size-16 flex-col items-center justify-center rounded-xl"
        >
          <span className="font-bold text-2xl leading-none">Aa</span>
          <span className="text-muted-foreground text-xs">Bold</span>
        </ToggleGroupItem>
      </ToggleGroup>
      <FieldDescription>
        Use{" "}
        <code className="rounded-md bg-muted px-1 py-0.5 font-mono">
          font-{fontWeight}
        </code>{" "}
        to set the font weight.
      </FieldDescription>
    </Field>
  );
}

export default ToggleGroupFontWeightSelector;
```

## RTL

To enable RTL support in shadcn/ui, see the [RTL configuration guide](https://ui.shadcn.com/docs/rtl).

### Example: toggle-group-rtl

```tsx
"use client";

import {
  ToggleGroup,
  ToggleGroupItem,
} from "@workspace/ui/components/toggle-group";
import { type Translations, useTranslation } from "./support";

const translations: Translations = {
  en: {
    dir: "ltr",
    values: {
      list: "List",
      grid: "Grid",
      cards: "Cards",
    },
  },
  ar: {
    dir: "rtl",
    values: {
      list: "قائمة",
      grid: "شبكة",
      cards: "بطاقات",
    },
  },
  he: {
    dir: "rtl",
    values: {
      list: "רשימה",
      grid: "רשת",
      cards: "כרטיסים",
    },
  },
};

export function ToggleGroupRtl() {
  const { dir, t } = useTranslation(translations, "ar");

  return (
    <ToggleGroup variant="outline" defaultValue={["list"]} dir={dir}>
      <ToggleGroupItem value="list" aria-label={t.list}>
        {t.list}
      </ToggleGroupItem>
      <ToggleGroupItem value="grid" aria-label={t.grid}>
        {t.grid}
      </ToggleGroupItem>
      <ToggleGroupItem value="cards" aria-label={t.cards}>
        {t.cards}
      </ToggleGroupItem>
    </ToggleGroup>
  );
}

export default ToggleGroupRtl;
```

## API Reference

See the [Base UI Toggle Group](https://base-ui.com/react/components/toggle-group#api-reference) documentation.

## Changelog

### 2026-05-17 Default Spacing

Changed the default `spacing` from `0` to `2` so toggle groups render with space between items by default. Use `spacing={0}` for connected items.

- [Documentation](https://base-ui.com/react/components/toggle-group)
- [API reference](https://base-ui.com/react/components/toggle-group#api-reference)


---

# Toolbar

Groups related commands and controls with arrow-key focus navigation.

Page: https://sui.draco.dev/docs/components/toolbar

Toolbar gives a set of actions a shared keyboard navigation model. Compose buttons, toggle groups, links, and a final input while keeping each action's own accessible name.

### Example: toolbar-demo

```tsx
import { Toggle } from "@workspace/ui/components/toggle";
import { ToggleGroup } from "@workspace/ui/components/toggle-group";
import {
  Toolbar,
  ToolbarButton,
  ToolbarGroup,
  ToolbarLink,
  ToolbarSeparator,
} from "@workspace/ui/components/toolbar";
import { cn } from "cn";
import {
  BoldIcon,
  ItalicIcon,
  RotateCcwIcon,
  UnderlineIcon,
} from "lucide-react";
import { useState } from "react";
import type { ExampleProps } from "../types";

export default function ToolbarDemo({ locale }: ExampleProps) {
  const chinese = locale === "zh-CN";
  const [formats, setFormats] = useState<string[]>([]);

  return (
    <div className="flex max-w-lg flex-col items-start gap-4">
      <Toolbar
        aria-label={chinese ? "文字格式工具栏" : "Text formatting toolbar"}
      >
        <ToolbarGroup aria-label={chinese ? "文字格式" : "Text formatting"}>
          <ToggleGroup
            multiple
            value={formats}
            onValueChange={setFormats}
            spacing={1}
          >
            <ToolbarButton
              render={<Toggle />}
              value="bold"
              size="icon"
              aria-label={chinese ? "加粗" : "Bold"}
            >
              <BoldIcon />
            </ToolbarButton>
            <ToolbarButton
              render={<Toggle />}
              value="italic"
              size="icon"
              aria-label={chinese ? "斜体" : "Italic"}
            >
              <ItalicIcon />
            </ToolbarButton>
            <ToolbarButton
              render={<Toggle />}
              value="underline"
              size="icon"
              aria-label={chinese ? "下划线" : "Underline"}
            >
              <UnderlineIcon />
            </ToolbarButton>
          </ToggleGroup>
        </ToolbarGroup>
        <ToolbarSeparator />
        <ToolbarButton
          size="icon"
          aria-label={chinese ? "清除格式" : "Reset formatting"}
          onClick={() => setFormats([])}
        >
          <RotateCcwIcon />
        </ToolbarButton>
        <ToolbarLink href={chinese ? "/zh-CN/docs" : "/docs"}>
          {chinese ? "帮助" : "Help"}
        </ToolbarLink>
      </Toolbar>
      <p
        className={cn(
          "text-sm",
          formats.includes("bold") && "font-medium",
          formats.includes("italic") && "italic",
          formats.includes("underline") && "underline",
        )}
      >
        {chinese
          ? "选中文字格式，预览会即时更新"
          : "Choose a text format to update this preview."}
      </p>
    </div>
  );
}
```

## Installation

```bash
bunx --bun shadcn@latest add @sui/toolbar
```

Install with the shadcn CLI or use the shared `@workspace/ui` package. Follow the [installation guide](/docs/installation) to configure the registry, load styles, and choose import aliases.

## Usage

```tsx showLineNumbers
import {
  Toolbar,
  ToolbarButton,
  ToolbarGroup,
  ToolbarSeparator,
} from "@workspace/ui/components/toolbar"

<Toolbar aria-label="Document actions">
  <ToolbarGroup aria-label="Editing actions">
    <ToolbarButton onClick={undo}>Undo</ToolbarButton>
    <ToolbarButton onClick={redo} disabled={!canRedo}>Redo</ToolbarButton>
  </ToolbarGroup>
  <ToolbarSeparator />
  <ToolbarButton onClick={save}>Save</ToolbarButton>
</Toolbar>
```

## Toggle and trigger composition

`ToolbarButton` supports the same `variant` and `size` values as `Button`, defaulting to `ghost` and `default`. Use `render` to compose it with `Toggle`, a menu trigger, or another Base UI control. `ToggleGroup` manages related format choices, while the toolbar coordinates focus among controls.

Use `ToolbarGroup` for related actions and `ToolbarSeparator` between groups. A separator automatically uses the orientation opposite to its toolbar.

## Search input

`ToolbarInput` participates in the toolbar's keyboard model. In a horizontal toolbar, place a single input last so text editing and horizontal focus movement stay predictable. The example filters real notes and moves between the matching results.

### Example: toolbar-search

```tsx
import {
  Toolbar,
  ToolbarButton,
  ToolbarInput,
  ToolbarSeparator,
} from "@workspace/ui/components/toolbar";
import { ArrowDownIcon, ArrowUpIcon } from "lucide-react";
import { useState } from "react";
import type { ExampleProps } from "../types";

export default function ToolbarSearch({ locale }: ExampleProps) {
  const chinese = locale === "zh-CN";
  const noMatchesLabel = chinese ? "没有匹配的笔记" : "No matching notes.";
  const [query, setQuery] = useState("");
  const [position, setPosition] = useState(0);
  const notes = chinese
    ? ["检查键盘交互", "调整组件主题", "更新双语文档", "发布组件示例"]
    : [
        "Check keyboard interactions",
        "Customize component themes",
        "Update bilingual documentation",
        "Publish component examples",
      ];
  const filtered = notes.filter((note) =>
    note.toLocaleLowerCase().includes(query.toLocaleLowerCase()),
  );
  const selected = filtered.length ? position % filtered.length : 0;

  return (
    <div className="flex w-full max-w-md flex-col items-start gap-4">
      <Toolbar aria-label={chinese ? "查找笔记" : "Find notes"}>
        <ToolbarButton
          size="icon"
          aria-label={chinese ? "上一条结果" : "Previous result"}
          disabled={!filtered.length}
          onClick={() =>
            setPosition(
              (current) => (current + filtered.length - 1) % filtered.length,
            )
          }
        >
          <ArrowUpIcon />
        </ToolbarButton>
        <ToolbarButton
          size="icon"
          aria-label={chinese ? "下一条结果" : "Next result"}
          disabled={!filtered.length}
          onClick={() =>
            setPosition((current) => (current + 1) % filtered.length)
          }
        >
          <ArrowDownIcon />
        </ToolbarButton>
        <ToolbarSeparator />
        <ToolbarInput
          aria-label={chinese ? "搜索笔记" : "Search notes"}
          placeholder={chinese ? "搜索笔记…" : "Search notes…"}
          value={query}
          onChange={(event) => {
            setQuery(event.target.value);
            setPosition(0);
          }}
        />
      </Toolbar>
      <output className="text-muted-foreground text-sm" aria-live="polite">
        {filtered.length
          ? `${selected + 1} / ${filtered.length}: ${filtered[selected]}`
          : noMatchesLabel}
      </output>
    </div>
  );
}
```

## Vertical and disabled toolbars

Set `orientation="vertical"` to use a vertical layout and Up/Down focus navigation. `disabled` on `Toolbar` disables button and input controls; `disabled` on `ToolbarGroup` disables a set of actions. Buttons can also be disabled independently.

### Example: toolbar-disabled

```tsx
import { Field, FieldLabel } from "@workspace/ui/components/field";
import { Switch } from "@workspace/ui/components/switch";
import {
  Toolbar,
  ToolbarButton,
  ToolbarGroup,
  ToolbarSeparator,
} from "@workspace/ui/components/toolbar";
import { RotateCcwIcon, ZoomInIcon, ZoomOutIcon } from "lucide-react";
import { useId, useState } from "react";
import type { ExampleProps } from "../types";

export default function ToolbarDisabled({ locale }: ExampleProps) {
  const chinese = locale === "zh-CN";
  const id = useId();
  const [disabled, setDisabled] = useState(true);
  const [zoom, setZoom] = useState(100);

  return (
    <div className="flex flex-col items-start gap-4">
      <Field orientation="horizontal">
        <Switch id={id} checked={disabled} onCheckedChange={setDisabled} />
        <FieldLabel htmlFor={id}>
          {chinese ? "禁用工具栏" : "Disable toolbar"}
        </FieldLabel>
      </Field>
      <div className="flex items-center gap-4">
        <Toolbar
          orientation="vertical"
          disabled={disabled}
          aria-label={chinese ? "缩放工具栏" : "Zoom toolbar"}
        >
          <ToolbarGroup aria-label={chinese ? "调整缩放" : "Adjust zoom"}>
            <ToolbarButton
              size="icon"
              aria-label={chinese ? "放大" : "Zoom in"}
              onClick={() => setZoom((value) => Math.min(200, value + 10))}
              disabled={zoom >= 200}
            >
              <ZoomInIcon />
            </ToolbarButton>
            <ToolbarButton
              size="icon"
              aria-label={chinese ? "缩小" : "Zoom out"}
              onClick={() => setZoom((value) => Math.max(50, value - 10))}
              disabled={zoom <= 50}
            >
              <ZoomOutIcon />
            </ToolbarButton>
          </ToolbarGroup>
          <ToolbarSeparator />
          <ToolbarButton
            size="icon"
            aria-label={chinese ? "重置缩放" : "Reset zoom"}
            onClick={() => setZoom(100)}
          >
            <RotateCcwIcon />
          </ToolbarButton>
        </Toolbar>
        <output className="text-muted-foreground text-sm" aria-live="polite">
          {chinese ? "缩放" : "Zoom"}: {zoom}%
        </output>
      </div>
    </div>
  );
}
```

## Accessibility and keyboard

Give the toolbar an `aria-label` describing its purpose. Label each icon button, and label groups when their purpose adds useful context. Tab enters the toolbar, arrow keys move between its controls, and Tab leaves it. Focus wraps by default; set `loopFocus={false}` to stop at the ends.

Base UI disabled buttons remain focusable by default. Use `focusableWhenDisabled={false}` when disabled controls should be skipped. Keep native event handlers and the `render` composition intact so keyboard activation follows the same path as pointer interaction.

## API reference

| Part | Purpose |
| --- | --- |
| `Toolbar` | Accepts `orientation` (`horizontal` by default), `disabled`, `loopFocus`, normal root props, and `ref`. |
| `ToolbarButton` | A toolbar action with `variant`, `size`, `disabled`, `focusableWhenDisabled`, and `render`. |
| `ToolbarLink` | A navigable link with Button `variant`/`size`, anchor props, and `render`. |
| `ToolbarInput` | A text input integrated with toolbar focus navigation, styled through `Input`. |
| `ToolbarGroup` | Groups related controls and accepts a group-level `disabled` state. |
| `ToolbarSeparator` | Separates groups; its direction follows the toolbar unless explicitly overridden. |

See the [Base UI Toolbar API](https://base-ui.com/react/components/toolbar#api-reference) for all primitive props and keyboard behavior.


---

# Tooltip

A popup that displays information related to an element when the element receives keyboard focus or the mouse hovers over it.

Page: https://sui.draco.dev/docs/components/tooltip

### Example: tooltip-demo

```tsx
import { Button } from "@workspace/ui/components/button";
import {
  Tooltip,
  TooltipContent,
  TooltipTrigger,
} from "@workspace/ui/components/tooltip";

export function TooltipDemo() {
  return (
    <Tooltip>
      <TooltipTrigger render={<Button variant="outline" />}>
        Hover
      </TooltipTrigger>
      <TooltipContent>
        <p>Add to library</p>
      </TooltipContent>
    </Tooltip>
  );
}

export default TooltipDemo;
```

## Installation

```bash
bunx --bun shadcn@latest add @sui/tooltip
```

Install with the shadcn CLI or use the shared `@workspace/ui` package. Follow the [installation guide](/docs/installation) to configure the registry, load styles, and choose import aliases.

## Usage

```tsx showLineNumbers
import {
  Tooltip,
  TooltipContent,
  TooltipTrigger,
} from "@workspace/ui/components/tooltip"
```

```tsx showLineNumbers
<Tooltip>
  <TooltipTrigger>Hover</TooltipTrigger>
  <TooltipContent>
    <p>Add to library</p>
  </TooltipContent>
</Tooltip>
```

## Composition

Use the following composition to build a `Tooltip`:

```text
Tooltip
├── TooltipTrigger
└── TooltipContent
```

## Side

Use the `side` prop to change the position of the tooltip.

### Example: tooltip-sides

```tsx
import { Button } from "@workspace/ui/components/button";
import {
  Tooltip,
  TooltipContent,
  TooltipTrigger,
} from "@workspace/ui/components/tooltip";

export function TooltipSides() {
  return (
    <div className="flex flex-wrap gap-2">
      {(["left", "top", "bottom", "right"] as const).map((side) => (
        <Tooltip key={side}>
          <TooltipTrigger
            render={<Button variant="outline" className="w-fit capitalize" />}
          >
            {side}
          </TooltipTrigger>
          <TooltipContent side={side}>
            <p>Add to library</p>
          </TooltipContent>
        </Tooltip>
      ))}
    </div>
  );
}

export default TooltipSides;
```

## With Keyboard Shortcut

### Example: tooltip-keyboard

```tsx
import { Button } from "@workspace/ui/components/button";
import { Kbd } from "@workspace/ui/components/kbd";
import {
  Tooltip,
  TooltipContent,
  TooltipTrigger,
} from "@workspace/ui/components/tooltip";
import { SaveIcon } from "lucide-react";

export function TooltipKeyboard() {
  return (
    <Tooltip>
      <TooltipTrigger render={<Button variant="outline" size="icon-sm" />}>
        <SaveIcon />
      </TooltipTrigger>
      <TooltipContent>
        Save Changes <Kbd>S</Kbd>
      </TooltipContent>
    </Tooltip>
  );
}

export default TooltipKeyboard;
```

## Disabled Button

Show a tooltip on a disabled button by wrapping it with a span.

### Example: tooltip-disabled

```tsx
import { Button } from "@workspace/ui/components/button";
import {
  Tooltip,
  TooltipContent,
  TooltipTrigger,
} from "@workspace/ui/components/tooltip";

export function TooltipDisabled() {
  return (
    <Tooltip>
      <TooltipTrigger render={<span className="inline-block w-fit" />}>
        <Button variant="outline" disabled>
          Disabled
        </Button>
      </TooltipTrigger>
      <TooltipContent>
        <p>This feature is currently unavailable</p>
      </TooltipContent>
    </Tooltip>
  );
}

export default TooltipDisabled;
```

## RTL

To enable RTL support in shadcn/ui, see the [RTL configuration guide](https://ui.shadcn.com/docs/rtl).

### Example: tooltip-rtl

```tsx
"use client";

import { Button } from "@workspace/ui/components/button";
import {
  Tooltip,
  TooltipContent,
  TooltipTrigger,
} from "@workspace/ui/components/tooltip";
import { type Translations, useTranslation } from "./support";

const translations: Translations = {
  en: {
    dir: "ltr",
    values: {
      content: "Add to library",
      "inline-start": "Inline Start",
      left: "Left",
      top: "Top",
      bottom: "Bottom",
      right: "Right",
      "inline-end": "Inline End",
    },
  },
  ar: {
    dir: "rtl",
    values: {
      content: "إضافة إلى المكتبة",
      "inline-start": "بداية السطر",
      left: "يسار",
      top: "أعلى",
      bottom: "أسفل",
      right: "يمين",
      "inline-end": "نهاية السطر",
    },
  },
  he: {
    dir: "rtl",
    values: {
      content: "הוסף לספרייה",
      "inline-start": "תחילת השורה",
      left: "שמאל",
      top: "למעלה",
      bottom: "למטה",
      right: "ימין",
      "inline-end": "סוף השורה",
    },
  },
};

const physicalSides = ["left", "top", "bottom", "right"] as const;
const logicalSides = ["inline-start", "inline-end"] as const;

export function TooltipRtl() {
  const { dir, t } = useTranslation(translations, "ar");

  return (
    <div className="grid gap-4">
      <div className="flex flex-wrap justify-center gap-2">
        {physicalSides.map((side) => (
          <Tooltip key={side}>
            <TooltipTrigger render={<Button variant="outline" />}>
              {t[side]}
            </TooltipTrigger>
            <TooltipContent side={side} dir={dir}>
              {t.content}
            </TooltipContent>
          </Tooltip>
        ))}
      </div>
      <div className="flex flex-wrap justify-center gap-2">
        {logicalSides.map((side) => (
          <Tooltip key={side}>
            <TooltipTrigger render={<Button variant="outline" />}>
              {t[side]}
            </TooltipTrigger>
            <TooltipContent side={side} dir={dir}>
              {t.content}
            </TooltipContent>
          </Tooltip>
        ))}
      </div>
    </div>
  );
}

export default TooltipRtl;
```

## API Reference

See the [Base UI Tooltip](https://base-ui.com/react/components/tooltip#api-reference) documentation.

- [Documentation](https://base-ui.com/react/components/tooltip)
- [API reference](https://base-ui.com/react/components/tooltip#api-reference)


---

# DataTable

A shared table block with search, filters, column settings, selection, pagination, and drag sorting.

Page: https://sui.draco.dev/docs/blocks/data-table

DataTable composes SUI's [Table](/docs/components/table), Input, Combobox, Checkbox, Badge, Empty, Skeleton, and Pagination. Use the Table component directly for simple markup.

## Search, filters, sorting, and column controls

Search uses column metadata and the Search button or Enter. Column settings support visibility, pinning, and ordering. Density changes row spacing. Open a sortable header menu to choose ascending, descending, clear sorting, or hide the column.

### Example: block-table-demo

```tsx
import {
  DataTable,
  type DataTableColumnDef,
  DataTableColumnSettings,
  DataTableDensity,
  DataTableSearch,
} from "@workspace/ui/blocks/data-table";
import type { ExampleProps } from "../types";
import { chineseTableLabels } from "./block-table-labels";

type RecordRow = { id: string; name: string; status: string; amount: number };
const rows: RecordRow[] = Array.from({ length: 24 }, (_, index) => ({
  id: `R-${String(index + 1).padStart(3, "0")}`,
  name: ["Orion", "Northwind", "Atlas", "Nimbus"][index % 4],
  status: index % 3 === 0 ? "Draft" : "Active",
  amount: (index + 1) * 125,
}));

export default function TableBlockDemo({ locale }: ExampleProps) {
  const zh = locale === "zh-CN";
  const columns: DataTableColumnDef<RecordRow>[] = [
    { accessorKey: "id", header: "ID", meta: { pinned: "start" } },
    {
      accessorKey: "name",
      header: zh ? "名称" : "Name",
      meta: { search: { placeholder: zh ? "搜索名称" : "Search names" } },
    },
    {
      accessorKey: "status",
      header: zh ? "状态" : "Status",
      meta: {
        filter: {
          multiple: true,
          placeholder: zh ? "筛选状态" : "Filter status",
          options: [
            { label: zh ? "草稿" : "Draft", value: "Draft" },
            { label: zh ? "启用" : "Active", value: "Active" },
          ],
        },
      },
    },
    {
      accessorKey: "amount",
      header: zh ? "金额" : "Amount",
      cell: ({ getValue }) => `$${Number(getValue()).toFixed(2)}`,
      meta: { align: "end" },
    },
  ];
  return (
    <DataTable
      columns={columns}
      data={rows}
      rowKey="id"
      layout="auto"
      label={zh ? "项目列表" : "Projects"}
      className="w-full"
      labels={zh ? chineseTableLabels : undefined}
    >
      {({
        content,
        table,
        tableSize,
        onTableSizeChange,
        labels,
        loading,
        defaultColumnOrder,
        defaultColumnPinning,
      }) => (
        <>
          <div className="flex shrink-0 flex-col gap-3">
            <div className="flex flex-wrap items-center justify-end gap-2">
              <DataTableDensity
                value={tableSize}
                onValueChange={onTableSizeChange}
                disabled={loading}
                labels={labels}
              />
              <DataTableColumnSettings
                table={table}
                defaultColumnOrder={defaultColumnOrder}
                defaultColumnPinning={defaultColumnPinning}
                disabled={loading}
                labels={labels}
              />
            </div>
            <DataTableSearch table={table} disabled={loading} labels={labels} />
          </div>

          {content}
        </>
      )}
    </DataTable>
  );
}
```

## Free composition and independent controls

Refresh, column settings, and density are independently exported block controls. The table has no business header slot. Compose `DataTableRefresh`, `DataTableColumnSettings`, `DataTableDensity`, and `DataTableSearch` in the `children` render callback. It provides the table, density and setter, refresh callback, loading state, labels, default column settings, and `content`. The content includes column headers, rows, loading states, pagination, and bulk actions; arrange your title, search, and controls around it.

### Example: block-table-header

```tsx
import {
  DataTable,
  type DataTableColumnDef,
  DataTableColumnSettings,
  DataTableDensity,
  DataTableRefresh,
  DataTableSearch,
  type DataTableState,
} from "@workspace/ui/blocks/data-table";
import { Badge } from "@workspace/ui/components/badge";
import { Button } from "@workspace/ui/components/button";
import { useState } from "react";
import type { ExampleProps } from "../types";
import { chineseTableLabels } from "./block-table-labels";

type Project = { id: string; name: string; amount: number };
const records: Project[] = Array.from({ length: 18 }, (_, index) => ({
  id: `P-${index + 1}`,
  name: `Project ${index + 1}`,
  amount: (index + 1) * 125,
}));
async function request(state: DataTableState) {
  await new Promise((resolve) => setTimeout(resolve, 350));
  const query = String(
    state.columnFilters.find((filter) => filter.id === "name")?.value ?? "",
  ).toLowerCase();
  const rows = records.filter((row) => row.name.toLowerCase().includes(query));
  const sort = state.sorting[0];
  if (sort)
    rows.sort(
      (a, b) =>
        String(a[sort.id as keyof Project]).localeCompare(
          String(b[sort.id as keyof Project]),
          undefined,
          { numeric: true },
        ) * (sort.desc ? -1 : 1),
    );
  const start = state.pagination.pageIndex * state.pagination.pageSize;
  return {
    data: rows.slice(start, start + state.pagination.pageSize),
    total: rows.length,
  };
}

export default function TableHeader({ locale }: ExampleProps) {
  const zh = locale === "zh-CN";
  const [message, setMessage] = useState("");
  const columns: DataTableColumnDef<Project>[] = [
    { accessorKey: "id", header: "ID", meta: { pinned: "start" } },
    {
      accessorKey: "name",
      header: zh ? "项目名称" : "Project name",
      meta: {
        search: { placeholder: zh ? "搜索项目名称" : "Search Project name" },
      },
    },
    {
      accessorKey: "amount",
      header: zh ? "金额" : "Amount",
      cell: ({ getValue }) => `$${Number(getValue()).toFixed(2)}`,
      meta: { align: "end" },
    },
  ];
  return (
    <div className="flex w-full min-w-0 flex-col gap-3">
      <DataTable
        columns={columns}
        request={request}
        rowKey="id"
        labels={zh ? chineseTableLabels : undefined}
      >
        {({
          content,
          table,
          tableSize,
          onTableSizeChange,
          refresh,
          loading,
          labels,
          defaultColumnOrder,
          defaultColumnPinning,
        }) => (
          <>
            <div className="flex shrink-0 flex-wrap items-center justify-between gap-3">
              <div className="flex min-w-0 items-center gap-2">
                <h3 className="font-medium text-base">
                  {zh ? "项目列表" : "Projects"}
                </h3>
                <Badge variant="secondary">{table.getRowCount()}</Badge>
                {refresh && (
                  <DataTableRefresh
                    onRefresh={refresh}
                    loading={loading}
                    labels={labels}
                  />
                )}
              </div>
              <DataTableSearch
                table={table}
                disabled={loading}
                labels={labels}
                layout="inline"
                className="ms-auto"
              />
              <div className="ms-auto flex items-center gap-2">
                <DataTableColumnSettings
                  table={table}
                  defaultColumnOrder={defaultColumnOrder}
                  defaultColumnPinning={defaultColumnPinning}
                  disabled={loading}
                  labels={labels}
                />
                <DataTableDensity
                  value={tableSize}
                  onValueChange={onTableSizeChange}
                  disabled={loading}
                  labels={labels}
                />
                <Button
                  size="sm"
                  onClick={() =>
                    setMessage(
                      zh
                        ? "新建操作由应用处理"
                        : "The app handles the create action",
                    )
                  }
                >
                  {zh ? "新建项目" : "New project"}
                </Button>
              </div>
            </div>
            {content}
          </>
        )}
      </DataTable>
      <p role="status" className="text-muted-foreground text-sm">
        {message ||
          (zh
            ? "刷新放在标题旁，搜索与操作按钮同一行，窄屏自动换行。"
            : "Refresh sits next to the title; search and app actions share the row and wrap on narrow screens.")}
      </p>
    </div>
  );
}
```

## Search placement and layout

`DataTableSearch` can share a row with a title or actions, occupy its own row, or appear after `content`. Use `className` for placement and width. `layout="inline"` keeps inputs, filters, and actions together with wrapping; the default `layout="stacked"` retains stacked controls on narrow screens and separates fields from actions on desktop.

The basic example uses a separate search row, and the composition example places it next to the title. Here search and status filters follow the table and pagination, aligned with `className="justify-end"`. Editing conditions changes the draft; Search or Enter applies it, and Reset clears it.

### Example: block-table-search

```tsx
import {
  DataTable,
  type DataTableColumnDef,
  DataTableSearch,
} from "@workspace/ui/blocks/data-table";
import { Badge } from "@workspace/ui/components/badge";
import type { ExampleProps } from "../types";
import { chineseTableLabels } from "./block-table-labels";

type Project = { id: string; name: string; status: string };
const records: Project[] = Array.from({ length: 8 }, (_, index) => ({
  id: `R-${index + 1}`,
  name: ["Orion", "Northwind", "Atlas", "Nimbus"][index % 4],
  status: index < 4 ? "Active" : "Draft",
}));

export default function TableSearch({ locale }: ExampleProps) {
  const zh = locale === "zh-CN";
  const stateLabels = {
    active: zh ? "启用" : "Active",
    draft: zh ? "草稿" : "Draft",
  };
  const columns: DataTableColumnDef<Project>[] = [
    { accessorKey: "id", header: "ID" },
    {
      accessorKey: "name",
      header: zh ? "名称" : "Name",
      meta: { search: { placeholder: zh ? "搜索名称" : "Search names" } },
    },
    {
      accessorKey: "status",
      header: zh ? "状态" : "Status",
      cell: ({ getValue }) => (
        <Badge variant="secondary">
          {getValue() === "Active" ? stateLabels.active : stateLabels.draft}
        </Badge>
      ),
      meta: {
        filter: {
          multiple: true,
          placeholder: zh ? "筛选状态" : "Filter status",
          options: [
            { value: "Active", label: zh ? "启用" : "Active" },
            { value: "Draft", label: zh ? "草稿" : "Draft" },
          ],
        },
      },
    },
  ];
  return (
    <DataTable
      columns={columns}
      data={records}
      rowKey="id"
      className="w-full"
      labels={zh ? chineseTableLabels : undefined}
    >
      {({ content, table, loading, labels }) => (
        <>
          {content}
          <DataTableSearch
            table={table}
            disabled={loading}
            labels={labels}
            layout="inline"
            className="justify-end"
          />
        </>
      )}
    </DataTable>
  );
}
```

## Selection, row actions, and bulk actions

Add a `select` column using SUI Checkbox. The `bulkToolbar` callback receives selected rows and the table instance. Utility columns `select` and `drag` pin to the start; `actions` and `operation` pin to the end.

### Example: block-table-selection

```tsx
import {
  DataTable,
  type DataTableColumnDef,
} from "@workspace/ui/blocks/data-table";
import { Button } from "@workspace/ui/components/button";
import { Checkbox } from "@workspace/ui/components/checkbox";
import { useState } from "react";
import type { ExampleProps } from "../types";
import { chineseTableLabels } from "./block-table-labels";

type Member = { id: string; name: string; email: string };
const members: Member[] = [
  { id: "1", name: "Alex Chen", email: "alex@example.com" },
  { id: "2", name: "Sam Rivera", email: "sam@example.com" },
  { id: "3", name: "Jordan Lee", email: "jordan@example.com" },
];

export default function TableSelection({ locale }: ExampleProps) {
  const zh = locale === "zh-CN";
  const [message, setMessage] = useState("");
  const columns: DataTableColumnDef<Member>[] = [
    {
      id: "select",
      header: ({ table }) => (
        <Checkbox
          aria-label={zh ? "选择当前页" : "Select page"}
          checked={table.getIsAllPageRowsSelected()}
          indeterminate={table.getIsSomePageRowsSelected()}
          onCheckedChange={(value) => table.toggleAllPageRowsSelected(value)}
        />
      ),
      cell: ({ row }) => (
        <Checkbox
          aria-label={`${zh ? "选择" : "Select"} ${row.original.name}`}
          checked={row.getIsSelected()}
          onCheckedChange={(value) => row.toggleSelected(value)}
        />
      ),
      enableSorting: false,
    },
    { accessorKey: "name", header: zh ? "姓名" : "Name" },
    { accessorKey: "email", header: zh ? "邮箱" : "Email" },
    {
      id: "actions",
      header: zh ? "操作" : "Actions",
      cell: ({ row }) => (
        <Button
          size="sm"
          variant="ghost"
          onClick={() =>
            setMessage(`${zh ? "已查看" : "Viewed"} ${row.original.name}`)
          }
        >
          {zh ? "查看" : "View"}
        </Button>
      ),
    },
  ];
  return (
    <div className="flex w-full flex-col gap-3">
      <DataTable
        columns={columns}
        data={members}
        rowKey="id"
        layout="auto"
        pagination={false}
        bulkToolbar={({ selectedRows, table }) => (
          <Button
            size="sm"
            onClick={() => {
              setMessage(
                `${zh ? "已导出" : "Exported"} ${selectedRows.length}`,
              );
              table.resetRowSelection();
            }}
          >
            {zh ? "导出所选" : "Export selected"}
          </Button>
        )}
        labels={
          zh
            ? {
                ...chineseTableLabels,
                bulkClearSelection: "清除选择",
                bulkAnnouncement: (count) => `已选择 ${count} 行`,
              }
            : undefined
        }
      />
      <p role="status" className="text-muted-foreground text-sm">
        {message}
      </p>
    </div>
  );
}
```

## Pinned columns, grouped headers, and alignment

Combine selection, long text, centered status, end-aligned amounts, and row actions. Try density settings and drag mode. `layout="full"` scrolls within a constrained height; grouped headers stick at their measured offsets and pinned cells share the row's hover and selection surface.

This example has two header levels: Project groups ID and Domain, while Details groups Status and Amount. The upper row names the groups and the lower row names the columns. Flat column definitions produce a single header row.

### Example: block-table-layout

```tsx
import {
  DataTable,
  type DataTableColumnDef,
  DataTableColumnSettings,
  DataTableDensity,
} from "@workspace/ui/blocks/data-table";
import { Badge } from "@workspace/ui/components/badge";
import { Button } from "@workspace/ui/components/button";
import { Checkbox } from "@workspace/ui/components/checkbox";
import { LongText } from "@workspace/ui/components/long-text";
import { useState } from "react";
import type { ExampleProps } from "../types";
import { chineseTableLabels } from "./block-table-labels";

type Project = { id: string; name: string; status: string; amount: number };
const initialRows: Project[] = Array.from({ length: 18 }, (_, index) => ({
  id: String(index + 1),
  name: `production-api-gateway-${index + 1}.asia-east-1.example.com`,
  status: index % 3 === 0 ? "Draft" : "Active",
  amount: (index + 1) * 125,
}));

export default function TableLayout({ locale }: ExampleProps) {
  const zh = locale === "zh-CN";
  const stateLabels = zh
    ? {
        draft: "草稿",
        active: "启用",
        disableDrag: "关闭拖拽",
        enableDrag: "启用拖拽",
      }
    : {
        draft: "Draft",
        active: "Active",
        disableDrag: "Disable drag",
        enableDrag: "Enable drag",
      };
  const [rows, setRows] = useState(initialRows);
  const [drag, setDrag] = useState(false);
  const [message, setMessage] = useState("");
  const columns: DataTableColumnDef<Project>[] = [
    {
      id: "select",
      header: ({ table }) => (
        <Checkbox
          aria-label={zh ? "选择当前页" : "Select page"}
          checked={table.getIsAllPageRowsSelected()}
          indeterminate={table.getIsSomePageRowsSelected()}
          onCheckedChange={(checked) =>
            table.toggleAllPageRowsSelected(checked)
          }
        />
      ),
      cell: ({ row }) => (
        <Checkbox
          aria-label={`${zh ? "选择" : "Select"} ${row.original.id}`}
          checked={row.getIsSelected()}
          onCheckedChange={(checked) => row.toggleSelected(checked)}
        />
      ),
      enableSorting: false,
    },
    {
      id: "project",
      header: zh ? "项目" : "Project",
      meta: { align: "center" },
      columns: [
        {
          accessorKey: "id",
          header: "ID",
          size: 64,
          meta: { pinned: "start", align: "center" },
        },
        {
          accessorKey: "name",
          header: zh ? "域名" : "Domain",
          cell: ({ getValue }) => (
            <LongText className="w-48">{String(getValue())}</LongText>
          ),
        },
      ],
    },
    {
      id: "details",
      header: zh ? "详情" : "Details",
      meta: { align: "center" },
      columns: [
        {
          accessorKey: "status",
          header: zh ? "状态" : "Status",
          cell: ({ getValue }) => (
            <Badge variant="secondary">
              {getValue() === "Draft" ? stateLabels.draft : stateLabels.active}
            </Badge>
          ),
          meta: { align: "center" },
        },
        {
          accessorKey: "amount",
          header: zh ? "金额" : "Amount",
          cell: ({ getValue }) => (
            <span className="tabular-nums">
              ${Number(getValue()).toFixed(2)}
            </span>
          ),
          meta: { align: "end" },
        },
      ],
    },
    {
      id: "actions",
      header: zh ? "操作" : "Actions",
      size: 96,
      cell: ({ row }) => (
        <Button
          variant="ghost"
          size="sm"
          onClick={() =>
            setMessage(`${zh ? "已查看" : "Viewed"} ${row.original.id}`)
          }
        >
          {zh ? "查看" : "View"}
        </Button>
      ),
    },
  ];
  return (
    <div className="flex w-full min-w-0 flex-col gap-3">
      <div className="h-104 min-h-0">
        <DataTable
          columns={columns}
          data={rows}
          rowKey="id"
          layout="full"
          dragSort={drag ? { rowKey: "id", onDragSortEnd: setRows } : false}
          table={{ stickyHeader: true }}
          bulkToolbar={({ selectedRows, table }) => (
            <Button
              size="sm"
              onClick={() => {
                setMessage(
                  `${zh ? "已导出" : "Exported"} ${selectedRows.length}`,
                );
                table.resetRowSelection();
              }}
            >
              {zh ? "导出所选" : "Export selected"}
            </Button>
          )}
          labels={
            zh
              ? {
                  ...chineseTableLabels,
                  bulkClearSelection: "清除选择",
                }
              : undefined
          }
        >
          {({
            content,
            table,
            tableSize,
            onTableSizeChange,
            labels,
            loading,
            defaultColumnOrder,
            defaultColumnPinning,
          }) => (
            <>
              <div className="flex shrink-0 flex-wrap items-center justify-between gap-3">
                <Button
                  variant="outline"
                  size="sm"
                  aria-pressed={drag}
                  onClick={() => setDrag((value) => !value)}
                >
                  {drag ? stateLabels.disableDrag : stateLabels.enableDrag}
                </Button>
                <div className="flex items-center gap-2">
                  <DataTableDensity
                    value={tableSize}
                    onValueChange={onTableSizeChange}
                    disabled={loading}
                    labels={labels}
                  />
                  <DataTableColumnSettings
                    table={table}
                    defaultColumnOrder={defaultColumnOrder}
                    defaultColumnPinning={defaultColumnPinning}
                    disabled={loading}
                    labels={labels}
                  />
                </div>
              </div>

              {content}
            </>
          )}
        </DataTable>
      </div>
      <p role="status" className="text-muted-foreground text-sm">
        {message ||
          (zh
            ? "横向滚动检查固定列，纵向滚动检查分组表头。"
            : "Scroll horizontally to check pinned columns and vertically to check grouped headers.")}
      </p>
    </div>
  );
}
```

## Drag sorting and empty state

Supply stable row IDs and handle the reordered records. Drag sorting disables sorting and pagination to keep displayed order consistent. The handle also supports keyboard dragging: Space to pick up, arrow keys to move, and Space to drop.

### Example: block-table-drag

```tsx
import {
  DataTable,
  type DataTableColumnDef,
} from "@workspace/ui/blocks/data-table";
import { Button } from "@workspace/ui/components/button";
import { useState } from "react";
import type { ExampleProps } from "../types";
import { chineseTableLabels } from "./block-table-labels";

type Task = { id: string; name: string };
const initialRows: Task[] = [
  { id: "1", name: "Design tokens" },
  { id: "2", name: "Component library" },
  { id: "3", name: "Documentation" },
  { id: "4", name: "Release checklist" },
];
export default function TableDrag({ locale }: ExampleProps) {
  const zh = locale === "zh-CN";
  const stateLabels = zh
    ? {
        empty: "显示空状态",
        restore: "恢复数据",
      }
    : {
        empty: "Show empty state",
        restore: "Restore rows",
      };
  const [rows, setRows] = useState(initialRows);
  const columns: DataTableColumnDef<Task>[] = [
    { accessorKey: "id", header: "ID" },
    { accessorKey: "name", header: zh ? "任务" : "Task" },
  ];
  return (
    <div className="flex w-full flex-col gap-3">
      <Button
        size="sm"
        variant="outline"
        className="w-fit"
        onClick={() =>
          setRows((current) => (current.length ? [] : initialRows))
        }
      >
        {rows.length ? stateLabels.empty : stateLabels.restore}
      </Button>
      <DataTable
        columns={columns}
        data={rows}
        rowKey="id"
        dragSort={{ rowKey: "id", onDragSortEnd: setRows }}
        pagination={false}
        layout="auto"
        labels={
          zh
            ? {
                ...chineseTableLabels,
                noData: "暂无任务",
              }
            : undefined
        }
      />
      <p role="status" className="text-muted-foreground text-sm">
        {rows.map((row) => row.name).join(" → ")}
      </p>
    </div>
  );
}
```

## Requested data

Provide a stable `request` callback returning `{ data, total }`. The callback receives pagination, sorting, and column filters; it applies those operations on the server. Late responses from previous requests are ignored. This example uses a local asynchronous adapter. Without `total`, pagination uses sequential controls and stops after a short page. Compose `DataTableRefresh` in the header to reload requested data. Request failures offer retry.

### Example: block-table-request

```tsx
import {
  DataTable,
  type DataTableColumnDef,
  DataTableRefresh,
  DataTableSearch,
  type DataTableState,
} from "@workspace/ui/blocks/data-table";
import { Button } from "@workspace/ui/components/button";
import { useCallback, useState } from "react";
import type { ExampleProps } from "../types";
import { chineseTableLabels } from "./block-table-labels";

type RecordRow = { id: string; name: string };
const records: RecordRow[] = Array.from({ length: 28 }, (_, index) => ({
  id: `R-${index + 1}`,
  name: `Project ${index + 1}`,
}));
// Replace this local adapter with your API; pagination and sorting run in the request.
async function request(state: DataTableState) {
  const query = String(
    state.columnFilters.find((filter) => filter.id === "name")?.value ?? "",
  ).toLowerCase();
  const rows = records.filter((row) => row.name.toLowerCase().includes(query));
  const sort = state.sorting[0];
  if (sort)
    rows.sort(
      (a, b) =>
        String(a[sort.id as keyof RecordRow]).localeCompare(
          String(b[sort.id as keyof RecordRow]),
          undefined,
          { numeric: true },
        ) * (sort.desc ? -1 : 1),
    );
  const start = state.pagination.pageIndex * state.pagination.pageSize;
  return {
    data: rows.slice(start, start + state.pagination.pageSize),
    total: rows.length,
  };
}
export default function TableRequest({ locale }: ExampleProps) {
  const zh = locale === "zh-CN";
  const stateLabels = zh
    ? {
        includeTotal: "返回总数",
        omitTotal: "省略总数",
      }
    : {
        includeTotal: "Include total",
        omitTotal: "Omit total",
      };
  const [unknownTotal, setUnknownTotal] = useState(false);
  const load = useCallback(
    async (state: DataTableState) => {
      await new Promise((resolve) => setTimeout(resolve, 250));
      const result = await request(state);
      return unknownTotal ? { data: result.data } : result;
    },
    [unknownTotal],
  );
  const columns: DataTableColumnDef<RecordRow>[] = [
    { accessorKey: "id", header: "ID" },
    {
      accessorKey: "name",
      header: zh ? "项目" : "Project",
      meta: { search: { placeholder: zh ? "搜索项目" : "Search projects" } },
    },
  ];
  return (
    <div className="flex w-full flex-col gap-3">
      <Button
        variant="outline"
        size="sm"
        className="w-fit"
        aria-pressed={unknownTotal}
        onClick={() => setUnknownTotal((value) => !value)}
      >
        {unknownTotal ? stateLabels.includeTotal : stateLabels.omitTotal}
      </Button>
      <DataTable
        columns={columns}
        request={load}
        rowKey="id"
        layout="auto"
        className="w-full"
        labels={zh ? chineseTableLabels : undefined}
      >
        {({ content, table, refresh, loading, labels }) => (
          <>
            <div className="flex shrink-0 flex-col gap-3">
              <div className="flex justify-end">
                {refresh && (
                  <DataTableRefresh
                    onRefresh={refresh}
                    loading={loading}
                    labels={labels}
                  />
                )}
              </div>
              <DataTableSearch
                table={table}
                disabled={loading}
                labels={labels}
              />
            </div>

            {content}
          </>
        )}
      </DataTable>
    </div>
  );
}
```

## Loading, empty, and failed requests

First load uses SUI Skeleton. Existing rows remain under a centered loading overlay; empty and failed requests use SUI Empty. Override messages through `labels`.

### Example: block-table-states

```tsx
import {
  DataTable,
  type DataTableColumnDef,
} from "@workspace/ui/blocks/data-table";
import { Button } from "@workspace/ui/components/button";
import { useCallback, useRef, useState } from "react";
import type { ExampleProps } from "../types";
import { chineseTableLabels } from "./block-table-labels";

type RecordRow = { id: string; name: string };
export default function TableStates({ locale }: ExampleProps) {
  const zh = locale === "zh-CN";
  const [fail, setFail] = useState(false);
  const failOnce = useRef(true);
  const request = useCallback(async () => {
    if (failOnce.current) {
      failOnce.current = false;
      throw new Error("Demo request failed");
    }
    return { data: [{ id: "1", name: "Recovered project" }] };
  }, []);
  const columns: DataTableColumnDef<RecordRow>[] = [
    { accessorKey: "id", header: "ID" },
    { accessorKey: "name", header: zh ? "名称" : "Name" },
  ];
  return (
    <div className="flex w-full flex-col gap-4">
      <DataTable
        columns={columns}
        loading={{ rows: 3 }}
        labels={zh ? chineseTableLabels : undefined}
        layout="auto"
        pagination={false}
      />
      <Button
        variant="outline"
        className="w-fit"
        onClick={() => {
          failOnce.current = true;
          setFail((value) => !value);
        }}
      >
        {zh ? "切换空状态 / 加载失败" : "Toggle empty / failed request"}
      </Button>
      <DataTable
        key={String(fail)}
        columns={columns}
        data={[]}
        request={fail ? request : undefined}
        layout="auto"
        pagination={false}
        labels={zh ? chineseTableLabels : undefined}
      />
    </div>
  );
}
```

## Installation

```bash
bunx --bun shadcn@latest add @sui/data-table
```

Install this Block with the shadcn CLI command above. Follow the [installation guide](/docs/installation) for registry, dependency, and style setup. The examples below use workspace imports; registry-installed source uses the aliases configured in the consuming application's `components.json`.

## Usage

```tsx
import { DataTable, DataTableSearch, type DataTableColumnDef } from "@workspace/ui/blocks/data-table"

type Project = { id: string; name: string }
const columns: DataTableColumnDef<Project>[] = [
  { accessorKey: "id", header: "ID" },
  { accessorKey: "name", header: "Name", meta: { search: true } },
]

<DataTable
  columns={columns}
  data={[{ id: "1", name: "SUI" }]}
  rowKey="id"
  layout="auto"
  label="Projects"
>
  {({ table, loading, labels, content }) => (
    <>
      <DataTableSearch table={table} disabled={loading} labels={labels} />
      {content}
    </>
  )}
</DataTable>
```

## API

| Prop | Description |
| --- | --- |
| `columns`, `data` | TanStack Table v9 columns and local records. |
| `rowKey` | A record key or function returning a stable ID. Required for reliable selection and dragging. |
| `request` | Receives `DataTableState`, returns `{ data, total? }` synchronously or asynchronously. |
| `initialState`, `onChange` | Initial pagination, sorting, and column filters, and change notifications. |
| `children` | Render callback receiving table state and `content` for caller-owned layout. Omit it to render just the table content. |
| `bulkToolbar` | Content or render callbacks receiving `DataTableRenderContext` with table, rows, selection, density and setter, refresh, loading, labels, and default column settings. |
| `pagination` | Set `false` to show all local rows. |
| `dragSort` | `{ rowKey, onDragSortEnd }`; consumers store the resulting order. |
| `loading` | Boolean or `{ rows }` for first-load skeleton count; existing rows use a centered loading overlay. |
| `layout` | `auto` for content height; `full` for a constrained application container. |
| `table` | `{ stickyHeader, manual, pinning }`; `manual` skips local filtering and pagination, while sorting stays local. |
| `labels`, `label` | Partial `TableLabels` overrides and the accessible table name. Controls default to English; translations are supplied by your application. |

Column metadata supports `search`, `filter: { options, multiple, onFilter }`, `align`, and `pinned`. Use `useDataTableUrlState` to connect pagination, sorting, and filters to your router's search parameters without importing a router into the UI package.

## Composition

The shared block also exports `DataTableRefresh`, `DataTableColumnSettings`, `DataTableDensity`, `DataTableColumnHeader`, `DataTableFacetedFilter`, `DataTableSearch`, `DataTablePagination`, and `DataTableBulkActions`. They accept the typed table or column instance from `@workspace/ui/blocks/data-table/types`.

`DataTableDensity` uses controlled `value`/`onValueChange`; `DataTableRefresh` uses `onRefresh`/`loading`.

Their separation follows the [shadcn-admin data-table patterns](https://github.com/satnaing/shadcn-admin/tree/main/src/components/data-table), adapted to SUI Base UI components and TanStack Table v9.

### Application translations

The block ships English defaults only and has no locale or i18n dependency. Keep translations in your application and pass a partial `TableLabels` object through `labels`. Function labels such as `searchPlaceholder`, `paginationPage`, `paginationTotalRows`, and `bulkAnnouncement` let your application handle interpolation and plural rules. Pass the resolved `labels` from the render callback to composed controls so they use the same translations.

```tsx
<DataTable
  columns={columns}
  data={rows}
  labels={{ search: t("table.search"), noData: t("table.empty"), paginationPage: (page) => t("table.page", { page }) }}
/>
```


---

# Delete Resource

Resource name confirmation with asynchronous deletion, pending state, and retryable errors.

Page: https://sui.draco.dev/docs/blocks/delete-resource

Inspired by [Kumo Delete Resource](https://kumo-ui.com/blocks/delete-resource/), this block composes SUI AlertDialog, Field, Input, and Button. It requires the resource name before invoking the deletion callback.

## Name confirmation

Open the dialog and type `sui-preview`. The destructive action enables only when the input matches. Deletion keeps controls disabled until the callback finishes. The resource name in the confirmation hint has an inline copy action. Copying does not populate the confirmation field or submit the form; it is disabled during deletion.

### Example: block-delete-resource

```tsx
import { DeleteResource } from "@workspace/ui/blocks/delete-resource";
import { Button } from "@workspace/ui/components/button";
import { useState } from "react";
import type { ExampleProps } from "../types";

export default function DeleteResourceDemo({ locale }: ExampleProps) {
  const zh = locale === "zh-CN";
  const [open, setOpen] = useState(false);
  const [deleted, setDeleted] = useState(false);
  return (
    <div className="flex flex-col items-center gap-3">
      <Button
        variant="destructive"
        onClick={() => {
          setDeleted(false);
          setOpen(true);
        }}
      >
        {zh ? "删除项目" : "Delete project"}
      </Button>
      <DeleteResource
        open={open}
        onOpenChange={setOpen}
        resourceType="project"
        resourceName="sui-preview"
        onDelete={async () => {
          await new Promise((resolve) => setTimeout(resolve, 600));
          setDeleted(true);
        }}
        labels={
          zh
            ? {
                title: "删除项目？",
                description: "将永久删除 sui-preview，此操作无法撤销。",
                confirmation: "项目名称",
                copy: "复制资源名称",
                copying: "正在复制…",
                copied: "已复制",
                copyFailed: "复制失败，请选择名称手动复制。",
                hint: "输入 sui-preview 确认删除。",
                delete: "删除项目",
                cancel: "取消",
                deleting: "正在删除…",
              }
            : undefined
        }
      />
      {deleted && (
        <p role="status" className="text-muted-foreground text-sm">
          {zh ? "项目已删除" : "Project deleted"}
        </p>
      )}
    </div>
  );
}
```

## Failure and retry

The first attempt fails in this example. The dialog preserves the confirmation, displays the error, and allows a second attempt. Reopening clears the previous confirmation and error.

### Example: block-delete-resource-error

```tsx
import { DeleteResource } from "@workspace/ui/blocks/delete-resource";
import { Button } from "@workspace/ui/components/button";
import { useRef, useState } from "react";
import type { ExampleProps } from "../types";

export default function DeleteResourceError({ locale }: ExampleProps) {
  const zh = locale === "zh-CN";
  const [open, setOpen] = useState(false);
  const attempts = useRef(0);
  return (
    <>
      <Button
        variant="destructive"
        onClick={() => {
          attempts.current = 0;
          setOpen(true);
        }}
      >
        {zh ? "删除并重试" : "Delete with retry"}
      </Button>
      <DeleteResource
        open={open}
        onOpenChange={setOpen}
        resourceType="worker"
        resourceName="api-gateway"
        onDelete={async () => {
          await new Promise((resolve) => setTimeout(resolve, 600));
          attempts.current += 1;
          if (attempts.current === 1)
            throw new Error(
              zh
                ? "暂时无法删除。请重试。"
                : "Unable to delete right now. Please try again.",
            );
        }}
        labels={
          zh
            ? {
                title: "删除 Worker？",
                description: "将永久删除 api-gateway，此操作无法撤销。",
                confirmation: "Worker 名称",
                copy: "复制资源名称",
                copying: "正在复制…",
                copied: "已复制",
                copyFailed: "复制失败，请选择名称手动复制。",
                hint: "输入 api-gateway 确认删除。",
                delete: "删除 Worker",
                cancel: "取消",
                deleting: "正在删除…",
              }
            : undefined
        }
      />
    </>
  );
}
```

## Case-insensitive confirmation

Set `caseSensitive={false}` when confirmation should ignore letter case.

### Example: block-delete-resource-insensitive

```tsx
import { DeleteResource } from "@workspace/ui/blocks/delete-resource";
import { Button } from "@workspace/ui/components/button";
import { useState } from "react";
import type { ExampleProps } from "../types";

export default function DeleteResourceInsensitive({ locale }: ExampleProps) {
  const zh = locale === "zh-CN";
  const [open, setOpen] = useState(false);
  return (
    <>
      <Button variant="destructive" onClick={() => setOpen(true)}>
        {zh ? "删除域名" : "Delete domain"}
      </Button>
      <DeleteResource
        open={open}
        onOpenChange={setOpen}
        resourceType="domain"
        resourceName="Example.com"
        caseSensitive={false}
        onDelete={() => {}}
        labels={
          zh
            ? {
                title: "删除域名？",
                description: "将永久删除 Example.com，此操作无法撤销。",
                confirmation: "域名",
                copy: "复制资源名称",
                copying: "正在复制…",
                copied: "已复制",
                copyFailed: "复制失败，请选择名称手动复制。",
                hint: "输入 Example.com 确认，不区分大小写。",
                delete: "删除域名",
                cancel: "取消",
              }
            : { hint: "Type Example.com to confirm (case insensitive)." }
        }
      />
    </>
  );
}
```

## Installation

```bash
bunx --bun shadcn@latest add @sui/delete-resource
```

Install this Block with the shadcn CLI command above. Follow the [installation guide](/docs/installation) for registry, dependency, and style setup. The examples below use workspace imports; registry-installed source uses the aliases configured in the consuming application's `components.json`.

## Usage

```tsx
import { DeleteResource } from "@workspace/ui/blocks/delete-resource"

<DeleteResource
  open={open}
  onOpenChange={setOpen}
  resourceType="project"
  resourceName="sui-preview"
  onDelete={async () => { await deleteProject("sui-preview") }}
/>
```

The block keeps English defaults. Resolve translations in your application and pass them through `labels`; translate any callback error messages there too.

## API

| Prop | Default | Description |
| --- | --- | --- |
| `open`, `onOpenChange` | Required | Controlled visibility. |
| `resourceType`, `resourceName` | Required | Resource identity and confirmation target. Empty names cannot be confirmed. |
| `onDelete` | Required | Sync or async deletion callback. Resolve on success; throw on failure. |
| `caseSensitive` | `true` | Whether confirmation distinguishes case. Whitespace must match exactly. |
| `isDeleting` | `false` | Optional external pending state; combined with internal submission state. |
| `errorMessage` | — | Optional error from the application. |
| `description` | Generated | Custom explanatory content. |
| `labels` | English | Override title, description, confirmation, hint, cancel, delete, deleting, failed, copy, copying, copied, and copyFailed text. |
| `className` | — | Dialog layout classes. |

On success the block calls `onOpenChange(false)`. On failure it stays open. Duplicate submission and closing are blocked while deletion is pending. The application owns the actual delete operation; these previews only simulate it.


---

# TanStack Form

Validated report and profile forms composed from SUI fields and TanStack Form.

Page: https://sui.draco.dev/docs/blocks/tanstack-form

These shared blocks follow the [shadcn TanStack Form guide](https://ui.shadcn.com/docs/forms/tanstack-form), using SUI FieldGroup, Field, Input, Select, Checkbox, and Zod schemas. Validation runs on blur and submit. Invalid controls expose `aria-invalid` and associate errors with their fields.

## Bug report

Try submitting an empty report, then enter a title of 5–80 characters and a description of 20–500 characters. Successful submission displays feedback. Reset restores the initial values.

### Example: block-form-report

```tsx
import { BugReportForm } from "@workspace/ui/blocks/tanstack-form";
import { useState } from "react";
import type { ExampleProps } from "../types";
import { chineseBugReportFormLabels } from "./block-form-labels";

export default function ReportForm({ locale }: ExampleProps) {
  const [submitted, setSubmitted] = useState("");
  return (
    <div className="flex w-full max-w-md flex-col gap-3">
      <BugReportForm
        labels={locale === "zh-CN" ? chineseBugReportFormLabels : undefined}
        onSubmit={async (values) => {
          await new Promise((resolve) => setTimeout(resolve, 600));
          setSubmitted(values.title);
        }}
      />
      {submitted && (
        <p className="text-muted-foreground text-sm" role="status">
          {submitted}
        </p>
      )}
    </div>
  );
}
```

## Profile, select, and checkbox

This composition adds email validation, a role selector, and notification preferences. Toggle the failure simulation to check retry behavior.

### Example: block-form-profile

```tsx
import { ProfileForm } from "@workspace/ui/blocks/tanstack-form";
import { Button } from "@workspace/ui/components/button";
import { useState } from "react";
import type { ExampleProps } from "../types";
import { chineseProfileFormLabels } from "./block-form-labels";

export default function ProfileFormDemo({ locale }: ExampleProps) {
  const [fail, setFail] = useState(false);
  const zh = locale === "zh-CN";
  const stateLabels = zh
    ? {
        disableError: "关闭失败模拟",
        simulateError: "模拟提交失败",
      }
    : {
        disableError: "Disable error simulation",
        simulateError: "Simulate submission failure",
      };
  return (
    <div className="flex w-full max-w-md flex-col gap-3">
      <ProfileForm
        labels={locale === "zh-CN" ? chineseProfileFormLabels : undefined}
        initialValues={{
          name: "Alex Chen",
          email: "alex@example.com",
          role: "developer",
        }}
        onSubmit={async () => {
          await new Promise((resolve) => setTimeout(resolve, 600));
          if (fail)
            throw new Error(
              zh ? "保存失败，请重试。" : "Could not save. Please try again.",
            );
        }}
      />
      <Button
        variant="outline"
        aria-pressed={fail}
        onClick={() => setFail((value) => !value)}
      >
        {fail ? stateLabels.disableError : stateLabels.simulateError}
      </Button>
    </div>
  );
}
```

## Installation

```bash
bunx --bun shadcn@latest add @sui/tanstack-form
```

Install this Block with the shadcn CLI command above. Follow the [installation guide](/docs/installation) for registry, dependency, and style setup. The examples below use workspace imports; registry-installed source uses the aliases configured in the consuming application's `components.json`.

## Usage

```tsx
import { BugReportForm, ProfileForm } from "@workspace/ui/blocks/tanstack-form"

<BugReportForm onSubmit={async (values) => { await saveReport(values) }} />
<ProfileForm
  initialValues={{ name: "Alex", email: "alex@example.com", role: "developer" }}
  onSubmit={async (values) => { await saveProfile(values) }}
/>
```

The blocks keep English defaults and do not select a language. Your application can resolve translations with its own i18n system and pass them through `labels`:

```tsx
<BugReportForm
  labels={{ formTitle: t("report.title"), submit: t("report.submit"), titleMinLength: t("report.titleMinLength") }}
  onSubmit={saveReport}
/>
```

## API

| Prop | Description |
| --- | --- |
| `onSubmit` | Required callback; accepts validated values and can return a promise. Throw an error to show failure feedback and allow retry. |
| `initialValues` | Initial field values; Reset restores them. |
| `labels` | Partial `BugReportFormLabels` or `ProfileFormLabels`. Defaults to English; provide translations from your application. |
| `className` | Card layout classes. |

`BugReportValues` contains `title` and `description`. `ProfileValues` contains `name`, `email`, `role`, and `notifications`. Buttons and controls are disabled during submission. Both forms generate independent IDs, so multiple copies can share a page.

Both label types include `formTitle`, `formDescription`, `submit`, `submitting`, `reset`, `failed`, `saved`, `savedDescription`, and `submitError` (fallback for non-Error submission failures). Error messages thrown by your callback are displayed directly, so translate them in your application too.

`BugReportFormLabels` also includes `title`, `titlePlaceholder`, `description`, `descriptionHint`, `titleMinLength`, `titleMaxLength`, `descriptionMinLength`, and `descriptionMaxLength`. `ProfileFormLabels` also includes `name`, `email`, `role`, `rolePlaceholder`, `designerRole`, `developerRole`, `managerRole`, `notifications`, `nameMinLength`, `nameMaxLength`, `invalidEmail`, and `invalidRole`. Provide all keys for a fully translated form, or override individual keys while keeping the remaining English defaults.


---

# Utilities

CSS effects for scroll containers and loading text, included in SUI’s shared styles.

Page: https://sui.draco.dev/docs/utils

SUI includes two CSS utilities from the shared shadcn styles. They use Tailwind CSS v4 classes and work with plain HTML or existing SUI components.

- [Scroll fade](/docs/utils/scroll-fade) masks overflowing content at the scrollable edges, with vertical, horizontal, and logical RTL variants.
- [Shimmer](/docs/utils/shimmer) adds a text highlight that follows the reading direction and respects reduced motion.

Both are loaded through `@workspace/ui/globals.css`. Each page includes runnable examples, copyable source, class references, accessibility guidance, and browser fallbacks.


---

# Scroll fade

Utilities for adding a fade effect to the edges of a scroll container.

Page: https://sui.draco.dev/docs/utils/scroll-fade

### Example: scroll-fade-demo

```tsx
// biome-ignore-all lint/a11y/noNoninteractiveTabindex: These named scroll viewports need keyboard access.
import type { ExampleProps } from "../types";
export default function ScrollFadeDemo({ locale }: ExampleProps = {}) {
  const chinese = locale === "zh-CN";
  return (
    <div className="mx-auto w-full max-w-xs overflow-hidden rounded-[14px] ring-1 ring-border">
      <section
        tabIndex={0}
        aria-label={chinese ? "可滚动条目" : "Scrollable items"}
        className="scroll-fade no-scrollbar h-72 overflow-y-auto"
      >
        <div className="flex flex-col gap-1.5 p-1.5">
          {Array.from({ length: 12 }, (_, index) => index + 1).map(
            (itemNumber) => (
              <div
                key={itemNumber}
                className="rounded-lg bg-muted px-3 py-2.5 text-sm"
              >
                {chinese ? "条目" : "Item"} {itemNumber}
              </div>
            ),
          )}
        </div>
      </section>
    </div>
  );
}
```

## Installation

Follow the [installation guide](/docs/installation). Both utilities are included when you import SUI’s global styles:

```css
@import "@workspace/ui/globals.css";
```

The utilities use the existing `shadcn/tailwind.css` import in `globals.css`; no additional stylesheet or React component is needed.

## Usage

| Class                             | Styles                                                                                                              |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `scroll-fade`                     | `mask-image: var(--scroll-fade-mask, var(--scroll-fade-block));`  `animation-timeline: scroll(self y);`       |
| `scroll-fade-y`                   | `mask-image: var(--scroll-fade-mask, var(--scroll-fade-block));`  `animation-timeline: scroll(self y);`       |
| `scroll-fade-x`                   | `mask-image: var(--scroll-fade-mask, var(--scroll-fade-inline));`  `animation-timeline: scroll(self inline);` |
| `scroll-fade-t`                   | Fade mask on the top edge.  `animation-timeline: scroll(self y);`                                             |
| `scroll-fade-b`                   | Fade mask on the bottom edge.  `animation-timeline: scroll(self y);`                                          |
| `scroll-fade-l`                   | Fade mask on the left edge.  `animation-timeline: scroll(self x);`                                            |
| `scroll-fade-r`                   | Fade mask on the right edge.  `animation-timeline: scroll(self x);`                                           |
| `scroll-fade-s`                   | Fade mask on the start edge, mirrors in RTL.  `animation-timeline: scroll(self inline);`                      |
| `scroll-fade-e`                   | Fade mask on the end edge, mirrors in RTL.  `animation-timeline: scroll(self inline);`                        |
| `scroll-fade-<number>`            | `--scroll-fade-size: calc(var(--spacing) * <number>);`                                                              |
| `scroll-fade-[<value>]`           | `--scroll-fade-size: <value>;`                                                                                      |
| `scroll-fade-{t,b,s,e}-<number>`  | `--scroll-fade-{t,b,s,e}-size: calc(var(--spacing) * <number>);`                                                    |
| `scroll-fade-{t,b,s,e}-[<value>]` | `--scroll-fade-{t,b,s,e}-size: <value>;`                                                                            |
| `scroll-fade-none`                | `--scroll-fade-mask: none;`                                                                                         |

Add `scroll-fade` or `scroll-fade-y` to the scroll container, i.e. the element that has `overflow-y-auto`.

```tsx
<div className="scroll-fade overflow-y-auto">{/* ... */}</div>
```

The fade is scroll-aware and tracks the scroll position:

- At rest, the top edge is crisp and the bottom edge fades to hint at more content.
- As you scroll, a fade appears at the top and both edges stay faded mid-scroll.
- At the end, the bottom edge sharpens to show you have reached the last item.

The fade is applied with `mask-image`, so it dissolves the content itself rather than overlaying a color. The mask uses a linear fade from transparent to black, so it adapts to any background without configuration. If your scroll area sits inside a card, put the background and border on a wrapper and `scroll-fade` on the inner scroller, so the fade dissolves the content and not the card.

The [`ScrollArea`](/docs/components/scroll-area) and [`MessageScroller`](/docs/components/message-scroller) components can use `scroll-fade` on their scrollable viewport.

## No overflow

In browsers with scroll-driven animation support, content that does not overflow has no fade. You can apply `scroll-fade` without checking the scroll size. The static fallback described below still fades the selected edges.

### Example: scroll-fade-overflow

```tsx
// biome-ignore-all lint/a11y/noNoninteractiveTabindex: These named scroll viewports need keyboard access.
import type { ExampleProps } from "../types";
export default function ScrollFadeOverflow({ locale }: ExampleProps = {}) {
  const chinese = locale === "zh-CN";
  return (
    <div className="mx-auto w-full max-w-xs overflow-hidden rounded-[14px] ring-1 ring-border">
      <section
        tabIndex={0}
        aria-label={chinese ? "可滚动条目" : "Scrollable items"}
        className="scroll-fade no-scrollbar overflow-y-auto"
      >
        <div className="flex flex-col gap-1.5 p-1.5">
          {Array.from({ length: 3 }, (_, index) => index + 1).map(
            (itemNumber) => (
              <div
                key={itemNumber}
                className="rounded-lg bg-muted px-3 py-2.5 text-sm"
              >
                {chinese ? "条目" : "Item"} {itemNumber}
              </div>
            ),
          )}
        </div>
      </section>
    </div>
  );
}
```

## Horizontal scrolling

Use `scroll-fade-x` on containers that scroll horizontally, i.e. the element that has `overflow-x-auto`.

### Example: scroll-fade-horizontal

```tsx
// biome-ignore-all lint/a11y/noNoninteractiveTabindex: These named scroll viewports need keyboard access.
import type { ExampleProps } from "../types";

const tags = [
  ["Design", "设计"],
  ["Engineering", "工程"],
  ["Marketing", "市场"],
  ["Product", "产品"],
  ["Research", "研究"],
  ["Sales", "销售"],
  ["Support", "支持"],
  ["Operations", "运营"],
  ["Finance", "财务"],
  ["Legal", "法务"],
  ["People", "人力"],
  ["Security", "安全"],
];

export default function ScrollFadeHorizontal({ locale }: ExampleProps = {}) {
  const chinese = locale === "zh-CN";
  return (
    <div className="mx-auto w-full max-w-xs overflow-hidden rounded-[14px] ring-1 ring-border">
      <section
        tabIndex={0}
        aria-label={chinese ? "可滚动条目" : "Scrollable items"}
        className="scroll-fade-x no-scrollbar overflow-x-auto"
      >
        <div className="flex w-max gap-1.5 p-1.5">
          {tags.map(([tag, chineseTag]) => (
            <div
              key={chinese ? chineseTag : tag}
              className="shrink-0 rounded-lg bg-muted px-3 py-2.5 text-sm"
            >
              {chinese ? chineseTag : tag}
            </div>
          ))}
        </div>
      </section>
    </div>
  );
}
```

```tsx
<div className="flex scroll-fade-x overflow-x-auto">{/* ... */}</div>
```

The horizontal fade is direction-aware. In RTL layouts, the crisp edge and the fade follow the reading direction with no extra classes needed. `scroll-fade-<number>` and `scroll-fade-none` work the same for both axes.

## Edge fades

Use edge utilities when only one edge should track the scroll position.

### Example: scroll-fade-edge

```tsx
// biome-ignore-all lint/a11y/noNoninteractiveTabindex: These named scroll viewports need keyboard access.
import type { ExampleProps } from "../types";

const items = [
  ["Inbox triage", "收件箱整理"],
  ["Design review", "设计评审"],
  ["API contract", "API 约定"],
  ["QA pass", "质量检查"],
  ["Launch notes", "发布说明"],
  ["Metrics follow-up", "指标回顾"],
];

const tags = [
  ["Design", "设计"],
  ["Engineering", "工程"],
  ["Marketing", "市场"],
  ["Product", "产品"],
  ["Research", "研究"],
  ["Sales", "销售"],
  ["Support", "支持"],
  ["Operations", "运营"],
];

export default function ScrollFadeEdge({ locale }: ExampleProps = {}) {
  const chinese = locale === "zh-CN";
  return (
    <div className="mx-auto flex min-w-0 max-w-xs flex-col gap-6">
      <div className="flex flex-col gap-3">
        <div className="overflow-hidden rounded-[14px] ring-1 ring-border">
          <section
            tabIndex={0}
            aria-label={chinese ? "可滚动条目" : "Scrollable items"}
            className="scroll-fade-t no-scrollbar h-36 overflow-y-auto"
          >
            <ScrollFadeEdgeItems locale={locale} />
          </section>
        </div>
        <p className="text-center font-mono text-[0.9em] text-muted-foreground">
          scroll-fade-t
        </p>
      </div>
      <div className="flex flex-col gap-3">
        <div className="overflow-hidden rounded-[14px] ring-1 ring-border">
          <section
            tabIndex={0}
            aria-label={chinese ? "可滚动条目" : "Scrollable items"}
            className="scroll-fade-b no-scrollbar h-36 overflow-y-auto"
          >
            <ScrollFadeEdgeItems locale={locale} />
          </section>
        </div>
        <p className="text-center font-mono text-[0.9em] text-muted-foreground">
          scroll-fade-b
        </p>
      </div>
      <div className="flex flex-col gap-3">
        <div className="overflow-hidden rounded-[14px] ring-1 ring-border">
          <section
            tabIndex={0}
            aria-label={chinese ? "可滚动条目" : "Scrollable items"}
            className="scroll-fade-s no-scrollbar overflow-x-auto"
          >
            <ScrollFadeEdgeTags locale={locale} />
          </section>
        </div>
        <p className="text-center font-mono text-[0.9em] text-muted-foreground">
          scroll-fade-s
        </p>
      </div>
      <div className="flex flex-col gap-3">
        <div className="overflow-hidden rounded-[14px] ring-1 ring-border">
          <section
            tabIndex={0}
            aria-label={chinese ? "可滚动条目" : "Scrollable items"}
            className="scroll-fade-e no-scrollbar overflow-x-auto"
          >
            <ScrollFadeEdgeTags locale={locale} />
          </section>
        </div>
        <p className="text-center font-mono text-[0.9em] text-muted-foreground">
          scroll-fade-e
        </p>
      </div>
    </div>
  );
}

function ScrollFadeEdgeItems({ locale }: ExampleProps) {
  const chinese = locale === "zh-CN";
  return (
    <div className="flex flex-col gap-1.5 p-1.5">
      {items.map(([item, chineseItem]) => (
        <div
          key={chinese ? chineseItem : item}
          className="rounded-lg bg-muted px-3 py-2.5 text-sm"
        >
          {chinese ? chineseItem : item}
        </div>
      ))}
    </div>
  );
}

function ScrollFadeEdgeTags({ locale }: ExampleProps) {
  const chinese = locale === "zh-CN";
  return (
    <div className="flex w-max gap-1.5 p-1.5">
      {tags.map(([tag, chineseTag]) => (
        <div
          key={chinese ? chineseTag : tag}
          className="shrink-0 rounded-lg bg-muted px-3 py-2.5 text-sm"
        >
          {chinese ? chineseTag : tag}
        </div>
      ))}
    </div>
  );
}
```

```tsx
<div className="scroll-fade-b overflow-y-auto">{/* ... */}</div>
```

The edge utilities are scroll-aware. Start edges fade in after you scroll away from the start, and end edges fade out when you reach the end. Use `scroll-fade-t`, `scroll-fade-b`, `scroll-fade-l`, and `scroll-fade-r` for physical edges. Use `scroll-fade-s` and `scroll-fade-e` for logical inline edges that mirror in RTL.

## Fade size

The fade depth defaults to `12%` of the container, capped at `40px` so tall scrollers stay subtle. Use `scroll-fade-<number>` to set a fixed size on the spacing scale instead, the same way `scroll-mt-<number>` works.

### Example: scroll-fade-size

```tsx
// biome-ignore-all lint/a11y/noNoninteractiveTabindex: These named scroll viewports need keyboard access.
import type { ExampleProps } from "../types";
export default function ScrollFadeSize({ locale }: ExampleProps = {}) {
  const chinese = locale === "zh-CN";
  return (
    <div className="mx-auto flex w-full max-w-xs flex-col gap-6">
      <div className="flex flex-col gap-3">
        <div className="overflow-hidden rounded-[14px] ring-1 ring-border">
          <section
            tabIndex={0}
            aria-label={chinese ? "可滚动条目" : "Scrollable items"}
            className="scroll-fade no-scrollbar scroll-fade-4 h-48 overflow-y-auto"
          >
            <ScrollFadeSizeItems locale={locale} />
          </section>
        </div>
        <p className="text-center font-mono text-[0.9em] text-muted-foreground">
          scroll-fade-4
        </p>
      </div>
      <div className="flex flex-col gap-3">
        <div className="overflow-hidden rounded-[14px] ring-1 ring-border">
          <section
            tabIndex={0}
            aria-label={chinese ? "可滚动条目" : "Scrollable items"}
            className="scroll-fade no-scrollbar scroll-fade-24 h-48 overflow-y-auto"
          >
            <ScrollFadeSizeItems locale={locale} />
          </section>
        </div>
        <p className="text-center font-mono text-[0.9em] text-muted-foreground">
          scroll-fade-24
        </p>
      </div>
    </div>
  );
}

function ScrollFadeSizeItems({ locale }: ExampleProps) {
  const chinese = locale === "zh-CN";
  return (
    <div className="flex flex-col gap-1.5 p-1.5">
      {Array.from({ length: 8 }, (_, index) => index + 1).map((itemNumber) => (
        <div
          key={itemNumber}
          className="rounded-lg bg-muted px-3 py-2.5 text-sm"
        >
          {chinese ? "条目" : "Item"} {itemNumber}
        </div>
      ))}
    </div>
  );
}
```

```tsx
<div className="scroll-fade overflow-y-auto scroll-fade-24">{/* ... */}</div>
```

For one-off values, use an arbitrary length or percentage:

```tsx
<div className="scroll-fade overflow-y-auto scroll-fade-[15%]">{/* ... */}</div>
```

To fade opposite edges by different amounts, use the per-edge modifiers `scroll-fade-t-<number>`, `scroll-fade-b-<number>`, `scroll-fade-s-<number>`, and `scroll-fade-e-<number>`. They override `scroll-fade-<number>` on the edge they target and accept arbitrary values too.

```tsx
<div className="scroll-fade overflow-y-auto scroll-fade-b-8 scroll-fade-t-2">
  {/* ... */}
</div>
```

Use the logical `s`/`e` modifiers for horizontal scrollers so the sizes mirror in RTL.

The fade eases in and out over a fixed scroll distance rather than appearing instantly. That distance is the `--scroll-fade-reveal` variable, `96px` by default and independent of the fade depth. Lower it for a snappier reveal or raise it for a more gradual one:

```tsx
<div className="scroll-fade overflow-y-auto [--scroll-fade-reveal:64px]">
  {/* ... */}
</div>
```

## Disabling the fade

Use `scroll-fade-none` to remove the fade. It works in any class order, so the typical use is responsive or stateful:

```tsx
<div className="scroll-fade overflow-y-auto md:scroll-fade-none">
  {/* ... */}
</div>
```

### Example: scroll-fade-none

```tsx
// biome-ignore-all lint/a11y/noNoninteractiveTabindex: These named scroll viewports need keyboard access.
import type { ExampleProps } from "../types";
export default function ScrollFadeNone({ locale }: ExampleProps = {}) {
  const chinese = locale === "zh-CN";
  return (
    <div className="mx-auto flex min-w-0 max-w-xs flex-col gap-6">
      <div className="flex flex-col gap-3">
        <div className="overflow-hidden rounded-[14px] ring-1 ring-border">
          <section
            tabIndex={0}
            aria-label={chinese ? "可滚动条目" : "Scrollable items"}
            className="scroll-fade no-scrollbar h-48 overflow-y-auto"
          >
            <ScrollFadeNoneItems locale={locale} />
          </section>
        </div>
        <p className="text-center font-mono text-[0.9em] text-muted-foreground">
          scroll-fade
        </p>
      </div>
      <div className="flex flex-col gap-3">
        <div className="overflow-hidden rounded-[14px] ring-1 ring-border">
          <section
            tabIndex={0}
            aria-label={chinese ? "可滚动条目" : "Scrollable items"}
            className="scroll-fade no-scrollbar scroll-fade-none h-48 overflow-y-auto"
          >
            <ScrollFadeNoneItems locale={locale} />
          </section>
        </div>
        <p className="text-center font-mono text-[0.9em] text-muted-foreground">
          scroll-fade scroll-fade-none
        </p>
      </div>
    </div>
  );
}

function ScrollFadeNoneItems({ locale }: ExampleProps) {
  const chinese = locale === "zh-CN";
  return (
    <div className="flex flex-col gap-1.5 p-1.5">
      {Array.from({ length: 8 }, (_, index) => index + 1).map((itemNumber) => (
        <div
          key={itemNumber}
          className="rounded-lg bg-muted px-3 py-2.5 text-sm"
        >
          {chinese ? "条目" : "Item"} {itemNumber}
        </div>
      ))}
    </div>
  );
}
```

## Fallback

The scroll-aware behavior is implemented with [CSS scroll-driven animations](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_scroll-driven_animations), with no JavaScript and no scroll listeners. In browsers that do not support scroll-driven animations, `scroll-fade` falls back to a static fade on both edges, and edge utilities fall back to a static fade on the selected edge.

Since the mask is applied to the scroll container itself, a visible scrollbar fades with the content at the edges. Pair `scroll-fade` with `no-scrollbar`, which ships in the same package, if you want to hide the scrollbar entirely.

## RTL

Set `dir="rtl"` on the container or use SUI’s [DirectionProvider](/docs/components/direction).

`scroll-fade-x` follows the reading direction. At rest, the start edge is crisp and the end edge fades. In RTL layouts that means a crisp right edge and a fade on the left, mirrored from LTR.

### Example: scroll-fade-rtl

```tsx
// biome-ignore-all lint/a11y/noNoninteractiveTabindex: These named scroll viewports need keyboard access.
import type { ExampleProps } from "../types";

const tags = [
  "تصميم",
  "هندسة",
  "تسويق",
  "منتج",
  "أبحاث",
  "مبيعات",
  "دعم",
  "عمليات",
  "مالية",
  "قانوني",
];
export default function ScrollFadeRtl({ locale }: ExampleProps = {}) {
  const chinese = locale === "zh-CN";
  return (
    <div
      className="mx-auto w-full max-w-xs overflow-hidden rounded-[14px] ring-1 ring-border"
      dir="rtl"
    >
      <section
        tabIndex={0}
        aria-label={chinese ? "从右到左滚动" : "Right-to-left scrolling"}
        className="scroll-fade-x no-scrollbar overflow-x-auto"
      >
        <div className="flex w-max gap-1.5 p-1.5">
          {tags.map((tag) => (
            <div
              key={tag}
              className="shrink-0 rounded-lg bg-muted px-3 py-2.5 text-sm"
            >
              {tag}
            </div>
          ))}
        </div>
      </section>
    </div>
  );
}
```

## Accessibility

Keep important controls outside the masked edges. Give a plain scrolling viewport `tabIndex={0}` and an accessible name when it needs keyboard access. The utility changes only the visual mask: it does not remove content from the accessibility tree or trap focus. Set the viewport’s background and frame on an outer wrapper.


---

# Shimmer

Utilities for adding a shimmer effect to text elements.

Page: https://sui.draco.dev/docs/utils/shimmer

### Example: shimmer-demo

```tsx
import type { ExampleProps } from "../types";
export default function ShimmerDemo({ locale }: ExampleProps = {}) {
  const chinese = locale === "zh-CN";
  return (
    <p className="shimmer text-muted-foreground text-sm">
      {chinese ? "正在生成回复…" : "Generating response…"}
    </p>
  );
}
```

## Installation

Follow the [installation guide](/docs/installation). Both utilities are included when you import SUI’s global styles:

```css
@import "@workspace/ui/globals.css";
```

The utilities use the existing `shadcn/tailwind.css` import in `globals.css`; no additional stylesheet or React component is needed.

## Usage

| Class                         | Styles                                                                                               |
| ----------------------------- | ---------------------------------------------------------------------------------------------------- |
| `shimmer`                     | `background-clip: text;`  `animation: tw-shimmer var(--shimmer-duration, 2s) linear infinite;` |
| `shimmer-once`                | `animation-iteration-count: 1;`                                                                      |
| `shimmer-reverse`             | `animation-direction: reverse;`                                                                      |
| `shimmer-none`                | `--shimmer-image: none;`  `--shimmer-text-fill: currentColor;`                                 |
| `shimmer-color-<color>`       | `--shimmer-color: <color>;`                                                                          |
| `shimmer-color-[<value>]`     | `--shimmer-color: <value>;`                                                                          |
| `shimmer-color-<color>/<pct>` | `--shimmer-color: color-mix(in oklch, <color> <pct>, transparent);`                                  |
| `shimmer-duration-<number>`   | `--shimmer-duration: calc(<number> * 1ms);`                                                          |
| `shimmer-spread-<number>`     | `--shimmer-spread: calc(var(--spacing) * <number>);`                                                 |
| `shimmer-spread-[<value>]`    | `--shimmer-spread: <value>;`                                                                         |
| `shimmer-angle-<number>`      | `--shimmer-angle: calc(<number> * 1deg);`                                                            |

Add `shimmer` to a text element.

```tsx
<p className="shimmer text-muted-foreground">Generating response&hellip;</p>
```

The shimmer is built on `currentColor`, so it adapts to the element:

- The highlight is derived from the text color, with no configuration needed.
- It works on any color, from `text-muted-foreground` to brand colors.
- In dark mode, the highlight automatically brightens to stay visible.

The effect is pure CSS. The text is painted with `background-clip: text`, and the highlight sweeps across it in a seamless loop.

## With Marker

The shimmer composes with any component that renders text. A common pattern is a [Marker](/docs/components/marker) showing a live status while the assistant is working:

### Example: shimmer-marker

```tsx
import { Loader } from "@workspace/ui/components/loader";
import {
  Marker,
  MarkerContent,
  MarkerIcon,
} from "@workspace/ui/components/marker";
import type { ExampleProps } from "../types";

export default function ShimmerMarker({ locale }: ExampleProps = {}) {
  const chinese = locale === "zh-CN";
  return (
    <div className="flex w-full max-w-sm flex-col gap-4">
      <Marker role="status">
        <MarkerIcon>
          <Loader size="sm" label={chinese ? "正在思考" : "Thinking"} />
        </MarkerIcon>
        <MarkerContent className="shimmer">
          {chinese ? "正在思考…" : "Thinking…"}
        </MarkerContent>
      </Marker>
      <Marker variant="separator" role="status">
        <MarkerContent className="shimmer">
          {chinese ? "正在读取 4 个文件" : "Reading 4 files"}
        </MarkerContent>
      </Marker>
    </div>
  );
}
```

```tsx
<Marker role="status">
  <MarkerIcon>
    <Loader size="sm" label="Thinking" />
  </MarkerIcon>
  <MarkerContent className="shimmer">Thinking&hellip;</MarkerContent>
</Marker>
```

## Color

Use `shimmer-color-<color>` to set the highlight color explicitly. It accepts theme colors with an optional opacity modifier, or any arbitrary color value.

### Example: shimmer-color

```tsx
import type { ExampleProps } from "../types";
export default function ShimmerColor({ locale }: ExampleProps = {}) {
  const chinese = locale === "zh-CN";
  return (
    <div className="flex flex-col items-center gap-2 text-muted-foreground text-sm">
      <p className="shimmer shimmer-color-blue-500/60">
        {chinese ? "正在生成回复…" : "Generating response…"}
      </p>
      <p className="shimmer shimmer-color-[#378ADD]">
        {chinese ? "正在生成回复…" : "Generating response…"}
      </p>
    </div>
  );
}
```

```tsx
<p className="shimmer shimmer-color-blue-500/60">Generating response&hellip;</p>
<p className="shimmer shimmer-color-[#378ADD]">Generating response&hellip;</p>
```

## Duration

Use `shimmer-duration-<number>` to set the duration of one sweep in milliseconds. The default is `2000`, i.e. `2s`.

### Example: shimmer-duration

```tsx
import type { ExampleProps } from "../types";
export default function ShimmerDuration({ locale }: ExampleProps = {}) {
  const chinese = locale === "zh-CN";
  return (
    <div className="mx-auto grid w-full max-w-lg gap-6 text-center text-muted-foreground text-sm sm:grid-cols-2">
      <div className="flex flex-col gap-3">
        <p className="shimmer">
          {chinese ? "正在生成回复…" : "Generating response…"}
        </p>
        <p className="font-mono text-[0.9em]">shimmer</p>
      </div>
      <div className="flex flex-col gap-3">
        <p className="shimmer shimmer-duration-1000">
          {chinese ? "正在生成回复…" : "Generating response…"}
        </p>
        <p className="font-mono text-[0.9em]">shimmer-duration-1000</p>
      </div>
    </div>
  );
}
```

```tsx
<p className="shimmer shimmer-duration-1000">Generating response&hellip;</p>
```

## Spread

Use `shimmer-spread-<number>` to set the width of the highlight band using the spacing scale. The default is `calc(3ch + 40px)`: a fixed base plus a `3ch` term that scales with the font size.

### Example: shimmer-spread

```tsx
import type { ExampleProps } from "../types";
export default function ShimmerSpread({ locale }: ExampleProps = {}) {
  const chinese = locale === "zh-CN";
  return (
    <div className="mx-auto grid w-full max-w-lg gap-6 text-center text-muted-foreground text-sm sm:grid-cols-2">
      <div className="flex flex-col gap-3">
        <p className="shimmer shimmer-spread-4">
          {chinese ? "正在生成回复…" : "Generating response…"}
        </p>
        <p className="font-mono text-[0.9em]">shimmer-spread-4</p>
      </div>
      <div className="flex flex-col gap-3">
        <p className="shimmer shimmer-spread-24">
          {chinese ? "正在生成回复…" : "Generating response…"}
        </p>
        <p className="font-mono text-[0.9em]">shimmer-spread-24</p>
      </div>
    </div>
  );
}
```

```tsx
<p className="shimmer shimmer-spread-24">Generating response&hellip;</p>
```

For one-off values, use an arbitrary length or percentage:

```tsx
<p className="shimmer shimmer-spread-[5rem]">Generating response&hellip;</p>
```

## Angle

Use `shimmer-angle-<number>` to set the tilt of the highlight band in degrees. The default is `20`.

### Example: shimmer-angle

```tsx
import type { ExampleProps } from "../types";
export default function ShimmerAngle({ locale }: ExampleProps = {}) {
  const chinese = locale === "zh-CN";
  return (
    <div className="mx-auto grid w-full max-w-lg gap-6 text-center text-muted-foreground text-sm sm:grid-cols-2">
      <div className="flex flex-col gap-3">
        <p className="shimmer">
          {chinese ? "正在生成回复…" : "Generating response…"}
        </p>
        <p className="font-mono text-[0.9em]">shimmer</p>
      </div>
      <div className="flex flex-col gap-3">
        <p className="shimmer shimmer-angle-45">
          {chinese ? "正在生成回复…" : "Generating response…"}
        </p>
        <p className="font-mono text-[0.9em]">shimmer-angle-45</p>
      </div>
    </div>
  );
}
```

```tsx
<p className="shimmer shimmer-angle-45">Generating response&hellip;</p>
```

## Reverse

Use `shimmer-reverse` to sweep the highlight in the opposite direction. In RTL layouts the sweep already follows the reading direction. See [RTL](#rtl).

```tsx
<p className="shimmer shimmer-reverse">Generating response&hellip;</p>
```

## Play once

Use `shimmer-once` to play a single sweep instead of looping, useful as a reveal when streaming completes. Pair it with `shimmer-duration-<number>` to control how long the sweep takes.

### Example: shimmer-once

```tsx
import { Button } from "@workspace/ui/components/button";
import * as React from "react";
import type { ExampleProps } from "../types";

export default function ShimmerOnce({ locale }: ExampleProps = {}) {
  const chinese = locale === "zh-CN";
  const [key, setKey] = React.useState(0);

  return (
    <div className="flex flex-col items-center gap-4">
      <p
        key={key}
        className="shimmer shimmer-duration-1100 shimmer-once text-muted-foreground text-sm"
      >
        {chinese ? "正在生成回复…" : "Generating response…"}
      </p>
      <Button
        variant="outline"
        size="sm"
        onClick={() => setKey((value) => value + 1)}
      >
        {chinese ? "重播" : "Replay"}
      </Button>
    </div>
  );
}
```

```tsx
<p className="shimmer shimmer-duration-1100 shimmer-once">
  Response generated.
</p>
```

## Disabling the shimmer

Use `shimmer-none` to turn the effect off and render the text normally. It works in any class order, so the typical use is responsive or stateful:

### Example: shimmer-none

```tsx
import type { ExampleProps } from "../types";
export default function ShimmerNone({ locale }: ExampleProps = {}) {
  const chinese = locale === "zh-CN";
  return (
    <div className="flex flex-col items-center gap-3 text-muted-foreground text-sm">
      <p className="shimmer md:shimmer-none">
        {chinese ? "正在生成回复…" : "Generating response…"}
      </p>
      <p className="font-mono text-[0.9em]">shimmer md:shimmer-none</p>
    </div>
  );
}
```

```tsx
<p className="shimmer md:shimmer-none">Generating response&hellip;</p>
```

## Fallback

The shimmer is built on modern color features, [relative color syntax](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_colors/Relative_colors) and `color-mix()`, which are available in all current browsers. In older browsers without support, the highlight gradient is dropped and the text can render transparent. If you target older browsers, apply `shimmer` conditionally with a `supports-*` variant:

```tsx
<p className="supports-[color:oklch(from_white_l_c_h)]:shimmer">
  Generating response&hellip;
</p>
```

## Reduced motion

When the user prefers reduced motion, the animation is disabled automatically and the text renders normally. There is nothing to configure.

## RTL

Set `dir="rtl"` on the container or use SUI’s [DirectionProvider](/docs/components/direction).

The sweep follows the reading direction, left to right in LTR and right to left in RTL, with no extra classes. Use `shimmer-reverse` to flip the direction manually.

### Example: shimmer-rtl

```tsx
import type { ExampleProps } from "../types";
export default function ShimmerRtl({ locale }: ExampleProps = {}) {
  const chinese = locale === "zh-CN";
  return (
    <div className="mx-auto grid w-full max-w-lg gap-6 text-center text-muted-foreground text-sm sm:grid-cols-2">
      <div className="flex flex-col gap-3">
        <p dir="ltr" className="shimmer">
          {chinese ? "正在生成回复…" : "Generating response…"}
        </p>
        <p className="font-mono text-[0.9em]">dir=&quot;ltr&quot;</p>
      </div>
      <div className="flex flex-col gap-3">
        <p dir="rtl" className="shimmer">
          جارٍ إنشاء الرد&hellip;
        </p>
        <p className="font-mono text-[0.9em]">dir=&quot;rtl&quot;</p>
      </div>
    </div>
  );
}
```

## Accessibility

Shimmer is a visual effect, not a status announcement. Use a suitable `role="status"` for loading text and avoid repeatedly replacing the accessible label. Keep the underlying text readable; use `shimmer-none` after the operation completes. For a loading indicator with a label, see [Loader](/docs/components/loader).