# Koala UI documentation

> A commercial React design system: 123 components built on Tailwind CSS v4, Radix UI and
> tailwind-variants, with four themes (light, cream, dark, moonlight), eight accents and a
> two-step density axis, all flowing from one layer of semantic CSS variables. The CLI copies the
> source into your repo, so you own it; there is no runtime package to be locked into.

Every free docs page (guides, foundations and components) as markdown, in sidebar order. The index with the section catalog is https://www.koalaui.com/llms.txt; each page below also lives at its own URL, given above it.

## Conventions

- Multi-part components use `tv` with `slots`; there is no `cva` in this codebase.
- Parts are NAMED exports, never dot-notation: `Card`, `CardHeader`, `CardBody`. Namespaced
  statics do not survive the RSC server-to-client boundary.
- Cross-part state flows through React Context (`lib/create-context.tsx`), never by cloning
  children.
- Colors, radii, shadows and motion come from tokens. No raw hex, `oklch()`, `cubic-bezier()`
  or millisecond literals inside a component.
- Every component accepts `className`, merged last through `tailwind-merge`.
- React 19: `ref` is a regular prop, so there is no `forwardRef`.

## Install and update

```bash
npx koalaui-cli@latest init                       # once: tokens, lib helpers, theme provider, base deps
npx koalaui-cli@latest add button card dialog     # components, their dependencies pulled along
npx koalaui-cli@latest list                       # everything available, free and Pro
npx koalaui-cli@latest diff [item]                # what changed upstream since you installed
npx koalaui-cli@latest update [item] [--force]    # replace untouched files; edited files are kept
npx koalaui-cli@latest template <name> [dir]      # Pro: start a whole site from a template
npx koalaui-cli@latest skill                      # write the Koala agent skill into .claude/skills/koala-ui
```

`init` writes `koala.css` and imports it from the stylesheet that imports Tailwind. In Next.js
that is `app/globals.css`, and the root layout then loads Inter as `--font-sans` and DM Sans as
`--font-heading` with `next/font`. In Vite it is `src/index.css` (tokens in `src/styles/koala.css`),
and `init` wires both faces itself from `@fontsource-variable`. Either way the app is wrapped in
the `ThemeProvider` from `components/theme-provider.tsx` (themes: light, cream, dark, moonlight;
`forcedTheme` pins one). Components land in `components/ui/<name>/` (under `src/` in Vite) and
import through the `@/*` path alias. `add` refuses while a flat shadcn/ui file of the same name
would shadow a Koala folder. Every install is recorded in `koala.json`, which is how `diff` and
`update` know what you edited.

## Free and Pro

- Free, no account: all 123 components, the lib helpers and the design tokens.
  Their docs, code included, are below.
- Pro, with a license: every section, the page examples and the templates.
  Activate a key once per machine with `npx koalaui-cli@latest login <key>`, then add Pro items like free ones.
  Licenses: https://www.koalaui.com/pro. A section page's markdown names its Pro variants and stops there:
  their source is never published in these docs.

---

<!-- https://www.koalaui.com/docs.md -->

# Koala UI

The React implementation of Koala UI, built on Next.js, Tailwind v4, Radix, and tailwind-variants.

This is the React side of [koalaui.com](https://koalaui.com): the same design system, as production-ready React components. Components are owned source in your repo, styled with a single `tv` recipe, accessible by way of Radix primitives, and themed entirely through semantic design tokens. Four themes ship out of the box: light, dark, cream, and moonlight.

- [Get started](https://www.koalaui.com/docs/installation.md)
- [Browse components](https://www.koalaui.com/docs/components/button.md)
- [Architecture](https://www.koalaui.com/docs/architecture.md)

---

<!-- https://www.koalaui.com/docs/installation.md -->

# Installation

Add Koala UI to your React app. Run the one-time setup, wire the fonts and theme into your layout, add the components you need, and pull updates later without losing your edits.

Koala UI ships **owned source**: the CLI copies each component into your repo under `components/ui/`, so you own and edit the code, no runtime dependency on us. The fastest path is the CLI; you can also copy any component by hand from its docs page. It sets up Next.js and Vite apps alike.

## Quick start

1. **Run the setup**

   `init` writes the design tokens to `koala.css` and imports them from the stylesheet that imports Tailwind (`app/globals.css` in Next.js, `src/index.css` in Vite), drops the shared helpers (`cn` and the `tv` wrapper) into `lib/`, adds the theme provider and installs the base dependencies. It tells the two frameworks apart on its own. No account or auth needed.

   ```bash
   npx
   ```

   On a fresh `create-next-app` project it replaces the starter stylesheet, whose own colors and dark media query would fight Koala’s themes. On an existing stylesheet it only adds the imports, and warns you about anything left that would override the themes: its own `--background`, `--foreground` or `--radius`, or a dark variant of its own. Coming from shadcn/ui? It replaces shadcn’s `lib/utils.ts`, and [the migration guide](https://www.koalaui.com/docs/migrating-from-shadcn.md) covers the rest.

2. **Wire the fonts and the theme**

   **Next.js**

   Koala sets UI and body copy in Inter and headings in DM Sans, read through the `--font-sans` and `--font-heading` variables. Load both with `next/font` and wrap your app in the `ThemeProvider` that `init` installed. Until you do, text falls back to the system sans and only the light theme applies.

   ```tsx
   import { Inter, DM_Sans } from "next/font/google"
   import { ThemeProvider } from "@/components/theme-provider"
   import "./globals.css"

   const sans = Inter({ subsets: ["latin"], variable: "--font-sans" })
   const heading = DM_Sans({ subsets: ["latin"], variable: "--font-heading", axes: ["opsz"] })

   export default function RootLayout({ children }: { children: React.ReactNode }) {
     return (
       <html
         lang="en"
         suppressHydrationWarning
         className={`${sans.variable} ${heading.variable}`}
       >
         <body>
           <ThemeProvider>{children}</ThemeProvider>
         </body>
       </html>
     )
   }
   ```

   **Vite**

   Koala sets UI and body copy in Inter and headings in DM Sans. In a Vite app `init` has already wired both: it installs them from npm and declares `--font-sans` and `--font-heading` in your stylesheet, so the faces ship with your app and need no font CDN (a Tauri or Electron shell with a strict content policy included).

   ```css
   @import "tailwindcss";
   @import "@fontsource-variable/inter";
   @import "@fontsource-variable/dm-sans/opsz.css";
   @import "./styles/koala.css";

   /* Koala UI faces, wired by `koalaui init`: Inter for UI and body, DM Sans for headings. */
   :root {
     --font-sans: "Inter Variable", ui-sans-serif, system-ui, sans-serif;
     --font-heading: "DM Sans Variable", "Inter Variable", ui-sans-serif, system-ui, sans-serif;
   }
   ```

   Wrap your app in the `ThemeProvider` that `init` installed, in `src/main.tsx`. Until you do, only the light theme applies.

   ```tsx
   import { StrictMode } from "react"
   import { createRoot } from "react-dom/client"
   import { ThemeProvider } from "@/components/theme-provider"
   import App from "./App"
   import "./index.css"

   createRoot(document.getElementById("root")!).render(
     <StrictMode>
       <ThemeProvider>
         <App />
       </ThemeProvider>
     </StrictMode>,
   )
   ```

   The theme follows the visitor’s OS by default. Switch it anywhere with `useTheme` from next-themes, which works outside Next.js too. An app with a single theme pins it instead: `<ThemeProvider forcedTheme="dark">`.

   ```tsx
   "use client"

   import { useTheme } from "next-themes"
   import { Button } from "@/components/ui/button"

   // "light" | "cream" | "dark" | "moonlight" | "system"
   export function MoonlightButton() {
     const { setTheme } = useTheme()
     return <Button onClick={() => setTheme("moonlight")}>Moonlight</Button>
   }
   ```

3. **Add components**

   Pass one or more component slugs. Each lands in `components/ui/<name>/` (under `src/` in a Vite app) with its dependencies pulled along automatically.

   ```bash
   npx
   ```

4. **Import and use**

   Import from the path the CLI wrote to. Every component is a named export, themed through tokens, and accepts `className`.

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

   export function Example() {
     return <Button>Get started</Button>
   }
   ```

## Updating

The code is yours, so updates never land on their own. Every install is recorded in `koala.json` at your project root: which version of each item you took, and a fingerprint of every file as it was written. Commit it with the rest of your code.

1. **See what changed**

   On its own, `diff` lists the items with an update and the files you have edited. Name an item to read the line changes before you take them.

   ```bash
   npx
   ```

2. **Apply the update**

   Files you never touched are replaced. Files you edited are kept as they are and listed, so an update never overwrites your work. Any new dependency an update needs comes along with it.

   ```bash
   npx
   ```

To take Koala’s version of a file you edited, merge it by hand from the diff, or run `npx koalaui-cli@latest update <item> --force` to replace your copy outright. `init` is tracked too, so the tokens in `koala.css` update the same way.

## Pro sections

Components, the lib helpers and the tokens are free. Every section, the page examples and the templates are **Pro** and need a license key. Activate it once per machine, then add Pro items exactly like free ones.

1. **Activate your license**

   Lemon Squeezy emails your key with your receipt, and keeps it in [your orders](https://app.lemonsqueezy.com/my-orders). Activating claims one seat and saves the key and the seat to `~/.koalaui/config.json`, readable by you only. A bad key fails here, not later.

   ```bash
   npx
   ```

2. **Add a Pro item**

   Run `npx koalaui-cli@latest list` to see everything; Pro items are marked with a lock.

   ```bash
   npx
   ```

`npx koalaui-cli@latest whoami` shows the active license and whether this machine is activated. `npx koalaui-cli@latest logout` releases the seat and forgets the key, so run it before wiping a machine or the seat stays taken.

A license covers one person. Your key is exchanged for the source on our server, so you never receive a repository token and no access is granted to your GitHub account. Every Pro file arrives stamped with a fingerprint of your license, never the key itself.

To read the source before you install it, unlock the site at [/account](https://www.koalaui.com/account) with your key and purchase email: the Code tab of every Pro section then shows its files. Unlocking the site uses no seat.

A few sections link with `next/link`. In a Vite app `add` names them after it writes them: swap that import for your router’s link.

## Templates

A template is a whole site: a Next.js project with its pages, its own design layer and the Koala UI components it uses. It is Pro, and it installs into a new, empty folder rather than into a project you already have.

```bash
npx
```

The CLI writes the source, downloads the pictures from the live demo and checks each one against its checksum, then runs `npm ci`. Start it with `npm run dev`; its README says where the design variables live and what to replace before you launch. Inside it, `npx koalaui-cli@latest update` keeps the library files current like in any other project.

## CI and agents

Each `login` claims a seat, so a CI job must not run one per build. Activate one seat for CI once, from your own machine, without saving it on that machine:

```bash
npx
```

It prints `KOALAUI_LICENSE` and `KOALAUI_INSTANCE`. Store both as secrets in your CI and the CLI reads them from the environment. On CI, `login` refuses to run without `--no-save`. Coding agents working on your machine use your saved seat and need nothing extra.

## Manual installation

Prefer to copy by hand? Install the shared dependencies, bring the tokens over, then copy any component source straight from its docs page. Hand-copied files are not in `koala.json`, so the CLI’s `update` cannot track them.

1. **Install the dependencies**

   ```bash
   npm install clsx tailwind-merge tailwind-variants tw-animate-css next-themes
   ```

   In a Vite app, the two faces as well:

   ```bash
   npm install @fontsource-variable/inter @fontsource-variable/dm-sans
   ```

2. **Copy the tokens**

   The whole theme layer, color roles, radius and shadow scales, motion tokens and the custom utilities, lives in one stylesheet. Copy `registry/koala.css` from the repo to `app/koala.css` (`src/styles/koala.css` in Vite) and import it right after Tailwind. Without it, nothing is styled. In Vite, add the font lines from step 2 of the quick start as well.

   ```css
   @import "tailwindcss";
   @import "./koala.css";
   ```

3. **Wire the fonts and the theme**

   Copy `components/theme-provider.tsx` from the repo, then set up your root layout (or, in Vite, your entry file) as in step 2 of the quick start.

4. **Copy the source**

   Paste a component into `components/ui/<name>/` and point its imports at your project: components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Requirements

- **React 19**: components use `ref` as a regular prop (no `forwardRef`).

- **Tailwind CSS v4**: the tokens use `@theme`, `@utility` and `@custom-variant`, which v3 cannot read. A v3 project has to migrate first.

- **The `@/*` path alias**: every component imports through it. Most Next.js projects already have it; a Vite app declares it twice, for TypeScript and for Vite. `init` tells you if yours doesn’t.

  **Next.js**

  ```ts
  {
    "compilerOptions": {
      "paths": {
        "@/*": ["./*"]
      }
    }
  }
  ```

  **Vite**

  ```ts
  // tsconfig.json and tsconfig.app.json
  {
    "compilerOptions": {
      "paths": {
        "@/*": ["./src/*"]
      }
    }
  }
  ```

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

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

- **Next.js or Vite**: `init` recognizes both and wires each its own way. Any other React 19 + Tailwind v4 setup works too: it finds the stylesheet that imports Tailwind, and the fonts follow the Vite route. Templates are whole Next.js sites.

---

<!-- https://www.koalaui.com/docs/architecture.md -->

# Architecture

The house style for building Koala UI - a pragmatic distillation of modern React design-system patterns, taking what scales and dropping what's clever-but-fragile.

## The stack

- **Styling / variants**: tailwind-variants (tv) with slots
- **Class merge**: tailwind-merge, extended for Koala tokens
- **Behavior & a11y**: Radix UI primitives
- **Polymorphism (asChild)**: Radix Slot
- **Cross-part state**: React Context (typed helper)
- **Theming**: CSS variables + semantic tokens + class strategy

## What we reject

`recursiveCloneChildren`-style prop distribution (matching children by `displayName` to inject props) is elegant in a demo and a liability at scale: it breaks under minification, breaks when a part is wrapped, and clones the subtree each render. We use **React Context** for cross-part state - what Radix, React Aria, Ark, MUI, and Chakra all do internally.

## Full reference

The complete writeup lives in `docs/ARCHITECTURE.md` in the repo.

---

<!-- https://www.koalaui.com/docs/patterns.md -->

# Patterns

Component decision guide - when to reach for which piece, with live examples of each pattern in context.

## Select vs. Dropdown Menu

Both open a list on click - but they model different interactions. **Select carries a value** (part of a form, trigger echoes the selection). **Dropdown Menu triggers actions** (commands run, trigger stays fixed).

Select - picking a value

Click an option - the trigger updates to echo your choice. Correct for plan, country, sort order, or any form field.

Dropdown Menu - triggering actions

The trigger always reads "My account". Clicking an item runs a command - nothing is stored in the trigger.

Don't - Dropdown for value selection

Click any option. The trigger stays "Plan" - users can't tell what's selected, and the value can't be read as a form field.

Quick smell test: should the trigger echo whatever was picked? Use **Select**. Should it stay the same label regardless? Use **Dropdown Menu**.

## Dialog vs. Toast

**Dialog demands a decision** - it blocks the page until the user acts. **Toast is a passive observer** - it confirms what already happened and dismisses itself.

Dialog - requires a response

A destructive action needs explicit confirmation. The page blocks until the user decides - cancel or delete.

Toast - status feedback

The save already happened. Toast confirms it without interrupting the user's flow - it disappears on its own.

Never use a Toast to report an error the user must act on - those get missed. Use a Dialog, or inline validation next to the field instead.

## Tooltip - and when to escalate

Tooltips are **supplementary labels**, not content containers - they follow the WAI-ARIA tooltip role strictly. Hover the toolbar: the bubble glides between triggers via `TooltipGroup`.

Tooltip - labelling icon controls

Hover any button. Labels clarify icons without adding visual weight to the layout.

- Never put a link, button, or form inside a Tooltip - screen readers won’t reach it and pointer users can’t reliably click it.
- If the overlay needs to be clickable, use a **Dropdown Menu** (supports hover open).
- If it needs a form or a destructive action, escalate to a **Dialog**.

## Details that make interfaces feel better

Sourced from [Details that make interfaces feel better](https://jakub.kr/writing/details-that-make-interfaces-feel-better) by [Jakub Krehel](https://jakub.kr). Worth reading in full.

No single detail here is a feature - each one is a fraction of a second, a pixel, a rendering quirk. Stacked, they’re the difference between a UI that was *built* and one that was *designed*.

Tabular numbers

Watch the left counter: proportional digits shift width as values change (narrow 1 vs wide 9). The right stays locked. font-variant-numeric: tabular-nums makes every digit equal-width.

Concentric border radius

outer radius − gap = inner radius. With p-2 (8px) and a rounded-2xl (16px) wrapper, the inner surface wants rounded-lg (8px). Mismatching makes corners look accidental.

Animate icons on entry

Hover each button. Opacity-only pops the icon in abruptly. Adding scale makes the entry feel physical - the icon grows into place rather than materialising out of nowhere.

Shadows over solid borders

Layered box-shadows with rgba transparency adapt to any background. Solid borders assume a fixed surface colour; shadows cooperate with whatever is underneath.

Image outlines

A 1px inset outline at 10% opacity defines the edge of images and gradients against any background - especially on light-on-light or dark-on-dark surfaces where the boundary would otherwise dissolve.

Text wrap: balance

Distributes a heading's text evenly across lines, preventing a short orphaned word on the last line. Pair with text-wrap: pretty on body copy.

Font smoothing

-webkit-font-smoothing: antialiased switches macOS from subpixel to grayscale rendering - slightly thinner, crisper strokes. Apply once on the root; already set in globals.css.

Interruptible animations

Hover out of each bar mid-way. The keyframe bar snaps back to zero - it can't be interrupted. The transition bar reverses smoothly from wherever it is.

Staggered enter, subtle exit

Items cascade in with 75 ms delays - enter takes 350 ms. Exit fires all at once in 180 ms with no stagger. Exits should be faster and quieter than entrances.

Optical alignment

A trailing arrow shifts the button's visual weight right - equal padding (24/24) looks off-balance. Reducing the right side to 18px restores the feel. Toggle Show Padding to measure.

Built on the principles of [make-interfaces-feel-better](https://jakub.kr/skills), the skill by [Jakub Krehel](https://jakub.kr) that we recommend installing alongside Koala.

---

<!-- https://www.koalaui.com/docs/agents.md -->

# AI and agents

Koala's docs are built for coding agents too: every page as markdown, an llms.txt index, the whole docs in one file, and a skill that teaches an agent Koala's rules. How to use each.

## What there is

| What | Where | What it is for |
| --- | --- | --- |
| Markdown pages | Any docs URL plus `.md`, like `/docs/components/button.md` | One page as clean markdown: its prose, tables and every code sample, without the demo markup. |
| Copy page | The top right of every docs page | Copies the page as markdown, opens the markdown, or starts a ChatGPT or Claude chat that reads it. |
| llms.txt | [/llms.txt](https://www.koalaui.com/llms.txt) | The index: conventions, install and CLI commands, what is free and what is Pro, and every page with its summary. |
| llms-full.txt | [/llms-full.txt](https://www.koalaui.com/llms-full.txt) | Every free docs page (guides, foundations, components) in one file. |
| The skill | `npx koalaui-cli@latest skill` | The house rules, tokens, themes and CLI in one SKILL.md, plus a reference per component, written into your project. |

## Claude Code

Install the skill in your project. Claude Code loads project skills from `.claude/skills/`, and the skill’s description tells it to follow Koala’s rules whenever you ask for UI. Start a new session after installing it.

```bash
npx koalaui-cli@latest skill
```

Commit `.claude/skills/koala-ui/` so everyone on the project works from the same rules, and run the command again after you update Koala. For a page the skill does not cover, a foundation or a section family, give Claude its markdown URL: “Read https://www.koalaui.com/docs/foundations/theming.md and add a theme switch to the header.”

## Cursor, Codex and other agents

Install the skill the same way, then point the agent at it. Cursor reads project rules from `.cursor/rules/`; this writes one:

```bash
mkdir -p .cursor/rules
cat > .cursor/rules/koala-ui.mdc <<'EOF'
---
description: Building UI with Koala UI
globs: ["**/*.tsx"]
alwaysApply: false
---

Before writing UI, read .claude/skills/koala-ui/SKILL.md and follow it.
Component docs are in .claude/skills/koala-ui/references/<name>.md.
EOF
```

Agents that read `AGENTS.md`, Codex and Cursor among them, take the same instruction from there; this appends it:

```bash
cat >> AGENTS.md <<'EOF'

## UI

This project uses Koala UI. Before writing UI, read .claude/skills/koala-ui/SKILL.md and follow it.
Component docs are in .claude/skills/koala-ui/references/<name>.md.
EOF
```

To keep the skill somewhere else, pass `--dir`: `npx koalaui-cli@latest skill --dir docs/koala-skill`, and point the rule there.

## ChatGPT, Claude and other chats

On any docs page, open the Copy page menu at the top right. Copy page puts the page on your clipboard as markdown to paste into a chat; Open in ChatGPT and Open in Claude start a chat that reads the page for you. For a broader question, hand the assistant [llms.txt](https://www.koalaui.com/llms.txt), the index, or [llms-full.txt](https://www.koalaui.com/llms-full.txt), everything at once.

## What an agent can install

An agent runs the same CLI you do. Free items need nothing: every component, the lib helpers and the tokens install anywhere with `npx koalaui-cli@latest add <name>`. Sections, page examples and templates are Pro and install with your license once you have run `npx koalaui-cli@latest login <key>` on the machine, and an agent working there uses that seat. Without a license, `add` stops with a paywall message, and the skill tells the agent to report it rather than rebuild the section.

Pro source is never in the markdown. A section family’s page names its Pro variants and stops there; no `.md` page, llms file or skill reference carries the code of a Pro section, page or template.

## FAQ

### Is the markdown the same as the page?

It is rendered from the same page, at build time: the prose, tables and code samples are the page's own. Interactive demos are left out, and every demo's code sample stays.

### How do I keep the skill current?

Run the skill command again after you update Koala. It replaces the skill's files and removes references a newer version no longer has; nothing else in your project is touched.

### Does the skill need a connection when the agent works?

No. It is plain markdown in your repo, so the agent reads it like any other file. Only the .md pages and llms files live on the site.

---

<!-- https://www.koalaui.com/docs/migrating-from-shadcn.md -->

# Migrating from shadcn/ui

Most of what you know from shadcn/ui carries over: Radix underneath, Tailwind, the source in your repo. Here is every shadcn component's Koala counterpart, and every name that changes.

## At a glance

Where the two meet and where they part. The sections below go through each difference.

|  | shadcn/ui | Koala UI |
| --- | --- | --- |
| **Foundations** |  |  |
| Source in your repo | Yes | Yes |
| Radix primitives | Yes | Yes |
| Tailwind CSS v4 | Yes | Yes |
| Variant recipes | `cva` | `tv`, with slots |
| Icons | Lucide | Phosphor |
| **Theming** |  |  |
| Themes<br>Light, cream, dark and moonlight, where shadcn/ui ships light and dark. | 2 | 4 |
| Accent colors<br>Switched with a class, no rebuild. | 1 | 8 |
| Densities<br>Comfortable and compact, set once for a whole app shell. | 1 | 2 |
| **Components** |  |  |
| Data table, date picker, combobox<br>Components you configure. In shadcn/ui they are recipes you assemble. | No | Yes |
| Rich text editor, file upload, AI chat | No | Yes |
| Charts, carousel, drawer, calendar<br>shadcn/ui wraps Recharts, Embla, Vaul and react-day-picker. | Third-party | Built in |
| **Beyond components** |  |  |
| Sections<br>For marketing, app and store pages, in families: hero, feature, pricing, FAQ, checkout and more. | App blocks | 190 |
| Page examples | No | 34 |
| Templates | No | 7 |
| Updates that keep your edits<br>`update` replaces the files you did not touch and lists the ones you did. | No | Yes |
| **License** |  |  |
| Price<br>Every component is free. Most sections, the page examples and the templates are Pro. | Free | Free and Pro |

## What carries over

- The source lives in your repo under `components/ui/`, and the import paths stay the same: `@/components/ui/button`.
- Radix primitives for behavior and accessibility, `asChild` through Radix Slot, `className` merged last with `cn`, and a `data-slot` on every part.
- Named exports composed as parts: `<Card><CardHeader><CardTitle>`.
- Tailwind CSS v4, with theming through CSS variables.

## What changes

- **`tv` instead of `cva`.** Variant recipes are tailwind-variants, with `slots` for multi-part components, and `VariantProps` comes from `@/lib/tv`. Nothing in Koala uses class-variance-authority.
- **More tokens.** The color roles you know (`background`, `foreground`, `primary`, `muted`, `border`) are joined by `brand` (the accent), `body` for reading copy, `canvas`, `link` and status roles with a `-strong` text step. Four themes (`light`, `cream`, `dark`, `moonlight`) and eight accents replace one light and one dark palette. See [Colors](https://www.koalaui.com/docs/foundations/colors.md).
- **The brand leads.** `variant="primary"` is the brand color, where shadcn’s default button is near black. `neutral` is the black one.
- **Fields have two parts.** `InputRoot` is the frame and `InputField` the input, so prefixes, suffixes and buttons sit inside one border. The same goes for `TextareaRoot` and `TextareaField`.
- **Components, not recipes.** Data table, date picker, combobox (`SelectSearch`) and pagination ship as components you configure, not snippets you assemble.
- **Fewer dependencies.** Charts, the carousel, the drawer and the calendar are Koala’s own: no Recharts, Embla, Vaul or react-day-picker. Icons are Phosphor, not Lucide.
- **Density and control size.** `size` is `sm` 32, `md` 36 and `lg` 40px on every control, and a `DensityProvider` tightens a whole app shell at once. See [Density](https://www.koalaui.com/docs/foundations/density.md).
- **Its own CLI.** `koalaui-cli` records installs in `koala.json` instead of `components.json`, and `diff` and `update` bring upstream changes in without overwriting the files you edited. See [Installation](https://www.koalaui.com/docs/installation.md).

## Component map

Every shadcn/ui component and where it lands. A Koala name links to its docs page, where the full API and examples live.

| shadcn/ui | Koala UI | What changes |
| --- | --- | --- |
| Accordion | [Accordion](https://www.koalaui.com/docs/components/accordion.md) | Same parts. Adds a `variant` axis for flush, contained and grid layouts. |
| Alert | [Alert](https://www.koalaui.com/docs/components/alert.md) | The glyph goes in `AlertIcon` and the text in `AlertContent`; `AlertActions` holds buttons. Variants: `default`, `success`, `warning`, `info`, `destructive`. |
| Alert Dialog | [Dialog](https://www.koalaui.com/docs/components/dialog.md) | `AlertDialog`, `AlertDialogContent`, `AlertDialogAction` → `Dialog`, `DialogContent`, `DialogFooter`<br>There is no separate alert dialog: a `Dialog` whose footer carries the destructive `Button`. |
| Aspect Ratio | None yet, see [Aspect Ratio](https://www.koalaui.com/docs/foundations/aspect-ratio.md) | Tailwind's `aspect-*` utilities on the frame, no component. |
| Avatar | [Avatar](https://www.koalaui.com/docs/components/avatar.md) | Same three parts, plus `AvatarStatus`, `AvatarBadge`, a `size` scale and a `shape`. |
| Badge | [Badge](https://www.koalaui.com/docs/components/badge.md) | See the variant map below. Adds status and category tones, `dot`, `pill` and `size`. |
| Breadcrumb | [Breadcrumb](https://www.koalaui.com/docs/components/breadcrumb.md) | Same parts. |
| Button | [Button](https://www.koalaui.com/docs/components/button.md) | See the variant and size map below. `iconOnly` replaces `size="icon"`; `loading` is built in. |
| Button Group | [Button Group](https://www.koalaui.com/docs/components/button-group.md) | `Button` inside the group → `ButtonGroupItem`<br>The group sets `variant` and `size` for its items. |
| Calendar | [Date Picker](https://www.koalaui.com/docs/components/date-picker.md) | `Calendar` → `Calendar`<br>Koala's own calendar: no react-day-picker, no date library. |
| Card | [Card](https://www.koalaui.com/docs/components/card.md) | Same parts, plus `CardMedia` for an inset picture. |
| Carousel | [Carousel](https://www.koalaui.com/docs/components/carousel.md) | `CarouselItem` → `CarouselSlide`<br>No Embla dependency. Adds `CarouselIndicators`. |
| Chart | [Chart](https://www.koalaui.com/docs/components/chart.md) | `ChartContainer` → `Chart`<br>`ChartTooltip` + `ChartTooltipContent` → `ChartTooltip`<br>`ChartLegend` + `ChartLegendContent` → `ChartLegend`<br>Recharts `Line`, `Area`, `Bar` → `ChartLine`, `ChartArea`, `ChartBar`<br>Its own SVG charts, no Recharts: `Chart` takes `data`, `index` and `config`, and the series are parts. |
| Checkbox | [Checkbox](https://www.koalaui.com/docs/components/checkbox.md) | Same. |
| Collapsible | [Collapsible](https://www.koalaui.com/docs/components/collapsible.md) | Same parts, plus `CollapsibleIcon`, a mark that turns with its trigger. The height tween is built in; `className` on `CollapsibleContent` styles the body. |
| Combobox | [Select](https://www.koalaui.com/docs/components/select.md) | `Popover` + `Command` recipe → `SelectSearch`, `SelectSearchTrigger`, `SelectSearchContent`, `SelectSearchItem`<br>A component, not a recipe. For several values, `MultiSelect`. |
| Command | [Command](https://www.koalaui.com/docs/components/command.md) | Same parts, `CommandDialog` included. |
| Context Menu | [Context Menu](https://www.koalaui.com/docs/components/context-menu.md) | Same parts. |
| Data Table | [Data Table](https://www.koalaui.com/docs/components/data-table.md) | TanStack Table recipe → `DataTable`<br>A component, not a recipe: `columns` and `data` in, with sorting, filters, selection, pagination, grouping and row reorder. |
| Date Picker | [Date Picker](https://www.koalaui.com/docs/components/date-picker.md) | `Popover` + `Calendar` recipe → `DatePicker`, `DateRangePicker`<br>Components, with presets. |
| Dialog | [Dialog](https://www.koalaui.com/docs/components/dialog.md) | Same parts, plus `DialogBody`, `DialogIcon` and `DialogStepper`. The overlay is inside `DialogContent`. |
| Drawer | [Drawer](https://www.koalaui.com/docs/components/drawer.md) | No Vaul dependency: a bottom sheet is `DrawerContent side="bottom"`. Adds `DrawerBody` and stacked views. |
| Dropdown Menu | [Dropdown Menu](https://www.koalaui.com/docs/components/dropdown-menu.md) | Same parts. Rows can carry a description (`DropdownMenuItemText`); a delete row is `variant="destructive"`. |
| Empty | [Empty State](https://www.koalaui.com/docs/components/empty-state.md) | `Empty` → `EmptyState`<br>`EmptyMedia` → `EmptyStateMedia`<br>`EmptyTitle` → `EmptyStateTitle`<br>`EmptyDescription` → `EmptyStateDescription`<br>`EmptyContent` → `EmptyStateActions` |
| Field | [Field](https://www.koalaui.com/docs/components/field.md) | `FieldDescription`, `FieldError` → `FieldHint`<br>`FieldSet` + `FieldLegend` → `FieldGroup`, `FieldGroupLabel`<br>An error is `hasError` on `Field`: it turns the hint into the message and sets `aria-invalid`. |
| Form | [Form](https://www.koalaui.com/docs/components/form.md) | Not a react-hook-form wrapper: `Form` is a plain `<form>` that sets the rhythm and the control size, and `Field` wires the label and hint. Bring your own validation. |
| Hover Card | [Hover Card](https://www.koalaui.com/docs/components/hover-card.md) | Same parts, plus `HoverCardTitle` and `HoverCardDescription`. The card is Popover's surface, with `showArrow` and `density`. |
| Input | [Input](https://www.koalaui.com/docs/components/input.md) | `Input` → `InputRoot`, `InputField`<br>Two parts: `InputRoot` is the frame, `InputField` the `<input>`. Prefixes, suffixes, `PasswordInput`, `NumberInput` and `PhoneInput` included. |
| Input Group | [Input Group](https://www.koalaui.com/docs/components/input-group.md) | `InputGroup` joins ordinary Koala controls (an input, a select, a button) into one frame; `InputGroupAddon` holds text or icons. |
| Input OTP | [OTP Input](https://www.koalaui.com/docs/components/otp-input.md) | `InputOTP`, `InputOTPGroup`, `InputOTPSlot` → `OTPInput`<br>One component; the slots come from `length`. |
| Item | [List](https://www.koalaui.com/docs/components/list.md) | `ItemGroup` → `List`<br>`Item` → `ListItem`<br>`ItemMedia` → `ListItemMedia`<br>`ItemContent` → `ListItemContent`<br>`ItemTitle` → `ListItemTitle`<br>`ItemDescription` → `ListItemDescription`<br>`ItemActions` → `ListItemMeta` |
| Kbd | [Kbd](https://www.koalaui.com/docs/components/kbd.md) | Same. |
| Label | [Label](https://www.koalaui.com/docs/components/label.md) | Same, plus `Hint` for the line under a control. |
| Menubar | [Menubar](https://www.koalaui.com/docs/components/menubar.md) | Same parts. The menus are Dropdown Menu's panels: a delete row is `variant="destructive"`, and a checkbox row can be `variant="switch"`. |
| Native Select | [Native Select](https://www.koalaui.com/docs/components/native-select.md) | Same parts. `size` (sm, md, lg) matches the Select trigger, and inside a `Field` it wires its own id, hint and error state. |
| Navigation Menu | [Navbar](https://www.koalaui.com/docs/components/navbar.md) | `Navbar` is the whole site bar: brand, links with dropdowns, actions and the mobile menu. |
| Pagination | [Pagination](https://www.koalaui.com/docs/components/pagination.md) | A ready component (`page`, `pageCount`, `onPageChange`); `PaginationRoot` and its parts for a custom layout. |
| Popover | [Popover](https://www.koalaui.com/docs/components/popover.md) | Same parts, plus `PopoverTitle`, `PopoverDescription` and `PopoverCloseButton`. |
| Progress | [Progress](https://www.koalaui.com/docs/components/progress.md) | Same, plus `ProgressLabel` and `ProgressValue`. |
| Radio Group | [Radio Group](https://www.koalaui.com/docs/components/radio-group.md) | Same parts, plus `RadioCard` for option cards. |
| Resizable | [Resizable](https://www.koalaui.com/docs/components/resizable.md) | Same parts. |
| Scroll Area | [Scroll Area](https://www.koalaui.com/docs/components/scroll-area.md) | `ScrollBar` is not a part: `orientation` (vertical, horizontal, both) draws the bars. Adds `fade` for the edges and `viewportRef`. |
| Select | [Select](https://www.koalaui.com/docs/components/select.md) | Same parts. |
| Separator | [Divider](https://www.koalaui.com/docs/components/divider.md) | `Separator` → `Divider`<br>Adds a label and dashed, dotted and gradient strokes. |
| Sheet | [Drawer](https://www.koalaui.com/docs/components/drawer.md) | `Sheet` → `Drawer`<br>`SheetTrigger` → `DrawerTrigger`<br>`SheetContent` → `DrawerContent`<br>`SheetHeader` → `DrawerHeader`<br>`SheetTitle` → `DrawerTitle`<br>`SheetDescription` → `DrawerDescription`<br>`SheetFooter` → `DrawerFooter`<br>`SheetClose` → `DrawerClose`<br>`side` goes on `DrawerContent`. |
| Sidebar | [Sidebar](https://www.koalaui.com/docs/components/sidebar.md) | `SidebarMenuItem` + `SidebarMenuButton` → `SidebarItem`<br>The shell (`SidebarProvider`, `SidebarInset`, `SidebarTrigger`) is the Layout component: `Layout`, `LayoutSidebar`, `LayoutContent`, `LayoutSidebarTrigger`. |
| Skeleton | [Skeleton](https://www.koalaui.com/docs/components/skeleton.md) | Same. |
| Slider | [Slider](https://www.koalaui.com/docs/components/slider.md) | Same, plus `SliderInput`: a track beside a value box you can scrub. |
| Sonner (and Toast) | [Toast](https://www.koalaui.com/docs/components/toast.md) | `toast` and `<Toaster />` from sonner → `toast`, `Toaster`<br>The same call shape: `toast()`, `toast.success()`, `toast.error()`, `toast.promise()`. Mount `<Toaster />` once. |
| Spinner | [Spinner](https://www.koalaui.com/docs/components/spinner.md) | Same. |
| Switch | [Switch](https://www.koalaui.com/docs/components/switch.md) | Same. |
| Table | [Data Table](https://www.koalaui.com/docs/components/data-table.md) | `Table`, `TableHeader`, `TableBody`, `TableRow`, `TableHead`, `TableCell` → `Table`, `TableHeader`, `TableBody`, `TableRow`, `TableHead`, `TableCell`<br>The same parts, exported from `@/components/ui/data-table`. |
| Tabs | [Tabs](https://www.koalaui.com/docs/components/tabs.md) | Same parts. Adds a `variant` (`pill`, `folder`, `line`, `chip`) and `TabsPanels`. |
| Textarea | [Textarea](https://www.koalaui.com/docs/components/textarea.md) | `Textarea` → `TextareaRoot`, `TextareaField`<br>Two parts like Input, plus `TextareaCount` for a live character count. |
| Toggle | [Toggle](https://www.koalaui.com/docs/components/toggle.md) | Variants `outline` (the default) and `ghost`; `size` is `sm` or `md`, and `iconOnly` replaces the square size. Adds `ToggleIcon` for a pressed glyph. |
| Toggle Group | [Toggle Group](https://www.koalaui.com/docs/components/toggle-group.md) | Same parts. |
| Tooltip | [Tooltip](https://www.koalaui.com/docs/components/tooltip.md) | `Tooltip` + `TooltipTrigger` + `TooltipContent` → `Tooltip`<br>`TooltipProvider` → `TooltipGroup`<br>One element: `<Tooltip content="Save">` wraps the trigger, `placement` sets the side. |
| Typography | [Prose](https://www.koalaui.com/docs/components/prose.md) | `Prose` styles rendered long-form HTML (a blog post, docs) in one wrapper. |

## Variants and sizes

The values that are named differently. Anything not listed keeps its shadcn name.

### Button `variant`

| shadcn/ui | Koala UI | Notes |
| --- | --- | --- |
| `default` | `primary` | The brand color. For shadcn's black button, `neutral`. |
| `secondary` | `secondary` |  |
| `outline` | `outline` |  |
| `ghost` | `ghost` |  |
| `destructive` | `destructive` | A soft red tint; `destructiveGhost` for a quiet delete. |
| `link` | `link` |  |

### Button `size`

| shadcn/ui | Koala UI | Notes |
| --- | --- | --- |
| `sm` | `sm` | 32px |
| `default` | `md` | 36px, the default |
| `lg` | `lg` | 40px |
| `icon` | `iconOnly` | A boolean, combined with any size |
| None | `xl` | 44px, for marketing calls to action |

### Badge `variant`

| shadcn/ui | Koala UI | Notes |
| --- | --- | --- |
| `default` | `primary` | Koala's `default` is a muted gray chip. |
| `secondary` | `secondary` |  |
| `outline` | `outline` |  |
| `destructive` | `destructive` | A soft tint, like the other status tones. |

### Alert `variant`

| shadcn/ui | Koala UI | Notes |
| --- | --- | --- |
| `default` | `default` |  |
| `destructive` | `destructive` |  |
| None | `success`, `warning`, `info` |  |

## Moving a project over

1. **Clear shadcn’s colors.** Delete the `:root` and `.dark` blocks shadcn added to your global stylesheet (`app/globals.css`, or `src/index.css` in Vite), and its `@custom-variant dark` line: they redefine `--background`, the other roles and `--radius`, and would override Koala’s themes. `init` warns you about each one still there.
2. **Run init.** It writes the tokens to `koala.css` (`app/` in Next.js, `src/styles/` in Vite), the helpers to `lib/` and the theme provider. shadcn’s `lib/utils.ts` is replaced: Koala’s `cn` has the same signature, with tailwind-merge taught Koala’s tokens. If you edited yours, `init` keeps it and tells you what to merge.
3. **Swap one component at a time.** Delete shadcn’s file and add Koala’s. The import path does not change, so only the parts and props in the map above do. `add` refuses while a flat `components/ui/<name>.tsx` is still there, for the component you asked for and for every Koala component it pulls in: the import would resolve to that file instead of Koala’s folder.
4. **Let the type checker find the rest.** Koala’s props are typed, so a leftover shadcn prop or value fails to compile.
5. **Clean up** once nothing imports them: `components.json`, `class-variance-authority`, `lucide-react` and the packages Koala replaced.

```bash
# 1. Tokens, the lib helpers and the theme provider (after removing shadcn's color blocks)
npx koalaui-cli@latest init

# 2. One component at a time: delete shadcn's file, add Koala's
rm components/ui/button.tsx
npx koalaui-cli@latest add button
```

## Why Koala

- **More of the product, already built.** 123 components, free, including the ones you would otherwise assemble: a data table, date and range pickers, charts, a command palette, a rich text editor, file upload, and AI chat and prompt input.
- **Sections, pages and templates.** 190 sections for marketing, app and store pages, in families (hero, feature, pricing, FAQ, checkout and more), 34 page examples and 7 templates, all of them Koala UI Pro.
- **Theming with range.** Four themes, eight accents and a radius knob from one layer of tokens: a re-skin is a class, not a fork.
- **Two densities.** The same components set a spacious marketing page and a dense dashboard.
- **Finish.** Every component goes through the same polish pass: 40px hit areas, concentric radii, tabular numbers, reduced-motion fallbacks and AA contrast in every theme.
- **Updates that keep your edits.** `diff` and `update` compare against what was installed, replace the files you did not touch and list the ones you did.

## FAQ

### Can shadcn/ui and Koala share a project while I migrate?

Yes, one component at a time. Both live in components/ui with the same import paths, so each component is either shadcn's file or Koala's folder: delete the file before you add the folder (the CLI refuses otherwise, and names the files in the way). The core color roles share their names, so the shadcn components you have not moved yet mostly pick up Koala's colors.

### Can I install Koala with the shadcn CLI?

No. Koala installs with its own CLI, koalaui-cli, which records what you installed in koala.json so that later updates keep your edits.

### Do I need to change my Tailwind or React setup?

Koala needs Tailwind CSS v4 and React 19. A shadcn project still on Tailwind v3 upgrades Tailwind first; the rest carries over.

### What happens to my Lucide icons?

They keep working. Koala's components draw Phosphor icons, and the two can live side by side until you swap yours.

---

<!-- https://www.koalaui.com/docs/foundations/theming.md -->

# Theming

Koala is themed entirely through CSS variables. Components read semantic tokens, never a raw color, radius or shadow, so one block of variables restyles the whole system.

## How theming works

Every Koala component is built from **semantic color roles** (`bg-background`, `text-foreground`, `bg-primary`,`border-border` …), a single radius knob (`--radius`) and a single accent knob (`--brand`). None of those are hard-coded in a component - they resolve to CSS variables defined once per theme. Switch the variables, and every surface, control and focus ring follows.

The roles themselves are documented on the [Colors](https://www.koalaui.com/docs/foundations/colors.md) page. This page is about *changing* them.

```css title="how a component resolves a color"
/* A button reads a role, never a literal: */
.button { background: var(--primary); }

/* …and the role is defined once, per theme: */
:root      { --primary: oklch(0.205 0 0); }    /* light     */
.cream     { --primary: oklch(0.24 0.014 75); } /* cream     */
.dark      { --primary: oklch(0.922 0 0); }    /* dark      */
.moonlight { --primary: oklch(0.704 0.14 264); } /* moonlight */
```

## The four built-in themes

Koala ships **light**, **cream** (warm light), **dark** and **moonlight** (blue-tinted dark). Each is a class on `<html>`; `light` is the bare `:root`, so it needs no class. We drive the class with `next-themes` through a thin `ThemeProvider`.

```tsx title="app/layout.tsx"
import { ThemeProvider } from "@/components/theme-provider"

export default function RootLayout({ children }) {
  return (
    <html lang="en" suppressHydrationWarning>
      <body>
        {/* attribute="class" · themes: light, cream, dark, moonlight */}
        <ThemeProvider>{children}</ThemeProvider>
      </body>
    </html>
  )
}
```

Theme and accent are **orthogonal axes**: any of the nine accents works under any of the four themes, because the themes deliberately never redefine `--brand`.

## Accent color

The accent is one variable, `--brand`. Every component reads it through `bg-brand` / `border-brand` / `ring-brand`, so a single value recolors checkboxes, switches, sliders, focus rings and links at once. Nine presets ship as `[data-accent]` blocks - apply one by setting the attribute on `<html>`:

```tsx
<html data-accent="violet">
```

For a brand color outside the presets, set `--brand` yourself. The focus ring (`--ring-brand`) derives from it automatically. Eight presets are mid-tone and carry white labels; `lime` is light, so its preset follows the theme (a deeper lime on light, the vivid one on dark) and sets `--brand-foreground`, the ink that sits on a brand fill. A light brand color of your own needs the same: set `--brand-foreground` to a dark ink.

```css title="globals.css"
:root {
  --brand: oklch(0.55 0.2 255); /* or any hex / rgb, color-mix converts it */
}
```

## Corner radius

One knob, `--radius`, drives the entire rounding scale. `rounded-lg` is `--radius` itself; `rounded-sm` … `rounded-4xl` are relative multiples of it, so changing the base re-rounds every component concentrically.

```css title="globals.css"
:root {
  --radius: 0.5rem; /* default 0.71rem, set 0 for sharp corners */
}
```

## Density

Density is Koala’s spacing axis - the knob that retunes padding, gaps and control heights without touching color or radius. Koala serves both information-dense application UI and generous marketing surfaces, so `density` lets one subtree tighten or relax with no per-instance props. There are two values: `compact` (the default - 16px padding/gaps, smaller titles, shorter controls) and `comfortable` (the spacious alternative).

Wrap a subtree in `DensityProvider` and every nested Koala component follows. The wrapper is `display: contents`, so it never introduces a box into the layout, and it stamps `data-density` on itself as a CSS/debug escape hatch.

```tsx title="app shell"
import { DensityProvider } from "@/lib/density"

export default function AppShell({ children }) {
  return (
    // Every Koala component inside tightens up.
    <DensityProvider density="compact">
      {children}
    </DensityProvider>
  )
}
```

A component resolves its effective density with `useDensity()`. Precedence is **explicit prop > nearest provider > `compact`**, and the result feeds the component’s `tv` recipe. Unlike most Koala contexts, density has a safe default, so it works with no provider at all.

```tsx title="inside a component"
import { useDensity, type Density } from "@/lib/density"

function Card({ density }: { density?: Density }) {
  // explicit prop > nearest provider > "compact"
  const resolved = useDensity(density)
  return <div className={card({ density: resolved })} />
}
```

Density is **orthogonal** to theme, accent and radius - it changes only spacing, so any density composes with any theme or accent.

## Create your own theme

A theme is just a class that redefines the role variables. The fastest path is to copy an existing block (light or dark, whichever is closer) and retune the values - that guarantees you cover every role a component might read.

```css title="app/globals.css"
.sunset {
  /* Surfaces */
  --background: oklch(0.98 0.02 70);
  --foreground: oklch(0.25 0.03 50);
  --card: oklch(1 0.01 70);
  --card-foreground: oklch(0.25 0.03 50);
  --popover: oklch(1 0.01 70);
  --popover-foreground: oklch(0.25 0.03 50);
  /* Brand-neutral actions + muted/accent fills */
  --primary: oklch(0.45 0.15 30);
  --primary-foreground: oklch(0.98 0.02 70);
  --secondary: oklch(0.94 0.03 70);
  --secondary-foreground: oklch(0.3 0.04 40);
  --muted: oklch(0.94 0.03 70);
  --muted-foreground: oklch(0.52 0.03 55);
  --accent: oklch(0.92 0.04 65);
  --accent-foreground: oklch(0.3 0.04 40);
  /* Status, lines + focus */
  --destructive: oklch(0.577 0.245 27.325);
  --border: oklch(0.89 0.03 70);
  --border-soft: color-mix(in oklch, var(--border) 50%, transparent);
  --input: oklch(0.89 0.03 70);
  --ring: oklch(0.7 0.05 60);
  /* …also copy the success/warning/info, categorical hue,
     --syntax-* and per-theme --shadow-* roles from a sibling block. */
}
```

Then register the name so `next-themes` can apply it, and it shows up in any theme switcher built from `THEMES`:

```tsx title="components/theme-provider.tsx"
export const THEMES = ["light", "cream", "dark", "moonlight", "sunset"] as const
```

**Tip:** a colored container (a tinted hero, a brand panel) should declare `--surface` rather than paint a `--background` block, so nested Inputs, Selects and minimal Tables blend into it instead of cutting their own surface.

## Switching themes at runtime

Because the theme is a class, swapping it live is just `setTheme()` from `next-themes`. The header switcher on this site dogfoods exactly this with a `DropdownMenu` radio group. Read `resolvedTheme` rather than `theme`, so a visitor on the system preference still sees a row checked:

```tsx title="theme-switcher.tsx"
"use client"
import { useTheme } from "next-themes"
import { THEMES } from "@/components/theme-provider"
import { Button } from "@/components/ui/button"
import {
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuRadioGroup,
  DropdownMenuRadioItem,
  DropdownMenuTrigger,
} from "@/components/ui/dropdown-menu"

export function ThemeSwitcher() {
  const { resolvedTheme, setTheme } = useTheme()
  return (
    <DropdownMenu>
      <DropdownMenuTrigger asChild>
        <Button variant="ghost" size="sm">Theme</Button>
      </DropdownMenuTrigger>
      <DropdownMenuContent align="end">
        <DropdownMenuRadioGroup value={resolvedTheme} onValueChange={setTheme}>
          {THEMES.map((t) => (
            <DropdownMenuRadioItem key={t} value={t} className="capitalize">
              {t}
            </DropdownMenuRadioItem>
          ))}
        </DropdownMenuRadioGroup>
      </DropdownMenuContent>
    </DropdownMenu>
  )
}
```

---

<!-- https://www.koalaui.com/docs/foundations/colors.md -->

# Colors

Koala's color system is three layers deep: a literal value, the CSS variable that holds it, and the semantic token a component writes. Components only ever reach for the top layer.

## Three layers

It helps to keep three things apart. A **literal value** is a raw, theme-blind color (`#F84416`, `oklch(1 0 0)`). A **CSS variable** (`--background`, `--primary`) holds one literal per theme. A **semantic token** is the utility a component writes (`bg-background`, `text-foreground`). It resolves to the variable, never to a literal. Change a theme by swapping the variables; the literals move, the tokens stay put.

```css title="the chain, bottom to top"
/* 1: literal value (raw, theme-blind) */
oklch(0.205 0 0)

/* 2: CSS variable, one literal per theme */
:root  { --primary: oklch(0.205 0 0); }   /* light */
.dark  { --primary: oklch(0.922 0 0); }   /* dark  */

/* 3: semantic token, what a component writes */
@theme inline { --color-primary: var(--primary); }
.button { background: var(--color-primary); }  /* bg-primary */
```

The swatches below document the **token and variable** layers, the part you build with. The [literal colors](#literal-colors) at the bottom are the raw escape hatch. For *changing* the variables, see [Theming](https://www.koalaui.com/docs/foundations/theming.md).

## Surfaces

Each swatch shows the token a component writes and, below it, the CSS variable it resolves to.

### Backgrounds & surfaces

- `bg-background` (`--background`): App background
- `bg-canvas` (`--canvas`): App shell frame: black in light themes, the ground in dark ones
- `bg-card` (`--card`): Cards, raised panels
- `bg-popover` (`--popover`): Popovers, menus
- `bg-muted` (`--muted`): Subtle fills
- `bg-secondary` (`--secondary`): Secondary fills
- `bg-accent` (`--accent`): Hover / active accent

## Content

### Text & foreground

- `text-foreground` (`--foreground`): Primary text
- `text-body` (`--body`): Reading copy: ledes, quotes, answers
- `text-muted-foreground` (`--muted-foreground`): Meta: captions, roles, dates
- `text-card-foreground` (`--card-foreground`): Text on cards

Inline text links use one role, `text-link`, derived from `--brand` so a link carries the active accent. It stays its own role because it is tuned for *text* where `--brand` is tuned for fills: the raw accent only reaches 3.6:1 as text on white, so the light theme darkens it to clear the 4.5:1 AA floor while the dark themes use it straight. Keep it distinct from `text-info`, which is a status hue and never a link. Links carry a hairline underline at rest and turn both the text and the underline `text-link` on hover. Do not hand-roll that treatment: [use `<Link variant="prose">`](https://www.koalaui.com/docs/components/link.md).

### Links

- `text-link` (`--link`): Inline text links (the accent, darkened for text on light)

## Brand & state

### Actions

- `bg-primary` (`--primary`): Primary actions
- `bg-secondary` (`--secondary`): Secondary actions
- `bg-brand` (`--brand`): Accent, set via data-accent
- `text-brand-foreground` (`--brand-foreground`): Ink on a brand fill (white, dark on lime)
- `bg-destructive` (`--destructive`): Destructive / error

## Status

Status roles read at full strength for text and icons; soft badges derive their tint from the same role via opacity (`bg-success/10` + `text-success`).

### Feedback roles

- `bg-success` (`--success`): Success / positive
- `bg-warning` (`--warning`): Warning / caution
- `bg-info` (`--info`): Informational
- `bg-destructive` (`--destructive`): Error / danger

## Categorical hues

A small, fixed set of distinct hues for labels, tags and category badges. Use these when items need to be told apart, not ranked.

### Label & tag hues

- `bg-purple` (`--purple`)
- `bg-pink` (`--pink`)
- `bg-teal` (`--teal`)
- `bg-orange` (`--orange`)

## Lines & focus

### Borders & rings

- `border-border` (`--border`): Default borders
- `border-input` (`--input`): Form field borders
- `ring-ring` (`--ring`): Focus rings

## Literal colors

The bottom layer: raw values that do **not** respond to theming. Koala authors these in `oklch` for a wider, more even gamut, but any `color-mix()`-friendly literal works, including plain hex. Reach for a literal only when a color must stay fixed across every theme (a logo, a chart series, a brand mark). For anything that should restyle, use a semantic token above.

### The brand accent (default)

- `#F84416`, Hex: the default Koala accent
- `oklch(0.648 0.222 34.2)`, The same color, as authored

Tailwind v4’s entire oklch palette ships out of the box: 22 families × 11 shades, each a `bg-*` / `text-*` / `border-*` utility (`bg-blue-500`, `text-rose-600`, …). Every chip below is a fixed literal; hover one to read its `family-shade` name and oklch value.

| Family | 50 | 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900 | 950 |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| red | `oklch(97.1% 0.013 17.38)` | `oklch(93.6% 0.032 17.717)` | `oklch(88.5% 0.062 18.334)` | `oklch(80.8% 0.114 19.571)` | `oklch(70.4% 0.191 22.216)` | `oklch(63.7% 0.237 25.331)` | `oklch(57.7% 0.245 27.325)` | `oklch(50.5% 0.213 27.518)` | `oklch(44.4% 0.177 26.899)` | `oklch(39.6% 0.141 25.723)` | `oklch(25.8% 0.092 26.042)` |
| orange | `oklch(98% 0.016 73.684)` | `oklch(95.4% 0.038 75.164)` | `oklch(90.1% 0.076 70.697)` | `oklch(83.7% 0.128 66.29)` | `oklch(75% 0.183 55.934)` | `oklch(70.5% 0.213 47.604)` | `oklch(64.6% 0.222 41.116)` | `oklch(55.3% 0.195 38.402)` | `oklch(47% 0.157 37.304)` | `oklch(40.8% 0.123 38.172)` | `oklch(26.6% 0.079 36.259)` |
| amber | `oklch(98.7% 0.022 95.277)` | `oklch(96.2% 0.059 95.617)` | `oklch(92.4% 0.12 95.746)` | `oklch(87.9% 0.169 91.605)` | `oklch(82.8% 0.189 84.429)` | `oklch(76.9% 0.188 70.08)` | `oklch(66.6% 0.179 58.318)` | `oklch(55.5% 0.163 48.998)` | `oklch(47.3% 0.137 46.201)` | `oklch(41.4% 0.112 45.904)` | `oklch(27.9% 0.077 45.635)` |
| yellow | `oklch(98.7% 0.026 102.212)` | `oklch(97.3% 0.071 103.193)` | `oklch(94.5% 0.129 101.54)` | `oklch(90.5% 0.182 98.111)` | `oklch(85.2% 0.199 91.936)` | `oklch(79.5% 0.184 86.047)` | `oklch(68.1% 0.162 75.834)` | `oklch(55.4% 0.135 66.442)` | `oklch(47.6% 0.114 61.907)` | `oklch(42.1% 0.095 57.708)` | `oklch(28.6% 0.066 53.813)` |
| lime | `oklch(98.6% 0.031 120.757)` | `oklch(96.7% 0.067 122.328)` | `oklch(93.8% 0.127 124.321)` | `oklch(89.7% 0.196 126.665)` | `oklch(84.1% 0.238 128.85)` | `oklch(76.8% 0.233 130.85)` | `oklch(64.8% 0.2 131.684)` | `oklch(53.2% 0.157 131.589)` | `oklch(45.3% 0.124 130.933)` | `oklch(40.5% 0.101 131.063)` | `oklch(27.4% 0.072 132.109)` |
| green | `oklch(98.2% 0.018 155.826)` | `oklch(96.2% 0.044 156.743)` | `oklch(92.5% 0.084 155.995)` | `oklch(87.1% 0.15 154.449)` | `oklch(79.2% 0.209 151.711)` | `oklch(72.3% 0.219 149.579)` | `oklch(62.7% 0.194 149.214)` | `oklch(52.7% 0.154 150.069)` | `oklch(44.8% 0.119 151.328)` | `oklch(39.3% 0.095 152.535)` | `oklch(26.6% 0.065 152.934)` |
| emerald | `oklch(97.9% 0.021 166.113)` | `oklch(95% 0.052 163.051)` | `oklch(90.5% 0.093 164.15)` | `oklch(84.5% 0.143 164.978)` | `oklch(76.5% 0.177 163.223)` | `oklch(69.6% 0.17 162.48)` | `oklch(59.6% 0.145 163.225)` | `oklch(50.8% 0.118 165.612)` | `oklch(43.2% 0.095 166.913)` | `oklch(37.8% 0.077 168.94)` | `oklch(26.2% 0.051 172.552)` |
| teal | `oklch(98.4% 0.014 180.72)` | `oklch(95.3% 0.051 180.801)` | `oklch(91% 0.096 180.426)` | `oklch(85.5% 0.138 181.071)` | `oklch(77.7% 0.152 181.912)` | `oklch(70.4% 0.14 182.503)` | `oklch(60% 0.118 184.704)` | `oklch(51.1% 0.096 186.391)` | `oklch(43.7% 0.078 188.216)` | `oklch(38.6% 0.063 188.416)` | `oklch(27.7% 0.046 192.524)` |
| cyan | `oklch(98.4% 0.019 200.873)` | `oklch(95.6% 0.045 203.388)` | `oklch(91.7% 0.08 205.041)` | `oklch(86.5% 0.127 207.078)` | `oklch(78.9% 0.154 211.53)` | `oklch(71.5% 0.143 215.221)` | `oklch(60.9% 0.126 221.723)` | `oklch(52% 0.105 223.128)` | `oklch(45% 0.085 224.283)` | `oklch(39.8% 0.07 227.392)` | `oklch(30.2% 0.056 229.695)` |
| sky | `oklch(97.7% 0.013 236.62)` | `oklch(95.1% 0.026 236.824)` | `oklch(90.1% 0.058 230.902)` | `oklch(82.8% 0.111 230.318)` | `oklch(74.6% 0.16 232.661)` | `oklch(68.5% 0.169 237.323)` | `oklch(58.8% 0.158 241.966)` | `oklch(50% 0.134 242.749)` | `oklch(44.3% 0.11 240.79)` | `oklch(39.1% 0.09 240.876)` | `oklch(29.3% 0.066 243.157)` |
| blue | `oklch(97% 0.014 254.604)` | `oklch(93.2% 0.032 255.585)` | `oklch(88.2% 0.059 254.128)` | `oklch(80.9% 0.105 251.813)` | `oklch(70.7% 0.165 254.624)` | `oklch(62.3% 0.214 259.815)` | `oklch(54.6% 0.245 262.881)` | `oklch(48.8% 0.243 264.376)` | `oklch(42.4% 0.199 265.638)` | `oklch(37.9% 0.146 265.522)` | `oklch(28.2% 0.091 267.935)` |
| indigo | `oklch(96.2% 0.018 272.314)` | `oklch(93% 0.034 272.788)` | `oklch(87% 0.065 274.039)` | `oklch(78.5% 0.115 274.713)` | `oklch(67.3% 0.182 276.935)` | `oklch(58.5% 0.233 277.117)` | `oklch(51.1% 0.262 276.966)` | `oklch(45.7% 0.24 277.023)` | `oklch(39.8% 0.195 277.366)` | `oklch(35.9% 0.144 278.697)` | `oklch(25.7% 0.09 281.288)` |
| violet | `oklch(96.9% 0.016 293.756)` | `oklch(94.3% 0.029 294.588)` | `oklch(89.4% 0.057 293.283)` | `oklch(81.1% 0.111 293.571)` | `oklch(70.2% 0.183 293.541)` | `oklch(60.6% 0.25 292.717)` | `oklch(54.1% 0.281 293.009)` | `oklch(49.1% 0.27 292.581)` | `oklch(43.2% 0.232 292.759)` | `oklch(38% 0.189 293.745)` | `oklch(28.3% 0.141 291.089)` |
| purple | `oklch(97.7% 0.014 308.299)` | `oklch(94.6% 0.033 307.174)` | `oklch(90.2% 0.063 306.703)` | `oklch(82.7% 0.119 306.383)` | `oklch(71.4% 0.203 305.504)` | `oklch(62.7% 0.265 303.9)` | `oklch(55.8% 0.288 302.321)` | `oklch(49.6% 0.265 301.924)` | `oklch(43.8% 0.218 303.724)` | `oklch(38.1% 0.176 304.987)` | `oklch(29.1% 0.149 302.717)` |
| fuchsia | `oklch(97.7% 0.017 320.058)` | `oklch(95.2% 0.037 318.852)` | `oklch(90.3% 0.076 319.62)` | `oklch(83.3% 0.145 321.434)` | `oklch(74% 0.238 322.16)` | `oklch(66.7% 0.295 322.15)` | `oklch(59.1% 0.293 322.896)` | `oklch(51.8% 0.253 323.949)` | `oklch(45.2% 0.211 324.591)` | `oklch(40.1% 0.17 325.612)` | `oklch(29.3% 0.136 325.661)` |
| pink | `oklch(97.1% 0.014 343.198)` | `oklch(94.8% 0.028 342.258)` | `oklch(89.9% 0.061 343.231)` | `oklch(82.3% 0.12 346.018)` | `oklch(71.8% 0.202 349.761)` | `oklch(65.6% 0.241 354.308)` | `oklch(59.2% 0.249 0.584)` | `oklch(52.5% 0.223 3.958)` | `oklch(45.9% 0.187 3.815)` | `oklch(40.8% 0.153 2.432)` | `oklch(28.4% 0.109 3.907)` |
| rose | `oklch(96.9% 0.015 12.422)` | `oklch(94.1% 0.03 12.58)` | `oklch(89.2% 0.058 10.001)` | `oklch(81% 0.117 11.638)` | `oklch(71.2% 0.194 13.428)` | `oklch(64.5% 0.246 16.439)` | `oklch(58.6% 0.253 17.585)` | `oklch(51.4% 0.222 16.935)` | `oklch(45.5% 0.188 13.697)` | `oklch(41% 0.159 10.272)` | `oklch(27.1% 0.105 12.094)` |
| slate | `oklch(98.4% 0.003 247.858)` | `oklch(96.8% 0.007 247.896)` | `oklch(92.9% 0.013 255.508)` | `oklch(86.9% 0.022 252.894)` | `oklch(70.4% 0.04 256.788)` | `oklch(55.4% 0.046 257.417)` | `oklch(44.6% 0.043 257.281)` | `oklch(37.2% 0.044 257.287)` | `oklch(27.9% 0.041 260.031)` | `oklch(20.8% 0.042 265.755)` | `oklch(12.9% 0.042 264.695)` |
| gray | `oklch(98.5% 0.002 247.839)` | `oklch(96.7% 0.003 264.542)` | `oklch(92.8% 0.006 264.531)` | `oklch(87.2% 0.01 258.338)` | `oklch(70.7% 0.022 261.325)` | `oklch(55.1% 0.027 264.364)` | `oklch(44.6% 0.03 256.802)` | `oklch(37.3% 0.034 259.733)` | `oklch(27.8% 0.033 256.848)` | `oklch(21% 0.034 264.665)` | `oklch(13% 0.028 261.692)` |
| zinc | `oklch(98.5% 0 0)` | `oklch(96.7% 0.001 286.375)` | `oklch(92% 0.004 286.32)` | `oklch(87.1% 0.006 286.286)` | `oklch(70.5% 0.015 286.067)` | `oklch(55.2% 0.016 285.938)` | `oklch(44.2% 0.017 285.786)` | `oklch(37% 0.013 285.805)` | `oklch(27.4% 0.006 286.033)` | `oklch(21% 0.006 285.885)` | `oklch(14.1% 0.005 285.823)` |
| neutral | `oklch(98.5% 0 0)` | `oklch(97% 0 0)` | `oklch(92.2% 0 0)` | `oklch(87% 0 0)` | `oklch(70.8% 0 0)` | `oklch(55.6% 0 0)` | `oklch(43.9% 0 0)` | `oklch(37.1% 0 0)` | `oklch(26.9% 0 0)` | `oklch(20.5% 0 0)` | `oklch(14.5% 0 0)` |
| stone | `oklch(98.5% 0.001 106.423)` | `oklch(97% 0.001 106.424)` | `oklch(92.3% 0.003 48.717)` | `oklch(86.9% 0.005 56.366)` | `oklch(70.9% 0.01 56.259)` | `oklch(55.3% 0.013 58.071)` | `oklch(44.4% 0.011 73.639)` | `oklch(37.4% 0.01 67.558)` | `oklch(26.8% 0.007 34.298)` | `oklch(21.6% 0.006 56.043)` | `oklch(14.7% 0.004 49.25)` |

**Rule of thumb:** if it should change when the theme changes, it is a **token**: reach for a role above. If it must stay exactly that color forever, it is a **literal**.

---

<!-- https://www.koalaui.com/docs/foundations/typography.md -->

# Typography

Two typefaces: Inter carries UI and body copy, DM Sans the headings, with the system monospace as the code fallback. The scale, weights, tracking and leading come straight from Tailwind v4.

## Font families

Two bundled typefaces, both variable fonts loaded via `next/font`. `font-sans` (Inter) is the workhorse for UI, body and the smallest headings (`h5`–`h6`); `font-heading` (DM Sans, with an optical-size axis) carries the headings `h1`–`h4`, so the display voice reaches the content-level titles too. `font-mono` falls back to the platform UI monospace - nothing to download. A heading that acts as a 14px UI label rather than a title opts back into Inter with a plain `font-sans`, which beats the bare element rule.

font-sans The quick brown fox

font-heading The quick brown fox

font-mono const koala = true

## Type scale

Sizes are absolute (`rem`). Each ships a paired line-height that snaps the rendered leading onto the 4px / 0.25rem grid - the lead column.

- `text-xs`: 0.75rem · 12px (lh 1.333 → 1rem / 16px)
- `text-sm`: 0.875rem · 14px (lh 1.429 → 1.25rem / 20px)
- `text-base`: 1rem · 16px (lh 1.5 → 1.5rem / 24px)
- `text-lg`: 1.125rem · 18px (lh 1.556 → 1.75rem / 28px)
- `text-xl`: 1.25rem · 20px (lh 1.4 → 1.75rem / 28px)
- `text-2xl`: 1.5rem · 24px (lh 1.333 → 2rem / 32px)
- `text-3xl`: 1.875rem · 30px (lh 1.2 → 2.25rem / 36px)
- `text-4xl`: 2.25rem · 36px (lh 1.111 → 2.5rem / 40px)
- `text-5xl`: 3rem · 48px (lh 1 → 3rem / 48px)

These are raw sizes, not heading roles. A bare `h1`–`h4` carries the DM Sans face (with the negative tracking on `h1`–`h2` only) while `h5`–`h6` stay in Inter (see Font families), but none carry an intrinsic size, so each context steps off this scale on its own. For the document scale the [Rich Text Editor](https://www.koalaui.com/docs/components/rich-text-editor.md#prose-scale) maps onto `H1`–`H4` and body copy, see its Prose scale.

## Weights

Four stops off the variable weight axis, shared by both faces. We skip 100–300 (too fragile at text sizes) and everything above 700 (heavier than the brand needs).

- `font-normal`: 400 (body)
- `font-medium`: 500 (UI labels)
- `font-semibold`: 600 (headings)
- `font-bold`: 700 (emphasis)

## Tracking

`letter-spacing` in `em`, so it scales with size. The px column is resolved at this 18px sample. Rule of thumb: tighten large display text (`tracking-tight`), leave body at normal, and only open up small all-caps labels.

- `tracking-tighter`: -0.05em (−0.90px @ 18px)
- `tracking-tight`: -0.025em (−0.45px @ 18px)
- `tracking-normal`: 0em (0px @ 18px)
- `tracking-wide`: 0.025em (+0.45px @ 18px)
- `tracking-wider`: 0.05em (+0.90px @ 18px)
- `tracking-widest`: 0.1em (+1.80px @ 18px)

## Leading

Unitless `line-height`, multiplied by the font-size. The px column is resolved at this 16px sample. Most components inherit the type scale’s paired leading; reach for these only to override it.

- `leading-tight`: 1.25 (20px @ 16px)
- `leading-snug`: 1.375 (22px @ 16px)
- `leading-normal`: 1.5 (24px @ 16px)
- `leading-relaxed`: 1.625 (26px @ 16px)
- `leading-loose`: 2 (32px @ 16px)

---

<!-- https://www.koalaui.com/docs/foundations/spacing.md -->

# Spacing & Layout

Spacing and container widths are Tailwind v4 defaults, used as-is, with one addition (--container-8xl, 1440px) kept as an opt-in escape above the canonical 1280px section cap.

## Spacing scale

Every `p-*`, `m-*`, `gap-*` and `size-*` step is `0.25rem × n`.

- `1`: 0.25rem
- `2`: 0.5rem
- `3`: 0.75rem
- `4`: 1rem
- `6`: 1.5rem
- `8`: 2rem
- `12`: 3rem
- `16`: 4rem
- `24`: 6rem

## Containers

- `max-w-sm`: 24rem
- `max-w-md`: 28rem
- `max-w-lg`: 32rem
- `max-w-2xl`: 42rem
- `max-w-3xl`: 48rem
- `max-w-5xl`: 64rem
- `max-w-7xl`: 80rem

---

<!-- https://www.koalaui.com/docs/foundations/breakpoints.md -->

# Breakpoints

The five responsive thresholds Koala builds on: Tailwind v4 defaults, used verbatim. Styles are mobile-first: an unprefixed utility applies everywhere, a prefixed one applies from that width up.

## The scale

Each breakpoint is a `min-width` media query. The bar shows where each one kicks in, relative to the `2xl` ceiling.

- `sm`: 40rem (≥ 640px)
- `md`: 48rem (≥ 768px)
- `lg`: 64rem (≥ 1024px)
- `xl`: 80rem (≥ 1280px)
- `2xl`: 96rem (≥ 1536px)

## Mobile-first

Write the small-screen layout with unprefixed utilities, then layer overrides at each breakpoint and up. Don't use `sm:` to target only mobile: it means *640px and wider*.

```tsx title="responsive.tsx"
// Stacked on phones, side-by-side from 640px (sm), wider gap from 1024px (lg).
<div className="flex flex-col gap-4 sm:flex-row lg:gap-8">
  <aside className="w-full sm:w-64">…</aside>
  <main className="flex-1">…</main>
</div>
```

## Targeting a single range

For styles that should apply *below* a breakpoint, use the `max-*` variants. Combine a min and a max prefix to scope a utility to a single band.

```tsx title="ranges.tsx"
<div className="max-sm:hidden">Hidden below 640px</div>
<div className="md:max-lg:bg-accent">Tinted only between 768px and 1024px</div>
```

## Previewing breakpoints

Media queries respond to the *viewport*, so you can't see a layout reflow just by resizing a column. The [Marketing Sections](https://www.koalaui.com/marketing/sections/hero.md) preview renders each section inside an iframe, so its own breakpoints respond to the frame width, so switch between Mobile (375px), Tablet (768px) and Desktop, or drag the handle to any width in between.

---

<!-- https://www.koalaui.com/docs/foundations/density.md -->

# Density

Density is the cross-cutting knob that retunes padding, gaps and control heights without touching color or radius. comfortable is the marketing-first default; compact is the application-UI preset.

## Two densities

The same Card, rendered `comfortable` (the default) and `compact`. Only spacing and title scale change - corners stay the brand 16px radius.

```tsx
<Card density="comfortable">…</Card>
<Card density="compact">…</Card>
```

## On a real block

Density isn’t a one-component knob. Here it drives a whole [sign-in block](https://www.koalaui.com/docs/components/auth-form.md): toggle it and the card retunes all at once - `comfortable` opens the padding, gaps and title up for a roomier marketing feel, `compact` tightens everything for dense app UI.

## Application-UI spec

The compact preset, modelled on a dense dashboard: 16px padding and gaps, 1rem card titles, 14px muted descriptions, and controls that aren’t too tall.

|  | comfortable | compact |
| --- | --- | --- |
| Card padding / gap | p-6 · gap-6 | p-4 · gap-4 (16px) |
| Card title | text-lg | text-base (1rem) |
| Card description | text-sm muted | text-sm muted |
| Button height (default md) | h-9 (36px) | h-9 (36px) |
| Dialog padding / gap | p-6 · gap-4 | p-4 · gap-3 |
| Tabs pill | rounded-xl p-1 | rounded-lg p-0.5 |

## Set it once for a subtree

Wrap an app shell in `DensityProvider` and every nested Koala component tightens up - no per-instance props. Resolution precedence is **explicit prop > nearest provider > comfortable**, so any component can opt back out.

```tsx title="app-shell.tsx"
import { DensityProvider } from "@/lib/density"

export function Dashboard({ children }) {
  // Everything inside renders compact unless a component sets density itself.
  return <DensityProvider density="compact">{children}</DensityProvider>
}
```

```tsx
<DensityProvider density="compact">
  <Card>…</Card>
  <Button>Save threshold</Button>
</DensityProvider>
```

## Which components honor density

Density reaches across the library: controls (**Button**, **Select**, **Tabs**, **Pagination**), surfaces (**Card**, **Dialog**, **Drawer**), data display (**Stat**, **List**, **Description List**, **Data Table**) and the form blocks all retune. **Avatar** and **Badge** opt out by design - they already own explicit pixel `size` scales, so a spacing axis would be redundant.

Reading density makes a component a client component. Card, Dialog and Tabs already were; **Button** is now `"use client"` too, so it can participate in provider-driven density.

---

<!-- https://www.koalaui.com/docs/foundations/surfaces.md -->

# Radius & Shadows

The surface foundation. Radius is driven by a single --radius knob, so the whole scale re-rounds from one value. Shadows carry per-theme values so dark surfaces stay legible.

## Radius

The scale is relative to `--radius` (`1rem` / 16px), so `rounded-lg` = the knob itself. Quarter-step multipliers keep every value on the 4px grid; px below are resolved at a 16px root.

- `rounded-sm`: 8px · 0.5rem · 0.5×
- `rounded-md`: 12px · 0.75rem · 0.75×
- `rounded-lg`: 16px · 1rem · 1×
- `rounded-xl`: 20px · 1.25rem · 1.25×
- `rounded-2xl`: 24px · 1.5rem · 1.5×
- `rounded-3xl`: 28px · 1.75rem · 1.75×
- `rounded-4xl`: 32px · 2rem · 2×

## Shadows / elevation

Switch to a dark theme in the header - the shadows shift to heavier, cooler values automatically.

- `shadow-xs`
- `shadow-sm`
- `shadow-md`
- `shadow-lg`
- `shadow-xl`

---

<!-- https://www.koalaui.com/docs/foundations/aspect-ratio.md -->

# Aspect Ratio

The shapes media is framed in. Koala uses Tailwind's aspect-* utilities as-is: pick the ratio on the frame, let the image crop to fill it, and the layout holds its shape before the pixels arrive.

## Reframing

Switch between ratios to see one photo reframed. The frame keeps its ratio at any width, and the image crops around its center. Turn off *Crop to fill* to letterbox it instead.

## Common ratios

Eight ratios cover almost every surface. Landscape ones suit heroes, covers and video; portrait ones suit people, posters and phone screens.

## Usage

Put the ratio on the frame, not on the image. The frame reserves its space on first paint, so nothing shifts when the photo loads. The image fills it with `object-cover`. Keywords cover the two common cases (`aspect-square`, `aspect-video`), and any other ratio is a fraction: `aspect-4/5`.

```tsx title="cover.tsx"
<div className="relative aspect-video overflow-hidden rounded-lg bg-muted">
  <img src={src} alt={alt} className="absolute inset-0 size-full object-cover" />
</div>
```

## Cover or contain

`object-cover` fills the frame and trims whatever falls outside it, which is right for photography. `object-contain` shows the whole image and leaves bars on the frame's `bg-muted`. Use it for logos, screenshots and diagrams, where a cropped edge loses information. Move the focal point of a crop with `object-top` or `object-[50%_30%]`.

```tsx title="contain.tsx"
// A screenshot: never crop it, letterbox it.
<div className="relative aspect-4/3 overflow-hidden rounded-lg bg-muted">
  <img src={shot} alt={alt} className="absolute inset-0 size-full object-contain" />
</div>
```

---

<!-- https://www.koalaui.com/docs/foundations/motion.md -->

# Motion

Three easing curves and three durations, exposed as Tailwind utilities and mirrored in lib/motion.ts for JS animation. Never inline a raw cubic-bezier or ms value.

## Easing

Same duration, different curves - press Play to compare.

## Duration

Same curve (`ease-out`), different durations.

## Spring: overshoot for confirmation

A fourth curve, `ease-spring`, overshoots past its end value before settling back. Reserve it for moments that should feel rewarding - a confirmation, a checkmark, a control that pops into place - never for routine UI movement, where the bounce reads as nervous. Press Play to compare the overshoot against a flat `ease-out`.

```tsx title="confirm.tsx"
// Spring overshoots past the end, then settles - a "pop" on confirmation.
<div
  className={cn(
    // Name 'scale', not 'transform': in Tailwind v4 scale-* sets its own CSS property.
    "transition-[scale,opacity] duration-base ease-spring",
    confirmed ? "scale-100 opacity-100" : "scale-50 opacity-0",
  )}
/>

// JS-driven animation
import { easing, duration } from "@/lib/motion"
element.animate(keyframes, {
  duration: duration.base,        // 300
  easing: easing.spring,          // cubic-bezier(0.34, 1.56, 0.64, 1)
})
```

## Sine: for values that oscillate

`ease-sine` is symmetric and leaves and arrives at zero velocity. Reach for it when a value swings back and forth through a multi-stop `@keyframes` rather than travelling from A to B once - an error shake, a pendulum, a breathing loop. The reason is easy to miss: a timing function applies to *every segment between stops*, so `ease-out` makes each swing shoot to its extreme and stall there, and the motion reads as a buzz instead of a wobble.

```tsx title="globals.css"
/* Keyframe only the extremes; ease-sine draws the arc between them. */
--animate-otp-shake: otp-shake 650ms var(--ease-sine);

@keyframes otp-shake {
  0%, 100% { transform: translate3d(0, 0, 0); }
  17% { transform: translate3d(calc(var(--otp-shake-distance) * -1), 0, 0); }
  50% { transform: translate3d(calc(var(--otp-shake-distance) * 0.55), 0, 0); }
  83% { transform: translate3d(calc(var(--otp-shake-distance) * -0.25), 0, 0); }
}
```

## Usage

Compose the utilities directly in components, or import the constants from `lib/motion.ts` when animating from JS.

```tsx title="example.tsx"
// CSS / Tailwind - preferred
<div className="transition-colors duration-base ease-out" />

// JS-driven animation
import { easing, duration } from "@/lib/motion"
element.animate(keyframes, {
  duration: duration.base,        // 300
  easing: easing.out,             // cubic-bezier(0.23, 1, 0.32, 1)
})
```

## Interruptible transitions

Use CSS `transition` for any animation driven by interactive state - hover, focus, active, data attributes. CSS transitions can be reversed mid-flight; keyframe animations cannot. Reserve `@keyframes` for staged sequences that run once (spinners, skeleton pulses, entrance choreography).

```tsx title="button.tsx"
// ✓ CSS transition - interruptible, reverses cleanly on mouse-out
<button className="bg-primary transition-colors duration-fast ease-out hover:bg-primary/80">
  Save
</button>

// ✗ Keyframe - fires once, cannot be reversed mid-animation
<button className="animate-pulse">Save</button>
```

## Specify properties, never transition-all

`transition: all` triggers a style recalc on every CSS property change, including layout-affecting ones like `width` and `padding`. Always name the properties you actually animate. Tailwind’s `transition-transform` covers `transform, translate, scale, rotate` in one utility.

```tsx title="card.tsx"
// ✓ Specific - only the GPU-composited properties
<div className="transition-[opacity,transform] duration-base ease-out" />
<div className="transition-transform duration-fast ease-out hover:scale-[1.02]" />
<div className="transition-colors duration-fast ease-out" />

// ✗ Transitions layout + paint + composite on every change
<div className="transition-all duration-base" />
```

## Press and hover feedback

Every interactive control confirms a press with a small scale-down - `active:scale-[0.96]`, never below 0.95 - and cards add a subtle hover lift. The feedback is what makes a surface feel tappable. Hover and press the cards below; expose a `static` prop to opt out where the motion would be distracting.

One Tailwind v4 trap lives here: `scale-*` and `translate-*` set their own standalone CSS properties, not `transform`. A `transition-[box-shadow,transform]` will silently fail to tween them - they snap. Name `scale` and `translate` in the list, or use the `transition-transform` utility, which already covers all four.

```tsx title="action-card.tsx"
// ✓ Press scale + hover lift, with scale/translate named in the transition.
<button
  className="cursor-pointer rounded-xl border border-border bg-card p-4
             transition-[scale,translate,box-shadow,border-color] duration-fast ease-out
             hover:-translate-y-0.5 hover:shadow-md
             active:scale-[0.96]"
/>

// ✗ scale-* and translate-* are standalone props in v4 - 'transform' won't reach them.
<button className="transition-[box-shadow,transform] hover:-translate-y-0.5 active:scale-[0.96]" />
```

## Enter animations: split and stagger

Animating a container as one block looks mechanical. Break the content into chunks and stagger each by ~70-100 ms so the reader perceives hierarchy rather than a single blob appearing. Reach for the `Stagger` primitive rather than hand-rolling per-item delays. It sets each child’s delay off the motion tokens, plays once on mount, and falls back to no animation under reduced-motion.

```tsx title="stagger.tsx"
import { Stagger } from "@/lib/stagger"

// ✓ Lists / grids: one wrapper, the cascade is automatic.
<Stagger className="grid grid-cols-3 gap-2">
  {items.map((item) => (
    <Card key={item.id}>{item.name}</Card>
  ))}
</Stagger>

// ✓ Below the fold: reveal as it scrolls in, with a soft focus pull.
<Stagger inView blur className="grid grid-cols-3 gap-2">
  {items.map((item) => (
    <Card key={item.id}>{item.name}</Card>
  ))}
</Stagger>

// ✗ Whole container in one shot
<div className="animate-fade-in">
  <h2>Title</h2>
  <p>Body</p>
  <Button>Action</Button>
</div>
```

`Stagger` animates on mount by default: the right gate for “load” cascades. With stable keys, reordering reuses the DOM and won’t replay; genuinely new content (a filter, a fresh page, a layout switch) mounts and cascades. The DataTable’s cards layout uses it. Tune the gap with `step` (default 70 ms); add `blur` for the 4px → 0 focus pull and `inView` to hold the cascade until it scrolls into view (the same props a [Section Header](https://www.koalaui.com/docs/components/section-header.md) takes, so a header and the grid below it can reveal as one). Direct children must forward `className` and `style`.

## Exit animations: stay subtle

Exit animations should be softer than enters. A full-height collapse or a large translate draws too much attention to something leaving. Use a small fixed `translateY` (4–8 px) with a fade - the element slips away rather than crashing out.

```tsx title="toast.tsx"
// ✓ Subtle exit - short distance, fades out
// Enter: slides up 8px + fades in
// Exit:  slides down 4px + fades out (half the travel, softer)
<div
  className={cn(
    "transition-[opacity,transform] duration-base ease-out",
    visible
      ? "translate-y-0 opacity-100"
      : "translate-y-1 opacity-0",   // 4 px - barely moves
  )}
/>

// ✗ Full collapse - too dramatic
<div className={cn(visible ? "h-auto opacity-100" : "h-0 opacity-0")} />
```

## Scale from the origin

A surface that scales open - a menu, a popover, a tooltip - should grow out of the control that opened it, not its own center. A menu that zooms from its midpoint looks like it materialized in space; one anchored to its trigger looks like it unfolded from the button. Radix exposes the resolved corner as a CSS variable, so pin `transform-origin` to it and let the `zoom-in-95` / `zoom-out-95` enter and exit do the rest. Open both panels and watch where each one grows from.

## Morphing

A surface that changes size along with what it shows (a pill opening into a card, a dialog moving to a taller step) should not swap one box for another. It keeps one box, eases it to the new size and crossfades the contents inside. The technique, `useMorphBox`, and its rules have a page of their own: [Morphing](https://www.koalaui.com/docs/foundations/morphing.md).

## Icon animations

Never toggle icon visibility with a conditional render - the outgoing icon disappears instantly with no exit animation. Keep both icons in the DOM, position the secondary one absolutely, and cross-fade using `opacity`, `scale`, and `blur`. Enter: scale `0.25 → 1`, opacity `0 → 1`, blur `4px → 0`.

```tsx title="copy-button.tsx"
"use client"
import { Check, Copy } from "@phosphor-icons/react"
import { cn } from "@/lib/utils"

const iconClass = (visible: boolean) =>
  cn(
    "transition-[opacity,transform,filter] duration-fast",
    // cubic-bezier(0.2,0,0,1) - the snappy curve for icon swaps
    "[transition-timing-function:cubic-bezier(0.2,0,0,1)]",
    visible
      ? "scale-100 opacity-100 blur-0"
      : "scale-[0.25] opacity-0 blur-[4px]",
  )

export function CopyButton({ onCopy }: { onCopy: () => void }) {
  const [copied, setCopied] = React.useState(false)

  return (
    <button
      onClick={() => { onCopy(); setCopied(true); setTimeout(() => setCopied(false), 1500) }}
      className="relative inline-flex size-7 items-center justify-center"
    >
      <Copy className={cn("absolute", iconClass(!copied))} />
      <Check className={cn("absolute", iconClass(copied))} />
    </button>
  )
}
```

## Disclosure carets: turn, don’t swap

The section above cross-fades two glyphs that mean *different things*. A caret reporting open or closed is the opposite case: it is one mark pointing two ways, so it **rotates**. Swapping a `CaretUp` for a `CaretDown` throws away the thing that carried the meaning, which is the turn itself.

Two utilities carry it, and which one you use is part of the convention rather than a judgement call. `caret-turn` (`duration-base`) is for a caret answering a **content reveal**, so the glyph and the height it announces move on one clock. `caret-turn-fast` (`duration-fast`) is for a caret on a **popover trigger**, which opens quicker than a region reveals. Both bundle the reduced-motion stand-down, so it cannot be forgotten; the rotation itself stays at the call site, because it varies (180° for a panel, 90° for a tree branch, 45° for a plus becoming a cross).

```tsx title="disclosure.tsx"
// ✓ One glyph, turned by state. The beat and the reduced-motion guard ride along.
<CaretDown className="size-4 caret-turn group-data-[state=open]:rotate-180" />

// ✓ A popover trigger opens faster than a region reveals.
<CaretDown className="size-4 caret-turn-fast group-data-[state=open]:rotate-180" />

// ✗ Two glyphs swapped: the turn, which was the whole signal, is gone.
{open ? <CaretUp /> : <CaretDown />}

// ✗ Longhand: animates, but never stands down under reduced motion.
<CaretDown className="transition-transform duration-base ease-out" />
```

## Skip animation on page load

Elements that are visible on first render should not animate in - the user never asked for that transition. Gate CSS transitions behind a `data-mounted` attribute set in a `useEffect`. The attribute is absent during SSR and on the first paint, so the transition rule never fires.

```tsx title="panel.tsx"
"use client"
import * as React from "react"

export function Panel({ children }: { children: React.ReactNode }) {
  const ref = React.useRef<HTMLDivElement>(null)

  // Set the attribute after the first paint - transitions only fire after this.
  React.useEffect(() => {
    ref.current?.setAttribute("data-mounted", "")
  }, [])

  return (
    <div
      ref={ref}
      // Without data-mounted the element is fully visible (no opacity-0 default).
      // Once mounted, hovering or state changes can transition freely.
      className="opacity-0 transition-opacity duration-base ease-out data-[mounted]:opacity-100"
    >
      {children}
    </div>
  )
}
```

## Respect reduced motion

Some users set `prefers-reduced-motion` to avoid animation that triggers nausea or distraction. Honor it: a one-shot entrance should drop to an instant appear, and any ambient loop - a spinner, a shimmer, a marquee - should hold still. Tailwind’s `motion-reduce:` and `motion-safe:` variants cover the inline cases; the `Stagger` primitive already gates itself this way. Flip the preference below and Replay to feel the difference a reduced-motion user gets: the same grid, but the cascade is gone.

## will-change

`will-change` promotes an element to its own GPU layer before the animation starts, eliminating first-frame stutter. Only use it on properties the GPU can composite: `transform`, `opacity`, and `filter`. Overusing it wastes VRAM and can slow down everything else. Add it only when you observe a visible first-frame glitch.

```tsx title="drawer.tsx"
// ✓ Composited property - GPU can handle this without a layout pass
<div className="will-change-transform transition-transform duration-slow ease-drawer" />

// ✗ will-change: all - promotes the element for *every* property, wastes VRAM
<div className="will-change-auto transition-all duration-base" />

// ✗ Left on permanently - keeps the layer alive even when not animating
// Only add will-change while animating; remove it after.
```

---

<!-- https://www.koalaui.com/docs/foundations/morphing.md -->

# Morphing

A surface that changes what it shows eases to its new size while its contents crossfade inside, so the eye follows one object instead of watching one leave and another arrive.

## One object, not two

A pill turns into a card, a rail into a menu, a dialog moves to a taller step. The easy version swaps one box for another in a single frame: everything around it jumps, and the reader has to find their place again. A morph keeps one box on screen and eases it to the new size while the contents crossfade in place, so the change reads as the same object doing something new. Run the export in both modes.

The box growing is also the entrance. Nothing inside it needs to slide or stagger in, because the continuity is already carried by the one surface that never left.

## Measure where it’s going

The box never measures itself. It measures an inner *viewport* that is free to be its natural size. The moment the contents change, the viewport is already at the new size while the box is still at the old one, so a `ResizeObserver` on the viewport reads where the box is going rather than where it is. Written back as an inline width and height, that gives CSS two real numbers to tween between, and the clip on the box reveals the new view as it grows around it. Watch the dashed outline land first.

`useMorphBox` from `lib/morph.ts` is the whole technique: one hook and one class list. Spread `morphBox` and the returned `style` on the box, put the `ref` and `viewportClassName` on the viewport, and feed `ready` to `data-morph-ready`.

```tsx title="wizard-body.tsx"
import { morphBox, useMorphBox } from "@/lib/morph"

export function WizardBody({ step }: { step: React.ReactNode }) {
  // Destructure: reading morph.style off the object trips react-hooks/refs.
  const { ref, style, ready, viewportClassName } = useMorphBox("height")

  return (
    // The box: eases to whatever the viewport measures, and clips so it reads as one object.
    <div data-morph-ready={ready ? "" : undefined} style={style} className={cn(morphBox)}>
      {/* The viewport: its natural size, already at the next step. */}
      <div ref={ref} className={viewportClassName}>
        {step}
      </div>
    </div>
  )
}
```

Two details inside the hook are worth knowing. It reads the layout box (`offsetWidth`, `offsetHeight`), never a rect, so a press-scale on a child, which is a transform, can never feed jitter back into the size. And it takes a callback ref rather than a ref and a mount effect, because the measured node usually arrives later than the component that owns the hook: a dialog’s content, a menu’s popper, a panel behind a flag.

## Pick the axis

Tell the hook which dimensions the box owns. The viewport’s sizing follows from it, which is why `viewportClassName` comes back with the rest: a box that owns its width needs a viewport free to be wider than it is, and one that only owns its height needs a viewport that fills it.

- `"height"`: w-full (Tabs, dialogs)
- `"both"`: w-max (Island, Dock)
- `"width"`: w-max (Inline chips)

## The shape rides the size

When a box changes shape because it changes size, keep one radius and let the geometry do the work. Any radius past half the height is clamped to exactly half, so `rounded-2xl` is a perfect stadium on a 44px row and a card’s corner once the box grows. Tweening `rounded-pill` into `rounded-2xl` instead looks broken: the pill radius stays past half the height for nearly the whole run, so the box balloons into a capsule and only squares off in the last frames. Both end states are identical; play them and watch the corners in between.

When the corner has to change on purpose, derive it from the size the box is going to instead of switching classes. Island writes its measured height to a variable and resolves the corner with one formula: half the height while it is one row, capped at `radius-4xl` once it grows into a card, and on the radius knob throughout. The corner then eases with the box, between two values that are both real.

```tsx title="surface.tsx"
// ✓ One radius: clamped to a stadium while short, a card's corner once tall.
<div className="rounded-2xl transition-[width,height] duration-base ease-out" />

// ✓ A corner that must change, derived from the height it is going to (Island).
<div
  style={{ "--island-height": `${height}px` }}
  className="rounded-[min(var(--radius-pill),calc(var(--island-height)/2),var(--radius-4xl))]
             transition-[width,height,border-radius] duration-fast ease-out"
/>

// ✗ Two classes tweened: a capsule for most of the run, then a snap.
<div className={cn("transition-[width,height,border-radius]", open ? "rounded-2xl" : "rounded-pill")} />
```

## Contents crossfade in place

The box carries the movement, so the contents should not travel. The view on screen blurs in (`fade-in-0`, `zoom-in-96`, `blur-in-4`) while the view leaving is lifted out of flow, pinned to the centre where it was, and blurs out over the same beat. Lifting it out is what lets the viewport measure the incoming view at once; left in flow, it would hold the box at the old size until its exit had played.

Run the box and the crossfade on one clock. A box that lands before its contents, or contents still settling in a box that has stopped, read as two animations. Island runs both on `duration-fast`; the Dock, whose panel is larger, on `duration-base`. When the change has a direction, drilling into a layer and back out, say which way with two pixels of slide on the incoming layer only.

```tsx title="view.tsx"
// The view on screen: blurs in on the box's clock.
"data-[state=enter]:animate-in data-[state=enter]:fade-in-0 data-[state=enter]:zoom-in-96 data-[state=enter]:blur-in-4",

// The view leaving: out of flow and centred, so the viewport already measures the next one.
"data-[state=exit]:absolute data-[state=exit]:top-1/2 data-[state=exit]:left-1/2 data-[state=exit]:w-max",
"data-[state=exit]:-translate-x-1/2 data-[state=exit]:-translate-y-1/2",
"data-[state=exit]:animate-out data-[state=exit]:fade-out-0 data-[state=exit]:zoom-out-98",
"data-[state=exit]:blur-out-4 data-[state=exit]:fill-mode-forwards",

// Keyframes only. A duration with no property list transitions `all`, and the
// leaving view would slide into its centring translate instead of taking it.
"transition-none duration-base ease-out motion-reduce:animate-none",

// Layers with a direction (Dock): in from the right going deeper, from the left coming back.
"data-[direction=forward]:slide-in-from-right-2 data-[direction=backward]:slide-in-from-left-2",
```

The leaving view is `inert` and `aria-hidden`, and it usually holds the control that was just pressed (Back, Dismiss). Hand focus to the first control on screen before the browser drops it on the body, and announce the new state in a polite live region if the view that arrives has nothing to focus.

## Nothing morphs on load

A surface that is on screen at first paint was not asked to change, so it should not grow in from zero. `morphBox` only transitions under `data-morph-ready`, which the hook sets once a measurement exists: the server paints the natural size, the first measurement lands without a tween, and only the changes after it ease. Arm the crossfade the same way, on the first change of view.

When the measured node leaves, the hook drops its size with it, so a dialog that closes and opens again starts from its own content instead of easing down from whatever the last one happened to be. Under reduced motion `morphBox` stands down (`motion-reduce:transition-none`): the box takes the new size at once and the leaving view goes instead of blurring out. The change still happens; it just stops moving.

## Where not to morph

**It animates layout.** Width and height re-run layout every frame, for the box and whatever flows around it. That is cheap on a pill, a menu or a dialog body and expensive on a full-page panel. A drawer or a sheet still moves with `translate`.

**The clip is the point, and it cuts.** `overflow-hidden` is what makes the morph read as one object, and it also clips focus rings and anything not portalled. Leave the box room for a ring, draw rings inset the way `TabsPanels` does, or pad the viewport and give the space back with a negative margin, the way Island’s swap regions do (`p-1` with `-m-1`).

**Content without a ceiling turns it back into a jump.** Past a certain height the ease stops reading as movement and starts reading as lag. Cap the box with a max height and scroll inside it.

**Don’t cascade inside it.** Rows that stagger up through a growing box fight the box. The morph is the entrance, so let the rows arrive with it.

## In the library

- [Island](https://www.koalaui.com/docs/components/island.md)

  A floating pill whose views crossfade while it eases to each one’s size, corner included.

- [Dock](https://www.koalaui.com/docs/components/dock.md)

  A rail of icons that opens, in place, into a labelled menu with drill-down layers.

- [Tabs](https://www.koalaui.com/docs/components/tabs.md)

  `TabsPanels` eases the block’s height between panels of different lengths.

- [Animated Label](https://www.koalaui.com/docs/components/animated-label.md)

  The label rolls to its new copy while its box eases between the two widths.

- [Button](https://www.koalaui.com/docs/components/button.md)

  `swapKey` hands the label to Animated Label, so Next to Done morphs instead of jumping.

- [Carousel](https://www.koalaui.com/docs/components/carousel.md)

  The active dot grows into a pill: `rounded-full` rides the width, one radius the whole way.

---

<!-- https://www.koalaui.com/docs/foundations/scroll-fade.md -->

# Fade

A soft mask that dissolves a box into its surface at its edges. Use the static fade-* utilities for a constant bleed, or the scroll-fade-* siblings to track scroll position. Pure CSS, no JS.

## Static fade

The base primitive: a constant `mask-image` gradient that fades one or more edges into the surface, no matter the scroll position. Reach for it whenever the bleed is fixed - a marquee that drifts in from both sides, a masonry that clips at the section edges, or a preview that peeks up from the bottom of its frame.

```tsx title="logos.tsx"
// A marquee whose tiles dissolve into the band at both edges, at any scroll position.
<div className="group/marquee overflow-hidden fade-x [--fade-size:10%]">
  {/* Render the set twice so the -50% marquee loops with no seam. */}
  <div className="flex w-max animate-marquee gap-3 pr-3 group-hover/marquee:[animation-play-state:paused] motion-reduce:[animation:none]">
    {[...logos, ...logos].map((logo, i) => (
      <Logo key={i} {...logo} />
    ))}
  </div>
</div>
```

- `fade`
- `fade-x`
- `fade-t`
- `fade-b`
- `fade-l`
- `fade-r`

Depth per edge is the `--fade-size` knob (default `min(2.5rem, 12%)`); set it with an arbitrary property like `[--fade-size:6%]`. Inside that band the alpha runs on an eased smoothstep, not a straight line: a linear ramp turns a corner at each end of the band and the eye reads those corners as edges, which is exactly what the fade is there to avoid. It only gets more visible the deeper the band, so a long dissolve like `LoadMore`’s depends on it. The rest of this page covers `scroll-fade`, the same mask made to track scroll progress instead.

## Scroll-aware preview

Scroll the list. At the top the leading edge is crisp; once content slides under it, the top fades while the bottom keeps hinting at more below. Change the fade depth to feel the `--scroll-fade-size` knob.

## How it works

The fade is a `mask-image` linear gradient whose two inner stops are driven by `animation-timeline: scroll(self)` - a scroll-progress timeline, not a clock. Each edge’s depth is a registered`@property` number from `0` (crisp) to `1` (faded), so it interpolates as you scroll: the top fades in over the first `--scroll-fade-reveal` of travel, and the bottom sharpens over the last. No scroll listeners, no JavaScript, no layout cost.

Put the mask on the scroll container itself, and the border on a wrapper - the gradient masks whatever it covers, so a border on the same element would fade too. The frame stays crisp; only the content dissolves into the edge.

## Usage

Wrap the scroll area in a bordered, `overflow-hidden` frame, then put `scroll-fade` on the inner scrolling element.

```tsx title="notifications.tsx"
// Frame owns the border + corners; the inner element owns the scroll + mask.
<div className="overflow-hidden rounded-xl border border-border">
  <ul className="scroll-fade h-72 overflow-y-auto p-2">
    {items.map((item) => (
      <li key={item.id}>{item.title}</li>
    ))}
  </ul>
</div>
```

- `scroll-fade`
- `scroll-fade-x`
- `scroll-fade-t`
- `scroll-fade-b`
- `scroll-fade-l`
- `scroll-fade-r`

## Horizontal

`scroll-fade-x` masks the inline edges instead. The right edge fades while there are more chips to reach, and sharpens at the end of the row.

```tsx title="tabs.tsx"
<div className="overflow-hidden rounded-xl border border-border p-2">
  <div className="scroll-fade-x flex gap-2 overflow-x-auto px-2 py-1">
    {tags.map((tag) => (
      <Chip key={tag}>{tag}</Chip>
    ))}
  </div>
</div>
```

## Single edge

Reach for a one-sided utility when only one edge should bleed - a chat log that fades into its header (`scroll-fade-t`), or a list that only needs to hint at more rows below (`scroll-fade-b`). The crisp edge never fades, even mid-scroll.

## Customizing

Two CSS variables tune the effect per element - set them with an arbitrary property so they cascade cleanly and stay overridable.

- `--scroll-fade-size`: min(2.5rem, 12%)
- `--scroll-fade-reveal`: 6rem

```tsx title="customizing.tsx"
// Deeper fade, quicker reveal.
<ul className="scroll-fade overflow-y-auto [--scroll-fade-size:4rem] [--scroll-fade-reveal:3rem]">
  {/* … */}
</ul>
```

## Browser support

The scroll-aware behavior rides [scroll-driven animations](https://developer.mozilla.org/en-US/docs/Web/CSS/animation-timeline). Where they aren’t supported, a `@supports` fallback keeps a static fade on the utility’s edges, so the hint never disappears - it just stops tracking the scroll position. Because the effect is driven by the user’s own scrolling (it never plays on its own), it’s left on under `prefers-reduced-motion`.

---

<!-- https://www.koalaui.com/docs/foundations/icons.md -->

# Icons

Phosphor Icons - a flexible, MIT-licensed family with 6 weights per glyph and over 1 400 icons. Always import from /ssr in Server Components; the bare import is for 'use client' files only.

## Import

Phosphor ships two barrels. The `/ssr` barrel is tree-shaken and safe to use in any environment - Server Components, Edge, Node. The bare `@phosphor-icons/react` import registers a React context for the default weight, which requires a client boundary. Default to `/ssr` everywhere and only switch to the bare import inside `"use client"` files that need the context API.

```tsx title="example.tsx"
// ✓ Server Components and most files - default to this
import { Bell, Star, ArrowRight } from "@phosphor-icons/react/ssr"

// ✓ Client Components that need the context API (e.g. global weight)
"use client"
import { Bell, Star, ArrowRight } from "@phosphor-icons/react"

// ✗ Never import the whole package
import * as Icons from "@phosphor-icons/react"
```

## Sizes

Icons use Tailwind’s `size-*` utility (shorthand for `width` + `height`). Components apply a default of `size-4` to any unclassed `svg` child - only override when the context calls for a different size.

- `size-3`: 12px (tight inline, badge counters)
- `size-3.5`: 14px (separators, tag icons)
- `size-4`: 16px (default - most components)
- `size-5`: 20px (emphasis, standalone labels)
- `size-6`: 24px (display, empty states)

## Weights

Every Phosphor icon ships in six weights. Pass the `weight` prop - no separate import per style. `bold` is the default in Koala UI - it holds its weight at small sizes and reads as deliberate next to our type. Use `fill` for selected / active states, and drop to `regular` or `light` when you want a softer, more delicate mark.

- `thin`
- `light`
- `regular`
- `bold`
- `fill`
- `duotone`

```tsx title="example.tsx"
// Pass weight directly - no separate import
<Star weight="bold" />      {/* default */}
<Star weight="fill" />      {/* selected state */}
<Star weight="regular" />   {/* softer, lighter mark */}
```

## Color

Icons inherit the current text color - set `text-*` on the icon or any ancestor. Never hardcode a hex value; always use a semantic token so the icon re-themes correctly across all four Koala themes.

- `foreground`
- `muted-fg`
- `primary`
- `destructive`
- `success`
- `warning`
- `info`

## Accessibility

Most icons are decorative - they reinforce meaning already conveyed by adjacent text, so screen readers should skip them entirely. Interactive icons (icon-only buttons, links) need an accessible label so a keyboard or AT user knows what they do.

```tsx title="a11y.tsx"
// ✓ Decorative icon alongside text - silence it
<button>
  <ArrowRight aria-hidden />
  Continue
</button>

// ✓ Icon-only - label the interactive element, not the icon
<button aria-label="Go to next step">
  <ArrowRight aria-hidden />
</button>

// ✓ Icon-only with visible tooltip - sr-only is redundant, but keep aria-label
//   so AT users get the label without waiting for the tooltip to appear
<button aria-label="Notifications">
  <Bell aria-hidden />
</button>

// ✗ aria-label on the icon itself - AT reads "Go to next step" then "image"
<button>
  <ArrowRight aria-label="Go to next step" />
</button>
```

## In context

Button, Badge, and Breadcrumb all size icons automatically via `[&_svg]` selectors - you rarely need to pass a size class when composing with those components.

```tsx title="usage.tsx"
import { ArrowRight, Plus, Check } from "@phosphor-icons/react/ssr"
import { Button } from "@/components/ui/button"
import { Badge } from "@/components/ui/badge"

// Button sizes the svg to size-4 automatically
<Button><Plus /> New project</Button>
<Button variant="outline">Continue <ArrowRight /></Button>

// Badge sizes the svg to match its own size step
<Badge variant="success"><Check /> Deployed</Badge>
```

---

<!-- https://www.koalaui.com/docs/foundations/file-icons.md -->

# File Icons

File-type icons as pure inline SVG: a sheet with a folded corner and the extension, toned by category. Three variants, four sizes, and every icon ready to copy or download.

## File icons

42 common extensions, grouped by category and toned by it: PDFs read red, sheets green, pictures purple. Pick a variant above the grid, then hover an icon and use Copy SVG to paste it straight into Figma, or Download SVG for a standalone file. The export carries the colors of the theme you are viewing.

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add file-icon
```

Manual: run `npm install tailwind-variants tailwind-merge`, then copy the source into `components/ui/file-icon/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Variants

Three ways to spend the same tone. `default` is white paper with the tone on a label band, the one FileCard uses. `soft` washes the whole sheet in the tone, quieter for long lists. `solid` makes the sheet the tone, for a single file that leads. The label sits in the same place in all three.

- `default`: paper + tone band
- `soft`: tone wash
- `solid`: tone sheet

## Categories

An extension resolves to one of 12 categories, and the category picks the tone. Every tone is a semantic color role, so it re-themes with the palette. Pass `extension` and the category follows; pass `type` alone for a generic label (IMG, VID). Anything unknown falls back to gray.

- `pdf`: destructive (PDF)
- `image`: purple (Image)
- `video`: pink (Video)
- `audio`: orange (Audio)
- `doc`: info (Document)
- `sheet`: success (Spreadsheet)
- `slides`: warning (Presentation)
- `archive`: teal (Archive)
- `code`: teal (Code)
- `design`: foreground (Design)
- `text`: muted-foreground (Text)
- `default`: muted-foreground (Other)

## Sizes

`size` sets the height; the width follows the sheet’s 5:6 box. Or size it yourself with a height utility in `className`.

- `sm`: 32px (dense lists, table cells)
- `md`: 40px (default: rows, attachments)
- `lg`: 48px (upload trays, cards)
- `xl`: 64px (empty states, previews)

## In context

FileCard leads with this icon, so an attachment list gets the category at a glance. Derive the type from the filename and the row needs nothing else. The [FileCard](https://www.koalaui.com/docs/components/file-card.md) page covers progress, states and actions.

## Usage

Pass the extension or the whole filename. The icon is decorative (`aria-hidden`) because the name beside it says what the file is; give it an `aria-label` when it stands alone. It holds no state, so it renders in Server Components too.

```tsx title="attachments.tsx"
import { FileIcon, FILE_ICON_TYPES, fileTypeFromName } from "@/components/ui/file-icon"

// From an extension or a whole filename: the category and tone follow
<FileIcon extension="pdf" />
<FileIcon extension="Q3 revenue.xlsx" variant="soft" size="lg" />

// A category alone stamps its generic label (IMG, VID, ZIP)
<FileIcon type="image" variant="solid" />

// Override the stamped text, or the tone
<FileIcon type="code" label="TSX" />
<FileIcon extension="key" className="text-brand" />

// Name the category in a meta line
const type = fileTypeFromName(file.name)
<span>{FILE_ICON_TYPES[type].name}</span> // "Spreadsheet"
```

---

<!-- https://www.koalaui.com/docs/foundations/flags.md -->

# Flags

261 country and region flags as pure inline SVG, in three shapes and six sizes. Search the set, pick a shape, and copy or download any flag as a standalone SVG.

## Flags

Every country, the territories that fly their own flag, and a few regions such as the European Union, Scotland and Catalonia, sorted by name. Search by name or by code, pick a shape, then hover a flag and use Copy SVG to paste it into Figma, or Download SVG for a standalone file in that shape.

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add flag
```

Manual: run `npm install country-flag-icons tailwind-variants tailwind-merge`, then copy the source into `components/ui/flag/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Shapes

One set of 3:2 art, cropped three ways. `rectangle` shows the whole flag; `square` and `circle` cover the box from the centre, so the color always reaches the edge. A 1px hairline sits over the art so white flags like Japan’s keep their edge on a white surface.

- `rectangle`: 3:2, the flag whole
- `square`: 1:1, centre crop
- `circle`: 1:1, round crop

## Sizes

`size` sets the height and the shape sets the width, so a rectangle and a circle of the same size share a line. The corners grow with the flag and follow the radius knob.

- `xs`: 12px (inline in small text)
- `sm`: 16px (select items, menus)
- `md`: 20px (default: rows, inputs)
- `lg`: 24px (list leads)
- `xl`: 32px (cards, headers)
- `2xl`: 40px (profiles, hero stats)

## In context

A flag leads a row and the name beside it carries the meaning, which is why the flag is decorative by default. CountrySelect, PhoneInput and JobCard use this same round crop.

United States 38%

Germany 21%

Japan 14%

Brazil 9%

Scotland 4%

## Usage

Pass an ISO 3166-1 alpha-2 code (`ES`), or an ISO 3166-2 code for a region with its own flag (`GB-SCT`). The same codes key the `FLAGS` list, so names come along. Give the flag a `label` when it stands alone, as in a language switcher that shows only flags.

```tsx title="countries.tsx"
import { Flag, FLAGS, FLAG_BY_CODE } from "@/components/ui/flag"

// Rectangle by default, 20px tall
<Flag code="ES" />

// Round, beside its name
<Flag code="JP" shape="circle" size="sm" />
<span>{FLAG_BY_CODE.JP.name}</span>

// Standing alone: give it a name
<Flag code="FR" shape="square" label="Français" />

// Every flag, sorted by name
{FLAGS.map((flag) => (
  <Flag key={flag.code} code={flag.code} shape="circle" />
))}
```

The artwork is `country-flag-icons`, MIT licensed. Because `Flag` resolves any code, the whole set ships wherever it renders on the client, as it already does for CountrySelect and PhoneInput. It holds no state, so in a Server Component the art renders on the server and none of it reaches the browser.

---

<!-- https://www.koalaui.com/docs/logos.md -->

# Logos

Placeholder brand logos: fictional companies, each a colored symbol beside an invented wordmark, plus a small set of real marks. Pure inline SVG, no binary assets.

## Logos

48 imagotypes ordered around the hue wheel: a minimalist colored symbol beside its wordmark. Hover a logo and use Copy SVG to drop the symbol straight into Figma (just paste), or Download SVG for a standalone file. The brand color is baked into the export.

## Usage

In code, import the set and a brand, then render the symbol alone or the full lockup. Map the whole list for a logo wall. The symbols are decorative, so they are `aria-hidden`; the wordmark carries the accessible name.

```tsx title="logo-wall.tsx"
import {
  PLACEHOLDER_BRANDS,
  PlaceholderLogo,
} from "@/components/ui/placeholder-logos"

const [apex] = PLACEHOLDER_BRANDS

// The colored symbol on its own
<PlaceholderLogo brand={apex} variant="mark" />

// Symbol + wordmark lockup (the default)
<PlaceholderLogo brand={apex} variant="lockup" />

// A logo wall: map the set
<div className="flex flex-wrap items-center gap-x-10 gap-y-6">
  {PLACEHOLDER_BRANDS.map((brand) => (
    <PlaceholderLogo key={brand.name} brand={brand} variant="lockup" />
  ))}
</div>
```

These are fictional placeholders, never real companies. Each mark is dependency-free inline SVG that paints with its brand color: the one place these step outside the token system, the same documented exception as the OAuth brand marks. Because the symbol uses `currentColor`, the wordmark re-themes with `text-foreground`, so every lockup reads across all four Koala themes.

## Brand logos

Sometimes you need a real customer's logo, not a placeholder: say, Spotify or Netflix on a “works with” wall. Here are 57 of the most recognizable brand marks, ready to copy or download in their official colors. Search by name to find one fast. They live apart from the fictional set above because, unlike those, each one is a trademark you do not own.

Hover a logo and use Copy SVG to drop the mark straight into Figma, or grab it inline here. The Spotify mark, color baked in and ready to paste:

```tsx title="spotify.svg"
<svg xmlns="http://www.w3.org/2000/svg" width="48" height="48" viewBox="0 0 24 24" fill="#1ED760"><path d="M12 0C5.4 0 0 5.4 0 12s5.4 12 12 12 12-5.4 12-12S18.66 0 12 0zm5.521 17.34c-.24.359-.66.48-1.021.24-2.82-1.74-6.36-2.101-10.561-1.141-.418.122-.779-.179-.899-.539-.12-.421.18-.78.54-.9 4.56-1.021 8.52-.6 11.64 1.32.42.18.479.659.301 1.02zm1.44-3.3c-.301.42-.841.6-1.262.3-3.239-1.98-8.159-2.58-11.939-1.38-.479.12-1.02-.12-1.14-.6-.12-.48.12-1.021.6-1.141C9.6 9.9 15 10.561 18.72 12.84c.361.181.54.78.241 1.2zm.12-3.36C15.24 8.4 8.82 8.16 5.16 9.301c-.6.179-1.2-.181-1.38-.721-.18-.601.18-1.2.72-1.381 4.26-1.26 11.28-1.02 15.721 1.621.539.3.719 1.02.42 1.56-.299.421-1.02.599-1.559.3z"/></svg>
```

In code, the set works like the placeholders: import `BRAND_LOGOS` and render a mark with `BrandLogo`. Each entry carries the brand's domain (the homepage link via `brandHref`) and, when the brand publishes one, a `guidelines` URL, so your UI can always point back to the source.

```tsx title="brand-wall.tsx"
import { BRAND_LOGOS, BrandLogo, brandHref } from "@/components/docs/brand-logos"

const spotify = BRAND_LOGOS.find((b) => b.name === "Spotify")!

// The trademark mark in its official color
<BrandLogo brand={spotify} />

// Link to the brand, and to its guidelines when published
<a href={brandHref(spotify)}>{spotify.name}</a>
{spotify.guidelines && <a href={spotify.guidelines}>Brand guidelines</a>}

// A row of real brand logos
<div className="flex flex-wrap items-center gap-x-10 gap-y-6">
  {BRAND_LOGOS.map((brand) => (
    <BrandLogo key={brand.name} brand={brand} />
  ))}
</div>
```

---

<!-- https://www.koalaui.com/docs/components/announcement.md -->

# Announcement

The pill above a hero title: a standing label paired with the thing being announced. Single-element like Badge, and it nests a Badge for the announced half without drawing a second border around it.

```tsx
<Announcement>
  Update available
  <Badge variant="orange" dot pill>Koala UI v11 is here!</Badge>
</Announcement>
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add announcement
```

Manual: run `npm install radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/announcement/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

```tsx title="usage.tsx"
import { Announcement } from "@/components/ui/announcement"
import { Badge } from "@/components/ui/badge"

export function Example() {
  return (
    <Announcement>
      Update available
      <Badge variant="orange" dot pill>Koala UI v11 is here!</Badge>
    </Announcement>
  )
}
```

## Playground

The controls come straight from the recipe, so the two style axes are all there is: the surface it sits on, and whether it behaves like a link. Note that `interactive` is not something you normally set, it follows `asChild` on its own.

## Nesting a Badge

This is what the pill is for: a standing label plus the thing being announced. Drop a [Badge](https://www.koalaui.com/docs/components/badge.md) in and the recipe handles the nesting. It tightens its padding to 4px on the side the badge sits on, so the chip nests in an even crescent instead of floating with a wide gap on its outer side, and it trades the badge's own hairline for a fill, so you get one stroke around one chip instead of two borders four pixels apart. Works with the badge trailing, leading, or alone.

The horizontal padding is decided per edge, by whatever sits on it: bare text gets 16px, an icon or a dot 12px, a nested badge 4px. That is an optical correction, not a scale. Against a fully round cap the curve recedes from the baseline, so a word set at the same distance as a shape reads as drifting into the edge, while a chip or a glyph nests inside the curve and needs no help.

The label is held off the chip by 16px as well, not by the row's 8px gap. 8px is the distance between a mark and its own label, a dot and the word it belongs to; the label and the chip are two separate pieces of information, and at 8px they read as one run of text with a box drawn round half of it. A badge next to an icon keeps the 8px: a glyph already reads as separate.

```tsx
<Announcement>
  Update available
  <Badge variant="orange" dot pill>Koala UI v11 is here!</Badge>
</Announcement>

<Announcement>
  <Badge variant="info" dot pill>New</Badge>
  Density lands in every control
</Announcement>

<Announcement>
  <Badge variant="success" dot pill>Shipped</Badge>
</Announcement>
```

## Dot and glyph

For a one-line announcement there is nothing to pair, so skip the badge: `dot` renders the same small mark a dot Badge carries, in the current text color. A leading icon works too, and the recipe sizes it to 16px.

```tsx
<Announcement dot>Now in private beta</Announcement>
<Announcement><Rocket weight="bold" /> Koala UI for Mobile is live</Announcement>
<Announcement><Confetti weight="bold" /> 2,600 teams build on Koala</Announcement>
```

## Over media

`variant="glass"` is the pill for a photo or video hero: a translucent white surface with a backdrop blur, sized for the scrim rather than for the theme. A nested badge goes white with it, dot included, because a brand-colored dot clashes over a photograph.

```tsx
<Announcement variant="glass" dot>Now in private beta</Announcement>

<Announcement variant="glass">
  Series A
  <Badge dot pill>$61M to scale support</Badge>
</Announcement>
```

## As a link

Pass `asChild` to render the pill as an `<a>` pointing at the changelog. The hover, focus and press affordances follow `asChild` on their own, so a static pill never scales under a cursor that cannot click it, and the hit area is padded out to 40px tall without changing how the pill looks.

```tsx
<Announcement asChild>
  <a href="/changelog">
    Update available
    <Badge variant="orange" dot pill>Koala UI v11 is here!</Badge>
  </a>
</Announcement>

<Announcement asChild dot>
  <a href="/changelog">Read the release notes</a>
</Announcement>
```

## In a hero

Where it earns its keep. The pill is the first child of [HeroContent](https://www.koalaui.com/docs/components/hero.md) (or of `HeroColumn` in a split hero), above the title. It used to be a Hero part, but nothing ties it to one: the same pill sits in a navbar, over a pricing table, or at the top of a changelog entry.

```tsx title="hero.tsx"
<Hero>
  <HeroContent>
    <Announcement>
      Update available
      <Badge variant="orange" dot pill>Koala UI v11 is here!</Badge>
    </Announcement>
    <HeroTitle>A Design System built for AI-Powered Products</HeroTitle>
    {/* … */}
  </HeroContent>
</Hero>
```

## API reference

### Announcement

A single element that forwards every native `<div>` prop and merges `className` last. The children are the content: a label, a nested `Badge`, an icon, or any combination of them.

### variant

`"solid"` (default), the hairline card pill for a normal surface, or `"glass"`, the translucent pill for a photo or video hero.

### data-lead · data-trail

Not props: the component reads its own children and writes what sits on each edge, `"text"` or `"shape"`, onto the element for the recipe to match. CSS cannot work this out for itself: `:first-child` counts elements, and a label arrives as a text node, so a selector reads a label plus a badge as a pill holding one lone chip and spaces it as though the words were not there.

### dot

Renders a leading dot in the current text color. Use it for the one-line shape; when a badge is nested, let the badge carry the dot instead.

### asChild · interactive

`asChild` renders the pill styles onto a single child element (Radix Slot), typically a link, and `Slottable` keeps the dot inside that element so it belongs to the same hit area. `interactive` defaults to whatever `asChild` is and carries the cursor, the hover, the focus ring and the press scale. Set it explicitly only for a pill that is clickable without `asChild`. To hold a linked pill still, reach for `static` instead, which drops the press scale alone: `interactive={false}` would take the focus ring with it.

## FAQ

### When should I use Announcement instead of a Badge?

A Badge carries one label. An Announcement pairs two pieces of information: a standing label (“Update available”) and the thing being announced (“Koala UI v11 is here!”), and the pill is what pairs them. If you only have the second half, a single dot Badge is the lighter choice and the pill adds nothing.

### And instead of a Banner?

Banner is the full-bleed bar across the top of a page, sized to interrupt. Announcement is an inline pill that sits inside a composition, usually above a hero title. Same message, different furniture: one takes the whole viewport width, the other takes only the room its text needs.

### Why does a nested badge lose its border?

A dot Badge is a transparent chip with a hairline stroke. Inside the pill, which already has one, that paints a second hairline of the same color four pixels in from the first, which reads as a box in a box. The recipe swaps the stroke for a fill one step off the pill's own surface, so the chip stays distinct with a single border around the pair.

### Can I nest a filled badge, like a soft success one?

Yes. The recipe sets the nested surface, so a tinted badge would come out muted; pass the fill back on the badge itself (className="bg-success/10") and it wins, because className is merged last. The house convention for marketing pills is a dot badge, though.

### Does it re-theme?

The solid variant does: it is built from card, border and muted, so it follows light, dark, cream and moonlight. The glass variant deliberately does not. It only ever sits on darkened media, so it is fixed white-on-scrim, the same documented exception the hero's gradient scrim takes.

---

<!-- https://www.koalaui.com/docs/components/banner.md -->

# Banner

A full-bleed announcement bar for promos, release notes and site-wide notices. Soft tones tint the background, message, icon and action from one semantic token, so the whole bar reads as a single hue.

```tsx
<Banner variant="purple">
  <BannerIcon>
    <Megaphone />
  </BannerIcon>
  <BannerContent>New: cream and moonlight themes just landed.</BannerContent>
  <BannerAction href="#">
    Check it out
    <ArrowRight />
  </BannerAction>
</Banner>
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add banner
```

Manual: run `npm install radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/banner/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

```tsx title="usage.tsx"
import {
  Banner,
  BannerIcon,
  BannerContent,
  BannerAction,
} from "@/components/ui/banner"

export function Example() {
  return (
    <Banner variant="purple" dismissible>
      <BannerIcon>
        <Megaphone />
      </BannerIcon>
      <BannerContent>New: cream and moonlight themes just landed.</BannerContent>
      <BannerAction href="#">Check it out</BannerAction>
    </Banner>
  )
}
```

## Variants

Soft tones tint the background from a single semantic token and color the icon, action, and message to match. The message takes a deep, tone-tinted ink (a dark blue, dark purple, ...) on light themes and lifts to a bright tint on dark ones, so it stays readable while the icon and action keep the pure hue. Every tone re-themes across light, dark, cream, and moonlight.

```tsx
<Banner variant="brand">…</Banner>
<Banner variant="purple">…</Banner>
<Banner variant="info">…</Banner>
<Banner variant="success">…</Banner>
<Banner variant="warning">…</Banner>
<Banner variant="default">…</Banner>
```

## Solid

Set `appearance="solid"` for a filled bar. Solid is designed for two theme-stable surfaces: the `default` inverse bar (flips with the theme) and the `brand` accent bar. The soft tones stay tinted because the hue tokens shift lightness per theme.

```tsx
<Banner appearance="solid" variant="default">
  <BannerIcon>
    <Megaphone />
  </BannerIcon>
  <BannerContent>Black Friday: 40% off all plans this week.</BannerContent>
  <BannerAction href="#">Get the deal</BannerAction>
</Banner>

<Banner appearance="solid" variant="brand">
  <BannerIcon>
    <Rocket />
  </BannerIcon>
  <BannerContent>Koala UI v1.0 is live.</BannerContent>
  <BannerAction href="#">See what's new</BannerAction>
</Banner>
```

## Festive

Set `appearance="festive"` for a playful celebration bar: a flat, saturated fill behind white text, the natural home for launches, milestones, and holidays. It ignores the tone `variant`. Recolor the bar by overriding one CSS variable, `--banner-festive-via`, with a brand or flag color. Keep it deep and saturated so the white text stays legible across every theme.

```tsx
<Banner appearance="festive">
  <BannerIcon>
    <Confetti />
  </BannerIcon>
  <BannerContent>We just shipped v1.0. Thanks for celebrating with us.</BannerContent>
  <BannerAction href="#">See what's new</BannerAction>
</Banner>

// Recolor the bar with any deep tone
<Banner
  appearance="festive"
  style={{ "--banner-festive-via": "oklch(0.55 0.2 255)" }}
>
  <BannerIcon>
    <Sparkle />
  </BannerIcon>
  <BannerContent>Drive the bar with your own color.</BannerContent>
  <BannerAction href="#">Join the celebration</BannerAction>
</Banner>
```

## Interactive (confetti)

Add `confetti` to a festive bar to make it playful: it bursts once on mount and again on every click. The icon pops on the mount burst only, so clicking showers confetti while the icon stays still. The pieces are themed by the `--banner-confetti-*` tokens, which derive from the festive palette, so they re-tint with it (recolor the bar and the confetti follows). It is decorative and fully honors reduced-motion. Click the bars below.

```tsx
<Banner appearance="festive" confetti>
  <BannerIcon>
    <Confetti />
  </BannerIcon>
  <BannerContent>We just crossed 9,000 stars. Tap to celebrate!</BannerContent>
  <BannerAction href="#">Star the repo</BannerAction>
</Banner>

// Same interaction, recolored (--via fills the bar, --to accents the confetti)
<Banner
  appearance="festive"
  confetti
  style={{
    "--banner-festive-via": "oklch(0.55 0.2 255)",
    "--banner-festive-to": "oklch(0.52 0.21 25)",
  }}
>
  <BannerIcon>
    <Confetti />
  </BannerIcon>
  <BannerContent>Drive the bar and the confetti with your own colors.</BannerContent>
  <BannerAction href="#">Join in</BannerAction>
</Banner>
```

## Ornaments

Drop a `BannerOrnament` in to peek a decorative flag, mascot, or emoji in from an edge. It clips to the bar and sits behind the message, tilting away from its side. Below, two Venezuela flags (rounded 16px, not circular) peek from the corners of a flat solid bar, with the confetti tinted to the flag's yellow and red. The flag itself is any element you like, sized and rounded however you want.

```tsx
import VE from "country-flag-icons/react/3x2/VE"

<Banner
  appearance="solid"
  variant="brand"
  confetti
  style={{
    backgroundColor: "oklch(0.45 0.18 258)",
    "--banner-festive-via": "oklch(0.78 0.16 92)", // flag yellow → confetti
    "--banner-festive-to": "oklch(0.55 0.2 27)", // flag red → confetti
  }}
>
  <BannerOrnament side="left">
    <span className="block overflow-hidden rounded-lg ring-1 ring-black/10 dark:ring-white/10">
      <VE className="block h-14 w-auto max-w-none" />
    </span>
  </BannerOrnament>
  <BannerIcon>
    <Confetti />
  </BannerIcon>
  <BannerContent>We're celebrating with Venezuela today.</BannerContent>
  <Button size="sm" variant="secondary" asChild>
    <a href="#">Get full access</a>
  </Button>
  <BannerOrnament side="right">
    <span className="block overflow-hidden rounded-lg ring-1 ring-black/10 dark:ring-white/10">
      <VE className="block h-14 w-auto max-w-none" />
    </span>
  </BannerOrnament>
</Banner>
```

## Alignment

The default `align="center"` centers the message. Switch to `align="between"` to pin the message left and the action right, the natural home for a `Button` CTA.

```tsx
<Banner align="between" variant="info">
  <BannerIcon>
    <Lightning />
  </BannerIcon>
  <BannerContent>You have 14 days left in your free trial.</BannerContent>
  <Button size="sm">Upgrade</Button>
</Banner>

<Banner align="between" appearance="solid" variant="brand">
  <BannerIcon>
    <Sparkle />
  </BannerIcon>
  <BannerContent>Try the new AI components, free during beta.</BannerContent>
  <Button size="sm" variant="secondary" asChild>
    <a href="#">Get a demo</a>
  </Button>
</Banner>
```

## Shape

`shape` sets the bar's footprint. The default `"bar"` runs edge to edge, the classic strip atop a page. `"inset"` draws the same bar as a rounded card that sits inside the page gutter, above the navbar: place it in a `SectionContainer` (or any gutter) and it takes that width, its inner row trading the page-width cap for a card interior and a step more height.

```tsx
<SectionContainer className="py-2">
  <Banner variant="purple" shape="inset">
    <BannerIcon>
      <Megaphone />
    </BannerIcon>
    <BannerContent>Koala UI now available for Mobile Apps!</BannerContent>
    <BannerAction href="/changelog">Check it out</BannerAction>
  </Banner>
</SectionContainer>
```

## Dismissible

Set `dismissible` to render a trailing close button. Uncontrolled by default (the banner hides itself); pass `open` / `onOpenChange` to control it, and always give a descriptive `dismissLabel`.

```tsx
<Banner
  variant="purple"
  dismissible
  dismissLabel="Dismiss announcement"
>
  <BannerIcon>
    <Megaphone />
  </BannerIcon>
  <BannerContent>New: cream and moonlight themes just landed.</BannerContent>
  <BannerAction href="#">
    Check it out
    <ArrowRight />
  </BannerAction>
</Banner>
```

## As child action

Use `asChild` on `BannerAction` to render the link styles onto a framework link (e.g. Next.js `<Link>`) via Radix Slot, keeping client-side navigation.

```tsx
import Link from "next/link"

<Banner variant="teal">
  <BannerIcon>
    <Sparkle />
  </BannerIcon>
  <BannerContent>Read the v1.0 changelog.</BannerContent>
  <BannerAction asChild>
    <Link href="/changelog">
      See what's new
      <ArrowRight />
    </Link>
  </BannerAction>
</Banner>
```

## API reference

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| variant | default \| brand \| purple \| pink \| teal \| orange \| info \| success \| warning \| destructive | default | Tone of the bar. |
| appearance | soft \| solid \| festive | soft | Fill style. solid supports default (inverse) and brand; festive is a flat celebration bar themed by the --banner-festive-via var. |
| align | center \| between | center | Centered message, or message-left / action-right. |
| shape | bar \| inset | bar | Edge-to-edge strip, or a rounded card inside the page gutter. |
| dismissible | boolean | false | Render a trailing close button. |
| confetti | boolean | false | Burst confetti on mount and on click (pairs with festive); honors reduced-motion. |
| open | boolean | - | Controlled visibility. |
| defaultOpen | boolean | true | Uncontrolled initial visibility. |
| onOpenChange | (open: boolean) => void | - | Fires when dismissed. |
| dismissLabel | string | Dismiss | Accessible label for the close button. |
| className | string | - | Merged onto the root, last. |

Parts: `Banner`, `BannerIcon`, `BannerContent`, `BannerAction` (accepts `asChild`), and `BannerOrnament` (decorative edge peek, takes `side`). Each forwards its native props and merges `className` last.

## FAQ

### When should I use a Banner instead of an Alert?

Banner is a site-wide, full-bleed announcement bar - promos, release notes, maintenance notices - typically pinned above the navbar. Alert is an inline, in-page status message scoped to a section or form. If it spans the whole viewport width and speaks for the whole site, it's a Banner.

### How do I keep a banner dismissed across reloads?

Control it: render the banner with open/onOpenChange, persist the dismissed state yourself (localStorage, a cookie, or user settings), and read that value to set the initial open. The built-in uncontrolled mode only remembers within the current page session.

### Will the tones adapt to dark and the other themes?

Yes. Every tone tints from a semantic token (bg-<role>/10) and colors the icon/action from the same role, so banners re-theme automatically across light, dark, cream, and moonlight. The message text stays foreground for contrast.

### Can the action be a client-side route?

Yes: set asChild on BannerAction and pass a single link element (a Next.js <Link>, for instance). The action renders its styles onto that element via Radix Slot, so you keep client-side navigation and valid markup.

### How do I theme the festive bar (brand or flag colors)?

Override --banner-festive-via on the banner (a className or an inline style), or globally on a parent for a consistent palette. That single var fills the flat bar; --banner-festive-to accents the confetti alongside it. The default is a clean indigo chosen so white text holds contrast across all four themes; keep your custom color similarly deep and saturated. The festive bar ignores the tone variant, so this var is the only color source.

---

<!-- https://www.koalaui.com/docs/components/bento.md -->

# Bento

An asymmetric marketing grid of feature tiles. Named parts you assemble: a tinted icon, a balanced title, a description and a media region. Each tile claims a size and a tone, and the grid collapses to one column.

```tsx
<Bento>
  {/* Top row: two wide tiles. Every shot has a light and a dark take. */}
  <BentoItem size="md" tone="brand">
    <BentoItemIcon><Storefront /></BentoItemIcon>
    <BentoItemTitle>Store templates</BentoItemTitle>
    <BentoItemDescription>
      Crafted layouts that highlight product benefits, build trust, and drive conversion.
    </BentoItemDescription>
    <BentoItemImage
      src={storeLight}
      darkSrc={storeDark}
      alt="A product page: gallery, price and rating, pickers, and Add to cart"
      sizes="35rem"
      className="object-left-top"
    />
  </BentoItem>

  <BentoItem size="md" tone="teal">
    <BentoItemIcon><ChartLineUp /></BentoItemIcon>
    <BentoItemTitle>High-converting experience</BentoItemTitle>
    <BentoItemDescription>Structures built for maximum conversion.</BentoItemDescription>
    <BentoItemImage src={cartLight} darkSrc={cartDark} alt="A slide-over cart" sizes="35rem" className="object-right-top" />
  </BentoItem>

  {/* Bottom row: three tiles. */}
  <BentoItem size="sm" tone="purple">
    <BentoItemIcon><Palette /></BentoItemIcon>
    <BentoItemTitle>Maximum personalization</BentoItemTitle>
    <BentoItemDescription>Customize the components so each project is unique.</BentoItemDescription>
    <BentoItemImage src={themeLight} darkSrc={themeDark} alt="The theme controls" sizes="22rem" className="object-left-top" />
  </BentoItem>

  <BentoItem size="sm" tone="pink">
    <BentoItemIcon><BookOpen /></BentoItemIcon>
    <BentoItemTitle>Detailed documentation</BentoItemTitle>
    <BentoItemDescription>Maintain consistency with extensive documentation.</BentoItemDescription>
    <BentoItemImage src={docsLight} darkSrc={docsDark} alt="A component docs page" sizes="22rem" className="object-left-top" />
  </BentoItem>

  <BentoItem size="sm" tone="brand">
    <BentoItemIcon><Stack /></BentoItemIcon>
    <BentoItemTitle>All assets in 1 place</BentoItemTitle>
    <BentoItemDescription>Logos, avatars, flags, and icons, ready to drop in.</BentoItemDescription>
    <BentoItemImage src={logosLight} darkSrc={logosDark} alt="The logo set" sizes="22rem" className="object-left-top" />
  </BentoItem>
</Bento>
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add bento
```

Manual: run `npm install radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/bento/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

```tsx
import {
  Bento,
  BentoItem,
  BentoItemIcon,
  BentoItemTitle,
  BentoItemDescription,
  BentoItemImage,
  BentoItemMedia,
} from "@/components/ui/bento"

// Your own screenshots, one per theme.
import storeLight from "@/public/shots/store-light.webp"
import storeDark from "@/public/shots/store-dark.webp"

<Bento>
  <BentoItem size="md" tone="brand">
    <BentoItemIcon><Storefront /></BentoItemIcon>
    <BentoItemTitle>Store templates</BentoItemTitle>
    <BentoItemDescription>Crafted layouts that drive conversion.</BentoItemDescription>
    {/* A screenshot that peeks up from the bottom edge, in the page's theme. */}
    <BentoItemImage src={storeLight} darkSrc={storeDark} alt="A storefront product page" />
  </BentoItem>
</Bento>
```

## Sizes

Each `BentoItem` picks a `size`: `sm` (2 cols), `md` (3 cols), `lg` (4 cols), `feature` (4 cols × 2 rows, the anchor tile), and `full` (the whole row). Below the `lg` breakpoint the grid collapses to two columns, then one, so every tile stays legible on mobile.

```tsx
<Bento>
  <BentoItem size="feature" tone="brand">…</BentoItem>
  <BentoItem size="sm" tone="purple">…</BentoItem>
  <BentoItem size="sm" tone="teal">…</BentoItem>
  <BentoItem size="full" tone="orange">…</BentoItem>
</Bento>
```

## Collapse

`collapse` on `Bento` picks where the grid leaves one column. The default, `sm`, steps through two columns before the six. `lg` holds one column until `lg`: reach for it when a row holds three tiles, because a two-column step can only lay a row of three out as a pair and an orphan. The tiles read the choice from the grid, so a wide tile never forces a second column into a one-column grid. Narrow the window to see the difference.

```tsx
{/* 2 / 3 / 2: one column until lg, never a pair and an orphan. */}
<Bento collapse="lg">
  <BentoItem size="md">…</BentoItem>
  <BentoItem size="md">…</BentoItem>
  <BentoItem size="sm">…</BentoItem>
  <BentoItem size="sm">…</BentoItem>
  <BentoItem size="sm">…</BentoItem>
  <BentoItem size="md">…</BentoItem>
  <BentoItem size="md">…</BentoItem>
</Bento>
```

## Image fit

`imageFit` decides what a `BentoItemImage` is. `frame` (default) floats the shot in a window: inset by the tile padding, top corners rounded, lifted off a muted ground. `bleed` drops the window: the art is larger than the tile, pinned to the copy's left edge, and runs off the right and bottom edges, dissolving through the `fade-b` mask into whatever ground the theme gives it. Set it once on `Bento`; a tile's own `imageFit` wins.

```tsx
<Bento imageFit="bleed">
  <BentoItem size="md">
    <BentoItemTitle>Product Design Templates</BentoItemTitle>
    <BentoItemDescription>Create concepts with over 200 templates.</BentoItemDescription>
    {/* Wider than the tile, anchored top-left, dissolving at the foot. */}
    <BentoItemImage src={dashboard} alt="A dashboard template" sizes="(min-width: 1024px) 56rem, 130vw" />
  </BentoItem>

  {/* A tile's own imageFit beats the grid's. */}
  <BentoItem size="md" imageFit="frame">
    <BentoItemTitle>Framed, for contrast</BentoItemTitle>
    <BentoItemDescription>The same art in the default window.</BentoItemDescription>
    <BentoItemImage src={dashboard} alt="A dashboard template" />
  </BentoItem>
</Bento>
```

## Light and dark shots

A screenshot is taken in one theme, and a framed window is the first thing that gives it away: a white shot on a dark page reads as a mistake. Pass the same shot taken in a dark theme as `darkSrc` and `BentoItemImage` shows `src` on the light themes (light, cream) and `darkSrc` on the dark ones (dark, moonlight). The swap is the `dark:` variant, so it follows the nearest theme, a pinned band included, and only the shot on screen is downloaded. Every other prop applies to both.

```tsx
{/* One tile, two takes of its shot. */}
<BentoItem size="md" tone="teal">
  <BentoItemIcon><ChartLineUp /></BentoItemIcon>
  <BentoItemTitle>High-converting experience</BentoItemTitle>
  <BentoItemImage
    src={cartLight}
    darkSrc={cartDark}
    alt="A slide-over cart: line items, the subtotal, and Checkout"
    sizes="35rem"
    className="object-right-top"
  />
</BentoItem>
```

## Live art

A shot is one take of one moment. When the moment should follow the visitor's theme and accent, move, or answer a click, put the real components in the window instead. `BentoItemArt` is the same art window a `BentoItemImage` paints into, framed by default and bled under `imageFit="bleed"`, with your composition inside. Position it yourself: the window clips it, and a bled window is wider than the tile, so anything past the tile's edge is cut there.

```tsx
<BentoItem size="md" tone="purple">
  <BentoItemIcon><Palette /></BentoItemIcon>
  <BentoItemTitle>Real components, not a picture</BentoItemTitle>
  <BentoItemDescription>The window holds live parts.</BentoItemDescription>
  <BentoItemArt>
    <Card variant="elevated" className="absolute top-6 left-6 w-80">
      <CardContent>{/* switches, buttons… */}</CardContent>
    </Card>
  </BentoItemArt>
</BentoItem>
```

## Scale

`scale` on `Bento` is the board's type and spacing step. `md` (default) is a block among many: 24px tiles, 16px descriptions. `lg` is the landing board a home page tells its feature story with: 32px tiles, a 32px step to the art, and 18px descriptions. The title stays 8px from its description at both steps, and the bleed cancels the bigger padding. Set once on the grid, so a board never mixes steps.

```tsx
<Bento scale="lg" imageFit="bleed">
  <BentoItem size="md">
    <BentoItemTitle>Product Design Templates</BentoItemTitle>
    <BentoItemDescription>Create concepts with over 200 templates.</BentoItemDescription>
    <BentoItemImage src={dashboard} alt="A dashboard template" sizes="(min-width: 1024px) 56rem, 130vw" />
  </BentoItem>
  <BentoItem size="md" tone="teal">
    <BentoItemIcon><ChartLineUp /></BentoItemIcon>
    <BentoItemTitle>High-converting experience</BentoItemTitle>
    <BentoItemDescription>Structures created for maximum conversion.</BentoItemDescription>
  </BentoItem>
</Bento>
```

## API reference

### Bento

The grid container: one column on mobile, two at `sm`, six at `lg`. `collapse` is `"sm"` (default) or `"lg"`, which skips the two-column step; `imageFit` sets the default for every tile; `scale` is `"md"` (default) or `"lg"`, the landing step. Forwards native `<div>` props and `className`.

### BentoItem

One tile. `size` is `"sm"` (default), `"md"`, `"lg"`, `"feature"`, or `"full"`; `tone` is `"brand"` (default), `"purple"`, `"teal"`, `"orange"`, or `"pink"` and tints the icon; `imageFit` is `"frame"` (default) or `"bleed"` and overrides the grid's. Pass `asChild` to render the whole tile as a link.

### BentoItemIcon · BentoItemTitle · BentoItemDescription

The tinted icon chip (pass one Phosphor icon as the child, tone inherited from the tile), the balanced `<h3>` title, and the muted `<p>` description.

### BentoItemImage

A screenshot clipped at the tile's edge: a framed window peeking up from the bottom, or bleeding art with `imageFit="bleed"`. A plain lazy `<img>` that fills the window, so it runs in Next, Vite or any React app: pass `src` (a URL or a static image import) and `alt`, plus `darkSrc` for the dark themes' take of the same shot; its height (and the bleed's width) follows the tile `size` and is overridable via `frameClassName`. Children are extra layers inside the window (a floating panel over the shot), positioned by you and clipped and dissolved with the art.

### BentoItemArt

The art window with live children instead of a picture: framed or bled by the tile's `imageFit`, with the same height (and bleed width) per `size` as `BentoItemImage`. Position the composition inside it yourself; the window clips it. Forwards native `<div>` props and `className`.

### BentoItemMedia

A freeform bottom-aligned region (`mt-auto`) for anything that isn't a peeking image: a stat, a swatch row, or custom markup. Media edges line up across tiles in a row. Composed first, it flips: the visual sits at the top and the title and description settle on the bottom edge.

## FAQ

### How do I make the asymmetric layout?

Give each BentoItem a `size`. The grid is six columns at the `lg` breakpoint, so `feature` (4×2), `sm` (2), `md` (3), `lg` (4), and `full` (6) tile together into a bento. The default arrangement pairs one `feature` tile with two `sm` tiles and a `full` closing band.

### Where do the visuals inside the tiles come from?

You provide them. Use `BentoItemImage` for a screenshot that peeks up from the bottom edge (a lazy img that fills the window, so pass src and alt), or `BentoItemMedia` for any freeform bottom-aligned visual: a Chart, a Stat, or custom markup. The board above shows the library itself: each shot is taken from a real page of these docs. Keep purely decorative visuals aria-hidden.

### How do I keep a screenshot in the page's theme?

Shoot it twice, once in a light theme and once in a dark one, and pass the second as `darkSrc`. The light take shows on light and cream, the dark take on dark and moonlight, and only the one on screen loads. Anchor the side that matters with `className` (`object-left-top`, `object-right-top`): the window's height is fixed, so a narrow tile crops the shot at the sides.

### Can a whole tile be a link?

Yes. Pass `asChild` to `BentoItem` and render an `<a>` (or a Next `<Link>`) as its child; the link covers the full surface. The tile stays static on hover, like every in-flow card.

### Why does my 2 / 3 / 2 board leave a tile alone on a tablet?

The default grid steps through two columns at `sm`, and a row of three can only fill two columns as a pair and an orphan. Pass `collapse="lg"` to `Bento` to hold one column until the six-column layout takes over.

### How do I make the art run off the tile?

Use `imageFit="bleed"`, on `Bento` for every tile or on one `BentoItem`. The window loses its border, ground and shadow, grows wider than the tile, anchors the art to the top-left, and fades it out at the foot with the `fade-b` mask, so it dissolves into any theme's ground.

### What does tone change?

Only the icon chip's tint. It maps to the theme's hue roles (brand, purple, teal, orange, pink) as a soft 10% background with a solid foreground, so it reads on every theme.

### Is it responsive?

Yes. The grid is one column on mobile, two at `sm`, and six at `lg`, and every `size` resolves its spans only at `lg`, so tiles stack cleanly on small screens.

---

<!-- https://www.koalaui.com/docs/components/faqs.md -->

# FAQs

A marketing-ready frequently-asked-questions section built on the Accordion. It pairs a header with a single-expand question list and an optional contact CTA, in a centered stack or a sticky two-column split.

```tsx
<Faqs>
  <FaqsHeader>
    <FaqsTitle>Frequently asked questions</FaqsTitle>
    <FaqsDescription>
      Everything you need to know about the product and how it works.
    </FaqsDescription>
  </FaqsHeader>
  <FaqsList defaultValue="item-1">
    <FaqsItem value="item-1" question="Is Koala UI free to use?">
      The core library is free under a permissive license. A paid PRO tier adds marketing
      sections, full pages, and priority support.
    </FaqsItem>
    <FaqsItem question="Which frameworks does it support?">
      Koala UI targets React 19 and the Next.js App Router out of the box, and drops into any
      React setup running Tailwind CSS v4.
    </FaqsItem>
    <FaqsItem question="Can I restyle the components?">
      Yes. Every component is built on semantic tokens and tailwind-variants, and accepts a
      className that merges last, so you can re-theme globally or override one instance.
    </FaqsItem>
    <FaqsItem question="How do I install a component?">
      Run npx koalaui-cli@latest add &lt;component&gt;, or copy the source straight from the docs. There is
      no runtime package to lock you in.
    </FaqsItem>
  </FaqsList>
</Faqs>
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add faqs
```

Manual: run `npm install radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/faqs/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

```tsx title="usage.tsx"
import {
  Faqs,
  FaqsHeader,
  FaqsTitle,
  FaqsDescription,
  FaqsList,
  FaqsItem,
  FaqsFooter,
} from "@/components/ui/faqs"

export function Example() {
  return (
    <Faqs>
      <FaqsHeader>
        <FaqsTitle>Frequently asked questions</FaqsTitle>
        <FaqsDescription>Everything you need to know.</FaqsDescription>
      </FaqsHeader>
      <FaqsList>
        <FaqsItem question="Is Koala UI free to use?">
          The core library is free under a permissive license.
        </FaqsItem>
      </FaqsList>
    </Faqs>
  )
}
```

## Stacked layout

The default `layout="stacked"` centers the header above a width-constrained list. It is the classic centered FAQ, ideal at the foot of a landing page. Set a `defaultValue` on `FaqsList` (matching a `FaqsItem` value) to open the first answer so the section never reads as an empty stack of triggers.

```tsx
<Faqs layout="stacked">
  <FaqsHeader>
    <FaqsTitle>Frequently asked questions</FaqsTitle>
    <FaqsDescription>
      Short answers to the questions we hear most often.
    </FaqsDescription>
  </FaqsHeader>
  <FaqsList defaultValue="s-1">
    <FaqsItem value="s-1" question="Do you ship a Figma kit?">
      A Figma library mirroring the token set ships with the PRO tier, kept in sync with each
      release.
    </FaqsItem>
    <FaqsItem question="How do I get updates?">
      Re-run the CLI to pull the latest source for any component, or watch the changelog for
      release notes.
    </FaqsItem>
    <FaqsItem question="Is there a dark mode?">
      Yes. Every component re-themes across light, dark, cream, and moonlight from a single set
      of semantic tokens.
    </FaqsItem>
  </FaqsList>
</Faqs>
```

## Split layout

Set `layout="split"` for a two-column grid: a header column that stays `sticky` while the list scrolls beside it (the Stripe / Linear FAQ). The columns stack on mobile, and `FaqsFooter` spans both columns underneath.

```tsx
<Faqs layout="split">
  <FaqsHeader>
    <FaqsTitle>Billing and plans</FaqsTitle>
    <FaqsDescription>
      Short answers about pricing, seats, and renewals.
    </FaqsDescription>
  </FaqsHeader>
  <FaqsList defaultValue="b-1">
    <FaqsItem value="b-1" question="Can I change plans later?">
      Yes. Upgrade or downgrade at any time from your dashboard, and changes are prorated to
      the day.
    </FaqsItem>
    <FaqsItem question="Do you offer team seats?">
      Team and Enterprise plans include shared seats with centralized billing and role-based
      access.
    </FaqsItem>
    <FaqsItem question="What happens when my trial ends?">
      Your workspace moves to the free tier. Nothing is deleted, and you can upgrade whenever
      you are ready.
    </FaqsItem>
  </FaqsList>
  <FaqsFooter>
    Still have questions?
    <Button size="sm" asChild>
      <a href="#">
        <ChatCircleDots />
        Contact support
      </a>
    </Button>
  </FaqsFooter>
</Faqs>
```

## Grouped by topic

For a long, categorized help center, slot `FaqsGroup`s between the header and footer. Each takes a `title` (an `<h3>` under the section `<h2>`) and an optional `description`, then wraps its own questions, so the page reads header → topic → questions → topic. Each group owns its own list, so single-expand is scoped to the topic and the hairline dividers reset at every boundary. It defaults to the borderless `minimal` list, and still forwards every `FaqsList` prop (`variant`, `defaultValue`, `iconPosition`, …).

```tsx
const TOPIC_FAQS = [
  {
    topic: "Most asked",
    questions: [
      { q: "How is Koala UI different from other UI kits?", a: "…" },
      { q: "Who is it made for?", a: "…" },
    ],
  },
  {
    topic: "The product",
    questions: [
      { q: "How many themes ship with the design system?", a: "…" },
      { q: "How often is Koala UI updated?", a: "…" },
    ],
  },
  // …
]

<Faqs>
  <FaqsHeader>
    <FaqsTitle>Have any questions? We&apos;ve got answers</FaqsTitle>
    <FaqsDescription>
      The questions we hear most, grouped by topic so you can jump straight to the one you need.
    </FaqsDescription>
  </FaqsHeader>
  {TOPIC_FAQS.map((group, gi) => (
    <FaqsGroup
      key={group.topic}
      title={group.topic}
      defaultValue={gi === 0 ? `${group.topic}-0` : undefined}
    >
      {group.questions.map((item, i) => (
        <FaqsItem key={i} value={`${group.topic}-${i}`} question={item.q}>
          {item.a}
        </FaqsItem>
      ))}
    </FaqsGroup>
  ))}
</Faqs>
```

## Landing scale

`size="lg"` on `Faqs` is the landing-page FAQ: topic headings big enough to scan the page by, and every list inside defaults to the Accordion's own `lg` step (an 18px semibold question on a taller row), so questions and topics step up together. The first topic sits flush, because a landing FAQ usually has its lede in a `SectionHeader` above the block. Pair it with `marker="plus"`.

```tsx
<Faqs size="lg" className="max-w-2xl">
  {TOPIC_FAQS.map((group) => (
    <FaqsGroup key={group.topic} title={group.topic} marker="plus">
      {group.questions.map((item, i) => (
        <FaqsItem key={i} value={`${group.topic}-${i}`} question={item.q}>
          {item.a}
        </FaqsItem>
      ))}
    </FaqsGroup>
  ))}
</Faqs>
```

## List style

`FaqsList` forwards straight to the Accordion, so its `variant` controls the chrome: `card` (the default: one bordered box with shared dividers), `minimal` (borderless rows divided by hairlines), or `separated` (each item its own bordered box). None of those three paints a fill, so the list takes the ground it sits on, whether that is the page or a muted band. The fourth, `pill`, is the chip list: a closed question hugs its own text and the open one floods into a filled card, for a short FAQ sitting beside a picture rather than filling the measure on its own.

```tsx
{/* Default: one bordered box */}
<FaqsList variant="card" defaultValue="c-1">…</FaqsList>

{/* Borderless rows */}
<FaqsList variant="minimal" defaultValue="m-1">…</FaqsList>

{/* Each item its own card */}
<FaqsList variant="separated" defaultValue="p-1">…</FaqsList>

{/* Chips: closed questions hug their text */}
<FaqsList variant="pill" marker="plus" defaultValue="l-1">…</FaqsList>
```

## Helpful feedback

For a help-center / knowledge-base FAQ, set `iconPosition="leading"` on `FaqsList` to move the caret ahead of the question, and add `feedback` to a `FaqsItem` to mount a Helpful / Not helpful voting row beneath its answer. The chosen pill stays emphasized while the other dims, and an acknowledgement fades in. For full control (custom labels, an `onVote` handler), drop a `FaqsFeedback` into the answer yourself.

```tsx
<Faqs>
  <FaqsList variant="separated" iconPosition="leading" defaultValue="h-1">
    <FaqsItem
      value="h-1"
      feedback
      question="What sets your interior design agency apart from others in the industry?"
    >
      At our agency, we take pride in our distinctive personalized approach, meticulous
      attention to detail, and our unwavering commitment to delivering unparalleled designs
      that surpass client expectations.
    </FaqsItem>
    <FaqsItem feedback question="How long does a typical project take?">
      Most residential projects run six to twelve weeks from brief to install, depending on
      scope and lead times on custom pieces.
    </FaqsItem>
    <FaqsItem feedback question="Do you work with existing furniture?">
      Absolutely. We design around the pieces you love and fill the gaps, so the result feels
      collected rather than bought all at once.
    </FaqsItem>
  </FaqsList>
</Faqs>
```

## Footer call to action

`FaqsFooter` is an optional closing row for a contact prompt. Drop a line of copy beside one of our `Button` components; it centers in the stacked layout and spans both columns in the split layout.

```tsx
<Faqs>
  <FaqsHeader>
    <FaqsTitle>Frequently asked questions</FaqsTitle>
  </FaqsHeader>
  <FaqsList defaultValue="f-1">
    <FaqsItem value="f-1" question="How do I reach support?">
      Email the team or open a thread from your dashboard. We reply within one business day.
    </FaqsItem>
    <FaqsItem question="Where can I report a bug?">
      Open an issue from the docs footer and include a reproduction; we triage daily.
    </FaqsItem>
  </FaqsList>
  <FaqsFooter>
    Can&apos;t find what you&apos;re looking for?
    <Button size="sm" variant="secondary" asChild>
      <a href="#">
        <ChatCircleDots />
        Talk to us
      </a>
    </Button>
  </FaqsFooter>
</Faqs>
```

## Composition

The parts are plain composition, so a list of questions maps cleanly into `FaqsItem`s. Give each one a stable `value` when you want to target it with `defaultValue`; omit it and a unique id is generated for you.

```tsx
const PLAN_FAQS = [
  { q: "Can I change plans later?", a: "Yes, changes are prorated to the day." },
  { q: "Do you offer team seats?", a: "Team and Enterprise plans include shared seats." },
  // …
]

<Faqs>
  <FaqsHeader>
    <FaqsTitle>Billing and plans</FaqsTitle>
  </FaqsHeader>
  <FaqsList defaultValue="plan-0">
    {PLAN_FAQS.map((item, i) => (
      <FaqsItem key={i} value={`plan-${i}`} question={item.q}>
        {item.a}
      </FaqsItem>
    ))}
  </FaqsList>
</Faqs>
```

## API reference

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| Faqs.layout | stacked \| split | stacked | Centered header above the list, or a sticky two-column grid. |
| Faqs.size | md \| lg | md | Type scale. lg is the landing FAQ: bigger topic headings, and every list inside defaults to the Accordion's lg step. |
| FaqsList.variant | card \| minimal \| separated | card | Forwarded to Accordion: the list chrome. Borders only, never a fill. |
| FaqsList.type | single \| multiple | single | Forwarded to Accordion: one open answer, or many. |
| FaqsList.collapsible | boolean | true | Forwarded to Accordion (single only): allow closing the open item. |
| FaqsList.defaultValue | string \| string[] | - | Forwarded to Accordion: the item(s) open on mount. |
| FaqsList.density | comfortable \| compact | comfortable | Forwarded to Accordion: row height and content inset. |
| FaqsList.iconPosition | leading \| trailing | trailing | Forwarded to Accordion: caret before or after the question. |
| FaqsGroup.title | ReactNode | - | Topic heading (an <h3>) above the group's questions. |
| FaqsGroup.description | ReactNode | - | Optional supporting copy under the topic heading. |
| FaqsGroup.* | FaqsList props | variant="minimal" | Forwarded to the group's own FaqsList (variant, defaultValue, …). |
| FaqsItem.question | ReactNode | - | The question shown in the trigger row. |
| FaqsItem.value | string | auto | Unique item id. A stable id is generated when omitted. |
| FaqsItem.feedback | boolean \| FaqsFeedbackProps | false | Mount a Helpful / Not helpful voting row beneath the answer. |
| FaqsFeedback.reveal | "always" \| "hover" | "always" | `hover` opens the row with its answer instead of showing it permanently, for the always-open reading model where every answer is visible at once. The space is not reserved, so no empty gap sits under each answer; it still opens on keyboard focus, stays open once a vote is cast, and opts out entirely on touch, which has no hover. |
| FaqsFeedback.onVote | (v: "up" \| "down") => void | - | Called with the chosen vote when the reader rates the answer. |
| className | string | - | Accepted by every part, merged last. |

Parts: `Faqs`, `FaqsHeader`, `FaqsTitle`, `FaqsDescription`, `FaqsGroup`, `FaqsList`, `FaqsItem`, `FaqsFeedback`, `FaqsFooter`. `FaqsList` forwards all `Accordion` props; each part forwards its native props and merges `className` last.

## FAQ

### How is FAQs different from Accordion?

FAQs is a marketing section built on top of Accordion. Accordion is the generic disclosure list; FAQs adds the section composition around it - a header (title + description), the Q&A list with sensible marketing defaults, an optional contact CTA, and a stacked or split layout. Reach for Accordion for in-app disclosure, and FAQs for a landing-page question section.

### Do I have to give every FaqsItem a value?

No. FaqsItem generates a stable, SSR-safe id when you omit value. Pass an explicit value only when you want to open it via the list's defaultValue, or otherwise target it.

### Can more than one answer be open at once?

Yes. FaqsList forwards to Accordion, so set type="multiple" (and drop collapsible, which only applies to single) to let several answers stay open together.

### How do I split a long FAQ into topic sections?

Use FaqsGroup. Drop one per topic between FaqsHeader and FaqsFooter, give it a title (and optional description), and nest its FaqsItems inside. Each group is its own list, so single-expand is scoped to the topic. That is the grouped / help-center variant: header → topic → questions → topic.

### How do I make the contact prompt live in the header instead of the footer?

Because the parts are plain composition, just place your prompt and Button inside FaqsHeader rather than using FaqsFooter. In the split layout that keeps the call to action in the sticky left column beside the title.

---

<!-- https://www.koalaui.com/docs/components/footer.md -->

# Footer

A composable site footer for marketing, product and ecommerce pages. Pure layout: a brand column plus grouped link columns up top, and a bottom bar with copyright, legal links and social icons.

```tsx
<Footer>
  <FooterTop>
    <FooterBrand>
      <BrandMark />
      <FooterTagline>The commercial React design system…</FooterTagline>
      <FooterSocial>
        <FooterSocialLink href="#" aria-label="X"><XLogo /></FooterSocialLink>
        <FooterSocialLink href="#" aria-label="GitHub"><GithubLogo /></FooterSocialLink>
      </FooterSocial>
    </FooterBrand>
    <FooterColumns>
      <FooterColumn title="Product">
        <FooterLink href="#">Features</FooterLink>
        <FooterLink href="#">Pricing</FooterLink>
      </FooterColumn>
      {/* …more columns */}
    </FooterColumns>
  </FooterTop>
  <FooterBottom>
    <FooterCopyright>© 2026 Koala UI. All rights reserved.</FooterCopyright>
    <FooterLegal>
      <FooterLink href="#">Privacy</FooterLink>
      <FooterLink href="#">Terms</FooterLink>
    </FooterLegal>
  </FooterBottom>
</Footer>
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add footer
```

Manual: run `npm install radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/footer/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

```tsx title="usage.tsx"
import { GithubLogo, XLogo } from "@phosphor-icons/react"

import {
  Footer, FooterTop, FooterBrand, FooterTagline, FooterSocial, FooterSocialLink,
  FooterColumns, FooterColumn, FooterLink,
  FooterBottom, FooterCopyright, FooterLegal,
} from "@/components/ui/footer"

export function Example() {
  return (
    <Footer>
      <FooterTop>
        <FooterBrand>
          <span className="text-lg font-semibold">Koala UI</span>
          <FooterTagline>Tools for teams that ship every week.</FooterTagline>
          <FooterSocial>
            <FooterSocialLink href="https://x.com" aria-label="X"><XLogo /></FooterSocialLink>
            <FooterSocialLink href="https://github.com" aria-label="GitHub"><GithubLogo /></FooterSocialLink>
          </FooterSocial>
        </FooterBrand>
        <FooterColumns>
          <FooterColumn title="Product">
            <FooterLink href="/features">Features</FooterLink>
            <FooterLink href="/pricing">Pricing</FooterLink>
          </FooterColumn>
          <FooterColumn title="Company">
            <FooterLink href="/about">About</FooterLink>
            <FooterLink href="/careers">Careers</FooterLink>
          </FooterColumn>
        </FooterColumns>
      </FooterTop>
      <FooterBottom>
        <FooterCopyright>© 2026 Koala UI. All rights reserved.</FooterCopyright>
        <FooterLegal>
          <FooterLink href="/privacy">Privacy</FooterLink>
          <FooterLink href="/terms">Terms</FooterLink>
        </FooterLegal>
      </FooterBottom>
    </Footer>
  )
}
```

## With newsletter

A newsletter signup is just an [Input](https://www.koalaui.com/docs/components/input.md) and a [Button](https://www.koalaui.com/docs/components/button.md) composed inside `FooterBrand`. The footer stays dependency-free.

```tsx
<FooterBrand>
  <BrandMark />
  <FooterTagline>Get product updates. No spam.</FooterTagline>
  <form className="flex items-center gap-2">
    <InputRoot size="sm" className="max-w-2xs">
      <InputField type="email" placeholder="you@company.com" aria-label="Email address" />
    </InputRoot>
    <Button size="sm" iconOnly aria-label="Subscribe"><ArrowRight /></Button>
  </form>
</FooterBrand>
```

## Wide link grid

`layout="wide"` hands the whole top row to the link columns, for footers that lead with a deep sitemap instead of a brand statement. Drop `FooterBrand` and the columns distribute edge to edge.

```tsx
<Footer layout="wide">
  <FooterTop>
    <FooterColumns>
      <FooterColumn title="Product">…</FooterColumn>
      <FooterColumn title="Company">…</FooterColumn>
      <FooterColumn title="Resources">…</FooterColumn>
      <FooterColumn title="Legal">…</FooterColumn>
      <FooterColumn title="Solutions">…</FooterColumn>
      <FooterColumn title="Social">…</FooterColumn>
    </FooterColumns>
  </FooterTop>
  <FooterBottom>
    <FooterCopyright>© 2026 Koala UI. All rights reserved.</FooterCopyright>
    <FooterLegal>…</FooterLegal>
  </FooterBottom>
</Footer>
```

## Brand above the grid

The brand does not have to sit beside the columns. Stack `FooterTop` and the lockup leads the footer with the lede opposite it, the grid runs underneath, and the social row moves down into the bottom bar.

```tsx
<Footer layout="wide">
  <FooterTop className="lg:flex-col lg:gap-12">
    <FooterBrand className="w-full flex-row items-start justify-between gap-8 lg:max-w-none">
      <BrandMark />
      <FooterTagline className="max-w-sm">Subscribe now so you don't miss…</FooterTagline>
    </FooterBrand>
    <FooterColumns>{/* …six columns */}</FooterColumns>
  </FooterTop>
  <FooterBottom>
    <FooterCopyright>© 2026 Koala UI. All rights reserved.</FooterCopyright>
    <FooterSocial>…</FooterSocial>
  </FooterBottom>
</Footer>
```

## Bottom bar only

For simple pages, drop the columns and render just the `FooterBottom` bar: the brand, an inline nav, and the copyright on one line.

```tsx
<Footer density="compact">
  <FooterBottom className="mt-0 border-t-0 pt-0 sm:items-center">
    <BrandMark />
    <FooterLegal className="gap-x-6">
      <FooterLink href="#">Features</FooterLink>
      <FooterLink href="#">Pricing</FooterLink>
      <FooterLink href="#">Docs</FooterLink>
      <FooterLink href="#">Blog</FooterLink>
      <FooterLink href="#">Contact</FooterLink>
    </FooterLegal>
    <FooterCopyright>© 2026 Koala UI</FooterCopyright>
  </FooterBottom>
</Footer>
```

## Density

`density` tunes the block padding and the gap to the bottom bar. Set it per footer or for a whole subtree with `DensityProvider`. See [Density](https://www.koalaui.com/docs/foundations/density.md).

```tsx
<Footer density="compact">…</Footer>
```

## API reference

### Footer

The root `<footer>`. Provides the styling context to every part and renders the max-width gutter. Forwards all `<footer>` props.

- `layout`: `"aside"` (default: link columns cluster across the right half, beside the brand) or `"wide"` (they take the whole row and distribute edge to edge).
- `density`: `"comfortable"` (default) or `"compact"`. Falls back to the nearest `DensityProvider`.

### FooterTop · FooterBrand · FooterTagline

`FooterTop` lays the brand column beside the link columns; `FooterBrand` is that column (logo, tagline, social, or a newsletter); `FooterTagline` is the muted lead line.

### FooterColumns · FooterColumn · FooterLink

`FooterColumns` grids the columns; `FooterColumn` takes a `title` and stacks `FooterLink`s (each accepts `asChild` for a framework `<Link>`). A page that is not live yet takes `aria-disabled` (a `<span>` through `asChild`): it keeps its resting ink and stops answering the pointer. Pair it with a small `Badge`.

### FooterSocial · FooterSocialLink

A row of icon-only links. Pass `aria-label` to each `FooterSocialLink`. The glyph has no accessible name on its own.

### FooterBottom · FooterCopyright · FooterLegal

The lower bar (separated by a hairline), the tabular-nums copyright line, and the inline group for legal/secondary links.

## FAQ

### How do I add a newsletter signup to the footer?

There is no newsletter part. Compose an Input and a Button inside `FooterBrand`, which keeps the footer dependency-free and lets it reuse the controls you already have.

### Is there a filled or muted footer panel?

No. Every footer sits on the page background and is closed by a hairline top rule, so the closing band reads as part of the page rather than a card bolted onto the bottom of it. If you need a tinted closing band, that is a Section above the footer, not a footer variant.

### What does the `layout` prop change?

It decides how much of the top row the link columns own. `aside` (the default) clusters them across the right half so a brand column can sit beside them; `wide` gives them the whole row so a six-column sitemap distributes edge to edge.

### How do I render just a one-line footer without the link columns?

Drop `FooterTop` and `FooterColumns` and render only the `FooterBottom` bar: the brand, an inline nav, and the copyright sit together on one line.

### How do I use a framework Link inside FooterLink?

Pass `asChild` to `FooterLink` and provide your own `<Link>` as the child. The footer link styling wraps your routing component instead of a plain anchor.

### Why do my social icons have no accessible name?

`FooterSocialLink` is icon-only, so the glyph has no text. Pass an `aria-label` to each one so screen readers announce the destination.

### How do I tighten the footer spacing?

Set `density` to `compact` on `Footer` to reduce the block padding and the gap to the bottom bar. Set it per footer or for a whole subtree with `DensityProvider`.

---

<!-- https://www.koalaui.com/docs/components/gallery.md -->

# Gallery

A marketing concepts wall: a balanced headline and lead, an optional tab rail to switch template categories, and a full-bleed fake-masonry of framed preview tiles. Our own Tabs, plus plain CSS columns.

```tsx
<Gallery>
  <Tabs defaultValue="home">
    <GalleryHeader>
      <GalleryTitle>Create Multiple Concepts in a Matter of Seconds</GalleryTitle>
      <GalleryDescription>
        Cover virtually any marketing project with our pre-designed sections and templates.
      </GalleryDescription>
      <TabsList className="mt-5 mx-auto flex w-fit gap-1.5">
        <TabsTrigger value="home" className="gap-1.5"><House /> Home</TabsTrigger>
        <TabsTrigger value="blog" className="gap-1.5"><PencilSimpleLine /> Blog article</TabsTrigger>
        {/* …About, Pricing, Careers */}
      </TabsList>
    </GalleryHeader>

    <TabsContent value="home" className="data-[state=active]:animate-in data-[state=active]:fade-in-0">
      <GalleryMasonry>
        <GalleryItem><GalleryImage src="/previews/home-1.jpg" alt="Landing page concept" className="aspect-[4/5]" /></GalleryItem>
        <GalleryItem><GalleryImage src="/previews/home-2.jpg" alt="Product homepage" className="aspect-[3/2]" /></GalleryItem>
        {/* …more tiles */}
      </GalleryMasonry>
    </TabsContent>
    {/* …a TabsContent per tab */}
  </Tabs>
</Gallery>
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add gallery
```

Manual: run `npm install radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/gallery/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

```tsx title="usage.tsx"
import {
  Gallery, GalleryHeader, GalleryTitle, GalleryDescription,
  GalleryMasonry, GalleryItem, GalleryImage,
} from "@/components/ui/gallery"

const PHOTOS = [
  { src: "https://images.unsplash.com/photo-1497366216548-37526070297c?w=800", alt: "Open-plan office", ratio: "aspect-[4/5]" },
  { src: "https://images.unsplash.com/photo-1522071820081-009f0129c71c?w=800", alt: "Team at a table", ratio: "aspect-[3/2]" },
  { src: "https://images.unsplash.com/photo-1519389950473-47ba0277781c?w=800", alt: "Laptops on a desk", ratio: "aspect-square" },
]

export function Example() {
  return (
    <Gallery>
      <GalleryHeader>
        <GalleryTitle>Inside the studio</GalleryTitle>
        <GalleryDescription>A week of work, in pictures.</GalleryDescription>
      </GalleryHeader>
      <GalleryMasonry>
        {PHOTOS.map((photo) => (
          <GalleryItem key={photo.src}>
            <GalleryImage src={photo.src} alt={photo.alt} className={photo.ratio} />
          </GalleryItem>
        ))}
      </GalleryMasonry>
    </Gallery>
  )
}
```

## Without tabs

Tabs are an optional composition. Drop the `Tabs` wrapper and render a single `GalleryMasonry` directly inside the section for a plain heading-plus-wall layout.

```tsx
<Gallery>
  <GalleryHeader>
    <GalleryTitle>From our customers</GalleryTitle>
    <GalleryDescription>A wall of real projects shipped with Koala UI.</GalleryDescription>
  </GalleryHeader>
  <GalleryMasonry>
    <GalleryItem><GalleryImage src="/previews/1.jpg" alt="Project preview" className="aspect-[4/5]" /></GalleryItem>
    <GalleryItem><GalleryImage src="/previews/2.jpg" alt="Project preview" className="aspect-[3/2]" /></GalleryItem>
    {/* …more tiles */}
  </GalleryMasonry>
</Gallery>
```

## As an accordion

One more gallery layout: instead of a wall, present the work as a vertical index of collections. Each row previews itself with a peeking thumbnail stack and opens, on click, to a caption and a strip of framed photos that stagger in. It is built on our [Accordion](https://www.koalaui.com/docs/components/accordion.md) (Radix keyboard and ARIA), so only one collection is open at a time. Compose the parts with `GalleryAccordion` and friends.

```tsx
<GalleryAccordion defaultValue="brand">
  <GalleryAccordionItem value="brand">
    <GalleryAccordionTrigger
      tagline="The new mark, palette, and the system behind it."
      count={18}
      peek={<GalleryAccordionPeek images={brandThumbs} />}
    >
      Brand refresh
    </GalleryAccordionTrigger>
    <GalleryAccordionContent>
      <GalleryAccordionCaption>A ground-up rebrand: studies, palette, guidelines.</GalleryAccordionCaption>
      {/* Each tile opens the full-screen Lightbox at its index. */}
      <Lightbox images={brandPhotos}>
        <GalleryAccordionMedia>
          {brandPhotos.map((photo, i) => (
            <LightboxTrigger key={photo.src} index={i} asChild>
              <GalleryAccordionImage className="h-44 w-60" src={photo.src} alt={photo.alt} action="View" />
            </LightboxTrigger>
          ))}
        </GalleryAccordionMedia>
      </Lightbox>
    </GalleryAccordionContent>
  </GalleryAccordionItem>
  {/* …Mobile app, Design system, Marketing site, Illustration */}
</GalleryAccordion>
```

`density="compact"` tightens the rows for a denser index. The open chapter is controlled with `value` / `defaultValue` / `onValueChange`, and opens on click or keyboard, never hover.

```tsx
<GalleryAccordion density="compact" defaultValue="system">
  {/* …collection rows */}
</GalleryAccordion>
```

## API reference

### Gallery

The full-bleed `<section>` that provides the styling context and clips the masonry's outer tiles at its edges (`overflow-hidden`). Forwards native section props.

### GalleryHeader · GalleryTitle · GalleryDescription

The centered lede column and its balanced `<h2>` + muted lead paragraph. Place a [Tabs](https://www.koalaui.com/docs/components/tabs.md) rail inside the header to switch concept sets.

### GalleryMasonry

The fake-masonry wall — plain CSS `columns` (2 → 3 → 4 across breakpoints), so varied natural image heights do the staggering. Wider than the gutter by default; override `className` to retune the column count or width.

### GalleryItem

One framed tile: a concentric-radius card that lifts and deepens its shadow on hover. Accepts `asChild` to render as a link while keeping the tile styles.

### GalleryImage

The preview image; fills its tile and gently scales as the tile is hovered. Defaults to a lazy-loaded, non-draggable image with an empty `alt` — pass a real `alt` when the image carries meaning.

### GalleryAccordion · GalleryAccordionItem · GalleryAccordionTrigger

The accordion layout (see “As an accordion”). The root is a value-controlled Radix Accordion (`type="single"`, `collapsible`) with `density` / `size`; each `GalleryAccordionItem` needs a unique `value`. The trigger takes `tagline`, `count`, and a `peek` stack, and draws its own `+` toggle. Opens on click/keyboard, never hover.

### GalleryAccordionPeek · GalleryAccordionContent · GalleryAccordionCaption · GalleryAccordionMedia · GalleryAccordionImage

`GalleryAccordionPeek` is the overlapping thumbnail stack on a closed row (it fades out on open). The panel holds an optional `Caption` over a `Media` strip of framed `GalleryAccordionImage` tiles that stagger in; give a tile `overlay` for a `+N` badge or `action` to make it an interactive button that pairs with [Lightbox](https://www.koalaui.com/docs/components/lightbox.md).

## FAQ

### Where do the tabs come from?

Gallery ships no tabs of its own. The tab rail is composed from the existing Koala Tabs component: put the `TabsList` inside `GalleryHeader` and wrap each `GalleryMasonry` in a `TabsContent`, so the concepts wall stays consistent with the rest of the design system.

### How is the masonry built?

With plain CSS multi-column layout on `GalleryMasonry` (`columns-2 sm:columns-3 lg:columns-4`). The tiles keep their images' natural aspect ratios, and the varied heights are what produce the staggered, fake-masonry look. No JS measuring and no masonry library.

### Why do the outer tiles get cut off at the edges?

That is intentional. `Gallery` is `overflow-hidden` and the masonry is wider than the centered gutter, so the outer columns clip against the section edges for a wide, immersive band. Constrain `GalleryMasonry` with a narrower `max-w-*` in `className` if you want every tile fully visible.

### Can a tile be a link?

Yes. Pass `asChild` to `GalleryItem` and give it a single child (for example a Next `Link`); the tile styling, hover lift, and concentric radius merge onto your element.

### Do I have to use tabs?

No. Tabs are optional. Omit the `Tabs` wrapper and render one `GalleryMasonry` directly inside the section for a plain heading-plus-wall gallery.

### Should I use next/image for the previews?

`GalleryImage` is a plain lazy-loaded `<img>` so it works with any remote source without extra config. Swap in your own optimized image element via `asChild` on `GalleryItem` if you need `next/image` and have the remote host configured.

### Can the gallery be an accordion instead of a wall?

Yes. Gallery ships an accordion layout as one more option (see “As an accordion”): the `GalleryAccordion` parts present the work as a vertical index of collections that open, one at a time, to a strip of photos. It is built on the Accordion's Radix foundation, opens on click or keyboard (never hover), and pairs each photo with the Lightbox just like the masonry tiles.

---

<!-- https://www.koalaui.com/docs/components/hero.md -->

# Hero

A centered marketing hero section. Named parts you assemble: an announcement eyebrow, a balanced headline, a subtitle, a CTA row, a check-circle feature list and an integrated social-proof row.

```tsx
<Hero>
  <HeroCursors>
    <HeroCursor color="brand" facing="right" duration={15} className="left-[12%] top-[20%]" labels={["Client", "Founder", "Marketing"]} />
    <HeroCursor color="purple" duration={18} phase={0.4} className="right-[14%] top-[28%]" labels={["Developer", "Designer", "Product"]} />
    <HeroCursor color="success" duration={13} phase={0.7} className="left-[8%] top-[66%]" labels={["You", "Your team"]} />
  </HeroCursors>
  <HeroContent>
    <Announcement>
      Update available
      <Badge variant="orange" dot pill>Koala UI v11 is here!</Badge>
    </Announcement>
    <HeroTitle>A design system built to feel finished</HeroTitle>
    <HeroSubtitle>89 accessible React components and four themes, with the real source copied straight into your repo. Assemble production screens in an afternoon, not a sprint.</HeroSubtitle>
    <HeroActions>
      <Button size="lg">Buy once, use forever</Button>
      <Button size="lg" variant="outline">Get the Figma kit</Button>
      <Button size="lg" variant="outline">Browse the docs</Button>
    </HeroActions>
    <HeroFeatures balance>
      <HeroFeature>89 accessible components</HeroFeature>
      <HeroFeature>Own every line of source</HeroFeature>
      {/* …more */}
    </HeroFeatures>
    <HeroSocialProof>
      <AvatarGroup size="sm">
        <Tooltip content="Ana Ruiz">
          <Avatar size="sm"><AvatarFallback>AR</AvatarFallback></Avatar>
        </Tooltip>
        {/* …more */}
      </AvatarGroup>
      <HeroRating>4.8/5 average rating</HeroRating>
    </HeroSocialProof>
  </HeroContent>
</Hero>
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add hero
```

Manual: run `npm install radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/hero/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

```tsx title="usage.tsx"
import { Button } from "@/components/ui/button"
import {
  Hero, HeroContent, HeroTitle, HeroSubtitle, HeroActions, HeroFeatures, HeroFeature,
} from "@/components/ui/hero"

export function Example() {
  return (
    <Hero>
      <HeroContent>
        <HeroTitle>Ship the product, not the plumbing</HeroTitle>
        <HeroSubtitle>
          Everything your team needs to go from idea to launch, in one workspace.
        </HeroSubtitle>
        <HeroActions>
          <Button size="lg">Start free</Button>
          <Button size="lg" variant="outline">Book a demo</Button>
        </HeroActions>
        <HeroFeatures>
          <HeroFeature>No credit card</HeroFeature>
          <HeroFeature>Cancel anytime</HeroFeature>
        </HeroFeatures>
      </HeroContent>
    </Hero>
  )
}
```

## Minimal

Drop the features and social-proof rows for a lean hero: just the eyebrow, title, subtitle, and CTAs. Override the vertical rhythm on `HeroContent` when you want it tighter.

```tsx
<Hero>
  <HeroContent className="py-16 sm:py-20">
    <Badge variant="info" dot pill>New: Koala UI for React</Badge>
    <HeroTitle>Build polished products, faster</HeroTitle>
    <HeroSubtitle>A production-ready component library you can install with one command.</HeroSubtitle>
    <HeroActions>
      <Button size="lg">Get started</Button>
      <Button size="lg" variant="outline">Browse components</Button>
    </HeroActions>
  </HeroContent>
</Hero>
```

## Display title

`size` on `HeroTitle` sets the headline's scale. The default `"lg"` peaks at 60px, level with a `SectionHeader size="lg"`; `"xl"` is the display cut for the page's one big statement, peaking at 72px. The tracking stays `tight`: DM Sans follows its optical-size axis, so at display sizes it already sets in its tighter cut. Widen the column with `max-w-5xl` on `HeroContent` so a display headline keeps two lines, and give the rating `size="md"` stars so the proof row holds its own under the bigger type.

```tsx
<Hero>
  <HeroContent className="max-w-5xl">
    <Announcement>
      Update available
      <Badge variant="orange" dot pill>Koala UI v11 is here!</Badge>
    </Announcement>
    <HeroTitle size="xl">A Design System built for AI-Powered Products</HeroTitle>
    <HeroSubtitle>A Design System for builders of AI assistants, copilots and intelligent tools, ship MVPs fast.</HeroSubtitle>
    <HeroActions>
      <Button>Buy now &amp; use forever</Button>
      <Button variant="outline">Preview Desktop</Button>
    </HeroActions>
    <HeroSocialProof>
      <AvatarGroup size="md">{/* AvatarRoot size="md" × N */}</AvatarGroup>
      <HeroRating size="md">5.0 Ratings</HeroRating>
    </HeroSocialProof>
  </HeroContent>
</Hero>
```

## Rotating highlight

Pass `rotate` a list of phrases to `HeroHighlight` and the wash becomes a rotating *zone*: the words inside swap, each entering with a per-character stagger while the previous one clears, the wash **hugs each word** (tweening its width as the phrase changes), and each phrase takes the **next color** in the palette (semantic DS roles, so it tracks every theme), the tint crossfading as it swaps. Lead every phrase with the same word so the left edge stays anchored against the copy beside it and only the right edge resizes. Give the title a touch more line-height (the demo uses `leading-[1.2]`) so the wash always clears the line above it. It holds each phrase for `interval` ms (default 2600) and honors `prefers-reduced-motion` by holding the first phrase with no cascade.

```tsx
<HeroTitle className="leading-[1.2]">
  Bring your product into{" "}
  <HeroHighlight rotate={["every decision", "every workflow", "every release", "every roadmap"]}>
    every decision
  </HeroHighlight>
</HeroTitle>
```

## Cursors

Add a `HeroCursors` layer and place `HeroCursor`s in it for the feel of a live, shared design file. Each cursor wanders its own slow loop, pauses twice, and clicks at each pause: the arrow presses and a soft ripple leaves the tip. Give every cursor a different `duration` (seconds per loop, default 16) and `phase` (0 to 1) so they never move in step. `color` takes a semantic role (`brand`, `purple`, `teal`, `pink`, `orange`, `success`), so the fills follow every theme, and `facing` points the arrow left or right; the name tag always hangs on the side away from the point. Place each cursor's tip with `className`, and resize its loop with `[--cursor-x:…]` / `[--cursor-y:…]` (a negative x mirrors it).

Pass `labels` (an array of names) instead of children and the name tag rolls to the next one on every click, twice a loop: the old name lifts out, the new one rises in, and the pill eases to its width, the same `AnimatedLabel` roll every changing label in Koala uses. The swap is timed off the cursor's own loop, so it always lands as the arrow presses, and it stops whenever the cursor is hidden.

The layer is decoration only. It is hidden from assistive tech, lets every click through to the copy underneath, and shows its cursors only when the hero itself is at least 64rem wide (a container query, so it reads the hero's width, not the window's), which keeps them in the gutters and off the headline on smaller frames. When your cursors roam space the copy never reaches (the bands above and below it, as in this demo), reveal them sooner with `className="@2xl:block"` (a 42rem hero). Under `prefers-reduced-motion` they hold still where you placed them, with no ripple.

```tsx
<Hero>
  <HeroCursors>
    <HeroCursor color="brand" facing="right" duration={15} className="left-[18%] top-[9%] @2xl:block [--cursor-x:-28px]" labels={["Client", "Founder", "Marketing"]} />
    <HeroCursor color="purple" duration={18} phase={0.4} className="right-[22%] top-[12%] @2xl:block" labels={["Developer", "Designer", "Product"]} />
    <HeroCursor color="success" duration={13} phase={0.7} className="bottom-[14%] left-[24%] @2xl:block" labels={["You", "Your team"]} />
  </HeroCursors>
  <HeroContent className="py-28 sm:py-32">{/* eyebrow, title, subtitle, actions */}</HeroContent>
</Hero>
```

## Poster wall

When the product itself is a wall of covers (events, classes, listings, releases), open on that content instead of a screenshot of it. A `HeroScatter` layer fills the band with tilted `HeroScatterTile` prints and the copy stands in the clearing at its centre. Each tile takes a `size` (`sm` / `md` / `lg`, square, stepping up twice as the hero widens), a `depth` (`far` sits it smaller and lighter, further back), a `tilt` in degrees, and a `delay`, so the wall assembles card by card on mount. Place each one with `className`; a negative offset (`-left-4`) lets the band crop it, which is what makes the wall read as bigger than the page.

Give the copy a taller `pt` / `pb` than usual: that clearing is what keeps the top and bottom cards off the words where there are no gutters to put them in. The layer is a size container, so hold the rest back until the hero has earned the room (`hidden @5xl:block` for the sides of a 48rem copy column). Like the cursors it is decoration only: hidden from assistive tech, never in the way of a click, and still under `prefers-reduced-motion`. The copy on top of it stays the house stack, and the headline goes plain: the wall is already the colour on this band, and a `HeroHighlight` wash under a 72px line reads as a slab rather than an accent.

```tsx
<Hero>
  <HeroScatter>
    {tiles.map((tile, i) => (
      <HeroScatterTile key={tile.id} size={tile.size} depth={tile.depth} tilt={tile.tilt} delay={i * 40} className={tile.place}>
        <img src={tile.src} alt={tile.alt} />
      </HeroScatterTile>
    ))}
  </HeroScatter>
  {/* the clearing: a taller pt/pb keeps the cropped cards off the copy */}
  <HeroContent className="max-w-3xl pt-32 pb-36 sm:pt-36 sm:pb-40">
    <Badge variant="pink" dot pill>Free to host</Badge>
    {/* Plain headline: the wall is the colour on this band, so no keyword marker */}
    <HeroTitle size="xl" className="max-w-2xl">
      Host the kind of night people talk about
    </HeroTitle>
    <HeroSubtitle className="max-w-lg">
      Supper clubs, workshops, launch parties, a five-a-side game: build the page, send the invite,
      and keep every RSVP in one place.
    </HeroSubtitle>
    <HeroActions size="md">
      <Button>Create an event</Button>
      <Button variant="outline">Browse events</Button>
    </HeroActions>
  </HeroContent>
</Hero>
```

## Feature columns

`HeroFeatures` has a second shape. Set `layout="columns"` and the inline check row becomes three capability columns, each a bare brand-tinted mark over a title and a sentence: pass `icon` and `title` to every `HeroFeature` inside and the sentence stays as its children. Reach for it when the three claims each deserve a sentence rather than three words, and the page has no room for a separate feature section above the fold.

Nothing is drawn between the columns: no rule, no padding, no surface, so the gutter carries the separation and stays wide enough to do it. It is a grid, not a wrapping row, and every column subgrids onto the same three tracks, so a title that wraps to two lines pushes all three sentences down together instead of stranding its neighbours half a line high. Below the `sm` breakpoint the tracks collapse and the columns stack. The row follows the hero it sits in: centered under a centered column, flush-left in a `split`, and white over `background` media.

```tsx
<Hero>
  <HeroContent className="max-w-5xl">
    <Badge variant="info" dot pill>Design to launch</Badge>
    <HeroTitle className="max-w-3xl">
      Design, build and <HeroHighlight>launch</HeroHighlight> in one place
    </HeroTitle>
    <HeroSubtitle>Eighty-nine components, four themes and whole page sections.</HeroSubtitle>
    <HeroActions>
      <Button>Start for free</Button>
      <Button variant="outline">Browse components</Button>
    </HeroActions>
    <HeroFeatures layout="columns">
      <HeroFeature icon={<PaintBrushBroad weight="bold" />} title="Make it yours">
        Four themes and a radius knob, so the kit wears your brand before you write a line.
      </HeroFeature>
      <HeroFeature icon={<StackSimple weight="bold" />} title="Build from finished parts">
        Whole page sections, not just buttons: paste a hero, a pricing table, a footer.
      </HeroFeature>
      <HeroFeature icon={<RocketLaunch weight="bold" />} title="Ship the same day">
        You own the source. Drop it in your repo and launch without waiting on a handoff.
      </HeroFeature>
    </HeroFeatures>
    <HeroMedia className="w-full max-w-4xl">{/* framed screenshot */}</HeroMedia>
  </HeroContent>
</Hero>
```

## Split layout

Set `layout="split"` on `Hero` to turn the content into a two-column grid: a `HeroColumn` of copy beside a `HeroMedia` visual (an image, screenshot, or logo wall). It folds back to a single stacked column below the lg breakpoint. The same parts read the layout from context, so the only change is the prop.

```tsx
<Hero layout="split">
  <HeroContent>
    <HeroColumn>
      <Badge variant="info" dot pill>Now in public beta</Badge>
      <HeroTitle>Analytics your whole team actually uses</HeroTitle>
      <HeroSubtitle>Real-time dashboards with no setup.</HeroSubtitle>
      <HeroActions>
        <Button size="lg">Get started</Button>
        <Button size="lg" variant="outline">Live demo</Button>
      </HeroActions>
      <HeroSocialProof>{/* AvatarGroup + HeroRating */}</HeroSocialProof>
    </HeroColumn>
    <HeroMedia>{/* image placeholder, screenshot, or logo wall */}</HeroMedia>
  </HeroContent>
</Hero>
```

## Background media

Set `layout="background"` and add a `HeroBackground` to turn the hero into a full-bleed band: the media covers the section, a gradient scrim lays over it, the copy flips to white, and the eyebrow goes glassy, all from the one prop. Drop a plain `<img>` in for a photo, or an `autoPlay muted loop playsInline` `<video>` for ambient motion (muted autoplay is the only kind browsers allow unprompted). Give the video a `poster` so the band never flashes empty, and a still `<img className="hidden motion-reduce:block">` fallback so it holds a frame under `prefers-reduced-motion`.

```tsx
<Hero layout="background" className="rounded-lg">
  <HeroBackground>
    <video src={videoSrc} poster={posterSrc} autoPlay loop muted playsInline />
    <img className="hidden motion-reduce:block" src={posterSrc} alt="" />
  </HeroBackground>
  <HeroContent>
    <Announcement variant="glass" dot>Now in private beta</Announcement>
    <HeroTitle>Support that never sleeps</HeroTitle>
    <HeroSubtitle>AI agents pick up every call and answer in seconds.</HeroSubtitle>
    <HeroActions>
      <Button size="lg">Get started</Button>
    </HeroActions>
  </HeroContent>
</Hero>
```

```tsx
<Hero layout="background" className="rounded-lg">
  <HeroBackground>
    <img src={photoSrc} alt="" />
  </HeroBackground>
  <HeroContent>
    <Announcement variant="glass" dot>Series A: $61M to scale support</Announcement>
    <HeroTitle>AI that talks like a human. Handles millions of calls.</HeroTitle>
    <HeroSubtitle>AI agents for enterprise support.</HeroSubtitle>
    <HeroActions>
      <Button size="lg">Talk to us</Button>
    </HeroActions>
    {/* a monochrome trusted-by row over the scrim */}
  </HeroContent>
</Hero>
```

## Scroll stage

`HeroStage` is the hero that plays itself as the reader scrolls: one photograph opens full-bleed under a display line, contracts into a centred card, and a collage assembles around it while the copy rises underneath. Several things move at once rather than one: the frame contracts, the picture inside it pushes in on its own slower beat (so the shot gains depth instead of just getting smaller), the display line grows past the frame and defocuses as the camera goes through it, and each collage piece flies in from its own edge, leaning, and settles level. Once landed, the pictures keep a slow drift inside their frames, each on its own clock, so the composition breathes instead of freezing when the reader stops. All of it is **scrubbed by the scroll position** through a single CSS view timeline, so there is no animation library, no scroll listener and no `requestAnimationFrame` loop anywhere in it: it runs backwards when the reader scrolls back up, and costs nothing off screen. Compose it in place of `HeroContent`. Every part is droppable, so a stage holding nothing but a `HeroStageMedia` is a picture that contracts.

It spends three viewports of scrolling on a single statement, so it is a page's one cinematic moment, not a section to reach for twice. Browsers with no scroll-driven animations, and readers who asked for reduced motion, get a single viewport holding the **last** frame: the picture at its card size, the collage assembled around it, and the eyebrow, lede and CTAs where they land. Only the display word is missing there, since a word cut to fill a screen cannot sit inside a card, so put an ordinary `HeroTitle` in the closing `HeroStageReveal` when the section needs a headline visible at rest. See [the scroll stage section](https://www.koalaui.com/marketing/sections/hero.md) for the finished slab.

## Parallax cover

`layout="cover"` is the editorial opener: one picture or clip takes the whole viewport (`100svh`, so a phone's shrinking browser chrome can never cut the words off) and the copy stands along its bottom edge, the headline in one corner and the paragraph in the other. Where `layout="background"` centres a copy column in the middle of the band and treats the media as a backdrop for it, here the media **is** the statement and the words are a caption laid along the foot of it, so the frame is never covered. Set the headline to `size="2xl"`, the 96px poster cut, and keep it to two or three words.

It does not stay full bleed. As the reader scrolls, the frame pulls in to the page's own container (90rem, the `max-w-8xl` every other section sits in) and rounds its corners, so the opening picture hands the page back to its grid instead of ending at a hard seam. One registered number, `--hero-cover-t`, animates on the band and the frame's width, its corner and the caption's padding are `calc()`s reading it, so they cannot drift out of step: the caption steps in by exactly what the frame pulls in by and the words hold the same distance from the picture's edge from the first frame to the last, at every width. Retune the landing with `[--hero-cover-gutter:…]`, `[--hero-cover-max:…]` and `[--hero-cover-radius:…]`, and when it runs with `[--hero-cover-contract-start:…]` / `-end` (a hero opens at the top of the page, which is already halfway through its own `cover` range, so the beat starts at 50% and finishes half a viewport of scrolling later).

The parallax is one prop: `<HeroBackground parallax>`. The media travels slower than the band it fills while the caption over it travels a little faster, so the two planes separate and the band reads as a window rather than a picture glued to the page. It is **scrubbed by the scroll position** through a CSS view timeline, the same engine the scroll stage runs on, so there is no animation library (parallax is the effect people install GSAP and Lenis for), no scroll listener and no `requestAnimationFrame` loop: it runs on the compositor, off the main thread, goes backwards when the reader scrolls back up, and costs nothing off screen. The media is held a quarter larger than its frame for the whole travel, which is the slack the drift moves within, so give it a picture with room around its subject. Retune with `[--hero-parallax-travel:…]` and `[--hero-parallax-zoom:…]` on the hero, keeping travel at or under `(zoom - 1) / 2` or the frame will show its ground at the ends of the drift.

Browsers with no scroll-driven animations, and readers who asked for reduced motion, get the same hero full bleed and still, with the media sitting level in its frame: a parallax has a neutral frame, and the neutral frame is a finished, full-bleed cover. The drift also works under `layout="background"`, which declares the same timeline. See [the parallax cover section](https://www.koalaui.com/marketing/sections/hero.md) for the finished slab.

## API reference

### Hero · HeroContent · HeroColumn

`Hero` is the full-bleed `<section>` that provides the styling context. It takes a `layout` prop: `"centered"` (default), `"split"`, `"background"`, or `"cover"` (a full-viewport picture with the copy standing along its bottom edge). `HeroContent` is the max-width column (a stacked column when centered, a two-column grid when split); `HeroColumn` groups the copy in the split layout. All forward their native element props.

### HeroTitle · HeroHighlight · HeroSubtitle

The balanced `<h1>` (its `size` is `"lg"`, 60px, the `"xl"` 72px display cut, or the `"2xl"` 96px poster cut for a `cover`), `HeroHighlight` to mark a keyword inside the title with a soft brand wash, and the muted lead paragraph. `HeroHighlight` also takes `rotate` (a list of phrases to cycle through, with a per-character stagger, a wash that hugs each word, and a color per phrase) and `interval` (ms each phrase holds, default 2600). The wash is the only way Koala marks a word in a headline: no gradient text anywhere in the system. The announcement pill above the title is not a Hero part: it is the standalone [Announcement](https://www.koalaui.com/docs/components/announcement.md) atom, so the same pill works in a navbar or a pricing header. Over media it takes `variant="glass"`.

### HeroActions

The centered CTA row. Compose our [Button](https://www.koalaui.com/docs/components/button.md)s inside it.

### HeroFeatures · HeroFeature

`HeroFeatures` wraps the checklist; `HeroFeature` is one item and renders its own green check-circle glyph before the label. `HeroFeatures` also takes `balance`, which caps the row at a 36rem measure so the items wrap into even rows (2 + 2) instead of stranding the last one alone on its own line (3 + 1): `text-wrap: balance`, but for a flex row. Worth setting on any list of four or more items; a list that already fits the measure is untouched. Pass `layout="columns"` instead and the row becomes capability columns: each `HeroFeature` then takes an `icon`, drawn bare in the brand accent, and a `title` above the sentence, and drops the check-circle. Give every item in that row an icon, or none of them one: the columns share their tracks, so a single missing mark shifts that column's copy up a row.

### HeroSocialProof · HeroRating

The proof row. Drop an [AvatarGroup](https://www.koalaui.com/docs/components/avatar-group.md) in for the overlapping stack and a star rating beside it. `HeroRating` takes a `value` and `max` (both default 5), a star `size` (default `"sm"`; `"md"` beside a larger avatar stack), and renders the label as children.

### HeroMedia

The visual region. In a split hero it fills the second column; in a centered hero it sits below the copy. Drop an image or screenshot in, or a wall of customer logos. The demos ship an image placeholder so you can drop your own screenshot straight in.

### HeroBackground

The full-bleed media layer for `layout="background"` and `layout="cover"`. It stretches its child `<img>` or `<video>` to cover the section and lays a gradient scrim over it, so the white copy stays legible on any photo. It sits behind `HeroContent`, and the section's `overflow-clip` (plus any rounded corners) clips the media to the band, which is also what contains the parallax travel. It takes `parallax`, which drifts the media against the page as the reader scrolls (a CSS view timeline, no animation library and no scroll listener; still under reduced motion). See Parallax cover above.

### HeroCursors · HeroCursor

`HeroCursors` is the decorative layer: it covers the hero, is `aria-hidden` and `pointer-events-none`, and shows its cursors once the hero is at least 64rem wide. `HeroCursor` is one cursor, positioned by its tip through `className`. It takes `color` (default `"brand"`), `facing` (`"left"` or `"right"`, default left), `duration` (seconds per loop, default 16) and `phase` (0 to 1, default 0). Its children are the name tag; omit them for a bare arrow, or pass `labels` (a string array) for a tag that rolls to the next name on each click.

### HeroScatter · HeroScatterTile

`HeroScatter` is the poster-wall layer: like `HeroCursors` it covers the hero, is `aria-hidden` and `pointer-events-none`, and is a size container, but it sits *behind* the copy rather than over it. `HeroScatterTile` is one card: a photo print placed by its `className` (`-left-4 top-4`, plus a `hidden @5xl:block` gate where it needs room), holding a plain `<img>` that it sizes, rounds and crops. It takes `size` (`"sm"`, `"md"` default, or `"lg"`; square, and each steps up twice as the hero widens), `depth` (`"near"` default or `"far"`, which steps the card back into the page), `tilt` (degrees, keep the wall between about -12 and 12) and `delay` (ms before it drifts in, so the wall assembles card by card). It holds still under `prefers-reduced-motion`.

### HeroSpread · HeroSpreadMedia · HeroSpreadPanel · HeroSpreadIndex

The magazine spread: compose these **instead of** `HeroContent`, since the panel pads itself. `HeroSpread` is the two-track grid (stacked below `lg`); `HeroSpreadMedia` is the picture half, which covers and crops a plain `<img>` or `<video>` and carries its own aspect ratio while the halves are stacked; `HeroSpreadPanel` is the inked half, which takes `tone` (`"brand"` default, the raw accent, or `"ink"`, a slab pinned dark on every page theme) and wants *exactly two* children: it pushes the first to its top edge and the second to its foot. `HeroSpreadIndex` is the chapter mark in the outer corner, decorative and hidden from assistive tech. Over `brand` the lead action is `<Button tone="onMedia">`; over `ink` it is `variant="neutral"`.

### HeroStatement · HeroSignoff

`HeroStatement` is the section's `<h1>` when the hero *is* a sentence, so it replaces `HeroTitle` rather than joining it: display scale on a 36-character measure, semibold at 1.2 leading because a long sentence in bold display type reads as shouting. Mark the phrase it turns on with `HeroHighlight`, exactly as in a headline. `HeroSignoff` is the letter's closing under it, one line per child, in the house's small monospace voice. To close it by hand instead of with a typed name, drop a [Signature](https://www.koalaui.com/docs/components/signature.md) in as its last line: it writes itself in once the hero is on screen.

### HeroMosaic · HeroFrame

`HeroFrame` is one framed picture anywhere in a hero: the unpinned sibling of a `HeroScatterTile` (that one is a print pinned into a wall; this one sits in normal flow). Give it its shape with `className` (`aspect-square`, a `max-w-*`) and a plain `<img>` inside; it crops it, keeps the hairline on top of the picture and drifts in after `delay` ms, holding still under `prefers-reduced-motion`. `tone="mono"` drops its colour, which is what makes a wall of unrelated photographs read as one picture. `HeroMosaic` is the band those frames sit in: a twelve-track grid across the top of the hero (two tracks while stacked), so a tile can take a third or a sixth of the row, break the top line with its own `mt-*`, and step out of a narrow band with a `hidden lg:block` gate. The gates are viewport breakpoints, not container queries, because the tracks are declared on the element that would have to be the container and nothing can answer its own container query; inside a docs frame that still measures the frame, which is an iframe of its own. Pull the band up past the hero's top edge with a negative `-mt-*` and the section opens on pictures the band has already cropped.

### HeroStage · HeroStageMedia · HeroStageTitle · HeroStageCard · HeroStageReveal

The scroll stage: compose these **instead of** `HeroContent`, not inside it. `HeroStage` is a scroll track taller than the viewport with one pinned screen inside it, and the only thing that declares the timeline. `HeroStageMedia` is the frame that contracts from full-bleed to a card (give it a plain `<img>` or a muted, looping `<video>`; it covers rather than fits, so the crop tightens as it closes) and takes `scrim` (default `true`), the gradient that carries the word. `HeroStageTitle` is the section's `<h1>` at poster scale, set inside the frame so the frame's own clip trims it: keep it to two or three words. Given a plain string it leaves **character by character**: the line grows past the frame and lifts as one object, while each letter sits in a mask of its own and slides up out of it a beat after the one before it, so the letterform stays crisp right up to the edge that cuts it instead of spending its exit as a grey smear. The split row is hidden from assistive tech with the heading carrying the text as its label, so a screen reader still reads a word rather than a column of letters. Retune the cascade with `[--hero-stage-exit-stagger:…]` (`0` turns it off) and how far a letter travels with `[--hero-stage-letter-travel:…]`. That travel overshoots one box-height on purpose: a glyph's ink is not bounded by its line box, so a descender hangs below it and a letter moved exactly its own height leaves its tail behind the edge. Raise it for a face with deep descenders. Pass anything that is not a plain string and the whole line leaves together. `HeroStageCard` is one collage piece and `HeroStageReveal` a band of late copy; both take an `index`, their place in the stagger; `HeroStageCard` also derives its picture's drift direction and duration from that index, so neighbours never sway in step. Tune a part's arrival with `[--hero-stage-drift:…]` (sideways, negative arrives from the left), `[--hero-stage-shift:…]` (vertical, negative drops in from above) and `[--hero-stage-tilt:…]` (the lean it settles out of). Size the card the picture lands on with `[--hero-stage-w:…]` / `[--hero-stage-h:…]` on the stage, its corner with `[--hero-stage-radius:…]`, the total scroll length with `[--hero-stage-track:…]` (default 280svh) and the gap between stagger steps with `[--hero-stage-stagger:…]`.

**Place everything on the stage with inset utilities** (`top-*`, `left-*`, `inset-x-0`), never `translate-*` or `scale-*`: Tailwind v4 writes those to the standalone `translate` and `scale` properties, which are the two the entrance animates, so a centring `-translate-x-1/2` would be overwritten and the part would slide sideways as it arrived. The parts centre themselves.

## FAQ

### Where do the buttons and avatars in a Hero come from?

Hero is pure layout, so it ships no controls of its own. It is composed entirely of existing Koala components: drop our Button inside `HeroActions`, an `AvatarGroup` and `Rating` in `HeroSocialProof`, and a dot `Badge` for the eyebrow, so the hero stays consistent with the rest of the design system.

### How do I render a lean hero without the feature list and ratings?

Just omit `HeroFeatures` and `HeroSocialProof`. A minimal hero is the eyebrow, title, subtitle, and CTAs, and you can tighten the rhythm by overriding the padding on `HeroContent`.

### Do I need to add a checkmark icon to each HeroFeature?

No. `HeroFeature` renders its own green check-circle glyph before the label, so you only pass the text. Wrap the items in `HeroFeatures`. The one exception is `HeroFeatures layout="columns"`, where each item is a capability column instead of a checklist line: there you pass `icon` and `title`, and the check is dropped.

### What does the count prop on HeroRating do?

`HeroRating` renders that many stars (default 5) and shows the label you pass as children, so a 5.0 rating reads correctly next to the avatar stack in `HeroSocialProof`.

### How do I make the highlighted keyword rotate through several words?

Pass `rotate` a list of phrases to `HeroHighlight`. The words swap with a per-character stagger, the wash hugs each one (tweening its width as the phrase changes), and each phrase takes the next color in the palette (semantic DS roles, so it tracks every theme). Set `interval` to change the hold (default 2600ms). It honors reduced-motion by holding the first phrase. Give the title a little extra line-height so the wash clears the line above it, and lead each phrase with the same word so the left edge stays anchored and only the right edge resizes.

### How do I add the moving cursors around the headline?

Add a `HeroCursors` layer inside `Hero` and place one `HeroCursor` per person, with the name as its children. Position each tip with `className` (for example `left-[12%] top-[20%]`), pick a `color` and which way it's `facing`, and give each one a different `duration` and `phase` so they wander, pause and click out of step. Pass `labels` (for example `labels={["Client", "Founder", "Marketing"]}`) instead of children and the tag rolls to the next name every time the cursor clicks. The layer is decorative: it's hidden from screen readers, never blocks a click, only appears when the hero is at least 64rem wide, and holds still under reduced motion.

### How do I put a photo or video behind the hero?

Set `layout="background"` on `Hero` and add a `HeroBackground` with a plain `<img>` (photo) or an `autoPlay muted loop playsInline <video>` (ambient motion) inside. The one prop covers the band with the media, lays a gradient scrim over it for legibility, flips the copy to white, and makes the eyebrow glassy. Give a video a `poster` so the band never flashes empty, and add a still `<img className="hidden motion-reduce:block">` fallback so it holds a frame under prefers-reduced-motion. Muted autoplay is the only kind browsers will play without a user gesture.

---

<!-- https://www.koalaui.com/docs/components/job-card.md -->

# Job Card

The canonical open-role block: a category badge, the role title, a one-line summary and a meta tier of location, employment type and salary band. Renders as a chrome-less row or a bordered card.

```tsx
<JobCard variant="card">
  <JobCardContent>
    <Badge variant="success">Marketing</Badge>
    <JobCardTitle>Senior Graphic Designer</JobCardTitle>
    <JobCardDescription>
      Lead creative projects to elevate brand identity and visual storytelling.
    </JobCardDescription>
    <JobCardMeta>
      <JobCardMetaItem icon={<JobCardFlag country="US" />}>San Francisco, CA</JobCardMetaItem>
      <JobCardMetaItem icon={<CalendarBlank />}>Full-time</JobCardMetaItem>
      <JobCardMetaItem icon={<Money />}>
        <span className="tabular-nums">$80,000 – $120,000</span>
      </JobCardMetaItem>
    </JobCardMeta>
  </JobCardContent>
  <JobCardAction>
    <Button variant="outline">Apply</Button>
  </JobCardAction>
</JobCard>
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add job-card
```

Manual: run `npm install radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/job-card/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

Compose the parts you need and omit the rest: there is no `showX` prop anywhere on this component. A role with no summary simply leaves out `JobCardDescription`; a board that links whole rows instead of showing a button leaves out `JobCardAction`. The eyebrow is an ordinary `Badge` dropped as the first child of `JobCardContent`, so it takes any tone in the Badge scale.

## Variants

`plain` (the default) is chrome-less: the row sits flush on whatever holds it, and the list that owns it paints the hairline between rows. `card` gives the role a box of its own: the boundary and nothing else, drawn straight on the page ground with no fill behind it, and with an inset ring rather than a border so the corner stays concentric with the radius inside it.

```tsx
<JobCard variant="plain">…</JobCard>
<JobCard variant="card">…</JobCard>
```

## Layouts

`split` (the default) rides the action against the right edge, vertically centred. `stacked` drops it below the content, which is what a card in a narrow column wants. `inline` is the table shape: title and meta share one line, and the meta becomes equal-width auto columns so the same template repeats on every row and the columns line up down the whole board. Both row layouts start as a stacked column and only become a row at their breakpoint (`sm`for split, `md` for inline), so an action never strands itself in the corner of a narrow frame.

```tsx
<JobCard layout="split">…</JobCard>
<JobCard layout="stacked" variant="card">…</JobCard>
<JobCard layout="inline">…</JobCard>
```

## Divided rows

`divided` turns a stack of plain rows into a board: a hairline under each one and the vertical band that gives the row its height. It is a rule of its own rather than a `border-b`, so it stays straight even under a rounded interactive row. Compose it as a real list, one `<li>` per role and no gap between them: the hairline is the separation, and the trailing rule is dropped from the last list item so the board does not close with a line under nothing.

```tsx
<ul className="flex flex-col">
  {roles.map((role) => (
    <li key={role.title}>
      <JobCard divided>…</JobCard>
    </li>
  ))}
</ul>
```

## Interactive rows

Pass `interactive` (with `asChild` and an `<a>` child) when the whole row opens the role. A plain interactive row pulls its hover fill back into a detached rounded panel so the wash does not bleed to the container edge, while the text stays flush-aligned, and the hairline pulls in by the same amount so it never overhangs the text. There is no press scale: a row that shrinks pulls its fill off the edges it sits against and starts reading as a floating tile, so the press is a deepening fill instead.

```tsx
<li>
  <JobCard divided interactive asChild>
    <a href="#senior-graphic-designer">…</a>
  </JobCard>
</li>
```

## Any action, not just a button

`JobCardAction` is a plain slot, so a board that wants to show who is hiring drops an `AvatarGroup` into it instead of a button. Nothing about the recipe changes.

```tsx
{/* Pass the same size to the group AND to every child: the group picks its overlap
    from its own size, so unsized 40px avatars under a 32px overlap stack wrong. */}
<JobCardAction>
  <AvatarGroup size="sm">
    {team.map((p) => (
      <AvatarRoot key={p.name} size="sm">
        <AvatarImage src={p.src} alt={p.name} />
        <AvatarFallback>{p.name[0]}</AvatarFallback>
      </AvatarRoot>
    ))}
  </AvatarGroup>
</JobCardAction>
```

## API reference

### JobCard

The root `<div>`. Forwards all native `<div>` props.

- `variant`: `"plain"` (default) | `"card"`.
- `layout`: `"split"` (default) | `"stacked"` | `"inline"`.
- `divided`: `boolean`; the hairline rule under the row, plus the vertical band that gives the row its height. A divided list has no gap between rows by definition, so the row supplies its own. Expects a list-item wrapper: the trailing rule is dropped from the last `<li>`, not from the card itself.
- `interactive`: `boolean`; hover/press/focus affordance for a row that is itself a link.
- `asChild`: `boolean`; render via Radix Slot, e.g. as an `<li>` or `<a>`.

### JobCardMetaItem

One meta fact. Forwards native `<span>` props.

- `icon`: `ReactNode`; the leading 20px glyph. A node rather than a component type so one item can pass a Phosphor icon and the next a `JobCardFlag`.

### JobCardFlag

A country flag cropped into a ringed circle, sized to the meta glyph and marked decorative (the country is already spelled out beside it).

- `country`: `string`; an ISO 3166-1 alpha-2 code, matching the `iso2` field of the shared countries dataset.

### JobCardContent, JobCardTitle, JobCardDescription, JobCardMeta, JobCardAction

The block parts: the text column, the role title (a `<div>` by default, with `asChild` for a real heading), the muted summary, the meta tier, and the trailing action slot. Each forwards its native element props, and each is optional.

## FAQ

### When should I use JobCard instead of List or Card?

Reach for JobCard when the row is an open role. List is the compact settings or member row: text-sm, a truncating title, and meta pinned right on the same line. JobCard is a marketing-scale block whose meta is a third tier under the summary and is allowed to wrap. Card is the generic surface with no opinion about its contents.

### How do I hide the summary or the apply button?

Omit the part. Every piece of the anatomy is a separate component you compose, so a role with no summary simply leaves out JobCardDescription and a board with no button leaves out JobCardAction. There is no showX prop.

### Why does the card variant use a ring instead of a border, and no fill?

A 1px border sits outside the padding box, so it enlarges the element and breaks the concentric relationship between the outer corner and the radius of anything nested inside it. An inset ring paints in the same place without changing the box. It carries no background either: a grid of filled panels reads as chrome competing with the roles, and on the dark themes the card token is light enough to turn every row into a grey slab. Because it introduces no new ground, it deliberately does not redeclare --surface, so a nested Badge or Button keeps resolving the page's.

### How do the inline layout columns line up across rows?

The inline layout pins the title to a fixed first column and turns the meta tier into equal-width auto columns from md up. Every row uses the identical template inside the same container width, so the columns align down the whole board without needing a grid on the list itself, and each card stays a self-contained unit. The title has to be fixed rather than flexible: two flexible siblings split the row in half whatever is in them, which hands half the width to a two-word role and squeezes the meta until it truncates.

### Why does a divided row need an <li> around it?

Because the trailing rule keys off the list item. List and Activity Feed render their own <li> and hang the divider on it, so they can simply hide the rule on the last child. Job Card does not render the <li> — it also goes into card grids, scroll rails and standalone previews — so the list that owns it supplies one, and inside that wrapper the card is always its own parent's last child. Hiding on the card's own :last-child would therefore blank the hairline on every row of the board rather than only the final one. Compose a divided board as a real list: <ul className="flex flex-col"> with one <li> per role and no gap, since the hairline is the separation.

### Why does a divided row carry padding?

Because nothing else can. A list of divided rows stacks them with no gap — the hairline is the separation — so the row's own vertical padding is the only thing giving it height. Without it a 40px Apply button fills the row edge to edge and lands flush on the hairline above and below. An interactive row restates a slightly tighter band, so its hover panel sits closer to the text.

### Why is there no press scale on an interactive row?

A row sits flush to the edges of the surface holding it. Shrinking it on press pulls the fill away from those edges and the row starts reading as a floating tile. The press is a deepening fill instead: hover lands on a half-strength wash, active on the full one.

### Where do the flags come from?

JobCardFlag indexes country-flag-icons by ISO 3166-1 alpha-2 code, the same way CountrySelect and PhoneInput do, so the codes match the iso2 field of the shared countries dataset. It renders nothing for an unknown code rather than throwing.

---

<!-- https://www.koalaui.com/docs/components/navbar.md -->

# Navbar

A composable top navigation bar for marketing, product and ecommerce shells. Layout is composition, not configuration: a NavbarSpacer pushes groups apart. Collapses to a hamburger disclosure below md.

```tsx
<Navbar>
  <NavbarInner>
    <NavbarBrand href="/"><BrandMark /></NavbarBrand>
    <NavbarNav>
      <NavbarLink href="#">Home</NavbarLink>
      <NavbarLink href="#" active>Features</NavbarLink>
      <NavbarLink href="#">Pricing</NavbarLink>
      <DropdownMenu>
        <DropdownMenuTrigger asChild>
          <NavbarLink asChild>
            <button type="button">Company<CaretDown /></button>
          </NavbarLink>
        </DropdownMenuTrigger>
        <DropdownMenuContent align="start">…</DropdownMenuContent>
      </DropdownMenu>
    </NavbarNav>
    <NavbarSpacer />
    <NavbarActions>
      <Button size="sm" variant="outline">Sign in</Button>
      <Button size="sm">Sign up</Button>
    </NavbarActions>
    <NavbarMobileToggle />
  </NavbarInner>
  <NavbarMobileMenu>
    <NavbarMobileLink href="#">Home</NavbarMobileLink>
    …
  </NavbarMobileMenu>
</Navbar>
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add navbar
```

Manual: run `npm install radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/navbar/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

```tsx title="usage.tsx"
import { Button } from "@/components/ui/button"
import {
  Navbar, NavbarInner, NavbarBrand, NavbarNav, NavbarLink, NavbarSpacer, NavbarActions,
  NavbarMobileToggle, NavbarMobileMenu, NavbarMobileLink,
} from "@/components/ui/navbar"

export function Example() {
  return (
    <Navbar>
      <NavbarInner>
        <NavbarBrand href="/">Koala UI</NavbarBrand>
        <NavbarNav>
          <NavbarLink href="/">Home</NavbarLink>
          <NavbarLink href="/features" active>Features</NavbarLink>
          <NavbarLink href="/pricing">Pricing</NavbarLink>
        </NavbarNav>
        <NavbarSpacer />
        <NavbarActions>
          <Button size="sm" variant="outline">Sign in</Button>
          <Button size="sm">Sign up</Button>
        </NavbarActions>
        <NavbarMobileToggle />
      </NavbarInner>
      <NavbarMobileMenu>
        <NavbarMobileLink href="/">Home</NavbarMobileLink>
        <NavbarMobileLink href="/features">Features</NavbarMobileLink>
        <NavbarMobileLink href="/pricing">Pricing</NavbarMobileLink>
      </NavbarMobileMenu>
    </Navbar>
  )
}
```

## Floating

`variant="floating"` detaches the bar into a rounded card that hovers over the page. Give it top margin and a background to float over.

```tsx
<div className="p-3">
  <Navbar variant="floating">
    <NavbarInner>…</NavbarInner>
  </Navbar>
</div>
```

```tsx
{/* Links right, inside the card */}
<Navbar variant="floating">
  <NavbarInner>
    <NavbarBrand href="/"><BrandMark /></NavbarBrand>
    <NavbarSpacer />
    <NavbarNav>…</NavbarNav>
    <NavbarActions>…</NavbarActions>
  </NavbarInner>
</Navbar>
```

```tsx
{/* Logo on the card's centreline. The brand leads in the DOM so a phone still
    reads brand-left, then md:order-2 moves it to the middle column. */}
<Navbar variant="floating">
  <NavbarInner className="md:grid md:grid-cols-[1fr_auto_1fr]">
    <NavbarBrand href="/" className="mr-0 md:order-2 md:justify-self-center"><BrandMark /></NavbarBrand>
    <NavbarSpacer className="md:hidden" />
    <NavbarNav className="md:order-1">…</NavbarNav>
    <NavbarActions className="md:order-3 md:justify-self-end">…</NavbarActions>
    <NavbarMobileToggle className="md:order-4" />
  </NavbarInner>
</Navbar>
```

```tsx
{/* With a search field */}
<Navbar variant="floating">
  <NavbarInner>
    <NavbarBrand href="/"><BrandMark /></NavbarBrand>
    <NavbarNav>…</NavbarNav>
    <NavbarSpacer />
    <NavbarSearch placeholder="Search anything" className="w-56">
      <InputSuffix><Kbd size="sm">⌘K</Kbd></InputSuffix>
    </NavbarSearch>
    <NavbarActions><Button size="sm">Sign up</Button></NavbarActions>
  </NavbarInner>
</Navbar>
```

## Floating island

Release the width cap with `w-fit max-w-none` and the floating card stops stretching: it shrinks to its content and the recipe's own `mx-auto` centers it, so the whole bar becomes a compact pill hovering over the page. Best with a short link set and one CTA.

```tsx
<Navbar variant="floating">
  <NavbarInner className="w-fit max-w-none">
    <NavbarBrand href="/"><BrandMark /></NavbarBrand>
    <NavbarNav>…</NavbarNav>
    <NavbarActions className="ml-2"><Button size="sm">Join us</Button></NavbarActions>
  </NavbarInner>
</Navbar>
```

## Underline links

`linkStyle` changes what a link *is*, which is the one thing composition cannot express. The default, `"pill"`, makes each link a ghost chip floating in the bar: `bg-accent` on hover in the light themes, a faint `foreground/8` tint in the dark ones, where the accent would read as a heavy grey block. `"underline"` makes it a tab: the box fills the bar's full height so its indicator, a square 3px foreground stroke spanning the whole box, welds to the bar's bottom rule (ink, not brand: at full width it is already the loudest mark in the row). Hover previews that indicator in `border` instead of painting a full-height chip.

```tsx
<Navbar linkStyle="underline">
  <NavbarInner>
    <NavbarBrand href="/"><BrandMark /></NavbarBrand>
    <NavbarNav className="ml-2">
      <NavbarLink href="#">Home</NavbarLink>
      <NavbarLink href="#" active>Company</NavbarLink>
    </NavbarNav>
    <NavbarSpacer />
    <NavbarActions>…</NavbarActions>
  </NavbarInner>
</Navbar>
```

```tsx
{/* Tabs inside a floating card: the indicator welds to the card's bottom edge */}
<Navbar variant="floating" linkStyle="underline">
  <NavbarInner>…</NavbarInner>
</Navbar>
```

## Text links

`"text"` makes each link a plain word: no chip, no stroke. Links rest in `muted-foreground` and light up to full ink on hover and while their menu is open, so the only thing that moves is the label's color. The current page is simply the link that stays lit. There is no press scale either, since a label that shrinks under the pointer reads as a glitch, and a page that is not live yet dims one step below its siblings.

```tsx
<Navbar linkStyle="text">
  <NavbarInner>
    <NavbarBrand href="/"><BrandMark /></NavbarBrand>
    <NavbarNav className="ml-2">
      <NavbarLink href="#">Home</NavbarLink>
      <NavbarLink href="#" active>Features</NavbarLink>
      <NavbarLink href="#">Pricing</NavbarLink>
    </NavbarNav>
    <NavbarSpacer />
    <NavbarActions>…</NavbarActions>
  </NavbarInner>
</Navbar>
```

```tsx
{/* Text links on the floating card's centreline */}
<Navbar variant="floating" linkStyle="text">
  <NavbarInner className="md:grid md:grid-cols-[1fr_auto_1fr]">
    <NavbarBrand href="/"><BrandMark /></NavbarBrand>
    <NavbarSpacer className="md:hidden" />
    <NavbarNav className="md:justify-self-center">…</NavbarNav>
    <NavbarActions className="md:justify-self-end">…</NavbarActions>
    <NavbarMobileToggle />
  </NavbarInner>
</Navbar>
```

## Many links

A marketing bar that carries six links and two actions runs out of row long before the `md` breakpoint where the hamburger normally takes over, so on a tablet it would overflow or wrap. `collapseAt="lg"` moves the handover to 1024px: the inline nav, the toggle and the mobile panel switch together. A page that is not live yet renders as a `<span aria-disabled>` through `asChild`: muted, inert to the pointer, and paired with a small `Badge`.

```tsx
<Navbar linkStyle="underline" collapseAt="lg">
  <NavbarInner>
    <NavbarBrand href="/"><BrandMark /></NavbarBrand>
    <NavbarSpacer />
    <NavbarNav>
      {/* …five links and menus */}
      <NavbarLink asChild>
        <span aria-disabled="true">
          University
          <Badge variant="orange" size="sm">Soon</Badge>
        </span>
      </NavbarLink>
    </NavbarNav>
    <NavbarSpacer />
    <NavbarActions>…</NavbarActions>
    <NavbarMobileToggle />
  </NavbarInner>
  <NavbarMobileMenu>…</NavbarMobileMenu>
</Navbar>
```

## Elevate on scroll

`elevateOnScroll` rests the bar flat, borderless and shadowless, flush with the content, then brings its border and shadow in together the moment the page scrolls under it. Pair it with `sticky top-0`. The bar listens to the nearest scroll container, so it works on a page or inside a panel; scroll the preview to see it engage.

```tsx
<Navbar variant="floating" elevateOnScroll className="sticky top-0 z-50 pt-3">
  <NavbarInner>…</NavbarInner>
</Navbar>
```

## Alignment

There is no alignment prop. A `NavbarSpacer` pushes the groups on either side of it apart, which pins the nav to the right. To truly center it, swap the bar for a three-column grid: spacers would only center the nav *between* the brand and the actions, leaving it off the bar's centreline by half the difference in their widths.

```tsx
{/* Centered: a 3-column grid, so the nav sits on the bar's centreline.
    Gated behind md, where the inline nav replaces the hamburger. */}
<NavbarInner className="md:grid md:grid-cols-[1fr_auto_1fr]">
  <NavbarBrand href="/"><BrandMark /></NavbarBrand>
  <NavbarNav className="md:justify-self-center">…</NavbarNav>
  <NavbarActions className="md:justify-self-end">…</NavbarActions>
</NavbarInner>
```

```tsx
{/* Right: a single spacer after the brand */}
<NavbarInner>
  <NavbarBrand href="/"><BrandMark /></NavbarBrand>
  <NavbarSpacer />
  <NavbarNav>…</NavbarNav>
  <NavbarActions>…</NavbarActions>
</NavbarInner>
```

## Dropdown links

A link that opens a menu is a `NavbarLink` wrapped in the standard [DropdownMenu](https://www.koalaui.com/docs/components/dropdown-menu.md). The caret flips when its menu opens.

```tsx
<DropdownMenu>
  <DropdownMenuTrigger asChild>
    <NavbarLink asChild>
      <button type="button">Company<CaretDown /></button>
    </NavbarLink>
  </DropdownMenuTrigger>
  <DropdownMenuContent align="start">
    <DropdownMenuItem>About us</DropdownMenuItem>
    <DropdownMenuItem>Careers</DropdownMenuItem>
  </DropdownMenuContent>
</DropdownMenu>
```

## Open on hover, fluid between links

Swap the click-triggered `DropdownMenu` for a [NavigationMenu](https://www.koalaui.com/docs/components/navigation-menu.md) when the bar carries more than one dropdown link. It opens on hover, and every trigger shares one panel: moving from “Product” to “Resources” resizes it instead of swapping popovers.

```tsx
<NavbarInner>
  <NavbarBrand href="/"><BrandMark /></NavbarBrand>
  <div className="ml-2 hidden items-center gap-0.5 lg:flex">
    <NavbarLink href="/" active>Home</NavbarLink>
    <NavigationMenu>
      <NavigationMenuList>
        <NavigationMenuItem>
          <NavigationMenuTrigger>Product</NavigationMenuTrigger>
          <NavigationMenuContent>
            <div className="flex w-64 flex-col">
              <NavigationMenuLink href="/analytics">
                <ChartBar />
                <NavigationMenuLinkText>
                  Analytics
                  <NavigationMenuLinkDescription>Traffic and conversion</NavigationMenuLinkDescription>
                </NavigationMenuLinkText>
              </NavigationMenuLink>
              …
            </div>
          </NavigationMenuContent>
        </NavigationMenuItem>
        <NavigationMenuItem>
          <NavigationMenuTrigger>Resources</NavigationMenuTrigger>
          <NavigationMenuContent>…</NavigationMenuContent>
        </NavigationMenuItem>
        <NavigationMenuIndicator />
      </NavigationMenuList>
    </NavigationMenu>
  </div>
  <NavbarSpacer />
  <NavbarActions>…</NavbarActions>
  <NavbarMobileToggle className="md:inline-flex lg:hidden" />
</NavbarInner>
```

## Search

`NavbarSearch` is the DS [Input](https://www.koalaui.com/docs/components/input.md) with a leading magnifier. Set a width like `w-64` for a normal field, or `flex-1` to fill the center of the bar. Add `collapsible` and it rests as one of the bar's icon chips instead, growing into the same field on click (an [ExpandableSearch](https://www.koalaui.com/docs/components/expandable-search.md)): the choice for a bar whose links need the room until someone searches.

```tsx
<NavbarInner>
  <NavbarBrand href="/"><BrandMark /></NavbarBrand>
  <NavbarNav>…</NavbarNav>
  <NavbarSpacer />
  <NavbarSearch placeholder="Search anything" className="w-64" />
  <NavbarActions><Button size="sm">Sign up</Button></NavbarActions>
</NavbarInner>
```

```tsx
{/* Collapsible: an icon chip at rest, the field on click. className sets the open width. */}
<NavbarInner>
  <NavbarBrand href="/"><BrandMark /></NavbarBrand>
  <NavbarNav className="ml-2">…</NavbarNav>
  <NavbarSpacer />
  <NavbarSearch collapsible placeholder="Search docs" className="w-56" />
  <NavbarActions>…</NavbarActions>
</NavbarInner>
```

```tsx
{/* Input in the middle: no links at all. Brand left, search on the centreline,
    CTAs right, for a product whose navigation IS the search. */}
<NavbarInner className="md:grid md:grid-cols-[1fr_auto_1fr]">
  <NavbarBrand href="/"><BrandMark /></NavbarBrand>
  <NavbarSpacer className="md:hidden" />
  <NavbarSearch placeholder="Search for anything" className="w-72 md:justify-self-center">
    <InputSuffix><Kbd size="sm">⌘K</Kbd></InputSuffix>
  </NavbarSearch>
  <NavbarActions className="md:justify-self-end">…</NavbarActions>
</NavbarInner>
```

## Product app shell

A compact bar with a global search and an account cluster. Pass `bg-muted border-transparent` to `NavbarSearch` for the pill look, and drop an [Avatar](https://www.koalaui.com/docs/components/avatar.md) into `NavbarActions`. To make it the header of a whole app, put it in a [`LayoutTopbar`](https://www.koalaui.com/docs/components/layout.md#top-navigation): it docks onto the shell and spans the window.

```tsx
<Navbar density="compact">
  <NavbarInner>
    <NavbarBrand href="/"><BrandMark /></NavbarBrand>
    <NavbarNav className="ml-2">…</NavbarNav>
    <NavbarSearch className="ml-auto w-64 bg-muted border-transparent" />
    <NavbarActions>
      <Button size="sm" variant="ghost" iconOnly aria-label="Help"><Question /></Button>
      <Button size="sm" variant="ghost" iconOnly aria-label="Notifications"><Bell /></Button>
      <Avatar size="sm">
        <AvatarImage src="https://i.pravatar.cc/160?img=15" alt="Account" />
        <AvatarFallback>AS</AvatarFallback>
      </Avatar>
    </NavbarActions>
  </NavbarInner>
</Navbar>
```

```tsx
{/* Multi-action: utility icons, an avatar, and one primary CTA */}
<NavbarActions>
  <Button size="sm" variant="ghost" iconOnly aria-label="Help"><Question /></Button>
  <Button size="sm" variant="ghost" iconOnly aria-label="Notifications"><Bell /></Button>
  <Button size="sm" variant="ghost" iconOnly aria-label="Search"><MagnifyingGlass /></Button>
  <Avatar size="sm">…</Avatar>
  <Button size="sm">Sign up</Button>
</NavbarActions>
```

## Toolbar

Drop the brand and the links and the same parts become a toolbar: the view's controls on the left, its actions on the right. This is the bar that sits under an app shell's real header. Fold navigation back in and it takes the three-column grid, so controls, tabs, and account each hold their own third.

```tsx
<Navbar density="compact">
  <NavbarInner>
    <NavbarSearch placeholder="Search for anything" className="max-w-64">
      <InputSuffix><Kbd size="sm">⌘K</Kbd></InputSuffix>
    </NavbarSearch>
    <Button size="sm" variant="outline"><FunnelSimple />Filter</Button>
    <Button size="sm" variant="outline"><ArrowsDownUp />Sort</Button>
    <NavbarSpacer />
    <NavbarActions>…</NavbarActions>
  </NavbarInner>
</Navbar>
```

```tsx
{/* Controls left, tabs centered, account right */}
<Navbar density="compact" linkStyle="underline">
  <NavbarInner className="md:grid md:grid-cols-[1fr_auto_1fr]">
    <div className="flex items-center gap-2">
      <NavbarSearch className="max-w-56">…</NavbarSearch>
      <Button size="sm" variant="ghost" iconOnly aria-label="Filter"><FunnelSimple /></Button>
      <Button size="sm" variant="ghost" iconOnly aria-label="Sort"><ArrowsDownUp /></Button>
    </div>
    <NavbarSpacer className="md:hidden" />
    <NavbarNav className="md:justify-self-center">…</NavbarNav>
    <NavbarActions className="md:justify-self-end">…</NavbarActions>
  </NavbarInner>
</Navbar>
```

## Logo in the middle

A 3-column grid on `NavbarInner` centers the brand independently of the side groups: links left, logo centered, actions right.

```tsx
<NavbarInner className="grid grid-cols-[1fr_auto_1fr]">
  <NavbarNav>…</NavbarNav>
  <NavbarBrand href="/" className="justify-self-center"><BrandMark /></NavbarBrand>
  <NavbarActions className="justify-self-end">…</NavbarActions>
</NavbarInner>
```

## Multiple actions

Stack two quiet outline actions and a solid primary in `NavbarActions` for a stronger conversion path. Give the secondaries a `hidden sm:inline-flex` so they shed themselves as the bar narrows and the primary always survives.

```tsx
<NavbarActions>
  <Button size="sm" variant="outline" className="hidden sm:inline-flex">
    <UploadSimple />Sign up
  </Button>
  <Button size="sm" variant="outline" className="hidden md:inline-flex">
    <ArrowsLeftRight />Transfer
  </Button>
  <Button size="sm"><Plus />Register</Button>
</NavbarActions>
```

## Badge beside the brand

Group a [Badge](https://www.koalaui.com/docs/components/badge.md) next to `NavbarBrand` to flag a beta, plan, or environment.

```tsx
<div className="flex items-center gap-2">
  <NavbarBrand href="/"><BrandMark /></NavbarBrand>
  <Badge variant="secondary" size="sm" pill>Beta</Badge>
</div>
```

## Ecommerce

The same parts build a storefront header, with two conventions of its own: the links go uppercase and wide-tracked, and the marketing CTAs give way to the search, account, and cart trio. Unlike a marketing CTA the trio stays in the bar at every width, because the cart is the one control a shopper must never have to go looking for. Both are composition, so no variant is involved: the brand can lead, or the catalogue can, with the mark on the centreline.

```tsx
<NavbarLink href="#" className="text-xs font-semibold uppercase tracking-[0.14em]">
  New arrivals
</NavbarLink>
…
<NavbarActions>
  <Button size="sm" variant="ghost" iconOnly aria-label="Search"><MagnifyingGlass /></Button>
  <Button size="sm" variant="ghost" iconOnly aria-label="Account"><User /></Button>
  <Button size="sm" variant="ghost" iconOnly aria-label="Cart"><ShoppingCart /></Button>
</NavbarActions>
```

```tsx
{/* Catalogue on the centreline */}
<NavbarInner className="md:grid md:grid-cols-[1fr_auto_1fr]">
  <NavbarBrand href="/"><BrandMark /></NavbarBrand>
  <NavbarSpacer className="md:hidden" />
  <NavbarNav className="md:justify-self-center">…</NavbarNav>
  <NavbarActions className="md:justify-self-end">…</NavbarActions>
</NavbarInner>
```

```tsx
{/* Editorial storefront: links lead, the mark holds the centreline.
    Gated on the bar's own width (a container query), not the viewport: five uppercase
    labels plus a centred mark need the bar itself to have the room, which a viewport
    breakpoint gets wrong the moment the bar is narrower than the window. */}
<Navbar className="@container/navbar">
  <NavbarInner className="@7xl/navbar:grid @7xl/navbar:grid-cols-[minmax(0,1fr)_auto_minmax(0,1fr)]">
    <NavbarBrand href="/" className="mr-0 @7xl/navbar:order-2 @7xl/navbar:justify-self-center"><BrandMark /></NavbarBrand>
    <NavbarSpacer className="@7xl/navbar:hidden" />
    <NavbarNav className="md:hidden @7xl/navbar:order-1 @7xl/navbar:flex">…</NavbarNav>
    <NavbarActions className="@7xl/navbar:order-3 @7xl/navbar:justify-self-end">…</NavbarActions>
    <NavbarMobileToggle className="md:inline-flex @7xl/navbar:order-4 @7xl/navbar:hidden" />
  </NavbarInner>
</Navbar>
```

## Density

`density` tightens the bar height and gutters for application shells. Set it per navbar or for a whole subtree with `DensityProvider`. See [Density](https://www.koalaui.com/docs/foundations/density.md).

```tsx
<Navbar density="compact">
  <NavbarInner>…</NavbarInner>
</Navbar>
```

## API reference

### Navbar

The root `<header>`. Owns the mobile disclosure state and provides the styling context to every part. Forwards all `<header>` props.

- `variant`: `"full"` (default) or `"floating"`.
- `linkStyle`: `"pill"` (default), `"underline"` or `"text"`. Ghost chips floating in the bar, full-height tabs whose ink indicator welds to the bar's bottom rule, or plain muted words that light up to full ink on hover.
- `density`: `"comfortable"` (default) or `"compact"`. Falls back to the nearest `DensityProvider`.
- `collapseAt`: `"md"` (default) or `"lg"`. Where the inline links hand over to the hamburger. A bar carrying six links and two actions runs out of row well before 768px, so it collapses at 1024px instead of overflowing; the nav, the toggle and the mobile panel all move together.
- `docked`: sit the bar on an app shell's surface instead of painting its own: no fill, no bottom rule, and a full-width row instead of the marketing column. Inherited inside a [`LayoutTopbar`](https://www.koalaui.com/docs/components/layout.md#top-navigation), so you rarely pass it; `docked={false}` keeps a bar's standalone chrome inside a shell.
- `open` / `defaultOpen` / `onOpenChange`: control the mobile menu.

### NavbarInner

The max-width content row. Holds the brand, nav, spacers, actions, and toggle.

### NavbarBrand

The logo lockup; renders an `<a>`. Pass `asChild` to use a framework `<Link>`.

### NavbarNav

The horizontal link list (a labelled `<nav>`); hidden below md.

### NavbarLink

A link in the bar. `active` adds the style's indicator and `aria-current="page"`; `asChild` renders a custom element or a menu trigger. Its shape follows the bar's `linkStyle`: a ghost chip with a soft-capped underline, a full-height tab with a square one, or a plain word that stays lit. A page that is not live yet takes `aria-disabled` (render a `<span>` through `asChild`): the link goes muted and inert to the pointer. Pair it with a small `Badge` ("Soon"). `NavbarMobileLink` takes the same state.

### NavbarSearch

The DS `Input` with a leading magnifier and a default width. Forwards `InputRoot` props (`size`, `hasError`…); `inputProps` reaches the underlying `<input>`. `collapsible` rests it as a 36px icon chip that expands into the field on click (an `ExpandableSearch`); it then takes `open` / `defaultOpen` / `onOpenChange`, and `className` sets the open width.

### NavbarActions · NavbarSpacer

`NavbarActions` is the right-hand cluster; `NavbarSpacer` is a flexible gap that drives alignment.

### NavbarMobileToggle · NavbarMobileMenu · NavbarMobileLink

The hamburger, the disclosed panel (mounts only while open), and its stacked links. All visible only below md.

## FAQ

### How do I align the links left, center, or right? There is no alignment prop.

Alignment is composition, not configuration: drop a `NavbarSpacer` between groups to push them apart. One spacer after the brand pins the nav right. For a truly centered nav, reach for `className="md:grid md:grid-cols-[1fr_auto_1fr]"` on `NavbarInner` instead: spacers only center the nav between its neighbours, so it drifts off the bar's centreline whenever the brand and the actions differ in width.

### What does variant="floating" do?

It detaches the bar into a rounded card that hovers over the page instead of painting a full-bleed bottom rule. Give it top margin and a background to float over. The default is `variant="full"`.

### How do I add a link that opens a dropdown menu?

Wrap a `NavbarLink` in the standard DropdownMenu and render it `asChild` over a `<button>` trigger. The caret flips automatically when the menu opens because the link reads `data-state=open`.

### How does the mobile menu work?

Below md the nav collapses to a hamburger. `Navbar` owns the disclosure state (`open` / `defaultOpen` / `onOpenChange`); add a `NavbarMobileToggle` and a `NavbarMobileMenu` of `NavbarMobileLink` rows, which mount only while open.

### How do I mark the current page on a NavbarLink?

Set `active` on the `NavbarLink`. It lights the label to full ink, adds the style's indicator (a brand underline under `pill`, an ink stroke under `underline`, none under `text`) and sets `aria-current="page"` for assistive tech.

### How do I get links where only the text lights up on hover?

Use `linkStyle="text"`. Links rest in `muted-foreground` and turn full ink on hover, while their menu is open, and for the current page; there is no hover chip, no underline and no press scale. It suits marketing bars that want the row to read as quietly as a line of text.

### When should I use linkStyle="underline"?

When the bar is navigation you keep returning to rather than a marketing header you pass through: product shells, app toolbars, and any bar where the links behave like tabs. It fills each link box to the bar's full height so the active indicator welds to the bottom rule, drops the rounded hover chip (a full-height block reads far too heavy) and previews the indicator on hover instead. `"pill"` stays the default and is the right call for marketing bars.

### Why doesn't an underline link scale when I press it?

It is the one place the DS backs off scale-on-press. The indicator is welded to the bar's bottom edge, and scaling the box would visibly peel it away from that edge, so the tap dims the label instead. Pill links keep the usual `active:scale-[0.96]`.

### How do I make the floating bar a compact island instead of a full-width card?

Put `w-fit max-w-none` on `NavbarInner`. That releases the 1440px cap and stops the card stretching, so it shrinks to its content while the recipe's own `mx-auto` keeps it centered. Pair it with a short link set and a single CTA.

### What is NavbarSearch and how do I size it?

`NavbarSearch` is the DS Input with a leading magnifier. Give it a width like `w-64` for a normal field or `flex-1` to fill the center of the bar; it forwards `InputRoot` props, and `inputProps` reaches the underlying `<input>`.

### Can the search start as an icon and expand on click?

Yes: `<NavbarSearch collapsible />`. It rests as a 36px `rounded-md` chip, the same as the hamburger, and grows into the field on click; `className` sets the open width. Escape clears the query, then closes it, and it stays open on blur while it holds a query. Without `collapsible` it is the always-open field.

---

<!-- https://www.koalaui.com/docs/components/pricing.md -->

# Pricing

A responsive marketing pricing table. Named parts you assemble into plan cards: a name, a big tabular price, a feature checklist and a bottom-pinned call to action. Mark the recommended plan featured.

```tsx
<Pricing>
  <PricingTier>
    <PricingTierHeader>
      <PricingTierName>Starter</PricingTierName>
      <PricingTierDescription>For individuals exploring the system.</PricingTierDescription>
    </PricingTierHeader>
    <PricingPrice>
      <PricingAmount>$0</PricingAmount>
      <PricingPeriod>/month</PricingPeriod>
    </PricingPrice>
    <PricingFeatures>
      <PricingFeature>Up to 5 projects</PricingFeature>
      <PricingFeature>Up to 3 team members</PricingFeature>
      <PricingFeature>Community support</PricingFeature>
      <PricingFeature>1 GB storage</PricingFeature>
      <PricingFeature>Core integrations</PricingFeature>
      <PricingFeature>7-day activity history</PricingFeature>
      <PricingFeature included={false}>Custom domains</PricingFeature>
      <PricingFeature included={false}>Advanced analytics</PricingFeature>
      <PricingFeature included={false}>Audit logs</PricingFeature>
      <PricingFeature included={false}>SSO &amp; SAML</PricingFeature>
    </PricingFeatures>
    <PricingTierAction>
      <Button variant="outline">Get started</Button>
    </PricingTierAction>
  </PricingTier>

  {/* The recommended plan: a brand ring, a Most popular badge, and a primary CTA. */}
  <PricingTier featured>
    <PricingTierHeader>
      <div className="flex flex-wrap items-center gap-2">
        <PricingTierName>Pro</PricingTierName>
        <Badge variant="orange" dot pill>Most popular</Badge>
      </div>
      <PricingTierDescription>For teams shipping in production.</PricingTierDescription>
    </PricingTierHeader>
    <PricingPrice>
      <PricingAmount>$29</PricingAmount>
      <PricingPeriod>/month</PricingPeriod>
    </PricingPrice>
    <PricingFeatures>
      <PricingFeature>Unlimited projects</PricingFeature>
      <PricingFeature>Unlimited team members</PricingFeature>
      <PricingFeature hint="One-hour response time on business days.">Priority support</PricingFeature>
      <PricingFeature hint="Pooled across your whole team, not per seat.">100 GB storage</PricingFeature>
      <PricingFeature>Custom domains</PricingFeature>
      <PricingFeature>Advanced analytics</PricingFeature>
      <PricingFeature>Custom roles &amp; permissions</PricingFeature>
      <PricingFeature hint="10,000 requests per minute, per workspace.">API access</PricingFeature>
      <PricingFeature>Audit logs</PricingFeature>
    </PricingFeatures>
    <PricingTierAction>
      <Button>Start free trial</Button>
    </PricingTierAction>
  </PricingTier>

  <PricingTier>
    <PricingTierHeader>
      <PricingTierName>Enterprise</PricingTierName>
      <PricingTierDescription>For organizations operating at scale.</PricingTierDescription>
    </PricingTierHeader>
    <PricingPrice>
      <PricingAmount>Custom</PricingAmount>
    </PricingPrice>
    <PricingFeatures>
      <PricingFeature>Everything in Pro</PricingFeature>
      <PricingFeature>SSO &amp; SAML</PricingFeature>
      <PricingFeature>SCIM provisioning</PricingFeature>
      <PricingFeature>Dedicated manager</PricingFeature>
      <PricingFeature>Custom contracts &amp; invoicing</PricingFeature>
      <PricingFeature>Onboarding &amp; training</PricingFeature>
      <PricingFeature>Custom data residency</PricingFeature>
      <PricingFeature>99.99% uptime SLA</PricingFeature>
    </PricingFeatures>
    <PricingTierAction>
      <Button variant="outline">Contact sales</Button>
    </PricingTierAction>
  </PricingTier>
</Pricing>
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add pricing
```

Manual: run `npm install radix-ui @phosphor-icons/react tailwind-variants tailwind-merge`, then copy the source into `components/ui/pricing/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

```tsx
import {
  Pricing,
  PricingTier,
  PricingTierHeader,
  PricingTierName,
  PricingTierDescription,
  PricingPrice,
  PricingAmount,
  PricingPeriod,
  PricingFeatures,
  PricingFeature,
  PricingTierAction,
} from "@/components/ui/pricing"
import { Button } from "@/components/ui/button"

<Pricing columns={3}>
  <PricingTier featured>
    <PricingTierHeader>
      <PricingTierName>Pro</PricingTierName>
      <PricingTierDescription>For teams shipping in production.</PricingTierDescription>
    </PricingTierHeader>
    <PricingPrice>
      <PricingAmount>$29</PricingAmount>
      <PricingPeriod>/month</PricingPeriod>
    </PricingPrice>
    <PricingFeatures>
      <PricingFeature>Unlimited projects</PricingFeature>
      <PricingFeature included={false}>SSO &amp; SAML</PricingFeature>
    </PricingFeatures>
    <PricingTierAction>
      <Button>Start free trial</Button>
    </PricingTierAction>
  </PricingTier>
</Pricing>
```

## Card styles

The `tone` prop on `PricingTier` sets the card's surface, and is orthogonal to `featured` (the recommended ring), so the two combine. `default` is the bare card (a transparent fill, so it blends with whatever it sits on, delineated by its border alone); `outline` swaps the hairline for a brand edge; `solid` fills the card with the accent and flips every part to inverse text and glyphs (pair it with a light CTA and a light badge); `muted` sits the card on a soft grey panel; `dashed` draws the bare card on a dashed contour, for an open-ended plan (a custom quote, a service) beside fixed-price tiers. The CTA's `Button` variant stays your choice.

```tsx
<Pricing columns={2}>
  <PricingTier tone="outline">…<Button>Get started</Button>…</PricingTier>

  {/* Solid: inverse parts, plus a light badge + CTA so both hold contrast on the accent. */}
  <PricingTier tone="solid">
    <PricingTierHeader>
      <Badge variant="orange" dot pill className="border-transparent bg-white">
        Most popular
      </Badge>
      …
    </PricingTierHeader>
    …
    <PricingTierAction>
      <Button variant="secondary" tone="onMedia">
        Get started
      </Button>
    </PricingTierAction>
  </PricingTier>

  <PricingTier tone="default">…<Button variant="secondary">Get started</Button>…</PricingTier>
  <PricingTier tone="muted">…</PricingTier>
  <PricingTier tone="dashed">…<Button variant="secondary">Book a call</Button>…</PricingTier>
</Pricing>
```

## Banner

Wrap a tier in `PricingTierBanner` for the banner-behind treatment: the card nests inside a brand panel that peeks as a top `label` and a thin accent edge all around. It composes over any `tone` and, inside a grid, lines up with un-bannered neighbours.

```tsx
<Pricing columns={2}>
  <PricingTier tone="default">…</PricingTier>

  <PricingTierBanner label="Get 40% off">
    <PricingTier tone="outline">…</PricingTier>
  </PricingTierBanner>
</Pricing>
```

## Action position

`actionPosition` sets where the CTA sits. `bottom` (default) pins it to the card foot via `mt-auto`, so CTAs line up across cards no matter how long each list is. `top` lets it sit in flow right under the price, with the checklist below: place `PricingTierAction` accordingly in the markup.

```tsx
{/* Pinned to the foot (default). */}
<PricingTier actionPosition="bottom">
  <PricingPrice>…</PricingPrice>
  <PricingFeatures>…</PricingFeatures>
  <PricingTierAction>…</PricingTierAction>
</PricingTier>

{/* Under the price. Move PricingTierAction up to match. */}
<PricingTier actionPosition="top">
  <PricingPrice>…</PricingPrice>
  <PricingTierAction>…</PricingTierAction>
  <PricingFeatures>…</PricingFeatures>
</PricingTier>
```

## Feature states

Every `PricingFeature` is one of three states. Included rows (the default) get a filled success check. Mark a row `included={false}` for a filled cross and a dimmed label, so a single list reads as have vs. have-not. Add a `hint` to either to append an info glyph whose tooltip carries the caveat or limit, keeping the label terse.

```tsx
<PricingFeatures>
  {/* Included: success check (the default). */}
  <PricingFeature>Unlimited projects</PricingFeature>

  {/* Included, with a hint: a trailing info glyph reveals the detail on hover/focus. */}
  <PricingFeature hint="Pooled across your whole team, not per seat.">
    100 GB storage
  </PricingFeature>

  {/* Not included: muted minus + dimmed label. */}
  <PricingFeature included={false}>SSO &amp; SAML</PricingFeature>

  {/* A hint composes onto a not-included row too. */}
  <PricingFeature
    included={false}
    hint="Available as a paid add-on, or bundled in the Enterprise plan."
  >
    Dedicated manager
  </PricingFeature>
</PricingFeatures>
```

## Features with icons

For a lifetime or all-in bundle, the value isn't a have vs. have-not checklist, it's a long, categorised inventory. Swap the flat `PricingFeatures` for stacked `PricingFeatureGroup` sections: each is a centered `Divider` header (with an optional `icon`) over its own list, and every `PricingFeature` carries a contextual `icon` that reads neutral (the success-check tint stays reserved for the default checklist). The rows sit at full text strength because the icon, not a dimmed weight, marks the line, and any row can wrap a link. Here the CTA floats under the price with `actionPosition="top"` so the inventory reads beneath it.

```tsx
<PricingTier featured actionPosition="top" className="max-w-sm">
  <PricingTierHeader>
    <PricingTierName>Lifetime</PricingTierName>
    <PricingTierDescription>One payment. Every Koala UI asset, yours forever.</PricingTierDescription>
  </PricingTierHeader>
  <PricingPrice>
    <PricingAmount>$199</PricingAmount>
    <PricingPeriod>once · no subscription</PricingPeriod>
  </PricingPrice>
  <PricingTierAction>
    <Button>Buy now &amp; use forever</Button>
  </PricingTierAction>

  {/* Each group is a labelled Divider header over its own icon list. */}
  <PricingFeatureGroup label="What's inside">
    <PricingFeature icon={<FigmaLogo weight="bold" />}>
      {/* A row that links takes the DS Link's in-prose treatment. */}
      <Link href="#" variant="prose">Desktop · Marketing &amp; Product Apps</Link>
    </PricingFeature>
    <PricingFeature icon={<Package weight="bold" />}>Product Application</PricingFeature>
  </PricingFeatureGroup>

  <PricingFeatureGroup label="All features">
    <PricingFeature icon={<UserCircle weight="bold" />}>
      Up to <strong className="font-semibold text-foreground">1</strong> designer
    </PricingFeature>
    <PricingFeature icon={<Cube weight="bold" />}>
      Access to <strong className="font-semibold text-foreground">5000+</strong> Components
    </PricingFeature>
  </PricingFeatureGroup>

  {/* The label takes a leading icon of its own. */}
  <PricingFeatureGroup label="Some gifts included" icon={<Gift weight="bold" />}>
    <PricingFeature icon={<DiscordLogo weight="bold" />}>Exclusive access to Discord Server</PricingFeature>
  </PricingFeatureGroup>
</PricingTier>
```

## Size

`size` sets a tier's type scale. `md` (default) is the compact card for a docs page, a dialog or a three-up row. `lg` is the landing-page scale, where a long categorised inventory is read at body size: 16px rows, a 48px price, a 20px name and a readable group label. The name, price, rows and group labels step together, so the card keeps its hierarchy at either size.

```tsx
<PricingTier size="lg" actionPosition="top">
  <PricingTierHeader>…</PricingTierHeader>
  <PricingPrice>…</PricingPrice>
  <PricingTierAction>…</PricingTierAction>
  <PricingFeatureGroup label="What's inside">…</PricingFeatureGroup>
</PricingTier>
```

## Billing cycle

The component is stateless: you own the prices, so a billing toggle is a few lines of state that swap the `PricingAmount` and `PricingPeriod`. Because the amount is `tabular-nums`, the digits change without the row reflowing. Here a `Tabs` control drives a `columns={2}` table, and a small `RollingAmount` cross-fades and rolls the price so the swap reads as smooth instead of a snap.

```tsx
// Cross-fades + rolls the price on change. Commit on animationend keeps it interruptible
// and avoids set-state-in-an-effect. The incoming value stays in flow, so the baseline the
// PricingPeriod aligns to never moves.
function RollingAmount({ value }) {
  const [shown, setShown] = React.useState(value)
  const rolling = value !== shown

  return (
    <span className="relative inline-block tabular-nums">
      <span
        key={value}
        onAnimationEnd={rolling ? () => setShown(value) : undefined}
        className={rolling ? "animate-in fade-in slide-in-from-bottom-2 duration-base ease-out" : ""}
      >
        {value}
      </span>
      {rolling && (
        <span
          key={shown}
          aria-hidden
          className="absolute inset-0 animate-out fade-out slide-out-to-top-2 fill-mode-forwards duration-base ease-out"
        >
          {shown}
        </span>
      )}
    </span>
  )
}

function PricingBilling() {
  const [cycle, setCycle] = React.useState("monthly")
  const annual = cycle === "annual"
  const period = annual ? "/mo, billed yearly" : "/month"

  return (
    <div className="flex flex-col items-center gap-8">
      <Tabs value={cycle} onValueChange={setCycle}>
        <TabsList>
          <TabsTrigger value="monthly">Monthly</TabsTrigger>
          <TabsTrigger value="annual">
            Annual
            <Badge variant="success" dot pill size="sm">Save 20%</Badge>
          </TabsTrigger>
        </TabsList>
      </Tabs>

      <Pricing columns={2} className="max-w-2xl">
        <PricingTier featured>
          <PricingTierHeader>
            <div className="flex flex-wrap items-center gap-2">
              <PricingTierName>Pro</PricingTierName>
              <Badge variant="orange" dot pill>Most popular</Badge>
            </div>
            <PricingTierDescription>For teams shipping in production.</PricingTierDescription>
          </PricingTierHeader>
          <PricingPrice>
            <PricingAmount>
              <RollingAmount value={annual ? "$23" : "$29"} />
            </PricingAmount>
            <PricingPeriod>{period}</PricingPeriod>
          </PricingPrice>
          <PricingFeatures>
            <PricingFeature>Unlimited projects</PricingFeature>
            <PricingFeature>Unlimited team members</PricingFeature>
            <PricingFeature>Priority support</PricingFeature>
            <PricingFeature>100 GB storage</PricingFeature>
            <PricingFeature>Custom domains</PricingFeature>
            <PricingFeature>Advanced analytics</PricingFeature>
          </PricingFeatures>
          <PricingTierAction>
            <Button>Start free trial</Button>
          </PricingTierAction>
        </PricingTier>

        <PricingTier>
          <PricingTierHeader>
            <PricingTierName>Business</PricingTierName>
            <PricingTierDescription>For scaling organizations.</PricingTierDescription>
          </PricingTierHeader>
          <PricingPrice>
            <PricingAmount>
              <RollingAmount value={annual ? "$47" : "$59"} />
            </PricingAmount>
            <PricingPeriod>{period}</PricingPeriod>
          </PricingPrice>
          <PricingFeatures>
            <PricingFeature>Everything in Pro</PricingFeature>
            <PricingFeature>SSO &amp; SAML</PricingFeature>
            <PricingFeature>Dedicated manager</PricingFeature>
            <PricingFeature>Audit logs</PricingFeature>
            <PricingFeature>99.9% uptime SLA</PricingFeature>
            <PricingFeature>Custom contracts</PricingFeature>
          </PricingFeatures>
          <PricingTierAction>
            <Button variant="outline">Contact sales</Button>
          </PricingTierAction>
        </PricingTier>
      </Pricing>
    </div>
  )
}
```

## Build your plan

Because the component is stateless, the price is just a number you own, so you can drive it from anything, including a set of add-on checkboxes. Tick a box and the total *counts up* to the new figure instead of snapping: a small `useCountUp` hook tweens it on `requestAnimationFrame` (interruptible, and it collapses to an instant settle under `prefers-reduced-motion`). Each add-on is a full-row `label` so the whole row is the hit target; the selected row keeps a transparent background, with the brand-coloured price keying off the checkbox's `data-state` via `group-has`, so there's no extra state to thread.

```tsx
// Counts toward `target` on every change. setState fires only inside the rAF tick (never
// synchronously in the effect), the tween is interruptible, and it settles instantly under
// prefers-reduced-motion. Easing is easeOutCubic, decelerating into the final value.
function useCountUp(target) {
  const [value, setValue] = React.useState(target)
  const valueRef = React.useRef(target)
  const frameRef = React.useRef(null)

  React.useEffect(() => {
    const from = valueRef.current
    if (from === target) return
    const reduce = window.matchMedia?.("(prefers-reduced-motion: reduce)").matches
    const span = reduce ? 0 : 300
    const start = performance.now()

    function tick(now) {
      const t = span === 0 ? 1 : Math.min(1, (now - start) / span)
      const next = from + (target - from) * (1 - Math.pow(1 - t, 3))
      valueRef.current = next
      setValue(next)
      if (t < 1) frameRef.current = requestAnimationFrame(tick)
    }
    frameRef.current = requestAnimationFrame(tick)
    return () => cancelAnimationFrame(frameRef.current)
  }, [target])

  return value
}

function ConfigurablePlan() {
  const [selected, setSelected] = React.useState({})
  const total = ADDONS.reduce((sum, a) => sum + (selected[a.id] ? a.price : 0), 19)
  const shown = useCountUp(total)

  return (
    <PricingTier featured className="mx-auto w-full max-w-md">
      <PricingTierHeader>
        <PricingTierName>Build your plan</PricingTierName>
        <PricingTierDescription>Start with the essentials and add only what you need.</PricingTierDescription>
      </PricingTierHeader>

      <PricingPrice>
        {/* tabular-nums keeps the digits width-stable while they count */}
        <PricingAmount>${Math.round(shown)}</PricingAmount>
        <PricingPeriod>/month</PricingPeriod>
      </PricingPrice>

      <div className="border-t border-border pt-5">
        <p className="px-2 text-xs font-medium uppercase tracking-wide text-muted-foreground">Add-ons</p>
        <div className="-mx-2 mt-1 flex flex-col">
          {ADDONS.map((addon) => (
            <label
              key={addon.id}
              htmlFor={addon.id}
              className="group flex cursor-pointer items-center gap-3 rounded-lg px-2 py-2.5 transition-colors duration-fast ease-out hover:bg-muted/60"
            >
              <Checkbox
                id={addon.id}
                checked={!!selected[addon.id]}
                onCheckedChange={(checked) =>
                  setSelected((prev) => ({ ...prev, [addon.id]: checked === true }))
                }
              />
              <span className="min-w-0 flex-1">
                <span className="block text-sm font-medium text-foreground">{addon.label}</span>
                <span className="block text-xs text-muted-foreground">{addon.description}</span>
              </span>
              <span className="shrink-0 text-sm font-medium tabular-nums text-muted-foreground transition-colors duration-fast ease-out group-has-[[data-state=checked]]:text-brand">
                +${addon.price}
              </span>
            </label>
          ))}
        </div>
      </div>

      <PricingTierAction>
        <Button>Get started</Button>
      </PricingTierAction>
    </PricingTier>
  )
}
```

## API reference

### Pricing

The grid container. `columns` is `2`, `3` (default), or `4` and sets how many tiers sit in a row at the `lg` breakpoint; below that the grid collapses to two columns, then one. Forwards native `<div>` props and `className`.

### PricingTier

One plan card. `tone` is `default` (transparent fill), `outline` (brand edge), `solid` (accent fill, inverse parts), or `muted` (grey panel). `actionPosition` is `bottom` (default) or `top`. `size` is `md` (default) or `lg`, the landing-page type scale. Pass `featured` to anchor the recommended plan with a brand ring and elevated shadow (it also sets `data-featured`); it is orthogonal to `tone`. Pass `asChild` to render the whole card as a link.

### PricingTierHeader · PricingTierName · PricingTierDescription

The header block, the balanced `<h3>` plan name, and the muted `<p>` description. Drop a `Badge` next to the name (in a flex row) to label a featured plan.

### PricingPrice · PricingAmount · PricingPeriod

The baseline-aligned price row, the large headline `PricingAmount` (`tabular-nums`, so swapping plans never shifts the layout), and the muted `PricingPeriod` suffix (e.g. `/month`). The amount accepts text too, e.g. `Custom`.

### PricingFeatures · PricingFeature

The checklist `<ul>` and its rows. Each `PricingFeature` renders its own leading glyph: a filled success check when `included` (default), or a filled cross with a dimmed label when `included={false}`. Override the glyph with the `icon` prop. Pass `hint` (any node) to append a trailing info glyph whose tooltip carries the detail on hover or focus; `hintLabel` sets its accessible label (defaults to `"More information"`).

### PricingFeatureGroup

A labelled section of features for the "features with icons" layout: a centered `Divider` header (its `label`, plus an optional leading `icon`) over a `<ul>` of `PricingFeature` rows. Stack several inside a tier in place of a single flat `PricingFeatures` when the value is a long, categorised inventory rather than a have/have-not checklist. Rows in a group read at full text strength, and each one's contextual `icon` renders neutral (the success-check tint is reserved for the default checklist).

### PricingTierAction

The CTA wrapper. By default it is bottom-pinned (`mt-auto`), so buttons line up across cards no matter how long each feature list is; set the tier's `actionPosition="top"` and place it under the price to float it instead. Its direct child is stretched to the full card width: drop a Koala `Button` inside (primary for the featured plan, outline for the rest).

### PricingTierBanner

An optional wrapper around a `PricingTier` for the banner-behind treatment: the card nests inside a brand panel that peeks as a top `label` (the only required prop) and a thin accent edge. Composes over any `tone` and stretches to the row height inside a grid.

## FAQ

### How do I highlight the recommended plan?

Pass `featured` to its PricingTier for the brand ring and elevated shadow, drop a `<Badge variant="orange" dot pill>Most popular</Badge>` next to the name in the header, and use a primary Button in its PricingTierAction while the other tiers use `variant="outline"`.

### How do I show included vs not-included features?

Use one PricingFeatures list and mark the unavailable rows with `included={false}`. Included rows get a filled success check; excluded rows get a filled cross and a dimmed label, so the difference is obvious at a glance.

### How do I group features under headings, with an icon per row?

Reach for PricingFeatureGroup instead of a single flat PricingFeatures. Stack one group per section (each takes a `label`, and an optional `icon` beside it); it renders a centered Divider header over its own list. Give each PricingFeature its own `icon` for the contextual glyph. Grouped rows render at full text strength and their custom icons read neutral (the green check tint stays for the default checklist). See the Features with icons example.

### How do I add a monthly/annual toggle?

Pricing is stateless: you own the numbers. Hold the cycle in state (a Tabs control is a good fit) and swap the PricingAmount/PricingPeriod values. The amount is tabular-nums, so the price changes without the row reflowing. See the Billing cycle example.

### What's the difference between tone and featured?

They're independent. `tone` (default/outline/solid/muted) sets the card's surface; `featured` adds the brand ring and elevated shadow that marks the recommended plan. Use `featured` to single out one plan; reach for `tone` (or a PricingTierBanner) when you want a different look across the table. They compose, e.g. `<PricingTier tone="solid" featured>`.

### How do I keep the CTA and badge readable on a solid card?

The solid tone flips the card's own parts to inverse, but the composed Button and Badge are still yours, so tell them which ground they are on. CTA: `<Button variant="secondary" tone="onMedia">` — a primary brand button would disappear into the surface, and `onMedia` also re-points the focus ring, which is otherwise an invisible brand halo on a brand fill. Badge: `<Badge variant="orange" dot pill className="border-transparent bg-white">` (a plain orange dot-badge washes out against the accent).

### How many plans can I put in a row?

Set `columns` to 2, 3 (default), or 4 on Pricing. It always collapses to two columns at `sm` and one column on mobile, so cards stay legible on every screen.

### Can a whole plan card be a link?

Yes. Pass `asChild` to PricingTier and render an `<a>` (or a Next `<Link>`) as its child; the card's styles compose onto the link. Keep the CTA Button as the primary action either way.

---

<!-- https://www.koalaui.com/docs/components/pricing-comparison.md -->

# Pricing Comparison

A feature-by-feature pricing matrix: rows are features, columns are plans, and each cell is a check, a minus or a value. Group rows into sections, highlight the recommended plan, and hang a tooltip off any row.

```tsx
<PricingComparison featured={1}>
  <PricingComparisonHeader label="Compare plans">
    <PricingComparisonPlan name="Starter" price="$0" period="/mo">
      <Button variant="outline" size="sm">Get started</Button>
    </PricingComparisonPlan>
    <PricingComparisonPlan
      name="Pro"
      price="$29"
      period="/mo"
      badge={<Badge variant="orange" dot pill size="sm">Popular</Badge>}
    >
      <Button size="sm">Start free trial</Button>
    </PricingComparisonPlan>
    <PricingComparisonPlan name="Enterprise" price="Custom">
      <Button variant="outline" size="sm">Contact sales</Button>
    </PricingComparisonPlan>
  </PricingComparisonHeader>

  <PricingComparisonSection title="Projects & team">
    <PricingComparisonRow label="Projects">
      <PricingComparisonCell>5</PricingComparisonCell>
      <PricingComparisonCell>Unlimited</PricingComparisonCell>
      <PricingComparisonCell>Unlimited</PricingComparisonCell>
    </PricingComparisonRow>
    <PricingComparisonRow label="Team members" hint="A seat is one active member per month.">
      <PricingComparisonCell>3</PricingComparisonCell>
      <PricingComparisonCell>Unlimited</PricingComparisonCell>
      <PricingComparisonCell>Unlimited</PricingComparisonCell>
    </PricingComparisonRow>
    <PricingComparisonRow label="Storage" hint="Pooled across the whole team, not per seat.">
      <PricingComparisonCell>1 GB</PricingComparisonCell>
      <PricingComparisonCell>100 GB</PricingComparisonCell>
      <PricingComparisonCell>1 TB</PricingComparisonCell>
    </PricingComparisonRow>
  </PricingComparisonSection>

  <PricingComparisonSection title="Support & security">
    <PricingComparisonRow label="Community support">
      <PricingComparisonCell included />
      <PricingComparisonCell included />
      <PricingComparisonCell included />
    </PricingComparisonRow>
    <PricingComparisonRow label="Priority support" hint="One-hour response on business days.">
      <PricingComparisonCell included={false} />
      <PricingComparisonCell included />
      <PricingComparisonCell included />
    </PricingComparisonRow>
    <PricingComparisonRow label="SSO & SAML">
      <PricingComparisonCell included={false} />
      <PricingComparisonCell included={false} />
      <PricingComparisonCell included />
    </PricingComparisonRow>
    <PricingComparisonRow label="Dedicated manager">
      <PricingComparisonCell included={false} />
      <PricingComparisonCell included={false} />
      <PricingComparisonCell included />
    </PricingComparisonRow>
  </PricingComparisonSection>
</PricingComparison>
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add pricing-comparison
```

Manual: run `npm install @phosphor-icons/react tailwind-variants tailwind-merge`, then copy the source into `components/ui/pricing-comparison/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

```tsx
import {
  PricingComparison,
  PricingComparisonHeader,
  PricingComparisonPlan,
  PricingComparisonSection,
  PricingComparisonRow,
  PricingComparisonCell,
} from "@/components/ui/pricing-comparison"
import { Button } from "@/components/ui/button"

// `featured` is the 0-based index of the highlighted plan column.
<PricingComparison featured={1}>
  <PricingComparisonHeader label="Compare plans">
    <PricingComparisonPlan name="Starter" price="$0" period="/mo">
      <Button variant="outline" size="sm">Get started</Button>
    </PricingComparisonPlan>
    <PricingComparisonPlan name="Pro" price="$29" period="/mo" badge={<Badge variant="orange" dot pill size="sm">Popular</Badge>}>
      <Button size="sm">Start free trial</Button>
    </PricingComparisonPlan>
  </PricingComparisonHeader>

  <PricingComparisonSection title="Projects & team">
    <PricingComparisonRow label="Projects">
      <PricingComparisonCell>5</PricingComparisonCell>
      <PricingComparisonCell>Unlimited</PricingComparisonCell>
    </PricingComparisonRow>
    <PricingComparisonRow label="Priority support" hint="One-hour response on business days.">
      <PricingComparisonCell included={false} />
      <PricingComparisonCell included />
    </PricingComparisonRow>
  </PricingComparisonSection>
</PricingComparison>
```

## Cell states

A `PricingComparisonCell` is one of three things. Pass a value as children for a literal like `100 GB` or `Unlimited` (rendered `tabular-nums` so columns align). With no children it draws a success check, or a muted minus when `included={false}`. Every glyph cell also carries an SR-only "Included" / "Not included" label.

```tsx
<PricingComparison>
  <PricingComparisonHeader>
    <PricingComparisonPlan name="Monthly" price="$29" period="/mo">
      <Button variant="outline" size="sm">Choose monthly</Button>
    </PricingComparisonPlan>
    <PricingComparisonPlan name="Annual" price="$23" period="/mo">
      <Button size="sm">Choose annual</Button>
    </PricingComparisonPlan>
  </PricingComparisonHeader>

  <PricingComparisonSection>
    <PricingComparisonRow label="Billed">
      <PricingComparisonCell>Monthly</PricingComparisonCell>
      <PricingComparisonCell>Yearly</PricingComparisonCell>
    </PricingComparisonRow>
    <PricingComparisonRow label="Effective price" hint="Annual is billed once at $276/yr.">
      <PricingComparisonCell>$348/yr</PricingComparisonCell>
      <PricingComparisonCell>$276/yr</PricingComparisonCell>
    </PricingComparisonRow>
    <PricingComparisonRow label="Cancel anytime">
      <PricingComparisonCell included />
      <PricingComparisonCell included />
    </PricingComparisonRow>
    <PricingComparisonRow label="Price lock">
      <PricingComparisonCell included={false} />
      <PricingComparisonCell included />
    </PricingComparisonRow>
  </PricingComparisonSection>
</PricingComparison>
```

## Centered headers and marks

`align="center"` on the root puts every plan header on its column's axis, the same one as the checks and values under it, so a matrix without CTAs (a versus table, a plan overview) reads as labelled columns. It is set once on the root, so the columns can never disagree. The default, `start`, keeps the name and price on a left edge over full-width buttons. `icon` on a plan adds a mark above its name: a plan glyph here, a product logo in a versus matrix like the one in [Migrating from shadcn/ui](https://www.koalaui.com/docs/migrating-from-shadcn.md). It is decorative; the name stays the column's label.

```tsx
<PricingComparison featured={1} align="center">
  <PricingComparisonHeader>
    <PricingComparisonPlan name="Starter" icon={<Plant weight="bold" />} price="$0" period="/mo" />
    <PricingComparisonPlan name="Pro" icon={<Lightning weight="bold" />} price="$29" period="/mo" />
    <PricingComparisonPlan name="Enterprise" icon={<Buildings weight="bold" />} price="Custom" />
  </PricingComparisonHeader>
  <PricingComparisonSection>
    <PricingComparisonRow label="Projects">
      <PricingComparisonCell>5</PricingComparisonCell>
      <PricingComparisonCell>Unlimited</PricingComparisonCell>
      <PricingComparisonCell>Unlimited</PricingComparisonCell>
    </PricingComparisonRow>
    …
  </PricingComparisonSection>
</PricingComparison>
```

## Row hints

Add a `hint` to any `PricingComparisonRow` to append an info glyph beside the feature name. It reveals the detail in a tooltip on hover or focus, so terse row labels stay scannable while the caveats and limits stay one hover away. Set `hintLabel` to name the trigger for assistive tech (defaults to `"More information"`).

```tsx
<PricingComparisonRow label="Storage" hint="Pooled across the whole team, not per seat.">
  <PricingComparisonCell>1 GB</PricingComparisonCell>
  <PricingComparisonCell>100 GB</PricingComparisonCell>
  <PricingComparisonCell>1 TB</PricingComparisonCell>
</PricingComparisonRow>
```

## API reference

### PricingComparison

The matrix root (a scrollable `<table>`). `featured` is the 0-based index of the plan column to highlight (the single source of truth: the header cap and the body column tint both derive from it). Omit it for no highlight. `align` places every plan header in its column: `start` (the default) or `center`.

### PricingComparisonHeader · PricingComparisonPlan

The sticky plan-header row and its column cells. Header takes an optional `label` for the empty top-left corner. Each Plan takes `name`, `icon` (a decorative mark above the name), `price`, `period`, and an optional `badge`; its children are the CTA, stretched full-width and pinned to the bottom so buttons line up across columns.

### PricingComparisonSection

A labelled group of rows (a `<tbody>`). The `title` renders as a full-width band above its rows. Omit the title for an ungrouped block.

### PricingComparisonRow · PricingComparisonCell

A feature row and its per-plan cells. Row takes a `label` (the leading row header) and an optional `hint` / `hintLabel` for an info tooltip. Each Cell renders its children as a value, or a check / muted minus by `included` when empty. Order the cells to match the plan columns.

## When do I use this instead of Pricing?

Reach for Pricing (the card table) for the marketing moment: a handful of plans, each selling itself with a short feature list and a CTA. Reach for Pricing Comparison when buyers are deciding between plans and need to compare line by line: it lays every feature out as a row so differences are obvious at a glance. Many sites use both, the cards up top and the full matrix below.

## How do I highlight the recommended plan?

Set `featured` on the root to the 0-based index of that plan's column (e.g. `featured={1}` for the second plan). The header cell gets a brand cap and the whole column gets a soft tint, top to bottom. It's the single source of truth, so you never mark the column in two places.

## Do the cells have to be checks and minuses?

No. A cell renders whatever you pass as children, so mix glyphs with real values: `5`, `100 GB`, `Unlimited`, or a Badge. Leave a cell empty to get the success check, or `included={false}` for the muted minus.

## Is the header really sticky?

The plan header is `position: sticky`, so it stays in view while you scan a long matrix when the table scrolls within a bounded height. Give the component a `max-h-*` (or let it scroll inside a constrained container) and the header pins to the top as the rows scroll under it.

---

<!-- https://www.koalaui.com/docs/components/section.md -->

# Section

The content half of every marketing section: a full-bleed band and a centered 1280px gutter with a canonical gap to the content below. Pair it with SectionHeader and every block shares one rhythm.

```tsx
<Section className="bg-muted/40 [--surface:color-mix(in_oklab,var(--muted)_40%,var(--background))]">
  <SectionContainer>
    <SectionHeader align="center">
      <SectionHeaderText>
        <Badge variant="purple" pill>Features</Badge>
        <SectionHeaderHeading>Everything in one system</SectionHeaderHeading>
        <SectionHeaderDescription>
          One container width, one side padding, one 56px gap to the content
          below. Every section on the page shares the same rhythm.
        </SectionHeaderDescription>
      </SectionHeaderText>
    </SectionHeader>

    <div className="grid gap-4 sm:grid-cols-3">
      <Card><CardHeader><CardTitle>Fast</CardTitle>…</CardHeader></Card>
      <Card><CardHeader><CardTitle>Polished</CardTitle>…</CardHeader></Card>
      <Card><CardHeader><CardTitle>Themeable</CardTitle>…</CardHeader></Card>
    </div>
  </SectionContainer>
</Section>
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add section
```

Manual: run `npm install radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/section/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

`Section` is the full-bleed band; `SectionContainer` is the centered gutter. Drop a [SectionHeader](https://www.koalaui.com/docs/components/section-header.md) and your content inside the container, and the 56px gap between them comes for free.

```tsx
import { Section, SectionContainer } from "@/components/ui/section"
import {
  SectionHeader,
  SectionHeaderText,
  SectionHeaderHeading,
  SectionHeaderDescription,
} from "@/components/ui/section-header"

export function Features() {
  return (
    <Section>
      <SectionContainer>
        <SectionHeader align="center">
          <SectionHeaderText>
            <SectionHeaderHeading>Everything in one system</SectionHeaderHeading>
            <SectionHeaderDescription>One rhythm for every section.</SectionHeaderDescription>
          </SectionHeaderText>
        </SectionHeader>

        <div className="grid gap-4 sm:grid-cols-3">{/* content */}</div>
      </SectionContainer>
    </Section>
  )
}
```

## Anatomy

Two parts, one job each. `Section` is the band: it owns the vertical rhythm (`py-16 sm:py-24`) and spans edge to edge, so a background tint or image bleeds full-width. `SectionContainer` is the gutter: it caps the width, pads `20px` on the sides (`32px` from `sm`), and stacks its children in a flex column with a **56px gap** (`gap-14`). Because the gap lives on the container, you never set a header-to-content margin per section again.

```tsx
<Section>                {/* full-bleed band — py-16 sm:py-24 */}
  <SectionContainer>     {/* centered gutter — max-w 1280px, px-6 sm:px-8, gap-14 (56px) */}
    <SectionHeader … />  {/* the lede */}
    <YourContent />      {/* lands 56px below the header */}
  </SectionContainer>
</Section>
```

## Container width

`width` caps the content column. `wide` (default, 1280px) is the marketing width; the rest map to Tailwind's native scale: `default` (1152px), `narrow` (768px) for reading-width content, or `full` for an edge-to-edge row. `xlarge` (1440px) is an opt-in escape for a band that must run wider than the canon. It mirrors [LayoutContainer](https://www.koalaui.com/docs/components/layout.md), so app and marketing shells share one width vocabulary.

```tsx
<SectionContainer width="wide">…</SectionContainer>    {/* 1280px (default) */}
<SectionContainer width="xlarge">…</SectionContainer>  {/* 1440px, opt-in escape */}
<SectionContainer width="default">…</SectionContainer> {/* 1152px */}
<SectionContainer width="narrow">…</SectionContainer>  {/* 768px  */}
<SectionContainer width="full">…</SectionContainer>    {/* edge to edge */}
```

## Full-bleed band

The band spans the page, so a tint, gradient, or image set on `Section` reads edge to edge while the content stays in the centered gutter. Override the vertical rhythm with a `className` when a section needs to sit tighter (it merges last).

```tsx
<Section className="bg-brand/10">
  <SectionContainer>
    <SectionHeader align="center">
      <SectionHeaderText>
        <SectionHeaderHeading>Ship polished products, starting today</SectionHeaderHeading>
        <SectionHeaderDescription>Pay once, and use it forever.</SectionHeaderDescription>
      </SectionHeaderText>
      <SectionHeaderActions>
        <Button size="lg">Get Koala UI</Button>
        <Button size="lg" variant="outline">Read the docs</Button>
      </SectionHeaderActions>
    </SectionHeader>
  </SectionContainer>
</Section>
```

## API reference

### Section

The full-bleed band. Renders a `<section>` landmark with `py-16 sm:py-24` rhythm. Forwards native `<section>` props and `className` (merged last, so a `bg-*` or padding override wins).

### SectionContainer

The centered gutter: caps width per `width` (`"wide"` default, `"xlarge"`, `"default"`, `"narrow"`, `"full"`), pads 24px on the sides (32px from sm), and stacks children in a flex column with a 56px gap. Forwards native `<div>` props and `className`.

## FAQ

### What is the difference between Section and SectionHeader?

They are the two halves of a section. SectionHeader is the lede (eyebrow, heading, description, optional CTA row). Section is the shell around it: the full-bleed band plus the centered gutter that holds the header and the content below it. Use them together.

### Why is the 56px gap on the container instead of the content?

So you never tune a header-to-content margin per section. SectionContainer is a flex column with gap-14 (56px), so dropping a SectionHeader followed by your content yields one canonical gap automatically, and every section on the page matches.

### How do I make a section full-bleed edge to edge?

Set width="full" on SectionContainer to remove the max-width cap, or skip the container entirely and place a full-bleed child directly inside Section. The band itself is always full-width, so background tints set on Section reach the page edges either way.

### Why is the container capped at 1280px and not 1440?

Because 1440 is a viewport — the Figma artboard — not a container. Capping a section at it makes the band run edge to edge on a 1440 laptop with no outer margin at all; 1280 (Tailwind's native 7xl) leaves about 80px of air a side. A --container-8xl token (90rem) still exists in globals.css for the rare band that must run wider, reachable as width="xlarge".

### Can I use it in a Server Component?

Yes. Section and SectionContainer are pure layout with no client state, so they stay server components and drop into RSC marketing pages directly. SectionHeader is a client component, but a server page renders it as a child just fine.

---

<!-- https://www.koalaui.com/docs/components/section-header.md -->

# Section Header

The lede every section opens with: a Badge eyebrow, a balanced heading, a supporting paragraph and a CTA row. Two axes, align and orientation, recompose it, so every block on the page shares one rhythm.

```tsx
<SectionHeader align="left" orientation="split">
  <SectionHeaderText>
    <Badge variant="success" dot pill>Best value</Badge>
    <SectionHeaderHeading>Discover our key features</SectionHeaderHeading>
    <SectionHeaderDescription>
      At Koala Studio, we take pride in providing a unique set of essential
      features that truly distinguish us from the competition.
    </SectionHeaderDescription>
  </SectionHeaderText>
  <SectionHeaderActions>
    <Button>Get started</Button>
    <Button variant="outline">Explore features</Button>
  </SectionHeaderActions>
</SectionHeader>
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add section-header
```

Manual: run `npm install radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/section-header/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

```tsx
import {
  SectionHeader,
  SectionHeaderText,
  SectionHeaderHeading,
  SectionHeaderDescription,
  SectionHeaderActions,
} from "@/components/ui/section-header"
import { Badge } from "@/components/ui/badge"
import { Button } from "@/components/ui/button"

export function Example() {
  return (
    <SectionHeader>
      <SectionHeaderText>
        <Badge variant="success" dot pill>Best value</Badge>
        <SectionHeaderHeading>Discover our key features</SectionHeaderHeading>
        <SectionHeaderDescription>
          A unique set of essential features that distinguish us.
        </SectionHeaderDescription>
      </SectionHeaderText>
      <SectionHeaderActions>
        <Button>Get started</Button>
        <Button variant="outline">Explore features</Button>
      </SectionHeaderActions>
    </SectionHeader>
  )
}
```

## Alignment

`align="left"` (default) anchors the block to the leading edge; `align="center"` centers it in a capped column, the classic centered section lede.

```tsx
<SectionHeader align="left">…</SectionHeader>

<SectionHeader align="center">…</SectionHeader>
```

## Orientation

`orientation="stacked"` (default) drops the actions below the text. `split` moves them beside the text on a row from the `lg` breakpoint up (and stacks again below it). Split is a left-aligned layout; centered headers always stack.

```tsx
<SectionHeader orientation="stacked">…</SectionHeader>

<SectionHeader orientation="split">…</SectionHeader>
```

## Sizes

`size` scales the heading and description together to roughly the scale of a Heading 1 (`lg`), Heading 2 (`md`, the default), or Heading 3 (`sm`). It is independent of the heading `level` (the semantic tag), so an `h2` can read at the Heading 1 size.

| Size | Heading | Description |
| --- | --- | --- |
| `sm` Heading 3 | `text-2xl sm:text-3xl` 24 → 30px | `text-sm sm:text-base` 14 → 16px |
| `md` Heading 2 · default | `text-4xl sm:text-5xl` 36 → 48px | `text-base sm:text-lg` 16 → 18px |
| `lg` Heading 1 | `text-4xl sm:text-5xl lg:text-6xl` 36 → 48 → 60px | `text-lg` 18px |

Values are mobile → `sm` (640px) → `lg` (1024px); the heading and description step up together at those breakpoints. Both slots inherit Tailwind's default type scale (no token override).

```tsx
<SectionHeader size="sm">…</SectionHeader>  {/* Heading 3 scale */}
<SectionHeader size="md">…</SectionHeader>  {/* Heading 2 scale */}
<SectionHeader size="lg">…</SectionHeader>  {/* Heading 1 scale */}
```

## Responsive

The header is responsive on every axis at once. `size` steps the heading and description up at `sm` and `lg`; the actions row stacks full-width on a phone (`items-stretch`) and returns to a wrapping row from `sm`; a `split` header lays the lede and actions side by side from `lg` and falls back to the stacked column below it; a centered block shrinks to the viewport instead of overflowing; and any inline `SectionHeaderChip` rides the heading (it is sized in `em`). Drag the frame, or use the mobile / tablet / desktop presets, to watch it recompose.

```tsx
{/* Recomposes across breakpoints: the size scale, the actions row, and the split layout. */}
<SectionHeader align="left" orientation="split">
  <SectionHeaderText>
    <Badge variant="success" dot pill>Best value</Badge>
    <SectionHeaderHeading>Discover our key features</SectionHeaderHeading>
    <SectionHeaderDescription>
      At Koala Studio, we take pride in providing a unique set of essential features
      that truly distinguish us from the competition.
    </SectionHeaderDescription>
  </SectionHeaderText>
  <SectionHeaderActions>
    <Button>Get started</Button>
    <Button variant="outline">Explore features</Button>
  </SectionHeaderActions>
</SectionHeader>

{/* Centered headers with em-sized chips ride the heading at each breakpoint. */}
<SectionHeader align="center" size="lg">
  <SectionHeaderText>
    <SectionHeaderHeading level={1}>
      The daily <SectionHeaderChip variant="bare">📅</SectionHeaderChip> planner to keep{" "}
      <SectionHeaderChip variant="bare">⚡</SectionHeaderChip> distracted{" "}
      <SectionHeaderChip variant="bare">🧠</SectionHeaderChip> minds on track
    </SectionHeaderHeading>
  </SectionHeaderText>
</SectionHeader>
```

## With an email capture

The actions row composes any control, not just buttons: drop an [Input](https://www.koalaui.com/docs/components/input.md) beside a `Button` for a newsletter or waitlist lede. The row imposes one height on everything inside it, so the field and the button come out level without either of them being given a size.

```tsx
<SectionHeader align="center">
  <SectionHeaderText>
    <SectionHeaderHeading>Stay in the loop</SectionHeaderHeading>
    <SectionHeaderDescription>Get product updates and design tips. No spam.</SectionHeaderDescription>
  </SectionHeaderText>
  <SectionHeaderActions>
    <InputRoot className="w-full max-w-xs">
      <InputField type="email" placeholder="you@company.com" aria-label="Email address" />
    </InputRoot>
    <Button>Subscribe</Button>
  </SectionHeaderActions>
</SectionHeader>
```

## Inline media

Drop a `SectionHeaderChip` between the words of the heading to flow a mark or emoji inline with the copy. A `framed` chip (default) is a rounded tile that holds a logo, icon, or image, the app-icon look set right into the headline; a `bare` chip drops the box for a naked glyph or emoji interleaved with the text. It is sized entirely in `em`, so the tile, its radius, and the glyph inside all scale with the heading at every `size` and breakpoint. Chips are decorative by default (`aria-hidden`); pass an `aria-label` when one stands in for a word.

```tsx
<SectionHeader align="center" size="lg">
  <SectionHeaderText>
    <SectionHeaderHeading level={1}>
      Be yourself until you can be a{" "}
      <SectionHeaderChip aria-label="Koala">
        <Image src="/koala-logo.webp" alt="" width={80} height={80} className="size-full" />
      </SectionHeaderChip>
    </SectionHeaderHeading>
  </SectionHeaderText>
</SectionHeader>

{/* A framed chip frames an icon just as well as an image. */}
<SectionHeader align="center" size="lg">
  <SectionHeaderText>
    <SectionHeaderHeading level={1}>
      Built for <SectionHeaderChip><Lightning weight="bold" /></SectionHeaderChip> fast teams
    </SectionHeaderHeading>
  </SectionHeaderText>
</SectionHeader>
```

Drop the frame with `variant="bare"` and the chip is just a glyph or emoji sized to the cap height, so icons and emoji sit inline between the words without a container.

```tsx
<SectionHeader align="center" size="lg">
  <SectionHeaderText>
    <SectionHeaderHeading level={1}>
      The daily <SectionHeaderChip variant="bare">📅</SectionHeaderChip> planner to keep{" "}
      <SectionHeaderChip variant="bare">⚡</SectionHeaderChip> distracted{" "}
      <SectionHeaderChip variant="bare">🧠</SectionHeaderChip> minds on track
    </SectionHeaderHeading>
  </SectionHeaderText>
</SectionHeader>

{/* Mix in any emoji you like: a bare chip keeps them sized and aligned with the copy. */}
<SectionHeader align="center" size="lg">
  <SectionHeaderText>
    <SectionHeaderHeading level={1}>
      Ship faster <SectionHeaderChip variant="bare">🚀</SectionHeaderChip> sleep better{" "}
      <SectionHeaderChip variant="bare">😴</SectionHeaderChip>
    </SectionHeaderHeading>
  </SectionHeaderText>
</SectionHeader>
```

### Reveal on scroll

Add `reveal` and the chip waits for the reader: until the heading scrolls into view it is closed, taking no width and giving back one of the two spaces around it, so the heading reads as plain copy. When it arrives, the words part to make room and the mark pops into the gap. It fires later than the library's other scroll gates, once the heading has climbed past the lower third of the screen: this animation is the thing you came to look at, so it waits until the heading is actually in front of you instead of playing while it is still a sliver at the bottom edge. Every gap in a heading opens together, so a heading wrapped over several lines keeps its line breaks the whole way; the marks then land one after another. Plays once, and with `prefers-reduced-motion` the chips are simply there. Scroll this preview out of view and reload to see it again.

```tsx
<SectionHeader align="center" size="lg">
  <SectionHeaderText>
    <SectionHeaderHeading>
      Built for{" "}
      <SectionHeaderChip reveal><Lightning weight="bold" /></SectionHeaderChip>{" "}
      fast teams and{" "}
      <SectionHeaderChip reveal variant="bare">🧠</SectionHeaderChip>{" "}
      sharp minds
    </SectionHeaderHeading>
  </SectionHeaderText>
</SectionHeader>
```

## Stagger

A section can *opt in* to a load animation: set `stagger` and the lede cascades in on mount, each unit rising one beat after the last rather than the whole block appearing at once. It is off by default, so you choose where motion earns its keep. Pass `stagger` (or `stagger={true}`) for the default 70 ms cadence, or a number to set the gap between units yourself.

Two knobs shape how it reads. `staggerBy` picks the unit: `"phrase"` (default) reveals the lede part by part (eyebrow, heading, description, then the actions row); `"word"` reveals the heading and description word by word, so the copy types itself in. And `staggerBlur` adds a soft 4px → 0 focus pull as each unit lands, on top of the rise and fade. Try the combinations:

```tsx
// Off by default: the header just renders.
<SectionHeader>…</SectionHeader>

// Opt in: cascade the parts at the DS's 70ms cadence.
<SectionHeader stagger>…</SectionHeader>

// Reveal the copy word by word, with a soft focus pull.
<SectionHeader stagger staggerBy="word" staggerBlur>…</SectionHeader>

// Tune the gap between units (snappier or more relaxed).
<SectionHeader stagger={40} staggerBy="word">…</SectionHeader>

// Below the fold? Play as the reader reaches it, not on load.
<SectionHeader stagger staggerTrigger="inView">…</SectionHeader>
```

By default the cascade plays on **mount**, the right gate for an above-the-fold load reveal. For a section further down the page, set `staggerTrigger="inView"` and it waits until the header scrolls into view, so the reveal happens as the reader arrives instead of finishing off-screen. (The demo above uses `inView`, which is why it replays each time you scroll back to it.)

The whole cascade is continuous: in word mode the eyebrow leads, the heading and description words flow in reading order, and the actions land last, one slot after the final word. It plays once and honors `prefers-reduced-motion` (every unit simply appears). It is backed by the same [motion](https://www.koalaui.com/docs/foundations/motion.md) tokens as the `Stagger` primitive, so a header reads identically to a staggered list or grid below it. For the content *below* the header (a feature grid, a list of cards), wrap it in the `Stagger` primitive (which takes the matching `blur` and `inView` props) to keep one cascade down the section.

## API reference

### SectionHeader

The root. `align` is `"left"` (default) or `"center"`; `orientation` is `"stacked"` (default) or `"split"` (left-aligned only); `size` is `"sm"`, `"md"` (default), or `"lg"`; `stagger` is `false` (default), `true` (cascade the lede in on mount at 70 ms), or a number (the ms gap between units); `staggerBy` is `"phrase"` (default, part by part) or `"word"` (word by word); `staggerBlur` (default `false`) adds a 4px → 0 focus pull to the entrance; `staggerTrigger` is `"mount"` (default) or `"inView"` (cascade when scrolled into view). Forwards native `<div>` props and `className`.

### SectionHeaderText

Groups the lede (eyebrow `Badge`, heading, and description) so alignment applies as a unit and it can sit beside the actions in `split`.

### SectionHeaderHeading

The heading. `level` is `1`, `2` (default), or `3` and picks the semantic tag (`h1`/`h2`/`h3`); the visual scale comes from the root `size`.

### SectionHeaderDescription · SectionHeaderActions

The muted supporting `<p>`, and the CTA row: drop our [Button](https://www.koalaui.com/docs/components/button.md)s (or an `Input` + Button) into it. The row wraps and aligns with the block.

### SectionHeaderChip

An inline media chip for the heading: drop it between the words to flow a logo, icon, or emoji inline with the copy. `variant` is `"framed"` (default, a rounded tile that holds the mark) or `"bare"` (no box, a naked glyph or emoji). Sized in `em` so it scales with the heading. Decorative by default (`aria-hidden`); pass an `aria-label` and it is exposed as an image with that name. `reveal` (default `false`) holds it closed until the heading scrolls into view, then opens a gap in the copy and pops the mark in. Forwards native `<span>` props and `className`.

## FAQ

### When do I use this instead of Hero?

Hero is the page-opening statement (big, fixed-centered, with social proof and a feature checklist). SectionHeader is the lighter lede for every section below it (features, pricing, gallery), with left/center alignment and an optional split actions row.

### How do I add the eyebrow pill?

Drop a `Badge` as the first child of `SectionHeaderText`. It composes our real Badge, so you control its variant, dot, and size; the text wrapper handles its alignment.

### What is the difference between level and size?

`level` (on SectionHeaderHeading) sets the semantic tag h1/h2/h3 for document outline and accessibility. `size` (on SectionHeader) sets the visual scale of the heading and description. They are independent, so an h2 can render at the large size.

### Why does split stack on mobile?

Side-by-side text and actions only fit on wider screens, so `split` becomes a row from the `lg` breakpoint and falls back to the stacked column below it. It is a responsive layout, not a desktop-only one.

### How do I put a logo or emoji inside the heading?

Drop a `SectionHeaderChip` between the words of `SectionHeaderHeading`. A `framed` chip (default) frames a logo, icon, or image in a rounded tile; `variant="bare"` drops the box for a naked glyph or emoji. It's sized in `em`, so it scales with the heading automatically at every size and breakpoint. It's decorative by default (aria-hidden); pass an `aria-label` when the chip stands in for a word so screen readers still get it.

### When should I turn on stagger?

Reach for `stagger` on hero-adjacent or above-the-fold section headers where a brief entrance adds polish; leave it off for dense, content-heavy pages where every section animating would feel busy. It plays once on mount and respects reduced-motion, so it never gets in the way. It's the header counterpart to the `Stagger` primitive you'd wrap the content below it in.

---

<!-- https://www.koalaui.com/docs/components/team-member.md -->

# Team Member

The person block of a team roster: a photo frame, the name, the role, an optional bio and a row of social links. Stacked, inline or set over the photo, as a plain block or an outline card.

```tsx
<TeamMember>
  <TeamMemberMedia shape="portrait">
    <img src="/team/lucia.jpg" alt="Lucía Ferrer" />
  </TeamMemberMedia>
  <TeamMemberContent>
    <TeamMemberName>Lucía Ferrer</TeamMemberName>
    <TeamMemberRole>Co-founder & CEO</TeamMemberRole>
    <TeamMemberSocials>
      <TeamMemberSocial href="#" label="Lucía on LinkedIn">
        <LinkedinLogo weight="bold" />
      </TeamMemberSocial>
    </TeamMemberSocials>
  </TeamMemberContent>
</TeamMember>
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add team-member
```

Manual: run `npm install radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/team-member/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

Compose the parts you need and leave the rest out: there is no `showX` prop. A roster without bios omits `TeamMemberBio`, one without links omits `TeamMemberSocials`, and a list with no photos omits the media altogether. `TeamMemberMedia` is a frame for whatever picture you pass it (an `<img>` or `next/image`), cropped to cover. A small face can be the `Avatar` component instead, which every layout treats the same way. Pass `asChild` to render the member as the `<li>` of your roster list.

## Layouts

`stacked` (the default) puts the photo above the copy, the portrait grid and the carousel card. `inline` puts a small photo beside it, the directory row, and scales the frame and its radius down with it. `overlay` sets the copy on the foot of the photo over a dark scrim, the wall of faces; the scrim is dark on every theme, so the names stay white and legible whatever the picture.

```tsx
<TeamMember layout="stacked">…</TeamMember>
<TeamMember layout="inline">…</TeamMember>
<TeamMember layout="overlay">…</TeamMember>
```

## Card

`variant="card"` gives the member a box of its own: an inset ring on the page ground, no fill. Around a round face it pads 20px; around a photo that fills its width it insets the photo 8px, so the photo's 16px corner stays concentric with the card's 24px one, and the copy keeps its own 12px step. In a row of cards the links sit on each card's foot. Over a photograph the card becomes a floating panel inset from the foot instead of a scrim.

```tsx
<TeamMember variant="card">
  <TeamMemberMedia shape="circle" className="size-14">…</TeamMemberMedia>
  <TeamMemberContent>…</TeamMemberContent>
</TeamMember>
<TeamMember variant="card">
  <TeamMemberMedia shape="landscape">…</TeamMemberMedia>
  <TeamMemberContent>…</TeamMemberContent>
</TeamMember>
<TeamMember layout="overlay" variant="card">…</TeamMember>
```

```tsx
<TeamMember layout="inline" variant="card">
  <TeamMemberMedia shape="square" className="size-24">…</TeamMemberMedia>
  <TeamMemberContent>…</TeamMemberContent>
</TeamMember>
<TeamMember layout="inline" variant="card">
  <AvatarRoot size="lg">…</AvatarRoot>
  <TeamMemberContent>…</TeamMemberContent>
</TeamMember>
```

## Shapes

The frame's `shape`: a 4:5 `portrait` (the default), a 4:3 `landscape`, a `square`, or a `circle`. The first three fill their column; a circle holds the size you give it, since a round face stretched to a wide column would crowd the row.

```tsx
<TeamMemberMedia shape="portrait">…</TeamMemberMedia>
<TeamMemberMedia shape="landscape">…</TeamMemberMedia>
<TeamMemberMedia shape="square">…</TeamMemberMedia>
<TeamMemberMedia shape="circle" className="size-36">…</TeamMemberMedia>
```

## Alignment

`align="center"` centres the frame, the copy and the links on the column, the shape for round portraits and centred rosters. `start` (the default) keeps everything on the left edge.

```tsx
<TeamMember align="center">
  <TeamMemberMedia shape="circle" className="size-32">…</TeamMemberMedia>
  <TeamMemberContent>…</TeamMemberContent>
</TeamMember>
```

## Anatomy

`TeamMember` is the root and carries the `layout`, `align` and `variant`. `TeamMemberMedia` is the photo frame and carries the `shape`. `TeamMemberContent` groups the copy so it can sit beside or over the photo as one block. `TeamMemberName` is an `<h3>` (or your own element with `asChild`), `TeamMemberRole` and `TeamMemberBio` are paragraphs, and `TeamMemberSocials` holds the `TeamMemberSocial` icon links. Every part forwards its native props and carries a `data-slot`.

## FAQ

### Why is the photo's edge a ring painted over the picture?

An inset ring on an image is drawn under it, so it never shows. The frame paints its hairline with an ::after overlay instead, in pure black or white at 10%: a tinted neutral would pick up the photo's colour and read as dirt on its edge.

### Why does the card have no fill?

A grid of filled panels reads as chrome competing with the faces, and on the dark themes the card token is light enough to turn every member into a grey slab. The card is the boundary and nothing else, so anything nested keeps resolving the page's ground.

### How do I keep a row of cards even?

Write the bios to one measure, about sixty characters each, so the cards in a row wrap to the same number of lines. The links sit on each card's foot either way, so a name that wraps never pushes one row of icons out of line.

### Are the social links accessible?

Each TeamMemberSocial takes a label, used as the link's accessible name and as its hover title, since the glyph alone says nothing to a screen reader. The glyph box is 32px and its tap target is extended to 40px, 44px on touch.

---

<!-- https://www.koalaui.com/docs/components/testimonials.md -->

# Testimonials

A minimal quote card for social-proof walls. Named parts you assemble: an optional quote mark, the quote, an author row and an optional logo. Stars come from Rating, the headshot from Avatar.

```tsx
<div className="grid gap-4 sm:grid-cols-2 lg:grid-cols-3">
  <Testimonial>
    <TestimonialQuote>We replaced our in-house kit in a weekend…</TestimonialQuote>
    <TestimonialFooter>
      <Avatar size="md"><AvatarImage src="https://i.pravatar.cc/160?img=13" alt="Alex Rivera" /><AvatarFallback>AR</AvatarFallback></Avatar>
      <TestimonialAuthor>
        <TestimonialName>Alex Rivera</TestimonialName>
        <TestimonialTitle>Founder, Lumen</TestimonialTitle>
      </TestimonialAuthor>
    </TestimonialFooter>
  </Testimonial>
  {/* …more */}
</div>
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add testimonials
```

Manual: run `npm install radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/testimonials/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

```tsx title="usage.tsx"
import { Avatar, AvatarFallback, AvatarImage } from "@/components/ui/avatar"
import {
  Testimonial, TestimonialQuote, TestimonialFooter,
  TestimonialAuthor, TestimonialName, TestimonialTitle,
} from "@/components/ui/testimonials"

export function Example() {
  return (
    <Testimonial>
      <TestimonialQuote>
        We replaced our in-house kit in a weekend and never looked back.
      </TestimonialQuote>
      <TestimonialFooter>
        <Avatar size="md">
          <AvatarImage src="https://i.pravatar.cc/160?img=13" alt="Alex Rivera" />
          <AvatarFallback>AR</AvatarFallback>
        </Avatar>
        <TestimonialAuthor>
          <TestimonialName>Alex Rivera</TestimonialName>
          <TestimonialTitle>Founder, Lumen</TestimonialTitle>
        </TestimonialAuthor>
      </TestimonialFooter>
    </Testimonial>
  )
}
```

## Variants

The default is `plain`: a flat, tinted surface with no border line or shadow. `outline` adds a hairline border, `soft` trades it for a subtle shadow, and `elevated` drops the border and lifts the card to feature one quote. There is also a borderless `ghost` for walls on a tinted section, and `bare`, which strips the surface and padding entirely so the quote sits flush on the page.

```tsx
<Testimonial variant="plain">…</Testimonial>
<Testimonial variant="outline">…</Testimonial>
<Testimonial variant="soft">…</Testimonial>
<Testimonial variant="elevated">…</Testimonial>
<Testimonial variant="ghost">…</Testimonial>
<Testimonial variant="bare">…</Testimonial>
```

## With a rating

Drop our [Rating](https://www.koalaui.com/docs/components/rating.md) with `readOnly` above the quote for star social proof.

```tsx
<Testimonial variant="outline">
  <Rating readOnly value={5} size="sm" />
  <TestimonialQuote>…</TestimonialQuote>
  <TestimonialFooter>…</TestimonialFooter>
</Testimonial>
```

## Author on top

Lead with the byline by rendering the `TestimonialFooter` first with `className="mt-0"`: a compact, scannable layout for dense walls.

```tsx
<Testimonial>
  <TestimonialFooter className="mt-0">
    <Avatar size="md"><AvatarImage src="https://i.pravatar.cc/160?img=13" alt="Alex Rivera" /><AvatarFallback>AR</AvatarFallback></Avatar>
    <TestimonialAuthor>
      <TestimonialName>Alex Rivera</TestimonialName>
      <TestimonialTitle>Founder, Lumen</TestimonialTitle>
    </TestimonialAuthor>
  </TestimonialFooter>
  <TestimonialQuote className="text-sm">…</TestimonialQuote>
</Testimonial>
```

## Divided, with a logo

Set `divided` for a hairline rule above the author row, and drop a `TestimonialLogo` in the footer for a company wordmark; it sits flush to the trailing edge.

```tsx
<Testimonial variant="outline" divided>
  <TestimonialQuote>…</TestimonialQuote>
  <TestimonialFooter>
    <Avatar size="md"><AvatarImage src="https://i.pravatar.cc/160?img=13" alt="Alex Rivera" /><AvatarFallback>AR</AvatarFallback></Avatar>
    <TestimonialAuthor>
      <TestimonialName>Alex Rivera</TestimonialName>
      <TestimonialTitle>Founder, Lumen</TestimonialTitle>
    </TestimonialAuthor>
    <TestimonialLogo>Lumen</TestimonialLogo>
  </TestimonialFooter>
</Testimonial>
```

## Logo-led

Lead the card with the company logo instead of trailing it: drop a `TestimonialLogo` at the top and put a logo lockup inside it (here, a colored mark from the placeholder set). Outside a `TestimonialFooter` the logo stays on the start edge; it only pushes to the trailing edge inside the footer. Pairs well with `variant="bare"` for a logo wall.

```tsx
<div className="grid gap-x-10 gap-y-10 sm:grid-cols-3">
  <Testimonial variant="bare" className="gap-3">
    <TestimonialLogo>
      <CompanyLogo /> {/* a colored SVG mark + wordmark */}
    </TestimonialLogo>
    <TestimonialQuote className="font-semibold text-foreground">…</TestimonialQuote>
    <TestimonialFooter className="mt-auto pt-4">
      <Avatar size="md"><AvatarImage src="https://i.pravatar.cc/160?img=13" alt="Alex Rivera" /><AvatarFallback>AR</AvatarFallback></Avatar>
      <TestimonialAuthor>
        <TestimonialName>Alex Rivera</TestimonialName>
        <TestimonialTitle>Founder, Halcyon</TestimonialTitle>
      </TestimonialAuthor>
    </TestimonialFooter>
  </Testimonial>
  {/* …more */}
</div>
```

## Container-less

The most minimal option: `variant="bare"` strips the surface entirely (no border, background, padding, or radius) so the quotes sit flush on the page with nothing but whitespace between them.

```tsx
<div className="grid gap-x-10 gap-y-10 sm:grid-cols-2">
  <Testimonial variant="bare">
    <TestimonialQuote className="text-sm">…</TestimonialQuote>
    <TestimonialFooter>
      <Avatar size="md"><AvatarImage src="https://i.pravatar.cc/160?img=13" alt="Alex Rivera" /><AvatarFallback>AR</AvatarFallback></Avatar>
      <TestimonialAuthor>
        <TestimonialName>Alex Rivera</TestimonialName>
        <TestimonialTitle>Founder, Lumen</TestimonialTitle>
      </TestimonialAuthor>
    </TestimonialFooter>
  </Testimonial>
  {/* …more */}
</div>
```

## Centered pull-quote

Pair `variant="bare"` with `align="center"` for a single standout quote: centers the mark, quote, and byline with no chrome at all.

```tsx
<Testimonial variant="bare" align="center" className="mx-auto max-w-xl gap-6">
  <TestimonialMark />
  <TestimonialQuote className="text-xl text-balance sm:text-2xl">…</TestimonialQuote>
  <TestimonialFooter>
    <Avatar size="md"><AvatarImage src="https://i.pravatar.cc/160?img=13" alt="Alex Rivera" /><AvatarFallback>AR</AvatarFallback></Avatar>
    <TestimonialAuthor>
      <TestimonialName>Alex Rivera</TestimonialName>
      <TestimonialTitle>Founder, Lumen</TestimonialTitle>
    </TestimonialAuthor>
  </TestimonialFooter>
</Testimonial>
```

## Headline and size

A `TestimonialQuote` followed by a `TestimonialBody` becomes the card's headline (semibold, full-strength ink) over the longer quote; drop the body and it reads as a plain pull-quote again. `size` sets the type scale: `md` (default) for dense grids and carousels, `lg` for landing rows and walls (an 18px headline over 16px body and byline), and `xl` for one quote given room beside a picture (24px over 18px). Pair the bigger steps with an `lg` Avatar.

```tsx
<Testimonial variant="bare" size="lg">
  <div className="flex flex-col gap-1.5">
    <TestimonialQuote>We shipped the new site in a weekend.</TestimonialQuote>
    <TestimonialBody>We replaced our half-finished in-house kit…</TestimonialBody>
  </div>
  <TestimonialFooter>
    <Avatar size="lg"><AvatarImage src="https://i.pravatar.cc/160?img=13" alt="Alex Rivera" /><AvatarFallback>AR</AvatarFallback></Avatar>
    <TestimonialAuthor>
      <TestimonialName>Alex Rivera</TestimonialName>
      <TestimonialTitle>Founder, Lumen</TestimonialTitle>
    </TestimonialAuthor>
  </TestimonialFooter>
</Testimonial>
```

## Featured

Drop a `TestimonialMark` in for a quotation glyph and use `variant="elevated"` to lift one standout quote.

```tsx
<Testimonial variant="elevated" className="max-w-md">
  <TestimonialMark />
  <TestimonialQuote className="text-lg">Radix under the hood means I stopped worrying about a11y bugs.</TestimonialQuote>
  <TestimonialFooter>
    <Avatar size="md"><AvatarImage src="https://i.pravatar.cc/160?img=32" alt="Mei Lin" /><AvatarFallback>ML</AvatarFallback></Avatar>
    <TestimonialAuthor>
      <TestimonialName>Mei Lin</TestimonialName>
      <TestimonialTitle>Frontend Lead, Cadence</TestimonialTitle>
    </TestimonialAuthor>
  </TestimonialFooter>
</Testimonial>
```

## API reference

### Testimonial

The root `<figure>` card. Provides the styling context to every part. `variant` is `"plain"` (default), `"outline"`, `"soft"`, `"elevated"`, `"ghost"` (no surface, keeps padding), or `"bare"` (container-less: no surface or padding). `align` is `"start"` (default) or `"center"`, and `divided` adds a rule above the footer. `size` is `"md"` (default), `"lg"` or `"xl"`, the type scale of the quote, body and byline together. Accepts `asChild`.

### TestimonialMark · TestimonialQuote · TestimonialBody

An optional decorative quote glyph, the `<blockquote>` itself, and the optional longer quote under it. A quote followed by a `TestimonialBody` styles itself as the headline.

### TestimonialFooter · TestimonialAuthor · TestimonialName · TestimonialTitle · TestimonialLogo

The author row (`<figcaption>`): drop an [Avatar](https://www.koalaui.com/docs/components/avatar.md) beside the name/title stack, and an optional `TestimonialLogo` for a company wordmark on the trailing edge. For the stars, use our [Rating](https://www.koalaui.com/docs/components/rating.md) with `readOnly`.

## FAQ

### How do I add the star rating and the headshot?

Testimonial is pure layout, so it does not ship its own stars or avatar. Drop our `Rating` with `readOnly` in for the stars, and our `Avatar` into the `TestimonialFooter` beside the author stack.

### What is the difference between the variants?

`plain` (default) is a flat tinted surface with no border or shadow, `outline` adds a hairline border, `soft` trades it for a subtle shadow, `elevated` removes the border and lifts the card to feature one quote, and `ghost` is fully transparent for walls on a tinted section. Set it with the `variant` prop.

### How do I make a container-less testimonial?

Use `variant="bare"`. It strips the surface entirely: no border, background, padding, or radius, so the quote and byline sit flush on the page. `ghost` is the in-between, dropping the surface but keeping the padding for use inside an already-spaced section.

### How do I center a single pull-quote?

Pair `variant="bare"` with `align="center"`. The `align` prop centers the quote mark, the quote text, and the author row, and reads `start` (default) or `center`.

### What does the `divided` prop do?

It adds a hairline rule above the author row, separating the quote from the byline (a Vercel-style treatment). Combine it with a `TestimonialLogo` for a clean, branded card footer.

### How do I assemble the author row?

Use `TestimonialFooter` as the row, with the `Avatar` first and a `TestimonialAuthor` holding a `TestimonialName` and `TestimonialTitle` stack beside it. Add an optional `TestimonialLogo` for a wordmark on the right. The footer is a real `figcaption`.

### How do I put the author above the quote?

Render the `TestimonialFooter` before the `TestimonialQuote` and pass `className="mt-0"` to it. The footer's default `mt-auto` pushes it to the bottom, so resetting the margin lets it lead.

### What is TestimonialMark for?

It is an optional decorative quotation glyph that sits above the quote. It is aria-hidden and brand-tinted, so it adds visual flourish without affecting the semantics or screen-reader output.

### Can the card be a link?

Yes. `Testimonial` accepts `asChild`, so it renders onto your own element (for example an anchor) via Radix Slot while keeping the figure styling and passing context to every part.

### How do I lay out a wall of testimonials?

The root is a self-contained `figure` with `h-full`, so it stretches to equal height in a grid. Arrange a set in a CSS grid, or place them inside our Carousel, to build a testimonial wall.

---

<!-- https://www.koalaui.com/docs/components/ai-panel.md -->

# AI Panel

The assistant sidepanel: a header, a scrollable conversation and a pinned composer in one column. Drop a Chat in the body and a Prompt Input in the footer. Pure layout, so it docks in a page or drops into a Drawer.

```tsx
<AIPanel>
  <AIPanelHeader>
    <Avatar><AvatarFallback className="bg-brand/10 text-brand"><Sparkle /></AvatarFallback></Avatar>
    <AIPanelHeading>
      <AIPanelTitle>Koala Assistant</AIPanelTitle>
      <AIPanelDescription>Always here to help</AIPanelDescription>
    </AIPanelHeading>
    <AIPanelActions>
      <AIPanelAction aria-label="History"><ClockCounterClockwise /></AIPanelAction>
      <AIPanelAction aria-label="New chat"><PencilSimpleLine /></AIPanelAction>
    </AIPanelActions>
  </AIPanelHeader>

  <AIPanelBody>
    <Conversation>
      {messages.map((m) => (
        <Message key={m.id} role={m.role}>
          {m.role === "assistant" && <MessageAvatar name="Koala" />}
          <MessageBody><MessageContent>{m.text}</MessageContent></MessageBody>
        </Message>
      ))}
    </Conversation>
  </AIPanelBody>

  <AIPanelFooter>
    <PromptInput size="sm" loading={loading} onSubmit={send}>
      <PromptInputTextarea placeholder="Reply to Koala…" />
      <PromptInputToolbar>
        <PromptInputButton iconOnly aria-label="Add"><Plus /></PromptInputButton>
        <PromptInputSubmit />
      </PromptInputToolbar>
    </PromptInput>
  </AIPanelFooter>
</AIPanel>
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add ai-panel
```

Manual: run `npm install tailwind-variants tailwind-merge`, then copy the source into `components/ui/ai-panel/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

```tsx title="usage.tsx"
import {
  AIPanel,
  AIPanelHeader,
  AIPanelHeading,
  AIPanelTitle,
  AIPanelBody,
  AIPanelFooter,
} from "@/components/ui/ai-panel"
import { Conversation } from "@/components/ui/chat"
import { PromptInput } from "@/components/ui/prompt-input"

export function Assistant() {
  return (
    <AIPanel>
      <AIPanelHeader>
        <AIPanelHeading>
          <AIPanelTitle>Assistant</AIPanelTitle>
        </AIPanelHeading>
      </AIPanelHeader>
      <AIPanelBody>
        <Conversation>{/* messages */}</Conversation>
      </AIPanelBody>
      <AIPanelFooter>
        <PromptInput onSubmit={send}>{/* composer */}</PromptInput>
      </AIPanelFooter>
    </AIPanel>
  )
}
```

The panel fills its container (`h-full`) and owns the scroll: only the body scrolls, while the header and composer stay pinned. Give it a sized frame when docking it in a page.

## Window modes (split & floating)

The panel can manage its own window, Notion/Edge-style. Beyond the embedded `inline` default, it has two windowed views: `split` (a full-height rail pinned to the right edge, the split-screen assistant) and `floating` (a compact window hovering bottom-right). Drop an `AIPanelExpandToggle` in the header to flip between them; it swaps its own icon and label with the view. These modes are non-modal: the page stays interactive, so closing is the host's call (render the panel behind a launcher). The view is controllable via `view` / `defaultView` / `onViewChange`.

```tsx
function Assistant() {
  const [open, setOpen] = React.useState(false)
  const [view, setView] = React.useState<AIPanelView>("split")
  return (
    <>
      {!open && <Button onClick={() => setOpen(true)}>Ask Koala</Button>}
      {open && (
        <AIPanel view={view} onViewChange={setView}>
          <AIPanelHeader>
            <AIPanelHeading><AIPanelTitle>Assistant</AIPanelTitle></AIPanelHeading>
            <AIPanelActions>
              {/* swaps Float ⇄ Dock with the current view */}
              <AIPanelExpandToggle />
              <AIPanelAction aria-label="Close" onClick={() => setOpen(false)}><X /></AIPanelAction>
            </AIPanelActions>
          </AIPanelHeader>
          {/* body · footer */}
        </AIPanel>
      )}
    </>
  )
}
```

## As an overlay (Drawer)

Because it's pure layout, the same panel drops straight into a `DrawerContent` for a slide-in assistant: the Drawer brings the trigger, scrim, focus trap, and animation. Hide the Drawer's own close (`showClose=false`) and put a close action in the panel header instead. An overlay is never a dead end: keep a *minimize to window* action that pops the panel out to a `floating` window (and back), so the assistant can ride along while the user keeps working.

```tsx
<Drawer>
  <DrawerTrigger asChild>
    <Button variant="outline"><Sparkle /> Ask Koala</Button>
  </DrawerTrigger>
  <DrawerContent side="right" showClose={false} className="p-0">
    <DrawerTitle className="sr-only">Koala Assistant</DrawerTitle>
    <AIPanel>{/* header · body · footer */}</AIPanel>
  </DrawerContent>
</Drawer>
```

## Empty state

With no messages yet, center a greeting and a few starters in the body. The body is a plain flex region, so a centered welcome composes with no extra parts. For genuine *no-content* moments (no history, no results, offline), reach for the canonical `EmptyState` instead: see below.

```tsx
<AIPanelBody className="flex flex-col items-center justify-center gap-5 text-center">
  <span className="flex size-12 items-center justify-center rounded-full bg-brand/10 text-brand">
    <Sparkle className="size-6" />
  </span>
  <div>
    <p className="text-pretty text-base font-semibold">How can I help?</p>
    <p className="text-pretty text-sm text-muted-foreground">Ask about your workspace…</p>
  </div>
  <PromptInputSuggestions className="justify-center">
    {starters.map(({ label, icon: Icon }) => (
      <PromptInputSuggestion key={label} onClick={() => setValue(label)}>
        <Icon /> {label}
      </PromptInputSuggestion>
    ))}
  </PromptInputSuggestions>
</AIPanelBody>
```

## No content & error states

Beyond the welcome state, an assistant hits real *no-content* moments: an empty history, a search that finds nothing, a dropped connection. Because the body is a plain flex region, drop the canonical `EmptyState` straight in. `density="compact"` fits the in-panel scale, and `variant` re-themes the media and action for an error (`destructive`) versus a neutral zero state (`default`).

```tsx
<AIPanelBody className="flex items-center justify-center">
  <EmptyState density="compact" variant="destructive">
    <EmptyStateMedia><WifiSlash /></EmptyStateMedia>
    <EmptyStateTitle>Can't reach the assistant</EmptyStateTitle>
    <EmptyStateDescription>
      Koala is offline right now. Check your connection and try again.
    </EmptyStateDescription>
    <EmptyStateActions>
      <Button variant="outline"><ArrowClockwise /> Retry</Button>
    </EmptyStateActions>
  </EmptyState>
</AIPanelBody>
```

## API reference

### AIPanel

The shell: a full-height flex column on the popover surface, exposing `--surface` so the nested composer blends in. Owns the view state: `inline` (fills container), `split` (right rail), or `floating`, controllable via `view` / `defaultView` / `onViewChange`. Forwards all native `div` props.

### AIPanelHeader · AIPanelHeading · AIPanelTitle · AIPanelDescription

The bordered header row: leading media (e.g. an `Avatar`), a title/description column, and actions. Inside a Drawer, also render a `<DrawerTitle className="sr-only">` for screen readers.

### AIPanelActions · AIPanelAction · AIPanelExpandToggle

Header actions: new chat, history, close. `AIPanelAction` is a ghost icon `Button` (all Button props apply; use `asChild` to wrap a `DrawerClose`). `AIPanelExpandToggle` is a prewired action that flips the panel between the `split` rail and the `floating` window.

### AIPanelBody · AIPanelFooter

`AIPanelBody` is the only scrolling region; drop a `Conversation` inside. `AIPanelFooter` is the pinned composer dock; drop a `PromptInput` inside.

## FAQ

### How do I dock AIPanel in a page versus floating it as an overlay?

AIPanel is pure layout and fills its container with `h-full`, so to dock it just give it a sized frame in your page. For an overlay, drop the same panel into a `DrawerContent` and let the Drawer supply the trigger, scrim, focus trap, and slide animation.

### What does the view prop do and how do I add the window toggle?

`view` switches between `inline` (fills its container, the default), `split` (a full-height rail pinned to the right edge), and `floating` (a compact window hovering bottom-right). Drop an `AIPanelExpandToggle` into your header `AIPanelActions` to flip between split and floating; the view is controllable via `view` / `defaultView` / `onViewChange`, or left uncontrolled.

### Are the split and floating modes modal, and how do I close them?

No, they're non-modal: there's no scrim and the page stays interactive, Notion/Edge-style. Closing is the host's call, so render the panel behind your own open state (e.g. a launcher button) and add a close `AIPanelAction` that flips it off. To reserve layout space for a `split` rail, pad your page content by the rail width.

### Which region scrolls, and where do I put the conversation and composer?

Only `AIPanelBody` scrolls; the header and `AIPanelFooter` stay pinned. Drop a `Conversation` (from Chat) inside `AIPanelBody` and a `PromptInput` inside `AIPanelFooter`.

### How should I handle the close action when the panel lives in a Drawer?

Hide the Drawer's own close with `showClose={false}` and put a close action in the panel header instead. Render an `AIPanelAction` with `asChild` wrapping a `DrawerClose`, and add a `<DrawerTitle className="sr-only">` for screen readers.

### How do I show an empty state when there's no content?

The body is a plain flex region, so center whatever fits the moment. For a fresh chat, drop a greeting plus a few `PromptInputSuggestions` starters. For genuine no-content cases (no saved history, a search with no results, or an offline/error), reach for the canonical `EmptyState` at `density="compact"` and swap its `variant` (`default` for a neutral zero state, `destructive` for an error). Add `className="flex items-center justify-center"` to `AIPanelBody` so it centers.

### Why is AIPanelAction styled differently from a plain Button?

`AIPanelAction` is a thin wrapper over `Button` defaulting to `variant="ghost"`, `size="sm"`, and `iconOnly`, with muted foreground, so header controls stay quiet and consistent. All Button props still apply, and it derives a tooltip from its `aria-label`.

---

<!-- https://www.koalaui.com/docs/components/chat.md -->

# Chat

The AI conversation thread, the second piece of the AI module. The assistant answers as a document, the Notion and ChatGPT style; the user turn stays a bubble. Streaming and reasoning included.

```tsx
{/* Document style is the default: the assistant answer has no bubble or avatar. */}
<Conversation>
  <Message role="user">
    <MessageBody>
      <MessageContent>Explain how the density system works in this codebase.</MessageContent>
    </MessageBody>
  </Message>
  <Message role="assistant">
    {/* no MessageAvatar: the answer is a page, not an identity */}
    <MessageBody>
      <MessageContent>
        <p>Density is a single axis, <strong>comfortable</strong> or <strong>compact</strong>…</p>
        <h3>How it works</h3>
        <ul>
          <li>DensityProvider puts the active density on the context.</li>
          <li>Components read it with the useDensity hook.</li>
        </ul>
      </MessageContent>
    </MessageBody>
  </Message>
</Conversation>
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add chat
```

Manual: run `npm install radix-ui tailwind-variants tailwind-merge @phosphor-icons/react`, then copy the source into `components/ui/chat/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Anatomy

Every part is a named export, never dot-notation, so each one crosses the server and client boundary cleanly. `Conversation` is the scrollable thread; each `Message` carries its `role` to its parts through context, so one prop drives the side, tint, and meta alignment. Compose only the parts a turn needs.

```tsx title="anatomy.tsx"
<Conversation>
  <Message role="assistant">
    <MessageAvatar name="Koala" />
    <MessageBody>
      <MessageHeader>
        <MessageName>Koala</MessageName>
        <MessageTime>2:34 PM</MessageTime>
      </MessageHeader>

      <MessageReasoning>
        <MessageReasoningTrigger>Thought for 6s</MessageReasoningTrigger>
        <MessageReasoningContent>…</MessageReasoningContent>
      </MessageReasoning>

      <MessageContent>…</MessageContent>

      <MessageActions>
        <MessageAction aria-label="Copy">…</MessageAction>
      </MessageActions>
    </MessageBody>
  </Message>
</Conversation>
```

## Usage

```tsx title="usage.tsx"
import {
  Conversation,
  Message,
  MessageAvatar,
  MessageBody,
  MessageContent,
} from "@/components/ui/chat"

export function Thread() {
  return (
    <Conversation className="max-h-[32rem]">
      <Message role="user">
        <MessageBody>
          <MessageContent>Where is the theme applied on load?</MessageContent>
        </MessageBody>
      </Message>
      <Message role="assistant">
        <MessageAvatar name="Koala" />
        <MessageBody>
          <MessageContent>In app/layout.tsx, via a blocking script before paint.</MessageContent>
        </MessageBody>
      </Message>
    </Conversation>
  )
}
```

## Roles

A message's `role` is the only switch. `assistant` aligns left with an avatar and a muted bubble; `user` aligns right with a solid blue bubble. Both use a soft, uniform radius on all four corners.

```tsx
<Message role="user">
  <MessageBody>
    <MessageContent>Why is pnpm build failing on CI but not locally?</MessageContent>
  </MessageBody>
</Message>

<Message role="assistant">
  <MessageAvatar name="Koala" src="/koala-logo.webp" />
  <MessageBody>
    <MessageContent>CI runs Node 18, but the config calls structuredClone…</MessageContent>
  </MessageBody>
</Message>
```

## With avatar (bubble)

The default is the document style above. For a chat with an identity, the “robotized” look, set `variant="bubble"` on the `Conversation`: every turn gets a bubble, and you pair the assistant with a `MessageAvatar`, name, time, and actions. A per-message `variant` overrides the conversation default.

```tsx
<Conversation variant="bubble" className="max-h-[26rem]">
  <Message role="user">
    <MessageBody>
      <MessageContent>Add an empty state to the data table when there are no rows.</MessageContent>
    </MessageBody>
  </Message>

  <Message role="assistant">
    <MessageAvatar name="Koala" src="/koala-logo.webp" />
    <MessageBody>
      <MessageHeader>
        <MessageName>Koala</MessageName>
        <MessageTime>2:34 PM</MessageTime>
      </MessageHeader>
      <MessageContent>
        <p>Done. I dropped an EmptyState into the table body:</p>
        <ul>
          <li>Renders when rows.length === 0.</li>
          <li>Stays hidden while loading so the skeleton shows.</li>
        </ul>
      </MessageContent>
      <MessageActions>
        <MessageAction aria-label="Copy"><Copy /></MessageAction>
        <MessageAction aria-label="Regenerate"><ArrowsClockwise /></MessageAction>
      </MessageActions>
    </MessageBody>
  </Message>
</Conversation>
```

## Rich content

`MessageContent` is markup-agnostic. Drop in plain text or your own rendered markdown; the bubble styles the common elements (paragraphs, headings, lists, inline `code`, `pre` blocks, and links) through descendant selectors, tinted to read on either bubble.

```tsx
<MessageContent>
  <p>Define the component recipe with <code>tv</code> and read its variants:</p>
  <pre><code>{`const button = tv({
  base: "inline-flex items-center justify-center",
  variants: { size: { sm: "h-8 px-3", md: "h-10 px-4" } },
})`}</code></pre>
  <p>See the <a href="/docs/foundations/density">foundations</a> for the house style.</p>
</MessageContent>
```

## Actions

`MessageActions` holds a row of `MessageAction` buttons for copy, regenerate, and feedback. Each wraps our `Button`, so it inherits the press scale, the focus ring, and a tooltip drawn from its `aria-label`.

```tsx
<MessageActions>
  <MessageAction aria-label="Copy"><Copy /></MessageAction>
  <MessageAction aria-label="Regenerate"><ArrowsClockwise /></MessageAction>
  <MessageAction aria-label="Good response"><ThumbsUp /></MessageAction>
  <MessageAction aria-label="Bad response"><ThumbsDown /></MessageAction>
</MessageActions>
```

## Typing indicator

While a response streams, drop a `MessageTyping` inside a `MessageContent`. Three dots ripple left to right, and hold still under reduced-motion.

```tsx
<Message role="assistant">
  <MessageAvatar name="Koala" />
  <MessageBody>
    <MessageContent><MessageTyping /></MessageContent>
  </MessageBody>
</Message>
```

## Reasoning

The collapsible “thinking” block, the way Claude and ChatGPT show it. While `streaming` the icon pulses and the trigger reads “Investigating…”; once done, it settles to a summary like “Investigated 14 sources” that anyone can expand. For a simple answer, pass plain text; for an agentic run, the block becomes a log of what it did. Group each phase in a `MessageReasoningStep` (an optional `label` captions it, a dot pins onto the rail so a column reads as a timeline, and `status="active"` pulses the in-progress one). Show the searches it ran with `MessageReasoningQuery` and the URLs it consulted with `MessageReasoningSource`, as compact favicon and domain chips by default or a bordered title list via `layout="list"`. The domain and favicon are derived from the `href`. Built on Radix Collapsible, so keyboard and ARIA come for free. Press *Ask again* to watch it stream through the phases.

```tsx
<MessageReasoning streaming={thinking} open={open} onOpenChange={setOpen}>
  <MessageReasoningTrigger>
    <AnimatedLabel swapKey={thinking ? "thinking" : "done"}>
      {thinking ? "Investigating…" : "Investigated 14 sources"}
    </AnimatedLabel>
  </MessageReasoningTrigger>
  <MessageReasoningContent>
    <MessageReasoningStep>
      <p>Reproducing the flash of the wrong theme on first load.</p>
    </MessageReasoningStep>

    <MessageReasoningStep label="Searching the codebase">
      <MessageReasoningQueries>
        <MessageReasoningQuery>useTheme localStorage</MessageReasoningQuery>
        <MessageReasoningQuery>suppressHydrationWarning</MessageReasoningQuery>
      </MessageReasoningQueries>
    </MessageReasoningStep>

    <MessageReasoningStep label="Reading the docs">
      <MessageReasoningSources>
        <MessageReasoningSource href="https://nextjs.org" />
        <MessageReasoningSource href="https://react.dev" />
        <MessageReasoningSource href="#" favicon="">+10 more</MessageReasoningSource>
      </MessageReasoningSources>
    </MessageReasoningStep>

    <MessageReasoningStep label="Reviewing sources · 2" status="active">
      <MessageReasoningSources layout="list">
        <MessageReasoningSource
          href="https://nextjs.org"
          title="Avoiding a theme hydration mismatch"
        />
        <MessageReasoningSource
          href="https://react.dev"
          title="You Might Not Need an Effect"
        />
      </MessageReasoningSources>
    </MessageReasoningStep>
  </MessageReasoningContent>
</MessageReasoning>
```

## API reference

### Conversation

The scrollable thread viewport (`role="log"`, a polite live region, so appended turns are announced). A flex column with a gap; set a height or max-height to make it scroll. `variant` (`"plain"` default, `"bubble"`) sets the style for every turn inside. `stickToBottom` (default `true`) follows new turns, pinning the viewport to the newest message as the thread grows, and only while the reader is already at the bottom, so scrolling up to reread history is never yanked back down. Turn it off for a static transcript that should open at the top. Forwards all native `div` props.

### Message

One turn. `role?: "assistant" | "user"` (default `"assistant"`) drives alignment and bubble tint, and flows to every part through context. `variant` overrides the conversation default for this turn.

### MessageAvatar

Wraps our `Avatar`. Takes `src` or `name` (initials fallback) plus any Avatar prop (e.g. `size`); children override the fallback, for example with an icon.

### MessageBody · MessageHeader · MessageName · MessageTime · MessageContent

`MessageBody` is the vertical column that aligns to the message side; `MessageContent` is the bubble (markup-agnostic). Header, Name, and Time are the optional meta row above the bubble.

### MessageActions · MessageAction · MessageTyping

`MessageAction` is a ghost icon `Button` (all Button props apply, and the `aria-label` drives both the name and a tooltip); `MessageTyping` is the three-dot streaming indicator.

### MessageReasoning · MessageReasoningTrigger · MessageReasoningContent

The collapsible thinking block (Radix Collapsible). `MessageReasoning` takes `streaming` (pulses the icon, defaults the label to “Thinking…”) plus Collapsible's `open` / `defaultOpen` / `onOpenChange`. The trigger's children are the label; the content holds the chain of thought behind a left rail.

### MessageReasoningStep · MessageReasoningQueries · MessageReasoningQuery

`MessageReasoningStep` is one phase of an agentic reasoning log. `label` captions it, `status?: "active" | "done"` (default `"done"`) turns the rail dot into a brand pulse, and `marker={false}` drops the dot. `MessageReasoningQuery` is a monospace search pill; wrap several in a `MessageReasoningQueries` row.

### MessageReasoningSources · MessageReasoningSource

`MessageReasoningSources` groups the consulted URLs. `layout?: "chips" | "list"` (default `"chips"`) switches between compact domain pills and a bordered title list, and flows to each source through context. `MessageReasoningSource` takes a required `href` (the domain and favicon derive from it), an optional `title` for the list layout, and an optional `favicon` override (it falls back to a globe glyph). It renders an anchor that opens in a new tab.

## FAQ

### What does the role prop on Message control?

role is the only switch: assistant aligns left with an avatar and a muted bubble, while user aligns right with a solid blue bubble. The value flows to every part through context, and both bubbles use a soft, uniform radius on all four corners.

### What is the difference between the plain and bubble variants?

plain is the default document style: the assistant answer renders as a page with no bubble, avatar, or identity, like Notion or ChatGPT. bubble is the with-identity look where every turn is a chat bubble and you pair the assistant with a MessageAvatar. Set it on Conversation for the whole thread, or per Message to override.

### How do I show a streaming response?

Drop a MessageTyping inside a MessageContent while the response streams. It renders three dots that ripple left to right, and holds still under reduced-motion. For the thinking phase, keep MessageReasoning open with streaming set, then collapse it to a summary once done.

### How do I render markdown inside a message?

MessageContent is markup-agnostic, so pass plain text or your own rendered markdown. The bubble styles paragraphs, headings, lists, inline code, pre blocks, and links via descendant selectors, tinted to read on either bubble.

### How do I show the searches and sources the model used?

Inside MessageReasoningContent, group each phase in a MessageReasoningStep. Put the searches it ran in MessageReasoningQuery pills, and the URLs it consulted in MessageReasoningSource. Sources are favicon and domain chips by default, or set layout="list" on MessageReasoningSources for favicon, title, and domain rows.

### Where do the source domain and favicon come from?

Both are derived from the source href: the domain is the hostname with any leading www stripped, and the favicon defaults to a service icon for that domain, falling back to a globe glyph if it is missing or fails to load. Pass title to set the list headline, or favicon to override the icon.

### Does the thread announce new messages to screen readers?

Yes. Conversation is the scrollable viewport with role="log" and a polite live region, so appended messages are announced. Set a height or max-height on it to make it scroll.

### Does the thread scroll to the newest message on its own?

Yes. Conversation ships stickToBottom on by default: it pins the viewport to the newest turn as the thread grows, instantly on the first paint and smoothly after it, and it honors prefers-reduced-motion. It only follows while you are already within about a bubble's height of the bottom, so scrolling up to reread history is never interrupted. Pass stickToBottom={false} for a static transcript that should open at the top.

### How do the action buttons work?

MessageActions holds a row of MessageAction buttons, each a ghost icon Button, so all Button props apply and the aria-label drives both the accessible name and a tooltip. Use them for copy, regenerate, and feedback.

---

<!-- https://www.koalaui.com/docs/components/generation.md -->

# Generation

The card a model fills while it paints a picture. The frame is sized by its ratio before there is anything to put in it, so nothing jumps, and the picture comes in from the top out of a halftone field of dots.

```tsx
<Generation status={done ? "complete" : "generating"} progress={progress} ratio="landscape">
  <GenerationHeader>
    <GenerationIcon><ImageSquare weight="bold" /></GenerationIcon>
    <GenerationLabel>Image</GenerationLabel>
    <GenerationStatus />
  </GenerationHeader>

  <GenerationPrompt lines={2}>{prompt}</GenerationPrompt>

  <GenerationCanvas>
    {/* Mounted while it generates: the reveal is what brings it in */}
    <GenerationImage src={src} alt={alt} />
    <GenerationCaption>{null}</GenerationCaption>
    <GenerationPercent />
    <GenerationOverlay>
      <GenerationActions>
        <GenerationAction tone="onMedia" aria-label="Open full size">
          <ArrowsOut weight="bold" />
        </GenerationAction>
        <GenerationAction tone="onMedia" aria-label="Download image">
          <DownloadSimple weight="bold" />
        </GenerationAction>
      </GenerationActions>
    </GenerationOverlay>
  </GenerationCanvas>

  <GenerationFooter>
    <GenerationMeta>Flux 1.1 · 1536×1152</GenerationMeta>
    <Button variant="ghost" size="sm" onClick={regenerate}>Regenerate</Button>
  </GenerationFooter>
</Generation>
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add generation
```

Manual: run `npm install radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/generation/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

```tsx title="usage.tsx"
import {
  Generation,
  GenerationHeader,
  GenerationIcon,
  GenerationLabel,
  GenerationStatus,
  GenerationActions,
  GenerationAction,
  GenerationPrompt,
  GenerationCanvas,
  GenerationImage,
  GenerationCaption,
  GenerationProgress,
  GenerationPercent,
  GenerationOverlay,
  GenerationGrid,
  GenerationFooter,
  GenerationMeta,
} from "@/components/ui/generation"

export function Example() {
  return (
    <Generation status="generating" progress={62} ratio="square">
      <GenerationHeader>
        <GenerationIcon><ImageSquare weight="bold" /></GenerationIcon>
        <GenerationLabel>Image</GenerationLabel>
      </GenerationHeader>

      <GenerationPrompt lines={2}>A valley at first light…</GenerationPrompt>

      <GenerationCanvas>
        <GenerationImage src={src} alt={alt} />
        <GenerationCaption />
        <GenerationProgress />
      </GenerationCanvas>

      <GenerationFooter>
        <GenerationMeta>Flux 1.1 · 1024×1024</GenerationMeta>
      </GenerationFooter>
    </Generation>
  )
}
```

## Anatomy

Four blocks, in reading order. An eyebrow says what kind of card this is (`GenerationIcon` + `GenerationLabel`, with a `GenerationStatus` chip or `GenerationActions` trailing). A `GenerationPrompt` quotes back what you asked for. The `GenerationCanvas` is the frame everything happens inside. A footer carries the meta and whatever you do next.

The frame never resizes. You know how big a picture will be long before you know what is in it, so the canvas takes its ratio up front: the card stands at its final height from the first frame, and nothing below it jumps when the bytes land. The picture is inset 8px from the card's edge with the radius that follows from it (24 − 8 = 16), the same geometry `CardMedia` uses, so the copy keeps its own, wider measure and the photograph reads as framed rather than as a header band.

```tsx
{/* See the Usage block above. */}
```

## The reveal

Mount the `GenerationImage` as soon as you have a URL, not when you are finished. Everything below it sits under a halftone screen whose holes open as `progress` climbs. At 62% you are looking at the picture through a plate that is 62% open — everywhere at once, the way a halftone resolves when you step back from it. The percentage stops being a number beside the picture and becomes the picture.

It glides rather than marches. The reveal is a registered custom property (`--generation-reveal`), which means a percentage that CSS can interpolate: a model reporting 40 → 62 → 100 reads as one continuous movement, and finishing just carries the number to 100, so the last stretch wipes in instead of cutting. Report no percentage at all and there is nothing to wipe to — the frame simply works at full size and a bar goes indeterminate, which is the honest reading.

The screen is the frame's own ground with two layers of one 12px dot grid drawn on it — small dots everywhere, large ones in the middle — breathing on a registered `--generation-dot` radius, so the plate swells and settles like something being worked on. The holes are punched half a cell off the dots, so they open *between* them and the dots are the last thing left standing. It is the part the frame keeps for itself: nothing to compose, nothing to remember to remove.

Nothing sweeps, nothing is tinted, and nothing travels in a direction. A shimmer passing over the frame, a blurred veil, a brand-coloured field, a lit hairline and a top-to-bottom wipe were each built and each thrown out: every one read as an effect laid over the work rather than as the work. A line crossing a picture reads as a scanner passing over it. The dots are plain ink at 30%, so they re-theme by themselves and leave the picture as the only coloured thing in the card.

Drag the percentage below to take the reveal at your own pace. Note the demo sets `transition="none"`: a frame driven continuously — a slider under your finger, a stream reporting every frame — shouldn't ease, or it trails a third of a second behind you and reads as lag. It is the same axis, for the same reason, that `Progress` carries.

```tsx
// The picture goes in while it is still generating — that is the point.
<Generation
  status={progress >= 100 ? "complete" : "generating"}
  progress={progress}
  ratio="landscape"
  transition="none"
>
  <GenerationCanvas>
    <GenerationImage src={src} alt={alt} />
    <GenerationCaption>{null}</GenerationCaption>
    <GenerationProgress />
  </GenerationCanvas>
  <GenerationFooter>
    <GenerationMeta>Flux 1.1 · {Math.round(progress)}% painted</GenerationMeta>
  </GenerationFooter>
</Generation>

<Slider value={[progress]} onValueChange={([v]) => setProgress(v)} />
```

## States

One `status` on the root moves the whole card: `idle` → `generating` → `complete`, or `failed`. Only the frame changes. While it works, the halftone screen sits over the picture and breathes; as the percentage climbs its holes open, and at 100% there is no plate left — the frame simply holds a photograph.

The state parts know when they aren't wanted. `GenerationCaption` and `GenerationProgress` render nothing once the picture is there; `GenerationOverlay` renders nothing until it is. Not hidden, not transparent — not in the DOM. So you leave all three in your markup unconditionally and never write a ternary around them.

```tsx
{/* idle · generating · complete · failed — the same markup in all four */}
<Generation status={status} progress={62} ratio="landscape" density="compact">
  <GenerationHeader>
    <GenerationIcon><ImageSquare weight="bold" /></GenerationIcon>
    <GenerationLabel>Image</GenerationLabel>
    <GenerationStatus />
  </GenerationHeader>
  <GenerationCanvas>
    {src ? <GenerationImage src={src} alt={alt} /> : null}
    <GenerationCaption />
    <GenerationProgress />
    <GenerationOverlay>
      <GenerationAction tone="onMedia" aria-label="Download image">
        <DownloadSimple weight="bold" />
      </GenerationAction>
    </GenerationOverlay>
  </GenerationCanvas>
  <GenerationFooter>
    <GenerationMeta>{meta}</GenerationMeta>
  </GenerationFooter>
</Generation>
```

## Variations

`GenerationGrid` lays a batch out as a contact sheet, two to four across. Each `GenerationCanvas` takes its own `status`, because a real batch comes back one tile at a time — so each frame keeps its own shimmer and settles when it is ready. Tiles land a beat apart rather than all at once, which is the difference between a sheet developing and four boxes appearing.

```tsx
<GenerationGrid columns={2}>
  {renders.map((render, i) => (
    <GenerationCanvas key={render.src} status={i < landed ? "complete" : "generating"}>
      {i < landed ? <GenerationImage src={render.src} alt={render.alt} /> : null}
      {/* null children: no room for words on a 120px tile */}
      <GenerationCaption>{null}</GenerationCaption>
      <GenerationOverlay>
        <GenerationAction tone="onMedia" aria-label={`Download variation ${i + 1}`}>
          <DownloadSimple weight="bold" />
        </GenerationAction>
      </GenerationOverlay>
    </GenerationCanvas>
  ))}
</GenerationGrid>
```

## Ratios

`ratio` on the root sizes the hero frame and every tile of a sheet at once: `square`, `portrait` (3:4), `landscape` (4:3), `wide` (16:9), `tall` (9:16), or `auto` when the height comes from the layout around it. A single `GenerationCanvas` can overrule it — a landscape hero over a square sheet is the common pair.

```tsx
<Generation ratio="square">…</Generation>
<Generation ratio="portrait">…</Generation>
<Generation ratio="wide">…</Generation>

{/* One frame out of step with the rest */}
<GenerationCanvas ratio="landscape">…</GenerationCanvas>
```

## In a chat turn

`variant="plain"` drops the ring, the shadow and the gutter so a generation sits inside a `Chat` turn or an `AIPanel` body as part of the answer rather than as a card inside a card. The picture then takes the full measure of the turn: there is nothing left for it to be inset from, so the inset lets go too.

```tsx
<Message role="assistant">
  <MessageContent>
    Here's the valley at first light.
    <Generation variant="plain" ratio="landscape" className="mt-3">
      <GenerationCanvas>
        <GenerationImage src={src} alt={alt} />
      </GenerationCanvas>
      <GenerationFooter>
        <GenerationMeta>Flux 1.1 · 1536×1152 · 6.2s</GenerationMeta>
      </GenerationFooter>
    </Generation>
  </MessageContent>
</Message>
```

## API reference

Generation

The root and the provider. Takes `status?: "idle" | "generating" | "complete" | "failed"` (default `complete`), `progress?: number | null` (percent, or `null` for a model that reports none), `ratio`, `variant?: "card" | "plain"`, `transition?: "smooth" | "none"` (how the reveal reacts to a new percentage), `density` and `asChild`. Sets `aria-busy` while generating.

GenerationCanvas

The frame. Takes its own `ratio`, `status` and `progress` to overrule the root for one frame — which is how a sheet of variations comes in tile by tile, each at its own pace. It owns the halftone screen, the edge ring over the picture, and it pins a `GenerationProgress` dropped inside it to the bottom edge.

GenerationImage

The picture, under the screen: it fades up as its bytes decode, and the screen over it opens as the percentage climbs. Mount it as soon as you have a URL, not when you are finished. Change the `src` and it all happens again, so a regenerate reads as the same frame being re-exposed. Forwards all `img` props; a cached image that was already complete before React saw it still fades in rather than staying blank.

GenerationCaption / GenerationPercent / GenerationProgress / GenerationOverlay

The parts that come and go with the state, none of which needs a ternary around it. `GenerationCaption` is the line inside an empty frame, with the glyph its state implies — pass `null` for a thumbnail with no room for words. Then pick *one* readout: `GenerationPercent`, a chip in the corner of the frame (a Badge in the overlay tone, so it holds on a photograph), or `GenerationProgress`, a hairline pinned to the bottom edge that composes `Progress` and so inherits the indeterminate sweep. A bar and a number saying the same thing is the same news twice. `GenerationOverlay` holds the tools that arrive over a finished picture, and reveals on touch as well as hover.

GenerationGrid

A sheet of frames, `columns?: 2 | 3 | 4` (default 2, and two columns hold on a phone). It staggers its tiles' entrances in CSS, so nothing is cloned onto the children.

Layout parts

`GenerationHeader`, `GenerationIcon`, `GenerationLabel`, `GenerationStatus` (a Badge derived from the root's status), `GenerationActions` / `GenerationAction` (a ghost icon `Button` wrapper — pass `tone="onMedia"` over a picture), `GenerationPrompt` (takes `lines?: 1 | 2 | 3`), `GenerationFooter` and `GenerationMeta`. Every part is droppable: a generation renders correctly with any subset of them.

## FAQ

### Why does the frame need a ratio before there is an image?

Because that is the one thing you already know. A generation is a wait with a shape: the model was told to paint 1024×1024 before it painted anything. If the frame waited for the bytes, the card would grow around the picture and everything under it — the meta, the buttons, the rest of the conversation — would jump at the exact moment you finally had something to look at. Taking the ratio up front costs nothing and buys a card that never moves.

### Why does the picture come through a screen instead of just fading in?

Because a fade tells you nothing and a wait with no shape is the worst part of generating an image. Opening a halftone plate ties the percentage to something you can actually see, and it does it without direction: at 62% you are looking through a plate that is 62% open, everywhere at once. A top-to-bottom wipe was built first and thrown out — a line crossing the picture reads as a scanner passing over it rather than as an image being made.

### Why mount the image before the generation finishes?

Because the screen has nothing to open onto otherwise. Put the GenerationImage in as soon as you have a URL and the frame does the rest: the plate covers it, its holes widen with progress, and finishing just carries the number to 100. If you only mount it at the end you get a plain fade-in, which is still fine, just quieter.

### The reveal lags behind my slider. Why?

Because it is eased by default, which is what you want for a model reporting 12% at a time and what you don't want when something is dragging it continuously. Pass transition="none" and the reveal is welded to the number. It is the same axis, for the same reason, that Progress carries.

### The model doesn't report a percentage. What do I do?

Leave progress alone. Its default is null, which the frame reads as nothing to open to — the picture is simply there once it decodes — and which Progress reads as indeterminate, so a bar sweeps instead of implying a number nobody has. Don't fake a climb: a plate that opens to 80% and then sits there is worse than one that never claimed to know.

### Can each tile of a grid finish on its own?

Yes, and that is the point of a per-canvas status. A real batch comes back one at a time, so each GenerationCanvas takes its own status and keeps its own shimmer; the root's status then describes the batch as a whole. Because every frame was already the right size, the sheet fills in without a single reflow.

### Why is there no lightbox built in?

Because Koala already has one. Put a LightboxTrigger or your own button in the GenerationOverlay and wire it to Gallery's Lightbox — the overlay is a plain slot for exactly that, and building a second lightbox into this card would be a component re-implementing another one's job.

### Can I put a generation inside a chat message?

Yes, that's what variant="plain" is for. It drops the ring, the shadow and the gutter so the picture sits in the turn as part of the answer rather than as a card inside a card, and the media inset lets go with them since there is no longer a card edge to be inset from.

### Is it accessible?

The root sets aria-busy while it generates, so a screen reader is told the card is working rather than being re-read on every percent. The progress hairline is a real Radix progressbar with an accessible name. The dot field, the edge ring and the caption glyph are decoration and are aria-hidden; the caption's words are not. Overlay tools are icon-only Buttons, which require an aria-label and get a tooltip from it, and they stay visible on keyboard focus and on a coarse pointer, where hover-to-reveal would otherwise hide them for good.

### Will it adapt to dark and the other themes?

Yes, and there is very little colour to re-theme. The dot field is plain foreground ink at 30%, the ground is muted and the chips are the DS's own tones, so the whole frame follows light, dark, cream and moonlight by itself. The one deliberate exception is the image edge ring, which is pure black at 10% in light and pure white at 10% in dark: a tinted neutral there picks up the surface underneath and reads as dirt on the picture's edge.

---

<!-- https://www.koalaui.com/docs/components/plan.md -->

# Plan

The card an assistant hands you before it acts: what it intends to do, as a short list of to-dos you can read, edit and approve. Deliberately quiet, so status lives in a small mark at the head of each row.

```tsx
<Plan status={status}>
  <PlanHeader>
    <PlanIcon><ListChecks weight="bold" /></PlanIcon>
    <PlanLabel>Plan overview</PlanLabel>
    <PlanActions>
      <Button variant="ghost" size="sm" iconOnly aria-label="Regenerate plan">
        <ArrowsClockwise weight="bold" />
      </Button>
    </PlanActions>
  </PlanHeader>

  <PlanHeading>
    <PlanTitle>Marketing site analytics</PlanTitle>
    <PlanDescription>
      Replace the legacy tracking with a consented, typed event schema.
    </PlanDescription>
  </PlanHeading>

  <PlanGroup>
    <PlanGroupHeader>
      <PlanGroupTitle>To-dos</PlanGroupTitle>
      <PlanGroupCount>6</PlanGroupCount>
    </PlanGroupHeader>
    <PlanSteps>
      <PlanStep status="done">
        <PlanStepContent>
          <PlanStepTitle>Audit the current tracking setup</PlanStepTitle>
        </PlanStepContent>
      </PlanStep>
      {/* …more to-dos */}
    </PlanSteps>
    <PlanMore expanded={open} count={3} onClick={() => setOpen(!open)} />
  </PlanGroup>

  <PlanFooter>
    <PlanSummary>6 to-dos · about 6 min</PlanSummary>
    <div className="flex items-center gap-1">
      <Button variant="ghost" size="sm" onClick={regenerate}>Regenerate</Button>
      <Button size="sm" onClick={() => setStatus("running")}>Approve</Button>
    </div>
  </PlanFooter>
</Plan>
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add plan
```

Manual: run `npm install radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/plan/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

```tsx title="usage.tsx"
import {
  Plan,
  PlanHeader,
  PlanIcon,
  PlanLabel,
  PlanActions,
  PlanHeading,
  PlanTitle,
  PlanDescription,
  PlanStatus,
  PlanGroup,
  PlanGroupHeader,
  PlanGroupTitle,
  PlanGroupCount,
  PlanSteps,
  PlanStep,
  PlanStepContent,
  PlanStepTitle,
  PlanStepDescription,
  PlanStepTrigger,
  PlanStepDetail,
  PlanTasks,
  PlanTask,
  PlanStepAction,
  PlanStepEdit,
  PlanStepInput,
  PlanStepSkeleton,
  PlanAddStep,
  PlanMore,
  PlanFooter,
  PlanSummary,
} from "@/components/ui/plan"

export function Example() {
  return (
    <Plan status="review">
      <PlanHeader>
        <PlanIcon><ListChecks weight="bold" /></PlanIcon>
        <PlanLabel>Plan overview</PlanLabel>
      </PlanHeader>
      <PlanHeading>
        <PlanTitle>Refresh the pricing page</PlanTitle>
      </PlanHeading>
      <PlanGroup>
        <PlanGroupHeader>
          <PlanGroupTitle>To-dos</PlanGroupTitle>
          <PlanGroupCount>3</PlanGroupCount>
        </PlanGroupHeader>
        <PlanSteps>
          <PlanStep>
            <PlanStepContent>
              <PlanStepTitle>Pull the three current tiers</PlanStepTitle>
            </PlanStepContent>
          </PlanStep>
          {/* …more to-dos */}
        </PlanSteps>
      </PlanGroup>
      <PlanFooter>
        <PlanSummary>3 to-dos · about 2 min</PlanSummary>
        <Button size="sm">Approve</Button>
      </PlanFooter>
    </Plan>
  )
}
```

## Anatomy

Four blocks, in reading order. An eyebrow says what kind of card this is (`PlanIcon` + `PlanLabel`, with `PlanActions` trailing). A heading says what the plan will do. A `PlanGroup` holds the work as a flat list under its own quiet label and count. A footer carries the meta and the decision — ghost on the left, primary on the right, per the house rule.

The card is the only container. Nothing inside it is boxed again and there are no dividers: groups are made by a label and whitespace, the way the Accordion's `minimal` variant makes rows. A panel inside a card reads as a slab in the dark themes and as a redundant line in the light ones, and every row shares the card's own left edge, so a plan has exactly one text axis from the eyebrow down to the footer. Every block is droppable.

```tsx
{/* See the Usage block above. */}
```

## To-do states

Each `PlanStep` carries a `status`, and that mark plus one step of ink is the whole of its styling: a dashed ring while it waits, a brand spinner while it runs, a green check once it's done, a red warning when it isn't. Only the live row goes to full ink; a finished one fades back. No row fill, no rail, no numerals — a column of solid circles reads as a diagram, and this is a paragraph you happen to be able to click.

```tsx
<PlanSteps>
  <PlanStep status="done">…</PlanStep>
  <PlanStep status="active">…</PlanStep>
  <PlanStep status="failed">
    <PlanStepContent>
      <PlanStepTitle>Attach the screenshots</PlanStepTitle>
    </PlanStepContent>
    <PlanStepAction>
      <Button variant="ghost" size="sm">Retry</Button>
    </PlanStepAction>
  </PlanStep>
  <PlanStep>…</PlanStep>
</PlanSteps>
```

## Collapsible to-dos

Give a to-do `collapsible` and its `PlanStepTrigger` unfolds a `PlanStepDetail` with the sub-tasks it breaks down into. It wraps Radix Collapsible, so keyboard and ARIA come for free, and the panel opens on the DS collapsible keyframes. A plan mixes both shapes freely: rows with nothing to show stay plain. Sub-tasks are marked with a dash rather than a ring and sit a step quieter, so an unfolded row can never be mistaken for more to-dos of the plan itself.

```tsx
<PlanStep collapsible defaultOpen status="active">
  <PlanStepContent>
    <PlanStepTrigger>
      <PlanStepTitle>Convert each entry to MDX</PlanStepTitle>
    </PlanStepTrigger>
    <PlanStepDetail>
      <PlanTasks>
        <PlanTask done>Port the frontmatter</PlanTask>
        <PlanTask>Move the images into public/changelog</PlanTask>
      </PlanTasks>
    </PlanStepDetail>
  </PlanStepContent>
</PlanStep>

{/* Nothing to unfold: stay a plain row. */}
<PlanStep>
  <PlanStepContent>
    <PlanStepTitle>Redirect the old URLs</PlanStepTitle>
  </PlanStepContent>
</PlanStep>
```

## Read-only, then edit

A plan is read-only by default. That is how it's looked at nine times out of ten: you read what the assistant proposes and approve it. Editing is a mode you deliberately enter, so `PlanStepEdit` and `PlanAddStep` render nothing at all — not hidden, not transparent, not in the DOM — until the root gets `editing`. Leave them in your markup unconditionally and let the one flag decide; no call site can leave half the card in the wrong mode.

Inside edit mode, every row is already a field — there is no pencil to press first, because a pencil whose only job is to focus the input sitting under it is a button that shouldn't exist. Render a `PlanStepInput` in place of each `PlanStepTitle`: it inherits the row's type *and its resting tone* and paints no frame, so the rows sit exactly where they sat, in the ink they were in, and simply start taking keys. Ink arrives on the one you reach for or land in. The field grows with the copy, Escape cancels, and Enter is yours to wire — the demo opens the next to-do with it, the way every list editor behaves.

That leaves `PlanStepEdit` holding one button: remove. It fades in with the pointer — six rows each carrying a trash can is a toolbar, not a plan — but never away from the keyboard or from a touch screen. It is also out of the row's flow, which matters more than it sounds: in flow, a 32px button is taller than a 20px line, so every single-line to-do would grow to the button's height while a wrapped one stayed taller and the rhythm would fall apart the moment you pressed Edit. Instead the row reserves one uniform 36px gutter for it, so the list is sized by its copy in both modes.

```tsx
<Plan status="review" editing={editing}>
  <PlanGroup>
    <PlanSteps>
      <PlanStep>
        <PlanStepContent>
          {editing ? (
            <PlanStepInput
              autoFocus={focusId === step.id}
              value={step.title}
              onValueChange={(value) => setTitle(step.id, value)}
              // Enter is yours: open the next to-do instead of committing this one,
              // which the field already wrote straight to state.
              onKeyDown={(event) => {
                if (event.key === "Enter" && !event.shiftKey) {
                  event.preventDefault()
                  addAfter(step.id)
                }
              }}
              onCommit={(value) => { if (!value.trim()) remove(step.id) }}
              placeholder="Describe the to-do…"
              aria-label="To-do"
            />
          ) : (
            <PlanStepTitle>{step.title}</PlanStepTitle>
          )}
        </PlanStepContent>

        {/* Renders nothing at all while the plan is read-only. */}
        <PlanStepEdit>
          <Button variant="destructiveGhost" size="sm" iconOnly aria-label="Remove" onClick={() => remove(step.id)}>
            <Trash weight="bold" />
          </Button>
        </PlanStepEdit>
      </PlanStep>
    </PlanSteps>

    <PlanAddStep onClick={addStep} />
  </PlanGroup>

  <PlanFooter>
    <PlanSummary>{steps.length} to-dos · about 2 min</PlanSummary>
    {editing ? (
      <Button size="sm" onClick={() => setEditing(false)}>Done</Button>
    ) : (
      <>
        <Button variant="ghost" size="sm" onClick={() => setEditing(true)}>Edit</Button>
        <Button size="sm">Approve</Button>
      </>
    )}
  </PlanFooter>
</Plan>
```

## Long lists and drafting

A plan is something you scan, so a long one opens at a readable length and offers the rest: `PlanMore` is the row that closes the panel — “3 more” collapsed, “Show less” open. Which rows you actually render is yours; this is the control and the label.

While the model is still writing, drop `PlanStepSkeleton` rows in. They keep the list's exact geometry — the same mark column, the same row height — so the real to-dos land in place instead of pushing the panel around when they arrive. Vary `width` across rows so a draft reads organic rather than striped, and each row that mounts while the plan is `drafting` plays the DS entrance, which is all the cascade a stream needs: rows arrive one at a time already.

```tsx
{/* Collapsed to a preview */}
<PlanSteps>{visible.map(…)}</PlanSteps>
<PlanMore expanded={open} count={3} onClick={() => setOpen(!open)} />

{/* Still drafting */}
<PlanSteps>
  <PlanStepSkeleton />
  <PlanStepSkeleton width="short" />
  <PlanStepSkeleton width="long" />
</PlanSteps>
```

## Status chip

`PlanStatus` derives its chip from the root's `status`, so a label and a state can never drift apart, and the root sets `aria-busy` while the plan is still moving. It is optional on purpose: in the quiet default the eyebrow says what the card is and the footer says what happens next, and a chip on top of both is one badge too many. Reach for it when a plan sits in a feed where it has to announce itself.

```tsx
<PlanHeader>
  <PlanIcon><ListChecks weight="bold" /></PlanIcon>
  <PlanLabel>Plan overview</PlanLabel>
  <PlanStatus />   {/* "Drafting" · "Ready for review" · "Running" · "Complete" · "Failed" */}
</PlanHeader>
```

## Inside a conversation

Set `variant="plain"` for a plan the assistant hands back inside a Chat turn or an AI Panel body. It drops the ring, the lift and the gutter, so the plan reads as part of the answer instead of a card inside a card. The panel keeps its own edge, which is all the structure the turn needs.

```tsx
<Message role="assistant">
  <MessageContent>
    <p>Here's how I'd approach it. Say the word and I'll start.</p>
    <Plan variant="plain" status="review" className="mt-4">
      <PlanGroup>…</PlanGroup>
      <PlanFooter>
        <PlanSummary>3 to-dos · about 4 min</PlanSummary>
        <Button size="sm">Approve</Button>
      </PlanFooter>
    </Plan>
  </MessageContent>
</Message>
```

## Density

Like Card and Dialog, the Plan reads the density context (or a `density` prop). Here it tunes the row rhythm and the block gaps only. The card's 12px gutter and the panel's 4px inset are the concentric ladder — they set the panel's and the rows' corners — so they are fixed in both tiers, because a gutter that moves with density breaks that nesting in one of them.

```tsx
<Plan density="comfortable" status="running">…</Plan>
<Plan density="compact" status="running">…</Plan>
```

## API reference

Plan

The root card and the context provider. Forwards all `div` props.

- `status?: "drafting" | "review" | "running" | "complete" | "failed"` — the plan's own state. Drives `PlanStatus`, the row entrance and `aria-busy`. Defaults to `"review"`.
- `editing?: boolean` — put the card in edit mode. A plan is read-only by default; `PlanStepEdit` and `PlanAddStep` render nothing until this is on. Also exposed as `data-editing`.
- `variant?: "card" | "plain"` — `card` is the standalone artifact; `plain` drops the chrome and the gutter for a plan rendered inside a Chat turn or an AI Panel.
- `density?: "comfortable" | "compact"` — row rhythm and block gaps; defaults from the density context.
- `asChild?: boolean` — render as a child element via Radix Slot.

PlanStep

- `status?: "pending" | "active" | "done" | "failed"` — the row's 14px mark and its ink. Defaults to `"pending"`.
- `collapsible?: boolean` plus `open` / `defaultOpen` / `onOpenChange` — turns the row into a Radix Collapsible whose trigger is `PlanStepTrigger` and whose panel is `PlanStepDetail`.

PlanStepAction / PlanStepEdit

Two trailing slots with different lifetimes. `PlanStepAction` is what the row is *telling* you — a duration, a Badge, a Retry on a failed row — and is always visible. `PlanStepEdit` is what you can *do* to the row — in practice one Remove button, since every row is already a field in edit mode — renders nothing unless the plan is `editing`, and fades in with the pointer (staying visible on keyboard focus and on a coarse pointer, where there is no hover).

PlanStepInput

The inline editor that replaces a row's title while the plan is editing — every row at once, so there is no rename button. It inherits the row's type and resting tone, so flipping the mode changes nothing on screen. Controlled: `value` + `onValueChange`, with `onCommit` (Enter or blur) and `onCancel` (Escape). Shift+Enter still breaks a line and an open IME composition is never hijacked. Forwards all `textarea` props.

PlanMore / PlanAddStep

The two rows that close a list, both forwarding all `button` props. `PlanMore` takes `expanded?: boolean` and `count?: number` and labels itself “3 more” / “Show less”. `PlanAddStep` renders nothing unless the plan is `editing`.

PlanStepSkeleton

The placeholder row for a plan still being written. Takes `width?: "full" | "long" | "short"` so a draft reads organic.

Layout parts

`PlanHeader`, `PlanIcon`, `PlanLabel`, `PlanActions`, `PlanHeading`, `PlanTitle` (takes `asChild`), `PlanDescription`, `PlanGroup` + `PlanGroupHeader` / `PlanGroupTitle` / `PlanGroupCount`, `PlanSteps`, `PlanTasks` / `PlanTask`, `PlanFooter` and `PlanSummary`. Every part is droppable: a plan renders correctly with any subset of them.

## FAQ

### Why are there no numbers on the to-dos?

Because a numbered column of filled discs reads as a diagram, and an approval card is something you scan in a second. The list is a semantic ordered list, so position and count are still announced by a screen reader; visually, the only mark a row carries is the 14px status glyph at its head. If a plan genuinely needs visible ordering, the group title and count carry it.

### What's the difference between the plan's status and a to-do's status?

They're different scopes and deliberately different words. The plan moves drafting to review to running to complete (or failed); a to-do is pending, active, done or failed. The plan's status drives the optional header chip, the aria-busy state and the entrance each new row plays. A to-do's status is its mark and one step of ink, nothing more.

### Why is edit a mode instead of always-on hover buttons?

Because a plan is read far more often than it is rewritten, and controls you can trip over change what the card is. Hover-revealed pencils on every row turn a plan into a toolbar, and on a touch screen they either sit there permanently or can't be reached at all. One editing flag on the root keeps reading clean, makes the switch explicit, and means no call site can leave half the card in the wrong mode. Once you are in that mode there is no pencil either: every row is already a PlanStepInput, so you type over the to-do directly and only Remove stays as a button.

### Why no progress bar?

A plan is short and its rows already say where it is: the finished ones check off and fade back, the live one is the only line at full ink. A labeled bar with a derived X-of-Y count is Checklist's job — reach for that when the list is a set of tasks a person works through rather than a plan an assistant runs.

### Can I have more than one panel?

Yes. PlanGroup is a composed part rather than something the root puts up on its own, precisely so an agent card can list to-dos in one panel and files or commands in another, each with its own title and count. Stack as many as the card needs; they inherit the same row geometry.

### Can I put a plan inside a chat message?

Yes, that's what variant="plain" is for. It drops the ring, the shadow and the gutter so the plan sits inside a Chat turn or an AI Panel body as part of the answer, not as a card inside a card. The panel keeps its own edge, which is all the structure the turn needs.

### Is it accessible?

The to-dos are an ordered list, so count and position are announced natively. Each row carries a data-status plus an sr-only label (Not started / In progress / Done / Failed) so its state is spoken, not only colored, and the mark itself is aria-hidden decoration. Collapsible rows are Radix Collapsible, so the trigger gets aria-expanded and the keyboard wiring for free, and the root sets aria-busy while the plan is drafting or running.

### Will it adapt to dark and the other themes?

Yes. Every color is a semantic token — brand, success, destructive, muted, border and edge — so the tinted glyph tile, the panel edge, the green checks and the status chip re-theme across light, dark, cream and moonlight automatically.

---

<!-- https://www.koalaui.com/docs/components/prompt-input.md -->

# Prompt Input

The AI composer: an auto-growing textarea with a built-in toolbar and a send or stop button. Wire onSubmit once and the textarea, model picker, count and submit stay in sync through context.

```tsx
<PromptInput loading={loading} onSubmit={send} onStop={stop}>
  <PromptInputTextarea placeholder="Ask Koala anything…" />
  <PromptInputToolbar>
    <AddMenu />
    <ModelPicker />
    <ToolsMenu />
    <div className="ml-auto flex items-center gap-0.5">
      <PromptInputButton iconOnly aria-label="Dictate">
        <Microphone />
      </PromptInputButton>
      <PromptInputSubmit className="ml-0" />
    </div>
  </PromptInputToolbar>
</PromptInput>
```

The bar is built out of our `Button`: an attach menu, the model picker, and a single tools dropdown (image, canvas, web / deep research, code) on the left, dictate and send on the right. Only one tool runs at a time, so the menu is single-select: picking one clears the others. The trigger names what's on, showing the active tool's icon and label rather than a generic `Tools` word. Every toolbar glyph renders at a consistent 20px, and the send button is an upward arrow that flips to a stop square while a response streams.

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add prompt-input
```

Manual: run `npm install tailwind-variants tailwind-merge @phosphor-icons/react`, then copy the source into `components/ui/prompt-input/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

```tsx title="usage.tsx"
import {
  PromptInput,
  PromptInputTextarea,
  PromptInputToolbar,
  PromptInputButton,
  PromptInputSubmit,
} from "@/components/ui/prompt-input"

export function Composer() {
  return (
    <PromptInput onSubmit={(value) => sendMessage(value)}>
      <PromptInputTextarea />
      <PromptInputToolbar>
        <PromptInputSubmit />
      </PromptInputToolbar>
    </PromptInput>
  )
}
```

The composer is uncontrolled by default: it owns its value and clears itself after a submit. `Enter` sends, `Shift+Enter` inserts a newline, and the field grows to fit its content up to a cap, then scrolls.

## Minimal

Same capabilities, quieter chrome: each group becomes its own compact icon dropdown (attachments, model, tools) so the bar is just icons plus send. Models are a radio group; the tools (image, canvas, web / deep research, code) are mutually exclusive, so picking one clears the rest (at most one active; their check sits on the right, the menu convention). Each trigger is a `static` icon-only `PromptInputButton`.

```tsx
<PromptInputToolbar>
  {/* Attachments */}
  <DropdownMenu>
    <DropdownMenuTrigger asChild>
      <PromptInputButton static iconOnly tooltip={false} aria-label="Add photos & files">
        <Plus />
      </PromptInputButton>
    </DropdownMenuTrigger>
    <DropdownMenuContent align="start">
      <DropdownMenuItem><Image /> Add photo</DropdownMenuItem>
      <DropdownMenuItem><Paperclip /> Add files</DropdownMenuItem>
    </DropdownMenuContent>
  </DropdownMenu>

  {/* Model */}
  <DropdownMenu>
    <DropdownMenuTrigger asChild>
      <PromptInputButton static iconOnly tooltip={false} aria-label="Model">
        <Sparkle />
      </PromptInputButton>
    </DropdownMenuTrigger>
    <DropdownMenuContent align="start">
      <DropdownMenuLabel>Model</DropdownMenuLabel>
      <DropdownMenuRadioGroup value={model} onValueChange={setModel}>
        <DropdownMenuRadioItem value="opus"><Sparkle /> Opus 4.8</DropdownMenuRadioItem>
        <DropdownMenuRadioItem value="sonnet"><Sparkle /> Sonnet 4.6</DropdownMenuRadioItem>
      </DropdownMenuRadioGroup>
    </DropdownMenuContent>
  </DropdownMenu>

  {/* Tools: image · canvas · web / deep research · code (single-select: at most one) */}
  <DropdownMenu>
    <DropdownMenuTrigger asChild>
      <PromptInputButton static iconOnly tooltip={false} aria-label="Tools">
        <SlidersHorizontal />
      </PromptInputButton>
    </DropdownMenuTrigger>
    <DropdownMenuContent align="start">
      <DropdownMenuLabel>Tools</DropdownMenuLabel>
      {/* one `tool` state; picking one clears the rest, re-picking it clears to null */}
      <DropdownMenuCheckboxItem checked={tool === "image"} onCheckedChange={(on) => setTool(on ? "image" : null)}>
        <Image /> Image
      </DropdownMenuCheckboxItem>
      <DropdownMenuCheckboxItem checked={tool === "deep"} onCheckedChange={(on) => setTool(on ? "deep" : null)}>
        <Binoculars /> Deep research
      </DropdownMenuCheckboxItem>
      {/* …canvas, web research, code */}
    </DropdownMenuContent>
  </DropdownMenu>

  <PromptInputSubmit />
</PromptInputToolbar>
```

## Sizes

Three sizes retune the field's padding, text, and min-height, and the send button scales with them. The surface radius stays constant (a brand trait). Set it once on the root with `size`.

```tsx
<PromptInput size="sm">…</PromptInput>
<PromptInput size="md">…</PromptInput>  {/* default */}
<PromptInput size="lg">…</PromptInput>
```

## Streaming (send ⇄ stop)

Pass `loading` while a response streams and the send button becomes a stop button that fires `onStop`. The toolbar holds plain `PromptInputButton` actions (Search, Reason) on the left; the submit claims the right edge automatically.

```tsx
<PromptInput defaultValue="Write a haiku about koalas." loading={loading} onSubmit={send} onStop={stop}>
  <PromptInputTextarea />
  <PromptInputToolbar>
    <PromptInputButton><Globe /> Search</PromptInputButton>
    <PromptInputButton><Brain /> Reason</PromptInputButton>
    <PromptInputSubmit />
  </PromptInputToolbar>
</PromptInput>
```

## Suggestions

Prompt-starter chips sit above the composer, filled in the `secondary` color so the row reads as one quiet set. Give each its own 20px glyph (not a generic sparkle) and let the shape do the differentiating. They're context-free on purpose: wire each `onClick` to set the prompt, submit, or both.

The row is a single line that scrolls, never one that wraps. A starter is usually a whole question, so on a phone even two of them are wider than the screen, and a chip cannot give width back: wrapped, the second one simply ran off the edge. Scrolled, the edge fades toward the starters you have not seen yet, and the fade is inert whenever they already fit.

```tsx
<PromptInputSuggestions>
  {suggestions.map(({ label, icon: Icon }) => (
    <PromptInputSuggestion key={label} onClick={() => setValue(label)}>
      <Icon /> {label}
    </PromptInputSuggestion>
  ))}
</PromptInputSuggestions>

<PromptInput value={value} onValueChange={setValue} onSubmit={clear}>
  <PromptInputTextarea />
  <PromptInputToolbar>
    <PromptInputSubmit />
  </PromptInputToolbar>
</PromptInput>
```

## Banner

A notice that tucks behind the composer for model availability, usage caps, or errors. The composer stays a complete rounded card on top and the banner slides *under* it, so only its outer edge peeks out. Drop the `PromptInputBanner` as a sibling of `PromptInput` in a `flex flex-col isolate` wrapper (the `isolate` keeps its negative z local), and add `shadow-md` to the composer so its shadow falls on the strip. `side` picks which edge it peeks from: `top` (banner *before* the composer) or `bottom` (banner *after*). No absolute positioning. `tone` tints the icon (`default` / `info` / `warning` / `destructive`); pass `onClose` for a dismiss button.

```tsx
<div className="flex flex-col isolate">
  {open && (
    <PromptInputBanner side="top" tone="warning" onClose={() => setOpen(false)}>
      Fable 5 is unavailable right now.
      <PromptInputBannerAction className="ml-auto">Learn more</PromptInputBannerAction>
    </PromptInputBanner>
  )}
  <PromptInput onSubmit={send} className="shadow-md">
    <PromptInputTextarea placeholder="How can I help you today?" />
    <PromptInputToolbar>
      <PromptInputButton iconOnly aria-label="Add photos & files">
        <Plus />
      </PromptInputButton>
      <ModelPicker />
      <PromptInputSubmit />
    </PromptInputToolbar>
  </PromptInput>
</div>
```

Move it below with `side="bottom"` for a promo (a "connect your apps" nudge, say). Same wrapper, but place the banner *after* the composer so it peeks out the bottom instead.

```tsx
<div className="flex flex-col isolate">
  <PromptInput onSubmit={send} className="shadow-md">…</PromptInput>
  {open && (
    <PromptInputBanner side="bottom" icon={<Sparkle />} onClose={() => setOpen(false)}>
      Get better answers from your apps.
      <PromptInputBannerAction className="ml-auto">Connect</PromptInputBannerAction>
    </PromptInputBanner>
  )}
</div>
```

## Character count

Drop a `PromptInputCount` into the toolbar: it reads the composer's length from context (pass `current` to show tokens instead). With a `max` it renders `current / max` and turns destructive once exceeded.

```tsx
<PromptInput defaultValue="A serene koala napping on a branch">
  <PromptInputTextarea placeholder="Describe the image you want…" />
  <PromptInputToolbar>
    <PromptInputButton iconOnly aria-label="Attach file">
      <Paperclip />
    </PromptInputButton>
    <div className="ml-auto flex items-center gap-2">
      <PromptInputCount max={500} />
      <PromptInputSubmit className="ml-0" />
    </div>
  </PromptInputToolbar>
</PromptInput>
```

## API reference

### PromptInput

Root `<form>` + context provider. Forwards all native form props.

- `value? / defaultValue?`: controlled or initial value. Uncontrolled clears itself after a submit.
- `onValueChange?(value)`: called on every keystroke.
- `onSubmit?(value)`: fired on Enter or send; skipped when empty, disabled, or loading.
- `onStop?()`: fired by the stop button.
- `loading?`: a response is streaming; flips send → stop.
- `disabled?`: dims and freezes the composer.

### PromptInputTextarea

Auto-growing field. Forwards all native `<textarea>` props except `value` / `onChange` (owned by the root).

- `submitOnEnter?`: Enter submits (default). Set `false` so Enter adds a line and ⌘/Ctrl+Enter sends.

### PromptInputSubmit

The send⇄stop button: a `Button` under the hood, so it takes all Button props (`variant`, `size`, …). Its send glyph is an upward arrow by default (it flips to a stop square while loading); pass `children` to override it. Custom `sendLabel` / `stopLabel` set the accessible names.

### PromptInputButton · PromptInputToolbar · PromptInputCount

`PromptInputButton` is a ghost `Button` for toolbar actions (its icons render at a consistent 20px across the bar); `PromptInputToolbar` is the bottom bar; `PromptInputCount` takes `current?` / `max?`.

### PromptInputBanner · PromptInputBannerAction

A second card that sits behind the composer, plus an inline link-styled `PromptInputBannerAction`. `side` (`top` / `bottom`) picks the edge it peeks from; `tone` (`default` / `info` / `warning` / `destructive`) tints the leading icon; `icon` overrides or drops (`false`) the glyph; `onClose` / `closeLabel` add a dismiss button.

### PromptInputSuggestions · PromptInputSuggestion

Context-free chip row + chip, meant to sit above the composer. The chip forwards all native `<button>` props; wire `onClick` yourself.

## FAQ

### Is the composer controlled or uncontrolled by default?

Uncontrolled: it owns its value and clears itself after a submit. Pass `value` plus `onValueChange` to control it, in which case you reset the value yourself to clear it.

### How do I switch the send button into a stop button while a response streams?

Pass `loading` to PromptInput. The PromptInputSubmit button flips from a `type="submit"` send button to a stop button that fires `onStop`.

### What are the Enter key semantics, and can I change them?

By default Enter submits and Shift+Enter inserts a newline. Set `submitOnEnter={false}` on PromptInputTextarea so Enter adds a line and Cmd/Ctrl+Enter sends instead. Submitting mid-IME-composition is guarded.

### How do I add a character or token count to the toolbar?

Drop a `PromptInputCount` into the toolbar; it reads the composer length from context. Give it a `max` to render `current / max` and turn destructive once exceeded, or pass `current` to show tokens instead of characters.

### Why is PromptInputSubmit disabled and how do I size the toolbar buttons?

Send is disabled while the value is empty, disabled, or loading. Every toolbar control tracks the root `size` through context (sm/md/lg line up 1:1 with Button sizes), so set `size` once on PromptInput rather than on each button.

### What is the difference between PromptInputSuggestions and the toolbar?

PromptInputSuggestions is a context-free chip row meant to sit above the composer, so you wire each chip's `onClick` yourself. The PromptInputToolbar is the bottom bar wired into composer state through context.

---

<!-- https://www.koalaui.com/docs/components/suggestions.md -->

# Suggestions

Inline AI edit suggestions over a body of text. The AI marks spans with a colored dotted underline; click one to see the proposed replacement and a reason, then apply it in place or dismiss it.

```tsx
<Suggestions onApply={review} onDismiss={review}>
  Our onboarding flow{" "}
  <SuggestionMark
    variant="clarity"
    suggestion="helps new users get started in minutes"
    reason="Be specific about the outcome, not just that it is good."
  >
    is really good for users
  </SuggestionMark>
  . We{" "}
  <SuggestionMark variant="tone" suggestion="believe" reason="A confident verb reads stronger.">
    kinda think
  </SuggestionMark>{" "}
  it{" "}
  <SuggestionMark variant="grammar" suggestion="increases" reason="Subject-verb agreement.">
    increase
  </SuggestionMark>{" "}
  activation.
</Suggestions>
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add suggestions
```

Manual: run `npm install radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/suggestions/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

```tsx title="usage.tsx"
import { Suggestions, SuggestionMark } from "@/components/ui/suggestions"

export function Review() {
  return (
    <Suggestions onApply={(next, original) => save(next)}>
      The deadline is{" "}
      <SuggestionMark
        variant="grammar"
        suggestion="Friday"
        reason="Capitalize the day of the week."
      >
        friday
      </SuggestionMark>
      .
    </Suggestions>
  )
}
```

Wrap each improvable span in a `SuggestionMark` with its `suggestion` (the replacement) and an optional `reason`. Applying swaps the children for the suggestion in place; dismissing keeps the original. Both fire the root's `onApply` / `onDismiss` so you can persist the edit or tick down a counter.

## Categories

The `variant` tints the underline and the popover badge, so a reader can tell a grammar fix from a tone or clarity nudge at a glance: `grammar`, `clarity`, `tone`, and a neutral `default`.

```tsx
<SuggestionMark variant="grammar" suggestion="their house" reason="Possessive, not a contraction.">
  they're house
</SuggestionMark>

<SuggestionMark variant="clarity" suggestion="use the tools" reason="Plainer words read faster.">
  utilize the tooling
</SuggestionMark>

<SuggestionMark variant="tone" suggestion="we believe" reason="Confident, active voice.">
  we kinda think
</SuggestionMark>
```

## API reference

### Suggestions

The prose container and context for the marks. Forwards all native `div` props.

- `onApply?(suggestion, original)`: fired when any mark is applied.
- `onDismiss?(original)`: fired when any mark is dismissed.

### SuggestionMark

One improvable span. The children are the original text; applying replaces them with `suggestion`.

- `suggestion`: the replacement text (required).
- `variant?`: `default` · `grammar` · `clarity` · `tone`.
- `label?` / `reason?`: the popover badge text and one-line explanation.
- `onApply? / onDismiss?`: per-mark hooks (the root's run too).

## FAQ

### What goes in the children of a SuggestionMark versus the suggestion prop?

The children are the original text the user wrote, and the `suggestion` prop is the replacement. When the user clicks Apply, the children are swapped for the suggestion in place; Dismiss keeps the children.

### What does the variant prop change?

It tints both the dotted underline on the span and the badge in the popover, so a reader can tell categories apart at a glance. The options are `grammar` (destructive red), `clarity` (info), `tone` (purple), and a neutral `default`.

### When do I use the root onApply versus the per-mark onApply?

Put `onApply` and `onDismiss` on the root `Suggestions` to handle every mark in one place, for example to persist the edit or tick down a counter. The root callback receives the suggestion and the original; a per-mark hook fires alongside it and receives just the suggestion.

### Why does the badge label say Grammar when I did not set one?

The badge defaults to the variant's name. Pass `label` on the `SuggestionMark` to override it with custom copy, and `reason` to add the one-line explanation shown beneath the diff.

### Does the mark stay interactive after the user decides?

No. Once a mark is applied or dismissed it collapses to plain text, the accepted replacement or the kept original, and the popover trigger is gone. Each mark owns its own resolved status.

### What is the marked span rendered as for accessibility?

It is a real focusable button that opens our Popover, so it is reachable by keyboard and shows a focus ring. The word's text color is inherited so it stays readable; only the underline and hover tint carry the category color.

---

<!-- https://www.koalaui.com/docs/components/auth-form.md -->

# Authentication

The sign-in and sign-up pair, shipped as two ready blocks: social providers, an email and password core, and the cross-link to its sibling. Sign-up adds a name field and a live password-strength meter.

```tsx
<LoginForm onSubmit={signIn} onProvider={oauth} />
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add auth-form
```

Manual: run `npm install radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/auth-form/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

```tsx title="usage.tsx"
"use client"

import { LoginForm, type AuthProvider, type LoginFormData } from "@/components/ui/auth-form"

export function Example() {
  async function signIn({ email, password, remember }: LoginFormData) {
    await fetch("/api/sign-in", {
      method: "POST",
      body: JSON.stringify({ email, password, remember }),
    })
  }

  function continueWith(provider: AuthProvider) {
    window.location.assign("/api/oauth/" + provider)
  }

  return <LoginForm onSubmit={signIn} onProvider={continueWith} />
}
```

## Sign up

`SignUpForm` adds a full-name field and a [password-strength](https://www.koalaui.com/docs/components/password-strength.md) meter, and gates the submit on the terms checkbox.

```tsx
<SignUpForm onSubmit={register} onProvider={oauth} />
```

## Provider-first

`ProviderForm` drops the password core for a stack of full-width `Continue with…` buttons: the password-less OAuth pattern. Add `showEmail` for a magic-link fallback below the providers.

```tsx
<ProviderForm
  providers={["google", "github", "apple"]}
  showEmail
  onProvider={oauth}
  onSubmit={sendMagicLink}
/>
```

### Single provider · consent gate

Pass one provider with `emphasizeFirst` for a single dominant button, and `requireTerms` to gate it behind a consent checkbox. A `social` rail links out to the community: the OAuth-only screen used by game servers and Discord-native products.

```tsx
<ProviderForm
  title="Want to join Eleven?"
  description="Sign in with Discord to request your whitelist."
  providers={["discord"]}
  emphasizeFirst
  action="sign-in"
  requireTerms
  termsLabel={<>I accept the <a href="/terms">terms and conditions</a> of Eleven</>}
  social={[
    { network: "x", href: "#" },
    { network: "discord", href: "#" },
    { network: "youtube", href: "#" },
    { network: "instagram", href: "#" },
  ]}
/>
```

## Localization

Every word the three blocks print reads from one `labels` dictionary, so a translation is written once and handed to all of them. Pass only the keys you change; the rest keep their English defaults. In the two provider phrases, `{provider}` is replaced with the provider's name wherever your language puts it. The consent sentences carry links whose words move in a translation, so they are whole nodes instead: `termsLabel` on SignUpForm and ProviderForm. `providers` picks the social row on LoginForm and SignUpForm too, and the row takes one track per provider.

```tsx
const es: Partial<AuthFormLabels> = {
  continueWith: "Continuar con {provider}",
  email: "Correo electrónico",
  emailPlaceholder: "tu@empresa.com",
  password: "Contraseña",
  passwordPlaceholder: "Tu contraseña",
  forgotPassword: "¿La has olvidado?",
  rememberMe: "Recordarme 30 días",
  signIn: "Entrar",
  signUp: "Crea una",
  noAccount: "¿No tienes cuenta?",
  loginDivider: "o entra con tu correo",
}

<LoginForm
  title="Hola de nuevo"
  description="Entra en tu cuenta para seguir."
  providers={["google", "apple"]}
  labels={es}
/>
```

## Full-page screens

Composed into complete pages, these blocks become the [Authentication](https://www.koalaui.com/app/sections/authentication.md) section family: seven finished sign-in and sign-up screens (split and centered, plus the community Discord screens), each with a full-screen, resizable device-frame preview. For a split screen, drop `variant="bare"` on the form and place it in a [SplitLayout](https://www.koalaui.com/docs/components/layout.md) pane so the shell owns the surface; for a centered page, keep the default bordered card on a soft backdrop.

## API reference

### LoginForm

Composes [Input](https://www.koalaui.com/docs/components/input.md), [Checkbox](https://www.koalaui.com/docs/components/checkbox.md), and [Divider](https://www.koalaui.com/docs/components/divider.md).

- `onSubmit`: `(data: { email, password, remember }) => void | Promise<void>`.
- `onProvider`: `(provider: "google" | "github" | "apple") => void`.
- `variant`: `"card"` (default) or `"bare"` to embed in a page shell.
- `showSocial` (default `true`), `forgotHref`, `signUpHref`.
- `providers`: the social row, left to right (default Google, GitHub, Apple).
- `labels`: `Partial<AuthFormLabels>`, the block's strings for a translation.

### SignUpForm

Adds a password-strength meter and a terms gate.

- `onSubmit`: `(data: { name, email, password, acceptedTerms }) => void | Promise<void>`.
- `variant` (`"card"` / `"bare"`), `showSocial`, `signInHref`, `termsHref`, `privacyHref`.
- `providers`, `labels` (as on LoginForm), and `termsLabel` to replace the consent sentence whole.

### ProviderForm

The password-less provider-first block: a stack of full-width `Continue with…` buttons with an optional magic-link email and social rail.

- `providers`: `("google" | "github" | "apple" | "discord")[]` (default the first three).
- `emphasizeFirst` renders the first provider as the solid primary button; `action` sets the verb (`"continue"` / `"sign-in"`).
- `requireTerms` gates every action behind a consent checkbox; `termsLabel`, `termsHref`, `privacyHref` control the copy.
- `showEmail` + `onSubmit` `(email: string) => void | Promise<void>` add a magic-link field; `social` renders the community link rail.
- `labels`: the button phrase (`continueWith` or `signInWith`, following `action`), the divider, the email field and the rail's name.

## FAQ

### What is the difference between LoginForm and SignUpForm?

LoginForm is the sign-in block with email, password, a "Remember me" checkbox, and a forgot-password link. SignUpForm adds a full-name field and a live password-strength meter, and gates its submit button on the terms checkbox via `acceptedTerms`.

### How do I wire these blocks to my auth backend?

Pass `onSubmit`, which receives the field data (`{ email, password, remember }` for login, `{ name, email, password, acceptedTerms }` for sign-up), and `onProvider`, which receives the OAuth provider id. Return a promise from `onSubmit` and the submit button drives its own loading spinner until it resolves.

### When should I use variant="bare" instead of the default card?

Use the default `card` variant for a standalone bordered block on a backdrop. Switch to `bare` to drop the border, surface, shadow, max-width, and padding so the form fills a page shell such as a SplitPane, letting the host own the surface and spacing.

### How does density affect the form?

density sets the outer gap and title size, and the card padding through variant by density compounds: `compact` (the Koala default, 16px) and `comfortable` (24px). If you omit the prop it falls back to the nearest DensityProvider, so a section-wide density setting flows in automatically.

### How do I translate the forms?

Pass a `labels` dictionary: every key is optional and the rest keep their English defaults, and the same object works on all three blocks. Provider phrases take a `{provider}` placeholder ("Continuar con {provider}"), so the name lands where your language puts it. The title and description are ordinary props, and the consent sentence is replaced whole with `termsLabel`, because a translation moves its words around the links.

### Can I hide the social provider row?

Yes, set `showSocial={false}` to drop the provider button grid and the "or continue with email" divider, leaving just the email and password core. It defaults to `true`.

### Why do nested Inputs blend into the card automatically?

Neither variant paints a fill of its own, so the composed Input, Checkbox, and password-strength parts take the same ground the form sits on: the page, a muted band, or a panel that declares `--surface`. The focus rings offset against that same ground, in `card` and `bare` alike.

---

<!-- https://www.koalaui.com/docs/components/contact-form.md -->

# Contact Form

A family of ready get-in-touch blocks on one recipe: ContactForm, LeadForm for sales, and SupportForm for help-desk requests. Each wires its controls through Field, owns its state and confirms on submit.

```tsx
<ContactForm onSubmit={(data) => send(data)} />
```

## Lead capture

`LeadForm` is the richer sales / collaboration block: a name and social row, a company-size Select, a country-aware [PhoneInput](https://www.koalaui.com/docs/components/input.md), and a message. Drop it beside a hero to capture qualified leads.

```tsx
<LeadForm defaultCountry="ES" onSubmit={(data) => send(data)} />
```

## Support request

`SupportForm` is tuned for an inbound support queue: a name and email row, a support-topic Select, an optional order / reference field so an agent can pull the account up fast, and a message.

```tsx
<SupportForm onSubmit={(data) => openTicket(data)} />
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add contact-form
```

Manual: run `npm install radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/contact-form/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

```tsx title="usage.tsx"
"use client"

import { ContactForm, type ContactFormData } from "@/components/ui/contact-form"

export function Example() {
  async function send(data: ContactFormData) {
    await fetch("/api/contact", { method: "POST", body: JSON.stringify(data) })
  }

  return <ContactForm onSubmit={send} />
}
```

## API reference

### ContactForm / LeadForm / SupportForm

Each composes [Field](https://www.koalaui.com/docs/components/field.md), [Input](https://www.koalaui.com/docs/components/input.md), [Select](https://www.koalaui.com/docs/components/select.md), and [Textarea](https://www.koalaui.com/docs/components/textarea.md) (LeadForm adds [PhoneInput](https://www.koalaui.com/docs/components/input.md)). Each forwards all `<div>` props.

- `onSubmit`: called with the block's data object on a valid submit ( `{ name, email, subject, message }` for ContactForm, `{ firstName, linkedin, email, companySize, phone, message }` for LeadForm, `{ name, email, topic, reference, message }` for SupportForm). Return a promise to drive the loading spinner.
- `variant`: `card` (default, standalone bordered block) or `bare` (drops the chrome to embed in a page shell).
- `density`: `compact` (16px padding, 32px fields, default) or `comfortable` (24px padding, 36px fields). The fields take the default control size for that density rather than the 40px a bare `Form` imposes, so the card stays proportional.
- `title`, `description`, `action`: override the default copy.
- `defaultCountry` (LeadForm only): initial ISO2 for the phone field.

## FAQ

### Which block should I reach for: ContactForm, LeadForm, or SupportForm?

Use ContactForm for an open-ended `get in touch` block (name, email, a general subject, and a message). Use LeadForm to capture qualified sales or collaboration leads: it adds a LinkedIn field, a company-size Select, and a country-aware phone field. Use SupportForm for an inbound support queue: it swaps in support-focused topics and an order / reference field. All three share one recipe and the same loading to success flow, so they feel identical to drop in.

### How do I embed a block inside a hero or marketing slab without the doubled card chrome?

Pass variant="bare" to drop the border, surface, shadow, max-width, and padding, so the block fills whatever shell hosts it. The card variant (the default) is the standalone bordered panel. It paints no fill of its own, so nested Inputs, Selects, and Textareas take the same ground the form sits on. The Contact marketing section composes LeadForm as a card floating over a photo.

### What shape is the data passed to onSubmit, and how do I drive the loading spinner?

onSubmit receives the block's typed data object (ContactFormData, LeadFormData, or SupportFormData). Return a promise from your handler and the submit Button shows its loading state until that promise resolves, after which the form swaps to the success panel, which renders with role="status" so it is announced to screen readers.

### How do I change the heading, supporting text, or submit button label?

Pass the title, description, and action props to override the defaults. Set description to null to drop the supporting line entirely.

### How does the family handle density and how do nested controls blend with the card?

The density prop accepts compact (16px padding, the default) or comfortable (24px), and falls back to the nearest DensityProvider when omitted. It also picks the field height: compact fields and the submit button are 32px, comfortable ones 36px, the same default size a bare control gets at that density. The block overrides the 40px a plain Form imposes, because a small card with tall fields reads as oversized. The card paints no fill of its own, so the nested Input, Select, PhoneInput, and Textarea take the same ground the form sits on instead of painting a mismatched block. Place it on a panel that declares --surface and they follow that panel.

---

<!-- https://www.koalaui.com/docs/components/feedback-form.md -->

# Feedback Form

A compact sentiment and comment block. A row of five faces reveals an optional comment field once one is picked, then submits. It owns its rating and message state; wire onSubmit to your sink.

```tsx
<FeedbackForm onSubmit={({ rating, message }) => record(rating, message)} />
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add feedback-form
```

Manual: run `npm install radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/feedback-form/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

```tsx title="usage.tsx"
"use client"

import { FeedbackForm, type FeedbackFormData } from "@/components/ui/feedback-form"

export function Example() {
  async function record({ rating, message }: FeedbackFormData) {
    await fetch("/api/feedback", { method: "POST", body: JSON.stringify({ rating, message }) })
  }

  return <FeedbackForm onSubmit={record} />
}
```

## API reference

### FeedbackForm

Composes a single-select [Toggle Group](https://www.koalaui.com/docs/components/toggle-group.md) and a [Textarea](https://www.koalaui.com/docs/components/textarea.md). Forwards all `<div>` props.

- `onSubmit`: `(data: { rating, message }) => void | Promise<void>`. Rating is the chosen value `"1"`-`"5"`.
- `title`, `description`, `action`: override the default copy.

## FAQ

### When should I reach for FeedbackForm instead of building my own rating UI?

Use it whenever you want a quick sentiment plus optional comment in one card: it owns the rating and message state, reveals the comment field only after a face is picked, and shows a built-in success state, so you just wire `onSubmit`. Build your own only if you need a different scale or layout than the five-face row.

### What does the onSubmit callback receive, and how do I show a loading spinner?

`onSubmit` is called with `{ rating, message }` where rating is the chosen value "1" through "5" and message is the comment text. Return a promise from it and the submit Button drives its own loading spinner until the promise resolves, then the card flips to the success state.

### Can I change the title, description, and button label?

Yes. Pass `title`, `description`, and `action` to override the default copy. They are ReactNodes, so you can pass strings or richer markup, and setting `description` to null hides the description line.

### How does density affect the card?

The `density` prop tunes the card padding, outer gap, title size, and success padding. `compact` is the 16px Koala default and `comfortable` is the roomier 24px option; omit the prop and it falls back to the nearest DensityProvider.

### Is the rating row accessible?

It composes a single-select ToggleGroup labelled "Rate your experience", and each face carries an aria-label like "Good" or "Terrible". The live caption under the faces uses aria-live="polite" so screen readers announce the chosen sentiment, and the success message is wrapped in a role="status" region.

### Why does the submit button stay disabled, and what is the comment length cap?

The submit Button is disabled until a face is selected, since a rating is required, and the comment field stays hidden until then. The Textarea is capped at 280 characters with a live count in its footer, so there is nothing extra to validate by hand.

---

<!-- https://www.koalaui.com/docs/components/newsletter-form.md -->

# Newsletter Form

A ready-to-ship email-capture block. It owns its own email state, validates the address and runs the loading to success flow. Two layouts: a self-contained card and a single-row inline signup.

```tsx
<NewsletterForm onSubscribe={(email) => subscribe(email)} />
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add newsletter-form
```

Manual: run `npm install radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/newsletter-form/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

```tsx title="usage.tsx"
"use client"

import { NewsletterForm } from "@/components/ui/newsletter-form"

export function Example() {
  async function subscribe(email: string) {
    await fetch("/api/newsletter", { method: "POST", body: JSON.stringify({ email }) })
  }

  return <NewsletterForm onSubscribe={subscribe} />
}
```

## Inline

`variant="inline"` drops the card chrome for a single row, ideal inside a [Footer](https://www.koalaui.com/docs/components/footer.md) or a hero section.

```tsx
<NewsletterForm variant="inline" action="Subscribe" />
```

## API reference

### NewsletterForm

A self-contained signup composed from [Input](https://www.koalaui.com/docs/components/input.md) and [Button](https://www.koalaui.com/docs/components/button.md). Forwards all `<div>` props.

- `variant`: `"card"` (default) or `"inline"`.
- `onSubscribe`: `(email: string) => void | Promise<void>`. Return a promise to keep the spinner up until your request resolves.
- `title`, `description`, `placeholder`, `action`, `fineprint`: override the default copy (card variant). Pass `null` to hide description or fineprint.

## FAQ

### Do I have to manage the email state myself?

No. NewsletterForm is a ready-to-ship block: it owns its own email state, validates the address, and runs the loading then success flow. Drop it in and it works.

### How do I hook it up to my mailing-list API?

Wire `onSubscribe`, which receives the entered email on a valid submit. Return a promise from it to keep the spinner up until your request resolves, then the success panel replaces the form.

### When should I use variant="inline" instead of the card?

Use `variant="inline"` for a single-row signup in a Footer or hero section: it drops the card chrome (border, background, padding) down to just the input and button. The default `card` variant adds a heading, lead, and fine print.

### How do I change the copy or hide parts of the card?

Override `title`, `description`, `placeholder`, `action`, and `fineprint`. Pass `null` to `description` or `fineprint` to hide them entirely.

### Why does the nested Input blend with the card instead of looking filled?

Neither layout paints a fill of its own, so the composed Input takes whatever ground the form sits on instead of a mismatched block. Put it on a filled panel that declares `--surface` and the Input follows that panel. That is the DS surface contract at work.

### Does it honor density?

Yes. Density tunes the card padding, gap, and title size, with `compact` (16px) as the default and `comfortable` (24px) for a roomier card; it also reads a surrounding DensityProvider.

---

<!-- https://www.koalaui.com/docs/components/payment-form.md -->

# Payment Form

A complete card-checkout block. The number, expiry and CVC are masked as you type, the card brand is detected live, and the billing country shows circular flags. Accept promo codes to roll the total.

```tsx
<PaymentForm
  amount="$49.00"
  promoCodes={{
    KOALA20: { percentOff: 20, label: "KOALA20 · 20% off" },
    WELCOME10: { amountOff: 10, label: "WELCOME10 · $10 off" },
  }}
  promoHint="Try KOALA20 for 20% off, or WELCOME10 for $10 off."
  onSubmit={(data) => pay(data)}
/>
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add payment-form
```

Manual: run `npm install radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/payment-form/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

```tsx title="usage.tsx"
"use client"

import { PaymentForm, type PaymentFormData } from "@/components/ui/payment-form"

export function Example() {
  async function pay(data: PaymentFormData) {
    await fetch("/api/checkout", { method: "POST", body: JSON.stringify(data) })
  }

  return (
    <PaymentForm
      amount="$49.00"
      promoCodes={{ WELCOME10: { amountOff: 10, label: "WELCOME10 · $10 off" } }}
      onSubmit={pay}
    />
  )
}
```

## API reference

### PaymentForm

Composes [Field](https://www.koalaui.com/docs/components/field.md), [Input](https://www.koalaui.com/docs/components/input.md), and [Select](https://www.koalaui.com/docs/components/select.md). The masking and brand detection are presentation only; never store an unmasked card number. Forwards all `<div>` props.

- `amount`: display total (e.g. `"$49.00"`). Shows the summary row and labels the Pay button. When a code is applied, the shown total is the discounted one.
- `promoCodes`: `Record<string, PaymentPromoCode>` keyed by code (matched case-insensitively). Reveals the promo-code row; each code carries a `percentOff` and/or `amountOff` (and an optional `label`). Applying one drops in a subtotal → discount breakdown and rolls the total. Requires a parseable `amount`.
- `promoHint`: caption under the promo input (e.g. `"Try KOALA20"`).
- `defaultCountry`: billing country ISO2 (default `"US"`).
- `onSubmit`: `(data: PaymentFormData) => void | Promise<void>`, where `PaymentFormData` is `{ cardNumber, expiry, cvc, name, country, promoCode? }`.

## FAQ

### Does PaymentForm process payments or store card data?

No. The masking and live brand detection are presentation only, and PaymentForm never touches a network. Wire your `onSubmit` handler to a provider like Stripe, and never store the unmasked card number yourself.

### How do I run a loading spinner while the charge settles?

Return a promise from `onSubmit`. The form sets its internal status to loading (the Pay button shows a spinner) until the promise resolves, then flips to the built-in success screen.

### How do promo codes work?

Pass `promoCodes` as a map of code to a `{ percentOff?, amountOff?, label? }` discount. A "Promo code" field appears under the billing country; codes are matched case-insensitively. Applying a valid one slides a subtotal → discount breakdown into the summary and rolls the total to its new value, an invalid one shows an inline error, and the applied code arrives on `onSubmit` as `data.promoCode`. The discount math re-uses your `amount` string's currency symbol, decimals, and grouping.

### What shape is the data passed to onSubmit?

A `PaymentFormData` object with `cardNumber`, `expiry`, `cvc`, `name`, and `country` (ISO2). The card number, expiry, and CVC arrive masked exactly as displayed.

### How do I set the order total and the default billing country?

Pass `amount` as a preformatted string like `"$49.00"` to show the summary row and label the Pay button, and `defaultCountry` as an ISO2 code (default `"US"`) to preselect the CountrySelect.

### Why do the nested Inputs blend into the card instead of looking filled?

The card paints no fill of its own, so the composed Field, Input, and CountrySelect take the same ground the card sits on rather than a separate background block. The summary wells are the one filled part, and they declare their own `--surface`.

### Can I change the spacing to match a denser layout?

Set `density` to `compact` (16px, the default) or `comfortable` (24px). Omit it and the form inherits from the nearest DensityProvider.

---

<!-- https://www.koalaui.com/docs/components/settings-form.md -->

# Settings Form

An account-profile editing block: an avatar with change and remove controls, a name row, a prefixed username, email and a bio with a live count, closed by a Cancel and Save footer.

```tsx
<SettingsForm defaultValues={user} onSave={(data) => save(data)} />
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add settings-form
```

Manual: run `npm install radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/settings-form/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

```tsx title="usage.tsx"
"use client"

import { SettingsForm, type SettingsFormData } from "@/components/ui/settings-form"

export function Example() {
  async function save(data: SettingsFormData) {
    await fetch("/api/profile", { method: "PATCH", body: JSON.stringify(data) })
  }

  return (
    <SettingsForm
      defaultValues={{ firstName: "Ana", lastName: "Ruiz", email: "ana@koalaui.com" }}
      onSave={save}
    />
  )
}
```

## API reference

### SettingsForm

Composes [Avatar](https://www.koalaui.com/docs/components/avatar.md), [Field](https://www.koalaui.com/docs/components/field.md), [Input](https://www.koalaui.com/docs/components/input.md), and [Textarea](https://www.koalaui.com/docs/components/textarea.md). The root is a `<form>` that forwards all its props.

- `defaultValues`: `Partial<{ firstName, lastName, username, email, bio }>`.
- `onSave`: `(data: SettingsFormData) => void | Promise<void>`; `onCancel`: `() => void`.
- `avatarSrc`, `usernamePrefix` (default `"koalaui.com/"`), `title`, `description`.

## FAQ

### When should I use SettingsForm versus building my own form?

Reach for `SettingsForm` when you need the standard account-profile editing block: avatar with change/remove, name, a prefixed username, email, and a bio with a live count, closed by a Cancel and Save footer. It owns its field state and confirms inline once saved, so you do not hand-wire those pieces.

### How do I seed and read the form's values?

Pass `defaultValues` (a `Partial` of `{ firstName, lastName, username, email, bio }`) to prefill the fields, and handle `onSave`, which receives the full `SettingsFormData`. `onSave` may return a Promise, so the block can show its saving state while you persist.

### What does usernamePrefix do?

`usernamePrefix` renders a static prefix before the username input (defaulting to `koalaui.com/`), so the row reads as a full handle. Override it with your own domain or namespace.

### How do I customize the heading and the avatar?

Set `title` and `description` to change the block's heading copy, and `avatarSrc` to seed the current avatar image used by the change and remove controls.

### What components does it compose, and can I restyle it?

The root is a `<form>` that composes `Avatar`, `Field`, `Input`, and `Textarea`, so it inherits their theming and accessibility. It forwards all `<form>` props and accepts `className` for layout tweaks, but the internal field set is fixed.

---

<!-- https://www.koalaui.com/docs/components/survey.md -->

# Survey

Google-Forms-style question cards: an eyebrow, a title with an optional required asterisk, and an answer. Survey owns the layout and semantics; the controls are the real DS components.

```tsx
<SurveyQuestion required className="max-w-xl">
  <SurveyHeader>
    <SurveyEyebrow>Question 1</SurveyEyebrow>
    <SurveyTitle>How do you build UI today?</SurveyTitle>
  </SurveyHeader>
  <SurveyOptions defaultValue="shared">
    <SurveyOption value="shared">A shared internal component library</SurveyOption>
    <SurveyOption value="kit">An off-the-shelf UI kit</SurveyOption>
    <SurveyOption value="handrolled">Hand-rolled components in each project</SurveyOption>
    <SurveyOption value="mixed">A mix, depending on the team</SurveyOption>
  </SurveyOptions>
</SurveyQuestion>
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add survey
```

Manual: run `npm install radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/survey/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

```tsx title="usage.tsx"
import {
  SurveyQuestion,
  SurveyHeader,
  SurveyEyebrow,
  SurveyTitle,
  SurveyOptions,
  SurveyOption,
} from "@/components/ui/survey"

export function Example() {
  return (
    <SurveyQuestion required>
      <SurveyHeader>
        <SurveyEyebrow>Question 1</SurveyEyebrow>
        <SurveyTitle>How do you build UI today?</SurveyTitle>
      </SurveyHeader>
      <SurveyOptions defaultValue="shared">
        <SurveyOption value="shared">A shared internal component library</SurveyOption>
        <SurveyOption value="kit">An off-the-shelf UI kit</SurveyOption>
      </SurveyOptions>
    </SurveyQuestion>
  )
}
```

## Single & multiple choice

Without a prop, `SurveyOptions` is a single choice: the DS `RadioGroup` with its canonical dot and roving focus, reporting a `string`. Add `multiple` and each row becomes a DS `Checkbox` reporting a `string[]`. The controls aren't re-styled; they're the same radio and checkbox you'd use anywhere else.

```tsx
// Single choice: circular controls, reports a string
<SurveyOptions value={source} onValueChange={setSource}>
  <SurveyOption value="copy">Copied into my repo</SurveyOption>
  <SurveyOption value="package">Installed as a package</SurveyOption>
</SurveyOptions>

// Multiple choice: square controls, reports a string[]
<SurveyOptions multiple value={priorities} onValueChange={setPriorities}>
  <SurveyOption value="a11y">Accessibility out of the box</SurveyOption>
  <SurveyOption value="theming">Theming and tokens</SurveyOption>
  <SurveyOption value="types">First-class TypeScript types</SurveyOption>
</SurveyOptions>
```

## Text, paragraph & dropdown

A question doesn't have to be a choice. `SurveyShortAnswer` composes the DS `Input`, `SurveyParagraph` the auto-growing `Textarea` (with an optional counter), and `SurveyDropdown` the `Select` for long option lists. Each is labelled by the question title automatically.

```tsx
// Short answer: composes the DS Input
<SurveyQuestion required>
  <SurveyHeader>
    <SurveyEyebrow>Question 5</SurveyEyebrow>
    <SurveyTitle>What are you building with Koala UI?</SurveyTitle>
  </SurveyHeader>
  <SurveyShortAnswer placeholder="e.g. an internal analytics console" />
</SurveyQuestion>

// Paragraph: composes the auto-growing DS Textarea
<SurveyParagraph placeholder="Tell us what’s missing…" showCount maxLength={280} />

// Dropdown: composes the DS Select
<SurveyDropdown
  options={[
    { value: "solo", label: "Just me" },
    { value: "small", label: "2 to 10 people" },
    { value: "medium", label: "11 to 50 people" },
    { value: "large", label: "51 to 200 people" },
    { value: "xlarge", label: "200+ people" },
  ]}
  placeholder="Select a team size…"
/>
```

## Linear scale

`SurveyScale` is a 1-to-N rating row built on `RadioGroup`. Set `min`/`max` and optional `minLabel`/`maxLabel` captions for the ends.

```tsx
const [rating, setRating] = useState("4")

<SurveyQuestion required>
  <SurveyHeader>
    <SurveyEyebrow>Question 8</SurveyEyebrow>
    <SurveyTitle>How easy was it to drop Koala UI into your project?</SurveyTitle>
  </SurveyHeader>
  <SurveyScale
    min={1}
    max={5}
    minLabel="Took some work"
    maxLabel="Effortless"
    value={rating}
    onValueChange={setRating}
    name="setup"
  />
</SurveyQuestion>
```

## Rating

`SurveyRating` composes the DS `Rating` for a star score, labelled by the question title. It forwards every `Rating` prop: `max`, `size`, `icon`, `readOnly`.

```tsx
const [stars, setStars] = useState(4)

<SurveyQuestion required>
  <SurveyHeader>
    <SurveyEyebrow>Question 9</SurveyEyebrow>
    <SurveyTitle>How would you rate the documentation?</SurveyTitle>
  </SurveyHeader>
  <SurveyRating value={stars} onValueChange={setStars} size="lg" />
</SurveyQuestion>
```

## Description & disabled options

Add a `SurveyDescription` under the title for context, and disable any single `SurveyOption`: keyboard navigation skips it and its row dims.

```tsx
<SurveyQuestion required>
  <SurveyHeader>
    <SurveyEyebrow>Question 4</SurveyEyebrow>
    <SurveyTitle>Pick a release channel</SurveyTitle>
    <SurveyDescription>
      Stable ships monthly. The canary channel is paused while we land v1.0.
    </SurveyDescription>
  </SurveyHeader>
  <SurveyOptions defaultValue="stable">
    <SurveyOption value="stable">Stable, updated monthly</SurveyOption>
    <SurveyOption value="next">Next, weekly previews</SurveyOption>
    <SurveyOption value="canary" disabled>Canary, paused until v1.0</SurveyOption>
  </SurveyOptions>
</SurveyQuestion>
```

## Density

`density="compact"` tightens the card padding, gaps, and row height for embedded, information-dense forms; radius and color never change. Defaults to `comfortable`, or set it once on a `DensityProvider`.

```tsx
<SurveyQuestion density="compact">
  <SurveyHeader>
    <SurveyEyebrow>Question 2</SurveyEyebrow>
    <SurveyTitle>How did you hear about Koala UI?</SurveyTitle>
  </SurveyHeader>
  <SurveyOptions defaultValue="search">
    <SurveyOption value="search">Search engine</SurveyOption>
    <SurveyOption value="social">Social media</SurveyOption>
    <SurveyOption value="friend">A friend or colleague</SurveyOption>
  </SurveyOptions>
</SurveyQuestion>
```

## Controlled

Pass `value` and `onValueChange` to own the selection. For a `multiple` group the value is a `string[]`.

```tsx
const [values, setValues] = useState(["table"])

<SurveyOptions multiple value={values} onValueChange={setValues}>
  <SurveyOption value="table">Data table</SurveyOption>
  <SurveyOption value="forms">Form controls</SurveyOption>
  <SurveyOption value="charts">Charts</SurveyOption>
  <SurveyOption value="nav">Navigation</SurveyOption>
</SurveyOptions>
```

## Composing a form

There is no Survey root or provider: every `SurveyQuestion` is a standalone card, so a survey is just the cards you need stacked inside your own `form`. Pass `name` to a single-choice `SurveyOptions`, `SurveyScale`, or a text part and the answer lands in `FormData`. A `multiple` group owns a `string[]` in React state, so serialize that one yourself.

```tsx
<Form density="comfortable" onSubmit={handleSubmit} className="max-w-xl">
  <SurveyQuestion required>
    <SurveyHeader>
      <SurveyEyebrow>Question 1 of 3</SurveyEyebrow>
      <SurveyTitle>How do you build UI today?</SurveyTitle>
    </SurveyHeader>
    <SurveyOptions name="approach" defaultValue="shared">
      <SurveyOption value="shared">A shared internal component library</SurveyOption>
      <SurveyOption value="kit">An off-the-shelf UI kit</SurveyOption>
    </SurveyOptions>
  </SurveyQuestion>

  <SurveyQuestion required>
    <SurveyHeader>
      <SurveyEyebrow>Question 2 of 3</SurveyEyebrow>
      <SurveyTitle>How easy was it to drop Koala UI into your project?</SurveyTitle>
    </SurveyHeader>
    <SurveyScale min={1} max={5} minLabel="Took some work" maxLabel="Effortless" name="setup" />
  </SurveyQuestion>

  <SurveyQuestion>
    <SurveyHeader>
      <SurveyEyebrow>Question 3 of 3</SurveyEyebrow>
      <SurveyTitle>What would make Koala UI a better fit for your stack?</SurveyTitle>
    </SurveyHeader>
    <SurveyParagraph name="notes" placeholder="Tell us what’s missing…" showCount maxLength={280} />
  </SurveyQuestion>

  <FormActions>
    <Button type="button" variant="ghost">Skip</Button>
    <Button type="submit">Submit answers</Button>
  </FormActions>
</Form>
```

## FAQ

### How do I switch SurveyOptions between single and multiple choice?

Leave SurveyOptions bare for a single choice: it renders the DS RadioGroup and reports a `string`. Add the `multiple` prop and each row becomes a DS Checkbox reporting a `string[]`. The controls are the real DS components, not restyled copies.

### Which part do I use for free text instead of choices?

`SurveyShortAnswer` composes the DS Input for one line, `SurveyParagraph` the auto-growing Textarea (pass `showCount` and `maxLength` for a counter), and `SurveyDropdown` the Select for long option lists. Each is labelled by the question title automatically.

### What is the difference between SurveyScale and SurveyRating?

`SurveyScale` is a 1-to-N linear scale built on RadioGroup: set `min` and `max` and optional `minLabel` and `maxLabel` captions for the ends. `SurveyRating` composes the DS Rating for a star score and forwards Rating props like `max`, `size`, `icon`, and `readOnly`.

### How do I mark a question as required?

Pass `required` to `SurveyQuestion` and the title renders a destructive asterisk plus an sr-only (required) note. You can override the inherited state on an individual `SurveyTitle` with its own `required` prop.

### Are the answer controls wired to the question title for screen readers?

Yes. SurveyQuestion generates a title id, and every answer part (options, short answer, paragraph, dropdown, scale, rating) is given `aria-labelledby` pointing at it, so you do not label the controls again.

### How do I make a survey card denser?

Set `density="compact"` on `SurveyQuestion` to tighten padding, gaps, and row height for embedded forms, or set it once on a `DensityProvider` for a whole subtree. Radius and color never change.

### Why does the hover highlight slide between rows?

Because it is one highlight, not a fill per row: the same travelling wash the Command palette uses, from the shared `useGlide` hook. It follows the cursor across the options and along a `SurveyScale`, moves with the keyboard focus ring, appears on the row you enter on rather than sliding in from the last one, and skips disabled rows. Selection is still carried by the control alone, so a chosen row takes no fill of its own.

### How do I submit a survey?

There is no Survey root or provider. Each `SurveyQuestion` is a standalone card, so wrap the ones you need in your own `<form>` and lay them out with a flex column. Pass `name` to a single-choice `SurveyOptions` or to `SurveyScale` and the answer lands in `FormData`; a `multiple` group owns a `string[]` in React state, so serialize that one yourself.

---

<!-- https://www.koalaui.com/docs/components/waitlist-form.md -->

# Waitlist Form

A centered waitlist block: a headline, a one-row email capture and a social-proof footer with overlapping avatars and a running count. On submit it flips to a confirmed state; wire onJoin to your list.

```tsx
<WaitlistForm count={1284} onJoin={(email) => join(email)} />
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add waitlist-form
```

Manual: run `npm install radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/waitlist-form/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

```tsx title="usage.tsx"
"use client"

import { WaitlistForm } from "@/components/ui/waitlist-form"

export function Example() {
  async function join(email: string) {
    await fetch("/api/waitlist", { method: "POST", body: JSON.stringify({ email }) })
  }

  return <WaitlistForm count={1284} onJoin={join} />
}
```

## API reference

### WaitlistForm

Composes [Input](https://www.koalaui.com/docs/components/input.md), [Button](https://www.koalaui.com/docs/components/button.md), and [Avatar](https://www.koalaui.com/docs/components/avatar.md). Forwards all `<div>` props.

- `onJoin`: `(email: string) => void | Promise<void>`.
- `count`: people already joined, shown beside the avatars (`tabular-nums`).
- `avatars`: `{ src?, fallback, alt? }[]` for the proof stack.
- `badge`, `title`, `description`, `placeholder`, `action`: override the copy.

## FAQ

### How do I connect the form to my list?

Wire `onJoin`, which is called with the entered email on a valid submit. It accepts `(email: string) => void | Promise<void>`; the form owns its own email and status, so all you do is hand the email to your backend or email provider.

### Does it show a loading spinner while my submit runs?

Yes, if you return a promise from `onJoin`. The form awaits it to drive the spinner, then flips to its confirmed success state once it resolves.

### How do I customize the avatars and the joined count?

Pass `count` for the running number shown beside the stack (rendered with `tabular-nums` so it does not reflow), and `avatars` as an array of `{ src?, fallback, alt? }` for the social-proof stack. It composes Avatar, Input, and Button under the hood.

### How do I change the headline and button copy?

Override the copy props: `badge`, `title`, `description`, `placeholder`, and `action` (the join button label). Pass `badge={null}` to hide the pill above the headline entirely.

### How does spacing change with density?

The `density` prop sets the padding, outer gap, and title size: `compact` (16px) is the default and `comfortable` is 24px. If you omit it the form falls back to the nearest DensityProvider.

### Why does the nested email input blend into the card?

The card paints no fill of its own, so the nested Input takes the same ground the card sits on. If you restyle the root with a fill, declare it as `--surface` too (for example `bg-muted [--surface:var(--muted)]`) so the input keeps blending with it.

---

<!-- https://www.koalaui.com/docs/components/animated-label.md -->

# Animated Label

Text that rolls when it changes state: the outgoing label lifts out while the incoming one rises from below, and the box eases between the two widths. The prose sibling of Animated Number: Next to Done, Weak to Strong.

```tsx
const [state, setState] = React.useState("Draft")

<AnimatedLabel swapKey={state} className="text-5xl font-semibold">
  {state}
</AnimatedLabel>
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add animated-label
```

Manual: run `npm install radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/animated-label/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

```tsx title="usage.tsx"
import { AnimatedLabel } from "@/components/ui/animated-label"

export function Example({ expanded }: { expanded: boolean }) {
  // `swapKey` is what says the label now means something else; children alone
  // are new elements on every render, so they can't tell a state change apart.
  return (
    <AnimatedLabel swapKey={expanded ? "less" : "more"}>
      {expanded ? "Show less" : "Show more"}
    </AnimatedLabel>
  )
}
```

## Inside a button

When the whole label swaps, don't reach for this: give `Button` a `swapKey` and it wraps its children for you. Reach for `AnimatedLabel` when only part of the button should roll, the case below. `swapKey` boxes every child into the swap, so an icon left inside it dissolves and re-appears rather than turning; a caret has to sit outside the roll to rotate. The label still carries the width change, so the button morphs and the caret rides along.

This is the shape used by `LoadMoreTrigger`, `CodeSnippet` and the Chat reasoning trigger. The caret takes `caret-turn`, the shared disclosure beat - see [Motion](https://www.koalaui.com/docs/foundations/motion.md).

```tsx
<Button variant="secondary" aria-expanded={expanded} onClick={toggle}>
  <AnimatedLabel swapKey={expanded ? "less" : "more"}>
    {expanded ? "Show less" : "Show more"}
  </AnimatedLabel>
  <CaretDown weight="bold" className={cn("caret-turn", expanded && "rotate-180")} />
</Button>
```

## Alignment

The box is briefly a different width than the label it holds (that's the morph), so the label needs to know which edge to hold on to. `align` defaults to `center`, which is right inside a button. Left-aligned copy wants `start`, or the text drifts sideways as the box eases.

```tsx
<AnimatedLabel swapKey={state} align="start" className="text-lg font-medium">
  {state}
</AnimatedLabel>
```

## How it works

Two layers: the current label in normal flow, so it alone sizes the box, and a snapshot of the outgoing one taken out of flow on top of it, so it can leave without widening anything. Both run the `label-swap-*` keyframes at `--duration-base`, with the opacity front-loaded against the travel (solid by 45%) the same way the number roll does it: the two labels sit on top of each other, so a long half-visible cross-fade would read as one smeared word. The snapshot is `aria-hidden` and dropped as soon as its roll ends, so the accessible name flips straight to the new label.

The width is the part CSS can't express on its own, so it's driven from a layout effect: pin the old label's width, hand over the new one, release back to `auto` once it lands. The start value is read off the snapshot rather than remembered, so it can't go stale, and interrupting a morph starts from the width that's on screen rather than the one it was heading for. The first paint never rolls, and under `prefers-reduced-motion` the label simply swaps.

## API reference

### AnimatedLabel

Renders one inline `<span>` (the layers inside are managed for you). Props: `swapKey` (identifies the label on screen; a change rolls it), `align` (`center` · `start` · `end`, which edge the label holds while the box eases), `className` (styles the label, e.g. size / weight / color), plus all `<span>` props.

## FAQ

### Why do I need swapKey - can't it see the children changed?

Children are new React elements on every render, so the component can't tell an actual state change from a re-render; animating on identity would roll the label constantly. swapKey is the signal that the label now means something different. Often the text itself is the natural key (swapKey={label}).

### When do I use this instead of Button's swapKey?

Use Button's swapKey when the whole label swaps - it wraps the children for you. Use AnimatedLabel directly when only part of the content should roll, like a label sitting beside an icon that rotates rather than swaps, or when the label isn't in a button at all (a status word, a strength verdict).

### The color changes with the label. Which one does the outgoing text keep?

Whichever you put on the layer rather than the container. A class on AnimatedLabel itself lives above both layers, so the departing label would repaint to the new color; wrap the children in a span carrying the color instead and each label keeps the one it was born with. That's how PasswordStrength keeps Weak leaving red while Fair arrives orange.

### Does the width really animate, or is the box just as wide as the longest label?

It animates. The box is only ever as wide as the label it's showing; on a swap a layout effect pins the outgoing label's measured width and transitions to the incoming one, then releases the box back to auto. So neither state pays for the other's width at rest.

### What happens under reduced motion?

The roll and the width morph are both off and the label swaps instantly. The animation classes are motion-safe, and the outgoing layer rests at opacity 0 so nothing lingers over the new label.

---

<!-- https://www.koalaui.com/docs/components/animated-number.md -->

# Animated Number

A figure that rolls when it changes, one character at a time: each changed digit lifts out while its replacement rises from below. Backed by the motion tokens and tabular-nums, so the width never jumps.

```tsx
const [n, setN] = React.useState(2450)

<AnimatedNumber
  value={n.toLocaleString("en-US")}
  className="text-6xl font-semibold tracking-tight"
/>
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add animated-number
```

Manual: run `npm install radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/animated-number/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

```tsx title="usage.tsx"
import { AnimatedNumber } from "@/components/ui/animated-number"

export function Example({ total }: { total: string }) {
  // Whenever `total` changes, the old value rolls up and the new rolls in.
  return <AnimatedNumber value={total} className="text-2xl font-semibold" />
}
```

## Currency & formatting

`value` takes whatever you want to display, a pre-formatted string is easiest. The container is `tabular-nums`, so even as the digit count changes the figure keeps a steady width and the layout never shifts. Only the digits are tabular: a comma, a period or a currency mark keeps its natural width, since a separator handed a digit’s advance leaves a hole either side of itself and sets `1,368` as `1 , 368` in a wide face. Format with `Intl.NumberFormat` / `toFixed` and pass the result.

```tsx
const money = (c) => "$" + (c / 100).toFixed(2)
const [cents, setCents] = React.useState(3442)

<AnimatedNumber value={money(cents)} className="text-4xl font-semibold" />
```

## How it works

The value is split into per-character cells, paired against the previous value from the right (the way a number grows). Only the characters that actually changed roll: each keeps two layers, the incoming glyph in normal flow and the outgoing one taken out of flow, so the cell never widens as the old glyph leaves. Everything else holds perfectly still at full strength, which is what keeps a change from reading as the whole figure dimming.

The changed cells fire in sequence, left to right, one `--number-roll-stagger` step (45ms) apart, so a figure sweeps across like a departure board. The stagger counts only the cells that move, so a change in the last two digits starts immediately, and it compresses past six steps so a long value still lands as one gesture. The two `number-roll-*` keyframes run at `--duration-base` with the opacity front-loaded against the travel (solid by 45%), so what you track is movement at full strength rather than a long half-visible cross-fade. There is no clip window, so no hard top or bottom edges. The first paint never animates, a screen reader gets the value as one uninterrupted string, and everything holds still under `prefers-reduced-motion` (the value simply swaps).

## API reference

### AnimatedNumber

Renders one inline `<span>` (the per-character cells inside are managed for you). Props: `value` (the figure to show, any `ReactNode`, usually a formatted string; a change triggers the roll), `className` (styles the figure, e.g. size / weight / color), plus all `<span>` props.

## FAQ

### Does it animate on first render?

No. The enter roll is gated so the initial paint shows the value at rest; only subsequent changes roll. This keeps a list of numbers from all rolling in at once on page load.

### Can I animate a currency or a percentage?

Yes, pass the fully formatted string as value (e.g. "$34.42" or "98%"). Characters are paired from the right, so the currency symbol, the separators and any digit that didn't change stay put while the rest rolls, and tabular-nums keeps the width stable so the surrounding layout never shifts.

### What happens under reduced motion?

The roll is disabled and the value swaps instantly. The animation classes are motion-safe, and the outgoing layer is hidden under prefers-reduced-motion, so nothing lingers.

### Where does the timing come from?

The number-roll-in / number-roll-out keyframes in globals.css, applied under a prefers-reduced-motion query and built on --duration-base and --ease-out, plus --number-roll-stagger for the gap between characters. The component only supplies a unitless multiplier per cell, so retuning the roll or the stagger is a one-line change in the token layer.

---

<!-- https://www.koalaui.com/docs/components/chart.md -->

# Chart

A dependency-free plotting primitive for trends, funnels and pies. Compose the named parts into one measured SVG; the legend focuses and toggles series, and every hue re-themes.

```tsx
// The week of Sep 29 is still running: "partial" dashes its stretch.
<Chart
  data={signups}
  index="week"
  label="Weekly signups by platform"
  config={{
    web: { label: "Web", color: "blue" },
    ios: { label: "iOS", color: "teal" },
    android: { label: "Android", color: "purple" },
  }}
  partial
  padding={{ bottom: 28, left: 36, top: 8, right: 12 }}
  className="h-80"
>
  <ChartLegend value="sum" />
  <ChartGrid />
  <ChartYAxis />
  <ChartLine dataKey="web" curve="monotone" />
  <ChartLine dataKey="ios" curve="monotone" />
  <ChartLine dataKey="android" curve="monotone" />
  <ChartXAxis interval="auto" />
  <ChartTooltip sort="desc" total />
  <ChartAnnotation
    index={7}
    label="1"
    title="Pricing v2 went live"
    description="Annual plans now include two months free."
  />
</Chart>
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add chart
```

Manual: run `npm install tailwind-variants tailwind-merge tippy.js`, then copy the source into `components/ui/chart/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

`Chart` is composed from named parts, like [Card](https://www.koalaui.com/docs/components/card.md). The root takes the `data`, an optional `index` key for category labels, and a `config` that names each series’ label and color. The parts (`ChartGrid`, `ChartArea`, `ChartLine`, `ChartTooltip`) read it from context and draw into one shared, pixel-measured SVG.

```tsx title="revenue-chart.tsx"
import {
  Chart,
  ChartGrid,
  ChartArea,
  ChartLine,
  ChartXAxis,
  ChartTooltip,
} from "@/components/ui/chart"

const revenue = [
  { month: "Jan", revenue: 4200 },
  { month: "Feb", revenue: 4600 },
  // …
]

export function RevenueChart() {
  return (
    <Chart
      data={revenue}
      index="month"
      config={{ revenue: { label: "Revenue", color: "blue" } }}
      padding={{ bottom: 28, top: 12 }}
      className="h-72"
    >
      <ChartGrid />
      <ChartArea dataKey="revenue" />
      <ChartLine dataKey="revenue" />
      <ChartXAxis />
      <ChartTooltip />
    </Chart>
  )
}
```

## Load animation

Every chart plays a one-shot reveal the first time it mounts: the `ChartLine` self-draws left to right, the `ChartArea` fill rises from the baseline, and each `ChartBar` grows up from the zero line in a left-to-right cascade. It fires once, never on hover or re-sort, and honors `prefers-reduced-motion` (every layer simply appears drawn). Pass `animate={false}` on the `Chart` root to opt out. Press Replay to watch it again.

```tsx
// The load reveal is on by default: the line draws, the area rises,
// and bars grow from the baseline. Pass animate={false} to opt out.
<Chart data={months} index="month"
  config={{ revenue: { label: "Revenue", color: "blue" } }}
  padding={{ bottom: 28, top: 12 }} className="h-64">
  <ChartGrid />
  <ChartArea dataKey="revenue" />
  <ChartLine dataKey="revenue" />
  <ChartXAxis />
  <ChartTooltip valueFormatter={(v) => `$${v.toLocaleString("en-US")}`} />
</Chart>
```

## Line

Layer a `ChartLine` per series; each resolves its hue from `config`, or takes an explicit `color`. The shared `ChartTooltip` lists every series at the hovered category, and a crosshair tracks the active point.

```tsx
<Chart
  data={months}
  index="month"
  config={{
    desktop: { label: "Desktop", color: "blue" },
    mobile: { label: "Mobile", color: "teal" },
  }}
  padding={{ bottom: 28, left: 40, top: 12 }}
  className="h-72"
>
  <ChartGrid />
  <ChartYAxis />
  <ChartLine dataKey="desktop" />
  <ChartLine dataKey="mobile" />
  <ChartXAxis />
  <ChartTooltip />
</Chart>
```

## Area

`ChartArea` fills the space under the trend with a `currentColor` gradient that fades to the baseline, so the wash is just the series hue at low opacity: a `blue` line yields a soft blue-100/200 fill. Pair it with a `ChartLine` for a crisp edge.

```tsx
<Chart data={months} index="month"
  config={{ revenue: { label: "Revenue", color: "blue" } }}
  padding={{ bottom: 28, top: 12 }} className="h-64">
  <ChartGrid />
  <ChartArea dataKey="revenue" />
  <ChartLine dataKey="revenue" />
  <ChartXAxis />
  <ChartTooltip valueFormatter={(v) => `$${v.toLocaleString("en-US")}`} />
</Chart>
```

## Smooth curves

Pass `curve="monotone"` to `ChartLine`, `ChartArea` or `ChartAreas` to join the points with a monotone cubic instead of straight segments. It is smooth, yet it still passes through every point and never swings above a peak or below a trough the data does not have: a plateau stays flat and an extreme sits exactly on its point, so the curve never invents a value. Gaps, stacking, `dashed`, `markEnd`, the draw-in and the hover dot all follow the curve. Set the same `curve` on the area and the line drawn over it.

```tsx
// The same data, joined two ways. Set the curve on the area and the line over it.
<Chart data={sessions} index="month"
  config={{ sessions: { label: "Sessions", color: "blue" } }} className="h-56">
  <ChartGrid />
  <ChartYAxis />
  <ChartArea dataKey="sessions" curve="monotone" />
  <ChartLine dataKey="sessions" curve="monotone" markEnd />
  <ChartXAxis />
  <ChartTooltip />
</Chart>
```

## Missing data

A point with a non-numeric (or absent) value is a gap. By default the `ChartLine` and `ChartArea` **break** at the gap, so a dropout reads honestly. Pass `connectNulls` to bridge across it instead.

```tsx
// Rows with a missing "signal" key are gaps.
const signal = [
  { day: "Mon", signal: 40 },
  { day: "Tue", signal: 52 },
  { day: "Wed" }, // gap → line breaks here
  { day: "Thu", signal: 48 },
]

<Chart data={signal} index="day" config={{ signal: { color: "blue" } }} className="h-56">
  <ChartGrid />
  <ChartArea dataKey="signal" />          {/* break at gaps (default) */}
  <ChartLine dataKey="signal" />
  {/* …or bridge across them: */}
  <ChartLine dataKey="signal" connectNulls />
</Chart>
```

## Bar

`ChartBar` draws a bar per category from a 0-anchored baseline. Each bar stands square on the baseline and rounds only at its value end (the bottom, for a negative bar), and `ChartGrid` draws the zero line a step stronger, so the bars stand on a floor. Hovering a column brings it forward and dims the rest, so the active value reads at a glance.

```tsx
<Chart data={months} index="month"
  config={{ orders: { label: "Orders", color: "blue" } }}
  padding={{ bottom: 28, left: 36, top: 12 }} className="h-64">
  <ChartGrid />
  <ChartYAxis />
  <ChartBar dataKey="orders" />
  <ChartXAxis />
  <ChartTooltip />
</Chart>
```

## Value labels & highlight

Pass `label` to `ChartBar` to print each value just past its bar end. It returns inline content, so a figure can carry a glyph. To single one datum out, draw the series in `neutral` (the foreground at 10% on every theme) and pass its index to `highlight`, so that one bar takes the brand. Hovering a column also lifts its x-axis tick to the foreground.

```tsx
const label = (value, index) => (
  <>
    {index === 2 && <Crown weight="bold" />}
    {money(value)}
  </>
)

<Chart data={weeks} index="week" className="h-64"
  config={{ revenue: { label: "Revenue", color: "neutral" } }}
  padding={{ top: 28, right: 0, bottom: 32, left: 0 }}>
  <ChartGrid />
  {/* One series; the current week (index 3) takes the brand. */}
  <ChartBar dataKey="revenue" highlight={3} label={label} />
  <ChartXAxis />
  <ChartTooltip />
</Chart>
```

## Highlight & active bar

`highlight` on `ChartBar` paints chosen bars in `highlightColor` (the brand by default) and leaves the rest in the series hue: an index for today, a list, a predicate over the row, or `"active"` for the bar under the pointer. The chart reports that bar through `onActiveIndexChange` (and takes a controlled `activeIndex`), so a legend or a headline can follow it. Here the latest month is lit until another is hovered. Swapping the highlight recolors the bars in place, so the grow-in never replays, and the tooltip swatch takes the hue the bar is wearing. While a column is hovered the others dim, except `neutral` bars: already faint, they hold their ink and the hovered one steps up instead, so no bar ever disappears.

```tsx
// A fixed highlight: today (the last day) in the brand, the week behind it neutral.
<Chart data={week} index="day"
  config={{ orders: { label: "Orders", color: "neutral" } }} className="h-56">
  <ChartBar dataKey="orders" highlight={week.length - 1} />
  <ChartXAxis />
  <ChartTooltip />
</Chart>

// The highlight follows the pointer and rests on the latest month. The chart reports
// the hovered index, so the legend always names the bar that is lit.
const [active, setActive] = React.useState<number | null>(null)
const lit = active ?? months.length - 1

<ChartLegend items={[{ label: months[lit].month, color: "brand", value: usd(months[lit].revenue) }]} />
<Chart data={months} index="month" onActiveIndexChange={setActive}
  config={{ revenue: { label: "Revenue", color: "neutral" } }} className="h-56">
  <ChartBar dataKey="revenue" highlight={lit} />
  <ChartXAxis />
  <ChartTooltip />
</Chart>

// Other shapes: highlight={[0, 6]}, highlight="active" (only the hovered bar),
// highlight={(row) => Number(row.orders) > 50}, and highlightColor="teal".
```

## Grouped & stacked bars

`ChartBars` draws several bar series in one band. By default they render **grouped** side by side; set `stack` on `Chart` to **stack** them, and the y-axis grows to the per-category total automatically. Grouped series rotate distinct hues; stacked ones take shades of one blue, since their order already tells them apart. A color in `config` always wins.

```tsx
// Grouped (default): series sit side by side.
<Chart data={months} index="month"
  config={{ desktop: { color: "blue" }, mobile: { color: "teal" } }} className="h-64">
  <ChartGrid />
  <ChartYAxis />
  <ChartBars keys={["desktop", "mobile"]} />
  <ChartXAxis />
  <ChartTooltip />
</Chart>

// Stacked: add "stack" on Chart; the y-axis covers the per-category total.
<Chart data={months} index="month" stack
  config={{ desktop: { color: "blue" }, mobile: { color: "teal" } }} className="h-64">
  <ChartGrid />
  <ChartYAxis />
  <ChartBars keys={["desktop", "mobile"]} />
  <ChartXAxis />
  <ChartTooltip />
</Chart>
```

## Stacked area

`ChartAreas` stacks several area series into a band chart when `stack` is set on `Chart`: each series sits on the cumulative total below it as a flat band with its own edge line. A stack reads by its order, so series that name no color take shades of the house blue, dark at the floor to light at the top (`palette="tonal"`, the default whenever `stack` is set). Without `stack` the series overlap from the baseline.

```tsx
// Stacked band chart: "stack" on Chart + ChartAreas.
<Chart data={months} index="month" stack
  config={{ desktop: { color: "blue" }, mobile: { color: "teal" } }} className="h-72">
  <ChartGrid />
  <ChartYAxis />
  <ChartAreas keys={["desktop", "mobile"]} />
  <ChartXAxis />
  <ChartTooltip />
</Chart>
```

## Legend

Put `ChartLegend` inside the `Chart` and it keys the chart’s own series, sits above the plot (or below it, with `placement="bottom"`) and becomes the chart’s control surface, as in Mixpanel. Hover a key and its series comes forward while the rest recede; click it to hide or show the series, and the scale and the stack refit around what is left; Alt+click shows it alone. The last series showing never hides. Past `max` keys, the rest fold into a +N more menu with the same controls.

```tsx
// Inside the Chart, the legend keys its series: hover to focus,
// click to hide or show, Alt+click to isolate. Six keys, four inline.
<Chart data={channels} index="month" config={channelConfig} stack
  padding={{ bottom: 28, left: 40, top: 8, right: 12 }} className="h-80">
  <ChartLegend max={4} />
  <ChartGrid />
  <ChartYAxis tickFormatter={(v) => `$${v}K`} />
  <ChartBars barRatio={0.56} />
  <ChartXAxis />
  <ChartTooltip sort="desc" total />
</Chart>
```

Outside a chart, `ChartLegend` is a plain key: feed it the same `config` (or explicit `items`) and each swatch resolves its hue exactly like the chart, palette fallback included.

```tsx
const config = {
  desktop: { label: "Desktop", color: "blue" },
  mobile: { label: "Mobile", color: "teal" },
}

<div className="flex flex-col gap-3">
  <ChartLegend config={config} align="end" />
  <Chart data={months} index="month" config={config} className="h-72">
    <ChartGrid />
    <ChartYAxis />
    <ChartLine dataKey="desktop" />
    <ChartLine dataKey="mobile" />
    <ChartXAxis />
    <ChartTooltip />
  </Chart>
</div>
```

Give an item a `value` and it prints after the label in the foreground, so the key doubles as a summary of each series. Inside a chart, `value="sum"`, `"average"` or `"last"` summarises each series from the data, in its own `format`.

```tsx
<ChartLegend
  items={[
    { label: "Travel", color: "purple", value: "$456,478" },
    { label: "Health", color: "success", value: "$234,567" },
    { label: "Food", color: "destructive", value: "$123,456" },
  ]}
/>
```

## Driving it from outside

The series state is controllable, so a table under the chart can run it, the way Mixpanel pairs every insight with its breakdown. `hiddenSeries` with `onHiddenSeriesChange` takes the checkboxes, and `focusedSeries` with `onFocusedSeriesChange` lights the plan under the pointer. A series and the period it is compared against always stay lit together.

```tsx
const [hidden, setHidden] = React.useState<string[]>([])
const [focused, setFocused] = React.useState<string | null>(null)

<Chart data={mrr} index="month" config={plans}
  hiddenSeries={hidden} onHiddenSeriesChange={setHidden}
  focusedSeries={focused} onFocusedSeriesChange={setFocused}
  padding={{ bottom: 28, left: 40, top: 12, right: 12 }} className="h-64">
  <ChartGrid />
  <ChartYAxis />
  {Object.keys(plans).map((key) => (
    <ChartLine key={key} dataKey={key} curve="monotone" />
  ))}
  <ChartXAxis />
  <ChartTooltip sort="desc" />
</Chart>

// Each table row: hover focuses the plan, the checkbox shows or hides it.
<tr onPointerEnter={() => setFocused(key)} onPointerLeave={() => setFocused(null)}>
  <td>
    <Checkbox
      checked={!hidden.includes(key)}
      onCheckedChange={(on) =>
        setHidden((prev) => (on ? prev.filter((k) => k !== key) : [...prev, key]))
      }
    />
  </td>
  …
</tr>
```

## Dual axis & per-series format

Give a series `axis: "right"` in `config` to scale it against a secondary y-axis (so two metrics at different magnitudes share one chart), and render a second `ChartYAxis` with `side="right"`. Each series can also carry its own `format`, so the tooltip shows, say, currency for revenue and a plain count for orders.

```tsx
<Chart data={months} index="month"
  config={{
    revenue: { label: "Revenue", color: "blue", axis: "left",
               format: (v) => `$${v.toLocaleString("en-US")}` },
    orders:  { label: "Orders", color: "teal", axis: "right" },
  }}
  padding={{ bottom: 28, left: 48, right: 44, top: 12 }} className="h-72">
  <ChartGrid />
  <ChartYAxis tickFormatter={(v) => `$${(v / 1000).toFixed(0)}k`} />
  <ChartYAxis side="right" />
  <ChartLine dataKey="revenue" />
  <ChartLine dataKey="orders" />
  <ChartXAxis />
  <ChartTooltip />
</Chart>
```

## Forecast & end marker

`ChartLine` takes `dashed` for projected data and `markEnd` to pin a filled dot on the last point (a “current value” marker). Split actuals and projection into two series that share the seam point, and the solid line meets its dashed continuation cleanly.

```tsx
// Two series share the Jun point, so solid meets dashed seamlessly.
const trend = [
  { month: "May", actual: 5600, projected: null },
  { month: "Jun", actual: 6100, projected: 6100 },
  { month: "Jul", actual: null, projected: 6700 },
]

<Chart data={trend} index="month"
  config={{ actual: { color: "blue" }, projected: { color: "blue" } }} className="h-72">
  <ChartGrid />
  <ChartYAxis />
  <ChartLine dataKey="actual" markEnd />
  <ChartLine dataKey="projected" dashed />
  <ChartXAxis />
  <ChartTooltip />
</Chart>
```

## Incomplete period

Today’s count is still climbing, so drawn like a finished day it reads as a collapse. Pass `partial` on `Chart` (or a number, for several trailing periods) and the open period draws as provisional, Mixpanel’s treatment: a line dashes from the last complete point on the exact same curve, its area fades, a bar hatches, and the tooltip marks the period with `partialLabel`.

```tsx
// Today (the last row) is still running.
<Chart data={days} index="day" partial
  config={{ active: { label: "Active users", color: "blue" } }}
  padding={{ bottom: 28, left: 36, top: 12, right: 12 }} className="h-56">
  <ChartGrid />
  <ChartYAxis />
  <ChartArea dataKey="active" />
  <ChartLine dataKey="active" />
  <ChartXAxis interval="auto" />
  <ChartTooltip partialLabel="Today, so far" />
</Chart>

// Bars hatch instead. partial={3} marks the last three periods.
<Chart data={days} index="day" partial
  config={{ orders: { label: "Orders", color: "blue" } }} className="h-56">
  <ChartGrid />
  <ChartBar dataKey="orders" />
  <ChartXAxis interval="auto" />
  <ChartTooltip partialLabel="Today, so far" />
</Chart>
```

## Compare to previous period

Name the earlier period in a series’ config with `compare` and the pair reads as one story. The earlier series becomes a ghost: it borrows the hue, takes no palette slot, and its `ChartLine` draws thin, faint and dashed with no prop set. The tooltip prints the change beside the current value, green up and red down; give a down-is-good metric (churn, refunds, latency) `inverted` and the colors flip. In `ChartBars` the ghost stands beside its partner, faint.

```tsx
// "compare" names the earlier period; it becomes the faint dashed ghost.
<Chart
  data={quarter}
  index="week"
  config={{
    revenue: { label: "This quarter", color: "blue", compare: "previous", format: usd },
    previous: { label: "Last quarter", format: usd },
  }}
  padding={{ bottom: 28, left: 40, top: 8, right: 12 }}
  className="h-72"
>
  <ChartLegend />
  <ChartGrid />
  <ChartYAxis />
  <ChartArea dataKey="revenue" curve="monotone" />
  <ChartLine dataKey="previous" curve="monotone" />
  <ChartLine dataKey="revenue" curve="monotone" />
  <ChartXAxis />
  <ChartTooltip />
</Chart>
```

## Reference lines

`ChartReferenceLine` draws a horizontal threshold (`y`) or vertical marker (`x`) across the plot, with an optional `label`. Compose it after the data so it annotates on top, for a target, limit, or average. It defaults to a muted dashed line; pass a `color` to emphasize it.

```tsx
<Chart data={revenue} index="month"
  config={{ revenue: { label: "Revenue", color: "blue" } }} className="h-72">
  <ChartGrid />
  <ChartYAxis tickFormatter={(v) => `$${(v / 1000).toFixed(0)}k`} />
  <ChartArea dataKey="revenue" />
  <ChartLine dataKey="revenue" />
  {/* after the data => annotates on top */}
  <ChartReferenceLine y={5000} label="Target $5k" color="destructive" />
  <ChartXAxis />
  <ChartTooltip />
</Chart>
```

## Annotations

`ChartAnnotation` pins a note to a category: a launch, an outage, a release, so the jump in the line explains itself. Its marker sits in a lane above the plot (the plot steps down to make room on its own) with a faint rule down to the baseline, and hovering it opens the note. Mixpanel numbers its markers; pass any short `label`, or none for a dot, and a `color` for a note that is bad news. The text also reaches screen readers beside the data table.

```tsx
<Chart data={september} index="day"
  config={{ signups: { label: "Signups", color: "blue" } }}
  padding={{ bottom: 28, left: 36, top: 8, right: 12 }} className="h-72">
  <ChartGrid />
  <ChartYAxis />
  <ChartArea dataKey="signups" />
  <ChartLine dataKey="signups" />
  <ChartXAxis interval="auto" minInterval={7} />
  <ChartTooltip />
  <ChartAnnotation index={9} label="1" title="Launched on Product Hunt"
    description="#2 product of the day." />
  <ChartAnnotation index={16} label="2" title="EU region outage"
    description="Signups failed for 47 minutes." color="destructive" />
  <ChartAnnotation index={22} label="3" title="Onboarding v3"
    description="The new setup checklist shipped to everyone." />
</Chart>
```

## Tooltip rows

`footer` on `ChartTooltip` adds rows under the series, below a hairline, for a figure the chart does not draw: here the net of income and expenses. Build each row with `ChartTooltipItem` (a swatch, a label, a value) so it lines up with the rows above and its swatch keeps its hue in the portaled bubble. `labelFormatter` receives the whole row and its index after the label, so the heading can say more than the axis (a full month name).

```tsx
const cashflow = [
  { month: "Mar", name: "March 2026", income: 51200, expenses: 38400 },
  // …
]

<Chart data={cashflow} index="month" className="h-64"
  config={{
    income: { label: "Income", color: "brand", format: usd },
    expenses: { label: "Expenses", color: "neutral", format: usd },
  }}>
  <ChartGrid />
  <ChartYAxis tickFormatter={(v) => `$${v / 1000}k`} />
  <ChartBars keys={["income", "expenses"]} barRatio={0.6} />
  <ChartXAxis />
  <ChartTooltip
    // The heading gets the row too: the full month name instead of "Mar".
    labelFormatter={(_, row) => row.name}
    // Rows under the series, below a hairline: the net the chart does not draw.
    footer={(row) => (
      <ChartTooltipItem color="success" label="Net" value={usd(Number(row.income) - Number(row.expenses))} />
    )}
  />
</Chart>
```

## Tooltip order & totals

With several series, the tooltip reads best as a ranking. `sort="desc"` orders the rows by their value at the hovered category, so the leader comes first however the lines cross (a comparison row stays under its series). `total` adds the column’s sum below a hairline (a string names it), and `maxItems` folds the tail into a +N more line. While a legend key holds the focus, the other rows recede with their series.

```tsx
// No colors in config: a stack takes shades of the house blue (palette="tonal").
<Chart data={tickets} index="week" config={regions} stack
  padding={{ bottom: 28, left: 36, top: 12, right: 12 }} className="h-72">
  <ChartGrid />
  <ChartYAxis />
  <ChartAreas curve="monotone" />
  <ChartXAxis />
  {/* Largest first, a named total, and the tail folded after three rows. */}
  <ChartTooltip sort="desc" total="All regions" maxItems={3} />
</Chart>
```

## Axis labels that fit

`interval="auto"` on `ChartXAxis` measures its labels against the plot’s width and skips just enough of them that none collide, re-thinning as the chart resizes. It counts back from the last category, so the latest day or month always carries its name. `minTickGap` sets the clear space between labels (12px), and `minInterval` keeps a month of days reading by the week however wide the plot. A number still labels every Nth category from the first.

```tsx
// Thirty days: the axis keeps the labels that fit the plot, counted back from Sep 27.
<Chart data={daily} index="day"
  config={{ visits: { label: "Visits", color: "blue" } }} className="h-52">
  <ChartGrid />
  <ChartArea dataKey="visits" curve="monotone" />
  <ChartLine dataKey="visits" curve="monotone" markEnd />
  <ChartXAxis interval="auto" />
  <ChartTooltip />
</Chart>

// Never more often than weekly, however wide the plot:
<ChartXAxis interval="auto" minInterval={7} />
```

## Axis titles & compact figures

`ChartYAxis` prints compact figures by default (12K, 1.4M), the way Mixpanel and Attio label an axis; pass `tickFormatter` for currency or units. Both axes take a `label`: the y title turns to run along the outer edge, the x title centers under the ticks, as in Attio’s report builder. Give the chart the room for them in `padding`.

```tsx
<Chart data={countries} index="country"
  config={{ companies: { label: "Companies", color: "blue" } }}
  padding={{ bottom: 52, left: 56, top: 12, right: 12 }} className="h-80">
  <ChartGrid />
  <ChartYAxis label="Companies" />
  <ChartBar dataKey="companies" barRatio={0.7} />
  <ChartXAxis interval="auto" label="Primary location · Country" />
  <ChartTooltip />
</Chart>
```

## Negative values

The domain anchors to zero, and bars and areas grow from the **value baseline** (the y-zero line), so positive values rise above it and negative values drop below. No extra config: pass data that crosses zero and it reads correctly.

```tsx
// net crosses zero; bars grow up/down from the y-zero baseline.
const net = [{ month: "Jan", net: 12 }, { month: "Feb", net: -8 }, /* … */]

<Chart data={net} index="month"
  config={{ net: { label: "Net change", color: "blue" } }}
  padding={{ bottom: 28, left: 36, top: 12 }} className="h-64">
  <ChartGrid />
  <ChartYAxis />
  <ChartBar dataKey="net" />
  <ChartXAxis />
  <ChartTooltip />
</Chart>
```

## Fitted domain

A full chart starts its y-axis at zero, which is right for bars and totals. A balance or a rate moves in a band far from zero, and a zero floor flattens it into a line. Pass `domain="fit"` and the axis wraps the data’s own extent in nice rounded bounds, with ticks on a nice step, so the grid and the labels still land on round values. It never crosses zero when the data does not. A `[min, max]` pair still fixes the domain exactly.

```tsx
// A balance between $1.67M and $1.84M: "fit" wraps it in $1.65M to $1.85M.
<Chart data={balance} index="week" domain="fit"
  config={{ balance: { label: "Balance", color: "blue", format: usd } }} className="h-56">
  <ChartGrid />
  <ChartYAxis tickFormatter={(v) => `$${(v / 1_000_000).toFixed(2)}M`} />
  <ChartArea dataKey="balance" curve="monotone" />
  <ChartLine dataKey="balance" curve="monotone" markEnd />
  <ChartXAxis interval="auto" />
  <ChartTooltip />
</Chart>
```

## Funnel

`ChartFunnel` draws conversion through ordered steps, as Mixpanel and Attio do. Each step is a column, and above it a faint ghost rises to the step before, so what dropped off reads as the empty part of the column. Each step carries its conversion from the first, and `ChartTooltip` adds the conversion and drop-off rows by itself. Give the chart about 32px of `padding.top` for the first label.

```tsx
const funnel = [
  { step: "Visited pricing", users: 12480 },
  { step: "Started signup", users: 5920 },
  { step: "Verified email", users: 4310 },
  { step: "Created workspace", users: 3180 },
  { step: "Invited a teammate", users: 1240 },
]

<Chart data={funnel} index="step"
  config={{ users: { label: "Users", color: "blue" } }}
  padding={{ bottom: 28, left: 36, top: 32, right: 12 }} className="h-80">
  <ChartGrid />
  <ChartYAxis />
  <ChartFunnel dataKey="users" />
  <ChartXAxis interval="auto" />
  <ChartTooltip />
</Chart>
```

## Pie & donut

`ChartPie` draws each row as a slice, clockwise from twelve o’clock, with a clean gap between slices. `innerRadius` sets the hole (0.62 by default, a donut; 0 for a pie), and its children center in the hole. Hovering a slice lifts it out a step while the rest recede, with its value and share in the tooltip. A `ChartLegend` in the same chart keys the slices in their hues and lights them from the key.

```tsx
// A donut: children center in the hole. The legend keys the slices.
<Chart data={sources} index="source" config={{ visits: { label: "Visits" } }} className="h-80">
  <ChartPie dataKey="visits" colors={["blue", "teal", "purple", "orange", "pink"]}>
    <span className="text-xs text-muted-foreground">Visits</span>
    <span className="text-2xl font-semibold text-foreground">40.0K</span>
  </ChartPie>
  <ChartLegend placement="bottom" align="center" value={share} />
</Chart>

// A pie: no hole.
<Chart data={stages} index="stage" config={{ deals: { label: "Deals" } }} className="h-80">
  <ChartPie dataKey="deals" innerRadius={0} />
  <ChartLegend placement="bottom" align="center" />
</Chart>
```

## Category bar

`CategoryBar` breaks one whole into its parts in a single line: credits by tool, storage by file type, time by project. It takes the same rows as a pie (each one a category, named by `index`, sized by `dataKey`), so where a donut spends a square, this sits under a figure or across a card. Each segment’s width is its share, with a clean gap between segments, and `CategoryBarLegend` keys them underneath with the share after each name. Hovering a segment or a key lights it and recedes the rest, with its amount and share in the tooltip. Give the long tail’s Other the `gray` hue.

```tsx
const credits = [
  { tool: "Image generation", credits: 3370 },
  { tool: "Video", credits: 2496 },
  // …
  { tool: "Other", credits: 1498 },
]

<CategoryBar
  data={credits}
  index="tool"
  dataKey="credits"
  label="Credits by tool this month"
  colors={["success", "pink", "info", "purple", "warning", "orange", "teal", "blue", "gray"]}
  valueFormatter={(v) => `${v.toLocaleString("en-US")} credits`}
>
  <CategoryBarLegend />
</CategoryBar>
```

`size` sets the thickness (6, 8 or 12px), `palette="tonal"` paints shades of the house blue instead of distinct hues, and the legend’s `value` prints the share, the amount (through `valueFormatter`), both, or nothing.

```tsx
<CategoryBar data={storage} index="type" dataKey="gb" size="sm">
  <CategoryBarLegend />
</CategoryBar>

<CategoryBar data={storage} index="type" dataKey="gb" size="lg" palette="tonal"
  valueFormatter={(v) => `${v} GB`}>
  <CategoryBarLegend value="both" />
</CategoryBar>
```

## Sparkline

Pass `sparkline` for a chromeless trend: zero padding (it bleeds to the edge), points spanning the full width, and `currentColor` so a single `text-*` utility sets the hue. This is exactly what [StatSparkline](https://www.koalaui.com/docs/components/stat.md) renders under the hood.

```tsx
// Chromeless: zero padding, full-width points, currentColor.
// Sparklines drop the crosshair automatically (crosshair defaults off).
<Chart data={[31, 40, 28, 51, 42, 60, 58, 71]} sparkline className="h-12 text-success">
  <ChartArea />
  <ChartLine />
  <ChartTooltip />
</Chart>
```

## Sparkline bars

A sparkline can draw bars too, for a week of orders beside a figure. Once a `ChartBar` is in it, the categories sit in bands (the first and last bars keep their full width) and the scale runs from zero, so the shortest bar still reads as a bar. Add `ChartTooltip` for a hover readout, and `highlight` to light today.

```tsx
// Bars in a sparkline sit in bands and grow from zero; today takes the brand.
<Chart data={week} index="day" sparkline
  config={{ orders: { label: "Orders", color: "neutral" } }} className="h-12 w-28">
  <ChartBar dataKey="orders" highlight={week.length - 1} radius={3} />
  <ChartTooltip />
</Chart>
```

## Colors

Every series takes a semantic hue: `blue` (the default), `teal`, `purple`, `orange`, `pink`, the status roles, or `current` to inherit the ambient color. Series without a color follow the chart’s `palette`: `categorical` rotates distinct hues led by `blue`, for lines that cross and must be told apart; `tonal` spreads the blue ramp (`blue-800` to `blue-200`) as far apart as the count allows, and is the default for a stack.

```tsx
// Per-series hue via the "color" prop (or resolved from "config"); blue is the default.
<Chart data={trend} sparkline className="h-12">
  <ChartArea color="blue" />
  <ChartLine color="blue" />
</Chart>
```

## Loading & empty

Pass `loading` to render a Skeleton in place of the plot (it also sets `aria-busy`). When `data` is empty, the chart shows a muted message; override it with the `empty` prop.

```tsx
// Loading: a Skeleton replaces the plot (and sets aria-busy).
<Chart data={revenue} loading className="h-44" />

// Empty: a muted message; override with the "empty" prop.
<Chart data={[]} className="h-44" />
<Chart data={[]} empty={<MyEmptyState />} className="h-44" />
```

## Accessibility

The SVG is decorative (`aria-hidden`): pixels do not read well to a screen reader. Instead, every full chart renders a **visually-hidden data table** as its accessible equivalent, so assistive tech gets the real numbers, row by row. Pass `label` to name the chart, it becomes the table’s caption. `loading` sets `aria-busy`. Sparklines stay decorative (no table), since they are labelled by their surrounding context, like a [Stat](https://www.koalaui.com/docs/components/stat.md)’s value.

```tsx title="accessible-chart.tsx"
// "label" names the chart and captions the visually-hidden data table
// that screen readers read in place of the (aria-hidden) SVG.
<Chart data={revenue} index="month" label="Monthly revenue"
  config={{ revenue: { label: "Revenue", color: "blue" } }} className="h-72">
  <ChartGrid />
  <ChartArea dataKey="revenue" />
  <ChartLine dataKey="revenue" />
  <ChartXAxis />
  <ChartTooltip valueFormatter={(v) => `$${v.toLocaleString("en-US")}`} />
</Chart>
```

## API reference

`Chart` takes `data` (an array of rows, or a bare `number[]`), `index`, `config`, `domain` (`"auto"`, the default, from zero; `"fit"` around the data; or a fixed `[min, max]`), `sparkline`, `stack` (stack multi-series bars and size the domain to the total), `palette` (`"categorical"` hues or `"tonal"` shades of blue for series with no color; tonal by default on a stack), `padding`, `animate` (the load reveal, on by default), `crosshair` (the hover tracking line, which paints behind the data so the trend stays on top; defaults on for full charts, off for sparklines), `activeIndex` and `onActiveIndexChange` (the hovered category, controlled or reported), `hiddenSeries`, `defaultHiddenSeries` and `onHiddenSeriesChange` (the series switched off), `focusedSeries` and `onFocusedSeriesChange` (the series in focus), `partial` (trailing periods still in progress), `loading`, `empty`, and `label` (accessible name + data-table caption), and forwards `div` props, a `ref` included (merged with the one it measures through). The series parts ( `ChartLine`, `ChartArea`, `ChartBar`) take a `dataKey` and optional `color`; `ChartBar` also takes `label` (a value label per bar) and `highlight` with `highlightColor` (bars painted in another hue); `ChartLine` and `ChartArea` also take `connectNulls` and `curve` (`"linear"` or `"monotone"`); `ChartLine` adds `dashed`, `markEnd` and `variant` (`"comparison"` draws the faint dashed ghost, the default for a series another one compares against). `ChartBars` and `ChartAreas` draw several bar / area series (grouped, or stacked when `stack` is set) from a `keys` list, and `ChartAreas` takes a `curve` too. `ChartGrid`, `ChartXAxis` (with `interval`, a number or `"auto"`, plus `minTickGap` and `minInterval`), and `ChartYAxis` (with `side="right"` for the secondary axis and compact figures by default) are the chrome, both axes with an optional `label` title, and `ChartGrid` takes `baseline` (the stronger zero line, on by default); per-series `config` entries take `format`, `axis`, `compare` (the key of the period it is measured against) and `inverted` (down is good); `ChartAnnotation` pins a note (`index`, `label`, `title`, `description`, `color`) to a category; `ChartFunnel` draws steps with their drop-off (`dataKey`, `barRatio`, `radius`, `label`); `ChartPie` draws a pie or a donut (`dataKey`, `innerRadius`, `gap`, `colors`, `valueFormatter`, `tooltip`, and children for the hole); `CategoryBar` splits one whole in a single bar (`data`, `index`, `dataKey`, `colors`, `palette`, `size`, `valueFormatter`, `tooltip`, `animate`, `label`) with `CategoryBarLegend` under it (`value`: share, value, both or none); `ChartReferenceLine` adds a `y`/`x` threshold with an optional `label`; `ChartTooltip` adds the hover bubble with `valueFormatter`, `labelFormatter` (label, row, index), `footer`, `sort`, `total`, `maxItems` and `partialLabel`, whose rows are `ChartTooltipItem`s (`color`, `label`, `value`, `change`, `inverted`, `ghost`, `dimmed`); and `ChartLegend` is the key: inside a chart it lists the series (or a pie’s slices) and focuses, hides and isolates them, with `placement`, `max`, `interactive` and `value`; outside it is a plain key fed the same `config`, or `items` with an optional `value`. Every part accepts `className`, merged last.

## FAQ

### How do the series parts know which values to draw?

Each series part takes a dataKey that names the field in your data rows, for example ChartLine dataKey="revenue". The part resolves its hue from the matching config entry, or you can pass an explicit color.

### When do I need an index prop?

Pass index when your data is an array of objects and you want category labels on the x-axis, for example index="month". A bare number[] needs no index, which is the typical sparkline case.

### How do I make a chromeless inline trend?

Pass sparkline on Chart. It zeroes the padding so the plot bleeds to the edge, spans the points across the full width, and paints in currentColor so a single text-* utility sets the hue. StatSparkline is just a thin wrapper over this.

### How do I format the tooltip and axis values?

ChartTooltip takes valueFormatter and labelFormatter, and ChartYAxis takes tickFormatter, so you can render currency or compact units. For per-series formatting, give a config entry its own format function, which the tooltip uses over the shared valueFormatter.

### Can two series use different scales (dual axis)?

Yes. Give a series axis: "right" in config to scale it against a secondary y-axis, and render a second ChartYAxis with side="right". It is the right call for two metrics at very different magnitudes, like revenue and order count on one chart.

### How do I show a forecast or a current-value dot?

ChartLine takes dashed for projected data (it renders dashed and skips the self-draw) and markEnd to pin a filled dot on the last point. Split actuals and projection into two series that share the seam point so the solid line meets the dashed continuation cleanly.

### How does the hover crosshair stack with the data?

The crosshair is owned by the Chart root and paints behind the grid, area, line, and markers, so the trend always reads on top of the tracking line (the area fades to transparent, so the crosshair still shows through). It is on by default for full charts and off for sparklines; toggle it with the crosshair prop on Chart.

### Will my chart re-theme across the four palettes?

Yes. Series take semantic hues like blue, teal, purple, orange, and pink (or current to inherit the ambient color), so every chart re-themes across all four palettes. Series with no color follow the palette prop: distinct hues led by blue by default, or shades of one blue (palette="tonal", the default on a stack), since a stack reads by its order and needs no rainbow.

### Why layer ChartArea and ChartLine separately?

They are independent parts reading the same measured SVG from context, so you compose the look you want: ChartArea fills under the trend with a fading gradient, and ChartLine adds a crisp edge on top.

### How are negative values and missing data handled?

The domain anchors to zero and bars/areas grow from the y-zero baseline, so negative values render below it with no extra config. Missing points (a non-numeric or absent value) break the line and area by default so dropouts read honestly; pass connectNulls on ChartLine/ChartArea to bridge across them.

### How do I show multiple bar series, grouped or stacked?

Use ChartBars with a keys list. By default the series render grouped side by side; set stack on Chart to stack them, which also grows the y-axis to the per-category total. ChartBar stays the simple single-series option. The same applies to ChartAreas for stacked area bands.

### Where does the legend go?

Put ChartLegend inside the Chart: it keys the chart's own series and sits above the plot (placement="bottom" for below), taking its height from the plot. Hover a key to focus its series, click to hide or show it, Alt+click to see it alone; max folds the rest into a +N more menu. Outside a chart it is a plain key fed the same config or items.

### Can I hide or highlight series from my own UI?

Yes. hiddenSeries with onHiddenSeriesChange controls which series are switched off (hidden series leave the scale, the stacks and the tooltip), and focusedSeries with onFocusedSeriesChange controls the one in focus while the rest recede. A table's checkboxes and row hover can drive both, as in the Driving it from outside example.

### How do I show that today isn't finished yet?

Pass partial on Chart (or a number for several trailing periods). The open stretch of every line dashes on the same curve, areas fade, bars hatch, and the tooltip marks the period with partialLabel, so a half-counted day never reads as a drop.

### How do I compare against the previous period?

Add both series to config and give the current one compare: "previousKey". The earlier series borrows the hue, draws as a faint dashed ghost with no prop set, and the tooltip prints the change beside the current value. Set inverted on metrics where down is good.

### How do I mark a launch or an outage on the chart?

Add a ChartAnnotation with the category index, a short label (a number, or none for a dot), a title and an optional description. The marker sits in a lane above the plot, which makes room for it on its own, and opens the note on hover; the text also reaches screen readers.

### Does Chart draw funnels and pies?

Yes. ChartFunnel draws ordered steps with the drop-off as a faint ghost above each column and the conversion from the first step on top; the tooltip adds conversion and drop-off rows. ChartPie draws each row as a slice, a donut by default (innerRadius 0 for a pie), with children centered in the hole and a ChartLegend keying the slices.

### How do I show a breakdown as one bar?

Use CategoryBar with the rows a pie would take (index names each category, dataKey sizes it) and put a CategoryBarLegend inside it for the key with each share. It rotates distinct hues by default; pass colors to pick them (gray suits an Other bucket) or palette="tonal" for shades of one blue. Hovering a segment or a key recedes the rest and shows the amount and share.

### Why do axis ticks read 12K instead of 12,000?

ChartYAxis prints compact figures by default, the way analytics tools label an axis, so a column of ticks stays narrow and scannable. Pass tickFormatter for currency or any other format; the tooltip and the data table keep the full figures.

### How do I draw a target or threshold line?

Use ChartReferenceLine with y for a horizontal threshold (or x for a vertical marker) and an optional label. Compose it after the data parts so it annotates on top; it is a muted dashed line by default, and a color prop emphasizes it (e.g. destructive for a limit).

### Why does the y-axis go a bit above my largest value?

Full charts round the domain to nice bounds and a 1/2/5 tick step (for example a max of 7,100 extends the axis to 8,000 with ticks at 0, 2k, 4k, 6k, 8k). Grid lines and y-axis labels share that one tick set, so they always align. domain="fit" rounds the same way around the data instead of from zero. Sparklines and an explicit [min, max] domain skip the rounding.

### How do I draw a smooth line?

Pass curve="monotone" to ChartLine and to the ChartArea under it (ChartAreas takes it too). It is a monotone cubic: smooth, but it passes through every point and never overshoots, so a plateau stays flat and a peak sits exactly on its value. Gaps, stacking, dashed lines, markEnd and the draw-in all follow the curve.

### How do I light one bar, or the one under the pointer?

Draw the series in neutral and pass highlight to ChartBar: an index (today), a list, a predicate over the row, or "active" for the hovered bar. highlightColor sets the hue, the brand by default. The predicate also receives the active index, so (row, i, active) => i === (active ?? last) keeps the latest bar lit until another is hovered. Swapping the highlight never replays the grow-in.

### Can I know which category is hovered?

Yes. onActiveIndexChange on Chart reports the index as the pointer crosses the ChartTooltip bands, and null when it leaves. Pass activeIndex to control it instead, for example to light a column from a table row. The crosshair, the active dot, the bar dim and an "active" highlight all follow it.

### How do I add a row to the tooltip?

Pass footer to ChartTooltip. It receives the row and its index and renders under the series rows, below a hairline. Build each row with ChartTooltipItem (color, label, value) so it lines up with the series and keeps its swatch hue in the portaled bubble. labelFormatter also receives the row and index, for a richer heading.

### How do I stop x-axis labels from colliding?

Set interval="auto" on ChartXAxis. It measures the labels against the plot width, skips just enough to keep them apart (minTickGap, 12px by default), re-thins on resize, and counts back from the last category so the latest period always keeps its label. minInterval sets a floor, like 7 for a month read by the week.

### Can a sparkline show bars?

Yes. Put a ChartBar in a sparkline Chart: the categories lay out in bands so the edge bars keep their full width, and the scale runs from zero so every bar keeps its height. ChartTooltip and highlight work as in a full chart.

### Can I pass a ref to Chart?

Yes. Chart merges your ref with the one it measures its box through, so a ref (object or callback) reaches the root div and the chart keeps sizing itself.

### What shows while data is loading or empty?

Pass loading on Chart for a Skeleton placeholder (it also sets aria-busy). With empty data the chart shows a muted message you can replace via the empty prop.

### How accessible is the chart to screen readers?

The SVG is aria-hidden (pixels do not read well), and every full chart renders a visually-hidden data table as its accessible equivalent, so assistive tech reads the real values row by row. Pass label to name the chart; it captions that table. Sparklines stay decorative since they are labelled by their context, like a Stat's value.

### Can I turn off the load animation?

Pass animate={false} on the Chart root. By default every chart plays a one-shot reveal on mount (the line draws, the area rises, bars grow from the baseline). It fires once, not on hover or re-sort, and is held static under prefers-reduced-motion, so opting out is rarely needed.

---

<!-- https://www.koalaui.com/docs/components/data-table.md -->

# Data Table

A data grid built on TanStack Table for behavior (sorting, grouping, row selection, column pinning) with Koala styling on top. Drive features from column defs, or compose the styled primitives directly.

```tsx
// The whole component from booleans + a filter set + an actions slot.
<DataTable
  columns={columns}
  data={members}
  getRowId={(r) => r.id}
  enableSorting
  enableRowSelection
  searchable
  viewOptions
  enableCardLayout
  enablePagination
  pageSize={8}
  filters={[
    { columnId: "status", title: "Status", options: statusOptions },
  ]}
  renderSelectionActions={(rows, table) => (
    <>
      <Button variant="ghost" size="sm" onClick={() => table.resetRowSelection()}>
        <Export /> Export
      </Button>
      <Button variant="destructive" size="sm"><Trash /> Delete</Button>
    </>
  )}
  toolbarActions={
    <>
      <Button variant="outline" iconOnly aria-label="Filter"><FunnelSimple /></Button>
      <Button variant="outline" iconOnly aria-label="Export"><Export /></Button>
      <Button>Register</Button>
    </>
  }
/>
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add data-table
```

Manual: run `npm install @tanstack/react-table radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/data-table/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

Koala splits the two concerns the way TanStack does. The `Table` primitives own the look; TanStack owns the behavior. `DataTable` wires them together: hand it `columns` and `data`, flip on the features you want, and ride alignment and pinning along on each column’s `meta`.

```tsx title="members-table.tsx"
import {
  DataTable,
  TableCellText,
  type ColumnDef,
} from "@/components/ui/data-table"
import { Badge } from "@/components/ui/badge"

type Member = {
  id: string
  name: string
  email: string
  status: "Active" | "Invited" | "Suspended"
  balance: number
}

const columns: ColumnDef<Member>[] = [
  {
    accessorKey: "name",
    header: "Member",
    cell: ({ row }) => (
      <TableCellText primary={row.original.name} secondary={row.original.email} />
    ),
  },
  {
    accessorKey: "status",
    header: "Status",
    cell: ({ getValue }) => <Badge size="sm">{getValue<string>()}</Badge>,
  },
  {
    accessorKey: "balance",
    header: "Balance",
    meta: { numeric: true },
    cell: ({ getValue }) => `$${getValue<number>()}`,
  },
]

export function MembersTable({ data }: { data: Member[] }) {
  return (
    <DataTable
      columns={columns}
      data={data}
      getRowId={(row) => row.id}
      enableSorting
      enableRowSelection
    />
  )
}
```

## Container

The table is chromeless by default (no border, radius, or fill, with the edge cells pulled flush) so it reads as lined records and drops into whatever already frames it. That is the `minimal` surface you see throughout this page. When the table needs to stand on its own, set `variant="container"` to wrap it in the bordered, rounded card. Striping, hover, and pinned columns rebase onto each surface automatically, so every feature keeps working either way.

```tsx
// "minimal" (default, chromeless + flush) or "container" (bordered card)
<DataTable columns={columns} data={members} variant="container" enableSorting />
```

Left at its default, the table drops straight into the page section it belongs to (a settings panel, a dashboard block) sitting on the page surface with only its own row rules, no box stacked around content that’s already laid out. The minimal surface renders on the page background; for a distinct surface, reach for `variant="container"`.

```tsx
// Default (minimal) dropped straight into a page section: no box of its own.
<section>
  <h3 className="font-semibold">Team members</h3>
  <p className="text-sm text-muted-foreground">People with access to this workspace.</p>
  <DataTable columns={columns} data={members} className="mt-4" />
</section>
```

Flush edges leave no padding to absorb a control’s invisible hit area, so the first and last cells clip sideways: an icon button in the last column grows its 40px target without nudging a table that fits into scrolling by a few pixels. Nothing you could see is cut (the scroll box already ended there), and hit areas still reach up and down between rows.

## Toolbar

The control rail above the table is built in and toggled with simple booleans, no wiring. `searchable` adds a search box that filters every column (TanStack’s global filter), and `toolbarActions` is a right-side slot for your own buttons (filter, export, a primary action). The search and any icon buttons are Koala natives ([Input](https://www.koalaui.com/docs/components/input.md) and [Button](https://www.koalaui.com/docs/components/button.md)), so they share the system’s focus rings, density, and press feedback.

```tsx
// searchable filters every column; toolbarActions is the right-side slot.
<DataTable
  columns={columns}
  data={members}
  getRowId={(r) => r.id}
  enableSorting
  searchable
  toolbarActions={
    <>
      <Button variant="outline" iconOnly aria-label="Filter"><FunnelSimple /></Button>
      <Button variant="outline" iconOnly aria-label="Export"><Export /></Button>
      <Button>Register</Button>
    </>
  }
/>
```

On a phone the rail reflows by itself: the search takes the first row at full width, and the filters and the right-hand actions share the next one, filters from the left and actions pushed to the right edge. A single view-options button never ends up alone on a row of its own, so there is nothing to override and no control to drop for small screens.

Need a layout the toggles don’t cover? The parts: `DataTableToolbar`, `DataTableToolbarSection`, and `DataTableSearch` are exported, so you can compose your own rail and drop it above a plain `DataTable`.

```tsx
import {
  DataTable,
  DataTableToolbar,
  DataTableToolbarSection,
  DataTableSearch,
} from "@/components/ui/data-table"

// Compose your own rail, then drop it above a plain DataTable.
<div className="flex flex-col gap-4">
  <DataTableToolbar>
    <DataTableToolbarSection>
      <DataTableSearch />
      <Button variant="outline" iconOnly aria-label="Filter"><FunnelSimple /></Button>
      <Button variant="outline" iconOnly aria-label="Sort"><ArrowsDownUp /></Button>
    </DataTableToolbarSection>
    <DataTableToolbarSection>
      <Button variant="outline" iconOnly aria-label="Export"><Export /></Button>
      <Button>Register</Button>
    </DataTableToolbarSection>
  </DataTableToolbar>

  <DataTable columns={columns} data={members} enableSorting />
</div>
```

## View options

`viewOptions` adds a `SlidersHorizontal` dropdown to the toolbar for showing and hiding columns. Every column with a label appears as a checkbox, and the menu stays open so you can toggle several at once. Give a column a `meta.label` for its name there (a string `header` is used as the fallback); the selection and icon-only action columns have no label, so they’re left out.

`enableCardLayout` adds a Rows/Cards switch to the same dropdown and renders the rows as a responsive card grid when chosen: the first column becomes the card title, the rest stack as labelled fields, and an icon-only action rides along top-right. Pass `renderCard` to take over the card entirely. The cards cascade in on load via the shared [Stagger](https://www.koalaui.com/docs/foundations/motion.md) primitive.

```tsx
// viewOptions: column show/hide. enableCardLayout: Rows/Cards switch + card grid.
<DataTable
  columns={columns}
  data={members}
  getRowId={(r) => r.id}
  enableSorting
  searchable
  viewOptions
  enableCardLayout
/>

// Name a column in the menu (and as a card field label):
const columns = [
  { accessorKey: "balance", header: "Balance", meta: { label: "Balance", numeric: true } },
]

// Or take over the card entirely:
<DataTable columns={columns} data={members} enableCardLayout renderCard={(row) => (
  <Card>…</Card>
)} />
```

## Filtering

Beyond the global `searchable` box, pass `filters` to add per-column faceted filters. Each field becomes a multi-select dropdown in the toolbar (with the count of matching rows per option) and a removable chip below it; a `Reset` clears them all. Filtered columns use the built-in `filterFn: "arrIncludesSome"`.

```tsx
// Each filtered column uses filterFn: "arrIncludesSome".
const columns = [
  { accessorKey: "status", header: "Status", filterFn: "arrIncludesSome", cell: StatusBadge },
  { accessorKey: "team", header: "Team", filterFn: "arrIncludesSome" },
]

<DataTable
  columns={columns}
  data={members}
  getRowId={(r) => r.id}
  searchable
  filters={[
    {
      columnId: "status",
      title: "Status",
      options: [
        { value: "Active", label: "Active" },
        { value: "Invited", label: "Invited" },
        { value: "Suspended", label: "Suspended" },
      ],
    },
    {
      columnId: "team",
      title: "Team",
      options: [
        { value: "Engineering", label: "Engineering", icon: <UsersThree /> },
        { value: "Design", label: "Design", icon: <UsersThree /> },
        { value: "Marketing", label: "Marketing", icon: <UsersThree /> },
      ],
    },
  ]}
/>
```

The parts are exported too: `DataTableFacetedFilter` and `DataTableActiveFilters`, for hand-composed toolbars over a table instance you own.

## Tabs

Line tabs over a table split one list into views (All, Active, Invited), each with its count. Wrap the table in `DataTableTabs`, put a `DataTableTabsList` of `DataTableTab`s above it, and hand each tab its `count`. The rows stay yours to filter, from the same place the counts come from; the parts own the rest. The table becomes the panel the tabs control, so a screen reader hears which view it is in, and switching views takes it back to its first page while the search, the sort and the selection that still applies stay put. No remounting the table with a `key` to reset the page, and nothing lost when you do.

```tsx
import {
  DataTable,
  DataTableTabs,
  DataTableTabsList,
  DataTableTab,
} from "@/components/ui/data-table"

const views = [
  { value: "all", label: "All" },
  { value: "Active", label: "Active" },
  { value: "Invited", label: "Invited" },
  { value: "Suspended", label: "Suspended" },
]

const inView = (view: string) =>
  view === "all" ? members : members.filter((member) => member.status === view)

function Members() {
  const [view, setView] = useState("all")
  const rows = useMemo(() => inView(view), [view])
  return (
    <DataTableTabs value={view} onValueChange={setView} className="w-full">
      <DataTableTabsList aria-label="Member status">
        {views.map((item) => (
          <DataTableTab key={item.value} value={item.value} count={inView(item.value).length}>
            {item.label}
          </DataTableTab>
        ))}
      </DataTableTabsList>
      <DataTable
        columns={columns}
        data={rows}
        getRowId={(row) => row.id}
        enableSorting
        enableRowSelection
        searchable
        enablePagination
        pageSize={6}
      />
    </DataTableTabs>
  )
}
```

## Remembering view state

Pass a `persistKey` and the table remembers how the user left it (which columns are visible, their order, the sort, the rows/cards layout, and the page size) by writing them to `localStorage` under that key. It’s SSR-safe: the server renders the defaults and the saved state is applied after mount, so hydration stays clean. Hide a column or switch to cards below, then reload the page, and it comes back the same.

```tsx
// Remembers visible columns, their order, sort, layout, and page size across reloads.
<DataTable
  columns={columns}
  data={members}
  getRowId={(r) => r.id}
  enableSorting
  viewOptions
  enableCardLayout
  persistKey="members"
/>
```

Use a key that’s unique per table (and per user, if you scope storage that way). Persistence is best-effort: unavailable or full storage fails quietly and the table just opens at its defaults.

## Cell types

A column’s `cell` renders anything, so a row reads like a record rather than a wall of text. Compose the cells from the same DS parts you use everywhere else: an avatar beside two-line text (`TableCellText`), a status [Badge](https://www.koalaui.com/docs/components/badge.md), a row of tag chips, a directional trend delta tinted `success`/`destructive`, an inline sparkline built on [Chart](https://www.koalaui.com/docs/components/chart.md) in sparkline mode, and an overlapping [Avatar](https://www.koalaui.com/docs/components/avatar.md) stack with a `+N` overflow. Numbers right-align with `meta.numeric` (it adds `tabular-nums`).

```tsx
import { Chart, ChartArea, ChartLine } from "@/components/ui/chart"
import { Avatar, AvatarImage, AvatarFallback } from "@/components/ui/avatar"
import { Badge } from "@/components/ui/badge"

const columns: ColumnDef<Member>[] = [
  {
    accessorKey: "name",
    header: "Member",
    cell: ({ row }) => <MemberCell member={row.original} />,
  },
  {
    accessorKey: "status",
    header: "Status",
    cell: ({ getValue }) => <Badge variant={statusVariant[getValue<Status>()]} size="sm">{getValue<string>()}</Badge>,
  },
  {
    accessorKey: "tags",
    header: "Tags",
    // First few as chips, the rest rolled into a tooltipped "+N".
    cell: ({ row }) => <TagsCell tags={row.original.tags} />,
  },
  {
    accessorKey: "delta",
    header: "Trend",
    meta: { align: "right" },
    // Arrow + signed % tinted success/destructive, tabular-nums.
    cell: ({ row }) => <TrendCell delta={row.original.delta} />,
  },
  {
    accessorKey: "activity",
    header: "Activity",
    // Chart in sparkline mode; paints in currentColor, so a text-* utility themes it.
    cell: ({ row }) => (
      <Chart data={row.original.activity} sparkline aria-hidden className="h-8 w-24 text-success">
        <ChartArea />
        <ChartLine strokeWidth={2} hideActiveDot />
      </Chart>
    ),
  },
  {
    id: "assignees",
    header: "Assignees",
    // Overlapping avatars with a +N overflow (the canonical Avatar stack).
    cell: ({ row }) => <AssigneesCell people={row.original.assignees} />,
  },
]

<DataTable columns={columns} data={members} getRowId={(r) => r.id} enableSorting />
```

## Column tooltips

Two per-column hints ride along on `meta`, both backed by the shared [Tooltip](https://www.koalaui.com/docs/components/tooltip.md). `headerTooltip` appends a small info icon after the header label, for explaining what a column measures without crowding the title (hover the Balance header). `cellTooltip` is a function given the cell context that returns the hint to show for each cell. Return `null` to skip one. It pairs naturally with a clamped column: truncate the cell and reveal the full value on hover or focus (hover a member name). Both triggers are keyboard-reachable.

The cell hint fills the cell exactly as its content would, so it never changes the column’s layout: a full-width [Progress](https://www.koalaui.com/docs/components/progress.md) keeps its width (hover an Onboarding bar), text keeps the column’s alignment, and a truncated cell still truncates.

```tsx
const columns: ColumnDef<Member>[] = [
  {
    accessorKey: "name",
    header: "Member",
    // Clamp the cell, then tooltip it with the full value so nothing is lost.
    meta: {
      cellTooltip: ({ row }) => `${row.original.name} · ${row.original.email}`,
    },
    cell: ({ row }) => (
      <span className="block max-w-[12rem] truncate">
        {row.original.name} · {row.original.email}
      </span>
    ),
  },
  {
    accessorKey: "role",
    header: "Role",
    cell: ({ getValue }) => <span className="text-muted-foreground">{getValue<string>()}</span>,
  },
  {
    id: "onboarding",
    accessorFn: (row) => row.onboarding,
    header: "Onboarding",
    // The hint wraps the cell without resizing it, so a full-width Progress keeps its width.
    meta: {
      label: "Onboarding",
      cellTooltip: ({ getValue }) => `${getValue<number>()} of 5 steps done`,
    },
    cell: ({ row, getValue }) => (
      <Progress value={getValue<number>()} max={5} aria-label={`${row.original.name}'s onboarding`} />
    ),
  },
  {
    accessorKey: "balance",
    header: "Balance",
    // An info icon after the header label reveals this on hover/focus.
    meta: {
      numeric: true,
      headerTooltip: "Outstanding balance for the current billing cycle, in USD.",
    },
    cell: ({ getValue }) => currency.format(getValue<number>()),
  },
]

<DataTable columns={columns} data={members} getRowId={(r) => r.id} enableSorting />
```

## Sorting

Set `enableSorting` to make headers click-to-sort. The header shows a muted up/down caret until active, then a solid directional one. Seed an order with `initialSorting`.

```tsx
<DataTable
  columns={columns}
  data={members}
  getRowId={(r) => r.id}
  enableSorting
  initialSorting={[{ id: "balance", desc: true }]}
/>
```

## Reordering

Sorting computes an order; reordering lets the user author one. Pass `onRowReorder` and every row grows a grip: drag it and the move arrives as the two indices it travelled between, which you apply to your own data (`moveItem` does the array move). The table never reorders `data` itself, so the order stays in the source of truth you already own and is yours to save.

```tsx
import { DataTable, moveItem } from "@/components/ui/data-table"

function MembersTable() {
  const [rows, setRows] = useState(members)
  return (
    <DataTable
      columns={columns}
      data={rows}
      getRowId={(r) => r.id}
      // Drag a row's grip (or focus it and press the arrow keys) and the move lands here.
      onRowReorder={({ fromIndex, toIndex }) =>
        setRows((current) => moveItem(current, fromIndex, toIndex))
      }
    />
  )
}
```

The row you grab is lifted, and the rows it passes step aside: the gap that opens is the drop indicator, so there is no line to read and no guessing which side of it you land on. Release and the row eases into the gap before the move is applied, so it settles rather than jumps. The gesture runs on pointer events, not the HTML5 drag-and-drop API, which is what lets it work on touch, keep its own cursor, and pull the view along when you drag past the edge of a scrolling table. `Esc` cancels mid-drag and leaves the data alone.

The grip is the only drag source, so selecting text in a cell still works, and it has a keyboard twin: focus it and press `↑` or `↓` to walk the row one place at a time, with each move announced to screen readers. A hand-made order only means something while the rows are in data order, so the grips go inert (and say why) under a sort or a grouping.

`enableColumnOrdering` does the same for columns, and a column travels whole: the header and every cell under it move together, with the columns on either side opening the gap. Grip it, or nudge it with `←` / `→`. That one the table can own outright, so there is nothing to wire; take `onColumnOrderChange` if you want to know, seed it with `initialColumnOrder`, or hand the table a `persistKey` and it remembers the order itself. Columns pinned with `meta.sticky` stay where they are pinned.

```tsx
<DataTable
  columns={columns}
  data={members}
  getRowId={(r) => r.id}
  enableColumnOrdering
  enableSorting
  // Optional: hear about it, seed it, or let persistKey remember it.
  onColumnOrderChange={(order) => console.log(order)}
/>
```

## Row hover

Rows highlight on hover by default: only body rows, never the header. Pass `hoverable={false}` to opt out (the striped example below does, so the zebra pattern stays crisp).

## Striped rows

`striped` zebra-stripes even rows for faster scanning. The stripe is scoped to skip hovered and selected rows, so those states always read clearly.

```tsx
<DataTable columns={columns} data={members} striped hoverable={false} />
```

## Condensed rows

Density is Koala’s cross-cutting spacing axis (see [Density](https://www.koalaui.com/docs/foundations/density.md)). For a table it’s the condensed-rows knob: `compact` is the dense default; `comfortable` is roomier. Set it per-table or for a whole subtree with `DensityProvider`.

```tsx
// "compact" (condensed, the default) or "comfortable"
<DataTable columns={columns} data={members} density="compact" />
```

## Grouping

`enableGrouping` with an `initialGrouping` column collapses rows into expandable groups. Give a column an `aggregationFn` and `aggregatedCell` to summarize each group; here the balance column sums per team.

```tsx
const columns: ColumnDef<Member>[] = [
  { accessorKey: "team", header: "Team" },
  { accessorKey: "name", header: "Member", aggregatedCell: () => null },
  {
    accessorKey: "balance",
    header: "Balance",
    meta: { numeric: true },
    aggregationFn: "sum",
    cell: ({ getValue }) => format(getValue<number>()),
    aggregatedCell: ({ getValue }) => format(getValue<number>()),
  },
]

<DataTable
  columns={columns}
  data={members}
  enableGrouping
  initialGrouping={["team"]}
/>
```

## Expandable rows

Pass `renderSubRow` to reveal a detail panel under a row. It prepends a caret toggle column and renders your node full-width beneath the expanded row. Limit which rows can expand with `getRowCanExpand`.

```tsx
<DataTable
  columns={columns}
  data={members}
  getRowId={(r) => r.id}
  // Optional: only some rows expand
  getRowCanExpand={(row) => row.original.role !== "Viewer"}
  // A read-only detail panel, so these are your own label/value rows, not form Fields.
  renderSubRow={(row) => (
    <div className="grid gap-4 rounded-lg bg-muted/40 p-4 sm:grid-cols-3">
      <DetailField icon={<EnvelopeSimple />} label="Email" value={row.original.email} />
      <DetailField icon={<IdentificationBadge />} label="Role" value={row.original.role} />
      <DetailField icon={<UsersThree />} label="Team" value={row.original.team} />
    </div>
  )}
/>
```

## With checkboxes

`enableRowSelection` prepends a checkbox column with a header “select all” that goes indeterminate on a partial selection. Subscribe with `onRowSelectionChange`; pass a stable `getRowId` so selection survives re-sorts.

```tsx
const [selection, setSelection] = useState({})

<DataTable
  columns={columns}
  data={members}
  getRowId={(r) => r.id}
  enableRowSelection
  onRowSelectionChange={setSelection}
/>
```

The selection control is the shared [Checkbox](https://www.koalaui.com/docs/components/checkbox.md) component, in checked, indeterminate, and disabled states:

```tsx
<Checkbox checked onCheckedChange={...} />
<Checkbox checked="indeterminate" />
<Checkbox checked={false} />
<Checkbox checked disabled />
```

## Bulk actions

With selection on, pass `renderSelectionActions` and a floating pill rises while rows are selected: the live count, a clear button, and your actions. It’s a dark bar (the Figma/Linear look) that reads as one distinct object over the table, and any Koala `Button` or menu you drop in re-tints to it automatically. It overlays the bottom of the table out of flow, so it appears and leaves without shifting the toolbar above or anything on the page below. The renderer receives the selected rows and the table instance, so an action can read the selection and reset it. Select a couple of rows below.

```tsx
<DataTable
  columns={columns}
  data={data}
  getRowId={(r) => r.id}
  enableRowSelection
  // The pill is a dark bar; drop plain Koala Buttons in and they read light on it for free.
  renderSelectionActions={(rows, table) => (
    <>
      {/* Quiet actions: icon-only ghosts (aria-label doubles as the tooltip). */}
      <Button variant="ghost" size="sm" iconOnly aria-label="Assign"><UserPlus /></Button>
      <Button variant="ghost" size="sm" iconOnly aria-label="Add tag"><Tag /></Button>
      <Button variant="ghost" size="sm" iconOnly aria-label="Archive"><Archive /></Button>
      <Button variant="ghost" size="sm" onClick={() => table.resetRowSelection()}>
        <Export /> Export
      </Button>
      {/* Overflow menu for the rest. */}
      <DropdownMenu>
        <DropdownMenuTrigger asChild>
          <Button variant="ghost" size="sm" iconOnly aria-label="More actions" tooltip={false}>
            <DotsThree />
          </Button>
        </DropdownMenuTrigger>
        <DropdownMenuContent align="end">
          <DropdownMenuItem><Copy /> Duplicate</DropdownMenuItem>
          <DropdownMenuItem><FolderSimple /> Move to project</DropdownMenuItem>
          <DropdownMenuItem><EnvelopeSimple /> Email selected</DropdownMenuItem>
        </DropdownMenuContent>
      </DropdownMenu>
      <span aria-hidden className="mx-0.5 h-5 w-px bg-border" />
      <Button
        variant="destructive"
        size="sm"
        onClick={() => {
          const ids = new Set(rows.map((r) => r.original.id))
          setData((prev) => prev.filter((m) => !ids.has(m.id)))
          table.resetRowSelection()
        }}
      >
        <Trash /> Delete
      </Button>
    </>
  )}
/>
```

## Opening a row

The record-list pattern: click a row and the screen shows that record, in a pane beside the table, a drawer or a page of its own. Pass `onRowClick` and every row opens on a click anywhere across it, while the controls inside keep their own jobs (the checkbox checks, the row menu opens, a link navigates) and a drag that selects text is left alone. Rows become focusable with a brand ring, and `Enter` on a focused row opens it, so the keyboard gets the same path as the pointer.

Tell the table which record is open with `activeRowId`. That row takes a brand tint, deliberately a different color from the checkbox-selected fill, since a row can be picked for a bulk action and open at once, and it carries `aria-current`. To walk the list from the pane, `onDisplayedRowsChange` hands you the rows in the order the table shows them, search and sort included, so previous and next follow the screen. Search, re-sort, then step through below.

```tsx
function Members() {
  const [openId, setOpenId] = useState<string | null>("2")
  // The rows in the order the table shows them, search and sort included.
  const [shown, setShown] = useState<Member[]>([])
  const open = members.find((member) => member.id === openId) ?? null
  const position = shown.findIndex((member) => member.id === openId)

  const step = (delta: -1 | 1) => {
    const next = shown[position + delta]
    if (next) setOpenId(next.id)
  }

  return (
    <div className="flex w-full flex-col gap-4">
      <DataTable
        columns={columns}
        data={members}
        getRowId={(row) => row.id}
        enableSorting
        enableRowSelection
        searchable
        onRowClick={(row) => setOpenId(row.id)}
        activeRowId={openId}
        onDisplayedRowsChange={(rows) => setShown(rows.map((row) => row.original))}
      />
      {open ? (
        <Card aria-label="Open member">
          <CardHeader>
            <CardTitle>{open.name}</CardTitle>
            <CardDescription>{open.email}</CardDescription>
            <CardAction className="flex items-center gap-1">
              <span className="mr-1 text-sm text-muted-foreground tabular-nums">
                {position >= 0 ? `${position + 1} of ${shown.length}` : "Not in view"}
              </span>
              <Button variant="ghost" size="sm" iconOnly aria-label="Previous member"
                disabled={position <= 0} onClick={() => step(-1)}>
                <CaretUp />
              </Button>
              <Button variant="ghost" size="sm" iconOnly aria-label="Next member"
                disabled={position < 0 || position >= shown.length - 1} onClick={() => step(1)}>
                <CaretDown />
              </Button>
            </CardAction>
          </CardHeader>
          <CardContent>
            <DescriptionList>
              <DescriptionListItem>
                <DescriptionTerm>Role</DescriptionTerm>
                <DescriptionDetails>{open.role}</DescriptionDetails>
              </DescriptionListItem>
              <DescriptionListItem>
                <DescriptionTerm>Team</DescriptionTerm>
                <DescriptionDetails>{open.team}</DescriptionDetails>
              </DescriptionListItem>
              <DescriptionListItem>
                <DescriptionTerm>Balance</DescriptionTerm>
                <DescriptionDetails className="tabular-nums">
                  {currency.format(open.balance)}
                </DescriptionDetails>
              </DescriptionListItem>
            </DescriptionList>
          </CardContent>
        </Card>
      ) : null}
    </div>
  )
}
```

## Sticky header

`stickyHeader` pins the header while the body scrolls. Cap the scroll container’s height with `containerClassName` (e.g. `max-h-72`) to create the scroll.

```tsx
<DataTable
  columns={columns}
  data={rows}
  stickyHeader
  containerClassName="max-h-72"
/>
```

## Sticky column

Pin a column to an edge with `meta: { sticky: "left" }` (or `"right"`). It stays put, tracking the row’s hover and selected background, while the rest scrolls sideways.

```tsx
const columns: ColumnDef<Member>[] = [
  {
    accessorKey: "name",
    header: "Member",
    meta: { sticky: "left" }, // pinned while the rest scrolls sideways
    cell: ({ row }) => <MemberCell member={row.original} />,
  },
  { accessorKey: "team", header: "Team" },
  { accessorKey: "role", header: "Role" },
  { accessorKey: "status", header: "Status", cell: /* Badge */ },
  { accessorKey: "tags", header: "Tags", cell: /* chips */ },
  { accessorKey: "delta", header: "Trend", cell: /* trend */ },
  { accessorKey: "activity", header: "Activity", cell: /* sparkline */ },
  { accessorKey: "email", header: "Email" },
  { accessorKey: "balance", header: "Balance", meta: { numeric: true } },
]

// The table is wider than its container, so the un-pinned columns scroll under the pinned one.
<DataTable columns={columns} data={members} className="min-w-[72rem]" />
```

## Pagination

`enablePagination` pages the rows client-side and drops a [Pagination](https://www.koalaui.com/docs/components/pagination.md) toolbar below the table: prev/next, a “Page X of Y” readout, and a rows-per-page select. Set the initial page size with `pageSize` and the select’s choices with `pageSizeOptions`. It shares the table’s density, and pages are disabled while `loading`.

```tsx
<DataTable
  columns={columns}
  data={members}
  getRowId={(r) => r.id}
  enablePagination
  pageSize={8}
  pageSizeOptions={[8, 16, 24, 50, 100]}
/>
```

The page never points past the end. When `data` shrinks under it (a delete, a filter your screen applies itself) the table steps back to the last page that still exists, and an edit that keeps the row count keeps the page. The rows-per-page select always offers the size in use: left out of `pageSizeOptions`, it is merged in and sorted, and with no options at all they are built around `pageSize` (one, two and three pages, then 50 and 100). Go to page 3 below, then remove rows.

```tsx
function Members() {
  const [rows, setRows] = useState(() => members.slice(0, 14))
  return (
    <div className="flex w-full flex-col gap-3">
      <div className="flex flex-wrap gap-2">
        <Button
          variant="outline"
          size="sm"
          disabled={rows.length === 0}
          onClick={() => setRows((current) => current.slice(0, -5))}
        >
          Remove 5 rows
        </Button>
        <Button
          variant="ghost"
          size="sm"
          disabled={rows.length === 14}
          onClick={() => setRows(members.slice(0, 14))}
        >
          Restore
        </Button>
      </div>
      {/* No pageSizeOptions: the select offers 5, 10, 15, 50 and 100. */}
      <DataTable
        columns={columns}
        data={rows}
        getRowId={(row) => row.id}
        enablePagination
        pageSize={5}
      />
    </div>
  )
}
```

## Load on scroll

For server-driven lists, swap paging for infinite scroll: pass `onLoadMore` and a `hasMore` flag, and the table fetches the next batch as a sentinel scrolls into view (prefetching ~200px early). Flip `loadingMore` while the request is in flight; it shows a loading row and blocks duplicate calls. You fetch and append to `data`; the sentinel watches the nearest scroll container (here a capped `max-h` wrapper) or the viewport. It replaces the pagination toolbar; the two are mutually exclusive.

```tsx
function MembersTable() {
  const [rows, setRows] = useState(() => fetchPage(0))
  const [loadingMore, setLoadingMore] = useState(false)
  const hasMore = rows.length < total

  async function loadMore() {
    setLoadingMore(true)
    const next = await fetchPage(rows.length)
    setRows((prev) => [...prev, ...next])
    setLoadingMore(false)
  }

  return (
    // The sentinel watches the nearest scroll container (or the viewport).
    <div className="max-h-96 overflow-auto">
      <DataTable
        columns={columns}
        data={rows}
        getRowId={(r) => r.id}
        variant="container"
        onLoadMore={loadMore}
        hasMore={hasMore}
        loadingMore={loadingMore}
      />
    </div>
  )
}
```

## Server-side data

By default the table sorts, filters, and pages the rows it’s given. For large or remote datasets, flip the work to the server: set `manualSorting`, `manualFiltering`, and/or `manualPagination`, then fetch on the `onSortingChange` / `onPaginationChange` / `onColumnFiltersChange` callbacks and feed back the current page as `data`. Pass `pageCount` (or `rowCount`) so the pager knows the total. The demo simulates a 500ms round-trip per sort and page.

```tsx
function MembersTable() {
  const [rows, setRows] = useState(() => fetchPage({ sorting: [], pageIndex: 0 }))
  const [loading, setLoading] = useState(false)

  async function load(query) {
    setLoading(true)
    const { rows, pageCount } = await fetchPage(query) // your server
    setRows(rows)
    setLoading(false)
  }

  return (
    <DataTable
      columns={columns}
      data={rows}
      getRowId={(r) => r.id}
      enableSorting
      enablePagination
      manualSorting
      manualPagination
      pageCount={pageCount}
      loading={loading}
      onSortingChange={(sorting) => load({ sorting, pageIndex: 0 })}
      onPaginationChange={(p) => load({ sorting, pageIndex: p.pageIndex })}
    />
  )
}
```

## Controlled state

The table keeps its own state until you want it. Pass `sorting`, `globalFilter` or `columnVisibility` with the matching `on*Change` and that piece is yours: reset it from a button, keep it in the URL, or drive the search from a field elsewhere on the screen (a controlled `globalFilter` filters with or without the built-in box). Left uncontrolled, every `on*Change` still reports each change, the built-in search box included, and always after the table has committed it, never from inside a state update, so setting your own state straight from one is safe.

`onDisplayedRowsChange` reads the other way: it hands you the rows the table is showing, in its order, across every page, after mount and whenever that list changes. Use it for a summary, an export of the current view, or previous and next in a detail pane. Sort or search below and the line under the table follows.

```tsx
const BALANCE_FIRST: SortingState = [{ id: "balance", desc: true }]

function Members() {
  const [query, setQuery] = useState("")
  const [sorting, setSorting] = useState<SortingState>(BALANCE_FIRST)
  const [shown, setShown] = useState<Member[]>([])
  const total = shown.reduce((sum, member) => sum + member.balance, 0)
  const changed = query !== "" || sorting !== BALANCE_FIRST

  return (
    <div className="flex w-full flex-col gap-4">
      <DataTableToolbar>
        <DataTableToolbarSection>
          <DataTableSearch
            placeholder="Search members"
            shortcut={false}
            value={query}
            onChange={(event) => setQuery(event.target.value)}
          />
        </DataTableToolbarSection>
        <DataTableToolbarSection>
          <Button
            variant="outline"
            disabled={!changed}
            onClick={() => {
              setQuery("")
              setSorting(BALANCE_FIRST)
            }}
          >
            Reset view
          </Button>
        </DataTableToolbarSection>
      </DataTableToolbar>
      <DataTable
        columns={columns}
        data={members}
        getRowId={(row) => row.id}
        enableSorting
        sorting={sorting}
        onSortingChange={setSorting}
        globalFilter={query}
        onGlobalFilterChange={setQuery}
        onDisplayedRowsChange={(rows) => setShown(rows.map((row) => row.original))}
      />
      <p className="text-sm text-pretty text-muted-foreground tabular-nums">
        {shown.length} of {members.length} members on show, {currency.format(total)} outstanding.
        {shown[0] ? ` First in line: ${shown[0].name}.` : ""}
      </p>
    </div>
  )
}
```

## Loading

Pass `loading` to swap the rows for skeleton placeholders while data is in flight. They mirror the real column layout (numeric columns get a short right-aligned bar, the select column a checkbox-sized square) so the table doesn’t reflow when data lands. Tune the count with `loadingRows`; the region is announced with `aria-busy`.

```tsx
<DataTable columns={columns} data={data} loading loadingRows={5} />
```

## Empty states

When there are no rows, the table renders `DataTableEmpty`, a preset over [EmptyState](https://www.koalaui.com/docs/components/empty-state.md) built for the two cases a grid hits. The default is `kind="empty"` (nothing here yet); override the `emptyState` prop and pass action buttons as children.

```tsx
import { DataTable, DataTableEmpty } from "@/components/ui/data-table"

<DataTable
  columns={columns}
  data={[]}
  emptyState={
    <DataTableEmpty>
      <Button variant="outline">Register</Button>
    </DataTableEmpty>
  }
/>
```

When a search or filter comes up empty, switch to `kind="search"`: the not-found icon and copy, with a “clear filters” escape hatch. With the built-in `searchable` toolbar this happens automatically: an active search that matches nothing falls back to the search-empty placeholder.

```tsx
// when a search/filter comes up empty
<DataTable
  columns={columns}
  data={filtered}
  emptyState={
    <DataTableEmpty kind="search">
      <Button variant="outline">Clear filters</Button>
    </DataTableEmpty>
  }
/>
```

## Primitives

For a static or fully bespoke table, skip TanStack and compose the styled primitives directly: `Table`, `TableHeader`, `TableBody`, `TableFooter`, `TableRow`, `TableHead`, `TableCell`. The same variants (variant, striped, hover, density, sticky) apply.

```tsx
<Table>
  <TableHeader>
    <TableRow>
      <TableHead>Member</TableHead>
      <TableHead>Status</TableHead>
      <TableHead align="right">Balance</TableHead>
    </TableRow>
  </TableHeader>
  <TableBody>
    {members.map((m) => (
      <TableRow key={m.id}>
        <TableCell>
          <TableCellText primary={m.name} secondary={m.email} />
        </TableCell>
        <TableCell><Badge size="sm">{m.status}</Badge></TableCell>
        <TableCell numeric>{format(m.balance)}</TableCell>
      </TableRow>
    ))}
  </TableBody>
  <TableFooter>
    <TableRow>
      <TableCell colSpan={2}>Total</TableCell>
      <TableCell numeric>{format(total)}</TableCell>
    </TableRow>
  </TableFooter>
</Table>
```

## FAQ

### When should I use DataTable versus composing the Table primitives directly?

Reach for DataTable when you need behavior driven from column defs: sorting, grouping, row selection, faceted filters, pagination, or the card layout. For a static or fully bespoke table, skip TanStack and compose Table, TableHeader, TableBody, TableRow, TableHead, and TableCell yourself, which keep the same variant, striped, hover, density, and sticky options.

### How do I right-align a numeric column and pin one to an edge?

Both ride along on a column's meta. Set meta.numeric to right-align the header and cells and apply tabular-nums, and set meta.sticky to 'left' or 'right' to pin a column while the rest scrolls horizontally. Use meta.align for non-numeric center or right alignment.

### Does dragging work on touch, and why not use HTML5 drag and drop?

Yes: the gesture is built on pointer events, so it works the same with a finger, a pen or a mouse. The native HTML5 drag-and-drop API does not fire on touch at all, it hands you the browser's washed-out snapshot of the row instead of the row itself, it will not let you change the cursor, and it cannot ease the row into place on drop. Pointer events give all four, plus Escape to cancel and autoscroll when you drag past the edge of a scrolling table.

### Why are the row grips greyed out?

A hand-made row order only means something while the rows are in data order. Under a sort or a grouping the table is deciding the order, so the grips go inert and their tooltip says which one to clear. Column grips are never blocked that way, since a column's place is never computed from the data.

### Does dragging rows change my data?

No. onRowReorder reports the move as fromIndex and toIndex, both indices into the data array you passed, and nothing moves until you apply it. Use the exported moveItem helper (setRows((rows) => moveItem(rows, fromIndex, toIndex))) and persist the result however you already persist that data. Column order is different: the table owns that state, so enableColumnOrdering needs no wiring, and persistKey remembers it for you.

### Why does row selection lose its checks after I sort or filter?

Selection is keyed by row id, so without a stable key TanStack falls back to the row index and the selection no longer follows the row. Pass a stable getRowId, for example getRowId={(r) => r.id}, and the selection (and grouping) survives re-sorts.

### How do I open a row in a detail pane without the checkbox or the row menu opening it too?

Pass onRowClick. It fires for a click anywhere on the row except on a control inside it (a button, link, checkbox, input, label or menu item), and for Enter on a focused row. Then pass the open record's id as activeRowId: that row takes a brand tint distinct from the selected fill and carries aria-current, and onDisplayedRowsChange gives you the rows in display order for previous and next.

### Can I set my own state from onSortingChange, onRowSelectionChange or the other callbacks?

Yes. Every on*Change fires after the table has committed the change, never from inside a state update, so calling setState from it is safe and it fires once, even under StrictMode. To own a piece of state outright, pass sorting, globalFilter or columnVisibility alongside its callback and the table follows your value.

### How do I build a custom toolbar instead of using the searchable and toolbarActions toggles?

Compose the exported parts: DataTableToolbar, DataTableToolbarSection, and DataTableSearch for the rail, plus DataTableFacetedFilter and DataTableActiveFilters for filters. Drop your rail above a plain DataTable when the built-in booleans do not cover the layout you need.

### Can the toolbar search and icon buttons be reached by keyboard, and are the tooltips accessible?

Yes. The search box is the Koala Input and toolbar buttons are the Koala Button, so they share the system focus rings and press feedback. The headerTooltip info icon and cellTooltip wrapper are both focusable triggers, so the hints are reachable by keyboard, not only on hover.

### Can I use both client-side pagination and infinite scroll at the same time?

No, they are mutually exclusive. Setting onLoadMore (with hasMore and loadingMore) enables infinite scroll and replaces the Pagination toolbar that enablePagination would render, so choose one. For remote datasets, flip manualSorting, manualFiltering, or manualPagination and refetch on the matching on*Change callback.

---

<!-- https://www.koalaui.com/docs/components/description-list.md -->

# Description List

A semantic key/value detail view for records: profiles, invoices, settings read-outs. It renders a real dl/dt/dd tree, splits term and value at sm, and any value cell composes Koala parts like Badge or Avatar.

```tsx
<Card className="w-full max-w-md">
  <CardHeader>
    <CardTitle>Subscription</CardTitle>
  </CardHeader>
  <CardContent>
    <DescriptionList divided>
      <DescriptionListItem>
        <DescriptionTerm>
          <CreditCard /> Plan
        </DescriptionTerm>
        <DescriptionDetails>
          Pro <Badge variant="success" size="sm" pill>Annual</Badge>
        </DescriptionDetails>
      </DescriptionListItem>
      <DescriptionListItem>
        <DescriptionTerm>
          <UsersThree /> Seats
        </DescriptionTerm>
        <DescriptionDetails>12 of 20</DescriptionDetails>
      </DescriptionListItem>
      <DescriptionListItem>
        <DescriptionTerm>
          <CalendarDots /> Renews
        </DescriptionTerm>
        <DescriptionDetails>March 1, 2026</DescriptionDetails>
      </DescriptionListItem>
      <DescriptionListItem>
        <DescriptionTerm>
          <UserCircle /> Owner
        </DescriptionTerm>
        <DescriptionDetails>Jordi Espinosa</DescriptionDetails>
      </DescriptionListItem>
    </DescriptionList>
  </CardContent>
</Card>
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add description-list
```

Manual: run `npm install radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/description-list/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

```tsx title="usage.tsx"
import {
  DescriptionList,
  DescriptionListItem,
  DescriptionTerm,
  DescriptionDetails,
} from "@/components/ui/description-list"

export function Example() {
  return (
    <DescriptionList>
      <DescriptionListItem>
        <DescriptionTerm>Email</DescriptionTerm>
        <DescriptionDetails>jordi@koalaui.com</DescriptionDetails>
      </DescriptionListItem>
    </DescriptionList>
  )
}
```

## Layout

`row` (default) places the term in a fixed-width column with the value beside it, splitting at the `sm` breakpoint and stacking on mobile. `stack` keeps the term above the value at every width, better for narrow surfaces and long values. `auto` and `inline` follow below. A term that leads with an icon keeps the value on its text's baseline, not the icon's edge.

```tsx
<DescriptionList layout="row">
  <DescriptionListItem>
    <DescriptionTerm>Email</DescriptionTerm>
    <DescriptionDetails>jordi@koalaui.com</DescriptionDetails>
  </DescriptionListItem>
  <DescriptionListItem>
    <DescriptionTerm>Location</DescriptionTerm>
    <DescriptionDetails>Barcelona, Spain</DescriptionDetails>
  </DescriptionListItem>
</DescriptionList>

<DescriptionList layout="stack">
  {/* term sits above the value */}
</DescriptionList>
```

## Values with pictures

A value can lead with an Avatar, a Flag, a logo or icon, a Badge or a Select, and the row still reads on the text: the name sits on the term's baseline and the picture is centred on that line, 8px from the text after it. Put them straight in `DescriptionDetails` with no `flex` or alignment classes: a flex value takes its baseline from its first item, so a leading picture would hand the row its bottom edge and drop the text below the term.

```tsx
<DescriptionListItem>
  <DescriptionTerm><User /> Owner</DescriptionTerm>
  <DescriptionDetails>
    <AvatarRoot size="xs">
      <AvatarImage src={owner.photo} alt="" />
      <AvatarFallback>AT</AvatarFallback>
    </AvatarRoot>
    Ana Torres
  </DescriptionDetails>
</DescriptionListItem>
<DescriptionListItem>
  <DescriptionTerm><MapPin /> Location</DescriptionTerm>
  <DescriptionDetails>
    <Flag code="ES" shape="circle" size="sm" />
    Barcelona
  </DescriptionDetails>
</DescriptionListItem>
<DescriptionListItem>
  <DescriptionTerm><Buildings /> Company</DescriptionTerm>
  <DescriptionDetails>
    <PlaceholderLogo brand={brand} variant="mark" className="size-4" />
    Vela
  </DescriptionDetails>
</DescriptionListItem>
<DescriptionListItem>
  <DescriptionTerm><Tag /> Plan</DescriptionTerm>
  <DescriptionDetails>
    <Badge variant="purple" size="sm" dot>Enterprise</Badge>
  </DescriptionDetails>
</DescriptionListItem>
<DescriptionListItem>
  <DescriptionTerm><Receipt /> Invoice</DescriptionTerm>
  <DescriptionDetails>
    <Select value={invoice} onValueChange={setInvoice}>
      <SelectTrigger size="sm" aria-label="Invoice status" className="w-40">
        <SelectValue />
      </SelectTrigger>
      <SelectContent>…</SelectContent>
    </Select>
  </DescriptionDetails>
</DescriptionListItem>
```

## Auto layout

`layout="auto"` splits by the list's own width instead of the viewport's. The term asks for `--dl-term` (12rem) and the value for `--dl-value` (10rem); when both fit on one line they sit side by side, and when they don't, the value wraps under its term. So a narrow card on a wide screen stacks, a phone drawer with a short term keeps its rows, and the switch point moves with the term column you set. The same list is shown below in a 20rem and a 28rem column.

```tsx
<DescriptionList layout="auto" divided>
  <DescriptionListItem>
    <DescriptionTerm><EnvelopeSimple /> Email</DescriptionTerm>
    <DescriptionDetails>jordi@koalaui.com</DescriptionDetails>
  </DescriptionListItem>
  <DescriptionListItem>
    <DescriptionTerm><MapPin /> Location</DescriptionTerm>
    <DescriptionDetails>Barcelona, Spain</DescriptionDetails>
  </DescriptionListItem>
</DescriptionList>

{/* A shorter term column keeps rows in a narrower space */}
<DescriptionList layout="auto" style={{ "--dl-term": "7rem" }}>…</DescriptionList>
```

## Inline

`layout="inline"` flows the pairs along a line, each term straight before its value, and wraps when the line runs out: a strip of facts under a heading or inside a row. The pairs carry no row padding and no rule; the gaps between them do the separating.

```tsx
<DescriptionList layout="inline">
  <DescriptionListItem>
    <DescriptionTerm>Fine</DescriptionTerm>
    <DescriptionDetails className="font-semibold">$150</DescriptionDetails>
  </DescriptionListItem>
  <DescriptionListItem>
    <DescriptionTerm>Points</DescriptionTerm>
    <DescriptionDetails className="font-semibold">2</DescriptionDetails>
  </DescriptionListItem>
  <DescriptionListItem>
    <DescriptionTerm>Suspension</DescriptionTerm>
    <DescriptionDetails className="font-semibold">30 days</DescriptionDetails>
  </DescriptionListItem>
  <DescriptionListItem>
    <DescriptionTerm className="sr-only">Class</DescriptionTerm>
    <DescriptionDetails>
      <Badge variant="warning" dot>Misdemeanor</Badge>
    </DescriptionDetails>
  </DescriptionListItem>
</DescriptionList>
```

## Divided

Set `divided` for a hairline rule between rows. Turns a loose list into a scannable, table-like read.

```tsx
<DescriptionList divided>
  <DescriptionListItem>
    <DescriptionTerm>Invoice</DescriptionTerm>
    <DescriptionDetails>INV-2026-0042</DescriptionDetails>
  </DescriptionListItem>
  <DescriptionListItem>
    <DescriptionTerm>Status</DescriptionTerm>
    <DescriptionDetails>
      <Badge variant="success" size="sm" pill>Paid</Badge>
    </DescriptionDetails>
  </DescriptionListItem>
</DescriptionList>
```

## Density

Density tunes the per-row vertical padding. `compact` (the default) suits dashboards; `comfortable` gives a roomier marketing read. It also honors a surrounding `DensityProvider`.

```tsx
<DescriptionList density="compact" divided>…</DescriptionList>
<DescriptionList density="comfortable" divided>…</DescriptionList>
```

## Custom term width

In `row` layout the term column width is the CSS variable `--dl-term` (default `12rem`). Override it per instance via an inline style or class, no recipe surgery needed.

```tsx
<DescriptionList style={{ "--dl-term": "8rem" }}>
  <DescriptionListItem>
    <DescriptionTerm>SKU</DescriptionTerm>
    <DescriptionDetails>KOALA-DS-001</DescriptionDetails>
  </DescriptionListItem>
</DescriptionList>
```

## API reference

### DescriptionList

The root `<dl>`. Forwards all native `<dl>` props.

- `layout`: `"row"` (default, splits at the `sm` viewport) | `"stack"` | `"auto"` (splits by the list's own width) | `"inline"` (pairs flow along a line).
- `divided`: `boolean`; hairline rule between rows.
- `density`: `"compact"` (default) | `"comfortable"`; honors `DensityProvider`.
- `asChild`: `boolean`; render via Radix Slot.
- `--dl-term` (CSS var): term column width in `row` and `auto` layouts (default `12rem`).
- `--dl-value` (CSS var): in `auto` layout, the least room a value needs beside its term before it wraps under it (default `10rem`).

### DescriptionListItem

Groups one term/value pair (a `<div>` inside the list). Accepts `asChild` and all native div props.

### DescriptionTerm

The label (`<dt>`). Renders a leading Phosphor icon when given one. Forwards native `<dt>` props.

### DescriptionDetails

The value (`<dd>`). Holds plain text or composed parts (Badge, Avatar, links). Forwards native `<dd>` props.

## FAQ

### When should I reach for DescriptionList instead of a Table?

Use DescriptionList for the fields of a single record, like a profile, invoice, or settings read-out, where each row is one term/value pair. Reach for a Table when you are comparing the same fields across many records (rows of data), since a `<dl>` models one entity, not a grid.

### What is the difference between layout="row" and layout="stack"?

`row` (the default) puts the term in a fixed-width column with the value beside it, splitting at the `sm` breakpoint and stacking on mobile. `stack` keeps the term above the value at every width, which reads better on narrow surfaces and for long values like URLs or tokens.

### Why does my value with an avatar sit lower than its term?

Because the value was made a flex row (`flex items-center gap-2`). A flex box takes its baseline from its first item, and a picture's baseline is its bottom edge, so the row lined the term up with the bottom of the avatar. Drop the flex classes: DescriptionDetails keeps its content in inline flow, centres a leading Avatar, Flag, svg, img, Badge or Select trigger on the text line, and spaces a picture 8px from the text after it. Use `text-right` rather than `flex justify-end` to right-align a value.

### How do I make rows follow the card instead of the screen?

Use `layout="auto"`. It puts the term and value side by side when the list itself has room for both (`--dl-term` plus `--dl-value`, 12rem and 10rem by default) and wraps the value under its term when it doesn't, so a narrow card on a wide screen stacks and a phone drawer with a short term column keeps its rows. `row` keeps its viewport `sm` split.

### How do I show a few facts on one line?

Use `layout="inline"`: the pairs flow along a line, each term straight before its value, and wrap when the line runs out. There is no row padding and no rule, so it sits under a heading or inside a list row without overrides.

### How do I assemble a row from the named parts?

Wrap each pair in DescriptionListItem, then place a DescriptionTerm (the `<dt>` label) and a DescriptionDetails (the `<dd>` value) inside it. Import the parts as named exports rather than dot-notation, since `DescriptionList.Item` style statics do not survive the RSC server to client boundary.

### Can a value cell hold more than plain text?

Yes. DescriptionDetails accepts composed Koala parts, so you can drop a Badge, Avatar, or link straight into the value. DescriptionTerm also renders a leading Phosphor icon when you pass one, sized to the label's cap height.

### How do I widen the term column?

In `row` layout the term column width is the CSS variable `--dl-term` (default `12rem`). Override it per instance with an inline style like `style={{ "--dl-term": "8rem" }}` or a class, with no changes to the recipe needed.

### Does it pick up density automatically?

The `density` prop tunes the per-row vertical padding, defaulting to `compact` for dashboards with `comfortable` as the roomier option. If you omit the prop it honors a surrounding DensityProvider, so wrapping a region resolves density for every list inside it.

---

<!-- https://www.koalaui.com/docs/components/heatmap.md -->

# Heatmap

A grid of cells tinted by value, for activity by hour, a year of days or a retention cohort. Scale it per grid, row or column; every cell reads out on hover, on focus and to screen readers.

```tsx
<Heatmap
  data={traffic}
  rows={["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"]}
  columns={hours}
  label="Visits by weekday and hour"
  valueFormatter={(value) => `${value} visits`}
>
  <HeatmapGrid>
    <HeatmapRowLabels />
    <HeatmapColumnLabels interval={3} />
  </HeatmapGrid>
  <HeatmapLegend />
</Heatmap>
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add heatmap
```

Manual: run `npm install tailwind-variants tailwind-merge tippy.js`, then copy the source into `components/ui/heatmap/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

`Heatmap` is composed from named parts, like [Chart](https://www.koalaui.com/docs/components/chart.md). The root takes the `data` (one array per row), the `rows` and `columns` labels and the colour scale. `HeatmapGrid` draws the cells; `HeatmapRowLabels` and `HeatmapColumnLabels` go inside it so they line up with the cells, and `HeatmapLegend` is the Less / More key.

```tsx title="traffic-heatmap.tsx"
import {
  Heatmap,
  HeatmapGrid,
  HeatmapRowLabels,
  HeatmapColumnLabels,
  HeatmapLegend,
} from "@/components/ui/heatmap"

const days = ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"]
const hours = Array.from({ length: 24 }, (_, h) => `${h % 12 || 12}${h < 12 ? "am" : "pm"}`)

// traffic: 7 rows (days) of 24 numbers (hours)
export function TrafficHeatmap({ traffic }: { traffic: number[][] }) {
  return (
    <Heatmap data={traffic} rows={days} columns={hours} label="Visits by weekday and hour">
      <HeatmapGrid>
        <HeatmapRowLabels />
        <HeatmapColumnLabels interval={3} />
      </HeatmapGrid>
      <HeatmapLegend />
    </Heatmap>
  )
}
```

## Activity card

The dashboard widget: one row per event, one column per day, in a [Card](https://www.koalaui.com/docs/components/card.md). Visits and abandonments are a thousand times apart, so each row is shaded against itself (`normalize="row"`), and the tooltip adds the date the column header leaves out through `renderTooltip`. Switch the week: the cells tween to their new shades instead of redrawing.

```tsx
const [week, setWeek] = React.useState<WeekKey>("current")
const data = ACTIVITY[week]

<Card className="w-full max-w-md">
  <CardHeader>
    <CardTitle>User activity</CardTitle>
    <CardDescription className="tabular-nums">{total.toLocaleString("en-US")} events</CardDescription>
    <CardAction>
      <Select value={week} onValueChange={(value) => setWeek(value as WeekKey)}>
        <SelectTrigger size="sm" aria-label="Activity week" className="w-32">
          <SelectValue />
        </SelectTrigger>
        <SelectContent>
          <SelectItem value="current">This week</SelectItem>
          <SelectItem value="previous">Last week</SelectItem>
        </SelectContent>
      </Select>
    </CardAction>
  </CardHeader>
  <CardContent>
    <Heatmap
      data={data.rows.map((row) => row.counts)}
      rows={data.rows.map((row) => row.event)}
      columns={["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"]}
      normalize="row"
      color="brand"
      label={`Events per day, ${data.dates[0]} to ${data.dates[6]}`}
    >
      <HeatmapGrid
        renderTooltip={(cell) => (
          <TooltipHeader>
            <TooltipHeaderText>
              <TooltipTitle>{cell.rowLabel}</TooltipTitle>
              <TooltipDescription>
                {cell.columnLabel}, {data.dates[cell.column]}
              </TooltipDescription>
            </TooltipHeaderText>
            <TooltipValue>{cell.formattedValue}</TooltipValue>
          </TooltipHeader>
        )}
      >
        <HeatmapRowLabels />
        <HeatmapColumnLabels />
      </HeatmapGrid>
      <HeatmapLegend />
    </Heatmap>
  </CardContent>
</Card>
```

## Normalization

`normalize` decides what a cell’s shade is measured against. `grid` (the default) puts every cell on one scale, the honest reading when the rows share a unit and a magnitude. `row` shades each row from its own quietest cell to its busiest, for rows that differ by orders of magnitude; `column` does the same down each column. The tooltip and each cell’s accessible name always carry the real number, whatever the shade.

```tsx
<Heatmap data={counts} rows={events} columns={days} normalize="grid" aspect="wide">…</Heatmap>
<Heatmap data={counts} rows={events} columns={days} normalize="row" aspect="wide">…</Heatmap>
<Heatmap data={counts} rows={events} columns={days} normalize="column" aspect="wide">…</Heatmap>

// each one:
<Heatmap data={counts} rows={events} columns={days} normalize="row" aspect="wide" label="Events per day, normalised by row">
  <HeatmapGrid>
    <HeatmapRowLabels />
    <HeatmapColumnLabels />
  </HeatmapGrid>
</Heatmap>
```

## Calendar strip

A year of days, one column per week. `size="sm"` tightens the gaps and lowers the cell minimum, so 53 weeks fit a card; on a phone the strip scrolls sideways inside its own box while the day labels stay pinned. `null` marks the days before the range starts (a blank, not a zero). `tickFormatter` prints each month once and every other weekday, and `cellLabel` names each cell by its real date. The legend is a part like any other, so it can share a row with a summary.

```tsx
// deploys: 7 rows (Mon to Sun) of 53 weeks; null before the range starts.
// dayAt(row, column) turns a cell back into its date.
<Heatmap
  data={deploys}
  rows={["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"]}
  columns={weekLabels}
  size="sm"
  color="teal"
  label="Deploys per day, last 12 months"
  valueFormatter={(value) => `${value} ${value === 1 ? "deploy" : "deploys"}`}
>
  <HeatmapGrid
    cellLabel={(cell) => `${cell.formattedValue} on ${longDate.format(dayAt(cell.row, cell.column))}`}
    renderTooltip={(cell) => (
      <TooltipHeader>
        <TooltipHeaderText>
          <TooltipTitle>{cell.formattedValue}</TooltipTitle>
          <TooltipDescription>{longDate.format(dayAt(cell.row, cell.column))}</TooltipDescription>
        </TooltipHeaderText>
      </TooltipHeader>
    )}
  >
    <HeatmapRowLabels tickFormatter={(label, index) => (index % 2 === 0 && index < 6 ? label : null)} />
    <HeatmapColumnLabels tickFormatter={monthTick} />
  </HeatmapGrid>
  <div className="flex flex-wrap items-center justify-between gap-x-4 gap-y-2">
    <p className="text-sm text-muted-foreground tabular-nums">{total.toLocaleString("en-US")} deploys in the last year</p>
    <HeatmapLegend />
  </div>
</Heatmap>

/** A month's name over the first week that opens in it (not in the last two, where it would not fit). */
function monthTick(_label: string, week: number) {
  if (week > WEEKS - 3) return null
  const month = dayAt(0, week).getUTCMonth()
  return week === 0 || month !== dayAt(0, week - 1).getUTCMonth() ? monthName.format(dayAt(0, week)) : null
}
```

## Retention cohort

The share of each signup cohort still active week by week. Newer cohorts have lived fewer weeks, so the weeks still to come are `null` and the grid reads as a triangle. `domain={[0, 100]}` pins the scale to the whole percentage range instead of the data’s own, so a cell’s shade means the same thing in every report, and `steps={6}` gives the scale more shades to tell the weeks apart.

```tsx
// retention: one row per cohort, one column per week; the weeks still to come are null.
<Heatmap
  data={retention}
  rows={["Jul 27", "Aug 3", "Aug 10", "Aug 17", "Aug 24", "Aug 31", "Sep 7", "Sep 14"]}
  columns={["Week 0", "Week 1", "Week 2", "Week 3", "Week 4", "Week 5", "Week 6", "Week 7"]}
  domain={[0, 100]}
  steps={6}
  color="purple"
  label="Weekly retention by signup cohort"
  valueFormatter={(value) => `${value}%`}
  className="w-full max-w-xl"
>
  <HeatmapGrid
    cellLabel={(cell) => `${cell.rowLabel} cohort, ${cell.columnLabel}: ${cell.formattedValue} retained`}
    renderTooltip={(cell) => (
      <TooltipHeader>
        <TooltipHeaderText>
          <TooltipTitle>{cell.rowLabel} cohort</TooltipTitle>
          <TooltipDescription>{cell.columnLabel}</TooltipDescription>
        </TooltipHeaderText>
        <TooltipValue>{cell.formattedValue}</TooltipValue>
      </TooltipHeader>
    )}
  >
    <HeatmapRowLabels />
    <HeatmapColumnLabels tickFormatter={(label) => label.replace("Week ", "W")} />
  </HeatmapGrid>
  <HeatmapLegend lowLabel="0%" highLabel="100%" />
</Heatmap>
```

## Colors

The scale is one hue mixed into the muted track: an empty cell is the track itself and each step adds more of the hue until the last is the hue at full strength. The hues are the Chart’s: `blue` (the default, the house chart hue), `brand` for a heatmap that is the story of the screen, `primary`, the accents, the status roles, and `current` to build the scale from the ambient text colour. Every hue re-themes across light, dark, cream and moonlight.

```tsx
<Heatmap data={visits} rows={days} columns={hours} color="blue" size="sm"><HeatmapGrid /></Heatmap>
<Heatmap data={visits} rows={days} columns={hours} color="brand" size="sm"><HeatmapGrid /></Heatmap>
<Heatmap data={visits} rows={days} columns={hours} color="primary" size="sm"><HeatmapGrid /></Heatmap>
<Heatmap data={visits} rows={days} columns={hours} color="purple" size="sm"><HeatmapGrid /></Heatmap>
<Heatmap data={visits} rows={days} columns={hours} color="pink" size="sm"><HeatmapGrid /></Heatmap>
<Heatmap data={visits} rows={days} columns={hours} color="teal" size="sm"><HeatmapGrid /></Heatmap>
<Heatmap data={visits} rows={days} columns={hours} color="orange" size="sm"><HeatmapGrid /></Heatmap>
<Heatmap data={visits} rows={days} columns={hours} color="success" size="sm"><HeatmapGrid /></Heatmap>
<Heatmap data={visits} rows={days} columns={hours} color="warning" size="sm"><HeatmapGrid /></Heatmap>
<Heatmap data={visits} rows={days} columns={hours} color="info" size="sm"><HeatmapGrid /></Heatmap>
<Heatmap data={visits} rows={days} columns={hours} color="destructive" size="sm"><HeatmapGrid /></Heatmap>

// current: the scale takes the ambient text colour
<div className="text-foreground">
  <Heatmap data={visits} rows={days} columns={hours} color="current" size="sm"><HeatmapGrid /></Heatmap>
</div>
```

## Steps

`steps` sets how many shades sit above the empty track (four by default, up to ten). Fewer steps read faster and hide small differences; more steps show them. The legend always paints the scale the grid uses.

```tsx
<Heatmap data={visits} rows={days} columns={hours} steps={3} size="sm">
  <HeatmapGrid />
  <HeatmapLegend />
</Heatmap>

<Heatmap data={visits} rows={days} columns={hours} size="sm">{/* 4, the default */}…</Heatmap>
<Heatmap data={visits} rows={days} columns={hours} steps={7} size="sm">…</Heatmap>
```

## Size

Cells always share the width of the box, down to a minimum. `md` (the default) keeps them at least 24px with 4px gaps, room for a three-letter label over every column in a dashboard card; `sm` goes down to 10px with 2px gaps, for a dense strip. Below the minimum the grid scrolls sideways inside its own box, never the page.

```tsx
<Heatmap data={traffic} rows={days} columns={hours} size="md">
  <HeatmapGrid>
    <HeatmapRowLabels />
    <HeatmapColumnLabels interval={3} />
  </HeatmapGrid>
</Heatmap>

<Heatmap data={traffic} rows={days} columns={hours} size="sm">
  <HeatmapGrid>
    <HeatmapRowLabels />
    <HeatmapColumnLabels interval={3} />
  </HeatmapGrid>
</Heatmap>
```

## Aspect

Cells are square by default, so a many-column grid keeps its proportions. `aspect="wide"` holds one row height (28px at `md`, 12px at `sm`) and lets the cells stretch across their column, for a few columns in a lot of width, where squares would make a tower.

```tsx
<Heatmap data={counts} rows={events} columns={days} normalize="row" color="brand" className="max-w-sm">
  <HeatmapGrid>
    <HeatmapRowLabels />
    <HeatmapColumnLabels />
  </HeatmapGrid>
</Heatmap>

<Heatmap data={counts} rows={events} columns={days} normalize="row" color="brand" aspect="wide">
  <HeatmapGrid>
    <HeatmapRowLabels />
    <HeatmapColumnLabels />
  </HeatmapGrid>
</Heatmap>
```

## Only the parts you need

Every part is optional. Leave out the legend for a tight card, or the labels too for a bare strip beside a figure: the grid takes back the room they would have used, with no gutter left behind. The tooltip is a render prop on `HeatmapGrid`; return `null` to go without one.

```tsx
// Legend dropped
<Heatmap data={counts} rows={events} columns={days} normalize="row" aspect="wide">
  <HeatmapGrid>
    <HeatmapRowLabels />
    <HeatmapColumnLabels />
  </HeatmapGrid>
</Heatmap>

// Labels and legend dropped: a bare strip
<Heatmap data={weekdayTraffic} rows={days} columns={hours} size="sm">
  <HeatmapGrid />
</Heatmap>

// Tooltips dropped: renderTooltip returns null
<Heatmap data={counts} rows={events} columns={days} normalize="row" aspect="wide">
  <HeatmapGrid renderTooltip={() => null}>
    <HeatmapRowLabels />
  </HeatmapGrid>
  <HeatmapLegend />
</Heatmap>
```

## Load animation

Like the Chart, a heatmap plays a one-shot reveal when it mounts: the cells fade and grow in a diagonal wave from the top-left corner. It never replays on hover or when the data changes (a changed cell tweens its shade instead), and it holds still under `prefers-reduced-motion`. Pass `animate={false}` to opt out. Press Replay to watch it again.

```tsx
// On by default. Bump a key to replay it; pass animate={false} to opt out.
<Heatmap key={run} data={traffic} rows={days} columns={hours} label="Visits by weekday and hour">
  <HeatmapGrid>
    <HeatmapRowLabels />
    <HeatmapColumnLabels interval={3} />
  </HeatmapGrid>
</Heatmap>
```

## Empty state

With no rows or no columns, `HeatmapGrid` shows a muted message in place of the cells and the labels and legend step aside. Pass `empty` on the root to say something more useful. A grid of zeros is not empty: it paints the muted track, which is the truth.

```tsx
<Heatmap data={[]} label="Visits by weekday and hour">
  <HeatmapGrid>
    <HeatmapRowLabels />
    <HeatmapColumnLabels />
  </HeatmapGrid>
  <HeatmapLegend />
</Heatmap>

<Heatmap data={[]} label="Deploys per day" empty="No deploys in this period yet">
  …
</Heatmap>
```

## Accessibility

The cells are an ARIA grid named by `label`. It is one tab stop: the arrow keys move between cells (skipping blanks), Home and End jump to the ends of a row, and Ctrl+Home and Ctrl+End to the first and last cell. Focus opens the same tooltip as hover. Every cell carries its full reading as its name (“Sign-ups, Mon: 131”), so the row and column labels are decorative duplicates hidden from assistive tech, and the legend is too. Write a `cellLabel` when the labels alone do not say what a cell is, like a calendar day.

```tsx title="accessible-heatmap.tsx"
<Heatmap
  data={deploys}
  rows={days}
  columns={weeks}
  // The grid's accessible name.
  label="Deploys per day, last 12 months"
  valueFormatter={(value) => `${value} deploys`}
>
  {/* Each cell's name. The default is "row, column: value". */}
  <HeatmapGrid cellLabel={(cell) => `${cell.formattedValue} on ${dateOf(cell)}`}>
    <HeatmapRowLabels />
    <HeatmapColumnLabels />
  </HeatmapGrid>
</Heatmap>
```

## API reference

`Heatmap` takes `data` (an array of rows, each an array of `number | null`), `rows` and `columns` (the labels), `normalize` (`grid | row | column`), `domain` (a fixed `[low, high]`), `steps` (default 4), `color` (default `blue`), `size` (`sm | md`), `aspect` (`square | wide`), `valueFormatter`, `label` (the grid’s accessible name), `animate` (the load reveal, on by default) and `empty`, and forwards `div` props. `HeatmapGrid` takes `renderTooltip` and `cellLabel`, both called with the cell (`row`, `column`, `rowLabel`, `columnLabel`, `value`, `formattedValue`, `level`). `HeatmapRowLabels` and `HeatmapColumnLabels` take `tickFormatter` and `interval`, like the Chart’s axes; `HeatmapLegend` takes `lowLabel` and `highLabel`. Every part accepts `className`, merged last, and carries a `data-slot`; cells also carry `data-row`, `data-column` and `data-level`.

## FAQ

### What shape does data take?

One array per row, one entry per column: data={[[4, 0, 12], [7, 3, 9]]}. Pass rows and columns with the labels in the same order. Ragged rows are padded with blanks, and anything that is not a finite number becomes a blank cell.

### What is the difference between 0 and null?

Zero is a real reading of nothing: the cell paints the muted track and still has a tooltip and a name. null is no reading at all: the cell stays blank, takes no focus and has no tooltip, which is how the days before a calendar starts or the future weeks of a retention cohort should look.

### When should I normalise per row?

When the rows measure different things at very different magnitudes, like visits and refunds. On one shared scale the small rows would all sit on the lightest step. With normalize="row" each row is shaded from its own quietest cell to its busiest, so its shape reads; the numbers in the tooltip stay exact. Say so in the label, since shades are then not comparable across rows.

### How do I pin the scale to a known range?

Pass domain={[low, high]}, for example [0, 100] for percentages. Every cell is then measured against that range, so a shade means the same in every report and normalize no longer applies.

### Why does the colour look lighter than the hue?

The scale mixes the hue into the muted track: the first step is mostly track and the last step is the hue itself. That keeps an empty cell and the lightest step apart in every theme, including the dark ones, where a translucent tint over the card would sink into it.

### How do I change what the tooltip shows?

Pass renderTooltip to HeatmapGrid. It receives the cell (labels, value, formatted value, level) and returns the tooltip body, composed from the Tooltip graph parts. Return null for a cell to give it no tooltip.

### How do I show only some labels?

HeatmapRowLabels and HeatmapColumnLabels take interval (every Nth label) and tickFormatter (return a label, or null to leave that slot empty), the same props as the Chart's axes. Labels never widen a column, so every column stays the same width. A label followed by an empty slot is a tick: it marks its column from the start edge and spills over the empty slots, the way month names sit over a year of weeks. Labelled neighbours sit centred, so keep those short (Mon, 9am) or thin them out.

### What happens on a phone?

Cells never shrink below the size minimum (24px at md, 10px at sm). When the columns cannot fit, the grid scrolls sideways inside its own box and the row labels stay pinned to the start edge, so the page itself never overflows.

### Is it accessible to keyboard and screen reader users?

Yes. The cells form an ARIA grid with one tab stop and arrow key navigation, and focus opens the tooltip. Every cell's accessible name is its full reading, so a screen reader announces "Sign-ups, Mon: 131" rather than a colour. Name the grid with label.

### Can I turn off the load animation?

Pass animate={false} on Heatmap. The reveal plays once on mount, never on hover or data changes, and it is held still under prefers-reduced-motion.

---

<!-- https://www.koalaui.com/docs/components/order-summary.md -->

# Order Summary

The checkout and cart order read-out. One composable card that stacks line items, a promo-code band and a totals breakdown, with every price on tabular-nums so the column never jitters.

```tsx
<OrderSummary density="comfortable" className="max-w-sm">
  <OrderSummaryHeader>
    <OrderSummaryTitle asChild><h3>Order summary</h3></OrderSummaryTitle>
    <Badge variant="secondary" pill>4 items</Badge>
  </OrderSummaryHeader>

  <OrderSummaryItems>
    <OrderSummaryItem>
      <OrderSummaryItemThumbnail count={2}>
        <img src="/sneakers.jpg" alt="Retro Sneakers" />
      </OrderSummaryItemThumbnail>
      <OrderSummaryItemContent>
        <OrderSummaryItemName>Retro Sneakers</OrderSummaryItemName>
        <OrderSummaryItemOptions>Size 10 · Red</OrderSummaryItemOptions>
      </OrderSummaryItemContent>
      <OrderSummaryItemPrice>$64.00</OrderSummaryItemPrice>
    </OrderSummaryItem>
    {/* …more items */}
  </OrderSummaryItems>

  <OrderSummaryPromo>
    <InputGroup>
      <InputRoot><InputField placeholder="Promo code" defaultValue="WELCOME10" /></InputRoot>
      <Button variant="secondary">Apply</Button>
    </InputGroup>
  </OrderSummaryPromo>

  <OrderSummaryTotals>
    <OrderSummaryRow label="Subtotal">$291.00</OrderSummaryRow>
    <OrderSummaryRow label="Shipping" tone="muted">Free</OrderSummaryRow>
    <OrderSummaryRow label="Estimated tax">$23.28</OrderSummaryRow>
    <OrderSummaryRow label="Discount (WELCOME10)" tone="discount">-$29.10</OrderSummaryRow>
    <OrderSummaryTotal label="Total">$285.18</OrderSummaryTotal>
  </OrderSummaryTotals>

  <OrderSummaryFooter>
    <Button className="w-full">Checkout</Button>
    <p className="text-center text-xs text-muted-foreground">
      Taxes and shipping calculated at checkout.
    </p>
  </OrderSummaryFooter>
</OrderSummary>
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add order-summary
```

Manual: run `npm install radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/order-summary/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

```tsx title="usage.tsx"
import {
  OrderSummary,
  OrderSummaryHeader,
  OrderSummaryTitle,
  OrderSummaryItems,
  OrderSummaryItem,
  OrderSummaryItemThumbnail,
  OrderSummaryItemContent,
  OrderSummaryItemName,
  OrderSummaryItemOptions,
  OrderSummaryItemPrice,
  OrderSummaryPromo,
  OrderSummaryTotals,
  OrderSummaryRow,
  OrderSummaryTotal,
  OrderSummaryFooter,
} from "@/components/ui/order-summary"

export function Example() {
  return (
    <OrderSummary>
      <OrderSummaryItems>
        <OrderSummaryItem>
          <OrderSummaryItemThumbnail count={2}>
            <img src="/sneakers.jpg" alt="Retro Sneakers" />
          </OrderSummaryItemThumbnail>
          <OrderSummaryItemContent>
            <OrderSummaryItemName>Retro Sneakers</OrderSummaryItemName>
            <OrderSummaryItemOptions>Size 10 · Red</OrderSummaryItemOptions>
          </OrderSummaryItemContent>
          <OrderSummaryItemPrice>$64.00</OrderSummaryItemPrice>
        </OrderSummaryItem>
      </OrderSummaryItems>

      <OrderSummaryTotals>
        <OrderSummaryRow label="Subtotal">$64.00</OrderSummaryRow>
        <OrderSummaryTotal label="Total">$64.00</OrderSummaryTotal>
      </OrderSummaryTotals>
    </OrderSummary>
  )
}
```

## Anatomy

`OrderSummary` is a multi-part component: one `tv` recipe whose slots flow to every named part through React Context. Compose only the bands you need, in any order. There are no internal dividers or boxing: the bands and the line items are simply set apart by whitespace (the house minimal style), so the summary reads clean on any surface. The `card` variant adds an outer border and insets the content with padding; `plain` sits flush.

```tsx title="anatomy.tsx"
<OrderSummary>            {/* the card shell */}
  <OrderSummaryHeader>     {/* title + item-count Badge */}
    <OrderSummaryTitle />
  </OrderSummaryHeader>

  <OrderSummaryItems>      {/* the <ul> of line items */}
    <OrderSummaryItem>     {/* one <li> row */}
      <OrderSummaryItemThumbnail count={2} />
      <OrderSummaryItemContent>
        <OrderSummaryItemName />
        <OrderSummaryItemOptions />
      </OrderSummaryItemContent>
      <OrderSummaryItemPrice />
    </OrderSummaryItem>
  </OrderSummaryItems>

  <OrderSummaryPromo />     {/* slot for an InputGroup */}

  <OrderSummaryTotals>      {/* the <dl> breakdown */}
    <OrderSummaryRow label="Subtotal">…</OrderSummaryRow>
    <OrderSummaryTotal label="Total">…</OrderSummaryTotal>
  </OrderSummaryTotals>

  <OrderSummaryFooter />    {/* slot for the checkout CTA */}
</OrderSummary>
```

## Line items

Each `OrderSummaryItem` is a `<li>` laying out a thumbnail, the name + options, and the line price. The thumbnail holds an `<img>` (auto `object-cover` with the DS image-outline) or a Phosphor glyph, and its `count` prop drops a quantity pill on the corner. The name truncates rather than shoving the price off the row, and the price is `tabular-nums` so the column stays aligned.

```tsx
<OrderSummaryItems>
  <OrderSummaryItem>
    <OrderSummaryItemThumbnail count={2}>
      <img src="/sneakers.jpg" alt="Retro Sneakers" />
    </OrderSummaryItemThumbnail>
    <OrderSummaryItemContent>
      <OrderSummaryItemName>Retro Sneakers</OrderSummaryItemName>
      <OrderSummaryItemOptions>Size 10 · Red</OrderSummaryItemOptions>
    </OrderSummaryItemContent>
    <OrderSummaryItemPrice>$64.00</OrderSummaryItemPrice>
  </OrderSummaryItem>
  {/* …Canvas High-Tops, Aluminum Watch */}
</OrderSummaryItems>
```

## Shopping cart

Compose `OrderSummaryItemActions` after the price to turn the read-out into a shopping cart. It holds `OrderSummaryItemQuantity` (the canonical [NumberInput](https://www.koalaui.com/docs/components/input.md) in its compact inline − value + form) and `OrderSummaryItemRemove` (the canonical [Button](https://www.koalaui.com/docs/components/button.md) in its quiet destructiveGhost trash form). Wire their `onValueChange` / `onClick` to your cart state; here the line prices and the subtotal recompute live. Removing a row sets `leaving` on its `OrderSummaryItem` so it **collapses and drifts out** before it's dropped from state (the rows below glide up, no jump); clearing the cart shows the empty state.

```tsx
const money = (n) => "$" + n.toFixed(2)

function ShoppingCart() {
  const [items, setItems] = React.useState(INITIAL) // [{ id, name, options, unit, qty, src }]
  const [leaving, setLeaving] = React.useState(new Set())
  const setQty = (id, qty) => setItems((p) => p.map((i) => (i.id === id ? { ...i, qty } : i)))
  const remove = (id) => setLeaving((s) => new Set(s).add(id)) // play the exit
  const finalize = (id) => {
    setItems((p) => p.filter((i) => i.id !== id))
    setLeaving((s) => { const n = new Set(s); n.delete(id); return n })
  }
  const subtotal = items.filter((i) => !leaving.has(i.id)).reduce((s, i) => s + i.unit * i.qty, 0)

  return (
    <OrderSummary className="max-w-lg">
      <OrderSummaryHeader className="flex-col items-start gap-1">
        <OrderSummaryTitle asChild><h3>Summary</h3></OrderSummaryTitle>
        <p className="text-sm text-muted-foreground">Review your items before checkout.</p>
      </OrderSummaryHeader>

      <OrderSummaryItems>
        {items.map((item) => (
          <OrderSummaryItem
            key={item.id}
            leaving={leaving.has(item.id)}
            onAnimationEnd={(e) => e.target === e.currentTarget && finalize(item.id)}
          >
            <OrderSummaryItemThumbnail>
              <img src={item.src} alt={item.name} />
            </OrderSummaryItemThumbnail>
            <OrderSummaryItemContent>
              <OrderSummaryItemName>{item.name}</OrderSummaryItemName>
              <OrderSummaryItemOptions>{item.options}</OrderSummaryItemOptions>
            </OrderSummaryItemContent>
            <OrderSummaryItemPrice>{money(item.unit * item.qty)}</OrderSummaryItemPrice>
            <OrderSummaryItemActions>
              <OrderSummaryItemQuantity
                value={item.qty}
                onValueChange={(v) => v != null && setQty(item.id, v)}
              />
              <OrderSummaryItemRemove onClick={() => remove(item.id)} />
            </OrderSummaryItemActions>
          </OrderSummaryItem>
        ))}
      </OrderSummaryItems>

      <OrderSummaryTotals>
        <OrderSummaryRow label="Subtotal">{money(subtotal)}</OrderSummaryRow>
        <OrderSummaryTotal label="Total">{money(subtotal)}</OrderSummaryTotal>
      </OrderSummaryTotals>
    </OrderSummary>
  )
}
```

## Totals & tones

`OrderSummaryTotals` renders a semantic `<dl>`. Each `OrderSummaryRow` takes a `label` (the `<dt>`) and its value as children (the `<dd>`). The `tone` prop accents the value: `discount` greens a credit, `muted` softens a "Free" or "calculated later" placeholder. `OrderSummaryTotal` is the emphasized grand total, set apart from the rows by extra whitespace.

```tsx
<OrderSummaryTotals>
  <OrderSummaryRow label="Subtotal">$291.00</OrderSummaryRow>
  <OrderSummaryRow label="Shipping" tone="muted">Free</OrderSummaryRow>
  <OrderSummaryRow label="Estimated tax">$23.28</OrderSummaryRow>
  <OrderSummaryRow label="Store credit" tone="discount">-$15.00</OrderSummaryRow>
  <OrderSummaryTotal label="Total due">$299.28</OrderSummaryTotal>
</OrderSummaryTotals>
```

## Promo code

`OrderSummaryPromo` is a band you fill with the canonical [`InputGroup`](https://www.koalaui.com/docs/components/input-group.md) — a field joined to an **Apply** button in one seamless shell. Nothing is re-styled inline; the summary composes the real controls, so the promo row stays in lockstep with the input family.

The band imposes the big control tier on what you put in it (`size="lg"`, 40px), the way [Form](https://www.koalaui.com/docs/components/form.md) does for its fields: a promo code is a real form control, not a table filter, so it matches the **Checkout** button under the totals instead of shrinking to the ambient density. Pass `size` for a different tier; a `size` on the control itself still wins.

```tsx title="promo.tsx"
<OrderSummaryPromo>
  <InputGroup>
    <InputRoot>
      <InputField placeholder="Promo code" />
    </InputRoot>
    <Button variant="secondary">Apply</Button>
  </InputGroup>
</OrderSummaryPromo>
```

## Variants & density

The default `card` variant is the bordered checkout sidebar. `plain` drops the frame so the bands sit flush on whatever surface holds them — a page column or a [Drawer](https://www.koalaui.com/docs/components/drawer.md). Density is Koala's spacing axis: `comfortable` (the default) suits a checkout page; `compact` tightens the padding and shrinks the thumbnails for a mini-cart. Set it per instance or once on a `DensityProvider`.

```tsx
<OrderSummary variant="plain" density="compact" className="max-w-xs">
  <OrderSummaryItems>
    <OrderSummaryItem>{/* …thumbnail + content + price */}</OrderSummaryItem>
    <OrderSummaryItem>{/* … */}</OrderSummaryItem>
  </OrderSummaryItems>
  <OrderSummaryTotals>
    <OrderSummaryRow label="Subtotal">$142.00</OrderSummaryRow>
    <OrderSummaryRow label="Shipping" tone="muted">Free</OrderSummaryRow>
    <OrderSummaryTotal label="Total">$142.00</OrderSummaryTotal>
  </OrderSummaryTotals>
  <OrderSummaryFooter>
    <Button className="w-full"><ShieldCheck weight="bold" /> Secure checkout</Button>
  </OrderSummaryFooter>
</OrderSummary>
```

## API reference

### OrderSummary

The card shell (a `<section>`). Props: `variant` (`"card"` | `"plain"`, default `"card"`), `density` (`"comfortable"` | `"compact"`), `asChild`, plus all `<section>` props. Density resolves prop > nearest `DensityProvider` > `"comfortable"`.

### OrderSummaryHeader / OrderSummaryTitle

The title band (a `justify-between` row) and its title. `OrderSummaryTitle` takes `asChild` to render a real heading (`<h2>`/`<h3>`).

### OrderSummaryItems / OrderSummaryItem

The line-item `<ul>` and each `<li>` row. Rows stack with whitespace (the density-scaled `items` gap), no dividers.

### OrderSummaryItemThumbnail

The product tile. Holds an `<img>` (auto `object-cover` + image outline), a Phosphor glyph, or nothing. Prop `count` renders a quantity pill on the corner.

### OrderSummaryItemContent / Name / Options / Price

The content column (name truncates), the muted options line, and the trailing line price (`tabular-nums`).

### OrderSummaryPromo

A band; fill it with an `InputGroup` (promo field + Apply button). Takes `size` (`sm` · `md` · `lg`, default `lg`), the control height it imposes on its children.

### OrderSummaryTotals / OrderSummaryRow / OrderSummaryTotal

The totals `<dl>`. `OrderSummaryRow` takes `label` (`<dt>`), its value as children (`<dd>`), and `tone` (`"default"` | `"discount"` | `"muted"`). `OrderSummaryTotal` is the emphasized grand total.

### OrderSummaryFooter

A band for the checkout `Button` and a trust note.

## FAQ

### Why are the line items a <ul> and the totals a <dl>?

Because that's what they are semantically. The items are a list of products (OrderSummaryItems renders a <ul> of <li> rows), and the totals are label/value pairs (OrderSummaryTotals renders a <dl> with <dt> labels and <dd> values). Screen readers announce them correctly with no extra ARIA.

### How do I wire the promo code or the Checkout button?

OrderSummary is a presentational read-out; it owns no cart state. Compose the real controls inside the OrderSummaryPromo and OrderSummaryFooter slots — an InputGroup with your onSubmit for the promo, a Button with your onClick (or an <a asChild>) for checkout — and drive the totals from your own cart model.

### Can a thumbnail use a real product photo?

Yes. Drop an <img> inside OrderSummaryItemThumbnail; it's sized to fill (object-cover) and gets the DS image outline automatically. A Phosphor glyph or an empty tile (a muted placeholder) work too, so a cart with missing imagery still looks finished.

### When should I reach for compact or the plain variant?

compact tightens the padding and shrinks the thumbnails for a mini-cart or a Drawer summary; comfortable is the roomier checkout-page default. plain drops the card frame so the bands sit flush on a surface you already own (a page column, a Drawer body). Set density once on a DensityProvider to theme a whole app shell.

### Will the prices stay aligned as the cart updates?

Yes. Every price — the line prices, the totals rows, and the grand total — is tabular-nums, so digits occupy a fixed width and the right-hand column never shifts as quantities or amounts change.

---

<!-- https://www.koalaui.com/docs/components/ranking.md -->

# Ranking

A leaderboard card for the tops of a dashboard: products, customers or countries. Read it as stacked rows or a vertical bar chart, each row carrying a position chip, a value and a relative-share bar.

```tsx
<Ranking>
  <RankingHeader>
    <div className="space-y-1">
      <RankingTitle>Top products</RankingTitle>
      <RankingDescription>By units sold this month</RankingDescription>
    </div>
    <RankingAction>
      <Button variant="outline" size="sm">View all</Button>
    </RankingAction>
  </RankingHeader>

  <RankingList>
    {products.map((p, i) => (
      // Keep the row light; let the detail live in a Tooltip.
      <Tooltip key={p.name} content={<ProductTip p={p} />} variant="graph" placement="right">
        <RankingItem interactive>
          <RankingRank highlight={i === 0}>{i + 1}</RankingRank>
          <RankingMedia><p.icon /></RankingMedia>
          <RankingContent>
            <RankingLabel>{p.name}</RankingLabel>
            <RankingBar value={p.share} />
          </RankingContent>
          <RankingValue>{p.units.toLocaleString("en-US")}</RankingValue>
        </RankingItem>
      </Tooltip>
    ))}
  </RankingList>
</Ranking>
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add ranking
```

Manual: run `npm install @phosphor-icons/react radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/ranking/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

Ranking is composed from named parts, like [Card](https://www.koalaui.com/docs/components/card.md) and [Stat](https://www.koalaui.com/docs/components/stat.md). The `Ranking` root owns the surface and variant; `RankingList` is a semantic `<ol>` so assistive tech announces the positions, and each `RankingItem` lays out a rank, content, and value.

```tsx title="top-categories.tsx"
import {
  Ranking,
  RankingHeader,
  RankingTitle,
  RankingList,
  RankingItem,
  RankingRank,
  RankingContent,
  RankingLabel,
  RankingValue,
} from "@/components/ui/ranking"

export function TopCategories({ rows }: { rows: { name: string; revenue: string }[] }) {
  return (
    <Ranking>
      <RankingHeader>
        <RankingTitle>Top categories</RankingTitle>
      </RankingHeader>
      <RankingList>
        {rows.map((r, i) => (
          <RankingItem key={r.name}>
            <RankingRank highlight={i === 0}>{i + 1}</RankingRank>
            <RankingContent>
              <RankingLabel>{r.name}</RankingLabel>
            </RankingContent>
            <RankingValue>{r.revenue}</RankingValue>
          </RankingItem>
        ))}
      </RankingList>
    </Ranking>
  )
}
```

```tsx
<Ranking>
  <RankingHeader>
    <RankingTitle>Top categories</RankingTitle>
  </RankingHeader>
  <RankingList>
    {rows.map((r, i) => (
      <RankingItem key={r.name}>
        <RankingRank highlight={i === 0}>{i + 1}</RankingRank>
        <RankingContent><RankingLabel>{r.name}</RankingLabel></RankingContent>
        <RankingValue>{r.revenue}</RankingValue>
      </RankingItem>
    ))}
  </RankingList>
</Ranking>
```

## Media and meta

Give a row a face. `RankingMedia` is a tinted icon tile for things (products, countries); for people, drop an [Avatar](https://www.koalaui.com/docs/components/avatar.md) in the same slot. `RankingMeta` adds a muted second line under the label (a category, an order count) and `RankingValue` holds the figure in `tabular-nums` so the column stays aligned.

```tsx
<RankingItem>
  <RankingRank highlight={i === 0}>{i + 1}</RankingRank>
  <Avatar size="sm">
    <AvatarImage src={customer.avatar} alt={customer.name} />
    <AvatarFallback>{initials(customer.name)}</AvatarFallback>
  </Avatar>
  <RankingContent>
    <RankingLabel>{customer.name}</RankingLabel>
    <RankingMeta>{customer.orders} orders</RankingMeta>
  </RankingContent>
  <RankingValue>{customer.spent}</RankingValue>
</RankingItem>
```

## Relative bars

`RankingBar` draws each row’s share of the leader from a `value` of 0–100, so the list reads as a chart at a glance. The fill width is a runtime value, so it rides a CSS variable (never a generated class) and animates when the data changes.

```tsx
<RankingItem>
  <RankingRank highlight={i === 0}>{i + 1}</RankingRank>
  <RankingContent>
    <div className="flex items-baseline justify-between gap-3">
      <RankingLabel>{p.name}</RankingLabel>
      <RankingValue>{p.units.toLocaleString("en-US")}</RankingValue>
    </div>
    {/* value is the share of the leader, 0–100 */}
    <RankingBar value={p.share} />
  </RankingContent>
</RankingItem>
```

## Vertical bars

Set `layout="bars"` to read the same list as a vertical bar chart: `RankingList` turns into a row of full-height columns and each `RankingBar` grows from the bottom to its share. The columns are narrow, so lean on the [Tooltip](https://www.koalaui.com/docs/components/tooltip.md) and wrap each `RankingItem` and surface the full detail on hover instead of squeezing it under the bar.

```tsx
// layout="bars" reads the list as a vertical bar chart.
<Ranking layout="bars">
  <RankingHeader>
    <RankingTitle>Top products</RankingTitle>
    <Badge size="sm" variant="success">+12% MoM</Badge>
  </RankingHeader>
  <RankingList>
    {products.map((p) => (
      // Narrow columns: wrap each bar in a Tooltip for the detail.
      <Tooltip key={p.name} content={<ProductTip p={p} />}>
        <RankingItem>
          <RankingValue className="text-xs">{p.units.toLocaleString("en-US")}</RankingValue>
          <RankingBar value={p.share} />
          <RankingLabel className="w-full text-xs font-normal text-muted-foreground">
            {p.short}
          </RankingLabel>
        </RankingItem>
      </Tooltip>
    ))}
  </RankingList>
</Ranking>
```

## Inline bars

Set `layout="inline"` for a horizontal bar chart: the name holds a fixed column and a thick bar runs beside it. The bars rest neutral and the brand is the hover: the bar under the pointer lights up, and so does a bar that takes keyboard focus as a tooltip trigger. Nothing is lit at rest. `highlight` on a `RankingBar` pins the brand on one bar, for a row that really is selected; it works in the other layouts too.

```tsx
<Ranking layout="inline">
  <RankingList>
    <RankingItem>
      <RankingMedia>🍔</RankingMedia>
      <RankingContent>
        <RankingLabel>Burgers</RankingLabel>
      </RankingContent>
      <RankingBar value={62} />
    </RankingItem>
    <RankingItem>
      <RankingMedia>💧</RankingMedia>
      <RankingContent>
        <RankingLabel>Water</RankingLabel>
      </RankingContent>
      <RankingBar value={56} />
    </RankingItem>
  </RankingList>
</Ranking>
```

## Bar tones

`tone` sets a bar’s fill: `blue`, `brand`, `neutral`, `success`, `warning`, `destructive` or `info`, the same names and inks as the [Chart](https://www.koalaui.com/docs/components/chart.md)’s series, so a Ranking beside a chart can carry its key. Put the leader in the brand and the rest in `neutral` when the list is about one row, or let a status tone report each row’s health. Set `tone` on the `Ranking` to paint every bar at once; a bar’s own tone wins over it, and `highlight` wins over both. In the `inline` layout the hovered bar still lights up in the brand.

```tsx
// The leader in the brand, the rest quiet:
<RankingItem>
  <RankingRank highlight={i === 0}>{i + 1}</RankingRank>
  <RankingContent>
    <div className="flex items-baseline justify-between gap-3">
      <RankingLabel>{p.name}</RankingLabel>
      <RankingValue>{p.units.toLocaleString("en-US")}</RankingValue>
    </div>
    <RankingBar value={p.share} tone={i === 0 ? "brand" : "neutral"} />
  </RankingContent>
</RankingItem>

// A status tone reporting each row's health:
const capacityTone = (used: number) =>
  used >= 90 ? "destructive" : used >= 75 ? "warning" : "success"

<RankingBar value={w.used} tone={capacityTone(w.used)} />

// Or every bar at once, from the root (a bar's own tone still wins):
<Ranking tone="brand">…</Ranking>
```

## Headline figure

When the list breaks down a total, lead with the total. Ranking has no figure part of its own on purpose: the figure is the [Stat](https://www.koalaui.com/docs/components/stat.md)’s `StatValue`, which renders outside a Stat, with a `StatTrend` beside it. Set them between the header and the list, so every card in a dashboard leads with the same figure and the same chip, and the description is free to say what the number counts.

```tsx
import { StatTrend, StatValue } from "@/components/ui/stat"

<Ranking tone="brand">
  <RankingHeader>
    <div className="flex min-w-0 flex-col gap-1.5">
      <RankingTitle>Country visitors</RankingTitle>
      <RankingDescription>Visits this week, by country</RankingDescription>
    </div>
    <RankingAction>
      <Button variant="outline" size="sm">View all</Button>
    </RankingAction>
  </RankingHeader>
  {/* The total the list breaks down: the Stat's figure and trend chip, no Stat around them. */}
  <div className="flex flex-wrap items-center gap-2">
    <StatValue>12,480</StatValue>
    <StatTrend direction="up">+8.2%</StatTrend>
  </div>
  <RankingList>
    {countries.map((c) => (
      <RankingItem key={c.code}>
        <Flag code={c.code} shape="circle" size="sm" className="mt-0.5" />
        <RankingContent>
          <div className="flex items-baseline justify-between gap-3">
            <RankingLabel>{c.name}</RankingLabel>
            <RankingValue>{c.visits.toLocaleString("en-US")}</RankingValue>
          </div>
          <RankingBar value={(c.visits / leader) * 100} />
        </RankingContent>
      </RankingItem>
    ))}
  </RankingList>
</Ranking>
```

## Interactive rows

Pass `interactive` to a `RankingItem` for a clickable row: pointer, a hover wash that bleeds to the card edge, and a focus ring. The wash sits close to the rank chip, media tile, and bar track, so those nested surfaces step down to the card surface on hover to keep their definition instead of dissolving into the wash, while the highlighted leader chip holds its primary fill. Wire it with `onClick` and add a trailing chevron to signal the affordance.

```tsx
<RankingItem interactive onClick={() => openProduct(p.id)}>
  <RankingRank highlight={i === 0}>{i + 1}</RankingRank>
  <RankingMedia><p.icon /></RankingMedia>
  <RankingContent>
    <RankingLabel>{p.name}</RankingLabel>
    <RankingMeta>{p.units.toLocaleString("en-US")} units</RankingMeta>
  </RankingContent>
  <CaretRight className="size-4 shrink-0 text-muted-foreground" />
</RankingItem>
```

## Variants

`default` sits on a hairline border with a soft shadow; `outline` drops the shadow for flat, gridded dashboards; `elevated` trades the border for a lifted shadow.

```tsx
<Ranking variant="default">…</Ranking>
<Ranking variant="outline">…</Ranking>
<Ranking variant="elevated">…</Ranking>
```

## API reference

`Ranking` forwards all `div` props and adds `variant` (`default | outline | elevated`), `layout` (`list | bars | inline`), `tone` (every bar’s default hue) and `asChild`. `RankingList` renders an `<ol>`; `RankingItem` renders an `<li>` and adds `interactive`. `RankingRank` adds `highlight` for the leader; `RankingBar` takes a `value` (0–100), `tone` (`blue | brand | neutral | success | warning | destructive | info`) and `highlight` (a brand fill that wins over the tone). The rest: `RankingHeader`, `RankingTitle`, `RankingDescription`, `RankingAction`, `RankingMedia`, `RankingContent`, `RankingLabel`, `RankingMeta`, `RankingValue`, forward their element props. Every part accepts `className`, merged last.

## FAQ

### Why is RankingList an <ol> and what do I compose inside each row?

RankingList renders a semantic ordered list so assistive tech announces the positions. Each RankingItem (an `<li>`) lays out a RankingRank, optional RankingMedia or an Avatar, a RankingContent (RankingLabel plus RankingMeta), and a RankingValue.

### How do I highlight the leader of the list?

Pass `highlight` to the first RankingRank to give it a filled primary chip. On interactive rows the leader chip keeps its primary fill even through the hover wash.

### What does the value on RankingBar mean?

RankingBar takes a `value` from 0 to 100 representing each row's share of the leader, so the list reads as a chart. The fill width is a runtime value, so it rides a CSS variable and animates when the data changes.

### How do I read the same list as a vertical bar chart?

Set `layout="bars"` on the Ranking root. RankingList becomes a row of full-height columns and each RankingBar grows from the bottom. The columns are narrow, so wrap each RankingItem in a Tooltip for the detail instead of crowding the row.

### How do I recolor the bars?

Pass `tone` to a RankingBar (`blue`, `brand`, `neutral`, `success`, `warning`, `destructive`, `info`, the Chart's series names), or to the Ranking root to paint every bar. "The leader in the brand, the rest quiet" is `tone={i === 0 ? "brand" : "neutral"}`. There is no need to reach into the fill with a `[&>div]` selector.

### Where does the total go?

Ranking has no figure part: set a standalone `StatValue` (with a `StatTrend` beside it) between the RankingHeader and the RankingList. It is the same headline figure a Stat tile or a chart card uses, so every card in a dashboard leads alike.

### How do I make rows clickable?

Pass `interactive` to a RankingItem for a pointer, hover wash, and focus ring, then wire `onClick`. Nested surfaces (rank chip, media tile, bar track) step down to the card surface on hover so they keep definition; add a trailing chevron to signal the affordance.

### How does variant change the card?

`variant` sets the surface treatment: `default` (border plus soft shadow), `outline` (flat, no shadow), or `elevated` (lifted shadow, no border). Ranking is a dashboard widget, so its spacing is fixed compact, there's no density knob to tune.

---

<!-- https://www.koalaui.com/docs/components/stat.md -->

# Stat

A KPI/metric card for dashboards: a label, a big tabular-nums value, a directional trend chip, and optional icon or sparkline. Compose the named parts into a tile, then drop a row of them above a Data Table.

```tsx
// A row of KPI tiles above your Orders table.
<div className="grid gap-4 sm:grid-cols-2 lg:grid-cols-4">
  <Stat>
    <StatHeader>
      <StatLabel>Total orders</StatLabel>
      <StatIcon className="bg-primary/10 text-primary"><ShoppingBag /></StatIcon>
    </StatHeader>
    <StatValue>1,429</StatValue>
    <StatFooter>
      <StatTrend direction="up">12.4%</StatTrend>
      <StatCaption>vs last month</StatCaption>
    </StatFooter>
  </Stat>
  {/* …Revenue, Avg. order value, Refunds */}
</div>
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add stat
```

Manual: run `npm install @phosphor-icons/react radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/stat/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

Stat is composed from named parts, like [Card](https://www.koalaui.com/docs/components/card.md). The `Stat` root owns the surface, variant, and density; the parts (`StatLabel`, `StatValue`, `StatTrend`) read it from context.

```tsx title="orders-stat.tsx"
import {
  Stat,
  StatHeader,
  StatLabel,
  StatValue,
  StatTrend,
  StatCaption,
  StatFooter,
  StatIcon,
} from "@/components/ui/stat"
import { ShoppingBag } from "@phosphor-icons/react"

export function OrdersStat() {
  return (
    <Stat>
      <StatHeader>
        <StatLabel>Total orders</StatLabel>
        <StatIcon className="bg-primary/10 text-primary"><ShoppingBag /></StatIcon>
      </StatHeader>
      <StatValue>1,429</StatValue>
      <StatFooter>
        <StatTrend direction="up">12.4%</StatTrend>
        <StatCaption>vs last month</StatCaption>
      </StatFooter>
    </Stat>
  )
}
```

## Group

`StatGroup` fuses a row of tiles into one segmented surface, the way a dashboard bands its headline KPIs together instead of floating them as separate cards. The group owns the single border, radius, and shadow; each nested `Stat` senses the group and sheds its own chrome to lie flush, with hairline dividers between. Set the widest-breakpoint column count with `columns` (`2 | 3 | 4`); it steps down gracefully on narrow screens.

```tsx
// One bordered surface, hairline dividers, tiles laid flush.
// Each Stat sheds its own border/shadow inside the group automatically.
<StatGroup columns={4}>
  <Stat>
    <StatHeader>
      <StatLabel>Total orders</StatLabel>
      <StatIcon className="bg-primary/10 text-primary"><ShoppingBag /></StatIcon>
    </StatHeader>
    <div className="flex flex-wrap items-center gap-x-2 gap-y-1">
      <StatValue>1,429</StatValue>
      <StatTrend direction="up">12.4%</StatTrend>
    </div>
  </Stat>
  {/* …Revenue, Avg. order value, Refunds */}
</StatGroup>
```

## Anatomy

A tile reads top-to-bottom: a `StatHeader` pairs the label with a tinted `StatIcon` (or an action), the `StatValue` carries the figure in `tabular-nums` so it never reflows, and a `StatFooter` sets the trend beside a muted comparison caption.

```tsx
<Stat>
  <StatHeader>
    <StatLabel>Total orders</StatLabel>
    <StatIcon className="bg-primary/10 text-primary"><ShoppingBag /></StatIcon>
  </StatHeader>
  <StatValue>1,429</StatValue>
  <StatFooter>
    <StatTrend direction="up">12.4%</StatTrend>
    <StatCaption>vs last month</StatCaption>
  </StatFooter>
</Stat>
```

## Trend

`StatTrend` is a soft chip whose arrow and color come from `direction`: `up` reads green, `down` red, and `neutral` muted. For metrics where down is the good outcome (refunds, churn, bounce rate), set `inverted`: the color flips to match the meaning while the arrow keeps pointing the honest way. The chip never wraps or shrinks, so a “+1.1 pts” in a narrow tile stays one chip and the row beside it gives way.

```tsx
<StatTrend direction="up">12.4%</StatTrend>          {/* green, ↑ */}
<StatTrend direction="down">2.3%</StatTrend>          {/* red, ↓ */}
<StatTrend direction="down" inverted>5.0%</StatTrend> {/* green, ↓ down is good */}
<StatTrend direction="neutral">0.0%</StatTrend>       {/* muted, – */}
```

## Sparkline

`StatSparkline` is built on [Chart](https://www.koalaui.com/docs/components/chart.md) in sparkline mode: a soft area fill under a trend line that bleeds to the bottom and side edges of the tile. It paints in `currentColor`, so set the hue with a text utility (`text-success`, `text-destructive`) and it themes across all four palettes for free. Pass `tooltip` to light up each point on hover with a gliding bubble.

```tsx
// Built on Chart: paints in currentColor, bleeds to the tile edges.
// "tooltip" lights each point on hover with a gliding bubble.
<Stat>
  <StatHeader>
    <StatLabel>Orders this week</StatLabel>
    <StatTrend direction="up">18.2%</StatTrend>
  </StatHeader>
  <StatValue>1,429</StatValue>
  <StatSparkline data={[18, 22, 19, 27, 24, 31, 29, 38, 42]} tooltip className="mt-3 text-success" />
</Stat>
```

## Count up

Pass `countUp` to `StatValue` and the figure counts up from zero to its value the first time it scrolls into view, the same trigger the marketing sections use, re-counting each time it scrolls back in. It climbs fast and decelerates onto the final figure, so it reads as a real count-up. It reads the string children (`"4,100+"`, `"$4.2M"`, `"4.6×"`) and preserves the prefix, suffix, and comma/decimal format as it counts, riding the built-in `tabular-nums` so the row never jitters as the count climbs. It no-ops for number-less content and honors `prefers-reduced-motion` by showing the final figure immediately.

```tsx
// "countUp" counts the figure up from zero to its value the first time it scrolls
// into view, and re-counts on every re-entry. It parses the string (prefix, number,
// suffix) and keeps the format, so "$4.2M" lands on $4.2M and "4.6×" on 4.6×.
// Honors prefers-reduced-motion.
<StatGroup columns={3}>
  <Stat density="comfortable" className="items-center gap-1.5 text-center">
    <StatValue countUp className="text-4xl">4,100+</StatValue>
    <StatLabel>Teams building on Koala</StatLabel>
  </Stat>
  <Stat density="comfortable" className="items-center gap-1.5 text-center">
    <StatValue countUp className="text-4xl">$4.2M</StatValue>
    <StatLabel>Engineering time saved</StatLabel>
  </Stat>
  <Stat density="comfortable" className="items-center gap-1.5 text-center">
    <StatValue countUp className="text-4xl">4.6×</StatValue>
    <StatLabel>Faster to ship</StatLabel>
  </Stat>
</StatGroup>
```

## Variants

`default` sits on a hairline border with a soft shadow; `outline` drops the shadow for flat, gridded dashboards; `elevated` trades the border for a lifted shadow when a tile needs to float; `plain` has no tile at all.

```tsx
<Stat variant="default">…</Stat>
<Stat variant="outline">…</Stat>
<Stat variant="elevated">…</Stat>
<Stat variant="plain">…</Stat>
```

## Without a frame

Most dashboards lead a chart or a card with one big figure, and that figure is not a tile. `variant="plain"` drops the ring, the shadow, the fill and the padding, and keeps everything else: the display-face figure, the density’s type ramp, and a tighter rhythm between the parts, since there is no frame left to space them against. Lay it on the sheet beside a chart, or inside a [Card](https://www.koalaui.com/docs/components/card.md), where the card is the frame. Inside a `StatGroup` the group already owns the frame, so a plain tile keeps the group’s padding.

```tsx
// On the sheet: the figure with no tile around it.
<Stat variant="plain">
  <StatLabel>Net sales</StatLabel>
  <div className="flex flex-wrap items-center gap-2">
    <StatValue>$48,290</StatValue>
    <StatTrend direction="up">+8.1%</StatTrend>
  </div>
  <StatCaption className="tabular-nums">Sep 21–27, against the week before</StatCaption>
</Stat>

// Inside a Card: the card is the frame.
<Card>
  <CardHeader>
    <CardTitle>Refunds</CardTitle>
    <CardDescription>Money returned to customers this week.</CardDescription>
  </CardHeader>
  <CardContent>
    <Stat variant="plain">
      <div className="flex flex-wrap items-center gap-2">
        <StatValue>$2,840</StatValue>
        <StatTrend direction="down" inverted>-4.2%</StatTrend>
      </div>
      <StatCaption className="tabular-nums">32 orders, 2.1% of sales</StatCaption>
    </Stat>
  </CardContent>
</Card>
```

## Parts on their own

The parts do not need a Stat around them. `StatValue`, `StatTrend`, `StatLabel` and `StatCaption` (and the header, footer and icon rows) render anywhere with the plain look at the ambient density, so the headline figure of a chart card is a `StatValue`, and the trend chip beside a number in a description is a `StatTrend`, the same chip a tile carries. `countUp` works there too. Only `StatSparkline` needs a Stat, because it bleeds to the tile’s edges.

```tsx
// The headline figure of a card, with the window it covers:
<Card>
  <CardHeader>
    <CardTitle>Orders</CardTitle>
    <CardDescription>Placed on the storefront.</CardDescription>
  </CardHeader>
  <CardContent>
    <div className="flex items-baseline justify-between gap-3">
      <StatValue>1,429</StatValue>
      <StatCaption className="tabular-nums">Sep 21–27</StatCaption>
    </div>
  </CardContent>
</Card>

// The trend chip beside any figure:
<Card>
  <CardHeader>
    <CardTitle>Traffic sources</CardTitle>
    <CardDescription className="flex flex-wrap items-center gap-x-2 gap-y-1">
      <span className="tabular-nums">12,480 visits</span>
      <StatTrend direction="up">+6.3%</StatTrend>
      <span>against last week</span>
    </CardDescription>
  </CardHeader>
</Card>
```

## Density

Density is Koala’s cross-cutting spacing axis (see [Density](https://www.koalaui.com/docs/foundations/density.md)). For Stat it tunes padding, gap, the icon tile, and the value size. `compact` is the dashboard default; `comfortable` is roomier. Set it per-tile or for a whole grid with `DensityProvider`.

```tsx
// "compact" (the dashboard default) or "comfortable"
<Stat density="compact">…</Stat>
<Stat density="comfortable">…</Stat>
```

## Interactive

A KPI tile is data, not a control, so it stays inert by default. When the whole tile should drill into a detail view, pass `asChild` to render it as a link and `interactive` to add the pointer, hover lift, and focus ring. For a per-tile menu instead, drop a [Button](https://www.koalaui.com/docs/components/button.md) into the header.

```tsx
// The whole tile drills into a detail view:
<Stat asChild interactive>
  <a href="/orders">
    <StatHeader>
      <StatLabel>Total orders</StatLabel>
      <StatIcon className="bg-primary/10 text-primary"><ShoppingBag /></StatIcon>
    </StatHeader>
    <StatValue>1,429</StatValue>
    <StatFooter>
      <StatTrend direction="up">12.4%</StatTrend>
      <StatCaption>View all orders</StatCaption>
    </StatFooter>
  </a>
</Stat>

// Or a per-tile menu: drop a Button in the header:
<StatHeader>
  <StatLabel>Revenue</StatLabel>
  <Button variant="ghost" size="sm" iconOnly aria-label="More"><DotsThree /></Button>
</StatHeader>
```

## API reference

`Stat` forwards all `div` props and adds `variant` (`default | outline | elevated | plain`), `density` (`compact | comfortable`), `interactive`, and `asChild`. `StatGroup` bands a row of tiles into one surface and forwards `div` props plus `variant` (`default | outline | elevated`), `columns` (`2 | 3 | 4`), and `asChild`. The parts `StatHeader`, `StatLabel`, `StatValue`, `StatCaption`, `StatFooter`, `StatIcon` all forward `div` props; `StatValue` adds `countUp` to count a string figure up from zero on scroll. `StatTrend` adds `direction` (`up | down | neutral`) and `inverted`; `StatSparkline` takes a `data: number[]`, an optional `strokeWidth`, and `tooltip` to enable per-point hover. Every part but `StatSparkline` also renders outside a `Stat`, with the plain look at the ambient density. Every part accepts `className`, merged last.

## FAQ

### How do I compose a tile from the named parts?

The `Stat` root owns the surface, variant, and density; nest a `StatHeader` (with `StatLabel` plus an optional `StatIcon`), then `StatValue`, then a `StatFooter` pairing `StatTrend` with `StatCaption`. The parts read the root from context, so you never wire props between them.

### When should I use StatGroup instead of separate Stat cards?

Reach for `StatGroup` to band a row of headline KPIs into one segmented surface: the group owns the single border, radius, and shadow, and each nested `Stat` sheds its own chrome to lie flush with hairline dividers. Use standalone `Stat` tiles when they should float as separate cards. Set the widest-breakpoint column count with `columns` (`2 | 3 | 4`).

### What does the inverted prop on StatTrend do?

By default `StatTrend` colors `up` green and `down` red. For metrics where down is the good outcome, like refunds, churn, or bounce rate, set `inverted` so the color flips to match the meaning while the arrow keeps pointing the honest way.

### How do I make a whole tile clickable?

A KPI tile is data, so it is inert by default. Pass `asChild` to render it as a link (wrap an `<a>`) and `interactive` to add the pointer, hover lift, and focus ring; for a per-tile menu instead, drop a `Button` into the `StatHeader`.

### How do I color the StatSparkline and theme it?

`StatSparkline` paints in `currentColor`, so set the hue with a text utility like `text-success` or `text-destructive` and it themes across all four palettes for free. Pass `tooltip` to light up each point on hover.

### How do I animate the figures counting up?

Pass `countUp` to `StatValue`. It counts the figure up from zero to its value the first time it scrolls into view (an IntersectionObserver, same trigger as the marketing sections) and re-counts on every re-entry, climbing fast then decelerating onto the final figure. It parses the string children to keep the prefix, suffix, and comma/decimal format: `$4.2M` lands on $4.2M, `4.6×` on 4.6×, `74%` on 74%. It relies on the value's built-in `tabular-nums` so the row never jitters as the count climbs, no-ops for number-less content, and honors `prefers-reduced-motion` by showing the final figure immediately.

### How do I show a headline figure without the tile?

Use `variant="plain"`: no ring, no shadow, no fill and no padding, with the Stat's type ramp and a tighter gap between the parts. It is the figure laid on the sheet beside a chart, or inside a Card where the card is the frame. For a lone number, skip the Stat entirely: `StatValue`, `StatTrend`, `StatLabel` and `StatCaption` all render on their own.

### Can I use StatTrend next to a figure that is not in a Stat?

Yes. Outside a Stat, `StatTrend` is the same soft chip with the same `direction` and `inverted` rules, so a trend in a card description or a table row matches the tiles. It never wraps or shrinks: in a tight row the text beside it gives way instead.

### Which density should I use for a dashboard?

`compact` is the dashboard default and tunes padding, gap, the icon tile, and the value size down; `comfortable` is roomier. Set it per-tile via the `density` prop or for a whole grid with `DensityProvider`.

---

<!-- https://www.koalaui.com/docs/components/accordion.md -->

# Accordion

A stack of disclosure rows built on Radix Accordion: keyboard nav, ARIA, and single or multiple expansion. The variant axis spans a flush minimal list, contained cards, a pill list that hugs its own text, and a board grid.

```tsx
<Accordion type="single" collapsible defaultValue="what">
  <AccordionItem value="what">
    <AccordionTrigger>What is Koala UI?</AccordionTrigger>
    <AccordionContent>
      A commercial React component library: polished, token-driven, and
      Radix-backed, built to ship design systems that feel finished on day one.
    </AccordionContent>
  </AccordionItem>
  <AccordionItem value="themes">
    <AccordionTrigger>How does theming work?</AccordionTrigger>
    <AccordionContent>
      Every color is a semantic token redefined per theme, so all four themes
      (light, dark, cream, and moonlight) re-skin automatically.
    </AccordionContent>
  </AccordionItem>
  <AccordionItem value="a11y">
    <AccordionTrigger>Is it accessible?</AccordionTrigger>
    <AccordionContent>
      Behavior and a11y come from Radix primitives: focus, keyboard, and ARIA are
      handled for you, never hand-rolled.
    </AccordionContent>
  </AccordionItem>
</Accordion>
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add accordion
```

Manual: run `npm install radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/accordion/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

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

export function Example() {
  return (
    <Accordion type="single" collapsible>
      <AccordionItem value="item-1">
        <AccordionTrigger>Section title</AccordionTrigger>
        <AccordionContent>Section body.</AccordionContent>
      </AccordionItem>
    </Accordion>
  )
}
```

## Variants

Three levels of chrome along one axis. `minimal` is a flush list of rows split by hairlines; `card` wraps the set in a single bordered box with dividers; `separated` gives every item its own. None of them paints a fill: they take the ground they sit on, so on a muted band the rows read as the band.

Off that axis sits `pill`, the one variant where a closed row does *not* span the list: each question hugs its own text as a chip, and the open one floods to full width and squares off into a filled card. It is a control, not a container, so it does paint a fill: the same ink tint a Tabs segment uses, which reads one step off whatever ground it lands on. Built for a short list beside something else, a photograph or a product shot, where a ragged column of labels beats a stack of full-width rules.

`board` takes `separated`'s outline and lays it out as a grid: closed questions read as a wall you scan rather than a list you go down, and the one you open spans every column, so its answer gets a full measure instead of a third of one. The root is the grid, so its column count comes from a `className` like `lg:grid-cols-3`.

```tsx
{/* minimal: borderless, hairline dividers (default) */}
<Accordion type="single" collapsible variant="minimal">…</Accordion>

{/* card: one container, shared dividers */}
<Accordion type="single" collapsible variant="card">…</Accordion>

{/* separated: each item is its own card */}
<Accordion type="single" collapsible variant="separated">…</Accordion>

{/* pill: closed questions hug their text; the open one is a filled card */}
<Accordion type="single" collapsible variant="pill">…</Accordion>

{/* board: tiles in a grid; the open one spans every column */}
<Accordion type="single" collapsible variant="board" className="lg:grid-cols-3">…</Accordion>
```

## Single vs. multiple

Radix drives expansion. `type="single"` keeps one row open at a time. Add `collapsible` to allow closing the open row. `type="multiple"` lets several stay open at once.

```tsx
<Accordion type="multiple" variant="card" defaultValue={["one", "two"]}>
  <AccordionItem value="one">…</AccordionItem>
  <AccordionItem value="two">…</AccordionItem>
  <AccordionItem value="three">…</AccordionItem>
</Accordion>
```

## Density

Like Card and Dialog, Accordion honors Koala's density axis. `comfortable` is the spacious marketing default; `compact` tightens row height and inset for dense application UI. Set it per-instance or once via a `DensityProvider`.

```tsx
<Accordion type="single" collapsible variant="card" density="compact">…</Accordion>
```

## Icon position

`iconPosition` controls where the caret sits. `trailing` (the default) pins it to the right edge of the row; `leading` moves it ahead of the label for a help-center / knowledge-base look. The caret still flips on open and keeps its ARIA wiring either way.

```tsx
{/* trailing: caret on the right (default) */}
<Accordion type="single" collapsible variant="card" iconPosition="trailing">…</Accordion>

{/* leading: caret ahead of the label */}
<Accordion type="single" collapsible variant="card" iconPosition="leading">…</Accordion>
```

## Marker

`marker` picks the disclosure mark. `caret` (the default) is a chevron that flips a full 180°; `plus` is the FAQ / help-centre mark, a plus that turns 45° into a cross. It is the same glyph and the same turn `GalleryAccordion` uses, so the library has one disclosure mark rather than two idioms for the same gesture. Both ride the shared `caret-turn` beat, so glyph and height tween move together, and both stay neutral in every state: the motion is the feedback, not a color change.

```tsx
{/* caret: a chevron that flips 180° (default) */}
<Accordion type="single" collapsible variant="card" marker="caret">…</Accordion>

{/* plus: a plus that turns 45° into a cross */}
<Accordion type="single" collapsible variant="card" marker="plus">…</Accordion>
```

## Size

`size` is the type scale, orthogonal to density (which only moves spacing). `md` (the default) leaves the row to density; `lg` is the landing-page FAQ, where each question reads as a heading: an 18px semibold question on a taller row, a 16px answer and a 20px mark. `Faqs` sets it for every list inside with its own `size`.

```tsx
<Accordion type="single" collapsible variant="minimal" marker="plus" size="lg">…</Accordion>
```

## FAQ

### What is the difference between the minimal, card, and separated variants?

They are three points on one chrome axis. `minimal` (the default) is a borderless list of rows split by hairline dividers; `card` wraps the whole set in a single bordered, shadowed surface with shared dividers; `separated` gives every `AccordionItem` its own standalone card stacked with a gap.

### How do I set the columns on the board variant?

With a className on the Accordion itself: the root is the grid, so lg:grid-cols-3 lands on it and tailwind-merge swaps the recipe's own column count. The tile you open always spans whatever that count is, because it is col-span-full rather than a fixed span, and its answer keeps a reading measure of its own so a full-width tile does not run to 100 characters a line.

### When should I reach for the pill variant?

When the list is short and sits beside something else, like the photo half of a FAQ diptych. A closed question hugs its own text as a chip and the open one floods to full width as a filled card, so five or six questions read as a ragged column of labels rather than a table of contents. It is the one variant that paints a fill (an ink tint, so it works on a page, a muted half, or a dark band alike) and the one whose closed rows do not line up on the right.

### Why does a pill widen instantly when it opens but narrow smoothly when it closes?

Because opening has to be instant. Radix measures the answer's height the moment it mounts, so if the chip were still widening it would measure the prose wrapped at chip width, far too tall, and then animate to that wrong height while the text re-wrapped underneath. Closing has no such problem: by then the answer is hidden and there is nothing left to re-wrap, so the card narrows back into its chip. The one-way behaviour is a single class, `transition-[background-color,transform]` on the open state, since a transition only runs when the new style still lists the property.

### Why does the pill variant keep the same border radius open and closed?

So the shape morph rides the height, which is the thing actually changing. A radius past half the height is clamped to exactly half, so `rounded-2xl` is a perfect stadium on a 44px row and a rounded card once the answer grows the box. Animating `rounded-pill` to `rounded-2xl` instead looks broken: the clamp pins the corners at half the height for most of the tween, so the card balloons into a lozenge and only snaps square at the very end.

### How do I allow only one row open at a time but still let the user close it?

Set `type="single"` to keep one row open at a time, then add the `collapsible` prop so clicking the open row closes it. Without `collapsible`, single mode always keeps one row expanded.

### When should I use type="multiple" instead of type="single"?

Use `type="multiple"` when several sections can be relevant at once, like an FAQ where readers scan many answers. It lets any number of rows stay open, and its initial state is an array (`defaultValue={["one", "two"]}`) rather than a single string.

### Do I need to wire up keyboard navigation or ARIA myself?

No. Accordion is built on Radix Accordion, so arrow-key navigation between triggers, Home/End, Space/Enter to toggle, and the heading/region ARIA wiring are all handled. The disclosure mark on each `AccordionTrigger` (a caret by default, or a plus with `marker="plus"`) is marked aria-hidden and turns on open via data-state.

### How do I make the accordion more compact for dense application UI?

Pass `density="compact"` to tighten the row height and content inset (`comfortable` is the spacious default). You can set it per instance or once for a subtree via a `DensityProvider`, and the contained variants adjust their horizontal inset to match.

### Why does my row not show a height animation when it opens?

The open/close tween relies on Radix's `--radix-accordion-content-height` variable feeding the accordion-down/up keyframes, so keep your body inside `AccordionContent` rather than restyling the wrapper. Padding lives on an inner div, so add spacing via `AccordionContent` and avoid overriding its overflow-hidden wrapper.

---

<!-- https://www.koalaui.com/docs/components/activity-feed.md -->

# Activity Feed

A vertical timeline of what happened: comments, mentions, status changes, uploads, members joining. One rail threads every event, while each row varies its marker and its body, from a terse audit log to a rich inbox.

```tsx
<ActivityFeed>
  {/* A posted comment: avatar marker, quoted in a card */}
  <ActivityItem>
    <ActivityMarker>
      <Avatar size="sm">
        <AvatarImage src={user.avatar} alt={user.name} />
        <AvatarFallback>SC</AvatarFallback>
      </Avatar>
    </ActivityMarker>
    <ActivityContent>
      <ActivityHeader>
        <ActivityActor>Sarah Chen</ActivityActor>
        commented
        <ActivityTime dateTime="2026-06-15T12:30:00Z">2h ago</ActivityTime>
      </ActivityHeader>
      <ActivityCard>Love the new onboarding flow…</ActivityCard>
    </ActivityContent>
  </ActivityItem>

  {/* A mention: tinted icon marker */}
  <ActivityItem>
    <ActivityMarker>
      <ActivityIcon tone="purple"><At /></ActivityIcon>
    </ActivityMarker>
    <ActivityContent>
      <ActivityHeader>
        <ActivityActor>Marcus Lee</ActivityActor>
        mentioned you
        <ActivityTime dateTime="2026-06-15T11:05:00Z">3h ago</ActivityTime>
      </ActivityHeader>
      <ActivityBody>“@you can you own the migration checklist?”</ActivityBody>
    </ActivityContent>
  </ActivityItem>

  {/* An upload: image gallery + a reused FileCard row */}
  <ActivityItem>
    <ActivityMarker>
      <ActivityIcon tone="teal"><UploadSimple /></ActivityIcon>
    </ActivityMarker>
    <ActivityContent>
      <ActivityHeader>
        <ActivityActor>Priya Nair</ActivityActor>
        uploaded 2 files
        <ActivityTime dateTime="2026-06-15T09:48:00Z">5h ago</ActivityTime>
      </ActivityHeader>
      <ActivityAttachments>
        <div className="flex flex-wrap gap-2">
          <ActivityImage src={shot} alt="Brand exploration" />
        </div>
        <FileCard>
          <FileCardIcon type="pdf" />
          <FileCardContent>
            <FileCardName>Brand-guidelines.pdf</FileCardName>
            <FileCardMeta>2.4 MB · PDF document</FileCardMeta>
          </FileCardContent>
        </FileCard>
      </ActivityAttachments>
    </ActivityContent>
  </ActivityItem>

  {/* A status change: success icon + Badge */}
  <ActivityItem>
    <ActivityMarker>
      <ActivityIcon tone="success"><CheckCircle /></ActivityIcon>
    </ActivityMarker>
    <ActivityContent>
      <ActivityHeader>
        <ActivityActor>Marcus Lee</ActivityActor>
        changed status to <Badge size="sm" variant="success">Done</Badge>
        <ActivityTime dateTime="2026-06-15T08:20:00Z">6h ago</ActivityTime>
      </ActivityHeader>
    </ActivityContent>
  </ActivityItem>

  {/* A minor edit: low-emphasis dot closes the rail */}
  <ActivityItem>
    <ActivityMarker><ActivityDot /></ActivityMarker>
    <ActivityContent>
      <ActivityHeader>
        <ActivityActor>Priya Nair</ActivityActor>
        changed the due date to <span className="text-foreground">Jun 20</span>
        <ActivityTime dateTime="2026-06-14T16:30:00Z">Yesterday</ActivityTime>
      </ActivityHeader>
    </ActivityContent>
  </ActivityItem>
</ActivityFeed>
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add activity-feed
```

Manual: run `npm install @phosphor-icons/react radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/activity-feed/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

Activity Feed is composed from named parts, like [Ranking](https://www.koalaui.com/docs/components/ranking.md). The `ActivityFeed` root is a semantic `<ol>` that owns density and the connecting rail; each `ActivityItem` pairs an `ActivityMarker` (drop an `ActivityIcon`, an [Avatar](https://www.koalaui.com/docs/components/avatar.md), or an `ActivityDot` inside it) with an `ActivityContent` body. The rail is drawn automatically and closes itself on the last event.

```tsx title="activity.tsx"
import {
  ActivityFeed,
  ActivityItem,
  ActivityMarker,
  ActivityIcon,
  ActivityContent,
  ActivityHeader,
  ActivityActor,
  ActivityTime,
} from "@/components/ui/activity-feed"
import { GitMerge } from "@phosphor-icons/react"

export function Timeline() {
  return (
    <ActivityFeed>
      <ActivityItem>
        <ActivityMarker>
          <ActivityIcon tone="success"><GitMerge /></ActivityIcon>
        </ActivityMarker>
        <ActivityContent>
          <ActivityHeader>
            <ActivityActor>Alex Rivera</ActivityActor>
            merged the pull request
            <ActivityTime dateTime="2026-06-15T10:30:00Z">30m ago</ActivityTime>
          </ActivityHeader>
        </ActivityContent>
      </ActivityItem>
    </ActivityFeed>
  )
}
```

```tsx
<ActivityFeed>
  <ActivityItem>
    <ActivityMarker>
      <ActivityIcon tone="info"><ChatCircle /></ActivityIcon>
    </ActivityMarker>
    <ActivityContent>
      <ActivityHeader>
        <ActivityActor>Alex Rivera</ActivityActor>
        opened the issue
        <ActivityTime dateTime="2026-06-15T10:00:00Z">1h ago</ActivityTime>
      </ActivityHeader>
    </ActivityContent>
  </ActivityItem>
  <ActivityItem>
    <ActivityMarker>
      <ActivityIcon tone="success"><GitMerge /></ActivityIcon>
    </ActivityMarker>
    <ActivityContent>
      <ActivityHeader>
        <ActivityActor>Alex Rivera</ActivityActor>
        merged the pull request
        <ActivityTime dateTime="2026-06-15T10:30:00Z">30m ago</ActivityTime>
      </ActivityHeader>
    </ActivityContent>
  </ActivityItem>
</ActivityFeed>
```

## Playground

Flip the knobs and watch the snippet keep up. Note that the two groups do different things: **Props** are values the component takes, while **Parts** are children you compose in or leave out, which is why turning one off removes an element from the code rather than adding a `show`-something prop. Turn them all off and the event still holds its alignment.

## Only the parts you need

There is no `showTime` or `showBody` prop, because there is nothing to switch off: an event is whatever parts you put in it. Every part is droppable, and whichever one leads the content takes over the alignment, so a header-only event, a body-only event, and a card-only event all sit on the same axis as their marker.

```tsx
// No showX props: an event is the parts you give it, and whichever
// part leads the content takes over the alignment with the marker.

{/* header only */}
<ActivityContent>
  <ActivityHeader>
    <ActivityActor>Dana Wu</ActivityActor>
    commented
    <ActivityTime dateTime="2026-06-15T12:30:00Z">2h</ActivityTime>
  </ActivityHeader>
</ActivityContent>

{/* body only */}
<ActivityContent>
  <ActivityBody>Reopened after the staging deploy went out.</ActivityBody>
</ActivityContent>

{/* card only */}
<ActivityContent>
  <ActivityCard>Can we ship the copy tweaks before Friday?</ActivityCard>
</ActivityContent>
```

## Markers

The marker carries the type of event. `ActivityIcon` is a soft tinted tile: pass a Phosphor glyph and a `tone` (`brand`, `success`, `info`, `destructive`, `purple`, and more). For people, drop an `Avatar` in the same slot; for minor events, `ActivityDot` is a low-emphasis dot. All three share a 32px footprint, so the rail stays aligned whichever you use.

```tsx
{/* Avatar: for people */}
<ActivityMarker>
  <Avatar size="sm">
    <AvatarImage src={user.avatar} alt={user.name} />
    <AvatarFallback>JP</AvatarFallback>
  </Avatar>
</ActivityMarker>

{/* Tinted icon: for typed events */}
<ActivityMarker>
  <ActivityIcon tone="orange"><UserPlus /></ActivityIcon>
</ActivityMarker>

{/* Dot: for minor events */}
<ActivityMarker>
  <ActivityDot />
</ActivityMarker>
```

## Attachments

Events carry payloads, and the feed composes them from existing components rather than re-rolling chips. Stack them in `ActivityAttachments`: drop a [File Card](https://www.koalaui.com/docs/components/file-card.md) row in for each file (it already ships the type-tinted icon, name, and meta) and lay `ActivityImage` thumbnails out in a `flex flex-wrap` row for an image gallery. For an upload-in-progress state, use File Card’s `FileCardProgress`; to collect the files in the first place, see [File Upload](https://www.koalaui.com/docs/components/file-upload.md).

```tsx
<ActivityAttachments>
  {/* an image gallery */}
  <div className="flex flex-wrap gap-2">
    <ActivityImage src={poster} alt="Poster concept" />
    <ActivityImage src={study} alt="Color study" />
  </div>
  {/* files reuse the FileCard component, no custom chip */}
  <FileCard>
    <FileCardIcon type="archive" />
    <FileCardContent>
      <FileCardName>source-assets.zip</FileCardName>
      <FileCardMeta>18 MB · Archive</FileCardMeta>
    </FileCardContent>
  </FileCard>
</ActivityAttachments>
```

## Quoted comments

`ActivityCard` is a nested surface for quoted content: a posted comment, a review, a changelog note. Its radius steps down concentrically from the Card the feed usually sits in. For a short, muted one-liner under the header, use `ActivityBody` instead.

```tsx
<ActivityContent>
  <ActivityHeader>
    <ActivityActor>Dana Wu</ActivityActor>
    left a review
    <ActivityTime dateTime="2026-06-15T07:10:00Z">8h ago</ActivityTime>
  </ActivityHeader>
  <ActivityCard>
    The motion polish is great, but the empty-state illustration feels a
    touch heavy against the cream theme. Maybe drop it to 80% opacity?
  </ActivityCard>
</ActivityContent>
```

## Unread

Mark an event as new to this reader with `unread` on `ActivityItem`: the header comes up to full-strength text and a brand dot rides the end of the row (with a screen-reader label). Deliberately no tinted row fill, since a feed is chrome-less and a band would read as a container.

```tsx
// unread: full-strength header text + a brand dot at the end of the row.
<ActivityFeed connector={false}>
  <ActivityItem unread>
    <ActivityMarker>
      <ActivityIcon tone="purple"><At /></ActivityIcon>
    </ActivityMarker>
    <ActivityContent>
      <ActivityHeader>
        <ActivityActor>Marcus Lee</ActivityActor>
        mentioned you in <ActivityActor asChild><a href="#">Q3 roadmap</a></ActivityActor>
        <ActivityTime dateTime="2026-06-15T11:05:00Z">3h ago</ActivityTime>
      </ActivityHeader>
    </ActivityContent>
  </ActivityItem>
  <ActivityItem>…already read…</ActivityItem>
</ActivityFeed>
```

## Interactive events

Pass `asChild` with an `<a>` child to make a whole event a link: the `<li>` stays the list item while the child becomes the hover-lit surface, so the markup is valid `<li><a>`. Use `interactive` on its own for a row that takes an `onClick`. The press feedback deepens the fill rather than scaling the row, the same call [List](https://www.koalaui.com/docs/components/list.md) makes for flush rows.

```tsx
// asChild puts the row on the <a>, keeping valid <li><a>…</a></li>.
<ActivityItem asChild>
  <a href={event.href}>
    <ActivityMarker>
      <ActivityIcon tone="brand"><GitMerge /></ActivityIcon>
    </ActivityMarker>
    <ActivityContent>
      <ActivityHeader>
        <ActivityActor>Alex Rivera</ActivityActor>
        merged <span className="text-foreground">Fix rail alignment</span>
        <ActivityTime dateTime="2026-06-15T10:30:00Z">30m ago</ActivityTime>
      </ActivityHeader>
    </ActivityContent>
  </a>
</ActivityItem>

{/* or, for a handler instead of a link */}
<ActivityItem interactive onClick={open}>…</ActivityItem>
```

## Row actions

`ActivityActions` is a trailing slot for per-event controls: a reply, a download, an overflow menu. It sits beside `ActivityContent` rather than inside the header (which wraps), and parks on the marker’s axis so it rides the first line however tall the event grows. Don’t combine it with `asChild`, which would nest a control inside a link.

```tsx
// ActivityActions is a sibling of ActivityContent, not a child of the header.
<ActivityItem>
  <ActivityMarker>
    <Avatar size="sm">…</Avatar>
  </ActivityMarker>
  <ActivityContent>
    <ActivityHeader>
      <ActivityActor>Sarah Chen</ActivityActor>
      commented
      <ActivityTime dateTime="2026-06-15T12:30:00Z">2h ago</ActivityTime>
    </ActivityHeader>
    <ActivityCard>The motion polish landed nicely…</ActivityCard>
  </ActivityContent>
  <ActivityActions>
    <Button variant="ghost" size="sm" iconOnly aria-label="Reply">
      <ArrowBendUpLeft />
    </Button>
    <Button variant="ghost" size="sm" iconOnly aria-label="More actions">
      <DotsThree />
    </Button>
  </ActivityActions>
</ActivityItem>
```

## Day groups

`ActivityGroup` gathers a run of events under a heading, a day or any other bucket, with an `ActivityGroupLabel` first. The label sits in the events' text column and the rail runs straight past it, so the timeline stays one line from the first event to the last. Each group is its own list, named by its label for a screen reader (“Today, list, 2 items”). The label is droppable, and a divided feed or one without the rail groups the same way.

```tsx
<ActivityFeed density="compact">
  <ActivityGroup>
    <ActivityGroupLabel>Today</ActivityGroupLabel>
    <ActivityItem>
      <ActivityMarker>
        <Avatar size="sm">
          <AvatarImage src={patient.avatar} alt="" />
          <AvatarFallback>SC</AvatarFallback>
        </Avatar>
      </ActivityMarker>
      <ActivityContent>
        <ActivityHeader>
          <ActivityActor>Sarah Chen</ActivityActor>
          checked in for the 10:30 visit
          <ActivityTime dateTime="2026-09-27T10:24:00Z">10:24</ActivityTime>
        </ActivityHeader>
      </ActivityContent>
    </ActivityItem>
    <ActivityItem>
      <ActivityMarker>
        <ActivityIcon tone="success"><CheckCircle /></ActivityIcon>
      </ActivityMarker>
      <ActivityContent>
        <ActivityHeader>
          <ActivityActor>Front desk</ActivityActor>
          marked the invoice paid
          <ActivityTime dateTime="2026-09-27T09:02:00Z">09:02</ActivityTime>
        </ActivityHeader>
      </ActivityContent>
    </ActivityItem>
  </ActivityGroup>

  <ActivityGroup>
    <ActivityGroupLabel>Yesterday</ActivityGroupLabel>
    <ActivityItem>
      <ActivityMarker>
        <ActivityIcon tone="info"><ChatCircle /></ActivityIcon>
      </ActivityMarker>
      <ActivityContent>
        <ActivityHeader>
          <ActivityActor>Marcus Lee</ActivityActor>
          left a note on the record
          <ActivityTime dateTime="2026-09-26T16:40:00Z">16:40</ActivityTime>
        </ActivityHeader>
        <ActivityBody>Prefers morning slots, bring the X-ray from March.</ActivityBody>
      </ActivityContent>
    </ActivityItem>
    <ActivityItem>
      <ActivityMarker>
        <ActivityDot tone="brand" />
      </ActivityMarker>
      <ActivityContent>
        <ActivityHeader>
          <ActivityActor>Sarah Chen</ActivityActor>
          booked a visit
          <ActivityTime dateTime="2026-09-26T11:15:00Z">11:15</ActivityTime>
        </ActivityHeader>
      </ActivityContent>
    </ActivityItem>
  </ActivityGroup>
</ActivityFeed>
```

## Divided

`divided` swaps the vertical rail for a hairline rule between events: the audit-log and notification-inbox reading. It re-balances the per-event rhythm so each rule sits evenly between its neighbours, and it takes the rail with it. A rule and a rail are two answers to the same question, so a divided feed never draws the connector and `connector` is ignored there.

```tsx
// The three coherent feeds. A rule and a rail say the same thing, so
// a divided feed never draws the connector.
<ActivityFeed>…</ActivityFeed>                    {/* the rail */}
<ActivityFeed divided>…</ActivityFeed>            {/* a rule */}
<ActivityFeed connector={false}>…</ActivityFeed>  {/* neither */}
```

## Without the rail

Set `connector={false}` on the feed for a plain list of events with no connecting line, useful for a single notification, a digest, or a card where the timeline framing would be too heavy.

```tsx
// connector={false} drops the connecting rail entirely.
<ActivityFeed connector={false}>
  <ActivityItem>
    <ActivityMarker>
      <Avatar size="sm">…</Avatar>
    </ActivityMarker>
    <ActivityContent>…</ActivityContent>
  </ActivityItem>
</ActivityFeed>
```

## Density

Density is Koala’s cross-cutting spacing axis (see [Density](https://www.koalaui.com/docs/foundations/density.md)). For the feed it tunes the gap to the rail and each event’s own padding; the marker size stays fixed so the rail aligns identically at both densities. `comfortable` is the default; `compact` tightens it for dense app timelines. Set it per-feed or for a whole subtree with `DensityProvider`.

```tsx
// "comfortable" (default) or "compact"
<ActivityFeed density="comfortable">…</ActivityFeed>
<ActivityFeed density="compact">…</ActivityFeed>
```

## API reference

`ActivityFeed` renders an `<ol>` and adds `density` (`comfortable | compact`) and `divided` (`boolean`, default `false`) and `connector` (`boolean`, default `true`, ignored when the feed is divided). `ActivityItem` renders an `<li>` and takes `unread`, `interactive`, and `asChild` (which implies `interactive`). `ActivityIcon` and `ActivityDot` take a `tone` (`default | brand | success | warning | info | destructive | purple | pink | teal | orange`). `ActivityActor` accepts `asChild`; `ActivityTime` renders a `<time>` (pass `dateTime`); `ActivityImage` requires `alt`. `ActivityGroup` renders an `<li>` of the feed holding its own `<ol>`, and `ActivityGroupLabel` names it. The rest ( `ActivityMarker`, `ActivityContent`, `ActivityHeader`, `ActivityBody`, `ActivityCard`, `ActivityAttachments`, `ActivityActions`) forward their element props. Attachments compose existing components ([File Card](https://www.koalaui.com/docs/components/file-card.md) for files). Every part accepts `className`, merged last.

## FAQ

### How do I choose between ActivityIcon, an Avatar, and ActivityDot for a marker?

Use `ActivityIcon` with a tone for typed events (a status change, an upload), an `Avatar` when a specific person acted, and `ActivityDot` for low-emphasis minor events like a field edit. All three share a fixed footprint inside `ActivityMarker`, so the rail stays aligned whichever you pick.

### What tones can ActivityIcon and ActivityDot take?

Both accept a `tone` of `default`, `brand`, `success`, `warning`, `info`, `destructive`, `purple`, `pink`, `teal`, or `orange`. The icon renders a soft tinted tile (border/bg/text in that role) and the dot renders a solid fill, and every tone re-themes across all palettes.

### Do I have to draw the connecting line between events myself?

No. The rail is pure layout with no JS: each `ActivityMarker` stretches and appends a connector, which fills the column below the marker and then carries across the gap to the next one on a negative bottom margin. The feed hides the connector on the last list item, so the line always stops cleanly at the final event.

### How do I render a single notification or digest without the timeline line?

Pass `connector={false}` on the `ActivityFeed` root for a plain list of events with no connecting rail. It is useful when the timeline framing would feel too heavy, such as one notification or a card-bound digest.

### When should I use ActivityCard versus ActivityBody for an event's text?

Use `ActivityBody` for a short muted one-liner under the header, and `ActivityCard` for quoted content like a posted comment, a review, or a changelog note. `ActivityCard` is a nested surface whose radius steps down concentrically from the Card the feed usually sits in.

### Is there a prop to hide the timestamp, the body, or the avatar?

No, and there won't be. Structure is composed, not switched: an event renders exactly the parts you put in it, so you drop `ActivityTime` rather than setting `showTime={false}`. Props are reserved for appearance that spans the whole feed (`density`, `divided`) and for per-event state (`unread`, `interactive`). Every part is built to lead the content on its own, so nothing breaks when you leave one out.

### How do I make a whole event clickable?

Pass `asChild` on `ActivityItem` with a single `<a>` or `<button>` child. The `<li>` keeps the list semantics and the divider while the child takes the row layout and the hover/focus treatment, which keeps the markup valid `<li><a>…</a></li>`. Use `interactive` on its own when you want the affordance with an `onClick` handler instead of a link.

### Can I put row actions inside an interactive event?

Not with `asChild`: that would nest a button inside a link, which is invalid markup and unusable by keyboard. Use `interactive` with an `onClick` on the row so the action in `ActivityActions` stays its own hit target, or drop the row-level interaction and let the actions carry it.

### When should I use divided instead of the rail?

Use the rail when events are a story that reads top-down, and `divided` when they are separate records you scan, like an audit log or a notification inbox. They are the same decision, so a divided feed never draws the rail and `connector` is ignored there: the three coherent feeds are the rail, the rule, or neither (`connector={false}`).

### How do I group events by day?

Wrap each day's events in `ActivityGroup` inside one `ActivityFeed`, with an `ActivityGroupLabel` first. The rail runs through every label to the next group's first marker, and only the last group closes it. Each group is its own `<ol>` named by the label, so a screen reader hears the day before its events. Don't render one feed per day: the rail would break at every heading.

### How should I attach files and images to an event?

Wrap them in `ActivityAttachments`. For files, drop a `FileCard` row in rather than re-rolling a chip, since it already ships the type-tinted icon, name, and meta; for images, lay `ActivityImage` thumbnails out in a `flex flex-wrap` row. Note `ActivityImage` requires an `alt`, and `ActivityTime` should get a `dateTime` ISO string.

---

<!-- https://www.koalaui.com/docs/components/alert.md -->

# Alert

An inline status banner for page-level messages, validation summaries, and contextual feedback. Five semantic variants, optional icon, actions, and a dismiss button.

```tsx
<Alert variant="success">
  <AlertIcon />
  <AlertContent>
    <AlertTitle>Deployment successful</AlertTitle>
    <AlertDescription>
      Your application has been deployed to production.
    </AlertDescription>
  </AlertContent>
</Alert>
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add alert
```

Manual: run `npm install radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/alert/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

```tsx title="usage.tsx"
import {
  Alert,
  AlertIcon,
  AlertContent,
  AlertTitle,
  AlertDescription,
  AlertActions,
} from "@/components/ui/alert"

export function Example() {
  return (
    <Alert variant="info">
      <AlertIcon />
      <AlertContent>
        <AlertTitle>Heads up</AlertTitle>
        <AlertDescription>This action cannot be undone.</AlertDescription>
      </AlertContent>
    </Alert>
  )
}
```

## Variants

Five semantic variants. Each keeps a neutral surface (`border-border` on `bg-background`) and only recolors the leading icon from a single semantic token (`--success`, `--warning`, etc.), so the status reads at a glance and re-themes across all four Koala themes automatically.

```tsx
<Alert variant="default">
  <AlertIcon />
  <AlertContent>
    <AlertTitle>Default</AlertTitle>
    <AlertDescription>A neutral, non-semantic message.</AlertDescription>
  </AlertContent>
</Alert>
<Alert variant="info">
  <AlertIcon />
  <AlertContent>
    <AlertTitle>Info</AlertTitle>
    <AlertDescription>Informational context for the user.</AlertDescription>
  </AlertContent>
</Alert>
<Alert variant="success">
  <AlertIcon />
  <AlertContent>
    <AlertTitle>Success</AlertTitle>
    <AlertDescription>The operation completed successfully.</AlertDescription>
  </AlertContent>
</Alert>
<Alert variant="warning">
  <AlertIcon />
  <AlertContent>
    <AlertTitle>Warning</AlertTitle>
    <AlertDescription>Review before proceeding.</AlertDescription>
  </AlertContent>
</Alert>
<Alert variant="destructive">
  <AlertIcon />
  <AlertContent>
    <AlertTitle>Error</AlertTitle>
    <AlertDescription>Something went wrong. Please try again.</AlertDescription>
  </AlertContent>
</Alert>
```

## Sizes

```tsx
<Alert variant="info" size="sm">
  <AlertIcon />
  <AlertContent>
    <AlertTitle>Small alert</AlertTitle>
    <AlertDescription>Compact size for dense UIs.</AlertDescription>
  </AlertContent>
</Alert>
<Alert variant="info" size="md">
  <AlertIcon />
  <AlertContent>
    <AlertTitle>Medium alert</AlertTitle>
    <AlertDescription>Default size for most contexts.</AlertDescription>
  </AlertContent>
</Alert>
```

## With icon

`AlertIcon` auto-selects the matching Phosphor icon for the current variant when no children are given. Pass children to use a custom icon instead.

```tsx
{/* Auto icon from variant */}
<Alert variant="warning">
  <AlertIcon />
  <AlertContent>
    <AlertTitle>Auto icon</AlertTitle>
  </AlertContent>
</Alert>

{/* Custom icon */}
<Alert variant="warning">
  <AlertIcon><Rocket weight="fill" /></AlertIcon>
  <AlertContent>
    <AlertTitle>Custom icon</AlertTitle>
  </AlertContent>
</Alert>

{/* No icon */}
<Alert variant="warning">
  <AlertContent>
    <AlertTitle>No icon</AlertTitle>
  </AlertContent>
</Alert>
```

## With actions

Use `AlertActions` inside `AlertContent` to add a row of action buttons below the description.

```tsx
<Alert variant="warning">
  <AlertIcon />
  <AlertContent>
    <AlertTitle>Unsaved changes</AlertTitle>
    <AlertDescription>
      You have unsaved changes that will be lost if you leave.
    </AlertDescription>
    <AlertActions>
      <Button size="sm" variant="outline">Discard</Button>
      <Button size="sm">Save changes</Button>
    </AlertActions>
  </AlertContent>
</Alert>
```

## Dismissible

Pass `onDismiss` to render a close button. The component is uncontrolled - the consumer manages visibility. Use `dismissLabel` to provide a screen-reader accessible label (defaults to `"Dismiss"`).

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

{open && (
  <Alert variant="info" onDismiss={() => setOpen(false)}>
    <AlertIcon />
    <AlertContent>
      <AlertTitle>New update available</AlertTitle>
      <AlertDescription>Version 2.4.0 is ready to install.</AlertDescription>
    </AlertContent>
  </Alert>
)}
```

## FAQ

### When should I reach for Alert instead of Toast?

Use Alert for inline, persistent messages that stay in the page flow: validation summaries, page-level banners, or contextual feedback next to the content it describes. Reach for Toast when the message is ephemeral and should auto-dismiss without occupying layout space.

### What does the variant prop change beyond the color?

variant sets the semantic tone (`default`, `info`, `success`, `warning`, `destructive`) which drives both the accent color and, when you render an empty `AlertIcon`, the auto-selected Phosphor icon. The tints derive from a single token per role so all five variants re-theme across the four Koala themes.

### How does AlertIcon pick its icon?

Leave `AlertIcon` empty and it auto-selects the icon matching the current variant (CheckCircle for success, Warning for warning, and so on). Pass children to use a custom icon, or omit `AlertIcon` entirely for an icon-free alert.

### How do I make an Alert dismissible?

Pass an `onDismiss` handler to render the close button; the component is uncontrolled, so you own the visibility state (typically a `useState` boolean that conditionally renders the Alert). Set `dismissLabel` to customize the screen-reader label, which defaults to "Dismiss".

### Where do AlertActions and AlertContent go in the part tree?

Wrap your title and description in `AlertContent`, and place `AlertActions` as the last child inside `AlertContent` so the button row sits below the description. Keep `AlertIcon` as a sibling of `AlertContent`, not nested inside it.

### Is Alert announced to screen readers?

Yes. The root renders with `role="alert"`, so assistive tech announces the content when it appears. For messages that are not urgent status updates, consider whether a less interruptive pattern is more appropriate.

---

<!-- https://www.koalaui.com/docs/components/avatar.md -->

# Avatar

Represents a user with an image, initials fallback, and optional presence status. Multi-part over Radix Avatar; size and shape flow to every part through Context.

```tsx
<Avatar size="lg">
  <AvatarImage src="/jordi.jpg" alt="Jordi Espinosa" />
  <AvatarFallback>JE</AvatarFallback>
  <AvatarStatus variant="online" />
</Avatar>
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add avatar
```

Manual: run `npm install radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/avatar/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

```tsx title="usage.tsx"
import { Avatar, AvatarImage, AvatarFallback } from "@/components/ui/avatar"

export function Example() {
  return (
    <Avatar>
      <AvatarImage src="/jordi.jpg" alt="Jordi Espinosa" />
      <AvatarFallback>JE</AvatarFallback>
    </Avatar>
  )
}
```

## Sizes

Five fixed sizes, from `xs` (24px) to `xl` (64px). The status dot and fallback text scale with the box.

```tsx
<Avatar size="xs">…</Avatar>
<Avatar size="sm">…</Avatar>
<Avatar size="md">…</Avatar>
<Avatar size="lg">…</Avatar>
<Avatar size="xl">…</Avatar>
```

## Shape

Circular by default; set `shape="square"` for a rounded-square avatar (e.g. organizations).

```tsx
<Avatar shape="circle">…</Avatar>
<Avatar shape="square">…</Avatar>
```

## Fallback

When no image is provided or it fails to load, Radix shows the fallback. Use `delayMs` to avoid a flash while a valid image loads.

```tsx
<Avatar>
  <AvatarImage src="/missing.jpg" alt="Jordi Espinosa" />
  <AvatarFallback delayMs={600}>JE</AvatarFallback>
</Avatar>

<Avatar>
  <AvatarFallback>KO</AvatarFallback>
</Avatar>
```

The fallback adapts to the box. A small avatar (`xs`/`sm`) shows a single initial so the glyph never crowds the silhouette; `md` and up show two. Pass the same two-letter string everywhere and let the size decide, or override per instance with `maxInitials`.

```tsx
{/* one initial on small boxes, two from md up, no per-size string needed */}
<Avatar size="xs"><AvatarFallback>JE</AvatarFallback></Avatar>
<Avatar size="sm"><AvatarFallback>JE</AvatarFallback></Avatar>
<Avatar size="md"><AvatarFallback>JE</AvatarFallback></Avatar>
<Avatar size="lg"><AvatarFallback>JE</AvatarFallback></Avatar>
<Avatar size="xl"><AvatarFallback>JE</AvatarFallback></Avatar>
```

## Color

`color` tints the initials fallback with a soft background and strong text from a single categorical token - the same palette as the [Badge](https://www.koalaui.com/docs/components/badge.md#categorical) hues, so it re-themes across all four themes. Use it to distribute initials across users, teams, or tags. It only paints the fallback; an image, when present, covers it.

```tsx
<Avatar color="brand"><AvatarFallback>JE</AvatarFallback></Avatar>
<Avatar color="purple"><AvatarFallback>MJ</AvatarFallback></Avatar>
<Avatar color="pink"><AvatarFallback>AL</AvatarFallback></Avatar>
<Avatar color="teal"><AvatarFallback>RT</AvatarFallback></Avatar>
<Avatar color="orange"><AvatarFallback>SD</AvatarFallback></Avatar>
```

## Status

`AvatarStatus` adds a presence dot that sits outside the silhouette and reuses the status tokens (online/away/busy/offline).

```tsx
{(["online", "away", "busy", "offline"] as const).map((variant) => (
  <Avatar key={variant} size="lg">
    <AvatarImage src="/jordi.jpg" alt="Jordi" />
    <AvatarFallback>JE</AvatarFallback>
    <AvatarStatus variant={variant} />
  </Avatar>
))}
```

The `position` prop controls which corner the dot occupies - useful when another element (icon, badge) already occupies the default bottom-right corner.

```tsx
<Avatar size="lg">
  <AvatarFallback>JE</AvatarFallback>
  <AvatarStatus variant="online" position="bottom-right" />
</Avatar>

<Avatar size="lg">
  <AvatarFallback>JE</AvatarFallback>
  <AvatarStatus variant="busy" position="top-right" />
</Avatar>
```

## Logo badge

`AvatarBadge` is the same corner overlay as `AvatarStatus`, but it holds a brand or app mark instead of a presence dot. Drop an `<img>` or icon inside and it fits the coin, which carries a `ring-background` gap so it reads off the photo behind it. Use it to tag who someone is on another platform, an org badge, or a verified mark.

```tsx
<Avatar size="lg">
  <AvatarImage src="/jordi.jpg" alt="Jordi Espinosa" />
  <AvatarFallback>JE</AvatarFallback>
  <AvatarBadge>
    <img src="https://cdn.simpleicons.org/figma" alt="Figma" />
  </AvatarBadge>
</Avatar>
```

The coin's `shape` is its own, independent of the avatar: keep the round coin or set `shape="square"` for the classic app-icon look.

```tsx
<Avatar size="lg">
  <AvatarImage src="/jordi.jpg" alt="Jordi Espinosa" />
  <AvatarFallback>JE</AvatarFallback>
  <AvatarBadge shape="circle">
    <img src="https://cdn.simpleicons.org/dropbox" alt="Dropbox" />
  </AvatarBadge>
</Avatar>

<Avatar size="lg">
  <AvatarImage src="/jordi.jpg" alt="Jordi Espinosa" />
  <AvatarFallback>JE</AvatarFallback>
  <AvatarBadge shape="square">
    <img src="https://cdn.simpleicons.org/dropbox" alt="Dropbox" />
  </AvatarBadge>
</Avatar>
```

It scales with the avatar and takes the same `position` prop as the status dot, so you can move it off the default `bottom-right` corner.

```tsx
<Avatar size="xl">
  <AvatarImage src="/jordi.jpg" alt="Jordi Espinosa" />
  <AvatarFallback>JE</AvatarFallback>
  <AvatarBadge position="top-right">
    <img src="https://cdn.simpleicons.org/spotify" alt="Spotify" />
  </AvatarBadge>
</Avatar>
```

## Stack

`AvatarGroup` stacks collaborators into one cluster. It owns the overlap, the `ring-background` separation, and the hover lift, so the children stay plain `Avatar`s with no per-instance ring or z-index. Cap the visible count with `max` and the rest collapse into a `+N` chip; pass `total` when the real count exceeds the avatars you render. Match the group's `size` to its children; the overlap tightens as the box grows.

```tsx
<AvatarGroup size="md" max={4} total={9}>
  {team.map(({ img, name }) => (
    <Tooltip key={img} content={name}>
      <Avatar size="md">
        <AvatarImage src={`/avatars/${img}.jpg`} alt={name} />
        <AvatarFallback>{initials(name)}</AvatarFallback>
      </Avatar>
    </Tooltip>
  ))}
</AvatarGroup>
```

Reach for `renderOverflow` to swap the default chip for a richer affordance, like a `Tooltip` that names the people the stack hides. See the full API on the [Avatar Group](https://www.koalaui.com/docs/components/avatar-group.md) page.

## Examples

Common patterns where avatars appear in product UI - combined with other components.

```tsx
<div className="flex w-64 flex-col items-center gap-4 text-center">
  <Avatar size="xl">
    <AvatarImage src="/jordi.jpg" alt="Jordi Espinosa" />
    <AvatarFallback>JE</AvatarFallback>
    <AvatarStatus variant="online" />
  </Avatar>
  <div className="space-y-1">
    <p className="font-semibold leading-none">Jordi Espinosa</p>
    <p className="text-sm text-muted-foreground">Product Designer</p>
  </div>
  <Badge variant="info" size="sm" dot>Admin</Badge>
  <div className="flex w-full gap-2">
    <Button size="sm" className="flex-1">Follow</Button>
    <Button size="sm" variant="outline" className="flex-1">Message</Button>
  </div>
</div>
```

```tsx
<div className="w-80">
  <div className="flex items-center justify-between">
    <h3 className="font-semibold">Team members</h3>
    <Button size="sm" variant="ghost" className="-mr-2">Invite</Button>
  </div>
  <List variant="plain" className="mt-2 border-t border-border">
    {members.map((m) => (
      <ListItem key={m.name}>
        <ListItemMedia>
          <Avatar size="sm">
            <AvatarImage src={m.src} alt={m.name} />
            <AvatarFallback>{initials(m.name)}</AvatarFallback>
            <AvatarStatus variant={m.status} />
          </Avatar>
        </ListItemMedia>
        <ListItemContent>
          <ListItemTitle>{m.name}</ListItemTitle>
          <ListItemDescription>{m.email}</ListItemDescription>
        </ListItemContent>
        <ListItemMeta>
          <Badge variant={roleVariant[m.role]} size="sm" dot>{m.role}</Badge>
          <DropdownMenu>…</DropdownMenu>
        </ListItemMeta>
      </ListItem>
    ))}
  </List>
</div>
```

```tsx
<ActivityFeed>
  {comments.map((c) => (
    <ActivityItem key={c.name}>
      <ActivityMarker>
        <Avatar size="sm">
          <AvatarImage src={c.src} alt={c.name} />
          <AvatarFallback>{initials(c.name)}</AvatarFallback>
        </Avatar>
      </ActivityMarker>
      <ActivityContent>
        <ActivityHeader>
          <ActivityActor>{c.name}</ActivityActor>
          <ActivityTime dateTime={c.dateTime}>{c.time}</ActivityTime>
        </ActivityHeader>
        <ActivityBody>{c.text}</ActivityBody>
        <div className="-ml-2.5 mt-1 flex gap-0.5">
          <Button variant="ghost" size="sm"><Heart />Like</Button>
          <Button variant="ghost" size="sm"><ChatCircle />Reply</Button>
        </div>
      </ActivityContent>
    </ActivityItem>
  ))}
</ActivityFeed>
```

## FAQ

### Why does AvatarFallback sometimes show one initial and sometimes two?

The fallback reads the resolved `size` from context and caps initials to fit the box: `xs` and `sm` show one initial so the glyph never crowds the silhouette, while `md` and up show two. Pass the same two-letter string everywhere and let size decide, or override per instance with `maxInitials`.

### How does the fallback know when to replace the image?

Avatar is built on Radix Avatar, which tracks image load state and swaps in `AvatarFallback` when no image is set or it fails to load. Use the `delayMs` prop on the fallback to avoid a flash of initials while a valid image is still loading.

### How do I put a brand or app logo on an avatar?

Add an `AvatarBadge` as a child and drop an `<img>` (or icon) inside it. It is the same corner overlay as `AvatarStatus`, a `background` coin with a `ring-background` gap, but big enough to hold a mark, and it fits whatever you put in it. It scales with the avatar `size` and takes the same `position` prop (`bottom-right` by default, plus the other three corners). Its own `shape` is independent of the avatar: keep the round coin or set `shape="square"` for an app-icon look. Use it to tag the platform someone is on, an org badge, or a verified mark.

### What does the color prop tint, and when should I use it?

color tints only the initials fallback with a soft background and strong text (`brand`, `purple`, `pink`, `teal`, `orange`, or neutral `default`), using the same categorical palette as Badge so it re-themes across all four themes. An image, when present, covers it, so use color to distinguish users or teams that fall back to initials.

### How do I move the presence dot off the bottom-right corner?

Set the `position` prop on `AvatarStatus` to `top-right`, `bottom-left`, or `top-left`. This is useful when another element already occupies the default `bottom-right` corner. The `variant` prop (`online`, `away`, `busy`, `offline`) sets the dot color from the status tokens.

### How do size and shape reach AvatarImage, AvatarFallback, and AvatarStatus?

Set `size` and `shape` once on the `Avatar` root and they flow to every part through React Context, so you never repeat them on the children. The shape lives on the root and the image and fallback inherit it via `rounded-[inherit]`, which is what lets the status dot sit outside the silhouette.

### How do I build an overlapping avatar stack?

Wrap the avatars in `AvatarGroup`. It owns the overlap, the `ring-background` separation, and the hover lift, so the children stay plain `Avatar`s. Cap the visible count with `max` and the rest collapse into a `+N` chip; pass `total` when more people exist than you render, and `renderOverflow` to replace the chip with a Tooltip that names them. Set the group's `size` to match the children.

---

<!-- https://www.koalaui.com/docs/components/avatar-group.md -->

# Avatar Group

An overlapping stack of avatars with built-in overflow. Cap how many show and the rest fold into a +N chip. The group owns the overlap, the ring separation and the hover lift; the children stay plain Avatars.

```tsx
<AvatarGroup size="md" max={4} total={9}>
  {team.map(({ img, name }) => (
    <Tooltip key={img} content={name}>
      <Avatar size="md">
        <AvatarImage src={`/avatars/${img}.jpg`} alt={name} />
        <AvatarFallback>{initials(name)}</AvatarFallback>
      </Avatar>
    </Tooltip>
  ))}
</AvatarGroup>
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add avatar-group
```

Manual: run `npm install radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/avatar-group/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

Wrap your [Avatar](https://www.koalaui.com/docs/components/avatar.md) children in `AvatarGroup` and set `max`. The group owns only the layout and the overflow chip: the avatars stay plain `Avatar`s with no per-instance ring or z-index. Match the group's `size` to its children.

```tsx title="team.tsx"
import { AvatarGroup } from "@/components/ui/avatar-group"
import { Avatar, AvatarImage, AvatarFallback } from "@/components/ui/avatar"

export function Team({ members }: { members: Member[] }) {
  return (
    <AvatarGroup size="md" max={4} total={members.length}>
      {members.slice(0, 4).map((m) => (
        <Avatar key={m.id} size="md">
          <AvatarImage src={m.avatar} alt={m.name} />
          <AvatarFallback>{m.initials}</AvatarFallback>
        </Avatar>
      ))}
    </AvatarGroup>
  )
}
```

## Sizes

Set `size` on the group to match the avatars; it sizes the `+N` chip and tightens the overlap as the box grows, so the stack stays a single cluster at every size.

```tsx
<AvatarGroup size="sm" max={4} total={9}>{avatars}</AvatarGroup>
<AvatarGroup size="md" max={4} total={9}>{avatars}</AvatarGroup>
<AvatarGroup size="lg" max={4} total={9}>{avatars}</AvatarGroup>
```

## Fallbacks

With no image the avatar shows its initials. Inside a group, give each fallback a `color` so the stack reads as distinct people instead of a row of identical gray chips: pass one of the Avatar `color` hues per child and stride-mix them so no two neighbours share a tint. The neutral gray default is fine for a lone avatar, not for a cluster. The `+N` chip stays neutral since it's a count, not initials.

```tsx
<AvatarGroup size="md">
  {team.map(({ name, color }) => (
    <Tooltip key={name} content={name}>
      <Avatar size="md" color={color}>
        <AvatarFallback>{initials(name)}</AvatarFallback>
      </Avatar>
    </Tooltip>
  ))}
</AvatarGroup>
```

## Overflow

`max` caps the avatars shown; everything past it collapses into a single `+N` chip. Pass `total` when more people exist than you render (e.g. a server count) so the chip reflects the real number. Omit `max` to show every avatar.

```tsx
// max caps the inline avatars; total counts everyone, even those not rendered.
<AvatarGroup max={2} total={9}>{avatars}</AvatarGroup>
<AvatarGroup max={3} total={9}>{avatars}</AvatarGroup>
<AvatarGroup total={9}>{avatars}</AvatarGroup> {/* no max: show all */}
```

## Custom overflow

Take over the chip with `renderOverflow`, which receives the overflow count. Return any node: here the chip is a [Tooltip](https://www.koalaui.com/docs/components/tooltip.md) that names the people the stack hides, riding the same shared bubble as the avatars.

```tsx
<AvatarGroup
  size="md"
  max={4}
  total={9}
  renderOverflow={(overflow) => (
    <Tooltip content={<NamesList names={hidden} />}>
      <Avatar size="md" tabIndex={0}>
        <AvatarFallback maxInitials={4} className="tabular-nums">
          {`+${overflow}`}
        </AvatarFallback>
      </Avatar>
    </Tooltip>
  )}
>
  {avatars}
</AvatarGroup>
```

## API reference

### AvatarGroup

A `<div>` that lays out its `Avatar` children as an overlapping stack and appends the overflow chip. Its children sit inside a `TooltipGroup`, so every `Tooltip` in the stack shares one gliding bubble. Forwards all native div props; `className` is merged last.

- `size` — `xs | sm | md | lg | xl` (default `md`). Sizes the chip and the overlap; pass the same value you set on the children.
- `max` — cap the visible avatars; the rest fold into the `+N` chip.
- `total` — the real count when it exceeds the rendered avatars, so `+N` reflects it.
- `renderOverflow` — `(overflow: number) => ReactNode`; replace the default chip with a custom affordance.

## FAQ

### When should I reach for AvatarGroup instead of laying out Avatars myself?

Use AvatarGroup whenever you stack collaborators: it owns the overlap, the `ring-background` separation, and the hover lift, and adds a `+N` overflow chip via `max`. Hand-rolling those classes on each Avatar drifts the moment the recipe changes, which is exactly what this component prevents.

### Does AvatarGroup style my avatars for me?

It adds the ring, overlap, and hover lift to each child through descendant utilities, so you don't repeat `ring-2 ring-background` per Avatar. The avatars keep their own `size`, `shape`, `color`, image, and fallback. Only the default `+N` chip is rendered by the group.

### What is the difference between max and total?

`max` caps how many avatars render inline. `total` tells the chip how many people exist overall, even ones you never render, so `+N` can read `+614` while you only show four avatars. Use `total` for server counts; without it the chip just counts the hidden children.

### How do I name each person on hover?

Wrap each Avatar in a Tooltip. Tooltip clones its trigger and portals the bubble out, so the Avatar stays the direct child of the group and the overlap and ring still apply. For the hidden people, pass `renderOverflow` and put the names in a single Tooltip on the chip.

### Why does one tooltip slide across the stack instead of each avatar opening its own?

AvatarGroup wraps its children in a `TooltipGroup` (a Tippy singleton, no extra DOM), the same way Toolbar does. Every Tooltip in the stack, the overflow chip's included, registers with it, so one bubble glides from face to face as the pointer crosses the cluster. Because the bubble is shared, per-tooltip `variant`, `delay`, `offset`, `interactive` and `open` are ignored inside the group.

### Why is the size prop on the group as well as the avatars?

The group needs a size to render the `+N` chip and to pick the overlap amount, since it can't read the children's individual sizes. Pass the same `size` to both so the chip matches the avatars and the overlap looks right.

---

<!-- https://www.koalaui.com/docs/components/badge.md -->

# Badge

A compact label for status, counts, and categories. Single-element like Button; status variants are soft tints derived from semantic tokens, so they re-theme everywhere.

```tsx
<Badge variant="success" dot pill>Online</Badge>
<Badge variant="purple" pill><Lightning /> Beta</Badge>
<Badge variant="info" pill>v2.4.0</Badge>
<Badge variant="outline"><GitBranch /> main</Badge>
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add badge
```

Manual: run `npm install radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/badge/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

```tsx title="usage.tsx"
import { Badge } from "@/components/ui/badge"

export function Example() {
  return <Badge>New</Badge>
}
```

## Playground

The whole control set is derived from the component’s recipe: change a tone or add a size and this follows on its own. Note that dismissal isn’t a flag but a handler, so the trailing button exists exactly when `onRemove` does.

## Variants

```tsx
<Badge variant="default">Default</Badge>
<Badge variant="primary">Primary</Badge>
<Badge variant="secondary">Secondary</Badge>
<Badge variant="outline">Outline</Badge>
```

## Status

Soft status variants pair a tinted background (the status hue at `/10`) with a darker text counterpart and no border, so the fill carries the color while the label stays legible. Both derive from one semantic token (`--success`, `--warning`, `--info`), so they re-theme across all four themes.

```tsx
<Badge variant="success"><CheckCircle weight="fill" /> Approved</Badge>
<Badge variant="success"><Confetti /> Merged</Badge>
<Badge variant="info"><GitPullRequest /> In review</Badge>
<Badge variant="warning"><Clock weight="fill" /> Pending</Badge>
<Badge variant="destructive"><X /> Failed</Badge>
<Badge variant="secondary"><Spinner aria-hidden /> Running</Badge>
<Badge variant="default"><Minus /> Skipped</Badge>
```

## Categorical

Four extra hues for labeling categories, feature flags, and tags. All follow the same soft-tint pattern and re-theme across all four themes.

```tsx
<Badge variant="purple"><Lightning /> Beta</Badge>
<Badge variant="purple"><Rocket /> New</Badge>
<Badge variant="pink"><Star /> Featured</Badge>
<Badge variant="pink"><Tag /> Design</Badge>
<Badge variant="teal">Engineering</Badge>
<Badge variant="teal">Frontend</Badge>
<Badge variant="orange">Deprecated</Badge>
<Badge variant="orange"><Package /> v1 Legacy</Badge>
```

## With dot

The `dot` prop adds a leading status dot in the variant color - ideal for presence and at-a-glance state. The background is stripped so only the dot carries the color.

```tsx
<Badge variant="success" dot>Online</Badge>
<Badge variant="warning" dot>Away</Badge>
<Badge variant="destructive" dot>Busy</Badge>
<Badge variant="default" dot>Offline</Badge>
<Badge variant="info" dot>In a call</Badge>
<Badge variant="purple" dot>Focused</Badge>
<Badge variant="teal" dot>On break</Badge>
<Badge variant="pink" dot>Do not disturb</Badge>
```

## Toggling the dot

Drive `dot` from state and the change animates: the dot grows in and pushes the label over, the tint gives way to the hairline, and the label settles on foreground. Turning it off plays the same thing in reverse, back to the tinted badge. A badge that never passes `dot` renders no dot at all.

```tsx
const [live, setLive] = useState(true)

<Badge variant="success" dot={live}>Online</Badge>
<Switch checked={live} onCheckedChange={setLive} />
```

## Sizes

```tsx
<Badge variant="success" size="sm" dot>Online</Badge>
<Badge variant="success" size="md" dot>Online</Badge>
<Badge variant="success" size="lg" dot>Online</Badge>
<Badge variant="info" size="sm" pill>v2.4.0</Badge>
<Badge variant="info" size="md" pill>v2.4.0</Badge>
<Badge variant="info" size="lg" pill>v2.4.0</Badge>
```

## Pill

Set `pill` for fully rounded edges - pairs well with dot and icon badges.

```tsx
<Badge pill>Default</Badge>
<Badge variant="success" pill dot>Online</Badge>
<Badge variant="purple" pill><Lightning /> Beta</Badge>
<Badge variant="info" pill>v2.4.0</Badge>
```

## With icon

```tsx
<Badge variant="success"><Check /> Verified</Badge>
<Badge variant="purple"><Lightning /> Beta</Badge>
<Badge variant="orange"><Rocket /> New</Badge>
<Badge variant="info"><Star /> Featured</Badge>
<Badge variant="outline"><Lock /> Private</Badge>
<Badge variant="outline"><GitBranch /> feature/auth</Badge>
```

## Dismissible

Pass `onRemove` to render a trailing dismiss button. Give each a descriptive `removeLabel` for screen readers.

```tsx
<Badge
  variant="secondary"
  pill
  onRemove={() => remove(tag)}
  removeLabel={`Remove ${tag}`}
>
  {tag}
</Badge>
```

## As child

Use `asChild` to render the badge styles on another element - e.g. a link - via Radix Slot.

```tsx
<Badge asChild variant="info">
  <a href="/changelog">What's new</a>
</Badge>
```

## FAQ

### When should I use a Badge instead of a Button?

A Badge labels: it states status, a count, or a category and is not meant to be clicked. A Button performs an action. If a user is expected to interact, reach for Button (or a chip with an explicit control). The exception is asChild, which lets the badge styling wrap a link.

### What's the difference between the dot and the soft status variants?

Both read from the same semantic token. The soft variant tints a background plus text; adding the dot prop strips the background so only a small colored dot carries the state, ideal for presence indicators and dense lists where a full tinted pill would be too heavy.

### Why does `dot={false}` render differently from leaving dot out?

Passing dot as a boolean, false included, tells the badge its dot can change, so it keeps a collapsed dot slot mounted and flipping the prop animates both ways. The collapsed slot has no width and cancels the flex gap, so an off badge measures exactly like a plain one. Leave dot out entirely on badges that never change and they render no slot.

### How do I make a dismissible tag?

Pass an onRemove handler to render a trailing dismiss button, and always give a descriptive removeLabel (e.g. `Remove Design`) so screen readers announce what is being removed. pill pairs well with removable tags.

### Can I put a Badge inside a link or another element?

Yes: set asChild and pass a single child element (an <a>, for instance). The badge renders its styles onto that element via Radix Slot instead of emitting its own <span>, so you keep valid markup.

### Will the colors adapt to dark and the other themes?

Yes. Every variant, including the categorical hues, derives from semantic tokens, so badges re-theme automatically across light, dark, cream, and moonlight. Avoid hard-coding a palette color if you want that behavior.

---

<!-- https://www.koalaui.com/docs/components/badge-group.md -->

# Badge Group

A cluster of badges with built-in overflow. Cap how many show inline and the rest fold into a +N chip that reveals the full list in a tooltip, so a long set of tags never blows out its row.

```tsx
<BadgeGroup max={3}>
  {skills.map((skill) => (
    <Badge key={skill} variant="secondary" size="sm">
      {skill}
    </Badge>
  ))}
</BadgeGroup>
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add badge-group
```

Manual: run `npm install radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/badge-group/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

Wrap your [Badge](https://www.koalaui.com/docs/components/badge.md) children in `BadgeGroup` and set `max`. The group owns only the layout and the overflow affordance: the badges stay plain `Badge`s, styled however you like. The reveal rides the shared [Tooltip](https://www.koalaui.com/docs/components/tooltip.md).

```tsx title="skills.tsx"
import { BadgeGroup } from "@/components/ui/badge-group"
import { Badge } from "@/components/ui/badge"

export function Skills({ skills }: { skills: string[] }) {
  return (
    <BadgeGroup max={3}>
      {skills.map((skill) => (
        <Badge key={skill} variant="secondary" size="sm">
          {skill}
        </Badge>
      ))}
    </BadgeGroup>
  )
}
```

## Overflow

`max` caps the badges shown inline; everything past it collapses into a single `+N` chip. Hover or focus the chip to reveal the whole list in a tooltip. Omit `max` to show every badge.

```tsx
// max caps the inline badges; the rest fold into a tooltipped "+N".
<BadgeGroup max={2}>{badges}</BadgeGroup>
<BadgeGroup max={4}>{badges}</BadgeGroup>
<BadgeGroup>{badges}</BadgeGroup> {/* no max: show all */}
```

## Wrap

Without a cap, set `wrap` to let a long set flow onto multiple lines instead of staying on one. Constrain the width and the badges wrap to fit.

```tsx
<BadgeGroup wrap className="max-w-xs">
  {skills.map((skill) => (
    <Badge key={skill} variant="outline" size="sm">
      <Tag /> {skill}
    </Badge>
  ))}
</BadgeGroup>
```

## Overflow chip

The `+N` chip defaults to a small `outline` badge. Match it to the badges it stands in for with `overflowVariant` and `overflowSize`.

```tsx
<BadgeGroup max={2} overflowVariant="secondary">
  {badges /* secondary, sm */}
</BadgeGroup>

<BadgeGroup max={2} overflowVariant="purple" overflowSize="md">
  {badges /* purple, md */}
</BadgeGroup>
```

## Interactive overflow

When the badges carry links or a dismiss button, pass `interactive` so the tooltip stays open while the pointer moves into it, so you can click the contents. Here each tag is dismissible; remove a few and the `+N` recounts.

```tsx
<BadgeGroup max={3} interactive overflowVariant="secondary">
  {tags.map((tag) => (
    <Badge
      key={tag}
      variant="secondary"
      size="sm"
      pill
      onRemove={() => remove(tag)}
      removeLabel={`Remove ${tag}`}
    >
      {tag}
    </Badge>
  ))}
</BadgeGroup>
```

## Custom overflow

Take over the tooltip body with `renderOverflow`, which receives the full list and the hidden slice. Return any node: a titled section, a grid, a different layout for just the hidden badges.

```tsx
<BadgeGroup
  max={3}
  renderOverflow={(all, hidden) => (
    <div className="flex flex-col gap-1.5 p-1 text-left">
      <span className="text-xs font-medium text-muted-foreground">
        {hidden.length} more skills
      </span>
      <div className="grid grid-cols-2 gap-1">{hidden}</div>
    </div>
  )}
>
  {badges}
</BadgeGroup>
```

## FAQ

### When should I reach for BadgeGroup instead of just laying out Badges myself?

Use BadgeGroup when a tag set can overflow its row and you want a clean cap: set `max` and the extras fold into a single `+N` chip that reveals the full list on hover or focus. If you just want a plain row that never overflows, a flex container of `Badge`s is enough.

### Does BadgeGroup style my badges for me?

No. It owns only the layout and the overflow affordance, so your children stay plain `Badge`s with whatever `variant`, `size`, or `pill` you give them. Only the `+N` chip is styled by the group, via `overflowVariant` and `overflowSize`.

### What is the difference between max and wrap?

`max` caps how many badges show inline and collapses the rest into the `+N` chip, keeping everything on one line. `wrap` instead lets the full set flow onto multiple lines. You can combine them: `wrap` with a `max` still hard-caps the count.

### How do I make the overflow chip match my badges?

The chip defaults to a small `outline` badge. Set `overflowVariant` and `overflowSize` to mirror the badges it stands in for, for example `overflowVariant="secondary"` with `overflowSize="md"`.

### My hidden badges have links or remove buttons but the tooltip closes before I can click them. What gives?

Pass `interactive` so the reveal tooltip stays open while the pointer moves into it, letting you click links or dismiss buttons inside. The chip is also focusable with `tabIndex={0}`, so the list is reachable by keyboard, and removing badges makes the `+N` count recompute.

### Can I customize what the tooltip shows instead of the default stacked list?

Yes. Pass `renderOverflow`, which receives the full `items` array and the `hidden` slice and returns any node, so you can show only the hidden badges, a titled section, or a grid layout.

---

<!-- https://www.koalaui.com/docs/components/breadcrumb.md -->

# Breadcrumb

Shows the user's location within a site hierarchy. A multi-part navigation landmark built from semantic HTML with no shared state between parts.

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

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add breadcrumb
```

Manual: run `npm install radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/breadcrumb/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

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

export function Example() {
  return (
    <Breadcrumb>
      <BreadcrumbList>
        <BreadcrumbItem>
          <BreadcrumbLink href="/">Home</BreadcrumbLink>
        </BreadcrumbItem>
        <BreadcrumbSeparator />
        <BreadcrumbItem>
          <BreadcrumbPage>Dashboard</BreadcrumbPage>
        </BreadcrumbItem>
      </BreadcrumbList>
    </Breadcrumb>
  )
}
```

## Custom separator

Pass any content to `BreadcrumbSeparator` to replace the default caret - a text slash, a custom icon, or any node.

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

## Collapsed

Use `BreadcrumbEllipsis` inside a `BreadcrumbItem` to indicate hidden ancestors - a static indicator. To let users open the collapsed segments, swap it for the [dropdown](#dropdown) below.

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

## Dropdown

Make the collapsed segment interactive: drop a [DropdownMenu](https://www.koalaui.com/docs/components/dropdown-menu.md) into the `BreadcrumbItem` so the ellipsis opens a menu of the hidden ancestors - full keyboard navigation and focus management come from the underlying Radix primitive. The dots sit in a container that reveals its surface on hover and while open, so the collapsed crumb reads as a tappable control, with a 40px tap target.

```tsx
import { DotsThree } from "@phosphor-icons/react"
import {
  DropdownMenu, DropdownMenuTrigger, DropdownMenuContent, DropdownMenuItem,
} from "@/components/ui/dropdown-menu"

<BreadcrumbItem>
  <DropdownMenu>
    <DropdownMenuTrigger aria-label="Show more pages" className="...ellipsis + hit area">
      <DotsThree weight="bold" className="size-4" />
    </DropdownMenuTrigger>
    <DropdownMenuContent align="start">
      <DropdownMenuItem asChild>
        <a href="#">Documentation</a>
      </DropdownMenuItem>
      {/* …more items */}
    </DropdownMenuContent>
  </DropdownMenu>
</BreadcrumbItem>
```

## Sibling navigation

Turn the current crumb into the trigger: its label plus a caret that rotates on open, dropping a menu of sibling pages so users can jump sideways without going back up.

```tsx
<BreadcrumbItem>
  <DropdownMenu>
    <DropdownMenuTrigger className="group flex items-center gap-1 font-medium text-foreground …">
      Breadcrumb
      <CaretDown className="size-3.5 caret-turn-fast group-data-[state=open]:rotate-180" />
    </DropdownMenuTrigger>
    <DropdownMenuContent align="start">
      <DropdownMenuItem asChild><a href="#">Avatar</a></DropdownMenuItem>
      {/* …more siblings */}
    </DropdownMenuContent>
  </DropdownMenu>
</BreadcrumbItem>
```

## Grouped menu

Compose the menu’s parts inside a breadcrumb - a `DropdownMenuLabel`, a `DropdownMenuSeparator`, and items that lead with an icon (auto-sized to `size-4`).

```tsx
<DropdownMenuContent align="start">
  <DropdownMenuLabel>Jump to</DropdownMenuLabel>
  <DropdownMenuItem asChild>
    <a href="#"><House /> Home</a>
  </DropdownMenuItem>
  <DropdownMenuItem asChild>
    <a href="#"><Folder /> Documentation</a>
  </DropdownMenuItem>
  <DropdownMenuSeparator />
  <DropdownMenuItem asChild>
    <a href="#"><FileText /> Components</a>
  </DropdownMenuItem>
</DropdownMenuContent>
```

## With icon

Lead a crumb with an icon - keep it inline with the label and sized to the text (`size-4`) so the row stays on one baseline.

```tsx
<BreadcrumbLink href="#" className="inline-flex items-center gap-1.5">
  <House className="size-4" /> Home
</BreadcrumbLink>
```

## As child

Use `asChild` on `BreadcrumbLink` to merge its styles onto a different element - e.g. a Next.js `Link` - via [Radix Slot](https://www.radix-ui.com/primitives/docs/utilities/slot), with no extra wrapper.

```tsx title="with-link.tsx"
import Link from "next/link"
import {
  Breadcrumb, BreadcrumbList, BreadcrumbItem,
  BreadcrumbLink, BreadcrumbSeparator, BreadcrumbPage,
} from "@/components/ui/breadcrumb"

export function Example() {
  return (
    <Breadcrumb>
      <BreadcrumbList>
        <BreadcrumbItem>
          <BreadcrumbLink asChild>
            <Link href="/">Home</Link>
          </BreadcrumbLink>
        </BreadcrumbItem>
        <BreadcrumbSeparator />
        <BreadcrumbItem>
          <BreadcrumbPage>Dashboard</BreadcrumbPage>
        </BreadcrumbItem>
      </BreadcrumbList>
    </Breadcrumb>
  )
}
```

## FAQ

### What is the difference between BreadcrumbLink and BreadcrumbPage?

`BreadcrumbLink` renders an `<a>` for ancestor crumbs the user can navigate to. `BreadcrumbPage` renders a non-link `<span>` with `aria-current="page"` for the current location, so it should be the last crumb and is not clickable.

### How do I wire this up with a Next.js Link?

Set `asChild` on `BreadcrumbLink` and pass a `<Link>` as the only child. Radix Slot merges the crumb styles onto your link with no extra wrapper, so routing stays with Next.js.

### How do I change the separator between crumbs?

Pass any content as children to `BreadcrumbSeparator` and it replaces the default `CaretRight` icon, for example `<BreadcrumbSeparator>/</BreadcrumbSeparator>`. The separator is an `aria-hidden` `<li>`, so it stays out of the accessibility tree.

### When should I use BreadcrumbEllipsis versus a dropdown?

Use `BreadcrumbEllipsis` as a static indicator that ancestors are hidden when there is nowhere to take the user. If the collapsed segment should be openable, drop a `DropdownMenu` into the `BreadcrumbItem` instead, which adds keyboard navigation and focus management from the underlying Radix primitive.

### Why is the breadcrumb a nav and do I need to label it?

`Breadcrumb` renders a `<nav>` with `aria-label="breadcrumb"` built in, so it is announced as a navigation landmark with no extra wiring. The structure is plain semantic HTML, an `<ol>` from `BreadcrumbList` with `<li>` items, so there is no shared state between parts.

### The links look short but feel easy to tap. How is the hit area handled?

`BreadcrumbLink` and `BreadcrumbEllipsis` keep a tight visual footprint but extend their tap target to about 40px with an inert `before` pseudo-element, so small crumbs stay comfortable to click without changing the layout.

---

<!-- https://www.koalaui.com/docs/components/button.md -->

# Button

Triggers an action or event. The reference single-element component: one tv recipe, Radix Slot for asChild, semantic tokens only.

```tsx
<Button>
  <Plus /> New project
</Button>
<Button variant="outline">Cancel</Button>
<Button variant="ghost">Learn more</Button>
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add button
```

Manual: run `npm install radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/button/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

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

export function Example() {
  return <Button>Click me</Button>
}
```

## Playground

Every knob here is a prop, because a Button is one element with nothing to compose. **variant**, **size** and **iconOnly** are read straight off the component’s own recipe, so they can never drift from it.

## Variants

`primary` carries the brand and is the one action a screen leads with. `neutral` is the achromatic solid: an ink fill with the page ground as its label, black on the light themes and near-white on the dark ones. Reach for it when a strong action shares the screen with a brand CTA and must not compete with it ("See all components" under a brand "Buy now"), where `secondary` would be too quiet.

```tsx
<Button variant="primary">Primary</Button>
<Button variant="neutral">Neutral</Button>
<Button variant="secondary">Secondary</Button>
<Button variant="outline">Outline</Button>
<Button variant="ghost">Ghost</Button>
<Button variant="destructive">Destructive</Button>
<Button variant="destructiveGhost">Destructive ghost</Button>
<Button variant="link">Link</Button>
<Button loading>Loading</Button>
```

## On a filled band

A button sitting on a color band or over a photo has the wrong ground: the brand fill of a primary action disappears into a brand band, and `accent` hovers resolve against the page, not the band. `tone` says which ground it is on, and every variant answers for itself.

`onMedia` is a fixed white family, for a brand band, a photo, or a dark scrim. The lead action becomes a white chip and the second stays a white outline, which is how GOV.UK, Spectrum and Tailwind Plus handle a colored band. The chip's label is near-black ink, never the brand color: the band already carries the accent, and black on white clears AA on every accent. `onInverse` is its token-flipping twin, for a `bg-foreground` band: that band inverts with the theme, so the button inverts with it. Both also re-point the focus ring, which is otherwise an invisible brand halo on a brand fill - so reach for the prop rather than a `className`, which would fix the fill and leave the ring broken.

```tsx
<Button tone="onMedia">Get started</Button>
<Button variant="outline" tone="onMedia">Book a demo</Button>
<Button variant="ghost" tone="onMedia">Learn more</Button>
```

```tsx
<Button tone="onInverse">Get started</Button>
<Button variant="outline" tone="onInverse">Talk to sales</Button>
```

## Over a picture

`tone="onMedia"` trusts the ground to be dark or saturated. An action placed straight on a picture can't: a thumbnail's corner button may land on a white frame as easily as on a dark one, and a white ghost glyph vanishes there. `variant="overlay"` brings its own ground, a dark translucent chip with a faint white edge (the same recipe as Badge's `overlay`), so it reads over any frame. Its focus ring is white on a transparent offset, like the on-media tones.

```tsx
<div className="relative aspect-video overflow-hidden rounded-xl">
  <img src={thumbnail} alt="" className="size-full object-cover" />
  <div className="absolute top-2 right-2 flex gap-1">
    <Button variant="overlay" size="sm" iconOnly aria-label="Download">
      <DownloadSimple />
    </Button>
    <Button variant="overlay" size="sm" iconOnly aria-label="Delete">
      <Trash />
    </Button>
  </div>
</div>
```

## Sizes

Three control sizes on a 4px grid - `sm` (32px), `md` (36px, the default), and `lg` (40px). The label stays `text-sm` across them; only height, padding, and the icon gap step up - so a larger button reads as the same control with more presence, not bigger text. Then `xl` (44px), the marketing CTA tier: the one step where the label grows to 16px and a glyph to 20px, because beside a 60-72px display title a 14px label reads as fine print. It is button-only (no form wants a 44px field), and a hero's CTA row imposes it by default.

```tsx
<Button size="sm">Small</Button>
<Button size="md">Medium</Button>
<Button size="lg">Large</Button>
<Button size="xl">Extra large</Button>
```

## Density

Height always comes from `size`, never from density. The default button is `md` (36px) everywhere: a compact dashboard under `DensityProvider` and a comfortable landing render the same unsized button, so the product has one default. A `density` prop on the button itself still picks its default (the two below: comfortable md, compact sm), and a container that imposes a tier (InputGroup, a data-table toolbar, Form, hero actions) keeps its buttons level with the fields beside them. An explicit `size` always wins; a pseudo-element holds `sm` at a hit target of ≥40px. See [Density](https://www.koalaui.com/docs/foundations/density.md).

```tsx
<Button density="comfortable">Comfortable</Button>
<Button density="compact">Compact</Button>
```

## Icons

Icons are composed as children, not props - the recipe sizes any `svg` to `size-4` and a `gap` spaces it from the label. Put the icon before or after the text to place it **left** or **right**. A button carrying an icon trims its horizontal padding one step (`has-[>svg]:px-*`) - an icon reads lighter than a text edge, so this keeps it optically balanced. For an **icon-only** button set `iconOnly` - it collapses to a square at any size - and always pass an `aria-label`, since there is no visible text. Koala warns in development if an `iconOnly` button has no accessible name.

### Left or right: a UX rule

Placement is not decorative. In left-to-right reading the eye lands on the start of the button and leaves at the end, so each side has a different job: a **leading** icon identifies the action, a **trailing** icon signals where it goes.

Leading - identifies the action

Read before the label, the icon says what kind of action this is and doubles as a scannable anchor. The default, and right for actions that operate on something: add, download, delete, search.

Trailing - signals what comes next

Sitting where the eye exits the label, a trailing icon should point onward rather than name the action. Reserve it for forward navigation, disclosure chevrons, and links that leave the page.

Don't - an icon on both sides

Flanking the label with two icons splits the focal point: the leading glyph names the action, the trailing one points elsewhere, and the button reads as two competing ideas. Pick the single side that matches the intent.

One nuance overrides the default: keep the icon on the side that matches its *meaning*. A back-arrow belongs on the left because it points the way the action travels, even though most icons lead. When unsure, lead with the icon.

```tsx
{/* Icon left */}
<Button>
  <Plus /> New project
</Button>

{/* Icon right */}
<Button variant="outline">
  Continue <ArrowRight />
</Button>

{/* No icon */}
<Button variant="secondary">Save</Button>

{/* Icon only */}
<Button iconOnly aria-label="Add">
  <Plus />
</Button>
```

### Attached to the label, not the edge

The icon rides directly beside the label, and the pair centers together as one unit. This matters most on **full-width** buttons - form submits, social sign-in, mobile CTAs - where pinning the icon to the button's edge opens a gap that strands the mark away from the text it belongs to.

Attached - reads as one unit

The mark sits next to the label and the group centers together, so the icon stays glued to the action even when the button stretches full-width.

Don't - pinned to the edge

Anchoring the icon to the far edge while the label centers splits the two apart: a gap opens across the button and the mark looks stranded, disconnected from what it labels.

## Social buttons

`SocialButton` is a sign-in button carrying a real brand logo - the authentic marks, not icon-style approximations. It wraps `Button`, so every size, density, the press scale, loading, and the icon-only tooltip all carry over. Pass a `provider` and it supplies the logo and the default *Continue with…* label.

```tsx
<SocialButton provider="google" />
<SocialButton provider="apple" />
<SocialButton provider="github" />
<SocialButton provider="figma" />
<SocialButton provider="x" />
```

### Solid

`appearance="solid"` fills the button with the provider's official color and flattens the logo to white - for a single dominant choice or a brand-forward row.

```tsx
<SocialButton provider="discord" appearance="solid" />
<SocialButton provider="google" appearance="solid" />
<SocialButton provider="slack" appearance="solid" />
<SocialButton provider="spotify" appearance="solid" />
```

### Icon only

Set `iconOnly` for a square logo button - the provider name becomes the `aria-label` and the hover tooltip. Every supported provider:

```tsx
{SOCIAL_PROVIDER_IDS.map((id) => (
  <SocialButton key={id} provider={id} iconOnly />
))}
```

## Disabled

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

## Loading

`loading` shows a spinner and marks the button busy (`aria-busy`) while an action is in flight. The label is hidden but its space is reserved, so the button never reflows; it's also disabled so it can't be re-triggered. The spinner respects `prefers-reduced-motion`.

```tsx
<Button loading>Saving</Button>
<Button variant="outline" loading>Saving</Button>
<Button loading iconOnly aria-label="Saving" />
```

## Label swap

When a button's label changes with its state - Next → Done, Copy → Copied, Follow → Following - give it a `swapKey` that changes with it. The outgoing label lifts up and out while the new one rises from below, and the button eases between the two label widths instead of snapping to the new one. It respects `prefers-reduced-motion`, where the label simply swaps.

```tsx
<Button swapKey={isLast ? "done" : "next"} onClick={next}>
  {isLast ? "Done" : "Next"}
</Button>

<Button variant="outline" swapKey={copied ? "copied" : "copy"} onClick={copy}>
  {copied ? "Copied" : "Copy"}
</Button>
```

## As child

Use `asChild` to render the button styles on a different element - e.g. a Next.js `Link` - via Radix Slot, with no extra wrapper.

```tsx
<Button asChild>
  <a href="/docs">Documentation</a>
</Button>
```

## FAQ

### Why is variant="destructive" a soft red tint instead of a solid red button?

So the dangerous action is unmistakable without being the loudest thing on the screen. It paints the destructive hue at /10 behind the darker `-strong` label, the same tinted recipe as a destructive Badge or a negative Stat chip, so it reads as a dim maroon pill in the dark themes and a pale pink one on light. Both the rest and hover (/20) steps clear AA against the label in all four themes, and a `primary` CTA beside it still reads as the default choice. Use destructiveGhost for the chrome-less version, a remove-line trash in a list or cart, and a `className` if you genuinely need the solid fill.

### When should I use variant="link" instead of a plain anchor?

Reach for variant="link" when a text action lives inline among other buttons and should share their focus ring and press behavior. For real navigation, pair it with asChild so the styles wrap an actual `<a>` or Next.js Link and the element stays a link.

### Why is every button a pill, and what happens with the radius setting?

The label reads as one object rather than text in a box, and a row of pills stays calm next to rounded cards. The shape comes from `rounded-pill`, which is derived from the global radius knob: it stays fully round at every preset from Small to Full and turns square only at None, so a system set to sharp gets sharp buttons too. An attached ButtonGroup squares the inner seams and keeps the round outer ends.

### What does iconOnly do beyond hiding the label?

It collapses the button to a circle that tracks the active size and zeroes the label padding and gap so the glyph optically centers. It also auto-wraps the button in a Tooltip from your `aria-label`, and Koala warns in development if no accessible name is present.

### How is loading different from disabled?

loading shows a centered spinner, sets `aria-busy`, and disables the button so it cannot be re-triggered, while reserving the label's space so the width never reflows. Plain disabled just greys it out with no spinner or busy state.

### Why does my asChild button ignore the loading prop?

Radix Slot expects a single child, so a sibling spinner would break it. Under asChild the rendered child owns its content, and loading is intentionally a no-op there.

### Why doesn't a compact app shell shrink my buttons?

On purpose. The default button is md (36px) on dashboards and landings alike, so an unsized Button ignores the DensityProvider around it. Where a button has to match smaller fields, its container handles it (InputGroup, a data-table toolbar, ButtonGroup); anywhere else, set size="sm" or density="compact" on the button. A pseudo-element keeps the sm hit target at least 40px.

### Why is the white chip's label black and not the brand color?

The band around it already carries the accent, so a brand-colored label on the chip would only repeat it at a weaker contrast: a brand label on white is exactly as weak as white on the brand fill, 3.6:1 on the default orange. The label is near-black ink instead, which clears AA on white with room to spare in every theme and on every accent, hover included, while the band keeps the raw brand color. This is the pattern GOV.UK, Adobe Spectrum and Tailwind Plus follow: a white lead action on a colored band.

### How do I put a button on a colored band or over a photo?

Pass `tone`. `onMedia` is a fixed white family for a brand fill, a photo, or a dark scrim; `onInverse` is the token-flipping twin for a `bg-foreground` band, which itself inverts with the theme. Each variant answers for itself: the solid action becomes the light shape, the outline keeps its hairline in the band ink, the ghost keeps no chrome. Do not reach for a `className` here - it can fix the fill but leaves the focus ring an invisible brand halo on a brand band, which `tone` re-points for you.

### How do I opt out of the press animation?

Pass the `static` prop, which neutralizes the active:scale press effect for places where the motion would distract.

### Why does swapKey need a key at all - can't the button see its label changed?

Children are new React elements on every render, so a button can't tell an actual state change from a re-render; animating on identity would roll the label constantly. swapKey is the signal that the label now means something different. Change it in step with children (swapKey={copied ? "copied" : "copy"}) and nothing rolls until the state does.

### Is the label swap announced to screen readers?

Only the new label is. The outgoing one is a snapshot that is aria-hidden and dropped as soon as its roll finishes, so the button's accessible name flips straight to the new label with no duplicate text in between.

### How big is the tap target on a phone?

At least 44 by 44px. With a mouse every size meets 40px (sm grows its target with an invisible pseudo-element, so the visual stays 32px); on a touch screen every size grows its target to 44px, the size a fingertip needs. The step keys on the pointer, not the screen width, and it never changes the button's visual size. It comes from `lib/hit-area.ts`, the same constants Switch, Checkbox, Radio and the close buttons use.

---

<!-- https://www.koalaui.com/docs/components/button-group.md -->

# Button Group

A set of related buttons arranged as a visual unit. Supports attached (fused pill) and detached (spaced) layouts, with shared variant, size, and density propagated via context.

```tsx
<ButtonGroup>
  <ButtonGroupItem>Day</ButtonGroupItem>
  <ButtonGroupItem>Week</ButtonGroupItem>
  <ButtonGroupItem>Month</ButtonGroupItem>
</ButtonGroup>

<ButtonGroup size="sm">
  <ButtonGroupItem iconOnly aria-label="Align left">
    <TextAlignLeft />
  </ButtonGroupItem>
  <ButtonGroupItem iconOnly aria-label="Align center">
    <TextAlignCenter />
  </ButtonGroupItem>
  <ButtonGroupItem iconOnly aria-label="Align right">
    <TextAlignRight />
  </ButtonGroupItem>
  <ButtonGroupItem iconOnly aria-label="Justify">
    <TextAlignJustify />
  </ButtonGroupItem>
</ButtonGroup>
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add button-group
```

Manual: run `npm install radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/button-group/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

```tsx title="usage.tsx"
import { ButtonGroup, ButtonGroupItem } from "@/components/ui/button-group"

export function Example() {
  return (
    <ButtonGroup>
      <ButtonGroupItem>Day</ButtonGroupItem>
      <ButtonGroupItem>Week</ButtonGroupItem>
      <ButtonGroupItem>Month</ButtonGroupItem>
    </ButtonGroup>
  )
}
```

## Attached vs Detached

By default, `attached` fuses buttons into a single pill: interior border radii are stripped and every item after the first drops its left border, so neighbours share one 1px stroke instead of stacking two. Set `attached={false}` for a spaced layout where each button keeps its own rounding.

```tsx
{/* Attached (default) */}
<ButtonGroup>
  <ButtonGroupItem>Day</ButtonGroupItem>
  <ButtonGroupItem>Week</ButtonGroupItem>
  <ButtonGroupItem>Month</ButtonGroupItem>
</ButtonGroup>

{/* Detached */}
<ButtonGroup attached={false}>
  <ButtonGroupItem>Day</ButtonGroupItem>
  <ButtonGroupItem>Week</ButtonGroupItem>
  <ButtonGroupItem>Month</ButtonGroupItem>
</ButtonGroup>
```

## Variants

The `variant` prop on `ButtonGroup` is inherited by every `ButtonGroupItem` inside it. Supports all the same variants as [Button](https://www.koalaui.com/docs/components/button.md).

```tsx
<ButtonGroup variant="primary">
  <ButtonGroupItem>One</ButtonGroupItem>
  <ButtonGroupItem>Two</ButtonGroupItem>
  <ButtonGroupItem>Three</ButtonGroupItem>
</ButtonGroup>

<ButtonGroup variant="secondary">
  <ButtonGroupItem>One</ButtonGroupItem>
  <ButtonGroupItem>Two</ButtonGroupItem>
  <ButtonGroupItem>Three</ButtonGroupItem>
</ButtonGroup>

<ButtonGroup variant="outline">
  <ButtonGroupItem>One</ButtonGroupItem>
  <ButtonGroupItem>Two</ButtonGroupItem>
  <ButtonGroupItem>Three</ButtonGroupItem>
</ButtonGroup>

<ButtonGroup variant="ghost">
  <ButtonGroupItem>One</ButtonGroupItem>
  <ButtonGroupItem>Two</ButtonGroupItem>
  <ButtonGroupItem>Three</ButtonGroupItem>
</ButtonGroup>
```

## Sizes

Inherits the same three sizes as Button - `sm` (32px), `md` (36px, the default), and `lg` (40px).

```tsx
<ButtonGroup size="sm">
  <ButtonGroupItem>Small</ButtonGroupItem>
  <ButtonGroupItem>Group</ButtonGroupItem>
</ButtonGroup>

<ButtonGroup size="md">
  <ButtonGroupItem>Medium</ButtonGroupItem>
  <ButtonGroupItem>Group</ButtonGroupItem>
</ButtonGroup>

<ButtonGroup size="lg">
  <ButtonGroupItem>Large</ButtonGroupItem>
  <ButtonGroupItem>Group</ButtonGroupItem>
</ButtonGroup>
```

## Density

`density` tightens the group for application UI - the same axis as Button and the rest of Koala. Set it per-group or for a whole subtree with `DensityProvider`. See [Density](https://www.koalaui.com/docs/foundations/density.md).

```tsx
<ButtonGroup density="comfortable">
  <ButtonGroupItem>Comfortable</ButtonGroupItem>
  <ButtonGroupItem>Group</ButtonGroupItem>
</ButtonGroup>

<ButtonGroup density="compact">
  <ButtonGroupItem>Compact</ButtonGroupItem>
  <ButtonGroupItem>Group</ButtonGroupItem>
</ButtonGroup>
```

## Icon-only

Set `iconOnly` on each item to collapse it to a square. Always pass an `aria-label` - Koala warns in development if one is missing.

```tsx
{/* Alignment toolbar */}
<ButtonGroup size="sm">
  <ButtonGroupItem iconOnly aria-label="Align left">
    <TextAlignLeft />
  </ButtonGroupItem>
  <ButtonGroupItem iconOnly aria-label="Align center">
    <TextAlignCenter />
  </ButtonGroupItem>
  <ButtonGroupItem iconOnly aria-label="Align right">
    <TextAlignRight />
  </ButtonGroupItem>
  <ButtonGroupItem iconOnly aria-label="Justify">
    <TextAlignJustify />
  </ButtonGroupItem>
</ButtonGroup>

{/* Formatting toolbar */}
<ButtonGroup size="sm">
  <ButtonGroupItem iconOnly aria-label="Bold">
    <TextB />
  </ButtonGroupItem>
  <ButtonGroupItem iconOnly aria-label="Italic">
    <TextItalic />
  </ButtonGroupItem>
  <ButtonGroupItem iconOnly aria-label="Underline">
    <TextUnderline />
  </ButtonGroupItem>
</ButtonGroup>
```

## Per-item overrides

Any prop set directly on a `ButtonGroupItem` overrides the group context. Mix variants within the same group to give one action more visual weight - keep all items the same surface style (both bordered, or both filled) so the joined edges look intentional.

```tsx
{/* secondary base + primary confirm - both have a solid fill */}
<ButtonGroup variant="secondary">
  <ButtonGroupItem>Cancel</ButtonGroupItem>
  <ButtonGroupItem variant="primary">Save changes</ButtonGroupItem>
</ButtonGroup>

{/* detached - mixed variants always work when items are separated */}
<ButtonGroup attached={false}>
  <ButtonGroupItem>Discard</ButtonGroupItem>
  <ButtonGroupItem variant="destructive">Delete</ButtonGroupItem>
</ButtonGroup>
```

## FAQ

### When should I use a ButtonGroup instead of separate Buttons?

Use ButtonGroup when several related actions read as one unit, like a Day/Week/Month switch or a formatting toolbar. It shares variant, size, and density across items via context and, when attached, fuses them into a single pill. For unrelated actions, keep them as standalone Buttons.

### What is the difference between attached and detached?

attached (the default) strips interior border radii and drops the left border of every item after the first, so neighbours share one 1px stroke and the items look joined. Set attached={false} for a spaced layout where each item keeps its own rounding.

### How do I set the variant or size for the whole group?

Set variant, size, or density on the ButtonGroup and every ButtonGroupItem inherits it through context. The group defaults to variant="outline" and size="md".

### Can I override one item's variant?

Yes. Any prop on a ButtonGroupItem overrides the group context, for example a primary confirm next to secondary items. In attached mode keep all items the same surface style (both bordered or both filled) so the joined edges look intentional.

### Do icon-only items need anything special?

Set iconOnly on the item to collapse it to a square, and always pass an `aria-label` since there is no visible text. Koala warns in development when an iconOnly item has no accessible name.

### Why does the group lose the press-scale animation?

ButtonGroupItem sets active:scale-100 so adjacent fused items do not visually shift against each other on press. The focus ring and z-index lift on hover and focus still signal the active item.

---

<!-- https://www.koalaui.com/docs/components/card.md -->

# Card

A surface that groups related content. The reference multi-part component: one tv recipe with slots, shared variants flowing to every part through React Context.

```tsx
<Card className="w-full max-w-sm">
  <CardHeader>
    <CardTitle>Upgrade to Pro</CardTitle>
    <CardDescription>Unlock every theme and component.</CardDescription>
  </CardHeader>
  <CardContent className="text-sm text-muted-foreground">
    Billed annually. Cancel anytime from settings.
  </CardContent>
  <CardFooter className="gap-2">
    <Button variant="ghost">Learn more</Button>
    <Button>Upgrade</Button>
  </CardFooter>
</Card>
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add card
```

Manual: run `npm install radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/card/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

```tsx title="usage.tsx"
import {
  Card, CardHeader, CardTitle,
  CardDescription, CardContent, CardFooter,
} from "@/components/ui/card"

export function Example() {
  return (
    <Card>
      <CardHeader>
        <CardTitle>Title</CardTitle>
        <CardDescription>Supporting text.</CardDescription>
      </CardHeader>
      <CardContent>Body content.</CardContent>
      <CardFooter>Footer</CardFooter>
    </Card>
  )
}
```

## Playground

Card is the other shape: two props, and everything else is composition. Turn a **Part** off and a whole element leaves the snippet, rather than a `show`-something prop appearing. Drop them all and the card still holds together.

## Anatomy

```tsx
<Card className="w-full max-w-sm">
  <CardHeader>
    <CardTitle>Upgrade to Pro</CardTitle>
    <CardDescription>Unlock every theme and component.</CardDescription>
    <CardAction>
      <Button size="sm" variant="ghost">Dismiss</Button>
    </CardAction>
  </CardHeader>
  <CardContent className="text-sm text-muted-foreground">
    Billed annually. Cancel anytime from settings.
  </CardContent>
  <CardFooter className="gap-2">
    <Button variant="ghost">Maybe later</Button>
    <Button>Upgrade</Button>
  </CardFooter>
</Card>
```

## Variants

`default` and `outline` sit in the page flow, so they paint no fill: they are contours that take whatever they sit on, the page, a muted band or a dialog. `default` adds a hairline shadow, `outline` is the bare border. `elevated` is the one that floats: it drops the border, leans on shadow, and is the only variant with a fill.

```tsx
<Card variant="default">…</Card>
<Card variant="outline">…</Card>
<Card variant="elevated">…</Card>
```

## Density

`density` flows from the root through context to every part’s padding and the title scale. `compact` is the Koala default (16px padding & gaps, 1rem title); `comfortable` is the spacious alternative for marketing layouts. Set it per-card or for a whole subtree with `DensityProvider` - see [Density](https://www.koalaui.com/docs/foundations/density.md).

```tsx
<Card>…</Card>
<Card density="comfortable">…</Card>
```

## Media

`CardMedia` holds a photo, video or screenshot inset from the card’s edges, never bled to them. The inset is 8px on every side, tighter than the copy’s padding, so the picture reads as framed. Its radius is concentric with the card’s: 20px outside, minus 8px of inset, is 12px inside. Badges laid over the picture anchor to the frame, not the card. The frame is `aspect-video` by default; pass another ratio in `className`.

```tsx
<Card variant="elevated" className="w-full max-w-xs">
  <CardMedia>
    <img src="…" alt="A living room with a green sofa and warm light" />
    <Badge variant="overlay" pill className="absolute top-3 left-3">
      Best seller
    </Badge>
  </CardMedia>
  <CardHeader>
    <CardTitle>Interior kit</CardTitle>
    <CardDescription>48 rooms, 6 moods, every one editable.</CardDescription>
  </CardHeader>
  <CardFooter>
    <Button className="w-full">View kit</Button>
  </CardFooter>
</Card>

<Card className="w-full max-w-xs" density="comfortable">
  <CardHeader>
    <CardTitle>Mountain retreat</CardTitle>
    <CardDescription>Media can close the card too.</CardDescription>
  </CardHeader>
  <CardMedia className="aspect-[4/3]">
    <img src="…" alt="Sunlit valley between green mountains" />
  </CardMedia>
</Card>
```

## Interactive

When the whole card is the way in (a task on a board, a template in a gallery, a customer in a grid), render it as the link or the button itself: pass `asChild` around an `<a>` or a `<button>`, and `interactive` to add the pointer, a hover and a focus ring. The hover follows the variant: `default` lifts and strengthens its edge, `outline` strengthens its edge with a whisper of lift, `elevated` rises further. The edge matters on the dark themes, where a shadow alone barely reads. Only the box-shadow moves, and nothing scales under the press. Keep other controls out of an interactive card: a link or button nested in another is invalid, so a card with its own actions stays a plain card with a link in its title.

```tsx
<Card asChild interactive>
  <a href="/tasks/redirect-map">
    <CardHeader>
      <CardTitle>Redirect map</CardTitle>
      <CardDescription>Point every legacy URL at its new page.</CardDescription>
    </CardHeader>
  </a>
</Card>

<Card asChild interactive variant="outline">…</Card>
<Card asChild interactive variant="elevated">…</Card>
```

## Action on a narrow card

A wide action (a period switch, a select) leaves the title a sliver of room on a phone-width card. Pass `wrap="narrow"` on `CardAction` and it drops under the title and description once the card header is narrower than 24rem, then returns to the top-right when there is room. It is measured on the header with a container query, so it follows the card, not the viewport: a narrow card on a wide screen wraps too, and a wide card on a tablet does not. It is opt-in because an icon button reads best beside the title at any width. Both cards below hold the same header.

```tsx
<Card className="w-full max-w-xs">
  <CardHeader>
    <CardTitle>Income vs expenses</CardTitle>
    <CardDescription>Net of refunds, in USD.</CardDescription>
    <CardAction wrap="narrow">
      <ToggleGroup type="single" variant="segmented" size="sm" defaultValue="30d" aria-label="Period">
        <ToggleGroupItem value="7d">7d</ToggleGroupItem>
        <ToggleGroupItem value="30d">30d</ToggleGroupItem>
        <ToggleGroupItem value="12m">12m</ToggleGroupItem>
      </ToggleGroup>
    </CardAction>
  </CardHeader>
  <CardContent className="text-2xl font-semibold tabular-nums">$48,200</CardContent>
</Card>

<Card className="w-full max-w-md">…the same header…</Card>
```

## FAQ

### Why are the parts named exports instead of Card.Header?

Namespaced statics like Card.Header do not survive the React Server Components server to client boundary, so Koala exports each part by name. Import and compose them as `<Card><CardHeader>` and so on.

### How do I put an action in the top-right of the header?

Wrap it in CardAction inside CardHeader. The header is a grid that switches to two columns when it detects a card-action, so the action sits top-right and the title and description stay optically aligned.

### How do I move the action under the title on a phone?

Pass wrap="narrow" on CardAction. Once the card header is under 24rem the action drops below the title and description, flush left; wider, it goes back to the top-right. The header measures itself with a container query, so the switch follows the card's width, not the screen's. The card then takes its width from the layout (a grid track, w-full or a max-w), not from its header's content.

### Can I truncate the description to one line?

Yes. Put a truncate class on CardDescription. Its pretty wrapping is only a zero-specificity default, so truncate, whitespace-nowrap or line-clamp on the description win without any extra class.

### When should I use variant="elevated" over the default?

Use elevated when the card should float above the page: it drops the border, leans on a larger shadow, and is the only variant that paints a fill. Default and outline are for cards that sit in the page flow: they keep their border and take the background they sit on. Default adds a hairline shadow; outline is the bare border.

### Why does only elevated have a background?

Koala treats a fill as elevation. In the light theme the card token and the page background are the same white, so a filled card in the page flow looks exactly like an empty one. In dark and moonlight the card token sits above the page, so the same card would turn into a grey slab nobody designed. The fill is kept where something really rises, like elevated cards and overlays, because on near-black a shadow barely reads and the lighter surface is what shows the depth.

### Can I put form controls inside a card?

Yes. Inputs, Selects and the other surface-aware controls paint the surface their container declares. Default and outline declare none, so the controls take whatever is behind the card, the same as the card itself. Elevated declares the card surface, so its controls blend with its fill.

### Why does my Card render tighter than I expected?

Card defaults to density="compact" (16px padding and gaps, 1rem title), unlike most marketing surfaces. Pass density="comfortable" on the card, or wrap a subtree in DensityProvider, for the more spacious layout.

### How does density reach every part?

The root computes the tv slots once from the resolved density and shares them through React Context, so CardHeader, CardContent, and CardFooter all read the same padding and the title scales with it. There is no prop drilling or child cloning.

### Why doesn't the image in CardMedia touch the card's edges?

Koala insets media: the picture sits 8px in from the card on every side, with a radius concentric to the card's (20px outside, 12px inside). Framed like that it reads as part of the card instead of a band cut across it, and the copy below keeps its own, wider padding. It is the house rule for any card that carries a picture.

### Can I render the card as a different element, like a link?

Yes. Pass asChild on Card to render its styles onto your own element via Radix Slot, with no extra wrapper. If the whole card is the link or the button, add interactive too: it brings the pointer, a hover that follows the variant and a focus ring.

---

<!-- https://www.koalaui.com/docs/components/carousel.md -->

# Carousel

A horizontal slide viewer with a clickable indicator. The track translates between full-width slides, arrow keys step it, and the indicator ships with a closed set of forms: dots, lines, fraction, thumbnails.

```tsx
<Carousel label="Product highlights">
  <CarouselContent>
    <CarouselSlide>{/* slide one */}</CarouselSlide>
    <CarouselSlide>{/* slide two */}</CarouselSlide>
    <CarouselSlide>{/* slide three */}</CarouselSlide>
  </CarouselContent>
  <CarouselIndicators />
</Carousel>
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add carousel
```

Manual: run `npm install radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/carousel/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

```tsx title="usage.tsx"
import {
  Carousel, CarouselContent, CarouselSlide, CarouselIndicators,
} from "@/components/ui/carousel"

export function Example() {
  return (
    <Carousel label="Product highlights">
      <CarouselContent>
        <CarouselSlide>{/* … */}</CarouselSlide>
        <CarouselSlide>{/* … */}</CarouselSlide>
      </CarouselContent>
      <CarouselIndicators />
    </Carousel>
  )
}
```

## Indicator variants

The indicator ships as one component with a closed set of forms, picked with the `variant` prop. Never hand-roll a new indicator per carousel: pick the form that fits the surface.

- `dots` (default): pill-morphing bullets, for most cards and testimonials.
- `lines`: thin fixed-width ticks, a quieter alternative to dots.
- `fraction`: a contained 2 / 5 readout for dense image galleries; the active number rolls like an odometer, and the pill grows smoothly by one digit-width when the count crosses a boundary (99 / 100).
- `thumbnails`: one slide preview per slide; pass a `thumbnails` node array indexed to the slides. A single brand ring glides from tile to tile rather than toggling per preview.
- `tabs`: one text label per slide; pass a `labels` array indexed to the slides. A single underline glides to the active tab rather than toggling per label.
- `numbers`: a numbered chip per slide; the active one fills like a numbered pager. Good for short, countable sets.
- `progress`: a single continuous bar that fills with position (25% on slide 1 of 4). A readout, not per-slide clickable; navigate with arrows, drag, or the arrow keys.

```tsx
{/* one component, pick the form with `variant` */}
<CarouselIndicators variant="dots" />
<CarouselIndicators variant="lines" />
<CarouselIndicators variant="fraction" />
<CarouselIndicators
  variant="thumbnails"
  thumbnails={slides.map((s) => <img key={s.id} src={s.thumb} alt="" />)}
/>
<CarouselIndicators variant="tabs" labels={["Photo", "Stats", "Map", "Camera"]} />
<CarouselIndicators variant="numbers" />
<CarouselIndicators variant="progress" />
```

## Contained

Pass `contained` to seat `dots`, `lines` or `progress` in a pill, the same one `fraction` wears. In the flow it is a muted fill; with `overlay` it turns dark and frosted so the white dots hold on any photo.

```tsx
<CarouselIndicators contained />
<CarouselIndicators variant="lines" contained />
<CarouselIndicators variant="progress" contained />

{/* over the image */}
<CarouselIndicators contained overlay align="center" />
```

## Over a hero

Positioning is orthogonal to the form: any variant composes with `overlay` (float over the image, white treatment) and `align` (`end` bottom-right or `center` bottom-centered). Full-bleed heroes usually want centered overlay dots.

```tsx
{/* centered white dots */}
<CarouselIndicators overlay align="center" />
```

## On images / cards

For photo galleries, add `CarouselPrevious` / `CarouselNext`: overlay arrows that reveal on hover (and on keyboard focus), and stay hidden at the first/last slide. Pass `overlay` to `CarouselIndicators` to float the dots over the bottom-right of the image; over photos they switch to fixed white so they stay legible on any background.

```tsx
<Carousel label="Photo gallery">
  <CarouselContent>
    <CarouselSlide><img … /></CarouselSlide>
    <CarouselSlide><img … /></CarouselSlide>
  </CarouselContent>
  <CarouselPrevious />
  <CarouselNext />
  <CarouselIndicators overlay />
</Carousel>
```

## Product gallery

`thumbnailSize` sets the thumbnail tile: `sm` (the default, 56×40) suits landscape photos, `lg` is a 64px square for product packshots, where a landscape crop would cut the object in half. The gliding ring resizes with the tiles. This is the gallery on the ecommerce product pages.

```tsx
<Carousel label="Everyday Backpack photos">
  <CarouselContent>
    {photos.map((photo) => (
      <CarouselSlide key={photo.src}>
        <div className="relative aspect-square">
          <img src={photo.src} alt={photo.alt} draggable={false} className="size-full object-cover" />
        </div>
      </CarouselSlide>
    ))}
  </CarouselContent>
  <CarouselPrevious />
  <CarouselNext />
  <CarouselIndicators
    variant="thumbnails"
    thumbnailSize="lg"
    thumbnails={photos.map((photo) => <img key={photo.src} src={photo.thumb} alt="" />)}
  />
</Carousel>
```

## Controlled

Pass `index` and `onIndexChange` to drive the active slide from your own state, e.g. to pair the dots with external prev/next buttons or a step counter. Omit them for uncontrolled use with `defaultIndex`.

```tsx
const [index, setIndex] = useState(0)

<Carousel index={index} onIndexChange={setIndex}>
  <CarouselContent>{/* slides */}</CarouselContent>
  <CarouselIndicators />
</Carousel>
<Button onClick={() => setIndex((i) => i - 1)}>Previous</Button>
<Button onClick={() => setIndex((i) => i + 1)}>Next</Button>
```

## FAQ

### When should I use Carousel instead of Pagination?

Carousel is a slide viewer: it translates a track between full-width slides with clickable indicator dots. Pagination is the page toolbar on the data table. If you are paging through tabular records rather than swiping through panels, reach for Pagination.

### How do I add the hover arrows for an image gallery?

Drop CarouselPrevious and CarouselNext inside the Carousel. They are overlay arrows that reveal on hover and on keyboard focus, and stay hidden at the first and last slide.

### What indicator forms are there, and do I create a new component for each?

No, never hand-roll a new indicator. CarouselIndicators is one component with a closed set of forms picked via the variant prop: dots (default), lines, fraction (a contained 2 / 5 readout), and thumbnails (one slide preview per slide, passed via the thumbnails prop). Positioning with overlay and align composes with every form, and contained seats dots, lines or progress in a pill.

### What does the overlay prop on CarouselIndicators do?

It floats the indicator over the image instead of below it, and switches it to a fixed white treatment so it stays legible on any photo background. Use align to place overlay indicators bottom-right (end) or bottom-centered (center).

### Should I control the active slide?

Pass index and onIndexChange to drive it from your own state, for example to pair the dots with external prev/next buttons or a step counter. Omit them for uncontrolled use with defaultIndex.

### Is the carousel keyboard and screen-reader accessible?

Yes. The region exposes aria-roledescription="carousel" with your label, ArrowLeft and ArrowRight step the active slide while it is focused, and each dot is a button with an aria-label from dotLabel plus aria-current on the active one.

### Can I disable swipe and customize the dot labels?

Pass draggable={false} on CarouselContent to turn off pointer and touch swiping, and pass a dotLabel function to CarouselIndicators to build each dot's accessible label, for example by slide title.

---

<!-- https://www.koalaui.com/docs/components/checkbox.md -->

# Checkbox

A control for a binary or tri-state choice, built on Radix Checkbox. Supports the indeterminate state a “select all” needs. It's the same control the DataTable uses for row selection.

```tsx
<label htmlFor="terms" className="flex items-center gap-2.5">
  <Checkbox id="terms" defaultChecked />
  Accept terms and conditions
</label>
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add checkbox
```

Manual: run `npm install radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/checkbox/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

```tsx title="usage.tsx"
import { Checkbox } from "@/components/ui/checkbox"

export function Example() {
  return (
    <label htmlFor="terms" className="flex items-center gap-2.5">
      <Checkbox id="terms" defaultChecked />
      Accept terms and conditions
    </label>
  )
}
```

## States

Checked and indeterminate both fill with the accent (brand) color; indeterminate shows a minus rather than a check. Drive the tri-state by passing `checked="indeterminate"`.

```tsx
<Checkbox checked={false} />
<Checkbox checked />
<Checkbox checked="indeterminate" />
<Checkbox disabled />
<Checkbox disabled checked />
```

## Sizes

`sm` (16px) sits inside dense tables; `md` (20px) is the default for forms. The indicator scales with the box.

```tsx
<Checkbox size="sm" defaultChecked />
<Checkbox size="md" defaultChecked />
```

## With a label

Checkbox renders only the box; pair it with a `<label htmlFor>` for an accessible name and a larger hit target. With a description, nudge the box to the first line.

```tsx
<div className="flex items-start gap-3">
  <Checkbox id="notify" defaultChecked className="mt-0.5" />
  <label htmlFor="notify" className="flex flex-col gap-0.5">
    <span className="text-sm font-medium">Email notifications</span>
    <span className="text-sm text-muted-foreground">
      Get notified when someone mentions you.
    </span>
  </label>
</div>
```

## Select all (indeterminate)

A parent checkbox reads `true` when all children are checked, `"indeterminate"` on a partial selection, and `false` when none are. The same pattern the [DataTable](https://www.koalaui.com/docs/components/data-table.md) header uses.

```tsx
const ITEMS = ["Engineering", "Design", "Marketing"]
const [checked, setChecked] = useState({ Design: true })

const selected = ITEMS.filter((i) => checked[i])
const allChecked = selected.length === ITEMS.length
const someChecked = selected.length > 0 && !allChecked

<Checkbox
  checked={allChecked ? true : someChecked ? "indeterminate" : false}
  onCheckedChange={(v) =>
    setChecked(Object.fromEntries(ITEMS.map((i) => [i, !!v])))
  }
/>
```

## FAQ

### When should I use a Checkbox versus a Switch?

Use a Checkbox for selecting items in a set or accepting terms, especially where a tri-state or select-all is involved. Use a Switch for toggling a single setting on or off that takes effect immediately.

### How do I drive the indeterminate state?

Pass checked="indeterminate" rather than a boolean. It fills with the accent (brand) color like checked but shows a minus instead of a check, which is exactly what a select-all header needs.

### How do I build a select-all parent?

Compute the parent's checked from its children: true when all are checked, "indeterminate" on a partial selection, and false when none are, then fan onCheckedChange out to every child. This is the same pattern the DataTable header uses.

### Why does my Checkbox have no visible label?

Checkbox renders only the box. Pair it with a `<label htmlFor>` for an accessible name and a larger hit target, and with a multi-line description nudge the box to the first line with a small top margin.

### Which size should I pick?

Use size="sm" (16px) inside dense tables and size="md" (20px, the default) for forms. The drawn indicator scales with the box, and the corner radius stays proportional across both sizes.

### Does it support controlled and uncontrolled use?

Yes. It is built on Radix Checkbox, so use defaultChecked for uncontrolled, or checked with onCheckedChange to control it, plus standard props like disabled, name, and value.

---

<!-- https://www.koalaui.com/docs/components/checklist.md -->

# Checklist

The onboarding panel: a card that tracks a short list of setup tasks and their progress. The bar and the 3-of-6 read-out derive from value and total, and the bar turns green the moment every step is done.

```tsx
<Checklist value={2} total={6}>
  <ChecklistHeader>
    <ChecklistTitle>Finish setting up your workspace</ChecklistTitle>
    <ChecklistDescription>
      A few quick steps to get the most out of Koala.
    </ChecklistDescription>
    <ChecklistProgress />
  </ChecklistHeader>

  <ChecklistItems>
    <ChecklistItem status="complete">
      <ChecklistItemContent>
        <ChecklistItemTitle>Create your account</ChecklistItemTitle>
        <ChecklistItemDescription>You're in. Welcome to Koala.</ChecklistItemDescription>
      </ChecklistItemContent>
    </ChecklistItem>

    <ChecklistItem status="active">
      <ChecklistItemContent>
        <ChecklistItemTitle>Invite your team</ChecklistItemTitle>
        <ChecklistItemDescription>Add teammates to collaborate on projects.</ChecklistItemDescription>
      </ChecklistItemContent>
      <ChecklistItemAction>
        <Button size="sm">Invite</Button>
      </ChecklistItemAction>
    </ChecklistItem>

    <ChecklistItem status="todo">
      <ChecklistItemContent>
        <ChecklistItemTitle>Set up billing</ChecklistItemTitle>
        <ChecklistItemDescription>Add a payment method to move to production.</ChecklistItemDescription>
      </ChecklistItemContent>
      <ChecklistItemAction>
        <Button size="sm" variant="outline">Add card</Button>
      </ChecklistItemAction>
    </ChecklistItem>
  </ChecklistItems>
</Checklist>
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add checklist
```

Manual: run `npm install radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/checklist/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

```tsx title="usage.tsx"
import {
  Checklist,
  ChecklistHeader,
  ChecklistTitle,
  ChecklistDescription,
  ChecklistProgress,
  ChecklistItems,
  ChecklistItem,
  ChecklistItemContent,
  ChecklistItemTitle,
  ChecklistItemDescription,
  ChecklistItemAction,
} from "@/components/ui/checklist"

export function Example() {
  return (
    <Checklist value={2} total={6}>
      <ChecklistHeader>
        <ChecklistTitle>Get started</ChecklistTitle>
        <ChecklistProgress />
      </ChecklistHeader>
      <ChecklistItems>
        <ChecklistItem status="complete">
          <ChecklistItemContent>
            <ChecklistItemTitle>Create your account</ChecklistItemTitle>
          </ChecklistItemContent>
        </ChecklistItem>
        {/* …more items */}
      </ChecklistItems>
    </Checklist>
  )
}
```

## Item states

Every `ChecklistItem` carries a `status`, drawn by the one task mark every task list in the kit shares: 16px, centred on the title's first line. A `complete` row fills it with the brand and a tick and de-emphasizes the title; `active` marks the one recommended next step with a brand ring half filled, started but not done, and the primary action; the row stays flat, so the button is what draws the eye. `todo` rows wait quietly with an empty ring and an outline action.

```tsx
<Checklist value={1} total={3}>
  <ChecklistHeader>
    <ChecklistTitle>Getting started</ChecklistTitle>
    <ChecklistProgress />
  </ChecklistHeader>
  <ChecklistItems>
    <ChecklistItem status="complete">
      <ChecklistItemContent>
        <ChecklistItemTitle>Create your account</ChecklistItemTitle>
        <ChecklistItemDescription>You're all set.</ChecklistItemDescription>
      </ChecklistItemContent>
    </ChecklistItem>
    <ChecklistItem status="active">
      <ChecklistItemContent>
        <ChecklistItemTitle>Invite your team</ChecklistItemTitle>
        <ChecklistItemDescription>Add teammates to collaborate.</ChecklistItemDescription>
      </ChecklistItemContent>
      <ChecklistItemAction>
        <Button size="sm">Invite</Button>
      </ChecklistItemAction>
    </ChecklistItem>
    <ChecklistItem status="todo">
      <ChecklistItemContent>
        <ChecklistItemTitle>Set up billing</ChecklistItemTitle>
        <ChecklistItemDescription>Add a payment method to go live.</ChecklistItemDescription>
      </ChecklistItemContent>
      <ChecklistItemAction>
        <Button size="sm" variant="outline">Add card</Button>
      </ChecklistItemAction>
    </ChecklistItem>
  </ChecklistItems>
</Checklist>
```

## Progress & completion

Pass `value` (completed count) and `total` to the root; `ChecklistProgress` derives the bar, the “X of Y” label and the percentage itself. When every step is done the bar eases from brand to success-green and the label swaps to All steps complete.

```tsx
{/* In progress: brand bar, "2 of 4 complete" */}
<Checklist value={2} total={4}>…</Checklist>

{/* Done: green bar, "All steps complete" */}
<Checklist value={4} total={4}>…</Checklist>
```

## Density

Like Card and Dialog, the Checklist reads the density context (or a `density` prop). Density tunes the card and row padding only. The indicator footprint is fixed at both densities, so the left rail lines up identically.

```tsx
<Checklist density="comfortable" value={1} total={2}>…</Checklist>
<Checklist density="compact" value={1} total={2}>…</Checklist>
```

## Tasks the reader ticks

Give a `ChecklistItem` `checked` and `onCheckedChange` (or `defaultChecked` to let it keep its own state) and it becomes a task list: the indicator turns into the task mark, a real checkbox drawn like the small `Checkbox` only round, 16px and centred on the title's first line, with a black tick. It is named by the item's title, the whole row is its hit area, and a ticked title is struck through as it mutes. Leave `value` and `total` off the root and the Checklist counts its own items, so the bar follows every tick with no wiring. A row's `ChecklistItemAction` stays its own target above the hit area.

```tsx
<Checklist>
  <ChecklistHeader>
    <ChecklistTitle>Team tasks</ChecklistTitle>
    <ChecklistDescription>Housekeeping for this week and next.</ChecklistDescription>
    <ChecklistProgress />
  </ChecklistHeader>
  <ChecklistItems>
    <ChecklistItem defaultChecked={true}>
      <ChecklistItemContent>
        <ChecklistItemTitle>Rotate the on-call schedule</ChecklistItemTitle>
        <ChecklistItemDescription>Ana Torres, due Friday</ChecklistItemDescription>
      </ChecklistItemContent>
    </ChecklistItem>
    <ChecklistItem defaultChecked={false}>
      <ChecklistItemContent>
        <ChecklistItemTitle>Archive tickets older than 90 days</ChecklistItemTitle>
        <ChecklistItemDescription>Marc Vidal, due Monday</ChecklistItemDescription>
      </ChecklistItemContent>
    </ChecklistItem>
    <ChecklistItem defaultChecked={false}>
      <ChecklistItemContent>
        <ChecklistItemTitle>Review the refund macro</ChecklistItemTitle>
        <ChecklistItemDescription>Lucia Ramos, due Tuesday</ChecklistItemDescription>
      </ChecklistItemContent>
    </ChecklistItem>
  </ChecklistItems>
</Checklist>

{/* Controlled, from your own task data */}
<ChecklistItem checked={task.done} onCheckedChange={(done) => setDone(task.id, done)}>…</ChecklistItem>
```

## Inside a Card

`variant="plain"` drops the Checklist's own contour and outer padding, so it sits inside a `Card` (or any surface that already frames it) without a frame inside a frame. The Card's header carries the heading; the indicators line up with it, and the row pills bleed into the Card's padding the way List's plain rows do. `ChecklistProgress` can lead the header on its own.

```tsx
<Card className="w-full max-w-sm">
  <CardHeader>
    <CardTitle>Team tasks</CardTitle>
    <CardDescription>Housekeeping for this week and next.</CardDescription>
  </CardHeader>
  <CardContent>
    <Checklist variant="plain" density="compact">
      <ChecklistHeader>
        <ChecklistProgress />
      </ChecklistHeader>
      <ChecklistItems>
        <ChecklistItem defaultChecked={true}>
          <ChecklistItemContent>
            <ChecklistItemTitle>Rotate the on-call schedule</ChecklistItemTitle>
            <ChecklistItemDescription>Ana Torres, due Friday</ChecklistItemDescription>
          </ChecklistItemContent>
        </ChecklistItem>
        <ChecklistItem defaultChecked={false}>
          <ChecklistItemContent>
            <ChecklistItemTitle>Archive tickets older than 90 days</ChecklistItemTitle>
            <ChecklistItemDescription>Marc Vidal, due Monday</ChecklistItemDescription>
          </ChecklistItemContent>
        </ChecklistItem>
        <ChecklistItem defaultChecked={false}>
          <ChecklistItemContent>
            <ChecklistItemTitle>Review the refund macro</ChecklistItemTitle>
            <ChecklistItemDescription>Lucia Ramos, due Tuesday</ChecklistItemDescription>
          </ChecklistItemContent>
        </ChecklistItem>
      </ChecklistItems>
    </Checklist>
  </CardContent>
</Card>
```

## The task mark on its own

`ChecklistMark` draws the same mark without the Checklist around it, for a task list something else lays out: the steps of an `Accordion`, a row that is already a button. An empty ring while the task waits, a brand ring half filled on the `active` step, the brand fill with a tick once it is `complete`: fill only ever means done. It centres itself on a `text-sm` first line, so put it in an `items-start` row. It is decoration, so the row says the state in words.

```tsx
<Accordion type="single" collapsible variant="minimal" defaultValue="team">
  <AccordionItem value="workspace">
    <AccordionTrigger>
      <span className="flex min-w-0 flex-1 items-start gap-3">
        <ChecklistMark status="complete" />
        <span className="text-muted-foreground">Name your workspace</span>
        <span className="sr-only">(done)</span>
      </span>
    </AccordionTrigger>
    <AccordionContent className="pl-7">Pick a name and upload a logo.</AccordionContent>
  </AccordionItem>
  <AccordionItem value="team">
    <AccordionTrigger>
      <span className="flex min-w-0 flex-1 items-start gap-3">
        <ChecklistMark status="active" />
        <span>Invite your teammates</span>
      </span>
    </AccordionTrigger>
    <AccordionContent className="pl-7">Send an email invite or share a link.</AccordionContent>
  </AccordionItem>
  <AccordionItem value="billing">
    <AccordionTrigger>
      <span className="flex min-w-0 flex-1 items-start gap-3">
        <ChecklistMark status="todo" />
        <span>Connect billing</span>
      </span>
    </AccordionTrigger>
    <AccordionContent className="pl-7">Add a card to keep the workspace running.</AccordionContent>
  </AccordionItem>
</Accordion>
```

## API reference

Checklist

The root card. Forwards all `div` props.

- `value?: number`: completed task count. Leave it out and the Checklist counts its complete items.
- `total?: number`: total task count. Leave it out and the Checklist counts its items. Both drive the derived progress (clamped so a bad count can't overrun the bar).
- `variant?: "card" | "plain"`: the panel contour, or none for a Checklist inside a Card. @default `"card"`
- `density?: "comfortable" | "compact"`: padding tier; defaults from the density context.
- `asChild?: boolean`: render as a child element via Radix Slot.

ChecklistProgress

The labeled `role="progressbar"` bar. Reads progress from context. Pass `label` to override the default “X of Y complete” text.

ChecklistItem

- `status?: "todo" | "active" | "complete"`: the task state. On a row the reader ticks, `checked` decides `complete`. @default `"todo"`
- `checked?: boolean`, `defaultChecked?: boolean`, `onCheckedChange?: (checked: boolean) => void`: any of them makes the row a task the reader ticks: a Radix checkbox named by `ChecklistItemTitle`, the row as its hit area, `data-state` on the row.

ChecklistMark

The task mark alone, `aria-hidden`, no Checklist needed. Forwards all `span` props.

- `status?: "todo" | "active" | "complete"`: an empty ring, a brand ring half filled, or the brand fill with a tick. @default `"todo"`

ChecklistHeader · ChecklistTitle · ChecklistDescription · ChecklistItems · ChecklistItemContent · ChecklistItemTitle · ChecklistItemDescription · ChecklistItemAction

Structural parts. Each accepts `className` (merged last) and forwards its native element props. `ChecklistTitle` takes `asChild`.

## FAQ

### How is the progress bar calculated?

From the root's value and total. ChecklistProgress derives the percentage, the 'X of Y complete' label and the aria-valuenow itself, so the header and the item statuses can't drift out of sync. Both counts are clamped, so a value greater than total (or a negative) can never overrun the bar or report over 100%.

### Do I have to keep value/total in sync with the item statuses?

No, you can leave them out: the Checklist then counts its own items, a status="complete" row or a checked one as done. Pass them when the progress covers more than the rows on screen (tasks collapsed or paginated out of view), and keep them from the same source of truth as the statuses.

### How do I let people tick tasks off?

Pass checked and onCheckedChange (or defaultChecked) on each ChecklistItem. The indicator becomes a Radix checkbox named by the item's title, clicking anywhere on the row toggles it, Space works from the keyboard, and a ticked title is struck through. Put any other control in ChecklistItemAction, which stays its own target.

### How do I put a Checklist inside a Card?

Use variant="plain". It drops the Checklist's own contour and outer padding, so there is no frame inside the frame: let the Card's header carry the heading and keep ChecklistProgress in a ChecklistHeader of its own.

### What does the active status do?

It marks the one recommended next step: its mark becomes a brand ring half filled, started but not done, and it's the row you'd give the primary (brand) button. The row itself never lights up, so the button is what the eye lands on. Everything still incomplete stays todo with a quieter outline action. Using active is optional; a checklist reads fine with just todo and complete.

### Can each task have its own icon?

No, on purpose. Every task list in the kit draws the same mark, the same size and colours whether its rows tick or only show a status, so a done task reads the same in an onboarding card, a team's to-do list or an Accordion of steps. An icon per task would put a second picture in that slot and make done harder to scan. Let the title name the task.

### Is it accessible?

The bar is a named role=progressbar with valuemin/max/now and a valuetext of 'X of Y complete'. Each status item carries a data-status plus an sr-only label (Not started / In progress / Completed) so the state is announced, not only colored; its mark is aria-hidden decoration. On a row the reader ticks, the indicator is a real checkbox named by the title, which announces its own state.

### Will it adapt to dark and the other themes?

Yes. Every color is a semantic token, brand, success, muted, border, card, so the panel, the task marks and the green completion bar re-theme across light, dark, cream, and moonlight automatically.

---

<!-- https://www.koalaui.com/docs/components/code-snippet.md -->

# Code Snippet

A polished code block: rounded surface, optional window chrome, copy-on-hover, line numbers and token-driven highlighting. The highlighter is a small, dependency-free tokenizer for TS/TSX, shell and CSS.

```tsx title="call-to-action.tsx"
import { Button } from "@/components/ui/button"
import { ArrowRight } from "@phosphor-icons/react"

export function CallToAction() {
  // The label is the affordance; the icon just clarifies it.
  return (
    <Button>
      Get started
      <ArrowRight className="size-4" />
    </Button>
  )
}
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add code-snippet
```

Manual: run `npm install radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/code-snippet/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

```tsx title="usage.tsx"
import { CodeSnippet } from "@/components/ui/code-snippet"

export function Example() {
  return <CodeSnippet lang="tsx" code={`const x = 1`} />
}
```

## Languages

Set `lang` to switch grammars. TS/TSX, shell (`bash`/`sh`), and CSS are highlighted; the language chip in the header reflects the choice.

```bash title="install.sh"
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add a component (its dependencies come along)
npx koalaui-cli@latest add button
```

```css title="globals.css"
:root {
  --radius: 1rem;
  --primary: oklch(0.62 0.19 256);
  --syntax-keyword: oklch(0.5 0.2 295);
}

.dark {
  --primary: oklch(0.7 0.16 256);
}
```

## Window chrome

A `filename` adds the header with a language chip; `dots` adds macOS-style window dots. With either, the snippet wears the inset look: the header sits on a tinted frame and the code is a sheet set 8px into it, its corners concentric with the frame's. Omit both for a chromeless block.

```tsx title="button.tsx"
export function Button() {
  return <button className="btn">Click me</button>
}
```

```tsx
export function Button() {
  return <button className="btn">Click me</button>
}
```

When the snippet is already a sheet inside another frame (a preview's Code tab), a second frame would double the chrome. Pass `inset={false}` and the header becomes a strip across the one surface instead.

```tsx title="button.tsx"
export function Button() {
  return <button className="btn">Click me</button>
}
```

## Terminal sessions

In a shell snippet, start a line with `$` and it reads as a session: the prompt dims, each line without one is the command's output, in muted ink with a leading ✓ kept green. The copy button copies only the commands, without their prompt, so what lands on the clipboard runs as pasted.

```bash title="Terminal"
$ npx koalaui-cli@latest add button
✓ wrote components/ui/button/button.tsx
✓ wrote components/ui/button/index.ts
✓ added button
```

## Line numbers

Set `showLineNumbers` to render a tabular-nums gutter, useful for longer listings or when referencing a specific line.

```tsx title="tokenize.ts"
export function tokenize(code: string) {
  const tokens = []
  for (const line of code.split("\n")) {
    tokens.push(line.trim())
  }
  return tokens
}
```

## Diff

Show a change in context. `startLine` numbers the gutter from the excerpt's real position in the file, and `diff` marks lines as added or removed by that same number. A marked line takes a soft success or destructive band across the code plus a bar in the gutter, so the mark never rests on color alone, and a screen reader hears “Added” or “Removed” before it. The copy button still copies the plain `code` string.

```ts title="auth/reset.ts"
export function buildResetLink(userId: string) {
  const token = signResetToken({ uid: userId })

  const baseUrl = "https://staging.example.com"
  const baseUrl = "https://example.com"

  const url = new URL("/reset-password", baseUrl)
  url.searchParams.set("token", token)
  return url.toString()
}
```

## Collapsible

Long listings get noisy. Set `collapsible` to clamp the block to `collapsedHeight` (320px by default): the last lines dissolve into a bottom fade and a *Show more* toggle expands it to full height, animated. The toggle only appears once the content actually overflows the clamp, measured from the DOM, so short blocks are left untouched.

```tsx title="members-table.tsx"
import * as React from "react"

import { tv } from "@/lib/tv"
import { Button } from "@/components/ui/button"

type Member = {
  id: string
  name: string
  email: string
  status: "Active" | "Invited" | "Suspended"
  balance: number
}

const columns: ColumnDef<Member>[] = [
  {
    accessorKey: "name",
    header: "Member",
    cell: ({ row }) => (
      <TableCellText primary={row.original.name} secondary={row.original.email} />
    ),
  },
  {
    accessorKey: "status",
    header: "Status",
    cell: ({ getValue }) => <Badge size="sm">{getValue<string>()}</Badge>,
  },
  {
    accessorKey: "balance",
    header: "Balance",
    meta: { numeric: true },
    cell: ({ getValue }) => `$${getValue<number>()}`,
  },
]

export function MembersTable({ data }: { data: Member[] }) {
  return <DataTable columns={columns} data={data} />
}
```

## Density

Like other Koala surfaces, Code Snippet honors `density`. `compact` (the default) suits dense app UI; `comfortable` opens up the padding for docs and marketing. Density retunes spacing only, never radius or color.

```tsx title="comfortable.tsx"
const theme = "moonlight"
```

```tsx title="compact.tsx"
const theme = "moonlight"
```

## API reference

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| code | string | - | The source to render and copy. Required. |
| lang | "tsx" \| "ts" \| "js" \| "css" \| "bash" \| "sh" | "tsx" | Grammar used for highlighting and the header chip. |
| filename | string | - | Filename chip in the header (also enables the header bar). |
| dots | boolean | false | Show macOS-style window dots in the header. |
| inset | boolean | true | With a header, sit it on a tinted frame and set the code 8px into it as a sheet. false turns the header into a strip across one surface. No effect without a header. |
| showLineNumbers | boolean | false | Render a line-number gutter. |
| startLine | number | 1 | First number in the gutter, for an excerpt of a longer file. `diff` uses the same numbering. |
| diff | { added?: number[]; removed?: number[] } | - | Lines to mark as added or removed, by gutter number: a tinted band plus a gutter bar, announced to screen readers. |
| collapsible | boolean | false | Clamp long listings behind a Show more / Show less toggle. The toggle only appears once the content overflows the clamp. |
| collapsedHeight | number | 320 | Clamped height in px when collapsible and collapsed. |
| density | "comfortable" \| "compact" | "compact" | Padding density. Resolves prop > provider > compact. |
| className | string | - | Merged onto the root surface. All other div props forward too. |

## FAQ

### Which languages does the highlighter support?

Set lang to switch grammars: TS/TSX, shell (bash or sh), and CSS are highlighted by a small, dependency-free tokenizer, and the header chip reflects the choice. Other values render as plain text.

### How do I get the window chrome header?

Pass a filename to add the header with a language chip, and add the dots prop for macOS-style window dots. The header sits on a tinted frame with the code inset 8px as a sheet. Omit both for a chromeless block.

### Why does my snippet show a frame inside a frame?

It is already a sheet of another frame, like a preview's Code tab. Pass inset={false} and the header becomes a strip across the one surface instead of a second frame.

### How do I show a command and its output?

Use lang="bash" and start each command line with "$ ". Lines without the prompt read as output in muted ink, and the copy button copies only the commands.

### Will the syntax colors follow my theme?

Yes. Highlighting is driven by syntax tokens (CSS variables), so the code re-themes across all four palettes rather than using fixed colors. Density retunes spacing only, never radius or color.

### How do I add a line-number gutter?

Set showLineNumbers to render a tabular-nums gutter, useful for longer listings or when referencing a specific line.

### Can it show a diff?

Yes. Pass diff with the added and removed line numbers, and startLine when the snippet is an excerpt, so the gutter and the marks use the file's real numbering. Marked lines get a soft green or red band and a gutter bar, and are announced as Added or Removed.

### How do I collapse a long code block?

Set collapsible to clamp the block to collapsedHeight (320px by default). The last lines fade into the surface and a Show more / Show less toggle expands it to full height. The toggle only shows up once the content actually overflows the clamp, so short blocks stay untouched.

### There are two CodeSnippets in Koala. Which import do I use?

For app code use the component at @/components/ui/code-snippet. The @/components/docs/code-snippet import is a docs-site wrapper used by these pages.

### Is there a copy button?

Yes. The block shows a copy-on-hover control that copies the exact code string you pass, so consumers can grab it without selecting text.

---

<!-- https://www.koalaui.com/docs/components/collapsible.md -->

# Collapsible

One region that opens under its trigger: show more, advanced settings, the log behind an error. No chrome of its own, a height tween on the system's motion tokens, and a mark that turns rather than swaps.

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

<Collapsible open={open} onOpenChange={setOpen}>
  <div className="flex items-center justify-between">
    <h4>Attachments 5</h4>
    <CollapsibleTrigger asChild>
      <Button variant="ghost" size="sm" swapKey={open ? "less" : "more"} className="-mr-2.5">
        {open ? "Show less" : "Show 3 more"}
        <CollapsibleIcon />
      </Button>
    </CollapsibleTrigger>
  </div>
  <ul>{/* the first two files */}</ul>
  <CollapsibleContent>
    <ul>{/* the other three */}</ul>
  </CollapsibleContent>
</Collapsible>
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add collapsible
```

Manual: run `npm install radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/collapsible/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

```tsx title="usage.tsx"
import {
  Collapsible,
  CollapsibleTrigger,
  CollapsibleIcon,
  CollapsibleContent,
} from "@/components/ui/collapsible"

export function Example() {
  return (
    <Collapsible>
      <CollapsibleTrigger>
        Advanced settings
        <CollapsibleIcon />
      </CollapsibleTrigger>
      <CollapsibleContent>…</CollapsibleContent>
    </Collapsible>
  )
}
```

## The trigger

On its own, `CollapsibleTrigger` is a quiet text control with the mark beside it, and its target grows to 40px without growing the text. With `asChild` it hands its behavior to your own control and keeps none of its look, which is how the Button above works: the Button stays a Button, and its label rolls while the caret turns.

```tsx
<Collapsible>
  <p>Koala ships every component as source you own…</p>
  <CollapsibleContent>
    <p>Updates keep your edits…</p>
  </CollapsibleContent>
  <CollapsibleTrigger className="mt-3">
    Read more
    <CollapsibleIcon />
  </CollapsibleTrigger>
</Collapsible>
```

## Markers

`CollapsibleIcon` turns with the trigger it sits in, on the same `caret-turn` beat as the height, so the mark and the region move as one gesture. `marker` picks the glyph and its turn: `caret` (the default) flips 180° for a panel below, `branch` turns 90° into a nested list, and `plus` turns 45° into a cross, the same mark Accordion and FAQ rows use.

```tsx
<CollapsibleTrigger>Caret <CollapsibleIcon /></CollapsibleTrigger>
<CollapsibleTrigger><CollapsibleIcon marker="branch" /> Branch</CollapsibleTrigger>
<CollapsibleTrigger>Plus <CollapsibleIcon marker="plus" /></CollapsibleTrigger>
```

## Advanced settings

The fields most people never touch, folded under the ones everyone fills in. Layout goes on `CollapsibleContent`'s `className`: it styles the body, never the wrapper whose height is tweening, so the motion stays smooth.

```tsx
<Collapsible>
  <CollapsibleTrigger>
    <Gear weight="bold" className="size-4 text-muted-foreground" />
    Advanced settings
    <CollapsibleIcon />
  </CollapsibleTrigger>
  <CollapsibleContent className="flex flex-col gap-4 pt-4">
    <Field>
      <FieldLabel>Build command</FieldLabel>
      <InputRoot><InputField defaultValue="npm run build" /></InputRoot>
      <FieldHint>Runs before every deploy.</FieldHint>
    </Field>
    <div className="flex items-center justify-between gap-4">
      <Label htmlFor="preview-deploys">Preview deploys for every branch</Label>
      <Switch id="preview-deploys" defaultChecked />
    </div>
  </CollapsibleContent>
</Collapsible>
```

## Detail on demand

Collapsible paints nothing, so it drops inside other components without a second frame. Here an Alert says what happened, and the log that says why stays folded until someone asks for it.

```tsx
<Alert variant="destructive">
  <AlertIcon />
  <AlertContent>
    <AlertTitle>Build failed</AlertTitle>
    <AlertDescription>The deploy stopped at the type check. Nothing went live.</AlertDescription>
    <Collapsible>
      <CollapsibleTrigger className="mt-2">
        Show build log
        <CollapsibleIcon />
      </CollapsibleTrigger>
      <CollapsibleContent className="pt-3">
        <CodeSnippet lang="bash" code={buildLog} />
      </CollapsibleContent>
    </Collapsible>
  </AlertContent>
</Alert>
```

## Motion

The region's height tweens on the collapsible keyframes, retimed to `duration-base` and `ease-out`, and its body fades in with a 4px drop on the same clock, then out with a plain fade, softer than the way in. Content that renders open is never animated on page load: Radix skips the height, and the root holds the fade back until the state has changed once.

## API reference

### Collapsible

A plain `<div>` with no chrome. Props: `open`, `defaultOpen`, `onOpenChange`, `disabled`, `asChild`, `className`.

### CollapsibleTrigger

A `<button>` carrying `aria-expanded`, `aria-controls` and `data-state`. Styled as a text control unless `asChild` is set, in which case your element keeps its own look.

### CollapsibleIcon

The disclosure mark, decorative. Props: `marker` (`caret` · `branch` · `plus`), `className`, and any SVG attribute. It turns on the state of the trigger it sits in.

### CollapsibleContent

The region, unmounted while closed. Takes every `<div>` prop; `className` styles the body inside the animated wrapper.

## FAQ

### Collapsible or Accordion?

Collapsible for one region that opens on its own. Accordion for a set of rows that share rules, such as only one open at a time, and that should look like a list.

### Where do I put padding and gaps?

On `CollapsibleContent` through `className`: it styles the body, not the wrapper whose height animates. Padding on the animated wrapper would jump at the start and end of the tween.

### Can the trigger open on hover?

No. A region that opens and closes under a moving pointer reads as accidental and does nothing on touch or keyboard. It opens on click, Space and Enter.

### Why doesn't my mark turn?

`CollapsibleIcon` turns on the state of the trigger around it, so it has to be inside `CollapsibleTrigger`, or inside the element you passed to it with `asChild`.

### Is the hidden content still in the page?

No. A closed region is removed once its exit animation ends, so it leaves the tab order and the accessibility tree. Fields inside it unmount with it: if the region can close before the form is sent, keep their values in state or in your form library rather than only in the inputs.

---

<!-- https://www.koalaui.com/docs/components/color-picker.md -->

# Color Picker

A full HSV color picker in one panel: a HEX/HSL/RGB switcher, a draggable saturation square, hue and alpha rails, channel fields, an eyedropper and a preset palette. The rails ride Radix Slider for keyboard and ARIA.

```tsx
const [color, setColor] = useState("#67aa38")

// The panel paints its own card, so it drops straight onto a page.
<ColorPicker value={color} onValueChange={setColor} />
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add color-picker
```

Manual: run `npm install @phosphor-icons/react radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/color-picker/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

The panel paints its own card, so it drops straight onto a page. Pass `value` with `onValueChange` for a controlled hex string, or `defaultValue` to let it own its state.

```tsx title="usage.tsx"
import { ColorPicker } from "@/components/ui/color-picker"

export function Example() {
  const [color, setColor] = useState("#67aa38")
  return <ColorPicker value={color} onValueChange={setColor} />
}
```

## Anatomy

Every piece of the panel is a named export, and the default layout is simply this composition. Pass `children` to write it out yourself: drop a part, reorder it, or wrap it. Nothing here is a `showX` flag that a part depends on.

```tsx
<ColorPicker value={color} onValueChange={setColor}>
  <div className="flex w-full items-center gap-2">
    <ColorPickerFormat />
    <ColorPickerEyeDropper />
  </div>
  <ColorPickerArea />
  <ColorPickerControls />
  <ColorPickerFields />
  <ColorPickerSwatches />
</ColorPicker>
```

## Playground

Flip the knobs to see the panel and its snippet change together.

## Formats

The switcher at the top of the panel chooses how the colour is *written*: one hex box, or three numeric channels for HSL and RGB. It never changes the colour. HSV stays the working model in every format, so cycling HEX → HSL → RGB round-trips losslessly, and `onValueChange` always emits hex. Set the initial format with `defaultFormat`, or drive it with `format` and `onFormatChange`.

```tsx
// The switcher changes how the colour is written, never the colour.
<ColorPicker value={color} onValueChange={setColor} defaultFormat="hex" />
<ColorPicker value={color} onValueChange={setColor} defaultFormat="hsl" />
<ColorPicker value={color} onValueChange={setColor} defaultFormat="rgb" />

// Or drive it:
<ColorPicker format={format} onFormatChange={setFormat} />
```

## Sizes

Two footprints. `md` is the full 324px panel; `sm` is 216px and drops the fields row, which has no room at that width. Passing `density="compact"` picks `sm` as the default size, and `size` always wins over it. Unlike the form controls, the panel does not read an ambient [DensityProvider](https://www.koalaui.com/docs/foundations/density.md): these are fixed panel widths, not height tiers, and inheriting `compact` from an app shell would silently take the fields away.

```tsx
<ColorPicker size="md" defaultValue="#67aa38" />  // 324px, with the fields row
<ColorPicker size="sm" defaultValue="#67aa38" />  // 216px, without it

// density picks the default size; an explicit size still wins.
<ColorPicker density="compact" />  // → sm
```

## Alpha

The transparency rail and its percentage field are on by default. The emitted hex carries the `aa` byte whenever alpha drops below 100%, so a fully opaque colour is still a plain six-digit hex. Pass `showAlpha={false}` for an opaque-only picker.

```tsx
// On by default: emits #rrggbbaa once alpha drops below 100%.
<ColorPicker value={color} onValueChange={setColor} />

// Opaque only:
<ColorPicker showAlpha={false} value={color} onValueChange={setColor} />
```

## Presets

The palette is a labelled section fenced off by a hairline. Pass your own `presets` array, and set `label` on `ColorPickerSwatches` to rename the heading or `null` to drop it. The chosen chip is marked with a ring in its own colour rather than a checkmark, which reads at 24px on light and dark swatches alike.

```tsx
const presets = ["#ef4444", "#f97316", "#eab308", "#84cc16", /* … */]

<ColorPicker value={color} onValueChange={setColor} presets={presets} />

// Drop the heading (and its hairline) with label={null}:
<ColorPicker defaultValue="#3b82f6" showInput={false}>
  <ColorPickerArea />
  <ColorPickerControls />
  <ColorPickerSwatches label={null} className="border-t-0 pt-0" />
</ColorPicker>
```

## Surface

By default the panel is a card: border, radius, elevation, and a `--surface` declaration so the fields and rings inside blend with it. Drop to `surface="plain"` when it already sits in something that draws the frame, such as a [Card](https://www.koalaui.com/docs/components/card.md) or a settings panel, so you never nest one card inside another.

```tsx
// The default: the panel is its own card.
<ColorPicker defaultValue="#67aa38" />

// Inside something that already draws a frame:
<Card>
  <CardHeader><CardTitle>Brand color</CardTitle></CardHeader>
  <CardContent>
    <ColorPicker surface="plain" defaultValue="#7c3aed" />
  </CardContent>
</Card>
```

## Fill modes

Pass `modes` with two or more entries to add a Figma-style fill-type row at the top: a tile per fill kind (Solid, each gradient geometry, Image), each a live preview. The gradient editor gives you a draggable stop track (click to add a stop, drag to move it, Delete to remove) and an angle rail for linear gradients; the image mode takes an upload or a URL with a cover/contain fit. Use `onFillChange` to receive one CSS value across every mode: a hex, a `linear-gradient()`, or a `url()`.

```tsx
const [fill, setFill] = useState("linear-gradient(90deg, #6366f1, #ec4899)")

<ColorPicker
  modes={["solid", "gradient", "image"]}
  defaultMode="gradient"
  defaultValue="#6366f1"
  onFillChange={setFill}
/>

// fill is a hex, a linear-gradient()/radial-gradient(), or a url("…")
```

## In a popover

Wrap a `ColorPickerTriggerSwatch` in `ColorPickerTrigger` for the classic field affordance: a swatch of the current color that opens the panel on click. `ColorPickerContent` only positions and animates: the card you see is the picker's own, so there is exactly one frame either way.

```tsx
const [color, setColor] = useState("#22c55e")

<ColorPickerPopover>
  <ColorPickerTrigger asChild>
    <ColorPickerTriggerSwatch value={color} aria-label="Choose brand color" />
  </ColorPickerTrigger>
  <ColorPickerContent>
    <ColorPicker value={color} onValueChange={setColor} />
  </ColorPickerContent>
</ColorPickerPopover>
```

## Composition

Because the parts are droppable, the same component covers the whole range from a full panel down to a bare swatch grid or a square with two rails. Render only what the task needs; the state, the keyboard handling, and the colour maths come along either way.

```tsx
// Swatches only:
<ColorPicker value={color} onValueChange={setColor} className="w-fit">
  <ColorPickerSwatches presets={presets} label="Brand palette" className="border-t-0 pt-0" />
</ColorPicker>

// Square and rails only:
<ColorPicker defaultValue="#3b82f6" size="sm">
  <ColorPickerArea />
  <ColorPickerControls />
</ColorPicker>
```

## API reference

`ColorPicker` takes `value`, `defaultValue`, `onValueChange`, `size`, `surface`, `density`, `format`, `defaultFormat`, `onFormatChange`, `showAlpha`, `showInput`, `showPresets`, `presets`, and the fill-mode props `modes`, `mode`, `defaultMode`, `onModeChange`, `onFillChange`, `defaultGradient`, `defaultImage`.

The parts are `ColorPickerFormat`, `ColorPickerArea`, `ColorPickerControls` (which composes `ColorPickerHueSlider` and `ColorPickerAlphaSlider`), `ColorPickerFields`, `ColorPickerHexInput`, `ColorPickerEyeDropper`, `ColorPickerPreview`, `ColorPickerSwatches`, `ColorPickerModes`, `ColorPickerGradient`, and `ColorPickerImage`, plus the popover trio `ColorPickerPopover`, `ColorPickerTrigger`, `ColorPickerContent` and the ready-made `ColorPickerTriggerSwatch`. The colour maths is exported too: `hexToHsva`, `hsvaToHex`, `hsvaToRgba`, `rgbaToHsva`, `hsvaToHsla`, `hslaToHsva`, and `gradientToCss`.

## FAQ

### When should I use ColorPicker versus the plain Slider or a swatch grid?

Reach for ColorPicker when a user needs to choose an arbitrary color: it gives you the 2D saturation/brightness square, hue and alpha rails, the HEX/HSL/RGB fields, and an eyedropper. If you only need a fixed set of brand colors, render ColorPickerSwatches on its own with a presets array, and if you just need a 1D value pick a plain Slider instead.

### Does switching between HEX, HSL and RGB change my color?

No. The switcher is a display choice only: the picker keeps HSV as its working model in every format, so the fields are a projection of the same colour. Cycling HEX → HSL → RGB and back round-trips losslessly, and onValueChange always emits a hex string regardless of the active format. Set the starting format with defaultFormat, or control it with format and onFormatChange.

### What is the difference between size and density here?

size is the real knob: "md" is the full 324px panel and "sm" is the 216px one, which drops the fields row because three numeric boxes plus alpha cannot fit at that width. Passing density="compact" picks sm as the default size, and an explicit size always wins. Unlike Button or Input, the panel deliberately does NOT read an ambient DensityProvider: these are fixed panel widths rather than height tiers, so inheriting compact from an app shell would silently remove the fields.

### Why does my picker look like a card inside another card?

The panel paints its own card by default (surface="card"): border, radius, elevation, and a --surface declaration so the nested fields blend with it. If you are dropping it into something that already draws a frame, pass surface="plain". Note ColorPickerContent draws no chrome of its own precisely for this reason, so the popover build needs no change.

### How do I turn on the Solid / Gradient / Image modes?

Pass the `modes` prop with the kinds you want, for example modes={["solid", "gradient", "image"]}. With a single mode (the default) no switcher renders and the picker is the standard panel. With two or more, a Figma-style fill-type row of live-preview tiles appears at the top, one tile per fill kind, with each gradient geometry (linear/radial) getting its own tile so picking it both switches mode and sets the geometry. Control the active mode with `mode`/`defaultMode`/`onModeChange` if you need it, and recompose by hand with ColorPickerModes, ColorPickerGradient, and ColorPickerImage.

### What does the picker emit in gradient and image modes?

Use `onFillChange`, which fires in every mode with a single CSS value you can drop straight into a `background`: a hex in solid mode, a `linear-gradient()`/`radial-gradient()` in gradient mode, and a `url("…")` in image mode. `onValueChange` keeps firing the solid hex for backward compatibility, so existing solid-only code is untouched.

### How does the gradient stop track work?

Click an empty spot on the track to add a stop (it samples the color already showing there), drag a stop to move it, and select one to edit its color with the square, rails, and fields below. With three or more stops, pressing Delete or Backspace on a focused stop removes it; the arrow keys nudge its position (hold Shift for a larger step). The geometry (linear/radial) is set from the fill-type tiles at the top of the panel, and the angle rail sets a linear gradient's direction.

### How do I get a transparent color out of the picker?

The alpha rail and its percentage field are on by default. onValueChange emits an 8-digit hex with the trailing `aa` byte whenever alpha drops below 100%, for example `#a855f7cc`; at full opacity you get a plain six-digit hex. Pass showAlpha={false} to remove the rail entirely.

### Is ColorPicker controlled or uncontrolled?

Both. Pass `value` plus `onValueChange` for a controlled hex string, or pass `defaultValue` (which falls back to `#3b82f6`) and let the picker own its state. Internally it keeps HSV as the source of truth via reconcileHsva, so dragging brightness to black never throws away your hue.

### How do I build the popover swatch field, and which parts compose it?

Wrap a `ColorPickerTriggerSwatch` (pass it the same `value`) inside `ColorPickerTrigger asChild`, then put a `ColorPicker` inside `ColorPickerContent`. ColorPickerPopover, ColorPickerTrigger, and ColorPickerContent are thin Radix Popover wrappers, so the panel portals and animates for free, and the card comes from the picker itself.

### Can keyboard users operate the saturation square?

Yes. The square has role `slider` and is focusable, and the arrow keys nudge saturation and brightness by 1, or by 10 with Shift held. The hue and alpha rails ride on Radix Slider, so they get full keyboard, drag, and ARIA support automatically, and the format switcher, the fill-type tiles, and the image-fit toggle are all ToggleGroups with roving focus, so each row is a single tab stop the arrow keys move within.

### Where did the checkmark on the selected swatch go?

It was replaced by a ring: a gap ring in the panel's own surface with a halo of the swatch colour outside it. A 24px chip had to guess its own contrast to draw a legible checkmark on every possible preset, light or dark; a ring in the chip's own colour reads on all of them and matches the design. The button still carries aria-pressed, so assistive tech is unaffected.

---

<!-- https://www.koalaui.com/docs/components/command.md -->

# Command

A searchable command palette: the Cmd-K menu. Arrows move the highlight, Enter runs the active row, and focus never leaves the input. Built on Radix Dialog; filtering and the roving highlight are hand-rolled.

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

useEffect(() => {
  function onKeyDown(e: KeyboardEvent) {
    if ((e.metaKey || e.ctrlKey) && e.key.toLowerCase() === "k") {
      e.preventDefault()
      setOpen((o) => !o)
    }
  }
  document.addEventListener("keydown", onKeyDown)
  return () => document.removeEventListener("keydown", onKeyDown)
}, [])

// The trigger is a BUTTON that reads as a field, so it follows the DS's field-shaped
// trigger contract (the one Select/MultiSelect/DatePicker share), not the Input recipe:
// --surface fill, shadow-xs, hover border, and the soft brand-ring halo on focus AND
// while the dialog is open. Name scale in the transition or the press would snap.
<button type="button" onClick={() => setOpen(true)} aria-label="Search"
  data-state={open ? "open" : "closed"}
  className="group flex h-9 w-64 cursor-pointer items-center gap-2 rounded-md border border-input
             bg-[var(--surface,var(--background))] px-3 text-left text-sm text-muted-foreground shadow-xs
             transition-[border-color,box-shadow,scale] duration-fast ease-out
             hover:border-ring/50
             outline-none focus-visible:border-brand focus-visible:brand-ring
             data-[state=open]:border-brand data-[state=open]:brand-ring
             active:scale-[0.99]">
  <MagnifyingGlass className="size-4 shrink-0" />
  <span className="flex-1">Search components…</span>
  <span className="ml-4 flex shrink-0 items-center gap-1">
    <Kbd size="sm" variant="ghost">⌘</Kbd>
    <Kbd size="sm" variant="ghost">K</Kbd>
  </span>
</button>

<CommandDialog open={open} onOpenChange={setOpen}>
  <CommandInput placeholder="Type a command or search…" />
  <CommandList>
    <CommandEmpty>No results found.</CommandEmpty>
    <CommandGroup heading="Suggestions">
      <CommandItem value="New file" keywords={["create"]} onSelect={run}>
        <FilePlus /> New file
        <CommandShortcut><Kbd size="sm">⌘</Kbd><Kbd size="sm">N</Kbd></CommandShortcut>
      </CommandItem>
      <CommandItem value="Invite member" onSelect={run}>
        <UserPlus /> Invite member
      </CommandItem>
    </CommandGroup>
    <CommandSeparator />
    <CommandGroup heading="Settings">
      <CommandItem value="Profile" onSelect={run}>
        <User /> Profile
      </CommandItem>
      <CommandItem value="Billing" onSelect={run}>
        <CreditCard /> Billing
      </CommandItem>
    </CommandGroup>
  </CommandList>
</CommandDialog>
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add command
```

Manual: run `npm install radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/command/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

```tsx title="usage.tsx"
import {
  Command,
  CommandInput,
  CommandList,
  CommandEmpty,
  CommandGroup,
  CommandItem,
} from "@/components/ui/command"

export function Example() {
  return (
    <Command label="Quick actions">
      <CommandInput placeholder="Search actions…" />
      <CommandList>
        <CommandEmpty>No results found.</CommandEmpty>
        <CommandGroup heading="Create">
          <CommandItem value="New project" onSelect={() => create()}>
            New project
          </CommandItem>
        </CommandGroup>
      </CommandList>
    </Command>
  )
}
```

Each `CommandItem` has a required `value` (its searchable identity) and an optional `keywords` array for synonyms. A row that doesn't match the query removes itself, so empty groups and the `CommandEmpty` state collapse on their own.

## Inline

Skip `CommandDialog` and use `Command` directly to embed the palette in a page or a Popover. It brings its own surface, so it reads as a finished card on any background. Disabled rows stay visible but drop out of the keyboard order.

```tsx
<Command label="Quick actions">
  <CommandInput placeholder="Search actions…" />
  <CommandList>
    <CommandEmpty>Nothing matches that.</CommandEmpty>
    <CommandGroup heading="Create">
      <CommandItem value="New project"><Plus /> New project</CommandItem>
      <CommandItem value="Invite teammate"><UserPlus /> Invite teammate</CommandItem>
    </CommandGroup>
    <CommandGroup heading="Navigate">
      <CommandItem value="Dashboard"><ChartBar /> Dashboard</CommandItem>
      <CommandItem value="Account"><User /> Account</CommandItem>
      <CommandItem value="Support" disabled><Lifebuoy /> Support (offline)</CommandItem>
    </CommandGroup>
  </CommandList>
</Command>
```

## Keyboard

The search field keeps focus while you navigate (the active row is announced through `aria-activedescendant`): `↑` / `↓` move the highlight (wrapping at the ends), `Home` / `End` jump to the first and last rows, `Enter` runs the active row, and (inside `CommandDialog`) `Esc` closes. Wire a global `⌘K` / `Ctrl+K` listener to toggle the dialog.

```tsx title="shortcut.tsx"
const [open, setOpen] = useState(false)

useEffect(() => {
  function onKeyDown(e: KeyboardEvent) {
    if ((e.metaKey || e.ctrlKey) && e.key.toLowerCase() === "k") {
      e.preventDefault()
      setOpen((o) => !o)
    }
  }
  document.addEventListener("keydown", onKeyDown)
  return () => document.removeEventListener("keydown", onKeyDown)
}, [])
```

## Motion

The palette is tuned to keep up with the keyboard. One shared highlight glides between rows as you arrow or sweep the pointer (it jumps without easing when typing changes the rows under it), the list eases its height as the query trims or restores results, and `CommandDialog` opens and closes on the fast duration, growing down from the search field. The dialog is centered on screen as the full-height panel, so the field you type into stays put while results shrink beneath it. Each motion is a CSS transition, so a held arrow key retargets smoothly instead of queueing. Under `prefers-reduced-motion` the glide, the height ease and the zoom switch off, leaving a plain fade on the dialog.

## Density

Like the rest of Koala, Command honors the cross-cutting `density` axis (or a `DensityProvider`): `compact` tightens the search height and row padding for an information-dense surface, never touching color or radius.

```tsx
<Command label="Theme" density="compact">
  <CommandInput placeholder="Search themes…" />
  <CommandList>
    <CommandGroup heading="Appearance">
      <CommandItem value="Light"><Sun /> Light</CommandItem>
      <CommandItem value="Dark"><Moon /> Dark</CommandItem>
      <CommandItem value="System"><Gear /> System</CommandItem>
    </CommandGroup>
  </CommandList>
</Command>
```

## API reference

### Command

The palette root and search/highlight state owner. Forwards every other `div` prop.

- `search` / `defaultSearch` / `onSearchChange`: the query string (controlled or not).
- `filter`: `(search, value, keywords?) => number`; return `0` to hide a row, any positive number to keep it. Defaults to a case-insensitive substring match.
- `onSelect`: fires when any row is chosen (after that row's own `onSelect`).
- `label`: accessible name for the result list.
- `density`: `comfortable` (default) or `compact`.

### CommandDialog

Wraps `Command` in a Radix Dialog. Takes all `Command` props plus:

- `open` / `defaultOpen` / `onOpenChange`: dialog open state.
- `closeOnSelect`: close after a row is chosen (default `true`).
- `title` / `description`: visually hidden labels for assistive tech.

### CommandInput, CommandList, CommandEmpty, CommandGroup, CommandItem, CommandSeparator, CommandShortcut

- `CommandInput`: the search field (combobox). It leads with the typed text, aligned to the rows below; pass `icon` for the magnifying glass, or a node for your own glyph. Inside `CommandDialog` it ends with an `Esc` hint that also closes the dialog on click.
- `CommandList`: the scrolling `listbox` viewport. It also paints the active row's highlight, so rows need to live inside one.
- `CommandEmpty`: shown only when no row matches.
- `CommandGroup`: a labeled section (`heading`) that hides when all its rows filter out.
- `CommandItem`: a selectable row. `value` (required), `keywords`, `disabled`, `onSelect(value)`.
- `CommandShortcut`: trailing key hint; drop `Kbd` children inside.

## FAQ

### When should I reach for Command versus DropdownMenu or Select?

Use Command for an open-ended, searchable list of actions or destinations (the ⌘K pattern), where typing to filter is the primary interaction. DropdownMenu and Select are for short, fixed sets that you pick from without searching.

### Do I need to render CommandDialog, or can I drop Command straight into a page?

Command is self-contained and brings its own surface, so you can render it inline in a page or inside a Popover. Wrap it in CommandDialog only when you want the modal behavior: Radix gives you the focus trap, scroll lock, Escape-to-close, and enter/exit animations.

### How does filtering decide which CommandItem rows show?

Each CommandItem has a required `value` (its searchable identity) plus an optional `keywords` array of synonyms, and the default filter does a case-insensitive substring match against both. A non-matching row renders nothing, so empty CommandGroup sections and the CommandEmpty state collapse on their own.

### Can I customize the match logic, for example to add fuzzy scoring?

Yes. Pass a `filter` prop of type `(search, value, keywords?) => number` to Command: return `0` to hide a row and any positive number to keep it. An empty query keeps everything by default.

### How do I run an action when a row is chosen, and close the dialog?

Put `onSelect(value)` on each CommandItem for its own handler, or a single `onSelect` on Command (or CommandDialog) that fires for any chosen row. Inside CommandDialog, rows close the palette by default; set `closeOnSelect={false}` to keep it open.

### How does keyboard navigation and screen reader support work?

Focus stays in CommandInput while arrow keys move the highlight (wrapping at the ends), Home and End jump to the first and last rows, and Enter runs the active row. The active row is communicated to assistive tech via `aria-activedescendant`, and disabled rows stay visible but drop out of the keyboard order.

---

<!-- https://www.koalaui.com/docs/components/context-menu.md -->

# Context Menu

The actions menu that opens where you right-click. Built on Radix ContextMenu for keyboard navigation and a11y; it shares its surface and density with Dropdown Menu, but anchors to the cursor.

```tsx
<ContextMenu>
  <ContextMenuTrigger asChild>
    <Card className="w-72 cursor-default select-none transition-shadow hover:shadow-md">
      <CardHeader>
        <div className="flex items-center gap-3">
          <div className="flex size-10 shrink-0 items-center justify-center rounded-lg bg-purple/10 text-purple">
            <FolderOpen className="size-5" />
          </div>
          <div className="min-w-0">
            <CardTitle className="text-base">Q3 Marketing Plan</CardTitle>
            <CardDescription>Edited 2 hours ago · 14 files</CardDescription>
          </div>
        </div>
        <p className="mt-4 text-xs text-muted-foreground">Right-click to open the menu</p>
      </CardHeader>
    </Card>
  </ContextMenuTrigger>
  <ContextMenuContent className="w-56">
    <ContextMenuItem>
      <FolderOpen /> Open
      <ContextMenuShortcut>⏎</ContextMenuShortcut>
    </ContextMenuItem>
    <ContextMenuItem>
      <PencilSimple /> Rename
      <ContextMenuShortcut>⌘R</ContextMenuShortcut>
    </ContextMenuItem>
    <ContextMenuItem>
      <Copy /> Duplicate
      <ContextMenuShortcut>⌘D</ContextMenuShortcut>
    </ContextMenuItem>
    <ContextMenuSeparator />
    <ContextMenuItem>
      <PushPin /> Pin to top
    </ContextMenuItem>
    <ContextMenuSub>
      <ContextMenuSubTrigger>
        <ShareNetwork /> Share
      </ContextMenuSubTrigger>
      <ContextMenuSubContent className="w-44">
        <ContextMenuItem>
          <Envelope /> Email
        </ContextMenuItem>
        <ContextMenuItem>
          <Link /> Copy link
          <ContextMenuShortcut>⌘L</ContextMenuShortcut>
        </ContextMenuItem>
        <ContextMenuSeparator />
        <ContextMenuItem>
          <ChatCircle /> Send message
        </ContextMenuItem>
      </ContextMenuSubContent>
    </ContextMenuSub>
    <ContextMenuSeparator />
    <ContextMenuItem variant="destructive">
      <Trash /> Delete
      <ContextMenuShortcut>⌫</ContextMenuShortcut>
    </ContextMenuItem>
  </ContextMenuContent>
</ContextMenu>
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add context-menu
```

Manual: run `npm install radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/context-menu/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

```tsx title="usage.tsx"
import {
  ContextMenu, ContextMenuTrigger, ContextMenuContent,
  ContextMenuItem, ContextMenuSeparator, ContextMenuShortcut,
} from "@/components/ui/context-menu"
import { Card } from "@/components/ui/card"
import { Copy, PencilSimple, Trash } from "@phosphor-icons/react"

export function Example() {
  return (
    <ContextMenu>
      <ContextMenuTrigger asChild>
        <Card className="w-72 select-none p-6">Right-click me</Card>
      </ContextMenuTrigger>
      <ContextMenuContent className="w-48">
        <ContextMenuItem>
          <PencilSimple /> Rename
          <ContextMenuShortcut>⌘R</ContextMenuShortcut>
        </ContextMenuItem>
        <ContextMenuItem>
          <Copy /> Duplicate
          <ContextMenuShortcut>⌘D</ContextMenuShortcut>
        </ContextMenuItem>
        <ContextMenuSeparator />
        <ContextMenuItem variant="destructive">
          <Trash /> Delete
        </ContextMenuItem>
      </ContextMenuContent>
    </ContextMenu>
  )
}
```

## Any surface as the trigger

Wrap any element with `ContextMenuTrigger` and `asChild`; the menu opens at the cursor anywhere inside it. An image is the classic right-click target.

```tsx
<ContextMenu>
  <ContextMenuTrigger asChild>
    <figure className="aspect-[3/2] w-72 overflow-hidden rounded-xl border border-border shadow-xs">
      <img src="/landscape.jpg" alt="Mountain landscape" className="size-full object-cover" />
    </figure>
  </ContextMenuTrigger>
  <ContextMenuContent className="w-52">
    <ContextMenuItem>
      <CornersOut /> Open full size
    </ContextMenuItem>
    <ContextMenuItem>
      <ImageSquare /> Copy image
      <ContextMenuShortcut>⌘C</ContextMenuShortcut>
    </ContextMenuItem>
    <ContextMenuItem>
      <Link /> Copy image address
    </ContextMenuItem>
    <ContextMenuSeparator />
    <ContextMenuItem>
      <DownloadSimple /> Save image
      <ContextMenuShortcut>⌘S</ContextMenuShortcut>
    </ContextMenuItem>
    <ContextMenuItem>
      <Star /> Add to favorites
    </ContextMenuItem>
  </ContextMenuContent>
</ContextMenu>
```

## Checkbox items

Toggle independent options straight from the menu. `ContextMenuCheckboxItem` keeps the menu open on click so several can be flipped in one pass.

```tsx
<ContextMenu>
  <ContextMenuTrigger asChild>
    <div className="flex h-40 w-72 items-center justify-center rounded-xl border border-dashed">
      Right-click the canvas
    </div>
  </ContextMenuTrigger>
  <ContextMenuContent className="w-52">
    <ContextMenuLabel>View</ContextMenuLabel>
    <ContextMenuSeparator />
    <ContextMenuCheckboxItem checked>Show grid</ContextMenuCheckboxItem>
    <ContextMenuCheckboxItem checked>Snap to grid</ContextMenuCheckboxItem>
    <ContextMenuCheckboxItem>Rulers</ContextMenuCheckboxItem>
    <ContextMenuCheckboxItem>Pixel preview</ContextMenuCheckboxItem>
  </ContextMenuContent>
</ContextMenu>
```

## Switch items

Pass `variant="switch"` to a checkbox item for an option that applies the moment it flips. The menu stays open when it is toggled, so a few can be set before it closes; the row is still a menu checkbox, with the switch as its drawing.

```tsx
<ContextMenuContent className="w-56">
  <ContextMenuLabel>View</ContextMenuLabel>
  <ContextMenuSeparator />
  <ContextMenuCheckboxItem variant="switch" checked={grid} onCheckedChange={setGrid}>
    <GridFour /> Show grid
  </ContextMenuCheckboxItem>
  <ContextMenuCheckboxItem variant="switch" checked={snap} onCheckedChange={setSnap}>
    <Magnet /> Snap to grid
  </ContextMenuCheckboxItem>
</ContextMenuContent>
```

## Radio items

A mutually exclusive choice lives in a `ContextMenuRadioGroup` with a shared `value`; the active row shows a check.

```tsx
<ContextMenu>
  <ContextMenuTrigger asChild>
    <div className="flex h-40 w-72 items-center justify-center rounded-xl border border-dashed">
      Right-click to sort
    </div>
  </ContextMenuTrigger>
  <ContextMenuContent className="w-48">
    <ContextMenuLabel>Sort by</ContextMenuLabel>
    <ContextMenuSeparator />
    <ContextMenuRadioGroup value="modified">
      <ContextMenuRadioItem value="name">
        <TextAa /> Name
      </ContextMenuRadioItem>
      <ContextMenuRadioItem value="modified">
        <PencilSimple /> Last modified
      </ContextMenuRadioItem>
      <ContextMenuRadioItem value="size">
        <ArrowsOutCardinal /> Size
      </ContextMenuRadioItem>
    </ContextMenuRadioGroup>
  </ContextMenuContent>
</ContextMenu>
```

## Groups, submenus & shortcuts

Section items with `ContextMenuGroup`, nest a `ContextMenuSub`, and add right-aligned hints with `ContextMenuShortcut` (decorative; wire the real binding in your app). Use `inset` to align items that have no leading icon.

```tsx
<ContextMenu>
  <ContextMenuTrigger asChild>
    <div className="flex h-40 w-72 items-center justify-center rounded-xl border border-dashed">
      Right-click the editor
    </div>
  </ContextMenuTrigger>
  <ContextMenuContent className="w-56">
    <ContextMenuGroup>
      <ContextMenuItem>
        <Copy /> Copy
        <ContextMenuShortcut>⌘C</ContextMenuShortcut>
      </ContextMenuItem>
      <ContextMenuItem>
        <PencilSimple /> Cut
        <ContextMenuShortcut>⌘X</ContextMenuShortcut>
      </ContextMenuItem>
      <ContextMenuItem inset>
        Paste
        <ContextMenuShortcut>⌘V</ContextMenuShortcut>
      </ContextMenuItem>
    </ContextMenuGroup>
    <ContextMenuSeparator />
    <ContextMenuSub>
      <ContextMenuSubTrigger>
        <ShareNetwork /> Share
      </ContextMenuSubTrigger>
      <ContextMenuSubContent className="w-44">
        <ContextMenuItem>
          <Envelope /> Email link
        </ContextMenuItem>
        <ContextMenuItem>
          <Link /> Copy link
          <ContextMenuShortcut>⌘L</ContextMenuShortcut>
        </ContextMenuItem>
        <ContextMenuSeparator />
        <ContextMenuItem>
          <ChatCircle /> Messages
        </ContextMenuItem>
      </ContextMenuSubContent>
    </ContextMenuSub>
    <ContextMenuSeparator />
    <ContextMenuItem variant="destructive">
      <Trash /> Delete
      <ContextMenuShortcut>⌫</ContextMenuShortcut>
    </ContextMenuItem>
  </ContextMenuContent>
</ContextMenu>
```

## FAQ

### When should I use a Context Menu versus a Dropdown Menu?

They share the same surface and items; the difference is how they open. A Dropdown Menu opens on click of a visible trigger button, so the affordance is obvious. A Context Menu opens on right-click (or long-press) of an arbitrary area like a card, row, image, or canvas, so it is best for secondary or power-user actions that should not take up button space. Many apps offer both: a more-actions button and the same actions on right-click.

### How do I make a card or any element the trigger?

Pass `asChild` to ContextMenuTrigger and render your element inside it, such as a Card or a figure. Radix attaches the right-click handler and ARIA to your element instead of rendering its own wrapper, and the menu anchors to the cursor position within it.

### Why doesn't ContextMenuContent take a `side` or `sideOffset`?

A context menu is positioned at the cursor where you right-clicked, not relative to a trigger element, so there is no side or gap to offset. Radix still flips the menu to stay on-screen and sets data-side, which drives the same fade-and-slide enter animation Dropdown Menu uses.

### Does ContextMenuShortcut bind the keyboard shortcut?

No. ContextMenuShortcut is purely decorative right-aligned text rendered through the shared Kbd primitive, so it just displays the hint like ⌘R. Wire up the real key binding in your app with a global listener.

### How does it behave on touch devices?

Radix opens the menu on long-press, the platform convention for touch. Keep the right-click actions reachable another way too (a more-actions button) since not every user will discover the long-press gesture.

### How do I tighten the menu for dense application UI?

Set `density="compact"` on ContextMenuContent, or drive it globally with DensityProvider since every part reads the density context. Compact shortens rows from 36px to 32px. The horizontal rhythm does not change between densities: icons, labels, shortcuts and the check always sit 16px from the menu's outer edge, and the corners stay concentric at either size.

---

<!-- https://www.koalaui.com/docs/components/cookie-consent.md -->

# Cookie Consent

A GDPR-ready consent surface in two coordinated pieces over one shared state: a non-blocking banner and a preferences dialog with a toggle per cookie category. The parts are the real DS components.

```tsx
<CookieConsent categories={categories} onAcceptAll={persist} onRejectAll={persist} onSave={persist}>
  <CookieBanner position="bottom-right">
    <CookieBannerIcon><Cookie /></CookieBannerIcon>
    <CookieBannerContent>
      <CookieBannerTitle>We value your privacy</CookieBannerTitle>
      <CookieBannerDescription>
        We use cookies to enhance your experience and analyse traffic. Read our{" "}
        <a href="/cookies" className="font-medium text-foreground underline underline-offset-4">
          Cookie Policy
        </a>.
      </CookieBannerDescription>
    </CookieBannerContent>
    <CookieBannerActions>
      <CookieCustomizeButton size="sm" />
      <CookieRejectAllButton size="sm" />
      <CookieAcceptAllButton size="sm" />
    </CookieBannerActions>
  </CookieBanner>

  <CookiePreferences>
    <CookiePreferencesContent>
      <CookiePreferencesHeader>
        <CookiePreferencesTitle>Cookie preferences</CookiePreferencesTitle>
        <CookiePreferencesDescription>Choose which cookies we can use.</CookiePreferencesDescription>
      </CookiePreferencesHeader>
      <CookieCategoryList />
      <CookiePreferencesFooter>
        <CookieRejectAllButton variant="ghost" />
        <CookieSavePreferencesButton />
      </CookiePreferencesFooter>
    </CookiePreferencesContent>
  </CookiePreferences>
</CookieConsent>
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add cookie-consent
```

Manual: run `npm install radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/cookie-consent/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

```tsx title="usage.tsx"
import { ShieldCheck, ChartBar } from "@phosphor-icons/react"
import {
  CookieConsent,
  CookieBanner,
  CookieBannerContent,
  CookieBannerTitle,
  CookieBannerDescription,
  CookieBannerActions,
  CookieAcceptAllButton,
  CookieRejectAllButton,
  CookieCustomizeButton,
  CookiePreferences,
  CookiePreferencesContent,
  CookiePreferencesHeader,
  CookiePreferencesTitle,
  CookieCategoryList,
  CookiePreferencesFooter,
  CookieSavePreferencesButton,
  type CookieCategoryDef,
} from "@/components/ui/cookie-consent"

const categories: CookieCategoryDef[] = [
  { id: "necessary", label: "Strictly necessary", required: true, icon: ShieldCheck, description: "Essential for the site to work." },
  { id: "analytics", label: "Analytics", icon: ChartBar, description: "Help us understand how the site is used." },
]

export function Example() {
  return (
    <CookieConsent categories={categories} onSave={(prefs) => savePreferences(prefs)}>
      <CookieBanner position="bottom-right">
        <CookieBannerContent>
          <CookieBannerTitle>We value your privacy</CookieBannerTitle>
          <CookieBannerDescription>We use cookies to improve your experience.</CookieBannerDescription>
        </CookieBannerContent>
        <CookieBannerActions>
          <CookieCustomizeButton size="sm" />
          <CookieRejectAllButton size="sm" />
          <CookieAcceptAllButton size="sm" />
        </CookieBannerActions>
      </CookieBanner>

      <CookiePreferences>
        <CookiePreferencesContent>
          <CookiePreferencesHeader>
            <CookiePreferencesTitle>Cookie preferences</CookiePreferencesTitle>
          </CookiePreferencesHeader>
          <CookieCategoryList />
          <CookiePreferencesFooter>
            <CookieRejectAllButton variant="ghost" />
            <CookieSavePreferencesButton />
          </CookiePreferencesFooter>
        </CookiePreferencesContent>
      </CookiePreferences>
    </CookieConsent>
  )
}
```

## Details on hover

`CookieBannerDetails` keeps the banner clean: it stays folded away and unrolls above the copy on hover or keyboard focus, so the buttons never move under the pointer. `CookieDetailList` fills it from your `categories`, listing the `cookies` of each one with its purpose, provider and duration. Touch screens have no hover, so `CookieBannerDetailsTrigger` shows there, and only there. Escape folds it again.

```tsx
const categories: CookieCategoryDef[] = [
  {
    id: "analytics",
    label: "Analytics",
    cookies: [{ name: "_ga", purpose: "Tells visits apart", provider: "Google", duration: "2 years" }],
  },
  // …
]

<CookieBanner position="bottom-right">
  <CookieBannerContent>
    <CookieBannerTitle>We value your privacy</CookieBannerTitle>
    <CookieBannerDescription>We use cookies to run the site and, if you agree, to measure it.</CookieBannerDescription>
  </CookieBannerContent>
  <CookieBannerDetails>
    <CookieDetailList />
  </CookieBannerDetails>
  <CookieBannerActions>
    <CookieBannerDetailsTrigger size="sm" />
    <CookieRejectAllButton size="sm" />
    <CookieAcceptAllButton size="sm" />
  </CookieBannerActions>
</CookieBanner>
```

## Essential cookies only

A site that stores only what it needs to work (a sign-in, a saved theme) needs no consent, so there is nothing to accept or reject, only something to know. `layout="launcher"` rests the banner as its icon alone in a small circle. On hover, focus or a tap, the circle grows into the card and the icon slides to its seat beside the title, with the reason and the full list above. This is the notice koalaui.com runs.

```tsx
<CookieConsent categories={essential} storageKey="cookie-notice">
  <CookieBanner position="bottom-right" layout="launcher">
    <CookieBannerIcon><Cookie /></CookieBannerIcon>
    <CookieBannerContent>
      <CookieBannerTitle>Only essential cookies</CookieBannerTitle>
    </CookieBannerContent>
    <CookieBannerDetails>
      <CookieBannerDescription>No analytics, no ads, no tracking.</CookieBannerDescription>
      <CookieDetailList />
    </CookieBannerDetails>
    <CookieBannerActions>
      <CookieBannerDetailsTrigger size="sm" />
      <CookieAcceptAllButton size="sm" variant="secondary">Got it</CookieAcceptAllButton>
    </CookieBannerActions>
  </CookieBanner>
</CookieConsent>
```

## Remember the choice

Pass `storageKey` and the root keeps the answer in localStorage: the banner shows only until the visitor answers, the preferences come back on the next visit, and every open tab follows. The record is dated and versioned. Bump `version` when your categories change and everyone is asked again; after `maxAgeDays` (six months by default) the choice expires and the banner returns. Nothing optional is on until the visitor says so, so gate each script on the preferences map.

```tsx title="consent.tsx"
<CookieConsent categories={categories} storageKey="cookie-consent" version={2} maxAgeDays={180}>
  …
  <Analytics />
</CookieConsent>

// Stored as: { "version": 2, "date": "2026-09-27T10:04:12.000Z", "preferences": { "necessary": true, "analytics": false } }

function Analytics() {
  const { prefs } = useCookieConsent()
  // Off until the visitor accepts, and off again the moment they withdraw.
  if (!prefs.analytics) return null
  return <Script src="https://plausible.io/js/script.js" data-domain="example.com" />
}
```

## Preferences dialog

The configurator is a DS `Dialog` bound to the same shared state. `CookieCategoryList` maps your `categories` into rows, each with a leading icon, a description, and a `Switch`. Required categories render locked-on with an *Always on* badge. Open it from the banner's `CookieCustomizeButton`, or from a standalone `CookiePreferencesTrigger` anywhere on the page.

```tsx
<CookieConsent categories={categories} defaultConsented>
  <CookiePreferences>
    <CookiePreferencesTrigger asChild>
      <Button variant="outline"><Gear /> Cookie settings</Button>
    </CookiePreferencesTrigger>
    <CookiePreferencesContent>
      <CookiePreferencesHeader>
        <CookiePreferencesTitle>Cookie preferences</CookiePreferencesTitle>
        <CookiePreferencesDescription>
          Choose which cookies we can use. Strictly necessary cookies are always on.
        </CookiePreferencesDescription>
      </CookiePreferencesHeader>
      <CookieCategoryList />
      <CookiePreferencesFooter>
        <CookieRejectAllButton variant="ghost" />
        <CookieAcceptAllButton variant="secondary" />
        <CookieSavePreferencesButton />
      </CookiePreferencesFooter>
    </CookiePreferencesContent>
  </CookiePreferences>
</CookieConsent>
```

## Position

`position` anchors the banner: `bottom` is a full-bleed bar that rows its content out on wide screens, while `bottom-left` and `bottom-right` are compact floating cards. Each slides in from its own edge. `layout` arranges the parts inside: `stack` (the default) is a column, `inline` one slim row, and `launcher` (corners only) the icon alone until the banner is expanded.

```tsx
<CookieBanner position="bottom"> … </CookieBanner>
<CookieBanner position="bottom-left"> … </CookieBanner>
<CookieBanner position="bottom-right"> … </CookieBanner>
```

## API reference

### CookieConsent

The root and single source of truth. Owns the category booleans and the coordinated actions; both surfaces read from it.

- `categories`: the cookie categories to manage (`CookieCategoryDef[]`): each has an `id`, `label`, optional `description`, `icon`, `required` (locks the toggle on), and `cookies` (`name`, `purpose`, `provider`, `duration`) for the detail list.
- `storageKey` / `version` (default `1`) / `maxAgeDays` (default `180`): remember the answer in localStorage, dated and versioned, and ask again when the version changes or it expires.
- `value` / `defaultValue` / `onValueChange`: the preferences map (`{ [id]: boolean }`), controlled or uncontrolled. Required categories are always clamped on.
- `onAcceptAll` / `onRejectAll` / `onSave`: fire on each coordinated action with the resulting map. Persist it (cookie / localStorage) here.
- `open` / `defaultOpen` / `onOpenChange`: the preferences dialog open state.
- `defaultConsented`: start with the banner hidden (pass `true` for returning visitors).
- `density`: `comfortable` (default) or `compact`.

### CookieBanner

The non-blocking consent region (`role="region"`), hidden once a choice is made. Takes `position` (`bottom` / `bottom-left` / `bottom-right`) and `layout` (`stack` / `inline` / `launcher`). Compose `CookieBannerIcon`, `CookieBannerContent`, `CookieBannerTitle`, `CookieBannerDescription`, `CookieBannerDetails` (the layer that opens on hover, focus or `CookieBannerDetailsTrigger`), and `CookieBannerActions` inside. The banner stamps `data-expanded` while the layer is open. `CookieDetailList` lists every category's cookies, in the layer or anywhere inside the root.

### CookiePreferences

The dialog family: `CookiePreferences` (root, bound to the shared open state), `CookiePreferencesTrigger` (`asChild`), `CookiePreferencesContent`, `CookiePreferencesHeader` / `Title` / `Description` / `Footer`, and `CookieCategoryList` / `CookieCategory` for the rows.

### Action buttons & hook

Pre-wired DS Buttons: `CookieAcceptAllButton`, `CookieRejectAllButton`, `CookieCustomizeButton`, `CookieSavePreferencesButton`. Each forwards every `Button` prop. For a custom surface, read the state directly with the `useCookieConsent()` hook.

## FAQ

### When should I reach for Cookie Consent instead of a plain Dialog?

Use Cookie Consent when you need a GDPR/ePrivacy consent flow specifically: it pairs a non-blocking CookieBanner with a CookiePreferences dialog over one shared state, so toggling a category and clicking Accept all mutate the same source of truth. A plain Dialog gives you a modal but none of the category booleans, the always-on clamping, or the coordinated accept/reject/save actions.

### Does Cookie Consent make my site GDPR compliant?

It covers the interface the rules ask for: nothing optional is on until the visitor chooses (no pre-ticked boxes), Reject all sits on the first layer next to Accept all, consent is granular per category, the cookies behind each one are listed with purpose, provider and duration, the choice can be changed from the preferences dialog at any time, and with storageKey it is dated, versioned and renewed after six months. What stays with you: list the cookies you really set, keep each script from loading until useCookieConsent().prefs allows it, and link a privacy policy.

### How do I persist the visitor's choice and stop the banner reappearing?

Pass storageKey and the root does it: the answer is stored in localStorage with its date and version, the banner shows only until the visitor answers, and it asks again once the version changes or the answer is older than maxAgeDays. To keep the choice somewhere else (a server-side record, a first-party cookie), leave storageKey out, persist the map you receive in onAcceptAll, onRejectAll, and onSave, and pass defaultConsented on the next visit.

### My site only uses essential cookies. Do I need a banner?

Consent, no: strictly necessary storage (a sign-in session, a saved theme, the record of this notice) is exempt. Telling visitors is still good practice, which is what the inline notice with a single Got it button does. Mark every category required and nothing can be switched off. The day you add analytics, give it its own category, show Reject all and Accept all, and bump version so everyone is asked.

### How do I mark a category like Strictly necessary as non-optional?

Set required: true on that CookieCategoryDef. The root clamps it on in the preferences map regardless of value or defaultValue, and CookieCategory renders its Switch disabled-on with an Always on Badge.

### Can I open the preferences dialog from somewhere other than the banner, like a footer link?

Yes. Wrap your own element in CookiePreferencesTrigger with asChild, or read the state directly with the useCookieConsent() hook and call setDialogOpen(true) from any custom surface such as a footer Cookie settings link.

### How do the action buttons behave, and can I restyle them?

CookieAcceptAllButton, CookieRejectAllButton, CookieCustomizeButton, and CookieSavePreferencesButton are thin DS Button wrappers with the consent action pre-bound, so they forward every Button prop including variant and size. An onClick you pass still runs after the consent action fires, so the defaults are a starting point, not a cage.

### Does Cookie Consent respond to density, and where does that come from?

It does. Pass density="compact" on CookieConsent or let it inherit from a surrounding DensityProvider; compact tightens the banner padding and the category rows without touching radius or color, while the dialog picks up the same density through CookiePreferencesContent.

---

<!-- https://www.koalaui.com/docs/components/date-picker.md -->

# Date Picker

A calendar surface plus two ready pickers, single date and range, over Radix Popover with native Date math and no date dependency. Selection reads the brand accent; the in-range fill stays neutral.

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

<DatePicker value={date} onChange={setDate} presets clearable />
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add date-picker
```

Manual: run `npm install radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/date-picker/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

```tsx title="usage.tsx"
import { DatePicker } from "@/components/ui/date-picker"

export function Example() {
  const [date, setDate] = React.useState<Date>()
  return <DatePicker value={date} onChange={setDate} />
}
```

## Calendar

The `Calendar` is the standalone grid the pickers wrap. Use it directly when you need an always-open calendar. The caption cycles day → month → year views; arrow keys move the focused day, PageUp/PageDown move a month, Home/End jump to the week edges.

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

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

## Range selection

Set `mode="range"` to select a `{ from, to }` span. The first click sets the start, the second closes the range; hovering previews the span. Show multiple months with `numberOfMonths`.

```tsx
const [range, setRange] = React.useState<DateRange>()

<Calendar mode="range" selected={range} onSelect={setRange} numberOfMonths={2} />
```

## Presets

Pass `presets` to render a quick-pick rail. Use `presets` (boolean) for the built-in set, or pass your own array. The single-date set ships `getDatePresets()`; the range set ships `getDateRangePresets()` with eleven common spans (Today, Last 7 days, This month, Last year, …).

```tsx
<DateRangePicker presets clearable />
```

```tsx
const presets = getDatePresets().slice(0, 3)

<DatePicker presets={presets} />
```

## Range with presets

The combination most analytics surfaces want: a two-month range picker with the full preset rail.

```tsx
const presets = getDateRangePresets()

<DateRangePicker presets={presets} numberOfMonths={2} />
```

## Sizes

```tsx
<DatePicker size="sm" />
<DatePicker size="md" />
<DatePicker size="lg" />
```

## Constraints

Bound the range with `min` / `max`, or disable arbitrary days with `isDateDisabled`. Disabled days are inert and struck through.

```tsx
<DatePicker
  min={today}
  max={endOfNextMonth}
  isDateDisabled={(d) => d.getDay() === 0 || d.getDay() === 6}
/>
```

## Density

Like the rest of Koala, the calendar honors `density`: `compact` tightens cells and controls for dense application UI.

```tsx
<DatePicker density="compact" presets />
```

## Inside a Field

Drop a picker inside a `Field` and it auto-wires the label, hint, `id`, and error/disabled state, with no manual props.

```tsx
<Field>
  <FieldLabel>Start date</FieldLabel>
  <DatePicker block placeholder="Select a start date" />
  <FieldHint>Your subscription begins on this date.</FieldHint>
</Field>
```

## FAQ

### When should I reach for the standalone Calendar instead of DatePicker or DateRangePicker?

Use Calendar when you need an always-open grid inline on the page, such as a booking surface or a sidebar. DatePicker and DateRangePicker wrap that same Calendar in a Radix Popover with a trigger, so prefer them whenever the calendar should open from a field-like button.

### How do I switch the range picker to a single-date picker, and how does selection differ?

They are separate exports: DatePicker resolves a single Date, while DateRangePicker resolves a `{ from, to }` DateRange. On the underlying Calendar this maps to `mode="single"` versus `mode="range"`, where the first range click sets `from` and the second closes the span with a hover preview in between.

### What is the difference between passing `presets` as a boolean versus an array?

Passing `presets` as `true` renders the built-in rail: getDatePresets() for DatePicker and getDateRangePresets() for DateRangePicker. Pass your own array of `{ label, value }` items (DatePreset or DateRangePreset) to fully control the shortcuts shown.

### How do I disable specific days like weekends or dates outside a window?

Bound the selectable window with the `min` and `max` props (both inclusive), and pass `isDateDisabled` for arbitrary rules, for example `(d) => d.getDay() === 0 || d.getDay() === 6` to block weekends. Disabled days become inert and render struck through.

### What keyboard navigation does the calendar grid support?

The grid uses a roving tabindex, so arrow keys move the focused day, PageUp and PageDown shift by a month, and Home and End jump to the week edges. Enter or Space commits the focused day, and the caption button cycles the day, month, and year views.

### Do I need to wire up the label and error state when using a picker inside a Field?

No. Both pickers read useFieldContext, so dropping a DatePicker inside a Field auto-wires the `id`, `aria-describedby`, disabled, and error state from the surrounding Field. You can still override explicitly with the `disabled`, `hasError`, and `id` props when used standalone.

---

<!-- https://www.koalaui.com/docs/components/dialog.md -->

# Dialog

A modal window over the page. Built on Radix Dialog for focus trap, scroll lock, and a11y; styled with one tv slots recipe and animated with interruptible enter/exit.

Every pattern below is its own block: a live preview in a device frame you can resize (mobile / tablet / desktop, or drag the handle) plus its code. Dialogs cap at `md` (30rem) by default, the width nearly every dialog should use. Drag any frame narrow to watch the card shrink to fit.

```tsx
<Dialog>
  <DialogTrigger asChild>
    <Button>Open dialog</Button>
  </DialogTrigger>
  <DialogContent>
    <DialogIcon><UserCircle /></DialogIcon>
    <DialogHeader>
      <DialogTitle>Edit profile</DialogTitle>
      <DialogDescription>
        Make changes to your profile here. Click save when you're done.
      </DialogDescription>
    </DialogHeader>
    <DialogFooter>
      <DialogClose asChild>
        <Button variant="ghost">Cancel</Button>
      </DialogClose>
      <Button>Save changes</Button>
    </DialogFooter>
  </DialogContent>
</Dialog>
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add dialog
```

Manual: run `npm install radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/dialog/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

```tsx title="usage.tsx"
import {
  Dialog, DialogTrigger, DialogContent, DialogIcon, DialogHeader,
  DialogFooter, DialogTitle, DialogDescription, DialogClose,
} from "@/components/ui/dialog"
import { UserCircle } from "@phosphor-icons/react"
import { Button } from "@/components/ui/button"

export function Example() {
  return (
    <Dialog>
      <DialogTrigger asChild>
        <Button>Open dialog</Button>
      </DialogTrigger>
      <DialogContent>
        <DialogIcon><UserCircle /></DialogIcon>
        <DialogHeader>
          <DialogTitle>Edit profile</DialogTitle>
          <DialogDescription>
            Make changes to your profile here. Click save when you're done.
          </DialogDescription>
        </DialogHeader>
        <DialogFooter>
          <DialogClose asChild>
            <Button variant="ghost">Cancel</Button>
          </DialogClose>
          <Button>Save changes</Button>
        </DialogFooter>
      </DialogContent>
    </Dialog>
  )
}
```

## Confirmation

A destructive confirmation: no header close button (`showClose={false}`) forces an explicit choice, and the leading icon is tinted red.

```tsx
<Dialog>
  <DialogTrigger asChild>
    <Button variant="destructive">Delete account</Button>
  </DialogTrigger>
  <DialogContent size="sm" showClose={false}>
    {/* Tint the leading icon red for a destructive action */}
    <DialogIcon className="text-destructive"><Trash /></DialogIcon>
    <DialogHeader>
      <DialogTitle>Delete account?</DialogTitle>
      <DialogDescription>
        This permanently deletes your account and all data. This cannot be undone.
      </DialogDescription>
    </DialogHeader>
    <DialogFooter>
      <DialogClose asChild><Button variant="ghost">Cancel</Button></DialogClose>
      <DialogClose asChild><Button variant="destructive">Delete</Button></DialogClose>
    </DialogFooter>
  </DialogContent>
</Dialog>
```

## Form

Place labelled fields between `DialogHeader` and `DialogFooter`. Land focus on the first field with `onOpenAutoFocus`; inline validation appears below each field on submit.

```tsx
function InviteDialog() {
  const nameRef = React.useRef<HTMLInputElement>(null)
  const [name, setName] = React.useState("")
  const [email, setEmail] = React.useState("")
  const [nameError, setNameError] = React.useState("")
  const [emailError, setEmailError] = React.useState("")

  function handleSubmit() {
    if (!name.trim()) { setNameError("Name is required."); return }
    if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)) {
      setEmailError("Enter a valid email address."); return
    }
    // submit…
  }

  return (
    <Dialog>
      <DialogTrigger asChild>
        <Button>Invite member</Button>
      </DialogTrigger>
      <DialogContent
        size="sm"
        onOpenAutoFocus={(e) => {
          e.preventDefault()
          nameRef.current?.focus()
        }}
      >
        <DialogHeader>
          <DialogTitle>Invite team member</DialogTitle>
          <DialogDescription>
            Enter the details below. An invitation will be sent by email.
          </DialogDescription>
        </DialogHeader>
        <FormSection>
          <Field hasError={!!nameError}>
            <FieldLabel>Full name</FieldLabel>
            <InputRoot>
              <InputField ref={nameRef} value={name} onChange={(e) => setName(e.target.value)} />
            </InputRoot>
            {nameError && <FieldHint>{nameError}</FieldHint>}
          </Field>
          <Field hasError={!!emailError}>
            <FieldLabel>Email address</FieldLabel>
            <InputRoot>
              <InputField type="email" value={email} onChange={(e) => setEmail(e.target.value)} />
            </InputRoot>
            {emailError && <FieldHint>{emailError}</FieldHint>}
          </Field>
        </FormSection>
        <DialogFooter>
          <DialogClose asChild>
            <Button variant="ghost">Cancel</Button>
          </DialogClose>
          <Button onClick={handleSubmit}>Send invite</Button>
        </DialogFooter>
      </DialogContent>
    </Dialog>
  )
}
```

## Compact density

`density="compact"` tightens padding, gaps and the title for application UI; it re-provides itself to the header, body and footer so every part stays in sync. Best driven once via `DensityProvider`; see [Density](https://www.koalaui.com/docs/foundations/density.md).

```tsx
<DialogContent density="compact" size="sm">
  <DialogIcon><Rows /></DialogIcon>
  <DialogHeader>
    <DialogTitle>Compact dialog</DialogTitle>
    <DialogDescription>Tighter padding and a 1rem title for dense application UI.</DialogDescription>
  </DialogHeader>
  <DialogFooter>
    <DialogClose asChild><Button>Got it</Button></DialogClose>
  </DialogFooter>
</DialogContent>
```

## Scrollable body

For tall content (terms, changelogs, long forms) put the middle in a `DialogBody`. The dialog then caps itself to the viewport and only the body scrolls, its edges fading into the dialog while the header and footer stay pinned. It runs edge to edge, so the fade and the scrollbar use the full width. When it holds only text, give it `tabIndex={0}` so a keyboard user can scroll it.

```tsx
<DialogContent>
  <DialogIcon><FileText /></DialogIcon>
  <DialogHeader>
    <DialogTitle>Terms of service</DialogTitle>
    <DialogDescription>Please read the full terms before accepting.</DialogDescription>
  </DialogHeader>
  {/* Only the body scrolls; the header and footer stay pinned */}
  <DialogBody tabIndex={0} className="text-sm text-muted-foreground">
    {/* …long content… */}
  </DialogBody>
  <DialogFooter>
    <DialogClose asChild><Button variant="ghost">Decline</Button></DialogClose>
    <DialogClose asChild><Button>Accept</Button></DialogClose>
  </DialogFooter>
</DialogContent>
```

## Mobile

Below the `sm` breakpoint a dialog docks to the bottom edge as a sheet: within thumb reach, with square bottom corners, rising on the drawer curve and keeping the home indicator’s safe area clear. This frame opens at phone width; switch it to Tablet or Desktop to watch the same dialog float back to the center. Pass `mobile="center"` to keep a dialog floating at every width. There is no grab handle, since a handle promises a drag: reach for Drawer when you want swipe to dismiss.

```tsx
// On a phone this docks to the bottom edge as a sheet (the default)
<DialogContent>…</DialogContent>

// Floating mid-screen at every width
<DialogContent mobile="center">…</DialogContent>
```

## Nested dialogs

Open a dialog from inside another and the one underneath steps back: it scales to 90% and lifts slightly, and a lighter second scrim keeps the page from going black. It is plain CSS on the real component, so there is nothing to wire, and closing the top dialog brings the other forward in step with its exit. It tracks two levels, which is also the most a flow should ask for.

```tsx
<Dialog>
  <DialogTrigger asChild><Button variant="outline">Delete project</Button></DialogTrigger>
  <DialogContent>
    <DialogHeader>
      <DialogTitle>Delete project</DialogTitle>
      <DialogDescription>Koala Web and its 12 environments will be removed.</DialogDescription>
    </DialogHeader>
    <DialogFooter>
      <DialogClose asChild><Button variant="ghost">Cancel</Button></DialogClose>
      {/* Opened from inside the first dialog: that one steps back on its own */}
      <Dialog>
        <DialogTrigger asChild><Button variant="destructive">Delete</Button></DialogTrigger>
        <DialogContent size="sm">
          <DialogHeader>
            <DialogTitle>Are you absolutely sure?</DialogTitle>
            <DialogDescription>This can't be undone.</DialogDescription>
          </DialogHeader>
          <DialogFooter>
            <DialogClose asChild><Button variant="ghost">Keep project</Button></DialogClose>
            <DialogClose asChild><Button variant="destructive">Delete forever</Button></DialogClose>
          </DialogFooter>
        </DialogContent>
      </Dialog>
    </DialogFooter>
  </DialogContent>
</Dialog>
```

## Share

A leading `DialogIcon` above composed [Input](https://www.koalaui.com/docs/components/input.md) parts: a read-only link with a copy button, and an email field paired with a send action.

```tsx
<DialogContent>
  <DialogIcon><LinkSimple /></DialogIcon>
  <DialogHeader>
    <DialogTitle>Share incident</DialogTitle>
    <DialogDescription>Choose who you want to share the incident with.</DialogDescription>
  </DialogHeader>
  <FormSection>
    <Field required>
      <FieldLabel>Copy the link directly</FieldLabel>
      <InputRoot>
        <InputField readOnly value="lspcad.flab/incident21414" />
        <InputSuffixButton aria-label="Copy link"><Copy /></InputSuffixButton>
      </InputRoot>
    </Field>
    <Field required>
      <FieldLabel>Send the link via invitation</FieldLabel>
      {/* Stack on mobile so the button never overflows a narrow dialog; row from sm */}
      <div className="flex flex-col gap-2 sm:flex-row sm:items-center">
        <InputRoot className="min-w-0 sm:flex-1">
          <InputPrefix><EnvelopeSimple /></InputPrefix>
          <InputField type="email" placeholder="Enter your email address" />
        </InputRoot>
        <Button className="w-full sm:w-auto">Send invite</Button>
      </div>
    </Field>
  </FormSection>
</DialogContent>
```

## Feedback

A rating prompt: a single-select [ToggleGroup](https://www.koalaui.com/docs/components/toggle-group.md) for the score and a [Textarea](https://www.koalaui.com/docs/components/textarea.md) with a live character count. The primary action stays disabled until a score is picked, and the split footer carries a help link on the left.

```tsx
const [rating, setRating] = React.useState("")

<DialogContent size="sm">
  <DialogIcon><Star /></DialogIcon>
  <DialogHeader>
    <DialogTitle>Help us improve!</DialogTitle>
    <DialogDescription>Share your experience with us so we can make it better.</DialogDescription>
  </DialogHeader>

  <div className="grid gap-4">
    <FieldGroup required>
      <FieldGroupLabel>Rate your experience</FieldGroupLabel>
      <ToggleGroup type="single" size="sm" value={rating} onValueChange={setRating} className="w-full">
        {["1", "2", "3", "4", "5"].map((n) => (
          <ToggleGroupItem key={n} value={n} aria-label={`${n} out of 5`} className="flex-1">{n}</ToggleGroupItem>
        ))}
      </ToggleGroup>
    </FieldGroup>
    <div className="grid gap-2">
      <TextareaLabel htmlFor="feedback-message">Your message</TextareaLabel>
      <TextareaRoot>
        <TextareaField id="feedback-message" placeholder="Write your message here..." rows={4} maxLength={500} showCount />
      </TextareaRoot>
    </div>
  </div>

  <DialogFooter className="sm:items-center sm:justify-between">
    {/* help link on the left */}
    <div className="flex flex-col-reverse gap-2 sm:flex-row">
      <DialogClose asChild><Button variant="outline">Cancel</Button></DialogClose>
      <DialogClose asChild><Button disabled={!rating}>Submit</Button></DialogClose>
    </div>
  </DialogFooter>
</DialogContent>
```

## Two-factor (2FA)

A verification flow: a live [QR Code](https://www.koalaui.com/docs/components/qr-code.md) on a nested surface (so it takes a **concentric** radius one step inside the dialog) above an [OTP Input](https://www.koalaui.com/docs/components/otp-input.md). `Verify` enables only once all six digits are in.

```tsx
const [code, setCode] = React.useState("")

<DialogContent size="sm" onOpenAutoFocus={(e) => e.preventDefault()}>
  <DialogIcon><ShieldCheck /></DialogIcon>
  <DialogHeader>
    <DialogTitle>Enable two-factor authentication</DialogTitle>
    <DialogDescription>
      Scan the QR code with your authentication app, then enter the 6-digit code to verify and activate 2FA.
    </DialogDescription>
  </DialogHeader>

  {/* Concentric radius: rounded-lg panel nested inside the rounded-xl content */}
  <div className="flex items-center justify-center rounded-lg border border-border bg-accent p-6">
    <QRCode value="otpauth://totp/Koala:jordi?secret=...&issuer=Koala" level="Q"
      size={176} margin={2} className="rounded-md p-3 shadow-xs" />
  </div>

  <OTPInput label="Introduce code" required size="sm" length={6} autoFocus value={code} onChange={setCode} />

  <DialogFooter className="sm:items-center sm:justify-between">
    {/* help link on the left */}
    <div className="flex flex-col-reverse gap-2 sm:flex-row">
      <DialogClose asChild><Button variant="outline">Cancel</Button></DialogClose>
      <DialogClose asChild><Button disabled={code.length < 6}>Verify</Button></DialogClose>
    </div>
  </DialogFooter>
</DialogContent>
```

## Selectable cards

A single choice rendered as cards rather than bare dots: wrap each option in a `<label>` around a [RadioGroup](https://www.koalaui.com/docs/components/radio-group.md) item and let CSS `:has([data-state=checked])` light the selected card. The whole card is the hit target.

```tsx
const [theme, setTheme] = React.useState("light")

const THEMES = [
  { value: "light", title: "Light theme", hint: "For a clean and minimal look.", icon: Sun },
  { value: "dark", title: "Dark theme", hint: "Perfect for working in low-light conditions.", icon: Moon },
  { value: "system", title: "System", hint: "Automatically adapts to your device's settings.", icon: Desktop },
]

<DialogContent size="sm">
  <DialogIcon><Palette /></DialogIcon>
  <DialogHeader>
    <DialogTitle>Change theme</DialogTitle>
    <DialogDescription>Choose your preferred theme to customize your experience.</DialogDescription>
  </DialogHeader>

  <FieldGroup required>
    <FieldGroupLabel>Choose your theme</FieldGroupLabel>
    <RadioGroup value={theme} onValueChange={setTheme}>
      {THEMES.map(({ value, title, hint, icon: Icon }) => (
        <RadioCard key={value} value={value} icon={<Icon />}>
          <RadioCardTitle>{title}</RadioCardTitle>
          <RadioCardDescription>{hint}</RadioCardDescription>
        </RadioCard>
      ))}
    </RadioGroup>
  </FieldGroup>

  <DialogFooter className="sm:items-center sm:justify-between">
    {/* help link on the left */}
    <div className="flex flex-col-reverse gap-2 sm:flex-row">
      <DialogClose asChild><Button variant="outline">Cancel</Button></DialogClose>
      <DialogClose asChild><Button>Apply</Button></DialogClose>
    </div>
  </DialogFooter>
</DialogContent>
```

## Announcement

A leading `DialogIcon`, a hero media band, and a split footer: a helper on the left with actions on the right via `className="sm:justify-between"` (the footer's top divider is on by default).

```tsx
<DialogContent>
  <DialogIcon><Megaphone /></DialogIcon>
  <DialogHeader>
    <DialogTitle>Mobile Version Now Available!</DialogTitle>
    <DialogDescription>Access your dashboard anytime, anywhere.</DialogDescription>
  </DialogHeader>

  {/* hero media + body copy */}
  <div className="flex aspect-[16/10] flex-col items-center justify-center gap-3 rounded-lg bg-gradient-to-br from-accent to-muted text-muted-foreground">
    <DeviceMobile className="size-12" />
    <span className="text-sm font-medium">Dashboard on mobile</span>
  </div>
  <p className="text-pretty text-sm text-muted-foreground">
    Enjoy a seamless experience on the go with our mobile-friendly dashboard.
  </p>

  {/* Split footer: helper left, actions right (top divider is the default) */}
  <DialogFooter className="sm:items-center sm:justify-between">
    <span className="flex items-center gap-1.5 text-sm text-muted-foreground">
      <Info className="size-4" /> Need some help?
    </span>
    <div className="flex flex-col-reverse gap-2 sm:flex-row">
      <Button variant="outline">Cancel</Button>
      <Button>Create</Button>
    </div>
  </DialogFooter>
</DialogContent>
```

## Multi-step (wizard)

For create flows that span several screens, put a vertical [Stepper](https://www.koalaui.com/docs/components/stepper.md) in a left rail and swap the active step's form on the right. The Stepper owns no state: drive its `value` from your own step state. Wrap the body in a `Stagger` keyed by step so each screen cascades in, and give it a `min-h` so the dialog holds its height between steps.

```tsx
const [step, setStep] = React.useState(1)

<DialogContent size="lg" density="compact">
  <DialogHeader>
    <DialogTitle>Create project</DialogTitle>
    <DialogDescription>Set up your workspace in a few steps.</DialogDescription>
  </DialogHeader>

  <div className="grid grid-cols-[auto_1fr] items-start gap-4 sm:gap-8">
    {/* Left rail: vertical stepper with solid, brand-filled indicators and no connectors. */}
    <Stepper value={step} onValueChange={setStep} orientation="vertical"
      variant="solid" density="comfortable" className="pr-2">
      {STEPS.map((s, i) => (
        <StepperItem key={s.title} step={i + 1} disabled={i + 1 > step}
          className="[&:not(:last-child)]:min-h-[2.75rem]">
          <StepperTrigger className="items-center">
            <StepperIndicator />
            <StepperTitle className="font-semibold">{s.title}</StepperTitle>
          </StepperTrigger>
        </StepperItem>
      ))}
    </Stepper>

    {/* key={step} replays the entrance per step; min-h sets the dialog's height. */}
    <Stagger key={step} className="grid min-h-[18rem] content-start gap-3">
      {step === 1 && <ProjectFields />}
      {step === 2 && <InviteFields />}
      {step === 3 && <ReviewSummary />}
    </Stagger>
  </div>

  <DialogFooter className="sm:justify-between">
    <Button variant="ghost" disabled={step === 1} onClick={() => setStep((s) => s - 1)}>
      <ArrowLeft /> Back
    </Button>
    {step === STEPS.length
      ? <Button onClick={create} loading={submitting}>Create project</Button>
      : <Button onClick={() => setStep((s) => s + 1)}>Next <ArrowRight /></Button>}
  </DialogFooter>
</DialogContent>
```

## Upgrade / Subscribe

An in-app upsell: a two-column dialog pairing edge-to-edge cover art with a benefits list and a single brand CTA. It composes the same `dialogVariants` recipe, cancelling the content padding and gap (`p-0 gap-0`) and splitting into two columns; use `size="xl"`. Drag the frame narrow to watch the columns stack.

```tsx
const BENEFITS = [
  { icon: LockKey, title: "Internal comments", description: "Separate internal team discussion from external stakeholder comments in shares." },
  { icon: FolderLock, title: "Restricted projects", description: "Create projects that are only accessible to you and the specific people you invite." },
  { icon: UsersThree, title: "Up to 15 members", description: "Add more people to your account for maximum collaboration on every project." },
  { icon: Cloud, title: "3 TB storage", description: "Even more room to store your media and assets, all within your workspace." },
]

<DialogContent size="xl" className="gap-0 overflow-hidden p-0 sm:grid-cols-2">
  {/* Left: cover art (banner on mobile, fills the column on sm+) */}
  <div className="relative aspect-[16/10] w-full sm:aspect-auto sm:h-full">
    <img src={cover} alt="" aria-hidden className="absolute inset-0 size-full object-cover" />
    <div aria-hidden className="pointer-events-none absolute inset-0 ring-1 ring-inset ring-black/10" />
  </div>

  {/* Right: benefits + CTA */}
  <div className="flex flex-col gap-6 p-6 sm:p-8">
    <DialogIcon><Crown /></DialogIcon>
    <DialogHeader className="gap-2 text-left">
      <DialogTitle className="text-xl leading-snug">
        Upgrade to <span className="text-brand">Team</span>
      </DialogTitle>
      <DialogDescription>Everything your team needs to collaborate, with room to grow.</DialogDescription>
    </DialogHeader>

    {/* Minimal divided list: a Divider between each feature */}
    <div role="list" className="flex flex-col gap-4">
      {BENEFITS.map(({ icon: Icon, title, description }, i) => (
        <React.Fragment key={title}>
          {i > 0 && <Divider />}
          <div role="listitem" className="flex gap-3.5">
            <Icon weight="bold" aria-hidden className="mt-0.5 size-5 shrink-0 text-brand" />
            <div className="flex flex-col gap-1">
              <p className="text-sm font-semibold leading-none text-foreground">{title}</p>
              <p className="text-sm text-pretty text-muted-foreground">{description}</p>
            </div>
          </div>
        </React.Fragment>
      ))}
    </div>

    <div className="mt-auto flex flex-col gap-3">
      <DialogClose asChild>
        <Button size="lg" className="w-full"><Sparkle weight="bold" /> Subscribe to Team</Button>
      </DialogClose>
    </div>
  </div>
</DialogContent>
```

## Sizes

`size` on `DialogContent` caps the *max width*; the dialog still shrinks to fit narrow viewports, so it is a ceiling, not a fixed width. The default `md` (30rem) is the width nearly every dialog should use; reach for the others only when one genuinely needs less or more:

- `sm`: `max-w-sm` (384px). Confirmations and short prompts.
- `md`: `max-w-[30rem]` (480px). The **default**; most forms and messages.
- `lg`: `max-w-2xl` (672px). Denser forms with side-by-side fields.
- `xl`: `max-w-4xl` (896px). Rich content: tables, multi-column layouts.
- `media`: a 16:9 frame as wide as the viewport allows while it still fits the height. A video lightbox: no padding, no header or footer, the embedded player fills it, and the close button turns light over the footage. Pair it with `mobile="center"` (a video is not a sheet) and give it a visually hidden `DialogTitle`.

The previews below are the real `DialogContent` rendered inline so you can compare the widths directly:

```tsx
<DialogContent size="sm">…</DialogContent>
<DialogContent size="md">…</DialogContent>  {/* default, 30rem */}
<DialogContent size="lg">…</DialogContent>
<DialogContent size="xl">…</DialogContent>
```

```tsx
<Dialog>
  <DialogTrigger asChild>
    <Button variant="outline">Watch the tour</Button>
  </DialogTrigger>
  <DialogContent size="media" mobile="center">
    <DialogTitle className="sr-only">Product tour</DialogTitle>
    <iframe
      src="https://www.youtube-nocookie.com/embed/Dg3I9e8wUM0?autoplay=1"
      title="Product tour"
      allow="autoplay; encrypted-media; picture-in-picture"
      allowFullScreen
    />
  </DialogContent>
</Dialog>
```

## Unsaved changes

Behavior that needs a real trigger, so this one stays interactive. Use a controlled `open` / `onOpenChange` pair and intercept `onInteractOutside` + `onEscapeKeyDown` to guard against accidental data loss. When the form is dirty, every close attempt (the ✕, the scrim, Escape, or Cancel) opens a nested confirmation dialog instead.

```tsx
"use client"

const [open, setOpen] = React.useState(false)
const [discardOpen, setDiscardOpen] = React.useState(false)
const isDirty = title.trim().length > 0 || body.trim().length > 0

function attemptClose() {
  if (isDirty) setDiscardOpen(true)
  else setOpen(false)
}

{/* Main dialog */}
<Dialog open={open} onOpenChange={(next) => (next ? setOpen(true) : attemptClose())}>
  <DialogTrigger asChild>
    <Button variant="outline">New post</Button>
  </DialogTrigger>
  <DialogContent
    onInteractOutside={(e) => { e.preventDefault(); attemptClose() }}
    onEscapeKeyDown={(e) => { e.preventDefault(); attemptClose() }}
  >
    {/* form fields */}
    <DialogFooter>
      <Button variant="ghost" onClick={attemptClose}>Cancel</Button>
      <Button onClick={save}>Publish</Button>
    </DialogFooter>
  </DialogContent>
</Dialog>

{/* Discard confirmation */}
<Dialog open={discardOpen} onOpenChange={setDiscardOpen}>
  <DialogContent size="sm" showClose={false}>
    <DialogHeader>
      <DialogTitle>Discard changes?</DialogTitle>
      <DialogDescription>
        You have unsaved content. Closing now will permanently lose your changes.
      </DialogDescription>
    </DialogHeader>
    <DialogFooter>
      <Button variant="ghost" onClick={() => setDiscardOpen(false)}>Keep editing</Button>
      <Button variant="destructive" onClick={confirmDiscard}>Discard changes</Button>
    </DialogFooter>
  </DialogContent>
</Dialog>
```

## FAQ

### When should I reach for Dialog versus Drawer or Popover?

Use Dialog for a focused, blocking task that needs a focus trap and scrim, like a confirmation, a short form, or terms you must accept. Reach for Drawer when the content is a side panel or a long task on mobile, and Popover for a small non-modal surface anchored to a trigger that does not lock the page.

### What does the size prop on DialogContent actually control?

size sets the max width only (sm is max-w-sm, md is 30rem/480px by default, lg is max-w-2xl, xl is max-w-4xl); md is the width nearly every dialog should use, and the others are for when one genuinely needs less or more. The dialog still shrinks to fit narrow viewports, so it is a ceiling, not a fixed width. Height always hugs the content, so for long bodies scroll an inner max-h container rather than the whole dialog.

### Does the footer have a divider by default, and how do I turn it off?

Yes. DialogFooter carries a full-bleed top divider by default (a 12px action band flush to the dialog's edges), the canonical dialog look. Pass bordered={false} for a borderless footer that just sits below the body, and add className='sm:justify-between' when you want a helper on the left with the actions on the right.

### How do I compose the named parts, and why import them instead of using dot notation?

Nest DialogHeader (holding DialogTitle and DialogDescription) and DialogFooter inside DialogContent, with DialogTrigger and DialogClose using asChild to wrap your own buttons. Each part is a named export rather than Dialog.Header because dot-notation accessors break the server-to-client boundary in React Server Components.

### How do I land focus on the first field instead of the dialog container when it opens?

Radix moves focus onto the content container on open for screen-reader announcement, so pass onOpenAutoFocus to DialogContent, call e.preventDefault(), and focus your input ref instead. Escape and clicking the scrim close the dialog for free, and a focus trap plus scroll lock come from Radix.

### Why does Escape or clicking outside still close my dialog when I have unsaved changes?

By default those dismissals are uncontrolled, so wire a controlled open and onOpenChange pair and intercept onInteractOutside and onEscapeKeyDown, calling e.preventDefault() to route every close attempt through your guard. For an explicit-choice confirmation, also set showClose={false} so there is no quiet escape hatch in the top-right corner.

---

<!-- https://www.koalaui.com/docs/components/divider.md -->

# Divider

A thin rule that separates content, optionally with a centered label. Smart by default: it collapses when it would be orphaned, so a dynamic list never leaves a rule at the edge or over an empty state.

```tsx
<Divider static />
<Divider static variant="dashed" />
<Divider static>OR</Divider>
<Divider static variant="gradient" />
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add divider
```

Manual: run `npm install radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/divider/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

```tsx title="usage.tsx"
import { Divider } from "@/components/ui/divider"

export function Example() {
  return (
    <div>
      <p>Above</p>
      <Divider />
      <p>Below</p>
    </div>
  )
}
```

## Smart by default

A divider only earns its space when it actually separates two things. By default it auto-collapses when it would be orphaned: at the very start or end of a group, doubled against another divider, or stranded next to content that filtered or rendered away. So you can drop a `<Divider />` after every row without guarding it: a dynamic list never shows a rule at the edge, and the empty state stays clean. Toggle the rows below, then flip `static` to switch the guarantee off and watch the orphaned trailing rule reappear.

```tsx
{sections.map((s) =>
  show[s.id] && (
    <Fragment key={s.id}>
      <Row {...s} />
      {/* one after every row; smart-collapse drops the orphans */}
      <Divider />
    </Fragment>
  ),
)}
```

The contract is the idiomatic one: absent content renders `null` (or carries the `hidden` attribute), so a neighbour that is gone is gone from the layout too. Where the dividers are the content themselves (a showcase), or a leading or trailing rule is intentional, pass `static` to opt out.

## Variants

Four stroke styles. `solid`, `dashed`, and `dotted` ride the `border-*` utilities; `gradient` fades a hairline out at both ends for a softer separation between large surfaces. The gallery pins each rule with `static` so every stroke shows at once; on its own a Divider is smart by default.

```tsx
<Divider static variant="solid" />
<Divider static variant="dashed" />
<Divider static variant="dotted" />
<Divider static variant="gradient" />
```

## With label

Pass children to render a centered label between two lines, ideal for an “OR” separator in auth forms. The label is text or an icon; the flanking lines are `aria-hidden` so the a11y tree still exposes exactly one separator.

```tsx
<Divider static>OR</Divider>
<Divider static variant="dashed">Continue with</Divider>
<Divider static variant="gradient">
  <GoogleLogo /> Google
</Divider>
```

## Label position

`labelPosition` sets where the label sits. `start` and `end` drop the line on that side so the label hugs the edge.

```tsx
<Divider static labelPosition="start">Start</Divider>
<Divider static labelPosition="center">Center</Divider>
<Divider static labelPosition="end">End</Divider>
```

## Vertical

Set `orientation="vertical"` to separate inline content. The divider stretches to the height of its container, so place it in a flex row. Vertical dividers don't take a label.

```tsx
<div className="flex h-5 items-center gap-4">
  <span>Docs</span>
  <Divider orientation="vertical" />
  <span>Guides</span>
  <Divider orientation="vertical" variant="dashed" />
  <span>API</span>
  <Divider orientation="vertical" variant="gradient" />
  <span>Blog</span>
</div>
```

## FAQ

### What happens to a divider with no content on one side?

By default a Divider is smart: it auto-collapses when it would be orphaned, at the very start or end of its group, doubled against another divider, or stranded next to content that filtered or rendered away. So you can place a divider after every item in a dynamic list and never end with a trailing rule or one floating over an empty state. The contract is the idiomatic one: absent content renders `null` (or carries the `hidden` attribute), so a neighbour that is gone is gone from the layout.

### How do I keep a divider that the smart collapse hides?

Pass `static`. It opts the divider out of the auto-collapse so the rule always paints, which is what you want where the dividers are the content themselves (a showcase of stroke styles), or where a leading or trailing rule is intentional.

### What is the difference between the gradient variant and the solid, dashed, and dotted ones?

The `solid`, `dashed`, and `dotted` variants ride the `border-*` utilities so they track the `--border` token across themes. The `gradient` variant drops the hard border and paints a one-pixel hairline that fades to transparent at both ends, which reads softer between large surfaces.

### How do I add an OR label between two lines?

Pass children to the Divider, for example `<Divider>OR</Divider>`. The label is text or an icon, and the two flanking lines are rendered `aria-hidden` so the accessibility tree still exposes exactly one separator.

### What does labelPosition do?

`labelPosition` sets where a label sits: `center` (default) keeps lines on both sides, while `start` and `end` drop the line on that side so the label hugs the edge. It is ignored when there are no children.

### Can a vertical divider have a label?

No. Labels are a horizontal-only affordance, so a vertical divider ignores children. Set `orientation="vertical"` and place it inside a flex row, since it stretches to the height of its container.

### When should I use the decorative prop?

Pass `decorative` when the rule is purely visual and carries no structural meaning. It swaps the Radix Separator role for `role="none"` so it is removed from the accessibility tree.

---

<!-- https://www.koalaui.com/docs/components/dock.md -->

# Dock

A floating rail of icon controls that morphs, in place, into a labelled menu with drill-down layers. One box animates its own width, height and corner, so the rail becomes the menu instead of opening a second surface.

```tsx
<Dock aria-label="Koala workspace" trigger="hover">
  <DockItem icon={<SquaresFour weight="bold" />} label="Components" shortcut="⌘1" active />
  <DockItem icon={<Browsers weight="bold" />} label="Templates" shortcut="⌘2" />
  <DockItem icon={<Flask weight="bold" />} label="Playground" shortcut="⌘3" />

  <DockGroup icon={<Palette weight="bold" />} label="Appearance">
    <DockLabel>Theme</DockLabel>
    <DockItem icon={<Sun weight="bold" />} label="Light" active />
    <DockItem icon={<Coffee weight="bold" />} label="Cream" />
    <DockItem icon={<Moon weight="bold" />} label="Dark" />
    <DockItem icon={<MoonStars weight="bold" />} label="Moonlight" />
  </DockGroup>

  <DockGroup icon={<Buildings weight="bold" />} label="Workspace">
    <DockItem icon={<UsersThree weight="bold" />} label="Members" />
    <DockItem icon={<ChartLine weight="bold" />} label="Usage" />
    <DockItem icon={<CreditCard weight="bold" />} label="Billing" />
    <DockSeparator />
    <DockItem icon={<Key weight="bold" />} label="API keys" />
  </DockGroup>

  <DockExpander />
</Dock>
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add dock
```

Manual: run `npm install radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/dock/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

```tsx title="usage.tsx"
import {
  Dock,
  DockItem,
  DockGroup,
  DockLabel,
  DockSeparator,
  DockExpander,
} from "@/components/ui/dock"

<Dock aria-label="Workspace">
  <DockItem icon={<SquaresFour weight="bold" />} label="Components" shortcut="⌘1" active />
  <DockGroup icon={<Palette weight="bold" />} label="Appearance">
    <DockLabel>Theme</DockLabel>
    <DockItem icon={<Sun weight="bold" />} label="Light" />
  </DockGroup>
  <DockExpander />
</Dock>
```

The label is a prop, not children, because the dock renders it twice: as the tooltip on the collapsed icon, and as the row's text in the panel. One source, two shapes.

## Variants

Floating is the default: the house's elevated popover surface, because a dock is chrome and chrome should inherit the page's theme rather than punch a slab of the opposite colour through it. Solid is the inverted slab, for a dock that has to hold its own over a photograph, a canvas or a video. It flips foreground and background rather than hardcoding black, so it reads dark on the light themes and light on the dark ones.

```tsx
{/* floating (default) */}
<Dock aria-label="Floating rail">…</Dock>

{/* solid */}
<Dock aria-label="Solid rail" variant="solid">…</Dock>

{/* both shapes: pass `expanded` to hold the panel open */}
<Dock aria-label="Floating panel" expanded>…</Dock>
<Dock aria-label="Solid panel" variant="solid" expanded>…</Dock>
```

## Sizes and density

`size` sizes the rail, and only the rail. It is not the page's comfortable/compact knob, because a floating control bar that shrinks to form-compact becomes hard to hit. Every step is built on one identity, 4px padding + half the icon button = the rail's corner, so the buttons come out as true circles and concentric inside the pill at all three sizes. The 4px is the panel's own padding, so the rail and the menu it opens into read at one scale. The panel is a menu, so it follows `density` like every DropdownMenu on the page: the same 36px or 32px rows, row for row.

```tsx
<Dock size="sm">…</Dock>
<Dock size="md">…</Dock>  {/* default */}
<Dock size="lg">…</Dock>

{/* the panel: from the nearest DensityProvider, or per instance */}
<Dock density="comfortable" expanded>…</Dock>
<Dock density="compact" expanded>…</Dock>
```

## Layers

A `DockGroup` is a drill-down. Opening it replaces the panel's contents with a “Back” row and its children, and the box resizes to fit: no second surface, no popup beside a popup. Groups nest, so a group inside a group is one layer deeper. Press `Esc` to step back one layer at a time.

```tsx
<Dock aria-label="Canvas" variant="solid" defaultExpanded closeOnSelect={false}>
  <DockItem icon={<Selection weight="bold" />} label="Select" shortcut="V" active />
  <DockItem icon={<FrameCorners weight="bold" />} label="Frame" shortcut="F" />
  <DockItem icon={<TextT weight="bold" />} label="Text" shortcut="T" />

  <DockGroup icon={<Export weight="bold" />} label="Export">
    <DockLabel>Format</DockLabel>
    <DockItem icon={<FilePng weight="bold" />} label="PNG" active />
    <DockItem icon={<FileSvg weight="bold" />} label="SVG" />
    <DockItem icon={<FilePdf weight="bold" />} label="PDF" />
    <DockSeparator />

    {/* a group inside a group: one layer deeper */}
    <DockGroup icon={<ArrowsOutSimple weight="bold" />} label="Scale">
      <DockItem icon={<Ruler weight="bold" />} label="1x" active />
      <DockItem icon={<Ruler weight="bold" />} label="2x" />
      <DockItem icon={<Ruler weight="bold" />} label="3x" />
    </DockGroup>
  </DockGroup>
</Dock>
```

## Captions and shortcuts

`DockLabel` sorts a long panel into topics, and `shortcut` puts the menu's gray key chip at the end of a row, exactly where DropdownMenuShortcut sits. Both live in the panel only: the rail has no room for a word, so while the dock is collapsed the shortcut rides in the tooltip beside the label instead.

```tsx
<Dock aria-label="Editor menu" expanded>
  <DockLabel>Insert</DockLabel>
  <DockItem icon={<FrameCorners weight="bold" />} label="Frame" shortcut="F" />
  <DockItem icon={<TextT weight="bold" />} label="Text" shortcut="T" />
  <DockItem icon={<Shapes weight="bold" />} label="Shape" shortcut="R" />
  <DockSeparator />
  <DockLabel>Canvas</DockLabel>
  <DockItem icon={<Ruler weight="bold" />} label="Rulers" shortcut="⇧R" active />
  <DockItem icon={<SquaresFour weight="bold" />} label="Grid" shortcut="⌘G" />
</Dock>
```

## Trigger

`trigger="click"` is the default and the right pick on touch. `trigger="hover"` expands when the pointer lands on the expander and collapses shortly after it leaves the dock. The grace period is there so crossing a 2px gap on the way to a row never dismisses the thing you are reaching for.

```tsx
<Dock aria-label="Opens on click">…</Dock>

<Dock aria-label="Opens on hover" trigger="hover">…</Dock>
```

## States

`active` marks the current destination in ink, not colour: a faint chip, a heavier label and a full-strength glyph among muted ones (it also sets `aria-current="page"`). `disabled` takes a control out of the roving focus, and `DockSeparator` is axis-aware: a vertical tick in the rail, a horizontal rule in the panel.

```tsx
<Dock aria-label="States">
  <DockItem icon={<Gauge weight="bold" />} label="Overview" shortcut="⌘1" active />
  <DockItem icon={<ChartLine weight="bold" />} label="Traffic" shortcut="⌘2" />
  <DockItem icon={<Lightning weight="bold" />} label="Realtime (Pro)" disabled />
  <DockSeparator />
  <DockItem icon={<Export weight="bold" />} label="Export report" />
  <DockExpander />
</Dock>
```

## Links

Pass `asChild` with your own element and the dock renders its icon and label inside it, so a nav dock can use `next/link` and keep client-side routing.

```tsx
<Dock aria-label="Documentation" expanded>
  <DockItem icon={<SquaresFour weight="bold" />} label="Components" asChild active>
    <Link href="/docs/components/dock" />
  </DockItem>
  <DockItem icon={<Swatches weight="bold" />} label="Colors" asChild>
    <Link href="/docs/foundations/colors" />
  </DockItem>
</Dock>
```

## Controlled

Drive the shape yourself with `expanded` / `onExpandedChange`, to open the dock from a keyboard shortcut, or to keep it open while a tour points at it.

```tsx
const [expanded, setExpanded] = React.useState(false)

<Dock
  aria-label="Controlled dock"
  expanded={expanded}
  onExpandedChange={setExpanded}
>
  …
  <DockExpander />
</Dock>
```

## API reference

### Dock

The morphing box and the roving-focus root (Radix `Toolbar.Root`, so it forwards `dir`, `loop` and the rest). Takes `variant` (floating · solid), `size` (sm · md · lg, the rail), `density` (comfortable · compact, the panel; defaults to the nearest DensityProvider), `expanded` / `defaultExpanded` / `onExpandedChange`, `trigger` (click · hover), `closeOnSelect`, `tooltipPlacement`, and `static` to drop the press-scale on the rail icons (panel rows never scale, like menu rows). The arrow-key axis follows the shape: horizontal in the rail, vertical in the panel.

### DockItem

A destination or an action. Takes `icon`, `label` (required), `shortcut`, `active`, `disabled`, `onSelect`, and `asChild` to hand the control to a link. Collapsed it is an icon with the label as its tooltip; expanded it is a labelled row.

### DockGroup

A drill-down layer. Takes `icon`, `label`, `value` (its identity in the open path, defaulting to the label), `backLabel` (default `"Back"`) and `disabled`. Its children are the rows of its layer; pressing it from the rail expands the dock straight into that branch.

### DockLabel · DockExpander · DockSeparator

`DockLabel` is a caption over a run of rows (panel only). `DockExpander` is the control that turns the rail into the panel (`label`, or your own `children` in place of the menu glyph); it exists only in the rail, because once the labels are on screen there is nothing left for it to reveal. `DockSeparator` is the axis-aware hairline (Radix `Toolbar.Separator`).

## FAQ

### How is this different from Toolbar?

Toolbar is a band of controls: it stays one shape and groups icon buttons, toggles and dropdown triggers. Dock is a navigation surface that changes shape: it collapses to a rail of icons and expands, in place, into a labelled menu with drill-down layers. Both are built on Radix Toolbar, so they share the roving focus and arrow-key model; reach for Toolbar to act on something (a format bar, a tool rail) and for Dock to go somewhere.

### Why does the box animate instead of opening a menu next to it?

Because the rail and the menu are the same object. The root measures its own content with a ResizeObserver and writes the next width/height, then CSS tweens between them behind overflow-hidden, so the incoming layer is revealed by a box that is still growing. A popup beside the rail would be a second surface to track; this is one.

### Why is the label a prop instead of children?

Because the dock renders it twice. Collapsed, the label is the tooltip on the icon (and the button's aria-label); expanded, it is the row's text. Passing it once as a prop keeps those two in sync and is what lets the same declarative tree describe both shapes.

### When should I use solid instead of floating?

When the dock sits over something that is not your page: a photograph, a video, a map, a design canvas. Floating inherits the page's popover surface and is the right default everywhere else. Solid flips foreground and background rather than hardcoding black, so it stays legible in all four themes instead of becoming a dark hole on a dark page.

### How deep can groups nest?

As deep as you like. A DockGroup opens a layer, and a group inside it opens the next one; the Back row always returns to the parent. Only the layer on screen is mounted, so a branch you have not opened costs nothing.

### How do I close it?

Click outside, press Escape (which steps back one layer at a time before it closes), or choose an item, and closeOnSelect is on by default. With trigger="hover" it also collapses shortly after the pointer leaves, on a short grace period so a 2px gap on the way to a row never dismisses it.

### Is it keyboard accessible?

Yes. It is a Radix Toolbar: the whole dock is a single Tab stop and arrow keys move between controls, on the axis that matches the current shape. Opening a layer moves focus to its first row, but only when you drove the change, so a hover-driven expand never yanks focus away from what you were doing.

### Does it follow the page's comfortable/compact density?

The panel does, the rail does not. The panel is a menu, so its rows follow density exactly like DropdownMenu's (36px comfortable, 32px compact), from the nearest DensityProvider or the density prop. The rail keeps its own size axis (sm / md / lg), the same call as Toolbar, because a floating control bar that shrinks to form-compact becomes hard to hit.

### How does the panel relate to DropdownMenu?

It is the same menu, row for row: 4px of surface padding, 8px row padding, a 20px muted icon, a 500-weight label, the gray shortcut chip and the caret on the same 12px edge line, rounded-lg over rounded-md. Only the behaviour differs: the dock's panel grows out of the rail it replaces. If you want the drill-down from an ordinary trigger instead, use DropdownMenu with submenu="navigation".

### Does it respect reduced motion?

Yes. Under prefers-reduced-motion: reduce the box resizes instantly instead of tweening, the layer swap does not animate, and the tactile press-scale is dropped, and every functional state (hover, active chip, focus ring) stays exactly as it is.

### Where should I put it on the page?

Position it yourself, the way you would any floating surface: typically fixed, bottom-centered. The dock grows from its own top-left corner, so anchoring it by bottom makes the panel open upward, which is what you want above a page's content.

---

<!-- https://www.koalaui.com/docs/components/drawer.md -->

# Drawer

A panel that slides in from any edge of the screen. Built on Radix Dialog for focus trap, scroll lock and a11y; tuned for mobile with full-bleed side panels, a bottom-sheet grab handle, and swipe-to-dismiss.

```tsx
<Drawer>
  <DrawerTrigger asChild>
    <Button>Open drawer</Button>
  </DrawerTrigger>
  <DrawerContent side="right">
    <DrawerHeader>
      <DrawerTitle>Notifications</DrawerTitle>
      <DrawerDescription>You're all caught up.</DrawerDescription>
    </DrawerHeader>
    <DrawerBody>{/* … */}</DrawerBody>
    <DrawerFooter>
      <DrawerClose asChild>
        <Button variant="ghost">Close</Button>
      </DrawerClose>
      <Button>Mark all read</Button>
    </DrawerFooter>
  </DrawerContent>
</Drawer>
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add drawer
```

Manual: run `npm install radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/drawer/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

```tsx title="usage.tsx"
import {
  Drawer, DrawerTrigger, DrawerContent, DrawerHeader,
  DrawerBody, DrawerFooter, DrawerTitle, DrawerDescription, DrawerClose,
} from "@/components/ui/drawer"
import { Button } from "@/components/ui/button"

export function Example() {
  return (
    <Drawer>
      <DrawerTrigger asChild>
        <Button>Open drawer</Button>
      </DrawerTrigger>
      <DrawerContent side="right">
        <DrawerHeader>
          <DrawerTitle>Notifications</DrawerTitle>
          <DrawerDescription>You're all caught up.</DrawerDescription>
        </DrawerHeader>
        <DrawerBody>{/* … */}</DrawerBody>
        <DrawerFooter>
          <DrawerClose asChild>
            <Button variant="ghost">Close</Button>
          </DrawerClose>
          <Button>Mark all read</Button>
        </DrawerFooter>
      </DrawerContent>
    </Drawer>
  )
}
```

## Sides

`side` on `DrawerContent` picks the edge the panel slides from: `top`, `right` (default), `bottom`, or `left`. Top and bottom render as sheets with a grab handle; left and right as full-height panels. Every variant animates with the dedicated `ease-drawer` curve.

```tsx
<DrawerContent side="top">…</DrawerContent>
<DrawerContent side="right">…</DrawerContent>  {/* default */}
<DrawerContent side="bottom">…</DrawerContent>
<DrawerContent side="left">…</DrawerContent>
```

## Mobile: bottom sheet

On touch devices the bottom sheet is the native pattern. It rounds its top corners, shows a grab handle, and pads past the home-indicator safe area. It is **swipe-to-dismiss** by default. Drag the handle or header down and release past ~45% (or flick) to close, handing the exit animation back to Radix. The drag only arms after a few pixels, so taps on the rows still register, and it never starts on the scrollable body, so a drag and a scroll never fight. Disable it with `swipeToClose={false}`.

```tsx
<DrawerContent side="bottom" showClose={false}>
  <DrawerHeader>
    <DrawerTitle>Project roadmap</DrawerTitle>
    <DrawerDescription>Choose an action for this document.</DrawerDescription>
  </DrawerHeader>
  <DrawerBody>
    {actions.map((a) => (
      <DrawerClose asChild key={a.label}>
        <button className="…">{a.icon}{a.label}</button>
      </DrawerClose>
    ))}
  </DrawerBody>
</DrawerContent>
```

## Navigate inside the sheet

A bottom sheet often needs to drill into nested views (an action sheet that opens a sub-panel, a settings menu, a multi-step filter) without ever leaving the sheet. Wrap the pages in `DrawerNav` and give each a `DrawerView`: only the active view renders, it enters with a native horizontal push (from the right going forward, the left on back), and the sheet's height animates to fit it. A `DrawerNavTrigger` drills in; a `DrawerNavBack` (which renders nothing at the root, so you can place it in a shared header) pops. The stack resets when the sheet closes, and swipe-down still dismisses the whole sheet from any view.

```tsx
<DrawerContent side="bottom" showClose={false}>
  <DrawerNav defaultView="root">
    <DrawerView view="root">
      <DrawerHeader className="flex-row items-center gap-1">
        <DrawerNavBack />            {/* hidden at the root */}
        <DrawerTitle>Settings</DrawerTitle>
      </DrawerHeader>
      <DrawerBody>
        <DrawerNavTrigger view="notifications" asChild>
          <button className="…">Notifications <CaretRight /></button>
        </DrawerNavTrigger>
      </DrawerBody>
    </DrawerView>

    <DrawerView view="notifications">
      <DrawerHeader className="flex-row items-center gap-1">
        <DrawerNavBack />
        <DrawerTitle>Notifications</DrawerTitle>
      </DrawerHeader>
      <DrawerBody>{/* toggles… */}</DrawerBody>
    </DrawerView>
  </DrawerNav>
</DrawerContent>
```

## Form panel

A right-side panel is the desktop home for an edit form; it keeps the underlying page visible for context. Compose labelled [Input](https://www.koalaui.com/docs/components/input.md) parts in the `DrawerBody` and land focus on the first field with `onOpenAutoFocus`.

```tsx
<DrawerContent
  side="right"
  onOpenAutoFocus={(e) => { e.preventDefault(); nameRef.current?.focus() }}
>
  <DrawerHeader>
    <DrawerTitle>Edit profile</DrawerTitle>
    <DrawerDescription>Update your details.</DrawerDescription>
  </DrawerHeader>
  <DrawerBody>
    <div className="grid gap-4">
      <div className="grid gap-1.5">
        <InputLabel htmlFor="name">Full name</InputLabel>
        <InputRoot><InputField ref={nameRef} id="name" /></InputRoot>
      </div>
      {/* … */}
    </div>
  </DrawerBody>
  <DrawerFooter>
    <DrawerClose asChild><Button variant="ghost">Cancel</Button></DrawerClose>
    <DrawerClose asChild><Button>Save changes</Button></DrawerClose>
  </DrawerFooter>
</DrawerContent>
```

## Navigation menu

A left drawer makes a compact, off-canvas navigation menu for small screens. The `DrawerBody` scrolls independently while the header and footer stay pinned; each link is wrapped in `DrawerClose` so picking one dismisses the panel.

```tsx
<DrawerContent side="left" size="sm">
  <DrawerHeader>
    <DrawerTitle>Koala</DrawerTitle>
    <DrawerDescription>Workspace navigation</DrawerDescription>
  </DrawerHeader>
  <DrawerBody>
    <nav className="flex flex-col gap-1">
      {items.map((i) => (
        <DrawerClose asChild key={i.label}>
          <a href={i.href} className="…">{i.icon}{i.label}</a>
        </DrawerClose>
      ))}
    </nav>
  </DrawerBody>
  <DrawerFooter className="sm:justify-start">…</DrawerFooter>
</DrawerContent>
```

## Sizes

`size` caps the panel's cross-axis extent: the *width* of left/right panels and the *height* of top/bottom sheets. Panels stay full-bleed below the cap, so on a phone they fill the screen and on desktop they settle into a panel. Four steps: `sm`, `md` (default), `lg`, `xl`.

```tsx
<DrawerContent side="right" size="sm">…</DrawerContent>
<DrawerContent side="right" size="md">…</DrawerContent>  {/* default */}
<DrawerContent side="right" size="lg">…</DrawerContent>
<DrawerContent side="bottom" size="lg">…</DrawerContent>  {/* caps height */}
```

## Density

`density` tightens padding, gaps and the title for application UI; it re-provides itself to the header, body and footer so every part stays in sync. Best driven once via `DensityProvider`. See [Density](https://www.koalaui.com/docs/foundations/density.md).

```tsx
<DrawerContent side="right" density="compact">…</DrawerContent>
```

## FAQ

### When should I use a Drawer instead of a Dialog?

Both are built on Radix Dialog, but reach for a Drawer when the panel should slide in from a screen edge: a right-side edit form that keeps the page visible, a left off-canvas nav, or a mobile bottom sheet. Use Dialog for a centered, modal confirmation or focused task that does not belong to an edge.

### Drawer or Sheet?

A Drawer interrupts: it opens over the page, dims it, traps focus and closes when the task is done. For a panel that stays open next to the page for as long as it is open, like the place list over a map or the layers of a design board, use the Sheet (/docs/components/sheet): it never dims or traps, and it turns into a bottom sheet with detents on a narrow container.

### What does the side prop on DrawerContent control?

It picks the edge the panel slides from: `top`, `right` (the default), `bottom`, or `left`. Left and right render as full-height panels, while top and bottom render as sheets with a grab handle and rounded inner corners.

### How does swipe-to-dismiss work and can I turn it off?

Swipe-to-dismiss is on by default: drag the handle or header toward the closing edge and release past about 45 percent (or flick) to close, which hands the exit animation back to Radix. The drag only arms after a few pixels of slop and never starts on the scrollable DrawerBody, so taps and scrolling still work. Disable it with `swipeToClose={false}`.

### How do I land focus on a specific field when the drawer opens?

DrawerContent forwards Radix's `onOpenAutoFocus`, so call `e.preventDefault()` and focus your own element, for example the first Input via a ref. This keeps focus management accessible while overriding the default landing spot.

### How do I build nested views inside a bottom sheet?

Wrap your pages in `DrawerNav` with a `defaultView`, give each page a `DrawerView` keyed by `view`, then drill in with a `DrawerNavTrigger` and pop with a `DrawerNavBack`. Only the active view renders, it enters with a horizontal push, the sheet height animates to fit, and the stack resets when the drawer closes.

### What is the difference between the size and density props?

`size` caps the panel's cross-axis extent: the width of left and right panels and the height of top and bottom sheets, across four steps (`sm`, `md` default, `lg`, `xl`). `density` instead tightens padding, gaps, and the title for application UI and re-provides itself to the header, body, and footer; drive it once via DensityProvider.

---

<!-- https://www.koalaui.com/docs/components/dropdown-menu.md -->

# Dropdown Menu

A contextual menu that opens on trigger. Built on Radix DropdownMenu for keyboard navigation, focus management, and a11y; animated with interruptible enter/exit transitions.

```tsx
<DropdownMenu>
  <DropdownMenuTrigger asChild>
    <Button variant="outline">My account</Button>
  </DropdownMenuTrigger>
  <DropdownMenuContent className="w-56">
    <DropdownMenuLabel className="flex flex-col gap-0.5">
      <span>Alex Johnson</span>
      <span className="font-normal text-xs text-muted-foreground">
        alex@example.com
      </span>
    </DropdownMenuLabel>
    <DropdownMenuSeparator />
    <DropdownMenuGroup>
      <DropdownMenuItem>
        <UserCircle /> Profile
        <DropdownMenuShortcut>⌘P</DropdownMenuShortcut>
      </DropdownMenuItem>
      <DropdownMenuItem>
        <BellSimple /> Notifications
      </DropdownMenuItem>
      <DropdownMenuItem>
        <CreditCard /> Billing
        <DropdownMenuShortcut>⌘B</DropdownMenuShortcut>
      </DropdownMenuItem>
      <DropdownMenuItem>
        <Gear /> Settings
        <DropdownMenuShortcut>⌘,</DropdownMenuShortcut>
      </DropdownMenuItem>
    </DropdownMenuGroup>
    <DropdownMenuSeparator />
    <DropdownMenuGroup>
      <DropdownMenuItem>
        <Users /> Team
      </DropdownMenuItem>
      <DropdownMenuSub>
        <DropdownMenuSubTrigger>
          <Plus /> Invite members
        </DropdownMenuSubTrigger>
        <DropdownMenuSubContent className="w-48">
          <DropdownMenuItem>
            <Envelope /> Email
          </DropdownMenuItem>
          <DropdownMenuItem>
            <Link /> Copy invite link
          </DropdownMenuItem>
          <DropdownMenuSeparator />
          <DropdownMenuItem>
            <ChatCircle /> Send message
          </DropdownMenuItem>
        </DropdownMenuSubContent>
      </DropdownMenuSub>
    </DropdownMenuGroup>
    <DropdownMenuSeparator />
    <DropdownMenuItem variant="destructive">
      <SignOut /> Log out
      <DropdownMenuShortcut>⌘Q</DropdownMenuShortcut>
    </DropdownMenuItem>
  </DropdownMenuContent>
</DropdownMenu>
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add dropdown-menu
```

Manual: run `npm install radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/dropdown-menu/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

```tsx title="usage.tsx"
import {
  DropdownMenu, DropdownMenuTrigger, DropdownMenuContent,
  DropdownMenuItem, DropdownMenuLabel, DropdownMenuSeparator,
  DropdownMenuShortcut,
} from "@/components/ui/dropdown-menu"
import { Button } from "@/components/ui/button"
import { Gear, SignOut, UserCircle } from "@phosphor-icons/react"

export function Example() {
  return (
    <DropdownMenu>
      <DropdownMenuTrigger asChild>
        <Button variant="outline">My account</Button>
      </DropdownMenuTrigger>
      <DropdownMenuContent className="w-48">
        <DropdownMenuLabel>My account</DropdownMenuLabel>
        <DropdownMenuSeparator />
        <DropdownMenuItem>
          <UserCircle /> Profile
          <DropdownMenuShortcut>⌘P</DropdownMenuShortcut>
        </DropdownMenuItem>
        <DropdownMenuItem>
          <Gear /> Settings
          <DropdownMenuShortcut>⌘,</DropdownMenuShortcut>
        </DropdownMenuItem>
        <DropdownMenuSeparator />
        <DropdownMenuItem variant="destructive">
          <SignOut /> Log out
        </DropdownMenuItem>
      </DropdownMenuContent>
    </DropdownMenu>
  )
}
```

## Avatar trigger

Any element can be the trigger via `asChild`. A common pattern is a header avatar that opens an account menu, with the signed-in identity repeated as a non-interactive label at the top.

```tsx
<DropdownMenu>
  <DropdownMenuTrigger asChild>
    <button
      aria-label="Open user menu"
      className="cursor-pointer rounded-full outline-none ring-ring ring-offset-2 ring-offset-background transition-transform duration-fast ease-out focus-visible:ring-2 active:scale-[0.96]"
    >
      <Avatar size="md">
        <AvatarImage src="/avatar.jpg" alt="Jordi Espinosa" />
        <AvatarFallback>JE</AvatarFallback>
        <AvatarStatus variant="online" />
      </Avatar>
    </button>
  </DropdownMenuTrigger>
  <DropdownMenuContent align="end" className="w-60">
    <DropdownMenuLabel className="flex items-center gap-3 py-2 font-normal">
      <Avatar size="sm">
        <AvatarImage src="/avatar.jpg" alt="Jordi Espinosa" />
        <AvatarFallback>JE</AvatarFallback>
      </Avatar>
      <div className="min-w-0">
        <p className="truncate text-sm font-medium leading-none text-foreground">
          Jordi Espinosa
        </p>
        <p className="mt-1 truncate text-xs text-muted-foreground">jordi@koala.ui</p>
      </div>
    </DropdownMenuLabel>
    <DropdownMenuSeparator />
    <DropdownMenuGroup>
      <DropdownMenuItem>
        <UserCircle /> Profile
      </DropdownMenuItem>
      <DropdownMenuItem>
        <CreditCard /> Billing
      </DropdownMenuItem>
      <DropdownMenuItem>
        <Gear /> Settings
      </DropdownMenuItem>
    </DropdownMenuGroup>
    <DropdownMenuSeparator />
    <DropdownMenuItem variant="destructive">
      <SignOut /> Log out
    </DropdownMenuItem>
  </DropdownMenuContent>
</DropdownMenu>
```

## Icon button trigger

A ghost `iconOnly` button makes a compact “more actions” menu for table rows and card headers. Align the content to the trigger edge with `align="end"`.

```tsx
<DropdownMenu>
  <DropdownMenuTrigger asChild>
    <Button variant="ghost" iconOnly aria-label="More actions">
      <DotsThree />
    </Button>
  </DropdownMenuTrigger>
  <DropdownMenuContent align="end" className="w-44">
    <DropdownMenuItem>
      <PencilSimple /> Edit
    </DropdownMenuItem>
    <DropdownMenuItem>
      <Copy /> Duplicate
    </DropdownMenuItem>
    <DropdownMenuItem>
      <ShareNetwork /> Share
    </DropdownMenuItem>
    <DropdownMenuSeparator />
    <DropdownMenuItem variant="destructive">
      <Trash /> Delete
    </DropdownMenuItem>
  </DropdownMenuContent>
</DropdownMenu>
```

## Keyboard shortcuts

`DropdownMenuShortcut` renders right-aligned monospaced text - purely decorative; wire up the actual key binding in your app with a global listener.

```tsx
<DropdownMenu>
  <DropdownMenuTrigger asChild>
    <Button variant="outline">Edit</Button>
  </DropdownMenuTrigger>
  <DropdownMenuContent className="w-52">
    <DropdownMenuLabel>Edit</DropdownMenuLabel>
    <DropdownMenuSeparator />
    <DropdownMenuItem>
      <FilePlus /> New file
      <DropdownMenuShortcut>⌘N</DropdownMenuShortcut>
    </DropdownMenuItem>
    <DropdownMenuItem>
      <PencilSimple /> Rename
      <DropdownMenuShortcut>F2</DropdownMenuShortcut>
    </DropdownMenuItem>
    <DropdownMenuSeparator />
    <DropdownMenuSub>
      <DropdownMenuSubTrigger>
        <ShareNetwork /> Share
      </DropdownMenuSubTrigger>
      <DropdownMenuSubContent className="w-44">
        <DropdownMenuItem>
          <Envelope /> Email link
        </DropdownMenuItem>
        <DropdownMenuItem>
          <Link /> Copy link
          <DropdownMenuShortcut>⌘L</DropdownMenuShortcut>
        </DropdownMenuItem>
        <DropdownMenuSeparator />
        <DropdownMenuItem>
          <ChatCircle /> Messages
        </DropdownMenuItem>
      </DropdownMenuSubContent>
    </DropdownMenuSub>
    <DropdownMenuSeparator />
    <DropdownMenuItem variant="destructive">
      <Trash /> Delete
      <DropdownMenuShortcut>⌫</DropdownMenuShortcut>
    </DropdownMenuItem>
  </DropdownMenuContent>
</DropdownMenu>
```

## Checkbox items

```tsx
<DropdownMenu>
  <DropdownMenuTrigger asChild>
    <Button variant="outline">View</Button>
  </DropdownMenuTrigger>
  <DropdownMenuContent className="w-52">
    <DropdownMenuLabel>Appearance</DropdownMenuLabel>
    <DropdownMenuSeparator />
    <DropdownMenuCheckboxItem checked>Status bar</DropdownMenuCheckboxItem>
    <DropdownMenuCheckboxItem>Activity bar</DropdownMenuCheckboxItem>
    <DropdownMenuCheckboxItem checked>Panel</DropdownMenuCheckboxItem>
    <DropdownMenuSeparator />
    <DropdownMenuLabel>Layout</DropdownMenuLabel>
    <DropdownMenuSeparator />
    <DropdownMenuCheckboxItem checked>Word wrap</DropdownMenuCheckboxItem>
    <DropdownMenuCheckboxItem>Minimap</DropdownMenuCheckboxItem>
  </DropdownMenuContent>
</DropdownMenu>
```

## Switch items

For a setting that applies the moment it flips, pass `variant="switch"` to a checkbox item. The row draws a switch on the same line as the shortcut and the check, and the menu stays open when it is toggled (`closeOnSelect` is off for switches), so several can be set in one visit. The row is still a menu checkbox with its checked state announced; the switch is its drawing, not a second control.

```tsx
const [settings, setSettings] = useState({ desktop: true, email: false, mentions: true })

<DropdownMenu>
  <DropdownMenuTrigger asChild>
    <Button variant="outline">Notifications</Button>
  </DropdownMenuTrigger>
  <DropdownMenuContent className="w-60">
    <DropdownMenuLabel>Notify me about</DropdownMenuLabel>
    <DropdownMenuSeparator />
    <DropdownMenuCheckboxItem
      variant="switch"
      checked={settings.desktop}
      onCheckedChange={(desktop) => setSettings({ ...settings, desktop })}
    >
      <Monitor /> Desktop alerts
    </DropdownMenuCheckboxItem>
    {/* Email digest, Mentions … */}
  </DropdownMenuContent>
</DropdownMenu>
```

## Links

A row that navigates stays a menu item: wrap the link with `asChild`, so it keeps the row’s styling, arrow-key focus and Enter to activate, while Next.js client navigation and Cmd/Ctrl-click keep working. Mark a link that leaves the site with a trailing `ArrowUpRight` at `size-4`.

```tsx
import NextLink from "next/link"

<DropdownMenuContent className="w-56">
  <DropdownMenuItem asChild>
    <NextLink href="/docs"><BookOpen /> Documentation</NextLink>
  </DropdownMenuItem>
  <DropdownMenuSeparator />
  <DropdownMenuItem asChild>
    <a href="https://github.com/jespinosa19/koala-ui" target="_blank" rel="noreferrer">
      <GithubLogo /> GitHub
      <ArrowUpRight className="ml-auto size-4" />
    </a>
  </DropdownMenuItem>
</DropdownMenuContent>
```

## Descriptions

A navigation menu often needs more than a label: a title over a sentence that says where the row goes. Put both in a `DropdownMenuItemText` after the leading icon, the sentence in a `DropdownMenuItemDescription`. A described row pins its icon to the title’s line instead of centering it on the block, and the sentence steps back by color and weight at the same size, so the title keeps the hierarchy. Give the content a wider measure (`w-80`) so the sentences wrap readably. Both parts are optional: a row without them stays a plain item.

```tsx
<DropdownMenuContent className="w-80">
  <DropdownMenuItem asChild>
    <NextLink href="/docs">
      <BookOpen />
      <DropdownMenuItemText>
        Documentation
        <DropdownMenuItemDescription>
          Guides, examples and the API for every component.
        </DropdownMenuItemDescription>
      </DropdownMenuItemText>
    </NextLink>
  </DropdownMenuItem>
  {/* …more rows */}
</DropdownMenuContent>
```

## Radio items

```tsx
<DropdownMenu>
  <DropdownMenuTrigger asChild>
    <Button variant="outline">Theme</Button>
  </DropdownMenuTrigger>
  <DropdownMenuContent className="w-44">
    <DropdownMenuLabel>Theme</DropdownMenuLabel>
    <DropdownMenuSeparator />
    <DropdownMenuRadioGroup value="system">
      <DropdownMenuRadioItem value="light">
        <Sun /> Light
      </DropdownMenuRadioItem>
      <DropdownMenuRadioItem value="dark">
        <Moon /> Dark
      </DropdownMenuRadioItem>
      <DropdownMenuRadioItem value="system">
        <Monitor /> System
      </DropdownMenuRadioItem>
    </DropdownMenuRadioGroup>
  </DropdownMenuContent>
</DropdownMenu>
```

## Navigation

By default a sub-menu is nested: it flies out beside its row. Pass `submenu="navigation"` and it drills in place instead: its rows replace the menu's behind a Back row, and the surface resizes to fit. Use it for a deep menu, or one with no room beside it. The parts and the rows are the same, and so are the keys: `→` goes in, and `←` or `Esc` steps back one layer before the menu closes. It is the Dock's panel, opened from a trigger.

```tsx
<DropdownMenu>
  <DropdownMenuTrigger asChild>
    <Button variant="outline">Workspace</Button>
  </DropdownMenuTrigger>
  <DropdownMenuContent submenu="navigation" className="w-56">
    <DropdownMenuLabel>Koala UI</DropdownMenuLabel>
    <DropdownMenuItem>
      <SquaresFour /> Components
      <DropdownMenuShortcut>⌘1</DropdownMenuShortcut>
    </DropdownMenuItem>
    <DropdownMenuItem>
      <Browsers /> Templates
      <DropdownMenuShortcut>⌘2</DropdownMenuShortcut>
    </DropdownMenuItem>
    <DropdownMenuSeparator />
    <DropdownMenuSub>
      <DropdownMenuSubTrigger>
        <Palette /> Appearance
      </DropdownMenuSubTrigger>
      <DropdownMenuSubContent>
        <DropdownMenuLabel>Theme</DropdownMenuLabel>
        <DropdownMenuRadioGroup value={theme} onValueChange={setTheme}>
          <DropdownMenuRadioItem value="light">
            <Sun /> Light
          </DropdownMenuRadioItem>
          <DropdownMenuRadioItem value="dark">
            <Moon /> Dark
          </DropdownMenuRadioItem>
        </DropdownMenuRadioGroup>
      </DropdownMenuSubContent>
    </DropdownMenuSub>
    <DropdownMenuSub>
      <DropdownMenuSubTrigger>
        <Buildings /> Workspace
      </DropdownMenuSubTrigger>
      <DropdownMenuSubContent>
        <DropdownMenuItem>
          <UsersThree /> Members
        </DropdownMenuItem>
        <DropdownMenuItem>
          <CreditCard /> Billing
        </DropdownMenuItem>
      </DropdownMenuSubContent>
    </DropdownMenuSub>
  </DropdownMenuContent>
</DropdownMenu>
```

## FAQ

### When should I use a Dropdown Menu versus a Select?

Use DropdownMenu for a list of actions or commands fired from a trigger, like a row's more-actions menu or an account menu. Reach for Select when the user is choosing a value to submit in a form; the menu's items run callbacks rather than holding a form value.

### How do I make an arbitrary element the trigger?

Pass `asChild` to DropdownMenuTrigger and render your own element inside it, such as an Avatar button or a ghost iconOnly Button. Radix merges the trigger behavior and ARIA onto your element instead of rendering its own button.

### What is the difference between DropdownMenuCheckboxItem and DropdownMenuRadioItem?

DropdownMenuCheckboxItem is an independent toggle driven by its own `checked` state, while DropdownMenuRadioItem is one mutually exclusive choice inside a DropdownMenuRadioGroup with a shared `value`. Both render the same Check indicator, since the exclusive-versus-toggle semantics live in the ARIA role and grouping, not the glyph.

### Does DropdownMenuShortcut actually bind the keyboard shortcut?

No. DropdownMenuShortcut is purely decorative right-aligned text rendered through the shared Kbd primitive, so it just displays the hint like ⌘P. Wire up the real key binding in your app with a global listener.

### How do I keep items aligned when some have leading icons and others do not?

Pass the `inset` prop to DropdownMenuItem (or DropdownMenuLabel and DropdownMenuSubTrigger) to add left padding that lines text up with icon-bearing siblings. This keeps a mixed list visually aligned without adding a placeholder icon.

### How do I style a destructive action like Delete or Log out?

Pass `variant="destructive"` to DropdownMenuItem. It colors the label red and, unlike the default muted leading icon, colors that icon red too so the whole row reads as one destructive unit; the hover background tints red to match. The check indicator on checkbox and radio items is never affected.

### How do I tighten the menu for dense application UI?

Set `density="compact"` on DropdownMenuContent, or drive it globally with DensityProvider since every part reads the density context. Compact shortens rows from 36px to 32px. The horizontal rhythm does not change between densities, so the menu keeps the same edge line and concentric corners at either size.

### Does the menu open over an element that is full screen?

Yes. DropdownMenuContent is portalled to the body, or to the element that is full screen when the menu opens, because the browser paints nothing outside that element over the screen. Pass `container` to portal it somewhere else.

### How far do icons sit from the menu's edge?

12px, measured from the outer edge of the menu: 4px of content padding plus 8px of row padding. The edge is drawn as an inset ring rather than a border, so it takes no layout space and the sum stays exact. Leading icons, label text, shortcuts, the submenu caret and the selection check all sit on that 12px line, left and right. An `inset` row starts its text at 40px from the edge (4px + 36px), which lines it up with the text of icon-bearing siblings.

### Should a sub-menu fly out or drill in place?

Fly out (the default, `submenu="nested"`) when the menu is shallow and has room beside it: the parent stays visible, so it reads as a side trip. Drill in place (`submenu="navigation"` on DropdownMenuContent) when the menu is two or more levels deep, sits near a screen edge, or opens on a phone: each layer takes the menu's place behind a Back row, so nothing ever opens off-screen. It is set once for the whole menu, the parts are the same, and DropdownMenuSubContent takes `backLabel` to rename the Back row. In this mode the sub takes the menu's width, so size the content, not the sub.

---

<!-- https://www.koalaui.com/docs/components/emoji-picker.md -->

# Emoji Picker

A complete picker: searchable, with a scroll-spy category nav, a pinned frequently-used row, persisted recents and a hovered preview. Categories mount lazily, so a large set never paints at once.

```tsx
<EmojiPicker onEmojiSelect={(char) => setEmoji(char)} />
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add emoji-picker
```

Manual: run `npm install radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/emoji-picker/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

```tsx title="usage.tsx"
import { EmojiPicker } from "@/components/ui/emoji-picker"

export function Example() {
  return <EmojiPicker onEmojiSelect={(char, datum) => console.log(char, datum.name)} />
}
```

## In a popover

The most common flow: a trigger opens the picker in a Radix popover that closes on select. Compose `EmojiPickerPopover`, `EmojiPickerTrigger` (use `asChild` to keep your own button), and `EmojiPickerContent`.

```tsx
<EmojiPickerPopover>
  <EmojiPickerTrigger asChild>
    <Button variant="outline">
      <Smiley /> Add emoji
    </Button>
  </EmojiPickerTrigger>
  <EmojiPickerContent onEmojiSelect={(char) => setEmoji(char)} />
</EmojiPickerPopover>
```

## Recents & presets

The picker tracks a **recently used** row automatically and persists it to `localStorage` (set `storageKey`, or pass `null` to disable). For full control, drive `recent` / `onRecentChange` yourself. The **presets** row is a fixed quick-pick list pinned above the categories; override it with the `presets` prop.

```tsx title="recents-presets.tsx"
<EmojiPicker
  presets={["👍", "❤️", "😂", "🎉", "🚀"]}
  recent={recent}
  onRecentChange={setRecent}
  recentLimit={16}
/>
```

## Density

Density retunes the panel width, viewport height, grid gap, and glyph size, never color or radius. `comfortable` is the marketing default; `compact` tightens it for application UI. It also resolves from a surrounding `DensityProvider`.

```tsx
<EmojiPicker density="comfortable" />
<EmojiPicker density="compact" />
```

## Minimal

Every region is toggleable. Drop the preview footer and the recents/presets rows with `showPreview`, `showRecent`, and `showPresets` for a lean search-and-grid.

```tsx
<EmojiPicker
  showPreview={false}
  showRecent={false}
  showPresets={false}
/>
```

## Performance

Categories mount in batches. Only `categoriesPerPage` are in the DOM at first, and a bottom sentinel reveals the next batch as you scroll (search results stream the same way). Counts only ever grow, so scroll height never jitters. Lower the value for a lighter first paint, or pass your own fuller dataset via `data` without changing the component.

```tsx title="performance.tsx"
// Mount two categories per scroll batch instead of three.
<EmojiPicker categoriesPerPage={2} data={myFullUnicodeSet} />
```

## FAQ

### When should I use the bare EmojiPicker versus the EmojiPickerPopover trio?

Render the bare `EmojiPicker` when the panel lives permanently in the layout, for example a sidebar or a reaction tray. Use `EmojiPickerPopover` with `EmojiPickerTrigger` and `EmojiPickerContent` for the common click-a-button-then-pick flow, since the content closes the popover on select by default.

### Why isn't there a kit of fine-grained parts like the search row or grid?

The search, category nav, viewport, and footer share scroll position, active section, and roving focus, so they are too tightly coupled to expose as loose parts. The public surface is the configured `EmojiPicker` plus the thin Radix Popover trio.

### How do recents get persisted, and how do I take control of them?

By default the picker tracks a recently-used row and persists it to localStorage under the `storageKey` (default "koala-emoji-recent"); pass `null` to disable persistence. For full control, drive `recent` and `onRecentChange` yourself and tune the cap with `recentLimit`.

### How do I strip it down to just a search box and grid?

Every region is toggleable. Set `showPreview`, `showRecent`, and `showPresets` to false for a lean search-and-grid, and `showSearch` to false if you do not need the search row at all.

### What keyboard navigation does the grid support?

The viewport has roving focus: arrow keys move by one (left/right) or by a row of eight (up/down), and Home/End jump to the first or last emoji. Pressing ArrowDown from the search field focuses the first emoji, and each button carries an `aria-label` of the emoji name.

### Can I swap in the full Unicode set without rewriting the component?

Yes. Pass your own categorized dataset to the `data` prop; it defaults to a curated set. Categories mount in batches of `categoriesPerPage` (3 by default) via a scroll sentinel, so a large set never paints all at once.

---

<!-- https://www.koalaui.com/docs/components/empty-state.md -->

# Empty State

The zero-data, no-results and first-run placeholder. A neutral icon tile, a balanced title, a readable description and a single outline action, composed from named parts, with a density axis for in-panel use.

```tsx
<EmptyState>
  <EmptyStateMedia>
    <FolderOpen />
  </EmptyStateMedia>
  <EmptyStateTitle>No projects yet</EmptyStateTitle>
  <EmptyStateDescription>
    Create your first project to start organizing work, inviting teammates, and shipping.
  </EmptyStateDescription>
  <EmptyStateActions>
    <Button variant="outline"><Plus /> New project</Button>
  </EmptyStateActions>
</EmptyState>
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add empty-state
```

Manual: run `npm install radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/empty-state/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

```tsx title="usage.tsx"
import {
  EmptyState,
  EmptyStateMedia,
  EmptyStateTitle,
  EmptyStateDescription,
  EmptyStateActions,
} from "@/components/ui/empty-state"
import { Button } from "@/components/ui/button"
import { MagnifyingGlass } from "@phosphor-icons/react/ssr"

export function Example() {
  return (
    <EmptyState>
      <EmptyStateMedia>
        <MagnifyingGlass />
      </EmptyStateMedia>
      <EmptyStateTitle>No results found</EmptyStateTitle>
      <EmptyStateDescription>
        Try adjusting your search or filters to find what you&apos;re looking for.
      </EmptyStateDescription>
      <EmptyStateActions>
        <Button variant="outline">Clear filters</Button>
      </EmptyStateActions>
    </EmptyState>
  )
}
```

## Variants

The `variant` prop colors the icon from a single semantic token. The tile around it stays neutral, with no fill and the plain border, so a search, error, or success state reads as one family across all four themes. Set it on the root and every part picks it up through context.

```tsx
<EmptyState variant="info">
  <EmptyStateMedia><MagnifyingGlass /></EmptyStateMedia>
  <EmptyStateTitle>No results</EmptyStateTitle>
  <EmptyStateDescription>Nothing matched that search.</EmptyStateDescription>
</EmptyState>

<EmptyState variant="destructive">
  <EmptyStateMedia><WarningCircle /></EmptyStateMedia>
  <EmptyStateTitle>Couldn't load data</EmptyStateTitle>
  <EmptyStateDescription>Something went wrong on our end.</EmptyStateDescription>
  <EmptyStateActions>
    <Button variant="outline"><ArrowClockwise /> Retry</Button>
  </EmptyStateActions>
</EmptyState>

<EmptyState variant="success">
  <EmptyStateMedia><CheckCircle /></EmptyStateMedia>
  <EmptyStateTitle>All caught up</EmptyStateTitle>
  <EmptyStateDescription>You&apos;ve cleared your inbox.</EmptyStateDescription>
</EmptyState>
```

## Density

`density` retunes padding, the media and icon size, the title size, and the description measure, never color or the rounded brand corners. `comfortable` (the default) suits a full page or marketing surface; `compact` fits an in-panel placeholder. It also reads from a `DensityProvider`, so an app shell can set it once.

```tsx
<EmptyState density="comfortable">
  <EmptyStateMedia><Bell /></EmptyStateMedia>
  <EmptyStateTitle>No notifications</EmptyStateTitle>
  <EmptyStateDescription>You&apos;re all caught up. New alerts land here.</EmptyStateDescription>
</EmptyState>

<EmptyState density="compact">
  <EmptyStateMedia><Bell /></EmptyStateMedia>
  <EmptyStateTitle>No notifications</EmptyStateTitle>
  <EmptyStateDescription>You&apos;re all caught up. New alerts land here.</EmptyStateDescription>
</EmptyState>
```

## Without actions

The action row is optional; drop `EmptyStateActions` for a purely informational placeholder.

```tsx
<EmptyState>
  <EmptyStateMedia><Users /></EmptyStateMedia>
  <EmptyStateTitle>No team members</EmptyStateTitle>
  <EmptyStateDescription>
    Invitations you send will show up here until they&apos;re accepted.
  </EmptyStateDescription>
</EmptyState>
```

## FAQ

### How do I compose an EmptyState?

Nest the named parts inside the root: `EmptyStateMedia` (wrap a single icon), `EmptyStateTitle`, `EmptyStateDescription`, and the optional `EmptyStateActions`. They are exported individually rather than as `EmptyState.Media`, because dot-notation statics do not survive the RSC server-to-client boundary.

### What does the variant prop change?

It only colors the media icon, from one semantic token. The tile keeps its neutral border and no fill in every variant. Options are `default`, `primary`, `success`, `warning`, `info`, and `destructive`, and every part reads it through context once you set it on the root.

### Are the action buttons required?

No. `EmptyStateActions` is optional, so drop it for a purely informational placeholder. When present, it holds exactly one `outline` Button: an empty state points at a single next step, never a choice. The row imposes the `sm` size, so the button needs no size of its own.

### When should I use density compact versus comfortable?

`comfortable` is the spacious default for a full page or marketing surface, while `compact` tightens padding, the media and icon size, the title size, and the description measure for an in-panel placeholder. It never touches color or the rounded corners.

### Can an app shell set the density once for many empty states?

Yes. Density resolves prop over provider over comfortable, so wrapping a region in a `DensityProvider` lets every nested EmptyState inherit it without passing `density` on each one.

### How do I render the media as something other than a div?

Both `EmptyState` and `EmptyStateMedia` accept `asChild` to merge their props onto your own element via Radix Slot. The media is marked `aria-hidden` since the icon is decorative and the title carries the meaning.

---

<!-- https://www.koalaui.com/docs/components/expandable-search.md -->

# Expandable Search

A search that rests as an icon button and grows into a full field on click. One box widens under the magnifier, so the glyph never moves and the open field is the DS Input, pixel for pixel.

```tsx
<div className="flex items-center gap-2">
  <p className="text-sm font-medium">All files</p>
  <span className="text-sm text-muted-foreground tabular-nums">128</span>
  <div className="flex-1" />
  <ExpandableSearch size="md" placeholder="Search files" className="w-56" />
  <Button variant="outline">Export</Button>
  <Button>Upload</Button>
</div>
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add expandable-search
```

Manual: run `npm install radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/expandable-search/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

```tsx title="usage.tsx"
import { ExpandableSearch } from "@/components/ui/expandable-search"

export function Example() {
  return (
    <ExpandableSearch
      placeholder="Search files"
      className="w-64" // the OPEN width
      inputProps={{ onChange: (e) => setQuery(e.target.value) }}
    />
  )
}
```

## How it opens and closes

A click opens it and puts the caret in the field. Escape steps back one layer at a time: the first press clears the query, the second folds the search away and hands focus back to the button. Clicking elsewhere folds an empty search, but one that holds a query stays open, so the text filtering the page never disappears behind an icon. The width transition names its properties and switches off under reduced motion.

## Sizes

The Input's own axis: `sm` 32px, `md` 36px, `lg` 40px. At rest it is a square of that height, the same size as a ghost icon Button beside it; unset, it follows the container's imposed size or the density.

```tsx
<ExpandableSearch size="sm" />
<ExpandableSearch size="md" />
<ExpandableSearch size="lg" />
```

## With a shortcut

Trailing content rides inside the open field, like a `Kbd` hint. Control `open` when something outside the component opens it: press `/` anywhere on this page.

```tsx
const [open, setOpen] = useState(false)
const field = useRef<HTMLInputElement>(null)

// "/" opens it from anywhere on the page, except while typing in a field.
useEffect(() => {
  const onKey = (e: KeyboardEvent) => {
    if (e.key !== "/" || e.metaKey || e.ctrlKey || e.altKey) return
    if ((e.target as HTMLElement).closest("input, textarea, select, [contenteditable=true]")) return
    e.preventDefault()
    setOpen(true)
  }
  window.addEventListener("keydown", onKey)
  return () => window.removeEventListener("keydown", onKey)
}, [])

// Opened from outside, so the caller hands focus to the field once it is live.
useEffect(() => { if (open) field.current?.focus() }, [open])

<ExpandableSearch
  open={open}
  onOpenChange={setOpen}
  placeholder="Search anything"
  className="w-72"
  inputProps={{ ref: field }}
>
  <InputSuffix><Kbd size="sm">/</Kbd></InputSuffix>
</ExpandableSearch>
```

## States

At rest, open with a query, and disabled. It is an `InputRoot` underneath, so `hasError`, a surrounding `Field` and the focus ring all behave exactly as they do on an Input.

```tsx
<ExpandableSearch />
<ExpandableSearch defaultOpen className="w-56" inputProps={{ defaultValue: "Quarterly report" }} />
<ExpandableSearch disabled />
```

## In a navbar

[`NavbarSearch collapsible`](https://www.koalaui.com/docs/components/navbar.md#search) is this component tuned for the bar: 36px and `rounded-md` at rest, the hamburger's chip, so it reads as one of the bar's icons until someone searches.

```tsx
<Navbar linkStyle="text">
  <NavbarInner>
    <NavbarBrand href="/"><BrandMark /></NavbarBrand>
    <NavbarNav className="ml-2">…</NavbarNav>
    <NavbarSpacer />
    <NavbarSearch collapsible placeholder="Search docs" />
    <NavbarActions>…</NavbarActions>
  </NavbarInner>
</Navbar>
```

## API reference

### ExpandableSearch

An `InputRoot` whose leading magnifier is the button that opens it. Forwards `InputRoot` props (`hasError`, `disabled`, `density`…).

- `open` / `defaultOpen` / `onOpenChange`: the expanded state. Focus moves only for the component's own button, never for `defaultOpen` or a controlled change.
- `size`: `"sm"`, `"md"` or `"lg"`. The closed square and the open field's height.
- `className`: merged onto the box; a width class (`w-80`) sets the OPEN width, default `w-64`. The closed width is pinned by the size, so it never fights yours.
- `placeholder`: default `"Search"`. `label` overrides the accessible name the button and the field share (defaults to the placeholder).
- `inputProps`: forwarded to the `<input type="search">` (`value`, `onChange`, `name`, `ref`…). Escape clears a controlled value through its own `onChange`.
- `children`: trailing content inside the open field, such as `InputSuffix` with a `Kbd`.

## FAQ

### When should I use ExpandableSearch instead of a plain search Input?

When the row can't spare a field's width until someone actually searches: a table toolbar, a dense app header, a marketing navbar with a full link set. Where search is the main way around the product, keep the always-open field (an `Input` with an `InputPrefix`, or `NavbarSearch`) so nobody has to find it first.

### How do I set how wide it opens?

Give it a width class: `className="w-80"`. That class only applies while it is open; the closed width is pinned by `size` (a 32, 36 or 40px square), so the two never fight. Default open width is `w-64`.

### Why doesn't it close when I click away?

It does, unless the field holds a query. Folding a live search behind an icon would hide the very text that is filtering the page. Press Escape to clear the query, and Escape again to close it.

### How do I open it with a keyboard shortcut?

Control `open`: set it to true from your shortcut handler (`/` or ⌘K), and focus the field (through `inputProps.ref`) once it is open. The component moves focus only when its own button opens it, so a search that mounts open or opens from outside never steals the page's focus on its own.

### Is it accessible?

At rest it is a labelled button with `aria-expanded` and `aria-controls` pointing at the field; the closed field is `inert`, out of the tab order and the accessibility tree. Open, the magnifier drops out of the tab order and the `type="search"` field carries the same accessible name.

---

<!-- https://www.koalaui.com/docs/components/field.md -->

# Field

The wrapper that turns any control into a labelled form field. Field generates the id, htmlFor and aria-describedby wiring for you and cascades error and disabled state to the control inside.

```tsx
<Field>
  <FieldLabel>Email</FieldLabel>
  <InputRoot>
    <InputField placeholder="you@example.com" type="email" />
  </InputRoot>
  <FieldHint>We'll only use it for account notifications.</FieldHint>
</Field>
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add field
```

Manual: run `npm install radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/field/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

Drop a control between `FieldLabel` and `FieldHint`. You never touch `id`, `htmlFor`, or `aria-describedby` - `Field` generates them with `useId` and hands them to the control through context. Clicking the label focuses the control, and screen readers announce the hint.

```tsx title="usage.tsx"
import { Field, FieldLabel, FieldHint } from "@/components/ui/field"
import { InputRoot, InputField } from "@/components/ui/input"

export function Example() {
  return (
    <Field>
      <FieldLabel>Email</FieldLabel>
      <InputRoot>
        <InputField type="email" />
      </InputRoot>
      <FieldHint>We'll only use it for account notifications.</FieldHint>
    </Field>
  )
}
```

## Required & error

Set `required` to append a destructive asterisk to the label. Set `hasError` on the `Field` - it cascades to the control’s border, sets `aria-invalid`, and turns the hint into the destructive error message. You set it in one place, not on every part.

```tsx
<Field required>
  <FieldLabel>Email</FieldLabel>
  <InputRoot>
    <InputField defaultValue="wrong@" type="email" />
  </InputRoot>
</Field>

<Field hasError required>
  <FieldLabel>Email</FieldLabel>
  <InputRoot>
    <InputField defaultValue="wrong@" type="email" />
  </InputRoot>
  <FieldHint>Enter a valid email address.</FieldHint>
</Field>
```

## Any control

`Field` is control-agnostic. Because Input, Select, and PasswordInput all forward native props, the same wrapper labels any of them - the wiring lands on the right element automatically.

```tsx
<Field>
  <FieldLabel>Country</FieldLabel>
  <Select>
    <SelectTrigger>
      <SelectValue placeholder="Select a country" />
    </SelectTrigger>
    <SelectContent>
      <SelectItem value="es">Spain</SelectItem>
      <SelectItem value="fr">France</SelectItem>
      <SelectItem value="de">Germany</SelectItem>
    </SelectContent>
  </Select>
</Field>

<Field>
  <FieldLabel>Password</FieldLabel>
  <PasswordInput placeholder="Create a password" />
  <FieldHint>At least 8 characters.</FieldHint>
</Field>
```

## Two fields per row

`FieldRow` places sibling fields side by side and stacks them on narrow viewports - the answer to *Name · Surname* pairs. It is pure layout, so it composes with any number of fields.

```tsx
<FieldRow>
  <Field>
    <FieldLabel>First name</FieldLabel>
    <InputRoot><InputField placeholder="Ada" /></InputRoot>
  </Field>
  <Field>
    <FieldLabel>Last name</FieldLabel>
    <InputRoot><InputField placeholder="Lovelace" /></InputRoot>
  </Field>
</FieldRow>
```

## A whole form

Wrap the fields in a [`Form`](https://www.koalaui.com/docs/components/form.md), which owns the gap so no form has to invent its own, reach for `FieldRow` where two values belong together, and let each `Field` own its own wiring. This is a full registration form, name pair, email, country, and a password pair, with nothing wired by hand.

```tsx
<Form>
  <FieldRow>
    <Field required>
      <FieldLabel>First name</FieldLabel>
      <InputRoot><InputField placeholder="Ada" /></InputRoot>
    </Field>
    <Field required>
      <FieldLabel>Last name</FieldLabel>
      <InputRoot><InputField placeholder="Lovelace" /></InputRoot>
    </Field>
  </FieldRow>

  <Field required>
    <FieldLabel>Email</FieldLabel>
    <InputRoot><InputField placeholder="ada@example.com" type="email" /></InputRoot>
    <FieldHint>We'll send a confirmation link here.</FieldHint>
  </Field>

  <Field required>
    <FieldLabel>Country</FieldLabel>
    <Select>
      <SelectTrigger>
        <SelectValue placeholder="Select a country" />
      </SelectTrigger>
      <SelectContent>
        <SelectItem value="es">Spain</SelectItem>
        <SelectItem value="fr">France</SelectItem>
        <SelectItem value="de">Germany</SelectItem>
        <SelectItem value="uk">United Kingdom</SelectItem>
      </SelectContent>
    </Select>
  </Field>

  <FieldRow>
    <Field required>
      <FieldLabel>Password</FieldLabel>
      <PasswordInput placeholder="Create a password" />
    </Field>
    <Field required>
      <FieldLabel>Confirm password</FieldLabel>
      <PasswordInput placeholder="Repeat it" />
    </Field>
  </FieldRow>

  <FormActions align="stack" className="mt-1">
    <Button type="submit">Create account</Button>
  </FormActions>
</Form>
```

## In a Dialog

`Field` composes straight into a Dialog. The wiring flows through Radix's Portal because React context follows the component tree, not the DOM - so `htmlFor`, `aria-describedby`, and the `hasError` cascade all still work. The modal's own name comes from `DialogTitle` / `DialogDescription` (Radix), independent of the per-field labels. Try submitting with an invalid email to see the error cascade.

```tsx
<Dialog>
  <DialogTrigger asChild>
    <Button>Create account</Button>
  </DialogTrigger>
  <DialogContent size="md">
    <DialogHeader>
      <DialogTitle>Create your account</DialogTitle>
      <DialogDescription>It takes less than a minute.</DialogDescription>
    </DialogHeader>

    <FormSection>
      <FieldRow>
        <Field required>
          <FieldLabel>First name</FieldLabel>
          <InputRoot><InputField placeholder="Ada" /></InputRoot>
        </Field>
        <Field required>
          <FieldLabel>Last name</FieldLabel>
          <InputRoot><InputField placeholder="Lovelace" /></InputRoot>
        </Field>
      </FieldRow>

      <Field required hasError={!!emailError}>
        <FieldLabel>Email</FieldLabel>
        <InputRoot><InputField type="email" value={email} onChange={…} /></InputRoot>
        <FieldHint>{emailError ?? "We'll send a confirmation link here."}</FieldHint>
      </Field>

      <Field required>
        <FieldLabel>Country</FieldLabel>
        <Select>
          <SelectTrigger><SelectValue placeholder="Select a country" /></SelectTrigger>
          <SelectContent>{/* …items */}</SelectContent>
        </Select>
      </Field>

      <Field required>
        <FieldLabel>Password</FieldLabel>
        <PasswordInput placeholder="Create a password" />
        <FieldHint>At least 8 characters.</FieldHint>
      </Field>
    </FormSection>

    <DialogFooter>
      <Button variant="ghost">Cancel</Button>
      <Button>Create account</Button>
    </DialogFooter>
  </DialogContent>
</Dialog>
```

## Disabled

`disabled` on the `Field` dims the label and disables the control inside.

```tsx
<Field disabled>
  <FieldLabel>Email</FieldLabel>
  <InputRoot>
    <InputField placeholder="you@example.com" />
  </InputRoot>
</Field>
```

## Field vs FieldGroup

A Field wraps *one* control, because a `label` needs exactly one control to point at. When several controls answer a single question, a radio set or a cluster of checkboxes, there is nothing for the label to name, so the right wrapper is [`FieldGroup`](https://www.koalaui.com/docs/components/form.md): a real `fieldset` with a real `legend`. It ships alongside Field and takes the same `hasError`, `disabled`, and `required` props, and the same `FieldHint` describes the whole group.

```tsx
// One control: a Field.
<Field required>
  <FieldLabel>Email</FieldLabel>
  <InputRoot><InputField type="email" /></InputRoot>
</Field>

// Several controls, one question: a FieldGroup.
<FieldGroup required>
  <FieldGroupLabel>Email preferences</FieldGroupLabel>
  <RadioGroup>…</RadioGroup>
  <FieldHint>Pick at least one.</FieldHint>
</FieldGroup>
```

## FAQ

### What wiring does Field actually generate for me?

Field calls useId to mint stable ids and hands them through context to its parts: FieldLabel gets the matching htmlFor, the control gets the id, and FieldHint gets pointed at by aria-describedby. You never set id, htmlFor, or aria-describedby yourself.

### How does a control opt into the Field context?

Controls read the Field context to receive their id, aria, and error or disabled state, which is why Input, Select, and PasswordInput just work inside a Field. Field never inspects child types across the server to client boundary, so any control that consumes the context picks up the wiring automatically.

### Where do I set the error state, on the Field or on each part?

Set `hasError` once on the Field. It cascades to the control's border, sets aria-invalid on the control, and turns the FieldHint into a destructive error message, so you never repeat the flag on every part.

### What do the required and disabled props do?

`required` appends a destructive asterisk to the FieldLabel. `disabled` dims the label and disables the control inside, again set in one place on the Field rather than on each part.

### Why is aria-describedby only present when there is a hint?

FieldHint registers itself on mount, so Field only advertises aria-describedby when a hint is actually rendered and never points the control at a missing node. Because it registers on mount rather than by inspecting child types, SSR and the first client render agree and there is no hydration mismatch.

### Does Field still wire correctly inside a Dialog or other portal?

Yes. React context follows the component tree, not the DOM, so htmlFor, aria-describedby, and the hasError cascade all keep working through Radix's Portal. The dialog's own accessible name comes from DialogTitle and DialogDescription, independent of the per-field labels.

### How do I place two fields side by side?

Wrap sibling Fields in FieldRow. It is pure layout with no context, laying fields out in a grid that stacks to one column on narrow viewports, so it composes with any number of fields. Pass columns={3} for a three-up row; the default is 2.

### Can I put a RadioGroup or a checkbox cluster in a Field?

Use FieldGroup instead. A Field wraps one control because a label needs exactly one control to point at, while several controls answering a single question need a fieldset and legend, which is what FieldGroup renders. A single checkbox, like 'I agree to the terms', is still one control, so that one is a Field.

---

<!-- https://www.koalaui.com/docs/components/file-card.md -->

# File Card

A card for a single file: a realistic file-type illustration or image thumbnail, the name, a meta line, trailing actions and an optional progress bar. Composes into attachment rows and upload trays.

```tsx
<FileCard>
  <FileCardIcon type="pdf" />
  <FileCardContent>
    <FileCardName>Annual report 2025.pdf</FileCardName>
    <FileCardMeta>2.4 MB · PDF document</FileCardMeta>
  </FileCardContent>
  <FileCardActions>
    <Button variant="ghost" size="sm" iconOnly aria-label="Download"><DownloadSimple /></Button>
    <Button variant="ghost" size="sm" iconOnly aria-label="Remove"><Trash /></Button>
  </FileCardActions>
</FileCard>

<FileCard state="success">
  <FileCardIcon type="image" />
  <FileCardContent>
    <FileCardName>hero-banner.png</FileCardName>
    <FileCardMeta>880 KB · Uploaded</FileCardMeta>
  </FileCardContent>
  <FileCardStatus />
</FileCard>
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add file-card
```

Manual: run `npm install @phosphor-icons/react radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/file-card/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

File Card is composed from named parts, like [Card](https://www.koalaui.com/docs/components/card.md). The `FileCard` root owns the surface, variant, state, and density; the parts (`FileCardIcon`, `FileCardName`, `FileCardProgress`) read it from context.

```tsx title="attachment.tsx"
import {
  FileCard,
  FileCardIcon,
  FileCardContent,
  FileCardName,
  FileCardMeta,
  FileCardActions,
  fileTypeFromName,
} from "@/components/ui/file-card"
import { Button } from "@/components/ui/button"
import { DownloadSimple, Trash } from "@phosphor-icons/react"

export function Attachment({ file }) {
  return (
    <FileCard>
      <FileCardIcon type={fileTypeFromName(file.name)} />
      <FileCardContent>
        <FileCardName>{file.name}</FileCardName>
        <FileCardMeta>{file.size}</FileCardMeta>
      </FileCardContent>
      <FileCardActions>
        <Button variant="ghost" size="sm" iconOnly aria-label="Download"><DownloadSimple /></Button>
        <Button variant="ghost" size="sm" iconOnly aria-label="Remove"><Trash /></Button>
      </FileCardActions>
    </FileCard>
  )
}
```

## Anatomy

A row reads left-to-right: a `FileCardIcon` (or `FileCardThumbnail`) leads, a `FileCardContent` column fills with the `FileCardName` over a muted `FileCardMeta` line, and `FileCardActions` ride the right edge. The name truncates so a long filename never pushes the actions off the card.

```tsx
<FileCard>
  <FileCardIcon type="pdf" />
  <FileCardContent>
    <FileCardName>Annual report 2025.pdf</FileCardName>
    <FileCardMeta>2.4 MB · PDF document</FileCardMeta>
  </FileCardContent>
  <FileCardActions>
    <Button variant="ghost" size="sm" iconOnly aria-label="Download"><DownloadSimple /></Button>
    <Button variant="ghost" size="sm" iconOnly aria-label="More"><DotsThree /></Button>
  </FileCardActions>
</FileCard>
```

## File types

Pass `type` to `FileCardIcon` and it renders a realistic file illustration: a sheet with a dog-eared corner and a colored band stamped with the extension. The tone re-themes across all four palettes: PDFs read red, images purple, sheets green, and so on. The band shows a short stand-in (PDF, XLS, IMG…) by default; pass `label` to stamp the real extension (the demo below shows `DOCX`, `XLSX`, `TSX`). Don’t know the type up front? Derive it from the filename with `fileTypeFromName(file.name)`. The illustration is `FileIcon`, also usable on its own: every extension, its soft and solid variants and SVG downloads live on [File Icons](https://www.koalaui.com/docs/foundations/file-icons.md).

```tsx
// type picks the tone + a default band label
<FileCardIcon type="pdf" />     {/* red · "PDF" */}
<FileCardIcon type="image" />   {/* purple · "IMG" */}
<FileCardIcon type="sheet" />   {/* green · "XLS" */}
<FileCardIcon type="code" />    {/* teal · "</>" */}

// stamp the real extension on the band
<FileCardIcon type="sheet" label="CSV" />

// …or derive the type straight from the filename
<FileCardIcon type={fileTypeFromName("index.tsx")} />
```

## Thumbnail

For images, swap the glyph tile for a `FileCardThumbnail`. It fills the same footprint, clips the preview to the concentric radius, and carries a subtle inset outline so the image edge reads cleanly on any surface. Always pass a meaningful `alt`.

```tsx
<FileCard>
  <FileCardThumbnail src={previewUrl} alt="Mountain landscape" />
  <FileCardContent>
    <FileCardName>mountain-vista.jpg</FileCardName>
    <FileCardMeta>1.8 MB · 2400 × 1600</FileCardMeta>
  </FileCardContent>
  <FileCardActions>
    <Button variant="ghost" size="sm" iconOnly aria-label="Remove"><Trash /></Button>
  </FileCardActions>
</FileCard>
```

## Tile layout

Same card, second arrangement. Pass `layout="tile"` and the row becomes the square cell of an image grid: the `FileCardThumbnail` fills it edge to edge and `FileCardActions` become a blurred scrim that fades in on hover or keyboard focus. The tile itself never moves - no lift, no press scale - so the photo and the wash carry the whole interaction. Pair it with [File Upload](https://www.koalaui.com/docs/components/file-upload.md)’s `FileUploadGrid`.

```tsx
<Lightbox images={shots}>
  <div className="grid grid-cols-3 gap-3">
    {shots.map((shot, i) => (
      <FileCard key={shot.src} layout="tile">
        <FileCardThumbnail src={shot.src} alt={shot.alt} />
        <FileCardActions>
          <Button variant="ghost" size="sm" iconOnly aria-label="Delete"
            tone="onMedia">
            <Trash />
          </Button>
          <LightboxTrigger asChild index={i}>
            <Button variant="ghost" size="sm" iconOnly aria-label="Preview"
              tone="onMedia">
              <Eye />
            </Button>
          </LightboxTrigger>
        </FileCardActions>
      </FileCard>
    ))}
  </div>
</Lightbox>
```

## Upload progress

Drop a `FileCardProgress` into the content column to show an in-flight upload. It renders the DS [Progress](https://www.koalaui.com/docs/components/progress.md) bar, so a live `value` animates smoothly, the percentage uses `tabular-nums`, and the bar re-tones to destructive when the card’s `state` is `error`. Swap it for a `FileCardMeta` once the upload lands.

The readout is droppable. Leave it in and the label and percentage sit above the bar; pass `hideValue` and move the number out to a `FileCardValue` beside the content column, and the bar runs the full width with the percentage holding the row’s right edge.

```tsx
{/* Label + percentage above the bar */}
<FileCard state={done ? "success" : "uploading"}>
  <FileCardIcon type="video" />
  <FileCardContent>
    <FileCardName>product-demo.mp4</FileCardName>
    {done ? (
      <FileCardMeta>48 MB · Uploaded</FileCardMeta>
    ) : (
      <FileCardProgress value={progress} label="Uploading…" />
    )}
  </FileCardContent>
  <FileCardStatus />
</FileCard>

{/* Or move the percentage out, so the bar runs the full content width */}
<FileCard state={done ? "success" : "uploading"}>
  <FileCardIcon type="video" />
  <FileCardContent>
    <FileCardName>product-demo.mp4</FileCardName>
    {done ? (
      <FileCardMeta>48 MB · Uploaded</FileCardMeta>
    ) : (
      <FileCardProgress value={progress} hideValue />
    )}
  </FileCardContent>
  {done ? <FileCardStatus /> : <FileCardValue>{progress}%</FileCardValue>}
</FileCard>
```

## States

The root `state` drives the surface and the trailing `FileCardStatus` glyph: `uploading` spins, `success` lights a green check, and `error` pulls a soft destructive border with a warning so a failed file reads at a glance.

```tsx
<FileCard state="uploading">…<FileCardProgress value={42} label="Uploading…" />…</FileCard>
<FileCard state="success">…<FileCardStatus />…</FileCard>   {/* green check */}
<FileCard state="error">…<FileCardStatus />…</FileCard>     {/* red border + warning */}
```

## Variants

`default` sits on a hairline border with a soft shadow; `outline` drops the shadow for flat, gridded lists; `elevated` trades the border for a lifted shadow when a card needs to float; `ghost` strips all chrome and padding so the row sits flush in feeds, comment threads, and dense lists. The file illustration still carries the file’s identity.

```tsx
<FileCard variant="default">…</FileCard>
<FileCard variant="outline">…</FileCard>
<FileCard variant="elevated">…</FileCard>
<FileCard variant="ghost">…</FileCard>   {/* chrome-less, flush in feeds/lists */}
```

## Density

Density is Koala’s cross-cutting spacing axis (see [Density](https://www.koalaui.com/docs/foundations/density.md)). For File Card it tunes padding, gap, and the media tile. `compact` is the dense app default for upload trays and file lists; `comfortable` is roomier. Set it per-card or for a whole list with `DensityProvider`.

```tsx
// "compact" (the app default) or "comfortable"
<FileCard density="compact">…</FileCard>
<FileCard density="comfortable">…</FileCard>
```

## Interactive

A file row is inert by default. When the whole card should open the file, pass `asChild` to render it as a link and `interactive` to add the pointer, hover lift, and focus ring. For per-file actions instead, keep the card inert and drop [Button](https://www.koalaui.com/docs/components/button.md)s into `FileCardActions`.

```tsx
// The whole card opens the file:
<FileCard asChild interactive>
  <a href={file.url}>
    <FileCardIcon type="pdf" />
    <FileCardContent>
      <FileCardName>Annual report 2025.pdf</FileCardName>
      <FileCardMeta>2.4 MB · Click to open</FileCardMeta>
    </FileCardContent>
  </a>
</FileCard>
```

## API reference

`FileCard` forwards all `div` props and adds `layout` (`row | tile`), `variant` (`default | outline | elevated | ghost`), `state` (`idle | uploading | success | error`), `density` (`compact | comfortable`), `interactive`, and `asChild`. The parts ( `FileCardContent`, `FileCardName`, `FileCardMeta`, `FileCardValue`, `FileCardActions`) forward `div` props. `FileCardIcon` adds `type` and an optional `label` band override (or pass your own glyph as children); `FileCardThumbnail` forwards `img` props and requires `alt`; `FileCardProgress` takes `value`, `label`, and `hideValue`; `FileCardStatus` takes an optional `status` (else it reads the card’s state). The helper `fileTypeFromName(name)` maps a filename to a type. Every part accepts `className`, merged last.

## FAQ

### How do I pick the right illustration and tint without knowing the file type up front?

Pass `type` to FileCardIcon to render a realistic file illustration (a sheet with a dog-eared corner and a colored extension band) with a re-themable tint, for example "pdf" reads red and "image" reads purple. If you only have a filename, call `fileTypeFromName(file.name)` and pass its result as the type; it falls back to "default" for unknown or extensionless names. By default the band shows a short per-type stand-in (PDF, XLS, IMG…); pass `label` to stamp the exact extension, e.g. label="CSV".

### When should I use FileCardThumbnail instead of FileCardIcon?

Use FileCardThumbnail for images: it fills the same footprint as the icon tile, clips the preview to the concentric radius, and carries a subtle inset outline so the edge reads on any surface. It requires a meaningful `alt` and forwards native img props, so an object URL src works for not-yet-uploaded blobs.

### How do the variant and state props differ?

`variant` controls chrome: default has a border and soft shadow, outline drops the shadow, elevated trades the border for a lift, and ghost strips all chrome and padding to sit flush in feeds. `state` (idle, uploading, success, error) drives the surface tint and the FileCardStatus glyph, with error pulling a soft destructive border.

### Does FileCardStatus need its own status prop?

Usually not. FileCardStatus reads the card's `state` from context by default, so `<FileCard state="success">` lights the green check and "error" shows the warning automatically. Pass an explicit `status` only when you want a glyph that differs from the card's state.

### How do I show an upload bar, and how does it animate smoothly?

Drop a FileCardProgress into the FileCardContent column and pass `value` from 0 to 100, plus an optional `label` and `hideValue`. The fill width rides a CSS variable so a live value animates with a width-only transition, and the percentage uses tabular-nums so it never reflows; swap it for a FileCardMeta once the upload lands.

### How do I make the whole card open the file versus offering per-file actions?

For a card that opens the file, pass `asChild` to render it as your own anchor and `interactive` to add the pointer, hover lift, and focus ring. For per-file actions instead, keep the card inert and drop Buttons into FileCardActions.

### What does density change on a File Card?

Density tunes the padding, gap, and media tile size. `compact` is the dense app default for upload trays and file lists, `comfortable` is roomier, and you can set it per card or for a whole list with DensityProvider.

---

<!-- https://www.koalaui.com/docs/components/file-preview.md -->

# File Preview

Look at a file where it is instead of opening another tab. PDFs page through with selectable text, images zoom and pan, and one set of controls fits, zooms, rotates and pages every kind.

```tsx
<FilePreview src="/files/q3-report.pdf" name="Koala Q3 2026 report.pdf">
  <FilePreviewHeader>
    <FilePreviewIcon />
    <FilePreviewInfo>
      <FilePreviewTitle />
      <FilePreviewMeta />
    </FilePreviewInfo>
    <FilePreviewActions>
      <FilePreviewDownload />
    </FilePreviewActions>
  </FilePreviewHeader>
  <FilePreviewThumbnails />
  <FilePreviewViewport>
    <FilePreviewToolbar>
      <FilePreviewThumbnailsToggle />
      <ToolbarSeparator />
      <FilePreviewPageNav />
      <ToolbarSeparator />
      <FilePreviewZoomOut />
      <FilePreviewZoomMenu />
      <FilePreviewZoomIn />
      <ToolbarSeparator />
      <FilePreviewFit />
      <FilePreviewRotate />
      <ToolbarSeparator />
      <FilePreviewFullscreen />
    </FilePreviewToolbar>
  </FilePreviewViewport>
</FilePreview>
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add file-preview
```

Manual: run `npm install pdfjs-dist @phosphor-icons/react radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/file-preview/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

Hand the root a `file` (a `File` from an input or a drop) or a `src`. It works out how to show it from the type and the name, and every part below reads the file, the zoom and the page from it. PDFs render with Mozilla's PDF.js, which is loaded only when a PDF is opened.

```tsx title="preview.tsx"
import {
  FilePreview,
  FilePreviewHeader,
  FilePreviewIcon,
  FilePreviewInfo,
  FilePreviewTitle,
  FilePreviewMeta,
  FilePreviewActions,
  FilePreviewDownload,
  FilePreviewViewport,
  FilePreviewToolbar,
  FilePreviewZoomOut,
  FilePreviewZoomMenu,
  FilePreviewZoomIn,
  FilePreviewFit,
} from "@/components/ui/file-preview"

<FilePreview file={file}>
  <FilePreviewHeader>
    <FilePreviewIcon />
    <FilePreviewInfo>
      <FilePreviewTitle />
      <FilePreviewMeta />
    </FilePreviewInfo>
    <FilePreviewActions>
      <FilePreviewDownload />
    </FilePreviewActions>
  </FilePreviewHeader>
  <FilePreviewViewport>
    <FilePreviewToolbar>
      <FilePreviewZoomOut />
      <FilePreviewZoomMenu />
      <FilePreviewZoomIn />
      <FilePreviewFit />
    </FilePreviewToolbar>
  </FilePreviewViewport>
</FilePreview>
```

## Preview an upload

The flow it exists for: files arrive in a [File Upload](https://www.koalaui.com/docs/components/file-upload.md) list and a click opens them over the page with `FilePreviewDialog`, instead of in a new tab. Drop your own files in, they preview straight from the disk and never leave the browser. The dialog is edge to edge on a phone, lands focus on the canvas so the keys work at once, and keeps showing the file while it fades out, so clearing it on close is safe.

```tsx
const [file, setFile] = React.useState<File | null>(null)
const [open, setOpen] = React.useState(false)

<FileUploadList>
  {files.map((file) => (
    <FileCard key={file.name} asChild interactive>
      <button type="button" onClick={() => { setFile(file); setOpen(true) }}>
        <FileCardIcon type={fileTypeFromName(file.name)} />
        <FileCardContent>
          <FileCardName>{file.name}</FileCardName>
          <FileCardMeta>{formatBytes(file.size)} · Click to preview</FileCardMeta>
        </FileCardContent>
      </button>
    </FileCard>
  ))}
</FileUploadList>

<FilePreviewDialog open={open} onOpenChange={setOpen} file={file}>
  <FilePreviewHeader>
    <FilePreviewIcon />
    <FilePreviewInfo>
      <FilePreviewTitle />
      <FilePreviewMeta />
    </FilePreviewInfo>
    <FilePreviewActions>
      <FilePreviewDownload />
      <FilePreviewClose />
    </FilePreviewActions>
  </FilePreviewHeader>
  <FilePreviewThumbnails />
  <FilePreviewViewport>
    <FilePreviewToolbar>…</FilePreviewToolbar>
  </FilePreviewViewport>
</FilePreviewDialog>
```

## Every kind of file

The renderer follows the file. A PDF pages through with selectable text and a page rail. An image zooms and, once it no longer fits, drags to pan (double-click toggles 100%). Text and code read as a numbered sheet. Video plays in the [Video Player](https://www.koalaui.com/docs/components/video-player.md) and audio in a compact player whose seek bar is the clip's own waveform. Anything else says so and offers its download. A control with nothing to do for the file renders nothing, and the bar folds the separator it leaves behind.

```tsx
<FilePreview src="/files/living-room.jpg">…</FilePreview>
<FilePreview src="/files/q3-report.pdf">…</FilePreview>
<FilePreview src="/files/CHANGELOG.md">…</FilePreview>
<FilePreview src="/files/walkthrough.mp4">…</FilePreview>
<FilePreview src="/files/success-chime.mp3">…</FilePreview>
<FilePreview src="/files/brand-kit.zip">…</FilePreview>

{/* the type decides; force a renderer when the name can't */}
<FilePreview src="/api/files/8412" name="notes" kind="text">…</FilePreview>
```

## Fit and zoom

`"fit"` shows the whole page and `"width"` fills the canvas side to side; both follow the canvas as it resizes. A number is a fixed level, 1 being the file's actual size. The buttons walk the familiar steps, the readout opens every level, and `⌘` + wheel or a pinch zooms continuously. Every change holds a point still, the pointer for a wheel or a pinch and the centre otherwise, so a zoom never throws you somewhere else in the file. A photo never grows past its own pixels on `"fit"`: an upscaled photo is a blurred one.

```tsx
<FilePreview src="/files/living-room.jpg" defaultZoom="fit">
  <FilePreviewHeader>…</FilePreviewHeader>
  <FilePreviewViewport>
    <FilePreviewToolbar>
      <FilePreviewZoomOut />
      <FilePreviewZoomMenu />
      <FilePreviewZoomIn />
      <ToolbarSeparator />
      <FilePreviewFit />
      <FilePreviewRotate direction="counterclockwise" />
      <FilePreviewRotate />
    </FilePreviewToolbar>
  </FilePreviewViewport>
</FilePreview>
```

## Docked toolbar

The toolbar floats over the canvas when it sits in `FilePreviewViewport`. Put it in the header instead, with `variant="plain"`, for a bar docked above the document like a desktop reader. The same controls, the same behaviour. This one opens at `defaultZoom="width"`, the reading layout.

```tsx
<FilePreview src="/files/q3-report.pdf" defaultZoom="width">
  <FilePreviewHeader>
    <FilePreviewIcon />
    <FilePreviewInfo>
      <FilePreviewTitle />
      <FilePreviewMeta />
    </FilePreviewInfo>
    <FilePreviewToolbar variant="plain" className="max-md:hidden">
      <FilePreviewPageNav />
      <ToolbarSeparator />
      <FilePreviewZoomOut />
      <FilePreviewZoomMenu />
      <FilePreviewZoomIn />
      <ToolbarSeparator />
      <FilePreviewFit />
    </FilePreviewToolbar>
    <FilePreviewActions>
      <FilePreviewDownload />
    </FilePreviewActions>
  </FilePreviewHeader>
  <FilePreviewViewport />
</FilePreview>
```

## Variants

The frame follows the library's contours. Default is the edge ring with the smallest lift, outline the ring alone, and plain drops the frame for a preview that sits in a surface which already has one: a pane, a card, the dialog (which uses it). None of them paints a fill; the canvas is the one ground, so the document reads the same on every surface.

```tsx
<FilePreview src="/files/living-room.jpg">…</FilePreview>
<FilePreview src="/files/living-room.jpg" variant="outline">…</FilePreview>
<FilePreview src="/files/living-room.jpg" variant="plain">…</FilePreview>
```

## Only the parts you need

Every part can go. Here the canvas stands alone, with no header and no bar: an image inline in a card or a chat message. The keys, the wheel and the pinch still zoom it, because they live on the canvas, not on the buttons. Leave out the rail, the page field or any single control the same way.

```tsx
<FilePreview src="/files/living-room.jpg" className="h-96 max-w-md">
  <FilePreviewViewport />
</FilePreview>
```

## Controlled

Hold the zoom yourself with `zoom` and `onZoomChange`: here a Slider outside the preview drives it, and the buttons, the menu and a pinch inside it report back. `rotation` works the same way, and `defaultPage` with `onPageChange` opens a PDF at a page and follows the reader through it.

```tsx
const [zoom, setZoom] = React.useState<FilePreviewZoom>(0.5)

<Slider
  aria-label="Zoom"
  min={10}
  max={300}
  value={[typeof zoom === "number" ? zoom * 100 : 50]}
  onValueChange={([value]) => setZoom(value / 100)}
/>
<FilePreview src="/files/q3-report.pdf" zoom={zoom} onZoomChange={setZoom}>
  …
</FilePreview>
```

## Keyboard and gestures

The keys work while focus is anywhere in the preview, except in the page field and inside a video player, which keeps its own. The dialog puts focus on the canvas as it opens, and the arrow keys, Page Up/Down and Space scroll it natively.

- **`+` `−`**: Zoom in and out, one step (⌘/Ctrl too, so the browser's own zoom stays out of it)
- **`0`**: Fit the page
- **`⌘/Ctrl` `Wheel`**: Zoom around the pointer (a trackpad pinch arrives the same way)
- **`R` `⇧R`**: Rotate right, rotate left
- **`←` `→`**: Previous and next page, when nothing scrolls sideways
- **`F`**: Full screen
- **`Esc`**: Leave full screen, then close the dialog

On a touch screen one finger scrolls natively, with its momentum, and two pinch. A photo larger than the canvas drags to pan; a document keeps its drag for selecting text.

## PDF setup

PDF.js runs its parser in a Web Worker. In a Next.js app (Turbopack or webpack) the component starts it from the package on first use, with nothing to configure. With another bundler, or to serve the worker yourself (a CDN, a shared worker), set `GlobalWorkerOptions.workerSrc` before the first PDF opens and the component leaves it alone. Documents that rely on the standard fonts, on CJK character maps or on JPEG 2000 images render best with PDF.js's assets available: copy them into `public/` and pass their folders through `pdfOptions`.

```tsx title="report-preview.tsx"
// cp -r node_modules/pdfjs-dist/{cmaps,standard_fonts,wasm} public/pdfjs/

<FilePreview
  src="/files/q3-report.pdf"
  pdfOptions={{
    cMapUrl: "/pdfjs/cmaps/",
    standardFontDataUrl: "/pdfjs/standard_fonts/",
    wasmUrl: "/pdfjs/wasm/",
  }}
/>
```

```tsx title="pdf-worker.ts"
// Vite: the worker's URL comes from the bundler, then PDF.js is told where it is.
import { GlobalWorkerOptions } from "pdfjs-dist"
import workerSrc from "pdfjs-dist/build/pdf.worker.min.mjs?url"

GlobalWorkerOptions.workerSrc = workerSrc
```

## API reference

### FilePreview

The root. Takes the file as `file` (a `File` or `Blob`) or `src`, with `name`, `type` and `size` to name it when a URL can't, and `kind` to pick the renderer yourself (`pdf` · `image` · `text` · `video` · `audio` · `unsupported`). The view: `zoom` / `defaultZoom` (`"fit"`, `"width"` or a scale; default `"fit"`) with `onZoomChange`, `rotation` / `defaultRotation` with `onRotationChange`, `defaultPage` and `onPageChange`, `minZoom` (0.1) and `maxZoom` (5). Also `variant` (default · outline · plain), `defaultThumbnailsOpen`, `textLayer` (PDF selectable text, on), `pdfOptions` (passed to PDF.js) and `onDownload` to replace the built-in download.

### FilePreviewHeader · FilePreviewIcon · FilePreviewInfo · FilePreviewTitle · FilePreviewMeta · FilePreviewActions

The identity bar. `FilePreviewIcon` is the file's [FileIcon](https://www.koalaui.com/docs/foundations/file-icons.md), `FilePreviewTitle` its name and `FilePreviewMeta` a line composed from what is known (format, size, then the page count, the pixel size, the running time or the line count as the file loads). Children replace the title and the meta.

### FilePreviewDownload · FilePreviewClose

Ghost Buttons for the header. Download saves the file under its own name (a cross-origin URL is fetched first, since the browser ignores `download` there); pass children for a labelled button. Close closes a `FilePreviewDialog`; anywhere else, wire its `onClick`.

### FilePreviewThumbnails

The page rail beside the canvas, from `md` up, for a document with more than one page. Thumbnails paint as the rail scrolls; the current page wears the brand ring.

### FilePreviewViewport

The canvas: renders the file and holds what floats over it. It owns the gestures (wheel, pinch, drag to pan, double-click) and the scroller that takes focus; `contentProps` reaches that scroller.

### FilePreviewToolbar

The bar the controls live in, a [Toolbar](https://www.koalaui.com/docs/components/toolbar.md) that takes the Toolbar's props (`variant`, `size`, `scrollable`, on by default). Floats in the viewport, docks in the header.

### FilePreviewZoomOut · FilePreviewZoomMenu · FilePreviewZoomIn · FilePreviewFit · FilePreviewRotate · FilePreviewPageNav · FilePreviewThumbnailsToggle · FilePreviewFullscreen

The controls, each a ToolbarButton with its tooltip and shortcut. `FilePreviewZoomMenu` takes `presets`, `FilePreviewRotate` a `direction`. Each renders nothing when it has nothing to do for the file in hand, and the fullscreen control nothing where the browser can't go full screen.

### FilePreviewDialog

The preview in a modal: every `FilePreview` prop, plus `open`, `defaultOpen`, `onOpenChange`, `title` (the accessible title, the file name by default) and `previewClassName`. Built on Radix Dialog with the Dialog's own scrim.

## FAQ

### Which files can it show?

PDFs (with PDF.js), every image format the browser decodes (JPEG, PNG, WebP, AVIF, GIF, SVG), text and source files (Markdown, JSON, CSV, code), and the video and audio formats the browser plays. Word, Excel or PowerPoint files are not rendered in the browser: convert them to PDF on your server and preview that, or let the canvas offer the download.

### Does the file leave the browser?

No. A File from an input or a drop is shown through an object URL created on the spot and revoked when the preview lets it go. Nothing is uploaded to preview it.

### How big a PDF can it handle?

Hundreds of pages. Every page gets a placeholder at its true size up front, but only the pages near the view are painted, and bitmaps far off screen are handed back. The canvas behind each page is capped in pixels, lower on touch devices, so zooming a long document never runs a phone out of memory.

### Why does a zoomed page look soft for a moment?

A zoom stretches the bitmap already on screen at once, then repaints the page sharp as soon as the zoom settles. It keeps a pinch at the frame rate of your fingers instead of the speed of the renderer.

### Can I select and copy text from a PDF?

Yes. PDF.js lays the page's text over the picture as transparent runs, so a drag selects real text, copy works, and the browser's find-in-page lands on it. Turn it off with textLayer={false} for a picture-only preview.

### Why is the fit for a photo sometimes smaller than the canvas?

A photo never grows past its own pixels on "fit", the way object-fit: scale-down behaves. Fit to width, a fixed level or a double-click still take it past 100% when you ask.

### Does rotating change the file?

No. Rotation, like zoom, is a view setting: the download saves the original file untouched.

### Does it respect reduced motion?

Yes. With prefers-reduced-motion the page arrows jump instead of gliding, the rotation of a photo doesn't animate, and the play/pause glyphs swap without the cross-fade.

---

<!-- https://www.koalaui.com/docs/components/file-upload.md -->

# File Upload

The uploading experience: a drag-and-drop dropzone, a browse trigger, import shortcuts and built-in accept, size and count validation. Pairs with File Card for the resulting rows and per-file progress.

```tsx
<Field required>
  <FieldLabel>Upload image</FieldLabel>
  <FileUpload multiple accept="image/*,.pdf,.zip" onFiles={addItems}>
    <FileUploadDropzone>
      <FileUploadIcon />
      <FileUploadTitle>
        Drag and drop your files, or <FileUploadLink />
      </FileUploadTitle>
      <FileUploadTrigger className="w-full">Upload files</FileUploadTrigger>
    </FileUploadDropzone>

    <FileUploadList>
      {items.map((it) => (
        <FileCard key={it.id} state={it.status}>
          <FileCardIcon type={it.type} />
          <FileCardContent>
            <FileCardName>{it.name}</FileCardName>
            {it.status === "uploading" ? (
              <FileCardProgress value={it.progress} hideValue />
            ) : (
              <FileCardMeta>{formatBytes(it.size)}</FileCardMeta>
            )}
          </FileCardContent>
          {it.status === "uploading" && <FileCardValue>{it.progress}%</FileCardValue>}
          <FileCardActions>
            <FileCardStatus />
            <Button variant="ghost" size="sm" iconOnly aria-label="Remove" onClick={() => removeItem(it.id)}>
              <Trash />
            </Button>
          </FileCardActions>
        </FileCard>
      ))}
    </FileUploadList>
  </FileUpload>
</Field>
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add file-upload
```

Manual: run `npm install @phosphor-icons/react radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/file-upload/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

File Upload owns *selection*: it emits accepted files through `onFiles` and rejections through `onReject`, and you own the list. Render the resulting rows with [File Card](https://www.koalaui.com/docs/components/file-card.md) inside a `FileUploadList` - the two compose into the full experience.

```tsx title="uploader.tsx"
import {
  FileUpload,
  FileUploadDropzone,
  FileUploadIcon,
  FileUploadTitle,
  FileUploadLink,
  FileUploadTrigger,
  FileUploadList,
  formatBytes,
} from "@/components/ui/file-upload"
import {
  FileCard,
  FileCardIcon,
  FileCardContent,
  FileCardName,
  FileCardMeta,
  fileTypeFromName,
} from "@/components/ui/file-card"

export function Uploader() {
  const [files, setFiles] = React.useState<File[]>([])
  return (
    <FileUpload multiple onFiles={(f) => setFiles((prev) => [...prev, ...f])}>
      <FileUploadDropzone>
        <FileUploadIcon />
        <FileUploadTitle>
          Drag and drop your files, or <FileUploadLink />
        </FileUploadTitle>
        <FileUploadTrigger className="w-full">Upload files</FileUploadTrigger>
      </FileUploadDropzone>

      <FileUploadList>
        {files.map((file, i) => (
          <FileCard key={i}>
            <FileCardIcon type={fileTypeFromName(file.name)} />
            <FileCardContent>
              <FileCardName>{file.name}</FileCardName>
              <FileCardMeta>{formatBytes(file.size)}</FileCardMeta>
            </FileCardContent>
          </FileCard>
        ))}
      </FileUploadList>
    </FileUpload>
  )
}
```

## Anatomy

The `FileUpload` root holds a hidden file input and the shared state; the `FileUploadDropzone` is the dashed drop surface, filled with a `FileUploadIcon`, a `FileUploadTitle` with the `FileUploadLink` sitting inline in the sentence, and a `FileUploadTrigger` (or a `FileUploadSources` row).

The panel is a drop target, not a button. Clicking anywhere on it still opens the picker, but the keyboard path runs through the real controls inside it, so **every dropzone must compose a `FileUploadLink` or a `FileUploadTrigger`**. A `role="button"` panel wrapping those would be a nested-interactive violation and would swallow their Enter/Space.

```tsx
<FileUpload onFiles={handleFiles}>
  <FileUploadDropzone>
    <FileUploadIcon />
    <FileUploadTitle>
      Drag and drop your files, or <FileUploadLink />
    </FileUploadTitle>
    <FileUploadTrigger className="w-full">Upload files</FileUploadTrigger>
  </FileUploadDropzone>
</FileUpload>
```

## Import shortcuts

The local disk isn’t the only place a file lives. Introduce a `FileUploadSources` row with a labelled [Divider](https://www.koalaui.com/docs/components/divider.md) and give each provider a `FileUploadSource` tile. A source owns its own picker - an OAuth flow, a provider SDK, your own modal - so it takes a `onClick` and deliberately does *not* route back into the native file dialog.

The mark is `children`, not a `brand` prop: pass whatever you own - a real logo, an `img`, or a Phosphor glyph.

```tsx
<FileUpload multiple onFiles={handleFiles}>
  <FileUploadDropzone>
    <FileUploadIcon />
    <FileUploadTitle>
      Drag and drop your files, or <FileUploadLink />
    </FileUploadTitle>

    {/* `static`: the smart Divider would otherwise collapse between two blocks */}
    <Divider static>Or import from</Divider>

    <FileUploadSources>
      {SOURCES.map((brand) => (
        <FileUploadSource key={brand.name} label={brand.name} onClick={() => connect(brand)}>
          <BrandLogo brand={brand} className="size-5" />
        </FileUploadSource>
      ))}
    </FileUploadSources>
  </FileUploadDropzone>
</FileUpload>
```

## Thumbnail layout

When the upload *is* the picture, a filename row gets in the way. Swap `FileUploadList` for `FileUploadGrid` and give each File Card `layout="tile"`: the thumbnail fills the square and `FileCardActions` become a scrim that fades in on hover or keyboard focus. The tile never moves - the photo and the scrim carry the whole interaction.

```tsx
<Lightbox images={shots}>
  <FileUploadGrid>
    {shots.map((shot, i) => (
      <FileCard key={shot.src} layout="tile">
        <FileCardThumbnail src={shot.src} alt={shot.alt} />
        <FileCardActions>
          <Button variant="ghost" size="sm" iconOnly aria-label="Delete"
            tone="onMedia"
            onClick={() => remove(shot)}>
            <Trash />
          </Button>
          <LightboxTrigger asChild index={i}>
            <Button variant="ghost" size="sm" iconOnly aria-label="Preview"
              tone="onMedia">
              <Eye />
            </Button>
          </LightboxTrigger>
        </FileCardActions>
      </FileCard>
    ))}
  </FileUploadGrid>
</Lightbox>
```

## Row states

A row in flight reads either way. Put the bar under the name with `<FileCardProgress hideValue />` and move the percentage out to a `FileCardValue` on the right edge; or drop the bar for a plain `FileCardMeta` line when the pause and cancel controls matter more than the number. Once it lands, `FileCardStatus` reads the card’s `state` and lights the check on its own.

```tsx
{/* In flight - bar under the name, percentage on the right edge */}
<FileCard state="uploading">
  <FileCardIcon><ImageSquare /></FileCardIcon>
  <FileCardContent>
    <FileCardName>KoalaUIFinalDesign.jpg</FileCardName>
    <FileCardProgress value={60} hideValue />
  </FileCardContent>
  <FileCardValue>60%</FileCardValue>
</FileCard>

{/* In flight - controls instead of a bar */}
<FileCard state="uploading">
  <FileCardIcon><ImageSquare /></FileCardIcon>
  <FileCardContent>
    <FileCardName>KoalaUIFinalDesign.jpg</FileCardName>
    <FileCardMeta>182.2 MB · 60%</FileCardMeta>
  </FileCardContent>
  <FileCardActions>
    <Button variant="ghost" size="sm" iconOnly aria-label="Pause upload"><Pause /></Button>
    <Button variant="ghost" size="sm" iconOnly aria-label="Cancel upload"><X /></Button>
  </FileCardActions>
</FileCard>

{/* Landed */}
<FileCard state="success">
  <FileCardIcon><ImageSquare /></FileCardIcon>
  <FileCardContent>
    <FileCardName>KoalaUIFinalDesign.jpg</FileCardName>
    <FileCardMeta>182.2 MB</FileCardMeta>
  </FileCardContent>
  <FileCardStatus />
</FileCard>
```

## Browse button

No room for a dropzone? Drop a `FileUploadTrigger` on its own - it opens the same picker, so an attach action is a single button. The trigger reuses the DS [Button](https://www.koalaui.com/docs/components/button.md), so it inherits every variant, size, and the press scale.

```tsx
<FileUpload accept=".pdf,.doc,.docx" onFiles={(f) => setName(f[0]?.name)}>
  <div className="flex items-center gap-3">
    <FileUploadTrigger><Paperclip />Attach a file</FileUploadTrigger>
    <span className="text-sm text-muted-foreground">{name ?? "No file selected"}</span>
  </div>
</FileUpload>
```

## Avatar picker

Compose the trigger with an [Avatar](https://www.koalaui.com/docs/components/avatar.md) for a profile-photo picker: a single-file `image/*` upload that swaps the avatar in place, with a “Change photo” / “Remove” pair.

```tsx
<FileUpload accept="image/*" onFiles={pick}>
  <div className="flex items-center gap-4">
    <AvatarRoot size="xl">
      {url && <AvatarImage src={url} alt="Profile photo" />}
      <AvatarFallback>JC</AvatarFallback>
    </AvatarRoot>
    <div className="flex flex-col gap-2">
      <div className="flex items-center gap-2">
        <FileUploadTrigger size="sm" swapKey={url ? "change" : "upload"}>
          {url ? "Change photo" : "Upload photo"}
        </FileUploadTrigger>
        {url && <Button variant="ghost" size="sm" onClick={remove}>Remove</Button>}
      </div>
      <p className="text-xs text-muted-foreground">JPG, GIF or PNG. 2 MB max.</p>
    </div>
  </div>
</FileUpload>
```

## Validation

Pass `accept`, `maxSize` (bytes), and `multiple`, and dropped or picked files are split for you: `onFiles` gets the keepers, `onReject` gets the rest with a `reason` (`type`, `size`, or `count`) so you can surface a precise message.

```tsx
<FileUpload
  accept=".pdf"
  maxSize={2 * 1024 * 1024}
  onFiles={(accepted) => setFiles((prev) => [...prev, ...accepted])}
  onReject={(rejections) => {
    const r = rejections[0]
    setError(
      r.reason === "size" ? `${r.file.name} is too large - 2 MB max.`
      : r.reason === "type" ? `${r.file.name} isn't a PDF.`
      : "Only one file at a time.",
    )
  }}
>
  <FileUploadDropzone>
    <FileUploadIcon><FilePdf /></FileUploadIcon>
    <FileUploadTitle>Drop a PDF here, or <FileUploadLink /></FileUploadTitle>
    <FileUploadDescription>Single PDF file, up to 2 MB</FileUploadDescription>
  </FileUploadDropzone>
  {error && <p className="text-xs text-destructive">{error}</p>}
</FileUpload>
```

## Density

Density is Koala’s cross-cutting spacing axis (see [Density](https://www.koalaui.com/docs/foundations/density.md)). For File Upload it tunes the dropzone padding, the rhythm between its blocks, and the glyph. Density resolves prop → nearest `DensityProvider` → `compact`, so an unset dropzone renders compact; ask for `comfortable` to get the roomy panel.

```tsx
<FileUpload density="comfortable">…</FileUpload>
<FileUpload density="compact">…</FileUpload>
```

## Disabled

Pass `disabled` to the root and the whole control goes inert - the dropzone stops accepting drops and clicks, the link, trigger and sources disable, and the surface dims.

```tsx
<FileUpload disabled>
  <FileUploadDropzone>
    <FileUploadIcon />
    <FileUploadTitle>Uploads paused</FileUploadTitle>
    <FileUploadDescription>You've reached your storage limit</FileUploadDescription>
    <FileUploadTrigger className="w-full">Upload files</FileUploadTrigger>
  </FileUploadDropzone>
</FileUpload>
```

## API reference

`FileUpload` forwards `div` props and adds `accept`, `multiple`, `maxSize` (bytes), `disabled`, `density` (`comfortable | compact`), `onFiles(files)`, and `onReject(rejections)` (each rejection is `{ file, reason }`).

`FileUploadDropzone` forwards `div` props and renders the drop surface. `FileUploadLink` and `FileUploadTrigger` both open the picker - the first as inline sentence text, the second as a [Button](https://www.koalaui.com/docs/components/button.md) (defaulting to `outline`). `FileUploadSource` takes a `label` plus the provider mark as `children`, and forwards `button` props. `FileUploadIcon`, `FileUploadTitle`, `FileUploadDescription`, `FileUploadSources`, `FileUploadList`, and `FileUploadGrid` forward their element props. The helper `formatBytes(bytes)` renders a human file size for the meta line. Every part accepts `className`, merged last.

## FAQ

### Does File Upload store the selected files for me?

No. It owns selection only: accepted files arrive through `onFiles` and rejections through `onReject`, and you keep the list in your own state. Render that list with File Card inside `FileUploadList` (or `FileUploadGrid` for thumbnails).

### How do I reject files that are too big or the wrong type?

Pass `accept`, `maxSize` (in bytes), and `multiple` to the `FileUpload` root and dropped or picked files are split for you. The keepers go to `onFiles`; the rest go to `onReject` as `{ file, reason }` where reason is `type`, `size`, or `count`.

### Can I use a single button instead of the full dropzone?

Yes. Drop a `FileUploadTrigger` on its own without a `FileUploadDropzone`. It opens the same picker and extends our Button, so it inherits every variant and size (it defaults to `outline`).

### Is the dropzone keyboard accessible?

Through the controls inside it. The panel itself is a drop target rather than a button - a `role="button"` wrapper around the link, trigger and source tiles would be a nested-interactive violation and would swallow their Enter/Space. So compose at least one `FileUploadLink` or `FileUploadTrigger`: that is the keyboard path to the picker.

### What are the import shortcuts for?

`FileUploadSources` + `FileUploadSource` surface the other places a file can come from (Drive, Dropbox, a repo). Each tile is a plain button you wire to that provider's own picker; they do not open the native file dialog.

### How do I show uploaded images as a grid instead of rows?

Use `FileUploadGrid` in place of `FileUploadList` and give each File Card `layout="tile"`. The thumbnail fills the square cell and `FileCardActions` become a scrim that fades in on hover or focus.

### How do I make the whole control inert?

Pass `disabled` to the `FileUpload` root. The dropzone stops accepting drops and clicks, the link, trigger and source tiles disable, and the surface dims.

### How do I tune the dropzone padding for a dense form?

Set `density` to `compact` on the root (the default is `comfortable`), which tightens the dropzone padding, the rhythm between its blocks, and the glyph. Set it per instance or for a whole subtree with `DensityProvider`.

---

<!-- https://www.koalaui.com/docs/components/form.md -->

# Form

The anatomy layer above Field. Field solves one labelled control; Form owns everything around them: the form element and its rhythm, the chapters of a long form, the fieldset, and the bar that closes it.

```tsx
<Form onSubmit={handleSubmit}>
  <FormSection>
    <FormSectionHeader>
      <FormSectionTitle>Contact</FormSectionTitle>
      <FormSectionDescription>Where we send the receipt.</FormSectionDescription>
    </FormSectionHeader>

    <FieldRow>
      <Field required>
        <FieldLabel>First name</FieldLabel>
        <InputRoot><InputField placeholder="Ada" /></InputRoot>
      </Field>
      <Field required>
        <FieldLabel>Last name</FieldLabel>
        <InputRoot><InputField placeholder="Lovelace" /></InputRoot>
      </Field>
    </FieldRow>

    <Field required>
      <FieldLabel>Email</FieldLabel>
      <InputRoot><InputField type="email" placeholder="ada@example.com" /></InputRoot>
      <FieldHint>We'll only use it for this order.</FieldHint>
    </Field>
  </FormSection>

  <FormSection>
    <FormSectionTitle>Delivery</FormSectionTitle>

    <FieldGroup>
      <FieldGroupLabel>Delivery speed</FieldGroupLabel>
      <RadioGroup defaultValue="standard">
        <RadioCard value="standard">
          <RadioCardTitle>Standard</RadioCardTitle>
          <RadioCardDescription>Free, 4 to 6 business days</RadioCardDescription>
        </RadioCard>
        <RadioCard value="express">
          <RadioCardTitle>Express</RadioCardTitle>
          <RadioCardDescription>$12.00, 1 to 2 business days</RadioCardDescription>
        </RadioCard>
      </RadioGroup>
    </FieldGroup>
  </FormSection>

  <FormActions bordered>
    <Button type="button" variant="ghost">Cancel</Button>
    <Button type="submit">Place order</Button>
  </FormActions>
</Form>
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add form
```

Manual: run `npm install radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/form/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Anatomy

Every part answers one question: how many controls does this wrap, and what is it to the reader? Get that right and the spacing, the labelling, and the ARIA all follow without a decision.

| Part | Wraps |
| --- | --- |
| `Form` | The <form> element itself. Owns the vertical rhythm and the height of every control inside it. |
| `Field` | One labelled control. Generates the id / htmlFor / aria-describedby wiring and cascades error and disabled state. |
| `FieldGroup` | Several controls answering one question (a radio set, a checkbox cluster). A real fieldset + legend. |
| `FieldRow` | Two or three fields that belong on one line. Stacks to a single column below sm. |
| `FormSection` | A chapter of a long form, with its own title and description. Gets extra air from the chapter before it, and can set the header beside the fields with layout="split". |
| `FormActions` | The bar that closes the form. Aligns the buttons, optionally rules itself off from the fields above. |
| `InputGroup` | Several controls fused into ONE bordered box (a currency prefix, a url + select). Sits inside a Field, not beside one. |

The line that trips people up is `Field` versus `FieldGroup`. A single “I agree to the terms” checkbox is one control, so it is a `Field`. Three checkboxes picking email preferences answer one question, so they are a `FieldGroup`. And `InputGroup` is not a layout part at all: it fuses several controls into one bordered box, so it lives *inside* a Field where a single control would otherwise go.

## Usage

`Form` renders a plain `form` element, so `action`, `onSubmit`, and server actions all work exactly as they do on the native element. What it adds is the rhythm, so no form in your app has to invent its own gap.

```tsx
import { Form, FormActions } from "@/components/ui/form"
import { Field, FieldLabel } from "@/components/ui/field"

<Form onSubmit={handleSubmit}>
  <Field required>
    <FieldLabel>Email</FieldLabel>
    <InputRoot><InputField type="email" /></InputRoot>
  </Field>

  <FormActions>
    <Button variant="ghost">Cancel</Button>
    <Button type="submit">Continue</Button>
  </FormActions>
</Form>
```

## Control size

A form field is the thing being filled in, not a control tucked into a toolbar, so a Form sets its controls to `lg` (40px) by default. That is the top of the band the industry settled on: shadcn/ui ships a 36px input, Carbon's large is 48px, and touch guidance puts the comfortable range at 32 to 40px with a 44px hit area. 32px reads cramped for something you type into.

One prop retunes the whole form, fields and buttons together, so they can never mismatch. A control's own `size` still wins where you need one exception.

```tsx
<Form size="sm">…</Form>   {/* 32px */}
<Form size="md">…</Form>   {/* 36px */}
<Form>…</Form>             {/* 40px, the default */}
```

Reach for `sm` when the form is really a dense app surface: a filter bar above a table, a settings row inside a compact shell. Everything else, a signup, a checkout, a contact block, wants the default.

## Rhythm and density

Density and size are two different axes, and keeping them apart is what stops a form from drifting. `size` is how tall the controls are; `density` is how much space sits between them. The gap comes from the same axis that tunes every other gap in Koala: `compact` (the default) is 16px, `comfortable` is 20px.

```tsx
<Form density="compact">…</Form>
<Form density="comfortable">…</Form>
```

## Sections

Once a form is long enough to have chapters, wrap each one in a `FormSection`. Sections keep the field rhythm inside themselves and take extra air from the section before them, so a chapter break reads as a break without you reaching for a margin.

```tsx
<Form>
  <FormSection>
    <FormSectionHeader>
      <FormSectionTitle>Account</FormSectionTitle>
      <FormSectionDescription>How you sign in.</FormSectionDescription>
    </FormSectionHeader>
    <Field>…</Field>
  </FormSection>

  <FormSection>
    <FormSectionHeader>
      <FormSectionTitle>Profile</FormSectionTitle>
      <FormSectionDescription>Shown on your public page.</FormSectionDescription>
    </FormSectionHeader>
    <Field>…</Field>
    <Field>…</Field>
  </FormSection>
</Form>
```

`FormSectionTitle` renders an `h3`. When that is the wrong level for the page outline, pass `asChild` and bring your own heading: `<FormSectionTitle asChild><h2>Shipping</h2></FormSectionTitle>`.

`layout="split"` sets the header *beside* the fields instead of above them: the settings row you know from Stripe, Linear, and Tailwind UI. It stacks back to one column below `md`. Split sections need a `FormSectionBody` around the fields, because in a grid each field would otherwise claim a cell of its own instead of sharing the column.

```tsx
<FormSection layout="split" density="comfortable" className="border-t border-border py-8">
  <FormSectionHeader>
    <FormSectionTitle className="text-base">Profile</FormSectionTitle>
    <FormSectionDescription>This information is shown to your teammates.</FormSectionDescription>
  </FormSectionHeader>
  <FormSectionBody density="comfortable">
    <Field>…</Field>
    <Field>…</Field>
  </FormSectionBody>
</FormSection>
```

A section is also the form body where a `form` element can't go: inside a Dialog the actions belong to `DialogFooter`, so there is nothing to submit. There it stays pure layout, which keeps the fields the same height as the dialog's own buttons. Pass `size` on the section if you want the taller form controls anyway, or to give one chapter a different height from the rest.

## Field groups

When several controls answer one question, a label has nothing to point at: there is no single control to name. `FieldGroup` is a real `fieldset` and `FieldGroupLabel` a real `legend`, which is the one construct that names a set of controls with no ARIA at all. The hint below works the same as in a Field, and describes the whole group.

```tsx
<FieldGroup>
  <FieldGroupLabel required>Email preferences</FieldGroupLabel>
  <div className="flex flex-col gap-2.5">
    <label className="flex items-center gap-2.5 text-sm">
      <Checkbox defaultChecked />
      Product updates
    </label>
    <label className="flex items-center gap-2.5 text-sm">
      <Checkbox />
      Weekly digest
    </label>
  </div>
  <FieldHint>Pick at least one. You can change this any time.</FieldHint>
</FieldGroup>
```

`hasError` turns the hint into an error message, exactly as on a Field. `disabled` is the native fieldset attribute, so it disables every control nested inside without a single prop being passed down.

```tsx
<FieldGroup hasError>
  <FieldGroupLabel required>Delivery speed</FieldGroupLabel>
  <RadioGroup>…</RadioGroup>
  <FieldHint>Choose a delivery speed to continue.</FieldHint>
</FieldGroup>

<FieldGroup disabled>
  <FieldGroupLabel>Delivery speed</FieldGroupLabel>
  <RadioGroup defaultValue="standard">…</RadioGroup>
  <FieldHint>Delivery is set by your plan.</FieldHint>
</FieldGroup>
```

Do not add an `aria-label` to the control inside a group. The legend already names the set, and a second name only makes a screen reader say it twice.

## Rows

`FieldRow` puts fields that belong together on one line, and stacks them to a single column below `sm` so nothing gets cramped. It takes `columns` of 2 (the default) or 3.

```tsx
<FieldRow>
  <Field>…</Field>
  <Field>…</Field>
</FieldRow>

<FieldRow columns={3}>
  <Field>…</Field>
  <Field>…</Field>
  <Field>…</Field>
</FieldRow>
```

## Actions

`FormActions` closes the form. `end` (the default) is the ghost + primary pairing; `between` pushes a destructive action away from the primary one; `stack` is the full-width submit a signup or checkout wants. Add `bordered` when the form is long enough that the bar needs a seam, and put a status message in as a first child with `mr-auto`.

```tsx
<FormActions>
  <Button variant="ghost">Cancel</Button>
  <Button>Save changes</Button>
</FormActions>

<FormActions align="between">
  <Button variant="destructiveGhost">Delete</Button>
  <Button>Save changes</Button>
</FormActions>

<FormActions align="stack">
  <Button>Create account</Button>
</FormActions>

<FormActions bordered>
  <span className="mr-auto text-sm font-medium text-success">All changes saved</span>
  <Button variant="ghost">Cancel</Button>
  <Button>Save changes</Button>
</FormActions>
```

## One-line capture

A newsletter or waitlist form is one field and one button, not a column. `layout="row"` is that shape: the field grows, the button hugs, and the pair stacks below `sm`. It is the same layout `NewsletterForm` and `WaitlistForm` use, so the three can never drift apart.

```tsx
<Form layout="row" onSubmit={handleSubmit}>
  {/* w-full, not flex-1: flex-1 collapses the field's height when the row stacks. */}
  <InputRoot className="w-full">
    <InputPrefix><EnvelopeSimple weight="bold" /></InputPrefix>
    <InputField type="email" placeholder="you@company.com" aria-label="Work email" />
  </InputRoot>
  <Button type="submit" className="shrink-0 max-sm:w-full">Subscribe</Button>
</Form>
```

There is a third layout, `plain`, for when the form element *is* a card whose header, body, and footer sit flush against its borders. It contributes no rhythm at all, leaving a `FormSection` inside to own the field spacing. `SettingsForm` is built that way.

## Validation: bring your own

Form ships no validation, no schema prop, and no state. That is deliberate: most teams have already picked a form library or are using server actions, and a design system that insists on its own choice is one you have to fight. Field already exposes the surface validation needs, `hasError` and a `FieldHint` that doubles as the error message, so wiring any resolver is a few lines.

```tsx
// react-hook-form
const { register, handleSubmit, formState: { errors } } = useForm()

<Form onSubmit={handleSubmit(onValid)}>
  <Field required hasError={!!errors.email}>
    <FieldLabel>Email</FieldLabel>
    <InputRoot><InputField {...register("email", { required: true })} /></InputRoot>
    <FieldHint>{errors.email ? "Enter a valid email." : "We'll send a receipt here."}</FieldHint>
  </Field>
  <FormActions><Button type="submit">Continue</Button></FormActions>
</Form>
```

```tsx
// Server action, no client library at all
const [state, action] = useActionState(subscribe, {})

<Form action={action}>
  <Field required hasError={!!state.errors?.email}>
    <FieldLabel>Email</FieldLabel>
    <InputRoot><InputField name="email" type="email" /></InputRoot>
    <FieldHint>{state.errors?.email ?? "We'll send a receipt here."}</FieldHint>
  </Field>
  <FormActions><Button type="submit">Continue</Button></FormActions>
</Form>
```

## FAQ

### When do I use Field and when do I use FieldGroup?

Count the controls that answer the question. One control is a Field, so a single 'I agree to the terms' checkbox is a Field. Several controls answering one question is a FieldGroup, so a radio set or a cluster of preference checkboxes is a FieldGroup. The difference matters for more than spacing: a group has no single control for a label to point at, which is why FieldGroup renders a real fieldset and legend.

### Why does FieldGroup use fieldset and legend instead of ARIA?

A fieldset with a legend is the one construct in HTML that names a set of controls with no ARIA at all, and its disabled attribute natively disables everything nested inside it, so FieldGroup disabled needs to pass nothing down to the controls. Reaching for role='group' plus aria-labelledby would reimplement, badly, what the browser already does.

### Does Form handle validation?

No, and that is deliberate. Form renders a plain form element and owns layout and semantics only, so react-hook-form, Formik, server actions, or nothing at all all work unchanged. Field already gives validation everything it needs: set hasError on the Field and put the message in the FieldHint.

### What gap should I use between fields?

None of your own: Form owns it. The gap comes from density, compact at 16px (the default) and comfortable at 20px, which is the same axis that tunes every other gap in Koala. If you find yourself adding a margin between fields, you probably want a FormSection instead.

### Why are form controls taller than the same control elsewhere?

Because a Form sets its controls to lg (40px) by default, while a bare control follows density and lands at 32px in a compact shell. A field you type into is not the same as a control tucked into a toolbar, and 40px is the top of the band the industry uses: shadcn/ui ships 36px, Carbon's medium is 40px, and touch guidance wants 40px or a 44px hit area. Pass size on the Form to change it for the whole form at once.

### How do I make one control a different size from the rest of the form?

Put size on that control. The precedence runs most-local-first: the control's own size beats an explicit density on the control, which beats the size the Form imposes, which beats the ambient density. So the Form's size is a default, never an override, and a single field can opt out without you rewriting the form.

### Does density still affect control heights?

Only outside a Form. Density picks the default size for a bare control (compact picks sm, comfortable picks md), but inside a Form the Form's size wins, so the two axes stop fighting: size is how tall the controls are, density is how much space sits between them.

### Can I put a Form inside a Dialog?

Yes, and context follows the component tree rather than the DOM, so all the Field wiring keeps working through Radix's Portal. Use DialogFooter rather than FormActions for the dialog's buttons: an overlay's actions reverse to a stacked column on mobile so the primary action sits under the thumb, which is a different rule from a form in the page flow.

### How is InputGroup different from FieldRow?

FieldRow is layout: separate fields, each with its own label and border, laid side by side. InputGroup is a single control surface: several controls fused into ONE bordered box with hairline seams between them, like a currency prefix beside an amount. An InputGroup goes inside a Field, where one control would otherwise sit.

### Do I still need aria-label on a RadioGroup inside a FieldGroup?

No. The legend names the set, and adding an aria-label on the control gives it a second name that a screen reader will read out twice. A RadioGroup dropped into a plain Field is the case that does need the wiring, and it gets it automatically: because a RadioGroup renders a div that htmlFor cannot name, it picks up aria-labelledby from the Field's label instead.

---

<!-- https://www.koalaui.com/docs/components/hover-card.md -->

# Hover Card

A preview that opens while the pointer rests on a link: the profile behind a mention, the page behind a link, the commit behind a hash. Popover's surface, grown out of the link it previews.

```tsx
<HoverCard>
  <HoverCardTrigger asChild>
    <Link href="/people/katiep" variant="prose">@katiep</Link>
  </HoverCardTrigger>
  <HoverCardContent className="w-80">
    <div className="flex gap-3">
      <AvatarRoot size="lg">
        <AvatarImage src="https://i.pravatar.cc/160?img=5" alt="Katie Park" />
        <AvatarFallback>KP</AvatarFallback>
      </AvatarRoot>
      <div className="flex flex-col gap-1">
        <HoverCardTitle>Katie Park</HoverCardTitle>
        <span className="text-sm text-muted-foreground">@katiep · Design Systems at Koala</span>
      </div>
    </div>
    <HoverCardDescription>Tokens, type and the occasional motion curve…</HoverCardDescription>
    {/* location and join date */}
    <HoverCardFooter className="gap-4">
      <span><span className="font-semibold tabular-nums">128</span> following</span>
      <span><span className="font-semibold tabular-nums">2,418</span> followers</span>
    </HoverCardFooter>
  </HoverCardContent>
</HoverCard>
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add hover-card
```

Manual: run `npm install radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/hover-card/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

```tsx title="usage.tsx"
import {
  HoverCard,
  HoverCardTrigger,
  HoverCardContent,
} from "@/components/ui/hover-card"

export function Example() {
  return (
    <HoverCard>
      <HoverCardTrigger asChild>
        <a href="/people/katiep">@katiep</a>
      </HoverCardTrigger>
      <HoverCardContent>Katie Park, Design Systems</HoverCardContent>
    </HoverCard>
  )
}
```

## Link preview

The page behind a link. `HoverCardMedia` sets the picture 8px in from the card's edges instead of bleeding to them, with concentric corners (the card's 16px radius minus 8px of inset leaves 8px on the picture). The copy under it keeps the card's own 16px. It is aspect-video until you give it another ratio.

```tsx
<HoverCardContent className="w-80">
  <HoverCardMedia>
    <img src="…" alt="A style guide spread" />
  </HoverCardMedia>
  <div className="mt-3 flex flex-col gap-1">
    <span className="text-xs font-medium text-muted-foreground">koalaui.com/changelog</span>
    <HoverCardTitle>Koala 2.4: density comes to every form</HoverCardTitle>
    <HoverCardDescription>One size prop across fields, selects and buttons…</HoverCardDescription>
  </div>
</HoverCardContent>
```

## Commit preview

A reference in running text, opened into what it points at: the subject, the author, and the size of the change. The counts sit in `HoverCardFooter`, a muted well set in from the card's edges like the media, where a divider line would otherwise go. They are `tabular-nums`, so a column of them lines up. `align="start"` opens the card from the hash's left edge.

```tsx
<HoverCard>
  <HoverCardTrigger asChild>
    <Link href="/commits/8f3a2c1" variant="prose" className="font-mono">8f3a2c1</Link>
  </HoverCardTrigger>
  <HoverCardContent className="w-80" align="start">
    <HoverCardTitle>Select: cap the popper at the space left on screen</HoverCardTitle>
    {/* author row */}
    <HoverCardFooter className="justify-between">
      <span className="font-mono tabular-nums">
        <span className="text-success-strong">+128</span>
        <span className="text-destructive-strong">−14</span>
      </span>
      <Badge variant="success"><SealCheck weight="fill" /> Verified</Badge>
    </HoverCardFooter>
  </HoverCardContent>
</HoverCard>
```

## Placement

`side`, `align` and `sideOffset` are Radix's, and the card flips when the side you asked for has no room. `showArrow` adds a pointer toward the link. The card grows out of the trigger it previews, from Radix's transform origin, rather than from its own centre. These open after 150ms so you can sweep across them.

```tsx
<HoverCard openDelay={150}>
  <HoverCardTrigger asChild><Link href="#" variant="prose">Top</Link></HoverCardTrigger>
  <HoverCardContent side="top" showArrow density="compact" className="w-56">
    <HoverCardTitle>Opens top</HoverCardTitle>
    <HoverCardDescription>Collision-aware: it flips when there is no room on this side.</HoverCardDescription>
  </HoverCardContent>
</HoverCard>
```

## Timing

The card waits `openDelay` (700ms) before it opens, so a pointer passing over a paragraph full of links doesn't set off a string of cards, and `closeDelay` (300ms) after the pointer leaves, which is the time it has to cross the gap into the card. Both are props on `HoverCard`. Shorten the open delay where the preview is the point (a list of people), and keep the close delay: without it the card vanishes on the way to it.

## Accessibility

A hover card is for sighted pointer users. It opens when the trigger has focus, but the card never takes focus and it never opens on touch, so everything in it must also be reachable where the link goes. Make the trigger a real link to that place, and never put the only way to do something inside the card. When the content has to be operated, use a Popover, which opens on a click and moves focus into itself.

## API reference

### HoverCard

The root, no DOM. Props: `openDelay` (700), `closeDelay` (300), `open`, `defaultOpen`, `onOpenChange`.

### HoverCardTrigger

Renders an `<a>`; pass `asChild` to use your own link (a `Link`, a Next.js link).

### HoverCardContent

The card, portalled to the body. Props: `side`, `align` (`center`), `sideOffset` (8), `showArrow`, `density` (`comfortable` 16px padding · `compact` 12px), `className`. It declares `--surface`, so a nested control blends with the card.

### HoverCardTitle · HoverCardDescription

Optional type for the card: an `<h4>` title and a muted `<p>`, the same pair Popover uses.

### HoverCardMedia · HoverCardFooter

The inset parts, Popover's own. `HoverCardMedia` frames one `<img>` or `<video>` (aspect-video, override with `className`), first or last in the card. `HoverCardFooter` is a muted flex row that always closes the card. Both sit 8px in from the edges (4px at `compact`) with a concentric radius, and neither takes a `density` of its own.

## FAQ

### Hover Card, Tooltip or Popover?

A Tooltip names a control in a few words and never takes the pointer. A Hover Card previews where a link goes, and the pointer can move into it. A Popover opens on a click and takes focus, so it is the one for anything that has to be operated: forms, pickers, confirmations.

### Can the card hold links and buttons?

Links, yes: the pointer can move into the card and follow one. Keep buttons to shortcuts for things that also exist on the linked page, since keyboard and touch users never see the card.

### Why doesn't it open on my phone?

There is no hover on touch, and a tap has to follow the link. That is why the trigger must be a real link that goes where the card was previewing.

### Why is the trigger an anchor?

Because a hover card previews a destination, and the trigger is how you get there. Radix renders an `<a>`; with `asChild` you pass your own Link, which keeps client-side navigation.

### Why does it look exactly like a Popover?

It is built on Popover's recipe, extended rather than copied, so a change to the popover surface reaches both. The one addition is the transform origin: the card grows out of the link instead of from its own centre.

---

<!-- https://www.koalaui.com/docs/components/input.md -->

# Input

A compound text field with a label, optional hint, prefix icons, suffix icons, prefix labels, and interactive suffix buttons. Built with slots and Context - each part is a named export.

```tsx
<div className="flex flex-col gap-1.5">
  <InputLabel htmlFor="search">Search</InputLabel>
  <InputRoot>
    <InputPrefix><MagnifyingGlass /></InputPrefix>
    <InputField id="search" placeholder="Search components…" />
  </InputRoot>
</div>
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add input
```

Manual: run `npm install radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/input/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

```tsx title="usage.tsx"
import {
  InputRoot,
  InputField,
  InputLabel,
} from "@/components/ui/input"

export function Example() {
  return (
    <div className="flex flex-col gap-1.5">
      <InputLabel htmlFor="email">Email</InputLabel>
      <InputRoot>
        <InputField id="email" placeholder="you@example.com" type="email" />
      </InputRoot>
    </div>
  )
}
```

## Playground

The props dress the shell; the parts are everything around the field. A label, a hint, a leading icon and a trailing slot are all children you compose, so each one you switch off disappears from the code.

## Label & hint

`InputLabel` sits above the control - wire it to the field with `htmlFor` pointing at the `InputField`’s `id` so clicking the label focuses the input. Pass `required` to append a destructive asterisk. `InputHint` renders helper text below; give it an `id` and reference it from the field’s `aria-describedby`.

```tsx
<div className="flex flex-col gap-1.5">
  <InputLabel htmlFor="workspace" required>
    Workspace name
  </InputLabel>
  <InputRoot>
    <InputField
      id="workspace"
      placeholder="koala-ui"
      aria-describedby="workspace-hint"
    />
  </InputRoot>
  <InputHint id="workspace-hint">
    Used in your team URL. Lowercase letters and dashes only.
  </InputHint>
</div>
```

## Prefix icon

Use `InputPrefix` to place a decorative icon on the left. The slot sizes any `svg` automatically and marks it `aria-hidden` so it stays invisible to assistive tech.

```tsx
<div className="flex flex-col gap-1.5">
  <InputLabel htmlFor="email-prefix">Email address</InputLabel>
  <InputRoot>
    <InputPrefix><EnvelopeSimple /></InputPrefix>
    <InputField id="email-prefix" placeholder="you@example.com" type="email" />
  </InputRoot>
</div>
```

## Suffix icon

Use `InputSuffix` to place a decorative icon on the right - useful for status indicators or type hints.

```tsx
<div className="flex flex-col gap-1.5">
  <InputLabel htmlFor="search-suffix">Search</InputLabel>
  <InputRoot>
    <InputField id="search-suffix" placeholder="Search…" />
    <InputSuffix><MagnifyingGlass /></InputSuffix>
  </InputRoot>
</div>
```

## Prefix label

`InputPrefixLabel` renders a fixed text segment flush against the left border - ideal for URL schemes, currency symbols, or units. It uses a negative margin to reach the container edge and `overflow-hidden` on the root clips it at the rounded corner.

```tsx
<div className="flex flex-col gap-1.5">
  <InputLabel htmlFor="domain">Custom domain</InputLabel>
  <InputRoot>
    <InputPrefixLabel>https://</InputPrefixLabel>
    <InputField id="domain" placeholder="yourdomain.com" />
  </InputRoot>
</div>

<div className="flex flex-col gap-1.5">
  <InputLabel htmlFor="domain-icon">Custom domain</InputLabel>
  <InputRoot>
    <InputPrefixLabel><Globe /></InputPrefixLabel>
    <InputField id="domain-icon" placeholder="yourdomain.com" />
  </InputRoot>
</div>
```

## Suffix button

`InputSuffixButton` renders an interactive ghost button inside the field - e.g. a clear action. Always pass `aria-label` since there is no visible text.

```tsx
<div className="flex flex-col gap-1.5">
  <InputLabel htmlFor="clearable">Project name</InputLabel>
  <InputRoot>
    <InputField id="clearable" defaultValue="clearable value" />
    <InputSuffixButton aria-label="Clear" onClick={() => {}}>
      <X className="size-4" />
    </InputSuffixButton>
  </InputRoot>
</div>
```

## Password

`PasswordInput` is a convenience wrapper that manages the show/hide toggle internally. It renders `InputRoot` + `InputField` + `InputSuffixButton` with an Eye / EyeSlash icon from Phosphor. Pass `rootClassName` to style the wrapper, and all other props go to the underlying `input` element.

```tsx
<div className="flex flex-col gap-1.5">
  <InputLabel htmlFor="password">Password</InputLabel>
  <PasswordInput id="password" placeholder="Enter your password" />
</div>
```

## Number

`NumberInput` adds stepper controls that clamp to `min`/`max`, snap to `step`, and respond to `↑`/`↓` keys, click, and press-and-hold to repeat. The default `stacked` carets sit on the right; `layout="inline"` gives a `−` / `+` quantity stepper with full-height hit targets.

```tsx
// stacked (default)
<NumberInput value={value} onValueChange={setValue} min={0} max={100} />

// inline quantity stepper
<NumberInput layout="inline" value={qty} onValueChange={setQty} min={1} max={10} />
```

## Quantity stepper

The `layout="inline"` `NumberInput` **is** the `−` value `+` quantity stepper: compact, clamped at `min`, and keyboard- and hold-to-repeat friendly. It's the control behind a cart row's [`OrderSummaryItemQuantity`](https://www.koalaui.com/docs/components/order-summary.md) (see Order Summary → Shopping cart). Give it a fixed `rootClassName` width so it stays tidy in a row.

```tsx
<NumberInput
  layout="inline"
  size="sm"
  value={qty}
  onValueChange={setQty}
  min={1}
  max={99}
  rootClassName="w-24"
  aria-label="Quantity"
/>
```

## Phone

`PhoneInput` pairs the field with a searchable country picker - circular flags, type-to-filter, full keyboard navigation, and a live `+code` prefix. `onChange` reports a `{ country, dialCode, nationalNumber, e164 }` payload; store `e164` as the canonical value. The country segment takes the field's resolved size, so inside a `Form` it grows with the other controls and its hover fills flush to the border.

```tsx
<PhoneInput
  defaultCountry="US"
  defaultValue="555 0142"
  onChange={(p) => console.log(p.e164)}
/>
```

## Sizes

Three sizes on a 4px grid - `sm` (32 px), `md` (36 px, the default), and `lg` (40 px). Set `size` on `InputRoot`; all parts pick it up from context.

```tsx
<div className="flex flex-col gap-1.5">
  <InputLabel htmlFor="size-sm">Small</InputLabel>
  <InputRoot size="sm">
    <InputField id="size-sm" placeholder="Small" />
  </InputRoot>
</div>

<div className="flex flex-col gap-1.5">
  <InputLabel htmlFor="size-md">Medium (default)</InputLabel>
  <InputRoot size="md">
    <InputField id="size-md" placeholder="Medium" />
  </InputRoot>
</div>

<div className="flex flex-col gap-1.5">
  <InputLabel htmlFor="size-lg">Large</InputLabel>
  <InputRoot size="lg">
    <InputField id="size-lg" placeholder="Large" />
  </InputRoot>
</div>
```

## Error

Pass `hasError` to `InputRoot` to switch the border and focus ring to the destructive color and set `aria-invalid` on the underlying `input`. Pass the same `hasError` to `InputHint` so the helper text doubles as the error message.

```tsx
<div className="flex flex-col gap-1.5">
  <InputLabel htmlFor="email-error" required>Email</InputLabel>
  <InputRoot hasError>
    <InputField
      id="email-error"
      defaultValue="wrong@"
      type="email"
      aria-describedby="email-error-hint"
    />
  </InputRoot>
  <InputHint id="email-error-hint" hasError>
    Enter a valid email address.
  </InputHint>
</div>
```

## Disabled

```tsx
<div className="flex flex-col gap-1.5">
  <InputLabel htmlFor="disabled">Email</InputLabel>
  <InputRoot disabled>
    <InputField id="disabled" placeholder="Disabled" />
  </InputRoot>
</div>
```

## Inline

Pass `variant="inline"` to `InputRoot` for a chromeless field: the border and fill stay invisible at rest and the container only materializes on hover, while focus keeps the usual brand ring. Perfect for edit-in-place UI - editable titles, table cells, or settings rows that should read as plain text until you reach for them.

```tsx
<div className="flex flex-col gap-1.5">
  <InputLabel htmlFor="inline-title">Project title</InputLabel>
  <InputRoot variant="inline">
    <InputField id="inline-title" defaultValue="Untitled project" />
  </InputRoot>
</div>
```

## FAQ

### Why is the input split into InputRoot and InputField?

`InputRoot` is the bordered container that owns the size, error, and disabled state and shares it via context, while `InputField` is the actual `<input>`. Splitting them lets `InputPrefix`, `InputSuffix`, and buttons sit inside the same border as siblings of the field.

### Where do I set the size, and does it propagate to the parts?

Set `size` on `InputRoot` (`sm`, `md`, the default, or `lg`). Every part reads it from context, so the prefix, suffix, and field all scale together.

### When should I use InputSuffix versus InputSuffixButton?

Use `InputSuffix` for a decorative, non-interactive icon (it is marked `aria-hidden`). Use `InputSuffixButton` for an interactive control like a clear action, and always pass `aria-label` since it has no visible text.

### How do I show a validation error?

Pass `hasError` to `InputRoot` to switch the border and focus ring to the destructive color and set `aria-invalid` on the input. Pass the same `hasError` to `InputHint` so the helper text reads as the error message.

### Should I build my own password show/hide toggle?

No. Use `PasswordInput`, which wraps `InputRoot` + `InputField` + `InputSuffixButton` and manages the Eye / EyeSlash toggle internally. Use `rootClassName` to style the wrapper; other props pass through to the input.

### What value should I store from PhoneInput?

Store `e164` as the canonical value. `onChange` reports a `{ country, dialCode, nationalNumber, e164 }` payload, and `e164` is the normalized form you can persist and re-parse.

### Why does the text grow to 16px on a phone?

On a touch screen, `sm` and `md` fields switch from 14px to 16px text (`pointer-coarse:text-base`). iOS zooms the whole page into any focused field under 16px, and it decides by input device rather than screen width, so the rule keys on the pointer too: a desktop keeps 14px at any width. Textarea, PromptInput, the compact Command search, and the Select, MultiSelect, DatePicker and CountrySelect triggers that sit beside a field do the same.

### What happens when the browser autofills the field?

The frame takes a 6% brand tint over whatever surface it sits on, and the text keeps the theme's foreground color. Without it, Chrome and Safari paint their own yellow or blue and force near-black text, which is unreadable in the dark themes. It comes from the `autofill-tint` and `autofill-clear` utilities in globals.css, already applied to `InputRoot` and `InputField`.

---

<!-- https://www.koalaui.com/docs/components/input-group.md -->

# Input Group

Joins several controls, a field, a Select, a static affix, a small icon-only action, into one seamless segmented shell. The group owns the border and focus ring; each segment goes chromeless and melts in.

```tsx
<InputGroup>
  <InputGroupAddon>$</InputGroupAddon>
  <InputRoot>
    <InputField inputMode="decimal" defaultValue="1,250.00" className="tabular-nums" aria-label="Amount" />
  </InputRoot>
  <Select defaultValue="usd">
    <SelectTrigger aria-label="Currency">
      <SelectValue />
    </SelectTrigger>
    <SelectContent>
      <SelectItem value="usd"><CurrencyDollar /> USD</SelectItem>
      <SelectItem value="eur"><CurrencyEur /> EUR</SelectItem>
      <SelectItem value="gbp"><CurrencyGbp /> GBP</SelectItem>
    </SelectContent>
  </Select>
</InputGroup>
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add input-group
```

Manual: run `npm install radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/input-group/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

```tsx title="usage.tsx"
import { InputGroup, InputGroupAddon } from "@/components/ui/input-group"
import { InputRoot, InputField } from "@/components/ui/input"

export function Example() {
  return (
    <InputGroup>
      <InputGroupAddon>https://</InputGroupAddon>
      <InputRoot>
        <InputField placeholder="yourcompany" />
      </InputRoot>
      <InputGroupAddon>.com</InputGroupAddon>
    </InputGroup>
  )
}
```

## When to reach for it

An `Input` already handles adornments *inside a single field* - a leading icon (`InputPrefix`), a divided label (`InputPrefixLabel`), a trailing icon button (`InputSuffixButton`). Reach for `InputGroup` only when you need to *join several distinct controls* - a Select, another field, a static affix - into one unit. One shell, one focus ring, one set of rounded corners.

A prominent *text* action - Subscribe, Invite, Search - does not belong inside the shell. Crammed in, it reads as a button trapped in a field. Keep it a detached `Button` beside the group instead (see below). Only a small *icon-only* action may melt in.

## Pairing with an action

Do not fuse a big text button into the field. Drop the group (or a plain `InputRoot`) and the `Button` into one flex row (`items-stretch gap-2`) at the same size: the field flexes, the button caps the row from *outside*, and the heights line up on their own. It reads as a real button, not a segment.

```tsx
<div className="flex items-stretch gap-2">
  <InputRoot className="flex-1">
    <InputPrefix>
      <Envelope />
    </InputPrefix>
    <InputField type="email" placeholder="Enter your email address" aria-label="Email address" />
  </InputRoot>
  <Button>Subscribe</Button>
</div>
```

## With a Select

Drop a real `Select` in as a segment and it melts into the shell - its own border, ring, and background are stripped while its menu, keyboard nav, and ARIA stay intact. The field flexes to fill the row. The `Invite` action, being a text button, stays detached beside the group - same rule as the newsletter, one step richer.

```tsx
<div className="flex items-stretch gap-2">
  <InputGroup className="flex-1">
    <Select defaultValue="member">
      <SelectTrigger aria-label="Role">
        <SelectValue />
      </SelectTrigger>
      <SelectContent>
        <SelectItem value="admin"><ShieldCheck /> Admin</SelectItem>
        <SelectItem value="member"><User /> Member</SelectItem>
        <SelectItem value="viewer"><Eye /> Viewer</SelectItem>
      </SelectContent>
    </Select>
    <InputRoot>
      <InputField type="email" placeholder="teammate@company.com" aria-label="Email to invite" />
    </InputRoot>
  </InputGroup>
  <Button>Invite</Button>
</div>
```

## Text affixes

`InputGroupAddon` is a static, non-interactive segment for a unit, protocol, or symbol. It shares the shell background and reads as a muted label, on either side of the field.

```tsx
<InputGroup>
  <InputGroupAddon>https://</InputGroupAddon>
  <InputRoot>
    <InputField placeholder="yourcompany" aria-label="Subdomain" />
  </InputRoot>
  <InputGroupAddon>.com</InputGroupAddon>
</InputGroup>

<InputGroup>
  <InputGroupAddon>@</InputGroupAddon>
  <InputRoot>
    <InputField placeholder="username" aria-label="Username" />
  </InputRoot>
</InputGroup>
```

## Icon-only actions can melt in

The one action that *may* live inside the shell is a small *icon-only* button - copy, clear, a submit arrow. With no label to crowd the field, it sits flush as a fused segment: it keeps its fill and hover but drops its own radius, ring, and press-scale. Use `iconOnly` and give it an `aria-label`.

```tsx
<InputGroup>
  <InputGroupAddon>koala.dev/</InputGroupAddon>
  <InputRoot>
    <InputField readOnly defaultValue="s/ab12cd" aria-label="Share link" className="font-mono" />
  </InputRoot>
  <Button iconOnly variant="ghost" aria-label="Copy link" onClick={copy}>
    {copied ? <Check /> : <Copy />}
  </Button>
</InputGroup>
```

## Sizes

The `size` prop sets the shell height (`sm` 32, `md` 36, `lg` 40px) and the affix scale. Give the inner controls - and the detached Button - the matching size so every part lines up.

```tsx
<div className="flex items-stretch gap-2">
  <InputGroup size="sm" className="flex-1">
    <Select defaultValue="member">{/* ... */}</Select>
    <InputRoot size="sm">{/* ... */}</InputRoot>
  </InputGroup>
  <Button size="sm">Invite</Button>
</div>

{/* size="md" ... size="lg" ... */}
```

## States

`hasError` paints the whole shell red and turns the focus ring destructive; `disabled` dims and locks the row. Inside a `Field`, both cascade automatically. For form semantics, also disable the inner control so it is excluded from submission.

```tsx
<InputGroup hasError>
  <InputGroupAddon>@</InputGroupAddon>
  <InputRoot>
    <InputField defaultValue="not an email" aria-label="Email" />
  </InputRoot>
</InputGroup>

<InputGroup disabled>
  <InputGroupAddon>https://</InputGroupAddon>
  <InputRoot>
    <InputField defaultValue="koala" disabled aria-label="Subdomain" />
  </InputRoot>
  <InputGroupAddon>.com</InputGroupAddon>
</InputGroup>
```

## API reference

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| size | "sm" \| "md" \| "lg" | "md" | Shell height + affix sizing. Match it on the inner controls. |
| hasError | boolean | - | Error styling. Cascades from a surrounding Field. |
| disabled | boolean | - | Dim and lock the shell. Cascades from a surrounding Field. |
| ...divProps | ComponentProps<"div"> | - | Forwarded to the shell. `className` merges last. |

`InputGroupAddon` is a plain `span` segment and accepts every native span prop plus `className`.

## FAQ

### When do I use InputGroup vs the Input adornments?

Input already covers adornments inside one field: a leading icon (InputPrefix), a divided label (InputPrefixLabel), a trailing icon button (InputSuffixButton). Use InputGroup only when you are joining several distinct controls - a Select, another field, a static affix - into one shell. If everything lives in a single field, you do not need InputGroup.

### Why isn't the action button inside the group?

A prominent text action - Subscribe, Invite, Search - reads better as its own button beside the field than melted into the shell, where it looks like a button trapped in an input. Keep it detached in a flex row (flex items-stretch gap-2) at the same size, so the field flexes and the heights line up. Only a small icon-only action (copy, clear, a submit arrow) should melt into the group.

### So an icon-only button CAN go inside?

Yes. With no label to crowd the field, a small icon-only Button sits flush as a fused segment - it keeps its fill and hover but drops its radius, ring, and press-scale. That is the one button that belongs inside the shell. Anything with a text label stays detached beside the group.

### How does it join controls without the borders doubling up?

The group owns the single border, radius, focus ring, and background. Each known segment (input-root, select-trigger, and a fused icon-only button) is stripped of its own frame via data-slot selectors and the seams are redrawn as one 1px divider per junction. It is the same approach Button Group uses, adapted so the whole shell shares one focus ring.

### How do I keep every segment - and the detached button - the same height?

Height comes from one shared scale: Button, Input, InputGroup, and Select all map size sm/md/lg to 32/36/40px. So give the group, each inner control, and the detached Button the same size (e.g. size="lg") and they're identical - no height overrides. Density never changes a control's height; it only sets the DEFAULT size when you don't pass one (compact app shell -> sm, comfortable -> md), so a bare group and a bare Button still match. The flex row's items-stretch is the final guarantee.

### Does it wire up to Field?

Yes. Like InputRoot, InputGroup reads the Field context, so hasError and disabled cascade from a surrounding Field and you set them once. A prop on the group always wins over the field default.

---

<!-- https://www.koalaui.com/docs/components/island.md -->

# Island

A floating pill that changes with what the viewer is doing. Each state is a view, and switching views morphs the pill to its new size while the contents crossfade in place.

```tsx
const pane = React.useRef<HTMLDivElement>(null)
const progress = useScrollProgress(pane) // no argument: the document
const scrolled = progress > 3

<Island aria-label="Journal" view={post ? "reading" : "browse"}>
  <IslandView value="browse">
    <IslandButton tooltip="Dark theme" shortcut="L" onClick={toggleTheme}>
      <Moon weight="bold" />
    </IslandButton>
    <IslandButton tooltip="Layout grid" shortcut="G" pressed={grid} onClick={toggleGrid}>
      <GridFour weight="bold" />
    </IslandButton>
    <IslandSeparator />
    <LanguageMenu />
  </IslandView>

  <IslandView value="reading">
    <IslandButton tooltip="Back to journal" onClick={back}>
      <ArrowLeft weight="bold" />
    </IslandButton>
    <IslandSwap view={scrolled ? "top" : undefined}>
      <IslandView value="top">
        <IslandButton tooltip="Back to top" onClick={scrollToTop}>
          <ArrowUp weight="bold" />
        </IslandButton>
      </IslandView>
    </IslandSwap>
    <IslandButton tooltip="Save for later" pressed={saved} onClick={toggleSaved}>
      <BookmarkSimple weight={saved ? "fill" : "bold"} />
    </IslandButton>
    <IslandSeparator />
    <IslandSwap view={scrolled ? "progress" : "title"}>
      <IslandView value="title">
        <IslandTitle>{post.title}</IslandTitle>
      </IslandView>
      <IslandView value="progress">
        <IslandProgress value={progress} transition="none" aria-label="Reading progress" />
      </IslandView>
    </IslandSwap>
  </IslandView>
</Island>
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add island
```

Manual: run `npm install radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/island/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

```tsx title="usage.tsx"
import {
  Island,
  IslandView,
  IslandSwap,
  IslandButton,
  IslandIcon,
  IslandSeparator,
  IslandTitle,
  IslandProgress,
} from "@/components/ui/island"

<Island
  aria-label="Page"
  view={reading ? "reading" : "browse"}
  className="fixed bottom-6 left-1/2 z-50 -translate-x-1/2"
>
  <IslandView value="browse">
    <IslandButton tooltip="Dark theme" shortcut="L">
      <Moon weight="bold" />
    </IslandButton>
  </IslandView>
  <IslandView value="reading">
    <IslandButton tooltip="Back">
      <ArrowLeft weight="bold" />
    </IslandButton>
    <IslandSeparator />
    <IslandTitle>{post.title}</IslandTitle>
  </IslandView>
</Island>
```

Mount it once, in the layout, and drive `view` from the route. An island that each page renders for itself is a new island on every navigation, so it can only appear, never morph. Pin it yourself, the way you would any floating surface: fixed and centred, so it grows out from its middle, above `env(safe-area-inset-bottom)` on a phone.

## Variants

Floating is the default: the elevated popover surface, with the controls resting muted until one of them holds a state. Solid is the inverted slab, the closest thing to the hardware island and the one to reach for over a photograph, a video or a canvas. It flips foreground and background instead of hardcoding black, so it stays legible in all four themes.

```tsx
{/* floating (default) */}
<Island aria-label="Page">…</Island>

{/* solid */}
<Island aria-label="Page" variant="solid">…</Island>
```

## Sizes

`size` is the island's own density axis, not the page's comfortable/compact knob: a floating control bar that shrinks to form-compact becomes hard to hit. `md` is the original's 44px pill and `lg` the touch step. At every size, padding plus half a control is half the pill, so the round controls sit concentric in its ends.

```tsx
<Island size="sm">…</Island>
<Island size="md">…</Island>  {/* default */}
<Island size="lg">…</Island>
```

## Views

Declare every state as an `IslandView` and name the one on screen with `view`. Only that view is mounted, plus, for one beat, the one leaving. The pill eases to the new width and height while the old contents blur out and the new ones blur in. A view is a row; give it `flex-col` and the pill grows into a card, its corner easing from half the height to the card's radius on the same clock. `IslandIcon` holds a status glyph at a control's size, and `IslandProgress` is the readout and bar for a task that is running.

```tsx
<Island aria-label="Publish" view={view}>
  <IslandView value="idle">
    <IslandButton tooltip="Preview"><Eye weight="bold" /></IslandButton>
    <IslandButton tooltip="History"><ClockCounterClockwise weight="bold" /></IslandButton>
    <IslandSeparator />
    <Button onClick={publish}>Publish</Button>
  </IslandView>

  <IslandView value="publishing">
    <IslandIcon>
      <Spinner aria-hidden />
    </IslandIcon>
    <IslandTitle className="pl-0">Publishing</IslandTitle>
    <IslandProgress value={progress} aria-label="Publishing" />
  </IslandView>

  {/* flex-col: the pill grows into a card */}
  <IslandView value="published" className="w-72 flex-col items-stretch gap-1.5 p-2.5">
    <div className="flex items-center justify-between gap-3 pl-3">
      <p className="flex items-center gap-2 text-sm font-medium">
        <CheckCircle weight="fill" className="size-4 text-success" />
        Published
      </p>
      <Button variant="ghost" size="sm" className="text-muted-foreground" onClick={undo}>
        Undo
      </Button>
    </div>
    {/* The address is the way in: no second "Visit" button repeating it. */}
    <Button asChild variant="secondary" className="justify-between">
      <a href={url} target="_blank" rel="noreferrer">
        <Globe weight="bold" className="text-muted-foreground" />
        <span className="min-w-0 flex-1 truncate">koala-journal.vercel.app</span>
        <ArrowUpRight weight="bold" className="text-muted-foreground" />
      </a>
    </Button>
  </IslandView>
</Island>
```

## Swap

`IslandSwap` is a region of a view that changes on its own, with the same crossfade and a small morph of its own: the title that gives way to the progress readout once you scroll. Name a view no child answers to and the region empties and collapses to nothing, which is how a “back to top” grows into the pill past the fold and out of it again at the top.

```tsx
<IslandSwap view={scrolled ? "top" : undefined}>
  <IslandView value="top">
    <IslandButton tooltip="Back to top"><ArrowUp weight="bold" /></IslandButton>
  </IslandView>
</IslandSwap>
<IslandSeparator />
<IslandSwap view={scrolled ? "progress" : "title"}>
  <IslandView value="title">
    <IslandTitle>Three durations are enough</IslandTitle>
  </IslandView>
  <IslandView value="progress">
    <IslandProgress value={42} aria-label="Reading progress" />
  </IslandView>
</IslandSwap>
```

## Buttons and menus

One glyph makes an `IslandButton` a circle, a word makes it a pill. `pressed` lights the chip for a toggle that is on, `shortcut` puts a keycap in the tooltip, and `caret` turns it into a menu trigger whose caret points at the menu while it is open. Open menus upward, away from the edge the island sits on, and keep the Tooltip outside the trigger so the menu keeps its own hold on the button.

```tsx
<IslandButton tooltip="Dark theme" shortcut="L"><Moon weight="bold" /></IslandButton>
<IslandButton tooltip="Layout grid" shortcut="G" pressed><GridFour weight="bold" /></IslandButton>
<IslandButton tooltip="Comments are off on this page" disabled><ChatCircle weight="bold" /></IslandButton>
<IslandSeparator />
<IslandButton><ShareNetwork weight="bold" />Share</IslandButton>

<DropdownMenu>
  <Tooltip content="Language" placement="top">
    <DropdownMenuTrigger asChild>
      <IslandButton caret aria-label="Language: English">
        <Flag />
        <span>EN</span>
      </IslandButton>
    </DropdownMenuTrigger>
  </Tooltip>
  <DropdownMenuContent side="top" align="end">…</DropdownMenuContent>
</DropdownMenu>
```

## API reference

### Island

The morphing pill and the roving-focus root (Radix `Toolbar.Root`, so it forwards `dir`, `loop` and the rest). Takes `view` (the value of the view on screen), `variant` (floating · solid), `size` (sm · md · lg) and `tooltipPlacement` (default `"top"`). Without views, its children are simply its contents, and it still eases when they change size.

### IslandView

One state, named by `value`. Mounted while it is on screen; while it leaves it is out of flow, `inert` and hidden from assistive tech. A row by default; `className` can make it a card.

### IslandSwap

A region inside a view with its own `view` and its own `IslandView` children. A value no child answers to collapses it to nothing.

### IslandButton

A control (Radix `Toolbar.Button`). Takes `tooltip` (a string also becomes its `aria-label`), `shortcut`, `pressed`, `caret`, `disabled` and `asChild`.

### IslandIcon · IslandTitle · IslandProgress · IslandSeparator

`IslandIcon` is a status glyph at a control's size. `IslandTitle` is one line that truncates before it stretches the pill. `IslandProgress` takes `value` (0 to 100, or `null` for an unknown length), `transition` and an `aria-label`; its bar is our Progress. `IslandSeparator` is the hairline between clusters.

## FAQ

### How is this different from Dock and Toolbar?

Toolbar is a band of controls that keeps one shape. Dock is navigation that changes shape on demand: a rail you expand into a labelled menu. Island changes with context rather than on demand: its views follow what the viewer is doing (browsing, reading, waiting on a task), and it swaps them in place. All three sit on Radix Toolbar, so they share the roving focus and the arrow keys.

### Why declare every view up front instead of rendering the one I need?

Because the island has to keep the old view for one beat while it blurs out. With every view declared, the one leaving is the same instance that was on screen a moment ago, with its state and its tooltips, rather than a snapshot re-rendered in its place. Views that are neither on screen nor leaving are not mounted, so declaring them costs nothing.

### Where does it get its size?

From its own contents. The pill measures an inner viewport that is free to be its natural size, so mid-change it already knows where it is going, and CSS tweens the width, height and corner to it. The corner is half the height while the island is one row, capped at the card radius once a view grows taller, so one formula covers the pill and the card.

### Why should it live in the layout?

So it survives navigation. Driven by the route from the layout, going from a list to a post is a view change and the pill morphs. Rendered by each page, it would unmount with the old page and mount with the new one, and a new element can only appear.

### How do I show reading progress?

Pass useScrollProgress() (from Progress) to IslandProgress with transition="none", so the bar is welded to the scrollbar instead of trailing it. With no argument it reads the document; pass a ref to follow a scroll container instead. Swap the title for it with an IslandSwap once the reader has scrolled a little.

### What happens to focus when a view changes?

If the control you pressed lives in the view that is leaving (a Back button, say), focus moves to the first control still on screen, so a keyboard user is never dropped onto the page. The leaving view is inert while it fades, so nothing in it can be tabbed to or read out.

### Does it respect reduced motion?

Yes. Under prefers-reduced-motion: reduce the pill resizes instantly, the old view goes without waiting for a fade and the new one does not animate in. Every functional state (pressed chips, the open menu, focus rings) stays exactly as it is.

### Does it follow the page's comfortable/compact density?

No, by design, the same call as Dock and Toolbar. Its size axis (sm / md / lg) is its own density knob, because a floating control bar that shrinks to form-compact becomes hard to hit. Use lg where the island is mostly touched.

---

<!-- https://www.koalaui.com/docs/components/kbd.md -->

# Kbd

A keyboard key indicator for documenting shortcuts. Renders a native <kbd>; the default variant is a flat gray chip (no border, no shadow) that re-themes everywhere. Compose combos by placing several side by side.

```tsx
<Kbd><Command /></Kbd>
<Kbd>K</Kbd>
<Kbd variant="outline">Esc</Kbd>
<Kbd variant="solid">⏎ Enter</Kbd>
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add kbd
```

Manual: run `npm install radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/kbd/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

```tsx title="usage.tsx"
import { Kbd } from "@/components/ui/kbd"

export function Example() {
  return <Kbd>Esc</Kbd>
}
```

## Variants

`default` is a flat gray chip (no border, no shadow) whose translucent fill stays visible on any surface, a highlighted menu row included. `soft` is an alias of that same chip, `outline` is a hairline cap over a transparent fill for a key that should read lighter, `solid` inverts for high-contrast callouts, and `ghost` drops the cap entirely: just the muted glyph, for ⌘K hints inside a button or input where a raised key would read as a second control.

```tsx
<Kbd variant="default">K</Kbd>
<Kbd variant="soft">K</Kbd>
<Kbd variant="outline">K</Kbd>
<Kbd variant="solid">K</Kbd>
<Kbd variant="ghost">K</Kbd>
```

## Sizes

```tsx
<Kbd size="sm">⇧</Kbd>
<Kbd size="md">⇧</Kbd>
<Kbd size="lg">⇧</Kbd>
```

## Combinations

Kbd is a single key by design. Build a shortcut by placing several side by side in an `inline-flex` row, and each key keeps its own cap.

```tsx
<span className="inline-flex items-center gap-1">
  <Kbd><Command /></Kbd>
  <Kbd><ArrowUp /></Kbd>
  <Kbd>P</Kbd>
</span>
<span className="inline-flex items-center gap-1">
  <Kbd><Option /></Kbd>
  <Kbd>Tab</Kbd>
</span>
```

## Inline

Drop a key straight into running text. At `size="sm"` the gray chip sits inside the line height without pushing the lines apart.

```tsx
<p>Press <Kbd size="sm">⌘</Kbd>{" "}
<Kbd size="sm">K</Kbd> to open the command menu.</p>
```

## FAQ

### How do I render a multi-key shortcut like Cmd+K?

Kbd is one key by design, so place several side by side in an `inline-flex` row: each `Kbd` keeps its own cap. There is no combo prop.

### Which variant should I use for a hint inside a button or input?

Use `variant="ghost"`. It drops the keycap box entirely and renders just the muted glyph, so it does not read as a second, competing control next to the one it sits inside.

### Why does Kbd render a native <kbd> element?

So it carries the correct semantics for assistive tech and document outlines. It is a single styled element with one `tv` recipe, like Badge.

### When would I use the outline variant?

Use `variant="outline"` when a key should read lighter than the gray chip: it is a flat hairline with a transparent fill, so it recedes into dense help text instead of reading as a filled block.

### Can I wrap another element as the key?

Yes. Pass `asChild` and Kbd renders your child as the key via Radix Slot, merging the keycap styling onto it instead of emitting its own `<kbd>`.

### Does Kbd re-theme automatically?

Yes. It uses semantic tokens only: the default fill is `bg-foreground/8`, a translucent tint of the theme's own foreground, with `text-muted-foreground` on top. Because the tint composes over whatever sits behind it, the key stays one step darker than its surface in every theme, including a highlighted menu row, with no per-theme overrides.

---

<!-- https://www.koalaui.com/docs/components/label.md -->

# Label

The one label and helper-text recipe behind every form control in Koala. Input, Field and OTP Input all compose Label and Hint, and inside a Field they auto-wire their own ids, htmlFor and aria.

```tsx
<div className="flex w-full max-w-sm flex-col gap-1.5">
  <Label htmlFor="email" required>Email</Label>
  <InputRoot>
    <InputField id="email" type="email" placeholder="you@company.com" />
  </InputRoot>
  <Hint>We'll only use this to send receipts.</Hint>
</div>
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add label
```

Manual: run `npm install radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/label/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

```tsx title="usage.tsx"
import { Label, Hint } from "@/components/ui/label"

export function Example() {
  return (
    <div className="flex flex-col gap-1.5">
      <Label htmlFor="name">Name</Label>
      <input id="name" />
      <Hint>As it appears on your ID.</Hint>
    </div>
  )
}
```

## Required

Set `required` to append a destructive asterisk. It carries a visually-hidden `(required)` so screen readers announce it. The glyph itself is `aria-hidden`.

```tsx
<div className="flex w-full max-w-sm flex-col gap-4">
  <div className="flex flex-col gap-1.5">
    <Label>Workspace name</Label>
    <Skeleton animation="none" className="h-9 w-full" />
  </div>
  <div className="flex flex-col gap-1.5">
    <Label required>Workspace name</Label>
    <Skeleton animation="none" className="h-9 w-full" />
  </div>
</div>
```

## Hint & error

`Hint` is the helper text below a control. The same element doubles as the error message: set `hasError` and it switches to the destructive tone (the color transitions, so it fades in rather than snaps).

```tsx
<div className="flex w-full max-w-sm flex-col gap-4">
  <div className="flex flex-col gap-1.5">
    <Skeleton animation="none" className="h-9 w-full" />
    <Hint>Use 8 or more characters.</Hint>
  </div>
  <div className="flex flex-col gap-1.5">
    <Skeleton animation="none" className="h-9 w-full" />
    <Hint hasError>Password is too short.</Hint>
  </div>
</div>
```

## Disabled

`disabled` dims the label to match a disabled control. Inside a `Field` it's inferred from `<Field disabled>`.

```tsx
<div className="flex w-full max-w-sm flex-col gap-1.5">
  <Label disabled>Billing email</Label>
  <Skeleton animation="none" className="h-9 w-full opacity-50" />
</div>
```

## Inside a Field

Wrapped in a `Field`, the label and hint need no ids: the label adopts the control's `htmlFor` and `required`, and the hint registers itself so the control points `aria-describedby` at it. `FieldLabel` / `FieldHint` are these same two primitives, re-exported.

```tsx
<Field required className="max-w-sm">
  <FieldLabel>Email</FieldLabel>
  <InputRoot>
    <InputField type="email" placeholder="you@company.com" />
  </InputRoot>
  <FieldHint>We'll send a confirmation here.</FieldHint>
</Field>
```

## FAQ

### What is the difference between Label and Hint?

`Label` is the form label above a control; `Hint` is the helper text below it. They are the single recipe behind every Koala form control, so a field reads identically everywhere.

### How do I wire a standalone Label to its input?

Pass `htmlFor` on the `Label` pointing at the control's `id` so clicking the label focuses it. Inside a `Field` you can skip this: the label adopts the field's `id` from context automatically.

### How do I show a required field?

Set `required` on `Label` to append a destructive asterisk. The glyph is `aria-hidden`, and a visually hidden `(required)` is added so screen readers still announce it.

### How do I turn a Hint into an error message?

Set `hasError` on `Hint` and it switches to the destructive tone. The color transitions, so the error fades in rather than snapping, and the same element doubles as both helper and error text.

### What do I gain by wrapping Label and Hint in a Field?

Inside a `Field` they auto-wire: the label adopts the control's `htmlFor` and `required`, and the hint registers itself so the control points `aria-describedby` at it, with no manual ids. `FieldLabel` and `FieldHint` are these same two primitives re-exported.

### How do I dim a label for a disabled control?

Pass `disabled` to `Label`, or set `disabled` on the surrounding `Field` and the label infers it from context. The opacity transitions so it dims smoothly.

---

<!-- https://www.koalaui.com/docs/components/layout.md -->

# Layout

The application and page shell. One set of parts and two app shells that share it: plain, the classic rail-and-content layout, and docked, the default, a black frame with the content set into it.

```tsx
<Layout className="h-svh overflow-hidden">
  <LayoutSidebar>
    {/* docked automatically: no fill, no hairline, sized by the column */}
    <Sidebar aria-label="Main">
      <SidebarHeader>{/* workspace switcher */}</SidebarHeader>
      <SidebarContent>
        <SidebarGroup aria-label="Primary">
          <SidebarItem active><GearSix /> Settings</SidebarItem>
        </SidebarGroup>
      </SidebarContent>
      <SidebarFooter>{/* profile switcher */}</SidebarFooter>
    </Sidebar>
  </LayoutSidebar>

  <LayoutContent>            {/* the sheet, set into the black frame */}
    <LayoutHeader>           {/* the sheet's bar, edge to edge */}
      <LayoutSidebarTrigger />
      <Breadcrumb>
        <BreadcrumbList>
          <BreadcrumbItem>
            <BreadcrumbLink href="#">Settings</BreadcrumbLink>
          </BreadcrumbItem>
          <BreadcrumbSeparator />
          <BreadcrumbItem>
            <BreadcrumbPage>General</BreadcrumbPage>
          </BreadcrumbItem>
        </BreadcrumbList>
      </Breadcrumb>
    </LayoutHeader>

    <LayoutContainer>        {/* centered max-width column */}
      <h1 className="text-2xl font-semibold">General settings</h1>

      {/* settings sections: the header column beside the field column */}
      <FormSection layout="split" density="comfortable" className="border-t border-border py-8">
        <FormSectionHeader>
          <FormSectionTitle className="text-base">Profile</FormSectionTitle>
          <FormSectionDescription>This information is shown to your teammates.</FormSectionDescription>
        </FormSectionHeader>
        <FormSectionBody density="comfortable">
          <Field>
            <FieldLabel>Full name</FieldLabel>
            <InputRoot><InputField defaultValue="Mara Okonkwo" /></InputRoot>
          </Field>
        </FormSectionBody>
      </FormSection>

      <FormActions bordered>
        <Button variant="ghost">Cancel</Button>
        <Button>Save changes</Button>
      </FormActions>
    </LayoutContainer>
  </LayoutContent>
</Layout>
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add layout
```

Manual: run `npm install radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/layout/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

```tsx title="usage.tsx"
import {
  Layout, LayoutSidebar, LayoutSidebarTrigger, LayoutContent,
  LayoutHeader, LayoutContainer,
} from "@/components/ui/layout"

export function AppShell({ children }: { children: React.ReactNode }) {
  return (
    <Layout className="h-svh overflow-hidden">
      <LayoutSidebar>{/* nav */}</LayoutSidebar>
      <LayoutContent>
        <LayoutHeader>
          <LayoutSidebarTrigger />
          {/* breadcrumbs */}
        </LayoutHeader>
        <LayoutContainer>{children}</LayoutContainer>
      </LayoutContent>
    </Layout>
  )
}
```

## Variants

There are two app shells and one reading shell. **The two app shells are the same layout** — same parts, same structure, same scroll model, rail · content — at two levels of dress. Switching between them changes nothing about your markup.

- **`plain` — the classic shell.** One background, one hairline, nothing raised and nothing recessed. It is defined by what it doesn’t do: the content paints no surface of its own, and the rail is left alone, keeping the card surface and edge hairline a `Sidebar` wears when it stands on its own. A rail in a plain shell and a rail with no shell look identical.
- **`docked` — the same shell, dressed. (Default.)** The shell turns into a black `bg-canvas` frame with the rail sitting on it; the content is a sheet set into that frame, a narrow gutter on the sides the rail doesn’t hold and every corner rounded. In a light theme the sheet is white in the black frame; in a dark theme frame and sheet are one tone, and a hairline ring draws the sheet’s edge.

```tsx
<Layout variant="plain">   {/* the classic shell; identical markup to docked */}
  <LayoutSidebar><Sidebar>…</Sidebar></LayoutSidebar>
  <LayoutContent>
    <LayoutContainer width="wide">{/* page */}</LayoutContainer>
  </LayoutContent>
</Layout>
```

`flat`, the third, is a different *job* rather than a different look. Content sits flat on the page, the rail and a right-hand `LayoutAside` are divided from it by hairlines, and — the part that matters — the **page scrolls as a whole**: the content is not its own scroll container, which is what lets a window scroll-spy drive an “on this page” list. Documentation, not apps. This very site runs on it.

What the set deliberately does *not* contain is a second *decorated* app shell, say a flush Linear-style sheet beside the framed one. Undressed versus dressed is a real axis; *dressed one way* versus *dressed another* is how a design system drifts.

```tsx
<Layout variant="flat">
  <LayoutSidebar>{/* the docs rail */}</LayoutSidebar>
  <LayoutContent>
    <LayoutContainer width="narrow">
      {children}
    </LayoutContainer>
  </LayoutContent>
  <LayoutAside>
    <TableOfContents>
      <TableOfContentsTitle>On this page</TableOfContentsTitle>
      <TableOfContentsList>
        <TableOfContentsItem href="#overview">Overview</TableOfContentsItem>
        <TableOfContentsItem href="#anatomy">Anatomy</TableOfContentsItem>
        <TableOfContentsItem href="#variants">Variants</TableOfContentsItem>
        <TableOfContentsItem href="#density">Density</TableOfContentsItem>
      </TableOfContentsList>
    </TableOfContents>
  </LayoutAside>
</Layout>
```

## Structures

The variants set how a shell is dressed. The *structure* is which parts you drop in, and there is no prop for it: put a `LayoutTopbar` first and the shell becomes a column with the band on top; put a `LayoutRail` before the rail and it becomes two tiers; put `LayoutPane`s in the content and the sheet splits into a list and its detail. The chrome always sits on the frame and the sheet keeps a gutter on every side the chrome doesn’t hold, so every arrangement below reads as one app rather than a stack of boxes.

## Anatomy

`Layout` is a flex row on the black `bg-canvas` frame. `LayoutContent` is the sheet: a surface set into the frame, held off the top, right, and bottom window edges by an 8px gutter, every corner rounded. `LayoutHeader`, first in the sheet, is its bar, and `LayoutContainer` centers the column under it.

Space is distributed across four nested bands:

- **Frame**: the black `bg-canvas` floor the `w-64` (256px) rail sits on. It is black in the light themes and the theme’s own ground in the dark ones, and the rail column pins itself `.dark`, so its labels, chips and hairlines take their dark values on a light page with no hand-picked colours. It reads as one black surface: the rail’s header and footer drop their rules, and spacing alone sets the switchers off from the nav.
- **Sheet**: the `bg-card` surface in a light theme (white in the black frame) and the frame’s own tone in a dark one, where a second, lighter grey read as muddy. An 8px gutter of frame (the rail’s own padding, so the frame reads one width all round) on every side the chrome doesn’t hold, and `rounded-lg` on all four corners: with the frame on every side, no corner meets the window wall. No shadow; in the dark themes a hairline ring is the whole edge. Below `lg` the frame goes and the sheet fills the phone. Nest surfaces inside with a smaller, concentric radius (`the sheet’s radius − padding`).
- **Bar**: `LayoutHeader` across the top of the sheet, its rule running edge to edge. It is as tall as the rail’s switcher row (44px compact, 56px comfortable), so the two share a line across the gutter.
- **Column**: `LayoutContainer` centers a max-width column (`mx-auto`) and sets the content padding. Horizontal padding is responsive: it steps up at `sm` and `lg` so content breathes on wider viewports.

```tsx
<Layout className="h-svh overflow-hidden">
  <LayoutSidebar>
    {/* docked automatically: no fill, no hairline, sized by the column */}
    <Sidebar aria-label="Main">
      <SidebarHeader>{/* workspace switcher */}</SidebarHeader>
      <SidebarContent>
        <SidebarGroup aria-label="Primary">
          <SidebarItem active><GearSix /> Settings</SidebarItem>
        </SidebarGroup>
      </SidebarContent>
      <SidebarFooter>{/* profile switcher */}</SidebarFooter>
    </Sidebar>
  </LayoutSidebar>

  <LayoutContent>            {/* the sheet, set into the black frame */}
    <LayoutHeader>           {/* the sheet's bar, edge to edge */}
      <LayoutSidebarTrigger />
      <Breadcrumb>
        <BreadcrumbList>
          <BreadcrumbItem>
            <BreadcrumbLink href="#">Settings</BreadcrumbLink>
          </BreadcrumbItem>
          <BreadcrumbSeparator />
          <BreadcrumbItem>
            <BreadcrumbPage>General</BreadcrumbPage>
          </BreadcrumbItem>
        </BreadcrumbList>
      </Breadcrumb>
    </LayoutHeader>

    <LayoutContainer>        {/* centered max-width column */}
      <h1 className="text-2xl font-semibold">General settings</h1>

      {/* settings sections: the header column beside the field column */}
      <FormSection layout="split" density="comfortable" className="border-t border-border py-8">
        <FormSectionHeader>
          <FormSectionTitle className="text-base">Profile</FormSectionTitle>
          <FormSectionDescription>This information is shown to your teammates.</FormSectionDescription>
        </FormSectionHeader>
        <FormSectionBody density="comfortable">
          <Field>
            <FieldLabel>Full name</FieldLabel>
            <InputRoot><InputField defaultValue="Mara Okonkwo" /></InputRoot>
          </Field>
        </FormSectionBody>
      </FormSection>

      <FormActions bordered>
        <Button variant="ghost">Cancel</Button>
        <Button>Save changes</Button>
      </FormActions>
    </LayoutContainer>
  </LayoutContent>
</Layout>
```

## Container width

`LayoutContainer` takes a `width`: `narrow` (`max-w-3xl`), `default` (`max-w-6xl`), `wide` (`max-w-7xl`), or `full`. These map to Tailwind’s native `max-w-*` scale: use `narrow` (768px) for single-column forms and reading, `default` (1152px) for standard dashboards and two-column settings, `wide` (1280px) for dense tables and grids, and `full` for edge-to-edge canvases.

```tsx
<LayoutContainer width="narrow">…</LayoutContainer>
```

## Header bar

Put `LayoutHeader` straight inside `LayoutContent`, before the column, and it becomes the sheet’s bar: the rail toggle, the breadcrumbs, and anything you push right with `ml-auto`. It spans the sheet rather than the column, so its rule runs edge to edge however wide the screen, and the toggle sits right beside the rail it folds. It pins to the top of the sheet as the page scrolls under it, with a translucent, blurred fill (`bg-card/85` + `backdrop-blur-sm`), and it is exactly as tall as the rail’s switcher row, so the two line up across the gutter.

Global tools (search, notifications) belong beside the workspace switcher, in a [`SidebarActions`](https://www.koalaui.com/docs/components/sidebar.md#header-actions); the bar keeps what is about this page. Below `lg`, under a `LayoutMobileBar`, it scrolls away with the page instead of pinning a second band on a phone. Inside `LayoutContainer` the same part is a plain row at the top of the column instead (pass `sticky` to pin it), for reading layouts that have no rail to line up with.

```tsx
<LayoutContent>
  <LayoutHeader>
    <LayoutSidebarTrigger />
    <Breadcrumb>…</Breadcrumb>
    <Button variant="ghost" iconOnly aria-label="Help" className="ml-auto">
      <Question />
    </Button>
  </LayoutHeader>

  <LayoutContainer width="wide">…</LayoutContainer>
</LayoutContent>
```

## Page header

`PageHeader` is the title band that opens the column, under the sheet’s bar. The heading and its supporting text go in `PageHeaderContent`; the trailing `PageHeaderActions` holds page-level triggers (an outline secondary plus a primary). It stacks on phones and splits into a row at `sm`, so the actions never crowd a long title.

```tsx
<LayoutHeader>
  <LayoutSidebarTrigger />
  <Breadcrumb>…</Breadcrumb>
</LayoutHeader>

<LayoutContainer width="wide">
  <PageHeader>
    <PageHeaderContent>
      <PageHeaderHeading>Invoices</PageHeaderHeading>
      <PageHeaderDescription>
        Every charge across your workspace, with status and totals.
      </PageHeaderDescription>
    </PageHeaderContent>
    <PageHeaderActions>
      <Button variant="outline"><Export /> Export</Button>
      <Button><Plus /> New invoice</Button>
    </PageHeaderActions>
  </PageHeader>

  {/* page content */}
</LayoutContainer>
```

## Docked rail

The rail needs no configuration: nest a [`Sidebar`](https://www.koalaui.com/docs/components/sidebar.md) inside `LayoutSidebar` and it comes out *docked*, sitting bare on the frame beside the sheet instead of painting a second card on top of it. The column owns the surface, the width, and (in the `flat` shell) the dividing hairline; the rail owns its own chrome and padding. That split is what keeps the app shell free of `bg-transparent` / `border-r-0` patches at the call site.

It travels: `LayoutMobileSidebar` publishes the same contract, so the one rail reads correctly in the drawer too. A rail that genuinely wants its own surface opts out with `docked={false}`, or takes the `floating` card treatment shown under [Resizable panels](#resizable-panels).

```tsx title="docked.tsx"
{/* Before: the shell's look, faked at the call site */}
<LayoutSidebar className="p-0">
  <Sidebar className="w-full border-r-0 bg-transparent">…</Sidebar>
</LayoutSidebar>

{/* Now: the shell owns it */}
<LayoutSidebar>
  <Sidebar>…</Sidebar>
</LayoutSidebar>
```

## Collapsible rail

The shell owns the rail’s collapse state, so a screen doesn’t have to wire it. Drop a `LayoutSidebarTrigger` at the start of the sheet’s bar and the rail folds to a 48px icon column and back; ⌘B (Ctrl+B on Windows and Linux) does the same from anywhere, and stands down while you’re typing in a field or an editor, where the chord means bold. Only the rail column narrows: the sheet stays set in its frame and simply gains the width.

It is uncontrolled by default. Pass `defaultCollapsed` for a different starting state, or `collapsed` + `onCollapsedChange` to drive it yourself and persist the choice per user. `useLayoutSidebar()` reads and flips the same state from any descendant, for a bespoke trigger. Give each `SidebarItem` a `label` so the icon rows keep an accessible name and a hover tooltip.

```tsx
<Layout>                        {/* owns the state; ⌘B by default */}
  <LayoutSidebar>
    <Sidebar>
      <SidebarItem label="Overview"><SquaresFour /> Overview</SidebarItem>
    </Sidebar>
  </LayoutSidebar>

  <LayoutContent>
    <LayoutHeader>
      <LayoutSidebarTrigger />
      <Breadcrumb>…</Breadcrumb>
    </LayoutHeader>
    <LayoutContainer>…</LayoutContainer>
  </LayoutContent>
</Layout>
```

## Top navigation

For an app with a handful of top-level sections, put the navigation in a band across the top instead of a rail. Drop a `LayoutTopbar` in as the first child and the shell turns into a column: the band spans the window, and the sheet fills the rest and scrolls on its own. The band hosts a [`Navbar`](https://www.koalaui.com/docs/components/navbar.md) the way `LayoutSidebar` hosts a `Sidebar`: the bar docks onto it, painting no fill and no bottom rule of its own, and its row runs the full width instead of the marketing column.

The band is part of the black frame, pinned dark like the rail, and the sheet starts right under it: no gutter on top, where the band holds the edge, and the frame on the other three sides. Below `md` the links fold into the Navbar’s own menu.

```tsx
<Layout className="h-svh overflow-hidden">
  <LayoutTopbar>
    {/* docked automatically: no fill, no bottom rule, full-width row */}
    <Navbar density="compact" linkStyle="underline">
      <NavbarInner>
        <NavbarBrand href="/"><BrandMark /></NavbarBrand>
        <NavbarNav>
          <NavbarLink href="/">Overview</NavbarLink>
          <NavbarLink href="/invoices" active>Invoices</NavbarLink>
        </NavbarNav>
        <NavbarSpacer />
        <NavbarSearch className="hidden max-w-56 md:flex" />
        <NavbarActions>
          <Button variant="ghost" iconOnly aria-label="Notifications"><Bell /></Button>
          <AccountMenu />
        </NavbarActions>
        <NavbarMobileToggle />
      </NavbarInner>
      <NavbarMobileMenu>…</NavbarMobileMenu>
    </Navbar>
  </LayoutTopbar>

  <LayoutContent>              {/* the sheet, framed on three sides */}
    <LayoutContainer width="wide">…</LayoutContainer>
  </LayoutContent>
</Layout>
```

### With tabs

The band is a column, so a second row stacks under the first. Put both rows in one `Navbar` (one `<header>` landmark, two `NavbarInner`s) with `linkStyle="underline"`: the tab indicator lands right on the seam, so the current tab reads as the doorway into the sheet below it. The tab row never folds into a menu; on a phone it scrolls sideways.

```tsx
<LayoutTopbar>
  <Navbar density="compact" linkStyle="underline">
    <NavbarInner>
      <NavbarBrand href="/"><BrandMark /></NavbarBrand>
      <span aria-hidden className="text-lg font-light text-border">/</span>
      <ProjectSwitcher />
      <NavbarSpacer />
      <NavbarActions>…</NavbarActions>
    </NavbarInner>

    {/* the tab row: -ml-2 lines the first label up with the brand */}
    <NavbarInner className="h-11">
      <NavbarNav aria-label="Billing" className="-ml-2 flex min-w-0 overflow-x-auto">
        <NavbarLink href="/billing">Overview</NavbarLink>
        <NavbarLink href="/billing/invoices" active>Invoices</NavbarLink>
      </NavbarNav>
    </NavbarInner>
  </Navbar>
</LayoutTopbar>
```

## Top bar over the rail

The Slack, YouTube and IDE shell: a band across the whole window for the brand, a global search and the account, with the rail and the sheet side by side underneath. Put the rail and the sheet in a `LayoutBody`, the row that fills whatever the band leaves. The rail stops being viewport-tall and simply stretches to that row.

Band and rail are one L of frame here, and the sheet sits in its corner: no gutter against either of them, the frame on the right and the bottom. The rail toggle moves up into the band, lined up with the rail’s icons, so it still reads as the rail’s own control.

```tsx
<Layout className="h-svh overflow-hidden">
  <LayoutTopbar>
    <Navbar density="compact">
      <NavbarInner className="grid grid-cols-[minmax(0,1fr)_minmax(0,28rem)_minmax(0,1fr)] pl-2">
        <div className="flex items-center gap-1">
          <LayoutSidebarTrigger />
          <NavbarBrand href="/"><BrandMark /></NavbarBrand>
        </div>
        <NavbarSearch placeholder="Search Koala" className="max-w-none" />
        <NavbarActions className="justify-self-end">…</NavbarActions>
      </NavbarInner>
    </Navbar>
  </LayoutTopbar>

  <LayoutBody>                 {/* the row under the band */}
    <LayoutSidebar>
      <Sidebar aria-label="Main">…</Sidebar>
    </LayoutSidebar>
    <LayoutContent>            {/* the sheet, in the corner of the frame */}
      <LayoutContainer width="wide">…</LayoutContainer>
    </LayoutContent>
  </LayoutBody>
</Layout>
```

## Two-tier rail

When the app is several products in one (a mail, a calendar, a billing module), the rail splits in two. A `LayoutRail` strip on the far left switches between modules, and the `LayoutSidebar` beside it holds the open module’s own navigation. Put a plain `Sidebar` in the strip and it comes out as the 48px icon rail, since the strip hands it `collapsed`; give every row a `label` for its tooltip and accessible name. A hairline divides the two columns, because two columns on the same frame with no surface change between them would run together into one wide rail.

Pass `collapsible="offcanvas"` to the panel. The strip already is the icon column, so collapsing the panel slides it shut instead of folding it into a second strip. It slides out whole, labels and all, and leaves the tab order once it is gone.

```tsx
<Layout className="h-svh overflow-hidden">
  <LayoutRail>                     {/* the module strip: an icon rail, no props */}
    <Sidebar aria-label="Apps">
      <SidebarHeader>{/* workspace switcher */}</SidebarHeader>
      <SidebarContent>
        <SidebarGroup aria-label="Apps">
          <SidebarItem label="Home"><House /> Home</SidebarItem>
          <SidebarItem active label="Billing"><Receipt /> Billing</SidebarItem>
        </SidebarGroup>
      </SidebarContent>
      <SidebarFooter>{/* account switcher */}</SidebarFooter>
    </Sidebar>
  </LayoutRail>

  <LayoutSidebar collapsible="offcanvas">   {/* the open module's nav */}
    <Sidebar aria-label="Billing">…</Sidebar>
  </LayoutSidebar>

  <LayoutContent>
    <LayoutContainer width="wide">
      <LayoutHeader>
        <LayoutSidebarTrigger />   {/* slides the panel; the strip stays */}
        <Breadcrumb>…</Breadcrumb>
      </LayoutHeader>
      …
    </LayoutContainer>
  </LayoutContent>
</Layout>
```

## List and detail

Mail, chat and support queues are one screen split into columns: a list, the item you opened, sometimes an inspector beside it. Put `LayoutPane`s straight inside `LayoutContent` and the sheet lays them out as a row. Each pane scrolls on its own, and every pane after the first draws the hairline that divides it from the one before.

- **`width`** is `sm` (256px), `md` (320px), `lg` (384px) or `fill`, the default, which takes whatever the fixed panes leave. Give exactly one pane in the row `fill`.
- **`LayoutPaneHeader`** is the bar across the top of a pane: the list’s title, the reading pane’s actions. Every pane header is the same height, so side by side their bottom rules meet in one straight line across the seams.
- **The panes are one surface.** The frame-to-sheet edge is a surface change and keeps its rounded corners; the seams between panes are divisions *within* the sheet, so they get a hairline and nothing else.

```tsx
{/* the rail starts as icons: the reading pane gets the width */}
<Layout defaultCollapsed className="h-svh overflow-hidden">
  <LayoutSidebar>
    <Sidebar aria-label="Mail">…folders…</Sidebar>
  </LayoutSidebar>

  <LayoutContent>              {/* holding panes turns the sheet into a row */}
    <LayoutPane width="md" aria-label="Inbox">
      <LayoutPaneHeader>
        <h2 className="text-sm font-semibold">Inbox</h2>
        <Button variant="ghost" size="sm" iconOnly className="ml-auto" aria-label="Mark all as read">
          <CheckCircle />
        </Button>
      </LayoutPaneHeader>
      <List variant="plain" className="px-4 py-2">…messages…</List>
    </LayoutPane>

    <LayoutPane aria-label="Message">    {/* width="fill" by default */}
      <LayoutPaneHeader>…actions…</LayoutPaneHeader>
      <article className="p-6">…</article>
    </LayoutPane>
  </LayoutContent>
</Layout>
```

### With an inspector

A third pane on the right holds the details of the open item: the requester, the status, the fields an agent edits. It continues the same sheet, so it is just one more `LayoutPane`. Panes compose with any structure: here the queues ride in a top band, which leaves the sheet its full width for three columns. For panes the reader can drag wider, compose the same parts inside [Resizable panels](#resizable-panels).

```tsx
<Layout className="h-svh overflow-hidden">
  <LayoutTopbar>
    <Navbar density="compact" linkStyle="underline">…queues…</Navbar>
  </LayoutTopbar>

  <LayoutContent>
    <LayoutPane width="sm" aria-label="Open tickets">
      <LayoutPaneHeader>…</LayoutPaneHeader>
      <List variant="plain" className="px-4 py-2">…</List>
    </LayoutPane>

    <LayoutPane aria-label="Conversation">
      <LayoutPaneHeader>
        <h2 className="truncate text-sm font-semibold">Can't download my invoice PDF</h2>
        <Button variant="outline" size="sm" className="ml-auto"><CheckCircle /> Resolve</Button>
      </LayoutPaneHeader>
      …thread · reply box…
    </LayoutPane>

    <LayoutPane width="sm" aria-label="Ticket details">   {/* the inspector */}
      <LayoutPaneHeader>…</LayoutPaneHeader>
      <DescriptionList>…</DescriptionList>
    </LayoutPane>
  </LayoutContent>
</Layout>
```

## Mobile navigation

`LayoutSidebar` is hidden below `lg`. On small screens, put a `LayoutMobileBar` at the top of `LayoutContent` and drop a `LayoutMobileSidebar` inside it: a hamburger that opens the same `Sidebar` in a left [Drawer](https://www.koalaui.com/docs/components/drawer.md), so one rail serves both layouts. The demo below is framed as a phone and forces the mobile bar on at every width.

```tsx
<LayoutContent>
  <LayoutMobileBar>
    <LayoutMobileSidebar>
      <Sidebar>…</Sidebar>
    </LayoutMobileSidebar>
    <Brand />
  </LayoutMobileBar>

  <LayoutContainer>{/* page */}</LayoutContainer>
</LayoutContent>
```

## Resizable panels

By default the rail is a constant (`w-64`). Compose the shell with [Resizable](https://www.koalaui.com/docs/components/resizable.md) to make it a drag instead: wrap the columns in a `ResizablePanelGroup` on a fixed-height shell (`h-svh overflow-hidden`), and each `ResizablePanel` takes over the width the recipe used to fix. The `Layout` parts go inside the panels unchanged; give the sheet’s panel `flex` so the sheet fills it inside its gutter.

Two rules carry across every arrangement below. **Give every pane except one hard `px` bounds** (`minSize` / `maxSize`): the unbounded one absorbs the difference, so nothing collapses into an unusable sliver at small window sizes. And **the handle *is* the rail’s edge**: a sheet in the panel after a handle drops its left gutter on its own and meets the handle directly, keeping the frame on the other three sides. Since the sheet’s edge already draws that seam, a handle on the frame paints no line of its own (`bg-transparent`, no grip): a hairline there would run through the gutters above and below the sheet. It still shows the resize cursor and lights up in the brand colour while you drag.

```tsx
<Layout className="h-svh overflow-hidden">
  <ResizablePanelGroup>
    {/* the rail, on the frame. collapsible: snaps shut past half its min */}
    <ResizablePanel defaultSize={26} minSize="220px" maxSize="380px" collapsible>
      <LayoutSidebar className="flex h-full w-full">
        <Sidebar>…</Sidebar>
      </LayoutSidebar>
    </ResizablePanel>

    {/* on the frame: the sheet's edge is the seam, so no line or grip */}
    <ResizableHandle className="bg-transparent" />

    {/* the sheet: no left gutter beside the handle, the frame on the rest.
        flex, not h-full, so the sheet fills the panel inside its gutter */}
    <ResizablePanel defaultSize={74} className="flex">
      <LayoutContent>
        <LayoutContainer width="wide">{/* page */}</LayoutContainer>
      </LayoutContent>
    </ResizablePanel>
  </ResizablePanelGroup>
</Layout>
```

### Floating rail

The one place a card floats in the docked shell. Pass `floating` to the [Sidebar](https://www.koalaui.com/docs/components/sidebar.md) and it detaches into its own surface (outline, radius, shadow) on the frame, while the content stays the sheet, so the two read as distinct objects across the seam. The rail’s panel needs padding for that float to be visible: with none, the card butts against the window edge and there is nothing for it to float above.

```tsx
{/* p-2 is the air the floating card needs to read as detached */}
<ResizablePanel defaultSize={26} minSize="220px" maxSize="380px" className="p-2">
  <LayoutSidebar className="flex h-full w-full">
    <Sidebar floating>…</Sidebar>
  </LayoutSidebar>
</ResizablePanel>
```

### Three panes

The detail-view dashboard: a rail, the content, and a right-hand inspector, with a draggable seam between each pair. Each handle resizes only the two panes it sits between, so the three rebalance independently.

What makes this read correctly is that **the two seams are not the same kind of edge**, and treating them alike is the usual mistake:

- **Seam 1, frame → sheet.** The rail sits on the `bg-canvas` frame and the content is the sheet. This is the shell’s real edge, so the sheet keeps its rounded corners here: it is a surface change.
- **Seam 2, sheet → sheet.** The inspector *continues* the same sheet, so it goes *inside* `LayoutContent` as a second resizable group: no radius, no shadow, no fill of its own. It is a division *within* one surface, not a boundary between two. Give it a card of its own and the screen suddenly reads as three floating objects instead of one app.

Both outer panes are `collapsible` and bounded; the middle carries no `px` bounds, so it is the pane that absorbs whatever the other two give up.

```tsx
<ResizablePanelGroup>
  {/* rail — on the frame */}
  <ResizablePanel collapsible minSize="200px" maxSize="320px">
    <LayoutSidebar className="flex h-full w-full"><Sidebar>…</Sidebar></LayoutSidebar>
  </ResizablePanel>

  <ResizableHandle className="bg-transparent" />  {/* seam 1: frame → sheet, drawn by the sheet */}

  {/* the sheet holds the other two panes; they scroll, it clips */}
  <ResizablePanel defaultSize={78} className="flex">
    <LayoutContent className="overflow-hidden">
      <ResizablePanelGroup>
        {/* content. Unbounded: absorbs the difference */}
        <ResizablePanel defaultSize={70} className="overflow-y-auto">…</ResizablePanel>

        <ResizableHandle withHandle />  {/* seam 2: sheet → sheet */}

        {/* inspector — the SAME sheet continued: no fill, no radius, no shadow */}
        <ResizablePanel collapsible minSize="260px" maxSize="380px">
          <div className="h-full p-4">…</div>
        </ResizablePanel>
      </ResizablePanelGroup>
    </LayoutContent>
  </ResizablePanel>
</ResizablePanelGroup>
```

## Split layout

`SplitLayout` is a second shell in this module for the full-viewport auth, onboarding, and marketing screens. It fills the viewport (`min-h-svh`) and splits into two columns at `lg`. One pane carries the content (a centered `SplitPaneBody` column); the other, `SplitMedia`, is a full-bleed image panel with an optional `SplitMediaOverlay` for a caption or testimonial. Below `lg` the grid collapses to a single column and the media pane drops away, so the form fills the screen on phones.

```tsx
<SplitLayout>
  <SplitPane>                 {/* content side: centers a column */}
    <SplitPaneBody>           {/* the centered max-width column */}
      <Brand />
      <h1>Create an account</h1>

      <Button variant="outline" className="w-full"><GoogleLogo /> Google</Button>
      <Divider>or continue with email</Divider>

      <Form onSubmit={handleSubmit}>
        <Field>
          <FieldLabel>Email address</FieldLabel>
          <InputRoot><InputField type="email" /></InputRoot>
        </Field>
        <FormActions align="stack">
          <Button type="submit">Create account</Button>
        </FormActions>
      </Form>
    </SplitPaneBody>
  </SplitPane>

  <SplitMedia>                {/* full-bleed image side, hidden below lg */}
    <img className="absolute inset-0 size-full object-cover" src="/cover.jpg" alt="" />
    <SplitMediaOverlay>
      <p>Koala UI let us ship a polished product in days.</p>
    </SplitMediaOverlay>
  </SplitMedia>
</SplitLayout>
```

### Media side & ratio

Which side the media sits on is just DOM order. Put `SplitMedia` first for an image-left layout. The `ratio` prop divides the columns: `even` (the 50/50 default), `start`, or `end` to give the leading or trailing pane the larger 3:2 share. Here the media leads with `start` so the hero panel dominates.

```tsx
<SplitLayout ratio="start">
  <SplitMedia>                {/* media first, sits on the left */}
    <img className="absolute inset-0 size-full object-cover" src="/cover.jpg" alt="" />
    <SplitMediaOverlay className="justify-between">
      <Brand className="text-white" />
      <p>Welcome back to your workspace.</p>
    </SplitMediaOverlay>
  </SplitMedia>

  <SplitPane>
    <SplitPaneBody>{/* sign-in form */}</SplitPaneBody>
  </SplitPane>
</SplitLayout>
```

## Density

`density` on `Layout` flows through context to the rail padding, the column’s inner padding, and the header gap. `compact` is the default (app UI); `comfortable` is roomier. Either way the column’s horizontal padding is responsive (`px-4 sm:px-6 lg:px-8` in `compact`), so the gutter grows with the viewport. Set it once here or for a whole subtree with `DensityProvider`. See [Density](https://www.koalaui.com/docs/foundations/density.md).

```tsx
<Layout density="comfortable">…</Layout>
```

## FAQ

### Which variant should I use?

For an app or dashboard, pick between the two app shells: `docked` (the default) is a black frame with the rail on it and the content set into it as a rounded sheet, the way the Shopify admin is built; `plain` is that same shell undressed, one background and one hairline, with the rail keeping its own standalone chrome. They share the same markup, so switching is a one-word change. `flat` is not an app shell at all: use it for docs and reading, where content sits flat on the page with a right-hand `LayoutAside` and the *window* scrolls as a whole so a scroll-spy can work.

### Why is the rail dark on a light page?

Because in `docked` the chrome is the frame, and the frame is the same near-black in every theme; only the sheet follows the theme. The rail column, the strip and the top band pin themselves `.dark`, so everything in them (labels, hover chips, hairlines, a search field, a count badge) takes its dark value with no hand-picked colours. Menus they open still portal to the page, so they come out in the page's theme. If a screen wants the rail on the page ground instead, that is `plain`.

### Why is there a --canvas colour role instead of just using --background?

Because the frame has to be the same black in every theme, and `--background` is white in light and cream. `--canvas` is theme-agnostic, like `--brand`: declared once, redefined by no theme, and equal to the dark theme's own ground, so a rail pinned `.dark` reads as one piece with the gutter around the sheet.

### Why doesn't LayoutSidebar show on mobile?

`LayoutSidebar` is hidden below `lg` by design. On small screens, put a `LayoutMobileBar` at the top of `LayoutContent` with a `LayoutMobileSidebar`, which opens the same `Sidebar` in a left Drawer so one rail serves both layouts.

### How do I control the content column width?

Set `width` on `LayoutContainer`: `narrow` (768px) for forms and reading, `default` (1152px) for dashboards, `wide` (1280px) for dense tables, or `full` for edge-to-edge. These map to Tailwind's native `max-w-*` scale.

### How do I keep the breadcrumb header in view while scrolling?

Pass `sticky` to `LayoutHeader`. It pins to the top of the scrolling sheet, bleeds to the column edges with a translucent blurred fill, and its inset margins track the column's responsive padding so it lines up at every breakpoint.

### Do I need to restyle the Sidebar to sit in the shell?

No. Nesting a `Sidebar` in a `LayoutSidebar` docks it: the shell owns the surface, the width, and (in `flat`) the dividing hairline, so the rail drops its own card fill and hairline. `LayoutMobileSidebar` publishes the same contract, so one rail reads correctly on desktop and in the drawer. Pass `docked={false}` to opt a rail out.

### How do I collapse the sidebar to icons?

The shell owns that state. Drop a `LayoutSidebarTrigger` in the header, or press ⌘B (Ctrl+B), and the rail folds to a 48px icon column while the sheet stays set in its frame and gains the width. It's uncontrolled by default: pass `defaultCollapsed`, or `collapsed` + `onCollapsedChange` to drive and persist it, and `useLayoutSidebar()` to read or flip it from a custom trigger. Give each `SidebarItem` a `label` so the icon rows keep a name and a tooltip.

### Can I turn off the ⌘B shortcut?

Pass `collapseShortcut={false}`. The binding is document-level and on by default, which is right for an app with one shell; turn it off when a page mounts several `Layout`s (this documentation page does) or when ⌘B already means something else there. It also stands down on its own while you're typing in a field or a rich-text editor.

### How do I make the sidebar draggable instead of fixed-width?

Compose with Resizable: wrap the columns in a `ResizablePanelGroup` on a fixed-height shell (`h-svh overflow-hidden`). Each `ResizablePanel` now owns the width the recipe used to fix at `w-64`, and `collapsible` snaps the rail shut past half its min. One thing to get right: leave exactly one pane without `px` bounds so it absorbs the difference. The sheet handles the handle itself: in the panel after one, it drops its left gutter and meets the handle directly.

### In a three-pane layout, should the inspector be its own card?

No. The rail sits on the black frame and the content is the sheet, so that first seam is a real surface change and the sheet keeps its rounded corners there. The inspector continues that same sheet, so it goes inside `LayoutContent` (a second resizable group, or a `LayoutPane`): no fill, no radius, no shadow, no second gutter. The seam between them divides one surface rather than separating two. Giving the inspector its own card makes the screen read as three floating objects instead of one app.

### How do I put the navigation on top instead of in a rail?

Drop a `LayoutTopbar` in as the first child of `Layout` and put a `Navbar` inside it. The shell turns into a column on its own, with the band across the window and the sheet filling the rest, and the bar docks onto the band with no props. There is no `nav` prop to set: the structure is whichever parts you drop in. For a tab row, add a second `NavbarInner` to the same `Navbar`.

### Can I have a top bar and a rail at the same time?

Yes, that is the Slack or YouTube shell. Put the `LayoutTopbar` first, then a `LayoutBody` holding the `LayoutSidebar` and the `LayoutContent`. Band and rail form one L of frame and the sheet sits in its corner, framed on the right and the bottom. Move the `LayoutSidebarTrigger` into the band so the rail keeps its toggle.

### What is the difference between LayoutRail and LayoutSidebar?

`LayoutRail` is the thin module strip of a two-tier rail (Slack's workspaces, an IDE's activity bar): 48px wide, and the `Sidebar` inside it always renders as icons. `LayoutSidebar` is the rail proper, with the labelled navigation. Beside a strip, give the `LayoutSidebar` `collapsible="offcanvas"` so collapsing slides it shut instead of turning it into a second icon column.

### How do I build a mail or chat layout with a list and a reading pane?

Put two or more `LayoutPane`s straight inside `LayoutContent`. The sheet lays them out as a row, each pane scrolls on its own, and every pane after the first draws the dividing hairline. Give the list a fixed `width` (`sm`, `md` or `lg`) and leave the reading pane on `fill`. Start each pane with a `LayoutPaneHeader`: they share one height, so their bottom rules line up across the seams.

### What is SplitLayout for, and how do I choose which side the media sits on?

`SplitLayout` is a second shell for full-viewport auth, onboarding, and marketing screens that splits into two columns at `lg`. Which side `SplitMedia` sits on is just DOM order, and the `ratio` prop (`even`, `start`, or `end`) divides the columns.

---

<!-- https://www.koalaui.com/docs/components/link.md -->

# Link

The text link, in both house treatments. default and muted are the standalone UI link for chrome, warming to the brand accent on hover; prose is the hyperlink embedded in running copy, underlined at rest.

```tsx
<Link href="#">hello@koalaui.com</Link>
<Link href="#" variant="muted">Documentation</Link>
<Link href="#" underline>Read the changelog</Link>
<Link href="#">Open in a new tab <ArrowUpRight /></Link>

<p className="text-muted-foreground">
  Read the <Link href="#" variant="prose">changelog</Link> before upgrading.
</p>
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add link
```

Manual: run `npm install radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/link/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

```tsx title="usage.tsx"
import { Link } from "@/components/ui/link"

export function Example() {
  return <Link href="/pricing">See pricing</Link>
}
```

## Variants

`default` rests at `text-foreground` (full-strength, reads as a real label); `muted` starts quiet for a value in a directory or a footer link. Both lift to the brand accent on hover. `prose` is the third treatment, for a link inside a sentence: it sets *no* rest color, so it inherits the copy around it, and only its underline marks it until hover turns both text and underline the accent.

```tsx
<Link href="#" variant="default">Full-strength link</Link>
<Link href="#" variant="muted">Muted link</Link>

{/* prose sets no rest color: it inherits whatever copy it sits in. */}
<p className="text-muted-foreground">Muted copy with a <Link href="#" variant="prose">prose link</Link>.</p>
<p className="text-foreground">Full-strength copy with a <Link href="#" variant="prose">prose link</Link>.</p>
```

## In prose

A hyperlink inside running copy is a different animal from a link in UI chrome, so `prose` is a treatment rather than a color: it inherits the paragraph's color, wears a hairline `decoration-border` underline at rest, and turns both the text and the underline the `--link` token on hover. It stays `display: inline` so it breaks across lines mid-sentence instead of wrapping as an unbreakable block, drops the trailing-icon reveal the standalone variants carry (a glyph in prose is content, not a hover affordance), and hovers on the faster 160ms beat, because a word-sized target in a paragraph is swept over constantly and a slow fade out leaves a trail of words cooling back down.

```tsx title="in-prose.tsx"
import NextLink from "next/link"
import { Link } from "@/components/ui/link"

export function Example() {
  return (
    <p className="text-muted-foreground">
      Components are owned source in your repo. Start with the{" "}
      {/* asChild keeps an internal prose link on client-side routing. */}
      <Link asChild variant="prose">
        <NextLink href="/docs/installation">installation guide</NextLink>
      </Link>
      .
    </p>
  )
}
```

## Underline

The color shift carries the affordance in context, so the link is not underlined by default. Pass `underline` for a prose-like link that must read as underlined at rest. It applies to `default` and `muted` only: `prose` is underlined by definition, and pinning a thickness on it (the prop sets `decoration-1`) would stop the underline tracking the font metrics, so combining the two is a type error.

```tsx
<Link href="#">No underline</Link>
<Link href="#" underline>Underlined at rest</Link>
```

## With an icon

Drop a trailing glyph (a directional arrow for an outbound or routing link) beside the label. It reads as a hover affordance, so it stays hidden at rest and slides and fades in when the link is hovered or keyboard-focused, warming to brand with the text. The motion is a plain CSS transition (interruptible), and it collapses to an instant reveal under `prefers-reduced-motion`.

```tsx
<Link href="#">View the docs <ArrowUpRight /></Link>
```

## As child

Use `asChild` to render the link styles onto another element, e.g. Next.js's `Link`, via Radix Slot, so you keep client-side routing.

```tsx title="as-child.tsx"
import NextLink from "next/link"
import { Link } from "@/components/ui/link"

export function Example() {
  return (
    <Link asChild>
      <NextLink href="/pricing">See pricing</NextLink>
    </Link>
  )
}
```

## FAQ

### Which variant do I use?

Ask where the link sits. Outside running prose (a contact row, a directory card, a footer column, a meta row) use default, or muted when it should start quiet: both rest at a solid color and warm to brand on hover. Inside a sentence, use prose. Never hand-roll the classes: this component is the only place the treatment is defined.

### Why doesn't prose set a text color?

Because the paragraph already did. A hyperlink in running copy should read as part of its sentence, so prose inherits: text-muted-foreground inside a muted <p>, text-foreground inside a Pricing feature row. Only the hover state is colored, which is what makes that color mean something. Pass a text-* through className on the rare row that needs to override the copy around it.

### Why isn't it underlined by default?

That applies to default and muted only. Outside prose, these links sit in a labeled context (a value under a heading, a card, a footer column) where the layout already reads them as links, so the color shift on hover is enough affordance. Pass the underline prop when such a link needs to read as underlined at rest. prose is always underlined, since inside a sentence nothing else marks the link.

### How do I keep Next.js client-side routing?

Set asChild and pass a single next/link child. The Link renders its styles onto that element via Radix Slot instead of emitting its own <a>, so the navigation stays client-side.

### Does it re-theme and re-accent?

Yes. The rest color is text-foreground (or text-muted-foreground, or inherited under prose) and the hover is the brand accent, all semantic tokens, so it reads correctly in light, dark, cream, and moonlight and re-tints with the active accent. prose hovers to --link, which derives from --brand and so carries the accent too. It stays a separate role because it is tuned for text: on light it is darkened to clear the 4.5:1 AA floor the raw accent misses at 3.6:1, while the dark themes use the accent straight.

---

<!-- https://www.koalaui.com/docs/components/lightbox.md -->

# Lightbox

A full-screen, browsable image viewer over Radix Dialog. Give it the image list once and any LightboxTrigger opens it at that index. Page between images with arrow buttons, arrow keys and a thumbnail rail.

```tsx
<Lightbox images={images}>
  <div className="grid grid-cols-3 gap-3">
    {images.map((image, i) => (
      <LightboxTrigger key={image.src} index={i} className="aspect-[4/3] rounded-xl border">
        <img src={image.src} alt={image.alt} className="size-full object-cover" />
      </LightboxTrigger>
    ))}
  </div>
</Lightbox>
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add lightbox
```

Manual: run `npm install radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/lightbox/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

```tsx
import { Lightbox, LightboxTrigger, type LightboxImage } from "@/components/ui/lightbox"

const images: LightboxImage[] = [
  { src: "/previews/1.jpg", alt: "Homepage" },
  { src: "/previews/2.jpg", alt: "Pricing" },
]

<Lightbox images={images}>
  {images.map((image, i) => (
    <LightboxTrigger key={image.src} index={i} className="aspect-[4/3] rounded-xl">
      <img src={image.src} alt={image.alt} className="size-full object-cover" />
    </LightboxTrigger>
  ))}
</Lightbox>
```

## With Gallery

Wrap a [Gallery](https://www.koalaui.com/docs/components/gallery.md) tile in a `LightboxTrigger` with `asChild`, and give the `GalleryItem` an `action` label so it reveals the “See image” pill on hover and opens the viewer on click.

```tsx
<Lightbox images={images}>
  <GalleryMasonry>
    {images.map((image, i) => (
      <LightboxTrigger key={image.src} index={i} asChild>
        <GalleryItem action="See image">
          <GalleryImage src={image.src} alt={image.alt} className={i % 2 ? "aspect-[3/2]" : "aspect-[4/5]"} />
        </GalleryItem>
      </LightboxTrigger>
    ))}
  </GalleryMasonry>
</Lightbox>
```

## Single image

With one image the arrows and the thumbnail rail disappear, so a lone trigger works as a simple click-to-zoom for a single screenshot, with its own pill label.

```tsx
<Lightbox images={[{ src: "/preview.jpg", alt: "Preview" }]}>
  <LightboxTrigger index={0} label="See project" className="aspect-video w-full max-w-md rounded-xl border">
    <img src="/preview.jpg" alt="Preview" className="size-full object-cover" />
  </LightboxTrigger>
</Lightbox>
```

## API reference

### Lightbox

The root. Takes `images` (an array of `{ src, alt? }`) and renders the viewer. Open state is uncontrolled by default; pass `open` + `onOpenChange` to control it, and `defaultIndex` to set the first image. Built on Radix Dialog, so focus trap, scroll lock, Esc, and exit animations are handled.

### LightboxTrigger

Opens the viewer at its `index`. Renders a `<button>` with a hover/focus `label` pill (default “See image”, pass `null` to hide). Pass `asChild` to make any tile (for example a `GalleryItem`) the trigger — then it draws no pill and defers to that element's affordance.

### Navigation

The arrow buttons, the `←` / `→` keys, the thumbnail rail, and a swipe/drag on the image itself page between images (looping); the active thumbnail is ringed and a counter sits top-left. They all appear only with more than one image. The image follows the finger while you drag and commits on a firm swipe (by distance or a quick flick), otherwise it springs back to center. The rail is bounded to the screen width and scrolls sideways when the thumbnails outrun it (common on mobile or with many images), keeping the active tile scrolled to center as you page. Click the scrim or press `Esc` to close. All motion is gated behind `motion-safe`.

## FAQ

### How do I open the viewer at a specific image?

Give each trigger its position in the `images` array via the `index` prop. `LightboxTrigger` calls into the Lightbox to open at that index, so clicking the third tile opens the third image. The viewer then owns navigation from there.

### How do I move between photos?

Once the viewer is open, use the left/right arrow buttons, the ← and → keys, click a thumbnail in the bottom rail, or swipe/drag the image sideways (great on touch). The image follows your finger and commits on a firm swipe (distance or a quick flick), otherwise it springs back. Paging loops, and the photo crossfades as it changes. Arrows, the rail, and swipe only apply when there is more than one image.

### Can a Gallery tile open the lightbox?

Yes, that is the intended pairing. Wrap the `GalleryItem` in a `LightboxTrigger` with `asChild`, and set the item's `action` (for example `"See image"`). The tile reveals its pill on hover without shifting position, and clicking opens the viewer.

### How does it open and close?

It is a clean fade with a soft zoom-in, handled by Radix Dialog's enter/exit animations (no morph or flying transition). Opening fades the dark scrim in and the image zooms slightly into place; closing reverses it. Everything is gated behind `motion-safe`, so reduced-motion users get an instant open/close.

### Why is the chrome dark instead of themed?

The viewer always sits over a photo on a near-black scrim, so the controls (scrim, arrows, close, thumbnails) use a fixed dark wash rather than theme tokens. This mirrors the Dialog overlay, which is also a fixed scrim so it reads in every theme.

### Do I need next/image for the images?

No. The viewer and thumbnails use plain lazy-loaded `<img>` elements so any remote source works without extra configuration.

---

<!-- https://www.koalaui.com/docs/components/list.md -->

# List

The canonical vertical list group: stacked rows with leading media, a title and description, and trailing meta or actions. Rows are inert by default and become links or buttons via asChild.

```tsx
<List className="w-full max-w-md">
  <ListItem asChild>
    <a href="#account">
      <ListItemMedia><User /></ListItemMedia>
      <ListItemContent>
        <ListItemTitle>Account</ListItemTitle>
        <ListItemDescription>Profile, email, password</ListItemDescription>
      </ListItemContent>
      <ListItemMeta><CaretRight /></ListItemMeta>
    </a>
  </ListItem>
  <ListItem asChild>
    <a href="#billing">
      <ListItemMedia><CreditCard /></ListItemMedia>
      <ListItemContent>
        <ListItemTitle>Billing</ListItemTitle>
        <ListItemDescription>Plan, invoices, payment</ListItemDescription>
      </ListItemContent>
      <ListItemMeta><Badge variant="success" size="sm" pill>Pro</Badge><CaretRight /></ListItemMeta>
    </a>
  </ListItem>
  <ListItem asChild>
    <a href="#security">
      <ListItemMedia><ShieldCheck /></ListItemMedia>
      <ListItemContent>
        <ListItemTitle>Security</ListItemTitle>
        <ListItemDescription>2FA, sessions, devices</ListItemDescription>
      </ListItemContent>
      <ListItemMeta><CaretRight /></ListItemMeta>
    </a>
  </ListItem>
</List>
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add list
```

Manual: run `npm install radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/list/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

```tsx title="usage.tsx"
import {
  List,
  ListItem,
  ListItemMedia,
  ListItemContent,
  ListItemTitle,
  ListItemDescription,
  ListItemMeta,
} from "@/components/ui/list"

export function Example() {
  return (
    <List>
      <ListItem>
        <ListItemContent>
          <ListItemTitle>Inbox</ListItemTitle>
          <ListItemDescription>12 unread</ListItemDescription>
        </ListItemContent>
      </ListItem>
    </List>
  )
}
```

## Playground

Both shapes at once. **Props** belong to the list, except `interactive`, which is set per row on `ListItem`; **Parts** are the row slots you compose in or leave out.

## Variants

`card` (default) bands the rows inside a bordered surface; `plain` drops the chrome so rows sit flush on whatever holds them. Both keep the divider rule.

```tsx
<List variant="card">…</List>
<List variant="plain">…</List>
```

## Interactive rows

Pass `asChild` with an `<a>` or `<button>` to make the whole row a link/button: valid `<li><a>` nesting, with a hover fill that deepens on press, and an inset focus ring. It implies `interactive`; set `interactive` on its own for a row that handles `onClick` without being a link.

```tsx
<ListItem asChild>
  <a href="/team/ana">
    <ListItemMedia>
      <AvatarRoot size="sm">
        <AvatarImage src="https://i.pravatar.cc/160?img=5" alt="Ana Torres" />
        <AvatarFallback>AT</AvatarFallback>
      </AvatarRoot>
    </ListItemMedia>
    <ListItemContent>
      <ListItemTitle>Ana Torres</ListItemTitle>
      <ListItemDescription>ana@koalaui.com</ListItemDescription>
    </ListItemContent>
    <ListItemMeta><Badge size="sm">Admin</Badge><CaretRight /></ListItemMeta>
  </a>
</ListItem>
```

## With controls

Rows compose any Koala part in the meta slot. Here each row stays inert (it isn't a link) and drops a `Switch` on the right. The classic settings list.

```tsx
<List>
  <ListItem>
    <ListItemMedia><Bell /></ListItemMedia>
    <ListItemContent>
      <ListItemTitle>Push notifications</ListItemTitle>
      <ListItemDescription>Alerts on this device</ListItemDescription>
    </ListItemContent>
    <ListItemMeta><Switch defaultChecked /></ListItemMeta>
  </ListItem>
</List>
```

## Current row

In a list-detail screen one row is the record the rest of the screen is showing: the open thread, the chapter being read. Mark it with `current` on `ListItem`. It answers on two channels a hover never touches, so the two can't be confused in any theme: the fill goes to full strength and stays there under the pointer, and a brand bar sits on the row's leading edge, the same mark the Sidebar's active row carries. It also sets `aria-current` on the row surface (the `<button>` or `<a>` under `asChild`); pass `current="page"` when the rows are navigation links.

```tsx
<List variant="plain">
  {threads.map((thread) => (
    <ListItem key={thread.id} asChild current={thread.id === openId}>
      <button type="button" onClick={() => setOpenId(thread.id)}>
        <ListItemMedia>
          <AvatarRoot size="sm">
            <AvatarImage src={thread.photo} alt="" />
            <AvatarFallback>{thread.initials}</AvatarFallback>
          </AvatarRoot>
        </ListItemMedia>
        <ListItemContent>
          <ListItemTitle>{thread.name}</ListItemTitle>
          <ListItemDescription lines={1}>{thread.excerpt}</ListItemDescription>
        </ListItemContent>
        <ListItemMeta className="self-start">{thread.time}</ListItemMeta>
      </button>
    </ListItem>
  ))}
</List>

<List>
  <ListItem asChild current="page">
    <a href="/settings/account">…</a>
  </ListItem>
</List>
```

## Lines

`lines` sets how many lines the title and the description may take. The title defaults to `1`, one line with an ellipsis, so a long name never pushes the meta off the row; the description defaults to `"none"` and wraps in full. Pass `1` to keep an excerpt on one line, `2` or `3` to clamp at a word, or `"none"` on a title that is the content itself, like a pinned note. A `truncate` class on a description works too: its pretty wrapping is only ever a default.

```tsx
<ListItem>
  <ListItemMedia><PushPin /></ListItemMedia>
  <ListItemContent>
    <ListItemTitle lines="none">
      Freeze on the billing service from Thursday 18:00 until the migration lands.
    </ListItemTitle>
    <ListItemDescription>Ana Torres, pinned today</ListItemDescription>
  </ListItemContent>
</ListItem>

<ListItemTitle lines={2}>…</ListItemTitle>
<ListItemDescription lines={1}>…</ListItemDescription>
```

## API reference

### List

The root `<ul>`. Forwards all native `<ul>` props.

- `variant`: `"card"` (default) | `"plain"`.
- `divided`: `boolean`; hairline rule between rows (default `true`).
- `asChild`: `boolean`; render via Radix Slot.

### ListItem

One row (`<li>`). Forwards native `<li>` props.

- `asChild`: render the row surface as the single child (`<a>`/`<button>`) while keeping the `<li>` wrapper. Implies `interactive`.
- `interactive`: `boolean`; hover/press/focus affordance (defaults to `true` when `asChild` is set). On a `plain` list the fill is a square band exactly as wide as the rules around it; with `divided={false}` it rounds into a pill.
- `current`: `boolean | "page" | "step" | "location" | "date" | "time"`; the row the rest of the screen shows. Full fill, brand bar, and `aria-current` on the row surface.

### ListItemTitle, ListItemDescription

- `lines`: `1 | 2 | 3 | "none"`; how many lines the text may take. Title defaults to `1`, description to `"none"`.

### ListItemMedia, ListItemContent, ListItemTitle, ListItemDescription, ListItemMeta

The row parts: leading media (icon/Avatar), the content column (title + description), and the trailing meta slot (badges, timestamps, a chevron, or an action). Each forwards native `<div>` props.

## FAQ

### When should I use List instead of Data Table or Description List?

Reach for List when you have rows of content with leading media, a title, and a description, like a settings or member list. Data Table is for columnar tabular data, and Description List is for key/value detail pairs.

### How do I make a whole row a link without breaking <li><a> nesting?

Pass `asChild` on `ListItem` with a single `<a>` (or `<button>`) child. The `<li>` keeps the divider while the child becomes the interactive surface, so you get valid `<li><a>…</a></li>` markup. `asChild` implies `interactive`.

### What is the difference between the asChild and interactive props on ListItem?

`interactive` adds the hover fill, the deeper press fill, and the focus ring to a plain `<li>` that handles its own `onClick`. `asChild` does that and also hands the row surface to a link/button child. Setting `asChild` turns `interactive` on automatically.

### How do I compose the row parts?

Put a `ListItemMedia` (icon or Avatar) first, a `ListItemContent` wrapping `ListItemTitle` and `ListItemDescription` in the middle, and a `ListItemMeta` for trailing badges, a chevron, or a Switch. The title keeps to one line rather than pushing the meta off the row; set `lines` on it (or on the description) to clamp at two or three lines, or to let it wrap.

### How do I show which row is open?

Pass `current` on that `ListItem`. The row takes a full-strength fill that a hover never lightens and a brand bar on its leading edge, so it reads differently from a hovered row in every theme, and `aria-current` lands on the row surface for assistive tech. Use `current="page"` for navigation links.

### What is the difference between the card and plain variants?

`card` (default) bands the rows inside a bordered, shadowed surface. `plain` drops that chrome so rows sit flush on whatever holds them. Both keep the hairline divider unless you set `divided={false}`.

---

<!-- https://www.koalaui.com/docs/components/load-more.md -->

# Load More

Clamps a long region to a couple of rows, fades its cut edge, and puts one reveal button under it. The fade is a mask, not a painted gradient, so it works unchanged on any surface.

```tsx
<LoadMore collapsedHeight="22rem">
  <LoadMoreContent className="grid grid-cols-2 gap-x-6 gap-y-8 sm:grid-cols-3 lg:grid-cols-4">
    {catalog.map((item) => (
      <CatalogTile key={item.name} {...item} />
    ))}
  </LoadMoreContent>
  <LoadMoreTrigger more="See all components" less="Show less" />
</LoadMore>
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add load-more
```

Manual: run `npm install radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/load-more/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

```tsx title="usage.tsx"
import { LoadMore, LoadMoreContent, LoadMoreTrigger } from "@/components/ui/load-more"

export function Example() {
  return (
    <LoadMore>
      <LoadMoreContent>{/* the long grid, list or stack */}</LoadMoreContent>
      <LoadMoreTrigger more="See all" less="Show less" />
    </LoadMore>
  )
}
```

## Collapsed height

`collapsedHeight` sets how much shows before the reveal. Pick a value that cuts *through* a row rather than landing between two: a clean break reads as the end of the list, which is the opposite of the message you want. The default is `28rem`.

```tsx
<LoadMore collapsedHeight="12rem">
  <LoadMoreContent className="grid grid-cols-2 gap-x-6 gap-y-8 sm:grid-cols-3 lg:grid-cols-4">
    {/* … */}
  </LoadMoreContent>
  <LoadMoreTrigger more="See all 18 components" less="Show less" />
</LoadMore>
```

## Alignment

`align` moves the reveal button under the region: `center` (the default, which reads as a page-level affordance), `start`, or `end`. The button's row is always in flow, never floated over the fade, so opening costs no layout shift of its own.

```tsx
<LoadMore collapsedHeight="14rem" align="start">
  <LoadMoreContent className="grid grid-cols-2 gap-x-6 gap-y-8 sm:grid-cols-3 lg:grid-cols-4">
    {/* … */}
  </LoadMoreContent>
  <LoadMoreTrigger more="See all components" less="Show less" />
</LoadMore>
```

## Any surface

The cut edge fades through the `fade-b` mask utility rather than a background-coloured gradient panel, so it needs to know nothing about what sits behind it. The same component on a solid brand band cuts correctly with no configuration, where a painted gradient would smear the page background across the accent. The band is deep and its ramp is eased, so the clamp trails off instead of ending on a line. With `tone="onMedia"` the trigger becomes the white chip: on a band it is the only action on the fill, so it takes the light shape.

```tsx
<div className="rounded-2xl bg-brand p-8 text-brand-foreground [--surface:var(--brand)]">
  <LoadMore collapsedHeight="11rem">
    <LoadMoreContent className="flex flex-col gap-3">{/* … */}</LoadMoreContent>
    <LoadMoreTrigger
      more="See all components"
      less="Show less"
      tone="onMedia"
    />
  </LoadMore>
</div>
```

## Without the fade

`fade={false}` keeps the region opaque to the last pixel. Reach for it when a soft edge would misread as "this text trails off": a legal notice, a price list, a data table.

```tsx
<LoadMore collapsedHeight="12rem">
  <LoadMoreContent fade={false} className="flex flex-col gap-4">
    {/* … */}
  </LoadMoreContent>
  <LoadMoreTrigger more="Show the full list" less="Show less" />
</LoadMore>
```

## Open by default

`defaultExpanded` opens on mount, for a deep link that should land on the full list. The component owns the state from there on; pair it with `onExpandedChange` to react to each toggle.

```tsx
<LoadMore collapsedHeight="12rem" defaultExpanded>
  <LoadMoreContent className="grid grid-cols-2 gap-x-6 gap-y-8 sm:grid-cols-3">
    {/* … */}
  </LoadMoreContent>
  <LoadMoreTrigger more="See all components" less="Show less" />
</LoadMore>
```

## API reference

`LoadMore` forwards every `div` prop and adds `collapsedHeight` (any CSS length, default `28rem`), `defaultExpanded`, `onExpandedChange`, and `align`. `LoadMoreContent` forwards every `div` prop and adds `fade`. `LoadMoreTrigger` forwards every `Button` prop and takes `more` and `less` for its two labels. Its variant defaults to `outline`, or to the solid chip under an `onMedia` or `onInverse` tone. It renders its own caret, which rotates to point wherever the region is about to move, so there is no icon to pass. Every part accepts `className`.

## FAQ

### Why not Radix Collapsible?

Collapsible hides its content entirely when closed, and the whole point here is the partial peek: the clamp has to leave rows visible and cut mid-grid. So the behaviour is hand-rolled, with the ARIA wired by hand (aria-expanded plus aria-controls pointing at the region).

### Is the clamped content hidden from screen readers?

No, and that is deliberate. This is a visual clamp, not a disclosure: the content stays in the DOM and in the accessibility tree, so a screen-reader user gets the whole list either way. aria-expanded reports the visual state for anyone who can see the cut.

### Why does the reveal animate instead of jumping?

max-height transitions from the clamp to the region's measured scrollHeight, then settles to none once open so a later resize or font swap can never crop it. max-height: none is not interpolatable, so that settle snaps with no visible move, because the box already sits at content height. Collapsing re-pins the concrete height for one frame so there is a value to animate down from, and an interrupted open reverses in flight.

### Why one button rather than separate show and hide controls?

It stays mounted across the toggle, so keyboard focus survives the reveal and nothing is swapped out from under the cursor. Its label rolls between the two verbs and the box eases between their widths instead of snapping, while the caret beside it rotates 180 degrees to point wherever the region is about to move.

### Why does the label use an inline AnimatedLabel instead of the Button's swapKey?

Because of the caret. swapKey boxes every child of the button into the swap, so the caret would dissolve and re-appear along with the words. Wrapping only the words leaves the caret outside the roll, free to rotate: one mark that turns reads as the same thing changing direction, where two crossfading glyphs read as a substitution. The label still carries the width change, so the button morphs and the caret rides along.

### Can I control the open state myself?

The component is uncontrolled: pass defaultExpanded for the initial state and onExpandedChange to observe each toggle. Keeping the height animation's bookkeeping inside the component is what makes an interrupted open reversible.

### How deep is the fade, and can I change it?

It uses the shared fade-b mask utility, set here to 40% of the clamp (up to 16rem) so the cut row has all of its visible height to dissolve over. The band's ramp is an eased smoothstep rather than a straight line, so neither end of the dissolve lands on a visible edge. Override the depth per instance with an arbitrary property on LoadMoreContent, e.g. className="[--fade-size:6rem]".

---

<!-- https://www.koalaui.com/docs/components/menubar.md -->

# Menubar

The File, Edit, View row of a desktop-style app. One tab stop, arrow keys across the menus, and once one is open the next opens on hover. The menus are Dropdown Menu's panels, so both read as one object.

```tsx
<Menubar>
  <MenubarMenu>
    <MenubarTrigger>File</MenubarTrigger>
    <MenubarContent className="w-60">
      <MenubarItem>New document <MenubarShortcut>⌘N</MenubarShortcut></MenubarItem>
      <MenubarItem>Open… <MenubarShortcut>⌘O</MenubarShortcut></MenubarItem>
      <MenubarSeparator />
      <MenubarSub>
        <MenubarSubTrigger>Share</MenubarSubTrigger>
        <MenubarSubContent className="w-48">
          <MenubarItem>Copy link</MenubarItem>
          <MenubarItem>Email a copy</MenubarItem>
        </MenubarSubContent>
      </MenubarSub>
      <MenubarSeparator />
      <MenubarItem variant="destructive">Move to trash <MenubarShortcut>⌘⌫</MenubarShortcut></MenubarItem>
    </MenubarContent>
  </MenubarMenu>
  <MenubarMenu>
    <MenubarTrigger>Edit</MenubarTrigger>
    <MenubarContent>…</MenubarContent>
  </MenubarMenu>
  <MenubarMenu>
    <MenubarTrigger>View</MenubarTrigger>
    <MenubarContent>…</MenubarContent>
  </MenubarMenu>
  <MenubarMenu>
    <MenubarTrigger>Settings</MenubarTrigger>
    <MenubarContent>…</MenubarContent>
  </MenubarMenu>
</Menubar>
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add menubar
```

Manual: run `npm install radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/menubar/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

```tsx title="usage.tsx"
import {
  Menubar,
  MenubarMenu,
  MenubarTrigger,
  MenubarContent,
  MenubarItem,
  MenubarShortcut,
} from "@/components/ui/menubar"

export function Example() {
  return (
    <Menubar>
      <MenubarMenu>
        <MenubarTrigger>File</MenubarTrigger>
        <MenubarContent>
          <MenubarItem>
            New document <MenubarShortcut>⌘N</MenubarShortcut>
          </MenubarItem>
        </MenubarContent>
      </MenubarMenu>
    </Menubar>
  )
}
```

## Variants

`outline` (the default) is the Toolbar's band: a 12px radius around 4px of padding and 8px triggers, so the corners nest concentrically, with an inset edge that takes no layout. `plain` drops the band for an app header that already owns one. Either way the open menu lights its trigger, so the bar always shows which menu you are in.

```tsx
<Menubar variant="outline">…</Menubar>
<Menubar variant="plain">…</Menubar>
```

## Checkbox, radio and switch rows

The rows are Dropdown Menu's: a checked row or the chosen radio carries the brand check on the right, on the same 12px edge line as the shortcuts. `variant="switch"` on a checkbox row draws a mini Switch there instead, for a setting that applies the moment it flips, and keeps the menu open so several can be flipped in a row.

```tsx
<MenubarMenu>
  <MenubarTrigger>View</MenubarTrigger>
  <MenubarContent className="w-56">
    <MenubarCheckboxItem checked={ruler} onCheckedChange={setRuler}>Show ruler</MenubarCheckboxItem>
    <MenubarCheckboxItem checked={outline} onCheckedChange={setOutline}>Show outline</MenubarCheckboxItem>
    <MenubarSeparator />
    <MenubarLabel>Zoom</MenubarLabel>
    <MenubarRadioGroup value={zoom} onValueChange={setZoom}>
      <MenubarRadioItem value="75">75%</MenubarRadioItem>
      <MenubarRadioItem value="100">100%</MenubarRadioItem>
      <MenubarRadioItem value="150">150%</MenubarRadioItem>
    </MenubarRadioGroup>
  </MenubarContent>
</MenubarMenu>
<MenubarMenu>
  <MenubarTrigger>Settings</MenubarTrigger>
  <MenubarContent className="w-72">
    <MenubarCheckboxItem variant="switch" checked={autosave} onCheckedChange={setAutosave}>
      Autosave
    </MenubarCheckboxItem>
    …
  </MenubarContent>
</MenubarMenu>
```

## Density

The menus follow the density around the bar: 36px rows when comfortable, 32px when compact. React context crosses the portal the menus open in, so one `DensityProvider` around the bar sets every menu in it. The edge inset and the corners stay put at either density.

```tsx
<DensityProvider density="comfortable">
  <Menubar>…</Menubar>
</DensityProvider>
<DensityProvider density="compact">
  <Menubar>…</Menubar>
</DensityProvider>
```

## Keyboard

The whole bar is one tab stop. Left and Right move between menus, Down or Enter opens one, and once a menu is open, Left and Right (or the pointer) open its neighbours instead, the way an application menu behaves. Escape closes the menu and puts focus back on its trigger. Shortcuts are display only: bind the keys yourself.

## API reference

### Menubar

The band, `role="menubar"`. Props: `variant` (`outline` · `plain`), plus Radix's `value`, `defaultValue`, `onValueChange`, `loop`, `dir`.

### MenubarMenu · MenubarTrigger

One menu and the button that opens it; the trigger lights while its menu is open.

### MenubarContent

The panel, portalled to the body. It opens `align="start"` with `alignOffset` −2 and `sideOffset` 8, which puts the rows' text on the trigger's text line and clears the band. Takes `density`.

### Rows

`MenubarItem` (`inset`, `variant="destructive"`), `MenubarCheckboxItem` (`variant` `check` · `switch`, `closeOnSelect`), `MenubarRadioGroup` + `MenubarRadioItem`, `MenubarLabel`, `MenubarSeparator`, `MenubarShortcut` (a `Kbd`), `MenubarGroup`, and `MenubarSub` with `MenubarSubTrigger` and `MenubarSubContent`. They are Dropdown Menu's rows, built from its recipe.

## FAQ

### Menubar, Dropdown Menu or Toolbar?

A Menubar is a vocabulary of menus for an app with many commands (File, Edit, View). One menu behind a button is a Dropdown Menu. A row of icon actions, toggles and separators is a Toolbar.

### Do the menus look different from a Dropdown Menu?

No. The panels and rows are built from Dropdown Menu's recipe, not restyled here, so a menu opened from the bar and one opened from a button are the same object, and a change to one reaches both.

### Does it work on phones?

It works, but a row of menus is a desktop pattern: on a narrow screen fold the commands into one Dropdown Menu or a Sheet instead of squeezing the bar.

### Do the shortcuts do anything?

No, `MenubarShortcut` only shows the keys. Bind them where your app handles keyboard input, so they work whether the menu is open or not.

---

<!-- https://www.koalaui.com/docs/components/multi-select.md -->

# Multi Select

A select that picks many values and stays open while you toggle them. Radix Select closes on pick, so this is built on Radix Popover instead, matching Select's surface with a checkbox or switch per row.

```tsx
import { Code, PenNib, Megaphone, Package, ChartLineUp } from "@phosphor-icons/react"

<MultiSelect defaultValue={["engineering", "design"]}>
  <MultiSelectTrigger className="w-64">
    <MultiSelectValue placeholder="Select categories" />
  </MultiSelectTrigger>
  <MultiSelectContent>
    <MultiSelectItem value="engineering"><Code /> Engineering</MultiSelectItem>
    <MultiSelectItem value="design"><PenNib /> Design</MultiSelectItem>
    <MultiSelectItem value="marketing"><Megaphone /> Marketing</MultiSelectItem>
    <MultiSelectItem value="product"><Package /> Product</MultiSelectItem>
    <MultiSelectItem value="sales"><ChartLineUp /> Sales</MultiSelectItem>
  </MultiSelectContent>
</MultiSelect>
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add multi-select
```

Manual: run `npm install radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/multi-select/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

```tsx title="usage.tsx"
import { Code, PenNib } from "@phosphor-icons/react"
import {
  MultiSelect, MultiSelectTrigger, MultiSelectValue, MultiSelectContent,
  MultiSelectItem, MultiSelectSwitchItem,
  MultiSelectGroup, MultiSelectLabel, MultiSelectSeparator,
} from "@/components/ui/multi-select"

export function Example() {
  const [value, setValue] = useState<string[]>([])
  return (
    <MultiSelect value={value} onValueChange={setValue}>
      <MultiSelectTrigger className="w-64">
        <MultiSelectValue placeholder="Select categories" />
      </MultiSelectTrigger>
      <MultiSelectContent>
        <MultiSelectItem value="engineering"><Code /> Engineering</MultiSelectItem>
        <MultiSelectItem value="design"><PenNib /> Design</MultiSelectItem>
      </MultiSelectContent>
    </MultiSelect>
  )
}
```

## Checkbox items

`MultiSelectItem` is the default row: a leading checkbox, a label, and an optional icon. Clicking anywhere on the row toggles it, and the menu stays open so you can pick several. Each value is added to or removed from the selection array passed to `onValueChange`. Set `disabled` on a row to lock it.

```tsx
import { Eye, PencilSimple, UploadSimple, UsersThree, CreditCard } from "@phosphor-icons/react"

<MultiSelect defaultValue={["read"]}>
  <MultiSelectTrigger className="w-64">
    <MultiSelectValue placeholder="Select permissions" />
  </MultiSelectTrigger>
  <MultiSelectContent>
    <MultiSelectGroup>
      <MultiSelectLabel>Content</MultiSelectLabel>
      <MultiSelectItem value="read"><Eye /> Read</MultiSelectItem>
      <MultiSelectItem value="write"><PencilSimple /> Write</MultiSelectItem>
      <MultiSelectItem value="publish"><UploadSimple /> Publish</MultiSelectItem>
    </MultiSelectGroup>
    <MultiSelectSeparator />
    <MultiSelectGroup>
      <MultiSelectLabel>Admin</MultiSelectLabel>
      <MultiSelectItem value="users"><UsersThree /> Manage users</MultiSelectItem>
      <MultiSelectItem value="billing" disabled><CreditCard /> Billing (owner only)</MultiSelectItem>
    </MultiSelectGroup>
  </MultiSelectContent>
</MultiSelect>
```

## Switch items

`MultiSelectSwitchItem` swaps the checkbox for the DS [Switch](https://www.koalaui.com/docs/components/switch.md), giving the menu a settings-panel feel for on/off rows like notification channels. It shares the same selection state as `MultiSelectItem`, so the two can be mixed.

```tsx
import { EnvelopeSimple, DeviceMobile, ChatCircle, Desktop } from "@phosphor-icons/react"
import { AnimatedNumber } from "@/components/ui/animated-number"

<MultiSelect defaultValue={["email", "push"]}>
  <MultiSelectTrigger className="w-64">
    <MultiSelectValue
      placeholder="Notification channels"
      renderValue={(value) => (
        <>
          <AnimatedNumber value={value.length} /> channels on
        </>
      )}
    />
  </MultiSelectTrigger>
  <MultiSelectContent>
    <MultiSelectSwitchItem value="email"><EnvelopeSimple /> Email</MultiSelectSwitchItem>
    <MultiSelectSwitchItem value="push"><DeviceMobile /> Push</MultiSelectSwitchItem>
    <MultiSelectSwitchItem value="sms"><ChatCircle /> SMS</MultiSelectSwitchItem>
    <MultiSelectSwitchItem value="desktop"><Desktop /> Desktop</MultiSelectSwitchItem>
  </MultiSelectContent>
</MultiSelect>
```

## Rendering the value

By default `MultiSelectValue` shows a count (“3 selected”), robust because the trigger has no access to the row labels while the panel is closed. The number rolls as you toggle rows (“3 selected” → “4 selected”) via [AnimatedNumber](https://www.koalaui.com/docs/components/animated-number.md), so the change registers instead of hard-swapping. Pass `renderValue` to draw the selection yourself, e.g. as [Badge](https://www.koalaui.com/docs/components/badge.md) chips mapped from your own data. The chips carry that same on-change polish: each one zoom + fades in when selected and out when removed, so the row never hard-swaps.

```tsx
const CATEGORY_LABELS = {
  engineering: "Engineering", design: "Design",
  marketing: "Marketing", product: "Product",
}

const [value, setValue] = useState(["engineering", "product"])
// Keep a chip mounted through its exit so a deselected one can animate out,
// not just vanish. A chip is "leaving" once it's no longer in `value`.
const [display, setDisplay] = useState(value)

function handleChange(next) {
  setValue(next)
  setDisplay((prev) =>
    next.length === 0 ? [] : [...prev, ...next.filter((v) => !prev.includes(v))],
  )
}

<MultiSelect value={value} onValueChange={handleChange}>
  <MultiSelectTrigger className="w-72">
    <MultiSelectValue
      placeholder="Select categories"
      renderValue={() => (
        <span className="flex gap-1 overflow-hidden">
          {display.map((v) => {
            const leaving = !value.includes(v)
            return (
              <Badge
                key={v}
                variant="secondary"
                size="sm"
                pill
                className={cn(
                  "duration-fast ease-out",
                  leaving
                    // fill-mode-forwards holds opacity-0 after the exit finishes, so the chip
                    // never flashes back to full for a frame before it unmounts.
                    ? "animate-out fade-out-0 zoom-out-95 fill-mode-forwards"
                    : "animate-in fade-in-0 zoom-in-95",
                )}
                onAnimationEnd={() => {
                  if (leaving) setDisplay((d) => d.filter((x) => x !== v))
                }}
              >
                {CATEGORY_LABELS[v] ?? v}
              </Badge>
            )
          })}
        </span>
      )}
    />
  </MultiSelectTrigger>
  <MultiSelectContent>{/* ...items */}</MultiSelectContent>
</MultiSelect>
```

## Sections

Wrap related rows in `MultiSelectGroup` with a `MultiSelectLabel` heading, and split sections with `MultiSelectSeparator`: the same grouping model as [Select](https://www.koalaui.com/docs/components/select.md). See the checkbox example above for a two-section menu.

## Density

Trigger height comes from `size` on `MultiSelect` (sm/md/lg = 32/36/40px, the same scale as Button, Input, and Select). `density` no longer sets the height; it picks the default size when you do not pass one (compact → `sm`, comfortable → `md`) and tightens the menu rows - flowing to every part through context, or from a parent `DensityProvider`.

```tsx
import { Circle } from "@phosphor-icons/react"

<MultiSelect defaultValue={["a"]} density="compact">
  <MultiSelectTrigger className="w-44">
    <MultiSelectValue placeholder="Compact" />
  </MultiSelectTrigger>
  <MultiSelectContent>
    <MultiSelectItem value="a"><Circle /> Option A</MultiSelectItem>
    <MultiSelectItem value="b"><Circle /> Option B</MultiSelectItem>
  </MultiSelectContent>
</MultiSelect>
```

## FAQ

### Why is this built on Radix Popover instead of Radix Select?

Radix Select is strictly single-value and closes on pick, so it cannot host checkbox rows or stay open while you toggle. MultiSelect uses Radix Popover styled to match `SelectContent`, and each row toggles membership in one `string[]` instead of committing a single value.

### How do I read and control the selection?

The value is a `string[]`. Use `value` + `onValueChange` for controlled state, or `defaultValue` for uncontrolled. `onValueChange` fires with the full next array every time a row is toggled.

### What is the difference between MultiSelectItem and MultiSelectSwitchItem?

`MultiSelectItem` renders a leading-label row with a checkbox indicator; `MultiSelectSwitchItem` swaps in the DS Switch for a settings-panel feel. They share the same selection state, so you can mix both in one menu.

### Why does the trigger show a count instead of the chosen labels?

`MultiSelectValue` defaults to a count like 3 selected because the trigger has no access to the row labels while the panel is closed. Pass `renderValue={(values) => …}` to draw the selection yourself, for example as Badge chips mapped from your own data.

### How do I group and label options?

Wrap related rows in `MultiSelectGroup` with a `MultiSelectLabel` heading, and split sections with `MultiSelectSeparator`, the same grouping model as Select.

### What keyboard support do the rows have?

The panel has roving focus: Arrow keys, Home, and End move between option rows, and Enter or Space toggles the focused row. Disabled rows are skipped in the rotation.

---

<!-- https://www.koalaui.com/docs/components/native-select.md -->

# Native Select

The browser's own select, dressed as Koala's Select trigger. The list that opens is the operating system's: the wheel on iOS, the sheet on Android. Closed, it is indistinguishable from a Select of the same size.

```tsx
<Field>
  <FieldLabel>Timezone</FieldLabel>
  <NativeSelect defaultValue="Europe/Madrid">
    <NativeSelectOptGroup label="Americas">
      <NativeSelectOption value="America/New_York">New York (GMT−4)</NativeSelectOption>
      <NativeSelectOption value="America/Los_Angeles">Los Angeles (GMT−7)</NativeSelectOption>
      <NativeSelectOption value="America/Sao_Paulo">São Paulo (GMT−3)</NativeSelectOption>
    </NativeSelectOptGroup>
    <NativeSelectOptGroup label="Europe">
      <NativeSelectOption value="Europe/London">London (GMT+1)</NativeSelectOption>
      <NativeSelectOption value="Europe/Madrid">Madrid (GMT+2)</NativeSelectOption>
      <NativeSelectOption value="Europe/Berlin">Berlin (GMT+2)</NativeSelectOption>
    </NativeSelectOptGroup>
    <NativeSelectOptGroup label="Asia Pacific">
      <NativeSelectOption value="Asia/Tokyo">Tokyo (GMT+9)</NativeSelectOption>
      <NativeSelectOption value="Australia/Sydney">Sydney (GMT+10)</NativeSelectOption>
    </NativeSelectOptGroup>
  </NativeSelect>
  <FieldHint>Used for your reports and reminders.</FieldHint>
</Field>
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add native-select
```

Manual: run `npm install radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/native-select/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

```tsx title="usage.tsx"
import { NativeSelect, NativeSelectOption } from "@/components/ui/native-select"

export function Example() {
  return (
    <NativeSelect name="role" defaultValue="editor">
      <NativeSelectOption value="admin">Admin</NativeSelectOption>
      <NativeSelectOption value="editor">Editor</NativeSelectOption>
      <NativeSelectOption value="viewer">Viewer</NativeSelectOption>
    </NativeSelect>
  )
}
```

## Beside a Select

The closed control is the Select trigger, token for token: the same frame and `--surface` ground, the same caret, and the same brand border and halo once it has focus. Heights come from `size`, the scale every control shares (`sm` 32 · `md` 36 · `lg` 40px), so the two sit in a row without anyone noticing which one is native. Native on the left, Select on the right.

```tsx
<NativeSelect size="sm" defaultValue="editor">…</NativeSelect>
<Select defaultValue="editor"><SelectTrigger size="sm">…</SelectTrigger>…</Select>

<NativeSelect size="md" defaultValue="editor">…</NativeSelect>
<Select defaultValue="editor"><SelectTrigger size="md">…</SelectTrigger>…</Select>

<NativeSelect size="lg" defaultValue="editor">…</NativeSelect>
<Select defaultValue="editor"><SelectTrigger size="lg">…</SelectTrigger>…</Select>
```

## Placeholder

Make the first option the empty one (`value=""`), and `disabled` so it can't be chosen back. While it is the selected option the control reads in the muted placeholder ink at normal weight, like an empty Select; the rows in the open list keep the foreground.

```tsx
<NativeSelect defaultValue="">
  <NativeSelectOption value="" disabled>Choose a role</NativeSelectOption>
  <NativeSelectOption value="admin">Admin</NativeSelectOption>
  <NativeSelectOption value="editor">Editor</NativeSelectOption>
  <NativeSelectOption value="viewer">Viewer</NativeSelectOption>
</NativeSelect>
```

## In a form

Where a native picker is the better one: a card expiry is two short fixed lists, and on a phone the OS wheel beats any custom menu. `Form` imposes its `lg` size on every control inside it, the native selects included, so the row lines up with the security code beside it. The values post with the form, with no JavaScript required.

```tsx
<Form className="w-full max-w-sm">
  <div className="grid grid-cols-3 gap-3">
    <Field>
      <FieldLabel>Month</FieldLabel>
      <NativeSelect name="exp-month" defaultValue="">
        <NativeSelectOption value="" disabled>MM</NativeSelectOption>
        {months.map((m) => <NativeSelectOption key={m} value={m}>{m}</NativeSelectOption>)}
      </NativeSelect>
    </Field>
    <Field>
      <FieldLabel>Year</FieldLabel>
      <NativeSelect name="exp-year" defaultValue="">
        <NativeSelectOption value="" disabled>YYYY</NativeSelectOption>
        {years.map((y) => <NativeSelectOption key={y} value={y}>{y}</NativeSelectOption>)}
      </NativeSelect>
    </Field>
    <Field>
      <FieldLabel>CVC</FieldLabel>
      <InputRoot><InputField name="cvc" placeholder="123" inputMode="numeric" /></InputRoot>
    </Field>
  </div>
</Form>
```

## Error and disabled

Inside a `Field`, `hasError` turns the frame red and points `aria-describedby` at the hint, which becomes the message; `disabled` on the Field reaches the select too. Both need no wiring on the control itself.

```tsx
<Field hasError>
  <FieldLabel>Plan</FieldLabel>
  <NativeSelect defaultValue="">
    <NativeSelectOption value="" disabled>Choose a plan</NativeSelectOption>
    …
  </NativeSelect>
  <FieldHint>Pick a plan to continue.</FieldHint>
</Field>
<Field disabled>
  <FieldLabel>Billing cycle</FieldLabel>
  <NativeSelect defaultValue="annual">…</NativeSelect>
  <FieldHint>Fixed while a payment is pending.</FieldHint>
</Field>
```

## API reference

### NativeSelect

A `<select>` in a positioned frame with the caret. Props: `size` (`sm` · `md` · `lg`, defaulting from the nearest Form or density), `density`, and every `<select>` prop except `multiple`: `name`, `value`, `defaultValue`, `onChange`, `required`, `ref`. `className` goes on the frame, so a width moves the caret with it.

### NativeSelectOption · NativeSelectOptGroup

The native `<option>` and `<optgroup>`, with their `data-slot`s. The operating system draws them, so they take text only.

## FAQ

### Native Select or Select?

Native Select where the OS picker is the better one: forms used on phones, long fixed lists (years, timezones), and forms that must post without JavaScript. Select where the options need icons, flags, descriptions, a search, or the same look on every platform.

### Can I style the list that opens?

Barely, and that is the point: the operating system draws it. The rows keep the foreground ink on Windows, and the dark themes ask for the dark native picker, but icons, descriptions and custom rows need Select.

### Why no `multiple`?

A native multi-select is a box of rows you have to ctrl-click, which nobody discovers. For several values from a list, use MultiSelect.

### Why does the focus halo stay while I pick?

A native select is focused for as long as its list is open, so the halo holds through the choice the way a Select trigger's does while its menu is open.

### Where does className go?

On the frame around the select, so `w-56` or `flex-1` sizes the control and moves the caret with it. Everything else, including `ref`, goes on the `<select>`.

---

<!-- https://www.koalaui.com/docs/components/navigation-menu.md -->

# Navigation Menu

Menus that open on hover and share one floating panel, so moving between triggers resizes and slides the same surface instead of opening a new popover.

```tsx
<NavigationMenu>
  <NavigationMenuList>
    <NavigationMenuItem>
      <NavigationMenuTrigger>Product</NavigationMenuTrigger>
      <NavigationMenuContent>
        <div className="flex w-72 flex-col">
          <NavigationMenuLink href="/analytics">
            <ChartBar />
            <NavigationMenuLinkText>
              Analytics
              <NavigationMenuLinkDescription>Traffic, funnels, and retention</NavigationMenuLinkDescription>
            </NavigationMenuLinkText>
          </NavigationMenuLink>
          <NavigationMenuLink href="/monitoring">
            <Gauge />
            <NavigationMenuLinkText>
              Monitoring
              <NavigationMenuLinkDescription>Uptime and performance alerts</NavigationMenuLinkDescription>
            </NavigationMenuLinkText>
          </NavigationMenuLink>
          <NavigationMenuLink href="/integrations">
            <Plugs />
            <NavigationMenuLinkText>
              Integrations
              <NavigationMenuLinkDescription>Connect your existing stack</NavigationMenuLinkDescription>
            </NavigationMenuLinkText>
          </NavigationMenuLink>
        </div>
      </NavigationMenuContent>
    </NavigationMenuItem>
    <NavigationMenuItem>
      <NavigationMenuTrigger>Resources</NavigationMenuTrigger>
      <NavigationMenuContent>
        <div className="flex w-56 flex-col">
          <NavigationMenuLink href="/changelog">
            <Sparkle />
            <NavigationMenuLinkText>Changelog</NavigationMenuLinkText>
          </NavigationMenuLink>
          <NavigationMenuLink href="/guides">
            <Rocket />
            <NavigationMenuLinkText>Guides</NavigationMenuLinkText>
          </NavigationMenuLink>
        </div>
      </NavigationMenuContent>
    </NavigationMenuItem>
    <NavigationMenuItem>
      <NavigationMenuLink variant="bar" href="/pricing">Pricing</NavigationMenuLink>
    </NavigationMenuItem>
    <NavigationMenuIndicator />
  </NavigationMenuList>
</NavigationMenu>
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add navigation-menu
```

Manual: run `npm install radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/navigation-menu/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

```tsx title="usage.tsx"
import {
  NavigationMenu,
  NavigationMenuList,
  NavigationMenuItem,
  NavigationMenuTrigger,
  NavigationMenuContent,
  NavigationMenuLink,
} from "@/components/ui/navigation-menu"

export function Example() {
  return (
    <NavigationMenu>
      <NavigationMenuList>
        <NavigationMenuItem>
          <NavigationMenuTrigger>Product</NavigationMenuTrigger>
          <NavigationMenuContent>
            <NavigationMenuLink href="/analytics">Analytics</NavigationMenuLink>
          </NavigationMenuContent>
        </NavigationMenuItem>
      </NavigationMenuList>
    </NavigationMenu>
  )
}
```

## Columns

For a wide menu, set `NavigationMenuGroup`s side by side, each under a `NavigationMenuGroupLabel`, and close the panel with a `NavigationMenuFooter` for the link to everything else.

```tsx
<NavigationMenuContent>
  <div className="w-[34rem]">
    <div className="grid grid-cols-3 gap-1">
      <NavigationMenuGroup>
        <NavigationMenuGroupLabel>Platform</NavigationMenuGroupLabel>
        <NavigationMenuLink href="/analytics">Analytics</NavigationMenuLink>
        <NavigationMenuLink href="/monitoring">Monitoring</NavigationMenuLink>
        <NavigationMenuLink href="/alerts">Alerts</NavigationMenuLink>
        <NavigationMenuLink href="/dashboards">Dashboards</NavigationMenuLink>
      </NavigationMenuGroup>
      <NavigationMenuGroup>
        <NavigationMenuGroupLabel>Solutions</NavigationMenuGroupLabel>
        …
      </NavigationMenuGroup>
      <NavigationMenuGroup>
        <NavigationMenuGroupLabel>Developers</NavigationMenuGroupLabel>
        …
      </NavigationMenuGroup>
    </div>
    <NavigationMenuFooter>
      <NavigationMenuLink href="/platform">
        Explore the platform
        <ArrowRight className="size-4" />
      </NavigationMenuLink>
      <NavigationMenuLink href="/status" className="font-normal text-muted-foreground">
        <span aria-hidden className="size-2 rounded-full bg-success" />
        All systems normal
      </NavigationMenuLink>
    </NavigationMenuFooter>
  </div>
</NavigationMenuContent>
```

## Featured card

`variant="card"` turns a link into a featured block: a `NavigationMenuLinkMedia` picture over its title and description, beside the rows. The whole card is the link.

```tsx
<NavigationMenuContent>
  <div className="grid w-[34rem] grid-cols-[1fr_15rem] gap-1">
    <div className="flex flex-col">
      <NavigationMenuLink href="/docs">
        <BookOpen />
        <NavigationMenuLinkText>
          Documentation
          <NavigationMenuLinkDescription>Guides and the full API</NavigationMenuLinkDescription>
        </NavigationMenuLinkText>
      </NavigationMenuLink>
      …
    </div>
    <NavigationMenuLink variant="card" href="/customers/lumen">
      <NavigationMenuLinkMedia>
        <img src="/lumen-team.jpg" alt="" />
      </NavigationMenuLinkMedia>
      <NavigationMenuLinkText>
        How Lumen ships twice as fast
        <NavigationMenuLinkDescription>
          One dashboard for every team, and a release each week.
        </NavigationMenuLinkDescription>
      </NavigationMenuLinkText>
    </NavigationMenuLink>
  </div>
</NavigationMenuContent>
```

## Category rail

A `NavigationMenuSub` nests a menu inside the panel: a rail of categories down the side and a pane that switches the moment the pointer reaches the next one, with no delay. Its `defaultValue` picks the pane that shows first.

```tsx
<NavigationMenuContent>
  <NavigationMenuSub defaultValue="engineering">
    <NavigationMenuList className="w-40">
      <NavigationMenuItem value="engineering">
        <NavigationMenuTrigger>Engineering</NavigationMenuTrigger>
        <NavigationMenuContent>
          <div className="flex w-72 flex-col">
            <NavigationMenuLink href="/monitoring">
              <Gauge />
              <NavigationMenuLinkText>
                Monitoring
                <NavigationMenuLinkDescription>Uptime and latency by region</NavigationMenuLinkDescription>
              </NavigationMenuLinkText>
            </NavigationMenuLink>
            …
          </div>
        </NavigationMenuContent>
      </NavigationMenuItem>
      <NavigationMenuItem value="product">…</NavigationMenuItem>
      <NavigationMenuItem value="marketing">…</NavigationMenuItem>
      <NavigationMenuItem value="sales">…</NavigationMenuItem>
    </NavigationMenuList>
    <NavigationMenuSubViewport />
  </NavigationMenuSub>
  <NavigationMenuFooter>
    <NavigationMenuLink href="/solutions">
      See every solution
      <ArrowRight className="size-4" />
    </NavigationMenuLink>
  </NavigationMenuFooter>
</NavigationMenuContent>
```

## Icon tiles

`NavigationMenuLinkIcon` sets a row's glyph in a 32px tile. A brand logo keeps its own colours there, where a bare icon in a row is muted, so it's the pick for integrations and apps.

```tsx
<NavigationMenuContent>
  <div className="w-[32rem]">
    <div className="grid grid-cols-2">
      <NavigationMenuLink href="/integrations/github">
        <NavigationMenuLinkIcon>
          <GitHubLogo className="size-5" />
        </NavigationMenuLinkIcon>
        <NavigationMenuLinkText>
          GitHub
          <NavigationMenuLinkDescription>Link deploys to commits</NavigationMenuLinkDescription>
        </NavigationMenuLinkText>
      </NavigationMenuLink>
      …
    </div>
    <NavigationMenuFooter>
      <NavigationMenuLink href="/integrations">
        Browse all 120 integrations
        <ArrowRight className="size-4" />
      </NavigationMenuLink>
    </NavigationMenuFooter>
  </div>
</NavigationMenuContent>
```

## Timing

A trigger opens after `delayDuration` (200ms), so a cursor passing over the bar doesn't flash every menu. Reach a sibling trigger within `skipDelayDuration` (300ms) and it opens at once.

```tsx
<NavigationMenu delayDuration={100} skipDelayDuration={500}>
  <NavigationMenuList>
    <NavigationMenuItem>
      <NavigationMenuTrigger>Product</NavigationMenuTrigger>
      <NavigationMenuContent>
        <div className="flex w-56 flex-col">
          <NavigationMenuLink href="/analytics"><ChartBar />Analytics</NavigationMenuLink>
          <NavigationMenuLink href="/monitoring"><Gauge />Monitoring</NavigationMenuLink>
        </div>
      </NavigationMenuContent>
    </NavigationMenuItem>
    <NavigationMenuItem>
      <NavigationMenuTrigger>Company</NavigationMenuTrigger>
      <NavigationMenuContent>
        <div className="flex w-56 flex-col">
          <NavigationMenuLink href="/about"><Rocket />About us</NavigationMenuLink>
          <NavigationMenuLink href="/careers"><Storefront />Careers</NavigationMenuLink>
        </div>
      </NavigationMenuContent>
    </NavigationMenuItem>
    <NavigationMenuIndicator />
  </NavigationMenuList>
</NavigationMenu>
```

## Without the shared panel

`viewport={false}` gives each trigger its own panel, opened under it. Switching closes one and opens the next, so reach for it only when the menus are far apart.

```tsx
<NavigationMenu viewport={false}>
  <NavigationMenuList>
    <NavigationMenuItem>
      <NavigationMenuTrigger>Product</NavigationMenuTrigger>
      <NavigationMenuContent>
        <div className="flex w-56 flex-col">
          <NavigationMenuLink href="/analytics"><ChartBar />Analytics</NavigationMenuLink>
          <NavigationMenuLink href="/monitoring"><Gauge />Monitoring</NavigationMenuLink>
        </div>
      </NavigationMenuContent>
    </NavigationMenuItem>
    <NavigationMenuItem>
      <NavigationMenuTrigger>Resources</NavigationMenuTrigger>
      <NavigationMenuContent>
        <div className="flex w-56 flex-col">
          <NavigationMenuLink href="/changelog"><Sparkle />Changelog</NavigationMenuLink>
          <NavigationMenuLink href="/guides"><Rocket />Guides</NavigationMenuLink>
        </div>
      </NavigationMenuContent>
    </NavigationMenuItem>
  </NavigationMenuList>
</NavigationMenu>
```

## Density

`density` on the root sets the row height of every link in the menu. The panel padding stays put, so the corners stay concentric in both.

```tsx
<NavigationMenu density="comfortable">…</NavigationMenu>
<NavigationMenu density="compact">…</NavigationMenu>
```

## API reference

NavigationMenu

The root. Forwards Radix's `delayDuration`, `skipDelayDuration` and `value` / `onValueChange`. `viewport` (default `true`) renders the shared panel; `density` sets the row height of every link.

NavigationMenuList / NavigationMenuItem

The row and each entry in it. An item holds a trigger and its content, or a single `NavigationMenuLink variant="bar"`.

NavigationMenuTrigger / NavigationMenuContent

The chip in the bar and the contents of its panel. The caret turns while the panel is open.

NavigationMenuLink

`variant`: `"row"` (default), a row in a panel; `"bar"`, a plain entry beside the triggers; or `"card"`, a featured block. `active` marks the current page. Wrap a title and a `NavigationMenuLinkDescription` in `NavigationMenuLinkText` for a described row.

NavigationMenuLinkIcon / NavigationMenuLinkMedia

A 32px tile for a row's glyph, where a brand logo keeps its colours, and the inset picture frame of a `card` link. Put an `<img>` inside the frame; it owns an `aspect-video` ratio you can override.

NavigationMenuGroup / NavigationMenuGroupLabel / NavigationMenuFooter

A labelled column of links, its small muted heading, and the panel's foot under a hairline. Each is optional: a group reads fine without its label, and a footer with nothing above it drops its rule.

NavigationMenuSub / NavigationMenuSubViewport

A menu inside a panel. The Sub holds a `NavigationMenuList` rail (vertical by default) and, after it, the viewport the active pane shows in. It forwards Radix's `defaultValue`, `value` and `orientation`.

NavigationMenuIndicator / NavigationMenuViewport

The tip that slides under the active trigger (optional, the list's last child), and the shared panel, which the root already renders.

## FAQ

### How is this different from DropdownMenu?

DropdownMenu opens on click and every instance is its own popover: right for a single menu, like a Navbar's Collections link. NavigationMenu opens on hover and shares one panel across every trigger, so crossing from one to the next resizes that panel instead of swapping popovers.

### Why doesn't a passing cursor open every menu?

delayDuration (200ms) waits before the first open. Once one is open, skipDelayDuration (300ms) lets the next trigger open at once. Both are props on the root.

### Where does the panel sit?

Under the menu, aligned to its start edge, and as wide as the open content. Give the content's wrapper a width (w-56, w-72) to size each panel.

### Can one bar mix these layouts?

Yes. Every trigger's content mounts into the same panel, so a Product menu in columns, a Solutions rail and an Integrations grid can sit side by side: moving across the bar resizes the panel from one layout to the next.

### Is it accessible?

Yes. Radix handles the keyboard: arrow keys move between triggers, Enter or Space opens, Escape closes and returns focus to the trigger.

---

<!-- https://www.koalaui.com/docs/components/otp-input.md -->

# OTP Input

A numeric one-time-passcode field. Auto-advances on entry, distributes pasted codes across slots, and supports SMS autofill on mobile. Configure the digit count, size, and error state with plain props.

```tsx
<OTPInput
  length={6}
  placeholder="0"
  label="Verification code"
  hint="Enter the 6-digit code we sent to your phone."
/>
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add otp-input
```

Manual: run `npm install radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/otp-input/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

```tsx title="usage.tsx"
import { OTPInput } from "@/components/ui/otp-input"

export function Example() {
  return (
    <OTPInput
      length={6}
      onComplete={(code) => verify(code)}
    />
  )
}
```

## Length

`length` sets the number of digit slots, defaulting to `6`. Four-digit PINs and longer codes use the same component; paste a full code into any slot and it spreads across the rest.

```tsx
<OTPInput length={4} placeholder="0" />

<OTPInput length={6} placeholder="0" />
```

## Label & hint

Pass `label` to caption the field and `hint` for helper text below it. The label wires up as the group’s `aria-labelledby` (clicking it focuses the first slot) and the hint as its `aria-describedby`. Add `required` for a destructive asterisk.

```tsx
<OTPInput
  length={6}
  required
  label="Verification code"
  hint="Check your authenticator app."
  placeholder="0"
/>
```

## Sizes

Three sizes: `sm` (40 px slots), `md` (48 px, the default), and `lg` (56 px). Each stays at or above the 40 px minimum touch target.

```tsx
<OTPInput size="sm" length={4} label="Small" placeholder="0" />

<OTPInput size="md" length={4} label="Medium" placeholder="0" />

<OTPInput size="lg" length={4} label="Large" placeholder="0" />
```

## Separators

Split the slots into groups with `separator`: `"dash"` draws a short divider line, `"dot"` renders a centered `·`, or pass any node for a custom mark. Groups default to two even halves; override with `groupSize`.

```tsx
<OTPInput length={6} separator="dash" placeholder="0" />

<OTPInput length={6} separator="dot" placeholder="0" />

<OTPInput length={6} separator="dash" groupSize={2} placeholder="0" />
```

## Digit entry

Every digit you type rises into its slot from below, on the same roll `AnimatedNumber` uses: it travels up on `duration-base` with `ease-out` and reaches full opacity early, so the eye tracks motion rather than a fade. Typing over a digit, or deleting it, lifts the old one up and out as the new one comes in. Each slot keeps its own roll, so typing fast never cuts the previous digit short.

A pasted code fans in left to right, one `--number-roll-stagger` step apart, so it reads in the order you would say it. A code that is already there when the field mounts (`defaultValue`, a restored form) holds still. Under `prefers-reduced-motion` digits simply appear. The slots stay real inputs underneath, so the caret, selection, autofill and screen readers work as usual.

```tsx
<OTPInput length={6} separator="dash" placeholder="0" />
```

## Validation & errors

Input is numeric-only by construction: non-digit characters (and non-numeric pasted content) are stripped before they ever reach a slot, so you never validate the format yourself. For a *wrong code*, pass `hasError` to switch every slot to the destructive border and ring and set `aria-invalid`; pair it with a message below the field. Use `onComplete` to run verification the moment the last slot fills, and `onChange` for keystroke-level state. When `hasError` is set, the `hint` turns destructive so it doubles as the error message, and the row of slots shakes once (see below).

```tsx
<OTPInput
  length={6}
  hasError
  defaultValue="123456"
  label="Verification code"
  hint="That code didn't match. Try again."
/>
```

## Wrong-code shake

A rejected code doesn’t just recolor: the row of slots swings through a damped wobble and settles, so the refusal registers before you’ve read a word of the message. Each swing is weaker than the last and the motion runs on `ease-sine`, which leaves and arrives at zero velocity, so the throws join into one continuous arc rather than a buzz. Only the row moves. The label and the hint hold still, which keeps the error text readable the instant it lands, and the digits stay put so you can repair the one you got wrong instead of retyping all six.

It fires on its own every time `hasError` goes from `false` to `true`, including when the field mounts already in an error state (a form that came back rejected). No extra props: clear the error as the user edits and the next failure shakes again. The motion is decorative, so it is skipped entirely under `prefers-reduced-motion`, where the destructive border, `aria-invalid`, and the hint still carry the verdict.

```tsx
const [value, setValue] = useState("")
const [status, setStatus] = useState("idle")

<OTPInput
  length={6}
  placeholder="0"
  label="Verification code"
  value={value}
  hasError={status === "error"}
  onChange={(next) => {
    setValue(next)
    // Editing retracts the verdict, so the next
    // rejection is a fresh false → true flip.
    if (status !== "idle") setStatus("idle")
  }}
  onComplete={(code) =>
    setStatus(code === "424242" ? "verified" : "error")
  }
  hint={
    status === "error"
      ? "That code didn't match. Try again."
      : status === "verified"
        ? "Code verified."
        : "Enter any 6 digits to see the shake."
  }
/>
```

If you keep `hasError` pinned `true` across attempts, there is no flip to key off and the second identical rejection would sit silent. Change `errorKey` instead: any new value re-arms the shake under a standing error. An attempt counter is the usual choice.

```tsx
const [attempts, setAttempts] = useState(0)

<OTPInput
  length={6}
  placeholder="0"
  label="Verification code"
  value={value}
  // Never retracted while the user re-types...
  hasError={attempts > 0}
  // ...so the attempt count re-arms the shake.
  errorKey={attempts}
  onChange={setValue}
  onComplete={(code) => {
    if (code !== "424242") setAttempts((n) => n + 1)
  }}
/>
```

## Disabled

```tsx
<OTPInput length={6} disabled defaultValue="12" />
```

## FAQ

### What is the difference between onChange and onComplete?

`onChange` fires on every keystroke with the current value, so use it for keystroke-level state. `onComplete` fires once the moment the last slot fills, which is the right place to kick off verification.

### Do I need to validate or filter the input myself?

No. The field is numeric-only by construction: non-digit characters and non-numeric pasted content are stripped before they ever reach a slot, so you never validate the format yourself.

### How do I show a wrong-code error?

Pass `hasError` to switch every slot to the destructive border and ring and set `aria-invalid`. When set, the `hint` text also turns destructive, so it doubles as the error message.

### Does anything move when the code is wrong?

Yes. The row of slots shakes once, so the refusal registers before the message is read. Only the row moves: the label and hint hold still, and the digits stay so you can repair the wrong one instead of retyping all six. The shake is decorative and is skipped entirely under `prefers-reduced-motion`.

### The same wrong code twice doesn't shake the second time.

The shake fires when `hasError` goes from `false` to `true`, so a `hasError` that stays pinned true across attempts never re-fires. Either clear it as the user edits, or bump `errorKey` (an attempt counter works) on each rejection to re-arm the shake.

### Can I turn off the digit roll?

It follows `prefers-reduced-motion`: with reduced motion on, digits appear without moving. A prefilled code never rolls on mount, only digits that arrive after it. The visible digit is painted over the real input (which keeps the value, caret and selection), so screen readers and autofill are unaffected.

### How do I split the digits into groups?

Use `separator`: "dash" draws a short divider line, "dot" renders a centered middle dot, or pass any node for a custom mark. Groups default to two even halves; override the chunk size with `groupSize`.

### Does paste and SMS autofill work across the slots?

Yes. Pasting a full code into any slot spreads it across the rest, and on mobile the first slot carries `autoComplete="one-time-code"` so the OS can autofill a code from SMS.

### How are the label and hint wired for accessibility?

The `label` becomes the group's `aria-labelledby` (clicking it focuses the first slot) and the `hint` becomes its `aria-describedby`. Add `required` for a destructive asterisk.

---

<!-- https://www.koalaui.com/docs/components/pagination.md -->

# Pagination

A toolbar for navigating a paged dataset: current page and total, prev/next, a go-to-page field and a rows-per-page select. Each addon is toggled by a show* boolean, from a bare bar to a full footer.

```tsx
function Example() {
  const [page, setPage] = useState(1)
  const [rowsPerPage, setRowsPerPage] = useState(20)

  return (
    <Pagination
      page={page}
      pageCount={24}
      onPageChange={setPage}
      rowsPerPage={rowsPerPage}
      onRowsPerPageChange={setRowsPerPage}
      showInfo
      showControls
      showGoTo
      showRowsPerPage
    />
  )
}
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add pagination
```

Manual: run `npm install radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/pagination/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

```tsx title="usage.tsx"
import { Pagination } from "@/components/ui/pagination"

export function Example() {
  const [page, setPage] = useState(1)

  return (
    <Pagination
      page={page}
      pageCount={10}
      onPageChange={setPage}
    />
  )
}
```

## Default

Out of the box you get the page readout and prev/next controls. The component is fully controlled: drive it with `page` and `onPageChange`. The buttons disable themselves at the first and last page.

```tsx
<Pagination page={page} pageCount={10} onPageChange={setPage} />
```

## Go to page

Set `showGoTo` to add a numeric field for jumping to an arbitrary page. The value commits on `Enter` or blur and is clamped into range, so an out-of-bounds entry snaps back to the nearest valid page.

```tsx
<Pagination
  page={page}
  pageCount={50}
  onPageChange={setPage}
  showGoTo
/>
```

## Rows per page

Set `showRowsPerPage` and wire `rowsPerPage` / `onRowsPerPageChange` to let users choose how many rows to load. Customize the choices with `rowsPerPageOptions`.

```tsx
<Pagination
  page={page}
  pageCount={12}
  onPageChange={setPage}
  rowsPerPage={rowsPerPage}
  onRowsPerPageChange={setRowsPerPage}
  rowsPerPageOptions={[10, 25, 50, 100]}
  showRowsPerPage
/>
```

## Density

Like the rest of Koala, Pagination honors the `density` axis (prop or `DensityProvider`). The whole toolbar lands on one matched control height: a 40px row when comfortable, a 32px row when compact.

```tsx
<Pagination density="comfortable" page={page} pageCount={16} onPageChange={setPage} showGoTo />
<Pagination density="compact" page={page} pageCount={16} onPageChange={setPage} showGoTo />
```

## Custom layout

For a bespoke arrangement, drop the `show*` toggles and compose the parts yourself inside `PaginationRoot`. Every part: `PaginationInfo`, `PaginationControls`, `PaginationGoTo`, `PaginationRowsPerPage`, reads the shared state from context.

```tsx
<PaginationRoot page={page} pageCount={20} onPageChange={setPage}>
  <PaginationControls />
  <PaginationInfo />
  <PaginationGoTo label="Jump to" />
</PaginationRoot>
```

## FAQ

### Is Pagination controlled or uncontrolled?

It is fully controlled. Drive it with `page` and `pageCount` and update your state in `onPageChange`; the prev/next controls disable themselves automatically at the first and last page.

### How do I turn the extra pieces on?

Each addon is gated by a `show*` boolean: `showInfo` for the page readout, `showControls` for prev/next, `showGoTo` for the jump field, and `showRowsPerPage` for the rows-per-page select. That lets the same component be a bare prev/next bar or a full data-table footer.

### What happens if someone types an out-of-range page in the go-to field?

With `showGoTo`, the value commits on Enter or blur and is clamped into range, so an out-of-bounds entry snaps back to the nearest valid page.

### How do I wire the rows-per-page select?

Set `showRowsPerPage` and pass `rowsPerPage` with `onRowsPerPageChange`. Customize the choices with `rowsPerPageOptions`, for example `[10, 25, 50, 100]`.

### Can I build a custom layout from the parts?

Yes. Drop the `show*` toggles and compose `PaginationInfo`, `PaginationControls`, `PaginationGoTo`, and `PaginationRowsPerPage` yourself inside `PaginationRoot`; every part reads the shared state from context.

### Does Pagination respect density?

Yes. The `density` prop (or a surrounding DensityProvider) lands the whole toolbar on one matched control height: a 40px row when comfortable and a 32px row when compact.

---

<!-- https://www.koalaui.com/docs/components/password-strength.md -->

# Password Strength

A live strength meter for password fields: a segmented bar that climbs red to green, a one-word verdict and an optional requirements checklist. It scores the value against a rule set you control.

```tsx
const [value, setValue] = React.useState("")

<PasswordInput value={value} onChange={(e) => setValue(e.target.value)} />
<PasswordStrength value={value}>
  <PasswordStrengthMeter />
  <div className="flex items-center justify-between gap-2">
    <span className="text-sm text-muted-foreground">Password strength</span>
    <PasswordStrengthLabel placeholder="-" />
  </div>
</PasswordStrength>
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add password-strength
```

Manual: run `npm install radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/password-strength/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

Hold the password in state and hand the same value to both the `PasswordInput` and `PasswordStrength`. The root scores the value against its rule set and exposes the result to the parts through context - compose `PasswordStrengthMeter`, `PasswordStrengthLabel`, and `PasswordStrengthList` in any arrangement.

```tsx title="usage.tsx"
"use client"
import * as React from "react"
import { PasswordInput } from "@/components/ui/input"
import {
  PasswordStrength,
  PasswordStrengthMeter,
  PasswordStrengthLabel,
} from "@/components/ui/password-strength"

export function Example() {
  const [value, setValue] = React.useState("")
  return (
    <>
      <PasswordInput value={value} onChange={(e) => setValue(e.target.value)} />
      <PasswordStrength value={value}>
        <PasswordStrengthMeter />
        <PasswordStrengthLabel placeholder="-" />
      </PasswordStrength>
    </>
  )
}
```

## With requirements

Add `PasswordStrengthList` to spell out the policy. The moment the password satisfies a requirement, its dot lifts up and out while the check rises from below into place, so a rule being met reads as progress rather than a blink, and the user always knows what is left.

```tsx
<PasswordStrength value={value}>
  <PasswordStrengthMeter />
  <PasswordStrengthList />
</PasswordStrength>
```

## Inside a Field

It composes straight into a `Field`, sitting where the hint would - the label and input keep their auto-wiring while the meter reports on the value below them.

```tsx
<Field>
  <FieldLabel>Password</FieldLabel>
  <PasswordInput value={value} onChange={(e) => setValue(e.target.value)} />
  <PasswordStrength value={value}>
    <PasswordStrengthMeter />
  </PasswordStrength>
</Field>
```

## Custom policy

Pass `rules` to replace the default policy. Each rule is an `{ id, label, test }` - the meter normalises however many you supply onto its four segments, and the list renders one row per rule.

```tsx
const corporateRules = [
  { id: "length", label: "At least 12 characters", test: (v) => v.length >= 12 },
  { id: "case", label: "Upper & lowercase letters", test: (v) => /[a-z]/.test(v) && /[A-Z]/.test(v) },
  { id: "number", label: "At least one number", test: (v) => /\d/.test(v) },
  { id: "symbol", label: "At least one symbol (!@#$…)", test: (v) => /[^A-Za-z0-9]/.test(v) },
  { id: "no-spaces", label: "No spaces", test: (v) => v.length > 0 && !/\s/.test(v) },
]

<PasswordStrength value={value} rules={corporateRules}>
  <div className="flex items-center justify-between gap-2">
    <PasswordStrengthMeter className="max-w-[60%]" />
    <PasswordStrengthLabel placeholder="-" />
  </div>
  <PasswordStrengthList />
</PasswordStrength>
```

## FAQ

### Why is this a separate component from the password input?

Scoring is kept a separate concern so the meter drops in below any `PasswordInput` without coupling. You hold the password in state and hand the same value to both the input and `PasswordStrength`.

### How do I compose the parts?

The root scores the value and exposes the result through context, so place `PasswordStrengthMeter`, `PasswordStrengthLabel`, and `PasswordStrengthList` in any arrangement inside `PasswordStrength`. `PasswordStrengthLabel` takes a `placeholder` shown before anything is typed.

### How do I change the password policy?

Pass `rules`, an array of `{ id, label, test }`. The default policy is at least 8 characters, mixed case, a number, and a symbol; `test` receives the value and returns whether the rule is met.

### What happens to the four-segment meter if I supply a different number of rules?

The meter always normalises however many rules you pass onto its four segments, climbing red to green, while `PasswordStrengthList` renders exactly one row per rule. So five corporate rules still map cleanly onto the bar.

### Can it live inside a Field?

Yes. It composes straight into a `Field`, sitting where the hint would go, so the `FieldLabel` and input keep their auto-wiring while the meter reports on the value below them.

### How does the requirements list signal progress?

The moment the password satisfies a rule, that row's dot lifts up and out while the check rises from below into place, the same roll the strength verdict uses, so the whole component moves in one direction. Both glyphs stay mounted and cross-fade on a transition rather than a keyframe, so a rule that flips back mid-roll retargets instead of restarting - which matters when the list is reacting to every keystroke.

---

<!-- https://www.koalaui.com/docs/components/popover.md -->

# Popover

A general-purpose floating surface over Radix Popover: focus management, dismiss and collision-aware positioning. Hosts forms, pickers and info cards, with an exposed --surface so nested controls blend in.

```tsx
<Popover>
  <PopoverTrigger asChild>
    <Button variant="outline">Open popover</Button>
  </PopoverTrigger>
  <PopoverContent>
    <div className="space-y-1">
      <PopoverTitle>Invite teammates</PopoverTitle>
      <PopoverDescription>
        Share this workspace with anyone on your team.
      </PopoverDescription>
    </div>
  </PopoverContent>
</Popover>
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add popover
```

Manual: run `npm install radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/popover/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

```tsx title="usage.tsx"
import {
  Popover,
  PopoverTrigger,
  PopoverContent,
} from "@/components/ui/popover"

export function Example() {
  return (
    <Popover>
      <PopoverTrigger asChild>
        <Button variant="outline">Open</Button>
      </PopoverTrigger>
      <PopoverContent>Content</PopoverContent>
    </Popover>
  )
}
```

## With a form

The canonical use case. Because the content exposes `--surface`, nested `Input`s paint the panel surface rather than the page. Wrap actions in `PopoverClose` to dismiss on click.

```tsx
<Popover>
  <PopoverTrigger asChild>
    <Button variant="outline"><Gear /> Dimensions</Button>
  </PopoverTrigger>
  <PopoverContent className="w-80">
    {/* title + inputs */}
    <PopoverClose asChild>
      <Button size="sm">Save</Button>
    </PopoverClose>
  </PopoverContent>
</Popover>
```

## With arrow & close button

Set `showArrow` for a pointer toward the trigger, and use `PopoverCloseButton` for a styled top-right dismiss.

```tsx
<PopoverContent showArrow className="w-64">
  <PopoverCloseButton aria-label="Close">×</PopoverCloseButton>
  <PopoverTitle>Heads up</PopoverTitle>
  <PopoverDescription>…</PopoverDescription>
</PopoverContent>
```

## Alignment

Control placement along the trigger with `align` (`start` · `center` · `end`) and `side` / `sideOffset`, all forwarded to Radix.

```tsx
<PopoverContent align="start">…</PopoverContent>
<PopoverContent align="center">…</PopoverContent>
<PopoverContent align="end">…</PopoverContent>
```

## Density

`density` tunes the content padding: `compact` for dense application UI. It also cascades from a surrounding `DensityProvider`.

```tsx
<PopoverContent density="compact">…</PopoverContent>
```

## Confirm an action

A lightweight inline confirm for a destructive action. The footer pairs a `ghost` Cancel with a `destructive` primary, each wrapped in `PopoverClose` so either choice dismisses.

```tsx
<Popover>
  <PopoverTrigger asChild>
    <Button variant="outline"><Trash /> Delete project</Button>
  </PopoverTrigger>
  <PopoverContent className="w-72">
    <PopoverTitle>Delete project?</PopoverTitle>
    <PopoverDescription>This permanently removes the project and all of its data.</PopoverDescription>
    <div className="flex justify-end gap-2">
      <PopoverClose asChild><Button variant="ghost" size="sm">Cancel</Button></PopoverClose>
      <PopoverClose asChild><Button variant="destructive" size="sm">Delete</Button></PopoverClose>
    </div>
  </PopoverContent>
</Popover>
```

## Profile card

A richer surface: compose an `Avatar` with identity and actions for a hover-card style preview.

```tsx
<Popover>
  <PopoverTrigger asChild>
    <Button variant="ghost" size="sm">@katiep</Button>
  </PopoverTrigger>
  <PopoverContent className="w-72">
    <div className="flex items-center gap-3">
      <AvatarRoot size="lg">
        <AvatarImage src="https://i.pravatar.cc/160?img=5" alt="Katie Park" />
        <AvatarFallback>KP</AvatarFallback>
        <AvatarStatus variant="online" />
      </AvatarRoot>
      <div className="flex flex-col">
        <span className="text-sm font-semibold text-foreground">Katie Park</span>
        <span className="text-sm text-muted-foreground">@katiep</span>
      </div>
    </div>
    <div className="flex gap-2">
      <Button size="sm" className="flex-1">Follow</Button>
      <Button variant="outline" size="sm" className="flex-1">Message</Button>
    </div>
  </PopoverContent>
</Popover>
```

## Media and footer

`PopoverMedia` frames a picture or video 8px in from the panel's edges, first or last, with corners concentric to the panel's (16px outside, 8px on the picture). `PopoverFooter` closes the panel with a muted well on the same inset, where a divider line would otherwise go; its text lands back on the copy's line. At `compact` both sit 4px in, with 12px corners.

```tsx
<PopoverContent className="w-80">
  <PopoverMedia>
    <img src="…" alt="A style guide spread" />
  </PopoverMedia>
  <div className="mt-3 flex flex-col gap-1.5">
    <PopoverTitle>Density comes to every form</PopoverTitle>
    <PopoverDescription>One size prop across fields, selects and buttons…</PopoverDescription>
  </div>
  <PopoverFooter className="justify-between">
    <span className="text-muted-foreground">Koala 2.4 · 12 changes</span>
    <Link href="/changelog">Read the notes</Link>
  </PopoverFooter>
</PopoverContent>
```

## Share a link

A read-only `Input` blends with the panel through `--surface`, and the copy button swaps to a confirmation for a beat after a click.

```tsx
const [copied, setCopied] = useState(false)

<PopoverContent className="w-80">
  <PopoverTitle>Share link</PopoverTitle>
  <PopoverDescription>Anyone with this link can view the project.</PopoverDescription>
  <div className="flex items-center gap-2">
    <InputRoot size="sm" className="flex-1">
      <InputField readOnly value="koalaui.com/s/9f3a2" />
    </InputRoot>
    <Button size="sm" className="shrink-0" swapKey={copied ? "copied" : "copy"} onClick={copy}>
      {copied ? <><Check /> Copied</> : <><Copy /> Copy</>}
    </Button>
  </div>
</PopoverContent>
```

## Feedback prompt

A common composition: pair the surface with a `ToggleGroup` for a "Was this useful?" rating. The control is its own label, so no inputs are needed. Shown here always visible as a card; the same content drops straight into a `PopoverContent`.

```tsx
<div className="rounded-xl border border-border bg-card p-4 shadow-sm [--surface:var(--card)]">
  <PopoverTitle className="text-base">Was this useful?</PopoverTitle>
  <PopoverDescription>How would you rate your overall experience?</PopoverDescription>
  <ToggleGroup type="single" size="sm" value={rating} onValueChange={setRating}>
    <ToggleGroupItem value="yes"><ThumbsUp />Yes</ToggleGroupItem>
    <ToggleGroupItem value="no"><ThumbsDown />No</ToggleGroupItem>
  </ToggleGroup>
</div>
```

A compact take drops the subtitle and swaps in a thank-you once answered.

```tsx
<div className="rounded-xl border border-border bg-card p-4 shadow-xs [--surface:var(--card)]">
  {answer ? (
    <p className="text-sm text-muted-foreground">Thanks for your feedback!</p>
  ) : (
    <>
      <p className="text-sm font-semibold">Was this useful?</p>
      <ToggleGroup type="single" size="sm" value={answer} onValueChange={setAnswer}>
        <ToggleGroupItem value="yes"><ThumbsUp />Yes</ToggleGroupItem>
        <ToggleGroupItem value="no"><ThumbsDown />No</ToggleGroupItem>
      </ToggleGroup>
    </>
  )}
</div>
```

And floated in the popover itself, revealed from a trigger.

```tsx
<Popover>
  <PopoverTrigger asChild>
    <Button variant="outline">Was this useful?</Button>
  </PopoverTrigger>
  <PopoverContent align="start" className="w-auto">
    <PopoverTitle className="text-base">Was this useful?</PopoverTitle>
    <PopoverDescription>How would you rate your overall experience?</PopoverDescription>
    <ToggleGroup type="single" size="sm" value={rating} onValueChange={setRating}>
      <ToggleGroupItem value="yes"><ThumbsUp />Yes</ToggleGroupItem>
      <ToggleGroupItem value="no"><ThumbsDown />No</ToggleGroupItem>
    </ToggleGroup>
  </PopoverContent>
</Popover>
```

## FAQ

### When should I use a Popover instead of a DropdownMenu or Tooltip?

Reach for Popover to host arbitrary content like forms, pickers, or info cards. DropdownMenu is for lists of actions with menu keyboard semantics, and Tooltip is for a passive hover hint.

### How do I dismiss the popover when a button inside it is clicked?

Wrap the control in `PopoverClose` (use `asChild` to keep your own Button styling), and it closes the panel on click with no extra wiring. `PopoverCloseButton` is a ready-made styled top-right dismiss.

### Why do Inputs inside PopoverContent blend with the panel instead of the page?

PopoverContent exposes `--surface: var(--popover)`, so nested controls like Input and Select read that variable and paint the panel surface rather than a separate background block.

### How do I position the panel and add a pointer to the trigger?

Pass `align` (start, center, end), `side`, and `sideOffset`, all forwarded to Radix with collision-aware repositioning. Set `showArrow` to render a small arrow pointing at the trigger.

### How does density affect the popover?

The `density` prop tunes the content padding: `comfortable` is `p-4` and `compact` is `p-3`, and with it how far `PopoverMedia` and `PopoverFooter` sit in from the edge (8px or 4px, with the matching concentric radius). It also cascades from a surrounding DensityProvider.

### Do I need the helper parts like PopoverTitle and PopoverDescription?

No, they are optional structured-content helpers for consistent typography. PopoverContent will host any children you give it.

---

<!-- https://www.koalaui.com/docs/components/progress.md -->

# Progress

A bar that reports how far along something is. Built on Radix Progress, so the value is announced to assistive tech for free. The label and readout are droppable parts, and a chrome variant strips the track.

```tsx
<Progress value={64} />
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add progress
```

Manual: run `npm install radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/progress/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

Pass `value` (0 to `max`, which defaults to 100). That alone renders the bare bar. Anything you pass as children becomes the row above it, so a label and a readout are composed in rather than switched on: there is no `showLabel` prop, and dropping either part simply removes it.

```tsx title="usage.tsx"
import { Progress, ProgressLabel, ProgressValue } from "@/components/ui/progress"

export function Example() {
  return (
    <Progress value={72}>
      <ProgressLabel>Importing components</ProgressLabel>
      <ProgressValue />
    </Progress>
  )
}
```

## With a label and a readout

`ProgressValue` prints a whole percentage by default and reads the value from context, so it never drifts from the bar. Give it a function to phrase the readout yourself: `{(value, max) => …}` receives the same numbers. It is `aria-hidden`, because Radix already exposes the value on the bar itself and a screen reader should not hear it twice.

```tsx
<Progress value={72}>
  <ProgressLabel>Importing components</ProgressLabel>
  <ProgressValue />
</Progress>
```

## Sizes

Four heights. `xs` (4px) is page chrome: the reading or loading bar pinned under a header. `sm` is the default for a bar sitting in content, `md` and `lg` for a bar that is the point of the panel it is in.

```tsx
<Progress value={58} size="xs" />
<Progress value={58} size="sm" />
<Progress value={58} size="md" />
<Progress value={58} size="lg" />
```

## Tones

The fill takes any of the semantic roles, so a bar can report health as well as distance: flip to `success` when a task lands, `destructive` when a quota is nearly spent. Every tone is a token, so all four themes track it.

```tsx
<Progress value={64} tone="brand" />
<Progress value={100} tone="success" />
<Progress value={48} tone="warning" />
<Progress value={22} tone="destructive" />
<Progress value={76} tone="info" />
<Progress value={40} tone="foreground" />
```

## Vertical

`orientation="vertical"` stands the bar up for the things that fill from the floor: a tank, a level meter, a quota per volume. The fill rises from the bottom, `size` sets the bar’s width instead of its height, and the header parts stack centred above it, so `ProgressLabel` still names the bar. The bar is as tall as the root: give it a height with `className` (it is 128px otherwise), or let its parent size it, a column flex parent included: `h-auto flex-1` takes what the column leaves. The semantics do not change: the root is still a Radix progressbar reading the value, and it carries `data-orientation` as a styling hook. There is no `aria-orientation`, since ARIA does not allow it on a progressbar.

```tsx
<Progress orientation="vertical" size="lg" value={40} tone="success" className="h-40">
  <ProgressLabel>Tank 3</ProgressLabel>
  <ProgressValue />
</Progress>
```

For a tank gauge rather than a line, restyle the track through its `data-slot`: it fills the root’s width and becomes a ringed well, and padding on it insets the fill, which rises as a share of the well’s inner height (no `calc()` to write). Step the radii down concentrically: a 24px well with an 8px inset holds a 16px fill. The fill takes the track’s corners, so without the inset a low level in a round-cornered track is carved by the track’s own outline; the inset keeps it a clean pill at any height. Here each gauge is a flex item of a column, taking whatever height the column leaves it. The fill and the indeterminate sweep work the same at any width.

```tsx
// The gauge flexes into its column: no height on the Progress itself.
<div className="flex h-64 w-24 flex-col items-center gap-2">
  <Progress
    orientation="vertical"
    value={64}
    tone="success"
    aria-label="Unleaded tank"
    className="h-auto w-full flex-1 [&_[data-slot=progress-indicator]]:rounded-lg [&_[data-slot=progress-track]]:w-full [&_[data-slot=progress-track]]:rounded-2xl [&_[data-slot=progress-track]]:bg-[var(--surface,var(--background))] [&_[data-slot=progress-track]]:p-2 [&_[data-slot=progress-track]]:ring-1 [&_[data-slot=progress-track]]:ring-border"
  >
    <ProgressValue />
  </Progress>
  <span className="text-sm font-medium text-foreground">Unleaded</span>
</div>
```

## On a muted ground

The track is a relative tint of the foreground rather than the opaque muted token, so it always sits one step off whatever is behind it: on a card it reads as the muted groove it always was, and on a muted ground (a selected table row, a muted panel) it still shows, where a muted groove would vanish into the row. Nothing to set: it is how the track paints.

```tsx
// The selected row paints bg-muted, as a selected DataTable row does.
<li data-selected className="flex items-center justify-between gap-4 rounded-lg px-3 py-2.5 data-selected:bg-muted">
  <span>Vitals</span>
  <Progress value={60} aria-label="Vitals: 60% done" className="w-24" />
</li>
```

## A running task

Between discrete steps the fill glides rather than snapping, so a jump from 24% to 36% reads as movement. Start the upload to watch it climb and land on `tone="success"`.

```tsx
<Progress value={value} tone={done ? "success" : "brand"}>
  <ProgressLabel>{done ? "Upload complete" : "Uploading assets"}</ProgressLabel>
  <ProgressValue>{(v) => `${Math.round((v / 100) * 24)} of 24 files`}</ProgressValue>
</Progress>
```

## Indeterminate

Pass `value={null}` when there is no percentage to report. The fill becomes a short pill sweeping the track, which says "working" without inventing a number, and the readout falls back to a dash. Radix drops the value from the accessibility tree too, so the bar is announced as indeterminate rather than as zero.

```tsx
<Progress value={null}>
  <ProgressLabel>Connecting to the registry</ProgressLabel>
  <ProgressValue />
</Progress>
```

## Reading progress

`useScrollProgress()` returns how far the document has been scrolled, 0 to 100. Feed it to a `chrome` bar and you get the reading indicator that rides under a navbar: no track, square ends, and `transition="none"` so the fill is welded to the scrollbar. A transition here would trail the page by 300ms and read as lag, not polish. Pass it a ref to follow a scroll container instead (a reader pane, a modal body), which is what the panel below does. The [blog post page](https://www.koalaui.com/marketing/pages/blog-post.md) ships the document version.

```tsx
const progress = useScrollProgress()        // the document
// const progress = useScrollProgress(paneRef) // or a scroll container

<Progress
  value={progress}
  variant="chrome"
  size="xs"
  transition="none"
  aria-label="Reading progress"
  className="sticky top-0 z-30"
/>
```

## FAQ

### Why is the label a part instead of a prop?

So it can be dropped. Every part of a Koala component is omittable and composed rather than switched on with a `showX` flag: `<Progress value={64} />` is the bare bar, and adding `ProgressLabel` or `ProgressValue` as children builds the row above it. That also means you can put anything else in that row - a file count, a cancel button, a tone chip.

### Do I need to announce the value myself?

No. The root is a Radix Progress, so it already carries `role="progressbar"` with the value, min, and max. Give it an `aria-label` (or point `aria-labelledby` at your own heading) when the bar has no visible label. `ProgressValue` is `aria-hidden` on purpose, so the number is not read out twice.

### When should the fill animate, and when should it not?

`transition="smooth"` (the default) glides between discrete steps: an upload going 0 → 33 → 66 looks like progress rather than a series of jumps. `transition="none"` is for a value that changes every frame, like scroll position - a 300ms transition chasing a per-frame value always trails behind and reads as lag. Both honour `prefers-reduced-motion`.

### What does the chrome variant change?

It drops the muted track and squares off the ends. A bar that spans the full viewport has no edges to round and no gutter to sit a track in, so the fill paints straight onto the page. It is the treatment for a reading bar or a top-of-page loading bar; a bar sitting in content should stay on the default.

### Can I use a scale other than 0-100?

Yes. Pass `max` and the value is read against it, so `value={3} max={8}` is a step counter. The default readout still prints a percentage; pass a function to `ProgressValue` to phrase it as "3 of 8" instead.

### How do I make a vertical bar?

Pass `orientation="vertical"` and give the root a height (`className="h-40"`, 128px by default), or let a parent size it: inside a column flex parent, `className="h-auto flex-1"`. The fill rises from the bottom, `size` sets the bar's width, and `ProgressLabel` and `ProgressValue` stack above it. For a wide gauge, widen the track with `[&_[data-slot=progress-track]]:w-full` on the root.

### Why does the track stay visible on a selected table row?

It paints a relative tint of the foreground (4% in the light themes, 6% in the dark ones, the Tabs pill track's ink) instead of the opaque muted token. On a card that lands on the muted groove; on a muted ground it still sits one step darker (or lighter, in dark), so the bar never loses its track.

### Why width instead of a transform?

Scaling a rounded bar squashes its pill caps into ellipses at low values, which is visible on the larger sizes. The fill is a single element inside a fixed-height, overflow-hidden track, so animating width costs nothing measurable and keeps the ends honest.

---

<!-- https://www.koalaui.com/docs/components/promo-card.md -->

# Promo Card

The in-app feature promotion for dashboards: a product eyebrow, a short pitch and one quiet action, beside a framed peek of the feature that runs off the card's edge and dissolves into it.

```tsx
<PromoCard>
  <PromoCardContent>
    <PromoCardEyebrow>
      <BrandMark wordmark={false} />
      Invoicing
    </PromoCardEyebrow>
    <PromoCardTitle>Get paid for exactly what shipped.</PromoCardTitle>
    <PromoCardDescription>
      Turn delivered work into compliant invoices and follow each one until the payment clears.
    </PromoCardDescription>
    <PromoCardActions>
      <Button variant="secondary">Explore</Button>
    </PromoCardActions>
  </PromoCardContent>
  <PromoCardMedia>
    <InvoicePreview />
  </PromoCardMedia>
</PromoCard>
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add promo-card
```

Manual: run `npm install @phosphor-icons/react radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/promo-card/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

Promo Card is composed from named parts, like [Card](https://www.koalaui.com/docs/components/card.md). The `PromoCard` root owns the surface, the density and the open state; `PromoCardContent` is the copy column and `PromoCardMedia` the peek beside it.

```tsx title="analytics-promo.tsx"
import {
  PromoCard,
  PromoCardContent,
  PromoCardEyebrow,
  PromoCardTitle,
  PromoCardDescription,
  PromoCardActions,
  PromoCardMedia,
} from "@/components/ui/promo-card"
import { Button } from "@/components/ui/button"
import { BrandMark } from "@/components/landing/brand-mark"

export function AnalyticsPromo() {
  return (
    <PromoCard>
      <PromoCardContent>
        <PromoCardEyebrow>
          <BrandMark wordmark={false} />
          Analytics
        </PromoCardEyebrow>
        <PromoCardTitle>Your whole workspace on one screen.</PromoCardTitle>
        <PromoCardDescription>
          Revenue, subscriptions and churn side by side, refreshed every hour.
        </PromoCardDescription>
        <PromoCardActions>
          <Button variant="secondary">Open dashboard</Button>
        </PromoCardActions>
      </PromoCardContent>
      <PromoCardMedia>
        <img src="/analytics.webp" alt="" />
      </PromoCardMedia>
    </PromoCard>
  )
}
```

## Variants

`default` is a contour with no fill, so it sits on whatever ground the dashboard has. `muted` and `brand` are deliberate tints that set a promo apart from the data cards around it, and `elevated` fills and lifts for a promo that floats over a busy page.

```tsx
<PromoCard variant="default">…</PromoCard>
<PromoCard variant="muted">…</PromoCard>
<PromoCard variant="brand">…</PromoCard>
<PromoCard variant="elevated">…</PromoCard>
```

## Media

The peek is a tray with a screen inside it. It starts on the eyebrow’s line, runs off the right and bottom edges, and fades out to the right through a mask, so it dissolves into any theme’s ground. Put live components in it (every example above is built from DS parts) or an `<img>`, which fills the screen from the top-left. On a phone the peek stacks under the copy and holds its own aspect ratio. It is a picture of the product, so it is `aria-hidden` and `inert` by default.

```tsx
<PromoCard>
  <PromoCardContent>…</PromoCardContent>
  <PromoCardMedia>
    <img src="/home/showcase/bento-product.webp" alt="" />
  </PromoCardMedia>
</PromoCard>
```

## Without media

Every part can be left out. Without a `PromoCardMedia` the card collapses to one column and drops its resting height; without an eyebrow the pitch still lands on the same baseline. Two text-only promos fit side by side in a dashboard row.

```tsx
<PromoCard variant="muted">
  <PromoCardContent>
    <PromoCardEyebrow>
      <BrandMark wordmark={false} />
      Scheduling
    </PromoCardEyebrow>
    <PromoCardTitle>Let clients book the gaps in your week.</PromoCardTitle>
    <PromoCardDescription>Share one link, and every booking lands on the right calendar.</PromoCardDescription>
    <PromoCardActions><Button variant="secondary">Explore</Button></PromoCardActions>
  </PromoCardContent>
</PromoCard>

<PromoCard variant="muted">
  <PromoCardContent>
    <PromoCardTitle>Chase late invoices on autopilot.</PromoCardTitle>
    <PromoCardDescription>Pick a trigger, chain the follow-ups, and let the workflow run until it's paid.</PromoCardDescription>
    <PromoCardActions><Button variant="secondary">Explore</Button></PromoCardActions>
  </PromoCardContent>
</PromoCard>
```

## Dismissible

Add a `PromoCardClose` and the card can be dismissed: it fades out with a slight settle, then leaves the tree. The root works uncontrolled out of the box; pass `open` and `onOpenChange` to keep the choice, which is where a dashboard stores “don’t show this again”.

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

<PromoCard open={open} onOpenChange={setOpen} variant="muted">
  <PromoCardClose />
  <PromoCardContent>…</PromoCardContent>
  <PromoCardMedia>…</PromoCardMedia>
</PromoCard>
```

## Density

Density is Koala’s cross-cutting spacing axis (see [Density](https://www.koalaui.com/docs/foundations/density.md)). For Promo Card it tunes the padding, the resting height and the type step. `compact` is the app default; `comfortable` gives an onboarding or empty dashboard more room. The peek re-aligns to the copy at both.

```tsx
<DensityProvider density="compact">
  <PromoCard>…</PromoCard>
</DensityProvider>

<DensityProvider density="comfortable">
  <PromoCard>…</PromoCard>
</DensityProvider>
```

## API reference

`PromoCard` forwards all `div` props and adds `variant` (`default | muted | brand | elevated`), `density` (`compact | comfortable`), `open`, `defaultOpen` and `onOpenChange`. `PromoCardContent`, `PromoCardEyebrow`, `PromoCardTitle` and `PromoCardMedia` forward `div` props. The eyebrow leads with your app’s mark: in Koala that is `<BrandMark wordmark={false} />`; for another product, put its logo `<img>` in `PromoCardIcon`, which forwards `span` props and sizes the image like the BrandMark tile. `PromoCardDescription` forwards `p` props. `PromoCardActions` adds `size` (default `sm`), imposed on the buttons inside. `PromoCardClose` takes Button props and an `aria-label` (default “Dismiss”). Every part accepts `className`, merged last.

## FAQ

### Why does the preview run off the edge instead of sitting inside the card?

Because the crop is the message. A framed screen cut by the card's right and bottom edges reads as a window onto a bigger product; shrinking the whole feature to fit would make it read as a thumbnail. The right edge fades through a CSS mask rather than a painted gradient, so it dissolves into any theme's ground, including the tinted variants.

### Should the preview be a screenshot or live components?

Either works. Live DS parts re-theme with the dashboard, stay sharp at any zoom and cost no image weight, so they're the better default for UI you already ship. Use an image when the feature is visual (a map, a chart you don't render in the DS) or when it isn't built yet. An image fills the screen from its top-left corner.

### Is the preview announced to screen readers?

No. PromoCardMedia is aria-hidden and inert by default, since it's a picture of the product, and nothing inside it can take focus. The title, description and action carry the message. If the preview holds information that isn't in the copy, pass aria-hidden={false} inert={false}.

### Why does the peek move under the copy in a half-width column?

The layout follows the card's own width, not the viewport's. PromoCard is a size container: below 42rem it stacks the peek under the copy, above it puts them side by side. The same promo works in a full dashboard row, a half column and a narrow rail without breakpoints. One consequence: a size container can't take its width from its content, so as a flex item with no width it collapses. Put it in a grid cell or block flow, or give it flex-1 or a width.

### How do I remember that someone dismissed a promo?

Control the card: pass open and onOpenChange, and persist the false you receive (a user setting, a cookie, localStorage). The card plays its exit before it unmounts either way, so the dismissal never pops.

### Why is the action a small secondary button?

A promo points at a feature; it isn't the page's main task. PromoCardActions imposes the sm size, and a secondary button keeps the promo from competing with the dashboard's primary action. Pass size to PromoCardActions or to the Button if you need more weight.

---

<!-- https://www.koalaui.com/docs/components/prose.md -->

# Prose

The reading type. Wrap a document, CMS rich text, rendered Markdown or plain JSX, and its bare headings, lists, quotes, code and tables are typeset on Koala's tokens, with one size prop.

```tsx
<Prose>
  <h2>Constraints first</h2>
  <p>
    We started with constraints instead of components: four themes, one spacing
    scale and a fixed set of <strong>color roles</strong>. Read the{" "}
    <a href="/docs/foundations/colors">color foundations</a> for the full map.
  </p>
  <ul>
    <li>Components never hard-code a value, they read tokens.</li>
    <li>A theme change is one file, not a hundred.</li>
  </ul>
  <blockquote>A component is only shared if it is easier to use than to rebuild.</blockquote>
  <p>Constraints feel limiting for about a week. After that they are the reason a new component takes an afternoon.</p>
</Prose>
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add prose
```

Manual: run `npm install radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/prose/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

```tsx title="usage.tsx"
import { Prose } from "@/components/ui/prose"

export function Article({ html }: { html: string }) {
  return <Prose size="lg" dangerouslySetInnerHTML={{ __html: html }} />
}
```

## Sizes

The size picks the type and the rhythm together. `sm` is the 14px body of the product UI (a comment, a task description, what a RichTextEditor wrote); `md` is docs and release notes; `lg` is long-form reading at 17px, for an article at a ~42rem measure.

```tsx
<Prose size="sm">
  <h2>Release notes</h2>
  <p>Unified spacing across buttons, inputs and selects, so forms line up in dense dashboards.</p>
  <h3>Themes</h3>
  <p>The Moonlight theme gains contrast, and the branded focus ring follows it.</p>
</Prose>
```

```tsx
<Prose size="md">
  <h2>Release notes</h2>
  <p>Unified spacing across buttons, inputs and selects, so forms line up in dense dashboards.</p>
  <h3>Themes</h3>
  <p>The Moonlight theme gains contrast, and the branded focus ring follows it.</p>
</Prose>
```

```tsx
<Prose size="lg">
  <h2>Release notes</h2>
  <p>Unified spacing across buttons, inputs and selects, so forms line up in dense dashboards.</p>
  <h3>Themes</h3>
  <p>The Moonlight theme gains contrast, and the branded focus ring follows it.</p>
</Prose>
```

## Rich text from a CMS

A CMS, a Markdown renderer or a Tiptap export hands you a string of bare HTML. Set it on Prose and it is typeset as it is: no class to add to the content.

```tsx
const html = `<h2>Koala UI v11</h2><p>A major update focused on <strong>design system consistency</strong> …</p>…`

<Prose dangerouslySetInnerHTML={{ __html: html }} />
```

## Elements

Ordered lists carry tabular markers, inline `code` keeps the global chip, a `pre` is a muted block that scrolls on its own, a table scrolls inside the column instead of the page, and a picture gets the corner radius and the image outline. Media take a wider step than copy, so they read as breaks.

```tsx
<Prose>
  <h3>Install</h3>
  <ol>
    <li>Add the package.</li>
    <li>Import <code>globals.css</code> once, at the root.</li>
  </ol>
  <pre><code>npx koalaui-cli@latest add prose</code></pre>
  <figure>
    <img src="…" alt="A laptop on a desk, a code editor open" />
    <figcaption>The token map is the contract.</figcaption>
  </figure>
  <table>
    <thead><tr><th>Size</th><th>Body</th><th>Block step</th></tr></thead>
    <tbody>
      <tr><td>sm</td><td>14 / 24</td><td>16px</td></tr>
      <tr><td>md</td><td>16 / 28</td><td>20px</td></tr>
      <tr><td>lg</td><td>17 / 28</td><td>24px</td></tr>
    </tbody>
  </table>
  <hr />
  <h4>Still stuck?</h4>
  <p>Every size shares these rules; only the scale and the spacing change.</p>
</Prose>
```

## Components inside

Prose styles bare elements. An anchor or image that carries a class is a component, so it keeps its own look: a `Link` or a `Button` dropped into the copy is never underlined or restyled.

```tsx
<Prose>
  <p>
    A bare <a href="#">anchor</a> wears the prose link; a{" "}
    <Link variant="prose" href="#">Link</Link> is the same treatment, as a component.
  </p>
  <p>
    <Button variant="secondary" size="sm">View template</Button>
  </p>
</Prose>
```

## As child

Pass `asChild` to put the styling on your own element, an `article` or a `section`, instead of a wrapping `div`.

```tsx title="article.tsx"
<Prose asChild size="lg">
  <article>
    <h2>Tokens over values</h2>
    <p>A card does not know it is twelve pixels of radius; it knows it uses the surface radius.</p>
  </article>
</Prose>
```

## FAQ

### Do I need @tailwindcss/typography?

No. Prose is one tv recipe on Koala's own tokens: the body is the `--body` reading ink, headings and bold lift to `--foreground`, list markers step down to `--muted-foreground`, links turn `--link` on hover. It re-themes across light, cream, dark and moonlight with no plugin.

### Why does the copy start flush with the top of the wrapper?

Rhythm is space between top-level blocks only, never before the first one or after the last. So Prose adds no gap to whatever it sits in, and you space it from its neighbours like any other block (`mt-8`).

### Which size should I use?

Match the surface. `sm` inside product UI, where the body around it is 14px (a comment thread, a panel, the read-only view of a RichTextEditor). `md` for documentation and release notes. `lg` for an article someone sits down to read, at a measure around 42rem.

### How do I style one element differently?

Give it a class, or pass a descendant utility on Prose itself, for example `className="[&_h2]:text-brand"`. It is merged last, so it wins over the recipe.

### Why is my Link or Button not underlined inside Prose?

By design. Prose only styles a bare `<a>` (no class); anything with a class is a component and keeps its own look. `Link variant="prose"` is the same treatment as the bare anchor, as a component, for when you write the copy in JSX.

---

<!-- https://www.koalaui.com/docs/components/qr-code.md -->

# QR Code

A QR code rendered as crisp, dependency-free SVG. The matrix is generated in-house, byte mode, ECC levels L through H, with automatic version and mask selection, and paints in the current text color.

```tsx
<QRCode value="https://koalaui.com" size={200} />
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add qr-code
```

Manual: run `npm install radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/qr-code/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

```tsx title="usage.tsx"
import { QRCode } from "@/components/ui/qr-code"

export function Example() {
  return <QRCode value="https://koalaui.com" />
}
```

## Error correction

`level` sets how much of the code can be damaged or covered while still scanning. Higher levels add redundancy, so the same data needs a denser grid. Use `H` when a logo sits on top or the code is printed small; `M` (the default) is right for screens.

```tsx
<QRCode value="https://koalaui.com" level="L" />
<QRCode value="https://koalaui.com" level="M" /> {/* default */}
<QRCode value="https://koalaui.com" level="Q" />
<QRCode value="https://koalaui.com" level="H" />
```

## Sizing

`size` sets the rendered width and height in pixels. The SVG is resolution-independent, so it stays sharp at any size; drive it per breakpoint with `className` if you need a responsive code.

```tsx
<QRCode value="https://koalaui.com" size={96} />
<QRCode value="https://koalaui.com" size={144} />
<QRCode value="https://koalaui.com" size={192} />
```

## Quiet zone

`margin` is the light border around the code, measured in modules. The spec asks for at least **4** for reliable scanning; drop it lower only when the surrounding surface already supplies light padding (as the panel below does).

```tsx
{/* full 4-module quiet zone, baked in */}
<QRCode value="https://koalaui.com" margin={4} />

{/* tighter, because the panel adds its own padding */}
<div className="rounded-xl border border-border bg-accent p-6">
  <QRCode value="https://koalaui.com" margin={1} className="p-3" />
</div>
```

## Color & theming

Modules paint in `currentColor` over the component's background, so a code re-themes by default. You can recolor it with any text token, but keep the contrast high: scanners need the modules clearly darker (or clearly lighter) than the quiet zone. The brand-tinted example below still reads because `text-brand` stays well clear of the card background.

```tsx
{/* default: foreground modules on the page background */}
<QRCode value="https://koalaui.com" />

{/* brand-tinted modules on a card surface */}
<QRCode value="https://koalaui.com" className="bg-card text-brand p-3 shadow-xs" />
```

## Module shape

`moduleRadius` rounds each module, as a fraction of its size: `0` (the default) for sharp squares, `0.3` for a soft look, up to `0.5` for full dots. Keep it modest, heavy rounding eats into the modules and can hurt scanning.

```tsx
<QRCode value="https://koalaui.com" moduleRadius={0} /> {/* default */}
<QRCode value="https://koalaui.com" moduleRadius={0.3} />
<QRCode value="https://koalaui.com" moduleRadius={0.5} />
```

## In a dialog

A QR code pairs naturally with a verification flow. See the [two-factor (2FA) Dialog](https://www.koalaui.com/docs/components/dialog.md#two-factor-2fa) for a full example: a `QRCode` on a nested panel above an [OTP Input](https://www.koalaui.com/docs/components/otp-input.md).

## API reference

| Prop | Type | Default |
| --- | --- | --- |
| value | string | required |
| level | "L" \| "M" \| "Q" \| "H" | "M" |
| size | number | 160 |
| margin | number | 4 |
| moduleRadius | number | 0 |
| title | string | "QR code" |
| className | string | — |

All other native `svg` props are forwarded to the root element.

## FAQ

### Does this pull in a QR library?

No. The encoder is hand-rolled and dependency-free, matching the rest of Koala's hard primitives like Chart, Calendar, and the Command palette. It supports byte mode (UTF-8), which covers URLs, plain text, and otpauth:// URIs, and selects the smallest version and the lowest-penalty mask automatically.

### Will it scan in dark mode?

Yes. Modules use the current text color over the component's own background, so in every theme the code keeps a high-contrast light-vs-dark relationship. Modern scanners read inverted (light-on-dark) codes fine. For print or when you set a custom color, keep the modules clearly distinct from the quiet zone.

### How much data can it hold?

Up to QR version 40. At the default M level that is roughly 2300 bytes; level L holds more, level H less. The component throws if the value is too long to encode, so cap or shorten very large payloads (a short URL almost always fits in a small, dense-free code).

### Can I put a logo in the middle?

Overlay one yourself with an absolutely-positioned element centered over the code, and bump level to H so the redundancy covers the occluded modules. Keep the logo under about 25% of the area so enough of the matrix survives to scan.

---

<!-- https://www.koalaui.com/docs/components/radio-group.md -->

# Radio Group

A set of mutually exclusive options where exactly one can be selected, built on Radix RadioGroup. Sizes line up pixel-for-pixel with Checkbox, so radios and checkboxes sit flush in the same form.

```tsx
<RadioGroup defaultValue="Pro" className="w-56">
  {["Starter", "Pro", "Enterprise"].map((plan) => (
    <label key={plan} htmlFor={plan} className="flex cursor-pointer items-center gap-2.5 text-sm font-medium">
      <RadioGroupItem id={plan} value={plan} />
      {plan}
    </label>
  ))}
</RadioGroup>
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add radio-group
```

Manual: run `npm install radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/radio-group/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

```tsx title="usage.tsx"
import { RadioGroup, RadioGroupItem } from "@/components/ui/radio-group"

export function Example() {
  return (
    <RadioGroup defaultValue="pro">
      <label htmlFor="pro" className="flex items-center gap-2.5">
        <RadioGroupItem id="pro" value="pro" />
        Pro
      </label>
    </RadioGroup>
  )
}
```

## Sizes

`sm` (16px) matches the dense table checkbox; `md` (20px) is the default for forms. Set `size` on the group and every item inherits it through context.

```tsx
<RadioGroup size="sm" defaultValue="b">
  <RadioGroupItem value="a" />
  <RadioGroupItem value="b" />
</RadioGroup>

<RadioGroup size="md" defaultValue="b">
  <RadioGroupItem value="a" />
  <RadioGroupItem value="b" />
</RadioGroup>
```

## States

Disable a single `RadioGroupItem` and roving focus skips it, or disable the whole `RadioGroup` at once.

```tsx
<RadioGroup defaultValue="on">
  <RadioGroupItem value="on" />
  <RadioGroupItem value="off" disabled />
</RadioGroup>

<RadioGroup defaultValue="x" disabled>
  <RadioGroupItem value="x" />
  <RadioGroupItem value="y" />
</RadioGroup>
```

## With descriptions

Give each option a line of supporting text with `RadioCardDescription`. The whole card is the radio, so the entire surface is the hit target: selected, it borders brand, lifts the accent halo and pops its icon, exactly like the plan picker below.

```tsx
import { RadioGroup, RadioCard, RadioCardTitle, RadioCardDescription } from "@/components/ui/radio-group"
import { FieldGroup, FieldGroupLabel } from "@/components/ui/field"
import { Package, Truck, AirplaneTilt } from "@phosphor-icons/react"

const SHIPPING = [
  { value: "standard", icon: <Package />, title: "Standard", hint: "4–6 business days. Free." },
  { value: "express", icon: <Truck />, title: "Express", hint: "2–3 business days. $9." },
  { value: "overnight", icon: <AirplaneTilt />, title: "Overnight", hint: "Next business day. $24." },
]

<FieldGroup className="max-w-sm">
  <FieldGroupLabel>Delivery speed</FieldGroupLabel>
  <RadioGroup defaultValue="express" className="gap-3">
    {SHIPPING.map(({ value, icon, title, hint }) => (
      <RadioCard key={value} value={value} icon={icon}>
        <RadioCardTitle>{title}</RadioCardTitle>
        <RadioCardDescription>{hint}</RadioCardDescription>
      </RadioCard>
    ))}
  </RadioGroup>
</FieldGroup>
```

## Cards

Reach for `RadioCard` when each option deserves an icon and a line of supporting text, the affordance behind a plan, theme or payment-method picker. The card *is* the radio, so keyboard and focus come for free; selected, it borders `brand` and lifts the accent halo while the flooded dot tweens in.

```tsx
import { RadioGroup, RadioCard, RadioCardTitle, RadioCardDescription } from "@/components/ui/radio-group"
import { FieldGroup, FieldGroupLabel } from "@/components/ui/field"
import { Rocket, Crown, Buildings } from "@phosphor-icons/react"

const PLANS = [
  { value: "starter", icon: <Rocket />, title: "Starter", hint: "$0 / month. For side projects and prototypes." },
  { value: "pro", icon: <Crown />, title: "Pro", hint: "$59 / month. For growing teams that ship." },
  { value: "enterprise", icon: <Buildings />, title: "Enterprise", hint: "$99 / month. SSO, audit logs and support." },
]

<FieldGroup className="max-w-sm">
  <FieldGroupLabel>Plan</FieldGroupLabel>
  <RadioGroup defaultValue="pro" className="gap-3">
    {PLANS.map(({ value, icon, title, hint }) => (
      <RadioCard key={value} value={value} icon={icon}>
        <RadioCardTitle>{title}</RadioCardTitle>
        <RadioCardDescription>{hint}</RadioCardDescription>
      </RadioCard>
    ))}
  </RadioGroup>
</FieldGroup>
```

## Card sizes

`md` (the default, above) suits a title plus a line of description. Drop a `RadioCard` to `size="sm"` when the option is a single line, a title on its own or an icon and text, so it doesn't float in dead space. The padding, control and radius all tighten together, the row centers vertically, and the title drops to medium; the control still lines up with the standalone radio.

```tsx
import { RadioGroup, RadioCard, RadioCardTitle } from "@/components/ui/radio-group"
import { FieldGroup, FieldGroupLabel } from "@/components/ui/field"
import { User, Buildings, CreditCard, Wallet } from "@phosphor-icons/react"

{/* One-line options: title-only, in a two-up grid. sm centers + sets the title to medium. */}
<FieldGroup>
  <FieldGroupLabel>Billing type</FieldGroupLabel>
  <RadioGroup defaultValue="individual" className="grid grid-cols-2 gap-3">
    <RadioCard value="individual" size="sm" icon={<User />}>
      <RadioCardTitle>Individual</RadioCardTitle>
    </RadioCard>
    <RadioCard value="company" size="sm" icon={<Buildings />}>
      <RadioCardTitle>Company</RadioCardTitle>
    </RadioCard>
  </RadioGroup>
</FieldGroup>

{/* Icon + text, stacked. */}
<FieldGroup>
  <FieldGroupLabel>Payment method</FieldGroupLabel>
  <RadioGroup defaultValue="card" className="gap-2.5">
    <RadioCard value="card" size="sm" icon={<CreditCard />}>
      <RadioCardTitle>Credit or debit card</RadioCardTitle>
    </RadioCard>
    <RadioCard value="paypal" size="sm" icon={<Wallet />}>
      <RadioCardTitle>PayPal balance</RadioCardTitle>
    </RadioCard>
  </RadioGroup>
</FieldGroup>
```

## Swatches

`RadioSwatch` dresses a radio as a colour chip, the picker on a product page. The chip is filled with its `color` (any CSS colour: a product's colour is data, not a theme role), keeps a hairline edge so a pale colour never dissolves into the page, and takes a fine ink ring, cut off the chip by a gap in the ground's own colour, when chosen. The ring is ink rather than brand on purpose: the chip's colour is the content, so a brand ring would add a colour the product doesn't have. Keyboard focus is a separate brand outline outside it, so focus and selection never look alike. It has no visible text, so `label` is required: it is the name a screen reader announces. Show the chosen name in the legend for everyone else, and lay the group out as a row.

```tsx
import { RadioGroup, RadioSwatch } from "@/components/ui/radio-group"
import { FieldGroup, FieldGroupLabel } from "@/components/ui/field"

const colorways = [
  { value: "sand", label: "Sand", color: "#cbbba0" },
  { value: "sage", label: "Sage", color: "#9dae9a" },
  { value: "navy", label: "Navy", color: "#1f2a44" },
  { value: "chalk", label: "Chalk", color: "#ecebe6" },
  { value: "clay", label: "Clay", color: "#b5654a" },
]

const [value, setValue] = useState("sage")
const name = colorways.find((c) => c.value === value)?.label

<FieldGroup className="w-full max-w-xs">
  <FieldGroupLabel>
    Color <span className="ml-1 font-normal text-muted-foreground">{name}</span>
  </FieldGroupLabel>
  <RadioGroup value={value} onValueChange={setValue} className="flex flex-wrap gap-3">
    {colorways.map((c) => (
      <RadioSwatch key={c.value} value={c.value} label={c.label} color={c.color} />
    ))}
  </RadioGroup>
</FieldGroup>
```

## Swatch sizes

Swatches follow the group's `size`: `sm` is 24px for a product card or a filter, `md` is 32px for a product page. Either way the hit target grows to 40px (44 on touch), so keep at least an 8px gap between chips. A disabled swatch fades and roving focus skips it; say why in its label ("Clay, sold out").

```tsx
<RadioGroup size="sm" defaultValue="navy" aria-label="Color" className="flex gap-3">
  <RadioSwatch value="navy" label="Navy" color="#1f2a44" />
  <RadioSwatch value="clay" label="Clay, sold out" color="#b5654a" disabled />
</RadioGroup>

<RadioGroup size="md" defaultValue="navy" aria-label="Color" className="flex gap-3">
  <RadioSwatch value="navy" label="Navy" color="#1f2a44" />
  <RadioSwatch value="clay" label="Clay, sold out" color="#b5654a" disabled />
</RadioGroup>
```

## Controlled

Pass `value` and `onValueChange` to own the selection. The group lays out horizontally here with a `grid-flow-col` override on `className`.

```tsx
const [value, setValue] = useState("comfortable")

<FieldGroup className="w-auto text-center">
  <FieldGroupLabel className="justify-center">Density</FieldGroupLabel>
  <RadioGroup value={value} onValueChange={setValue} className="grid-flow-col gap-5">
    {["comfortable", "compact"].map((option) => (
      <label key={option} htmlFor={`d-${option}`} className="flex cursor-pointer items-center gap-2.5 text-sm font-medium capitalize">
        <RadioGroupItem id={`d-${option}`} value={option} />
        {option}
      </label>
    ))}
  </RadioGroup>
</FieldGroup>
```

## FAQ

### When should I use a RadioGroup instead of a Select?

Use RadioGroup for a single choice from a small, visible set so every option is in view. Reach for a Select once the options grow long enough to want a dropdown.

### How do I set the size, and why does it match Checkbox?

Set `size` on the RadioGroup (`sm` is 16px, `md` is 20px) and each RadioGroupItem inherits it through context. The sizes mirror Checkbox exactly so radios and checkboxes line up pixel-for-pixel in the same form.

### RadioGroupItem renders only a circle. How do I give it a label and a bigger hit target?

Pair each item with a `<label htmlFor>` matching the item's `id`. The label supplies the accessible name and extends the clickable area, since the item itself renders only the control.

### How do the keyboard and disabled states behave?

It is built on Radix RadioGroup, so arrow keys move roving focus and select. Disable a single RadioGroupItem and roving focus skips it, or set `disabled` on the whole RadioGroup at once.

### How do I make the whole option card highlight when selected, without JavaScript?

Reach for `RadioCard` (same import): it dresses a RadioGroupItem as a full selectable card with an optional `icon`, plus `RadioCardTitle` and `RadioCardDescription`. The card itself is the radio, so the whole surface is the hit target and it borders brand and lifts the accent halo when selected, no JavaScript. See the Cards example above.

### How do I build a colour picker for a product?

Use `RadioSwatch` inside the RadioGroup: pass each option's colour as `color` and its name as `label` (required, since the chip has no visible text). Lay the group out as a row with `className="flex flex-wrap gap-3"`, and put the chosen colour's name in the FieldGroup legend. See the Swatches example above.

### Is RadioGroup controlled or uncontrolled?

Both. Use `defaultValue` to let it manage its own selection, or pass `value` with `onValueChange` to own the state. These props forward straight to Radix.

---

<!-- https://www.koalaui.com/docs/components/rating.md -->

# Rating

A 1-to-N star rating built on Radix RadioGroup: roving focus, arrow keys and hover preview for free. Active stars render solid, the one place the DS opts out of its outline-only rule, and half stars read cleanly.

```tsx
const [value, setValue] = useState(4)

<Rating value={value} onValueChange={setValue} size="lg" aria-label="Rate your experience" />
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add rating
```

Manual: run `npm install radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/rating/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

```tsx title="usage.tsx"
import { Rating } from "@/components/ui/rating"

export function Example() {
  const [value, setValue] = useState(4)
  return <Rating value={value} onValueChange={setValue} aria-label="Rate your experience" />
}
```

## Sizes

`sm` (16px), `md` (20px), and `lg` (28px) line up with the rest of the control scale.

```tsx
<Rating size="sm" defaultValue={3} />
<Rating size="md" defaultValue={3} />
<Rating size="lg" defaultValue={3} />
```

## Tones

`tone` recolors the active glyph, independent of the icon: `amber` (default) is the vivid review-gold for stars, and `red` is the love-red that suits a `Heart`. Both ride dedicated rating tokens, brighter than the `warning` status hue.

```tsx
import { Heart } from "@phosphor-icons/react"

<Rating tone="amber" defaultValue={4} size="lg" />
<Rating tone="red" icon={Heart} defaultValue={4} size="lg" />
```

## Variants

`filled` (default) is the classic solid-star look: the active glyph renders at Phosphor's `fill` weight, the rest stay outline. `outline` keeps the DS rule, drawing the active star as a tinted outline instead.

```tsx
<Rating variant="outline" defaultValue={4} size="lg" />
<Rating variant="filled" defaultValue={4} size="lg" />
```

## Read-only & fractional

`readOnly` renders a static display and accepts fractional values: an average like `4.3` shows a partly-filled star via the clip overlay.

```tsx
<Rating value={5} readOnly />
<Rating value={4.3} readOnly />
<Rating value={2.5} readOnly />
```

## Custom icon & length

Swap the star for any Phosphor icon with `icon`, and set the scale length with `max`. Recolor the fill with `tone`: `amber` (default review-gold) or `red`, which suits a heart. The icon follows the active variant: solid by default, outline with `variant="outline"`.

```tsx
import { Heart } from "@phosphor-icons/react"

<Rating max={7} icon={Heart} tone="red" size="lg" defaultValue={3} aria-label="Rate with hearts" />
```

## Disabled

```tsx
<Rating defaultValue={3} disabled />
```

## FAQ

### How do I show a fractional average like 4.3 stars?

Set `readOnly` and pass the fractional `value`. Read-only mode drops the RadioGroup for a static display and clips a colored glyph over an empty one, so a partly-filled star reads cleanly. Interactive ratings only commit whole numbers.

### Why does Rating use a solid star when the DS is outline-only?

The default `filled` variant renders the active glyph at Phosphor's `fill` weight, the one documented place the DS opts out of icons-always-outline, because a filled star is the universal affordance. Use `variant="outline"` to keep the tinted-outline look.

### What keyboard and accessibility behavior do I get for free?

Interactive ratings ride on Radix RadioGroup, so you get roving focus, arrow-key increment and decrement, and a single selected value. Pass `aria-label` to name the group; it also builds each star's label like "Rate 3 of 5".

### How do I change the number of stars or the icon?

Set `max` for the scale length (default 5) and pass any Phosphor icon to `icon` (for example Heart). Recolor the fill with `tone`: `amber` (default review-gold) or `red`, which suits a heart. The custom icon follows the active variant: solid by default, outline with `variant="outline"`.

### Is Rating controlled or uncontrolled, and can I submit it in a form?

Both: use `defaultValue` for uncontrolled or `value` with `onValueChange` to control it. Pass a `name` and it maps to the underlying RadioGroup form field.

### What are the available sizes?

`sm` (16px), `md` (20px, default), and `lg` (28px), which line up with the rest of the control scale.

---

<!-- https://www.koalaui.com/docs/components/resizable.md -->

# Resizable

Split a surface into panels the user can drag to resize. No Radix primitive ships this, so the handle is hand-rolled: it carries role=separator, is arrow-key operable, and reports through aria-valuenow.

```tsx
<ResizablePanelGroup direction="horizontal" className="h-72 w-full rounded-lg border">
  <ResizablePanel defaultSize={22} minSize={14}>
    <div className="grid h-full place-items-center gap-1.5 p-4 text-sm font-medium text-muted-foreground">
      <SidebarSimple className="size-5" />
      Sidebar
    </div>
  </ResizablePanel>
  <ResizableHandle withHandle />
  <ResizablePanel defaultSize={52}>
    <div className="grid h-full place-items-center gap-1.5 p-4 text-sm font-medium text-muted-foreground">
      <FileText className="size-5" />
      Editor
    </div>
  </ResizablePanel>
  <ResizableHandle withHandle />
  <ResizablePanel defaultSize={26} minSize={16}>
    <div className="grid h-full place-items-center gap-1.5 p-4 text-sm font-medium text-muted-foreground">
      <Eye className="size-5" />
      Preview
    </div>
  </ResizablePanel>
</ResizablePanelGroup>
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add resizable
```

Manual: run `npm install radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/resizable/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

```tsx title="usage.tsx"
import {
  ResizablePanelGroup,
  ResizablePanel,
  ResizableHandle,
} from "@/components/ui/resizable"

export function Example() {
  return (
    <ResizablePanelGroup direction="horizontal" className="h-64 rounded-lg border">
      <ResizablePanel defaultSize={60}>One</ResizablePanel>
      <ResizableHandle withHandle />
      <ResizablePanel defaultSize={40}>Two</ResizablePanel>
    </ResizablePanelGroup>
  )
}
```

## Horizontal

The default direction lays panels side-by-side. Give each panel a `defaultSize` weight (conventionally summing to 100), then drag the divider to redistribute the space between the two panels it sits between.

```tsx
<ResizablePanelGroup direction="horizontal" className="h-60 w-full rounded-lg border">
  <ResizablePanel defaultSize={50}>
    <div className="grid h-full place-items-center p-4 text-sm font-medium text-muted-foreground">Left</div>
  </ResizablePanel>
  <ResizableHandle withHandle />
  <ResizablePanel defaultSize={50}>
    <div className="grid h-full place-items-center p-4 text-sm font-medium text-muted-foreground">Right</div>
  </ResizablePanel>
</ResizablePanelGroup>
```

## Vertical

Set `direction="vertical"` to stack panels and drag a horizontal divider. The handle, cursor, and keyboard axis all flip automatically.

```tsx
<ResizablePanelGroup direction="vertical" className="h-80 w-full rounded-lg border">
  <ResizablePanel defaultSize={60}>
    <div className="grid h-full place-items-center gap-1.5 p-4 text-sm font-medium text-muted-foreground">
      <ChartBar className="size-5" />
      Chart
    </div>
  </ResizablePanel>
  <ResizableHandle withHandle />
  <ResizablePanel defaultSize={40} minSize={20}>
    <div className="grid h-full place-items-center gap-1.5 p-4 text-sm font-medium text-muted-foreground">
      <Table className="size-5" />
      Table
    </div>
  </ResizablePanel>
</ResizablePanelGroup>
```

## With handle

Add `withHandle` to render a minimal, fully-rounded grip pill: a clear "drag me" affordance for wide gutters. Without it the divider is a hairline that highlights on hover and focus.

```tsx
<ResizablePanelGroup direction="horizontal" className="h-56 w-full rounded-lg border">
  <ResizablePanel defaultSize={50}>
    <div className="grid h-full place-items-center p-4 text-sm font-medium text-muted-foreground">Grip</div>
  </ResizablePanel>
  <ResizableHandle withHandle />
  <ResizablePanel defaultSize={50}>
    <div className="grid h-full place-items-center p-4 text-sm font-medium text-muted-foreground">Hairline</div>
  </ResizablePanel>
  <ResizableHandle />
  <ResizablePanel defaultSize={50}>
    <div className="grid h-full place-items-center p-4 text-sm font-medium text-muted-foreground">divider</div>
  </ResizablePanel>
</ResizablePanelGroup>
```

## Custom handle

Pass `children` to a `ResizableHandle` to swap the visual entirely (an icon nub, a brand chip, your own shape) while keeping all the drag, keyboard, and ARIA behavior. The two examples below show a dotted chip and a bold brand pill.

```tsx
<ResizablePanelGroup direction="horizontal" className="h-56 w-full rounded-lg border">
  <ResizablePanel defaultSize={34}>
    <div className="grid h-full place-items-center p-4 text-sm font-medium text-muted-foreground">Dotted chip</div>
  </ResizablePanel>
  <ResizableHandle>
    <span className="z-10 flex h-7 w-4 items-center justify-center rounded-full border border-border bg-card text-muted-foreground shadow-xs transition-colors duration-fast ease-out group-hover/handle:border-brand group-hover/handle:text-foreground [&_svg]:size-3">
      <DotsSixVertical />
    </span>
  </ResizableHandle>
  <ResizablePanel defaultSize={32}>
    <div className="grid h-full place-items-center p-4 text-sm font-medium text-muted-foreground">Brand pill</div>
  </ResizablePanel>
  <ResizableHandle>
    <span className="z-10 h-10 w-1.5 rounded-full bg-brand/40 transition-colors duration-fast ease-out group-hover/handle:bg-brand group-data-[dragging=true]/handle:bg-brand" />
  </ResizableHandle>
  <ResizablePanel defaultSize={34}>
    <div className="grid h-full place-items-center p-4 text-sm font-medium text-muted-foreground">Done</div>
  </ResizablePanel>
</ResizablePanelGroup>
```

## Min & max sizes

Clamp how far a panel can be dragged with `minSize` and `maxSize`. A number (or `"30%"`) is a proportional weight; a pixel string like `"240px"` is a hard bound pinned as a real CSS min/max-width, so it holds at any group size: drag it, then shrink your window and the sidebar below keeps its `240px–360px` range instead of scaling away.

```tsx
<ResizablePanelGroup direction="horizontal" className="h-56 w-full rounded-lg border">
  <ResizablePanel defaultSize={28} minSize="240px" maxSize="360px">
    <div className="grid h-full place-items-center p-4 text-sm font-medium text-muted-foreground">240px–360px</div>
  </ResizablePanel>
  <ResizableHandle withHandle />
  <ResizablePanel defaultSize={72} minSize="320px">
    <div className="grid h-full place-items-center p-4 text-sm font-medium text-muted-foreground">min 320px</div>
  </ResizablePanel>
</ResizablePanelGroup>
```

## Collapsible

Mark a panel `collapsible` and it snaps shut once dragged past half its `minSize`, settling at `collapsedSize` (default 0): the pattern for a sidebar that tucks away. Drag back out to restore it.

```tsx
<ResizablePanelGroup direction="horizontal" className="h-60 w-full rounded-lg border">
  <ResizablePanel defaultSize={24} minSize={16} collapsible collapsedSize={0}>
    <div className="grid h-full place-items-center gap-1.5 p-4 text-sm font-medium text-muted-foreground">
      <SidebarSimple className="size-5" />
      Collapsible
    </div>
  </ResizablePanel>
  <ResizableHandle withHandle />
  <ResizablePanel defaultSize={76}>
    <div className="grid h-full place-items-center gap-1.5 p-4 text-sm font-medium text-muted-foreground">
      <FileText className="size-5" />
      Content
    </div>
  </ResizablePanel>
</ResizablePanelGroup>
```

## Nested dashboard

Groups nest: put a vertical `ResizablePanelGroup` inside a panel of a horizontal one to build a real dashboard split. Each group resizes independently.

```tsx
<ResizablePanelGroup direction="horizontal" className="h-80 w-full rounded-lg border">
  <ResizablePanel defaultSize={28} minSize={18}>
    <div className="grid h-full place-items-center gap-1.5 p-4 text-sm font-medium text-muted-foreground">
      <SidebarSimple className="size-5" />
      Navigation
    </div>
  </ResizablePanel>
  <ResizableHandle withHandle />
  <ResizablePanel defaultSize={72}>
    <ResizablePanelGroup direction="vertical">
      <ResizablePanel defaultSize={65}>
        <div className="grid h-full place-items-center gap-1.5 p-4 text-sm font-medium text-muted-foreground">
          <ChartBar className="size-5" />
          Overview
        </div>
      </ResizablePanel>
      <ResizableHandle withHandle />
      <ResizablePanel defaultSize={35} minSize={20}>
        <div className="grid h-full place-items-center gap-1.5 p-4 text-sm font-medium text-muted-foreground">
          <Rows className="size-5" />
          Activity
        </div>
      </ResizablePanel>
    </ResizablePanelGroup>
  </ResizablePanel>
</ResizablePanelGroup>
```

## API reference

### ResizablePanelGroup

The split container. Forwards every `div` prop.

- `direction`: `"horizontal" | "vertical"`. Lay panels side-by-side or stacked. Default `"horizontal"`.
- `onLayout`: `(sizes: number[]) => void`. Fires with the panel weights (DOM order) whenever the layout changes.
- `className`: sizes the box; panels fill it. Give it a height (and usually a border/radius).

### ResizablePanel

One region of the split. Forwards every `div` prop.

- `defaultSize`: `number`. Starting weight (conventionally a percentage). Omit on every panel for an equal split.
- `minSize` / `maxSize`: `number | string`. Clamp the drag range. A number/`"%"` is a proportional weight; `"240px"` is a hard width/height bound that holds on window resize.
- `collapsible`: `boolean`. Snap shut past half `minSize`.
- `collapsedSize`: `number | string`. Size when collapsed. Default `0`.
- `asChild`: `boolean`. Render as the child element via Radix Slot.

### ResizableHandle

The draggable divider. `role="separator"`, arrow-key operable (Shift = coarse, Home/End jump to min/max). Forwards every `div` prop.

- `withHandle`: `boolean`. Show the minimal rounded grip pill.
- `children`: `ReactNode`. Custom handle content, centered on the divider, replaces the default pill while keeping all behavior.
- `disabled`: `boolean`. Disable dragging and keyboard resizing.

## FAQ

### How do I set the initial split between panels?

Give each ResizablePanel a `defaultSize` weight, conventionally summing to 100. Omit it on every panel for an equal split.

### What is the difference between a numeric minSize and a pixel string?

A number (or a `"%"` string) is a proportional weight that scales with the group. A pixel string like `"240px"` is a hard bound pinned as a real CSS min/max width, so it holds at any group size, even as the window resizes.

### How do I make a panel collapse like a tucked-away sidebar?

Mark the panel `collapsible`. It snaps shut once dragged past half its `minSize`, settling at `collapsedSize` (default 0). Drag back out to restore it.

### Is the handle keyboard accessible?

Yes. ResizableHandle carries `role="separator"` and reports its position via `aria-valuenow`. It is arrow-key operable, with Shift for coarse steps and Home/End to jump to min/max.

### How do I customize the divider's appearance?

Add `withHandle` for the minimal rounded grip pill, or pass `children` to ResizableHandle to replace the visual entirely (an icon nub, a brand chip) while keeping all the drag, keyboard, and ARIA behavior. Without either it is a hairline that highlights on hover and focus.

### Can I build a dashboard with rows and columns?

Yes, groups nest. Put a vertical ResizablePanelGroup inside a panel of a horizontal one. Each group resizes independently. Use `onLayout` on a group to read the panel weights whenever the layout changes.

---

<!-- https://www.koalaui.com/docs/components/rich-text-editor.md -->

# Rich Text Editor

A WYSIWYG editor for formatted prose: headings, bold, italic, underline, links and lists. Built on Tiptap for selection, undo and paste, with every pixel of UI owned as a Koala tv recipe.

```tsx
<RichTextEditor defaultValue="<h2>Release notes</h2>…">
  <RichTextEditorToolbar />
  <RichTextEditorContent />
</RichTextEditor>
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add rich-text-editor
```

Manual: run `npm install @tiptap/react @tiptap/starter-kit @tiptap/pm @tiptap/extensions radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/rich-text-editor/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

```tsx title="usage.tsx"
import {
  RichTextEditor,
  RichTextEditorToolbar,
  RichTextEditorContent,
} from "@/components/ui/rich-text-editor"

export function Example() {
  return (
    <RichTextEditor
      defaultValue="<p>Hello, world.</p>"
      onChange={(html) => console.log(html)}
    >
      <RichTextEditorToolbar />
      <RichTextEditorContent />
    </RichTextEditor>
  )
}
```

## Placeholder

An empty editor shows muted ghost text. Set it with the `placeholder` prop.

```tsx
<RichTextEditor placeholder="Write a description…">
  <RichTextEditorToolbar />
  <RichTextEditorContent />
</RichTextEditor>
```

## A complete composer

Everything together: a seeded document, the full toolbar, the on-selection bubble, a scrollable writing area, and a status bar that lives inside the editor surface: live word/character counts (`tabular-nums`, so they never reflow) and a save action with transient confirmation. The status bar is just a child that reads the editor via `useRichTextEditor`.

```tsx
function ComposerStatusBar() {
  const editor = useRichTextEditor()
  const { words, chars } = useEditorState({
    editor,
    selector: ({ editor }) => {
      const text = editor?.getText().trim() ?? ""
      return {
        words: text ? text.split(/\s+/).length : 0,
        chars: editor?.getText().length ?? 0,
      }
    },
  }) ?? { words: 0, chars: 0 }

  return (
    <div className="flex items-center justify-between border-t border-border px-3 py-2">
      <p className="text-xs text-muted-foreground">
        <span className="tabular-nums">{words}</span> words ·{" "}
        <span className="tabular-nums">{chars}</span> characters
      </p>
      <Button size="sm" onClick={saveDraft}><FloppyDisk /> Save draft</Button>
    </div>
  )
}

<RichTextEditor defaultValue={doc}>
  <RichTextEditorToolbar />
  <RichTextEditorBubbleMenu />
  <RichTextEditorContent className="max-h-80 overflow-y-auto" />
  <ComposerStatusBar />
</RichTextEditor>
```

## Selection bubble menu

Drop in `RichTextEditorBubbleMenu` and a floating toolbar surfaces over the current selection. **Double-click a word** or drag across a phrase and it appears above it (Medium / Notion style). It pairs with the top toolbar or replaces it entirely. Its link control expands *inline* so the selection-driven bubble never dismisses while you type the URL.

```tsx
<RichTextEditor defaultValue="<p>Select any of this text…</p>">
  <RichTextEditorToolbar />
  <RichTextEditorBubbleMenu />
  <RichTextEditorContent />
</RichTextEditor>
```

Or go chromeless: omit the top toolbar and let the bubble be the only formatting UI.

```tsx
<RichTextEditor defaultValue="<p>A clean canvas…</p>">
  <RichTextEditorBubbleMenu />
  <RichTextEditorContent />
</RichTextEditor>
```

## Density

Like the rest of Koala, the editor honors `density`. `compact` tightens the writing area for dense app surfaces. The toolbar sits outside that axis: its 8px padding is what keeps the controls' 12px corners concentric inside the 20px frame, and a format bar that shrank with form density would get hard to hit, so the controls hold 32px either way. Set it per instance or once with a `DensityProvider`.

```tsx
<DensityProvider density="compact">
  <RichTextEditor defaultValue="<p>Compact density…</p>">
    <RichTextEditorToolbar />
    <RichTextEditorContent />
  </RichTextEditor>
</DensityProvider>
```

## Read-only

Pass `editable={false}` and omit the toolbar to render stored content as styled prose, useful for previews and feeds.

```tsx
<RichTextEditor editable={false} defaultValue={savedHtml}>
  <RichTextEditorContent />
</RichTextEditor>
```

## Custom toolbar

With no children the toolbar renders the essential controls. For a custom set, pass `RichTextEditorButton`s and reach the live editor with the `useRichTextEditor` hook (pair it with Tiptap's `useEditorState` to reflect active formatting).

```tsx
function CustomToolbar() {
  const editor = useRichTextEditor()
  const s = useEditorState({
    editor,
    selector: ({ editor }) => ({ bold: !!editor?.isActive("bold") }),
  })
  return (
    <RichTextEditorToolbar>
      <RichTextEditorButton
        tooltip="Bold"
        pressed={s?.bold}
        onClick={() => editor?.chain().focus().toggleBold().run()}
      >
        <TextB />
      </RichTextEditorButton>
    </RichTextEditorToolbar>
  )
}
```

## Prose scale

Inside the editor, blocks render on a document scale tuned for reading: the heading steps mirror Tailwind's `@tailwindcss/typography` `prose-sm` proportions, scaled to the 14px body (no plugin dependency). Headings run `text-3xl` → `text-sm` in the strong foreground, while body copy stays the muted secondary color, so a document reads calm with only its headings and emphasis lifted. These sizes are fixed by the component. For the raw scale they draw from, see the [Typography](https://www.koalaui.com/docs/foundations/typography.md) foundation.

- `H1`: text-3xl · 30px (semibold · tight)
- `H2`: text-xl · 20px (semibold · tight)
- `H3`: text-lg · 18px (semibold)
- `H4`: text-sm · 14px (semibold)
- `Body`: text-sm · 14px (relaxed · muted)

## FAQ

### Why is this built on Tiptap rather than a Radix primitive?

Rich text needs ProseMirror's document model for selection, undo, and paste, which no Radix primitive provides. Like Tooltip wrapping Tippy.js, it is the considered exception to Koala's Radix-first rule, with every pixel of UI still owned as a tv recipe.

### How do I read the editor's value, and is it controlled?

Seed initial content with `defaultValue` (an HTML string) and subscribe to edits with `onChange`, which fires with the current HTML. For live derived UI like word counts, reach the editor instance from any child with the `useRichTextEditor` hook.

### What does RichTextEditorBubbleMenu add, and can it replace the toolbar?

It floats a formatting toolbar over the current selection (Medium / Notion style) when you double-click a word or drag across a phrase. It pairs with the top `RichTextEditorToolbar` or replaces it entirely for a chromeless canvas; its link control expands inline so the bubble never dismisses while you type a URL.

### How do I render stored content read-only?

Pass `editable={false}` and omit the `RichTextEditorToolbar`, leaving just `RichTextEditorContent` to render the saved HTML as styled prose. This is the pattern for previews and feeds.

### How do I build a custom toolbar with active formatting state?

Pass `RichTextEditorButton`s as children of `RichTextEditorToolbar`, get the editor via `useRichTextEditor`, and drive each button with `editor.chain().focus().toggleBold().run()`. Pair it with Tiptap's `useEditorState` and the button's `pressed` prop to reflect whether the mark is active.

### Does the editor honor density?

Yes. Set `density="compact"` per instance or once with a `DensityProvider` to tighten the writing area for dense app surfaces. The toolbar stays out of it: its 8px padding is what keeps the 12px controls concentric inside the editor's 20px frame, and a format bar that shrank with form density would get hard to hit, so the controls hold 32px in both densities.

---

<!-- https://www.koalaui.com/docs/components/scroll-area.md -->

# Scroll Area

A scrolling region with Koala's own scrollbar: an ink pill that overlays the content, shows while you are over it, fades rather than blinks, and looks the same on every OS and theme. The scrolling itself stays native.

```tsx
<ScrollArea fade className="h-72 w-72 rounded-lg shadow-xs ring-1 ring-edge">
  <div className="px-4 py-3">
    <h4 className="pb-1 text-sm font-semibold">Releases</h4>
    <List variant="plain">
      {releases.map((r) => (
        <ListItem key={r.version}>
          <ListItemContent>
            <ListItemTitle className="font-mono tabular-nums">v{r.version}</ListItemTitle>
          </ListItemContent>
          <ListItemMeta>
            <Badge variant={tone[r.tag]} size="sm">{r.tag}</Badge>
            {r.date}
          </ListItemMeta>
        </ListItem>
      ))}
    </List>
  </div>
</ScrollArea>
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add scroll-area
```

Manual: run `npm install radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/scroll-area/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

```tsx title="usage.tsx"
import { ScrollArea } from "@/components/ui/scroll-area"

export function Example() {
  return (
    <ScrollArea className="h-72">
      {/* anything taller than 288px */}
    </ScrollArea>
  )
}
```

Give the root a height (`h-72`, `max-h-96`, or `flex-1 min-h-0` in a flex column) and the viewport fills it. `className` styles the root; the viewport inherits its radius, so a rounded frame clips the content and the focus ring to its corners.

## Edge fade

`fade` dissolves the edge that still has content beyond it, so the region says there is more before anyone hovers it. It is the `scroll-fade` utility, pure CSS: the edge you are scrolling toward fades, and the one you reach sharpens.

```tsx
<ScrollArea className="h-56">…</ScrollArea>
<ScrollArea fade className="h-56">…</ScrollArea>
```

## Horizontal

`orientation="horizontal"` draws the bar along the bottom and lets the content grow to its own width (`w-max` on the row). The photos sit 8px inside the frame, on 8px corners under its 16px ones, each with the thin image outline.

```tsx
<ScrollArea orientation="horizontal" fade className="max-w-lg rounded-lg shadow-xs ring-1 ring-edge">
  <div className="flex w-max gap-2 p-2 pb-4">
    {photos.map((photo) => (
      <figure key={photo.id} className="w-44 shrink-0">
        <div className="relative aspect-[4/3] overflow-hidden rounded-sm">
          <img src={photo.src} alt={photo.label} className="size-full object-cover" />
        </div>
        <figcaption className="px-1 pt-2 text-xs font-medium text-muted-foreground">{photo.label}</figcaption>
      </figure>
    ))}
  </div>
</ScrollArea>
```

## Drag with the mouse

`draggable` lets a mouse pull the content the way a finger already does: press, drag, let go and it glides on. For a strip of cards or photos, where people reach for the content rather than the bar. A press that barely moves is still a click, and a real drag swallows the click it ends on, so a card link never opens by accident. Touch and pen keep their native scroll, and the glide is skipped under reduced motion.

```tsx
<ScrollArea orientation="horizontal" fade draggable className="max-w-lg rounded-lg shadow-xs ring-1 ring-edge">
  <div className="flex w-max gap-2 p-2 pb-4">
    {photos.map((photo) => (
      <figure key={photo.id} className="w-44 shrink-0">…</figure>
    ))}
  </div>
</ScrollArea>
```

## Both axes

`orientation="both"` draws both bars and a corner where they meet, for content wider and taller than its frame: a year of figures, a schedule, a canvas.

```tsx
<ScrollArea orientation="both" className="h-64 max-w-lg rounded-lg shadow-xs ring-1 ring-edge">
  <div className="px-4 py-1">
    <Table density="compact" className="w-max">…</Table>
  </div>
</ScrollArea>
```

## When the bar shows

`type` is Radix's: `hover` (the default) shows the bar while the pointer is over the region, `scroll` only while it is scrolling, and `always` whenever the content overflows. However it appears, it fades in and out, and it thickens a step when you reach for it, the way a native overlay bar does.

```tsx
<ScrollArea type="hover" className="h-40">…</ScrollArea>
<ScrollArea type="scroll" className="h-40">…</ScrollArea>
<ScrollArea type="always" className="h-40">…</ScrollArea>
```

## The viewport

`viewportRef` is the element that actually scrolls: read `scrollTop`, call `scrollTo`, or observe it. Here it drives a button that appears once you are away from the top and takes you back smoothly.

```tsx
const viewport = useRef<HTMLDivElement>(null)

<ScrollArea fade viewportRef={viewport} className="h-64">…</ScrollArea>
<Button size="sm" variant="secondary" onClick={() => viewport.current?.scrollTo({ top: 0, behavior: "smooth" })}>
  Back to top
</Button>
```

## API reference

### ScrollArea

The root, viewport, bars and corner in one. Props: `orientation` (`vertical` · `horizontal` · `both`), `fade`, `draggable`, `viewportRef`, plus Radix's `type` (`hover` · `scroll` · `always` · `auto`), `scrollHideDelay` (600ms) and `dir`. `className` goes on the root.

## FAQ

### Scroll Area or a plain overflow box?

The site's own scrollbars are hidden, so a plain `overflow-y-auto` box with the `scroll-fade` utility is the lighter option when the fade is cue enough: menus, pickers, chat logs. Use Scroll Area when the bar itself should show, for instance a long panel people drag through.

### Does it change how scrolling feels?

No. The viewport is a native scroller, so wheel, trackpad momentum, touch, keyboard and find-in-page all behave as usual. Only the bar is drawn by the component. `draggable` adds one thing on top, a mouse pull, and moves the same native scroll position to do it.

### Why doesn't my Scroll Area scroll?

It has no height to overflow. Give the root one: `h-72` or `max-h-96`, or `flex-1 min-h-0` inside a flex column, where `min-h-0` is what lets it shrink below its content.

### Why does `truncate` work inside a vertical area?

Radix wraps the content in a `display: table` box so a horizontal area can grow to its content. A vertical-only area puts that box back to a plain block, so truncation and long-word wrapping behave as they would anywhere else.

### Can a keyboard user scroll it?

Yes. The viewport is a native scroller: browsers let it take focus when nothing inside it can, and the arrow keys then scroll it. It shows an inset brand ring while focused.

---

<!-- https://www.koalaui.com/docs/components/select.md -->

# Select

A dropdown for picking one value from a list. Built on Radix Select for keyboard navigation, type-ahead and a11y, with interruptible enter and exit. Its sibling SelectSearch adds a search field.

```tsx
import { Pizza, Hamburger, Fish, Egg, Coffee } from "@phosphor-icons/react"

<Select>
  <SelectTrigger className="w-56">
    <SelectValue placeholder="Select a dish" />
  </SelectTrigger>
  <SelectContent>
    <SelectItem value="coffee">
      <span className="flex items-center gap-2"><Coffee /> Coffee</span>
    </SelectItem>
    <SelectItem value="egg">
      <span className="flex items-center gap-2"><Egg /> Eggs benedict</span>
    </SelectItem>
    <SelectItem value="fish">
      <span className="flex items-center gap-2"><Fish /> Grilled fish</span>
    </SelectItem>
    <SelectItem value="burger">
      <span className="flex items-center gap-2"><Hamburger /> Hamburger</span>
    </SelectItem>
    <SelectItem value="pizza">
      <span className="flex items-center gap-2"><Pizza /> Pizza</span>
    </SelectItem>
  </SelectContent>
</Select>
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add select
```

Manual: run `npm install radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/select/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

```tsx title="usage.tsx"
import { Pizza, Hamburger } from "@phosphor-icons/react"
import {
  Select, SelectTrigger, SelectValue, SelectContent,
  SelectItem, SelectGroup, SelectLabel, SelectSeparator,
} from "@/components/ui/select"

export function Example() {
  return (
    <Select>
      <SelectTrigger className="w-56">
        <SelectValue placeholder="Select a dish" />
      </SelectTrigger>
      <SelectContent>
        <SelectItem value="pizza">
          <span className="flex items-center gap-2"><Pizza /> Pizza</span>
        </SelectItem>
        <SelectItem value="burger">
          <span className="flex items-center gap-2"><Hamburger /> Hamburger</span>
        </SelectItem>
      </SelectContent>
    </Select>
  )
}
```

## Groups and labels

Use `SelectGroup` and `SelectLabel` to group related options. Add `SelectSeparator` between groups for visual clarity.

```tsx
import { Clock } from "@phosphor-icons/react"

<Select>
  <SelectTrigger className="w-64">
    <SelectValue placeholder="Select a timezone" />
  </SelectTrigger>
  <SelectContent>
    <SelectGroup>
      <SelectLabel>Europe</SelectLabel>
      <SelectItem value="cet">
        <span className="flex items-center gap-2"><Clock /> Central European Time (CET)</span>
      </SelectItem>
      <SelectItem value="gmt">
        <span className="flex items-center gap-2"><Clock /> Greenwich Mean Time (GMT)</span>
      </SelectItem>
    </SelectGroup>
    <SelectSeparator />
    <SelectGroup>
      <SelectLabel>North America</SelectLabel>
      <SelectItem value="cst">
        <span className="flex items-center gap-2"><Clock /> Central Standard Time (CST)</span>
      </SelectItem>
      <SelectItem value="est">
        <span className="flex items-center gap-2"><Clock /> Eastern Standard Time (EST)</span>
      </SelectItem>
      <SelectItem value="pst">
        <span className="flex items-center gap-2"><Clock /> Pacific Standard Time (PST)</span>
      </SelectItem>
    </SelectGroup>
  </SelectContent>
</Select>
```

## Long lists

When the options outgrow the available height the menu scrolls, and its top and bottom edges fade softly into the popover, the [scroll fade](https://www.koalaui.com/docs/foundations/scroll-fade.md) utility, so there’s a clear “more above / below” cue without a scrollbar. Open this and scroll: the leading edge stays crisp, the trailing edge dissolves, and a keyboard-focused row always lands clear of the fade. The list is capped at 20rem or the room left on screen, whichever is smaller, so on a phone it scrolls inside the panel instead of running off the viewport, and the arrows at either end sit over the fade rather than pushing the rows down.

```tsx
import { MapPin } from "@phosphor-icons/react"

const cities = ["Amsterdam", "Bangkok", "Berlin" /* … */]

<Select>
  <SelectTrigger className="w-56">
    <SelectValue placeholder="Select a city" />
  </SelectTrigger>
  <SelectContent>
    {cities.map((city) => (
      <SelectItem key={city} value={city}>
        <span className="flex items-center gap-2"><MapPin /> {city}</span>
      </SelectItem>
    ))}
  </SelectContent>
</Select>
```

## Searching the list

Past a couple of dozen options, scrolling stops being a way to find anything. `SelectSearch` is the same select with a search field in its panel: one value, the same trigger, the same rows and the same brand check, filtered as you type. Focus stays in the field the whole time, so typing never stops: arrows move the highlight, Enter commits the active row, Escape closes. Give each row a `textValue` (what the search reads, since `value` is an id) and `keywords` for the terms people actually type - here, a city finds its timezone. Rows that don’t match render nothing, so groups, separators and the empty state collapse on their own.

```tsx
import { Clock } from "@phosphor-icons/react"

<SelectSearch>
  <SelectSearchTrigger className="w-80">
    <Clock />
    <SelectSearchValue placeholder="Select a timezone" />
  </SelectSearchTrigger>
  <SelectSearchContent>
    <SelectSearchInput placeholder="Search zones or cities…" />
    <SelectSearchList label="Timezones">
      <SelectSearchGroup>
        <SelectSearchLabel>Europe</SelectSearchLabel>
        <SelectSearchItem
          value="cet"
          textValue="Central European Time (CET)"
          keywords={["madrid", "paris", "berlin"]}
        >
          <Clock /> Central European Time (CET)
        </SelectSearchItem>
      </SelectSearchGroup>
      <SelectSearchEmpty>No timezone matches that.</SelectSearchEmpty>
    </SelectSearchList>
  </SelectSearchContent>
</SelectSearch>
```

Pass `inline` and the panel renders in the page flow under its trigger instead of floating over it, for a picker that belongs to a form or a side panel. In flow it paints no fill and no shadow, just the hairline, because [fill is elevation](https://www.koalaui.com/docs/foundations/colors.md); the trigger stays quiet too, since the search field inside the panel is what holds the focus. This one also shows `renderValue`: the value is seeded from outside and the rows only exist while the panel is open, so the trigger is told how to draw it.

```tsx
<SelectSearch inline defaultOpen defaultValue="ava" className="w-80">
  <SelectSearchTrigger>
    <SelectSearchValue
      placeholder="Assign to…"
      renderValue={(value) => <Assignee value={value} />}
    />
  </SelectSearchTrigger>
  <SelectSearchContent>
    <SelectSearchInput placeholder="Search people…" />
    <SelectSearchList label="Teammates">
      <SelectSearchItem value="ava" textValue="Ava Smith" keywords={["design lead"]}>
        <Assignee value="ava" />
      </SelectSearchItem>
      <SelectSearchEmpty>Nobody by that name.</SelectSearchEmpty>
    </SelectSearchList>
  </SelectSearchContent>
</SelectSearch>
```

## Aligned to the selected item

By default the list opens below the trigger, which keeps the trigger’s brand ring in view and matches the pickers built on Popover (CountrySelect, MultiSelect, DatePicker). Pass `position="item-aligned"` for a short, toolbar-style list: it opens with the current option laid over the trigger, so the eye never moves. Keep it to a handful of options; a long list belongs below the trigger.

```tsx
<Select defaultValue="newest">
  <SelectTrigger className="w-48">
    <SelectValue />
  </SelectTrigger>
  <SelectContent position="item-aligned">
    <SelectItem value="alphabetical"><SortAscending /> Alphabetical</SelectItem>
    <SelectItem value="popular"><Fire /> Most popular</SelectItem>
    <SelectItem value="newest"><Sparkle /> Newest</SelectItem>
    <SelectItem value="oldest"><Clock /> Oldest</SelectItem>
  </SelectContent>
</Select>
```

## Country select

A plain `Select` over ~250 countries is a long scroll, so reach for `CountrySelect`, a searchable picker that looks like a Select trigger but filters as you type and is fully keyboard-navigable. It returns the selected ISO 3166-1 alpha-2 code and lives in the [Input](https://www.koalaui.com/docs/components/input.md) family, sharing the canonical country dataset and circular flags with `PhoneInput`. Inside a [Field](https://www.koalaui.com/docs/components/field.md) it wires up label, aria, and error state automatically.

```tsx
import { CountrySelect } from "@/components/ui/input"

const [country, setCountry] = useState("US")

<CountrySelect
  value={country}
  onValueChange={setCountry}
  className="w-56"
/>
```

## Disabled items

```tsx
import { Gift, Lightning, Buildings } from "@phosphor-icons/react"

<Select>
  <SelectTrigger className="w-56">
    <SelectValue placeholder="Select a plan" />
  </SelectTrigger>
  <SelectContent>
    <SelectItem value="enterprise" disabled>
      <span className="flex items-center gap-2"><Buildings /> Enterprise (contact us)</span>
    </SelectItem>
    <SelectItem value="free">
      <span className="flex items-center gap-2"><Gift /> Free</span>
    </SelectItem>
    <SelectItem value="pro">
      <span className="flex items-center gap-2"><Lightning /> Pro</span>
    </SelectItem>
  </SelectContent>
</Select>
```

## Option hints

Some labels are too terse to stand on their own. `High` and `Medium` say nothing about the trade-off behind them. Pass a `tooltip` to `SelectItem` to attach a hint that surfaces on hover and on keyboard focus, so the choice is informed without crowding the row. Use `tooltipPlacement` to change the side it grows toward (defaults to `right`).

```tsx
import { Gauge, Lightning, Brain } from "@phosphor-icons/react"

<Select defaultValue="low">
  <SelectTrigger className="w-56">
    <SelectValue placeholder="Reasoning effort" />
  </SelectTrigger>
  <SelectContent>
    <SelectItem value="minimal" tooltip="Fastest, shallowest pass. Good for simple, well-scoped tasks.">
      <span className="flex items-center gap-2"><Gauge /> Minimal</span>
    </SelectItem>
    <SelectItem value="low" tooltip="Optimizes for latency over depth.">
      <span className="flex items-center gap-2"><Lightning /> Low</span>
    </SelectItem>
    <SelectItem value="medium" tooltip="Balances response speed against how hard the model thinks.">
      <span className="flex items-center gap-2"><Gauge /> Medium</span>
    </SelectItem>
    <SelectItem value="high" tooltip="Deepest reasoning. Slower and more expensive, best for hard problems.">
      <span className="flex items-center gap-2"><Brain /> High</span>
    </SelectItem>
  </SelectContent>
</Select>
```

## Density

The trigger height comes from `size` on `SelectTrigger` - `sm`/`md`/`lg` map to 32/36/40px, the same scale as Button and Input, so a Select lines up with them at a shared size. `density` no longer sets the trigger height; it picks the *default* size when you do not pass one (compact → `sm`, comfortable → `md`) and tightens the dropdown menu rows. Pass `density` to `SelectContent` (or a parent `DensityProvider`) for the menu spacing.

```tsx
import { Circle } from "@phosphor-icons/react"

<Select>
  <SelectTrigger className="w-48" density="compact">
    <SelectValue placeholder="Compact" />
  </SelectTrigger>
  <SelectContent density="compact">
    <SelectItem value="a">
      <span className="flex items-center gap-2"><Circle /> Option A</span>
    </SelectItem>
    <SelectItem value="b">
      <span className="flex items-center gap-2"><Circle /> Option B</span>
    </SelectItem>
  </SelectContent>
</Select>
```

## Selecting multiple values

`Select` picks exactly one value and closes on pick. For checkboxes, switches, and sections that stay open while you toggle several values, reach for [Multi Select](https://www.koalaui.com/docs/components/multi-select.md) - a Popover-backed sibling with the same surface and motion.

## FAQ

### When should I use Select versus SelectSearch, MultiSelect or CountrySelect?

Use `Select` to pick exactly one value from a short list; it closes on pick. Past a couple of dozen options, `SelectSearch` is the same select with a search field in its panel. For toggling several values with checkboxes or switches that stay open, reach for `MultiSelect`, and for the ~250-country case use the ready-made `CountrySelect` from the Input family.

### Why is SelectSearch a separate component instead of a search field inside SelectContent?

Radix Select's content owns the keyboard (its type-ahead swallows every character), pulls focus onto the selected item, and only ever exists as a portalled, focus-trapped overlay that aria-hides the rest of the page and locks scrolling. None of that can host a text field, and none of it can render in the page flow. So `SelectSearch` is built on Radix Popover, exactly like `MultiSelect`, and dressed in the SAME `selectVariants` recipe: the trigger, panel, rows, check, labels and separators can't drift from their Select twins.

### How does SelectSearch filter, and what do textValue and keywords do?

`value` is the id the row commits, so the search reads `textValue` instead (give it the visible label) plus any `keywords` - synonyms, a handle, a city, a country code. The default match is a case-insensitive substring over both; pass `filter` on the root to score matches yourself (return 0 to hide a row). A row that doesn't match renders nothing, so groups, separators and the empty state collapse with plain CSS.

### Why does my SelectSearch trigger show nothing when I seed a value?

The option rows only exist while the panel is open, so the trigger can only remember a label the user picked in this session. Seed a value from outside (a `defaultValue`, a controlled value, a saved form) and you have to tell the trigger how to draw it: pass `renderValue` to `SelectSearchValue`, the same escape hatch `MultiSelectValue` uses for chips.

### When should the search panel be inline?

Pass `inline` when the picker belongs to a form or a side panel rather than floating over the page: the panel renders in the flow under its trigger, paints no fill and no shadow (fill is elevation), and the trigger drops its open halo since the search field inside the panel is what holds the focus. Escape clears the query instead of closing, because in flow there's nothing to dismiss.

### How do I compose the parts?

Wrap everything in `Select`, put `SelectValue` (with a `placeholder`) inside a `SelectTrigger`, and list `SelectItem`s inside `SelectContent`. Organize long lists with `SelectGroup` plus `SelectLabel`, and divide groups with `SelectSeparator`.

### How do I attach a hint to a terse option?

Pass a `tooltip` string to `SelectItem` to surface a hint on hover and on keyboard focus, useful for labels like High or Medium that say nothing about the trade-off. Use `tooltipPlacement` to change the side it grows toward (defaults to `right`).

### How do I size the trigger, and where does density go?

Trigger height comes from `size` on `SelectTrigger` (sm/md/lg = 32/36/40px, the same scale as Button and Input). `density` no longer sets the height - it picks the default size when you don't pass one (compact -> sm, comfortable -> md) and tightens the dropdown rows; pass it to `SelectContent` (or a parent `DensityProvider`) for the menu spacing. An explicit `size` always wins.

### Is keyboard navigation and type-ahead handled for me?

Yes. Select is built on Radix Select, so arrow-key navigation, type-ahead search, and ARIA come for free. Mark an option `disabled` to skip it in that navigation.

### How do I add an icon to each option?

Koala's convention is a leading Phosphor icon per option: wrap the icon and label in a `<span className="flex items-center gap-2">` inside the `SelectItem`. Render icons in outline weight to match the rest of the system.

---

<!-- https://www.koalaui.com/docs/components/sheet.md -->

# Sheet

A panel that stays open over a full-bleed canvas like a map: a floating card on a wide container, a bottom sheet with three detents on a narrow one. Unlike Drawer, it never blocks the page.

```tsx
<div className="relative h-[30rem]">
  {/* your map, board or canvas */}
  <Sheet size="sm">
    <SheetHandle />
    <SheetHeader>
      <SheetTitle>Nearby</SheetTitle>
      <SheetDescription>Five places open now, closest first.</SheetDescription>
    </SheetHeader>
    <SheetBody>
      <List variant="plain">…</List>
    </SheetBody>
    <SheetFooter>
      <Button variant="ghost" className="flex-1">Filters</Button>
      <Button className="flex-1">Directions</Button>
    </SheetFooter>
  </Sheet>
</div>
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add sheet
```

Manual: run `npm install radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/sheet/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

Put the Sheet inside the positioned element it floats over, usually the box your map fills. It is absolute in there, and that element is what it measures: wider than `breakpoint` (768px by default) it floats as a card, narrower it rises from the bottom. It follows the container, not the viewport, so it behaves the same full-screen and inside a panel.

```tsx title="usage.tsx"
import {
  Sheet, SheetHandle, SheetHeader, SheetTitle,
  SheetDescription, SheetBody, SheetFooter,
} from "@/components/ui/sheet"

export function MapScreen() {
  return (
    <div className="relative h-dvh">
      <Map className="absolute inset-0" />
      <Sheet>
        <SheetHandle />
        <SheetHeader>
          <SheetTitle>Nearby</SheetTitle>
          <SheetDescription>Five places open now.</SheetDescription>
        </SheetHeader>
        <SheetBody>{/* … */}</SheetBody>
        <SheetFooter>{/* … */}</SheetFooter>
      </Sheet>
    </div>
  )
}
```

## Detents

On a narrow canvas the sheet rests at one of three heights: `peek` (the header and a row or two, `peekHeight` sets it), `half`, and `full`, which leaves a strip of the canvas visible at the top. Drag the handle or the header and let go: the release velocity is projected, so a flick carries it to the next detent. A tap on the handle steps it up. Control it with `detent` and `onDetentChange`, or let it start at `defaultDetent`.

```tsx
const [detent, setDetent] = React.useState<SheetDetent>("half")

<Sheet detent={detent} onDetentChange={setDetent}>
  <SheetHandle />
  <SheetHeader>…</SheetHeader>
  <SheetBody>…</SheetBody>
</Sheet>
```

## Side and size

The floating card docks to the `left` (the default) or `right` edge, top to bottom with a margin all round. `size` picks its width on the same steps Drawer uses (`sm`, `md` by default, `lg`, `xl`); a width class of your own replaces it. A bottom sheet always spans the canvas.

```tsx
<Sheet side="right" size="sm" density="compact">
  <SheetHandle />
  <SheetHeader>
    <SheetTitle>Layers</SheetTitle>
    <SheetDescription>What the map draws on top of the streets.</SheetDescription>
  </SheetHeader>
  <SheetBody>…</SheetBody>
</Sheet>
```

## The visible area

A map centred on the whole canvas puts half of what you look at under the sheet. `onInsetChange` reports how much of the canvas the sheet covers, per edge and in pixels, every time that changes (the layout, the detent, the width, and each frame of a drag). Hand it to the map as padding and it centres things in the part that is still visible.

```tsx
<Sheet onInsetChange={(insets) => map.setPadding(insets)}>
  …
</Sheet>
```

## Keyboard and screen readers

The Sheet is a named `<aside>`, a complementary landmark, labelled by its `SheetTitle` (or pass an `aria-label`). Nothing traps focus and nothing behind it goes inert: it is part of the page. On a bottom sheet the handle is a focusable window splitter: ArrowUp and ArrowDown step between detents, Home and End jump to `peek` and `full`, Enter and Space step it up, and it announces the detent through `aria-valuetext` (rename them with `detentLabels`).

## API reference

`Sheet` renders an `<aside>` and adds `detent`, `defaultDetent` (`peek | half | full`, default `half`), `onDetentChange`, `side` (`left | right`), `size` (`sm | md | lg | xl`, default `md`), `breakpoint` (px, default `768`), `peekHeight` (px, default `176`), `onInsetChange` and `density` (`comfortable | compact`). It exposes `data-layout` (`floating | bottom`), `data-detent` and `data-dragging` for styling. `SheetHandle` takes `detentLabels` and renders nothing while the sheet floats. `SheetHeader`, `SheetBody` and `SheetFooter` are divs, `SheetTitle` an `<h2>` and `SheetDescription` a `<p>`; every part takes `className`. The `useSheet()` hook returns the `layout`, the `detent` and `setDetent` to anything inside.

## FAQ

### When should I use a Sheet instead of a Drawer?

Use a Drawer for a task that interrupts: it opens over the page, dims it, traps focus and closes when you are done. Use a Sheet for a panel that lives next to the page for as long as the page is open, like the place list over a map or the layers of a design board. The Sheet never dims, traps or closes; the canvas under it stays fully usable.

### Why does it follow the container width and not the viewport?

Because the Sheet lives inside the canvas it covers, and that canvas is not always the whole window: a map inside a dashboard pane is narrow on a wide screen. Measuring the container (with a ResizeObserver) picks the right shape wherever it is placed, including a docs preview. Change the switch point with `breakpoint`.

### How do I keep a map centred on what is still visible?

Pass `onInsetChange` and hand its insets to the map as padding, for example `map.setPadding(insets)` in MapLibre or Mapbox. It fires when the layout, detent or width changes and on each frame of a drag, so the map follows the sheet as it moves.

### Can I render something only on the bottom sheet, or at a given detent?

Yes: inside the Sheet, `useSheet()` returns the current `layout` (`floating` or `bottom`) and `detent`, plus `setDetent`. Use it to show a compact summary at `peek`, or to move to `full` when a search field gets focus.

### Where does an app's tab bar go?

In `SheetFooter`. It is pinned to the sheet's bottom edge, which on a bottom sheet is the canvas's own bottom edge, so the bar stays in reach at every detent while the body scrolls above it. A lone child fills the footer, so the bar spans the sheet without a width of its own; several children sit side by side, so give them `flex-1` to share the row.

---

<!-- https://www.koalaui.com/docs/components/sidebar.md -->

# Sidebar

The application navigation rail. Stack the parts you need: a workspace switcher up top, the primary pages first, labeled sections and favorites below, and a profile switcher pinned to the bottom.

```tsx
<Sidebar aria-label="Main">
  <SidebarHeader>
    {/* workspace switcher: a SidebarSwitcher in a DropdownMenu */}
    <DropdownMenu>
      <DropdownMenuTrigger asChild>
        {/* compact by default; pass variant="full" + a subtitle for the roomy identity row */}
        <SidebarSwitcher leading={<BrandMark wordmark={false} />} title="Koala" />
      </DropdownMenuTrigger>
      <DropdownMenuContent align="start">…</DropdownMenuContent>
    </DropdownMenu>
  </SidebarHeader>

  <SidebarContent>
    {/* primary pages: first, unlabeled */}
    <SidebarGroup aria-label="Primary">
      <SidebarItem active><SquaresFour /> Dashboard</SidebarItem>
      <SidebarItem>
        <Tray /> Inbox
        <Badge variant="secondary" size="sm" className="ml-auto tabular-nums">8</Badge>
      </SidebarItem>
      <SidebarItem><Stack /> Projects</SidebarItem>
    </SidebarGroup>

    {/* favorites: starred pages, marked with their page color */}
    <SidebarGroup aria-label="Favorites">
      <SidebarGroupLabel>Favorites</SidebarGroupLabel>
      <SidebarItem><Dot className="bg-purple" /> Q3 Roadmap</SidebarItem>
      <SidebarItem><Dot className="bg-teal" /> Design System</SidebarItem>
    </SidebarGroup>

    {/* a clearly-labeled section */}
    <SidebarGroup aria-label="Workspace">
      <SidebarGroupLabel>Workspace</SidebarGroupLabel>
      <SidebarItem><UsersThree /> Members</SidebarItem>
      <SidebarItem><GearSix /> Settings</SidebarItem>
    </SidebarGroup>
  </SidebarContent>

  <SidebarFooter>
    {/* profile switcher: same trigger, menu opens upward */}
    <DropdownMenu>
      <DropdownMenuTrigger asChild>
        <SidebarSwitcher leading={<Avatar />} title="Mara Okonkwo" />
      </DropdownMenuTrigger>
      <DropdownMenuContent side="top" align="start">…</DropdownMenuContent>
    </DropdownMenu>
  </SidebarFooter>
</Sidebar>
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add sidebar
```

Manual: run `npm install radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/sidebar/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

```tsx title="usage.tsx"
import {
  Sidebar, SidebarHeader, SidebarContent, SidebarFooter,
  SidebarGroup, SidebarGroupLabel, SidebarItem, SidebarSwitcher,
} from "@/components/ui/sidebar"

export function AppSidebar() {
  return (
    <Sidebar aria-label="Main">
      <SidebarHeader>{/* workspace switcher */}</SidebarHeader>
      <SidebarContent>
        <SidebarGroup aria-label="Primary">
          <SidebarItem active>{/* <Icon /> Label */}</SidebarItem>
        </SidebarGroup>
      </SidebarContent>
      <SidebarFooter>{/* profile switcher */}</SidebarFooter>
    </Sidebar>
  )
}
```

## Anatomy

`Sidebar` is a flex column on a `bg-card` surface. `SidebarHeader` and `SidebarFooter` pin to the top and bottom with a hairline separator, and either can hold a `SidebarActions` cluster beside its switcher; `SidebarContent` is the scroll region in between. Inside it, `SidebarGroup` is a navigation section. Give it a `SidebarGroupLabel` when it needs a heading, or leave it unlabeled for the primary pages. Each `SidebarItem` is a row.

## Switchers

`SidebarSwitcher` is one trigger used for both the workspace switcher (top) and the profile switcher (bottom): a `leading` visual, a `title` (with an optional `subtitle`), and an up/down caret. It renders a real `<button>`, so it drops straight into a `DropdownMenuTrigger asChild`. Radix owns the keyboard, focus, and ARIA; the switcher stays lit while its menu is open.

```tsx
<DropdownMenu>
  <DropdownMenuTrigger asChild>
    {/* compact by default, no variant needed */}
    <SidebarSwitcher leading={<BrandMark wordmark={false} />} title="Koala" />
  </DropdownMenuTrigger>
  <DropdownMenuContent align="start">
    <DropdownMenuItem><BrandMark wordmark={false} /> Koala <Check className="ml-auto" /></DropdownMenuItem>
    <DropdownMenuItem><Rocket /> Skunkworks</DropdownMenuItem>
    <DropdownMenuSeparator />
    <DropdownMenuItem><Plus /> Create workspace</DropdownMenuItem>
  </DropdownMenuContent>
</DropdownMenu>
```

## Full switcher

`SidebarSwitcher` takes a `variant`. The default is the compact trigger (a tight gap, a small muted caret, and reduced padding), the everyday switcher, paired with a small `leading` (an `Avatar size="xs"`, a single initial, or a compact logo tile). Pass `variant="full"` for the roomier identity row: a wider gap, a heavier title, and room for a `subtitle`. Pair it with a larger leading (an `Avatar size="md"`, which keeps both initials) for a primary or standalone switcher.

```tsx
{/* compact: the default, no variant needed */}
<SidebarSwitcher leading={<Avatar size="xs" />} title="Koala" />

{/* full: a larger leading + a subtitle reads as the roomy identity row */}
<SidebarSwitcher
  variant="full"
  leading={<Avatar size="md" />}
  title="Koala"
  subtitle="Enterprise plan"
/>
```

## Header actions

`SidebarActions` puts icon buttons beside a switcher: search and notifications next to the workspace, the way GitBook and Squarespace head their rail. Drop it into `SidebarHeader` (or `SidebarFooter`, for help or settings) after the switcher, and the zone lays the two out as a row: the switcher hugs its name so the caret follows it, and the icons sit at the far edge, in line with the ends of the rows below. Fill it with ghost icon-only `Button`s; they take the rail’s muted ink at rest and their `aria-label` as a tooltip.

This is where an app’s global tools live in the docked shell, which leaves the sheet’s [header bar](https://www.koalaui.com/docs/components/layout.md#header-bar) for the page. Collapsed to the icon rail, the buttons stack under the switcher’s mark instead of being cut off.

```tsx
<SidebarHeader>
  <SidebarSwitcher leading={<BrandMark wordmark={false} />} title="Koala" />
  <SidebarActions>
    <Button variant="ghost" iconOnly aria-label="Search">
      <MagnifyingGlass />
    </Button>
    <Button variant="ghost" iconOnly aria-label="Notifications">
      <Bell />
    </Button>
  </SidebarActions>
</SidebarHeader>
```

## Items

A `SidebarItem` is a `<button>` by default; pass `asChild` to wrap an `<a>` or a Next `<Link>`. Mark the current page with `active` (it fills the row and sets `aria-current="page"`). Lay the children out as `<Icon /> Label` and push a trailing `Badge` or count to the right with `ml-auto`.

```tsx
<SidebarItem active><SquaresFour /> Active page</SidebarItem>
<SidebarItem><Stack /> Default page</SidebarItem>
<SidebarItem>
  <Tray /> With a count
  <Badge variant="secondary" size="sm" className="ml-auto tabular-nums">12</Badge>
</SidebarItem>
<SidebarItem disabled><GearSix /> Disabled page</SidebarItem>
<SidebarItem asChild>
  <a href="#"><CalendarBlank /> A real link (asChild)</a>
</SidebarItem>
```

## Colored icon tiles

Swap the bare leading glyph for a `SidebarItemIcon`: a soft, hue-tinted rounded square that gives each destination its own color, the “colored spaces” rail you see in Productboard or Linear. Wrap a single icon and pass a `tone` (decorative: `purple`, `pink`, `teal`, `orange`; status: `green`, `blue`, `red`, `amber`, plus `brand`). The tile scales with density and becomes the centered chip in the collapsed rail. The active row still reads through the neutral chip and brand bar, the tiles decorate, they don’t signal selection.

```tsx
<SidebarGroup aria-label="Spaces">
  <SidebarGroupLabel>Spaces</SidebarGroupLabel>
  <SidebarItem active asChild>
    <a href="/portfolio">
      <SidebarItemIcon tone="purple"><Cube /></SidebarItemIcon>
      Product Portfolio
    </a>
  </SidebarItem>
  <SidebarItem asChild>
    <a href="/strategy">
      <SidebarItemIcon tone="orange"><Target /></SidebarItemIcon>
      Strategy
    </a>
  </SidebarItem>
  <SidebarItem asChild>
    <a href="/feedback">
      <SidebarItemIcon tone="green"><Gift /></SidebarItemIcon>
      Customer Feedback
    </a>
  </SidebarItem>
  <SidebarItem asChild>
    <a href="/roadmap">
      <SidebarItemIcon tone="pink"><Signpost /></SidebarItemIcon>
      Roadmapping
    </a>
  </SidebarItem>
</SidebarGroup>
```

## Nested navigation

`SidebarCollapsible` folds a sub-list of routes under a parent row. Give it an `icon` and `label`, drop the child `SidebarItem`s inside, and the row gains a caret that toggles them open, built on Radix Collapsible, so it owns the keyboard, focus, and height animation. The sub-list is indented under the label and traced by a guide rail; set `active` on the parent when one of its child routes is current. In the collapsed icon rail it falls back to a single icon row.

A long sub-list can be split under `SidebarGroupLabel` sub-headings: inside a sub-list the label stays a plain heading, even when the whole section sits in a collapsible group. With `indicator` on, folding a branch that holds the current route moves the pill to the first row still on show, so a parent marked `active` while folded catches it. The docs sidebar on this site is built exactly this way.

```tsx
<SidebarGroup aria-label="Primary">
  <SidebarItem active><SquaresFour /> Dashboard</SidebarItem>

  {/* a parent row that folds its routes: active because a child is current */}
  <SidebarCollapsible icon={<GearSix />} label="Settings" active defaultOpen>
    <SidebarItem active asChild><a href="#">General</a></SidebarItem>
    <SidebarItem asChild><a href="#">Members</a></SidebarItem>
    <SidebarItem asChild><a href="#">Billing</a></SidebarItem>
  </SidebarCollapsible>

  <SidebarCollapsible
    icon={<Stack />}
    label="Projects"
    actions={<Badge variant="secondary" size="sm">3</Badge>}
  >
    <SidebarItem asChild><a href="#">Koala UI</a></SidebarItem>
    <SidebarItem asChild><a href="#">Marketing site</a></SidebarItem>
  </SidebarCollapsible>
</SidebarGroup>
```

## Collapsible sections

Pass `collapsible` to a `SidebarGroup` and its `SidebarGroupLabel` becomes a toggle with a caret. Wrap the rows in `SidebarGroupContent` so they fold beneath it. Use `defaultOpen` (or the controlled `open`/`onOpenChange` pair) to set the initial state. Unlike nested navigation, this folds a whole flat section rather than revealing sub-routes.

```tsx
<SidebarGroup collapsible defaultOpen aria-label="Favorites">
  <SidebarGroupLabel>Favorites</SidebarGroupLabel>
  <SidebarGroupContent>
    <SidebarItem><Dot className="bg-purple" /> Q3 Roadmap</SidebarItem>
    <SidebarItem><Dot className="bg-teal" /> Design System</SidebarItem>
  </SidebarGroupContent>
</SidebarGroup>

{/* starts folded */}
<SidebarGroup collapsible defaultOpen={false} aria-label="Workspace">
  <SidebarGroupLabel>Workspace</SidebarGroupLabel>
  <SidebarGroupContent>
    <SidebarItem><UsersThree /> Members</SidebarItem>
    <SidebarItem><GearSix /> Settings</SidebarItem>
  </SidebarGroupContent>
</SidebarGroup>
```

## Collapsed (icon rail)

The rail has two variants, driven by the same markup. The `default` is the full-width rail; `collapsed` shrinks it to a 48px icon-only column. Labels go `sr-only`, each row becomes a centered icon, the active row is marked with a left accent bar instead of a full chip, sections are divided by a short rule, and the switcher reduces to its leading visual. Give every `SidebarItem` a `label` so the collapsed row gets a hover tooltip and an accessible name, and mark secondary sections with `<SidebarGroup hideWhenCollapsed>` so they drop out of the rail rather than reducing to bare glyphs.

```tsx
{/* default: the full-width rail */}
<Sidebar aria-label="Main">…</Sidebar>

{/* collapsed: a 48px icon rail */}
<Sidebar collapsed aria-label="Main">
  <SidebarHeader>{/* switcher collapses to its leading tile */}</SidebarHeader>
  <SidebarContent>
    <SidebarGroup aria-label="Primary">
      {/* label drives the collapsed tooltip + accessible name */}
      <SidebarItem active label="Dashboard"><SquaresFour /> Dashboard</SidebarItem>
      <SidebarItem label="Inbox">
        <Tray /> Inbox
        <Badge variant="secondary" size="sm" className="ml-auto tabular-nums">8</Badge>
      </SidebarItem>
      <SidebarItem label="Projects"><Stack /> Projects</SidebarItem>
    </SidebarGroup>
    {/* secondary sections drop out of the rail */}
    <SidebarGroup aria-label="Favorites" hideWhenCollapsed>…</SidebarGroup>
  </SidebarContent>
  <SidebarFooter>{/* profile switcher */}</SidebarFooter>
</Sidebar>
```

## Docked (in an app shell)

A rail standing on its own is a card: it paints `bg-card` and a hairline against the content beside it. Inside an app shell it shouldn’t: the shell already owns the surface, and a second fill on top of it is the difference between a docked dashboard and a rail bolted onto one. So nesting a `Sidebar` in a [`LayoutSidebar`](https://www.koalaui.com/docs/components/layout.md) turns `docked` on for you: no fill, no hairline, and the width comes from the shell column, which is also what animates the collapse.

The same applies in `LayoutMobileSidebar`, where the drawer panel is the surface. Pass `docked` explicitly to force the treatment outside a `Layout`, or `docked={false}` to opt a rail out of the shell it sits in. Combined with `floating` below, the card treatment wins: that pair is the detached rail floating in the shell gutter.

```tsx title="docked.tsx"
<Layout>
  <LayoutSidebar>
    <Sidebar aria-label="Main">…</Sidebar>   {/* docked, no props needed */}
  </LayoutSidebar>
  <LayoutContent>…</LayoutContent>
</Layout>

{/* Standalone: keeps its own card surface and hairline */}
<Sidebar aria-label="Main">…</Sidebar>
```

## Floating (inset)

`floating` detaches the rail into an inset card: a full outline, a rounded radius concentric with the app shell, and a shadow that lifts it off the canvas, instead of a single edge hairline. Pair it with padding on the container (or the [Layout](https://www.koalaui.com/docs/components/layout.md) gutter) so it floats clear of the viewport edges.

```tsx
<div className="flex h-full bg-muted/30 p-3">
  <Sidebar floating aria-label="Main" className="w-60">…</Sidebar>
  <main className="flex-1">…</main>
</div>
```

## Right side

`side="right"` docks the rail against the right edge. The separating hairline flips to its left so it reads as an inspector/detail panel beside the main content. Everything else (switchers, sections, density) is symmetric.

```tsx
<div className="flex h-full">
  <main className="flex-1">…</main>
  <Sidebar side="right" aria-label="Details" className="w-60">…</Sidebar>
</div>
```

## Density

`density` on `Sidebar` flows through context to the zone padding, the inter-section gap, the row height, and the switcher padding. `compact` is the default (app UI); `comfortable` is roomier. Set it once here or for a whole subtree with `DensityProvider`. See [Density](https://www.koalaui.com/docs/foundations/density.md).

```tsx
<Sidebar density="comfortable" aria-label="Main">…</Sidebar>
```

## FAQ

### How do I wire a workspace or profile switcher?

`SidebarSwitcher` is one trigger that renders a real `<button>`, so drop it into a `DropdownMenuTrigger asChild` and Radix owns the keyboard, focus, and ARIA. Use it in `SidebarHeader` for the workspace switcher (menu opens down) and in `SidebarFooter` for the profile switcher (menu opens up).

### What is the difference between SidebarCollapsible and a collapsible SidebarGroup?

`SidebarCollapsible` folds a sub-list of routes under a parent row, revealing nested navigation with a guide rail. Passing `collapsible` to a `SidebarGroup` turns its `SidebarGroupLabel` into a toggle that folds a whole flat section (wrap the rows in `SidebarGroupContent`). Use the first for sub-routes, the second to collapse a section.

### How do I mark the current page?

Set `active` on the `SidebarItem`: it fills the row and sets `aria-current="page"`. On a `SidebarCollapsible` parent, set `active` when one of its child routes is current.

### Should a SidebarItem be a button or a link?

It is a `<button>` by default; pass `asChild` and wrap an `<a>` or a Next `<Link>` to make it a real navigation link while keeping the row styling.

### How do I get the colored icon tiles?

Replace the row's bare leading glyph with a `SidebarItemIcon` wrapping a single icon, and pass a `tone` (`purple`, `pink`, `teal`, `orange`, `green`, `blue`, `red`, `amber`, or `brand`). It renders a soft hue-tinted rounded square that scales with density and becomes the centered chip when the rail is collapsed. It's decorative, so the active row still reads through the neutral chip and brand bar.

### Why does my rail look like a card sitting on the dashboard?

Because it is one when it stands alone: a standalone `Sidebar` paints `bg-card` and a hairline. Nest it in a `LayoutSidebar` and it docks automatically, dropping both so the shell owns the surface. Outside a `Layout`, pass `docked` to force the same treatment; inside one, `docked={false}` opts back out.

### What do I need for the collapsed icon rail?

Inside a `Layout` you need nothing: the shell owns the state (`LayoutSidebarTrigger` or ⌘B) and the rail inherits it. Standalone, pass `collapsed` to the `Sidebar` to shrink it to a 48px icon-only column. Give every `SidebarItem` a `label` so the collapsed row gets a hover tooltip and an accessible name, and mark secondary sections with `<SidebarGroup hideWhenCollapsed>` so they drop out rather than reducing to bare glyphs.

### What do floating and side='right' change?

`floating` detaches the rail into an inset card with a full outline, concentric radius, and a lifted shadow (pair it with container padding). `side="right"` docks the rail to the right edge and flips the separating hairline to its left so it reads as an inspector panel.

---

<!-- https://www.koalaui.com/docs/components/signature.md -->

# Signature

A handwritten signature that writes itself, stroke by stroke, at the pace a hand signs. Close a letter, a testimonial or a hero with it, or sign a Signature Pad and play the hand back.

```tsx
<span>Sincerely,</span>
<Signature viewBox="0 0 166 70" size="lg" aria-label="The Atelier team">
  <path d="M2 55.7C15 43.7 34.5 13.7 43 3.7C45.7 0.7 47.5 1.7 46.5 5.7C42.5 21.7 39.5 41.7 40.5 53.7C41.5 57.7 46.5 53.7 50 47.7C54.5 37.7 60 23.7 65 11.7C62 23.7 55.5 41.7 55 51.7C55 55.7 60 55.7 64.5 49.7C68.5 45.7 76 39.7 74.7 36.7C73.5 33.7 66.5 37.7 65.5 45.7C64.5 53.7 70 55.7 77.5 49.7C85.5 41.7 97 19.7 98 7.7C98.5 1.7 92 3.7 89.5 13.7C86 27.7 83 43.7 83 51.7C83 55.7 88 55.7 92.5 49.7C95.5 45.7 97.5 41.7 98.5 37.7C97 43.7 95.5 49.7 96.7 52.7C98 55.7 102.5 53.7 106.7 48.7C110.7 44.7 118 39.7 116.7 36.7C115.5 33.7 108.5 37.7 107.5 45.7C106.5 53.7 112 55.7 119.5 49.7C122.2 46.7 124.5 41.7 125.5 37.7C127 39.7 129 39.7 131.5 37.7C130 43.7 129.5 49.7 130.5 53.7C132 55.7 139.5 49.7 147.5 41.7" />
  <path d="M21.5 33.7C36.2 30.7 55.2 26.7 74 23.7" />
  <path d="M102 27.7C103.1 27.2 104.2 26.7 105.4 26.2" />
  <path d="M7 67.7C36.3 62.7 96.8 60.7 141.8 56.7C150 55.7 157.7 52.7 164 47.7" />
</Signature>
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add signature
```

Manual: run `npm install radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/signature/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

```tsx title="usage.tsx"
import { Signature } from "@/components/ui/signature"

export function Example() {
  return (
    <Signature viewBox="0 0 166 70" aria-label="The Atelier team">
      <path d="M2 55.7C15 43.7 …" />
      <path d="M21.5 33.7C36.2 30.7 …" />
    </Signature>
  )
}
```

One `<path>` per pen stroke, in the order they were written: the word, the bar across the t, the dot on the i, the underline. The pen is the component's, so a path needs nothing but its `d`; ink, weight and round ends override whatever an SVG export wrote on it.

## Draw your own

Sign the pad, pick a speed and a size, and the Signature beside it writes your hand back. Every stroke you add plays the whole signature again, and the snippet under it is that exact drawing, ready to paste. Clear the pad to start from a blank page.

## Speeds

The whole signature takes the same time at a given `speed` however long the hand is, each stroke getting its share by length, so the pen keeps one pace and a short dot never crawls. `base` is a person signing without hurry; `fast` is for a small mark that should not hold up the page; `slow` is for a hero moment where the writing is the show. `delay` holds the pen for that many ms once the signature is on screen, so it can wait for whatever enters before it.

```tsx
<Signature speed="fast" viewBox="0 0 121 75" aria-label="Maya Chen">…</Signature>
<Signature viewBox="0 0 121 75" aria-label="Maya Chen">…</Signature>
<Signature speed="slow" viewBox="0 0 121 75" aria-label="Maya Chen">…</Signature>
```

## Sizes

`size` sets the height and the nib together: a small signature writes with a finer pen, so it keeps the weight of handwriting instead of turning into a marker line. The width follows the drawing. For any other height, pass an `h-*` class; the nib keeps its weight on screen however far the drawing is scaled.

```tsx
<Signature size="sm" viewBox="0 0 166 70" aria-label="The Atelier team">…</Signature>
<Signature viewBox="0 0 166 70" aria-label="The Atelier team">…</Signature>
<Signature size="lg" viewBox="0 0 166 70" aria-label="The Atelier team">…</Signature>
```

## In a testimonial

The signature is an image with a name, so it drops into any stack: between a [Testimonial](https://www.koalaui.com/docs/components/testimonials.md)'s quote and its byline, under a founder's letter, or as the last line of a Hero's sign-off. It hugs its drawing and follows its parent's alignment, so it sits left in a left-aligned card and centred in a centred one.

```tsx
<Testimonial variant="outline">
  <TestimonialQuote>We rebuilt the whole site in a week…</TestimonialQuote>
  <Signature size="sm" delay={200} viewBox="0 0 121 75" aria-label="Maya Chen">…</Signature>
  <TestimonialFooter>
    <TestimonialAuthor>
      <TestimonialName>Maya Chen</TestimonialName>
      <TestimonialTitle>Founder, Northwind</TestimonialTitle>
    </TestimonialAuthor>
  </TestimonialFooter>
</Testimonial>
```

## Already signed

`static` renders the finished signature with no writing: a signed document in a list, a receipt, anywhere the moment of signing has passed. It is also what everyone sees under `prefers-reduced-motion`, with or without the prop.

```tsx
<Signature static size="sm" viewBox="0 0 121 75" aria-label="Maya Chen">…</Signature>
<p>Signed by Maya Chen on 12 September 2026</p>
```

## API reference

### Signature

An `<svg role="img">` whose children are the strokes. Props: `aria-label` (required: what the signature says), `viewBox` (the drawing's box; leave it out and the signature fits itself to its ink on the client), `size` (`sm` · `md` · `lg`), `speed` (`fast` · `base` · `slow`), `delay` (ms, once on screen), `static`, plus every SVG prop. The ink is `currentColor`, so a `text-*` class recolours it; `className` is merged last.

### Timing

The three speeds live in `signatureDraw` in `lib/motion.ts`: the duration of the whole signature and the pause between two strokes, per speed. The writing starts when a tenth of the signature is on screen and runs once; give it a new `key` to write it again.

## FAQ

### How do I get the paths for my own signature?

Sign the pad in Draw your own above and copy the snippet, or use a Signature Pad in your own app. From Figma or Illustrator, export the signature as open strokes, one per pen stroke. An outlined (filled) signature has no centre line for the pen to follow.

### Why does it need an aria-label?

To a screen reader the drawing is an image, and an image of a signature with no name reads as nothing. The label is what the signature says ("Maya Chen", "The Atelier team"), and it is read out in its place.

### Why pass a viewBox if it can fit itself?

Fitting happens on the client, after the drawing is measured, so the width settles a moment after the page loads. With a viewBox the signature takes its exact width from the first paint and nothing around it moves.

### Does it wait until it is on screen?

Yes. A signature further down the page writes itself when a tenth of it scrolls into view, the same gate every entrance in Koala uses, and then only once.

### Can I change the ink colour?

The ink is currentColor, so any text colour class recolours it: text-muted-foreground for a quieter mark, or your own colour for a pen that is not black.

---

<!-- https://www.koalaui.com/docs/components/signature-pad.md -->

# Signature Pad

A page to sign on with a mouse, a finger or a stylus. It keeps each pen stroke as a smooth SVG path, in writing order, so a Signature can play the hand back and a form can submit it.

```tsx
<Field>
  <FieldLabel>Signature</FieldLabel>
  <SignaturePad>
    <SignaturePadActions>
      <SignaturePadUndo />
      <SignaturePadClear />
    </SignaturePadActions>
  </SignaturePad>
  <FieldHint>Sign with your mouse, a finger or a stylus.</FieldHint>
</Field>
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add signature-pad
```

Manual: run `npm install radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/signature-pad/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

```tsx title="usage.tsx"
import {
  SignaturePad,
  SignaturePadActions,
  SignaturePadUndo,
  SignaturePadClear,
} from "@/components/ui/signature-pad"

export function Example() {
  const [strokes, setStrokes] = React.useState<string[]>([])
  return (
    <SignaturePad value={strokes} onValueChange={setStrokes}>
      <SignaturePadActions>
        <SignaturePadUndo />
        <SignaturePadClear />
      </SignaturePadActions>
    </SignaturePad>
  )
}
```

## Play it back

The value is one SVG path per stroke, in the order the hand wrote them, which is exactly what a [Signature](https://www.koalaui.com/docs/components/signature.md) takes as its children. `signatureViewBox(strokes)` gives it the box around the ink, so it takes its width from the first paint. The Signature page has the full playground, with every speed and size.

```tsx
const [strokes, setStrokes] = React.useState<string[]>([])

<SignaturePad value={strokes} onValueChange={setStrokes}>…</SignaturePad>

<Signature key={strokes.length} viewBox={signatureViewBox(strokes)} speed="fast" aria-label="Your signature">
  {strokes.map((d, i) => <path key={i} d={d} />)}
</Signature>
```

## States

Inside a [Field](https://www.koalaui.com/docs/components/field.md), the pad takes the field's label and hint as its name and description, and its `hasError` and `disabled` cascade in, the same as an Input. An error paints the frame; a disabled pad keeps its signature on show but no longer takes the pen or offers Undo and Clear. Both props can also be set on the pad itself. Focus works like any field's: the first stroke focuses the pad, and it stays lit through every lift of the pen and every Undo until you click away, so a signature of five strokes does not blink five times. While it has focus, `Ctrl` / `⌘` + `Z` takes back the last stroke.

```tsx
<Field hasError required>
  <FieldLabel>Signature</FieldLabel>
  <SignaturePad>…</SignaturePad>
  <FieldHint>Sign to accept the agreement.</FieldHint>
</Field>

<Field disabled>
  <FieldLabel>Signature</FieldLabel>
  <SignaturePad defaultValue={strokes}>…</SignaturePad>
  <FieldHint>Signed on 12 September 2026. The agreement is locked.</FieldHint>
</Field>
```

## Without actions

Undo and Clear are parts, not props: leave `SignaturePadActions` out and the pad is only a page, for an initial box or a flow that clears it some other way. With them in, they stay hidden until there is a stroke to take back. `placeholder` replaces the line under the empty page.

```tsx
<SignaturePad placeholder="Initial here" />
```

## In a form

With a `name`, the pad submits the drawing as a standalone SVG document, its ink in `currentColor`: store it, email it, or render it back. Sign, then submit, to see exactly what the form receives. `signatureToSvg(strokes)` builds the same document from a controlled value.

```tsx
<form action={submit}>
  <Field>
    <FieldLabel>Signature</FieldLabel>
    <SignaturePad name="signature">…</SignaturePad>
  </Field>
  <Button type="submit">Submit</Button>
</form>
```

## API reference

### SignaturePad

A `<div role="group" tabIndex={-1}>` framing the page, focused by the pen (the keyboard's tab stops are Undo and Clear). Props: `value` / `defaultValue` (`string[]`, one SVG path per stroke), `onValueChange` (called when a stroke lands, and on undo and clear), `name` (submits the SVG), `placeholder` (default "Sign here"), `hasError`, `disabled`, plus every div prop. Its height is 160px; give it an `h-*` class for another. `className` is merged last.

### SignaturePadActions · SignaturePadUndo · SignaturePadClear

The top-right corner and its two ghost `Button`s. Undo takes back the last stroke, Clear wipes the page; both are disabled while the pad is empty and pass every Button prop through, so `children` relabels them.

### signatureViewBox · signatureToSvg

`signatureViewBox(strokes, padding?)` returns the box around the ink as a `viewBox` string. `signatureToSvg(strokes)` returns the drawing as an SVG document, the value the pad submits.

## FAQ

### What does the value look like?

An array of strings, one SVG path per pen stroke in the order it was written, each a smooth curve through the points the pen touched. It is small, it is plain text, and a Signature renders it as it is.

### Does it work on phones and tablets?

Yes. It follows pointer events, so a mouse, a finger and a stylus all sign the same way, and it stops a finger from scrolling the page while it signs. A fast flourish keeps its curve, because every sample the browser collects between frames is used.

### Is drawing a signature accessible?

The pad is named by its field and announces when it has been signed, and Undo and Clear are ordinary buttons. Drawing itself needs a pointer, so where a signature is required, offer another way to sign too, such as typing the full name.

### Can I resize it?

The pad takes the full width of its container and is 160px tall; an h-* class sets another height. Strokes keep the position they were drawn at, so resize before signing, not after.

---

<!-- https://www.koalaui.com/docs/components/skeleton.md -->

# Skeleton

A loading placeholder that mirrors the shape of the content it stands in for. Single-element like Badge; the fill is a semantic token, so it re-themes everywhere, and the optional shimmer rides the shared motion tokens.

```tsx
<div className="flex w-full max-w-sm items-center gap-4">
  <Skeleton variant="circle" className="size-12" />
  <div className="flex-1 space-y-2.5">
    <Skeleton variant="text" className="w-1/2" />
    <Skeleton variant="text" />
  </div>
</div>
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add skeleton
```

Manual: run `npm install radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/skeleton/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

```tsx title="usage.tsx"
import { Skeleton } from "@/components/ui/skeleton"

export function Example() {
  return <Skeleton className="h-8 w-48" />
}
```

## Variants

Three shapes cover most placeholders. `rectangle` is the default block; `circle` takes a single `size-*` for avatars and icons; and `text` matches the surrounding line-height exactly via the `1lh` unit.

```tsx
<Skeleton variant="rectangle" className="h-16 w-24" />
<Skeleton variant="circle" className="size-16" />
<Skeleton variant="text" className="w-40" />
```

## Multi-line text

Pass `lines` with `variant="text"` to render a paragraph-shaped block. The last line wraps short, the way real running text does.

```tsx
<Skeleton variant="text" lines={4} className="max-w-md" />
```

## Animation

`pulse` (the default) breathes opacity; `shimmer` sweeps a highlight driven by the `--animate-shimmer` motion token; and `none` holds a static placeholder. All three stop under `prefers-reduced-motion`.

```tsx
<Skeleton animation="pulse" className="h-10 w-28" />
<Skeleton animation="shimmer" className="h-10 w-28" />
<Skeleton animation="none" className="h-10 w-28" />
```

## Composition

Skeletons are layout primitives; compose them to trace the real content. Wrap the loading region in `aria-busy="true"` so the placeholders (each `aria-hidden`) stay silent to screen readers while one status is announced for the whole region.

```tsx
<div aria-busy="true" className="w-full max-w-sm rounded-xl border border-border p-4">
  <Skeleton variant="rectangle" className="aspect-[2/1] w-full rounded-lg" />
  <div className="mt-4 space-y-2.5">
    <Skeleton variant="text" className="w-2/3" />
    <Skeleton variant="text" lines={2} />
  </div>
  <div className="mt-4 flex items-center gap-3">
    <Skeleton variant="circle" className="size-9" />
    <Skeleton variant="text" className="w-24" />
  </div>
</div>
```

## FAQ

### When should I reach for a Skeleton instead of a spinner?

Use a Skeleton when you know the shape of the content that is loading, like a card or a list row, so the layout stays stable and there is no jump when the data arrives. A spinner is better for indeterminate, full-page waits where the eventual layout is unknown.

### What is the difference between the rectangle, circle, and text variants?

`rectangle` is the default block (pair it with width/height via `className`); `circle` is aspect-square so a single `size-*` reads as a round avatar placeholder; and `text` is `h-[1lh]` so it matches the surrounding line-height exactly.

### How do I render a multi-line paragraph placeholder?

Pass `lines` together with `variant="text"` to stack that many lines, with the last one shortened the way real running text wraps. The prop is ignored for other variants and for `lines <= 1`.

### Which animation should I pick, and does it respect reduced motion?

`pulse` (the default) breathes opacity, `shimmer` sweeps a highlight via the `--animate-shimmer` token, and `none` holds static. All three stop automatically under `prefers-reduced-motion`.

### How do I keep skeletons quiet for screen readers?

Every Skeleton element is already `aria-hidden`, so wrap the loading region in `aria-busy="true"` and announce one status for the whole region rather than letting each placeholder shout.

---

<!-- https://www.koalaui.com/docs/components/slider.md -->

# Slider

Pick a value or a range by dragging along a track. Built on Radix Slider: thumbs auto-render from the value array, with an optional live bubble and full keyboard support. SliderInput pairs a rail with a number.

```tsx
<Slider
  defaultValue={[60]}
  variant="brand"
  tooltip
  formatValue={(v) => `${v}%`}
  aria-label="Brightness"
/>
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add slider
```

Manual: run `npm install radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/slider/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

```tsx title="usage.tsx"
import { Slider } from "@/components/ui/slider"

export function Example() {
  return <Slider defaultValue={[60]} aria-label="Volume" />
}
```

## Sizes

Three sizes scale the track thickness and thumb diameter together: `sm`, `md` (default), and `lg`.

```tsx
<Slider size="sm" defaultValue={[50]} />
<Slider size="md" defaultValue={[50]} />
<Slider size="lg" defaultValue={[50]} />
```

## Variants

The `variant` tints the range, thumb border, and tooltip as one. `default` uses the form-control primary; `brand` picks up the active accent; and the status fills carry domain meaning.

```tsx
<Slider variant="default" defaultValue={[55]} />
<Slider variant="brand" defaultValue={[55]} />
<Slider variant="success" defaultValue={[55]} />
<Slider variant="warning" defaultValue={[55]} />
<Slider variant="destructive" defaultValue={[55]} />
```

## Range

Pass two values and you get a two-thumb range, no extra component. Each thumb drags independently and carries its own value bubble.

```tsx
<Slider
  defaultValue={[25, 75]}
  variant="brand"
  tooltip
  formatValue={(v) => `$${v}`}
  aria-label="Price range"
/>
```

## Steps

`step` snaps the thumb to discrete stops. Pair it with `min`/`max` and your own labels for a scaled control.

```tsx
<Slider defaultValue={[3]} min={0} max={5} step={1} tooltip aria-label="Rating" />
```

## Vertical

Set `orientation="vertical"` and give the root a height. The same recipe styles both axes via `data-orientation`.

```tsx
<Slider
  orientation="vertical"
  defaultValue={[70]}
  variant="brand"
  className="h-40"
/>
```

## Square

`shape="square"` squares the rail and gives the thumb a fader-cap profile; corners stay concentric with the rail.

```tsx
<Slider shape="square" defaultValue={[60]} />
<Slider shape="square" size="lg" variant="brand" defaultValue={[40]} />
```

## Equalizer

Square + vertical turns the slider into a fader. A row of them reads as an equalizer; each is an independent control.

```tsx
const bands = ["60", "150", "400", "1k", "2.4k", "6k", "15k"]

<div className="flex items-end gap-5">
  {bands.map((label) => (
    <div key={label} className="flex flex-col items-center gap-3">
      <Slider
        orientation="vertical"
        shape="square"
        variant="brand"
        defaultValue={[50]}
        className="h-40"
        aria-label={`${label} Hz`}
      />
      <span className="text-xs tabular-nums text-muted-foreground">{label}</span>
    </div>
  ))}
</div>
```

## Disabled

`disabled` dims the whole control and stops all interaction.

```tsx
<Slider defaultValue={[40]} disabled />
```

## Controlled

Drive the slider from state with `value` and `onValueChange` (both arrays), or leave it uncontrolled with `defaultValue`.

```tsx
const [value, setValue] = useState([35])

<Slider value={value} onValueChange={setValue} aria-label="Volume" />
```

## In a settings card

The common shell: a labelled row with the live value trailing, the slider beneath.

```tsx
const [value, setValue] = useState([72])

<div className="rounded-xl border border-border p-4">
  <div className="mb-3 flex items-center justify-between">
    <span className="flex items-center gap-2 text-sm font-medium">
      <Sun className="size-4 text-muted-foreground" />
      Brightness
    </span>
    <span className="text-sm tabular-nums text-muted-foreground">{value[0]}%</span>
  </div>
  <Slider value={value} onValueChange={setValue} variant="brand" />
</div>
```

## Slider input

`SliderInput` is the inspector slider: an editable number box beside a slim rail with a pill thumb, the pair you find in video, design and audio tools. The rail opens to the full control height while hovered, dragged or focused. It edits one number (not an array), and the row shares the 32/36/40 height scale with Input, so a column of them lines up with the rest of a panel.

- Click or drag anywhere on the track; arrows, Shift+arrows, Home and End work once it has focus.
- Drag sideways on the number box to scrub it. A plain click edits it with the number selected.
- While typing, arrows step (Shift steps ×10), Enter commits and Escape reverts. Out-of-range input clamps and snaps to `step` on commit.
- Inside a `Field` the label focuses the box and names the thumb, no wiring needed.
- Drag past either end and the rail stretches a few pixels, then eases back on release (not with reduced motion).

```tsx
import { Field, FieldLabel } from "@/components/ui/field"
import { SliderInput, SliderInputTrack, SliderInputValue } from "@/components/ui/slider"

<Field className="grid grid-cols-[5.5rem_minmax(0,1fr)] items-center gap-3">
  <FieldLabel className="font-normal text-muted-foreground">Feather</FieldLabel>
  <SliderInput defaultValue={0} />
</Field>

<Field className="grid grid-cols-[5.5rem_minmax(0,1fr)] items-center gap-3">
  <FieldLabel className="font-normal text-muted-foreground">Opacity</FieldLabel>
  <SliderInput defaultValue={80}>
    <SliderInputValue suffix="%" />
    <SliderInputTrack />
  </SliderInput>
</Field>
```

## Slider input sizes

`size` sets the height, the same scale as every form control: `sm` 32px, `md` 36px and `lg` 40px. Unsized, it follows density the way Input does. Typed text stays 14px at every size.

```tsx
<SliderInput size="sm" defaultValue={50} aria-label="Size sm" />
<SliderInput size="md" defaultValue={50} aria-label="Size md" />
<SliderInput size="lg" defaultValue={50} aria-label="Size lg" />
```

## Slider input variants

`default` keeps the fill and pill neutral, because an inspector is a wall of these and colour on every row would shout. `brand` tints them with the accent for the one setting that matters.

```tsx
<SliderInput defaultValue={40} aria-label="Default" />
<SliderInput variant="brand" defaultValue={65} aria-label="Brand" />
```

## Only the parts you need

With no children the root renders both halves. Compose `SliderInputValue` and `SliderInputTrack` yourself to add a `suffix` unit, or drop either one: the track alone is a compact fader, the box alone a scrubbable number.

```tsx
// Both (the default when no children are passed)
<SliderInput defaultValue={30} aria-label="Both parts" />

// Track only: a compact fader
<SliderInput defaultValue={30} aria-label="Track only">
  <SliderInputTrack />
</SliderInput>

// Value only: a scrubbable number
<SliderInput defaultValue={30} aria-label="Value only">
  <SliderInputValue suffix="%" />
</SliderInput>
```

## Label inside the track

Give `SliderInputTrack` children and the track becomes the field, the slider you find in generation panels. `SliderInputLabel` sits inside on the left and `SliderInputValue` turns into a read-only readout on the right, while the fill paints as a raised chip that ends at the pill. Drag anywhere on it.

- The text insets match Input's side padding, so a column of these lines up with the inputs and selects around it.
- The pill fades while it passes under the label or the readout, and `ticks` fade out around the text.
- Name the stops of a discrete scale with `formatValue` on the root: the readout shows the name and the thumb announces it.
- Both parts are optional. A label alone or a readout alone is still a field.

```tsx
import {
  SliderInput,
  SliderInputLabel,
  SliderInputTrack,
  SliderInputValue,
} from "@/components/ui/slider"

const RESOLUTIONS = ["720p", "1080p", "1440p", "4K"]

<SliderInput defaultValue={1} max={3} formatValue={(v) => RESOLUTIONS[v]}>
  <SliderInputTrack ticks>
    <SliderInputLabel>Resolution</SliderInputLabel>
    <SliderInputValue />
  </SliderInputTrack>
</SliderInput>

<SliderInput defaultValue={6} min={2} max={10}>
  <SliderInputTrack ticks>
    <SliderInputLabel>Duration</SliderInputLabel>
    <SliderInputValue suffix="s" />
  </SliderInputTrack>
</SliderInput>

<SliderInput defaultValue={60} step={10}>
  <SliderInputTrack ticks>
    <SliderInputLabel>Motion</SliderInputLabel>
    <SliderInputValue suffix="%" />
  </SliderInputTrack>
</SliderInput>

<SliderInput defaultValue={7.5} max={20} step={0.5}>
  <SliderInputTrack>
    <SliderInputLabel>Guidance</SliderInputLabel>
    <SliderInputValue />
  </SliderInputTrack>
</SliderInput>
```

## Label inside: sizes and variants

The field layout keeps the same `size` and `variant`. Inside a field the pill stays a quiet grey next to the text, and `brand` tints the chip and the pill.

```tsx
<SliderInput size="sm" defaultValue={50}>
  <SliderInputTrack>
    <SliderInputLabel>Small</SliderInputLabel>
    <SliderInputValue suffix="%" />
  </SliderInputTrack>
</SliderInput>

// size="md" (default) and size="lg" work the same way

<SliderInput variant="brand" defaultValue={70}>
  <SliderInputTrack>
    <SliderInputLabel>Brand</SliderInputLabel>
    <SliderInputValue suffix="%" />
  </SliderInputTrack>
</SliderInput>
```

## Ticks

`ticks` on the track marks the stops: `true` for one at every `step`, or a number for one every that many units. The ends get no mark, since the rail's edges already show them. Inside the fill, marks only show while the track is hovered, dragged or focused. Past 64 marks none are drawn.

```tsx
// One mark per step
<SliderInput defaultValue={3} max={8} aria-label="Every step">
  <SliderInputValue />
  <SliderInputTrack ticks />
</SliderInput>

// One mark every 25 units
<SliderInput defaultValue={40} aria-label="Every 25">
  <SliderInputValue suffix="%" />
  <SliderInputTrack ticks={25} />
</SliderInput>

// In the field layout, marks fade out around the text
<SliderInput defaultValue={40}>
  <SliderInputTrack ticks={10}>
    <SliderInputLabel>Every 10</SliderInputLabel>
    <SliderInputValue suffix="%" />
  </SliderInputTrack>
</SliderInput>
```

## Decimal steps

The box shows as many decimals as `step` has, and everything you type or scrub snaps to that grid. Drive it with `value` and `onValueChange` (plain numbers); `onValueCommit` fires once when a drag, scrub or edit ends.

```tsx
const [value, setValue] = useState(1.25)

<SliderInput
  value={value}
  onValueChange={setValue}
  min={0.25}
  max={4}
  step={0.05}
  variant="brand"
  aria-label="Playback speed"
>
  <SliderInputValue suffix="×" />
  <SliderInputTrack />
</SliderInput>
```

## Slider input disabled

`disabled` (or a disabled `Field`) dims both halves together and stops every interaction.

```tsx
<SliderInput defaultValue={24} disabled aria-label="Feather" />
```

## FAQ

### How do I make a two-thumb range slider?

There is no separate component: pass two values like `defaultValue={[25, 75]}` and the thumbs auto-render from the array, each dragging independently with its own value bubble.

### What does the tooltip prop do, and how do I format the value?

`tooltip` shows a value bubble above each thumb on hover, focus, and while dragging. Pass `formatValue`, for example `(v) => `$${v}``, to format the number that appears.

### Controlled or uncontrolled: which props drive the value?

For controlled use `value` and `onValueChange` (both arrays); for uncontrolled use `defaultValue`. Mixing a `value` without `onValueChange` will freeze the thumb.

### How do I render a vertical slider or an equalizer fader?

Set `orientation="vertical"` and give the root an explicit height like `className="h-40"`. Add `shape="square"` for a fader-cap profile, and a row of those reads as an equalizer.

### What does the variant prop control?

`variant` tints the filled range, the thumb border, and the tooltip together as one accent: `default` is the form-control primary, `brand` is the active accent, and `success`/`warning`/`destructive` carry status meaning. The focus ring stays the brand accent regardless.

### When should I use SliderInput instead of Slider?

Use `Slider` for settings and filters where a thin rail and an optional value bubble are enough, ranges included. Use `SliderInput` in editors and inspectors, where people need to read and type the exact number as well as drag it.

### How do I show a unit like % or px next to the number?

Compose the parts and pass `suffix` to the box: `<SliderInputValue suffix="%" />`. The unit is painted muted after the number and is never part of what gets typed or submitted.

### How do I put the label and the value inside the slider?

Pass them as children of the track: `<SliderInputTrack><SliderInputLabel>Strength</SliderInputLabel><SliderInputValue suffix="%" /></SliderInputTrack>`. The track becomes a full-height field and the value becomes a read-only readout. `SliderInputLabel` also names the thumb for screen readers.

### How do I make a slider with named stops, like 720p / 1080p / 4K?

Use indexes as the value (`min={0} max={3}`) and name them with `formatValue` on the root: `formatValue={(v) => RESOLUTIONS[v]}`. The readout shows the name and the thumb announces it. Add `ticks` to the track to mark each stop.

### How is accessibility handled, and what about the small thumb hit area?

Radix Slider provides full arrow-key support and ARIA, so always pass an `aria-label`. The thumb also carries a centered 40x40 pseudo-element so the small visual still hits a comfortable drag target.

---

<!-- https://www.koalaui.com/docs/components/spinner.md -->

# Spinner

The one loading glyph in the system. It takes its size from whatever holds it and its color from the text around it, and it is announced once, never twice.

```tsx
<Button loading>Save changes</Button>
<Badge variant="secondary"><Spinner aria-hidden /> Syncing</Badge>
<Spinner className="text-muted-foreground" />
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add spinner
```

Manual: run `npm install radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/spinner/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

```tsx title="usage.tsx"
import { Spinner } from "@/components/ui/spinner"

export function Example() {
  return <Spinner />
}
```

## Follows its host

With no `size`, the spinner carries no size class, so the component holding it decides: 16px in a Button or an input, 14px in a Badge, the same box every other icon in that slot gets. Outside any host it is `1em`, so it scales with the text beside it.

```tsx
<Button size="sm" loading>Save</Button>
<Button loading>Save</Button>
<Button size="lg" loading>Save</Button>
<Badge variant="secondary"><Spinner aria-hidden /> Syncing</Badge>
<InputRoot className="max-w-64">
  <InputPrefix><MagnifyingGlass weight="bold" /></InputPrefix>
  <InputField placeholder="Search components" aria-label="Search components" />
  <InputSuffix><Spinner aria-hidden /></InputSuffix>
</InputRoot>
```

## Sizes

Pin a size when there is no host rule to follow: `sm` 14px, `md` 16px, `lg` 20px, and `xl` 40px for an overlay such as a video buffering or a panel loading.

```tsx
<Spinner size="sm" />
<Spinner size="md" />
<Spinner size="lg" />
<Spinner size="xl" />
```

## Color

The ring is `currentColor`, so it is whatever text color it sits in. Set it with a text utility, never a fill.

```tsx
<Spinner size="lg" className="text-muted-foreground" />
<Spinner size="lg" className="text-brand" />
<span className="rounded-lg bg-foreground p-3 text-background">
  <Spinner size="lg" />
</span>
```

## Accessibility

On its own the spinner is a `status` named “Loading”; give it a precise name with `label`. When the element around it already says it is busy (a Button with `loading`, a row that reads “Loading more results”), pass `aria-hidden`: the role and the name are dropped, so the state is announced once. Under reduced motion the ring stops turning and stays on screen, which still reads as in progress.

```tsx
<Spinner label="Uploading avatar" />
<p className="flex items-center gap-2 text-sm text-muted-foreground">
  <Spinner aria-hidden /> Loading more results
</p>
```

## API reference

- `size`: `sm` | `md` | `lg` | `xl`. Omit it to let the host size the glyph.
- `label`: the accessible name while announced. Defaults to “Loading”.
- `aria-hidden`: silences the spinner when its host already announces the busy state.
- Every other prop (`className`, SVG attributes) passes through to the Phosphor `CircleNotch` glyph it renders, with `className` merged last.

## FAQ

### When should I use a Spinner instead of a Skeleton?

Use a Skeleton when you know the shape of what is coming (a card, a table row) and want the layout to hold still while it loads. Use a Spinner for an action in flight whose result has no shape yet: a save, a search, an upload.

### Why doesn't a Button with loading need its own Spinner?

`loading` already renders one, centered over the label, and marks the button `aria-busy`. The spinner inside is `aria-hidden`, so the button is announced as busy once rather than as a button plus a separate status.

### How do I make it bigger or smaller?

Inside a component, don't: the host already gives it the right box. Anywhere else, pass `size` (`sm`, `md`, `lg` or `xl`). A `size-*` utility in `className` works too, since the host rule only fills in when no size class is present.

### What happens with reduced motion?

The ring stops turning (`motion-reduce:animate-none`) and stays visible. A still partial ring still reads as work in progress, so nothing else needs to change.

---

<!-- https://www.koalaui.com/docs/components/stepper.md -->

# Stepper

A progress indicator for sequential flows: onboarding, checkout and multi-step dialogs. Each step derives its state from a single active value, and the connecting line fills as you advance.

```tsx
const [step, setStep] = React.useState(1)

<Stepper value={step} onValueChange={setStep}>
  {["Your details", "Company", "Confirm"].map((title, i) => (
    <StepperItem key={title} step={i + 1}>
      <StepperTrigger>
        <StepperIndicator />
        <StepperTitle>{title}</StepperTitle>
      </StepperTrigger>
      {i < 2 && <StepperSeparator />}
    </StepperItem>
  ))}
</Stepper>

{/* drive setStep from your Back / Next buttons; give the primary one a
    swapKey so its label rolls when the flow reaches the last step */}
<Button swapKey={isLast ? "done" : "next"} onClick={next}>
  {isLast ? <><Check weight="bold" /> Done</> : <>Next <ArrowRight weight="bold" /></>}
</Button>
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add stepper
```

Manual: run `npm install radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/stepper/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

```tsx title="usage.tsx"
"use client"

import * as React from "react"
import {
  Stepper,
  StepperItem,
  StepperTrigger,
  StepperIndicator,
  StepperTitle,
  StepperSeparator,
} from "@/components/ui/stepper"

export function Example() {
  const [step, setStep] = React.useState(1)
  return (
    <Stepper value={step} onValueChange={setStep}>
      <StepperItem step={1}>
        <StepperTrigger>
          <StepperIndicator />
          <StepperTitle>Account</StepperTitle>
        </StepperTrigger>
        <StepperSeparator />
      </StepperItem>
      <StepperItem step={2}>
        <StepperTrigger>
          <StepperIndicator />
          <StepperTitle>Confirm</StepperTitle>
        </StepperTrigger>
      </StepperItem>
    </Stepper>
  )
}
```

## Orientation

Orientation is set on the root. `horizontal` lays steps in a row with a flexible connector; `vertical` stacks them with the connector running down the indicator column.

```tsx
<Stepper defaultValue={2}>
  <StepperItem step={1}>
    <StepperTrigger>
      <StepperIndicator />
      <StepperTitle>Cart</StepperTitle>
    </StepperTrigger>
    <StepperSeparator />
  </StepperItem>
  <StepperItem step={2}>
    <StepperTrigger>
      <StepperIndicator />
      <StepperTitle>Shipping</StepperTitle>
    </StepperTrigger>
    <StepperSeparator />
  </StepperItem>
  <StepperItem step={3}>
    <StepperTrigger>
      <StepperIndicator />
      <StepperTitle>Payment</StepperTitle>
    </StepperTrigger>
  </StepperItem>
</Stepper>

<Stepper defaultValue={2} orientation="vertical">
  {/* …same items… */}
</Stepper>
```

## With descriptions

Pair each `StepperTitle` with a `StepperDescription` in a vertical stack. Vertical orientation gives the supporting copy room to breathe.

```tsx
<Stepper defaultValue={2} orientation="vertical">
  <StepperItem step={1}>
    <StepperTrigger>
      <StepperIndicator />
      <span className="flex flex-col gap-0.5">
        <StepperTitle>Account</StepperTitle>
        <StepperDescription>Your login details</StepperDescription>
      </span>
    </StepperTrigger>
    <StepperSeparator />
  </StepperItem>
  {/* …more items… */}
</Stepper>
```

## Density

Density retunes the indicator size, connector geometry, and text, without touching color or radius. `comfortable` suits onboarding; `compact` fits dense app UI and dialogs.

```tsx
<Stepper defaultValue={2} density="comfortable">…</Stepper>
<Stepper defaultValue={2} density="compact">…</Stepper>
```

## Loading & disabled

Set `loading` on the active step to swap its number for a spinner while it validates or submits. Mark unreachable steps `disabled` to block selection and mute them.

```tsx
<Stepper defaultValue={2}>
  <StepperItem step={1}>…</StepperItem>
  <StepperItem step={2} loading>…</StepperItem>
  <StepperItem step={3} disabled>…</StepperItem>
</Stepper>
```

## In a dialog

The headline use case. Reach for `DialogStepper` (from `@/components/ui/dialog`). It places the stepper full-bleed with a divider beneath and inherits the dialog's density. Drive its `value` from the dialog's own step state and swap the body per step; future steps are `disabled` so the user can't skip ahead.

```tsx
const [step, setStep] = React.useState(1)

<DialogContent size="lg" density="compact">
  <DialogHeader>…</DialogHeader>

  <DialogStepper value={step} onValueChange={setStep}>
    {WIZARD.map((s, i) => (
      <StepperItem key={s.title} step={i + 1} disabled={i + 1 > step}>
        <StepperTrigger>
          <StepperIndicator />
          <StepperTitle>{s.title}</StepperTitle>
        </StepperTrigger>
        {i < WIZARD.length - 1 && <StepperSeparator />}
      </StepperItem>
    ))}
  </DialogStepper>

  {/* swap the body on `step`; Back/Next move setStep */}
  <DialogFooter className="sm:justify-between">…</DialogFooter>
</DialogContent>
```

## FAQ

### Do I need to track the active step myself?

Only if you want navigation. The Stepper is controllable: pass `value` and `onValueChange` to drive it from your Back and Next buttons, or use `defaultValue` for a static read-only progress indicator. Step numbers are 1-based.

### How does each StepperItem know if it is completed or active?

It derives that from the root's active value and its own 1-based `step` prop: a step is completed when it is below the active step, active when equal, and inactive otherwise. The state is published on `data-state` so the indicator, title, and separator restyle off it with no JS measurement.

### When should I use the loading and disabled props on a StepperItem?

Set `loading` on the active step to swap its number for a spinner while it validates or submits. Mark steps the user cannot reach yet `disabled` so their trigger is blocked and the step is muted, which is how you stop people skipping ahead in a wizard.

### Do I have to wrap each step in a StepperTrigger?

Only for navigable steppers. `StepperTrigger` is the clickable region that selects its step. For a pure read-only progress indicator, omit it and place `StepperIndicator` and `StepperTitle` directly in the item.

### What is the difference between the outline and solid variant?

`outline` (the default) is a quiet ringed circle with a brand halo on the active step. `solid` fills every state with a flat tone for the bolder Calendly-style rail used in larger multi-step wizards.

### How do I put a stepper in a dialog?

Reach for `DialogStepper` from `@/components/ui/dialog`. It places the stepper full-bleed with a divider beneath and inherits the dialog's density, so you only drive its `value` from the dialog's own step state.

---

<!-- https://www.koalaui.com/docs/components/switch.md -->

# Switch

A toggle for an instant, self-applying boolean, built on Radix Switch. Use it for settings that take effect immediately (notifications, airplane mode); reach for a Checkbox when the choice is submitted with a form.

```tsx
<label htmlFor="airplane" className="flex items-center gap-2.5">
  <Switch id="airplane" defaultChecked />
  Airplane mode
</label>
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add switch
```

Manual: run `npm install radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/switch/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

```tsx title="usage.tsx"
import { Switch } from "@/components/ui/switch"

export function Example() {
  return (
    <label htmlFor="airplane" className="flex items-center gap-2.5">
      <Switch id="airplane" defaultChecked />
      Airplane mode
    </label>
  )
}
```

## States

Off rests on the `input` fill; on slides the thumb across a `brand` (accent) track. The thumb carries a shadow so it reads on both states in every theme.

```tsx
<Switch checked={false} />
<Switch checked />
<Switch disabled />
<Switch disabled checked />
```

## Controlled

Drive the switch from state with `checked` and `onCheckedChange`, or leave it uncontrolled with `defaultChecked`.

```tsx
const [enabled, setEnabled] = useState(true)

<Switch checked={enabled} onCheckedChange={setEnabled} />
```

## In a settings list

The common shell: a label and description on the left, the switch trailing right. The whole row is the label, so the full width is the hit target.

```tsx
<label htmlFor="notifications" className="flex items-start gap-3 p-4">
  <BellSimple className="mt-0.5 size-5 shrink-0 text-muted-foreground" />
  <div className="flex flex-1 flex-col gap-0.5">
    <span className="text-sm font-medium leading-none">Push notifications</span>
    <span className="text-sm text-muted-foreground">
      Get notified when someone mentions you or replies to a thread.
    </span>
  </div>
  <Switch id="notifications" defaultChecked className="mt-0.5" />
</label>
```

## FAQ

### When should I use a Switch instead of a Checkbox?

Use a Switch for an instant, self-applying boolean that takes effect immediately, like notifications or airplane mode. Reach for a Checkbox when the choice is only submitted later with a form.

### How do I control a Switch from state?

Drive it with `checked` and `onCheckedChange`, both passed straight through to Radix Switch. Leave it uncontrolled with `defaultChecked` if you do not need to own the value.

### The Switch renders no label. How do I give it an accessible name?

It deliberately renders only the control, so wrap it in a `<label htmlFor>` matching the switch's `id`. That also makes the whole row a hit target, which is the pattern used in the settings list example.

### What does the static prop do?

It neutralizes the tactile scale-on-press animation (the `active:scale-[0.96]`) for places where that motion would distract. The visual track and thumb are unchanged.

### The track is only 20px tall. Is the tap target really that small?

No. A transparent pseudo-element extends the vertical click area to 40px without changing the visual, so the control stays comfortably tappable while looking compact.

---

<!-- https://www.koalaui.com/docs/components/table-of-contents.md -->

# Table of Contents

The on-this-page nav beside a long document. It marks the section being read as you scroll, with a bar that slides along a hairline track, and it needs nothing but the links themselves.

```tsx
const pane = React.useRef<HTMLDivElement>(null)

<div ref={pane} className="h-90 overflow-y-auto">
  <article>
    <h3 id="brief">The brief</h3>
    …
  </article>
</div>

<TableOfContents container={pane} defaultValue="brief">
  <TableOfContentsTitle>On this page</TableOfContentsTitle>
  <TableOfContentsList>
    <TableOfContentsItem href="#brief">The brief</TableOfContentsItem>
    <TableOfContentsItem href="#constraints">Constraints first</TableOfContentsItem>
    <TableOfContentsItem href="#signals">Signals over strings</TableOfContentsItem>
    <TableOfContentsItem href="#ranking">Ranking, not filtering</TableOfContentsItem>
    <TableOfContentsItem href="#shipping">Shipping it fast</TableOfContentsItem>
  </TableOfContentsList>
</TableOfContents>
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add table-of-contents
```

Manual: run `npm install radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/table-of-contents/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

```tsx title="usage.tsx"
import {
  TableOfContents,
  TableOfContentsTitle,
  TableOfContentsList,
  TableOfContentsItem,
} from "@/components/ui/table-of-contents"

<aside className="hidden lg:block">
  <TableOfContents className="sticky top-24">
    <TableOfContentsTitle>On this page</TableOfContentsTitle>
    <TableOfContentsList>
      {sections.map((section) => (
        <TableOfContentsItem key={section.id} href={`#${section.id}`}>
          {section.title}
        </TableOfContentsItem>
      ))}
    </TableOfContentsList>
  </TableOfContents>
</aside>
```

There is no list of ids to keep in step: each item registers the heading its `href` points at, and the nav watches those headings. Pin the rail yourself (`sticky` under your header) and give the headings a `scroll-margin-top` that clears that header, which the spy reads too. The items are plain anchors, so the jump, the URL hash and the back button stay the browser's; for a glide, set `scroll-behavior: smooth` on `html` behind `prefers-reduced-motion: no-preference`.

## Variants

Six looks over one behaviour, so switching is a prop, never a rewrite. Line is the default: a hairline track with a brand bar that slides to the section being read. Progress fills the same track from the top down to that section, so it also says how far in the reader is. Pill slides a soft chip behind the active row, the Sidebar's active fill, for a rail inside an app. Dash leads every row with a short rule that runs to full length on the active one. Plain marks it by ink and weight alone. Minimap rests as a column of dashes and opens into the list; it has its own section below. Click an item to move the mark.

```tsx
<TableOfContents>…</TableOfContents>                    {/* line (default) */}
<TableOfContents variant="progress">…</TableOfContents>
<TableOfContents variant="pill">…</TableOfContents>
<TableOfContents variant="dash">…</TableOfContents>
<TableOfContents variant="plain">…</TableOfContents>
<TableOfContents variant="minimap">…</TableOfContents>
```

## Minimap

The quietest rail: a column of dashes hung from the page's edge, one per section, subsections shorter, the one being read longer and in brand. It shows the shape of the document without a word of text. Hover it, or Tab into it, and the menu surface grows out of the column into the full list, clipped from its corner so the dashes swell into the panel instead of a popover appearing beside them. A mouse click on a link lets it close as soon as the pointer leaves; keyboard focus holds it open. The panel opens toward the content, so give the rail a column at the edge of the page.

```tsx
<div className="grid grid-cols-[minmax(0,1fr)_auto] gap-6">
  <article>…</article>
  <TableOfContents variant="minimap" className="sticky top-24 self-start">
    <TableOfContentsTitle>On this page</TableOfContentsTitle>
    <TableOfContentsList>
      <TableOfContentsItem href="#brief">The brief</TableOfContentsItem>
      …
    </TableOfContentsList>
  </TableOfContents>
</div>
```

## Levels

`level={3}` makes an item a subsection: it steps in 16px under its parent, and on the line variant the bar still runs down the same track, so the mark never jumps sideways between a section and its children. Two levels is the limit on purpose: a third reads as a sitemap, not a guide to the page.

```tsx
<TableOfContentsList>
  <TableOfContentsItem href="#requirements">Requirements</TableOfContentsItem>
  <TableOfContentsItem href="#install">Install</TableOfContentsItem>
  <TableOfContentsItem href="#cli" level={3}>With the CLI</TableOfContentsItem>
  <TableOfContentsItem href="#manual" level={3}>By hand</TableOfContentsItem>
  <TableOfContentsItem href="#configure">Configure</TableOfContentsItem>
  <TableOfContentsItem href="#tokens" level={3}>Tokens</TableOfContentsItem>
  <TableOfContentsItem href="#density" level={3}>Density</TableOfContentsItem>
  <TableOfContentsItem href="#next">Next steps</TableOfContentsItem>
</TableOfContentsList>
```

## Numbered

`numbered` prefixes each item with its position, for a document people cite by clause: a policy, terms, a spec. The numbers are CSS counters on the list, so they always agree with the order on screen, and a level-3 item reads `2.1` under its parent. Screen readers already get the order from the `<ol>`, so the glyphs are hidden from them.

```tsx
<TableOfContents numbered>
  <TableOfContentsTitle>Privacy policy</TableOfContentsTitle>
  <TableOfContentsList>
    <TableOfContentsItem href="#collect">What we collect</TableOfContentsItem>
    <TableOfContentsItem href="#use">How we use it</TableOfContentsItem>
    <TableOfContentsItem href="#billing" level={3}>Receipts and billing</TableOfContentsItem>
    <TableOfContentsItem href="#releases" level={3}>Release notes</TableOfContentsItem>
    <TableOfContentsItem href="#share">Who we share it with</TableOfContentsItem>
    <TableOfContentsItem href="#cookies">Cookies</TableOfContentsItem>
    <TableOfContentsItem href="#rights">Your rights</TableOfContentsItem>
  </TableOfContentsList>
</TableOfContents>
```

## Density

Compact rows are 32px, the Sidebar's, for a docs rail that has to fit a long page. Comfortable rows reach the 40px house minimum, so the whole row is an easy target on a marketing page. On a touch screen both grow to 44px: the row itself grows, since stacked rows can't borrow space from each other. Without the prop it follows the nearest `DensityProvider`, and compact when there is none.

```tsx
<TableOfContents density="compact">…</TableOfContents>
<TableOfContents density="comfortable">…</TableOfContents>
```

## Headings from the page

`useHeadings(selector)` reads the headings out of the DOM, so a docs or blog layout builds its items from whatever the page renders. Levels are relative: the shallowest heading found is a section and anything deeper a subsection, so an article built from `h3`s nests the same as one built from `h2`s. Controls inside a heading (a copy-link anchor) are left out of its label. In a layout that persists across routes, pass the pathname as the second argument to read them again.

```tsx
const headings = useHeadings("article :is(h3, h4)[id]")

<TableOfContents container={pane}>
  <TableOfContentsTitle>On this page</TableOfContentsTitle>
  <TableOfContentsList>
    {headings.map((heading) => (
      <TableOfContentsItem key={heading.id} href={`#${heading.id}`} level={heading.level}>
        {heading.text}
      </TableOfContentsItem>
    ))}
  </TableOfContentsList>
</TableOfContents>
```

## How the spy decides

- A heading counts as reached once it sits where an anchor jump would park it: the top of the view plus its own `scroll-margin-top`. The spy reads the margin off the heading, so it agrees with the jump under a sticky header without a second offset.
- The first heading not yet reached is the section being read if it is already in the top half of the view; lower down, the reader is still in the one before it.
- At the very end of a page that scrolled, the last section wins, since the closing sections are often too short to ever reach the top.
- A clicked item holds the mark while the page travels to it, so a smooth scroll doesn't flick through every section on the way, and hands it back as soon as the reader scrolls themselves.
- `container` watches a scroll pane instead of the window (every demo on this page does). There, an item scrolls the pane itself, since a native jump would move the page around it too.
- A rail that scrolls on its own, capped at the viewport height like the one beside this page, keeps the active item in view as the mark moves. Only the rail scrolls, never the page.

## Reacting to the section

`onValueChange` hears the id of the section being read, from the spy or a click: update a reading bar, the document title, an analytics event. Pass `value` to drive the mark yourself, and `defaultValue` so the server render already marks the first section instead of waiting for the spy's first reading.

```tsx
const [reading, setReading] = React.useState("The brief")

<p>Reading {reading}</p>

<TableOfContents
  container={pane}
  defaultValue="brief"
  onValueChange={(id) => setReading(titles[id])}
>
  …
</TableOfContents>
```

## A nav of your own

`useScrollSpy(ids)` is the same spy without the list, for when a rail doesn't fit: a phone that shows the section being read in a bar instead. It starts on the first id, so the server render already has an answer. Here the headings carry `scroll-mt-12` to clear the bar, and the spy honors it.

```tsx
const active = useScrollSpy(["brief", "constraints", "signals", "ranking", "shipping"], {
  container: pane,
})

<div ref={pane} className="h-90 overflow-y-auto">
  <div className="sticky top-0 flex h-10 items-center justify-between border-b bg-background">
    <span className="truncate font-medium">{titles[active]}</span>
    <span className="tabular-nums text-muted-foreground">{index + 1} / 5</span>
  </div>
  <article className="[&_h3]:scroll-mt-12">…</article>
</div>
```

## API reference

### TableOfContents

The `<nav>` and the spy. Takes `variant` (line · progress · pill · dash · plain · minimap), `density` (compact · comfortable), `numbered`, `value`, `defaultValue`, `onValueChange` and `container` (a ref to a scroll pane; the window when omitted). Its `aria-label` defaults to `"On this page"`; give each nav its own when a page has two.

### TableOfContentsTitle

The overline above the list, a `<p>`. `asChild` renders your own element instead, such as a heading.

### TableOfContentsList

The `<ol>`. On line and progress it draws the track and the bar, on pill the chip, each its own `::before`, so `className="before:bg-foreground"` restyles it. On minimap the list is the panel, and the dash column renders beside it from the same items.

### TableOfContentsItem

One link in its `<li>`. Takes `href` (`#` plus the heading's id; a link that leaves the page is shown but not spied) and `level` (2 · 3). The active item carries `aria-current="location"`.

### useHeadings · useScrollSpy

`useHeadings(selector?, key?)` returns `{ id, text, level }[]` for the headings matching `selector` (default `"h2[id], h3[id]"`), read again when `key` changes. `useScrollSpy(ids, { container? })` returns the id of the section being read.

## FAQ

### Why doesn't it take a list of ids?

Because the items already say where they point. Each TableOfContentsItem registers the heading its href names, so the spy always watches exactly the links on screen, and adding or removing an item needs no second edit elsewhere.

### Why aren't the clicks smooth?

The items are plain anchors, so the browser owns the jump, the hash in the URL, the back button and where Tab goes next. Add scroll-behavior: smooth to html inside @media (prefers-reduced-motion: no-preference) and every anchor on the site glides, this one included. The mark doesn't wait for the scroll: it moves to the clicked item at once.

### The wrong section lights up under my sticky header. What do I change?

Give the headings a scroll-margin-top that clears the header (scroll-mt-24 under a 64px bar, say). The anchor jump parks the heading below the header, and the spy reads the same margin to decide when a heading has been reached, so the two agree.

### Where does a share row or a back-to-top link go?

Beside the nav, not inside it: wrap both in a column and let the TableOfContents stay navigation only. That is how the Blog Post 2 page composes its rail.

### What should a phone show?

A rail rarely fits below lg. Hide it there and either put the same list above the article as a plain index, the way the Legal Section 2 section does, or show the section being read in a bar with useScrollSpy.

### Does it respect reduced motion?

Yes. The bar jumps instead of sliding, and inside a scroll container a click scrolls instantly. The page itself scrolls however your html rule says.

---

<!-- https://www.koalaui.com/docs/components/tabs.md -->

# Tabs

Switch between related panels. Built on Radix Tabs for behavior and a11y, styled with one tv slots recipe. The active state is a single indicator measured in JS and slid with transform.

```tsx
<Tabs defaultValue="overview">
  <TabsList>
    <TabsTrigger value="overview">Overview</TabsTrigger>
    <TabsTrigger value="activity">Activity</TabsTrigger>
    <TabsTrigger value="settings">Settings</TabsTrigger>
  </TabsList>
  <TabsContent value="overview">…</TabsContent>
  <TabsContent value="activity">…</TabsContent>
  <TabsContent value="settings">…</TabsContent>
</Tabs>
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add tabs
```

Manual: run `npm install radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/tabs/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

```tsx title="usage.tsx"
import {
  Tabs, TabsList, TabsTrigger, TabsContent,
} from "@/components/ui/tabs"

export function Example() {
  return (
    <Tabs defaultValue="account">
      <TabsList>
        <TabsTrigger value="account">Account</TabsTrigger>
        <TabsTrigger value="password">Password</TabsTrigger>
      </TabsList>
      <TabsContent value="account">Account panel</TabsContent>
      <TabsContent value="password">Password panel</TabsContent>
    </Tabs>
  )
}
```

## Pill (default)

```tsx
<Tabs defaultValue="overview">
  <TabsList>
    <TabsTrigger value="overview">Overview</TabsTrigger>
    <TabsTrigger value="activity">Activity</TabsTrigger>
    <TabsTrigger value="settings">Settings</TabsTrigger>
  </TabsList>
  <TabsContent value="overview">…</TabsContent>
  <TabsContent value="activity">…</TabsContent>
  <TabsContent value="settings">…</TabsContent>
</Tabs>
```

## Folder

```tsx
<Tabs defaultValue="overview" variant="folder">
  <TabsList>
    <TabsTrigger value="overview">Overview</TabsTrigger>
    <TabsTrigger value="activity">Activity</TabsTrigger>
    <TabsTrigger value="settings">Settings</TabsTrigger>
  </TabsList>
  …
</Tabs>
```

## Line

```tsx
<Tabs defaultValue="overview" variant="line">
  <TabsList>
    <TabsTrigger value="overview">Overview</TabsTrigger>
    <TabsTrigger value="activity">Activity</TabsTrigger>
    <TabsTrigger value="settings">Settings</TabsTrigger>
  </TabsList>
  …
</Tabs>
```

## Chip

A row of separate outlined chips for a showcase switcher, where each tab is a destination with its own icon rather than a view of one panel. The active chip settles onto a muted fill, so there is no sliding indicator. Chips take a 16px label with a 20px muted glyph, and paint an opaque fill (the ground they sit on) so the rail can be pinned with `sticky` over the artwork it switches. To fold the rail onto two rows on a phone, pass `flex-wrap` to `TabsList`.

```tsx
import { House, PencilSimpleLine, Money } from "@phosphor-icons/react/ssr"

<Tabs defaultValue="home" variant="chip">
  <TabsList>
    <TabsTrigger value="home"><House weight="bold" />Home</TabsTrigger>
    <TabsTrigger value="blog"><PencilSimpleLine weight="bold" />Blog article</TabsTrigger>
    <TabsTrigger value="pricing"><Money weight="bold" />Pricing</TabsTrigger>
  </TabsList>
  …
</Tabs>
```

## Icons

```tsx
import { House, ActivityIcon, Gear } from "@phosphor-icons/react/ssr"

<Tabs defaultValue="overview">
  <TabsList>
    <TabsTrigger value="overview"><House />Overview</TabsTrigger>
    <TabsTrigger value="activity"><ActivityIcon />Activity</TabsTrigger>
    <TabsTrigger value="settings"><Gear />Settings</TabsTrigger>
  </TabsList>
  …
</Tabs>
```

## Density

Tabs ship at one tight size (a 14px label in a 32px-tall trigger). `density` tightens the pill chrome for application UI: a snugger container and tighter concentric radii. Set it per tabs or for a whole subtree with `DensityProvider` - see [Density](https://www.koalaui.com/docs/foundations/density.md).

```tsx
<Tabs density="comfortable" defaultValue="a">…</Tabs>
<Tabs density="compact" defaultValue="a">…</Tabs>
```

## Overflow

When the tabs are wider than their container, the list scrolls horizontally in a single row instead of pushing the layout wide, so tabs never break the page on narrow viewports. Scrollbars are hidden across Koala, so the leading edge softly fades toward the tabs you can still scroll to. It is inert whenever the tabs already fit.

```tsx
<Tabs defaultValue="overview" className="max-w-xs">
  <TabsList>
    <TabsTrigger value="overview">Overview</TabsTrigger>
    <TabsTrigger value="activity">Activity</TabsTrigger>
    <TabsTrigger value="reports">Reports</TabsTrigger>
    <TabsTrigger value="members">Members</TabsTrigger>
    <TabsTrigger value="billing">Billing</TabsTrigger>
    <TabsTrigger value="security">Security</TabsTrigger>
  </TabsList>
  …
</Tabs>
```

## Vertical

Pass `orientation="vertical"` and the rail stands beside its panel instead of above it: the reading-pane layout, for a docs sidebar or a FAQ whose answers should not move the page. It is forwarded straight to Radix, so the arrow keys become up and down and the ARIA follows; Radix stamps `data-orientation` on the root, the list and every trigger, so the whole layout is one set of variants with no second prop to keep in sync. A vertical rail is a nav rather than a segmented control, so the trough stands down and the indicator becomes the selected row's own fill; rows grow to a 40px reading row and their labels wrap rather than forcing the rail wider. The sliding indicator needs nothing: it already tracks the active trigger's box, whichever way the list runs.

```tsx
<Tabs orientation="vertical" defaultValue="overview" className="items-start">
  <TabsList className="w-56 shrink-0">
    <TabsTrigger value="overview">Overview</TabsTrigger>
    <TabsTrigger value="activity">Activity</TabsTrigger>
    <TabsTrigger value="members">Members</TabsTrigger>
  </TabsList>
  <TabsContent value="overview" className="flex-1">…</TabsContent>
</Tabs>
```

## Panel height

Radix unmounts the panel you leave and mounts the one you arrive at, so panels of different heights make the block below the tabs snap from one to the other while the new panel is still fading up: two gestures fighting over the same moment. Wrap them in `TabsPanels` and the block eases to the new panel's height instead, with the fade riding along as one movement. It is the same measured box the Dock morphs with (`useMorphBox`).
It is opt-in because it clips, which is exactly what makes the reveal read as one object. A panel that has to paint outside its own box (a sticky header, a popover that is not portalled) should stay unwrapped, and so should one that can grow without a ceiling: past a certain height the ease stops reading as a gesture and turns back into a jump.

```tsx
<Tabs defaultValue="summary">
  <TabsList>
    <TabsTrigger value="summary">Summary</TabsTrigger>
    <TabsTrigger value="details">Details</TabsTrigger>
    <TabsTrigger value="history">History</TabsTrigger>
  </TabsList>

  <TabsPanels>
    <TabsContent value="summary">…</TabsContent>
    <TabsContent value="details">…</TabsContent>
    <TabsContent value="history">…</TabsContent>
  </TabsPanels>
</Tabs>
```

## FAQ

### How are TabsTrigger and TabsContent wired together?

Each `TabsTrigger` and its matching `TabsContent` share the same `value` string, and the active tab comes from `defaultValue` (uncontrolled) or `value` with `onValueChange` (controlled). It is Radix Tabs underneath, so they pair purely by value.

### What is the difference between the pill, folder, line, and chip variants?

`pill` (the default) is a contained segmented control with a sliding background. `folder` keeps a pill background on the active tab plus a sliding bar on a bottom rule. `line` drops the container entirely and shows only the accent-colored underline bar. `chip` is a row of separate outlined chips with no sliding indicator, where the active chip settles onto a muted fill; reach for it when each tab is a destination with its own icon, like a marketing page switcher.

### Can I change the size of the tabs?

Tabs ship at a single tight size (a 14px label in a 32px-tall trigger), so the control stays consistent everywhere. To make the chrome snugger for dense application UI, use `density` (`comfortable` or `compact`), which tightens the container padding and concentric radii without changing the text size. Set it per Tabs or for a subtree via `DensityProvider`.

### How does the active indicator slide?

A single indicator element is measured in JS (offset box of the active trigger) and moved with `transform`. It re-measures on selection change, resize, and font shifts, and the transition only switches on after the first paint so it never animates in from the origin on load.

### What happens when there are more tabs than fit?

The list scrolls horizontally in a single row instead of overflowing the page, so tabs stay on one line on narrow viewports. Scrollbars are hidden across Koala, so a soft edge fade (`scroll-fade-x`) hints at the tabs you can still scroll toward. The behavior is inert when the tabs already fit, and the sliding indicator scrolls glued to the active tab. To wrap onto multiple rows instead, pass `flex-wrap` to `TabsList`.

### Do I get keyboard navigation for free?

Yes. Because Tabs is built on Radix Tabs you get arrow-key roving focus, Home and End, and the correct tab and tabpanel ARIA roles without any extra wiring.

### How do I add an icon to a trigger?

Drop a Phosphor icon as a child of `TabsTrigger` alongside the label. The recipe already sizes any nested svg to 16px and spaces it from the text, so no extra classes are needed.

---

<!-- https://www.koalaui.com/docs/components/textarea.md -->

# Textarea

A multi-line text field built from slots and Context: pairs with a label and hint, grows to fit its content, and carries an optional character counter in its footer. Each part is a named export.

```tsx
<div className="flex flex-col gap-1.5">
  <TextareaLabel htmlFor="message">Message</TextareaLabel>
  <TextareaRoot>
    <TextareaField id="message" placeholder="Write your message…" />
  </TextareaRoot>
</div>
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add textarea
```

Manual: run `npm install radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/textarea/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

```tsx title="usage.tsx"
import {
  TextareaRoot,
  TextareaField,
  TextareaLabel,
} from "@/components/ui/textarea"

export function Example() {
  return (
    <div className="flex flex-col gap-1.5">
      <TextareaLabel htmlFor="message">Message</TextareaLabel>
      <TextareaRoot>
        <TextareaField id="message" placeholder="Write your message…" />
      </TextareaRoot>
    </div>
  )
}
```

## Label & hint

`TextareaLabel` sits above the control. Wire it with `htmlFor` pointing at the `TextareaField`’s `id` so clicking the label focuses the field. Pass `required` to append a destructive asterisk. `TextareaHint` renders helper text below; give it an `id` and reference it from the field’s `aria-describedby`. Both are the shared DS `Label` / `Hint` primitives.

```tsx
<div className="flex flex-col gap-1.5">
  <TextareaLabel htmlFor="feedback" required>
    Feedback
  </TextareaLabel>
  <TextareaRoot>
    <TextareaField
      id="feedback"
      placeholder="What could be better?"
      aria-describedby="feedback-hint"
    />
  </TextareaRoot>
  <TextareaHint id="feedback-hint">
    Your notes go straight to the product team.
  </TextareaHint>
</div>
```

## Auto-resize

Pass `autoResize` to `TextareaField` and the field grows to fit its content as you type, with no inner scrollbar. It rides the native CSS `field-sizing: content` where the browser supports it (no JavaScript at all), and falls back to a `scrollHeight` measurement everywhere else, so it works in every browser. Growth stays in sync on paste, autofill, or a controlled reset. It pins the drag handle to `none`, since manual dragging would fight the content height.

```tsx
<TextareaRoot>
  <TextareaField
    autoResize
    value={value}
    onChange={(e) => setValue(e.target.value)}
    placeholder="Start typing…"
  />
</TextareaRoot>
```

## Character count addon

For the common case, pass `showCount` to `TextareaField` and it renders the footer and counter for you, with no separate state and no extra parts. It tracks the field’s own length, so it works whether the field is controlled or uncontrolled. Add the native `maxLength` to show `current / max` and hard-cap the input.

```tsx
<TextareaRoot resize="none">
  <TextareaField
    showCount
    maxLength={180}
    placeholder="Tell us about yourself…"
  />
</TextareaRoot>
```

## Character counter (manual)

For full control over the footer, compose it by hand. `TextareaFooter` is a slot inside the field’s border, ideal for a helper note on the left and a counter on the right. `TextareaCount` takes the current length and an optional `max`; it uses `tabular-nums` so the count never shifts the layout, and turns destructive once you go over. Pair it with `hasError` on the root to flush the whole field red.

```tsx
<TextareaRoot resize="none" hasError={value.length > 180}>
  <TextareaField
    value={value}
    onChange={(e) => setValue(e.target.value)}
    placeholder="Tell us about yourself…"
  />
  <TextareaFooter>
    <span>Markdown supported</span>
    <TextareaCount current={value.length} max={180} />
  </TextareaFooter>
</TextareaRoot>
```

## Sizes

Three sizes scale padding, text, and the minimum height: `sm`, `md` (the default), and `lg`. Set `size` on `TextareaRoot`; every part picks it up from context.

```tsx
<TextareaRoot size="sm">
  <TextareaField placeholder="Small" />
</TextareaRoot>

<TextareaRoot size="md">
  <TextareaField placeholder="Medium (default)" />
</TextareaRoot>

<TextareaRoot size="lg">
  <TextareaField placeholder="Large" />
</TextareaRoot>
```

## Resize

The `resize` prop on `TextareaRoot` controls the drag handle: `vertical` (default), `none`, `horizontal`, or `both`. The handle stays clipped to the field’s rounded corner.

```tsx
<TextareaRoot resize="none">
  <TextareaField placeholder="Can't be resized" />
</TextareaRoot>

<TextareaRoot resize="vertical">
  <TextareaField placeholder="Drag the bottom edge" />
</TextareaRoot>
```

## Error

Pass `hasError` to `TextareaRoot` to switch the border and focus ring to the destructive color and set `aria-invalid` on the underlying `textarea`. Pass the same `hasError` to `TextareaHint` so the helper text doubles as the error message.

```tsx
<div className="flex flex-col gap-1.5">
  <TextareaLabel htmlFor="ta-error" required>Summary</TextareaLabel>
  <TextareaRoot hasError>
    <TextareaField
      id="ta-error"
      defaultValue="Too short"
      aria-describedby="ta-error-hint"
    />
  </TextareaRoot>
  <TextareaHint id="ta-error-hint" hasError>
    Add at least 20 characters.
  </TextareaHint>
</div>
```

## Disabled

```tsx
<div className="flex flex-col gap-1.5">
  <TextareaLabel htmlFor="ta-disabled">Message</TextareaLabel>
  <TextareaRoot disabled>
    <TextareaField id="ta-disabled" placeholder="Disabled" />
  </TextareaRoot>
</div>
```

## FAQ

### Why is the Textarea split into TextareaRoot and TextareaField?

`TextareaRoot` owns the bordered surface, size, resize behavior, and error state and shares them through Context, while `TextareaField` is the actual `textarea` element. Splitting them lets the footer and counter live inside the same border as the input.

### Should I use showCount or compose TextareaFooter and TextareaCount by hand?

For the common case, pass `showCount` (and optionally `maxLength`) to `TextareaField` and it renders the footer and counter for you, tracking the field's own length whether controlled or uncontrolled. Compose `TextareaFooter` with `TextareaCount` manually only when you also want custom footer content like a helper note.

### How do I make the field grow with its content?

Pass `autoResize` to `TextareaField`. It rides the native CSS `field-sizing: content` where supported with no JS, and falls back to a `scrollHeight` measurement elsewhere. It also pins the drag handle to none, since manual dragging would fight the content height.

### How do I wire up the label and hint accessibly?

Point `TextareaLabel`'s `htmlFor` at the `TextareaField`'s `id` so clicking the label focuses it, and give `TextareaHint` an `id` referenced from the field's `aria-describedby`. Add `required` on the label to append a destructive asterisk.

### How do I show an error state?

Pass `hasError` to `TextareaRoot` to flip the border and focus ring to the destructive color and set `aria-invalid` on the textarea. Pass the same `hasError` to `TextareaHint` so the helper text doubles as the error message.

### What is the difference between the size and resize props?

`size` (`sm`, `md`, `lg`) scales padding, text, and the minimum height and is read from Context by every part. `resize` controls only the drag handle (`vertical` by default, or `none`, `horizontal`, `both`). Both are set on `TextareaRoot`.

### Why does the text grow to 16px on a phone?

On a touch screen, `sm` and `md` switch from 14px to 16px text, because iOS zooms the page into any focused field under 16px. The rule keys on the pointer, not the width, so a desktop keeps 14px at any size. A browser-autofilled value gets the same 6% brand tint as Input, with the text held at the theme's foreground.

---

<!-- https://www.koalaui.com/docs/components/toast.md -->

# Toast

Transient status messages anchored to a corner. Toasts stack with a compressed fan when several are queued, hover to expand, follow a promise from loading to its result, and update in place.

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

<Button onClick={() => toast("Your changes have been saved.")}>
  Show toast
</Button>
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add toast
```

Manual: run `npm install radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/toast/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

Add `<Toaster />` once to your root layout: it renders the fixed viewport and is required for toasts to appear.

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

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        {children}
        <Toaster />
      </body>
    </html>
  )
}
```

## Usage

```tsx title="usage.tsx"
import { toast, useToast } from "@/components/ui/toast"

// Imperative: works anywhere (Server Action results, event handlers, outside React)
toast("File saved.")
toast.success("Uploaded.")
toast.error("Something went wrong.")
toast.warning("Disk space low.")
toast.info("Version 2.4 available.")

// Work in flight: one toast that follows the promise to its result
toast.promise(saveChanges(), {
  loading: "Saving…",
  success: "Saved.",
  error: "Couldn't save.",
})

// Beside the element that raised it, instead of the corner
toast.success("Link copied", { anchor: event.currentTarget })

// Close one toast by id, or all of them
toast.dismiss(id)
toast.dismiss()

// Hook: same API, inside React components
function MyComponent() {
  const { toast } = useToast()
  return <Button onClick={() => toast("Done!")}>Save</Button>
}
```

## Variants

Five semantic variants: `default`, `success`, `warning`, `destructive`, and `info`. Every toast is the same neutral elevated card (border + shadow); the status colour is carried by the icon, so the variants stay calm and never get lost on the corner. The buttons fire the real thing.

```tsx
toast("Changes saved successfully.")
toast.success("File uploaded.", { description: "profile-photo.png is ready." })
toast.warning("Storage almost full.", { description: "You have 200 MB remaining." })
toast.error("Upload failed.", { description: "The server returned a 413 error." })
toast.info("New version available.", { description: "Refresh the page to get v2.4.0." })
```

## Loading

`toast.loading` shows a spinner and stays up until you raise the same `id` again with the result. The card is updated in place: the spinner cross-fades into the result icon and the title rolls to its new line, so it reads as one piece of work finishing rather than a second message arriving.

```tsx
const id = toast.loading("Uploading 3 files…", { description: "Keep this tab open." })
await upload(files)
toast.success("Upload complete.", { id, description: "3 files are ready." })
```

## Promise

`toast.promise` does the loading-then-result dance for you. Each message can be a title, a full options object, or a function of the resolved value (or the error). It hands the promise back, so `await toast.promise(save(), …)` still returns the value or throws.

```tsx
toast.promise(saveChanges(), {
  loading: "Saving changes…",
  success: (count) => `Saved ${count} changes.`,
  error: {
    title: "Couldn't save.",
    description: "You're offline. We'll retry when you reconnect.",
  },
})
```

## Update in place

Give a toast an `id` and raising it again never stacks a copy. The card moves to the front, its timer restarts, and it replays a short cue so the repeat still registers: a pop for a confirmation, a shake for an error or a warning. Press either button several times to see it.

```tsx
toast.success("Link copied.", { id: "copy-link" })
toast.error("Wrong code.", { id: "verify", description: "Check the code and try again." })
```

## Anchored

Pass an `anchor` and the toast becomes a small bubble beside the element that raised it: a “Copied” next to the copy button rather than a card in the far corner. It sits above the element (below it when the element is near the top of the screen), stays up for 1.5 seconds, and closes as soon as the page scrolls or resizes, since it would otherwise drift away from what it describes. The bubble itself is hidden from assistive tech; an always-mounted live region announces it instead.

```tsx
<Button
  onClick={(event) =>
    toast.success("Link copied", { anchor: event.currentTarget })
  }
>
  Copy link
</Button>
```

## With action

Pass an `action` object with a `label` and `onClick` handler. The button appears below the description and is announced as an accessible action by screen readers.

```tsx
toast({
  title: "Email sent.",
  description: "Your message was delivered to alex@example.com.",
  action: {
    label: "Undo",
    onClick: () => toast("Send undone."),
  },
})
```

## Stacking

When multiple toasts are queued they compress into a fan: older toasts peek behind the newest one at decreasing scale and offset. Hover (or focus) the stack to expand all toasts to their full size with a 16px gap. Up to three toasts show in the collapsed fan; any beyond that are hidden until older ones are dismissed. On a touch screen, swipe a toast to the right to dismiss it: the card follows your finger.

```tsx
// Fire several toasts and hover the stack to expand
toast({ title: "Build passed", variant: "success" })
toast({ title: "Deploy queued", description: "Estimated time: 2 min." })
toast({ title: "Preview ready", variant: "info" })
```

## Persistent

Pass `duration: Infinity` to keep the toast until the user explicitly dismisses it. Useful for critical alerts. For work in progress, prefer `toast.loading`, which persists on its own and resolves in place.

```tsx
toast({
  title: "Syncing in background.",
  description: "This won't dismiss automatically.",
  duration: Infinity,
})
```

## FAQ

### Should I call toast(...) or use the useToast() hook?

Both share the same API. The imperative `toast(...)` works anywhere, including Server Action results, event handlers, and code outside React, while `useToast()` returns the same `toast` plus a `dismiss` function for use inside components. Reach for the hook only when you want the matching `dismiss` helper at hand.

### Why do my toasts never appear?

You almost certainly forgot to render `<Toaster />` once in your root layout. It draws the fixed viewport that every toast portals into, so without it the calls succeed silently but nothing shows.

### How do I stop the same message from stacking up?

Give it an `id`. Raising a toast whose id is still on screen updates that card in place, moves it to the front and restarts its timer, then replays a pop (confirmations) or a shake (errors and warnings) so the repeat is still noticed. Without an id every call is a new toast.

### When should I use toast.promise instead of loading plus success?

Whenever the work is a single promise. `toast.promise(work, { loading, success, error })` shows the spinner, then turns the same card into the result, and returns the promise so you can still await it. Use `toast.loading` with an id when the result arrives from somewhere else, such as a websocket event.

### Can a toast appear next to the button that raised it?

Yes: pass `anchor: event.currentTarget`. The toast becomes a small icon-and-title bubble beside that element for 1.5 seconds instead of a card in the corner, and it closes on scroll or resize. It has no close button or action, so keep it to a word or two, such as "Copied".

### How do I make a toast persist until dismissed?

Pass `duration: Infinity` in the options object. The default is 5000 ms, and `loading` toasts persist on their own. The toast stays up until the user clicks its Close button or your code calls `toast.dismiss(id)` with the id returned from `toast(...)`.

### What is the difference between toast.error and a destructive variant?

They are the same thing. `toast.error(...)` is a shortcut that sets `variant: "destructive"`, which is the role name used across the design system for danger styling. It is also the one variant announced assertively, so a screen reader interrupts for it; the others wait their turn.

### How do I add an Undo button to a toast?

Pass an `action` object with a `label` and an `onClick`. It renders below the description as a Radix Toast Action with the label as its `altText`, so screen readers announce it as an actionable control.

### Why do queued toasts collapse into a fan?

Stacking is handled by the Toaster: older toasts compress behind the newest at decreasing scale and offset so the corner stays calm. Hover or focus the stack to expand all of them to full size; only three show in the collapsed fan and the rest wait until older ones dismiss.

---

<!-- https://www.koalaui.com/docs/components/toggle.md -->

# Toggle

One control that stays pressed: bookmark, pin, mute, unread only. The single-item sibling of Toggle Group, sharing its paint and its heights, with a pressed glyph that fills in instead of blinking.

```tsx
<Toggle defaultPressed>
  <EnvelopeSimple weight="bold" /> Unread only
</Toggle>
<Toggle variant="ghost" iconOnly aria-label="Bookmark" defaultPressed>
  <ToggleIcon off={<BookmarkSimple weight="bold" />} on={<BookmarkSimple weight="fill" />} />
</Toggle>
<Toggle variant="ghost" iconOnly aria-label="Pin">
  <ToggleIcon off={<PushPin weight="bold" />} on={<PushPin weight="fill" />} />
</Toggle>
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add toggle
```

Manual: run `npm install radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/toggle/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

```tsx title="usage.tsx"
import { Toggle } from "@/components/ui/toggle"

export function Example() {
  return <Toggle aria-label="Show grid">Show grid</Toggle>
}
```

## Variants

`outline` (the default) is the Toggle Group pill: a framed control whose pressed state is the brand border and a soft halo, with no fill. `ghost` is bare at rest and takes the accent chip once pressed, the Toolbar's pressed look, for icon toggles in a row of other controls. Each is shown off, then on.

```tsx
<Toggle><GridFour weight="bold" /> Show grid</Toggle>
<Toggle defaultPressed><GridFour weight="bold" /> Show grid</Toggle>

<Toggle variant="ghost" iconOnly aria-label="Italic"><TextItalic weight="bold" /></Toggle>
<Toggle variant="ghost" iconOnly aria-label="Bold" defaultPressed><TextB weight="bold" /></Toggle>
```

## Sizes

The Toggle Group scale: `sm` is 32px and `md` (the default) is 40px, so a lone toggle lines up with a group beside it. `iconOnly` squares the control around one glyph and steps the glyph up to 20px at `md`. The 32px control grows its target to 40px (44px on touch) without growing the visual.

```tsx
<Toggle size="sm" defaultPressed><PushPin weight="bold" /> Pin</Toggle>
<Toggle size="sm" iconOnly aria-label="Pin" defaultPressed><PushPin weight="bold" /></Toggle>
<Toggle size="md" defaultPressed><PushPin weight="bold" /> Pin</Toggle>
<Toggle size="md" iconOnly aria-label="Pin" defaultPressed><PushPin weight="bold" /></Toggle>
```

## Pressed glyph

`ToggleIcon` holds two glyphs in one cell and cross-fades them on the toggle's state: the outgoing one shrinks to a quarter, fades and blurs as the incoming one resolves, on a CSS transition, so pressing twice quickly reverses mid-way instead of restarting. Pass the pressed glyph in its `fill` weight, which is how the system marks a selected state, or a different glyph when on means something else (a slashed microphone). Press them.

```tsx
<Toggle variant="ghost" iconOnly aria-label="Bookmark" defaultPressed>
  <ToggleIcon off={<BookmarkSimple weight="bold" />} on={<BookmarkSimple weight="fill" />} />
</Toggle>
<Toggle variant="ghost" iconOnly aria-label="Like">
  <ToggleIcon off={<Heart weight="bold" />} on={<Heart weight="fill" className="text-destructive" />} />
</Toggle>
<Toggle variant="ghost" iconOnly aria-label="Star">
  <ToggleIcon off={<Star weight="bold" />} on={<Star weight="fill" className="text-warning" />} />
</Toggle>
<Toggle variant="ghost" iconOnly aria-label="Mute">
  <ToggleIcon off={<Microphone weight="bold" />} on={<MicrophoneSlash weight="bold" />} />
</Toggle>
```

## With a tooltip

An icon-only toggle is named by its `aria-label`: the glyph is not a name. Show that name to sighted users with a `Tooltip`, and wrap the row in a `TooltipGroup` so the bubble glides from one toggle to the next.

```tsx
<TooltipGroup>
  <Tooltip content={<>Bold <Kbd size="sm">⌘B</Kbd></>}>
    <Toggle variant="ghost" size="sm" iconOnly aria-label="Bold" defaultPressed>
      <TextB weight="bold" />
    </Toggle>
  </Tooltip>
  <Tooltip content={<>Italic <Kbd size="sm">⌘I</Kbd></>}>
    <Toggle variant="ghost" size="sm" iconOnly aria-label="Italic">
      <TextItalic weight="bold" />
    </Toggle>
  </Tooltip>
</TooltipGroup>
```

## Controlled

Hold the state yourself with `pressed` and `onPressedChange`. Here it filters the list under it; the count is `tabular-nums`, so it never jitters as it changes.

```tsx
const [unreadOnly, setUnreadOnly] = useState(false)

<Toggle size="sm" pressed={unreadOnly} onPressedChange={setUnreadOnly}>
  <EnvelopeSimple weight="bold" /> Unread only
</Toggle>
```

## Disabled

`disabled` dims the control in either state and takes it out of the pointer's way, so a locked setting still shows which way it is set.

```tsx
<Toggle disabled><GridFour weight="bold" /> Show grid</Toggle>
<Toggle disabled defaultPressed><GridFour weight="bold" /> Show grid</Toggle>
```

## API reference

### Toggle

A `<button>` with `aria-pressed` and `data-state="on" | "off"`. Props: `variant` (`outline` · `ghost`), `size` (`sm` · `md`), `iconOnly`, plus Radix's `pressed`, `defaultPressed`, `onPressedChange`, `disabled` and every button prop. `className` is merged last.

### ToggleIcon

A decorative `<span>` that cross-fades two glyphs on the surrounding toggle's state. Props: `off` (the glyph at rest), `on` (the glyph while pressed), `className`. It reads the state through the toggle's `group/toggle` hook, so it only works inside a `Toggle`.

## FAQ

### Toggle, Toggle Group or Switch?

A Switch is a setting that applies on its own (notifications on). A Toggle is a button that stays pressed, usually beside other controls (bookmark, mute, unread only). A Toggle Group is a set of them, holding one choice or several.

### Why doesn't it shrink when I press it?

The pressed paint is the feedback. A control that shrinks on click and then changes its paint does two things for one gesture, so the Toggle only does the one that stays.

### Why are the heights 32 and 40, not the 36 of a Button?

They are Toggle Group's heights. A Toggle most often sits beside a group or stands in for a one-item group, and the two should line up. Inside a Toolbar, use the Toolbar's own toggle items, which follow the bar's scale.

### How do I name an icon-only toggle?

With `aria-label`, which also becomes what a screen reader announces with its pressed state ("Bookmark, toggle button, pressed"). Add a Tooltip carrying the same name for sighted users.

### Does the glyph cross-fade respect reduced motion?

Yes. Under `prefers-reduced-motion` the two glyphs swap without the transition.

---

<!-- https://www.koalaui.com/docs/components/toggle-group.md -->

# Toggle Group

A set of pressable pills that hold a selection, built on Radix ToggleGroup. Use single for a one-of-N choice or multiple for independent toggles. A chosen pill carries the brand outline.

```tsx
<ToggleGroup type="single" defaultValue="yes" aria-label="Was this useful?">
  <ToggleGroupItem value="yes">
    <ThumbsUp />
    Yes
  </ToggleGroupItem>
  <ToggleGroupItem value="no">
    <ThumbsDown />
    No
  </ToggleGroupItem>
</ToggleGroup>
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add toggle-group
```

Manual: run `npm install radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/toggle-group/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

```tsx title="usage.tsx"
import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group"

export function Example() {
  return (
    <ToggleGroup type="single" defaultValue="yes">
      <ToggleGroupItem value="yes">Yes</ToggleGroupItem>
      <ToggleGroupItem value="no">No</ToggleGroupItem>
    </ToggleGroup>
  )
}
```

## Single vs. multiple

`type="single"` is a mutually exclusive choice: selecting one pill clears the rest. `type="multiple"` lets each pill toggle on and off independently, like a formatting band.

```tsx
<ToggleGroup type="single" defaultValue="grid" aria-label="View">
  <ToggleGroupItem value="list"><ListBullets />List</ToggleGroupItem>
  <ToggleGroupItem value="grid"><SquaresFour />Grid</ToggleGroupItem>
  <ToggleGroupItem value="board"><Kanban />Board</ToggleGroupItem>
</ToggleGroup>

<ToggleGroup type="multiple" defaultValue={["bold"]} aria-label="Text style">
  <ToggleGroupItem value="bold" aria-label="Bold"><TextB /></ToggleGroupItem>
  <ToggleGroupItem value="italic" aria-label="Italic"><TextItalic /></ToggleGroupItem>
  <ToggleGroupItem value="underline" aria-label="Underline"><TextUnderline /></ToggleGroupItem>
</ToggleGroup>
```

## Variants

`outline` (the default) gives each pill its own border on the page ground, and the chosen one takes the brand outline. Use it when the pills are independent choices. `segmented` puts them in one muted track and lifts the chosen pill off it instead, the same elevation the [Tabs](https://www.koalaui.com/docs/components/tabs.md) pill indicator uses. Reach for it when the set reads as a single control, such as the format switch in the [Color Picker](https://www.koalaui.com/docs/components/color-picker.md). The lift is one sliding thumb rather than a background on each pill, so choosing another option travels instead of blinking: it snaps into place on load and slides only on later changes. `ghost` drops the pill altogether: bare labels in the foreground, the chosen one underlined, for a dense set where a frame per option would read as a wall of boxes.

```tsx
// Independent choices on the page ground:
<ToggleGroup type="single" variant="outline" defaultValue="hex">
  <ToggleGroupItem value="hex">HEX</ToggleGroupItem>
  <ToggleGroupItem value="hsl">HSL</ToggleGroupItem>
  <ToggleGroupItem value="rgb">RGB</ToggleGroupItem>
</ToggleGroup>

// One control: a shared track, the chosen pill floating off it.
<ToggleGroup type="single" variant="segmented" defaultValue="hex">
  <ToggleGroupItem value="hex">HEX</ToggleGroupItem>
  <ToggleGroupItem value="hsl">HSL</ToggleGroupItem>
  <ToggleGroupItem value="rgb">RGB</ToggleGroupItem>
</ToggleGroup>

// Bare labels, the chosen one underlined: dense sets like a size grid.
<ToggleGroup type="single" variant="ghost" defaultValue="hex">
  <ToggleGroupItem value="hex">HEX</ToggleGroupItem>
  <ToggleGroupItem value="hsl">HSL</ToggleGroupItem>
  <ToggleGroupItem value="rgb">RGB</ToggleGroupItem>
</ToggleGroup>
```

## Size grid

The `ghost` variant is the size picker on a product page: lay the group out as a grid and let the cells shed their side padding. Weight stays medium when a size is chosen, so a bolder label never nudges its neighbours. A sold-out size stays in the grid, disabled, its label wrapped in `<s>` and its `aria-label` saying so.

```tsx
<ToggleGroup type="single" variant="ghost" defaultValue="41" aria-label="Size (EU)" className="grid grid-cols-5 gap-1">
  {sizes.map(({ size, soldOut }) => (
    <ToggleGroupItem
      key={size}
      value={size}
      disabled={soldOut}
      aria-label={soldOut ? `${size}, sold out` : size}
      className="px-0 tabular-nums"
    >
      {soldOut ? <s>{size}</s> : size}
    </ToggleGroupItem>
  ))}
</ToggleGroup>
```

## Sizes

`sm` (32px) is the compact rating pill; `md` (40px) is the default. Set `size` on the group and every item inherits it through context.

```tsx
<ToggleGroup type="single" size="sm" defaultValue="yes">
  <ToggleGroupItem value="yes"><ThumbsUp />Yes</ToggleGroupItem>
  <ToggleGroupItem value="no"><ThumbsDown />No</ToggleGroupItem>
</ToggleGroup>

<ToggleGroup type="single" size="md" defaultValue="yes">
  <ToggleGroupItem value="yes"><ThumbsUp />Yes</ToggleGroupItem>
  <ToggleGroupItem value="no"><ThumbsDown />No</ToggleGroupItem>
</ToggleGroup>
```

## Icon-only with tooltips

`iconOnly` squares an item around its glyph (32px at `sm`, 40px at `md`, where the glyph steps up to 20px), the same square the lone [Toggle](https://www.koalaui.com/docs/components/toggle.md) draws. A glyph is not a name, so an icon-only item always needs a hint, and `tooltip` gives it one with the same wiring as [Button](https://www.koalaui.com/docs/components/button.md): a string `tooltip` is shown on hover and focus and also names an item that has no `aria-label`, and an icon-only item with an `aria-label` shows that label as its hint on its own. On a labelled pill a `tooltip` is a supplementary hint. Pass `tooltip={false}` to opt out when you wrap the item in your own `Tooltip`.

```tsx
// A string tooltip is the hint and, with no aria-label, the item's name.
<ToggleGroup type="single" variant="segmented" size="sm" defaultValue="3x3" aria-label="Wall layout">
  <ToggleGroupItem value="2x2" iconOnly tooltip="2 by 2 grid"><SquaresFour /></ToggleGroupItem>
  <ToggleGroupItem value="3x3" iconOnly tooltip="3 by 3 grid"><GridNine /></ToggleGroupItem>
</ToggleGroup>

// An icon-only item with an aria-label shows it as the hint, like an icon-only Button.
<ToggleGroup type="multiple" defaultValue={["bold"]} aria-label="Text style">
  <ToggleGroupItem value="bold" iconOnly aria-label="Bold"><TextB /></ToggleGroupItem>
  <ToggleGroupItem value="italic" iconOnly aria-label="Italic"><TextItalic /></ToggleGroupItem>
  <ToggleGroupItem value="underline" iconOnly aria-label="Underline"><TextUnderline /></ToggleGroupItem>
</ToggleGroup>

// On a labelled pill, the tooltip is a supplementary hint.
<ToggleGroup type="single" variant="segmented" size="sm" defaultValue="7d" aria-label="Range">
  <ToggleGroupItem value="7d" tooltip="Last 7 days">7D</ToggleGroupItem>
  <ToggleGroupItem value="30d" tooltip="Last 30 days">30D</ToggleGroupItem>
  <ToggleGroupItem value="90d" tooltip="Last 90 days">90D</ToggleGroupItem>
</ToggleGroup>
```

## Feedback card

The classic "Was this useful?" prompt: a title, a question, and a Yes/No band on a card. Rendered open so it reads at a glance, with the group controlled so the selection is yours to send.

```tsx
const [rating, setRating] = useState("yes")

<div className="w-72 rounded-xl border border-border bg-card p-4 text-card-foreground shadow-sm [--surface:var(--card)]">
  <div className="flex flex-col gap-4">
    <div className="flex flex-col gap-1">
      <p className="text-base font-semibold text-foreground">Was this useful?</p>
      <p className="text-sm text-muted-foreground">How would you rate your overall experience?</p>
    </div>
    <ToggleGroup type="single" size="sm" value={rating} onValueChange={setRating}>
      <ToggleGroupItem value="yes"><ThumbsUp />Yes</ToggleGroupItem>
      <ToggleGroupItem value="no"><ThumbsDown />No</ToggleGroupItem>
    </ToggleGroup>
  </div>
</div>
```

## Inline feedback

The compact variant: just the question and a Yes/No band, no subtitle. Answering swaps the prompt for a thank-you, so the widget always feels resolved.

```tsx
const [answer, setAnswer] = useState("")

<div className="w-64 rounded-xl border border-border bg-card p-4 text-card-foreground shadow-xs [--surface:var(--card)]">
  {answer ? (
    <p className="text-sm font-medium text-muted-foreground">Thanks for your feedback!</p>
  ) : (
    <div className="flex flex-col gap-3">
      <p className="text-sm font-semibold text-foreground">Was this useful?</p>
      <ToggleGroup type="single" size="sm" value={answer} onValueChange={setAnswer}>
        <ToggleGroupItem value="yes"><ThumbsUp />Yes</ToggleGroupItem>
        <ToggleGroupItem value="no"><ThumbsDown />No</ToggleGroupItem>
      </ToggleGroup>
    </div>
  )}
</div>
```

## Inside a popover

The same content floated: drop the card into a `Popover` when the prompt should appear on demand rather than sit in the page.

```tsx
const [rating, setRating] = useState("")

<Popover>
  <PopoverTrigger asChild>
    <Button variant="outline">Was this useful?</Button>
  </PopoverTrigger>
  <PopoverContent align="start" className="w-auto">
    <div className="flex flex-col gap-4">
      <div className="flex flex-col gap-1">
        <PopoverTitle className="text-base">Was this useful?</PopoverTitle>
        <PopoverDescription>How would you rate your overall experience?</PopoverDescription>
      </div>
      <ToggleGroup type="single" size="sm" value={rating} onValueChange={setRating}>
        <ToggleGroupItem value="yes"><ThumbsUp />Yes</ToggleGroupItem>
        <ToggleGroupItem value="no"><ThumbsDown />No</ToggleGroupItem>
      </ToggleGroup>
    </div>
  </PopoverContent>
</Popover>
```

## FAQ

### When should I use ToggleGroup instead of RadioGroup or Switch?

Use ToggleGroup when one or several options from a small, visible set should look chosen, like a rating or a view switch. Unlike RadioGroup the control is its own label, so no paired inputs are needed, and unlike Switch it can hold a one-of-N choice with `type="single"`.

### What is the difference between type=single and type=multiple?

`type="single"` is a mutually exclusive choice: selecting one `ToggleGroupItem` clears the rest. `type="multiple"` lets each pill toggle on and off independently, like a bold/italic/underline formatting band.

### How do I change the size of every pill at once?

Set `size` on the `ToggleGroup` root and every `ToggleGroupItem` inherits it through context, so you never set it per item. `sm` is the 32px compact rating pill and `md` (40px) is the default.

### Why does a selected pill have no fill, just an outline?

A chosen pill draws a brand outline plus a soft brand halo (`data-[state=on]`) with the label and glyph in the foreground, matching Figma. The fill is left off deliberately so the pill blends with whatever surface it sits on rather than painting a block that fights nested surfaces.

### Does the segmented pill slide between options?

Yes. `variant="segmented"` draws the chosen pill's lift as a single thumb measured in JS and moved with `transform`, the same indicator the Tabs `pill` variant slides. It snaps into place on load and only animates on later changes, and it stands down under `prefers-reduced-motion`. Because the thumb can only sit in one place, it is used when exactly one item is selected; with nothing selected or several on at once (`type="multiple"`) each chosen pill paints the same lift itself.

### Why does my pill look like a solid block on a colored card?

The item background reads `var(--surface)`, so a colored container must declare `--surface` to blend in. The doc demos set `[--surface:var(--card)]` on the card root; without it the pill falls back to the page `--background`.

### How do I label icon-only pills for screen readers?

Mark the item `iconOnly` and give it either an `aria-label` (which then doubles as its tooltip) or a string `tooltip` (which then doubles as its name), and put an `aria-label` on the `ToggleGroup` for the group as a whole. Radix ToggleGroup handles roving focus and the pressed state, so keyboard users can arrow through and toggle with Space or Enter.

### Do I still wrap items in a Tooltip by hand?

No. `tooltip` on a `ToggleGroupItem` is wired like Button's: it shows on hover and focus, adds no DOM around the item (so the segmented thumb and roving focus are unaffected), and takes `tooltipPlacement`. Wrap by hand only for rich content, and pass `tooltip={false}` on that item so the two do not stack.

---

<!-- https://www.koalaui.com/docs/components/toolbar.md -->

# Toolbar

A keyboard-navigable band that groups icon controls, dropdown triggers, toggle sets and separators into one unit. Built on Radix Toolbar, so it ships roving tab focus and arrow-key movement.

```tsx
<Toolbar aria-label="Text formatting">
  {/* Text style — a DropdownMenu trigger */}
  <DropdownMenu>
    <Tooltip content="Text style">
      <DropdownMenuTrigger asChild>
        <ToolbarButton caret aria-label="Text style">
          <TextT />
        </ToolbarButton>
      </DropdownMenuTrigger>
    </Tooltip>
    <DropdownMenuContent align="start">…</DropdownMenuContent>
  </DropdownMenu>

  {/* Text color — the caret trigger opens the canonical ColorPicker */}
  <ColorPickerPopover>
    <Tooltip content="Text color">
      <ColorPickerTrigger asChild>
        <ToolbarButton caret aria-label="Text color">
          <span className="size-5 rounded-sm" style={{ backgroundColor: color }} />
        </ToolbarButton>
      </ColorPickerTrigger>
    </Tooltip>
    <ColorPickerContent>
      <ColorPicker value={color} onValueChange={setColor} showAlpha showInput={false} showPresets={false} />
    </ColorPickerContent>
  </ColorPickerPopover>

  <ToolbarSeparator />

  <ToolbarToggleGroup type="multiple" value={marks} onValueChange={setMarks}>
    <ToolbarToggleItem value="bold" tooltip="Bold" shortcut="⌘B">
      <TextB />
    </ToolbarToggleItem>
    <ToolbarToggleItem value="italic" tooltip="Italic" shortcut="⌘I">
      <TextItalic />
    </ToolbarToggleItem>
    <ToolbarToggleItem value="underline" tooltip="Underline" shortcut="⌘U">
      <TextUnderline />
    </ToolbarToggleItem>
    <ToolbarToggleItem value="strike" tooltip="Strikethrough">
      <TextStrikethrough />
    </ToolbarToggleItem>
  </ToolbarToggleGroup>

  <ToolbarSeparator />

  <ToolbarButton tooltip="Link" shortcut="⌘K"><LinkSimple /></ToolbarButton>
  <ToolbarButton tooltip="Quote"><Quotes /></ToolbarButton>
  <ToolbarButton tooltip="Code block"><Code /></ToolbarButton>

  <ToolbarSeparator />

  <ToolbarToggleGroup type="single" value={align} onValueChange={setAlign}>
    <ToolbarToggleItem value="left" tooltip="Align left"><TextAlignLeft /></ToolbarToggleItem>
    <ToolbarToggleItem value="center" tooltip="Align center"><TextAlignCenter /></ToolbarToggleItem>
    <ToolbarToggleItem value="right" tooltip="Align right"><TextAlignRight /></ToolbarToggleItem>
  </ToolbarToggleGroup>

  <ToolbarSeparator />

  <ToolbarButton tooltip="Bullet list"><ListBullets /></ToolbarButton>
  <ToolbarButton tooltip="Numbered list"><ListNumbers /></ToolbarButton>

  <ToolbarSeparator />

  <ToolbarButton tooltip="Insert image"><Image /></ToolbarButton>
  <ToolbarButton tooltip="Comment"><ChatCircle /></ToolbarButton>
</Toolbar>
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add toolbar
```

Manual: run `npm install radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/toolbar/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

```tsx title="usage.tsx"
import {
  Toolbar,
  ToolbarButton,
  ToolbarSeparator,
  ToolbarToggleGroup,
  ToolbarToggleItem,
} from "@/components/ui/toolbar"

export function Example() {
  const [marks, setMarks] = useState<string[]>(["bold"])
  return (
    <Toolbar aria-label="Formatting">
      <ToolbarToggleGroup type="multiple" value={marks} onValueChange={setMarks}>
        <ToolbarToggleItem value="bold" tooltip="Bold" shortcut="⌘B">
          <TextB />
        </ToolbarToggleItem>
        <ToolbarToggleItem value="italic" tooltip="Italic" shortcut="⌘I">
          <TextItalic />
        </ToolbarToggleItem>
      </ToolbarToggleGroup>
      <ToolbarSeparator />
      <ToolbarButton tooltip="Link" shortcut="⌘K">
        <LinkSimple />
      </ToolbarButton>
    </Toolbar>
  )
}
```

## Collapsed

A full format bar can outgrow its surface. Collapse it: give each cluster its own caret dropdown that unlocks only its options (text style, color, marks, link, list, alignment, insert). The same bar, a fraction of the width, and every trigger is the same affordance: a caret, one meaning. (The three-dots overflow is a different thing entirely, reserved for the automatic [Responsive overflow](#responsive-overflow) below, where it means "controls that didn't fit.") Any `ToolbarButton` used as a dropdown trigger stays lit while its menu is open, and a `caret` button flips its chevron. No extra wiring: it's built into the button.

```tsx
<Toolbar aria-label="Compact formatting">
  {/* Each cluster is a caret dropdown that unlocks only its own options. The trigger
      auto-lights and flips its caret while open — no per-trigger className needed. */}
  <DropdownMenu>
    <Tooltip content="Text actions">
      <DropdownMenuTrigger asChild>
        <ToolbarButton caret aria-label="Text actions">
          <TextB />
        </ToolbarButton>
      </DropdownMenuTrigger>
    </Tooltip>
    <DropdownMenuContent align="start">
      <DropdownMenuLabel>Text actions</DropdownMenuLabel>
      {MARKS.map((m) => (
        <DropdownMenuCheckboxItem
          key={m.value}
          checked={marks.includes(m.value)}
          onCheckedChange={() => toggleMark(m.value)}
          onSelect={(e) => e.preventDefault()} // keep open to toggle several
        >
          <m.icon /> {m.label}
        </DropdownMenuCheckboxItem>
      ))}
    </DropdownMenuContent>
  </DropdownMenu>

  {/* …and so on for color, link, list. Alignment is a caret group too — the trigger
      mirrors the active alignment, and the menu is a radio group. */}
  <DropdownMenu>
    <Tooltip content="Alignment">
      <DropdownMenuTrigger asChild>
        <ToolbarButton caret aria-label="Alignment"><TextAlignLeft /></ToolbarButton>
      </DropdownMenuTrigger>
    </Tooltip>
    <DropdownMenuContent align="start">
      <DropdownMenuLabel>Alignment</DropdownMenuLabel>
      <DropdownMenuRadioGroup value={align} onValueChange={setAlign}>…</DropdownMenuRadioGroup>
    </DropdownMenuContent>
  </DropdownMenu>
</Toolbar>
```

## Responsive overflow

Let the bar collapse itself. `ToolbarOverflow` takes your controls as data, shows as many as fit, and folds the rest into the three-dots menu, live, expanding again when the space returns. **Drag the handle** to shrink the track and watch controls move into (and back out of) `More`. Each control's footprint is measured once on first paint, then a `ResizeObserver` only re-runs a cheap greedy pack, so resizing stays smooth. Each control is declared once and rendered in both places (a bar button and a menu row), so the two never drift.

```tsx
const [marks, setMarks] = useState(["bold"])
const toggle = (id) => setMarks((m) => (m.includes(id) ? m.filter((x) => x !== id) : [...m, id]))

// Declare the controls once; the primitive renders each as a bar button AND a menu row.
const items: ToolbarOverflowItem[] = [
  { type: "action", id: "undo", icon: ArrowUUpLeft, label: "Undo", shortcut: "⌘Z" },
  { type: "action", id: "redo", icon: ArrowUUpRight, label: "Redo", shortcut: "⌘⇧Z" },
  { type: "separator", id: "s1" },
  { type: "toggle", id: "bold", icon: TextB, label: "Bold", shortcut: "⌘B",
    pressed: marks.includes("bold"), onPressedChange: () => toggle("bold") },
  { type: "toggle", id: "italic", icon: TextItalic, label: "Italic",
    pressed: marks.includes("italic"), onPressedChange: () => toggle("italic") },
  // …more controls
]

// One component: it measures its width and folds what doesn't fit into a ⋮ menu, live.
<ToolbarOverflow items={items} aria-label="Formatting" />
```

## Scrolling

The low-chrome alternative to an overflow menu: pass `scrollable` and the bar scrolls on its axis instead of wrapping when its controls exceed the width. A scroll-aware edge fade (the `scroll-fade` utility) hints that there's more on whichever side you can still scroll toward, and the scrollbar is hidden. Reach for this when every control should stay reachable without a menu (a mobile format bar).

```tsx
<Toolbar scrollable aria-label="Formatting" className="w-full max-w-xs">
  <ToolbarButton tooltip="Undo"><ArrowUUpLeft /></ToolbarButton>
  <ToolbarButton tooltip="Redo"><ArrowUUpRight /></ToolbarButton>
  <ToolbarSeparator />
  {/* …more controls than the width can hold; the bar scrolls with an edge fade */}
</Toolbar>
```

## Variants

Three levels of chrome. `floating` (the default) is an elevated pill that hovers over content, like an on-selection format bar. `outline` is the same shape sitting flat on the page, and `plain` is chromeless for a header or footer that already owns its surface.

```tsx
<Toolbar aria-label="Floating">…</Toolbar>

<Toolbar variant="outline" aria-label="Outline">…</Toolbar>

<Toolbar variant="plain" aria-label="Plain">…</Toolbar>
```

## Solid

`solid` is an inverted, high-contrast strip for a contextual bar sitting over media or imagery: a player overlay, a canvas HUD. It's token-pure, flipping foreground and background, so it reads dark on light themes and light on dark, and re-tints its controls and dividers to match.

```tsx
<Toolbar variant="solid" aria-label="Overlay controls">
  <ToolbarButton tooltip="Previous"><SkipBack weight="fill" /></ToolbarButton>
  <ToolbarButton tooltip="Play"><Play weight="fill" className="translate-x-px" /></ToolbarButton>
  <ToolbarButton tooltip="Next"><SkipForward weight="fill" /></ToolbarButton>
  <ToolbarSeparator />
  <ToolbarButton tooltip="Volume"><SpeakerHigh /></ToolbarButton>
</Toolbar>
```

## Primary action

When a bar exists for one action, play in a transport or run in an editor, mark that control with `variant="primary"`. It fills with the brand accent, like a primary Button, and keeps its siblings' box and corners, so the band's rhythm and concentric radius hold and only the fill says it leads. Hover, pressed and open states stay on the fill. Keep it to one per bar; a second filled control and neither one leads.

```tsx
<Toolbar aria-label="Transport">
  <ToolbarButton tooltip="Undo" shortcut="⌘Z"><ArrowUUpLeft weight="bold" /></ToolbarButton>
  <ToolbarButton tooltip="Redo" shortcut="⇧⌘Z"><ArrowUUpRight weight="bold" /></ToolbarButton>
  <ToolbarSeparator />
  <ToolbarButton tooltip="Previous"><SkipBack weight="fill" /></ToolbarButton>
  <ToolbarButton variant="primary" tooltip="Play">
    <Play weight="fill" className="translate-x-px" />
  </ToolbarButton>
  <ToolbarButton tooltip="Next"><SkipForward weight="fill" /></ToolbarButton>
</Toolbar>
```

## Design canvas

The same shell dressed as a design tool's canvas HUD, the way Figma floats its bar over the artboard. It's the `solid` variant for the black chrome, a full run of canvas tools (move, frame, shapes, pen, text, hand, comment, insert), and a trailing group for AI and Dev Mode. Tools are single-select: the one in hand flips to a brand-blue chip, matching Figma's selected tool and the DS's brand-for-primary rule, while shapes and the pen are caret dropdowns whose trigger mirrors the variant currently in hand.

```tsx
// The active tool flips the pressed chip to brand (Figma's selected-tool blue).
const activeTool = "data-[pressed]:bg-brand data-[pressed]:text-brand-foreground data-[pressed]:hover:bg-brand"

<Toolbar variant="solid" aria-label="Design tools">
  <ToolbarButton tooltip="Move" shortcut="V" pressed={tool === "move"}
    onClick={() => setTool("move")} className={activeTool}>
    <Cursor />
  </ToolbarButton>

  {/* Shapes — a caret dropdown; the trigger wears the active shape */}
  <DropdownMenu>
    <Tooltip content="Shapes">
      <DropdownMenuTrigger asChild>
        <ToolbarButton caret aria-label="Shapes" pressed={tool === "shape"} className={activeTool}>
          <ShapeIcon />
        </ToolbarButton>
      </DropdownMenuTrigger>
    </Tooltip>
    <DropdownMenuContent align="start">
      <DropdownMenuRadioGroup value={shape} onValueChange={(v) => { setShape(v); setTool("shape") }}>
        {SHAPE_TOOLS.map((s) => <DropdownMenuRadioItem key={s.value} value={s.value}>…</DropdownMenuRadioItem>)}
      </DropdownMenuRadioGroup>
    </DropdownMenuContent>
  </DropdownMenu>

  {/* …text, hand, comment, insert… */}
  <ToolbarSeparator />
  <ToolbarButton tooltip="AI actions"><MagicWand /></ToolbarButton>
  <ToolbarButton tooltip="Dev Mode" pressed={devMode} onClick={() => setDevMode((v) => !v)}>
    <Code />
  </ToolbarButton>
</Toolbar>
```

## Sizes

`sm` (24px controls) for dense rails, `md` (28px, the default), and `lg` (36px) for a touch-friendly or marketing surface. This `size` axis is the toolbar's own density knob: it deliberately does *not* inherit the page's `comfortable/compact` form density, because a control bar that shrinks to form-compact gets hard to hit. All keep a 40px hit area via an invisible vertical extender, so small controls never get harder to click than they look.

```tsx
<Toolbar size="sm" aria-label="Small">…</Toolbar>

<Toolbar size="md" aria-label="Medium">…</Toolbar>

<Toolbar size="lg" aria-label="Large">…</Toolbar>
```

## Groups, title, and spacing

Build an app bar from three structural parts. `ToolbarGroup` wraps a run of controls into a named region (give it an `aria-label` and screen readers announce it), `ToolbarTitle` is a non-interactive label, and `ToolbarSpacer` is a flexible gap that pushes everything after it to the far end.

```tsx
<Toolbar aria-label="Document" variant="outline" className="w-full max-w-xl">
  <ToolbarTitle>Proposal.md</ToolbarTitle>
  <ToolbarSpacer />
  <ToolbarGroup aria-label="History">
    <ToolbarButton tooltip="Undo"><ArrowUUpLeft /></ToolbarButton>
    <ToolbarButton tooltip="Redo"><ArrowUUpRight /></ToolbarButton>
  </ToolbarGroup>
  <ToolbarSeparator />
  <ToolbarGroup aria-label="Text format">
    <ToolbarToggleGroup type="multiple" value={marks} onValueChange={setMarks}>…</ToolbarToggleGroup>
  </ToolbarGroup>
</Toolbar>
```

## Toggle groups

Wrap controls that hold their pressed state in a `ToolbarToggleGroup`. Use `type="multiple"` for independent on/off marks (bold, italic, underline) or `type="single"` for a mutually exclusive choice (text alignment). A selected item reads as a filled chip.

```tsx
<Toolbar aria-label="Toggle groups">
  <ToolbarToggleGroup type="multiple" value={marks} onValueChange={setMarks}>
    <ToolbarToggleItem value="bold" tooltip="Bold"><TextB /></ToolbarToggleItem>
    <ToolbarToggleItem value="italic" tooltip="Italic"><TextItalic /></ToolbarToggleItem>
    <ToolbarToggleItem value="underline" tooltip="Underline"><TextUnderline /></ToolbarToggleItem>
  </ToolbarToggleGroup>
  <ToolbarSeparator />
  <ToolbarToggleGroup type="single" value={align} onValueChange={setAlign}>
    <ToolbarToggleItem value="left" tooltip="Align left"><TextAlignLeft /></ToolbarToggleItem>
    <ToolbarToggleItem value="center" tooltip="Align center"><TextAlignCenter /></ToolbarToggleItem>
    <ToolbarToggleItem value="right" tooltip="Align right"><TextAlignRight /></ToolbarToggleItem>
  </ToolbarToggleGroup>
</Toolbar>
```

## Dropdown triggers

Set `caret` to make a control grow to fit its glyph and show a trailing chevron: the dropdown-trigger look. Compose it with our [Dropdown Menu](https://www.koalaui.com/docs/components/dropdown-menu.md) or [Popover](https://www.koalaui.com/docs/components/popover.md) via `asChild`. Wrap the trigger in a `Tooltip` for a hint (that keeps the hint outside the trigger, so it never fights the menu's open state).

```tsx
<DropdownMenu>
  <Tooltip content="Text style">
    <DropdownMenuTrigger asChild>
      <ToolbarButton caret aria-label="Text style">
        <TextT />
      </ToolbarButton>
    </DropdownMenuTrigger>
  </Tooltip>
  <DropdownMenuContent align="start">
    <DropdownMenuLabel>Turn into</DropdownMenuLabel>
    <DropdownMenuRadioGroup value={block} onValueChange={setBlock}>
      <DropdownMenuRadioItem value="paragraph">Paragraph</DropdownMenuRadioItem>
      <DropdownMenuRadioItem value="h1">Heading 1</DropdownMenuRadioItem>
      <DropdownMenuRadioItem value="h2">Heading 2</DropdownMenuRadioItem>
    </DropdownMenuRadioGroup>
  </DropdownMenuContent>
</DropdownMenu>
```

## Vertical orientation

Pass `orientation="vertical"` for a tool rail. Arrow-key navigation follows the axis, separators turn horizontal, and `tooltipPlacement="right"` keeps the hints clear of the column.

```tsx
<Toolbar aria-label="Canvas tools" orientation="vertical">
  <ToolbarToggleGroup type="single" orientation="vertical" value={tool} onValueChange={setTool}>
    <ToolbarToggleItem value="select" tooltip="Select" tooltipPlacement="right">…</ToolbarToggleItem>
    <ToolbarToggleItem value="text" tooltip="Text" tooltipPlacement="right">…</ToolbarToggleItem>
    <ToolbarToggleItem value="image" tooltip="Image" tooltipPlacement="right">…</ToolbarToggleItem>
  </ToolbarToggleGroup>
  <ToolbarSeparator />
  <ToolbarButton tooltip="Comment" tooltipPlacement="right"><ChatCircle /></ToolbarButton>
</Toolbar>
```

## Beyond text

The shell is generic. Here it holds media transport controls, showing the same buttons, toggle group, and separators serve a player just as well as an editor.

```tsx
<Toolbar aria-label="Playback controls">
  <ToolbarButton tooltip="Previous"><SkipBack /></ToolbarButton>
  <ToolbarButton tooltip={playing ? "Pause" : "Play"} onClick={toggle}>
    {playing ? <Pause /> : <Play className="translate-x-px" />}
  </ToolbarButton>
  <ToolbarButton tooltip="Next"><SkipForward /></ToolbarButton>
  <ToolbarSeparator />
  <ToolbarToggleGroup type="multiple" value={modes} onValueChange={setModes}>
    <ToolbarToggleItem value="shuffle" tooltip="Shuffle"><Shuffle /></ToolbarToggleItem>
    <ToolbarToggleItem value="repeat" tooltip="Repeat"><Repeat /></ToolbarToggleItem>
  </ToolbarToggleGroup>
  <ToolbarSeparator />
  <ToolbarButton tooltip="Volume"><SpeakerHigh /></ToolbarButton>
</Toolbar>
```

## API reference

### Toolbar

The band. Wraps Radix `Toolbar.Root` and forwards its props (`loop`, `dir`, …).

- `variant` — `"floating"` (default) · `"outline"` · `"plain"` · `"solid"` (inverted, for overlays).
- `size` — `"sm"` · `"md"` (default) · `"lg"`. The toolbar's own density axis; it does not inherit the page's `comfortable/compact` density.
- `scrollable` — scroll on the axis with an edge fade instead of wrapping when controls exceed the width.
- `orientation` — `"horizontal"` (default) · `"vertical"`. Drives both the layout and Radix's arrow-key axis.
- `aria-label` — names the toolbar for assistive tech. Defaults to `"Toolbar"`; set something specific.

### ToolbarButton

An icon control (Radix `Toolbar.Button`).

- `tooltip` — hover/focus hint; a string also becomes the `aria-label` when none is set.
- `shortcut` — a keycap shown in the tooltip (display only, e.g. `"⌘B"`).
- `pressed` — mark the control active (sets `aria-pressed` and the filled chip).
- `caret` — trailing chevron + auto width for a dropdown trigger.
- `asChild` — render as a menu/popover trigger; `static` — drop the press scale.
- `variant`: `"default"` · `"primary"` (the bar's main action, brand-filled).

### ToolbarToggleGroup · ToolbarToggleItem

Controls that hold a pressed state (Radix `Toolbar.ToggleGroup`). The group takes `type` (`"single"` / `"multiple"`) plus `value`/`onValueChange`. Each item shares `tooltip`, `shortcut`, and `tooltipPlacement`.

### ToolbarSeparator · ToolbarLink

A hairline that groups controls (orientation-aware), and a text link that lives in the bar and keeps the roving focus (Radix `Toolbar.Separator` / `Toolbar.Link`).

### ToolbarGroup · ToolbarTitle · ToolbarSpacer

Structure parts. `ToolbarGroup` is an `aria-label`led `role="group"` cluster; `ToolbarTitle` a non-interactive label; and `ToolbarSpacer` a flexible gap that pins later controls to the end.

### ToolbarOverflow

A self-collapsing toolbar. Takes `items` (an array of `action`, `toggle`, and `separator` descriptors), renders as many as fit, and folds the rest into a three-dots menu, remeasuring on resize. Also takes `overflowLabel`, `menuAlign`, and the `Toolbar` variant/size props. Horizontal only.

## FAQ

### How is this different from ButtonGroup?

ButtonGroup fuses a few related buttons into one pill and shares variant/size across them. Toolbar is a larger, keyboard-navigable container built on Radix Toolbar: it has role=toolbar, a single Tab stop with arrow-key movement between controls, separators, toggle groups, and links. Reach for Toolbar when you have many grouped controls (a format bar, a tool rail); reach for ButtonGroup for a small switch like Day/Week/Month.

### Why do all the tooltips glide instead of fading?

The Toolbar wraps its children in a TooltipGroup, so every control shares one bubble (a Tippy singleton) that slides from control to control. It's the smooth way to tooltip a dense row and matches how the rich text editor's toolbar behaves.

### How do I make a dropdown trigger?

Give a ToolbarButton the caret prop and render it asChild of a DropdownMenuTrigger (or PopoverTrigger). Wrap that trigger in a Tooltip for a hint, keeping the Tooltip outside the trigger so it doesn't fight the menu's open state.

### How do I collapse a toolbar that's too wide?

Fold each cluster into its own caret dropdown that unlocks just its options (text style, marks, alignment, insert, …). Keep every trigger a caret so the bar stays consistent — the caret means 'this control has options.' Any ToolbarButton used as a dropdown/popover trigger already lights its chip while open (Radix sets data-state=open on it) and a caret button flips its chevron, so you write plain <ToolbarButton caret> with no per-trigger className. See the Collapsed example.

### Caret dropdown or a three-dots (⋮) overflow: which when?

They're different affordances, don't mix them for the same job. A caret (⌄) means 'this control has its own options' — use it for curated clusters (text style, alignment). A three-dots (⋮) means 'more / overflow' — use it only when controls are moved out of view because they didn't fit, which is exactly what ToolbarOverflow does automatically. So: hand-curated groups get carets (Collapsed); automatic width-based collapse gets the ⋮ (Responsive overflow).

### Can the toolbar collapse automatically based on width?

Yes, with the ToolbarOverflow primitive (see Responsive overflow). Pass your controls as items (action / toggle / separator descriptors); it measures each control's footprint once, then a ResizeObserver re-runs a greedy pack against the live width and folds whatever doesn't fit into a three-dots menu, rendering each control as both a bar button and a menu row. If you'd rather keep everything reachable without a menu, use <Toolbar scrollable> instead.

### Does the toolbar follow the page's comfortable/compact density?

No, by design. Its size axis (sm / md / lg) is the toolbar's own density knob and does not read useDensity(), because a control bar that shrinks to form-compact becomes hard to hit. Set size explicitly. If you do want it to track the surrounding density, pass size from useDensity() yourself.

### Do the animations respect reduced motion?

Yes. Under prefers-reduced-motion: reduce the controls keep every functional state (hover, pressed chip, open highlight) but drop the transition tween and the tactile press-scale, and a caret flips to its open state instantly instead of animating. Nothing moves or eases.

### When should I use pressed vs a ToolbarToggleGroup?

Use the pressed prop on a standalone ToolbarButton when you're driving the active state yourself (e.g. reading it from an editor). Use ToolbarToggleGroup when the toolbar should own the selection: it gives you controlled value/onValueChange and single or multiple semantics with correct ARIA.

### Does it work vertically and in RTL?

Yes. Set orientation="vertical" for a tool rail; arrow-key navigation follows the axis and separators turn horizontal. Direction (LTR/RTL) comes from Radix Toolbar via the dir prop or the nearest DirectionProvider.

---

<!-- https://www.koalaui.com/docs/components/tooltip.md -->

# Tooltip

A small hint shown on hover or focus. Positioning, hover-intent and a11y come from Tippy.js in headless mode - Koala owns the bubble's markup, styled with our tokens. The one component built on a non-Radix primitive.

```tsx
<Button iconOnly aria-label="Save changes">
  <FloppyDisk />
</Button>
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add tooltip
```

Manual: run `npm install tippy.js`, then copy the source into `components/ui/tooltip/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

```tsx title="usage.tsx"
import { FloppyDisk } from "@phosphor-icons/react"
import { Button } from "@/components/ui/button"
import { Tooltip } from "@/components/ui/tooltip"

export function Example() {
  return (
    <Tooltip content="Save changes">
      <Button iconOnly aria-label="Save changes">
        <FloppyDisk />
      </Button>
    </Tooltip>
  )
}
```

## Variants

`variant` sets the content shape. `text` (the default) is a short label on an inverted chip, the page's ink as its ground, so it reads at a glance and never passes for a card. Switch to `graph` when the content is a multi-line card (a title plus stats, a picture, a route): it moves onto the popover surface with Popover's border and shadow, drops the centering for a left-aligned block and adds `8px 12px` padding so the rows aren't cramped against the edge.

```tsx
// Short label - the default
<Tooltip content="Save changes">…</Tooltip>

// Rich data card - left-aligned, roomier padding
<Tooltip
  variant="graph"
  content={
    <div className="space-y-0.5">
      <div className="font-medium text-popover-foreground">Trail Runner GTX</div>
      <div className="text-muted-foreground">1,284 units · 100% of #1</div>
      <div className="text-muted-foreground">$92,448 revenue · +14% MoM</div>
    </div>
  }
>
  <Button variant="outline" iconOnly aria-label="Product stats">
    <ChartBar />
  </Button>
</Tooltip>
```

## Data breakdown

For a richer `graph` tooltip, compose the breakdown parts instead of hand-rolling markup: `TooltipHeader` / `TooltipValue` for the title and total, `TooltipSeparator` for the rule, and `TooltipSection` + `TooltipStat` for tone-railed rows of label / percent / value. The rail color is a token role via `tone` (`brand · info · success · warning · destructive · neutral`), so it tracks the theme - no raw colors. Mark sub-lines with `indent`.

```tsx
<Tooltip
  variant="graph"
  placement="right"
  content={
    <>
      <TooltipHeader>
        <TooltipHeaderText>
          <TooltipTitle>Friday, Jul 5</TooltipTitle>
          <TooltipDescription>Total capacity</TooltipDescription>
        </TooltipHeaderText>
        <TooltipValue>08h 00m</TooltipValue>
      </TooltipHeader>
      <TooltipSeparator />
      <TooltipSection tone="info">
        <TooltipStat label="Tracked time" percent="40%" value="03h 09m" />
        <TooltipStat label="Billable" percent="79%" value="02h 30m" indent />
        <TooltipStat label="Non-billable" percent="21%" value="00h 39m" indent />
      </TooltipSection>
      <TooltipSection tone="neutral">
        <TooltipStat label="Remaining capacity" percent="60%" value="04h 50m" />
      </TooltipSection>
    </>
  }
>
  <Button variant="outline" iconOnly aria-label="Day capacity">
    <Clock />
  </Button>
</Tooltip>
```

## Rich card

The graph variant grows as far as a preview card: a picture, a mark, a title with its status, and a few facts, built from the same parts as the data card. It stays a tooltip as long as it only shows: it opens on hover and focus and holds nothing to click. The moment it needs a button, a form or more than one link, it is a Popover. Keep the picture's corner concentric with the card (8px inside a 16px card) and give it the hairline image outline.

```tsx
<Tooltip
  variant="graph"
  className="w-72"
  content={
    <>
      <img src="/pages/templates/urban-luxe-neo.jpg" alt="" className="aspect-video rounded-sm object-cover" />
      <TooltipHeader>
        <TooltipHeaderText>
          <TooltipTitle>Urban Luxe Neo</TooltipTitle>
          <TooltipDescription>Interior studio template</TooltipDescription>
        </TooltipHeaderText>
        <TooltipValue>New</TooltipValue>
      </TooltipHeader>
      <TooltipSeparator />
      <TooltipSection tone="brand">
        <TooltipStat label="Pages" value="12" />
        <TooltipStat label="Sections" value="48" />
      </TooltipSection>
    </>
  }
>
  <a href="/templates/urban-luxe-neo">Urban Luxe Neo</a>
</Tooltip>
```

## Placement

`placement` takes any Tippy placement (each also accepts a `-start` / `-end` suffix). The bubble grows out of the edge nearest the trigger.

The bubble is positioned `fixed`, so one that lands past the edge of the screen is clipped there instead of widening the page: a phone never scrolls sideways because of a tooltip. While it is up it follows its trigger when the trigger moves (a drawer sliding in, a row that grows), rather than staying where the trigger was when it opened.

```tsx
<Tooltip content="Tooltip" placement="top">…</Tooltip>
<Tooltip content="Tooltip" placement="right">…</Tooltip>
<Tooltip content="Tooltip" placement="bottom">…</Tooltip>
<Tooltip content="Tooltip" placement="left">…</Tooltip>
```

## With an icon

`content` is any node - a leading glyph sits a 4px gap from the label. Pair it with an icon-only button that would otherwise have no visible name.

```tsx
<Tooltip
  content={<><Copy /> Copy to clipboard</>}
>
  <Button variant="ghost" iconOnly aria-label="Copy">
    <Copy />
  </Button>
</Tooltip>
```

## Interactive

`interactive` keeps the tooltip open while the pointer is over it, so it can hold a link or action. Tune the hover-intent with `delay` (`[open, close]` in ms).

```tsx
<Tooltip
  interactive
  delay={[150, 80]}
  content={<>Read the <a href="/docs" className="underline">docs</a></>}
>
  <Button variant="outline" iconOnly aria-label="More info">
    <Info />
  </Button>
</Tooltip>
```

## Controlled

Pass `open` to drive the bubble yourself: the hover and focus triggers switch off, and it shows exactly while `open` is true. Use it for a hint that answers an action rather than a hover, like a copy confirmation.

```tsx
const [copied, setCopied] = React.useState(false)

<Tooltip open={copied} content="Copied to clipboard">
  <Button variant="outline" onClick={() => { copy(); setCopied(true) }}>
    Copy command
  </Button>
</Tooltip>
```

## Anchored to a point

Some things have no element to hang a tooltip on: a pin drawn on a map, a point on a chart, whatever sits under the cursor on a canvas. Give the tooltip an `anchor` instead of a child, the point in viewport coordinates (or a box, with `width` and `height`), and drive `open` from your own hover logic. Moving the anchor re-positions the open bubble without re-mounting it, and the bubble takes no pointer events, so it never steals the pointer it follows.

```tsx
const [hover, setHover] = React.useState<{ pin: Pin; x: number; y: number } | null>(null)

<div onPointerMove={(e) => setHover(nearestPin(e))} onPointerLeave={() => setHover(null)}>
  {/* the map, the chart, the canvas */}
  <Tooltip
    open={hover != null}
    anchor={{ x: hover?.x ?? 0, y: hover?.y ?? 0 }}
    variant="graph"
    content={<PinCard pin={hover?.pin} />}
  />
</div>
```

## Group

Wrap a set of tooltips in `TooltipGroup` to share a single bubble that *glides* from trigger to trigger - a Tippy singleton under the hood. Instead of each tooltip fading out and then in with its own delay, the bubble repositions instantly with a CSS `transform` transition. Use this for toolbars, avatar stacks, or any dense row of labeled controls.

```tsx
import { Tooltip, TooltipGroup } from "@/components/ui/tooltip"

<TooltipGroup>
  <Tooltip content="Edit" placement="top">
    <Button variant="ghost" iconOnly aria-label="Edit">
      <PencilSimple />
    </Button>
  </Tooltip>
  <Tooltip content="Copy" placement="top">
    <Button variant="ghost" iconOnly aria-label="Copy">
      <Copy />
    </Button>
  </Tooltip>
  <Tooltip content="Save" placement="top">
    <Button variant="ghost" iconOnly aria-label="Save">
      <FloppyDisk />
    </Button>
  </Tooltip>
  <Tooltip content="Delete" placement="top">
    <Button variant="ghost" iconOnly aria-label="Delete">
      <Trash />
    </Button>
  </Tooltip>
</TooltipGroup>
```

The `delay` and `offset` props on individual `Tooltip`s inside a group are ignored - set them once on `TooltipGroup`.

## On form inputs

Wrap an `InputSuffixButton` in a `Tooltip` to surface field hints - password rules, format requirements, contextual help - without cluttering the label. Place the button directly inside `InputRoot` (not inside `InputSuffix`, which is `aria-hidden`) so keyboard users can reach it.

```tsx
<div className="w-72 space-y-4">
  <div className="space-y-1.5">
    <label className="text-sm font-medium">API key</label>
    <InputRoot>
      <InputField placeholder="sk-…" />
      <Tooltip content="Your secret key - never share this publicly">
        <InputSuffixButton aria-label="API key help">
          <Question />
        </InputSuffixButton>
      </Tooltip>
    </InputRoot>
  </div>
  <div className="space-y-1.5">
    <label className="text-sm font-medium">Webhook URL</label>
    <InputRoot>
      <InputField placeholder="https://…" />
      <Tooltip
        content="Must be HTTPS and return 200 within 5 s"
        placement="right"
      >
        <InputSuffixButton aria-label="Webhook URL requirements">
          <Info />
        </InputSuffixButton>
      </Tooltip>
    </InputRoot>
  </div>
</div>
```

## Inside a dialog

Tippy appends its bubble to `document.body`, so tooltips always render above the dialog's stacking context - no extra `z-index` or portal config required. A small icon next to a form label is the most common pattern.

Focus opens a tooltip only when it is keyboard focus. A dialog or drawer opened with a click or a tap moves focus onto its first control by script, and that shows no bubble; opened from the keyboard, the focused control shows its hint like any other. To drop focus hints altogether, as the help icons below do, pass `trigger="mouseenter"`.

```tsx
<Dialog>
  <DialogTrigger asChild>
    <Button>Open dialog</Button>
  </DialogTrigger>
  <DialogContent size="sm">
    <DialogHeader>
      <DialogTitle>Create webhook</DialogTitle>
      <DialogDescription>
        Koala will POST a JSON payload to this URL on each event.
      </DialogDescription>
    </DialogHeader>
    <div className="space-y-4">
      <div className="space-y-1.5">
        <div className="flex items-center gap-1.5">
          <label className="text-sm font-medium">Endpoint URL</label>
          <Tooltip content="Must be HTTPS and publicly reachable" trigger="mouseenter">
            <button
              type="button"
              aria-label="Endpoint URL help"
              className="rounded text-muted-foreground transition-colors duration-fast ease-out hover:text-foreground focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-brand"
            >
              <Info className="size-3.5" />
            </button>
          </Tooltip>
        </div>
        <InputRoot>
          <InputField placeholder="https://…" />
        </InputRoot>
      </div>
      <div className="space-y-1.5">
        <div className="flex items-center gap-1.5">
          <label className="text-sm font-medium">Secret</label>
          <Tooltip
            content="Signs the X-Koala-Signature header"
            placement="right"
            trigger="mouseenter"
          >
            <button
              type="button"
              aria-label="Secret help"
              className="rounded text-muted-foreground transition-colors duration-fast ease-out hover:text-foreground focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-brand"
            >
              <Lock className="size-3.5" />
            </button>
          </Tooltip>
        </div>
        <InputRoot>
          <InputField placeholder="whsec_…" />
        </InputRoot>
      </div>
    </div>
    <DialogFooter>
      <DialogClose asChild>
        <Button variant="outline">Cancel</Button>
      </DialogClose>
      <Button>Create webhook</Button>
    </DialogFooter>
  </DialogContent>
</Dialog>
```

## Keyboard shortcut hint

Include a `Kbd` in `content` to pair an action name with its shortcut. On the inverted chip the key is built from the chip's own ink, so the same `Kbd` reads on both variants. Combine with `TooltipGroup` on a toolbar so the bubble glides between buttons instead of re-fading.

```tsx
<TooltipGroup>
  <Tooltip
    placement="bottom"
    content={
      <>New file <Kbd size="sm" className="ml-1">⌘N</Kbd></>
    }
  >
    <Button variant="ghost" iconOnly aria-label="New file">
      <FilePlus />
    </Button>
  </Tooltip>
  <Tooltip
    placement="bottom"
    content={
      <>Search <Kbd size="sm" className="ml-1">⌘K</Kbd></>
    }
  >
    <Button variant="ghost" iconOnly aria-label="Search">
      <MagnifyingGlass />
    </Button>
  </Tooltip>
  <Tooltip
    placement="bottom"
    content={
      <>Settings <Kbd size="sm" className="ml-1">⌘,</Kbd></>
    }
  >
    <Button variant="ghost" iconOnly aria-label="Settings">
      <GearSix />
    </Button>
  </Tooltip>
</TooltipGroup>
```

## Transitions

Both transition styles are interruptible CSS transitions - never keyframe animations - so re-hovering mid-exit retargets smoothly without resetting from the beginning.

### Shift-away (standalone)

The standalone `Tooltip` uses a shift-away effect: on exit the bubble scales to 95 % and slides a few pixels away from the trigger. The direction is derived from `data-placement` (stamped at mount from Popper.js), so the bubble always retreats toward its origin edge regardless of the configured placement.

```tsx
<Tooltip content="Shift-away on exit" placement="top">
  <Button variant="outline" iconOnly aria-label="Info">
    <Info />
  </Button>
</Tooltip>
```

```tsx title="tooltip.tsx - default transition classes"
// Opacity + scale (95→100) + directional slide driven by data-placement
"data-[state=hidden]:opacity-0 data-[state=visible]:opacity-100"
"data-[state=hidden]:scale-95 data-[state=visible]:scale-100"

// Retreats toward the nearest trigger edge on exit:
"data-[placement^=top]:data-[state=hidden]:-translate-y-1"
"data-[placement^=bottom]:data-[state=hidden]:translate-y-1"
"data-[placement^=left]:data-[state=hidden]:-translate-x-1"
"data-[placement^=right]:data-[state=hidden]:translate-x-1"
```

### Glide (singleton / group)

Inside a `TooltipGroup` the shared bubble uses the `singleton` transition variant: opacity-only on the bubble element (no scale, so it doesn’t shrink between consecutive triggers). Spatial motion is handled entirely by Tippy’s `moveTransition` - a single `transform` transition that drives the positional glide.

```tsx
// Hover slowly between the buttons to see the glide
<TooltipGroup>
  <Tooltip content="Edit"><Button …><PencilSimple /></Button></Tooltip>
  <Tooltip content="Copy"><Button …><Copy /></Button></Tooltip>
  <Tooltip content="Save"><Button …><FloppyDisk /></Button></Tooltip>
</TooltipGroup>
```

```tsx title="tooltip.tsx - singleton transition + moveTransition"
// Bubble: opacity-only (no scale jitter as it glides between triggers)
"data-[state=hidden]:opacity-0 data-[state=visible]:opacity-100"
"scale-100"  // fixed - spatial motion is not on the bubble element

// Positional glide - set on the Tippy singleton source:
moveTransition="transform var(--duration-base) var(--ease-out)"
```

### Base transition (shared)

Both variants extend the same base transition declaration. Only specific properties are named - never `transition: all` - so unrelated properties (like `background-color`) aren’t accidentally caught and the browser can composite the animation on the GPU.

```tsx title="tooltip.tsx - base transition"
// Tailwind class: "transition duration-fast ease-out"
// Expands to:
//   transition-property: opacity, transform, scale, filter;
//   transition-duration: var(--duration-fast); /* 160 ms */
//   transition-timing-function: var(--ease-out); /* cubic-bezier(0.23, 1, 0.32, 1) */
```

## Speed & delay

The bubble always animates at `duration-fast` (160 ms) - fast enough not to block the user, slow enough to feel intentional rather than a jump cut. The three motion tokens side by side:

The easing curve - for both the bubble animation and the singleton glide - is `ease-out`: an aggressive initial velocity that decelerates sharply. It reads as snappy without being harsh, and is the right curve for any short UI enter/exit:

Hover-intent is separate from animation speed and is controlled by the `delay` prop - an `[open, close]` tuple in ms. Animation speed stays at 160 ms regardless.

```tsx title="delay examples"
// Default - 150 ms open intent, instant close
<Tooltip delay={[150, 0]} content="…">…</Tooltip>

// Interactive - give the user time to reach the bubble before it closes
<Tooltip interactive delay={[150, 80]} content={<a href="…">Link</a>}>…</Tooltip>

// Instant open (kiosk / touch UI with no hover ambiguity)
<Tooltip delay={0} content="…">…</Tooltip>

// Group - delay is set once and shared by all children. The 200 ms close delay is the grace
// period that lets the pointer reach the next trigger while the bubble is still up.
<TooltipGroup delay={[150, 200]}>
  <Tooltip content="Save">…</Tooltip>
  <Tooltip content="Copy">…</Tooltip>
</TooltipGroup>
```

## FAQ

### Why is Tooltip the one component not built on Radix?

Tooltip uses Tippy.js in headless mode for positioning, hover-intent, and a11y, because its placement and singleton glide behavior go beyond what the Radix primitive offers. Koala still owns the bubble markup, styled with our tokens, so this is a documented exception to the Radix-first rule.

### When should I use variant="graph" instead of the default?

Use `graph` whenever `content` is more than a single short line - a title plus a couple of stat rows, like the data card shown over a chart bar. It left-aligns the block and adds 8px/12px padding so the rows breathe; the default `text` variant centers a single label with tight padding, which looks cramped around multi-line content. Inside a `TooltipGroup` the shared bubble has one shape, so set `variant` on the group, not the individual tooltips.

### How do I keep a tooltip open so I can click a link inside it?

Pass `interactive`, which keeps the bubble open while the pointer is over it. Pair it with a `delay` like `[150, 80]` so the close delay gives the user time to travel from the trigger to the bubble before it dismisses.

### What is TooltipGroup for?

Wrap several `Tooltip`s in `TooltipGroup` to share one bubble that glides from trigger to trigger (a Tippy singleton) instead of each fading out and in. Use it for toolbars, avatar stacks, or any dense row of labeled controls.

### Why are my per-tooltip delay and offset being ignored?

Inside a `TooltipGroup` the `delay` and `offset` on individual `Tooltip`s are ignored because one shared bubble can have only one timing and distance. Set `delay` and `offset` once on the `TooltipGroup` instead.

### Does a tooltip pop open when a dialog auto-focuses its button?

Only when the dialog was opened from the keyboard. Focus opens a tooltip only when it is keyboard focus: the focus a click or a tap gives, and the focus a dialog or drawer opened by one moves inside by script, show nothing. To drop focus hints altogether, pass `trigger="mouseenter"` (the default is `"mouseenter focus"`), knowing keyboard users then never see that hint.

### Can a tooltip make the page scroll sideways on a phone?

No. The bubble is positioned `fixed`, so when it lands past the edge of the screen (its trigger still sliding in with a drawer, or hugging the edge) it is clipped by the viewport instead of widening the page. While it is up it also follows its trigger as the trigger moves, so it settles next to it once the drawer is in place.

### Is a rich preview card a tooltip or a popover?

A tooltip, as long as it only shows: it opens on hover and focus, the pointer never has to enter it, and it holds nothing to click, however much it shows (a picture, a title, a status, a few facts). Once it needs a button, a form or several links, make it a Popover, which opens on click and takes focus. For a single link, `interactive` keeps a tooltip open while the pointer travels into it.

### How do I show a tooltip over a map pin or a point on a chart?

Give it an `anchor`, the point in viewport coordinates (or a box with `width` and `height`), instead of a child element, and drive `open` from your own hover logic. The bubble follows the anchor as it moves and takes no pointer events, so it can sit right under the cursor without flickering.

### Do I need to manage z-index to show a tooltip above a dialog?

No. Tippy appends the bubble to `document.body`, so it renders above the dialog stacking context with no extra `z-index` or portal configuration. While an element is full screen (a video player, a file preview) the bubble goes into that element instead, because the browser paints nothing outside it over the screen.

---

<!-- https://www.koalaui.com/docs/components/tree.md -->

# Tree

A nesting tree view for file explorers, category browsers and any hierarchy. Built on Radix Collapsible, with single selection, full keyboard navigation and CSS guide rails that trace every level.

```tsx
<Tree defaultValue="button.tsx" defaultExpandedValues={["src", "components", "lib", "public"]}>
  <TreeItem value="src" label="src" icon={<Folder />} expandedIcon={<FolderOpen />}>
    <TreeItem value="components" label="components" icon={<Folder />} expandedIcon={<FolderOpen />}>
      <TreeItem value="button.tsx" label="button.tsx" icon={<FileCode />} />
      <TreeItem value="card.tsx" label="card.tsx" icon={<FileCode />} />
      <TreeItem value="tree.tsx" label="tree.tsx" icon={<FileCode />} />
    </TreeItem>
    <TreeItem value="lib" label="lib" icon={<Folder />} expandedIcon={<FolderOpen />}>
      <TreeItem value="utils.ts" label="utils.ts" icon={<FileCode />} />
    </TreeItem>
    <TreeItem value="globals.css" label="globals.css" icon={<FileText />} />
  </TreeItem>
  <TreeItem value="public" label="public" icon={<Folder />} expandedIcon={<FolderOpen />}>
    <TreeItem value="logo.svg" label="logo.svg" icon={<FileImage />} />
  </TreeItem>
  <TreeItem value="package.json" label="package.json" icon={<FileText />} />
  <TreeItem value="README.md" label="README.md" icon={<FileText />} />
</Tree>
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add tree
```

Manual: run `npm install radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/tree/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

```tsx title="usage.tsx"
import { Tree, TreeItem } from "@/components/ui/tree"

export function Example() {
  return (
    <Tree defaultExpandedValues={["src"]}>
      <TreeItem value="src" label="src">
        <TreeItem value="index.ts" label="index.ts" />
      </TreeItem>
      <TreeItem value="package.json" label="package.json" />
    </Tree>
  )
}
```

A `TreeItem` with children is a branch (it renders a caret and a collapsible panel); without children it's a leaf. The `value` is the node's stable identity for selection and expansion. Pass `label` and `icon` so every row stays visually consistent, and nest items as `children` for depth.

## Selection

Tree holds a single selection. Control it with `value` / `onValueChange`, or let it manage its own with `defaultValue`. Mark any node `disabled` to take it out of selection, expansion, and the keyboard order.

```tsx
const [selected, setSelected] = useState("getting-started")

<Tree value={selected} onValueChange={setSelected} defaultExpandedValues={["guides", "components"]}>
  <TreeItem value="guides" label="Guides" icon={<Folder />} expandedIcon={<FolderOpen />}>
    <TreeItem value="getting-started" label="Getting started" icon={<FileText />} />
    <TreeItem value="installation" label="Installation" icon={<FileText />} />
  </TreeItem>
  <TreeItem value="components" label="Components" icon={<Folder />} expandedIcon={<FolderOpen />}>
    <TreeItem value="overview" label="Overview" icon={<FileText />} />
    <TreeItem value="changelog" label="Changelog" icon={<FileText />} disabled />
  </TreeItem>
</Tree>
```

## Trailing actions & guides

The tree isn't only for files. Drop a count, a badge, or a menu in the `actions` slot, and turn off the indent rails with `guides={false}` when the icons alone carry the hierarchy.

```tsx
<Tree guides={false} defaultExpandedValues={["electronics"]}>
  <TreeItem
    value="electronics"
    label="Electronics"
    icon={<Laptop />}
    actions={<Badge variant="secondary" size="sm">128</Badge>}
  >
    <TreeItem value="phones" label="Phones" icon={<DeviceMobile />} actions={<Badge variant="secondary" size="sm">54</Badge>} />
    <TreeItem value="audio" label="Audio" icon={<Headphones />} actions={<Badge variant="secondary" size="sm">31</Badge>} />
    <TreeItem value="laptops" label="Laptops" icon={<Laptop />} actions={<Badge variant="secondary" size="sm">43</Badge>} />
  </TreeItem>
</Tree>
```

## Drag to reorder

Pass `onMove` and every row becomes draggable. Drop near the top or bottom of a row to place a node `before` or `after` it, or onto the middle of a folder to drop it `inside`. The tree doesn't own your data, so it reports the move and you apply it; dropping a node into its own subtree is blocked, and `Alt` + `↑` / `↓` reorders siblings from the keyboard.

```tsx
const [tree, setTree] = useState(INITIAL_TREE)

// The tree doesn't own your data; apply the reported move to it.
function handleMove({ value, target, position }: TreeMoveEvent) {
  const { rest, found } = detach(tree, value) // pull the node out
  if (!found) return
  setTree(insert(rest, { value, target, position }, found)) // drop it back in
}

<Tree onMove={handleMove} defaultExpandedValues={["app", "components"]}>
  <TreeItem value="app" label="app" icon={<Folder />} expandedIcon={<FolderOpen />}>
    <TreeItem value="layout.tsx" label="layout.tsx" icon={<FileCode />} />
    <TreeItem value="page.tsx" label="page.tsx" icon={<FileCode />} />
  </TreeItem>
  <TreeItem value="README.md" label="README.md" icon={<FileText />} />
</Tree>
```

## Keyboard

Focus the tree and navigate without the mouse: `↑` / `↓` move between visible rows, `→` expands a collapsed branch then steps into it, `←` collapses an open branch then steps out to its parent, `Home` / `End` jump to the first and last rows, and `Enter` / `Space` select (and toggle a branch).

## API reference

### Tree

The `role="tree"` root. Owns selection and expansion state and forwards every other `ul` prop.

- `value` / `defaultValue` / `onValueChange`: the selected node's `value` (single selection).
- `expandedValues` / `defaultExpandedValues` / `onExpandedChange`: the set of expanded branch values.
- `guides`: show the nesting guide rails (default `true`).
- `onMove`: enables drag-to-reorder (and Alt+↑/↓); fires `{ value, target, position }` where `position` is `before` / `after` / `inside`. Apply it to your own data.

### TreeItem

A node. A branch when it has `children`, a leaf when it doesn't. Forwards every other `li` prop.

- `value`: required stable identity for selection and expansion.
- `label`: the row label.
- `icon` / `expandedIcon`: leading glyph, with an optional swap while a branch is open.
- `actions`: trailing content (a count, a badge, a menu).
- `disabled`: removes the node from selection, expansion, and focus.

## FAQ

### What makes a TreeItem a branch instead of a leaf?

Children. A `TreeItem` with nested `TreeItem` children renders a caret and a collapsible panel (a branch); one without children is a leaf. There is no separate type prop, just the presence of `children`.

### How do I control which node is selected?

Tree holds a single selection. Drive it with `value` and `onValueChange` for a controlled tree, or pass `defaultValue` to let it manage its own. Each `TreeItem` needs a stable `value` since that is the identity used for both selection and expansion.

### How does drag-to-reorder work given the tree does not own my data?

Pass `onMove` and every row becomes draggable. It fires `{ value, target, position }` where `position` is `before`, `after`, or `inside`, and you apply that move to your own data; dropping a node into its own subtree is blocked for you.

### What do the arrow keys do?

With the tree focused, up and down move between visible rows, right expands a collapsed branch then steps in, and left collapses an open branch then steps out to the parent. Home and End jump to the first and last rows, Enter or Space select, and with `onMove` set, Alt plus up or down reorders siblings.

### How do I turn off the indent guide rails?

Pass `guides={false}` on the `Tree` root. The rails are on by default; switch them off when leading icons alone carry the hierarchy, as in the category browser example.

### How do I add a count or menu to a row?

Use the `actions` slot on `TreeItem` for trailing content like a Badge, a count, or a menu. For the leading glyph use `icon`, and optionally `expandedIcon` to swap it (for example Folder to FolderOpen) while a branch is open.

---

<!-- https://www.koalaui.com/docs/components/video-player.md -->

# Video Player

A native way to play media: a real video element wrapped in a composable control surface. The scrubber and volume bar are Radix Sliders, and the controls auto-hide and stay legible over any frame.

```tsx
<VideoPlayer>
  <Video src={src} poster={poster} preload="metadata" />
  <VideoSpinner />
  <VideoControls>
    <VideoBar>
      <VideoPlayButton />
      <VideoSeek />
      <VideoTime />
      <VideoVolume />
      <VideoFullscreen />
    </VideoBar>
  </VideoControls>
</VideoPlayer>
```

## Installation

```bash
# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add video-player
```

Manual: run `npm install radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/video-player/` and adjust the import paths to your project. Components pull `cn` from `lib/utils`, the `tv` wrapper from `lib/tv`, and (for multi-part components) `createContext` from `lib/create-context`.

## Usage

```tsx title="usage.tsx"
import {
  VideoPlayer,
  Video,
  VideoControls,
  VideoBar,
  VideoPlayButton,
  VideoSeek,
  VideoTime,
  VideoVolume,
  VideoFullscreen,
  VideoSpinner,
} from "@/components/ui/video-player"

export function Example() {
  return (
    <VideoPlayer>
      <Video src="/clip.mp4" poster="/clip.jpg" preload="metadata" />
      <VideoSpinner />
      <VideoControls>
        <VideoBar>
          <VideoPlayButton />
          <VideoSeek />
          <VideoTime />
          <VideoVolume />
          <VideoFullscreen />
        </VideoBar>
      </VideoControls>
    </VideoPlayer>
  )
}
```

## Anatomy

The player is composed from named parts, never dot-notation. Drop in only the controls you need and arrange them however you like; every part reads the shared playback state from `VideoPlayer`'s context, so order and grouping are entirely up to you.

```tsx title="anatomy.tsx"
<VideoPlayer>
  <Video src={src} poster={poster} preload="metadata" />
  <VideoSpinner />
  <VideoControls>
    <VideoBar>
      <VideoPlayButton />
      <VideoSeek />
      <VideoTime />
      <VideoVolume />
      <VideoFullscreen />
    </VideoBar>
  </VideoControls>
</VideoPlayer>
```

## Minimal

Nothing is required but `VideoPlayer` and `Video`. Here's a stripped-back bar with just play, scrubber, and timecode on a single row.

```tsx
<VideoPlayer>
  <Video src={src} poster={poster} preload="metadata" />
  <VideoControls>
    <VideoBar>
      <VideoPlayButton />
      <VideoSeek />
      <VideoTime />
    </VideoBar>
  </VideoControls>
</VideoPlayer>
```

## Scrub preview

Hover (or drag) the scrubber and a timecode bubble rides the cursor, showing the moment you'd land on before you commit, so you can see where you're heading and, against the total in `VideoTime`, how much is left. It's built into `VideoSeek`, with no extra props. With `preload="metadata"` the duration is known up front, so it works before you ever press play.

```tsx
<VideoPlayer>
  <Video src={src} poster={poster} preload="metadata" />
  <VideoSpinner />
  <VideoControls>
    <VideoBar>
      <VideoPlayButton />
      <VideoSeek />
      <VideoTime />
      <VideoVolume />
      <VideoFullscreen />
    </VideoBar>
  </VideoControls>
</VideoPlayer>
```

## Hover controls

By default the controls stay up while the video is paused and auto-hide after an idle beat during playback. Pass `revealOn="hover"` for the cinematic treatment instead: the chrome is hidden until you point at the player, paused or playing alike, and reveals again on hover or when you tab into it (keyboard users are never stranded). The idle timer is skipped in this mode, visibility simply tracks the pointer.

It pairs naturally with the native `<video>` props that `Video` forwards: `autoPlay`, `loop`, and `muted` turn it into an ambient product loop with mute and zoom (fullscreen) one hover away. Browsers only allow autoplay on a muted video, so keep `muted` on whenever you set `autoPlay`.

```tsx
// Controls stay hidden until you hover the player (or tab into it).
// autoPlay / loop / muted are native <video> props that Video forwards.
<VideoPlayer revealOn="hover">
  <Video src={src} poster={poster} autoPlay loop muted preload="auto" />
  <VideoSpinner />
  <VideoControls>
    <VideoBar>
      <VideoPlayButton />
      <VideoSeek />
      <VideoTime />
      <VideoVolume />
      <VideoFullscreen />
    </VideoBar>
  </VideoControls>
</VideoPlayer>
```

## Labels

Every word the player speaks, from the play tooltip to the slider names a screen reader announces, comes from `labels`. Pass the keys you want to change; the rest keep their English defaults.

```tsx
<VideoPlayer
  labels={{
    play: "Reproducir",
    pause: "Pausa",
    seek: "Buscar",
    mute: "Silenciar",
    unmute: "Activar sonido",
    volume: "Volumen",
    enterFullscreen: "Pantalla completa",
    exitFullscreen: "Salir de pantalla completa",
    buffering: "Cargando",
  }}
>
  …
</VideoPlayer>
```

## Controlled volume

Pass `volume` and `muted` to own the level. The volume bar, the mute button and the arrow keys then show your values and report changes through `onVolumeChange` and `onMutedChange`, and the player stops writing volume or mute to the `<video>`. That is what lets you remember the level between visits, or play the sound somewhere else: audio tracks recorded apart from the picture and kept in sync with a video that stays muted. The demo keeps the level in state and applies it to the element itself.

```tsx
const [volume, setVolume] = React.useState(0.4)
const [muted, setMuted] = React.useState(false)

<VideoPlayer
  volume={volume}
  onVolumeChange={setVolume}
  muted={muted}
  onMutedChange={setMuted}
>
  {/* The player no longer writes to the element: apply the level
      yourself, or play the sound somewhere else. */}
  <Video ref={videoRef} src={src} />
  …
</VideoPlayer>
```

## Reaching the element

A `ref` on `Video` reaches the real `<video>`; the player keeps its own ref alongside yours. Media handlers you pass (`onPlay`, `onTimeUpdate`, `onVolumeChange` and the rest) run after the player's own, so listening to the element never cuts the controls off from its state.

```tsx title="element.tsx"
const videoRef = React.useRef<HTMLVideoElement>(null)

// Slave separately recorded audio to the video clock, recover a stalled decoder...
React.useEffect(() => attachAudioTracks(videoRef.current), [])

<VideoPlayer>
  <Video
    ref={videoRef}
    src={src}
    // Runs after the player's own handler, so the controls keep up.
    onTimeUpdate={(e) => saveProgress(e.currentTarget.currentTime)}
  />
  …
</VideoPlayer>
```

## Keyboard

Click the video to focus the player, then drive it from the keyboard. The Radix scrubber and volume slider keep their own arrow-key handling when focused, so the shortcuts below only fire when the player frame itself holds focus.

| Key | Action |
| --- | --- |
| Space / K | Play / pause |
| ← / → | Seek 5 seconds |
| ↑ / ↓ | Volume up / down |
| M | Mute / unmute |
| F | Toggle fullscreen |

## FAQ

### Which parts are required?

Only `VideoPlayer` and `Video`. Everything else, including `VideoControls`, `VideoBar`, and the individual controls, is optional. Every part reads playback state from the `VideoPlayer` context, so you drop in just the controls you need and arrange them in any order.

### Why do the controls render white-on-dark instead of using theme tokens?

The control bar floats over arbitrary video frames, so it cannot borrow a theme surface that might turn white over a bright shot. Like every native player it carries its own fixed contrast: white glyphs on a black scrim, legible over any frame in all four themes. This is a deliberate exception to semantic-roles-only.

### How do I get the seek preview to work before pressing play?

Set `preload="metadata"` on the `Video`. That makes the duration known up front, so the timecode bubble that rides the scrubber in `VideoSeek` can render before playback ever starts. The preview is built into `VideoSeek` with no extra props.

### Are the scrubber and volume bar accessible by keyboard?

Yes. Both `VideoSeek` and `VideoVolume` are Radix Sliders, so arrow-key handling and ARIA come for free when they hold focus. Click the video to focus the player frame for the player-level shortcuts (Space or K to play, arrows to seek and adjust volume, M to mute, F for fullscreen).

### Why is my single-row bar wrapping?

`VideoBar` lays its children on one line; the timecode in `VideoTime` is `shrink-0` and nowrap so it never reflows, and the scrubber yields the space instead. If a custom control is forcing a wrap, check that it is not stretching the row beyond the player width.

### Can I show a loading spinner while the video buffers?

Yes, add `VideoSpinner`. It reads the buffering state from context and centers a spinner over the frame, under the controls, while the video is waiting on data.

### How do I keep the controls hidden until hover?

Set `revealOn="hover"` on `VideoPlayer`. The chrome stays hidden until you point at the player (paused or playing alike) and reveals on hover or when you tab into it for keyboard access. The default, `revealOn="auto"`, keeps controls up while paused and auto-hides them after an idle beat during playback. Tune that idle delay with `hideDelay` (milliseconds, default 2600).

### How do I autoplay, loop, or mute the video?

`autoPlay`, `loop`, and `muted` are native `<video>` attributes, and `Video` forwards every prop to the underlying element, so set them directly: `<Video autoPlay loop muted />`. Browsers block autoplay on a video with sound, so keep `muted` on whenever you use `autoPlay`.