# Koala UI documentation

> A commercial React design system: 151 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.
> 46 foundation components are free; the other 105, the sections, the page
> examples and the templates come with Koala UI Pro.

Every docs page (guides, foundations and components; a Pro component with its API and usage, never its source) 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: the 46 foundation components (buttons, form controls, overlays,
  menus, tabs, feedback), the lib helpers and the design tokens. Their docs, code included, are below.
- Pro, with a license: the other 105 components, 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 Pro component's page documents its API and usage, and a
  section page's markdown names its Pro variants; their source is never published in these docs.
  Tell the user an item is Pro instead of rebuilding it.

---

<!-- 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 items

The foundation components, the lib helpers and the tokens are free. The other components, 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 component and 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/existing-members.md -->

# Existing members

Bought Koala UI on the old site? Your purchase carries over. Find your license key, unlock the site with it, and install the Pro source with the CLI.

The old site signed members in with an email and a password. This one has no accounts: **your license key is your login**. It is the same key Lemon Squeezy sent when you bought, so there is nothing to buy again and nothing to migrate.

Licenses issued byLemon Squeezy

## Get access

1. **Find your license key**

   Lemon Squeezy emailed it with your receipt. Can’t find the email? Open [your orders](https://app.lemonsqueezy.com/my-orders) and sign in with the email you paid with: every order shows its key. It looks like this, behind the same lemon as the log-in field:

   `38b1460a-5104-4067-a91d-77b872934d51`

2. **Unlock the site**

   Go to [/account](https://www.koalaui.com/account) and enter the key with your purchase email. The Code tab of every Pro section then shows its files. It uses no CLI seat, so unlock as many browsers as you like.

3. **Install with the CLI**

   Activate the key once per machine, then add Pro sections, pages and templates like any free component. The full setup is in [Installation](https://www.koalaui.com/docs/installation.md).

   ```bash
   npx
   ```

4. **Open the Figma file**

   Nothing changes here. The Figma library is still in your receipt email and in [your orders](https://app.lemonsqueezy.com/my-orders), with every update.

## What your purchase includes

A paid Koala UI license now covers the React kit too: every Pro section, page example and template, on top of the Figma file you bought. Purchases made before October 1, 2026 keep what the old license promised, lifetime updates at no extra cost. See clause 4 of the [license](https://www.koalaui.com/legal/license).

## FAQ

### Where did my old account and password go?

They no longer exist. The old log-in and password-reset links now open /account, where the license key and your purchase email replace them.

### I can't find my license key.

Sign in to [Lemon Squeezy orders](https://app.lemonsqueezy.com/my-orders) with every email you might have paid with, a work address included. Still nothing? Write to [info.koalaui@gmail.com](mailto:info.koalaui@gmail.com) with the purchase email and the rough date, and we find it for you.

### My key is refused.

Check that the email matches the one on the receipt exactly. A key from the free Figma download, or from a refunded order, does not unlock Pro. If neither applies, write to us with the key's last four characters.

### The CLI says my seat is taken.

A Solo license runs on one machine at a time. Run `npx koalaui-cli@latest logout` on the old one to free it. Machine gone? Write to [info.koalaui@gmail.com](mailto:info.koalaui@gmail.com) with the license id from /account and we free it.

### Do I need to pay again?

No. Koala UI is a one-time purchase that never expires, and your key keeps working on the new site, the CLI and the Figma file.

---

<!-- 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 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: the foundation components, the lib helpers and the tokens install anywhere with `npx koalaui-cli@latest add <name>`. The other components, 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 item.

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 | Koala Icons |
| **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 | 199 |
| Page examples | No | 35 |
| Templates | No | 8 |
| 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>The 46 foundation components are free. The other components, every section, 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 Koala Icons, our own set, 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.** 151 components, 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. The 46 foundations are free, the rest are Koala UI Pro.
- **Sections, pages and templates.** 199 sections for marketing, app and store pages, in families (hero, feature, pricing, FAQ, checkout and more), 35 page examples and 8 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 Koala Icons, and the two can live side by side until you swap yours.

---

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

# Changelog

What's new in Koala UI, day by day: new components, improvements and fixes.

## October 19, 2026

- Fixed

  [Textarea](https://www.koalaui.com/docs/components/textarea.md): The resize grip sits in the bordered box's corner, level with the counter, instead of floating above the footer, and is drawn with the new `Notches` Koala icon.

- Improved

  [Dialog](https://www.koalaui.com/docs/components/dialog.md): Clearer rhythm: the header stands apart from the body (and drops that margin when the footer follows), the icon sits closer to the title, the close button centres on the first row, and the bordered footer gets more room.

- Improved

  [Expandable Search](https://www.koalaui.com/docs/components/expandable-search.md): The docs header search is now an Expandable Search: it rests as a magnifier, opens on click and lists matches right under the field. ⌘K still opens the command palette.

- Fixed

  [Accordion](https://www.koalaui.com/docs/components/accordion.md): Every disclosure panel (Accordion, Collapsible, Tool, Plan, Tree, Sidebar groups) keeps its children's edge and focus rings painted while it opens and closes.

- Fixed

  [Paper](https://www.koalaui.com/docs/components/paper.md): A section band no longer doubles the rule above it.

- Improved

  [Paper](https://www.koalaui.com/docs/components/paper.md): A `SignaturePad` inside `PaperSignature` drops its own box and guide and signs on the sheet's line, scaled with the sheet.

- New

  [Input](https://www.koalaui.com/docs/components/input.md): `InputFloatingField`: the label rests as the placeholder and floats to the top edge on focus, value or autofill.

- Improved

  [Radio Group](https://www.koalaui.com/docs/components/radio-group.md): RadioCard states no longer compete: every state is one ink, keyboard focus adds a soft ink halo, a click shows the ink selection straight away, and hover is a quieter hint.

- Fixed

  [Floating Window](https://www.koalaui.com/docs/components/floating-window.md): A minimized window no longer shows a stray hairline under its bar.

- Improved

  [Floating Window](https://www.koalaui.com/docs/components/floating-window.md): Dragging lifts the window from the grab point with a deeper shadow, and the cursor holds while the pointer leaves the bar.

- Fixed

  [Tool](https://www.koalaui.com/docs/components/tool.md): The first section's top hairline no longer vanishes while the card opens.

- Fixed

  [Voice Roster](https://www.koalaui.com/docs/components/voice-roster.md): A group mark before the avatar keeps the full gap, and the header and overflow line align with the row text at each density.

- New

  [Field](https://www.koalaui.com/docs/components/field.md): `info` on `FieldLabel` and `FieldGroupLabel` puts the help behind an info icon with a tooltip; it still describes the control for screen readers.

- New

  [Empty State](https://www.koalaui.com/docs/components/empty-state.md): `layout="inline"` puts the parts on one left-aligned line, for an empty list inside a sheet or a panel.

- New

  [Rich Text Editor](https://www.koalaui.com/docs/components/rich-text-editor.md): `imageLinks` shows the picture under any block that links to an image file; the saved HTML keeps just the link.

## October 18, 2026

- Fixed

  [Layout](https://www.koalaui.com/docs/components/layout.md): The `docked` content keeps its top hairline under a topbar: it sits 1px lower, so the sticky bar no longer paints over the ring.

- Improved

  [TeamMember](https://www.koalaui.com/docs/components/team-member.md): Name and role sit closer together in every layout, so the pair reads as one label.

## October 17, 2026

- Improved

  [Koala Icons](https://www.koalaui.com/docs/foundations/icons.md): Every component, section and page now draws Koala Icons: 117 new icons bring the set to 487, and `@phosphor-icons/react` is no longer a dependency.

- New

  [Brand logos](https://www.koalaui.com/docs/foundations/icons.md): `@/lib/brand-logos` holds the monochrome brand marks (GitHub, X, LinkedIn, Dribbble, TikTok and more) with the same `size`, `color` and `title` props as an icon.

## October 16, 2026

- Improved

  [Motion](https://www.koalaui.com/docs/foundations/motion.md): No control scales down on press anymore: Button, inputs, pickers, toggles and every other control answer a press with the focus ring and color alone, and `static` stays for compatibility.

- Improved

  [SplitButton](https://www.koalaui.com/docs/components/button.md): Takes a `menuClassName` for the menu, never shrinks in a flex row, and now drives the docs Copy page menu.

- Improved

  [VoiceRoster](https://www.koalaui.com/docs/components/voice-roster.md): Speaks Koala now: rounded rows on the elevation floor, a soft green fill instead of the spine and wash, body type instead of mono, round group dots, the supervisor star after the name, and `panel` rows sit on the page's own ground like a List.

- Improved

  [Hero Section 1](https://www.koalaui.com/marketing/sections/hero-section-1): A `rotate` list turns the end of the headline into a rotating highlight, the same wash as `HeroHighlight`.

- Fixed

  [HeroHighlight](https://www.koalaui.com/docs/components/hero.md): A rotating highlight now server-renders only its first phrase, so search engines read a clean headline instead of every phrase run together.

- Improved

  [SwatchGrid](https://www.koalaui.com/docs/components/swatch-grid.md): Swatches are round now, the selection ring takes the swatch's own color, kept opaque and readable on either theme, and hover hints in that color.

- New

  [ease-lift](https://www.koalaui.com/docs/foundations/motion.md): A motion token for physical objects being picked up or selected: a gentle 10% overshoot, softer than `ease-spring`.

- Improved

  [Ink Tray](https://www.koalaui.com/docs/components/ink-tray.md): The tool in hand now lifts on `ease-lift` with a growing shadow, hover only hints at the lift, and the chosen colour rises slightly.

- Fixed

  `cn` and every recipe now let `ease-drawer`, `ease-spring`, `ease-lift` and `ease-sine` in `className` override a component's own easing.

## October 15, 2026

- New

  [Toast](https://www.koalaui.com/docs/components/toast.md): `appearance: "minimal"` for a compact one-row toast, `countdown` for a hairline that drains with the timer, and `progress` for a determinate bar you advance by raising the same `id`; the first two can be set app-wide on `<Toaster />`.

- New

  [Ink Tray](https://www.koalaui.com/docs/components/ink-tray.md): A whiteboard pen tray: pen, marker, pencil and eraser rise from behind the bar when picked up, and each tool keeps its own colour and stroke size.

- Improved

  [Fields](https://www.koalaui.com/docs/components/field.md): Input, InputGroup, Select, MultiSelect, NativeSelect, CountrySelect and DatePicker are rounded rectangles instead of pills (12, 14 and 16 by size), and Textarea steps down to `rounded-lg`.

- Improved

  [Button](https://www.koalaui.com/docs/components/button.md): A Button inside a `<form>` takes the field corner for its size, so a submit matches the inputs beside it; everywhere else, a Popover form included, it stays a pill.

- Improved

  [OTPInput](https://www.koalaui.com/docs/components/otp-input.md): Slots follow the field corners, 12, 14 and 16 by size, so a code entry matches the inputs and the Verify button beside it.

## October 13, 2026

- Improved

  No comments left in the code you install: components, sections, page examples, templates and the shared `lib` helpers all ship as plain code.

- New

  [Icons](https://www.koalaui.com/docs/foundations/icons.md): Koala Icons grows to 370 glyphs, and every example in the docs now draws with them instead of Phosphor.

- Improved

  [Rating](https://www.koalaui.com/docs/components/rating.md): `icon` takes any icon component, Koala Icons or Phosphor, and so do the icon props of CookieConsent categories and Toolbar overflow items.

- Improved

  [Terminal](https://www.koalaui.com/docs/components/terminal.md): A Windows window now: 8px corners, square seams, a `TerminalTab` that merges into the screen and `TerminalCaption` buttons with close going red on hover.

- Improved

  [PromptInput](https://www.koalaui.com/docs/components/prompt-input.md): One size now: the `size` prop is gone, and every composer is the tighter default, with one 32px control height and 16px icons across the toolbar, send included.

- New

  [PromptInput](https://www.koalaui.com/docs/components/prompt-input.md): `PromptInputBannerApps` and `PromptInputBannerApp`: a row of app logos in the banner under the composer, each a button with a tooltip, for a "connect your apps" strip.

- Improved

  [PromptInput](https://www.koalaui.com/docs/components/prompt-input.md): The banner takes a muted tint so it reads as tucked behind the composer, and its content wraps on narrow screens instead of overflowing.

- Improved

  [ModelSelector](https://www.koalaui.com/docs/components/model-selector.md): Capability glyphs are smaller and quieter, and each explains itself in a tooltip on hover through a new `description` prop.

- Fixed

  [Command](https://www.koalaui.com/docs/components/command.md): The sliding highlight no longer covers a group heading or separator as it glides from one group into the next.

- Fixed

  [Tool](https://www.koalaui.com/docs/components/tool.md): Opening or closing a call no longer shows its sheets cut flat by the height animation; they fade in step with it.

- Fixed

  [Citation](https://www.koalaui.com/docs/components/citation.md): A chip no longer wraps alone onto the next line, and no longer crops the first message of a Chat conversation.

## October 12, 2026

- New

  [Citation](https://www.koalaui.com/docs/components/citation.md): A chip in an answer that previews its sources on hover and goes to them on click.

- New

  [Tool](https://www.koalaui.com/docs/components/tool.md): One call an agent makes to a tool: its arguments, the result and an approval step when a person has to say yes.

- New

  [ModelSelector](https://www.koalaui.com/docs/components/model-selector.md): A searchable model picker grouped by provider, with each model's capabilities and context window.

- New

  [ContextMeter](https://www.koalaui.com/docs/components/context-meter.md): A small ring for how much of the context window a conversation has used, opening onto what fills it.

- New

  [EventCalendar](https://www.koalaui.com/docs/components/event-calendar.md): Month, week and day views where events drag between slots and resize, from the mouse or the keyboard.

- New

  [CompareSlider](https://www.koalaui.com/docs/components/compare-slider.md): Two pictures in one frame with a divider to drag between them, for a redesign, a retouch or a grade.

- New

  [Button](https://www.koalaui.com/docs/components/button.md): A split button: the main action stays visible and its alternatives sit in an attached menu.

- New

  [Chat](https://www.koalaui.com/docs/components/chat.md): An agent trace of reasoning steps, with an `ink-sweep` pass across the step still in progress.

- Improved

  [Tabs](https://www.koalaui.com/docs/components/tabs.md): `segmented` is now the default variant, with a tighter track.

- Improved

  [EmptyState](https://www.koalaui.com/docs/components/empty-state.md): Illustrated states: a small object that belongs to the job for each empty moment.

- Improved

  [DataTable](https://www.koalaui.com/docs/components/data-table.md): An AI generation example that fills an insight column row by row.

- Improved

  [ActivityFeed](https://www.koalaui.com/docs/components/activity-feed.md): A workflow example with a compact phase bar for the total time.

- Improved

  Leaner component source: the long explanatory comments are gone from every component, so the files you copy read as plain code. One-line prop docs stay for editor hints.

## October 11, 2026

- New

  [Combobox](https://www.koalaui.com/docs/components/combobox.md): A text field you type into to filter a list, then pick one option.

- New

  [Meter](https://www.koalaui.com/docs/components/meter.md): A measurement inside a known range, like storage used or a plan quota.

- New

  [NumberField](https://www.koalaui.com/docs/components/number-field.md): A numeric input with minus and plus steppers.

- New

  [Terminal](https://www.koalaui.com/docs/components/terminal.md): A command-line surface whose title bar doubles as a drag handle.

- New

  [StatusBar](https://www.koalaui.com/docs/components/status-bar.md): The thin strip of status items along the edge of an app shell.

- New

  [TabStrip](https://www.koalaui.com/docs/components/tab-strip.md): The browser-style row of open documents across the top of an app shell.

- New

  [DotMatrix](https://www.koalaui.com/docs/components/dot-matrix.md): A 5×5 dot-matrix loader with a light running through it.

- New

  [TabletFrame](https://www.koalaui.com/docs/components/tablet-frame.md): A device that floats over a game, a map or another full-bleed canvas.

- New

  [SwatchGrid](https://www.koalaui.com/docs/components/swatch-grid.md): A grid of pickable samples: a color, or a glyph over a color.

- New

  [FloatingWindow](https://www.koalaui.com/docs/components/floating-window.md): A small movable, resizable window over the app.

- New

  [Tabs](https://www.koalaui.com/docs/components/tabs.md): `variant="segmented"`, the pill-on-track look for switching views.

- Improved

  [Tabs](https://www.koalaui.com/docs/components/tabs.md): The line and folder indicators sit on the bottom edge of the list and stay fully visible.

- Improved

  [DropdownMenu](https://www.koalaui.com/docs/components/dropdown-menu.md): The exit animation is interruptible: reopening mid-close picks up where it was.

- Improved

  [Map](https://www.koalaui.com/docs/components/map.md): Map pins merge the collapsible chip with the new dispatch, fleet and incident symbols.

- Improved

  API tables and anatomy on the docs pages of every component merged this week, including AI panel, Chat, Prompt Input and Rich Text Editor.

- Fixed

  [DotMatrix](https://www.koalaui.com/docs/components/dot-matrix.md): Keyframes that were left open no longer break the animation.

- Fixed

  [Button](https://www.koalaui.com/docs/components/button.md): An icon-only `size="xs"` button stays round like every other size.

## October 10, 2026

- New

  [ChannelChat](https://www.koalaui.com/docs/components/channel-chat.md): A many-person channel log for team chat or a radio net.

- New

  [VoiceRoster](https://www.koalaui.com/docs/components/voice-roster.md): Who is on a voice channel, lit as they talk. `variant="panel"` sets it inside a page column.

- New

  [Chip](https://www.koalaui.com/docs/components/chip.md): A small pill you act on, the interactive sibling of Badge.

- New

  [Dot](https://www.koalaui.com/docs/components/dot.md): A status light or color swatch.

- New

  [HoldButton](https://www.koalaui.com/docs/components/hold-button.md): Press and hold to confirm a destructive or final action, with controlled holding and keyboard support.

- New

  [Receipt](https://www.koalaui.com/docs/components/receipt.md): A slip of thermal paper with a torn edge.

- New

  [HandheldDevice](https://www.koalaui.com/docs/components/handheld-device.md): The shell of a handheld gadget, with an LCD, keys and a printer.

- New

  [Button](https://www.koalaui.com/docs/components/button.md): `size="xs"`, a 28px tier for dense interfaces.

- New

  [Progress](https://www.koalaui.com/docs/components/progress.md): A timed mode: pass `duration` and the bar runs itself, like an auto-dismiss countdown.

- New

  [Typography](https://www.koalaui.com/docs/foundations/typography.md): `eyebrow` and `eyebrow-mono` label roles.

- Improved

  [Badge](https://www.koalaui.com/docs/components/badge.md): Takes any color, not only the preset variants.

- Improved

  [PushToTalk](https://www.koalaui.com/docs/components/push-to-talk.md): `size="sm"`, `variant="outline"` and a `live` prop for a hotkey handled elsewhere.

- Improved

  [NotebookPage](https://www.koalaui.com/docs/components/notebook-page.md): A red margin, a spiral binding and fields that sit on the rules. Focus shows only the caret unless `focusTint` is set.

- Improved

  [AI panel](https://www.koalaui.com/docs/components/ai-panel.md): Works inside a container, with jump to latest, prompt limits, quick actions and mentions.

- Improved

  [Chat](https://www.koalaui.com/docs/components/chat.md): The conversation keeps following the latest message through resizes.

- Improved

  [List](https://www.koalaui.com/docs/components/list.md): A `bleed` option and `currentStyle` for the active row.

- Improved

  [Banner](https://www.koalaui.com/docs/components/banner.md): A `size` prop.

- Improved

  [Tabs](https://www.koalaui.com/docs/components/tabs.md): A trailing badge sits concentric with its tab.

- Improved

  Focus rings use one brand color everywhere and are never clipped by a scroll container.

- Fixed

  [Dialog](https://www.koalaui.com/docs/components/dialog.md): Focus returns to the opener when there is no trigger, including a menu item that opened it.

- Fixed

  [Tooltip](https://www.koalaui.com/docs/components/tooltip.md): Automatic hints stand down under an explicit Tooltip, so you never get two bubbles.

- Fixed

  [TabStrip](https://www.koalaui.com/docs/components/tab-strip.md): A sortable tab no longer breaks the tab stop.

- Fixed

  [PushToTalk](https://www.koalaui.com/docs/components/push-to-talk.md): A hold interrupted by unmounting or disabling still ends through `onTalkEnd`.

- Fixed

  [PromptInput](https://www.koalaui.com/docs/components/prompt-input.md): Growing with its text no longer moves the thread above it.

## October 4, 2026

- New

  Koala UI for React 1.0: 125 free components, four themes and the CLI.

- New

  [Paper](https://www.koalaui.com/docs/components/paper.md): A printed document on screen that scales as a whole.

- New

  [NotebookPage](https://www.koalaui.com/docs/components/notebook-page.md): A sheet of notebook paper behind what someone writes.

- New

  [Existing members](https://www.koalaui.com/docs/existing-members.md): The access guide for buyers from the old site.

- Improved

  [RichTextEditor](https://www.koalaui.com/docs/components/rich-text-editor.md): Opt-in text alignment, `starterKit` and `extensions` props, quote and code styles, and translatable labels.

- Improved

  [Lightbox](https://www.koalaui.com/docs/components/lightbox.md): A `loop` prop and translatable labels.

- Improved

  [Carousel](https://www.koalaui.com/docs/components/carousel.md): A `peek` layout that shows the neighbouring slides.

- Improved

  [Navbar](https://www.koalaui.com/docs/components/navbar.md): `collapseAt="xl"` collapses it at the wider breakpoint.

- Improved

  [Chart](https://www.koalaui.com/docs/components/chart.md): Translucent stacked areas.

- Fixed

  [RichTextEditor](https://www.koalaui.com/docs/components/rich-text-editor.md): No longer calls `onChange` on mount.

---

<!-- 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
- `border-ring` (`--ring`): Neutral control edge on hover; focus rings use brand

## 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)

## Eyebrow

The small tracked caps line that names a group or a section from above it: a sidebar group, a table-of-contents title, a band in a comparison table, a panel’s “Recent activity”. It is a role, not a size, so it ships as one utility from the token layer instead of five classes copied from screen to screen, where the size and the tracking used to drift a step apart at every call site.

- `eyebrow`: 12 / 16px (500 · 0.05em)
- `eyebrow-mono`: 12 / 16px (400 · 0.08em)

`eyebrow` is the sans label of the UI. `eyebrow-mono` is the typed-note voice (a Hero sign-off, a spec or build line); mono is already wide, so it opens less. Both carry the meta ink and sit on `text-xs` with its paired 16px leading. They set the role and nothing else: spacing and alignment stay where the label is used, and any one trait yields to the matching utility on the same element (`font-semibold`, `tracking-wide`, `text-brand`, `text-white/80` on a photo). Never shrink one to 10 or 11px: a caps label smaller than the scale is a Badge.

```tsx title="panel.tsx"
// ✓ The role, in one class.
<p className="eyebrow">Recent activity</p>
<span className="eyebrow-mono">Build 2.4.1 · eu-west</span>

// ✓ One trait tuned, the rest of the role kept.
<h3 className="eyebrow font-semibold">On this page</h3>
<p className="eyebrow text-brand">New in 2.4</p>

// ✗ Hand-rolled: the size and tracking drift one call site at a time.
<p className="text-[0.6875rem] tracking-wide uppercase text-muted-foreground">Recent activity</p>
```

---

<!-- 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)
})
```

## Lift: weight for objects you pick up

`ease-lift` overshoots by about a tenth, enough to give a physical object weight without the bounce of `ease-spring`. Use it when something is picked up or chosen: a tool rising out of a tray, a swatch lifting when selected. Pair the rise with a shadow that grows, so the lift reads as elevation and not just position, and keep hover to a hint of the same move. Never use it on icons, text or a container changing shape: symbols snap, containers settle. The [Ink Tray](https://www.koalaui.com/docs/components/ink-tray.md) is the reference.

```tsx title="tool.tsx"
<button
  className={cn(
    "translate-y-6 drop-shadow-xs transition-[translate,filter] duration-base ease-lift",
    "data-[state=off]:hover:translate-y-5.5",
    "data-[state=on]:translate-y-1 data-[state=on]:drop-shadow-md",
  )}
/>
```

## 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" />
```

## Hover feedback

Cards hint that they are tappable with a subtle hover lift. A press never scales anything down: it confirms through the focus ring and a change of color, and the motion the action itself causes. Hover and press the cards below.

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"
// ✓ Hover lift, with translate named in the transition.
<button
  className="cursor-pointer rounded-xl border border-border bg-card p-4
             transition-[translate,box-shadow,border-color] duration-fast ease-out
             hover:-translate-y-0.5 hover:shadow-md"
/>

// ✗ translate-* is a standalone prop in v4: 'transform' won't reach it.
<button className="transition-[box-shadow,transform] hover:-translate-y-0.5" />
```

## 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 "koala-icons"
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 transform on a child, like a hover lift, 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

Koala Icons is our own stroke set, drawn on one 24px grid by one spec. Search it, copy any icon as SVG or JSX, and import it as a plain React component.

## Koala Icons

488 icons in 23 categories, and growing. Search by name, tag or category, and switch to Fill to see the solid weight. Hover an icon and use Copy SVG to paste the master into Figma, Copy JSX for the import and the element, or Download SVG for a file.

## Install and import

Install the `koala-icons` package and import each icon by name. Every icon is a plain function with no context and no client hooks, so it renders in Server Components with no `"use client"` boundary. Import `optical.css` once, in your root layout, for the small optical size.

```tsx title="Terminal"
npm install koala-icons
```

```tsx title="app/layout.tsx"
import "koala-icons/optical.css"
```

```tsx title="example.tsx"
import { Bell, ArrowRight } from "koala-icons"

<Bell />
<ArrowRight className="size-5" />

// One module per icon, for setups that don't tree-shake a barrel
import { Bell } from "koala-icons/icons/bell"
```

## Sizes

An icon is `1em` by default, so it follows the text beside it. Set a size with Tailwind's `size-*`, or the `size` prop in pixels. Pick it by context: 16 in buttons, 20 in rows led by a text label, 14 in chips. Button, Input and Badge size an unclassed icon for you.

- `size-3.5`: 14px (chips and badges)
- `size-4`: 16px (buttons, inputs, menus)
- `size-5`: 20px (text-label rows, nav items)
- `size-6`: 24px (display, empty states)

## Weights

Two weights: `regular`, the outline, and `fill`, the solid version for selected and status states. Fill is derived from the outline, so the two never drift. Only icons with a body get it; a line glyph like a check or an arrow keeps its outline.

- `Bell`: regular · fill
- `Star`: regular · fill
- `House`: regular · fill
- `Lock`: regular · fill
- `CheckCircle`: regular · fill
- `Check`: regular · fill

```tsx title="example.tsx"
<Star />                  {/* regular, the default */}
<Star weight="fill" />    {/* selected, active */}
<Check weight="fill" />   {/* no body: stays an outline */}
```

## Optical sizes

At 16px and below the stroke gets heavier, and icons with fine inner marks swap to a simpler small drawing. It happens by itself, from the size each icon renders at, once `optical.css` is imported. Without it, the large drawing shows at every size.

- `Trash` (14 · 16 · 20 · 24)
- `House` (14 · 16 · 20 · 24)
- `Info` (14 · 16 · 20 · 24)
- `Copy` (14 · 16 · 20 · 24)

## Color

Icons draw in `currentColor`, so a `text-*` utility on the icon or any ancestor colors it. Use semantic tokens only, never a raw value, so the icon re-themes across all four themes.

- `foreground`
- `muted-fg`
- `brand`
- `destructive`
- `success`
- `info`

## Accessibility

An icon is decorative by default: `aria-hidden="true"`, because the text beside it already says what it means. An icon-only control names the control, not the icon. An icon that carries meaning on its own takes `title` or `aria-label`, which gives it `role="img"`.

```tsx title="a11y.tsx"
// Decorative: the label says it, the icon is skipped
<Button>
  Continue <ArrowRight />
</Button>

// Icon-only: name the button, not the icon
<Button iconOnly aria-label="Notifications">
  <Bell />
</Button>

// Meaningful on its own: give the icon a name
<CheckCircle title="Verified" className="text-success" />

// Avoid: a label on the icon inside a labelled control is read twice
<Button aria-label="Next step">
  <ArrowRight aria-label="Next step" />
</Button>
```

## In context

Button and Badge size an unclassed icon to their own step, so composing needs no size class: 16px in a button, 14px in a badge.

Deployed 3 new

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

<Button><Plus /> New project</Button>
<Button variant="outline">Continue <ArrowRight /></Button>

<Badge variant="success"><Check /> Deployed</Badge>
<Badge variant="info"><Bell weight="fill" /> 3 new</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

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

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

Pro: `file-icon` comes with a [Koala UI Pro license](https://www.koalaui.com/pro). Its source is not published in these docs.

## 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

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

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

Pro: `flag` comes with a [Koala UI Pro license](https://www.koalaui.com/pro). Its source is not published in these docs.

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Installation

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

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

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

Pro: `announcement` comes with a [Koala UI Pro license](https://www.koalaui.com/pro). Its source is not published in these docs.

## Usage

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## API reference

### Announcement

One pill that pairs a label (often a nested `Badge`) with the thing announced. Forwards all native `<div>` props; accepts `className`, merged last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| variant | "solid" \| "glass" | "solid" | The hairline card pill for a normal surface, or the translucent white-on-scrim pill for a photo or video hero. |
| dot | boolean | false | A leading dot in the current text color, for the one-line shape. With a nested badge, let the badge carry the dot. |
| asChild | boolean | false | Renders the pill onto its single child (Radix Slot), typically a link; the dot rides inside that element. |
| interactive | boolean | asChild | Cursor, hover, focus ring and press. Set it only for a pill that is clickable without `asChild`. |
| static | boolean | false | Kept for compatibility; controls no longer scale on press. |

| Data attribute | Description |
| --- | --- |
| data-lead | `"text"` or `"shape"`: what sits on the leading edge, read from the children so the padding can match (a selector cannot see a text node). |
| data-trail | `"text"` or `"shape"`: what sits on the trailing edge. |

## 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 v12 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Installation

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

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

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

Pro: `banner` comes with a [Koala UI Pro license](https://www.koalaui.com/pro). Its source is not published in these docs.

## Usage

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Anatomy

```tsx
import {
  Banner,
  BannerOrnament,
  BannerIcon,
  BannerContent,
  BannerAction,
} from "@/components/ui/banner"

<Banner>
  <BannerOrnament />
  <BannerIcon />
  <BannerContent />
  <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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Size

`size` sets the strip's own height and side padding.`"md"` (default) is the page bar, with the 24px page gutter.`"sm"` is a compact strip for a panel, a tablet screen or the head of a card: 12px sides, a 32px row, the type a step down and a smaller close button, and no page-width cap. Use it instead of reaching into the inner row with selectors.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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`.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## API reference

### Banner

The full-bleed bar. Children land in an inner row; the close button and confetti layer are drawn for you. Forwards all native `<div>` props. Every part accepts `className`, merged last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| variant | "default" \| "brand" \| "purple" \| "pink" \| "teal" \| "orange" \| "info" \| "success" \| "warning" \| "destructive" | "default" | The tone. The icon, message and action all carry it. |
| appearance | "soft" \| "solid" \| "festive" | "soft" | The fill. `solid` is defined for `default` (inverse) and `brand`; `festive` is a flat celebration bar that ignores the tone. |
| align | "center" \| "between" | "center" | A centered message, or message left and action right (stacked on phones). |
| shape | "bar" \| "inset" | "bar" | An edge-to-edge strip, or a rounded card inside the page gutter. |
| size | "md" \| "sm" | "md" | The page bar (24px sides), or a compact strip (12px sides, 32px row, smaller type and close, no page-width cap) for panels and cards. |
| dismissible | boolean | false | Renders a trailing close button. |
| dismissLabel | string | "Dismiss" | The accessible label of the close button. |
| open | boolean | - | Visibility, controlled. A closed banner renders nothing. |
| defaultOpen | boolean | true | Visibility on first render, uncontrolled. |
| onOpenChange | (open: boolean) => void | - | Called when the banner is dismissed. |
| confetti | boolean | false | A burst on mount (with an icon pop) and on every click of the bar. Pairs with `festive`; off under reduced motion. |

| CSS variable | Description |
| --- | --- |
| --banner-festive-via | The fill of the `festive` bar. Override it on the banner or a parent; keep it deep enough for white text. |
| --banner-festive-to | A confetti accent alongside the festive fill. |
| --banner-confetti-{1,2,3} | The three confetti colors, derived from the festive stops by default. |
| --surface | Set to the fill of the bar, so a nested control blends with it. |

### BannerIcon

The leading icon, tinted to the tone. Forwards all native `<span>` props.

### BannerContent

The message, a deep tint of the tone. Forwards all native `<span>` props.

### BannerAction

The inline call-to-action link, tinted to the tone. Forwards all native `<a>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| asChild | boolean | false | Renders onto its single child (Radix Slot), such as a Next.js `<Link>`. |

### BannerOrnament

A decorative flag, mascot or emoji that peeks in from an edge behind the message, clipped to the bar and `aria-hidden`. Forwards all native `<span>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| side | "left" \| "right" | "left" | The edge it peeks in from; it tilts away from that edge. |

| Data attribute | Description |
| --- | --- |
| data-side | `"left"` or `"right"`. |

## 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 takes a deep tint of the same hue (the tone mixed toward foreground), so it holds 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Installation

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

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

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

Pro: `bento` comes with a [Koala UI Pro license](https://www.koalaui.com/pro). Its source is not published in these docs.

## Usage

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Anatomy

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

<Bento>
  <BentoItem>
    <BentoItemIcon />
    <BentoItemTitle />
    <BentoItemDescription />
    <BentoItemImage />
    {/* or <BentoItemArt />, or <BentoItemMedia /> */}
  </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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## API reference

### Bento

The grid: one column on phones, two at `sm`, six at `lg`. Forwards all native `<div>` props. Every part accepts `className`, merged last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| collapse | "sm" \| "lg" | "sm" | Where the grid leaves one column. `lg` skips the two-column step, for rows of three that would leave an orphan. |
| imageFit | "frame" \| "bleed" | "frame" | The default art window for every tile; a tile's own `imageFit` wins. |
| scale | "md" \| "lg" | "md" | The type and spacing step of the whole board: 24px tiles, or the 32px landing board with 18px descriptions. |

| Data attribute | Description |
| --- | --- |
| data-collapse | `"sm"` or `"lg"`. |

### BentoItem

One tile, a ring-edged card. Works outside a `Bento` too, with the defaults. Forwards all native `<div>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| size | "sm" \| "md" \| "lg" \| "feature" \| "full" | "sm" | Columns claimed at `lg` (2, 3, 4, 4 by 2 rows, 6) and the art height. The wide three also span both `sm` columns. |
| tone | "neutral" \| "brand" \| "purple" \| "teal" \| "orange" \| "pink" | "neutral" | The tint of the icon chip, nothing else. |
| imageFit | "frame" \| "bleed" | - | A floating screenshot window, or art that runs off the tile and dissolves. Overrides the grid's. |
| asChild | boolean | false | Renders the tile as its single child (Radix Slot), so the whole card is one link. |

### BentoItemIcon

The tinted icon chip; pass one Koala icon. Forwards all native `<div>` props.

### BentoItemTitle

The balanced title, an `<h3>`. Forwards all native `<h3>` props.

### BentoItemDescription

The muted description, a `<p>`. Forwards all native `<p>` props.

### BentoItemImage

A lazy screenshot clipped at the tile edge, in the window `imageFit` picks. Forwards native `<img>` props (`alt`, `sizes`, `srcSet`) to the image; `className` lands on the `<img>`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| src* | string \| { src: string } | - | A URL or a static image import. |
| darkSrc | string \| { src: string } | - | The same shot in a dark theme, shown on dark and moonlight. Only the visible one loads. |
| frameClassName | string | - | Classes for the art window (its height, the bleed width). |
| children | React.ReactNode | - | Extra layers over the image, positioned by you and clipped with it. |
| loading | "lazy" \| "eager" | "lazy" | The native loading hint. |
| decoding | "async" \| "sync" \| "auto" | "async" | The native decoding hint. |

### BentoItemArt

The same art window holding live components instead of a picture. Position the composition yourself; the window clips it. Forwards all native `<div>` props.

### BentoItemMedia

A freeform bottom-aligned region (a stat, a swatch row). Composed first, it flips: the visual on top, the copy on the bottom edge. Forwards all native `<div>` props.

## 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. `neutral` (the default) is a soft ink tint; the others map 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`, the wide sizes (`lg`, `feature`, `full`) span both `sm` columns, and every `size` takes its real span 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Installation

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

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

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

Pro: `faqs` comes with a [Koala UI Pro license](https://www.koalaui.com/pro). Its source is not published in these docs.

## Usage

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Anatomy

```tsx
import {
  Faqs,
  FaqsHeader,
  FaqsTitle,
  FaqsDescription,
  FaqsGroup,
  FaqsList,
  FaqsItem,
  FaqsFeedback,
  FaqsFooter,
} from "@/components/ui/faqs"

<Faqs>
  <FaqsHeader>
    <FaqsTitle />
    <FaqsDescription />
  </FaqsHeader>
  <FaqsList>
    <FaqsItem>
      <FaqsFeedback />
    </FaqsItem>
  </FaqsList>
  <FaqsGroup>
    <FaqsItem />
  </FaqsGroup>
  <FaqsFooter />
</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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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`, …).

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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"`.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## API reference

### Faqs

The section container; provides `layout` and `size` to every part. Forwards all native `<div>` props, and every part accepts `className`, merged last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| layout | "stacked" \| "split" | "stacked" | A centered header above a `max-w-3xl` list, or a two-column grid from `lg` with a sticky header column. |
| 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. |

### FaqsHeader

The header column for the title, description and anything else you drop in. Forwards all native `<div>` props.

### FaqsTitle

The section heading on the shared `section-heading` scale. Forwards all native `<h2>` props.

### FaqsDescription

The supporting blurb under the title. Forwards all native `<p>` props.

### FaqsList

The question list: an `Accordion` (Radix `Accordion.Root`) with marketing defaults, every one overridable. Forwards all Accordion props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| type | "single" \| "multiple" | "single" | One open answer at a time, or many. |
| collapsible | boolean | true | Lets the open item close again. `single` only. |
| variant | "card" \| "minimal" \| "separated" \| "pill" \| "board" | "card" | The list chrome: one contour, hairline rows, one box per item, chips that flood open, or a two-up tile grid. |
| size | "md" \| "lg" | - | The Accordion type scale, defaulting to the `Faqs` size; `lg` sets an 18px semibold question on a taller row. |
| marker | "caret" \| "plus" | "caret" | The disclosure mark: a caret that flips, or a plus that turns into a cross. |
| iconPosition | "trailing" \| "leading" | "trailing" | Mark after the question, or ahead of it (the help-center look). |
| density | "comfortable" \| "compact" | "compact" | Row height and content inset. Falls back to the nearest `DensityProvider`. |
| defaultValue | string \| string[] | - | The item(s) open on mount, uncontrolled; an array with `type="multiple"`. |
| value | string \| string[] | - | Controlled open item(s). |
| onValueChange | (value: string \| string[]) => void | - | Called when an item opens or closes; the value shape follows `type`. |
| disabled | boolean | false | Disables every item. |

| Data attribute | Description |
| --- | --- |
| data-orientation | `"vertical"`, set by Radix. |

### FaqsItem

One question and answer: Radix `Accordion.Item`, `Trigger` and `Content` in one call, with the answer as `children`. Forwards all `AccordionItem` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| question* | React.ReactNode | - | The question shown in the trigger row. |
| value | string | auto | Unique item value. A stable `useId` value is generated when omitted; pass one to target it with `defaultValue`. |
| feedback | boolean \| FaqsFeedbackProps | false | Mount a `FaqsFeedback` row under the answer: `true` for the defaults, or an object of its props. |
| disabled | boolean | false | Stops the item from opening or closing. |

| Data attribute | Description |
| --- | --- |
| data-state | `"open"` or `"closed"`, on the item, trigger and content. |
| data-disabled | Present when the item is disabled. |

| CSS variable | Description |
| --- | --- |
| --radix-collapsible-content-height | The answer's measured height, read by the open and close height tween. |

### FaqsGroup

A topic cluster for a categorized FAQ: an `<h3>` heading and optional blurb above its own `FaqsList`, so single-expand is scoped to the topic. Every other prop forwards to that list.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| title | React.ReactNode | - | The topic heading, rendered as an `<h3>`. |
| description | React.ReactNode | - | Supporting copy under the topic heading. |
| variant | "card" \| "minimal" \| "separated" \| "pill" \| "board" | "minimal" | The inner list's chrome; groups default to borderless rows. |
| className | string | - | Class for the group wrapper (heading and list). |
| listClassName | string | - | Class forwarded to the inner `FaqsList`. |

### FaqsFeedback

A Helpful / Not helpful vote row: a single-select `ToggleGroup` of two pills, then an acknowledgement. Works anywhere, not only inside `Faqs`; forwards all native `<div>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| onVote | (vote: "up" \| "down") => void | - | Called with the chosen vote, e.g. to forward it to analytics. |
| reveal | "always" \| "hover" | "always" | `hover` opens the row with its answer on hover or focus instead of reserving space; it stays open once voted and always shows on touch. |
| label | React.ReactNode | - | A lede before the buttons, e.g. "Was this helpful?". |
| helpfulLabel | React.ReactNode | "Helpful" | Label of the positive pill. |
| notHelpfulLabel | React.ReactNode | "Not helpful" | Label of the negative pill. |
| acknowledgement | React.ReactNode | "Thanks for your feedback." | Shown once a vote is cast; `null` suppresses it. |

| Data attribute | Description |
| --- | --- |
| data-voted | `"true"` once a vote is cast with `reveal="hover"`; pins the row open. |

### FaqsFooter

The closing call-to-action row: centered in `stacked`, spanning both columns in `split`. Forwards all native `<div>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| size | "sm" \| "md" \| "lg" | "md" | Control height imposed on the buttons and fields inside; a control's own `size` still wins. |

| Data attribute | Description |
| --- | --- |
| data-control-size | The imposed control size. |

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Installation

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

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

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

Pro: `footer` comes with a [Koala UI Pro license](https://www.koalaui.com/pro). Its source is not published in these docs.

## Usage

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Anatomy

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

<Footer>
  <FooterTop>
    <FooterBrand>
      <FooterTagline />
      <FooterSocial>
        <FooterSocialLink />
      </FooterSocial>
    </FooterBrand>
    <FooterColumns>
      <FooterColumn>
        <FooterLink />
      </FooterColumn>
    </FooterColumns>
  </FooterTop>
  <FooterBottom>
    <FooterCopyright />
    <FooterLegal>
      <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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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).

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## API reference

### Footer

The root `<footer>`: provides the styling context to every part and renders the max-width gutter inside. Forwards all native `<footer>` props; every part accepts `className`, merged last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| layout | "aside" \| "wide" | "aside" | `aside` clusters the link columns across the right band beside the brand; `wide` gives them the whole row, edge to edge. |
| density | "comfortable" \| "compact" | "compact" | Block padding and the gap to the bottom bar. Falls back to the nearest `DensityProvider`. |

### FooterTop

The upper region: lays the brand column beside the link columns, stacked below `lg`. Forwards all native `<div>` props.

### FooterBrand

The brand column: logo, tagline, social row or a newsletter form. Forwards all native `<div>` props.

### FooterTagline

The muted lead line under the brand mark. Forwards all native `<p>` props.

### FooterColumns

Grids the link columns: 2 or 3 up on small screens (4 up when there are exactly four), one row from `lg`. Forwards all native `<div>` props.

### FooterColumn

A titled column of links. Forwards all native `<div>` props except `title`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| title | React.ReactNode | - | Heading rendered as an `<h3>` above the links. Omit it for an untitled column. |

### FooterLink

A muted text link for columns and the legal row. Renders an `<a>` and forwards all its props; with `aria-disabled` (a page not live yet) it keeps its resting ink and ignores the pointer.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| asChild | boolean | false | Merge onto your own element, a framework `<Link>` or a `<span>` for a disabled entry, instead of rendering an `<a>`. |

### FooterSocial

A row of social icon links. Forwards all native `<div>` props.

### FooterSocialLink

An icon-only ghost link with a 40px hit area. Renders an `<a>` and forwards all its props; pass `aria-label`, since the glyph has no accessible name.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| asChild | boolean | false | Merge onto your own element, e.g. a framework `<Link>`, instead of rendering an `<a>`. |

### FooterBottom

The lower bar under a hairline: copyright on one side, legal links or social on the other. Forwards all native `<div>` props.

### FooterCopyright

The muted copyright line, set in `tabular-nums`. Forwards all native `<p>` props.

### FooterLegal

An inline, wrapping group for legal and secondary links in the bottom bar. Forwards all native `<div>` props.

## 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?

`density` sets the block padding and the gap to the bottom bar. Without a prop it follows the nearest `DensityProvider` and falls back to `compact`; set `density="comfortable"` for the roomier marketing spacing, 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Installation

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

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

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

Pro: `gallery` comes with a [Koala UI Pro license](https://www.koalaui.com/pro). Its source is not published in these docs.

## Usage

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Anatomy

```tsx
import {
  Gallery,
  GalleryHeader,
  GalleryTitle,
  GalleryDescription,
  GalleryMasonry,
  GalleryItem,
  GalleryImage,
  GalleryAccordion,
  GalleryAccordionItem,
  GalleryAccordionTrigger,
  GalleryAccordionPeek,
  GalleryAccordionContent,
  GalleryAccordionCaption,
  GalleryAccordionMedia,
  GalleryAccordionImage,
} from "@/components/ui/gallery"

<Gallery>
  <GalleryHeader>
    <GalleryTitle />
    <GalleryDescription />
  </GalleryHeader>
  <GalleryMasonry>
    <GalleryItem>
      <GalleryImage />
    </GalleryItem>
  </GalleryMasonry>
</Gallery>

<GalleryAccordion>
  <GalleryAccordionItem>
    <GalleryAccordionTrigger peek={<GalleryAccordionPeek />} />
    <GalleryAccordionContent>
      <GalleryAccordionCaption />
      <GalleryAccordionMedia>
        <GalleryAccordionImage />
      </GalleryAccordionMedia>
    </GalleryAccordionContent>
  </GalleryAccordionItem>
</GalleryAccordion>
```

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

`density` sets the row height: `compact` (the default, or the nearest `DensityProvider`) for a dense index, `comfortable` for a roomier one. The open chapter is controlled with `value` / `defaultValue` / `onValueChange`, and opens on click or keyboard, never hover.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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 all native `<section>` props; every part accepts `className`, merged last.

### GalleryHeader

The centered lede column for the title, the description and an optional Tabs rail. Forwards all native `<div>` props.

### GalleryTitle

The balanced section heading, on the shared `section-heading` scale. Forwards all native `<h2>` props.

### GalleryDescription

The muted lead paragraph. Forwards all native `<p>` props.

### GalleryMasonry

The fake-masonry wall: plain CSS `columns` (2, 3, then 4 across breakpoints), wider than the gutter so the outer columns clip. Retune the count or width via `className`; forwards all native `<div>` props.

### GalleryItem

One framed tile: a `<figure>` whose shadow deepens on hover, never a position change. Forwards all native props of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| action | React.ReactNode | - | Makes the tile a `<button>` that reveals this label as a centered pill on hover and focus. Pair it with `LightboxTrigger`, a link or your own `onClick`; the accessible name comes from the image `alt`. |
| asChild | boolean | false | Merge the tile styles onto your single child (a link, a `LightboxTrigger`). Ignored when `action` is set. |

### GalleryImage

The preview image, a plain lazy-loaded, non-draggable `<img>` that fills its tile. It has no default ratio: pass one per tile (`aspect-[4/5]`) or real `width` and `height`. Forwards all native `<img>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| alt | string | "" | Decorative by default; pass a real `alt` when the image carries meaning. |

### GalleryAccordion

The accordion layout's root, a single, collapsible Radix `Accordion.Root`: one collection open at a time, opened on click or keyboard, never hover.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| value | string | - | The open collection (controlled). Pair with `onValueChange`. |
| defaultValue | string | - | The collection open on mount (uncontrolled). None open when omitted. |
| onValueChange | (value: string) => void | - | Fires when the open collection changes, via click or keyboard. |
| density | "comfortable" \| "compact" | "compact" | Row height and panel inset. Falls back to the nearest `DensityProvider`. |
| size | "md" \| "lg" | "md" | The title scale; `lg` for hero use. |
| disabled | boolean | false | Disables every item. |

| Data attribute | Description |
| --- | --- |
| data-orientation | Always `"vertical"`. |

### GalleryAccordionItem

One collection, Radix `Accordion.Item`; forwards all its props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| value* | string | - | Unique id of the collection, matched by the root's `value`. |
| disabled | boolean | false | Stops this collection from opening. |

| Data attribute | Description |
| --- | --- |
| data-state | `"open"` or `"closed"`. |
| data-disabled | Present when the item is disabled. |
| data-orientation | Always `"vertical"`. |

### GalleryAccordionTrigger

The collection row, Radix `Accordion.Trigger` wrapped in its `Header`: the title (children) on the left, the peek, count and a turning `+` toggle on the right. Forwards all Radix Trigger props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| children* | React.ReactNode | - | The collection title. |
| tagline | React.ReactNode | - | One-line tagline under the title, always visible and truncated. |
| count | React.ReactNode | - | The collection size, set in tabular numbers; hidden below `sm`. |
| peek | React.ReactNode | - | A `GalleryAccordionPeek` (or any node) shown at rest and faded out on open. |

| Data attribute | Description |
| --- | --- |
| data-state | `"open"` or `"closed"`. |
| data-disabled | Present when the item is disabled. |
| data-orientation | Always `"vertical"`. |

### GalleryAccordionPeek

The overlapping thumbnail stack on a closed row, decorative (`aria-hidden`) and hidden below `sm`. Forwards all native `<span>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| images* | { src: string; alt?: string }[] | - | Thumbnails to stack. |
| max | number | 3 | How many thumbnails to show. |

### GalleryAccordionContent

The panel, Radix `Accordion.Content`, tweening its height on open and close. `className` lands on the inner padded column, not the animated wrapper.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| forceMount | true | - | Keep the panel mounted while closed (Radix). |

| Data attribute | Description |
| --- | --- |
| data-state | `"open"` or `"closed"`. |
| data-disabled | Present when the item is disabled. |
| data-orientation | Always `"vertical"`. |

| CSS variable | Description |
| --- | --- |
| --radix-collapsible-content-height | The measured panel height the open and close tween animates to and from. |

### GalleryAccordionCaption

Optional caption above the photo strip; fades and rises in on open. Forwards all native `<p>` props.

### GalleryAccordionMedia

The horizontal photo strip, scrolling on overflow; its children stagger in left to right on open. Forwards all native `<div>` props.

### GalleryAccordionImage

One framed photo on a mat. Renders a `<div>`, or a `<button>` when `action` is set, and forwards the remaining native props; size the tile via `className` (`h-44 w-60`).

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| src* | string | - | The photo source. |
| alt | string | "" | Alt text, also the tile's accessible name when `action` makes it a button. |
| overlay | React.ReactNode | - | A dimmed overlay over the tile, e.g. a `+12` signalling more photos behind it. |
| action | React.ReactNode | - | Makes the tile a `<button>` that reveals this label as a pill on hover and focus. Pair with `LightboxTrigger asChild`. |
| loading | "lazy" \| "eager" | "lazy" | The native `<img>` loading attribute. |

## 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 shadow, 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Installation

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

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

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

Pro: `hero` comes with a [Koala UI Pro license](https://www.koalaui.com/pro). Its source is not published in these docs.

## Usage

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Anatomy

```tsx
import {
  Hero,
  HeroContent,
  HeroColumn,
  HeroTitle,
  HeroHighlight,
  HeroSubtitle,
  HeroActions,
  HeroFeatures,
  HeroFeature,
  HeroSocialProof,
  HeroRating,
  HeroMedia,
  HeroBackground,
  HeroCursors,
  HeroCursor,
  HeroScatter,
  HeroScatterTile,
  HeroStage,
  HeroStageMedia,
  HeroStageTitle,
  HeroStageCard,
  HeroStageReveal,
  HeroSpread,
  HeroSpreadMedia,
  HeroSpreadPanel,
  HeroSpreadIndex,
  HeroStatement,
  HeroSignoff,
  HeroMosaic,
  HeroFrame,
} from "@/components/ui/hero"

<Hero>
  <HeroBackground />
  <HeroScatter>
    <HeroScatterTile />
  </HeroScatter>
  <HeroCursors>
    <HeroCursor />
  </HeroCursors>
  <HeroContent>
    <HeroColumn>
      <HeroTitle>
        <HeroHighlight />
      </HeroTitle>
      <HeroSubtitle />
      <HeroActions />
      <HeroFeatures>
        <HeroFeature />
      </HeroFeatures>
      <HeroSocialProof>
        <HeroRating />
      </HeroSocialProof>
    </HeroColumn>
    <HeroMedia />
  </HeroContent>
</Hero>

{/* Alternative bodies, each in place of HeroContent */}
<HeroStage>
  <HeroStageMedia>
    <HeroStageTitle />
  </HeroStageMedia>
  <HeroStageCard />
  <HeroStageReveal />
</HeroStage>

<HeroSpread>
  <HeroSpreadMedia />
  <HeroSpreadPanel>
    <HeroSpreadIndex />
    <HeroColumn />
    <HeroColumn />
  </HeroSpreadPanel>
</HeroSpread>

<HeroContent>
  <HeroMosaic>
    <HeroFrame />
  </HeroMosaic>
  <HeroStatement />
  <HeroSignoff />
</HeroContent>
```

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Feature columns

`HeroFeatures` has a second shape. Set `layout="columns"` and the inline check row becomes three capability columns, each a bare mark in full ink 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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`.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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

The full-bleed `<section>` that provides the styling context; every part reads its `layout`. Forwards all native `<section>` props; every part accepts `className`, merged last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| layout | "centered" \| "split" \| "background" \| "cover" | "centered" | One centered column; copy beside a `HeroMedia`; light copy centered over a `HeroBackground`; or a full-viewport picture with the copy along its bottom edge. |

| CSS variable | Description |
| --- | --- |
| --hero-parallax-travel | How far a `parallax` background drifts. Keep it at or under (zoom - 1) / 2. |
| --hero-parallax-zoom | How much larger than its frame a `parallax` background is held, the slack the drift moves within. |
| --hero-cover-gutter | `cover`: what the contracted frame leaves at the page edge. |
| --hero-cover-max | `cover`: the container the frame lands in (the site's `8xl` by default). |
| --hero-cover-radius | `cover`: the corner the frame rounds to (`radius-3xl` by default). |
| --hero-cover-pad | `cover`: the caption's padding inside the frame, before the gutter is added. |
| --hero-cover-contract-start | `cover`: where in the scroll the contraction starts (with `-end`). |

### HeroContent

The max-width content column: the stacked column itself when centered, the two-column grid holding a `HeroColumn` and a `HeroMedia` when split. Forwards all native `<div>` props.

### HeroColumn

Groups the copy stack in a `split` hero or a spread panel. Forwards all native `<div>` props.

### HeroTitle

The balanced `<h1>`; the pill above it is the standalone `Announcement` (`variant="glass"` over media), not a Hero part. Forwards all native `<h1>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| size | "lg" \| "xl" \| "2xl" | "lg" | Peaks at 60px; `xl` is the 72px display cut; `2xl` the 96px poster cut for the foot of a `cover`. |

### HeroHighlight

A keyword marker inside a title or statement: a soft ink wash, the only way Koala marks a word in a headline (no gradient text). Forwards all native `<span>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| rotate | string[] | - | Cycle a fixed zone through these phrases, each entering with a per-character stagger and its own color. Needs two or more; holds the first under reduced motion. |
| interval | number | 2600 | Milliseconds each phrase holds before the next swaps in. |

### HeroSubtitle

The muted lead paragraph. Forwards all native `<p>` props.

### HeroActions

The CTA row: drop `Button`s in, no `size` needed. Forwards all native `<div>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| size | "sm" \| "md" \| "lg" \| "xl" | "xl" | Control height imposed on the children; an explicit one still wins. Pass `lg` beside an inline signup Input so field and button match. |

| Data attribute | Description |
| --- | --- |
| data-control-size | The imposed control size. |

### HeroFeatures

The feature list, a `<ul>`. Forwards all native `<ul>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| layout | "inline" \| "columns" | "inline" | A wrapping check-circle checklist, or three hairline-divided capability columns whose items take `icon` and `title`. |
| balance | boolean | false | Caps the row at a 36rem measure so items wrap into even rows (2 + 2, not 3 + 1). Ignored by `columns`. |

| Data attribute | Description |
| --- | --- |
| data-layout | `"inline"` or `"columns"`. |

### HeroFeature

One item, an `<li>`: inline it draws its own green check-circle before the label; in `columns`, given a `title`, it becomes a column with `children` as the sentence. Forwards all native `<li>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| icon | React.ReactNode | - | `columns` only: the bare mark in full ink, sized to 20px. Give every item in the row one, or none. |
| title | React.ReactNode | - | `columns` only: the one-line claim. Without it the item stays an inline check row. |

### HeroSocialProof

The proof row: an `AvatarGroup` beside a `HeroRating`. Forwards all native `<div>` props.

### HeroRating

A read-only `Rating` with its label ("5.0 Ratings") as children. Forwards all native `<div>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| value | number | 5 | Filled stars. |
| max | number | 5 | Total stars. |
| size | "sm" \| "md" \| "lg" | "sm" | Star size: 16px beside a one-line label, `md` (20px) beside a larger avatar stack. |

### HeroMedia

The visual region: the second column of a split hero, or below the copy when centered. Drop a screenshot, product window or logo wall in; forwards all native `<div>` props.

### HeroBackground

The full-bleed media layer for `background` and `cover`: stretches a child `<img>` or `<video>` to cover the band under a gradient scrim. Forwards all native `<div>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| parallax | boolean | false | Drift the media against the page on scroll through a CSS view timeline; still under reduced motion. Give it a picture with room around its subject. |

| Data attribute | Description |
| --- | --- |
| data-parallax | Present when `parallax` is on. |

### HeroCursors

The decorative multiplayer-cursor layer: covers the hero, `aria-hidden`, lets clicks through, and shows its cursors once the hero is 64rem wide. Forwards all native `<div>` props.

### HeroCursor

One wandering cursor, positioned by its tip via `className` (`left-[12%] top-[20%]`); `children` is the name tag. Holds still under reduced motion; forwards all native `<div>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| color | "brand" \| "purple" \| "teal" \| "pink" \| "orange" \| "success" | "brand" | The cursor and name-tag fill. |
| facing | "left" \| "right" | "left" | Which way the arrow points; the label hangs on the other side. |
| duration | number | 16 | Seconds per loop. Vary it per cursor. |
| phase | number | 0 | Where in its loop it starts, 0 to 1, so siblings never move in step. |
| labels | readonly string[] | - | Names the tag rolls through, one per click, in place of `children`. |

| Data attribute | Description |
| --- | --- |
| data-color | The `color` value. |
| data-facing | `"left"` or `"right"`. |

| CSS variable | Description |
| --- | --- |
| --cursor-x | Horizontal reach of the loop (28px by default); negative mirrors it. |
| --cursor-y | Vertical reach of the loop (20px by default). |

### HeroScatter

The poster-wall layer behind the copy: covers the hero, `aria-hidden`, never blocks a click, and is a size container. Forwards all native `<div>` props.

### HeroScatterTile

One photo print in the wall, placed by `className` (`left-[8%] top-16`, `hidden @5xl:block`) around a plain `<img>` it sizes and crops. Forwards all native `<div>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| size | "sm" \| "md" \| "lg" | "md" | The square card size; each steps up as the hero widens. |
| depth | "near" \| "far" | "near" | `far` steps the card back into the page behind the near ones. |
| tilt | number | 0 | Degrees it leans, positive clockwise; keep the wall between about -12 and 12. |
| delay | number | 0 | Milliseconds before it drifts in, so the wall assembles card by card. |

### HeroStage

The scroll stage, composed instead of `HeroContent`: a track taller than the viewport with one pinned screen, the only part that declares the timeline. Forwards all native `<div>` props.

| CSS variable | Description |
| --- | --- |
| --hero-stage-track | Total scroll length of the section (default `280svh`). |
| --hero-stage-w | Width of the card the picture lands on. |
| --hero-stage-h | Height of the card the picture lands on. |
| --hero-stage-radius | The landed card's corner. |
| --hero-stage-stagger | Scroll gap between stagger steps (4% of the pin by default). |

### HeroStageMedia

The frame that contracts from full-bleed to a card, covering a plain `<img>` or `<video>`; put `HeroStageTitle` inside it. Forwards all native `<div>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| scrim | boolean | true | A bottom-weighted gradient that carries the display word and leaves with it. |

### HeroStageTitle

The section's `<h1>` at poster scale, trimmed by the frame; two or three words. A plain string leaves character by character, with the heading keeping the text as its label. Forwards all native `<h1>` props.

| CSS variable | Description |
| --- | --- |
| --hero-stage-exit-stagger | Gap between two letters leaving; `0` turns the cascade off. |
| --hero-stage-exit-start | Where the exit window starts (with `--hero-stage-exit-end`). |
| --hero-stage-letter-travel | How far a letter slides out of its mask (default `-140%`); raise it for deep descenders. |

### HeroStageCard

One collage photograph that arrives around the landed card, placed and sized with inset utilities (never `translate-*` or `scale-*`). Its sway derives from `index`; forwards all native `<div>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| index | number | 0 | Place in the stagger: 0 lands first, each step a little further into the scroll. Number parts in landing order, not DOM order. |

| CSS variable | Description |
| --- | --- |
| --hero-stage-shift | Vertical arrival distance (default `1.75rem`); negative drops the part in from above. |
| --hero-stage-drift | Sideways arrival distance; negative arrives from the left. |
| --hero-stage-tilt | The lean the part arrives with and settles out of. |

### HeroStageReveal

A band of late copy (eyebrow, lede, CTAs, or a `HeroTitle` that must show at rest), placed on the vertical axis only; it centres its children. Forwards all native `<div>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| index | number | 0 | Place in the stagger: 0 lands first, each step a little further into the scroll. Number parts in landing order, not DOM order. |

| CSS variable | Description |
| --- | --- |
| --hero-stage-shift | Vertical arrival distance (default `1.75rem`); negative drops the part in from above. |
| --hero-stage-drift | Sideways arrival distance; negative arrives from the left. |
| --hero-stage-tilt | The lean the part arrives with and settles out of. |

### HeroSpread

The editorial spread, composed instead of `HeroContent` inside a `split` hero: a picture half and a panel half, stacked below `lg`. Forwards all native `<div>` props.

### HeroSpreadMedia

The picture half; covers and crops a plain `<img>` or `<video>`. Put it first so it leads on a phone; forwards all native `<div>` props.

### HeroSpreadPanel

The inked half; give it exactly two groups and it pushes the first to the top, the second to the foot. Forwards all native `<div>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| tone | "brand" \| "ink" | "ink" | A slab pinned dark on every theme, or the raw accent. Lead with `variant="neutral"` over ink, `Button tone="onMedia"` over brand. |

### HeroSpreadIndex

The chapter mark ("01") in the panel's outer corner, hidden from assistive tech. Forwards all native `<div>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| tone | "brand" \| "ink" | "ink" | The panel tone it sits on, so the chip inverts with it. |

### HeroStatement

The section's `<h1>` when the hero is one sentence, used instead of `HeroTitle`: display scale on a ~36-character measure. Forwards all native `<h1>` props.

### HeroSignoff

A letter's closing under the statement, one line per child; a `Signature` can be its last line. Forwards all native `<div>` props.

### HeroMosaic

The picture band across the top of a hero: a twelve-track grid of `HeroFrame`s (two tracks while stacked) gated by viewport breakpoints. Forwards all native `<div>` props.

### HeroFrame

One rounded, cropping picture frame with a hairline over the photograph; shape it with `className` and drop a plain `<img>` in. Drifts in on mount; forwards all native `<div>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| tone | "color" \| "mono" | "color" | `mono` drops the colour so a wall of photographs reads as one. |
| delay | number | 0 | Milliseconds before it drifts in. |

## 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 do value and max on HeroRating do?

`HeroRating` renders `max` stars with `value` of them filled (both 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Installation

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

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

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

Pro: `job-card` comes with a [Koala UI Pro license](https://www.koalaui.com/pro). Its source is not published in these docs.

## 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.

## Anatomy

```tsx
import {
  JobCard,
  JobCardContent,
  JobCardTitle,
  JobCardDescription,
  JobCardMeta,
  JobCardMetaItem,
  JobCardFlag,
  JobCardAction,
} from "@/components/ui/job-card"

<JobCard>
  <JobCardContent>
    <Badge />
    <JobCardTitle />
    <JobCardDescription />
    <JobCardMeta>
      <JobCardMetaItem icon={<JobCardFlag country="…" />} />
    </JobCardMeta>
  </JobCardContent>
  <JobCardAction>…</JobCardAction>
</JobCard>
```

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## API reference

### JobCard

The root. Renders a `<div>` and forwards all its props. Every part accepts `className`, merged last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| variant | "plain" \| "card" | "plain" | `plain` is a chrome-less row; `card` adds an inset ring and padding, no fill. |
| layout | "split" \| "stacked" \| "inline" | "split" | `split` puts the action beside the text from `sm`; `stacked` keeps it below; `inline` lines title and meta up in columns from `md`. |
| divided | boolean | - | A hairline under the row plus its own vertical padding. The rule drops on the last `<li>`, so wrap each row in one. |
| interactive | boolean | - | Hover, press and focus affordance for a row that is itself a link. |
| asChild | boolean | false | Renders the child (an `<li>`, an `<a>`) as the root via Radix Slot. |

### JobCardContent

The text column. Drop a `Badge` in first as the eyebrow. Forwards native `<div>` props.

### JobCardTitle

The role title. Forwards native `<div>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| asChild | boolean | false | Renders the child (say an `<h3>`) as the title, for a real heading. |

### JobCardDescription

The muted one-line summary. Forwards native `<p>` props.

### JobCardMeta

The meta tier: location, type, salary. Forwards native `<div>` props.

### JobCardMetaItem

One meta fact; the text truncates. Forwards native `<span>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| icon | React.ReactNode | - | The leading 20px glyph: a Koala icon or a `JobCardFlag`. |

### JobCardAction

The trailing action slot: a button, an avatar stack, a link. Forwards native `<div>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| size | "sm" \| "md" \| "lg" | "md" | The control size imposed on the buttons inside. |

| Data attribute | Description |
| --- | --- |
| data-control-size | The imposed size. |

### JobCardFlag

A country flag cropped into a ringed circle at the meta glyph's size, `aria-hidden` (the country is spelled out beside it).

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| country* | string | - | An ISO 3166-1 alpha-2 code, e.g. `"US"`. Renders nothing for an unknown code. |
| className | string | - | Merged onto the circle. |

## 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 36px 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Installation

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

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

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

Pro: `navbar` comes with a [Koala UI Pro license](https://www.koalaui.com/pro). Its source is not published in these docs.

## Usage

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Anatomy

```tsx
import {
  Navbar,
  NavbarInner,
  NavbarBrand,
  NavbarNav,
  NavbarLink,
  NavbarSearch,
  NavbarSpacer,
  NavbarActions,
  NavbarMobileToggle,
  NavbarMobileMenu,
  NavbarMobileLink,
  NavbarMobileActions,
} from "@/components/ui/navbar"

<Navbar>
  <NavbarInner>
    <NavbarBrand />
    <NavbarNav>
      <NavbarLink />
    </NavbarNav>
    <NavbarSpacer />
    <NavbarSearch />
    <NavbarActions>…</NavbarActions>
    <NavbarMobileToggle />
  </NavbarInner>
  <NavbarMobileMenu>
    <NavbarMobileLink />
    <NavbarMobileActions>…</NavbarMobileActions>
  </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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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, and a page that is not live yet dims one step below its siblings.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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`.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Logo in the middle

A 3-column grid on `NavbarInner` centers the brand independently of the side groups: links left, logo centered, actions right.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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).

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## API reference

### Navbar

The root `<header>`: owns the mobile disclosure and gives every part its styling. Forwards all `<header>` props. Every part accepts `className`, merged last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| variant | "full" \| "floating" | "full" | `full` is an edge-to-edge bar over a hairline; `floating` detaches it into a rounded card. |
| linkStyle | "pill" \| "underline" \| "text" | "pill" | Ghost chips with an ink underline, full-height tabs whose ink stroke welds to the bottom rule, or plain muted words that light up. |
| density | "comfortable" \| "compact" | - | Bar height, 64 or 56px. Inherits the nearest `DensityProvider` (compact with none) when unset. |
| collapseAt | "md" \| "lg" \| "xl" | "md" | Where the inline links hand over to the hamburger. Six links and two actions want `lg`; seven, or long labels, `xl`. |
| mobileMenu | "inline" \| "overlay" | "inline" | `inline` drops the links into the header's flow. `overlay` fills the screen under the bar, locks the page, closes on Escape and pins `NavbarMobileActions` to the bottom. |
| elevateOnScroll | boolean | false | Rests flat and gains its border and shadow once its scroll container moves. |
| docked | boolean | - | Sits on an app shell's surface: no fill, no bottom rule, a full-width row. Inherited inside a `LayoutTopbar`, else `false`. |
| open | boolean | - | The mobile menu's open state, controlled. |
| defaultOpen | boolean | false | The mobile menu's initial state, uncontrolled. |
| onOpenChange | (open: boolean) => void | - | Called when the mobile menu opens or closes. |

| Data attribute | Description |
| --- | --- |
| data-mobile-menu | `open` or `closed`. |
| data-scrolled | Present once the page scrolls under an `elevateOnScroll` bar. |
| data-navbar-menu | Set to `open` on `<html>` while an overlay menu is open, so a floating widget can step aside. |

### NavbarInner

The max-width row holding brand, nav, spacers, actions and toggle. Forwards native `<div>` props.

### NavbarBrand

The logo lockup. Renders an `<a>` and forwards all its props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| asChild | boolean | false | Renders the child (a framework `Link`) as the brand. |

### NavbarNav

The inline link list, a `<nav>` labelled `Main` unless you pass `aria-label`. Hidden below `collapseAt`.

### NavbarLink

A link in the bar, shaped by the root's `linkStyle`. Renders an `<a>`; `aria-disabled` turns a page that is not live yet muted and inert.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| active | boolean | false | The current page: full ink, the style's indicator, and `aria-current="page"`. |
| asChild | boolean | false | Renders the child (a framework `Link`, a menu trigger, a `<span>` for a page not live yet) as the link. |

| Data attribute | Description |
| --- | --- |
| data-active | Present when `active`. |
| data-state | `open` while a menu it triggers is open (set by the trigger); the caret flips. |

### NavbarSearch

The DS Input with a leading magnifier and a default width. Forwards `InputRoot` props (`size`, `hasError`); `children` sit at the field's end, e.g. a `Kbd` hint.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| placeholder | string | "Search" | Also the field's `aria-label`. |
| inputProps | InputFieldProps | - | Reaches the `<input>`: `value`, `onChange`, `name`. |
| size | "sm" \| "md" \| "lg" | "sm" | Field height; `md` when `collapsible`. |
| collapsible | boolean | false | Rests as a 36px icon chip that grows into the field on click (an `ExpandableSearch`); `className` sets the open width. |
| open | boolean | - | A collapsible search's open state, controlled. |
| defaultOpen | boolean | false | A collapsible search's initial state. |
| onOpenChange | (open: boolean) => void | - | Called when a collapsible search expands or collapses. |

### NavbarSpacer

A flexible gap that pushes the groups on either side apart. `aria-hidden`. Forwards native `<div>` props.

### NavbarActions

The right-hand cluster; a run of icon-only buttons sits flush as one strip. Forwards native `<div>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| size | "sm" \| "md" \| "lg" | "sm" | Control size imposed on the buttons inside. |

| Data attribute | Description |
| --- | --- |
| data-control-size | The imposed size. |

### NavbarMobileToggle

The hamburger, visible only below `collapseAt`. Renders a `<button>` with `aria-expanded` and forwards its props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| label | string | "Toggle menu" | The accessible name. |

| Data attribute | Description |
| --- | --- |
| data-state | `open` or `closed`, morphing the glyph. |

### NavbarMobileMenu

The disclosed panel of stacked links. Mounts only while open and closes on Escape. Forwards native `<div>` props.

| CSS variable | Description |
| --- | --- |
| --navbar-menu-top | Under `overlay`: the bar's bottom edge, where the full-screen panel starts. |

### NavbarMobileLink

A stacked link in the mobile panel: a 56px row under `overlay`, 44px inside an `AccordionContent`. Renders an `<a>`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| active | boolean | false | The current page: full ink, the style's indicator, and `aria-current="page"`. |
| asChild | boolean | false | Renders the child (a framework `Link`, a menu trigger, a `<span>` for a page not live yet) as the link. |

| Data attribute | Description |
| --- | --- |
| data-active | Present when `active`. |

### NavbarMobileActions

The panel's closing call to action (Log in, Buy now). Pinned to the screen's bottom under `overlay`. Forwards native `<div>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| size | "sm" \| "md" \| "lg" | "lg" | Control size imposed on the buttons inside. |

## 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. For a phone, `mobileMenu="overlay"` turns the panel into a full-screen menu with `NavbarMobileActions` pinned to the bottom.

### 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 short ink underline under `pill`, a full-width 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.

### 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Installation

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

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

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

Pro: `pricing` comes with a [Koala UI Pro license](https://www.koalaui.com/pro). Its source is not published in these docs.

## Usage

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Anatomy

```tsx
import {
  Pricing,
  PricingTierBanner,
  PricingTier,
  PricingTierHeader,
  PricingTierName,
  PricingTierDescription,
  PricingPrice,
  PricingAmount,
  PricingPeriod,
  PricingFeatures,
  PricingFeature,
  PricingFeatureGroup,
  PricingTierAction,
} from "@/components/ui/pricing"

<Pricing>
  <PricingTierBanner label="…">
    <PricingTier>
      <PricingTierHeader>
        <PricingTierName />
        <PricingTierDescription />
      </PricingTierHeader>
      <PricingPrice>
        <PricingAmount />
        <PricingPeriod />
      </PricingPrice>
      <PricingFeatures>
        <PricingFeature />
      </PricingFeatures>
      <PricingFeatureGroup label="…">
        <PricingFeature icon={…} />
      </PricingFeatureGroup>
      <PricingTierAction>…</PricingTierAction>
    </PricingTier>
  </PricingTierBanner>
</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 an ink 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## API reference

### Pricing

The grid of tiers. Forwards native `<div>` props. Every part accepts `className`, merged last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| columns | 2 \| 3 \| 4 | 3 | Tiers per row at `lg`; below that the grid falls to two columns, then one. |

### PricingTier

One plan card; it owns its tone and shares it with its parts. Forwards native `<div>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| tone | "default" \| "outline" \| "solid" \| "muted" \| "dashed" | "default" | Transparent, an ink edge, a brand fill with inverse parts, a grey panel, or a dashed edge. |
| featured | boolean | false | Anchors the recommended plan with an ink edge; independent of `tone`. |
| actionPosition | "bottom" \| "top" | "bottom" | `bottom` pins the CTA so buttons line up across cards; `top` floats it under the price. |
| size | "md" \| "lg" | "md" | `lg` is the landing-page type scale. |
| asChild | boolean | false | Renders the child (an `<a>`) as the card, so the whole tier is one link. |

| Data attribute | Description |
| --- | --- |
| data-featured | Present when `featured`. |
| data-tone | The tier's `tone`, when set. |

### PricingTierHeader

The name and description block. Drop a Badge beside the name to label a plan. Forwards native `<div>` props.

### PricingTierName

The plan name, a balanced `<h3>`.

### PricingTierDescription

The muted line under the name, a `<p>`.

### PricingPrice

The baseline-aligned price row. Forwards native `<div>` props.

### PricingAmount

The headline figure in `tabular-nums`, so switching plans never shifts the layout. Text works too, e.g. `Custom`. Renders a `<span>`.

### PricingPeriod

The muted suffix, e.g. `/month`. Renders a `<span>`.

### PricingFeatures

The checklist, a `<ul>`.

### PricingFeature

One row, an `<li>`, with its own leading glyph.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| included | boolean | true | A success check; `false` dims the row and shows a neutral minus. |
| icon | React.ReactNode | - | Replaces the leading glyph. |
| hint | React.ReactNode | - | Appends an info glyph whose tooltip carries the detail on hover or focus. |
| hintLabel | string | "More information" | The info glyph's accessible label. |

| Data attribute | Description |
| --- | --- |
| data-included | Present when the feature is included. |

### PricingFeatureGroup

A labelled section of `PricingFeature` rows under a centred Divider header, for a long, categorised inventory. Rows read at full strength with neutral icons. Forwards native `<div>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| label | React.ReactNode | - | The header label, e.g. `What's inside`. Omit for a bare list. |
| icon | React.ReactNode | - | A glyph beside the label. |

### PricingTierAction

The CTA band; its direct child stretches to the card's width. Forwards native `<div>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| size | "sm" \| "md" \| "lg" \| "xl" | "md" | Button size imposed on the CTA, the house 36px by default. The Button's own `size` wins. |

| Data attribute | Description |
| --- | --- |
| data-control-size | The imposed size. |

### PricingTierBanner

Wraps a `PricingTier` in a brand panel that peeks as a top label and a thin edge. Works over any tone and stretches to the row in a grid. Forwards native `<div>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| label* | React.ReactNode | - | The banner's text, e.g. `Get 40% off`. |

## FAQ

### How do I highlight the recommended plan?

Pass `featured` to its PricingTier for the ink edge, 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 ink edge 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Installation

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

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

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

Pro: `pricing-comparison` comes with a [Koala UI Pro license](https://www.koalaui.com/pro). Its source is not published in these docs.

## Usage

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Anatomy

```tsx
import {
  PricingComparison,
  PricingComparisonHeader,
  PricingComparisonPlan,
  PricingComparisonSection,
  PricingComparisonRow,
  PricingComparisonCell,
} from "@/components/ui/pricing-comparison"

<PricingComparison>
  <PricingComparisonHeader>
    <PricingComparisonPlan name="…">…</PricingComparisonPlan>
  </PricingComparisonHeader>
  <PricingComparisonSection title="…">
    <PricingComparisonRow label="…">
      <PricingComparisonCell />
    </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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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"`).

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## API reference

### PricingComparison

The matrix root: a horizontally scrollable `<table>` in a `<div>` that forwards all its props. Every part accepts `className`, merged last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| featured | number | - | The 0-based index of the plan column to highlight. The header cap and the column tint both derive from it. Omit for none. |
| align | "start" \| "center" | "start" | Places every plan header in its column: `start` over full-width CTAs, `center` for a versus matrix. |

### PricingComparisonHeader

The sticky plan-header row, a `<thead>`; it numbers its plans so `featured` can find them.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| label | React.ReactNode | - | A caption for the empty top-left corner, e.g. `Compare plans`. |

### PricingComparisonPlan

One plan's column header, a `<th>`. Its children are the CTA, stretched full-width and pinned to the cell's bottom.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| name* | React.ReactNode | - | The plan name, the column's label. |
| icon | React.ReactNode | - | A decorative mark above the name: a logo or a plan glyph. |
| price | React.ReactNode | - | The headline price in `tabular-nums`, e.g. `$29` or `Custom`. |
| period | React.ReactNode | - | The muted suffix, e.g. `/mo`. |
| badge | React.ReactNode | - | A chip beside the name, e.g. a `Most popular` Badge. |

| Data attribute | Description |
| --- | --- |
| data-featured | Present on the featured plan's header. |

### PricingComparisonSection

A group of rows, a `<tbody>`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| title | React.ReactNode | - | A full-width band above the rows. Omit for an ungrouped block. |

### PricingComparisonRow

One feature, a `<tr>`. Order its cells to match the plan columns.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| label* | React.ReactNode | - | The feature name, the row's leading header cell. |
| hint | React.ReactNode | - | Appends an info glyph whose tooltip carries the detail. |
| hintLabel | string | "More information" | The info glyph's accessible label. |

### PricingComparisonCell

One plan's value for a feature, a `<td>`: its children as a value, or a glyph when empty.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| included | boolean | true | With no children, a success check, or a muted minus when `false`. Ignored when children are passed. |

## 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 an ink 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Installation

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

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

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

Pro: `section` comes with a [Koala UI Pro license](https://www.koalaui.com/pro). Its source is not published in these docs.

## 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 canonical gap between them (48px, 72px from lg) comes for free.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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 `24px` on the sides (`32px` from `sm`), and stacks its children in a flex column with a **48px gap**, opening to 72px from `lg` (`gap-12 lg:gap-18`). Because the gap lives on the container, you never set a header-to-content margin per section again.

```tsx
import { Section, SectionContainer } from "@/components/ui/section"

<Section>
  <SectionContainer>
    <SectionHeader />
    ...
  </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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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).

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## API reference

### Section

The full-bleed band, a `<section>` landmark that owns the page's vertical rhythm (64px, 96px from `sm`). Forwards all native `<section>` props, and every part accepts `className`, merged last (so a `bg-*` wins).

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| padding | "default" \| "none" | "default" | `none` drops the band's padding for a child that is already its own band (a Hero), so the rhythm keeps a single owner. |

| CSS variable | Description |
| --- | --- |
| --section-pb | Overrides the bottom padding when set on the band or an ancestor; `0px` collapses the join between two bands on the same ground. |

### SectionContainer

The centered gutter: caps the width, pads 24px on the sides (32px from `sm`) and stacks its children in a flex column with a 48px gap (72px from `lg`). Children stretch; each centers itself. Forwards all native `<div>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| width | "wide" \| "xlarge" \| "default" \| "narrow" \| "full" | "wide" | Max width of the column: 1280, 1440, 1152 or 768px, or no cap. |

## 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 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 a 48px gap (72px from lg), 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Installation

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

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

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

Pro: `section-header` comes with a [Koala UI Pro license](https://www.koalaui.com/pro). Its source is not published in these docs.

## Usage

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Anatomy

```tsx
import {
  SectionHeader,
  SectionHeaderText,
  SectionHeaderHeading,
  SectionHeaderChip,
  SectionHeaderDescription,
  SectionHeaderActions,
} from "@/components/ui/section-header"

<SectionHeader>
  <SectionHeaderText>
    <SectionHeaderHeading>
      ... <SectionHeaderChip /> ...
    </SectionHeaderHeading>
    <SectionHeaderDescription />
  </SectionHeaderText>
  <SectionHeaderActions>...</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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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).

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

### 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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:

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

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 that sets alignment, scale and the entrance for its parts. Forwards all native `<div>` props, and every part accepts `className`, merged last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| align | "left" \| "center" | "left" | Aligns the lede and the actions row; centered text caps at `max-w-2xl` (`max-w-3xl` at `lg`). |
| orientation | "stacked" \| "split" | "stacked" | `split` sets the lede and actions side by side from `lg` up; left-aligned only, it stacks below `lg`. |
| size | "sm" \| "md" \| "lg" | "md" | Visual scale of the heading and description; `lg` is the bold display step. |
| stagger | boolean \| number | false | Cascades the eyebrow, heading, description and actions in: `true` at 70ms per unit, a number for that many ms. Honors reduced motion. |
| staggerBy | "phrase" \| "word" | "phrase" | The cascade unit: part by part, or word by word through the heading and description. |
| staggerBlur | boolean | false | Adds a 4px to 0 focus pull to each unit's entrance. |
| staggerTrigger | "mount" \| "inView" | "mount" | Plays the cascade on first render, or the first time the header scrolls into view. |

### SectionHeaderText

Groups the lede (eyebrow `Badge`, heading, description) so alignment applies as a unit and it can sit beside the actions in `split`. Forwards all native `<div>` props.

### SectionHeaderHeading

The heading; its visual scale comes from the root's `size`. Forwards all native heading props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| level | 1 \| 2 \| 3 | 2 | Semantic tag: `h1`, `h2` or `h3`. |

### SectionHeaderDescription

The muted supporting paragraph. Forwards all native `<p>` props.

### SectionHeaderActions

The CTA row for `Button`s, or an `Input` plus a `Button`; it wraps and aligns with the block. Forwards all native `<div>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| size | "sm" \| "md" \| "lg" \| "xl" | "md" | Control height imposed on every Button and field in the row; a control's own `size` still wins. |

| Data attribute | Description |
| --- | --- |
| data-control-size | The imposed control size. |

### SectionHeaderChip

An inline logo, icon or emoji chip dropped between the heading's words, sized in `em` so it scales with the heading. Decorative (`aria-hidden`) unless it gets an `aria-label`, which exposes it as an image. Forwards all native `<span>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| variant | "framed" \| "bare" | "framed" | A rounded tile that frames the mark, or a naked glyph or emoji. |
| reveal | boolean | false | Holds the chip closed until the heading scrolls into view, then parts the words and pops the mark in; chips in one heading take turns. |

| Data attribute | Description |
| --- | --- |
| data-state | `open` or `closed`, on the reveal wrapper when `reveal` is set. |

| CSS variable | Description |
| --- | --- |
| --chip-w | The chip's measured width in `em`, which the reveal opens the gap to. |
| --chip-space | The heading's space width in `em`, swallowed while the chip is closed. |
| --chip-index | The chip's order in its heading, which staggers the marks. |

## 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, or when scrolled into view with `staggerTrigger="inView"`) 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Installation

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

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

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

Pro: `team-member` comes with a [Koala UI Pro license](https://www.koalaui.com/pro). Its source is not published in these docs.

## 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.

## Anatomy

The root carries the `layout`, `align` and `variant`; the media frame carries the `shape`. Every part is optional.

```tsx
import {
  TeamMember,
  TeamMemberMedia,
  TeamMemberContent,
  TeamMemberName,
  TeamMemberRole,
  TeamMemberBio,
  TeamMemberSocials,
  TeamMemberSocial,
} from "@/components/ui/team-member"

<TeamMember>
  <TeamMemberMedia>…</TeamMemberMedia>
  <TeamMemberContent>
    <TeamMemberName />
    <TeamMemberRole />
    <TeamMemberBio />
    <TeamMemberSocials>
      <TeamMemberSocial label="…">…</TeamMemberSocial>
    </TeamMemberSocials>
  </TeamMemberContent>
</TeamMember>
```

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## API reference

### TeamMember

The root, a `<div>` that shares its layout and variant with every part through context. Forwards all native `<div>` props; every part accepts `className`, merged last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| layout | "stacked" \| "inline" \| "overlay" | "stacked" | Photo above the copy, a small photo beside it, or the copy set on the photo's foot over a dark scrim. |
| align | "start" \| "center" | "start" | `center` centres the frame, the copy and the links on the column. |
| variant | "plain" \| "card" | "plain" | `card` draws an inset ring with no fill, insetting a filling photo 8px; over a photo it becomes a floating panel. |
| asChild | boolean | false | Render as the single child element, e.g. the `<li>` of a roster list. |

| Data attribute | Description |
| --- | --- |
| data-layout | `"stacked"`, `"inline"` or `"overlay"`. |

### TeamMemberMedia

The photo frame: pass an `<img>` or `next/image` as its child, cropped to cover, with a hairline painted over it. Forwards all native `<div>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| shape | "portrait" \| "landscape" \| "square" \| "circle" | "portrait" | 4:5, 4:3, 1:1 or round. The first three fill their column; a circle holds the size you give it (`className="size-32"`). |

| Data attribute | Description |
| --- | --- |
| data-shape | The frame's shape. |
| data-fill | Present on every shape but `circle`; a card reads it to inset the photo. |

### TeamMemberContent

Groups the name, role, bio and links into one block beside or over the photo. Forwards all native `<div>` props.

### TeamMemberName

The person's name, an `<h3>`. Forwards all native `<h3>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| asChild | boolean | false | Render your own element (another heading level) instead of the `<h3>`. |

### TeamMemberRole

Their role or title, on the muted ink. Forwards all native `<p>` props.

### TeamMemberBio

A line or two about them, on the reading ink. Forwards all native `<p>` props.

### TeamMemberSocials

The wrapping row of social links under the copy. Forwards all native `<div>` props.

### TeamMemberSocial

One icon link, rendered as the icon-only ghost `Button` (32px box, 40px hit area, 44px on touch). Forwards all native `<a>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| label* | string | - | The accessible name and the hover tooltip, e.g. `"Lucía on LinkedIn"`. |
| asChild | boolean | false | Render the child element as the link, e.g. to wrap `next/link`. |

### teamMemberVariants

The `tv` recipe behind every part, for styling a block of your own to match.

## 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 tooltip, 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Installation

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

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

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

Pro: `testimonials` comes with a [Koala UI Pro license](https://www.koalaui.com/pro). Its source is not published in these docs.

## Usage

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Anatomy

```tsx
import {
  Testimonial, TestimonialMark, TestimonialQuote, TestimonialBody,
  TestimonialFooter, TestimonialAuthor, TestimonialName, TestimonialTitle,
  TestimonialLogo,
} from "@/components/ui/testimonials"

<Testimonial>
  <TestimonialMark />
  <TestimonialQuote>…</TestimonialQuote>
  <TestimonialBody>…</TestimonialBody>
  <TestimonialFooter>
    {/* <Avatar /> */}
    <TestimonialAuthor>
      <TestimonialName>…</TestimonialName>
      <TestimonialTitle>…</TestimonialTitle>
    </TestimonialAuthor>
    <TestimonialLogo>…</TestimonialLogo>
  </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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## With a rating

Drop our [Rating](https://www.koalaui.com/docs/components/rating.md) with `readOnly` above the quote for star social proof.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Author on top

Lead with the byline by rendering the `TestimonialFooter` first with `className="mt-0"`: a compact, scannable layout for dense walls.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Featured

Drop a `TestimonialMark` in for a quotation glyph and use `variant="elevated"` to lift one standout quote.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## API reference

### Testimonial

The root card, a `<figure>` that shares its styles with every part through context. Forwards all native `<figure>` props; every part accepts `className`, merged last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| variant | "plain" \| "outline" \| "soft" \| "elevated" \| "ghost" \| "bare" | "plain" | The surface: a tinted fill, a hairline ring, a soft ring with shadow, a lifted card, no surface (keeps padding), or no surface and no padding. |
| align | "start" \| "center" | "start" | `center` centers the mark, quote and byline, for a single pull-quote. |
| divided | boolean | false | Adds a hairline rule above the `TestimonialFooter`. |
| size | "md" \| "lg" \| "xl" | "md" | The type scale of the quote, body and byline together. Pair `lg` and `xl` with an `lg` Avatar. |
| asChild | boolean | false | Renders onto its child element (Radix Slot) instead of a `<figure>`. |

| CSS variable | Description |
| --- | --- |
| --surface | Set by the `plain` and `elevated` variants to the card's fill, for nested parts that match it. |

### TestimonialMark

An optional decorative quotation glyph above the quote, `aria-hidden`. Forwards all native `<div>` props.

### TestimonialQuote

The quote, a `<blockquote>`. Followed by a `TestimonialBody`, it styles itself as the headline (semibold, full-strength ink). Forwards all native `<blockquote>` props.

### TestimonialBody

Optional longer quote under a headline `TestimonialQuote`, quieter and a step smaller. Forwards all native `<p>` props.

### TestimonialFooter

The author row, a `<figcaption>` pinned to the bottom with `mt-auto` (pass `mt-0` to lead with it). Forwards all native `<figcaption>` props.

### TestimonialAuthor

The name and title stack beside the Avatar. Forwards all native `<div>` props.

### TestimonialName

The author's name. Forwards all native `<div>` props.

### TestimonialTitle

The author's role, muted; truncates at `size="md"`. Forwards all native `<div>` props.

### TestimonialLogo

A company wordmark or logo: trailing edge inside the footer, start edge anywhere else. Forwards all native `<div>` props.

## 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 a faint muted gray, 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Installation

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

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

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

Pro: `ai-panel` comes with a [Koala UI Pro license](https://www.koalaui.com/pro). Its source is not published in these docs.

## Usage

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

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.

## Anatomy

```tsx
import {
  AIPanel,
  AIPanelHeader,
  AIPanelHeading,
  AIPanelTitle,
  AIPanelDescription,
  AIPanelActions,
  AIPanelAction,
  AIPanelExpandToggle,
  AIPanelBody,
  AIPanelFooter,
} from "@/components/ui/ai-panel"

<AIPanel>
  <AIPanelHeader>
    <AIPanelHeading>
      <AIPanelTitle />
      <AIPanelDescription />
    </AIPanelHeading>
    <AIPanelActions>
      <AIPanelExpandToggle />
      <AIPanelAction />
    </AIPanelActions>
  </AIPanelHeader>
  <AIPanelBody />
  <AIPanelFooter />
</AIPanel>
```

## 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`.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Inside an app frame (anchor)

By default the `split` and `floating` windows pin to the browser window (`fixed`, sized in `dvh`). When the assistant lives inside an app frame instead (a tablet window, a device mock, a dashboard pane) pass `anchor="container"`: the panel positions itself `absolute` against the nearest positioned ancestor and sizes the rail and the window in `%` of it, so it travels and scales with the frame. Give the frame `relative overflow-hidden`. The `AIPanelExpandToggle` morphs between the two exactly as it does on the viewport, and the docked rail draws only its inner border.

The example also hands the scroll to the thread: `<AIPanelBody scrollable={false}>` becomes a fixed column and the `Conversation` filling it scrolls, so a `ConversationScrollButton` can float over its bottom edge. Scroll up in the thread to see it.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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`).

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## API reference

### AIPanel

The shell: a full-height flex column on the popover surface that owns the view mode. Forwards all native `<div>` props. Every part accepts `className`, merged last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| view | "inline" \| "split" \| "floating" | - | The view mode, controlled: fills its container, a full-height right rail, or a bottom-right window. |
| defaultView | "inline" \| "split" \| "floating" | "inline" | The initial view mode, uncontrolled. |
| onViewChange | (view: "inline" \| "split" \| "floating") => void | - | Called when the view mode changes, e.g. from `AIPanelExpandToggle`. |
| anchor | "viewport" \| "container" | "viewport" | What the `split` and `floating` windows are positioned against: the browser window (`fixed`), or the nearest positioned ancestor (`absolute`, sized in %) for a panel inside an app frame. Ignored by `inline`. |

| Data attribute | Description |
| --- | --- |
| data-view | `"inline"`, `"split"` or `"floating"`: the current view mode. |
| data-anchor | `"viewport"` or `"container"`; absent in the `inline` view. |

| CSS variable | Description |
| --- | --- |
| --surface | Set to `var(--popover)`, so a nested composer blends with the panel rather than the page. |

### AIPanelHeader

The bordered header row: leading media (an `Avatar`), the heading column and the actions. Inside a Drawer, also render a `<DrawerTitle className="sr-only">`. Forwards all native `<div>` props.

### AIPanelHeading

The title and description column that grows between the media and the actions. Forwards all native `<div>` props.

### AIPanelTitle

The panel title, truncated to one line. Forwards all native `<div>` props.

### AIPanelDescription

A muted one-line subtitle under the title. Forwards all native `<div>` props.

### AIPanelActions

The trailing action row of the header. Forwards all native `<div>` props.

### AIPanelAction

A header action (new chat, history, close): a `Button` that takes every Button prop. Use `asChild` to wrap a `DrawerClose`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| variant | ButtonProps["variant"] | "ghost" | Any Button variant. |
| size | "sm" \| "md" \| "lg" \| "xl" | "sm" | The Button size. |
| iconOnly | boolean | true | A square icon button; its `aria-label` doubles as the tooltip. |

### AIPanelExpandToggle

A prewired `AIPanelAction` that flips the panel between the `split` rail and the `floating` window, swapping its icon and label ("Float" or "Dock to side"). Takes every Button prop; must live inside an `AIPanel`.

### AIPanelBody

The only scrolling region, with edge fades; drop a `Conversation` inside. Forwards all native `<div>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| scrollable | boolean | true | The body scrolls its own overflow, padded with a scroll fade. Set `false` to hand the scroll to the child that fills it, e.g. a `Conversation` with `min-h-0 flex-1`, so a `ConversationScrollButton` can float over the thread. |

| Data attribute | Description |
| --- | --- |
| data-scrollable | `"false"` when `scrollable` is off; absent otherwise. |

### AIPanelFooter

The pinned composer dock; drop a `PromptInput` inside. Forwards all native `<div>` props.

## 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.

### Can the split and floating windows live inside a container instead of the viewport?

Yes: pass `anchor="container"`. The panel then positions itself `absolute` against the nearest positioned ancestor and sizes the rail and window in % of it (no `fixed`, no `dvh`), so it stays inside an app frame such as a tablet window. Give that frame `relative overflow-hidden`. The `AIPanelExpandToggle` keeps morphing between split and floating.

### How do I add a jump-to-latest button to the panel's thread?

Hand the scroll to the thread: render `<AIPanelBody scrollable={false}>` and give the `Conversation` inside `className="min-h-0 flex-1 p-4"`. Then drop a `ConversationScrollButton` as the Conversation's last child; it floats over the thread's bottom edge while the reader is scrolled up.

### 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Installation

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

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

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

Pro: `chat` comes with a [Koala UI Pro license](https://www.koalaui.com/pro). Its source is not published in these docs.

## Usage

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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
import {
  Conversation,
  ConversationScrollButton,
  Message,
  MessageAvatar,
  MessageBody,
  MessageHeader,
  MessageName,
  MessageTime,
  MessageReasoning,
  MessageReasoningTrigger,
  MessageReasoningContent,
  MessageReasoningStep,
  MessageReasoningFiles,
  MessageReasoningFile,
  MessageReasoningFilesMore,
  MessageReasoningQueries,
  MessageReasoningQuery,
  MessageReasoningSources,
  MessageReasoningSource,
  MessageContent,
  MessageTyping,
  MessageActions,
  MessageAction,
} from "@/components/ui/chat"

<Conversation>
  <Message>
    <MessageAvatar />
    <MessageBody>
      <MessageHeader>
        <MessageName />
        <MessageTime />
      </MessageHeader>
      <MessageReasoning>
        <MessageReasoningTrigger />
        <MessageReasoningContent>
          <MessageReasoningStep>
            <MessageReasoningQueries>
              <MessageReasoningQuery />
            </MessageReasoningQueries>
            <MessageReasoningSources>
              <MessageReasoningSource />
            </MessageReasoningSources>
            <MessageReasoningFiles>
              <MessageReasoningFile />
              <MessageReasoningFilesMore />
            </MessageReasoningFiles>
          </MessageReasoningStep>
        </MessageReasoningContent>
      </MessageReasoning>
      <MessageContent>
        <MessageTyping />
      </MessageContent>
      <MessageActions>
        <MessageAction />
      </MessageActions>
    </MessageBody>
  </Message>
  <ConversationScrollButton />
</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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Actions

`MessageActions` holds a row of `MessageAction` buttons for copy, regenerate, and feedback. Each wraps our `Button`, so it inherits the focus ring and a tooltip drawn from its `aria-label`.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Typing indicator

While a response streams, drop a `MessageTyping` inside a `MessageContent`. Three dots ripple left to right, and hold still under reduced-motion.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Agent trace

For a coding agent, write each step as one line with `title`, in the present while it runs (“Reading 3 of 6 files”) and in the past once done (“Read 6 files about sessions and cookies”). The live line takes full ink and a slow sweep; finished lines go muted. Give a step an `icon` for its kind, a search or the final check. Mark an approach that went nowhere with `status="dead-end"`: a cross on the rail, and the line fades back. Set `elapsed` on the trigger and it counts “Thinking 9s”, then settles to “Thought for 14s”. Press *Run again* to watch the full trace.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Jump to latest

Drop a `ConversationScrollButton` as the last child of a `Conversation`. It stays hidden while the reader is at the newest turn; scroll up and a pill fades in, centered over the thread's bottom edge (a sticky row, so it never scrolls with the history and takes no room in it). Pressing it glides back down and resumes following. The follow survives streaming and resizing: a turn that grows by itself, or a panel that changes size, keeps a reader who was at the bottom there, and the thread's own glide never flashes the pill on the way down. Stream the answer below, then scroll up while it writes.

The Conversation must be the element that scrolls: give it a height (here `min-h-0 flex-1` in a sized column; in an AI Panel, `<AIPanelBody scrollable={false}>`).

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## API reference

### Conversation

The scrollable thread, a `role="log"` polite live region; give it a height or max-height to scroll. Forwards all native `<div>` props. Every part accepts `className`, merged last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| variant | "plain" \| "bubble" | "plain" | The style of every turn: the assistant answer as a page, or every turn a bubble. |
| stickToBottom | boolean | true | Follows new turns while the reader is already at the bottom; scrolling up is never yanked back. The first pass lands instantly, later ones glide. Turn it off for a static transcript that opens at the top. |

| Data attribute | Description |
| --- | --- |
| data-variant | `"plain"` or `"bubble"`. |

### ConversationScrollButton

The "jump to latest" pill: place it as the last child of a `Conversation`. It shows only while the reader has scrolled away from the newest turn, floats centered over the thread's bottom edge, and on press glides back down and resumes following. The `Conversation` must be the element that scrolls (`min-h-0 flex-1`, or `AIPanelBody scrollable={false}`). Takes every `Button` prop except `asChild`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| label | string | "Jump to latest" | The pill's text, also its accessible name. |
| children | React.ReactNode | - | Replaces the default arrow and `label`. |
| variant | ButtonProps["variant"] | "outline" | Any Button variant. |
| size | "sm" \| "md" \| "lg" \| "xl" | "sm" | The Button size. |

| Data attribute | Description |
| --- | --- |
| data-state | `"visible"` or `"hidden"`, on the sticky row that wraps the button. |

### Message

One turn; its role flows to every part. Forwards all native `<div>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| role | "assistant" \| "user" | "assistant" | Who sent it: drives the side, the alignment and the bubble tint. |
| variant | "plain" \| "bubble" | - | Overrides the style of the conversation for this turn. |

| Data attribute | Description |
| --- | --- |
| data-role | `"assistant"` or `"user"`. |

### MessageAvatar

The sender avatar, an `Avatar` that takes every Avatar root prop. Children replace the initials (with an icon, say).

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| src | string | - | The image URL. |
| name | string | - | The alt text, and the source of the initials fallback. |
| size | "xs" \| "sm" \| "md" \| "lg" \| "xl" | "sm" | The Avatar size. |

### MessageBody

The column holding header, content and actions, aligned to the message side. Forwards all native `<div>` props.

### MessageHeader

The optional meta row above the content. Forwards all native `<div>` props.

### MessageName

The sender name. Forwards all native `<span>` props.

### MessageTime

The muted timestamp. Forwards all native `<span>` props.

### MessageContent

The bubble (or, for a `plain` assistant turn, the page), markup-agnostic. Forwards all native `<div>` props.

### MessageActions

The row of actions under a turn. Forwards all native `<div>` props.

### MessageAction

One action (copy, regenerate): a `Button` that takes every Button prop; its `aria-label` names it and feeds the tooltip.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| variant | ButtonProps["variant"] | "ghost" | Any Button variant. |
| size | "sm" \| "md" \| "lg" \| "xl" | "sm" | The Button size. |
| iconOnly | boolean | true | A square icon button. |

### MessageTyping

Three animated dots, a `role="status"` labelled "Assistant is typing"; put it in a `MessageContent`. Forwards all native `<div>` props.

### MessageReasoning

The collapsible thinking block, over Radix `Collapsible.Root`: forwards all its props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| streaming | boolean | false | The model is still thinking: the icon pulses and the default label reads "Thinking…". |
| open | boolean | - | Open state, controlled. |
| defaultOpen | boolean | false | Open state on first render, uncontrolled. |
| onOpenChange | (open: boolean) => void | - | Called when it opens or closes. |

| Data attribute | Description |
| --- | --- |
| data-state | `"open"` or `"closed"`, from Radix. |

### MessageReasoningTrigger

The one-line toggle, over Radix `Collapsible.Trigger`. Children are the label ("Thought for 6s"); without them it rolls between "Thinking…" and "Reasoning".

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| elapsed | boolean \| number | - | `true` keeps its own clock: "Thinking 9s" while streaming, then "Thought for 14s". A number shows that many seconds. Ignored when you pass children. |

| Data attribute | Description |
| --- | --- |
| data-state | `"open"` or `"closed"`. Turns the caret. |

### MessageReasoningContent

The chain of thought behind a left rail, over Radix `Collapsible.Content`. `className` lands on the inner `<div>`.

| Data attribute | Description |
| --- | --- |
| data-state | `"open"` or `"closed"`. |

### MessageReasoningStep

One phase of the reasoning log, with a node on the rail. Forwards native `<div>` props except `title`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| title | React.ReactNode | - | The one line an agent-trace step reads as. Full ink and a sweep while active, muted once done, fainter as a dead end. |
| label | React.ReactNode | - | A quiet caption above the step ("Searching"). |
| status | "active" \| "done" \| "dead-end" | "done" | `active` turns the dot into an ink pulse; `dead-end` swaps it for a cross and fades the title. |
| marker | boolean | true | Draws the rail node (the dot, or the icon). |
| icon | React.ReactNode | - | A glyph in place of the dot (14px unless it carries its own `size-*`), such as a search or the final check. |

| Data attribute | Description |
| --- | --- |
| data-status | `"active"`, `"done"` or `"dead-end"`. |

### MessageReasoningFiles

A wrapping row of file pills. Forwards all native `<div>` props.

### MessageReasoningFile

One file or page the model opened: a pill, not a link. Forwards all native `<span>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| name* | string | - | The file name; its extension picks the glyph (ts, tsx, css, md…). Children replace it as the label. |
| icon | React.ReactNode | - | Overrides the derived glyph. |

### MessageReasoningFilesMore

The "+3 more" that closes a row of files. Forwards all native `<span>` props.

### MessageReasoningQueries

A wrapping row of query pills. Forwards all native `<div>` props.

### MessageReasoningQuery

One search the model ran: a monospace pill with a magnifier. Forwards all native `<span>` props.

### MessageReasoningSources

The URLs the model consulted. Forwards all native `<div>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| layout | "chips" \| "list" | "chips" | Compact domain pills, or a bordered list of titled rows. Flows to each source. |

| Data attribute | Description |
| --- | --- |
| data-layout | `"chips"` or `"list"`. |

### MessageReasoningSource

One source, an `<a>` that opens in a new tab. Forwards native `<a>` props except `title`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| href* | string | - | The URL; the domain and favicon derive from it. |
| title | React.ReactNode | - | The headline in the `list` layout; the domain by default. |
| favicon | string | - | Overrides the derived favicon; a globe shows if it fails. |

## 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 I show a jump-to-latest button when the reader scrolls up?

Render a ConversationScrollButton as the last child of the Conversation. It appears only while the reader is scrolled away from the newest turn, floats over the thread's bottom edge, and on press scrolls back down and resumes following. The Conversation has to be the scrolling element, so give it a height; inside an AI Panel use <AIPanelBody scrollable={false}> with a Conversation that has min-h-0 flex-1.

### Does resizing the panel around the thread make it lose its place?

No. A box that shrinks under a transition (an AI Panel morphing from split to floating, a composer growing) moves the scroll offset by itself, and Conversation does not mistake that for the reader leaving the bottom: a scroll only counts as theirs when it follows a wheel, touch, key or scrollbar press, or when neither the box nor its content changed size since it was last measured. A reader who was following stays pinned to the newest turn through the whole transition, and one who had scrolled up keeps their place.

### 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/citation.md -->

# Citation

The mark an answer leaves where a claim came from: a chip in the running text that previews its sources on hover or focus, and goes to them on click. One chip per claim, however many sources back it.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Installation

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

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

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

Pro: `citation` comes with a [Koala UI Pro license](https://www.koalaui.com/pro). Its source is not published in these docs.

## Usage

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Anatomy

Most of the time `<Citation sources={…} />` is all you write: it renders the chip and the card from the data. Compose the parts when the chip needs its own label or the card its own content.

```tsx
import {
  Citation,
  CitationTrigger,
  CitationContent,
  CitationSource,
} from "@/components/ui/citation"

<Citation sources={sources}>
  <CitationTrigger />
  <CitationContent>
    <CitationSource />
  </CitationContent>
</Citation>
```

## The card

Each source is a row: the favicon and domain as a quiet eyebrow, the page title, then the passage the claim rests on, clamped to three lines. Several sources stack as several rows in one card, each a link of its own, with its hover fill set 8px into the card on the Popover's inset rung so the corners stay concentric.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Source chips

`variant="source"` trades the counter for the favicon and the domain, with `+N` when more than one source backs the claim: the answer-engine register, where saying where without a hover is worth the width in the line. The counter stays the default because it reads quietest in dense prose.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## In a chat

Drop the chips straight into a Chat turn. The chip carries a `data-slot`, so the turn's prose styles leave it alone: markdown links get the underline, the chip keeps its own look.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## API reference

### Citation

The root: the sources and the HoverCard state every part reads. With no children it renders the chip and the card from `sources`. Forwards Radix `HoverCard.Root` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| sources* | CitationSourceData[] | - | `{ href, title?, description?, favicon? }` per source. The chip links to the first. |
| index | number | - | The footnote number the `number` chip shows. Omitted, it shows the source count. |
| variant | "number" \| "source" | "number" | `number` is a footnote counter; `source` shows the favicon, the domain and `+N`. |
| openDelay | number | 300 | Hover intent before the card opens, in ms. Shorter than a plain HoverCard's 700. |
| closeDelay | number | 200 | Delay before the card closes once the pointer leaves, in ms. |
| children | React.ReactNode | - | Compose the chip and card yourself with `CitationTrigger` and `CitationContent`. |

### CitationTrigger

The chip: a Badge on a real link to the first source, opened in a new tab. Its accessible name lists every source, because the card is never keyboard-reachable. Forwards native `<a>` props except `href`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| children | React.ReactNode | - | Overrides the label (the index, or the domain and count). |

### CitationContent

The preview card. With no children it lists every source; pass `CitationSource`s to compose it. Forwards `HoverCardContent` props (`side`, `align`, `density`).

### CitationSource

One source in the card: favicon and domain, the title, the extract. A link. Forwards native `<a>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| href* | string | - | The page. The domain and favicon derive from it. |
| title | string | - | The page title, clamped to two lines. |
| description | string | - | The passage the claim rests on, clamped to three lines. |
| favicon | string | - | Overrides the favicon derived from the domain. |

## FAQ

### Why one chip for several sources, not a chip per source?

Because the chip marks a claim, not a link. Three chips in a row at the end of a sentence are noise the reader has to parse; one chip that opens onto three sources says the same thing and keeps the sentence readable.

### Why a HoverCard and not a Popover?

A citation is a link someone wants to peek at before following, which is exactly what HoverCard is for: it opens on hover or focus, never takes focus, and does not open on touch, so a tap simply follows the link. A Popover would turn every citation into a two-step interaction.

### Can keyboard and screen reader users reach every source?

The card itself is never keyboard-reachable (HoverCard's rule), so the chip's accessible name carries every source title, and the chip is a real link to the first one. If an answer cites a lot, pair the chips with a sources list at the end of the turn, such as Chat's reasoning sources, so every link is reachable on its own.

### Where do the favicons come from?

From the source's domain, through a public favicon service, with a globe as the fallback when a site has none or the request fails. Pass favicon on a source to use your own.

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

Yes. The chip is a Badge in its default tone and the card is the HoverCard surface, so both re-theme across light, dark, cream and moonlight with no extra work.

---

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

# Context Meter

How much of the model's context window a conversation has used. A 16px ring and a percentage on the toolbar; hover or click it and it opens onto what the total is made of and what it has cost.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Installation

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

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

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

Pro: `context-meter` comes with a [Koala UI Pro license](https://www.koalaui.com/pro). Its source is not published in these docs.

## Usage

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Anatomy

```tsx
import {
  ContextMeter,
  ContextMeterTrigger,
  ContextMeterContent,
  ContextMeterRows,
  ContextMeterRow,
  ContextMeterFooter,
} from "@/components/ui/context-meter"

<ContextMeter>
  <ContextMeterTrigger />
  <ContextMeterContent>
    <ContextMeterRows>
      <ContextMeterRow />
    </ContextMeterRows>
    <ContextMeterFooter />
  </ContextMeterContent>
</ContextMeter>
```

## Levels

Three levels by the fraction of the window used: normal, then warning from `warnAt` (70%), then critical from `criticalAt` (90%). The level tints the ring and the bar and nothing else: a window filling up is information, not an error, until it is nearly full. Drag the slider to watch the ring sweep.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Ring only

`showValue={false}` drops the percentage for a crowded toolbar. The trigger keeps the whole reading as its accessible name, and the number is one hover away.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## An action in the footer

The footer is a muted well, so it can carry the way out of a full window as well as the cost: a ghost button to compact or summarise the conversation.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## In a composer

On PromptInput's toolbar it sits beside the send button, with the [Model Selector](https://www.koalaui.com/docs/components/model-selector.md) at the other end. Pass the selected model's window as `max` and the reading re-scales when you switch: the same chat is 42% of a 200K window and 8% of a 1M one.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## API reference

### ContextMeter

The root: the reading every part shares, and a Popover that opens on hover and on click.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| used* | number | - | Tokens the conversation uses now. |
| max* | number | - | The model's context window, in tokens. |
| warnAt | number | 0.7 | Fraction from which the reading turns `warning`. |
| criticalAt | number | 0.9 | Fraction from which the reading turns `critical`. |
| format | (tokens: number) => string | compact, en-US | How a token count is written (`84.2K`). Fixed locale by default, so server and client agree. |
| open | boolean | - | The panel's open state, controlled. |
| defaultOpen | boolean | - | The panel's initial open state. |
| onOpenChange | (open: boolean) => void | - | Called when the panel opens or closes. |

### ContextMeterTrigger

A ghost `Button` with the ring and the percentage. Its accessible name is the whole reading. Forwards `Button` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| showValue | boolean | true | Show the percentage beside the ring. |
| size | ButtonProps["size"] | "sm" | Match the bar it sits on. |

| Data attribute | Description |
| --- | --- |
| data-level | `normal`, `warning` or `critical`. |

### ContextMeterContent

The breakdown panel: the total over a Meter bar in the level's tone, then your rows. Forwards `PopoverContent` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| title | React.ReactNode | "Context window" | The panel's heading. |

### ContextMeterRows

The rows under the bar, a `<dl>`.

### ContextMeterRow

One part of the total, a `<dt>`/`<dd>` pair.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| label* | React.ReactNode | - | What the part is: `Input`, `Cached`. |
| tokens | number | - | Formatted the way the root formats. |
| value | React.ReactNode | - | Anything else in the value column (a price). |
| swatch | string | - | A text colour class for a leading dot, to key the row to a chart. |

### ContextMeterFooter

The muted well that closes the panel: the cost, or an action. Forwards native `<div>` props.

## FAQ

### Why a Popover and not a HoverCard?

The reading matters on a phone too, and a HoverCard never opens on touch. The Popover opens on hover for a pointer and on a tap or Enter for everyone else, so the breakdown is reachable however you get there.

### Why does the colour only change near the limit?

Because using context is normal. A ring that turned amber at 50% would train people to ignore it. It stays neutral until 70% (warning) and 90% (critical); move those with warnAt and criticalAt for a model that degrades earlier.

### Where do the numbers come from?

From your SDK's usage report: input, output, cached and reasoning tokens per turn, summed for the conversation. The component only formats and draws them; it does not count tokens.

### Is it accessible?

The trigger is a real button whose name is the whole reading, such as "Context: 42% used, 84.2K of 200K tokens". The panel's bar is a Meter with its own value text, and the breakdown is a description list.

---

<!-- 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Installation

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

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

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

Pro: `generation` comes with a [Koala UI Pro license](https://www.koalaui.com/pro). Its source is not published in these docs.

## Usage

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Anatomy

```tsx
import {
  Generation,
  GenerationHeader,
  GenerationIcon,
  GenerationLabel,
  GenerationStatus,
  GenerationActions,
  GenerationAction,
  GenerationPrompt,
  GenerationCanvas,
  GenerationImage,
  GenerationCaption,
  GenerationProgress,
  GenerationPercent,
  GenerationOverlay,
  GenerationGrid,
  GenerationFooter,
  GenerationMeta,
} from "@/components/ui/generation"

<Generation>
  <GenerationHeader>
    <GenerationIcon />
    <GenerationLabel />
    <GenerationStatus />
    <GenerationActions>
      <GenerationAction />
    </GenerationActions>
  </GenerationHeader>
  <GenerationPrompt />
  <GenerationCanvas>
    <GenerationImage />
    <GenerationCaption />
    <GenerationProgress />
    <GenerationPercent />
    <GenerationOverlay />
  </GenerationCanvas>
  <GenerationGrid>
    <GenerationCanvas />
  </GenerationGrid>
  <GenerationFooter>
    <GenerationMeta />
  </GenerationFooter>
</Generation>
```

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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## API reference

### Generation

The root and the provider; sets `aria-busy` while generating. Forwards all native `<div>` props; every part accepts `className`, merged last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| status | "idle" \| "generating" \| "complete" \| "failed" | "complete" | Drives the halftone screen, the `GenerationStatus` chip, `aria-busy` and which state parts render at all. |
| progress | number \| null | null | Percent, 0 to 100, read by every readout in the card. `null` means the model reports none: bars sweep and the screen stays shut. |
| ratio | "square" \| "portrait" \| "landscape" \| "wide" \| "tall" \| "auto" | "square" | The frame's shape, taken before there is a picture; sizes every canvas in the card. |
| variant | "card" \| "plain" | "card" | `card` is the ringed standalone artifact; `plain` drops the chrome and gutter for a Chat turn or an AIPanel body. |
| transition | "smooth" \| "none" | "smooth" | How the reveal reacts to a new percentage: eased, or welded to the number for a continuously driven frame. |
| density | "comfortable" \| "compact" | "compact" | Padding, gaps and the grid gutter; the 8px media inset never moves. Falls back to the nearest `DensityProvider`. |
| asChild | boolean | false | Merge onto your own element via Radix Slot instead of rendering a `<div>`. |

| Data attribute | Description |
| --- | --- |
| data-status | The resolved state: `idle`, `generating`, `complete` or `failed`. |

| CSS variable | Description |
| --- | --- |
| --generation-reveal | How far open the halftone screen is, as a percentage; a registered property, so it interpolates. |
| --generation-stagger | The beat between tiles of a `GenerationGrid` entering. |

### GenerationHeader

The eyebrow row: an icon, a label, then a status chip and/or actions. Forwards all native `<div>` props.

### GenerationIcon

The eyebrow's glyph, `aria-hidden`. Forwards all native `<span>` props.

### GenerationLabel

The eyebrow's word ("Image", the model's name), truncated. Forwards all native `<span>` props.

### GenerationStatus

An optional `Badge` derived from the root's `status` (Ready, Generating with a spinner, Done, Failed with a warning glyph). Forwards all `Badge` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| variant | BadgeProps["variant"] | - | Overrides the per-state tone. |
| children | React.ReactNode | - | Overrides the per-state wording. |

### GenerationActions

Trailing slot for icon buttons, in the header, the footer or the overlay. Forwards all native `<div>` props.

### GenerationAction

One tool, a thin `Button` wrapper; forwards all `Button` props. Over a picture, pass `tone="onMedia"`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| variant | ButtonProps["variant"] | "ghost" | The Button variant. |
| size | ButtonProps["size"] | "sm" | The Button size. |
| iconOnly | boolean | true | Square icon button; give it an `aria-label`. |

### GenerationPrompt

The prompt, quoted back in muted ink. Forwards all native `<p>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| lines | 1 \| 2 \| 3 | - | Clamp to this many lines; the full text stays in the DOM. No clamp when omitted. |

### GenerationCanvas

The frame, sized by its ratio from the first render; owns the halftone screen and the edge ring, and pins a `GenerationProgress` dropped inside to its bottom edge. Forwards all native `<div>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| ratio | "square" \| "portrait" \| "landscape" \| "wide" \| "tall" \| "auto" | - | Overrules the root's `ratio` for this frame. |
| status | "idle" \| "generating" \| "complete" \| "failed" | - | Overrules the root's `status` for this frame, so a sheet finishes tile by tile. |
| progress | number \| null | - | Overrules the root's `progress` for this frame, so each tile opens at its own pace. |

| Data attribute | Description |
| --- | --- |
| data-status | The resolved state: `idle`, `generating`, `complete` or `failed`. |

| CSS variable | Description |
| --- | --- |
| --generation-reveal | Set on the frame when it has its own `progress` or has finished ahead of the card. |
| --surface | Set to `var(--muted)`, read by nested controls. |

### GenerationImage

The picture under the screen: a raw `<img>` that fades up as it decodes, and again when `src` changes. Mount it as soon as you have a URL; forwards all native `<img>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| alt | string | "" | Decorative by default; pass a real `alt` when the image carries meaning. |

| Data attribute | Description |
| --- | --- |
| data-loaded | Present once the image has decoded. |

### GenerationCaption

The line inside an empty frame with the glyph its state implies; reads the root's `status` and renders nothing once it is `complete`. Forwards all native `<div>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| children | React.ReactNode | - | The words. Omitted, it says what the state says; `null` shows only the glyph, for a small tile. |

### GenerationProgress

How far along as a hairline, composing `Progress`; renders only while the root is `generating`. Forwards all `Progress` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| value | number \| null | - | Overrules the root's `progress`; `null` sweeps indeterminately. |
| variant | ProgressProps["variant"] | "chrome" | The Progress variant. |
| size | ProgressProps["size"] | "xs" | The Progress size. |
| tone | ProgressProps["tone"] | "foreground" | The Progress tone. |
| aria-label | string | "Generating" | The progressbar's accessible name. |

### GenerationPercent

How far along as a pill `Badge` in the frame's bottom-right corner; renders only while `generating` with a number to show. Use it or `GenerationProgress`, not both.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| value | number \| null | - | Overrules the root's `progress`. |
| children | (percent: number) => React.ReactNode | - | Formats the rounded percentage. Defaults to `62%`. |
| variant | BadgeProps["variant"] | "overlay" | The Badge variant, legible on a photograph. |
| size | BadgeProps["size"] | "sm" | The Badge size. |

### GenerationOverlay

The tools over a finished picture: a scrim that fades up on hover, focus or a coarse pointer. Renders only when the root is `complete`; forwards all native `<div>` props.

### GenerationGrid

A sheet of variations whose tiles enter one beat apart, in CSS. Forwards all native `<div>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| columns | 2 \| 3 \| 4 | 2 | Frames per row; two hold on a phone, three and four fan out from `sm`. |

### GenerationFooter

The closing row: meta on the left, actions kept to the right edge when it wraps. Forwards all native `<div>` props.

### GenerationMeta

Model, size and time in small tabular type, truncated. Forwards all native `<span>` props.

## 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/model-selector.md -->

# Model Selector

The picker for which model answers. A searchable list grouped by provider, where each row carries what decides the choice: what the model is for, what it can do and how much context it holds.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Installation

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

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

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

Pro: `model-selector` comes with a [Koala UI Pro license](https://www.koalaui.com/pro). Its source is not published in these docs.

## Usage

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Anatomy

```tsx
import {
  ModelSelector,
  ModelSelectorTrigger,
  ModelSelectorContent,
  ModelSelectorInput,
  ModelSelectorList,
  ModelSelectorGroup,
  ModelSelectorItem,
  ModelSelectorLogo,
  ModelSelectorName,
  ModelSelectorCapabilities,
  ModelSelectorCapability,
  ModelSelectorMeta,
} from "@/components/ui/model-selector"

<ModelSelector>
  <ModelSelectorTrigger>
    <ModelSelectorLogo />
  </ModelSelectorTrigger>
  <ModelSelectorContent>
    <ModelSelectorInput />
    <ModelSelectorList>
      <ModelSelectorGroup>
        <ModelSelectorItem>
          <ModelSelectorLogo />
          <ModelSelectorName addon={<ModelSelectorCapabilities>
            <ModelSelectorCapability />
          </ModelSelectorCapabilities>} />
          <ModelSelectorMeta />
        </ModelSelectorItem>
      </ModelSelectorGroup>
    </ModelSelectorList>
  </ModelSelectorContent>
</ModelSelector>
```

## In a composer

The trigger is a ghost Button at `sm`, so it sits on PromptInput's toolbar like every other control there. It shows what you give it, usually the provider's mark and the model's short name, rather than mirroring the row: the toolbar wants “Opus 5.5”, the list wants the full name. Its natural neighbour is the [Context Meter](https://www.koalaui.com/docs/components/context-meter.md), which turns over when you switch to a model with a different window.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Without search

`ModelSelectorInput` is optional. Leave it out when the list fits on one screen. Focus then lands on the list itself, so the arrow keys still walk the rows and Enter still chooses.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## API reference

### ModelSelector

The root: the selection and the panel's open state. Choosing a model closes the panel.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| value | string | - | The selected model's id, controlled. |
| defaultValue | string | - | The initially selected model's id. |
| onValueChange | (value: string) => void | - | Called with the chosen model's id. |
| open | boolean | - | The panel's open state, controlled. |
| defaultOpen | boolean | false | The panel's initial open state. |
| onOpenChange | (open: boolean) => void | - | Called when the panel opens or closes. |

### ModelSelectorTrigger

A ghost `Button` holding what you pass (a logo and the model's short name), with the caret added. No press scale. Forwards `Button` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| size | ButtonProps["size"] | "sm" | Match the bar it sits on. |

### ModelSelectorContent

The panel: a Command inside the Popover, with the Popover as its only surface. Forwards `PopoverContent` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| label | string | "Models" | The list's accessible name. |
| align | "start" \| "center" \| "end" | "start" | Alignment to the trigger. |

### ModelSelectorInput

The search row. Matches the id and `keywords`. Forwards `CommandInput` props.

### ModelSelectorList

The scrolling list, with the empty state. Forwards native `<div>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| empty | React.ReactNode | "No models found." | Shown when a search matches nothing. |

### ModelSelectorGroup

A provider's models under its name; collapses when filtered empty. Forwards `CommandGroup` props (`heading`).

### ModelSelectorItem

One model. Adds the selected check in a fixed slot. Forwards `CommandItem` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| value* | string | - | The model's id: what gets selected and searched. |
| keywords | string[] | - | More terms to match: the display name, the provider. |
| disabled | boolean | - | Shown but not choosable (no access on this plan). |

| Data attribute | Description |
| --- | --- |
| data-selected | Present on the chosen model. |

### ModelSelectorLogo

A provider's mark in the row's 20px box, with a hairline over it. `aria-hidden`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| src | string | - | An image URL. Or pass your own SVG as children. |

### ModelSelectorName

The model's name with an optional second line and something after it.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| description | React.ReactNode | - | A quiet second line: what the model is for. |
| addon | React.ReactNode | - | After the name: `ModelSelectorCapabilities` or a `Badge`. |

### ModelSelectorCapabilities

A run of small muted glyphs after the name. Renders a `<span>`.

### ModelSelectorCapability

One capability: a small glyph that explains itself in a Tooltip on hover (a plain hint for the name alone, the rich tooltip with a description). The name is also screen-reader text in the row.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| label* | string | - | What the glyph means: `Vision`, `Reasoning`. |
| description | React.ReactNode | - | One line under the name in the tooltip: what it means for this model. |

### ModelSelectorMeta

The trailing read-out (context window, price) in `tabular-nums`. Renders a `<span>`.

## FAQ

### Why not a Select?

A Select is right for three models. A real product lists a dozen across providers, each with a context window, capabilities and a price tier that decide the choice. The panel here is the DS's Command, so you get search, groups and the sliding keyboard highlight, inside a Popover with the Popover as the only surface.

### Why doesn't the trigger show the selected row automatically?

Rows only exist while the panel is open, and the toolbar almost always wants a shorter label than the list. You render the trigger's content from your own selected model, which keeps the two independent.

### Where do the provider logos come from?

From you. ModelSelectorLogo takes an image src or your own SVG as children, in a 20px box with a hairline over it so a white mark on a white panel still has an edge. The demo uses the providers' favicons.

### Is it accessible?

The trigger is a real button that opens a Popover; the list is the Command listbox, with arrow-key navigation, Enter to choose and the active row announced. Capability glyphs explain themselves in a tooltip on hover, and carry their names as screen-reader text in the row, since a tooltip on a glyph is a pointer-only hint. The selected row announces that it is selected.

---

<!-- 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Installation

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

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

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

Pro: `plan` comes with a [Koala UI Pro license](https://www.koalaui.com/pro). Its source is not published in these docs.

## Usage

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

```tsx
import {
  Plan,
  PlanHeader,
  PlanIcon,
  PlanLabel,
  PlanStatus,
  PlanActions,
  PlanHeading,
  PlanTitle,
  PlanDescription,
  PlanGroup,
  PlanGroupHeader,
  PlanGroupTitle,
  PlanGroupCount,
  PlanSteps,
  PlanStep,
  PlanStepContent,
  PlanStepTitle,
  PlanStepDescription,
  PlanStepInput,
  PlanStepAction,
  PlanStepEdit,
  PlanStepTrigger,
  PlanStepDetail,
  PlanTasks,
  PlanTask,
  PlanStepSkeleton,
  PlanMore,
  PlanAddStep,
  PlanFooter,
  PlanSummary,
} from "@/components/ui/plan"

<Plan>
  <PlanHeader>
    <PlanIcon />
    <PlanLabel />
    <PlanStatus />
    <PlanActions />
  </PlanHeader>
  <PlanHeading>
    <PlanTitle />
    <PlanDescription />
  </PlanHeading>
  <PlanGroup>
    <PlanGroupHeader>
      <PlanGroupTitle />
      <PlanGroupCount />
    </PlanGroupHeader>
    <PlanSteps>
      <PlanStep>
        <PlanStepContent>
          <PlanStepTitle />
          <PlanStepDescription />
        </PlanStepContent>
        <PlanStepAction />
        <PlanStepEdit />
      </PlanStep>
      <PlanStep collapsible>
        <PlanStepTrigger>
          <PlanStepContent>
            <PlanStepInput />
          </PlanStepContent>
        </PlanStepTrigger>
        <PlanStepDetail>
          <PlanTasks>
            <PlanTask />
          </PlanTasks>
        </PlanStepDetail>
      </PlanStep>
      <PlanStepSkeleton />
    </PlanSteps>
    <PlanMore />
    <PlanAddStep />
  </PlanGroup>
  <PlanFooter>
    <PlanSummary />
    …
  </PlanFooter>
</Plan>
```

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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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, an ink 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## API reference

### Plan

The card and the context every part reads. Forwards native `<div>` props. Every part accepts `className`, merged last, and every block is droppable.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| status | "drafting" \| "review" \| "running" \| "complete" \| "failed" | "review" | The plan's own state: drives `PlanStatus`, the row entrance while drafting, and `aria-busy` while drafting or running. |
| editing | boolean | false | Edit mode. A plan is read-only by default; `PlanStepEdit` and `PlanAddStep` render nothing until this is on. |
| variant | "card" \| "plain" | "card" | `card` is the standalone artifact; `plain` drops the chrome and gutter for a Chat turn or an AI Panel. |
| density | "comfortable" \| "compact" | - | Row rhythm, block gaps and padding. Inherits the nearest `DensityProvider` (compact with none). |
| asChild | boolean | false | Renders the child as the card via Radix Slot. |

| Data attribute | Description |
| --- | --- |
| data-status | The plan's `status`. |
| data-editing | Present in edit mode. |

### PlanHeader

The eyebrow row: icon, label, then a status chip or actions. Forwards native `<div>` props.

### PlanIcon

The identity mark: one muted glyph. `aria-hidden`. Renders a `<span>`.

### PlanLabel

The eyebrow's word, e.g. `Plan`. Renders a `<span>`.

### PlanActions

Trailing header slot for ghost icon buttons (regenerate, a menu). Forwards native `<div>` props.

### PlanHeading

The title and description block. Forwards native `<div>` props.

### PlanTitle

What the plan will do, in one line. Renders an `<h3>` and forwards its props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| asChild | boolean | false | Renders the child (another heading level) as the title. |

### PlanDescription

The muted lines under the title. Forwards native `<p>` props.

### PlanStatus

An optional chip worded and toned from the root's `status`. Forwards `Badge` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| variant | BadgeProps["variant"] | - | Overrides the tone the status picks. |
| children | React.ReactNode | - | Overrides the wording (`Drafting`, `Running`, and so on). |

### PlanGroup

A block of work, set apart by its label and whitespace, not a box. Forwards native `<div>` props.

### PlanGroupHeader

The group's label row. Forwards native `<div>` props.

### PlanGroupTitle

The group's quiet label, e.g. `To-dos`. Renders a `<span>`.

### PlanGroupCount

The group's count beside its title. Renders a `<span>`.

### PlanSteps

The to-do list, an `<ol>`.

### PlanStep

One to-do, an `<li>` with its own 14px mark drawn from `status`. Forwards all its props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| status | "pending" \| "active" \| "done" \| "failed" | "pending" | The row's mark and ink. |
| collapsible | boolean | false | Turns the row into a Radix Collapsible: `PlanStepTrigger` opens a `PlanStepDetail`. |
| open | boolean | - | A collapsible step's open state, controlled. |
| defaultOpen | boolean | - | A collapsible step's initial state. |
| onOpenChange | (open: boolean) => void | - | Called when a collapsible step opens or closes. |

| Data attribute | Description |
| --- | --- |
| data-status | The step's `status`. |
| data-state | `open` or `closed` on a collapsible step. |

### PlanStepContent

Wraps a row's text and fills, so the trailing slots ride the right edge. Forwards native `<div>` props.

### PlanStepTitle

The to-do itself; muted, the live row steps up to full ink. Forwards native `<div>` props.

### PlanStepDescription

An optional quieter second line. Forwards native `<div>` props.

### PlanStepTrigger

The disclosure row of a collapsible step, with a turning caret. Forwards Radix `Collapsible.Trigger` props.

### PlanStepDetail

What a collapsible step hides: sub-tasks, a note, a tool's output. Forwards Radix `Collapsible.Content` props.

### PlanTasks

The sub-task list inside a step's detail, a `<ul>`.

### PlanTask

One sub-task, an `<li>`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| done | boolean | false | The dash cross-fades to a green check. |

| Data attribute | Description |
| --- | --- |
| data-done | Present when `done`. |

### PlanStepInput

The inline editor for a row's title in edit mode; it keeps the row's type, so nothing shifts. Shift+Enter breaks a line. Forwards `<textarea>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| value* | string | - | The to-do's text. |
| onValueChange* | (value: string) => void | - | Called on every edit. |
| onCommit | (value: string) => void | - | Enter or blur accepts the edit. |
| onCancel | () => void | - | Escape abandons it. |

### PlanStepAction

What the row is telling you (a duration, a Badge, a Retry), always visible. Forwards native `<div>` props.

### PlanStepEdit

What you can do to the row, in practice one Remove button. Renders nothing unless the plan is `editing`, then fades in with the pointer. Forwards native `<div>` props.

### PlanStepSkeleton

The placeholder row while the plan is drafting, with the real row's geometry. Renders an `<li>`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| width | "full" \| "long" \| "short" | "full" | Vary it so a draft reads organic, not striped. |

### PlanMore

The overflow row that closes a long list. Which rows you render is yours. Forwards native `<button>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| expanded | boolean | false | Flips the label from `{count} more` to `Show less`. |
| count | number | - | How many rows are hidden, shown while collapsed. |

| Data attribute | Description |
| --- | --- |
| data-expanded | Present when `expanded`. |

### PlanAddStep

The row that closes an editable list. Renders nothing outside edit mode. Forwards native `<button>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| children | React.ReactNode | "Add step" | The row's label. |

### PlanFooter

The commit bar: the summary left, the ghost and primary pair right. Forwards native `<div>` props.

### PlanSummary

The footer's meta, e.g. `6 to-dos · about 4 min`, in `tabular-nums`. Forwards native `<p>` props.

## 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 (foreground, success, destructive, muted, border and edge), so the glyph, 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

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 16px on a 32px control, and the send button, the same size as its neighbours, 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

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

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

Pro: `prompt-input` comes with a [Koala UI Pro license](https://www.koalaui.com/pro). Its source is not published in these docs.

## Usage

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

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.

## Anatomy

```tsx
import {
  PromptInputSuggestions,
  PromptInputSuggestion,
  PromptInputQuickActions,
  PromptInputQuickAction,
  PromptInputBanner,
  PromptInputBannerAction,
  PromptInput,
  PromptInputMentions,
  PromptInputTextarea,
  PromptInputMentionList,
  PromptInputMentionItem,
  PromptInputMentionEmpty,
  PromptInputToolbar,
  PromptInputMentionButton,
  PromptInputButton,
  PromptInputCount,
  PromptInputSubmit,
} from "@/components/ui/prompt-input"

<PromptInputSuggestions>
  <PromptInputSuggestion />
</PromptInputSuggestions>
<PromptInputQuickActions>
  <PromptInputQuickAction />
</PromptInputQuickActions>
<div className="relative isolate flex flex-col">
  <PromptInputBanner>
    …
    <PromptInputBannerAction />
  </PromptInputBanner>
  <PromptInput>
    <PromptInputMentions>
      <PromptInputTextarea />
      <PromptInputMentionList>
        <PromptInputMentionItem />
        <PromptInputMentionEmpty />
      </PromptInputMentionList>
      <PromptInputToolbar>
        <PromptInputMentionButton />
        <PromptInputButton />
        <PromptInputCount />
        <PromptInputSubmit />
      </PromptInputToolbar>
    </PromptInputMentions>
  </PromptInput>
</div>
```

## 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`.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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 16px 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Connect your apps

Instead of a single action, the strip can carry the apps themselves: `PromptInputBannerApps` holds a row of `PromptInputBannerApp` logos, each a button named by a tooltip. The banner's muted tint is what makes it read as sitting behind the composer, and when the row outgrows the strip it scrolls under a soft fade instead of wrapping.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Character limit

Set `maxLength` once on the root. The textarea enforces it (typing and pasting stop at the cap), a `PromptInputCount` reads it as its `max`, and a value over it (one set from outside) cannot be sent. A count that is always on is noise; give it a `threshold` (a fraction of the limit) and it appears only near the cap. Here it shows from 80% on: type a few more words.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Quick actions

`PromptInputSuggestions` is a scrolling row of question chips. When the starters are *actions* (an icon and a verb), stack them as a list instead: `PromptInputQuickActions` takes an optional `label` that names the group, and `visible` folds the rest behind a “Show N more” toggle (a Collapsible: it carries `aria-expanded`, the rows tween open and the label rolls). Each `PromptInputQuickAction` is a ghost Button row whose `onClick` you own: the pattern below writes the full prompt into the composer instead of sending it, so the reader can edit it first.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Mentions

Wrap the textarea and a `PromptInputMentionList` in `PromptInputMentions`. Typing `@` at the start of a word (or pressing `PromptInputMentionButton`) opens a list right at the line being typed: a Radix Popover anchored to the caret, flipping when there is no room. The query flows out through `onQueryChange` (filter or fetch with it), and picking a row replaces `@query` with `@Name` and fires `onMentionSelect`.

Focus never leaves the textarea. It controls the listbox (`aria-controls`, `aria-haspopup`) and names the highlighted row with `aria-activedescendant`. ↑ ↓ move, Enter and Tab pick (`selectOnTab={false}` keeps Tab for leaving), and Escape closes *only* the list: it is caught before a dialog or a panel that closes on Escape can see it. It is a plain textarea, no contenteditable, so it behaves the same in every engine, older embedded Chromium included.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## API reference

### PromptInput

The composer: a `<form>` that owns the value and shares it with its parts. Forwards native `<form>` props but `onSubmit`. Every part accepts `className`, merged last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| value | string | - | The prompt, controlled. Reset it yourself to clear after a send. |
| defaultValue | string | - | The initial prompt. Uncontrolled, the field clears itself after a submit. |
| onValueChange | (value: string) => void | - | Called on every keystroke. |
| onSubmit | (value: string) => void | - | Called on Enter or the send button; skipped while empty, disabled or loading. |
| onStop | () => void | - | Called by the stop button. |
| loading | boolean | false | A response is streaming: send flips to stop. |
| disabled | boolean | false | Dims and freezes the composer. |
| maxLength | number | - | A character cap, set once here: the textarea enforces it natively (typing and pasting stop at it), `PromptInputCount` reads it as its `max`, and a value over it cannot be sent. |

| Data attribute | Description |
| --- | --- |
| data-disabled | Present when disabled. |
| data-loading | Present while loading. |

### PromptInputTextarea

The field; grows with its content up to a cap, then scrolls. Forwards `<textarea>` props but `value`, `defaultValue` and `onChange`, which the root owns.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| submitOnEnter | boolean | true | Enter sends and Shift+Enter breaks a line. `false`: Enter breaks, ⌘ or Ctrl+Enter sends. |
| placeholder | string | "Ask anything…" | The empty field's hint. |
| maxLength | number | - | The native cap; defaults to the composer's `maxLength`, so set it on the root instead. |

### PromptInputToolbar

The bottom bar for actions and the send button. Forwards native `<div>` props.

### PromptInputButton

A toolbar action (attach, model picker, mic): a ghost `Button` sized to the composer, so its icons line up across the bar. Forwards `Button` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| variant | ButtonProps["variant"] | "ghost" | The button's style. |
| size | ButtonProps["size"] | "sm" | 32px, the height every control on the toolbar shares. |

### PromptInputSubmit

The send button, disabled while the prompt is empty or over `maxLength`; a stop button calling `onStop` while loading. Pinned right. Forwards `Button` props but `iconOnly` and `asChild`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| children | React.ReactNode | - | The send glyph; an upward arrow by default. |
| variant | ButtonProps["variant"] | "primary" | The button's style. |
| size | ButtonProps["size"] | "sm" | 32px, the height every control on the toolbar shares. |
| sendLabel | string | "Send message" | The send state's accessible name. |
| stopLabel | string | "Stop generating" | The stop state's accessible name. |

### PromptInputCount

A character readout, `aria-live="polite"`. Forwards native `<span>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| current | number | - | Overrides the composer's character count, e.g. with tokens. |
| max | number | - | A limit: renders `current / max` and turns destructive past it. Defaults to the composer's `maxLength`. |
| threshold | number | 0 | Shows the count only near the limit: the fraction of `max` (0 to 1) it must reach first, e.g. `0.8`. Below it the part renders nothing. Needs a `max`. |

| Data attribute | Description |
| --- | --- |
| data-over | Present once the count passes `max`. |

### PromptInputBanner

A second card peeking from behind the composer (limits, errors). Place it beside `PromptInput` in a `relative isolate flex flex-col` wrapper. Forwards native `<div>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| side | "top" \| "bottom" | "top" | The edge it peeks from: render it before the composer for `top`, after for `bottom`. |
| tone | "default" \| "info" \| "warning" \| "destructive" | "default" | Tints the leading icon. |
| icon | React.ReactNode \| false | - | Overrides the tone's icon; `false` drops it. |
| onClose | () => void | - | Adds a dismiss button that calls it. |
| closeLabel | string | "Dismiss" | The dismiss button's accessible name. |

| Data attribute | Description |
| --- | --- |
| data-tone | The banner's `tone`. |
| data-side | The banner's `side`. |

### PromptInputBannerAction

An inline link-styled action in a banner, e.g. `Learn more`. Renders a `<button type="button">`.

### PromptInputBannerApps

A row of app logos at the end of a banner; scrolls with a fade when it outgrows the strip. A `role="group"` `<div>`: give it an `aria-label`.

### PromptInputBannerApp

One app in the row: its logo as a button, named by a tooltip. Forwards native `<button>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| label* | string | - | The tooltip and the button's accessible name, e.g. `Connect Slack`. |
| src | string | - | The logo's URL. Or pass your own SVG as children. |

### PromptInputSuggestions

A row of prompt-starter chips above the composer; context-free. Forwards native `<div>` props.

### PromptInputSuggestion

One chip. Renders a `<button type="button">`; wire `onClick` yourself (fill the prompt, send, or both).

### PromptInputQuickActions

A labelled list of starter actions above the composer while the thread is empty, the vertical sibling of `PromptInputSuggestions`; the tail can fold behind a "Show N more" Collapsible. A `role="group"`; forwards native `<div>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| label | React.ReactNode | - | A quiet caption above the rows ("Start with"); also names the group for screen readers. |
| visible | number | - | How many rows show before the rest fold behind the toggle. Omit to show them all. |
| moreLabel | (hidden: number) => React.ReactNode | (n) => Show ${n} more | The toggle's label while folded, given the hidden count. |
| lessLabel | React.ReactNode | "Show less" | The toggle's label while unfolded. |
| expanded | boolean | - | Unfolded, controlled. |
| defaultExpanded | boolean | false | Unfolded on first render, uncontrolled. |
| onExpandedChange | (expanded: boolean) => void | - | Called when the toggle folds or unfolds the rows. |

### PromptInputQuickAction

One quick action row: a ghost `Button` laid out full width and left aligned, icon muted. Forwards `Button` props; wire `onClick` yourself.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| variant | ButtonProps["variant"] | "ghost" | The button's style. |
| size | ButtonProps["size"] | "sm" | The button's size. |

### PromptInputMentions

Adds `@` mentions to the composer: wrap the `PromptInputTextarea`, a `PromptInputMentionList` and the toolbar with it, inside a `PromptInput`. Typing the trigger at the start of a word opens the list; picking a row replaces `@query` with `@text`. Escape closes only the list.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| trigger | string | "@" | The character that opens the list. |
| maxSpaces | number | 0 | Spaces allowed in the query before the list gives up: `0` for handles, `1` for "First Last" names. |
| onQueryChange | (query: string \| null) => void | - | Called as the query changes, with the text after the trigger, or `null` once the list closes. Filter or fetch with it. |
| onMentionSelect | (mention: PromptInputMention) => void | - | Called when a row is picked, as its text is written into the composer. |
| selectOnTab | boolean | true | Tab picks the highlighted row. `false` keeps Tab for leaving the field. |

### PromptInputMentionList

The mention list: a compact Popover surface holding a listbox, opening above the line and flipping when there is no room. Focus never leaves the textarea. Forwards Radix `Popover.Content` props but `asChild`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| anchor | "caret" \| "field" | "caret" | What the list hangs from: the line box of the `@` being typed, or the whole textarea so it spans the composer's width. |
| label | string | "Suggestions" | The listbox's accessible name. |
| container | HTMLElement \| null | document.body | The portal target, e.g. an app frame scaled with a transform. |
| side | "top" \| "right" \| "bottom" \| "left" | "top" | The preferred side of the anchor. |
| align | "start" \| "center" \| "end" | "start" | Alignment against the anchor. |
| sideOffset | number | 4 | The gap from the anchor, in pixels. |

| Data attribute | Description |
| --- | --- |
| data-anchor | `"caret"` or `"field"`. |
| data-state | `"open"` or `"closed"`, from Radix. |

### PromptInputMentionItem

One row of the list (`role="option"`); lay out an avatar, a name and a muted id inside. Forwards native `<div>` props but `onSelect`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| value* | string | - | The row's unique id (a user id, a handle), reported in `onMentionSelect`. |
| textValue | string | - | What gets written after the trigger when picked. Defaults to `value`. |
| disabled | boolean | false | Skips the row in keyboard navigation and blocks picking it. |
| onSelect | (mention: PromptInputMention) => void | - | Called when this row is picked, before the list-wide `onMentionSelect`. |

| Data attribute | Description |
| --- | --- |
| data-active | Present on the highlighted row. |
| data-disabled | Present when disabled. |

### PromptInputMentionEmpty

Shown only while the list has no rows ("No matches", "Searching…"); a polite live region. Forwards native `<div>` props.

### PromptInputMentionButton

A toolbar button that writes the trigger at the caret and opens the list. A `PromptInputButton`, so it sizes with the composer; an `@` glyph and the label "Mention" by default. Must live inside `PromptInputMentions`.

### usePromptInputMentions

A hook for parts inside `PromptInputMentions`. Returns `{ open, query, close, insertTrigger }`: whether the list is open, the query after the trigger (e.g. to show "Searching…"), and the two actions.

### findMentionQuery

The pure helper behind the list: `findMentionQuery(text, caret, trigger = "@", maxSpaces = 0)` returns `{ start, end, query }` for an open mention ending at the caret, or `null`.

## 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 big are the toolbar buttons?

Send is disabled while the value is empty, disabled, or loading. Every toolbar control, the send button included, is a 32px Button with a 16px icon, so the bar reads as one row of equals; pass `size` to a single button only for a deliberate exception.

### How do I cap the prompt length and show a counter only near the limit?

Set `maxLength` on PromptInput: the textarea enforces it, PromptInputCount reads it as its max, and a value over it cannot be sent. Give the count a `threshold`, e.g. `threshold={0.8}`, and it renders nothing until the text reaches 80% of the limit.

### Suggestion chips or quick actions?

PromptInputSuggestions is a single scrolling row of question chips. PromptInputQuickActions is a labelled vertical list of icon + verb rows, with `visible` folding the tail behind a Show N more toggle. Both are context-free: each item's onClick is yours, typically writing the full prompt into the composer.

### How do @-mentions work, and is the list accessible?

Wrap the PromptInputTextarea and a PromptInputMentionList in PromptInputMentions. Typing @ at the start of a word opens a listbox anchored to the caret; filter it from `onQueryChange` and picking a row writes `@Name ` into the composer and fires `onMentionSelect`. Focus stays in the textarea, which names the highlighted option with aria-activedescendant; arrow keys move, Enter and Tab pick, and Escape closes only the list.

### How does the textarea grow in engines without field-sizing?

PromptInputTextarea grows with CSS `field-sizing: content` where the browser has it, and with a small JS fallback elsewhere (Chromium 103 and other older engines). The fallback measures the field by collapsing it for one layout pass, and it holds the composer's height while it does, so the layout around it never moves: a Conversation above the composer keeps its scroll position on every keystroke, even when its thread nearly fits.

### 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Installation

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

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

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

Pro: `suggestions` comes with a [Koala UI Pro license](https://www.koalaui.com/pro). Its source is not published in these docs.

## Usage

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

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.

## Anatomy

```tsx
import { Suggestions, SuggestionMark } from "@/components/ui/suggestions"

<Suggestions>
  ...
  <SuggestionMark suggestion="...">...</SuggestionMark>
  ...
</Suggestions>
```

## 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`.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## API reference

### Suggestions

The prose container and context for the marks. Forwards all native `<div>` props; every part accepts `className`, merged last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| onApply | (suggestion: string, original: string) => void | - | Fires when any mark is applied, with the replacement and the original text. |
| onDismiss | (original: string) => void | - | Fires when any mark is dismissed, with the original text. |

### SuggestionMark

One improvable span: a Radix Popover `Trigger` button whose children are the original text. Forwards all native `<button>` props except `onSelect`. Once applied or dismissed it collapses to plain text.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| suggestion* | string | - | The replacement text swapped in for the children on Apply. |
| variant | "default" \| "grammar" \| "clarity" \| "tone" | "default" | Category: tints the dotted underline, the hover wash and the popover badge. |
| label | string | - | Badge text in the popover header. Defaults to the category name (`Suggestion`, `Grammar`, `Clarity` or `Tone`). |
| reason | string | - | One-line explanation shown beneath the diff. |
| onApply | (suggestion: string) => void | - | Per-mark apply hook. The root's `onApply` fires too. |
| onDismiss | () => void | - | Per-mark dismiss hook. The root's `onDismiss` fires too. |

| Data attribute | Description |
| --- | --- |
| data-state | `open` or `closed`, on the mark while it is pending, following its popover. |
| data-status | `applied` or `dismissed`, on the plain span the mark resolves to (`data-slot="suggestion-resolved"`). |
| data-settled | `true` or `false`, on the applied-edit morph while it plays; flips to `true` once the start state has painted. |
| data-variant | The category, on the applied-edit morph. |

## 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 category's name (`Suggestion` for the neutral `default`). 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/tool.md -->

# Tool

One call an agent makes to a tool: what it called, with which arguments, what came back, and the approval step when a person has to say yes. Collapsed, a call is one quiet line; open, the arguments and the result sit on sheets set into the frame.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Installation

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

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

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

Pro: `tool` comes with a [Koala UI Pro license](https://www.koalaui.com/pro). Its source is not published in these docs.

## Usage

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Anatomy

Three blocks. A header line that is also the disclosure: the status column, the name, a summary of the arguments and a meta read-out. The content it opens: an input sheet and an output sheet. And an approval row that exists only while the call is waiting for a person.

```tsx
import {
  Tool,
  ToolHeader,
  ToolIcon,
  ToolName,
  ToolSummary,
  ToolStatus,
  ToolMeta,
  ToolContent,
  ToolInput,
  ToolOutput,
  ToolApproval,
  ToolApprovalMessage,
  ToolApprovalActions,
} from "@/components/ui/tool"

<Tool>
  <ToolHeader>
    <ToolIcon />
    <ToolName />
    <ToolSummary />
    <ToolStatus />
    <ToolMeta />
  </ToolHeader>
  <ToolContent>
    <ToolInput />
    <ToolOutput />
  </ToolContent>
  <ToolApproval>
    <ToolApprovalMessage />
    <ToolApprovalActions />
  </ToolApproval>
</Tool>
```

## States

Six states, one per stage an agent SDK reports. They live in the 16px column at the head of the line: the tool's own glyph at rest (at half strength while the model is still writing the arguments), a spinner while it runs, a warning when it threw, a prohibit sign when someone turned it down. While pending or running, the name carries the same ink sweep as Chat's “Thinking…”. A finished call gets no green tick: a column of checks says nothing a finished line doesn't.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Status chip

`ToolStatus` is an optional Badge worded and toned from the root's status, so a label and a state can never drift apart. Leave it out in a chat, where the status column already says it; reach for it in an audit log or an activity feed, where each call has to announce itself.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Input and output

Pass the arguments and the result as they come from your SDK. An object is pretty-printed and highlighted as JSON, with copy on hover; a string is shown as plain text, so a shell's stdout keeps its own layout. A long JSON result clamps at 200px behind a Show more, so a 400-line response never unrolls at whoever opens the call.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Errors

Mark the call `error` and the output sheet reads its value as the message: labelled “Error”, in the destructive ink, wrapped rather than scrolled sideways, and announced as an alert. Nothing else on the card turns red; the warning in the status column is enough to find it in a list.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Approval

A call that needs a person mounts open, so you never have to expand a card to learn what you are being asked to allow, and `ToolApproval` sits outside the collapsible content, so the decision can't be folded away. It renders nothing in any other status: leave it in the markup and let the status decide. The pair is the house rule, ghost on the left and primary on the right.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Editing the arguments

`ToolInput editable` turns the same sheet into an editor: no new field, no frame, the same mono type, so nothing moves until you type. Pass the raw text back as `value`, validate it yourself and set `invalid` while it does not parse; this demo holds Send back until the JSON is valid again.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## In a chat

Inside a Chat turn or an AI Panel, use `variant="plain"`. It drops the frame, so the calls read as a few quiet lines of the answer rather than as cards inside a card, and the sheets indent to the name's axis when opened.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Density

Like Card and Plan, Tool reads the density context (or a `density` prop). It tunes the header band (44px or 40px) and the sheets' padding; the labels move with the code so “Input” always starts on the listing's left edge. The 8px gutter between frame and sheet is fixed in both, because it is what keeps the sheet's corner concentric with the frame's.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## API reference

### Tool

The call, and the context every part reads. A Radix `Collapsible.Root`, so it forwards its props. Every part accepts `className`, merged last, and every part but the header is droppable.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| status | "pending" \| "approval" \| "running" \| "done" \| "error" \| "rejected" | "done" | Where the call is. Drives the status column, the name's sweep, `ToolOutput`, `ToolApproval`, `ToolStatus` and `aria-busy` (pending or running). |
| variant | "card" \| "plain" | "card" | `card` is the tinted frame with the sheets set into it; `plain` drops the frame for a Chat turn or an AI Panel. |
| density | "comfortable" \| "compact" | - | Header band height and sheet padding. Inherits the nearest `DensityProvider` (compact with none). |
| open | boolean | - | Controlled open state of the arguments and result. |
| defaultOpen | boolean | - | Initial open state. Collapsed by default, except a call that mounts in `approval`. |
| onOpenChange | (open: boolean) => void | - | Called when the call opens or closes. |

| Data attribute | Description |
| --- | --- |
| data-status | The call's `status`. |
| data-state | `open` or `closed`. |

### ToolHeader

The line you see collapsed, and the disclosure trigger. Adds the caret and an sr-only status word. Forwards Radix `Collapsible.Trigger` props.

### ToolIcon

The 16px status column. Pass the tool's glyph; it cross-fades to a spinner while running, a warning on `error`, a prohibit sign on `rejected`. `aria-hidden`. Renders a `<span>`.

### ToolName

What was called. The line's one piece of ink; sweeps while pending or running. Renders a `<span>`.

### ToolSummary

The arguments in a few words. Muted, and the first thing to truncate. Renders a `<span>`.

### ToolMeta

Trailing read-out (duration, a count) in `tabular-nums`. Renders a `<span>`.

### ToolStatus

An optional chip worded and toned from the root's `status`. Forwards `Badge` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| variant | BadgeProps["variant"] | - | Overrides the tone the status picks. |
| children | React.ReactNode | - | Overrides the wording (`Running`, `Needs approval`, and so on). |

### ToolContent

What the header hides: the input and output sheets. Tweens its height. Forwards Radix `Collapsible.Content` props.

### ToolInput

The arguments, on their own sheet. Forwards native `<div>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| value | unknown | - | An object is pretty-printed and highlighted as JSON; a string is shown as plain text. |
| label | React.ReactNode | "Input" | The sheet's label. |
| editable | boolean | false | Turns the listing into an inline editor in the same mono type. |
| onValueChange | (value: string) => void | - | Called with the raw text on every edit. |
| invalid | boolean | false | Rings the sheet in the destructive tone and sets `aria-invalid`. |
| children | React.ReactNode | - | Your own content instead of the listing; the sheet and label stay. |

| Data attribute | Description |
| --- | --- |
| data-invalid | Present when `invalid`. |

### ToolOutput

What came back. Renders nothing while the call is `pending`, `approval` or `running`. Forwards native `<div>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| value | unknown | - | The result: JSON for an object, plain text for a string, the message for an error. |
| label | React.ReactNode | "Output" | The sheet's label; `Error` when the call failed. |
| error | boolean | - | Show `value` as an error. Defaults to `status === "error"`. |
| collapsible | boolean | true | Clamp a long JSON result behind CodeSnippet's Show more. |
| collapsedHeight | number | 200 | The clamp, in px. |
| children | React.ReactNode | - | Your own rendering of the result; the sheet and label stay. |

| Data attribute | Description |
| --- | --- |
| data-error | Present when the output is an error. |

### ToolApproval

The human-in-the-loop row. Renders nothing unless `status` is `approval`, and sits outside `ToolContent` so it can never be folded away. A `role="group"` `<div>`.

### ToolApprovalMessage

What the person is allowing. `<strong>` steps a name up to full ink. Forwards native `<p>` props.

### ToolApprovalActions

The decision: a ghost Reject, then the primary Approve. Forwards native `<div>` props.

## FAQ

### How do the states map to the Vercel AI SDK?

One to one: input-streaming is pending, approval-requested is approval, input-available is running, output-available is done, output-error is error and output-denied is rejected. Map the part's state once and pass it as status; ToolOutput and ToolApproval take care of when they appear.

### Why is a call collapsed by default?

Because nine times out of ten a call is evidence the agent did the work, not the work itself. A turn with six calls should read as six quiet lines above the answer. The one exception is a call waiting for approval: it mounts open, so you always see what you are allowing.

### Why no green check on a finished call?

A column of green ticks says nothing a finished line doesn't, and it competes with the answer underneath. A finished call keeps its tool's own glyph, which tells you which tool ran. Color is reserved for the two states that need your attention: a failure and a pending approval.

### Can I render the result my own way?

Yes. Pass children to ToolOutput (or ToolInput) instead of value: a list of search results, a table, an image. The sheet and its label stay, so a custom result still sits in the same frame as every other call.

### Is it accessible?

The header is a Radix Collapsible trigger, so it gets aria-expanded and the keyboard wiring for free, and its accessible name includes the status in words. The status column itself is aria-hidden decoration. The root sets aria-busy while the call is pending or running, a failed output is announced as an alert, and an editable input is labelled by its sheet label and marked aria-invalid when it does not parse.

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

Yes. The frame mixes the muted token into the ground (opaque, so a call floating over content never shows through), the sheets take the ground itself, and every ink is a semantic token, so it re-themes across light, dark, cream and moonlight.

---

<!-- 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Installation

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

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

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

Pro: `auth-form` comes with a [Koala UI Pro license](https://www.koalaui.com/pro). Its source is not published in these docs.

## Usage

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

### 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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

The sign-in block: provider row, email, password, "Remember me" and a forgot-password link. Forwards native `<div>` props (except `title` and `onSubmit`) and accepts `className`, merged last, like the other two blocks.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| title | React.ReactNode | "Welcome back" | The heading of the block. |
| description | React.ReactNode | "Sign in to your account to continue." | The line under the heading. |
| onSubmit | (data: LoginFormData) => void \| Promise<void> | - | Called with `{ email, password, remember }`. Return a promise and the submit button shows a spinner until it settles. |
| onProvider | (provider: "google" \| "github" \| "apple" \| "discord") => void | - | Called with the provider id when a provider button is pressed. |
| showSocial | boolean | true | Shows the provider row and the divider above the email form. |
| providers | ("google" \| "github" \| "apple" \| "discord")[] | ["google", "github", "apple"] | The provider row, left to right. |
| forgotHref | string | "#" | Target of the "Forgot password?" link. |
| signUpHref | string | "#" | Target of the "Sign up" cross-link. |
| variant | "card" \| "bare" | "card" | `card` is the standalone ring-edged block; `bare` drops the edge, shadow, max-width and padding to sit in a page shell. |
| density | "comfortable" \| "compact" | "compact" | Outer gap, title size and card padding (16px or 24px). Falls back to the nearest `DensityProvider`. |
| labels | Partial<AuthFormLabels> | - | The strings of the block, for a translation. Pass only the keys you change; provider phrases take a `{provider}` placeholder. |

### SignUpForm

The sign-up block: adds a full-name field, a live password-strength meter and a terms checkbox that gates the submit button.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| title | React.ReactNode | "Create your account" | The heading of the block. |
| description | React.ReactNode | "Start your free trial. No credit card required." | The line under the heading. |
| onSubmit | (data: SignUpFormData) => void \| Promise<void> | - | Called with `{ name, email, password, acceptedTerms }`. Return a promise to drive the spinner. |
| onProvider | (provider: "google" \| "github" \| "apple" \| "discord") => void | - | Called with the provider id when a provider button is pressed. |
| showSocial | boolean | true | Shows the provider row and the divider above the email form. |
| providers | ("google" \| "github" \| "apple" \| "discord")[] | ["google", "github", "apple"] | The provider row, left to right. |
| signInHref | string | "#" | Target of the "Sign in" cross-link. |
| termsHref | string | "#" | Target of the Terms link in the consent sentence. |
| privacyHref | string | "#" | Target of the Privacy Policy link in the consent sentence. |
| termsLabel | React.ReactNode | - | Replaces the consent sentence whole, for a translation that moves words around the links. |
| variant | "card" \| "bare" | "card" | `card` is the standalone ring-edged block; `bare` drops the edge, shadow, max-width and padding to sit in a page shell. |
| density | "comfortable" \| "compact" | "compact" | Outer gap, title size and card padding (16px or 24px). Falls back to the nearest `DensityProvider`. |
| labels | Partial<AuthFormLabels> | - | The strings of the block, for a translation. Pass only the keys you change; provider phrases take a `{provider}` placeholder. |

### ProviderForm

The password-less, provider-first block: a stack of full-width "Continue with" buttons, with an optional magic-link email, footer and social rail.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| title | React.ReactNode | "Welcome" | The heading of the block. |
| description | React.ReactNode | "Sign in or create your account to continue." | The line under the heading. |
| providers | ("google" \| "github" \| "apple" \| "discord")[] | ["google", "github", "apple"] | The provider buttons, top to bottom. |
| onProvider | (provider: "google" \| "github" \| "apple" \| "discord") => void | - | Called with the provider id when a provider button is pressed. |
| emphasizeFirst | boolean | false | Renders the first provider as the solid primary button, for a single dominant choice. |
| action | "continue" \| "sign-in" | "continue" | The verb on each button: "Continue with Google" or "Sign in with Google". |
| requireTerms | boolean | false | Gates every action behind a consent checkbox the user must tick first. |
| termsLabel | React.ReactNode | - | The consent copy: the checkbox label with `requireTerms`, otherwise a static line under the buttons (`null` hides it). |
| termsHref | string | "#" | Target of the Terms link in the default consent copy. |
| privacyHref | string | "#" | Target of the Privacy Policy link in the default consent copy. |
| showEmail | boolean | false | Adds a magic-link email field under a divider. |
| emailAction | React.ReactNode | "Continue with email" | The label of the email submit button. |
| onSubmit | (email: string) => void \| Promise<void> | - | Called with the email. Return a promise to drive the spinner. |
| footer | React.ReactNode | - | A cross-link line under the actions, e.g. "Don't have an account? Sign up". |
| social | { network: SocialNetwork; href: string; label?: string }[] | - | A community link rail at the very bottom. `network` is `"x"`, `"discord"`, `"youtube"`, `"instagram"`, `"github"` or `"linkedin"`. |
| variant | "card" \| "bare" | "card" | `card` is the standalone ring-edged block; `bare` drops the edge, shadow, max-width and padding to sit in a page shell. |
| density | "comfortable" \| "compact" | "compact" | Outer gap, title size and card padding (16px or 24px). Falls back to the nearest `DensityProvider`. |
| labels | Partial<AuthFormLabels> | - | The strings of the block, for a translation. Pass only the keys you change; provider phrases take a `{provider}` placeholder. |

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Installation

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

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

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

Pro: `contact-form` comes with a [Koala UI Pro license](https://www.koalaui.com/pro). Its source is not published in these docs.

## Usage

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## API reference

### ContactForm

The general get-in-touch block: name and email, a subject Select and a message with a live count. Owns its state and swaps to a `role="status"` success panel after submit; forwards native `<div>` props except `onSubmit` and `title`, and every block accepts `className`, merged last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| title | React.ReactNode | "Get in touch" | Heading above the form; `null` drops it. |
| description | React.ReactNode | - | Supporting line under the heading; `null` drops it. |
| action | React.ReactNode | "Send message" | Submit button label. |
| variant | "card" \| "bare" | "card" | `card` is the standalone ring-edged block; `bare` drops the edge, shadow, max-width and padding to embed in a page shell. |
| density | "comfortable" \| "compact" | "compact" | Padding 24px or 16px, with fields and submit at 36px or 32px. Falls back to the nearest `DensityProvider`. |
| onSubmit | (data: ContactFormData) => void \| Promise<void> | - | Called with `{ name, email, subject, message }` on a valid submit; return a promise to show the loading state until it resolves. |

### LeadForm

The sales and collaboration lead block: first name and LinkedIn, email, a company-size Select, a country-aware PhoneInput and a message. Same surface, states and native `<div>` passthrough as `ContactForm`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| title | React.ReactNode | "Let's collaborate" | Heading above the form; `null` drops it. |
| description | React.ReactNode | - | Supporting line under the heading; `null` drops it. |
| action | React.ReactNode | "Send message" | Submit button label. |
| variant | "card" \| "bare" | "card" | `card` is the standalone ring-edged block; `bare` drops the edge, shadow, max-width and padding to embed in a page shell. |
| density | "comfortable" \| "compact" | "compact" | Padding 24px or 16px, with fields and submit at 36px or 32px. Falls back to the nearest `DensityProvider`. |
| defaultCountry | string | "US" | Initial ISO2 country for the phone field. |
| onSubmit | (data: LeadFormData) => void \| Promise<void> | - | Called with `{ firstName, linkedin, email, companySize, phone, message }` on a valid submit; return a promise to show the loading state. |

### SupportForm

The help-desk request: name and email, a support-topic Select, an optional order or reference field and a message. Same surface, states and native `<div>` passthrough as `ContactForm`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| title | React.ReactNode | "How can we help?" | Heading above the form; `null` drops it. |
| description | React.ReactNode | - | Supporting line under the heading; `null` drops it. |
| action | React.ReactNode | "Submit request" | Submit button label. |
| variant | "card" \| "bare" | "card" | `card` is the standalone ring-edged block; `bare` drops the edge, shadow, max-width and padding to embed in a page shell. |
| density | "comfortable" \| "compact" | "compact" | Padding 24px or 16px, with fields and submit at 36px or 32px. Falls back to the nearest `DensityProvider`. |
| onSubmit | (data: SupportFormData) => void \| Promise<void> | - | Called with `{ name, email, topic, reference, message }` on a valid submit; return a promise to show the loading state. |

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Installation

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

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

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

Pro: `feedback-form` comes with a [Koala UI Pro license](https://www.koalaui.com/pro). Its source is not published in these docs.

## Usage

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## API reference

### FeedbackForm

One card that composes a single-select Toggle Group of five faces and a Textarea, and owns the rating and message state. Forwards all native `<div>` props; accepts `className`, merged last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| onSubmit | (data: FeedbackFormData) => void \| Promise<void> | - | Called with `{ rating, message }`, where `rating` is `"1"` to `"5"`. Return a promise and the submit button spins until it resolves, then the card shows its success state. |
| title | React.ReactNode | "How was your experience?" | The card heading; `null` hides it. |
| description | React.ReactNode | "Your feedback helps us make the product better for everyone." | Muted copy under the title; `null` hides it. |
| action | React.ReactNode | "Send feedback" | The submit button label. |
| density | "comfortable" \| "compact" | "compact" | Card padding and gap (24px or 16px), title size and control height (36px or 32px). Falls back to the nearest `DensityProvider`. |

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Installation

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

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

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

Pro: `newsletter-form` comes with a [Koala UI Pro license](https://www.koalaui.com/pro). Its source is not published in these docs.

## Usage

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## API reference

### NewsletterForm

A self-contained signup built from Input and Button: it owns the email state, validates the address and runs the loading then success flow. Forwards native `<div>` props; accepts `className`, merged last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| variant | "card" \| "inline" | "card" | `card` adds a heading, lead and fine print; `inline` is the single row, for a Footer or a hero. |
| density | "comfortable" \| "compact" | - | Card padding, gap and title size (16 or 24px). Inherits the nearest `DensityProvider` (compact with none). |
| onSubscribe | (email: string) => void \| Promise<void> | - | Called with the email on a valid submit. Return a promise to keep the spinner up until it resolves. |
| title | React.ReactNode | "Subscribe to our newsletter" | The card's heading. |
| description | React.ReactNode | "Product updates, design tips…" | The card's lead. `null` hides it. |
| placeholder | string | "you@company.com" | The email field's placeholder. |
| action | React.ReactNode | "Subscribe" | The submit button's label. |
| fineprint | React.ReactNode | "We care about your data…" | Small print under the card's form. `null` hides it. |

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Installation

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

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

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

Pro: `payment-form` comes with a [Koala UI Pro license](https://www.koalaui.com/pro). Its source is not published in these docs.

## Usage

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## API reference

### PaymentForm

A card checkout built from Field, Input and CountrySelect. Masking and brand detection are presentation only: never store an unmasked card number. Forwards native `<div>` props; accepts `className`, merged last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| onSubmit | (data: PaymentFormData) => void \| Promise<void> | - | Called with `{ cardNumber, expiry, cvc, name, country, promoCode? }`, masked as shown. Return a promise to hold the spinner until it settles. |
| amount | string | - | The display total, e.g. `"$49.00"`. Shows the summary row and labels the Pay button. |
| promoCodes | Record<string, PaymentPromoCode> | - | Accepted codes, matched case-insensitively, each `{ percentOff?, amountOff?, label? }`. Reveals the promo row; needs a parseable `amount`. |
| promoHint | React.ReactNode | - | A caption under the promo field, e.g. `"Try KOALA20"`. |
| defaultCountry | string | "US" | The billing country preselected, as ISO2. |
| title | React.ReactNode | "Payment details" | The heading above the form. |
| description | React.ReactNode | "Enter your card to complete…" | The line under the heading. |
| density | "comfortable" \| "compact" | - | Spacing, 24 or 16px. Inherits the nearest `DensityProvider` (compact with none). |

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Installation

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

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

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

Pro: `settings-form` comes with a [Koala UI Pro license](https://www.koalaui.com/pro). Its source is not published in these docs.

## Usage

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## API reference

### SettingsForm

A `<form>` card composing Avatar, Field, Input and Textarea; it owns the field state and the saved confirmation. Forwards all native `<form>` props except `onSubmit`, and accepts `className`, merged last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| defaultValues | Partial<SettingsFormData> | - | Initial `firstName`, `lastName`, `username`, `email` and `bio`; missing keys start empty. |
| onSave | (data: SettingsFormData) => void \| Promise<void> | - | Called with the full form data on submit. Return a promise to keep Save loading until it settles. |
| onCancel | () => void | - | Called when Cancel is pressed. |
| onPhotoChange | (file: File) => void | - | Called with the file picked through Change photo; the avatar previews it at once. Upload it and pass the stored URL back as `avatarSrc`. Without it, Change photo is hidden. |
| onPhotoRemove | () => void | - | Called when Remove is pressed; the avatar falls back to initials. Without it, or with no photo showing, Remove is hidden. |
| photoAccept | string | "image/jpeg,image/gif,image/png" | File types the photo picker accepts (the native `accept` attribute). |
| avatarSrc | string | - | Current avatar image; without it the avatar shows the name's initials. |
| usernamePrefix | string | "koalaui.com/" | Static prefix shown before the username input. |
| title | React.ReactNode | "Profile" | Header title. Set it and `description` to `null` to drop the header. |
| description | React.ReactNode | "This information will be displayed publicly on your profile." | Header text under the title. |
| density | "compact" \| "comfortable" | "compact" | Spacing axis: `compact` pads 16px with `sm` controls, `comfortable` pads 24px with `md` controls. Falls back to the nearest `DensityProvider`. |

## 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. Change photo and Remove appear when you pass `onPhotoChange` and `onPhotoRemove`: the first opens a file picker and hands you the `File`, the second clears the avatar to initials. A picked file previews immediately, and a new `avatarSrc` (your uploaded URL) takes over again.

### 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Installation

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

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

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

Pro: `survey` comes with a [Koala UI Pro license](https://www.koalaui.com/pro). Its source is not published in these docs.

## Usage

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Anatomy

```tsx
import {
  SurveyQuestion,
  SurveyHeader,
  SurveyEyebrow,
  SurveyTitle,
  SurveyDescription,
  SurveyOptions,
  SurveyOption,
} from "@/components/ui/survey"

<SurveyQuestion>
  <SurveyHeader>
    <SurveyEyebrow />
    <SurveyTitle />
    <SurveyDescription />
  </SurveyHeader>
  <SurveyOptions>
    <SurveyOption value="…" />
  </SurveyOptions>
  {/* or one answer part: SurveyShortAnswer, SurveyParagraph,
      SurveyDropdown, SurveyScale, SurveyRating */}
</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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Linear scale

`SurveyScale` is a 1-to-N rating row built on `RadioGroup`. Set `min`/`max` and optional `minLabel`/`maxLabel` captions for the ends.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Rating

`SurveyRating` composes the DS `Rating` for a star score, labelled by the question title. It forwards every `Rating` prop: `max`, `size`, `icon`, `readOnly`.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Description & disabled options

Add a `SurveyDescription` under the title for context, and disable any single `SurveyOption`: keyboard navigation skips it and its row dims.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Density

`density="compact"` tightens the card padding, gaps, and row height for embedded, information-dense forms; radius and color never change. Without the prop it follows the nearest `DensityProvider`, and `compact` when there is none.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Controlled

Pass `value` and `onValueChange` to own the selection. For a `multiple` group the value is a `string[]`.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## API reference

### SurveyQuestion

One standalone question card; there is no Survey root. Forwards all native `<div>` props; every part accepts `className`, merged last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| required | boolean | false | Adds a destructive asterisk and an sr-only "(required)" to the title. |
| density | "comfortable" \| "compact" | "compact" | Card padding, gaps and row height. Falls back to the nearest `DensityProvider`; set explicitly, it also sizes the card's text controls (`sm` or `md`). |

| Data attribute | Description |
| --- | --- |
| data-control-size | `"sm"` or `"md"`, set only when `density` is passed. |

### SurveyHeader

Groups the eyebrow, title and description with a tight gap. Forwards all native `<div>` props.

### SurveyEyebrow

The small muted label above the question ("Question 1"). Forwards all native `<p>` props.

### SurveyTitle

The question, an `<h3>` whose id labels the answer part. Forwards all native `<h3>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| required | boolean | - | Overrides the required state inherited from `SurveyQuestion`. |

### SurveyDescription

Muted supporting copy under the title. Forwards all native `<p>` props.

### SurveyOptions

The choice list: a `RadioGroup` for a single choice, or a `<fieldset>` of Checkboxes with `multiple`. One highlight glides to the row under the cursor. Forwards native props (`id`, `style`, `aria-*`, `data-*`, handlers) to that root.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| multiple | boolean | false | Checkboxes reporting a `string[]` instead of radios reporting a `string`. |
| value | string \| string[] | - | The selection, when controlled: `string[]` with `multiple`. |
| defaultValue | string \| string[] | - | The initial selection, when uncontrolled. |
| onValueChange | (value: string \| string[]) => void | - | Called with the new selection: a `string`, or a `string[]` with `multiple`. |
| disabled | boolean | false | Disables every option in the group. |
| name | string | - | Form field name. Single choice posts one `name=value`; `multiple` posts one `name=value` per checked option, read with `formData.getAll(name)`. |

| Data attribute | Description |
| --- | --- |
| data-multiple | Present when the group is multiple choice. |

### SurveyOption

One row: a `<label>` around the radio or checkbox, so the whole row is the hit target. Forwards all native `<label>` props except `onChange`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| value* | string | - | The value this option contributes to the selection. |
| disabled | boolean | false | Dims the row and keeps the highlight off it. |

### SurveyShortAnswer

A one-line answer, the DS Input labelled by the title. Forwards all `InputField` props (`className` goes to the field).

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| rootClassName | string | - | Classes for the bordered Input container. |

### SurveyParagraph

A long answer, the DS Textarea labelled by the title; grows with its text (`autoResize={false}` to stop it). Forwards all `TextareaField` props, such as `showCount` and `maxLength`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| rootClassName | string | - | Classes for the bordered Textarea container. |

### SurveyDropdown

A single choice as the DS Select, for long option lists. Its trigger is labelled by the title.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| options* | { value: string; label: string }[] | - | The choices, in display order. |
| placeholder | string | "Select an answer…" | Shown before a choice is made. |
| value | string | - | The selection, when controlled. |
| defaultValue | string | - | The initial selection, when uncontrolled. |
| onValueChange | (value: string) => void | - | Called with the chosen value. |
| disabled | boolean | false | Disables the dropdown. |
| name | string | - | Form field name. |
| className | string | - | Classes for the Select trigger. |

### SurveyScale

A 1-to-N linear scale on a `RadioGroup`, with optional end captions. Forwards native `<div>` props to its root.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| min | number | 1 | First value on the scale. |
| max | number | 5 | Last value on the scale. |
| minLabel | string | - | Caption under the lowest point, e.g. "Strongly disagree". |
| maxLabel | string | - | Caption under the highest point, e.g. "Strongly agree". |
| value | string | - | The chosen point as a string, when controlled. |
| defaultValue | string | - | The initial point, when uncontrolled. |
| onValueChange | (value: string) => void | - | Called with the chosen point. |
| disabled | boolean | false | Disables every point. |
| name | string | - | Form field name. Point ids come from `useId`, so any number of scales, named or not, can share a page. |

### SurveyRating

A star score, the DS `Rating` labelled by the title. Forwards every `Rating` prop (`max`, `size`, `icon`, `readOnly`, …).

### surveyVariants

The `tv` recipe behind every part, for styling a question of your own to match.

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Installation

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

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

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

Pro: `waitlist-form` comes with a [Koala UI Pro license](https://www.koalaui.com/pro). Its source is not published in these docs.

## Usage

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## API reference

### WaitlistForm

The whole block: badge, headline, a one-row email capture (Input and Button) and an Avatar proof stack. It owns its email and status, validates the address on submit and flips to a confirmed state. Forwards all native `<div>` props; `className` is merged last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| onJoin | (email: string) => void \| Promise<void> | - | Called with the entered email on a valid submit. Return a promise to drive the button spinner. |
| count | number | 1200 | People already on the list, shown beside the avatars as `1,200+` with `tabular-nums`. `0` hides the proof row. |
| avatars | WaitlistAvatar[] | 4 initials | The proof stack, each `{ src?, fallback, alt? }`. |
| badge | ReactNode | "Early access" | Pill above the headline. Pass `null` to hide it. |
| title | ReactNode | "Join the waitlist" | The headline, rendered as an `<h3>`. Pass `null` to hide it. |
| description | ReactNode | an invite note | Supporting line under the headline. Pass `null` to hide it. |
| placeholder | string | "you@company.com" | Placeholder of the email field. |
| action | ReactNode | "Join" | Label of the join button, followed by an arrow icon. |
| density | "compact" \| "comfortable" | "compact" | Padding, gap and title size: `compact` is 16px, `comfortable` 24px. Falls back to the nearest `DensityProvider`. |

## 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

One inline `<span>` whose layers are managed for you. Forwards all native `<span>` props; `className` (merged last) styles the label as a whole, so put a per-label color on a span inside the children instead.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| swapKey* | React.Key | - | Identifies the label on screen. Change it in step with the children and the two roll past each other. |
| align | "start" \| "center" \| "end" | "center" | The edge the label holds while the box eases between widths. Left-aligned copy wants `start`. |
| children | React.ReactNode | - | The label currently on screen. |

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Installation

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

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

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

Pro: `animated-number` comes with a [Koala UI Pro license](https://www.koalaui.com/pro). Its source is not published in these docs.

## Usage

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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

One inline, `tabular-nums` `<span>` whose per-character cells are managed for you. Forwards all native `<span>` props; accepts `className`, merged last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| value* | React.ReactNode | - | The figure to show, usually a formatted string. A change rolls the changed characters, paired from the right; an element rolls as one block. |

| Data attribute | Description |
| --- | --- |
| data-digit | On each character cell: `true` for a digit, `false` for a separator or symbol, which keeps its natural width. |

| CSS variable | Description |
| --- | --- |
| --number-roll-stagger | The delay between two rolling characters (a global token, `45ms`). The component only supplies a multiplier per cell. |

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Installation

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

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

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

Pro: `chart` comes with a [Koala UI Pro license](https://www.koalaui.com/pro). Its source is not published in these docs.

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Anatomy

```tsx
import {
  Chart,
  ChartLegend,
  ChartGrid,
  ChartXAxis,
  ChartYAxis,
  ChartArea,
  ChartLine,
  ChartReferenceLine,
  ChartAnnotation,
  ChartTooltip,
} from "@/components/ui/chart"

<Chart>
  <ChartLegend />
  <ChartGrid />
  <ChartXAxis />
  <ChartYAxis />
  <ChartArea />
  <ChartLine />
  {/* or ChartBar, ChartBars, ChartAreas, ChartFunnel, ChartPie */}
  <ChartReferenceLine />
  <ChartAnnotation />
  <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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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 full ink. Hovering a column also lifts its x-axis tick to the foreground.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Highlight & active bar

`highlight` on `ChartBar` paints chosen bars in `highlightColor` (`primary`, full ink, 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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 translucent band under 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

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`.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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`.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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).

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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`.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

`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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## API reference

### Chart

The root: measures itself, builds the scales and shares them with every part, which draw into one SVG. Renders a visually hidden data table for screen readers. Forwards all native `<div>` props, `ref` included. Every part accepts `className`, merged last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| data* | ChartDatum[] \| number[] | - | A row per category, or a bare `number[]` for a single `value` series. `null` marks a missing point. |
| index | string | - | The key holding each row's category label, for the x-axis and tooltip heading. |
| config | Record<string, ChartSeriesConfig> | - | Per series: `label`, `color`, `format`, `axis` (`"left" \| "right"`), `compare` (the key it is measured against) and `inverted` (down is good). A `ChartColor` is a semantic hue (`blue`, `teal`, `purple`, `brand`, `gray`, a status role, `blue-200` to `blue-800`) or `current`. |
| domain | "auto" \| "fit" \| [number, number] | "auto" | `auto` runs from zero to a nice top; `fit` wraps the data's own extent; a pair fixes it. |
| sparkline | boolean | false | Chromeless: zero padding, points across the full width, painted in `currentColor`. |
| stack | boolean | false | Stacks `ChartBars` and `ChartAreas`, and sizes the domain to the category total. |
| palette | "categorical" \| "tonal" | "categorical" ("tonal" with stack) | How series without a `color` are painted: distinct hues, or shades of one blue. |
| padding | Partial<{ top: number; right: number; bottom: number; left: number }> | - | The plot insets, in px. Raise `bottom` and `left` to make room for axes. |
| animate | boolean | true | The one-shot load reveal. Held under reduced motion. |
| crosshair | boolean | true (false for sparklines) | The hover tracking line, painted behind the data. |
| activeIndex | number \| null | - | The hovered category, controlled. |
| onActiveIndexChange | (index: number \| null) => void | - | Called as the pointer crosses categories, and with `null` when it leaves. |
| hiddenSeries | string[] | - | The series switched off, controlled. They leave the scale, stacks and tooltip. |
| defaultHiddenSeries | string[] | - | The series switched off at first, uncontrolled. |
| onHiddenSeriesChange | (keys: string[]) => void | - | Called when a series is shown or hidden. |
| focusedSeries | string \| null | - | The series in focus, controlled; the rest recede. |
| onFocusedSeriesChange | (key: string \| null) => void | - | Called when the focused series changes. |
| partial | boolean \| number | - | Trailing categories still in progress (`true` is the last): lines dash, areas fade, bars hatch. |
| loading | boolean | false | A Skeleton in place of the plot, with `aria-busy`. |
| empty | React.ReactNode | "No data" | Shown when `data` is empty. |
| label | string | - | The accessible name; it also captions the hidden data table. Strongly recommended. |

### ChartLine

A line series. Forwards SVG `<path>` props except `d`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| dataKey | string | "value" | The series to plot. |
| color | ChartColor | - | Overrides the hue from `config`. |
| curve | "linear" \| "monotone" | "linear" | Straight segments, or a smooth curve that never overshoots. Match the area under it. |
| connectNulls | boolean | false | Bridges missing points instead of breaking the line. |
| dashed | boolean | false | A dashed line for projected data; skips the draw-in. |
| markEnd | boolean | false | A filled dot on the last point. |
| variant | "default" \| "comparison" | - | `comparison` is the faint dashed ghost of a previous period, the default for a series another one `compare`s against. |
| hideActiveDot | boolean | false | Hides the dot on the hovered point. |
| strokeWidth | number | - | The stroke width. |

### ChartArea

An area series fading down from its edge; pair it with a `ChartLine` on top. Forwards SVG `<path>` props except `d`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| dataKey | string | "value" | The series to fill. |
| color | ChartColor | - | Overrides the hue from `config`. |
| curve | "linear" \| "monotone" | "linear" | How the top edge joins its points. |
| connectNulls | boolean | false | Bridges missing points instead of leaving a hole. |

### ChartAreas

Several area series at once, stacked into bands with `stack` on the root, each with its own edge line. Forwards SVG `<g>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| keys | string[] | - | The series to draw, bottom of the stack first. Defaults to every series. |
| curve | "linear" \| "monotone" | "linear" | How every band's edges join their points. |
| connectNulls | boolean | false | Bridges missing points instead of leaving a hole. |

### ChartBar

A single bar series. Forwards SVG `<path>` props except `d`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| dataKey | string | "value" | The series to draw. |
| color | ChartColor | - | Overrides the hue from `config`. |
| barRatio | number | 0.62 | Bar width as a fraction of the category band. |
| radius | number | 8 | Corner radius at the value end, in px. |
| label | (value: number, index: number) => React.ReactNode | - | A value label past each bar's end. Give the Chart about 24px of `padding.top`. |
| highlight | number \| number[] \| "active" \| ((datum, index, active) => boolean) | - | Bars painted in `highlightColor`: an index, a list, the hovered bar, or a predicate. |
| highlightColor | ChartColor | "primary" | The hue of a highlighted bar. |

### ChartBars

Several bar series sharing each band: grouped, or stacked with `stack` on the root. Forwards SVG `<path>` props except `d`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| keys | string[] | - | The series to draw, in order. Defaults to every series. |
| barRatio | number | 0.7 | Group width as a fraction of the category band. |
| radius | number | 8 | Corner radius at each bar's value end; a stack rounds its outer segment only. |

### ChartGrid

Horizontal grid lines on the y ticks. Forwards SVG `<g>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| rows | number | 4 | The number of horizontal bands. |
| showVertical | boolean | false | Also draws a line per category. |
| baseline | boolean | true | Draws the zero line a step stronger, when zero is in the domain. |

### ChartXAxis

The category labels under the plot. Forwards SVG `<g>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| tickFormatter | (value: string \| number, index: number) => string | - | Formats a category label. |
| interval | number \| "auto" | 1 | Labels every Nth category, or `auto`: thins by measuring, counted back from the last category. |
| minTickGap | number | 12 | With `auto`: the minimum space between labels, in px. |
| minInterval | number | 1 | With `auto`: never label more often than every Nth category. |
| label | string | - | An axis title under the labels. Give the Chart about 24px more `padding.bottom`. |

### ChartYAxis

The value ticks, in compact figures (12K, 1.4M) by default. Forwards SVG `<g>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| count | number | 4 | The number of ticks. |
| tickFormatter | (value: number) => string | - | Formats a tick, e.g. as currency. |
| side | "left" \| "right" | "left" | `right` labels the secondary scale on the right edge. |
| label | string | - | An axis title along the outer edge. Give the Chart about 20px more side padding. |

### ChartReferenceLine

A threshold (`y`) or marker (`x`) across the plot; compose it after the data. Forwards SVG `<line>` props except `x` and `y`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| y | number | - | Draws a horizontal line at this value. |
| x | number | - | Draws a vertical line at this category index. |
| label | string | - | A label at the line's end. |
| variant | "dashed" \| "solid" | "dashed" | The stroke. |
| color | ChartColor | - | The hue; a muted neutral by default. |

### ChartTooltip

The hover bands and the shared bubble, a row per series. Takes only the props below.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| valueFormatter | (value: number) => string | - | Formats each value. A series' own `format` wins. |
| labelFormatter | (value: string \| number, datum: ChartDatum, index: number) => React.ReactNode | - | Formats the heading from the category, its row and index. |
| footer | (datum: ChartDatum, index: number) => React.ReactNode | - | Extra rows under a hairline; build them with `ChartTooltipItem`. |
| sort | "none" \| "desc" \| "asc" | "none" | Orders the rows by value at the hovered category. |
| total | boolean \| string | - | Adds a total row ("Total", or your label). |
| maxItems | number | - | Folds the rows past this count into "+N more". |
| partialLabel | React.ReactNode | "In progress" | The heading of a `partial` category. |
| className | string | - | Merged onto the bubble. |

### ChartTooltipItem

One tooltip row: swatch, label, right-aligned value. Works in `footer` and outside a Chart. Forwards native `<span>` props except `children`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| label* | React.ReactNode | - | What the row measures. |
| value* | React.ReactNode | - | The figure. |
| color | ChartColor | - | The swatch hue; omit for no swatch. |
| change | number \| null | - | A change printed before the value, as a fraction (`0.12` is "+12%"). |
| inverted | boolean | false | Down is good: a fall prints green. |
| ghost | boolean | false | A comparison row with a faint swatch. |
| dimmed | boolean | false | Recedes the row. |

### ChartLegend

The key. Inside a Chart it lists the series (or slices) above the plot and focuses, hides and isolates them; outside, a plain key. Forwards all native `<div>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| config | ChartConfig | - | Outside a chart: entries from the same config the Chart takes. |
| items | { label: string; color?: ChartColor; value?: React.ReactNode; dataKey?: string }[] | - | Explicit entries; win over `config` and the chart's series. |
| align | "start" \| "center" \| "end" | "start" | The alignment of the row. |
| placement | "top" \| "bottom" | "top" | Inside a chart: above or below the plot. |
| interactive | boolean | true | Hover focuses, click toggles, Alt+click isolates. `false` for a static key. |
| max | number | - | Folds the keys past this count into a "+N more" menu. |
| value | "last" \| "sum" \| "average" \| ((key: string) => React.ReactNode) | - | A figure after each label, summarised from the data. |

| Data attribute | Description |
| --- | --- |
| data-hidden | On a key whose series is switched off (it also gets `aria-pressed="false"`). |

### ChartAnnotation

A note pinned to a category: a marker in a lane above the plot that opens on hover. Forwards SVG `<g>` props except `title`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| index* | number | - | The category the note belongs to. |
| title* | React.ReactNode | - | The headline of the note. |
| label | React.ReactNode | - | What the marker shows (a number, a letter); omit for a dot. |
| description | React.ReactNode | - | More detail under the title. |
| color | ChartColor | - | The marker hue; the foreground by default. |

### ChartFunnel

Ordered steps as columns, each with a ghost of the drop-off and its conversion from the first. Forwards SVG `<path>` props except `d`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| dataKey | string | "value" | The count at each step. |
| color | ChartColor | - | The column hue. |
| barRatio | number | 0.62 | Column width as a fraction of the band. |
| radius | number | 8 | Top corner radius, in px. |
| label | false \| ((value: number, index: number, conversion: number) => React.ReactNode) | - | The label over each step; the conversion by default, `false` for none. |

### ChartPie

A pie or donut, one slice per row named by the Chart's `index`. Forwards SVG `<g>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| dataKey | string | "value" | The value each slice is sized by. |
| innerRadius | number | 0.62 | The hole as a fraction of the radius; `0` draws a pie. |
| gap | number | 2 | Space between slices, in px. |
| colors | ChartColor[] | - | Slice hues in row order; the palette by default. |
| valueFormatter | (value: number) => string | - | Formats the value in the slice tooltip. |
| tooltip | boolean | true | A tooltip per slice with its value and share. |
| children | React.ReactNode | - | Content centered in a donut's hole. |

### CategoryBar

One whole split into segments in a single bar, standalone (no `Chart`). Forwards native `<div>` props except `children`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| data* | ChartDatum[] | - | One row per category. |
| index | string | "label" | The key holding each category's name. |
| dataKey | string | "value" | The key holding each amount; shares come from the total. |
| colors | ChartColor[] | - | Segment hues in row order. Give "Other" `gray`. |
| palette | "categorical" \| "tonal" | "categorical" | The hues for categories `colors` leaves out. |
| size | "sm" \| "md" \| "lg" | "md" | The track height: 6, 8 or 12px. |
| valueFormatter | (value: number) => string | - | Formats an amount in the tooltip and legend. |
| tooltip | boolean | true | A tooltip per segment: name, amount and share. |
| animate | boolean | true | Sweeps the bar open on mount. Held under reduced motion. |
| label | string | - | What the bar breaks down; leads its accessible name. |
| children | React.ReactNode | - | Parts under the bar: a `CategoryBarLegend`. |

### CategoryBarLegend

The key under a `CategoryBar`; hovering a key recedes the other segments. Forwards all native `<ul>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| value | "share" \| "value" \| "both" \| "none" | "share" | What follows each name. |

## 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, primary (full ink) 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Installation

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

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

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

Pro: `data-table` comes with a [Koala UI Pro license](https://www.koalaui.com/pro). Its source is not published in these docs.

## 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`.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Anatomy

```tsx
import {
  DataTableTabs,
  DataTableTabsList,
  DataTableTab,
  DataTableToolbar,
  DataTableToolbarSection,
  DataTableSearch,
  DataTable,
  Table,
  TableCaption,
  TableHeader,
  TableBody,
  TableFooter,
  TableRow,
  TableHead,
  TableCell,
} from "@/components/ui/data-table"

<DataTableTabs>
  <DataTableTabsList>
    <DataTableTab />
  </DataTableTabsList>
  <DataTableToolbar>
    <DataTableToolbarSection>
      <DataTableSearch />
    </DataTableToolbarSection>
    <DataTableToolbarSection />
  </DataTableToolbar>
  <DataTable />
</DataTableTabs>

<Table>
  <TableCaption />
  <TableHeader>
    <TableRow>
      <TableHead />
    </TableRow>
  </TableHeader>
  <TableBody>
    <TableRow>
      <TableCell />
    </TableRow>
  </TableBody>
  <TableFooter>
    <TableRow>
      <TableCell />
    </TableRow>
  </TableFooter>
</Table>
```

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

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"`.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

When the table is the whole pane (a split view, the body under a tab bar), `variant="full-bleed"` lets it fill the pane edge to edge: the row rules and the hover reach both sides, and the first and last cells take the pane’s gutter (`--table-inset`, 16px) instead of being pulled flush. Put it straight in the pane, with no padding around it, and let the pane’s own borders frame it, so no line is drawn twice.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

Flush edges would leave no room for a control’s focus ring or its invisible hit area, so the minimal scroll box bleeds: it reaches a strip past the table on every side (at least 4px, a 2px ring on a 2px offset, even when an app shrinks the root font size) and pads it back, so the columns sit exactly where they would and the rings land inside the box. The same strip is its scroll padding, so tabbing to a row at the edge of a scrolled table stops short of the edge. Controls that hug a cell edge (the sort buttons, the expand toggles, the reorder grips) draw their ring inside themselves. A table wider than its box still scrolls: there, a control half under the edge is half scrolled out of view, ring and all, until you scroll to it.

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

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`.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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"`.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

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`).

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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`.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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`.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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`.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

The selection control is the shared [Checkbox](https://www.koalaui.com/docs/components/checkbox.md) component, in checked, indeterminate, and disabled states:

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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 an ink tint, deliberately distinct from the checkbox-selected muted 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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. The box keeps a scroll padding the height of the header, so a row that keyboard focus scrolls up to lands below the header, ring included, instead of under it.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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`.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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`.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## AI generation

This example takes the existing members table and adds an AI insight column. Click`Generate with AI` to fill it row by row; completed insights stay visible while the next one is generated. The preview uses local sample responses, ready to be replaced by a model call in your app.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

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` box or `filters` this happens automatically: an active search or filter that matches nothing falls back to the search-empty placeholder.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## API reference

### DataTable

The TanStack-wired grid: it owns sorting, filtering, selection, grouping, paging and reordering, and renders into the `Table` primitives. Every part that renders an element accepts `className`, merged last; here it lands on the `<table>`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| columns* | ColumnDef<TData, TValue>[] | - | TanStack column definitions. Alignment, pinning, labels and tooltips ride on each column's `meta` (see `ColumnMeta`). |
| data* | TData[] | - | The rows. Keep the array and its items stable between renders (state or memo). |
| getRowId | (row: TData, index: number) => string | - | Stable row id, so selection, grouping and `activeRowId` survive re-sorts. Falls back to the row index. |
| variant | "minimal" \| "container" \| "full-bleed" | "minimal" | `minimal` is chromeless with flush edge cells; `container` is the ring-edged, rounded card; `full-bleed` fills its pane edge to edge, with the edge cells padded by `--table-inset`. |
| density | "comfortable" \| "compact" | "compact" | Row height and cell padding; also sets the toolbar controls (`sm` or `md`) and the pager. Falls back to the nearest `DensityProvider`. |
| striped | boolean | false | Zebra-stripe even rows; the stripe skips hovered, selected and current rows. |
| hoverable | boolean | true | Tint body rows on hover. |
| stickyHeader | boolean | false | Pin the header while the body scrolls. Cap the height with `containerClassName`. |
| containerClassName | string | - | Classes for the scroll container, e.g. `max-h-96` to give a sticky header something to scroll. |
| enableSorting | boolean | false | Click-to-sort headers with a sort caret. |
| initialSorting | SortingState | [] | The sort on mount, uncontrolled. |
| sorting | SortingState | - | The sort, controlled. Pair it with `onSortingChange`; `initialSorting` is then ignored. |
| onSortingChange | (sorting: SortingState) => void | - | Called after the sort changes; with `sorting` set, the change to apply. |
| enableRowSelection | boolean | false | Prepend a checkbox column with a select-all header that goes indeterminate on a partial selection. |
| onRowSelectionChange | (selection: RowSelectionState) => void | - | Called after each selection change, including rows dropping out because they left `data`. |
| renderSelectionActions | (rows: Row<TData>[], table: Table<TData>) => React.ReactNode | - | Bulk actions for the floating `DataTableSelectionBar` shown while rows are selected. Requires `enableRowSelection`. |
| onRowClick | (row: Row<TData>, event: React.MouseEvent \| React.KeyboardEvent) => void | - | Open a row on a click anywhere on it or Enter on a focused row; clicks on controls inside the row do their own job. Makes body rows focusable. |
| activeRowId | string \| null | - | The id of the row open elsewhere (a detail pane): painted with an ink tint and `aria-current="true"`. |
| onDisplayedRowsChange | (rows: Row<TData>[]) => void | - | The rows shown, in display order, across all pages (searched, filtered, sorted). Called after mount and whenever that list changes, not on paging. |
| toolbar | boolean | false | Force the toolbar rail on. It turns on by itself with `searchable`, `filters`, `toolbarActions`, `viewOptions` or `enableCardLayout`. |
| searchable | boolean | false | Add a search box that filters every column (TanStack global filter). |
| searchPlaceholder | string | "Search for anything" | Placeholder of the search box. |
| globalFilter | string | - | The search text, controlled, with or without the built-in box. Pair it with `onGlobalFilterChange`. |
| onGlobalFilterChange | (value: string) => void | - | Called as the search text changes; with `globalFilter` set, the change to apply. |
| toolbarActions | React.ReactNode | - | The toolbar's right-hand slot for your own buttons. |
| filters | DataTableFilterField[] | - | Faceted filters: a multi-select per field in the toolbar plus removable chips below it. Filtered columns need `filterFn: "arrIncludesSome"`. |
| onColumnFiltersChange | (filters: ColumnFiltersState) => void | - | Called after the column filters change. |
| viewOptions | boolean | false | Add the View options dropdown for showing and hiding labelled columns. |
| columnVisibility | VisibilityState | - | Visible columns, controlled (`{ columnId: false }` hides one). Pair it with `onColumnVisibilityChange`. |
| onColumnVisibilityChange | (visibility: VisibilityState) => void | - | Called after a column is shown or hidden. |
| enableCardLayout | boolean | false | Add a Rows/Cards switch to the view options (implies `viewOptions`) and render a card grid when chosen. |
| defaultLayout | "rows" \| "cards" | "rows" | The layout on mount when `enableCardLayout` is on. |
| renderCard | (row: Row<TData>) => React.ReactNode | - | Replace the generated card (first column as title, labelled columns as fields, icon-only action top-right). |
| enableGrouping | boolean | false | Collapse rows into expandable groups by the `initialGrouping` column. |
| initialGrouping | GroupingState | [] | The column id(s) to group by. |
| renderSubRow | (row: Row<TData>) => React.ReactNode | - | A detail panel under an expanded row; prepends a caret toggle column. Not combined with `enableGrouping`. |
| getRowCanExpand | (row: Row<TData>) => boolean | - | Which rows can expand a `renderSubRow` panel; every row when omitted. |
| onRowReorder | (event: DataTableRowReorder<TData>) => void | - | Adds a drag grip per row; reports `{ row, fromIndex, toIndex }` for you to apply with `moveItem`. Inert under a sort or grouping. |
| enableColumnOrdering | boolean | false | Drag headers (or arrow-nudge their grip) into a new order. Utility and `meta.sticky` columns stay put. |
| initialColumnOrder | string[] | - | Left-to-right column ids on mount; the `columns` order when omitted. |
| onColumnOrderChange | (order: string[]) => void | - | Called after the column order changes. |
| enablePagination | boolean | false | Page rows client-side with a Pagination toolbar below; the page steps back when `data` shrinks under it. |
| pageSize | number | 8 | Rows per page on mount. |
| pageSizeOptions | number[] | [8, 16, 24, 50, 100] | Rows-per-page choices; by default one, two and three pages of `pageSize`, then 50 and 100. The size in use is always merged in. |
| onPaginationChange | (pagination: PaginationState) => void | - | Called after the page or page size changes. |
| onLoadMore | () => void | - | Infinite scroll: called when a sentinel near the end scrolls into view. Replaces the pagination toolbar. |
| hasMore | boolean | false | More rows can still be loaded; the sentinel stops when false. |
| loadingMore | boolean | false | A load-more fetch is in flight: shows a loading row and blocks duplicate calls. |
| manualSorting | boolean | false | Sorting happens on the server; rows are not sorted client-side. |
| manualFiltering | boolean | false | Search and filters happen on the server; rows are not filtered client-side. |
| manualPagination | boolean | false | `data` is already the current page. Pass `pageCount` or `rowCount`. |
| pageCount | number | - | Total pages under `manualPagination`; derived from `rowCount` when omitted. |
| rowCount | number | - | Total rows across all pages, used to derive `pageCount`. |
| loading | boolean | false | Swap the rows for skeletons that mirror the columns; sets `aria-busy` and disables paging. |
| loadingRows | number | 5 | Skeleton rows (or cards) shown while `loading`. |
| emptyState | React.ReactNode | <DataTableEmpty /> | Shown with no rows. The default picks `kind="search"` while a search or filter is active, else `kind="empty"`. |
| persistKey | string | - | Remember visible columns, column order, sort, layout and page size in `localStorage` under this key. Applied after mount. |

| Data attribute | Description |
| --- | --- |
| data-state | `"selected"` on a selected row (or card). |
| data-row-id | The row id on each body row while `onRowReorder` is set. |
| data-column-id | The column id on each header while `enableColumnOrdering` is on. |

### ColumnMeta

Not a component: the keys Koala adds to TanStack's `columnDef.meta`, read by `DataTable` for each column's header and cells.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| numeric | boolean | - | Right-align the header and cells with `tabular-nums`. |
| align | "left" \| "center" \| "right" | "left" | Text alignment for the header and cells. |
| sticky | "left" \| "right" | - | Pin the column to an edge while the rest scrolls sideways. |
| label | string | - | The column's name in View options and as a card field label. Falls back to a string `header`; columns with neither cannot be hidden. |
| className | string | - | Extra classes for the column's header and cells. |
| headerTooltip | React.ReactNode | - | Appends a focusable info icon after the header label that shows this hint. |
| cellTooltip | (context: CellContext<TData, TValue>) => React.ReactNode | - | A tooltip per cell; return `null` or `undefined` to skip one. |

### DataTableTabs

Line `Tabs` (Radix `Tabs.Root`) wrapped around a `DataTable` to split one list into views. The table inside becomes the tab panel and returns to its first page on a switch. Forwards all `Tabs` props except `variant` and `orientation`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| value | string | - | The active view, controlled. |
| defaultValue | string | - | The view on mount, uncontrolled. |
| onValueChange | (value: string) => void | - | Called when the view changes. |
| density | "comfortable" \| "compact" | "compact" | Tabs spacing. Falls back to the nearest `DensityProvider`. |

| Data attribute | Description |
| --- | --- |
| data-orientation | `"horizontal"`, set by Radix. |

### DataTableTabsList

The full-width tab rail, Radix `Tabs.List`; scrolls sideways on a phone. Give it an `aria-label` naming what the views split.

### DataTableTab

One view, a `TabsTrigger` (Radix `Tabs.Trigger`); forwards all its props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| value* | string | - | The view this tab selects. |
| count | number | - | A count chip after the label that rolls to each new figure. Omit for no chip. |
| static | boolean | true | Kept for compatibility; controls no longer scale on press. |
| disabled | boolean | false | Makes the tab unselectable. |

| Data attribute | Description |
| --- | --- |
| data-state | `"active"` or `"inactive"`. |
| data-disabled | Present when the tab is disabled. |

### useDataTableTabs

Hook returning the nearest `DataTableTabs` context, `{ value }` with the active view, or `null` when the table stands on its own.

### DataTableToolbar

The control rail for a hand-composed toolbar: two `DataTableToolbarSection`s pushed to opposite edges, reflowing on a phone. Forwards all native `<div>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| size | "sm" \| "md" \| "lg" | - | Control height imposed on everything inside; a control's own `size` still wins. Unset, it follows the container's size, then density (`compact` gives `sm`). |

| Data attribute | Description |
| --- | --- |
| data-control-size | The resolved control size. |

### DataTableToolbarSection

A cluster of controls inside the toolbar: left for search and filters, right for actions. Forwards all native `<div>` props.

### DataTableSearch

A magnifier-prefixed search `Input` with a trailing shortcut hint. Forwards all `InputField` (native `<input>`) props and `ref`; `className` lands on the field.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| placeholder | string | "Search for anything" | Placeholder text. |
| shortcut | React.ReactNode \| false | "⌘K" | The `Kbd` hint on the right edge (display only; bind the key yourself). `false` hides it. |
| size | "sm" \| "md" \| "lg" | - | Control size; unset, it follows the toolbar around it. |
| rootClassName | string | - | Classes for the box (`InputRoot`), e.g. its width. Default width is full below `sm`, `w-72` above. |

### DataTableFacetedFilter

A dashed outline button opening a Popover of checkable options, each with its count of matching rows; writes an array to the column's filter value.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| column | Column<TData, unknown> | - | The TanStack column to filter, from `table.getColumn(id)`. It needs `filterFn: "arrIncludesSome"`. |
| title* | string | - | The button label. |
| options* | DataTableFilterOption[] | - | The choices: `{ label, value, icon? }`. |

### DataTableActiveFilters

The row of removable chips for every active faceted value, plus a Reset button that clears all column filters.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| table* | Table<TData> | - | The TanStack table instance. |
| filters* | DataTableFilterField[] | - | The same fields the filters were built from: `{ columnId, title, options }`. |

### DataTableViewOptions

The View options dropdown: an optional Rows/Cards switch above a checkbox per labelled, hideable column. The menu stays open while toggling.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| table* | Table<TData> | - | The TanStack table instance. |
| enableLayout | boolean | false | Show the Rows/Cards switch. |
| layout | "rows" \| "cards" | "rows" | The current layout, for the switch. |
| onLayoutChange | (layout: "rows" \| "cards") => void | - | Called when the switch changes. |
| label | string | "View options" | Accessible name of the icon trigger. |

### columnLabel

`columnLabel(column)` returns a column's display name: `meta.label`, else a string `header`, else `undefined`.

### DataTableSelectionBar

The floating bulk-action pill (count, clear, actions), dark in every theme. An absolute overlay: put it inside a `relative` container. Forwards native `<div>` props to the overlay; `className` lands on the pill.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| count* | number | - | How many rows are selected, shown as "N selected". |
| onClear* | () => void | - | Called by the clear (x) button. |
| children | React.ReactNode | - | The bulk-action controls, after a divider. |

### DataTableEmpty

The zero-row placeholder, a compact `EmptyState` preset with an icon, title and description per `kind`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| kind | "empty" \| "search" | "empty" | `empty` for no data yet; `search` for a search or filter that matched nothing. |
| icon | React.ReactNode | - | Replaces the preset icon. |
| title | React.ReactNode | - | Replaces the preset title. |
| description | React.ReactNode | - | Replaces the preset description. |
| children | React.ReactNode | - | The single action, e.g. an outline "Clear filters" Button. |

### DataTableGrip

The drag handle `DataTable` renders for row and column reordering, exported for hand-built tables. Renders a `<button>` and forwards its props; arrow keys on the axis call `onNudge`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| label* | string | - | Accessible name, e.g. "Reorder row". |
| axis* | "rows" \| "columns" | - | Rows move up and down, columns left and right. |
| onGrab | (event: React.PointerEvent<HTMLElement>) => void | - | Starts a drag on pointer down. |
| onNudge | (direction: -1 \| 1) => void | - | The keyboard path: one step up/left or down/right. |
| locked | React.ReactNode | - | Why dragging is off: the grip goes inert (`aria-disabled`) and shows this as a tooltip. |
| dragging | boolean | - | Holds the handle visible and lit while its row or column is dragged. |

| Data attribute | Description |
| --- | --- |
| data-dragging | `"true"` while `dragging`. |

### moveItem

`moveItem(items, fromIndex, toIndex)` returns a new array with one item moved; feed it an `onRowReorder` event.

### Table

The styled `<table>` primitive, wrapped in its scroll container; forwards all native `<table>` props. Provides the variants to every primitive below.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| variant | "minimal" \| "container" \| "full-bleed" | "minimal" | Chromeless with flush edge cells, the ring-edged, rounded card, or edge to edge with the edge cells padded by `--table-inset`. |
| density | "comfortable" \| "compact" | "compact" | Row height and cell padding. Falls back to the nearest `DensityProvider`. |
| striped | boolean | false | Zebra-stripe even body rows. |
| hoverable | boolean | true | Tint body rows on hover. |
| stickyHeader | boolean | false | Pin header cells to the top of the scroll container. |
| containerProps | React.ComponentProps<"div"> | - | Props for the scroll container, e.g. `{ className: "max-h-96" }`. |

| CSS variable | Description |
| --- | --- |
| --table-surface | The opaque row surface every stripe, hover and pinned cell mixes into; set to `var(--surface, var(--background))`. |
| --surface | Read from the container (a Dialog, a Card) so the table blends into it. |
| --table-inset | `full-bleed` only: the padding of the first and last cells, so the text lines up with the pane's gutter. Defaults to 16px. |

### TableHeader

Forwards all native `<thead>` props.

### TableBody

Forwards all native `<tbody>` props; carries the hover, stripe and current-row tints.

### TableFooter

A muted, `tabular-nums` totals band. Forwards all native `<tfoot>` props.

### TableRow

Forwards all native `<tr>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| selected | boolean | - | Paint the selected fill. |
| current | boolean | - | Mark the record open elsewhere: `aria-current="true"` and an ink tint, distinct from `selected`. |

| Data attribute | Description |
| --- | --- |
| data-state | `"selected"` when `selected`. |

### TableHead

A header cell. Forwards all native `<th>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| align | "left" \| "center" \| "right" | "left" | Text alignment. |
| sticky | "left" \| "right" | - | Pin the column to an edge while the rest scrolls sideways. |

### TableCell

A body cell. Forwards all native `<td>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| align | "left" \| "center" \| "right" | "left" | Text alignment. |
| numeric | boolean | - | Right-align with `tabular-nums`. |
| sticky | "left" \| "right" | - | Pin the cell to an edge; it inherits its row's background. |

### TableCaption

Muted copy describing the table. Forwards all native `<caption>` props.

### TableCellText

A two-line cell body: a primary label over muted supporting text. Compose it inside a `TableCell`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| primary* | React.ReactNode | - | The main line. |
| secondary | React.ReactNode | - | The muted line under it. |

### TableEmpty

A full-width row with one cell spanning every column, for a `TableBody` with no rows.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| colSpan* | number | - | How many columns the cell spans. |
| children | React.ReactNode | "No results." | The message. |

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Installation

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

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

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

Pro: `description-list` comes with a [Koala UI Pro license](https://www.koalaui.com/pro). Its source is not published in these docs.

## Usage

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Anatomy

```tsx
import {
  DescriptionList,
  DescriptionListItem,
  DescriptionTerm,
  DescriptionDetails,
} from "@/components/ui/description-list"

<DescriptionList>
  <DescriptionListItem>
    <DescriptionTerm />
    <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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Divided

Set `divided` for a hairline rule between rows. Turns a loose list into a scannable, table-like read.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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`.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## API reference

### DescriptionList

The root `<dl>`; forwards all native `<dl>` props and shares its variants with every part through context. Every part accepts `className`, merged last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| layout | "row" \| "stack" \| "auto" \| "inline" | "row" | `row` splits term and value at the `sm` viewport, `stack` keeps the term above, `auto` splits by the list's own width, `inline` flows the pairs along a line. |
| divided | boolean | false | Hairline rule between rows; the last row drops it. Ignored by `inline`. |
| density | "comfortable" \| "compact" | "compact" | Per-row vertical padding: 12px or 8px. Ignored by `inline`. Falls back to the nearest `DensityProvider`. |
| asChild | boolean | false | Merge onto your own element through Radix `Slot` instead of rendering a `<dl>`. |

| CSS variable | Description |
| --- | --- |
| --dl-term | Term column width in `row` and `auto` layouts (default `12rem`); `row` caps it at half the list's width. |
| --dl-value | In `auto` layout, the least room a value needs beside its term before it wraps under it (default `10rem`). |

### DescriptionListItem

One term/value pair, a `<div>` grouping inside the `<dl>` (valid HTML5). Forwards all native `<div>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| asChild | boolean | false | Merge onto your own element through Radix `Slot` instead of rendering a `<div>`. |

### DescriptionTerm

The muted label, a `<dt>`. A leading Koala icon is sized to 16px and centred while the text keeps the baseline. Forwards all native `<dt>` props.

### DescriptionDetails

The value, a `<dd>` with `tabular-nums`. A leading Avatar, Flag, svg, img, Badge or Select trigger is centred on the text line without flex classes. Forwards all 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 Koala 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Installation

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

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

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

Pro: `heatmap` comes with a [Koala UI Pro license](https://www.koalaui.com/pro). Its source is not published in these docs.

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Anatomy

```tsx
import {
  Heatmap,
  HeatmapGrid,
  HeatmapRowLabels,
  HeatmapColumnLabels,
  HeatmapLegend,
} from "@/components/ui/heatmap"

<Heatmap>
  <HeatmapGrid>
    <HeatmapRowLabels />
    <HeatmapColumnLabels />
  </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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## API reference

### Heatmap

The root: owns the data, the labels and the colour scale, and shares them with the parts through Context. Forwards all native `<div>` props except `color`; every part accepts `className`, merged last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| data* | ReadonlyArray<ReadonlyArray<number \| null \| undefined>> | - | One array per row, one entry per column. `null`, a missing entry or a non-finite number is a blank cell; zero paints the muted track. |
| rows | readonly string[] | - | Row labels, in order; used by `HeatmapRowLabels`, the tooltips and each cell's name. Missing ones read `Row 1`, `Row 2`... |
| columns | readonly string[] | - | Column labels, in order; missing ones read `Column 1`, `Column 2`... Its length also sets the minimum column count. |
| normalize | "grid" \| "row" \| "column" | "grid" | What each shade is measured against: the whole grid, its own row, or its own column. |
| domain | readonly [number, number] | - | Pin the scale to `[low, high]` (say `[0, 100]` for percentages); `normalize` then has no effect. |
| steps | number | 4 | Shades above the empty track, rounded and clamped to 1 through 10. |
| color | "blue" \| "brand" \| "primary" \| "purple" \| "pink" \| "teal" \| "orange" \| "success" \| "warning" \| "info" \| "destructive" \| "current" | "blue" | The hue the scale is built from; `current` takes the ambient text colour. |
| size | "sm" \| "md" | "md" | `md`: cells at least 24px, 4px apart. `sm`: at least 10px, 2px apart, for a dense strip. |
| aspect | "square" \| "wide" | "square" | `wide` keeps one row height (28px at `md`, 12px at `sm`) and stretches cells across their column. |
| valueFormatter | (value: number) => string | - | Formats a value for the tooltip and each cell's name; defaults to `en-US` grouping with up to two decimals. |
| label | string | - | Accessible name of the grid, for example `"Events per day, Sep 21 to Sep 27"`. Strongly recommended. |
| animate | boolean | true | Play the one-shot diagonal reveal on mount; held still under `prefers-reduced-motion`. |
| empty | ReactNode | "No data to display" | Shown in place of the cells when `data` has no rows or no columns. |

| Data attribute | Description |
| --- | --- |
| data-size | `"sm"` or `"md"`. |
| data-aspect | `"square"` or `"wide"`. |

| CSS variable | Description |
| --- | --- |
| --heatmap-color | The scale's hue, set by `color`; override it for a hue outside the list. |

### HeatmapGrid

The scroll box and the ARIA grid of cells, with one shared tooltip that glides between them. Holds `HeatmapRowLabels` and `HeatmapColumnLabels`; forwards all native `<div>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| renderTooltip | (cell: HeatmapCell) => ReactNode | - | The tooltip body for a cell, composed from the Tooltip graph parts; return `null` for no tooltip. Defaults to row label, column label and the formatted value. |
| cellLabel | (cell: HeatmapCell) => string | - | Each cell's accessible name. Defaults to `"row, column: value"` ("Sign-ups, Mon: 131"). |

| Data attribute | Description |
| --- | --- |
| data-row | On each cell: its row index, from 0. |
| data-column | On each cell: its column index, from 0. |
| data-level | On each cell with a value: its scale step, 0 (the track) to `steps`. |
| data-blank | On each cell with no value. |

| CSS variable | Description |
| --- | --- |
| --heatmap-alpha | Per cell: the share of the hue mixed into the muted track, as a percentage. |
| --heatmap-cell-min | The narrowest a column gets before the grid scrolls (set by `size`). |
| --heatmap-rows | Row count, set inline on the layout. |
| --heatmap-columns | Column count, set inline on the layout. |

### HeatmapRowLabels

The labels down the start edge, pinned while a wide grid scrolls; place it inside `HeatmapGrid`. Hidden from assistive tech, painted on `--surface` (falling back to `--background`); forwards all native `<div>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| tickFormatter | (label: string, index: number) => ReactNode | - | Format a label, or return `null` to leave its slot empty. |
| interval | number | 1 | Show every Nth label only, to thin out a crowded axis. |

| Data attribute | Description |
| --- | --- |
| data-active | On the label of the hovered or focused cell's row. |

### HeatmapColumnLabels

The labels across the top; place it inside `HeatmapGrid`. A label followed by an empty slot spills from its column's start edge. Hidden from assistive tech; forwards all native `<div>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| tickFormatter | (label: string, index: number) => ReactNode | - | Format a label, or return `null` to leave its slot empty. |
| interval | number | 1 | Show every Nth label only, to thin out a crowded axis. |

| Data attribute | Description |
| --- | --- |
| data-active | On the label of the hovered or focused cell's column. |
| data-spill | On a label whose next slot is empty, so it marks its column from the start edge. |

### HeatmapLegend

The scale from the empty track to the full hue. Hidden from assistive tech; forwards all native `<div>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| lowLabel | ReactNode | "Less" | Before the scale; `null` drops it. |
| highLabel | ReactNode | "More" | After the scale; `null` drops it. |

| Data attribute | Description |
| --- | --- |
| data-level | On each swatch: its step, 0 to `steps`. |

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Installation

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

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

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

Pro: `order-summary` comes with a [Koala UI Pro license](https://www.koalaui.com/pro). Its source is not published in these docs.

## Usage

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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
import {
  OrderSummary,
  OrderSummaryHeader,
  OrderSummaryTitle,
  OrderSummaryItems,
  OrderSummaryItem,
  OrderSummaryItemThumbnail,
  OrderSummaryItemContent,
  OrderSummaryItemName,
  OrderSummaryItemOptions,
  OrderSummaryItemPrice,
  OrderSummaryItemActions,
  OrderSummaryItemQuantity,
  OrderSummaryItemRemove,
  OrderSummaryPromo,
  OrderSummaryTotals,
  OrderSummaryRow,
  OrderSummaryTotal,
  OrderSummaryFooter,
} from "@/components/ui/order-summary"

<OrderSummary>
  <OrderSummaryHeader>
    <OrderSummaryTitle />
  </OrderSummaryHeader>
  <OrderSummaryItems>
    <OrderSummaryItem>
      <OrderSummaryItemThumbnail />
      <OrderSummaryItemContent>
        <OrderSummaryItemName />
        <OrderSummaryItemOptions />
      </OrderSummaryItemContent>
      <OrderSummaryItemPrice />
      <OrderSummaryItemActions>
        <OrderSummaryItemQuantity />
        <OrderSummaryItemRemove />
      </OrderSummaryItemActions>
    </OrderSummaryItem>
  </OrderSummaryItems>
  <OrderSummaryPromo>…</OrderSummaryPromo>
  <OrderSummaryTotals>
    <OrderSummaryRow label="…">…</OrderSummaryRow>
    <OrderSummaryTotal label="…">…</OrderSummaryTotal>
  </OrderSummaryTotals>
  <OrderSummaryFooter>…</OrderSummaryFooter>
</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 Koala 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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` suits a checkout page; `compact` (the default with no `DensityProvider`) tightens the padding and shrinks the thumbnails for a mini-cart. Set it per instance or once on a provider.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## API reference

### OrderSummary

The shell. Renders a `<section>` and forwards all its props. Every part accepts `className`, merged last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| variant | "card" \| "plain" | "card" | `card` adds a ring and insets the content; `plain` sits flush. |
| density | "comfortable" \| "compact" | - | Gaps, padding and thumbnail size. Inherits the nearest `DensityProvider` (compact with none) when unset. |
| asChild | boolean | false | Renders the child as the shell via Radix Slot. |

### OrderSummaryHeader

The title band: a title on the left, an item-count Badge or Edit link on the right. Forwards native `<div>` props.

### OrderSummaryTitle

The summary's title. Forwards native `<div>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| asChild | boolean | false | Renders the child (an `<h2>`, an `<h3>`) as a real heading. |

### OrderSummaryItems

The line items, a `<ul>`; rows stack on whitespace, no dividers.

### OrderSummaryItem

One cart line, an `<li>`. Forwards all its props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| leaving | boolean | - | Plays the exit (collapse, fade, drift). Drop the item in `onAnimationEnd`, guarded to `e.target === e.currentTarget`. |

| Data attribute | Description |
| --- | --- |
| data-leaving | Present while the row plays its exit. |

### OrderSummaryItemThumbnail

The product tile: an `<img>` (cover-fit, outlined), a Koala glyph, or nothing. Forwards native `<div>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| count | React.ReactNode | - | A quantity pill on the corner. Omit for single-quantity lines. |

### OrderSummaryItemContent

The name and options column; it fills so the price rides the right edge. Forwards native `<div>` props.

### OrderSummaryItemName

The product name; truncates. Forwards native `<div>` props.

### OrderSummaryItemOptions

The muted options line, e.g. `Size M · Oat`. Forwards native `<div>` props.

### OrderSummaryItemPrice

The line total, `tabular-nums`, never wrapping under the name. Forwards native `<div>` props.

### OrderSummaryItemActions

Trailing controls for an editable line: the quantity stepper and remove button. Forwards native `<div>` props.

### OrderSummaryItemQuantity

The quantity stepper: a small inline `NumberInput` (minus, value, plus).

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| value | number \| null | - | The quantity, controlled. |
| defaultValue | number \| null | - | The initial quantity, uncontrolled. |
| onValueChange | (value: number \| null) => void | - | Called on every committed change. |
| min | number | 1 | Lowest allowed quantity. |
| max | number | - | Highest allowed quantity. |
| aria-label | string | "Quantity" | The field's accessible name. |

### OrderSummaryItemRemove

The remove button: a `destructiveGhost` icon Button with a trash glyph. Wire `onClick`; forwards native `<button>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| aria-label | string | "Remove item" | The button's accessible name. |

### OrderSummaryPromo

A band for a promo `InputGroup` (field plus Apply). Forwards native `<div>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| size | "sm" \| "md" \| "lg" | "lg" | Control size imposed on the field and button, in line with the checkout CTA. |

| Data attribute | Description |
| --- | --- |
| data-control-size | The imposed size. |

### OrderSummaryTotals

The breakdown, a `<dl>`.

### OrderSummaryRow

One subtotal, shipping, tax or discount line: a `<dt>` label and a `<dd>` value. Forwards native `<div>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| label* | React.ReactNode | - | The label, e.g. `Subtotal`. |
| children* | React.ReactNode | - | The value, set `tabular-nums`. |
| tone | "default" \| "discount" \| "muted" | "default" | `discount` greens the value; `muted` softens it. |

### OrderSummaryTotal

The emphasized grand total. Forwards native `<div>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| label* | React.ReactNode | - | The label, e.g. `Total`. |
| children* | React.ReactNode | - | The value. |

### OrderSummaryFooter

A band for the checkout Button and a trust note. Forwards native `<div>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| size | "sm" \| "md" \| "lg" | "lg" | Control size imposed on the buttons inside. |

| Data attribute | Description |
| --- | --- |
| data-control-size | The imposed size. |

## 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 Koala 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 density (compact is the default with no provider). 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/paper.md -->

# Paper

A printed document on screen: a contract, an incident report, a ticket or a certificate. A white sheet in a serif with typed-in values, laid out at one design width and scaled as a whole to the room it gets, so it reads as the paper it stands for rather than as one more card of the app around it.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Installation

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

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

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

Pro: `paper` comes with a [Koala UI Pro license](https://www.koalaui.com/pro). Its source is not published in these docs.

## Usage

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Anatomy

Every part is optional but the sheet. A ticket can be a heading and three rows; a contract uses the lot. Parts stack in the order you write them, each ruled off the next.

```tsx
import {
  Paper,
  PaperBox,
  PaperCaption,
  PaperCheckItem,
  PaperChecklist,
  PaperField,
  PaperFooter,
  PaperHeader,
  PaperHeaderAside,
  PaperHeading,
  PaperNote,
  PaperRow,
  PaperSeal,
  PaperSection,
  PaperSignature,
  PaperSignatures,
  PaperSubtitle,
  PaperTable,
  PaperTableCell,
  PaperTableHead,
  PaperText,
  PaperTitle,
} from "@/components/ui/paper"

<Paper>
  {/* The letterhead: a seal, the centered heading, an aside of boxes */}
  <PaperHeader>
    <PaperSeal>{/* an img or an svg */}</PaperSeal>
    <PaperHeading>
      <PaperTitle />
      <PaperSubtitle />
      <PaperCaption />
    </PaperHeading>
    <PaperHeaderAside>
      <PaperBox label="Number" />
    </PaperHeaderAside>
  </PaperHeader>

  {/* The body: bands, rows of fields, copy, tables, checklists */}
  <PaperSection />
  <PaperRow>
    <PaperField label="Label" grow={2} />
  </PaperRow>
  <PaperText />
  <PaperTable>
    <PaperTableHead />
    <PaperTableCell />
  </PaperTable>
  <PaperNote />
  <PaperChecklist>
    <PaperCheckItem checked />
  </PaperChecklist>

  {/* Signature lines, side by side, and the small print */}
  <PaperSignatures>
    <PaperSignature label="Signature" name="Name" date="Date" />
  </PaperSignatures>
  <PaperFooter />
</Paper>
```

## Fit

A document is not responsive. The sheet is laid out at one design width, `width` in em (`52` by default, 832px at a 16px root), and with `fit` it scales as a whole to the width it is given: the title stays on one line, a label never breaks in two and the copy keeps its line breaks, at any size. The scale is the sheet's own font size, and every length inside is in em, so the page is laid out again for real rather than zoomed. It never grows past its design size: in a wider column it sits centered.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

`fit={false}` keeps the design width whatever the room, and the frame decides what happens to the overflow: here it scrolls sideways. `frameClassName` styles that frame, the `div` the sheet measures; padding on it is room the sheet keeps clear, for its shadow.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Letterhead

`PaperHeader` lays out a `PaperSeal`, the `PaperHeading` and a `PaperHeaderAside`, in that order. The seal and the aside are boxes of the same width, so the heading between them is centered on the sheet, not on the room they leave. The title wraps rather than run under the boxes; captions stack under the subtitle. The seal takes any `img` or `svg`: the `Seal` on these pages is a small inline SVG of the docs' own, drawn in `var(--paper-accent)` so it follows the sheet's accent.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

Drop the seal or the aside and keep the other side's box empty (`<PaperSeal />` or `<PaperHeaderAside />`) to hold the heading on the sheet's axis, or drop both and give the heading the whole row.

## Fields and boxes

A `PaperRow` is a ruled line of `PaperField`s: a pre-printed label over a typed-in value. `grow` is a field's share of the row, a flex factor. When a label wraps onto two lines the values in the row still sit on one line, and a value too long for its cell ends in an ellipsis. `PaperBox` is the same pair boxed on its own, for the aside: a number, a status, a date.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Running text

`PaperText` is copy someone reads: terms, a statement, a narrative. It is justified in the serif and keeps the line breaks it was typed with, so text straight from a textarea or a database lands as it was written, paragraphs and numbered clauses included.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Tables

`PaperTable` is a plain `table`: write the `thead` and `tbody` yourself with `PaperTableHead`, printed like a field label, and `PaperTableCell`, typed in. Widths are yours too; percentages hold at every scale. When a section has nothing to list, `PaperNote` says so in place of an empty table.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Checklist

`PaperChecklist` is a list of printed boxes and `PaperCheckItem` one line of it, ticked with `checked`. It records what was done; nothing on the sheet can be toggled, so the box is drawn, not a control.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Signatures

`PaperSignatures` sets `PaperSignature` blocks side by side: a label, the mark over a line, and the name and date under it. The mark is the children: a stored signature as an `img` (here the SVG a `SignaturePad` submits), a `Signature`, or a live `SignaturePad`, which drops its own box and guide to fill the mark and sign on the sheet's line. Sign the right-hand line: the pad maps the pointer with `getBoundingClientRect()`, which the sheet's scale never skews, and the date fills in when the first stroke lands. The app's own controls, like Clear here, sit outside the sheet. Left empty, a line waits to be signed.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Re-tinting

The sheet's inks are its own roles, derived from the light theme's tokens: `--paper-ink`, `--paper-muted`, `--paper-rule`, `--paper-label` (the label tint) and `--paper-accent` (the title, the section bands and anything you paint with it, like the seal here). The accent defaults to a letterhead navy; set any of them per sheet with a utility.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Old engines

Paper is built to hold in old embedded Chromium too, the kind a desktop or game shell ships (Chromium 10x): no container queries, no `:has()` and no standalone `translate` or `scale` anywhere. The fit is one `ResizeObserver` and one font size; without the observer the sheet is measured once, on mount. Because nothing is zoomed or transformed, a control set into the paper reads its pointer and its box as it would anywhere else, and the type is rasterized at the size it is shown, crisp.

## API reference

### Paper

The sheet, an `<article>` scoped `.light`, inside the frame it scales into (a `<div>`). Every `article` prop goes to the sheet. Every part forwards its element's props and merges `className` last; `paperVariants` is the recipe.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| width | number | 52 | The design width in em of the root type size (832px at 16px). Also set as `--paper-width`. |
| fit | boolean | true | Scales the sheet down to the frame's width, never up. The scale is set as `--paper-scale`; off, it stays `1` and the container decides what happens to the overflow. |
| frameClassName | string | - | Classes for the frame (the sheet itself takes `className`). |
| className | string | - | Merged last on the sheet, where the `--paper-*` roles live. |

| Data attribute | Description |
| --- | --- |
| data-slot | `"paper"` on the sheet, `"paper-frame"` on the frame. |

| CSS variable | Description |
| --- | --- |
| --paper-width | The design width, from `width`. |
| --paper-scale | The fit's scale, from 0 to 1: the sheet's font size, which every length inside is measured in. |
| --paper-ink | The type. The light theme's `--foreground`. |
| --paper-muted | Labels, captions and notes. The light theme's `--body`. |
| --paper-rule | Every rule and box edge. |
| --paper-label | The ground of a pre-printed label and the footer. |
| --paper-accent | The title and the section bands: a deep navy, ink with a little `--info` in it. |
| --paper-accent-foreground | The type on a section band. |

### PaperHeader

The letterhead row, a `<header>`: a seal, the heading and an aside of boxes, in that order.

| Data attribute | Description |
| --- | --- |
| data-slot | `"paper-header"`. |

### PaperSeal

A seal or logo (an `img` or an `svg` child), in a `<div>` boxed as wide as `PaperHeaderAside`, so the heading is centered on the sheet.

| Data attribute | Description |
| --- | --- |
| data-slot | `"paper-seal"`. |

### PaperHeading

The centered column, a `<div>`, for the title, the subtitle and the captions.

| Data attribute | Description |
| --- | --- |
| data-slot | `"paper-heading"`. |

### PaperTitle

The document's title, an `<h2>`, in small caps and the accent ink. A very long word wraps anywhere.

| Data attribute | Description |
| --- | --- |
| data-slot | `"paper-title"`. |

### PaperSubtitle

The issuing body, a `<p>` in italics under the title.

| Data attribute | Description |
| --- | --- |
| data-slot | `"paper-subtitle"`. |

### PaperCaption

A line of small print under the title (a jurisdiction, a form number), a `<p>`. Several stack tight.

| Data attribute | Description |
| --- | --- |
| data-slot | `"paper-caption"`. |

### PaperHeaderAside

The column on the right of the letterhead, a `<div>`, for `PaperBox`es (a number, a status).

| Data attribute | Description |
| --- | --- |
| data-slot | `"paper-header-aside"`. |

### PaperBox

A boxed field with its label on top, a `<div>`: a reference number, a status, a date.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| label* | React.ReactNode | - | The pre-printed label. |
| children | React.ReactNode | - | The typed-in value. |

| Data attribute | Description |
| --- | --- |
| data-slot | `"paper-box"`, with `"paper-box-label"` and `"paper-box-value"` inside. |

### PaperSection

The band that heads a part of the form ("Parties", "Terms"), an `<h3>`.

| Data attribute | Description |
| --- | --- |
| data-slot | `"paper-section"`. |

### PaperRow

A row of `PaperField`s, a `<div>` ruled underneath.

| Data attribute | Description |
| --- | --- |
| data-slot | `"paper-row"`. |

### PaperField

One labelled cell of a `PaperRow`, a `<div>`. The value is pinned to the bottom, so every value in a row sits on one line when a label wraps.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| label* | React.ReactNode | - | The pre-printed label. |
| children | React.ReactNode | - | The typed-in value, on one line, ending in an ellipsis when it runs long. |
| grow | number | 1 | The field's share of the row, a flex grow factor. |

| Data attribute | Description |
| --- | --- |
| data-slot | `"paper-field"`, with `"paper-field-label"` and `"paper-field-value"` inside. |

### PaperText

Running copy (terms, a narrative), a `<div>`, justified, keeping the line breaks it was typed with.

| Data attribute | Description |
| --- | --- |
| data-slot | `"paper-text"`. |

### PaperTable

A ruled `<table>`. Compose a plain `thead`/`tbody` with `PaperTableHead` and `PaperTableCell`.

| Data attribute | Description |
| --- | --- |
| data-slot | `"paper-table"`. |

### PaperTableHead

A column heading, a `<th>`, printed like a field label.

| Data attribute | Description |
| --- | --- |
| data-slot | `"paper-table-head"`. |

### PaperTableCell

A typed-in cell, a `<td>`.

| Data attribute | Description |
| --- | --- |
| data-slot | `"paper-table-cell"`. |

### PaperNote

What a section says when it has nothing to show ("No evidence logged."), a `<p>`.

| Data attribute | Description |
| --- | --- |
| data-slot | `"paper-note"`. |

### PaperChecklist

A list of printed check boxes, a `<ul>`.

| Data attribute | Description |
| --- | --- |
| data-slot | `"paper-checklist"`. |

### PaperCheckItem

One line of a `PaperChecklist`, an `<li>`: the box, ticked or not, and its text. The box is decorative; the item's text carries the meaning.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| checked | boolean | false | Ticks the printed box. |

| Data attribute | Description |
| --- | --- |
| data-slot | `"paper-check-item"`, with `"paper-check-box"` on the box. |
| data-checked | Present when `checked`. |

### PaperSignatures

The row of signature blocks, side by side, a `<div>`.

| Data attribute | Description |
| --- | --- |
| data-slot | `"paper-signatures"`. |

### PaperSignature

One signature block, a `<div>`: its label, the mark over a line, and the name and date under it.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| label | React.ReactNode | - | What the line is for ("Signature of the issuer"), above it. |
| name | React.ReactNode | - | Who signs, printed under the line. |
| date | React.ReactNode | - | The date, printed under the line at the right. |
| children | React.ReactNode | - | The mark above the line: an `img`, a `Signature`, a typed name, or a `SignaturePad` with `absolute inset-0`. Empty, the line waits to be signed. |

| Data attribute | Description |
| --- | --- |
| data-slot | `"paper-signature"`, with `"paper-signature-label"`, `"paper-signature-mark"` and `"paper-signature-meta"` inside. |

### PaperFooter

The strip at the foot of the sheet, a `<footer>`: the form's small print, spread edge to edge.

| Data attribute | Description |
| --- | --- |
| data-slot | `"paper-footer"`. |

## FAQ

### Paper or Card?

A Card is part of the app: it follows the theme, reflows with the layout and holds controls. Paper is a document the app shows: it keeps one layout at every size, stays light in a dark theme and reads as something printed, signed and filed.

### Why does the sheet shrink instead of reflowing?

Because a form that reflows stops looking like the form. A row of fields that wraps, a title that breaks in two or a signature block that drops under its neighbour all read as a broken page. Scaling the whole sheet keeps the layout the document was designed with, and the font-size scale lays it out again at the new size, so the text stays sharp.

### Why font-size and not transform or zoom?

A transform leaves the layout at full size and only paints it smaller, and zoom changes what the box and pointer coordinates mean, so a Signature Pad set into the sheet would draw away from the pen. With every length in em, shrinking the sheet's font size makes it genuinely smaller, and getBoundingClientRect() tells the truth.

### Why is it light in a dark theme?

Paper is white. The sheet scopes itself .light, so its ink and grounds are the light theme's tokens on any page, and the inks you derive from them (--paper-accent and the rest) stay printable.

### How do I let a long value wrap instead of truncating?

Override the value's white space on that field: `className="[&_[data-slot=paper-field-value]]:whitespace-normal"`. Values sit on one line by default so a row of fields keeps one baseline.

### Does it paginate?

No. Paper draws one sheet, as long as its content. To split a long document across pages, render one Paper per page.

---

<!-- 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Installation

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

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

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

Pro: `ranking` comes with a [Koala UI Pro license](https://www.koalaui.com/pro). Its source is not published in these docs.

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Anatomy

```tsx
import {
  Ranking,
  RankingHeader,
  RankingTitle,
  RankingDescription,
  RankingAction,
  RankingList,
  RankingItem,
  RankingRank,
  RankingMedia,
  RankingContent,
  RankingLabel,
  RankingMeta,
  RankingValue,
  RankingBar,
} from "@/components/ui/ranking"

<Ranking>
  <RankingHeader>
    <div>
      <RankingTitle />
      <RankingDescription />
    </div>
    <RankingAction />
  </RankingHeader>
  <RankingList>
    <RankingItem>
      <RankingRank />
      <RankingMedia />
      <RankingContent>
        <RankingLabel />
        <RankingMeta />
        <RankingBar />
      </RankingContent>
      <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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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 ink is the hover: the bar under the pointer lights up, and a bar that takes keyboard focus as a tooltip trigger lights in the focus color. Nothing is lit at rest. `highlight` on a `RankingBar` pins ink on one bar, for a row that really is selected; it works in the other layouts too.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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 ink.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## API reference

### Ranking

The card root; owns the surface, layout and default bar tone, and shares them with every part through context. Forwards all native `<div>` props. Every part accepts `className`, merged last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| variant | "default" \| "outline" \| "elevated" | "default" | `default` is an edge ring with a soft shadow, `outline` a full-strength ring with no shadow, `elevated` the card fill with a lifted shadow. |
| layout | "list" \| "bars" \| "inline" | "list" | `list` stacks rows with a bar under the label, `bars` is a vertical bar chart, `inline` a horizontal chart with the bar beside a fixed name column. |
| tone | "blue" \| "brand" \| "neutral" \| "success" \| "warning" \| "destructive" \| "info" | - | The hue every `RankingBar` takes unless it sets its own. Unset, `list` and `bars` paint blue and `inline` rests neutral. |
| asChild | boolean | false | Render the root onto your own child element instead of a `div`. |

### RankingHeader

The top row holding the title block and an action. Forwards all native `<div>` props.

### RankingTitle

The card title. Forwards all native `<div>` props.

### RankingDescription

Muted supporting text under the title. Forwards all native `<div>` props.

### RankingAction

A trailing slot in the header (a menu, a link). Forwards all native `<div>` props.

### RankingList

A semantic `<ol>`, so assistive tech announces the positions. Forwards all native `<ol>` props.

### RankingItem

One row, an `<li>`. Forwards all native `<li>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| interactive | boolean | false | Adds a pointer, hover wash and focus ring for a clickable row; wire `onClick` yourself. Nested chips and the bar track step down to the card surface on hover. |

### RankingRank

The square, tabular position chip. Forwards all native `<span>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| highlight | boolean | false | A filled primary chip for the leader; it keeps the fill through the row's hover wash. |

### RankingMedia

A tinted icon tile for non-people rows (products, countries); use an Avatar for people. Renders an `aria-hidden` `<div>`.

### RankingContent

The flexible middle column holding the label, meta and a `list` bar. Forwards all native `<div>` props.

### RankingLabel

The row's name, truncated to one line. Forwards all native `<div>` props.

### RankingMeta

A muted, truncated second line under the label. Forwards all native `<div>` props.

### RankingValue

The row's tabular figure. Forwards all native `<div>` props.

### RankingBar

The relative-share bar: a track `<div>` with a fill whose length rides a CSS variable. Forwards all native `<div>` props except `children`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| value* | number | - | Share of the leader, 0 to 100 (clamped). Drives the fill and animates on change. |
| tone | "blue" \| "brand" \| "neutral" \| "success" \| "warning" \| "destructive" \| "info" | - | This bar's hue, the Chart's series names. Falls back to the root's `tone`, then the layout's default. In `inline` the hovered bar still lights up in ink. |
| highlight | boolean | false | Pins this bar in ink; wins over `tone`. |

| CSS variable | Description |
| --- | --- |
| --ranking-bar | The fill's width (or height in `bars`) as a percentage, set from `value`. |

## 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` (an edge ring plus a soft shadow), `outline` (a full-strength ring, no shadow), or `elevated` (the card fill with a lifted shadow, no ring). Ranking is a dashboard widget, so its spacing is fixed compact, there's no density knob to tune.

---

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

# Receipt

A slip of thermal paper: a till receipt, a parking ticket, the printout of a breathalyzer. Cream paper in every theme with a torn edge, a monospace print face, dashed rules, label and value rows, a headline figure, a verdict stamp and the small print, each part optional.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Installation

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

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

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

Pro: `receipt` comes with a [Koala UI Pro license](https://www.koalaui.com/pro). Its source is not published in these docs.

## Usage

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Anatomy

Every part is optional but the paper, and they print in the order you write them. The header and the footer bring their own strong rule; a `ReceiptRule` that would double one of them, or lands at either end of the slip, folds away.

```tsx
import {
  Receipt,
  ReceiptFigure,
  ReceiptFooter,
  ReceiptHeader,
  ReceiptNote,
  ReceiptRow,
  ReceiptRule,
  ReceiptStamp,
  ReceiptSubtitle,
  ReceiptTitle,
} from "@/components/ui/receipt"

<Receipt size="md" edge="bottom">
  {/* The heading, ruled off underneath */}
  <ReceiptHeader>
    <ReceiptTitle />
    <ReceiptSubtitle />
  </ReceiptHeader>

  {/* The body: rows, rules, a figure, a verdict */}
  <ReceiptRow label="Label:">Value</ReceiptRow>
  <ReceiptRule />
  <ReceiptFigure caption="Result" unit="Unit">0.00</ReceiptFigure>
  <ReceiptStamp tone="success" />
  <ReceiptNote />

  {/* The brand line, ruled off above */}
  <ReceiptFooter />
</Receipt>
```

## Fingerprint record

A code reads better a step smaller than a reading: `size="md"` on the figure. A long value, like this one, breaks anywhere rather than running off the paper.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Shop receipt

Line items are rows too: a long item name wraps inside its own share of the line and the price keeps the right edge. A total is a row set larger, with a class. Torn at both ends, the slip reads as cut from the roll.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Sizes

`md` (the default, 20rem) is the ticket a dialog shows. `sm` (14rem) is the stub a handheld device feeds out, printed a step smaller. Its rows can run inline, the value straight after the label, with `layout="inline"`; a `tone` on a row prints its value bold in that ink.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Edges

`edge` picks the torn ends: `bottom` (the default, the slip as it leaves the printer), `top`, `both` (cut from the roll) or `none`. The teeth have a fixed size, `--receipt-tooth` (2em), and a whole number of them fits any width. The torn side keeps its copy clear of them.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Tones

`ReceiptStamp`, `ReceiptFigure` and `ReceiptRow` take a `tone`: `default` (the ink), `success`, `warning`, `destructive` and `info`. On the paper they are the light theme's `-strong` inks, legible on cream in any theme; the stamp adds the soft tint and edge of a Badge. Pick the tone by what the verdict means, not by its word: a positive breath test is `destructive`.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## In a dialog

To show a printed ticket on its own, strip the dialog to nothing and let the slip float on the scrim: the content goes transparent, unpadded and as wide as the receipt. The title stays for screen readers, and a white button under the slip closes it.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Print face

Koala has no dot-matrix face, so the receipt prints in the mono token, `font-mono`. Every size inside it is in `em` of the receipt's own font size, so a face is swapped, and resized, on the root alone. A pixel face such as VT323 has small glyphs for its size: set it one step up, `text-base` on `md` and `text-sm` on `sm`. Name the family with `font-[family-name:…]` so it replaces `font-mono` instead of sitting beside it. The width stays in `rem`.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Re-tinting

The receipt scopes itself `.light.cream`, so its ground and inks are the cream theme's on any page, and keeps its own roles on top of them. Set one on the root to re-tint a slip: `--receipt-paper`, `--receipt-ink`, `--receipt-muted`, `--receipt-faint`, `--receipt-rule`, `--receipt-rule-strong`, and `--receipt-tooth` for the size of the teeth.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Old engines

Receipt holds in old embedded Chromium too, the kind a desktop or game shell ships (Chromium 10x): no container queries, no `:has()` and no standalone `translate` or `scale`. The torn edge is a mask written both prefixed and unprefixed (the unprefixed `mask` only arrived in Chromium 120), made of conic gradients, which Chromium has drawn since 69. To slide a ticket out of a device, move the root with `[transform:translateY(…)]` rather than `translate-y-*`, which compiles to the standalone `translate` property.

## API reference

### Receipt

The slip, an `<article>` scoped `.light.cream`, with the paper inside it (a `<div>`). Every `article` prop is forwarded. The parts read the receipt's size from context, so they render inside a `Receipt` only; each forwards its element's props and merges `className` last. `receiptVariants` is the recipe and `ReceiptTone` the tone type.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| size | "sm" \| "md" | "md" | The width and the print size: `sm` is the 14rem stub a handheld device feeds out (`text-xs`), `md` the 20rem ticket a dialog shows (`text-sm`). |
| edge | "none" \| "top" \| "bottom" \| "both" | "bottom" | Which ends of the paper are torn. |
| className | string | - | Merged last on the root, where the face, the print size, the width and the `--receipt-*` roles live. A height or a min-height stretches the paper with it. |

| Data attribute | Description |
| --- | --- |
| data-slot | `"receipt"` on the root, `"receipt-paper"` on the paper. |
| data-size | `"sm"` or `"md"`. |
| data-edge | The torn ends. |

| CSS variable | Description |
| --- | --- |
| --receipt-paper | The paper's ground. |
| --receipt-ink | The print. |
| --receipt-muted | Subtitles, captions, units and the small print. |
| --receipt-faint | The footer's brand line. |
| --receipt-rule | The light 1px rule. |
| --receipt-rule-strong | The 2px rule of the header and the footer, and the default stamp's edge. |
| --receipt-tooth | The width of one tooth of the torn edge (`2em`). |

### ReceiptHeader

The heading block, a `<header>`: a logo, the title and the subtitle, centred and ruled off underneath with the strong rule. Last on the paper, it drops the rule.

| Data attribute | Description |
| --- | --- |
| data-slot | `"receipt-header"`. |

### ReceiptTitle

What the slip is ("Breath test", the shop's name), an `<h2>` in capitals, kept in the print face.

| Data attribute | Description |
| --- | --- |
| data-slot | `"receipt-title"`. |

### ReceiptSubtitle

A line under the title, a `<p>`: the issuer, an address, the kind of test.

| Data attribute | Description |
| --- | --- |
| data-slot | `"receipt-subtitle"`. |

### ReceiptRule

A dashed rule across the paper, a Radix Separator. One at either end of the paper, right under the header or next to another rule folds away.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| variant | "light" \| "strong" | "light" | 1px, or the 2px rule of the header and footer. |
| decorative | boolean | true | Printing, not structure (`role="none"`). Pass `false` to expose it as a separator. |
| orientation | "horizontal" \| "vertical" | "horizontal" | Forwarded to Radix Separator. |

| Data attribute | Description |
| --- | --- |
| data-slot | `"receipt-rule"`. |
| data-variant | `"light"` or `"strong"`. |

### ReceiptRow

One line of the slip, a `<div>`: a label and its value.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| label* | React.ReactNode | - | What the value is ("Subject:", an item), in bold. |
| children | React.ReactNode | - | The value. It wraps when it runs long, breaking a long code anywhere. |
| layout | "spread" \| "inline" | "spread" | `spread` sets the value at the end of the line, dropping under the label when the two do not fit side by side; `inline` runs it on after the label. |
| tone | "default" \| "success" \| "warning" \| "destructive" \| "info" | "default" | Prints the value bold in that status ink. |

| Data attribute | Description |
| --- | --- |
| data-slot | `"receipt-row"`, with `"receipt-row-label"` and `"receipt-row-value"` inside. |
| data-layout | `"spread"` or `"inline"`. |

### ReceiptFigure

The headline figure, a `<div>`, centred: a caption, the number and its unit.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| children | React.ReactNode | - | The figure itself. |
| caption | React.ReactNode | - | The line above it ("Result"), in small capitals. |
| unit | React.ReactNode | - | The line under it ("mg/L of breath"). |
| size | "md" \| "lg" | "lg" | 3em for a short reading, 1.875em for a code that runs longer. |
| tone | "default" \| "success" \| "warning" \| "destructive" \| "info" | "default" | Prints the figure in a status ink. |

| Data attribute | Description |
| --- | --- |
| data-slot | `"receipt-figure"`, with `"receipt-figure-caption"`, `"receipt-figure-value"` and `"receipt-figure-unit"` inside. |
| data-tone | The tone. |

### ReceiptStamp

The verdict ("Positive", "Paid"), a `<div>` boxed and in capitals. A leading icon sits at 1em, inline with the words.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| tone | "default" \| "success" \| "warning" \| "destructive" \| "info" | "default" | The verdict's ink and tint. `default` is an outlined box in the ink. |

| Data attribute | Description |
| --- | --- |
| data-slot | `"receipt-stamp"`. |
| data-tone | The tone. |

### ReceiptNote

The small print, a `<div>`: plain text, or several `p`s, which stack.

| Data attribute | Description |
| --- | --- |
| data-slot | `"receipt-note"`. |

### ReceiptFooter

The brand line at the foot, a `<footer>`, widely spaced and ruled off above. Several children sit in a row. First on the paper or after a `ReceiptRule`, it drops its own rule.

| Data attribute | Description |
| --- | --- |
| data-slot | `"receipt-footer"`. |

## FAQ

### Receipt or Paper?

Paper is a document: a contract or a report on a white sheet, in a serif, laid out at one width and scaled as a whole. Receipt is a slip from a printer: a narrow column of monospace lines on cream thermal paper with a torn edge. Use Receipt for what a till, a meter or a handheld device prints.

### Why is it cream in a dark theme?

Because thermal paper is. The receipt scopes itself .light.cream, so its ground and inks are the cream theme's on any page. .light comes first so the status inks are the light theme's too: .cream alone only swaps the neutrals and would inherit a dark page's bright greens and reds.

### Why does the shadow follow the teeth?

The torn edge is a mask on the paper, and a mask cuts away anything drawn outside it, a box-shadow or a ring included. The shadow is a drop-shadow filter on the root around it, which is drawn from the masked paper, teeth and all.

### How do I make a row's label normal weight?

Target the label slot from the row or the receipt: `className="[&_[data-slot=receipt-row-label]]:font-normal"`.

### Does it animate out of a printer?

No. The receipt is the paper; the device around it owns the motion. Clip the slot it comes out of with overflow-hidden and move the receipt with a transform transition.

---

<!-- 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Installation

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

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

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

Pro: `stat` comes with a [Koala UI Pro license](https://www.koalaui.com/pro). Its source is not published in these docs.

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

```tsx
import {
  StatGroup,
  Stat,
  StatHeader,
  StatLabel,
  StatIcon,
  StatValue,
  StatFooter,
  StatTrend,
  StatCaption,
  StatSparkline,
} from "@/components/ui/stat"

<StatGroup>
  <Stat>
    <StatHeader>
      <StatLabel />
      <StatIcon />
    </StatHeader>
    <StatValue />
    <StatFooter>
      <StatTrend />
      <StatCaption />
    </StatFooter>
    <StatSparkline data={[...]} />
  </Stat>
</StatGroup>
```

## 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 | 5 | 6`); it steps down gracefully on narrow screens.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

Inside a pane that already draws its own borders (a header band, a split view), `variant="plain"` drops the frame: no ring, radius, or shadow, only the dividers between tiles. The pane’s rules frame the band, so no edge is drawn twice and no rounded corner meets a straight line.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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`.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## API reference

### Stat

The tile root: owns the surface, variant and density, and shares them with its parts through context. Forwards all native `<div>` props; every part accepts `className`, merged last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| variant | "default" \| "outline" \| "elevated" \| "plain" | "default" | `default` is an edge ring plus a soft lift, `outline` the bare ring, `elevated` a card fill with a shadow, `plain` no frame or padding at all. |
| density | "compact" \| "comfortable" | "compact" | Padding, gap, value size and icon tile. Inherits the nearest `DensityProvider` when omitted. |
| interactive | boolean | - | Adds the pointer, a hover lift and a focus ring, for a tile that is a link or button. |
| asChild | boolean | false | Renders onto the child element via Radix `Slot` (e.g. an `<a>`). |

### StatGroup

Fuses a row of tiles into one segmented surface with hairline dividers; nested `Stat`s shed their own chrome. Forwards all native `<div>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| variant | "default" \| "outline" \| "elevated" \| "plain" | "default" | The group's frame, mirroring `Stat`'s variants. `elevated` sets the card as the tiles' ground; `plain` drops the frame and keeps only the dividers, for a band inside a pane that already has its own borders. |
| columns | 2 \| 3 \| 4 \| 5 \| 6 | 4 | Columns at the widest breakpoint; steps down to one, then two, on narrower screens. |
| asChild | boolean | false | Renders onto the child element via Radix `Slot`. |

| CSS variable | Description |
| --- | --- |
| --surface | Set to `var(--card)` by `elevated`; grouped tiles paint it as their opaque fill. |

### StatHeader

A row that sets the label on the left and an icon or action on the right. Forwards all native `<div>` props.

### StatLabel

The metric's name, muted and medium weight. Renders inside a `Stat` or on its own. Forwards all native `<div>` props.

### StatIcon

A tinted tile for a glyph, hidden from assistive tech. Forwards all native `<div>` props.

### StatValue

The headline figure in the display face with `tabular-nums`, sized by density. Renders inside a `Stat` or on its own at the ambient density. Forwards all native `<div>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| countUp | boolean | false | Counts a string figure (`"$4.2M"`, `"74%"`) up from zero each time it scrolls into view, keeping its prefix, suffix and format. Shows the final figure under reduced motion. |

### StatFooter

A row that pairs the trend with the caption. Forwards all native `<div>` props.

### StatTrend

The trend chip: an arrow and a soft tone. Never wraps or shrinks. Forwards all native `<span>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| direction | "up" \| "down" \| "neutral" | "up" | The arrow, and by default the tone: `up` green, `down` red, `neutral` muted. |
| inverted | boolean | false | Flips the tone without flipping the arrow, for metrics where down is good (churn, refunds). |

| Data attribute | Description |
| --- | --- |
| data-direction | `up`, `down` or `neutral`. |

### StatCaption

The muted line that frames the figure (a period, a comparison). Forwards all native `<div>` props.

### StatSparkline

A chromeless trend built on `Chart`, bleeding to the tile's bottom and side edges. Paints in `currentColor`, so set the hue with a text utility. Must sit inside a `Stat`; forwards native `<div>` props except `children`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| data* | number[] | - | The series, drawn as a soft area under a line. |
| strokeWidth | number | 2 | Line stroke width in px. |
| tooltip | boolean | false | Shows a gliding tooltip with each point's value on hover. |
| valueFormatter | (value: number) => string | - | Formats each point's value in the tooltip. |

## 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>
  )
}
```

## Anatomy

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

<Accordion>
  <AccordionItem>
    <AccordionTrigger />
    <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. `compact` is the default, tight row height and inset for dense application UI; `comfortable` opens it up for marketing pages. 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>
```

## API reference

### Accordion

The root, over Radix `Accordion.Root`: forwards all its props (`disabled`, `orientation`, `dir` among them). Every part accepts `className`, merged last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| type* | "single" \| "multiple" | - | Whether one row or any number of rows can be open. |
| collapsible | boolean | false | With `type="single"`, lets the open row close again. |
| value | string \| string[] | - | The open row (or rows, an array with `type="multiple"`), controlled. |
| defaultValue | string \| string[] | - | The row or rows open on first render, uncontrolled. |
| onValueChange | (value: string \| string[]) => void | - | Called when a row opens or closes. |
| variant | "minimal" \| "card" \| "separated" \| "pill" \| "board" | "minimal" | The chrome: a hairline list, one contour, one card per item, chips that flood open, or a grid of tiles. |
| density | "comfortable" \| "compact" | "compact" | Row height and content inset. Falls back to the nearest `DensityProvider`, then `compact`. |
| size | "md" \| "lg" | "md" | The type scale. `lg` is the landing-page FAQ: an 18px semibold question over a 16px answer. |
| marker | "caret" \| "plus" | "caret" | The disclosure mark: a chevron that flips 180°, or a plus that turns 45° into an ✕. |
| iconPosition | "trailing" \| "leading" | "trailing" | Puts the mark after or before the question, in DOM order, so focus and reading order follow. |

| Data attribute | Description |
| --- | --- |
| data-orientation | `"vertical"` or `"horizontal"`, from Radix. |

### AccordionItem

One row, over Radix `Accordion.Item`: forwards all its props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| value* | string | - | Identifies the row in `value` and `defaultValue`. |
| disabled | boolean | false | Stops the row from opening or closing. |

| Data attribute | Description |
| --- | --- |
| data-state | `"open"` or `"closed"`. |
| data-disabled | Present when the row is disabled. |

### AccordionTrigger

The question: a `<button>` inside a Radix `Accordion.Header` (`<h3>`). Forwards all Radix `Accordion.Trigger` props and draws the mark the root's `marker` picks.

| Data attribute | Description |
| --- | --- |
| data-state | `"open"` or `"closed"`. Drives the turn of the mark. |
| data-disabled | Present when the row is disabled. |

### AccordionContent

The answer, over Radix `Accordion.Content`: forwards all its props (`forceMount` among them). `className` lands on the padded inner `<div>`, not the animated wrapper, so the height tween stays smooth.

| Data attribute | Description |
| --- | --- |
| data-state | `"open"` or `"closed"`. Keys the open and close animations. |

| CSS variable | Description |
| --- | --- |
| --radix-accordion-content-height | The measured height of the answer, read by the open and close keyframes. |
| --radix-accordion-content-width | The measured width of the answer. |

## 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 change the density of the accordion?

`compact` is the default with no `DensityProvider` above it, and `density="comfortable"` opens up the row height and content inset. 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 (where `className` lands), so add spacing through `AccordionContent` rather than restyling the animated 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## A workflow at a glance

An episode moves from interview review to release in a series of small handoffs. Activity Feed keeps the full sequence readable; a compact phase bar makes the total production time easy to scan.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Installation

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

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

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

Pro: `activity-feed` comes with a [Koala UI Pro license](https://www.koalaui.com/pro). Its source is not published in these docs.

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Anatomy

```tsx
import {
  ActivityFeed,
  ActivityGroup,
  ActivityGroupLabel,
  ActivityItem,
  ActivityMarker,
  ActivityIcon,
  ActivityContent,
  ActivityHeader,
  ActivityActor,
  ActivityTime,
  ActivityBody,
  ActivityCard,
  ActivityAttachments,
  ActivityImage,
  ActivityActions,
} from "@/components/ui/activity-feed"

<ActivityFeed>
  <ActivityGroup>
    <ActivityGroupLabel />
    <ActivityItem>
      <ActivityMarker>
        <ActivityIcon />
      </ActivityMarker>
      <ActivityContent>
        <ActivityHeader>
          <ActivityActor />
          <ActivityTime />
        </ActivityHeader>
        <ActivityBody />
        <ActivityCard />
        <ActivityAttachments>
          <ActivityImage />
        </ActivityAttachments>
      </ActivityContent>
      <ActivityActions />
    </ActivityItem>
  </ActivityGroup>
</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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Markers

The marker carries the type of event. `ActivityIcon` is a soft tinted tile: pass a Koala 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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).

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Unread

Mark an event as new to this reader with `unread` on `ActivityItem`: the header comes up to full-strength text and an ink 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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. `compact` is the default; `comfortable` opens it up for a roomier inbox. Set it per-feed or for a whole subtree with `DensityProvider`.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## API reference

### ActivityFeed

The root, a semantic `<ol>` that owns density and the connecting rail. Forwards all native `<ol>` props. Every part accepts `className`, merged last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| density | "comfortable" \| "compact" | "compact" | Per-event rhythm and the gap to the rail. Falls back to the nearest `DensityProvider`, then `compact`. |
| divided | boolean | false | A hairline rule between events instead of the rail (the audit-log reading). |
| connector | boolean | true | Draws the vertical rail between markers. Ignored when `divided` is set. |

### ActivityGroup

A run of events under one heading, such as a day. Renders an `<li>` of the feed holding its own `<ol>`, named by its label. Forwards all native `<li>` props.

### ActivityGroupLabel

The small heading of a group ("Today"), first in the group and droppable. Renders an `<li>` that becomes the accessible name of the group's list. Forwards all native `<li>` props.

### ActivityItem

One event, an `<li>`. Forwards all native `<li>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| asChild | boolean | false | Renders the row as its single child (an `<a>` or `<button>`) inside the `<li>`. Implies `interactive`; do not pair with `ActivityActions`. |
| interactive | boolean | false | Adds the hover fill, press and focus ring. Defaults to `true` when `asChild` is set. |
| unread | boolean | false | Marks the event as new: full-strength header text plus an ink dot (and an sr-only "Unread"). |

### ActivityMarker

The rail column. Holds an `ActivityIcon`, `ActivityDot` or `Avatar` and appends the rail itself, closed on the last event. Forwards all native `<div>` props.

### ActivityIcon

A 28px tinted tile marker. Pass a Koala glyph as children. Forwards all native `<div>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| tone | "default" \| "brand" \| "success" \| "warning" \| "info" \| "destructive" \| "purple" \| "pink" \| "teal" \| "orange" | "default" | The soft tint, matched to the kind of event. |

### ActivityDot

A low-emphasis dot marker for minor events, in the same footprint as `ActivityIcon`. Forwards all native `<div>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| tone | "default" \| "brand" \| "success" \| "warning" \| "info" \| "destructive" \| "purple" \| "pink" \| "teal" \| "orange" | "default" | The solid color of the dot. |

### ActivityContent

The text column of an event. Forwards all native `<div>` props.

### ActivityHeader

The wrapping first line: actor, verb, target, time. Forwards all native `<div>` props.

### ActivityActor

The person or thing that acted, a `<span>`. Forwards all native `<span>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| asChild | boolean | false | Renders the actor as its child element, such as a profile link. |

### ActivityTime

The muted, tabular timestamp, a real `<time>`. Pass an ISO `dateTime` and a relative label as children. Forwards all native `<time>` props.

### ActivityBody

Secondary text under the header. Forwards all native `<div>` props.

### ActivityCard

A nested surface for quoted content (a comment, a review), on the concentric radius. Forwards all native `<div>` props.

### ActivityAttachments

A vertical stack for the payload: `FileCard` rows and `ActivityImage` rows. Forwards all native `<div>` props.

### ActivityImage

A 56px image thumbnail with the image-outline ring. `className` sizes the clipping wrapper; every other prop goes to the native `<img>`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| alt* | string | - | The image's alternative text. |

### ActivityActions

Trailing controls for one event, a sibling of `ActivityContent` that rides the first line. Forwards all native `<div>` props.

## 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 Koala 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 variant="ghost">Discard</Button>
      <Button>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>
)}
```

## API reference

### Alert

The root, a `<div role="alert">` that sets the tone for every part. Forwards all native `<div>` props. Every part accepts `className`, merged last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| variant | "default" \| "info" \| "success" \| "warning" \| "destructive" | "default" | The semantic tone: the icon color and the icon `AlertIcon` picks on its own. |
| size | "sm" \| "md" | "md" | Padding, gap, type and icon size. |
| onDismiss | () => void | - | Renders a close button that calls it. You own the visibility state. |
| dismissLabel | string | "Dismiss" | The accessible label of the close button. |

| CSS variable | Description |
| --- | --- |
| --surface | Read as the fill, falling back to `--background`, so the alert takes the ground it sits on. |

### AlertIcon

The leading icon column, a sibling of `AlertContent`. Left empty, it draws the icon of the variant; pass children for a custom one. Forwards all native `<div>` props.

### AlertContent

The text column holding the title, description and actions. Forwards all native `<div>` props.

### AlertTitle

The heading line, a `<p>`. Forwards all native `<p>` props.

### AlertDescription

The body text, a `<p>`. Forwards all native `<p>` props.

### AlertActions

A button row, last inside `AlertContent`. Sizes every control inside it through the control-size context. Forwards all native `<div>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| size | "sm" \| "md" \| "lg" | "sm" | The size the nested buttons take. |

| Data attribute | Description |
| --- | --- |
| data-control-size | The `size` the row hands its controls. |

## Anatomy

```tsx
import {
  Alert,
  AlertIcon,
  AlertContent,
  AlertTitle,
  AlertDescription,
  AlertActions,
} from "@/components/ui/alert"

<Alert>
  <AlertIcon />
  <AlertContent>
    <AlertTitle />
    <AlertDescription />
    <AlertActions />
  </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 icon color and, when you render an empty `AlertIcon`, the auto-selected Koala icon. The color comes from one 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>
  )
}
```

## Anatomy

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

<Avatar>
  <AvatarImage />
  <AvatarFallback />
  <AvatarStatus />
  <AvatarBadge />
</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" variant="ghost" className="flex-1">Message</Button>
    <Button size="sm" className="flex-1">Follow</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-3 mt-1 flex gap-0.5">
          <Button variant="ghost" size="sm">Like</Button>
          <Button variant="ghost" size="sm">Reply</Button>
        </div>
      </ActivityContent>
    </ActivityItem>
  ))}
</ActivityFeed>
```

## API reference

### Avatar

The root, over Radix `Avatar.Root` (a `<span>`): forwards all its props, and its size and shape flow to every part. Also exported as `AvatarRoot`. Every part accepts `className`, merged last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| size | "xs" \| "sm" \| "md" \| "lg" \| "xl" | "md" | 24, 32, 40, 48 or 64px. Also scales the status dot, the badge and the initials cap. |
| shape | "circle" \| "square" | "circle" | The silhouette; the image and fallback inherit its radius. |
| color | "default" \| "brand" \| "purple" \| "pink" \| "teal" \| "orange" | "default" | Tints the initials fallback only. An image covers it. |

### AvatarImage

The photo, over Radix `Avatar.Image` (an `<img>` rendered once it loads). Forwards all its props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| src | string | - | The image URL. |
| alt | string | - | The person's name, for assistive tech. |
| onLoadingStatusChange | (status: "idle" \| "loading" \| "loaded" \| "error") => void | - | Called as the image loads or fails. |

### AvatarFallback

The initials or icon shown when there is no image or it fails, over Radix `Avatar.Fallback`. Forwards all its props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| maxInitials | number | 1 at xs and sm, 2 above | Caps how many characters of a string child render. Any other node renders as is. |
| delayMs | number | - | Waits before showing, to avoid a flash of initials while a valid image loads. |

### AvatarStatus

A presence dot on a corner, ringed off the avatar. Forwards all native `<span>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| variant | "online" \| "away" \| "busy" \| "offline" | "online" | The dot color, from the status tokens. |
| position | "bottom-right" \| "top-right" \| "bottom-left" \| "top-left" | "bottom-right" | The corner the dot sits on. |

### AvatarBadge

A corner coin for a small logo or mark (an `<img>` or icon inside). Forwards all native `<span>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| position | "bottom-right" \| "top-right" \| "bottom-left" \| "top-left" | "bottom-right" | The corner the badge sits on. |
| shape | "circle" \| "square" | "circle" | The coin shape, independent of the avatar's. |

## 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 stacks its `Avatar` children with overlap, a background ring and a hover lift, then appends the `+N` chip. Children share one gliding tooltip (a `TooltipGroup`). Forwards all native `<div>` props; accepts `className`, merged last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| size | "xs" \| "sm" \| "md" \| "lg" \| "xl" | "md" | Sizes the overlap and the `+N` chip. Pass the same value you set on the children. |
| max | number | - | Caps the visible avatars; the rest fold into the `+N` chip. |
| total | number | - | The real count when it exceeds the rendered avatars (a server count), so `+N` reflects it. |
| renderOverflow | (overflow: number) => React.ReactNode | - | Replaces the default chip, e.g. with a Tooltip that names the hidden people. |

## 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} />
```

## Custom color

When the color arrives with the data (a dispatch call code with its category hex, a team, a label a user picked), pass it as `color`. The `variant` still picks the treatment: any page-ground tone gives the soft tint, with the label pulled toward the theme's foreground so a pale yellow still reads; `primary` (or `secondary`) gives a solid fill whose ink is chosen from the color itself, near-black on a light fill and white on a dark one; `outline` draws the hairline in the color. With `dot` the dot takes it.

```tsx
{codes.map((c) => (
  <Badge key={c.code} variant="primary" color={c.color}>{c.code}</Badge>
))}
// codes: 10-31 #dc2626 · 10-50 #f97316 · 10-16 #facc15 · 10-60 #a3e635 · 10-91 #e0f2fe · 10-99 #1e3a8a
```

```tsx
<Badge color="#7c3aed">Robbery</Badge>
<Badge color="#facc15">Traffic</Badge>
<Badge color="#0891b2" pill>Medical</Badge>
<Badge variant="outline" color="#dc2626">Shots fired</Badge>
<Badge color="#16a34a" dot>Units free</Badge>
<Badge variant="primary" color="#facc15" pill dot>10-16</Badge>
```

The ink is read from hex (`#rgb`, `#rrggbb`, with or without alpha) and `rgb()`; any other form (a named color, `hsl()`, a `var()`) paints fine but gets white ink, so prefer hex for solid badges. The same choice is exported as `readableInk(color)`, returning `"dark"` or `"light"`, for your own surfaces.

## 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>
```

## API reference

### Badge

A single `<span>` that labels a status, count or category. Forwards all native `<span>` props; accepts `className`, merged last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| variant | "default" \| "primary" \| "secondary" \| "outline" \| "success" \| "warning" \| "info" \| "destructive" \| "purple" \| "pink" \| "teal" \| "orange" \| "overlay" \| "overlayLight" | "default" | The fill: neutral, solid, outline, a soft status tint, a categorical hue, or a dark or light glass for media. |
| size | "sm" \| "md" \| "lg" | "md" | Padding, type and icon size. |
| pill | boolean | false | Fully rounded ends. |
| dot | boolean | - | A leading dot in the current color; the fill gives way to a hairline. Passing a boolean (even `false`) keeps the slot mounted, so flipping it animates. |
| color | string | - | Any CSS color. Paints the variant's treatment from it: a soft tint for the page-ground tones, a solid fill with a computed dark or white ink for `primary` / `secondary`, the hairline for `outline`; the dot takes it as is. Ignored by the `overlay*` fills. The root gets `data-color` and, when solid, `data-ink` (`dark` \| `light`). The exported `readableInk(color)` returns that same pick. |
| onRemove | () => void | - | Renders a trailing dismiss button that calls it. |
| removeLabel | string | "Remove" | The accessible label of the dismiss button. Name the item ("Remove Design"). |
| asChild | boolean | false | Renders the badge styles onto its single child (Radix Slot), such as a link. Ignores `dot` and `onRemove`. |

## 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.

### How do I color a badge from my data without losing contrast?

Pass the color to `color` instead of styling the background yourself. A hard-coded white label on an inline background disappears on yellows and pastels; with `color`, a solid badge (`variant="primary"`) picks near-black or white ink from the color, and the soft treatment pulls the label toward the theme's foreground.

### 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Installation

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

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

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

Pro: `badge-group` comes with a [Koala UI Pro license](https://www.koalaui.com/pro). Its source is not published in these docs.

## 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).

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Overflow chip

The `+N` chip defaults to a small `outline` badge. Match it to the badges it stands in for with `overflowVariant` and `overflowSize`.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## API reference

### BadgeGroup

A `<div>` that lays out its `Badge` children and folds the overflow into a `+N` chip whose tooltip lists them all. Forwards all native `<div>` props; accepts `className`, merged last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| max | number | - | Caps the badges shown inline; the rest collapse into the chip. Omit to show every badge. |
| wrap | boolean | false | Wraps onto several lines instead of holding one. |
| overflowVariant | BadgeProps["variant"] | "outline" | The Badge variant of the `+N` chip. |
| overflowSize | "sm" \| "md" \| "lg" | "sm" | The size of the chip. Match it to the badges it stands in for. |
| overflowLabel | string | "{n} more" | The accessible label of the chip. |
| interactive | boolean | false | Keeps the tooltip open while hovered, for badges with links or a remove button. |
| renderOverflow | (items: React.ReactNode[], hidden: React.ReactNode[]) => React.ReactNode | - | Your own tooltip body, given the full list and the hidden slice. Defaults to the whole list, stacked. |

## 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>
  )
}
```

## Anatomy

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

<Breadcrumb>
  <BreadcrumbList>
    <BreadcrumbItem>
      <BreadcrumbLink />
    </BreadcrumbItem>
    <BreadcrumbSeparator />
    <BreadcrumbItem>
      <BreadcrumbEllipsis />
    </BreadcrumbItem>
    <BreadcrumbSeparator />
    <BreadcrumbItem>
      <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 "koala-icons"
import {
  DropdownMenu, DropdownMenuTrigger, DropdownMenuContent, DropdownMenuItem,
} from "@/components/ui/dropdown-menu"

<BreadcrumbItem>
  <DropdownMenu>
    <DropdownMenuTrigger aria-label="Show more pages" className="...ellipsis + hit area">
      <DotsThree 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>
  )
}
```

## API reference

### Breadcrumb

The landmark, a `<nav aria-label="breadcrumb">`. Forwards all native `<nav>` props. Every part accepts `className`, merged last.

### BreadcrumbList

The wrapping `<ol>` of crumbs. Forwards all native `<ol>` props.

### BreadcrumbItem

One crumb, an `<li>`. Forwards all native `<li>` props.

### BreadcrumbLink

An ancestor the user can go to, an `<a>` with a 40px tall hit area. Forwards all native `<a>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| asChild | boolean | false | Merges the crumb styles onto its single child (Radix Slot), such as a Next.js `<Link>`. |

### BreadcrumbPage

The current location, a `<span aria-current="page">`; the last crumb, not a link. Forwards all native `<span>` props.

### BreadcrumbSeparator

An `aria-hidden` `<li>` between crumbs. Draws a caret unless you pass children (`/`, an icon). Forwards all native `<li>` props.

### BreadcrumbEllipsis

A static "More pages" mark for hidden ancestors, with a 40px hit area. For an openable one, put a `DropdownMenu` in the item instead. Forwards all native `<span>` props.

## 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>
}
```

## Split button

Keep the main action visible and put its alternatives in the attached menu. The two segments stay independent: clicking the label runs the primary action, while the caret opens the menu.

```tsx
import { SplitButton } from "@/components/ui/button"
import { DropdownMenuItem, DropdownMenuSeparator } from "@/components/ui/dropdown-menu"

<SplitButton
  onClick={publish}
  menu={
    <>
      <DropdownMenuItem onSelect={schedule}>Schedule for tomorrow</DropdownMenuItem>
      <DropdownMenuSeparator />
      <DropdownMenuItem onSelect={saveDraft}>Save as draft</DropdownMenuItem>
    </>
  }
>
  Publish
</SplitButton>
```

## 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. At the other end, `xs` (28px) is the dense-UI tier, covered below.

```tsx
<Button size="xs">Extra small</Button>
<Button size="sm">Small</Button>
<Button size="md">Medium</Button>
<Button size="lg">Large</Button>
<Button size="xl">Extra large</Button>
```

### Extra small, for dense UI

`xs` is 28px tall: a table row's actions, the close on a floating card, a toolbar packed into a panel. The label drops to `text-xs` and a glyph to 14px so both keep their proportion to the smaller box, and with `iconOnly` it is a 28 by 28 square. The visual shrinks, the target does not: an invisible pseudo-element keeps the hit area at 40px (44px on touch), the same extender `sm` uses. Like `xl` it is button-only; a field under a container that imposes it resolves it to `sm`. It works with every variant and tone, and on a ButtonGroup.

```tsx
<div className="flex items-center gap-1">
  <Button size="xs" variant="ghost" iconOnly aria-label="Edit">
    <PencilSimple />
  </Button>
  <Button size="xs" variant="destructiveGhost" iconOnly aria-label="Delete">
    <Trash />
  </Button>
  <Button size="xs" variant="ghost" iconOnly aria-label="More actions">
    <DotsThree />
  </Button>
</div>

<Button size="xs" variant="outline">
  <Plus /> Add row
</Button>

<Button size="xs" variant="ghost" iconOnly aria-label="Close">
  <X />
</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 `xs` and `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>
```

### Its own tooltip

An `iconOnly` button shows its `aria-label` (or `tooltip`) as a hint on hover and keyboard focus. `tooltip={false}` turns it off. Wrap the button in your own `Tooltip`, directly or through an `asChild` trigger like `PopoverTrigger`, and the built-in hint stands down: one bubble, the one you wrote.

```tsx
<Tooltip content={<>Search <Kbd size="sm">⌘K</Kbd></>}>
  <Button iconOnly aria-label="Search">
    <MagnifyingGlass />
  </Button>
</Tooltip>
```

### 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>
```

## API reference

### Button

A single `<button>` (or its child with `asChild`). Forwards all native `<button>` props; accepts `className`, merged last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| variant | "primary" \| "secondary" \| "neutral" \| "outline" \| "ghost" \| "overlay" \| "destructive" \| "destructiveGhost" \| "link" | "primary" | The fill. `primary` is the brand action; `destructive` is a soft red tint, `destructiveGhost` its chrome-less twin. |
| size | "xs" \| "sm" \| "md" \| "lg" \| "xl" | "md" | 28, 32, 36, 40 or 44px tall (xs is the dense-UI tier: row actions, a floating card's close). Unset, it follows `density`, then the container's tier, then `md`. |
| density | "comfortable" \| "compact" | - | Picks the default `size` only (compact is `sm`, comfortable is `md`). A Button ignores an ambient `DensityProvider`. |
| iconOnly | boolean | false | A square that tracks the size, auto-wrapped in a Tooltip from `aria-label`. Warns in development without an accessible name. |
| tone | "default" \| "onMedia" \| "onInverse" | "default" | Re-points fills and focus ring for a brand band or photo (`onMedia`, fixed white) or a `bg-foreground` band (`onInverse`). |
| loading | boolean | false | A centered spinner, `aria-busy` and disabled, with the label's width kept. Ignored with `asChild`. |
| swapKey | React.Key | - | Identifies the label on screen; change it with the children and the label rolls (AnimatedLabel). Ignored with `asChild` or while loading. |
| tooltip | React.ReactNode \| false | - | Tooltip content for an `iconOnly` button. Defaults to `aria-label`; `false` opts out. |
| tooltipPlacement | TooltipProps["placement"] | "top" | Where that tooltip sits. |
| static | boolean | false | Kept for compatibility; controls no longer scale on press. |
| asChild | boolean | false | Renders its single child as the button (Radix Slot), e.g. a Next.js `<Link>`. |

| Data attribute | Description |
| --- | --- |
| data-icon-only | Present on an `iconOnly` button. |
| data-loading | Present while `loading`. |

### SocialButton

An OAuth "Continue with" button with a real brand logo. Wraps `Button`, so every Button prop applies except `variant`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| provider* | "google" \| "discord" \| "github" \| "apple" \| "x" \| "threads" \| "microsoft" \| "figma" \| "facebook" \| "linkedin" \| "spotify" \| "slack" | - | Picks the logo, the label and the brand color. |
| appearance | "outline" \| "solid" | "outline" | A neutral outline with the full-color logo, or the brand's own fill with a white logo. |
| children | React.ReactNode | "Continue with {label}" | Replaces the label. Ignored when `iconOnly`. |
| iconOnly | boolean | false | Just the logo; `aria-label` defaults to "Continue with {label}". |

### SplitButton

A primary Button with a separate trailing DropdownMenu trigger. Button appearance props apply to both segments.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| children* | React.ReactNode | - | The visible label for the primary action. |
| menu* | React.ReactNode | - | Dropdown menu content, usually DropdownMenuItem and DropdownMenuSeparator. |
| menuLabel | string | "More options" | Accessible name for the menu trigger. |
| menuAlign | "start" \| "center" \| "end" | "end" | Alignment of the menu relative to its trigger. |
| menuClassName | string | - | Classes for the menu content, such as a fixed width. |
| asChild | boolean | false | Render the primary action on its child, such as a Next.js Link. |
| variant | ButtonProps["variant"] | "primary" | Shared button appearance. |
| size | ButtonProps["size"] | "md" | Shared button size. |
| disabled | boolean | false | Disables both segments. |

## 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 square that tracks the active size, with the same corner as Input, Select and Toggle (`rounded-md`, which follows the radius knob), 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` (which stands down when you wrap the button in your own Tooltip), 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 (or size="xs" for row actions in a dense table). A pseudo-element keeps the xs and sm hit targets 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.

### Does the button animate on press?

No. Buttons no longer scale on press: the focus ring and color carry the feedback. The `static` prop is kept for compatibility and has no visual effect.

### 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 (xs and sm grow their target with an invisible pseudo-element, so the visual stays 28 or 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>
  )
}
```

## Anatomy

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

<ButtonGroup>
  <ButtonGroupItem />
  <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 Button's sizes - `xs` (28px, for a toolbar of row actions in a dense table), `sm` (32px), `md` (36px, the default), and `lg` (40px). The marketing `xl` is not offered on a group.

```tsx
<ButtonGroup size="xs">
  <ButtonGroupItem>Extra small</ButtonGroupItem>
  <ButtonGroupItem>Group</ButtonGroupItem>
</ButtonGroup>

<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

With no `size`, `density` picks the height: compact is sm, comfortable is md. An explicit size still wins. Like a Button, the group ignores an ambient `DensityProvider` and stays md. 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>
```

## API reference

### ButtonGroup

A `<div role="group">` whose variant and size flow to every item. Forwards all native `<div>` props. Every part accepts `className`, merged last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| attached | boolean | true | Fuses the items into one pill: inner corners squared, neighbours sharing one stroke. `false` spaces them with a 4px gap. |
| variant | "primary" \| "secondary" \| "neutral" \| "outline" \| "ghost" \| "overlay" \| "destructive" \| "destructiveGhost" \| "link" | "outline" | The Button variant every item takes. |
| size | "xs" \| "sm" \| "md" \| "lg" | "md" | The height every item takes: 28, 32, 36 or 40px. Unset, it follows `density`, then the size a container imposes. |
| density | "comfortable" \| "compact" | - | Picks the size when none is set: `compact` is sm, `comfortable` is md. An explicit `size` wins. |

### ButtonGroupItem

One button in the group. Forwards all native `<button>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| variant | "primary" \| "secondary" \| "neutral" \| "outline" \| "ghost" \| "overlay" \| "destructive" \| "destructiveGhost" \| "link" | - | Overrides the group's variant for this item. |
| size | "xs" \| "sm" \| "md" \| "lg" | - | Overrides the group's size for this item. |
| density | "comfortable" \| "compact" | - | Overrides the group's density for this item; beats the group's `size` too. |
| iconOnly | boolean | false | A square icon button. Pass `aria-label`; development warns without one. |
| asChild | boolean | false | Renders its single child as the button (Radix Slot). |

## 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 md items. Density picks the size only when none is set.

### 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.

---

<!-- 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>
  )
}
```

## Anatomy

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

<Card>
  <CardMedia />
  <CardHeader>
    <CardTitle />
    <CardDescription />
    <CardAction />
  </CardHeader>
  <CardContent />
  <CardFooter />
</Card>
```

```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>
```

## 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.

## 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>
```

## API reference

### Card

The root, a flex column whose density flows to every part. Forwards all native `<div>` props. Every part accepts `className`, merged last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| variant | "default" \| "outline" \| "elevated" | "default" | A hairline-shadow contour, a bare border, or a filled card on a large shadow (the only one with a fill). |
| density | "comfortable" \| "compact" | "compact" | Padding and gaps (16px or 24px) and the title size. Falls back to the nearest `DensityProvider`. |
| interactive | boolean | false | Pointer, a hover lift that follows the variant, and a focus ring, for a card that is itself a link or button. |
| asChild | boolean | false | Renders the card onto its single child (Radix Slot), such as an `<a>`. |

| CSS variable | Description |
| --- | --- |
| --surface | Set to `var(--card)` by `elevated` only, so controls inside blend with its fill. |

### CardHeader

A grid for the title, description and an optional action, which it seats top-right. Forwards all native `<div>` props.

### CardTitle

The title, semibold. Forwards all native `<div>` props.

### CardDescription

Muted supporting text; `truncate` or `line-clamp` on it win over its pretty wrapping. Forwards all native `<div>` props.

### CardAction

The header's top-right slot, for a button or control. Forwards all native `<div>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| wrap | "never" \| "narrow" | "never" | `narrow` drops the action under the copy once the header is under 24rem (a container query). The card then needs its width from the layout. |

| Data attribute | Description |
| --- | --- |
| data-wrap | `"narrow"` when `wrap="narrow"`. |

### CardContent

The body, padded to the density. Forwards all native `<div>` props.

### CardFooter

A row for actions, padded to the density. Forwards all native `<div>` props.

### CardMedia

An inset 16:9 picture frame with a concentric radius; an `<img>` or `<video>` inside fills it. Override the ratio with `className`. Forwards all native `<div>` props.

## 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 slide viewer with a clickable indicator. The track slides or fades between full-width or peeking slides, arrow keys step it, autoplay counts down in the indicator, and the indicator ships with a closed set of forms: dots, lines, fraction, thumbnails.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Installation

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

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

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

Pro: `carousel` comes with a [Koala UI Pro license](https://www.koalaui.com/pro). Its source is not published in these docs.

## Usage

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Anatomy

```tsx
import {
  Carousel,
  CarouselContent,
  CarouselSlide,
  CarouselCaption,
  CarouselPrevious,
  CarouselNext,
  CarouselIndicators,
  CarouselPlayPause,
} from "@/components/ui/carousel"

<Carousel>
  <CarouselContent>
    <CarouselSlide>
      <CarouselCaption />
    </CarouselSlide>
  </CarouselContent>
  <CarouselPrevious />
  <CarouselNext />
  <CarouselIndicators />
  <CarouselPlayPause />
</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 ink 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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. `size="lg"` scales the dots, lines or bar up for a wide showcase row; contained, its pill stands as tall as an `xl` button.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Fade

`effect="fade"` on `CarouselContent` stacks the slides and fades the incoming one in on top of the outgoing one, which holds underneath until the fade is done, so the page never shows through mid-way. Arrows, keys, dots and a swipe all still step it. The first slide is simply there on load; only changes fade.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Autoplay

`autoplay` advances on its own: `true` every five seconds, or a number of milliseconds. The active dot or line counts down the interval. It holds while the pointer is over the carousel, while keyboard focus is inside it and while the tab is hidden, and picks up where it left off; a manual step starts a fresh interval. Autoplay turns `loop` on, so the arrows and keys wrap too. `CarouselPlayPause` is the switch that lasts, for anyone who needs the slides to hold still.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Peek

`peek` on `CarouselContent` narrows the slides to centered cards with the neighbours showing at both edges. With `loop` or `autoplay` the row never ends: the last card steps forward onto the first instead of rewinding past them all. `CarouselCaption` sets words over a card's photo, and the neighbours' captions dim so only the middle one reads at full strength. Size the cards with `[--carousel-slide:80%]` and the gutter with `[--carousel-gap:2rem]` in its `className`.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Slideshow

`kenBurns` adds a slow push-in and drift to each slide's photo (its direct `img`, `video` or `picture` child) while it shows, alternating direction so consecutive photos never travel the same way. With a fade and autoplay it is a slideshow: a welcome or loading screen, a hero backdrop. Put the words outside the slides and they hold still while the photos move. Off under reduced motion.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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`.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## API reference

### Carousel

The root, a `role="group"` region with `aria-roledescription="carousel"`; ArrowLeft and ArrowRight step it while focused. Forwards all native `<div>` props. Every part accepts `className`, merged last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| index | number | - | The active slide, 0-based, controlled. |
| defaultIndex | number | 0 | The first slide shown, uncontrolled. |
| onIndexChange | (index: number) => void | - | Called with the next index on navigation. |
| label | string | "Carousel" | The accessible name of the region. |
| autoplay | boolean \| number | false | Advances every 5s (`true`) or every n ms. Holds on hover, focus, off-screen, in a hidden tab and when paused. Turns `loop` on. |
| loop | boolean | autoplay | Wraps past either end for arrows, keys and swipe. On by default only with `autoplay`. |

| Data attribute | Description |
| --- | --- |
| data-autoplay | `"playing"` or `"paused"` while `autoplay` is set. |

| CSS variable | Description |
| --- | --- |
| --carousel-interval | The autoplay interval in ms, written from `autoplay`. Times the Ken Burns drift and the progress fill. |

### CarouselContent

The clipping viewport and its moving track. Children must be `CarouselSlide`s. Forwards all native `<div>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| draggable | boolean | true | Mouse and touch drag-to-swipe. A real drag swallows the trailing click. |
| effect | "slide" \| "fade" | "slide" | Translates the track, or crossfades stacked slides. |
| kenBurns | boolean | false | A slow push-in on each slide's direct `img`, `video` or `picture`. Off under reduced motion. |
| peek | boolean | false | Centered card slides with the neighbours showing, endless with `loop`. `effect="slide"` only. |

| CSS variable | Description |
| --- | --- |
| --carousel-slide | With `peek`, the width of a card (`87.5%` by default). Set it in `className`. |
| --carousel-gap | With `peek`, the gutter between cards. |

### CarouselSlide

One slide, labelled with its position ("2 of 4"). Forwards all native `<div>` props.

| Data attribute | Description |
| --- | --- |
| data-active | `"true"` on the slide showing. |

### CarouselCaption

A title, line and action over the foot of the photo on a legibility scrim; put it after the photo. Dims on non-centered `peek` cards. Forwards all native `<div>` props.

### CarouselPrevious

An overlay arrow that reveals on hover and focus, disabled at the first slide unless looping. A `Button` (every prop except `variant`, `size` and `iconOnly`).

### CarouselNext

The forward twin of `CarouselPrevious`, disabled at the last slide unless looping.

### CarouselIndicators

Position and navigation in one of seven forms; renders nothing for a single slide. Forwards all native `<div>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| variant | "dots" \| "lines" \| "fraction" \| "thumbnails" \| "tabs" \| "numbers" \| "progress" | "dots" | The form. `fraction` and `progress` are readouts, not per-slide buttons. |
| overlay | boolean | false | Floats the indicator over the image in a fixed white treatment. |
| align | "end" \| "center" | "end" | Where an `overlay` indicator sits: bottom-right or bottom-centered. |
| contained | boolean | false | Seats `dots`, `lines` or `progress` in a pill (muted, or frosted dark over media). |
| size | "md" \| "lg" | "md" | The scale of `dots`, `lines` and `progress`. |
| thumbnails | React.ReactNode[] | - | One preview per slide, in slide order. Required by `thumbnails`. |
| thumbnailSize | "sm" \| "lg" | "sm" | A 56 by 40 landscape tile, or a 64px square for packshots. |
| labels | React.ReactNode[] | - | One short label per slide for `tabs`, falling back to the slide number. |
| dotLabel | (index: number) => string | i => Go to slide ${i + 1} | Builds the accessible label of each per-slide button. |

| Data attribute | Description |
| --- | --- |
| data-active | Present on the item of the slide showing (it also gets `aria-current`). |

### CarouselPlayPause

Pauses and resumes `autoplay` for good (WCAG 2.2.2); renders nothing without autoplay. A `Button` (every prop except `variant`, `iconOnly` and `children`); place it yourself.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| overlay | boolean | false | The frosted dark chip for a button on the photo. |
| size | "sm" \| "md" \| "lg" \| "xl" | "sm" | The Button size. |

## 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 unless the carousel loops.

### 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), thumbnails (one slide preview per slide, via the thumbnails prop), tabs (one label per slide, via labels), numbers, and progress (a continuous bar). 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.

### Does autoplay meet the accessibility rules for moving content?

It pauses on hover, on keyboard focus and in a hidden tab, and CarouselPlayPause gives a lasting pause (WCAG 2.2.2). While it rotates the slides are not announced; once it holds, each new slide is announced politely. Every slide is labelled with its position ("2 of 4").

### How does the peek row loop without rewinding?

With peek and loop (or autoplay), CarouselContent repeats the first two slides after the last and the last two before the first. A wrapping step moves one card on, onto a copy, and once that move ends the track jumps unanimated to the real slide the copy stands for, which looks identical. The copies are aria-hidden and inert, so assistive tech and the tab order only ever meet the real slides.

### Where does Ken Burns apply?

To the slide's direct img, video or picture child, so a caption or a badge inside the slide never zooms. The slide clips it, so it works on the sliding track too, and it is off under prefers-reduced-motion.

### 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/channel-chat.md -->

# Channel Chat

A many-person channel log, the team-chat and radio-net shape: messages grouped by author, day separators, system notices, your own run tinted, a log that follows new messages until you scroll up, and a composer with a counter and a rejected notice.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Installation

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

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

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

Pro: `channel-chat` comes with a [Koala UI Pro license](https://www.koalaui.com/pro). Its source is not published in these docs.

## Usage

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Chat or Channel Chat

`Chat` is a two-party thread: you and an assistant, a bubble or a document each, built for streaming answers and reasoning. A channel has many authors talking at once, so it needs different structure: author groups with a name, a callsign and an avatar, separators between days, system notices for who joined, and a log that can be read while it moves. That is this component. It is built out of the same parts: the log scrolls in `ScrollArea`, the avatar is `Avatar`, separators are `Divider`, and the composer is `PromptInput` laid out as one row.

## Anatomy

Every part is a named export and every part is optional: a log without a header, a composer on its own, a group without an avatar (the text column keeps its place). Grouping is data, not markup: `groupChannelMessages` turns your flat list into rows, and you render each row with the parts.

```tsx
import {
  ChannelChat,
  ChannelChatAuthor,
  ChannelChatAvatar,
  ChannelChatCallsign,
  ChannelChatComposer,
  ChannelChatCount,
  ChannelChatEmpty,
  ChannelChatGroup,
  ChannelChatGroupHeader,
  ChannelChatHeader,
  ChannelChatInput,
  ChannelChatMessage,
  ChannelChatMeta,
  ChannelChatSend,
  ChannelChatSeparator,
  ChannelChatSystem,
  ChannelChatTime,
  ChannelChatTitle,
  ChannelChatViewport,
} from "@/components/ui/channel-chat"

<ChannelChat>
  <ChannelChatHeader>
    <ChannelChatTitle />
    <ChannelChatMeta />
  </ChannelChatHeader>
  <ChannelChatViewport>
    <ChannelChatSeparator />
    <ChannelChatGroup>
      <ChannelChatAvatar />
      <ChannelChatGroupHeader>
        <ChannelChatAuthor />
        <ChannelChatCallsign />
        <ChannelChatTime />
      </ChannelChatGroupHeader>
      <ChannelChatMessage />
    </ChannelChatGroup>
    <ChannelChatSystem />
    <ChannelChatEmpty />
  </ChannelChatViewport>
  <ChannelChatComposer>
    <ChannelChatInput />
    <ChannelChatCount />
    <ChannelChatSend />
  </ChannelChatComposer>
</ChannelChat>
```

## Grouping and separators

Consecutive messages from one author within `windowMs` (5 minutes) of the previous one share a header. A new local day opens a day separator, a silence of `gapMs` (an hour) on the same day opens a time separator, and a system notice always ends the run. Pass `own` on your own groups: they take a soft ink wash and your name in the link ink.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Following and jump to latest

The viewport opens on the newest message and follows new ones while you are at the bottom. Scroll up and it holds your place: a pill appears over the log, counting what arrived since, and takes you back down. Only a move up leaves the bottom, so the log never loses you halfway through its own smooth scroll. Sending from the composer jumps to the newest message too. Scroll up in the log below, then receive a message.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

What the log opened with is history and never animates. Only rows that mount after its first commit fade in, and a batch of more than five messages in one commit (a backlog that loaded late, a reconnect) lands still, as history. To open a different channel as fresh history, give the viewport a `key` per channel.

## Empty states

`ChannelChatEmpty` is our compact `EmptyState`, centered in the room it gets: inside the viewport for a quiet channel, or in place of it when there is no log at all. A composer with nowhere to send takes `disabled`.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Composer

`maxLength` caps the draft, and `ChannelChatCount` shows `length/max` only once the draft nears it (20 characters out by default, or `counterFrom`). When the server refuses a message (too fast, filtered, not delivered), pass the reason as `notice`: it tucks in behind the composer as PromptInput's banner and is announced as an alert. Enter sends, Shift+Enter breaks the line, and focus returns to the field after a send.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Accessibility

- The log is `role="log"` with `aria-live="polite"`: each arrival is read once, without interrupting. Name it with `aria-label` (the channel).
- Avatars are decorative (the name sits beside them). Times are `<time>` elements; pass `dateTime`.
- The hidden jump pill is out of the tab order and the accessibility tree; it rejoins both when it shows.
- The counter is a live region that stays mounted, and reads “15 characters left” rather than the visual `185/200`. The rejected notice is `role="alert"`.
- Arrivals honor reduced motion: no fade, and the jump is instant.

## Older engines

Built for Chromium 103 (in-game browsers such as CEF): no `:has()`, container queries or standalone `translate`/`scale` properties. The pill moves with `transform`, and the field grows with PromptInput's measured fallback where `field-sizing` is missing.

## API reference

### ChannelChat

The panel, a `<section>` laid out as a flex column. Size it (`h-96`, or `flex-1 min-h-0`); the viewport takes the room between header and composer. It lets the composer reach the viewport, so a send jumps to the newest message. Every part accepts `className`, merged last.

| Data attribute | Description |
| --- | --- |
| data-slot="channel-chat" | On the root. |

### ChannelChatHeader

A `<header>` with a hairline under it. A leading icon is muted.

### ChannelChatTitle

The channel name, an `<h2>` that truncates.

### ChannelChatMeta

Trailing meta in tabular figures (a frequency, a member count), a `<span>` pushed to the right edge.

### ChannelChatViewport

The scrolling log, `role="log"` with polite announcements. Give it a `key` per channel to open another channel as fresh history. Other props go on the frame.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| stickToBottom | boolean | true | Follows new messages while the reader is at the bottom, and shows the jump pill when not. Scrolling up is never yanked back down. |
| jumpLabel | (unread: number) => React.ReactNode | - | The pill's label, given how many messages arrived while scrolled up. Defaults to "n new messages" or "Jump to latest". |
| viewportRef | React.Ref<HTMLDivElement> | - | A ref to the scrolling element itself. |
| aria-label | string | - | Names the log (the channel). |
| aria-labelledby | string | - | Names the log from an element on the page. |

| Data attribute | Description |
| --- | --- |
| data-following | Present while the reader is at the bottom. |
| data-slot="channel-chat-jump" | The jump pill; carries `data-state` (`visible` or `hidden`). |

### ChannelChatSeparator

A day or quiet-gap separator: a labeled hairline (our `Divider`), read as plain text. Children are the label.

### ChannelChatGroup

A run of messages from one author. The avatar sits in a reserved gutter, so a group without one keeps the same text column.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| own | boolean | false | Your own run: a soft ink wash and the name in the link ink. |

| Data attribute | Description |
| --- | --- |
| data-own | Present while `own`. |

### ChannelChatAvatar

The author's avatar in the group's gutter, hidden from assistive tech. Every `Avatar` prop is forwarded.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| src | string | - | The photo. |
| name | string | - | Derives two initials for the fallback. |
| size | "xs" \| "sm" \| "md" \| "lg" \| "xl" | "sm" | Our Avatar sizes. |
| children | React.ReactNode | - | Overrides the fallback initials. |

### ChannelChatGroupHeader

The group's header row, baseline-aligned.

### ChannelChatAuthor

The author's name, a `<span>` that truncates.

### ChannelChatCallsign

The callsign in mono, a `<span>`.

### ChannelChatTime

A `<time>` in tabular figures. Pass `dateTime` (ISO) for a machine-readable stamp.

### ChannelChatMessage

One line of a group. Keeps the sender's line breaks and breaks a long token anywhere.

| Data attribute | Description |
| --- | --- |
| data-fresh | Stamped when it arrives after the log settled; history never animates. |

### ChannelChatSystem

A system notice between groups: a join, a leave, a channel switch.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| tone | "default" \| "info" \| "success" \| "warning" \| "destructive" | "default" | Tints the leading icon only; the text stays quiet. |

| Data attribute | Description |
| --- | --- |
| data-tone | The current `tone`. |

### ChannelChatEmpty

Our `EmptyState` in a centering frame. Every EmptyState prop is forwarded; `className` goes on the frame.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| density | "comfortable" \| "compact" | "compact" | The EmptyState density. |

### ChannelChatComposer

The message composer: our `PromptInput` as one row, with the notice as its banner. Compose `ChannelChatInput`, `ChannelChatCount` and `ChannelChatSend` inside.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| value | string | - | Controlled draft. Omit (and use `defaultValue`) to let the composer own it. |
| defaultValue | string | - | The initial draft, uncontrolled. |
| onValueChange | (value: string) => void | - | Called with the draft as it changes. |
| onSubmit | (text: string) => void | - | Receives the trimmed text. Never fires empty or disabled. Uncontrolled, the field clears itself, takes focus back and the log jumps to the newest message. |
| disabled | boolean | false | Nobody to talk to: the field and the send button go inert. |
| maxLength | number | - | Caps the draft and turns the counter on. |
| counterFrom | number | maxLength - 20 | The draft length at which the counter appears. |
| notice | React.ReactNode | - | The rejected-message notice, tucked behind the composer and announced as an alert. `null` removes it. |
| noticeTone | "default" \| "info" \| "warning" \| "destructive" | "destructive" | The notice's tone (PromptInputBanner tones). |
| onNoticeDismiss | () => void | - | Adds a close button to the notice that calls this. |

| Data attribute | Description |
| --- | --- |
| data-disabled | Present while `disabled`. |
| data-slot="channel-chat-notice" | The notice banner. |

### ChannelChatInput

The composer's auto-growing field. Enter sends, Shift+Enter breaks the line. Takes every `PromptInputTextarea` prop.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| placeholder | string | "Write a message…" | Also names the field when there is no `aria-label`. |

### ChannelChatCount

The draft counter, `length/max`, shown once the draft nears `maxLength`. Turns destructive at the cap. Renders nothing without `maxLength`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| srLabel | (left: number) => string | (left) => "n characters left" | Words the remaining count for screen readers. |

| Data attribute | Description |
| --- | --- |
| data-near | Present once the draft reaches `counterFrom`. |
| data-full | Present at the cap. |

### ChannelChatSend

The send button, disabled until there is a draft. Takes every `PromptInputSubmit` prop.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| sendLabel | string | "Send message" | The button's accessible name. |
| children | React.ReactNode | - | Replaces the arrow-up send icon. |

### groupChannelMessages

`groupChannelMessages(messages, options)` turns a flat list into rows: `{ type: "separator", kind: "day" | "gap", at }`, `{ type: "group", author, at, items }` and `{ type: "system", at, item }`, each with a `key`. It formats nothing; word the labels in your locale. Its options:

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| getKey* | (message: T) => string \| number | - | A stable key per message (its id). |
| getAuthor* | (message: T) => string \| number | - | Who sent it. Two messages group only when this matches. |
| getTime* | (message: T) => number \| Date | - | When it was sent, as epoch ms or a `Date`. |
| isSystem | (message: T) => boolean | - | Marks a system notice. Never grouped. |
| windowMs | number | 5 minutes | How close a message must follow the previous one to join its group. |
| gapMs | number | 1 hour | A same-day silence long enough for a time separator. `0` turns gap separators off. |
| leadingSeparator | boolean | true | Inserts a separator before the very first message. |

### channelChatVariants

The `tv` recipe behind every part, for styling a part of your own to match.

## FAQ

### Why is grouping a function and not automatic?

Because the log has to stay composable: you decide what a row looks like, and the parts never inspect each other. groupChannelMessages is a plain function, so it also runs on the server or in a test, and it never formats a date: you word Today and 14:02 in your own locale.

### Why do history messages not animate?

Anything that is already there on the viewport's first commit is history, and history should land still: a channel opening with forty messages sliding in reads as noise. Only rows that mount afterwards fade in, and a batch of more than five in one commit is treated as history too.

### How do I switch channels?

Give ChannelChatViewport a key per channel. The remount makes the new channel's messages history again, and the log opens at its newest message.

### Can I use the composer on its own?

Yes. ChannelChatComposer works outside ChannelChat; it just has no log to jump to after a send.

---

<!-- 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>
  )
}
```

## Anatomy

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

<Checkbox />

<CheckboxGroup allValues={[…]}>
  <Checkbox parent />
  <Checkbox value="…" />
  <CheckboxGroup allValues={[…]}>
    <Checkbox parent />
    <Checkbox value="…" />
  </CheckboxGroup>
</CheckboxGroup>
```

## States

Checked and indeterminate both fill with the primary (ink) 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>
```

## Group

`CheckboxGroup` holds one `string[]` for a whole set. Each member is a plain `Checkbox` with a `value`, so there is no per-box state to keep. Use `defaultValue`, or `value` with `onValueChange` to control it. Name the group with `aria-labelledby`.

```tsx
<span id="notify-heading">Notify me by</span>
<CheckboxGroup aria-labelledby="notify-heading" defaultValue={["email"]}>
  <label className="flex items-center gap-2.5">
    <Checkbox value="email" /> Email
  </label>
  <label className="flex items-center gap-2.5">
    <Checkbox value="push" /> Push notification
  </label>
  <label className="flex items-center gap-2.5">
    <Checkbox value="sms" /> Text message
  </label>
</CheckboxGroup>
```

## Select all

Pass `allValues` and add a `Checkbox parent`. It reads checked when every child is, indeterminate on a partial selection and unchecked when none are, and a click toggles them all. From a partial selection it cycles through all, none, then back to the selection you had, so a stray click never loses it. The same tri-state the [DataTable](https://www.koalaui.com/docs/components/data-table.md) header uses.

```tsx
const TEAMS = ["engineering", "design", "marketing"]
const [value, setValue] = useState(["design"])

<CheckboxGroup
  aria-label="Teams"
  value={value}
  onValueChange={setValue}
  allValues={TEAMS}
>
  <label className="flex items-center gap-2.5">
    <Checkbox parent /> Select all teams
  </label>
  <label className="flex items-center gap-2.5 pl-7.5">
    <Checkbox value="engineering" /> Engineering
  </label>
  {/* design, marketing */}
</CheckboxGroup>
```

## Nested

Put a `CheckboxGroup` inside another and leave out its `value`: it shares the outer group’s list and only scopes its own `allValues`. A tree of permissions stays one flat array, and every parent at every level follows its children with no wiring.

```tsx
const USERS = ["users.view", "users.invite", "users.remove"]

<CheckboxGroup
  aria-label="Permissions"
  allValues={["dashboard", "reports", ...USERS]}
  defaultValue={["dashboard", "users.view"]}
>
  <label><Checkbox parent /> All permissions</label>
  <div className="flex flex-col gap-3 pl-7.5">
    <label><Checkbox value="dashboard" /> View dashboard</label>
    <label><Checkbox value="reports" /> Export reports</label>
    {/* No value of its own: it shares the outer list. */}
    <CheckboxGroup aria-label="Manage users" allValues={USERS}>
      <label><Checkbox parent /> Manage users</label>
      <div className="flex flex-col gap-3 pl-7.5">
        <label><Checkbox value="users.view" /> View members</label>
        <label><Checkbox value="users.invite" /> Invite members</label>
        <label><Checkbox value="users.remove" /> Remove members</label>
      </div>
    </CheckboxGroup>
  </div>
</CheckboxGroup>
```

## API reference

### Checkbox

The box, Radix `Checkbox.Root`. Renders a `<button role="checkbox">` and forwards all its props. Pair it with a `<label htmlFor>`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| checked | boolean \| "indeterminate" | - | Controlled state. Ignored inside a `CheckboxGroup`, where the group decides. |
| defaultChecked | boolean \| "indeterminate" | false | Initial state when uncontrolled. |
| onCheckedChange | (checked: boolean \| "indeterminate") => void | - | Called when the box toggles, inside a group too. |
| value | string | "on" | The form value. Inside a `CheckboxGroup` it is also the member's identity in the group's list. |
| parent | boolean | false | Inside a `CheckboxGroup`: governs the group's `allValues`, reading checked, indeterminate or unchecked from them. |
| size | "sm" \| "md" | "md" | 16px for dense tables, 20px for forms. |
| disabled | boolean | false | Disables the box. Falls back to the group's, then the Field's. |
| name | string | - | Submitted with the form when checked. |
| required | boolean | false | Marks the box required in a form. |

| Data attribute | Description |
| --- | --- |
| data-state | `"checked"`, `"unchecked"` or `"indeterminate"`. |
| data-disabled | Present when disabled. |
| data-parent | Present on a `parent` box inside a group. |

### CheckboxGroup

A set of checkboxes sharing one `string[]`. Renders a `<div role="group">`, a column with a 12px gap; name it with `aria-labelledby` or `aria-label`. Forwards all native `<div>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| value | string[] | - | The checked values (controlled). |
| defaultValue | string[] | [] | The values checked at first (uncontrolled). |
| onValueChange | (value: string[]) => void | - | Called with the new list when a member or a parent toggles. |
| allValues | string[] | - | Every value the group's `parent` box governs. Required for a parent. On a nested group, its slice of the outer list. |
| disabled | boolean | false | Disables every checkbox in the group. |

| Data attribute | Description |
| --- | --- |
| data-disabled | Present when the group is disabled. |

## 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 primary (ink) 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?

Wrap the boxes in a CheckboxGroup with allValues, give each child a value, and add a Checkbox with parent. The group derives checked, indeterminate or unchecked for you. Outside a group you can still drive it by hand: pass checked="indeterminate" on a partial selection, as the DataTable header does.

### 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Installation

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

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

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

Pro: `checklist` comes with a [Koala UI Pro license](https://www.koalaui.com/pro). Its source is not published in these docs.

## Usage

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Anatomy

```tsx
import {
  Checklist,
  ChecklistHeader,
  ChecklistTitle,
  ChecklistDescription,
  ChecklistProgress,
  ChecklistItems,
  ChecklistItem,
  ChecklistItemContent,
  ChecklistItemTitle,
  ChecklistItemDescription,
  ChecklistItemAction,
} from "@/components/ui/checklist"

<Checklist>
  <ChecklistHeader>
    <ChecklistTitle />
    <ChecklistDescription />
    <ChecklistProgress />
  </ChecklistHeader>
  <ChecklistItems>
    <ChecklistItem>
      <ChecklistItemContent>
        <ChecklistItemTitle />
        <ChecklistItemDescription />
      </ChecklistItemContent>
      <ChecklistItemAction />
    </ChecklistItem>
  </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 ink and a tick and de-emphasizes the title; `active` marks the one recommended next step with an ink 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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 ink to success-green and the label swaps to All steps complete.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Density

Like Card and Dialog, the Checklist reads the density context (or a `density` prop). Density tunes the card and row padding only, and it is compact unless set. The indicator footprint is fixed at both densities, so the left rail lines up identically.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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 tick in the colour of the surface beneath. 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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, an ink ring half filled on the `active` step, the ink 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## API reference

### Checklist

The root panel; owns the progress its parts read. Forwards all native `<div>` props. Every part accepts `className`, merged last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| value | number | - | Completed tasks. Leave it out and the Checklist counts its complete rows. Clamped to `total`. |
| total | number | - | All tasks. Leave it out and the Checklist counts its rows. |
| variant | "card" \| "plain" | "card" | The ring-edged panel, or no contour and outer padding, for a Checklist inside a Card. |
| density | "comfortable" \| "compact" | "compact" | Card and row padding; the mark stays put. Falls back to the nearest `DensityProvider`. |
| asChild | boolean | false | Renders the panel onto its single child (Radix Slot). |

### ChecklistHeader

The block holding the title, description and progress. Forwards all native `<div>` props.

### ChecklistTitle

The panel heading, an `<h3>`. Forwards all native `<h3>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| asChild | boolean | false | Renders onto its single child, to change the heading level. |

### ChecklistDescription

The muted line under the title, a `<p>`. Forwards all native `<p>` props.

### ChecklistProgress

The labelled `role="progressbar"` bar, read from the root. Its fill turns success at 100%. Forwards all native `<div>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| label | React.ReactNode | "{value} of {total} complete" | The leading label. The default swaps to "All steps complete" with a check when done. |

### ChecklistItems

The task list, a `<ul>`. Forwards all native `<ul>` props.

### ChecklistItem

One task row, an `<li>` that draws its own mark and an sr-only status. Any of `checked`, `defaultChecked` or `onCheckedChange` makes it a row the reader ticks. Forwards native `<li>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| status | "todo" \| "active" \| "complete" | "todo" | The task state. On a row the reader ticks, `checked` decides `complete`. |
| checked | boolean | - | Ticked, controlled. The mark becomes a Radix checkbox named by the title; the whole row toggles it. |
| defaultChecked | boolean | - | Ticked on first render, uncontrolled. |
| onCheckedChange | (checked: boolean) => void | - | Called when the reader ticks or unticks the row. |

| Data attribute | Description |
| --- | --- |
| data-status | `"todo"`, `"active"` or `"complete"`, as resolved. |
| data-state | `"checked"` or `"unchecked"`, on a row the reader ticks. |

### ChecklistItemContent

The title and description column; grows so the action rides the right edge. Forwards all native `<div>` props.

### ChecklistItemTitle

The task name; mutes when complete and strikes through when ticked. Names the checkbox. Forwards all native `<div>` props.

### ChecklistItemDescription

The muted line under the task name. Forwards all native `<div>` props.

### ChecklistItemAction

The trailing slot for a `Button`; stays its own target on a row the reader ticks. Forwards all native `<div>` props.

### ChecklistMark

The task mark alone, `aria-hidden`, for task lists the Checklist does not lay out; needs no `Checklist`. Forwards all native `<span>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| status | "todo" \| "active" \| "complete" | "todo" | An empty ring, an ink ring half filled, or the ink fill with a tick. |

| Data attribute | Description |
| --- | --- |
| data-status | `"todo"`, `"active"` or `"complete"`. |
| data-state | `"checked"` when complete, else `"unchecked"`. |

## 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 an ink 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, primary, 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/chip.md -->

# Chip

A small pill you act on: a callsign that toggles its assignment, an assign-to choice, a frequency, a filter tag. The interactive sibling of Badge, with a free colour, a hover-swapped icon and its own remove button.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Installation

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

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

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

Pro: `chip` comes with a [Koala UI Pro license](https://www.koalaui.com/pro). Its source is not published in these docs.

## Usage

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

A Chip is a `<button type="button">` unless you give it another element through `asChild`. Reach for it when the pill *does* something: toggles, assigns, filters, links or drags. A pill that only shows a status or a count is a Badge.

## Anatomy

```tsx
import { Chip, ChipIcon, ChipRemove } from "@/components/ui/chip"

<Chip>
  <ChipIcon />
  Label
</Chip>

<Chip asChild>
  <span>
    Label
    <ChipRemove />
  </span>
</Chip>
```

## Assign to

Extra-small outline chips in a call banner: one click hands the call to a unit, a second click takes it back. The department colour rides on the edge and the mark; the chosen unit takes the ink edge and wash.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Frequencies

A leading `ChipIcon` and a numeric label: chips are `tabular-nums`, so a row of frequencies lines up digit for digit. Wrap a set in `role="group"` with a name, so the pressed chip is announced in context.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Filter tags

A tag whose only action is its × is a `<span>` (through `asChild`) holding a `ChipRemove`: a button cannot sit inside a button. The × has its own name, so say what it removes. A display-only chip does not answer hover or press; only the × does.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Variants and tones

`soft` (default) fills the pill: the muted ground for `neutral`, the tone's own wash otherwise. `outline` keeps only the edge. Tones are `neutral`, `brand`, `info`, `success`, `warning` and `destructive`; the label takes the tone's legible `-strong` ink.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Sizes

`xs` is 20px tall, `sm` (default) 24px. Both reach a 40px target (44px on touch) through an invisible extension, so a row of small chips stays easy to hit without growing.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Colour

`color` takes any CSS colour: a department's hex from your config, a theme variable. It tints the edge and the ground and adds a leading mark in that colour; the label stays in the foreground ink, since an arbitrary hex as text carries no contrast guarantee. The tint is an opacity layer, not `color-mix()`, so it holds in old embedded browsers too.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Selected

`selected` paints an ink edge and an ink wash over any variant, tone or colour (the colour mark stays). On the default button it also sets `aria-pressed`, so the chip is announced as a toggle; leave it `undefined` on a chip that is not one.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Icons

`ChipIcon` goes before the label (leading) or after it (trailing) and tucks in toward the edge. Pass `idle` and `hover` instead of children to swap one glyph for another while the chip is hovered or focused: a check that becomes an × says “click to remove” before the click. Both glyphs stay mounted and cross-fade.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Remove

`ChipRemove` is its own `<button>`, last in the chip, hugging the trailing edge at either size. Its target is 40px tall but never wider than itself, so it never takes a tap meant for the next chip. Name it with `label`.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## As a link or a drag handle

`asChild` hands the chip's paint to your element: a link to a unit's record, or the element a sortable (dnd-kit's `useSortable`) puts its listeners on. Hover and press answer on a link and on anything with `role="button"`. Try the arrow keys on a focused chip below.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Disabled

`disabled` dims the chip in any state and takes it out of the pointer's way: the native `disabled` on the default button, `aria-disabled` with `asChild`.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## API reference

### Chip

The pill. A `<button type="button">`, or your element with `asChild` (Radix Slot). Forwards every button prop; `className` is merged last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| variant | "soft" \| "outline" | "soft" | `soft` fills the pill (the muted ground for `neutral`, the tone's wash otherwise); `outline` keeps only the edge. |
| tone | "neutral" \| "brand" \| "info" \| "success" \| "warning" \| "destructive" | "neutral" | The hue of the label, edge and wash. The label takes the tone's `-strong` ink on a light ground. |
| size | "xs" \| "sm" | "sm" | `xs` is 20px tall, `sm` 24px. The hit area grows to 40px either way. |
| color | string | - | Any CSS colour (a hex, `var(--purple)`): tints the edge and ground and adds a leading mark in that colour. Takes over the tone's hue; the label stays foreground. |
| selected | boolean | - | Chosen: an ink edge and wash. Sets `aria-pressed` on the default button; with `asChild` only `data-selected` is set. Leave `undefined` for a chip that is not a toggle. |
| disabled | boolean | - | `disabled` on the default button, `aria-disabled` with `asChild`. |
| static | boolean | false | Kept for compatibility; controls no longer scale on press. |
| asChild | boolean | false | Renders the child element as the chip: a link, a `<span>` tag, a drag handle. |

| Data attribute | Description |
| --- | --- |
| data-slot="chip" | On the root. The leading colour mark is `data-slot="chip-mark"`. |
| data-size | `xs` or `sm`. |
| data-selected | Present while `selected`. |
| data-disabled | Present while `disabled`. |

| CSS variable | Description |
| --- | --- |
| --chip-color | Set from `color`; drives the mark, the edge and the wash. |

### ChipIcon

A decorative `<span>` (`aria-hidden`) for a leading or trailing glyph. Forwards every span prop.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| children | React.ReactNode | - | A plain glyph, when the icon does not swap. |
| idle | React.ReactNode | - | The glyph at rest, when the icon swaps on hover. |
| hover | React.ReactNode | - | The glyph on the chip's hover or keyboard focus (a check that becomes an ×). Both glyphs stay mounted and cross-fade. |

### ChipRemove

A `<button type="button">` with an × glyph. Place it last, in a chip that is not a button itself (a `<span>` through `asChild`). Forwards every button prop.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| label | string | "Remove" | The accessible name: say what goes ("Remove Patrol"). |
| children | React.ReactNode | - | Another glyph in place of the ×. |

### chipVariants

The `tv` recipe, with the slots `root`, `mark`, `icon`, `iconIdle`, `iconHover` and `remove`.

## FAQ

### Chip or Badge?

A Badge shows something: a status, a count, a version. A Chip is acted on: pressed, toggled, removed, followed or dragged. If nothing happens when you click it, it is a Badge.

### Chip or Toggle Group?

A Toggle Group is a fixed set of options with arrow-key navigation, a form control. Chips are data: units, frequencies, tags that come and go, often wrapped across lines, each one its own tab stop.

### Why can't a toggle chip hold a ChipRemove?

A button inside a button is invalid HTML and screen readers flatten it. A chip whose action is its × is a `<span>` through `asChild`; a toggle chip that also removes should swap its icon on hover (a check that becomes an ×) and let the click do it.

### Why does the colour not change the label?

An arbitrary colour as text has no contrast guarantee: a pale yellow department would be unreadable on a light ground. The colour goes on the edge, the wash and the mark; the label stays in the foreground ink.

### Does it work in an in-game browser (Chromium 103)?

Yes. The tints ride opacity instead of `color-mix()`, the press and the icon swap ride `transform` instead of the standalone `scale` property, and nothing uses `:has()` or container queries.

---

<!-- 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 "koala-icons"
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

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

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

Pro: `code-snippet` comes with a [Koala UI Pro license](https://www.koalaui.com/pro). Its source is not published in these docs.

## Usage

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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

### CodeSnippet

A highlighted, copyable code block with a copy button on hover. Forwards native `<div>` props except `children`; accepts `className`, merged last onto the root.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| code* | string | - | The source to render and copy. |
| lang | "tsx" \| "ts" \| "js" \| "css" \| "bash" \| "sh" | "tsx" | The grammar and the header chip. `ts` and `js` use the TSX grammar; a shell listing with `$` prompts reads as a session. |
| filename | string | - | A filename chip in the header (and turns the header on). |
| dots | boolean | false | macOS-style window dots in the header (and turns the header on). |
| inset | boolean | true | With a header: a tinted frame with the code set 8px in as a sheet. `false` makes it a strip across one surface. |
| showLineNumbers | boolean | false | A tabular line-number gutter. |
| startLine | number | 1 | The first gutter number, for an excerpt; `diff` uses the same numbering. |
| diff | { added?: number[]; removed?: number[] } | - | Lines marked by gutter number: a tinted band and gutter bar, announced as Added or Removed. |
| collapsible | boolean | false | Clamps a long listing behind Show more / Show less, once it overflows. |
| collapsedHeight | number | 320 | The clamped height in px. |
| density | "comfortable" \| "compact" | "compact" | Padding only. Falls back to the nearest `DensityProvider`. |

| Data attribute | Description |
| --- | --- |
| data-diff | `"added"` or `"removed"` on a marked line and its gutter cell. |

## 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. `ts` and `js` read with the TSX grammar.

### 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>
  )
}
```

## Anatomy

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

<Collapsible>
  <CollapsibleTrigger>
    <CollapsibleIcon />
  </CollapsibleTrigger>
  <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

The root, Radix `Collapsible.Root`: a plain `<div>` with no chrome that forwards all its props. Every part accepts `className`, merged last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| open | boolean | - | Controlled open state. |
| defaultOpen | boolean | false | Initial open state when uncontrolled. |
| onOpenChange | (open: boolean) => void | - | Called when the region opens or closes. |
| disabled | boolean | false | Stops the trigger from toggling the region. |
| asChild | boolean | false | Merge onto your own element instead of rendering a `<div>`. |

| Data attribute | Description |
| --- | --- |
| data-state | `"open"` or `"closed"`. |
| data-disabled | Present when `disabled` is set. |

### CollapsibleTrigger

Radix `Collapsible.Trigger`, a `<button>` carrying `aria-expanded` and `aria-controls`; forwards all its props. Styled as a quiet text control with a 40px hit area unless `asChild` is set.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| asChild | boolean | false | Hand the behavior to your own control (a Button, a row), which keeps its own look entirely. |

| Data attribute | Description |
| --- | --- |
| data-state | `"open"` or `"closed"`; the icon inside turns on it. |
| data-disabled | Present when the root is disabled. |

### CollapsibleIcon

The decorative disclosure mark; it turns on the state of the trigger it sits in, so it must be inside `CollapsibleTrigger` (or its `asChild` element). Forwards all native `<svg>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| marker | "caret" \| "branch" \| "plus" | "caret" | The glyph and its turn: a caret flips 180°, a branch caret turns 90°, a plus turns 45° into a cross. |

### CollapsibleContent

The region, Radix `Collapsible.Content`, unmounted once its close animation ends; forwards all its props. `className` styles the body inside the animated wrapper, so padding and layout go here without disturbing the height tween.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| forceMount | true | - | Keep the region mounted while closed, for animating it with your own library. |

| Data attribute | Description |
| --- | --- |
| data-state | `"open"` or `"closed"`. |
| data-disabled | Present when the root is disabled. |

| CSS variable | Description |
| --- | --- |
| --radix-collapsible-content-height | The region's measured height, read by the open and close tween. |
| --radix-collapsible-content-width | The region's measured width. |

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Installation

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

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

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

Pro: `color-picker` comes with a [Koala UI Pro license](https://www.koalaui.com/pro). Its source is not published in these docs.

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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
import {
  ColorPicker,
  ColorPickerModes,
  ColorPickerGradient,
  ColorPickerImage,
  ColorPickerFormat,
  ColorPickerEyeDropper,
  ColorPickerArea,
  ColorPickerControls,
  ColorPickerFields,
  ColorPickerSwatches,
  ColorPickerPopover,
  ColorPickerTrigger,
  ColorPickerTriggerSwatch,
  ColorPickerContent,
} from "@/components/ui/color-picker"

<ColorPickerPopover>
  <ColorPickerTrigger asChild>
    <ColorPickerTriggerSwatch />
  </ColorPickerTrigger>
  <ColorPickerContent>
    <ColorPicker>
      <ColorPickerModes />
      <ColorPickerGradient />
      <ColorPickerImage />
      <ColorPickerFormat />
      <ColorPickerEyeDropper />
      <ColorPickerArea />
      <ColorPickerControls />
      <ColorPickerFields />
      <ColorPickerSwatches />
    </ColorPicker>
  </ColorPickerContent>
</ColorPickerPopover>
```

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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`.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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()`.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## API reference

### ColorPicker

The root: owns the color, format, mode, gradient and image state, and renders the standard stacked layout unless you pass `children`. Forwards native `<div>` props except `onChange` and `defaultValue`; every part accepts `className`, merged last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| value | string | - | Controlled solid color as hex, `#rrggbb` or `#rrggbbaa`. |
| defaultValue | string | "#3b82f6" | Initial solid color when uncontrolled. |
| onValueChange | (hex: string) => void | - | Fires with the new hex on every solid-color change; it carries the `aa` byte once alpha drops below 100%. |
| size | "sm" \| "md" | "md" | Panel footprint: `md` is the full 324px panel, `sm` the 216px one with no fields row. |
| density | "comfortable" \| "compact" | - | Only picks the default `size` (`compact` gives `sm`) when passed explicitly; it does not read an ambient `DensityProvider`, and `size` always wins. |
| surface | "card" \| "plain" | "card" | `card` paints its own border, radius and elevation; `plain` inherits whatever holds it. |
| format | "hex" \| "hsl" \| "rgb" | - | Controlled channel format of the fields row; display only, the color never changes. |
| defaultFormat | "hex" \| "hsl" \| "rgb" | "hex" | Initial channel format when uncontrolled. |
| onFormatChange | (format: "hex" \| "hsl" \| "rgb") => void | - | Fires when the channel format changes. |
| showAlpha | boolean | true | Show the alpha rail and its percentage field. |
| showInput | boolean | true at size="md" | Show the format switcher and the fields row, which are one unit; off by default at `sm`. |
| showPresets | boolean | true | Show the preset swatch palette. |
| presets | string[] | defaultColorPresets | Hex colors for the preset palette; the default is 16 colors from Koala's ramps. |
| modes | ("solid" \| "gradient" \| "image")[] | ["solid"] | Fill kinds to offer; two or more add the fill-type tile row at the top. |
| mode | "solid" \| "gradient" \| "image" | - | Controlled active fill mode. |
| defaultMode | "solid" \| "gradient" \| "image" | modes[0] | Initial fill mode when uncontrolled. |
| onModeChange | (mode: "solid" \| "gradient" \| "image") => void | - | Fires when the active fill mode changes. |
| onFillChange | (fill: string) => void | - | Fires in every mode with one CSS value: a hex, a `linear-gradient()` or `radial-gradient()`, or `url("…")`. |
| defaultGradient | GradientValue | - | Initial gradient, `{ type, angle, stops }`; defaults to a 90° indigo to pink linear gradient. |
| defaultImage | ColorPickerImageValue | { src: "", fit: "cover" } | Initial image fill when uncontrolled. |
| children | React.ReactNode | - | Recompose the parts yourself; omit for the standard layout. |

| CSS variable | Description |
| --- | --- |
| --surface | Set to `var(--popover)` in the `card` surface, read by the nested fields and swatch rings. |

### ColorPickerFormat

The HEX / HSL / RGB switcher, a segmented `ToggleGroup` with radio semantics that always keeps one format chosen. Takes only `className`.

### ColorPickerArea

The 2D saturation and brightness square, a focusable `role="slider"`; arrow keys nudge by 1, or 10 with Shift. Takes only `className`.

### ColorPickerControls

The hue rail with the alpha rail under it when `showAlpha` is on: `ColorPickerHueSlider` plus `ColorPickerAlphaSlider`. Takes only `className`.

### ColorPickerHueSlider

The hue rail on its own, a Radix Slider from 0 to 360. Takes only `className`.

### ColorPickerAlphaSlider

The alpha rail on its own, a Radix Slider from 0 to 100 over a checkerboard. Takes only `className`.

### ColorPickerFields

The channel row for the active format: one hex box, or three numeric fields for HSL and RGB, plus an alpha percentage when `showAlpha` is on. Takes only `className`.

### ColorPickerHexInput

The hex field on its own, with a `#` prefix; it commits as soon as the text parses. Takes only `className`.

### ColorPickerEyeDropper

An icon button that samples a pixel from the screen; renders nothing where the browser has no `EyeDropper` API. Takes only `className`.

### ColorPickerPreview

A 36px chip of the current color over a checkerboard, for layouts that want one. Takes only `className`.

### ColorPickerSwatches

The preset palette: a labelled section fenced off by a hairline, holding a wrapping row of 24px chips.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| presets | string[] | defaultColorPresets | Hex colors to show; the default layout passes the root's `presets` through. |
| label | React.ReactNode | "Colors" | Section heading; `null` drops it. |

| Data attribute | Description |
| --- | --- |
| data-selected | `"true"` on the chip matching the current color, which also carries `aria-pressed`. |

### ColorPickerModes

The fill-type row of live-preview tiles (Solid, Linear, Radial, Image), filtered by `modes`. Renders nothing with fewer than two tiles. Takes only `className`.

### ColorPickerGradient

The gradient editor: a stop track (click to add, drag or arrow keys to move, Delete to remove while more than two stops remain) and an angle rail for linear gradients. Takes only `className`.

| Data attribute | Description |
| --- | --- |
| data-active | `"true"` on the stop button being edited. |

### ColorPickerImage

The image fill: an upload button or live preview, a URL field, and a Cover / Contain toggle once an image is set. Takes only `className`.

### ColorPickerPopover

Radix `Popover.Root`; renders no DOM.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| open | boolean | - | Controlled open state. |
| defaultOpen | boolean | false | Initial open state when uncontrolled. |
| onOpenChange | (open: boolean) => void | - | Called when the popover opens or closes. |
| modal | boolean | false | Trap focus and block outside interaction while open. |

### ColorPickerTrigger

Radix `Popover.Trigger`, unstyled; renders a `<button>` and forwards all its props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| asChild | boolean | false | Merge onto your own control, usually a `ColorPickerTriggerSwatch`. |

| Data attribute | Description |
| --- | --- |
| data-state | `"open"` or `"closed"`. |

### ColorPickerTriggerSwatch

A ready-made 36px swatch button showing a color over a checkerboard. Forwards native `<button>` props except `value`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| value* | string | - | The color to show; pass the same value you give the picker. |

### ColorPickerContent

Radix `Popover.Content` portalled to the body; it only positions and animates, since the `ColorPicker` inside paints the card. Forwards all its props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| side | "top" \| "right" \| "bottom" \| "left" | "bottom" | Preferred side of the trigger; the panel flips when there is no room. |
| align | "start" \| "center" \| "end" | "start" | Alignment against the trigger. |
| sideOffset | number | 8 | Gap in pixels between the trigger and the panel. |

| Data attribute | Description |
| --- | --- |
| data-state | `"open"` or `"closed"`. |
| data-side | The side the panel actually opened on, after collisions. |
| data-align | `"start"`, `"center"` or `"end"`. |

## 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/combobox.md -->

# Combobox

A text field that filters a list as you type. The field is Koala's Input and the list is Select's panel, so it sits beside both without a seam. Autocomplete is the free-text sibling.

```tsx
const FRAMEWORKS = [
  { value: "astro", label: "Astro" },
  { value: "next", label: "Next.js" },
  { value: "nuxt", label: "Nuxt" },
  { value: "remix", label: "Remix" },
  { value: "solid", label: "SolidStart" },
  { value: "svelte", label: "SvelteKit" },
]
const frameworkLabel = (value) => FRAMEWORKS.find((f) => f.value === value)?.label ?? value

<Combobox defaultValue="next" itemToString={frameworkLabel}>
  <ComboboxInput aria-label="Framework" placeholder="Pick a framework" className="w-64" />
  <ComboboxContent>
    {FRAMEWORKS.map((f) => (
      <ComboboxItem key={f.value} value={f.value}>{f.label}</ComboboxItem>
    ))}
    <ComboboxEmpty>No framework found.</ComboboxEmpty>
  </ComboboxContent>
</Combobox>
```

## 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 combobox
```

Manual: run `npm install radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/combobox/` 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 {
  Combobox, ComboboxInput, ComboboxContent, ComboboxItem, ComboboxEmpty,
} from "@/components/ui/combobox"

export function Example() {
  const [value, setValue] = useState("")
  return (
    <Combobox value={value} onValueChange={setValue}>
      <ComboboxInput aria-label="Framework" placeholder="Pick a framework" />
      <ComboboxContent>
        <ComboboxItem value="next">Next.js</ComboboxItem>
        <ComboboxItem value="remix">Remix</ComboboxItem>
        <ComboboxEmpty />
      </ComboboxContent>
    </Combobox>
  )
}
```

## Anatomy

```tsx
import {
  Combobox, Autocomplete, ComboboxInput, ComboboxContent, ComboboxItem,
  ComboboxGroup, ComboboxLabel, ComboboxSeparator, ComboboxEmpty, ComboboxStatus,
} from "@/components/ui/combobox"

<Combobox>            {/* or <Autocomplete> */}
  <ComboboxInput />
  <ComboboxContent>
    <ComboboxGroup>
      <ComboboxLabel />
      <ComboboxItem />
    </ComboboxGroup>
    <ComboboxSeparator />
    <ComboboxStatus />
    <ComboboxEmpty />
  </ComboboxContent>
</Combobox>
```

## Icons and flags

Rows take a leading icon like Select rows do, muted beside a medium label. Pass the picked option's glyph to `prefix` so the field shows it too. For countries, use [Flag](https://www.koalaui.com/docs/foundations/flags.md) and match on the ISO code with `keywords`.

```tsx
const [value, setValue] = useState("in-progress")
const Icon = STATUSES.find((s) => s.value === value)?.icon ?? Circle

<Combobox value={value} onValueChange={setValue} itemToString={statusLabel}>
  <ComboboxInput aria-label="Status" placeholder="Set status" prefix={<Icon />} className="w-64" />
  <ComboboxContent>
    {STATUSES.map(({ value, label, icon: StatusIcon }) => (
      <ComboboxItem key={value} value={value}><StatusIcon /> {label}</ComboboxItem>
    ))}
    <ComboboxEmpty>No status found.</ComboboxEmpty>
  </ComboboxContent>
</Combobox>
```

```tsx
import { Flag } from "@/components/ui/flag"
import { COUNTRIES, COUNTRY_BY_ISO2 } from "@/components/ui/input"

<Combobox value={value} onValueChange={setValue} itemToString={(code) => COUNTRY_BY_ISO2[code]?.name ?? code}>
  <ComboboxInput
    aria-label="Country"
    placeholder="Search countries"
    prefix={value ? <Flag code={value} shape="circle" size="sm" /> : <MagnifyingGlass />}
    className="w-64"
  />
  <ComboboxContent>
    {COUNTRIES.map((c) => (
      <ComboboxItem key={c.iso2} value={c.iso2} textValue={c.name} keywords={[c.iso2]}>
        <Flag code={c.iso2} shape="circle" /> {c.name}
      </ComboboxItem>
    ))}
    <ComboboxEmpty>No country found.</ComboboxEmpty>
  </ComboboxContent>
</Combobox>
```

## Groups

`ComboboxGroup` with a `ComboboxLabel` heading, split by `ComboboxSeparator`. A group hides once all its rows filter out, and separators step aside while you type, so no orphan rules are left.

```tsx
<Combobox>
  <ComboboxInput aria-label="Timezone" placeholder="Pick a timezone" className="w-64" />
  <ComboboxContent>
    {ZONES.map((group, i) => (
      <Fragment key={group.region}>
        {i > 0 && <ComboboxSeparator />}
        <ComboboxGroup>
          <ComboboxLabel>{group.region}</ComboboxLabel>
          {group.zones.map((z) => (
            <ComboboxItem key={z.value} value={z.value} keywords={[z.value]}>{z.label}</ComboboxItem>
          ))}
        </ComboboxGroup>
      </Fragment>
    ))}
    <ComboboxEmpty>No timezone found.</ComboboxEmpty>
  </ComboboxContent>
</Combobox>
```

## Clearable

The clear button shows while the field holds text. It stays out of the tab order because Escape does the same from the keyboard. Turn it off with `showClear={false}`.

```tsx
<Combobox defaultValue="svelte" itemToString={frameworkLabel}>
  <ComboboxInput aria-label="Framework, clearable" />
  <ComboboxContent>{/* rows */}</ComboboxContent>
</Combobox>

<Combobox defaultValue="svelte" itemToString={frameworkLabel}>
  <ComboboxInput aria-label="Framework, not clearable" showClear={false} />
  <ComboboxContent>{/* rows */}</ComboboxContent>
</Combobox>
```

## Async search

Control `inputValue` to fetch as the user types, and pass `filter={null}` so the server's results show as they are. `ComboboxStatus` holds the list's place while a request is in flight and is announced politely.

```tsx
const [query, setQuery] = useState("")
const [results, setResults] = useState([])
const [loading, setLoading] = useState(false)

useEffect(() => {
  if (!query.trim()) return
  const controller = new AbortController()
  searchPeople(query, controller.signal).then((found) => {
    setResults(found)
    setLoading(false)
  }).catch(() => {})
  return () => controller.abort()
}, [query])

<Combobox
  inputValue={query}
  onInputValueChange={(next) => {
    setQuery(next)
    setLoading(next.trim().length > 0)
  }}
  filter={null}
>
  <ComboboxInput aria-label="Assignee" placeholder="Search people" prefix={<MagnifyingGlass />} />
  <ComboboxContent>
    {!query.trim() ? (
      <ComboboxStatus>Type a name to search.</ComboboxStatus>
    ) : loading ? (
      <ComboboxStatus loading>Searching</ComboboxStatus>
    ) : (
      <>
        {results.map((name) => <ComboboxItem key={name} value={name}>{name}</ComboboxItem>)}
        <ComboboxEmpty>Nobody by that name.</ComboboxEmpty>
      </>
    )}
  </ComboboxContent>
</Combobox>
```

## Creatable

Add a row for the typed text when nothing matches it exactly. Its `textValue` is the query, so the filter always keeps it, and picking it commits the new value like any other row.

```tsx
const [labels, setLabels] = useState(["Bug", "Design", "Docs", "Feature"])
const [value, setValue] = useState("")
const [query, setQuery] = useState("")
const typed = query.trim()
const exists = labels.some((l) => l.toLowerCase() === typed.toLowerCase())

<Combobox
  value={value}
  onValueChange={(next) => {
    if (next && !labels.includes(next)) setLabels((l) => [...l, next].sort())
    setValue(next)
  }}
  inputValue={query}
  onInputValueChange={setQuery}
>
  <ComboboxInput aria-label="Label" placeholder="Add a label" prefix={<Tag />} />
  <ComboboxContent>
    {labels.map((l) => <ComboboxItem key={l} value={l}><Tag /> {l}</ComboboxItem>)}
    {typed && !exists ? (
      <ComboboxItem value={typed} textValue={typed}><Plus /> Create "{typed}"</ComboboxItem>
    ) : null}
  </ComboboxContent>
</Combobox>
```

## Autocomplete

`Autocomplete` takes the same parts, but the text is the value: anything typed is valid, and a suggestion only fills it in. Nothing is highlighted until you arrow down, so Enter keeps what you wrote. Rows carry no check.

```tsx
const [value, setValue] = useState("")

<Autocomplete value={value} onValueChange={setValue}>
  <ComboboxInput aria-label="Search the docs" placeholder="Search the docs" prefix={<MagnifyingGlass />} />
  <ComboboxContent>
    {["Accordion", "Button", "Combobox", "Dialog", "Popover", "Select", "Tooltip"].map((s) => (
      <ComboboxItem key={s} value={s}>{s}</ComboboxItem>
    ))}
  </ComboboxContent>
</Autocomplete>
```

## Inside a Field

In a [Field](https://www.koalaui.com/docs/components/field.md), the label names both the field and the list, the hint is wired as its description, and `hasError` and `disabled` cascade. Pass `name` to post the value with the form.

```tsx
<Field hasError={touched && !value} required className="w-64">
  <FieldLabel>Framework</FieldLabel>
  <Combobox
    value={value}
    onValueChange={setValue}
    onOpenChange={(open) => !open && setTouched(true)}
    itemToString={frameworkLabel}
    name="framework"
  >
    <ComboboxInput placeholder="Pick a framework" />
    <ComboboxContent>{/* rows */}</ComboboxContent>
  </Combobox>
  <FieldHint>{touched && !value ? "Pick a framework to continue." : "Used to scaffold your project."}</FieldHint>
</Field>
```

## Disabled

`disabled` on the root locks the whole field. On a row, it stays visible but the keyboard skips it and a click does nothing.

```tsx
<Combobox defaultValue="next" itemToString={frameworkLabel} disabled>
  <ComboboxInput aria-label="Framework, disabled" />
  <ComboboxContent />
</Combobox>

<Combobox>
  <ComboboxInput aria-label="Plan" placeholder="Pick a plan" />
  <ComboboxContent>
    <ComboboxItem value="free">Free</ComboboxItem>
    <ComboboxItem value="pro">Pro</ComboboxItem>
    <ComboboxItem value="enterprise" disabled>Enterprise (contact sales)</ComboboxItem>
  </ComboboxContent>
</Combobox>
```

## Sizes

`size` sets the field height on the shared control scale: sm 32, md 36, lg 40px, level with Input, Select and Button. Typed text stays 14px at every size.

```tsx
<Combobox size="sm">…</Combobox>
<Combobox size="md">…</Combobox>
<Combobox size="lg">…</Combobox>
```

## Keyboard

Focus never leaves the field. Arrow Down and Arrow Up open the list and move the highlight; Home and End jump to the ends while it is open. Enter picks the highlighted row. Escape first clears what you typed, then closes the list, then clears the value. Tab closes and moves on; leaving with exactly an option's text picks it, anything else reverts.

## API reference

### Combobox

Root. Owns the value, the typed text and the open state. Renders no DOM of its own.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| value | string | - | Controlled selected value. `""` means nothing is selected. |
| defaultValue | string | "" | Initial value when uncontrolled. |
| onValueChange | (value: string) => void | - | Called when an option is picked or the value is cleared. |
| inputValue | string | - | Controlled text in the field, e.g. to drive a search request. |
| defaultInputValue | string | - | Initial text when uncontrolled. |
| onInputValueChange | (inputValue: string) => void | - | Called on every keystroke, pick, clear and revert. |
| itemToString | (value: string) => string | - | Label shown for a value seeded from outside, before the list has rendered. |
| autoHighlight | boolean | true | Highlight the first match while typing, so Enter picks it. |
| openOnInputClick | boolean | true | Open the list when the field is clicked. |
| size | "sm" \| "md" \| "lg" | - | Field height, shared with Input, Select and Button (32, 36, 40px). Defaults from density. |
| density | "comfortable" \| "compact" | - | Row spacing in the list. Also picks the default `size`. |
| open | boolean | - | Controlled open state of the list. |
| defaultOpen | boolean | false | Open state on mount when uncontrolled. |
| onOpenChange | (open: boolean) => void | - | Called when the list opens or closes. |
| filter | (query: string, textValue: string, keywords?: string[]) => number \| null | contains | Return 0 to hide a row. Case and accent blind by default. Pass `null` to show every row (server results). |
| name | string | - | Posts the value with a native form submit. |
| disabled | boolean | - | Disables the field. Inherited from a surrounding `Field`. |

### Autocomplete

Root for free text. The field's text is the value; picking a row fills it in. Takes the same parts.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| value | string | - | Controlled text. |
| defaultValue | string | "" | Initial text when uncontrolled. |
| onValueChange | (value: string) => void | - | Called on every keystroke and pick. |
| autoHighlight | boolean | false | Off by default, so Enter keeps what was typed. |
| openOnInputClick | boolean | false | Opens on typing only, by default. |
| size | "sm" \| "md" \| "lg" | - | Field height, shared with Input, Select and Button (32, 36, 40px). Defaults from density. |
| density | "comfortable" \| "compact" | - | Row spacing in the list. Also picks the default `size`. |
| open | boolean | - | Controlled open state of the list. |
| defaultOpen | boolean | false | Open state on mount when uncontrolled. |
| onOpenChange | (open: boolean) => void | - | Called when the list opens or closes. |
| filter | (query: string, textValue: string, keywords?: string[]) => number \| null | contains | Return 0 to hide a row. Case and accent blind by default. Pass `null` to show every row (server results). |
| name | string | - | Posts the value with a native form submit. |
| disabled | boolean | - | Disables the field. Inherited from a surrounding `Field`. |

### ComboboxInput

The canonical Input with `role="combobox"`, a clear button and a chevron. Other props go to the `<input>`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| prefix | ReactNode | - | A leading glyph: a search icon, the picked option's flag. |
| showClear | boolean | true | Show the clear button while the field holds text. |
| showTrigger | boolean | true (Combobox), false (Autocomplete) | Show the chevron that opens the list. |
| className | string | - | Styles the field's frame. |
| inputClassName | string | - | Styles the text input. |

| Data attribute | Description |
| --- | --- |
| data-state | `open` or `closed`, on the frame. |

### ComboboxContent

The floating `listbox`, anchored to the field and exactly its width. Accepts Radix Popover content props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| label | string | "Options" | Accessible name, when there is no `Field` label to borrow. |
| align | "start" \| "center" \| "end" | "start" | Alignment against the field. |
| sideOffset | number | 6 | Gap from the field, in px. |

| Data attribute | Description |
| --- | --- |
| data-side | `top` or `bottom`, after collision handling. |

| CSS variable | Description |
| --- | --- |
| --radix-popover-content-available-height | Caps the list height so it scrolls inside the viewport. |

### ComboboxItem

An `option` row: Select's anatomy, with the ink check on the right.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| value* | string | - | The value this row commits. |
| textValue | string | row text | What the filter matches and what the field shows once picked. |
| keywords | string[] | - | Extra terms that also match (a code, a synonym). |
| disabled | boolean | - | Skipped by the keyboard and not pickable. |
| onSelect | (value: string) => void | - | Fires when the row is picked. |

| Data attribute | Description |
| --- | --- |
| data-active | Present on the highlighted row. |
| data-state | `checked` on the selected row. |
| data-disabled | Present when disabled. |

### ComboboxGroup

A `group` of rows. Hides itself when every row in it filters out.

### ComboboxLabel

A group heading, muted.

### ComboboxSeparator

A hairline between groups. Hidden while filtering.

### ComboboxEmpty

Shown only while the list has no rows. Defaults to "No results found."

### ComboboxStatus

A polite live message in the list: searching, an error, a hint.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| loading | boolean | - | Lead with the Spinner. |

## FAQ

### Combobox, Autocomplete or SelectSearch?

Combobox when the user types to find one option and the field itself is the control. Autocomplete when any text is valid and options only suggest (a search box). SelectSearch when you want a Select trigger that opens a panel with a search field inside it.

### Why does a seeded value need itemToString?

Rows only exist while the list is open, so on first render the field has no label for a `defaultValue` or controlled value. `itemToString` maps the value to its label. Without it the field shows the raw value.

### How do I filter on the server?

Control `inputValue`, fetch in an effect, render the results as rows and pass `filter={null}`. Show `ComboboxStatus loading` while the request is in flight.

### Does it work with long lists?

Every row is rendered, which is right for a few hundred local options like countries. Add `[content-visibility:auto]` on rows to skip painting off-screen ones. For unbounded remote data, search on the server instead.

### Is it accessible?

It follows the WAI-ARIA combobox pattern: the input has `role="combobox"`, `aria-expanded`, `aria-controls` and `aria-activedescendant`; the list is a `listbox` of `option` rows with `aria-selected`.

---

<!-- 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Installation

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

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

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

Pro: `command` comes with a [Koala UI Pro license](https://www.koalaui.com/pro). Its source is not published in these docs.

## Usage

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

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.

## Anatomy

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

<Command>
  <CommandInput />
  <CommandList>
    <CommandEmpty />
    <CommandGroup>
      <CommandItem>
        <CommandShortcut />
      </CommandItem>
    </CommandGroup>
    <CommandSeparator />
  </CommandList>
</Command>

{/* or, as a modal: CommandDialog in place of Command */}
<CommandDialog>
  <CommandInput />
  <CommandList />
</CommandDialog>
```

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## API reference

### Command

The palette root: owns the query and the roving highlight, and paints the popover surface. Forwards all native `<div>` props; every part accepts `className`, merged last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| search | string | - | Controlled search query. |
| defaultSearch | string | "" | Initial query when uncontrolled. |
| onSearchChange | (search: string) => void | - | Fires on every keystroke in the search field. |
| filter | (search: string, value: string, keywords?: string[]) => number | substring match | Return `0` to hide a row, any positive number to keep it. The default is a case-insensitive substring match on `value` and `keywords`; an empty query keeps every row. |
| onSelect | (value: string) => void | - | Fires when any row is chosen, after that row's own `onSelect`. |
| label | string | "Commands" | Accessible name for the search field and the result list. |
| density | "comfortable" \| "compact" | "compact" | Search row height and row padding. Falls back to the nearest `DensityProvider`. |

| CSS variable | Description |
| --- | --- |
| --surface | Set to `var(--popover)`, read by nested controls. |
| --command-list-max | Caps the list height; defaults to `min(28rem, 64vh)`. |

### CommandDialog

The palette in a Radix Dialog (focus trap, scroll lock, Escape to close), opening on the fast duration and hung from its search field. Takes every `Command` prop; `className` goes on the positioned dialog content, not the palette.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| open | boolean | - | Controlled open state. |
| defaultOpen | boolean | - | Initial open state when uncontrolled. |
| onOpenChange | (open: boolean) => void | - | Called when the dialog opens or closes. |
| closeOnSelect | boolean | true | Close after a row is chosen. Works controlled (`onOpenChange(false)` fires) and uncontrolled with `defaultOpen`. |
| title | string | "Command palette" | Visually hidden dialog title for assistive tech. |
| description | string | "Search for a command to run." | Visually hidden dialog description for assistive tech. |

| Data attribute | Description |
| --- | --- |
| data-state | `"open"` or `"closed"`, on the dialog content and the overlay. |

### CommandInput

The search field, a `combobox` that keeps focus while the active row is announced through `aria-activedescendant`. Forwards native `<input>` props except `value` and `onChange`; inside `CommandDialog` it ends with an `Esc` hint that closes the dialog on click.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| icon | boolean \| React.ReactNode | false | Leading glyph: `true` shows the magnifying glass, a node renders your own icon. |
| placeholder | string | "Type a command or search…" | Placeholder text for the empty field. |

### CommandList

The scrolling `listbox` viewport, which eases its height as rows filter in and out. It also paints the sliding highlight, so rows must live inside one. Forwards all native `<div>` props.

### CommandEmpty

Shown only while no row matches; children default to `No results found.` Forwards all native `<div>` props.

### CommandGroup

A labeled section that hides, heading and all, when every row inside it filters out. Forwards all native `<div>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| heading | React.ReactNode | - | Section label above the rows, also the group's accessible name. |

### CommandItem

A selectable row, `role="option"`; a row that does not match the query renders nothing. Forwards native `<div>` props except `onSelect`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| value* | string | - | The row's searchable identity, also passed to `onSelect`. |
| keywords | string[] | - | Extra terms to match on: synonyms, ids, a page path. |
| disabled | boolean | false | Keeps the row visible but out of the keyboard order and unclickable. |
| onSelect | (value: string) => void | - | Fires when the row is chosen by click or Enter. |

| Data attribute | Description |
| --- | --- |
| data-active | `"true"` on the highlighted row. |
| data-disabled | Present when `disabled` is set. |
| data-value | The row's `value`. |

### CommandSeparator

A rule between groups that hides itself when filtering strands it beside an empty group or over the empty state. Forwards all native `<div>` props.

### CommandShortcut

Trailing key hint on a row; drop `Kbd` children inside. Forwards all native `<span>` props.

## 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.

### Where does focus go when CommandDialog closes?

A palette opened with ⌘K has no trigger, so CommandDialog remembers the element that had focus when it opened, such as the field you were typing in, and returns focus there on close, as long as that element is still on the page. Without that, keyboard users would land back at the top of the document after every command.

### 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, controlled or uncontrolled (a controlled `open` also gets `onOpenChange(false)`); 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/compare-slider.md -->

# Compare Slider

Two pictures in one frame and a divider to drag between them, for a redesign, a retouch or a colour grade. A press anywhere glides the divider there; a drag keeps it under the hand.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Installation

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

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

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

Pro: `compare-slider` comes with a [Koala UI Pro license](https://www.koalaui.com/pro). Its source is not published in these docs.

## Usage

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Anatomy

```tsx
import {
  CompareSlider,
  CompareSliderBefore,
  CompareSliderAfter,
  CompareSliderHandle,
  CompareSliderLabel,
} from "@/components/ui/compare-slider"

<CompareSlider>
  <CompareSliderBefore>
    <CompareSliderLabel />
  </CompareSliderBefore>
  <CompareSliderAfter>
    <CompareSliderLabel />
  </CompareSliderAfter>
  <CompareSliderHandle />
</CompareSlider>
```

## Vertical

`orientation="vertical"` runs the divider top to bottom, with the before picture on top. Labels move with it: before in the top corner, after in the bottom one. Give the frame a taller ratio, such as `aspect-[4/5]`, for portrait pictures.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Follow the pointer

With `hover`, the divider follows a mouse across the frame without a press, easing over a short transition so a shaky hand still reads smooth. On touch it stays a drag, since a finger has no hover. The quiet `variant="line"` handle suits it: the pointer is already the grip.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Handles

`reveal`, the default, rests as a small dot threaded on the hairline and unfolds into a pill grip when the frame is hovered, the divider moves or the keyboard lands on it; on a touch screen, with no hover to discover it, the grip stays open. `knob` keeps a round grip shown at all times; `line` is the hairline alone. Every line carries an invisible 24px strip, so a finger can take the divider anywhere along it. The handle is a part, not a prop: leave it out and the frame still slides from a press, a tap or the keyboard.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Controlled

Pass `value` and `onValueChange` to drive the divider from outside. A new value glides there instead of jumping, so buttons that show one side or the other feel like the same gesture as a drag.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## API reference

### CompareSlider

The frame, a Radix Slider root that spans both pictures: a press anywhere moves the divider. It renders a zero-size thumb that carries `role="slider"`, the value and the keyboard. `aspect-video` and `rounded-xl` by default (any `aspect-*` or `h-*` class overrides). Forwards Radix Slider root props, and every part accepts `className`, merged last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| value | number | - | Where the divider sits, 0 to 100 from the left (or top) edge. Controlled. |
| defaultValue | number | 50 | Where the divider starts. Uncontrolled. |
| onValueChange | (value: number) => void | - | Called on every move. |
| onValueCommit | (value: number) => void | - | Called when a drag ends, a tap lands or a key moves the divider. |
| orientation | "horizontal" \| "vertical" | "horizontal" | Which way the divider travels. Vertical puts the before picture on top. |
| hover | boolean | false | The divider follows a mouse over the frame, no press needed. Touch still drags the handle. |
| keyboardStep | number | 5 | How far an arrow key moves the divider, in percent. `Shift` + arrow moves 1. |
| disabled | boolean | false | Freezes the divider and dims the grip. |
| aria-label | string | "Comparison position" | Names the slider thumb for screen readers. |

| Data attribute | Description |
| --- | --- |
| data-moving | `"drag"` while the hand drags the divider, `"hover"` while it follows the mouse. Absent while a jump glides. |
| data-orientation | `horizontal` or `vertical`. |
| data-disabled | Present when disabled. |

| CSS variable | Description |
| --- | --- |
| --compare-position | The divider's position as a percentage. Both clips and the handle read it. |

### CompareSliderBefore

The picture left of (or above) the divider, clipped at it. A direct `<img>` or `<video>` child fills the frame with `object-cover`. Forwards all native `<div>` props.

### CompareSliderAfter

The picture right of (or below) the divider, clipped at it. Forwards all native `<div>` props.

### CompareSliderHandle

The divider the reader sees: a white hairline with a 24px touch strip and, by default, a round grip whose carets part by a pixel while the frame is hovered. Visual only; focus shows as a brand ring on the grip. Forwards all native `<div>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| variant | "reveal" \| "knob" \| "line" | "reveal" | `reveal` rests as a dot on the line and opens into a pill grip on hover, while moving or on keyboard focus (always open on touch). `knob` keeps a round grip shown; `line` drops the grip for a quieter frame. |
| revealed | boolean | false | Keeps the `reveal` grip open at rest. |
| children | React.ReactNode | - | Replaces the two carets inside the grip. |

### CompareSliderLabel

A chip naming the picture, placed inside `CompareSliderBefore` or `CompareSliderAfter`. It pins to that picture's outer corner and fades out while the divider passes over it. Forwards all native `<span>` props.

| Data attribute | Description |
| --- | --- |
| data-covered | Present while the divider is over the label. |

## FAQ

### Does it scroll the page on phones?

Yes. A finger that lands on the picture and moves is left to scroll the page; a short tap moves the divider there. Dragging starts from the handle's line or grip, which take the gesture for themselves.

### How does it work with a keyboard?

Tab to the frame and use the arrow keys: 5% a press, 1% with Shift, 25% with Page Up and Page Down, and Home and End for either picture. Screen readers announce it as a slider with its percentage.

### Can I compare videos, or transparent images?

Yes. An <img> or <video> fills its side with object-cover, and both sides are clipped at the divider rather than stacked, so a transparent PNG never shows the other picture through it.

### Why does a press glide but a drag does not?

A drag is direct manipulation: any easing would leave the divider trailing the hand. A press, a tap, a key or a new value is a jump, and a short glide shows where the divider went. Reduced motion turns every glide off.

---

<!-- 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 "koala-icons"
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>
  )
}
```

## Anatomy

```tsx
import {
  ContextMenu,
  ContextMenuTrigger,
  ContextMenuContent,
  ContextMenuLabel,
  ContextMenuGroup,
  ContextMenuItem,
  ContextMenuShortcut,
  ContextMenuCheckboxItem,
  ContextMenuRadioGroup,
  ContextMenuRadioItem,
  ContextMenuSeparator,
  ContextMenuSub,
  ContextMenuSubTrigger,
  ContextMenuSubContent,
} from "@/components/ui/context-menu"

<ContextMenu>
  <ContextMenuTrigger />
  <ContextMenuContent>
    <ContextMenuLabel />
    <ContextMenuGroup>
      <ContextMenuItem>
        <ContextMenuShortcut />
      </ContextMenuItem>
    </ContextMenuGroup>
    <ContextMenuCheckboxItem />
    <ContextMenuRadioGroup>
      <ContextMenuRadioItem />
    </ContextMenuRadioGroup>
    <ContextMenuSeparator />
    <ContextMenuSub>
      <ContextMenuSubTrigger />
      <ContextMenuSubContent />
    </ContextMenuSub>
  </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` closes the menu when toggled, like any row; pass `closeOnSelect={false}` to flip several 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>
```

## API reference

### ContextMenu

The root, Radix `ContextMenu.Root`; renders no DOM. Every part that renders an element accepts `className`, merged last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| onOpenChange | (open: boolean) => void | - | Called when the menu opens or closes. A context menu has no controlled `open`: the gesture opens it. |
| modal | boolean | true | Block outside pointer interaction and hide the rest of the page from screen readers while open. |
| dir | "ltr" \| "rtl" | - | Reading direction for keyboard navigation and submenu placement. |

### ContextMenuTrigger

The area that opens the menu on right-click or long-press, Radix `ContextMenu.Trigger`. Renders a `<span>` and forwards all its props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| asChild | boolean | false | Merge onto your own element (a Card, a figure, a row) instead of rendering a `<span>`. |
| disabled | boolean | false | Let the native browser context menu open instead. |

| Data attribute | Description |
| --- | --- |
| data-state | `"open"` or `"closed"`. |
| data-disabled | Present when disabled. |

### ContextMenuContent

The menu, Radix `ContextMenu.Content` portalled to the body and anchored to the cursor; forwards all its props. Declares `--surface`, so a nested control blends with the menu.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| density | "comfortable" \| "compact" | "compact" | Row height for every row inside, 36px or 32px. Unset, the rows follow the nearest `DensityProvider`. |
| updatePositionStrategy | "optimized" \| "always" | "always" | `always` re-anchors an open menu to each new right-click point; `optimized` only re-measures on scroll and resize. |
| collisionPadding | number | 8 | Distance in pixels kept from the viewport edge; also shrinks the width the menu is capped at. |
| alignOffset | number | 0 | Offset in pixels from the cursor along the alignment axis. |
| avoidCollisions | boolean | true | Flip and shift to stay on screen. |
| loop | boolean | false | Wrap keyboard focus from the last row to the first. |
| onCloseAutoFocus | (event: Event) => void | - | Called as focus returns on close; `preventDefault()` to keep it elsewhere. |
| onEscapeKeyDown | (event: KeyboardEvent) => void | - | Called on Escape; `preventDefault()` to keep the menu open. |

| Data attribute | Description |
| --- | --- |
| data-state | `"open"` or `"closed"`. |
| data-side | The side of the cursor the menu opened on, after collisions. |
| data-align | `"start"`, `"center"` or `"end"`. |

| CSS variable | Description |
| --- | --- |
| --radix-popper-transform-origin | The cursor-side origin the menu grows from. |
| --radix-context-menu-content-available-width | Width left beside the cursor; the menu's `max-width`. |
| --radix-context-menu-content-available-height | Height left between the cursor and the viewport edge. |
| --surface | Set to `var(--popover)`, read by nested Inputs and Selects. |

### ContextMenuItem

One action row, Radix `ContextMenu.Item`; forwards all its props. A leading Koala icon is muted and sized to 20px.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| variant | "default" \| "destructive" | "default" | `destructive` colours the label, icon and highlight red. |
| inset | boolean | false | Indent the label to line up with siblings that lead with an icon. |
| density | "comfortable" \| "compact" | "compact" | Row height, 36px or 32px. Falls back to the menu's `density`, then the nearest `DensityProvider`. |
| disabled | boolean | false | Skip the row in keyboard navigation and ignore clicks. |
| onSelect | (event: Event) => void | - | Called when the row is chosen; `preventDefault()` to keep the menu open. |
| textValue | string | - | Text used for typeahead when the row's content is not plain text. |
| asChild | boolean | false | Merge onto your own element, such as a link. |

| Data attribute | Description |
| --- | --- |
| data-highlighted | Present while the row has keyboard or pointer focus. |
| data-disabled | Present when the row is disabled. |
| data-inset | Present when `inset` is set. |

### ContextMenuCheckboxItem

A toggle row, Radix `ContextMenu.CheckboxItem` (`menuitemcheckbox`); forwards all its props. Shows an ink check on the right, or a mini Switch.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| checked | boolean \| "indeterminate" | - | The checked state. |
| onCheckedChange | (checked: boolean) => void | - | Called when the row is toggled. |
| variant | "check" \| "switch" | "check" | How the state reads: the check, or a Switch drawing for a setting that applies the moment it flips. |
| closeOnSelect | boolean | true | Close the menu when the row is toggled. Defaults to `false` for `variant="switch"`. |
| density | "comfortable" \| "compact" | "compact" | Row height, 36px or 32px. Falls back to the menu's `density`, then the nearest `DensityProvider`. |
| disabled | boolean | false | Skip the row and ignore clicks. |
| onSelect | (event: Event) => void | - | Called when the row is chosen. |

| Data attribute | Description |
| --- | --- |
| data-state | `"checked"`, `"unchecked"` or `"indeterminate"`. |
| data-highlighted | Present while the row has keyboard or pointer focus. |
| data-disabled | Present when the row is disabled. |

### ContextMenuRadioGroup

Holds one exclusive choice, Radix `ContextMenu.RadioGroup`. Forwards all native `<div>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| value | string | - | The selected item's value. |
| onValueChange | (value: string) => void | - | Called when another item is chosen. |

### ContextMenuRadioItem

One option in a radio group, Radix `ContextMenu.RadioItem` (`menuitemradio`); the selected row shows the same ink check as a checkbox row.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| value* | string | - | The value this row selects. |
| density | "comfortable" \| "compact" | "compact" | Row height, 36px or 32px. Falls back to the menu's `density`, then the nearest `DensityProvider`. |
| disabled | boolean | false | Skip the row and ignore clicks. |
| onSelect | (event: Event) => void | - | Called when the row is chosen; `preventDefault()` to keep the menu open. |

| Data attribute | Description |
| --- | --- |
| data-state | `"checked"` or `"unchecked"`. |
| data-highlighted | Present while the row has keyboard or pointer focus. |
| data-disabled | Present when the row is disabled. |

### ContextMenuLabel

A small muted section heading, Radix `ContextMenu.Label`; not focusable. Forwards all native `<div>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| inset | boolean | false | Indent to line up with rows that lead with an icon. |
| density | "comfortable" \| "compact" | "compact" | Row height, 36px or 32px. Falls back to the menu's `density`, then the nearest `DensityProvider`. |

### ContextMenuSeparator

A hairline between sections, Radix `ContextMenu.Separator`, stopping at the menu's ring. Forwards all native `<div>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| density | "comfortable" \| "compact" | "compact" | Row height, 36px or 32px. Falls back to the menu's `density`, then the nearest `DensityProvider`. |

### ContextMenuGroup

Groups related rows for assistive tech, Radix `ContextMenu.Group`; unstyled. Forwards all native `<div>` props.

### ContextMenuShortcut

A right-aligned shortcut hint, Koala's `Kbd` at `size="sm"`; decorative, it binds nothing. Forwards all `Kbd` props.

### ContextMenuSub

The root of a nested menu, Radix `ContextMenu.Sub`; renders no DOM.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| open | boolean | - | Controlled open state. |
| defaultOpen | boolean | false | Initial open state when uncontrolled. |
| onOpenChange | (open: boolean) => void | - | Called when the submenu opens or closes. |

### ContextMenuSubTrigger

The row that opens a submenu, Radix `ContextMenu.SubTrigger`, with a caret on the right; forwards all its props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| inset | boolean | false | Indent to line up with rows that lead with an icon. |
| density | "comfortable" \| "compact" | "compact" | Row height, 36px or 32px. Falls back to the menu's `density`, then the nearest `DensityProvider`. |
| disabled | boolean | false | Skip the row and keep the submenu closed. |
| textValue | string | - | Text used for typeahead when the row's content is not plain text. |

| Data attribute | Description |
| --- | --- |
| data-state | `"open"` or `"closed"`. |
| data-highlighted | Present while the row has keyboard or pointer focus. |
| data-disabled | Present when the row is disabled. |

### ContextMenuSubContent

The nested menu, Radix `ContextMenu.SubContent`; same surface as the content, and it animates out on close. Forwards all its props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| density | "comfortable" \| "compact" | "compact" | Row height, 36px or 32px. Falls back to the menu's `density`, then the nearest `DensityProvider`. |
| sideOffset | number | 0 | Gap in pixels between the trigger row and the submenu. |
| alignOffset | number | 0 | Offset in pixels along the alignment axis. |
| collisionPadding | number | 0 | Distance in pixels kept from the viewport edge. |
| loop | boolean | false | Wrap keyboard focus from the last row to the first. |

| Data attribute | Description |
| --- | --- |
| data-state | `"open"` or `"closed"`. |
| data-side | The side the submenu opened on, after collisions. |
| data-align | `"start"`, `"center"` or `"end"`. |

| CSS variable | Description |
| --- | --- |
| --radix-popper-transform-origin | The trigger-side origin the submenu grows from. |

### ContextMenuPortal

Radix `ContextMenu.Portal`. `ContextMenuContent` already portals itself, so you rarely need it.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| container | HTMLElement \| null | document.body | Where to portal the content. |

## 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`, and the menu fades and scales in from the cursor point.

### 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 change the menu's density?

Rows are `compact` (32px) by default. For 36px rows, set `density="comfortable"` on ContextMenuContent and every row inside follows, sub-menus included. Without it, rows follow the nearest DensityProvider. A row's own `density` still wins, for a one-off. Icons, labels, shortcuts and the check sit 16px from the edge at either size, and the corners stay concentric.

---

<!-- 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Installation

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

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

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

Pro: `cookie-consent` comes with a [Koala UI Pro license](https://www.koalaui.com/pro). Its source is not published in these docs.

## Usage

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Anatomy

```tsx
import {
  CookieConsent,
  CookieBanner,
  CookieBannerIcon,
  CookieBannerContent,
  CookieBannerTitle,
  CookieBannerDescription,
  CookieBannerDetails,
  CookieDetailList,
  CookieBannerActions,
  CookieBannerDetailsTrigger,
  CookieCustomizeButton,
  CookieRejectAllButton,
  CookieAcceptAllButton,
  CookiePreferences,
  CookiePreferencesTrigger,
  CookiePreferencesContent,
  CookiePreferencesHeader,
  CookiePreferencesTitle,
  CookiePreferencesDescription,
  CookieCategoryList,
  CookiePreferencesFooter,
  CookieSavePreferencesButton,
} from "@/components/ui/cookie-consent"

<CookieConsent>
  <CookieBanner>
    <CookieBannerIcon />
    <CookieBannerContent>
      <CookieBannerTitle />
      <CookieBannerDescription />
    </CookieBannerContent>
    <CookieBannerDetails>
      <CookieDetailList />
    </CookieBannerDetails>
    <CookieBannerActions>
      <CookieBannerDetailsTrigger />
      <CookieCustomizeButton />
      <CookieRejectAllButton />
      <CookieAcceptAllButton />
    </CookieBannerActions>
  </CookieBanner>
  <CookiePreferences>
    <CookiePreferencesTrigger />
    <CookiePreferencesContent>
      <CookiePreferencesHeader>
        <CookiePreferencesTitle />
        <CookiePreferencesDescription />
      </CookiePreferencesHeader>
      <CookieCategoryList />
      <CookiePreferencesFooter>
        <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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## API reference

### CookieConsent

The root and single source of truth: owns the category booleans, the dialog's open state and the three actions; renders no DOM. Every part that renders an element accepts `className`, merged last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| categories* | CookieCategoryDef[] | - | The categories to manage, in display order: `{ id, label, description?, required?, icon?, cookies? }`. |
| value | Record<string, boolean> | - | Controlled preferences map, `{ [id]: boolean }`. Required categories are always clamped on. |
| defaultValue | Record<string, boolean> | - | Initial preferences when uncontrolled; a stored answer wins over it. Anything unset is off. |
| onValueChange | (value: Record<string, boolean>) => void | - | Called whenever a toggle or action changes the map. |
| onAcceptAll | (value: Record<string, boolean>) => void | - | Called when the visitor accepts every category. |
| onRejectAll | (value: Record<string, boolean>) => void | - | Called when the visitor rejects all but the required categories. |
| onSave | (value: Record<string, boolean>) => void | - | Called when the visitor saves the current selection. |
| open | boolean | - | Controlled open state of the preferences dialog. |
| defaultOpen | boolean | false | Initial dialog open state when uncontrolled. |
| onOpenChange | (open: boolean) => void | - | Called when the dialog opens or closes. |
| defaultConsented | boolean | false | Start with the banner hidden, for a visitor whose answer you stored yourself. |
| storageKey | string | - | Remember the answer in localStorage under this key, dated and versioned, and keep every tab in step. Omit to persist it yourself. |
| version | number \| string | 1 | Your cookie policy's version; an answer stored under another one no longer counts, so the banner asks again. |
| maxAgeDays | number | 180 | Days a stored answer stays valid before the banner asks again. Needs `storageKey`. |
| density | "comfortable" \| "compact" | "compact" | Banner padding (20 or 16px) and category rows; the dialog follows it too. Falls back to the nearest `DensityProvider`. |

### useCookieConsent

Reads the root's state from a custom surface: `prefs`, `categories`, `setPreference(id, value)`, `acceptAll()`, `rejectAll()`, `save()`, `dialogOpen`, `setDialogOpen(open)` and `bannerVisible`. Call it inside `CookieConsent`.

### CookieBanner

The non-blocking consent card, a fixed `<div role="region">` that animates in, and out once a choice is made; forwards all native `<div>` props. Declares `--surface`, so nested controls blend with it.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| position | "bottom" \| "bottom-left" \| "bottom-right" | "bottom-right" | `bottom` is a full-bleed bar that rows out from `lg`; the corners are floating cards. |
| layout | "stack" \| "inline" \| "launcher" | "stack" | A column, one slim row, or (corners only, needs `CookieBannerIcon`) the icon alone in a circle that grows into the inline card on hover, focus or tap. |

| Data attribute | Description |
| --- | --- |
| data-state | `"open"` while visible, `"closed"` during the exit animation. |
| data-expanded | Present while the details layer (or a launcher) is open. |

| CSS variable | Description |
| --- | --- |
| --surface | Set to `var(--popover)`, read by nested controls. |

### CookieBannerIcon

An optional leading glyph: pass a Koala icon, sized to 20px. Forwards all native `<div>` props.

### CookieBannerContent

The title and description column. Forwards all native `<div>` props.

### CookieBannerTitle

The banner's heading. Forwards all native `<p>` props.

### CookieBannerDescription

Muted supporting copy, usually with a link to your policy. Forwards all native `<p>` props.

### CookieBannerDetails

A layer folded away at rest that unrolls upward from the top of the banner on hover, keyboard focus or `CookieBannerDetailsTrigger`; Escape folds it. Forwards all native `<div>` props.

| Data attribute | Description |
| --- | --- |
| data-state | `"open"` or `"closed"`. |

### CookieBannerDetailsTrigger

Opens and closes the details layer on touch screens, hidden where a pointer can hover. Without children it is an icon-only caret that turns as the layer opens; forwards every `Button` prop.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| variant | ButtonProps["variant"] | "ghost" | Any Button variant. |

### CookieBannerActions

The action cluster; stacked corner cards stretch its buttons into an even row. Forwards all native `<div>` props.

### CookieDetailList

Every category with the cookies it sets (name, duration, purpose, provider), read from the root's `categories`; a category without `cookies` shows its description. Forwards all native `<div>` props.

| CSS variable | Description |
| --- | --- |
| --cookie-row | Each line's place in the stagger inside `CookieBannerDetails`, set per line. |

### CookiePreferences

The preferences dialog root, a Koala `Dialog` bound to the root's open state; renders no DOM. Forwards all `Dialog` props.

### CookiePreferencesTrigger

Opens the dialog from your own element, Koala's `DialogTrigger`. Renders a `<button>` and forwards all its props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| asChild | boolean | false | Merge onto your own element, such as a footer link. |

### CookiePreferencesContent

The dialog panel, Koala's `DialogContent` with the root's density; forwards all its props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| size | "sm" \| "md" \| "lg" \| "xl" | "md" | Dialog width; `md` is 480px. |

### CookiePreferencesHeader

Koala's `DialogHeader`, re-exported so the dialog reads from one import.

### CookiePreferencesTitle

Koala's `DialogTitle`, which names the dialog for assistive tech.

### CookiePreferencesDescription

Koala's `DialogDescription`.

### CookiePreferencesFooter

Koala's `DialogFooter`, the row for the save and reject buttons.

### CookieCategoryList

Maps the root's `categories` into `CookieCategory` rows inside one bordered container with dividers, a `role="group"`. Takes `className` only.

### CookieCategory

One row: icon, a `<label>` for the Switch, description and the Switch. A required category shows an Always on badge and a disabled, checked Switch.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| category* | CookieCategoryDef | - | The category to render; its `id` keys into the preferences map. |

### CookieAcceptAllButton

A Koala `Button` with accept-all bound; forwards every `Button` prop, and your `onClick` runs after the action.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| variant | ButtonProps["variant"] | "primary" | Any Button variant. |
| children | React.ReactNode | "Accept all" | The label. |

### CookieRejectAllButton

A Koala `Button` with reject-all bound; forwards every `Button` prop, and your `onClick` runs after the action.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| variant | ButtonProps["variant"] | "secondary" | Any Button variant. |
| children | React.ReactNode | "Reject all" | The label. |

### CookieCustomizeButton

A Koala `Button` with opening the preferences dialog bound; forwards every `Button` prop, and your `onClick` runs after the action.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| variant | ButtonProps["variant"] | "ghost" | Any Button variant. |
| children | React.ReactNode | "Customize" | The label. |

### CookieSavePreferencesButton

A Koala `Button` with saving the current selection bound; forwards every `Button` prop, and your `onClick` runs after the action.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| variant | ButtonProps["variant"] | "primary" | Any Button variant. |
| children | React.ReactNode | "Save preferences" | The label. |

## 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. Without a `density` prop on CookieConsent it follows the nearest DensityProvider, and is `compact` when there is none. Pass `density="comfortable"` for roomier banner padding and category rows; radius and color never change, and 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 is a solid ink fill; the in-range days take a soft grey.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Installation

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

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

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

Pro: `date-picker` comes with a [Koala UI Pro license](https://www.koalaui.com/pro). Its source is not published in these docs.

## Usage

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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`.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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, …).

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Range with presets

The combination most analytics surfaces want: a two-month range picker with the full preset rail.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Sizes

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Constraints

Bound the range with `min` / `max`, or disable arbitrary days with `isDateDisabled`. Disabled days are inert and struck through.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Density

Like the rest of Koala, the calendar honors `density`: `compact` (the default, or whatever the nearest `DensityProvider` sets) keeps 32px cells and a 32px trigger for dense application UI; `comfortable` opens them to 36px.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## API reference

### Calendar

The standalone month grid the pickers wrap, a `<div>` with a roving-tabindex `role="grid"`. Takes `className` on its root, merged last, as every export here does.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| mode | "single" \| "range" | "single" | Pick one `Date`, or a `DateRange` of `{ from, to }`. |
| selected | Date \| DateRange | - | Controlled selection: a `Date` in single mode, a `DateRange` in range mode. |
| defaultSelected | Date \| DateRange | - | Initial selection when uncontrolled. |
| onSelect | (value: Date \| DateRange \| undefined) => void | - | Called with the new selection; a range is `{ from }` until its second click. |
| month | Date | - | Controlled displayed month. |
| defaultMonth | Date | - | Initial month when uncontrolled; otherwise the selection's month, or today's. |
| onMonthChange | (month: Date) => void | - | Called when the displayed month changes. |
| min | Date | - | Earliest selectable day, inclusive. |
| max | Date | - | Latest selectable day, inclusive. |
| isDateDisabled | (date: Date) => boolean | - | Disable arbitrary days, such as weekends. Disabled days are inert and struck through. |
| weekStartsOn | 0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6 | 1 | First column of the week, `0` for Sunday; Monday by default. |
| locale | string | - | BCP-47 locale for month and weekday labels. Defaults to the visitor's; server and hydrating renders use `en-US`, then the visitor's takes over. |
| numberOfMonths | number | 1 | Month grids shown side by side. The caption switches to month and year views only with one. |
| density | "comfortable" \| "compact" | "compact" | Cell size: 36 or 32px. Falls back to the nearest `DensityProvider`. |

| Data attribute | Description |
| --- | --- |
| data-selected | On a day button: the selected day or a range endpoint. On a month or year cell: the displayed one. |
| data-today | On today's day button; set after hydration, never on the server. |
| data-outside | On a day from the neighbouring month. |
| data-disabled | On a day outside `min`/`max` or matched by `isDateDisabled`. |
| data-current | On the month or year cell that holds today. |

### DatePicker

A trigger that opens a `Calendar` in a Radix Popover, for one date; it closes on pick. Reads `Field` context for its id, description, disabled and error state.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| value | Date | - | Controlled date. |
| defaultValue | Date | - | Initial date when uncontrolled. |
| onChange | (date: Date \| undefined) => void | - | Called on pick, preset or clear. |
| placeholder | string | "Pick a date" | Trigger label while no date is set. |
| size | "sm" \| "md" \| "lg" | "sm" | Trigger height: 32, 36 or 40px. Unset, it follows density (`sm` compact, `md` comfortable), or the size a `Form` imposes. |
| block | boolean | false | Stretch the trigger to its container's width. |
| clearable | boolean | false | Show a clear button in the trigger once a value is set. |
| presets | boolean \| DatePreset[] | - | A quick-pick rail: `true` for the built-in set, or your own `{ label, value }` items. |
| format | (date: Date) => string | - | Format each date in the trigger label. Defaults to the locale's medium date. |
| min | Date | - | Earliest selectable day, inclusive. |
| max | Date | - | Latest selectable day, inclusive. |
| isDateDisabled | (date: Date) => boolean | - | Disable arbitrary days, such as weekends. Disabled days are inert and struck through. |
| weekStartsOn | 0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6 | 1 | First column of the week, `0` for Sunday; Monday by default. |
| locale | string | - | BCP-47 locale for month and weekday labels. Defaults to the visitor's; server and hydrating renders use `en-US`, then the visitor's takes over. |
| numberOfMonths | number | 1 | Month grids shown side by side. |
| density | "comfortable" \| "compact" | "compact" | Calendar cell size (36 or 32px) and the trigger's default size. Falls back to the nearest `DensityProvider`. |
| align | "start" \| "center" \| "end" | "start" | Popover alignment against the trigger; it opens 8px below. |
| disabled | boolean | - | Disable the trigger. Inside a `Field`, read from the field. |
| hasError | boolean | - | Mark the trigger invalid (`aria-invalid`, destructive border). Inside a `Field`, read from the field. |
| id | string | - | The trigger's id. Inside a `Field`, read from the field so its label points here. |
| triggerClassName | string | - | Extra classes for the trigger; `className` lands on the trigger too. |

| Data attribute | Description |
| --- | --- |
| data-state | On the trigger: `"open"` or `"closed"`. |
| data-placeholder | On the trigger while no value is set. |
| data-active | On the preset that matches the current value. |

| CSS variable | Description |
| --- | --- |
| --surface | Read by the trigger as its fill (falls back to `--background`); the popover sets it to `var(--popover)`. |

### DateRangePicker

The same picker for a `DateRange`; it closes once both ends are set or a preset is chosen. Reads `Field` context like `DatePicker`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| value | DateRange | - | Controlled range, `{ from, to }`. |
| defaultValue | DateRange | - | Initial range when uncontrolled. |
| onChange | (range: DateRange \| undefined) => void | - | Called on each click, preset or clear. |
| placeholder | string | "Pick a date range" | Trigger label while no start is set. |
| size | "sm" \| "md" \| "lg" | "sm" | Trigger height: 32, 36 or 40px. Unset, it follows density (`sm` compact, `md` comfortable), or the size a `Form` imposes. |
| block | boolean | false | Stretch the trigger to its container's width. |
| clearable | boolean | false | Show a clear button in the trigger once a value is set. |
| presets | boolean \| DateRangePreset[] | - | A quick-pick rail: `true` for the built-in set, or your own `{ label, value }` items. |
| format | (date: Date) => string | - | Format each date in the trigger label. Defaults to the locale's medium date. |
| min | Date | - | Earliest selectable day, inclusive. |
| max | Date | - | Latest selectable day, inclusive. |
| isDateDisabled | (date: Date) => boolean | - | Disable arbitrary days, such as weekends. Disabled days are inert and struck through. |
| weekStartsOn | 0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6 | 1 | First column of the week, `0` for Sunday; Monday by default. |
| locale | string | - | BCP-47 locale for month and weekday labels. Defaults to the visitor's; server and hydrating renders use `en-US`, then the visitor's takes over. |
| numberOfMonths | number | 2 | Month grids shown side by side. |
| density | "comfortable" \| "compact" | "compact" | Calendar cell size (36 or 32px) and the trigger's default size. Falls back to the nearest `DensityProvider`. |
| align | "start" \| "center" \| "end" | "start" | Popover alignment against the trigger; it opens 8px below. |
| disabled | boolean | - | Disable the trigger. Inside a `Field`, read from the field. |
| hasError | boolean | - | Mark the trigger invalid (`aria-invalid`, destructive border). Inside a `Field`, read from the field. |
| id | string | - | The trigger's id. Inside a `Field`, read from the field so its label points here. |
| triggerClassName | string | - | Extra classes for the trigger; `className` lands on the trigger too. |

| Data attribute | Description |
| --- | --- |
| data-state | On the trigger: `"open"` or `"closed"`. |
| data-placeholder | On the trigger while no value is set. |
| data-active | On the preset that matches the current value. |

| CSS variable | Description |
| --- | --- |
| --surface | Read by the trigger as its fill (falls back to `--background`); the popover sets it to `var(--popover)`. |

### getDatePresets

Returns the built-in single-date set: Today, Yesterday, Tomorrow, In a week, In two weeks, In a month.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| now | Date | new Date() | The day the presets are relative to. |

### getDateRangePresets

Returns the built-in eleven ranges, from Today and Last 7 days to This month and Last year.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| now | Date | new Date() | The day the presets are relative to. |
| weekStartsOn | 0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6 | 1 | Where This week and Last week begin. |

## 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>
        Visible to everyone in your workspace.
      </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 "koala-icons"
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>
            Visible to everyone in your workspace.
          </DialogDescription>
        </DialogHeader>
        <DialogFooter>
          <DialogClose asChild>
            <Button variant="ghost">Cancel</Button>
          </DialogClose>
          <Button>Save changes</Button>
        </DialogFooter>
      </DialogContent>
    </Dialog>
  )
}
```

## Anatomy

```tsx
import {
  Dialog, DialogTrigger, DialogContent, DialogIcon, DialogHeader, DialogTitle,
  DialogDescription, DialogStepper, DialogBody, DialogFooter, DialogClose,
} from "@/components/ui/dialog"

<Dialog>
  <DialogTrigger />
  <DialogContent>
    <DialogIcon />
    <DialogHeader>
      <DialogTitle />
      <DialogDescription />
    </DialogHeader>
    <DialogStepper />
    <DialogBody />
    <DialogFooter>
      <DialogClose />
    </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>
        All your data goes with it. This can't 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>
            They'll get an invite by email.
          </DialogDescription>
        </DialogHeader>
        <form className="contents" onSubmit={(e) => { e.preventDefault(); handleSubmit() }}>
          <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 type="button" variant="ghost">Cancel</Button>
            </DialogClose>
            <Button type="submit">Send invite</Button>
          </DialogFooter>
        </form>
      </DialogContent>
    </Dialog>
  )
}
```

## Compact density

Dialogs are `compact` unless a `DensityProvider` or `density="comfortable"` opens them up (20px padding instead of 16px, wider gaps, a larger icon). The content re-provides its density 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 for dense app 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>Updated October 2026.</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. The component tracks the open dialogs itself, 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>Anyone with the link can view it.</DialogDescription>
  </DialogHeader>
  <FormSection>
    <Field required>
      <FieldLabel>Link</FieldLabel>
      <InputRoot>
        <InputField readOnly value="lspcad.flab/incident21414" />
        <InputSuffixButton aria-label="Copy link"><Copy /></InputSuffixButton>
      </InputRoot>
    </Field>
    <Field required>
      <FieldLabel>Invite by email</FieldLabel>
      {/* Stack on mobile so the button never overflows a narrow dialog; row from sm */}
      <form className="flex flex-col gap-2 sm:flex-row sm:items-center" onSubmit={(e) => e.preventDefault()}>
        <InputRoot className="min-w-0 sm:flex-1">
          <InputPrefix><EnvelopeSimple /></InputPrefix>
          <InputField type="email" placeholder="name@company.com" />
        </InputRoot>
        <Button className="w-full sm:w-auto">Send invite</Button>
      </form>
    </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>Send feedback</DialogTitle>
    <DialogDescription>We read every message.</DialogDescription>
  </DialogHeader>

  <div className="grid gap-4">
    <FieldGroup required>
      <FieldGroupLabel>Rating</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">Message</TextareaLabel>
      <TextareaRoot>
        <TextareaField id="feedback-message" placeholder="What could be better?" 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="ghost">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>Set up two-factor authentication</DialogTitle>
    <DialogDescription>
      Scan it with your authenticator app.
    </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="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="ghost">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", hint: "Bright and clear.", icon: Sun },
  { value: "dark", title: "Dark", hint: "Easy on the eyes at night.", icon: Moon },
  { value: "system", title: "System", hint: "Follows your device.", icon: Desktop },
]

<DialogContent size="sm">
  <DialogIcon><Palette /></DialogIcon>
  <DialogHeader>
    <DialogTitle>Appearance</DialogTitle>
    <DialogDescription>Applies to this device only.</DialogDescription>
  </DialogHeader>

  <FieldGroup required>
    <FieldGroupLabel>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="ghost">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>Koala is on mobile</DialogTitle>
    <DialogDescription>Your dashboard, wherever you are.</DialogDescription>
  </DialogHeader>

  {/* hero media */}
  <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="ghost">Not now</Button>
      <Button>Get the app</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>

  {/* A real form, so Enter in a field presses Next and the buttons take the field corner */}
  <form className="contents" onSubmit={(e) => e.preventDefault()}>
    <div className="grid grid-cols-[auto_1fr] items-start gap-4 sm:gap-8">
      {/* Left rail: vertical stepper with solid, ink-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 type="button" variant="ghost" disabled={step === 1} onClick={() => setStep((s) => s - 1)}>
        Back
      </Button>
      {step === STEPS.length
        ? <Button type="submit" onClick={create} loading={submitting}>Create project</Button>
        : <Button type="submit" onClick={() => setStep((s) => s + 1)}>Next</Button>}
    </DialogFooter>
  </form>
</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: "Keep team talk apart from client threads." },
  { icon: FolderLock, title: "Restricted projects", description: "Visible only to the people you invite." },
  { icon: UsersThree, title: "Up to 15 members", description: "Bring the whole team in." },
  { icon: Cloud, title: "3 TB storage", description: "Room for every file and asset." },
]

<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, 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 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 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">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 className="contents" onSubmit={(e) => { e.preventDefault(); save() }}>
      {/* form fields */}
      <DialogFooter>
        <Button type="button" variant="ghost" onClick={attemptClose}>Cancel</Button>
        <Button type="submit">Publish</Button>
      </DialogFooter>
    </form>
  </DialogContent>
</Dialog>

{/* Discard confirmation */}
<Dialog open={discardOpen} onOpenChange={setDiscardOpen}>
  <DialogContent size="sm" showClose={false}>
    <DialogHeader>
      <DialogTitle>Discard changes?</DialogTitle>
      <DialogDescription>
        Your edits will be lost.
      </DialogDescription>
    </DialogHeader>
    <DialogFooter>
      <Button variant="ghost" onClick={() => setDiscardOpen(false)}>Keep editing</Button>
      <Button variant="destructive" onClick={confirmDiscard}>Discard changes</Button>
    </DialogFooter>
  </DialogContent>
</Dialog>
```

## Accessibility

Radix traps focus inside the dialog, closes it on Escape and hides the page from screen readers while it is open. On close, focus goes back to the `DialogTrigger`. A dialog opened by state has no trigger (a keyboard shortcut, a row action, a command), so DialogContent remembers the element that had focus when it opened and returns focus there instead, as long as that element is still on the page. Without this, focus would fall back to the top of the document. Drawer, CommandDialog, Lightbox and FilePreviewDialog do the same.

A dialog opened from a menu item goes back to the button that opened the menu, since the item closes with the menu. From a submenu, that is the button of the top menu. A ContextMenu has no button, so focus goes back to whatever had it before the menu opened.

To send focus somewhere else, pass `onCloseAutoFocus`, call `event.preventDefault()` and focus your own element. The dialog then leaves focus alone.

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

<InputRoot>
  <InputField
    placeholder="Write a message…"
    onKeyDown={(event) => {
      if (event.key === "Enter" && (event.metaKey || event.ctrlKey)) {
        event.preventDefault()
        setOpen(true)
      }
    }}
  />
</InputRoot>

{/* No DialogTrigger: on close, focus returns to the field */}
<Dialog open={open} onOpenChange={setOpen}>
  <DialogContent size="sm">
    <DialogHeader>
      <DialogTitle>Schedule message</DialogTitle>
      <DialogDescription>
        Pick when it goes out.
      </DialogDescription>
    </DialogHeader>
    <DialogFooter>
      <DialogClose asChild><Button variant="ghost">Cancel</Button></DialogClose>
      <DialogClose asChild><Button>Schedule</Button></DialogClose>
    </DialogFooter>
  </DialogContent>
</Dialog>
```

## API reference

### Dialog

The root, Radix `Dialog.Root`; renders no DOM. Every part that renders an element accepts `className`, merged last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| open | boolean | - | Controlled open state. |
| defaultOpen | boolean | false | Initial open state when uncontrolled. |
| onOpenChange | (open: boolean) => void | - | Called when the dialog opens or closes, by the trigger, a close, Escape or the scrim. |
| modal | boolean | true | Trap focus, lock scroll and hide the rest of the page from screen readers while open. |

### DialogTrigger

Opens the dialog, Radix `Dialog.Trigger`. Renders a `<button>` and forwards all its props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| asChild | boolean | false | Merge onto your own element (a `Button`) instead of rendering a `<button>`. |

| Data attribute | Description |
| --- | --- |
| data-state | `"open"` or `"closed"`. |

### DialogContent

The modal, Radix `Dialog.Content` portalled to the body with its own scrim and a centering wrapper; forwards all its props. Re-provides its density to every part inside.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| size | "sm" \| "md" \| "lg" \| "xl" \| "media" | "md" | Max width: 384px, 30rem, 672px, 896px, or a 16:9 video frame with no padding. A ceiling, not a fixed width. |
| density | "comfortable" \| "compact" | "compact" | Padding and gaps: 20px or 16px. Falls back to the nearest `DensityProvider`. |
| mobile | "sheet" \| "center" | "sheet" | Below `sm`, dock to the bottom edge as a sheet, or keep floating mid-screen. |
| showClose | boolean | true | Render the built-in top-right close button. |
| closeLabel | string | "Close" | Accessible label of the built-in close button. |
| onOpenAutoFocus | (event: Event) => void | - | Called as focus moves in on open; `preventDefault()` and focus your first field instead. |
| onCloseAutoFocus | (event: Event) => void | - | Called as focus returns to the trigger on close; `preventDefault()` to send it elsewhere. |
| onEscapeKeyDown | (event: KeyboardEvent) => void | - | Called on Escape; `preventDefault()` keeps the dialog open. |
| onInteractOutside | (event: Event) => void | - | Called on a pointer down or focus outside the content; `preventDefault()` keeps the dialog open. |
| forceMount | true | - | Keep the content mounted while closed, for an animation library to control. |

| Data attribute | Description |
| --- | --- |
| data-state | `"open"` or `"closed"`, on the content and on the scrim. |
| data-stacked | On the scrim, while another dialog is open beneath it: the lighter second wash. |

| CSS variable | Description |
| --- | --- |
| --surface | Set to `var(--popover)`, read by nested Inputs and Selects. |
| --dialog-nested | Set on the wrapper to `1` or `2` while dialogs are open on top, which scales this one back and nudges it up. |

### DialogIcon

An optional muted leading icon above the title, sized by density (24px or 20px). Forwards all native `<div>` props.

### DialogHeader

A left-aligned column holding the title and description. Forwards all native `<div>` props.

### DialogTitle

The heading the dialog is announced by, Radix `Dialog.Title` (an `<h2>`). Required for accessibility; hide it with `sr-only` when the design has none.

### DialogDescription

Muted supporting copy, Radix `Dialog.Description` (a `<p>`), announced after the title.

### DialogStepper

A full-bleed `Stepper` for wizard dialogs, placed right after the header; it inherits the dialog's density and takes every `Stepper` prop (`value`, `defaultValue`, `onValueChange`, `variant`).

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| bordered | boolean | true | Full-bleed divider beneath the stepper. |
| orientation | "horizontal" \| "vertical" | "horizontal" | Layout of the steps. |
| density | "comfortable" \| "compact" | "compact" | Falls back to the dialog's density. |

### DialogBody

The scrolling middle of a long dialog: with it present the content caps to the viewport and only this scrolls, edges fading. Give it `tabIndex={0}` when it holds only text. Forwards all native `<div>` props.

### DialogFooter

The action row: stacked and reversed on mobile, right-aligned from `sm`. Forwards all native `<div>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| bordered | boolean | true | Full-bleed top divider with a 12px band flush to the dialog's bottom edge; `false` lets the footer sit below the body. |

### DialogClose

Closes the dialog, Radix `Dialog.Close`. Renders a `<button>` and forwards all its props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| asChild | boolean | false | Merge onto your own element (a footer `Button`) instead of rendering a `<button>`. |

## 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; for long bodies put the middle in a DialogBody, which caps the dialog to the viewport and scrolls on its own.

### 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.

### Where does focus go when a dialog without a DialogTrigger closes?

Back to the element that had focus when the dialog opened, such as the field you were typing in when a shortcut opened it, as long as that element is still on the page. When there is a DialogTrigger, focus goes to the trigger as before. To choose the target yourself, pass onCloseAutoFocus to DialogContent, call e.preventDefault() and focus your own element.

### Where does focus go when a menu item opened the dialog?

To the button that opened the menu, because the item closes with the menu and cannot take focus back. From an item in a submenu, focus goes to the button of the top menu. A ContextMenu has no button, so focus goes back to whatever had it before the menu opened, or nowhere if nothing did.

### 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>
```

## API reference

### Divider

A plain rule is Radix `Separator.Root`; with a label it is a `<div role="separator">` wrapping two `aria-hidden` lines and the label. Forwards all native `<div>` props and accepts `className`, merged last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| variant | "solid" \| "dashed" \| "dotted" \| "gradient" | "solid" | Stroke style. `gradient` drops the border and paints a hairline that fades out at both ends. |
| orientation | "horizontal" \| "vertical" | "horizontal" | A vertical divider stretches to its container's height and ignores children. |
| children | React.ReactNode | - | A label (text or icon) set between two lines. Horizontal only. |
| labelPosition | "start" \| "center" \| "end" | "center" | Where the label sits; `start` and `end` drop the line on that side. Ignored without children. |
| decorative | boolean | false | Purely visual: the rule takes `role="none"` and leaves the accessibility tree. |
| static | boolean | false | Opt out of the smart auto-collapse, so the rule paints even at the edge of its group or next to another divider. |

| Data attribute | Description |
| --- | --- |
| data-orientation | `"horizontal"` or `"vertical"`, set by Radix on the plain (unlabeled) rule. |
| data-smart | Present unless `static`; opts the divider into the collapse rules in `globals.css`. |

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Installation

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

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

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

Pro: `dock` comes with a [Koala UI Pro license](https://www.koalaui.com/pro). Its source is not published in these docs.

## Usage

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

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.

## Anatomy

```tsx
import {
  Dock,
  DockItem,
  DockGroup,
  DockLabel,
  DockSeparator,
  DockExpander,
} from "@/components/ui/dock"

<Dock>
  <DockItem />
  <DockSeparator />
  <DockGroup>
    <DockLabel />
    <DockItem />
  </DockGroup>
  <DockExpander />
</Dock>
```

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## API reference

### Dock

The morphing box and roving-focus root, Radix `Toolbar.Root` (a `<div role="toolbar">`); forwards all its props except `orientation`, which follows the shape. Every part accepts `className`, merged last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| aria-label | string | "Dock" | Accessible name of the toolbar. |
| variant | "floating" \| "solid" | "floating" | The page's popover surface, or an inverted slab for a dock over a photo, canvas or video. |
| size | "sm" \| "md" \| "lg" | "md" | The rail only: 24px, 32px or 40px icon buttons. The panel ignores it. |
| density | "comfortable" \| "compact" | "compact" | The panel only: 36px or 32px rows, like DropdownMenu. Falls back to the nearest `DensityProvider`. |
| expanded | boolean | - | Controlled shape: `true` is the panel, `false` the rail. |
| defaultExpanded | boolean | false | Shape on mount when uncontrolled. |
| onExpandedChange | (expanded: boolean) => void | - | Called when the dock expands or collapses. |
| trigger | "click" \| "hover" | "click" | What opens the panel: a press on `DockExpander`, or the pointer landing on it (then it collapses shortly after the pointer leaves). |
| closeOnSelect | boolean | true | Collapse back to the rail after a `DockItem` is chosen. |
| tooltipPlacement | "top" \| "bottom" \| "left" \| "right" | "top" | Where the rail icons' tooltips open; also takes Tippy's `-start`, `-end` and `auto` placements. |
| static | boolean | false | Kept for compatibility; controls no longer scale on press. |
| loop | boolean | true | Arrow keys wrap from the last control to the first. |
| dir | "ltr" \| "rtl" | - | Reading direction for arrow-key movement. |

| Data attribute | Description |
| --- | --- |
| data-expanded | Present while the dock is in its panel shape. |
| data-ready | Present once the box has measured itself; the morph transition is armed only then. |
| data-orientation | `"horizontal"` in the rail, `"vertical"` in the panel. |

| CSS variable | Description |
| --- | --- |
| --surface | Set to `var(--popover)` (floating) or `var(--foreground)` (solid), read by nested controls. |

### DockItem

A destination or action, Radix `Toolbar.Button`: an icon with the label as its tooltip in the rail, a labelled row in the panel. Forwards no other native props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| label* | string | - | The tooltip and `aria-label` in the rail, the row text in the panel. |
| icon | React.ReactNode | - | The glyph; sized by `size` in the rail and to 20px in the panel unless it carries a `size-*` class. |
| shortcut | string | - | Display-only key chip at the end of the row; rides in the tooltip while collapsed. |
| active | boolean | false | Marks the current destination and sets `aria-current="page"`. |
| disabled | boolean | false | Dims the control and removes it from the roving focus. |
| onSelect | (event: React.MouseEvent<HTMLElement>) => void | - | Called on press, before `closeOnSelect` collapses the dock. |
| asChild | boolean | false | Render into your single child (a `Link`, an `<a>`); the dock still fills it with the icon and label. |

| Data attribute | Description |
| --- | --- |
| data-active | Present on the current destination. |
| data-orientation | The dock's current arrow-key axis. |

### DockGroup

A drill-down layer: an icon in the rail, a row with a caret in the panel. Opening it swaps the panel for a Back row plus its children; nest groups to go deeper.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| label* | string | - | Tooltip in the rail, row text in the panel. |
| icon | React.ReactNode | - | The glyph. |
| value | string | - | Identity in the open path; defaults to `label`. |
| backLabel | string | "Back" | Label of the row that returns to the parent layer. |
| disabled | boolean | false | Dims the control and removes it from the roving focus. |
| children | React.ReactNode | - | The rows of this group's layer. |

### DockLabel

A muted caption over a run of rows, rendered only in the panel. Forwards all native `<div>` props.

### DockSeparator

An axis-aware hairline, Radix `Toolbar.Separator`: a vertical tick in the rail, a horizontal rule in the panel. Forwards all its props.

| Data attribute | Description |
| --- | --- |
| data-orientation | The separator's own axis, opposite the dock's. |

### DockExpander

The rail's last control, which turns the rail into the panel; it unmounts once expanded.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| label | string | "Menu" | Accessible name and tooltip. |
| children | React.ReactNode | - | Replaces the default list glyph. |

## 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 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/dot-matrix.md -->

# Dot Matrix

A dot-matrix loader. A light runs a 5×5 grid of dots in a spiral, from the edge into the center, trailing a fading tail, then around again. For a boot screen or a panel's first load, where a spinner would be too small to carry the wait.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Installation

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

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

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

Pro: `dot-matrix` comes with a [Koala UI Pro license](https://www.koalaui.com/pro). Its source is not published in these docs.

## Usage

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Anatomy

```tsx
import { DotMatrix } from "@/components/ui/dot-matrix"

<DotMatrix />
```

## Sizes

`xl` (the default) is 64px, for a whole screen: a boot, a first load. `lg` is 36px, for a panel or a block inside a page. Both draw a 5px dot; the size sets the spacing.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Color

The dots paint `currentColor`, so the matrix takes the text color around it, or any `text-*` you give it. The tail is opacity on that one color, so it reads on every ground in every theme.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## In a panel

The matrix is a `status` named "Loading". When words beside it already say what is loading, make those words the status and pass `aria-hidden` to the matrix: its role and name are dropped, so the wait is announced once.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Speed

A lap takes 1.1s. `--dot-matrix-duration` retimes it, on the matrix or on any container above it: slower for a calm, long wait, never so fast that the tail stops reading as a trail.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Reduced motion

With `prefers-reduced-motion`, the light stops and the spiral stays drawn: each dot holds a still opacity that brightens along the path, faint at the edge and full at the center. It still reads as a loader, without moving. This is that state:

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## API reference

### DotMatrix

A `<div>` with `role="status"`, holding 25 dots. Every div prop but `children` is forwarded; `className` is merged last and color comes from `currentColor`. The motion is the `animate-dot-matrix` token.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| size | "lg" \| "xl" | "xl" | `lg` (36px) sits in a panel or a block; `xl` (64px) holds a whole screen. |
| label | string | "Loading" | The accessible name while it is announced. Ignored under `aria-hidden`. |
| aria-hidden | boolean | - | Drops the role and the name, for a host that already says it is busy. |

| Data attribute | Description |
| --- | --- |
| data-slot | `"dot-matrix"` on the root, `"dot-matrix-dot"` on each dot. |

| CSS variable | Description |
| --- | --- |
| --dot-matrix-duration | Retimes the `animate-dot-matrix` loop (default `1.1s`). |
| --dot-phase | Set on each dot: its place on the spiral, as the delay into the loop. |
| --dot-rest | Set on each dot: its still opacity under reduced motion, brighter along the spiral. |

## FAQ

### Dot Matrix or Spinner?

Spinner is the inline glyph: in a button, an input, a badge, sized by its host. Dot Matrix is a centerpiece for a wait that owns the space: a boot screen, an empty panel's first load.

### Does it cost much to animate 25 dots?

Each dot animates opacity only, which the compositor handles without layout or paint, and all 25 share one set of keyframes.

### Why does it start mid-spiral?

Each dot is phased by its place on the path, so the first frame already shows the light running with its tail behind it, the same as every later frame. Nothing lights up dot by dot on mount.

### Can it show progress?

No. Like Spinner it says that something is happening, not how much is left. Use Progress for a known amount.

---

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

# Dot

A small status or colour mark: a light that says live, recording or away, or a swatch that says which department or which paint. Tones re-theme; a free colour comes straight from your data.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Installation

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

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

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

Pro: `dot` comes with a [Koala UI Pro license](https://www.koalaui.com/pro). Its source is not published in these docs.

## Usage

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Anatomy

```tsx
import { Dot } from "@/components/ui/dot"

<Dot />
```

## Tones

A `tone` takes its colour from a semantic role, so it re-themes across all four themes with the rest of the system. `neutral` is the default (the muted ink, for offline or idle), and `current` follows the text colour around it.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Free colour

When the colour comes from data (a department, a call category, a team), pass it as `color`: any CSS colour, hex, `rgb()`, `hsl()` or a `var()`. It overrides `tone`, and the halo of a `ping` follows it too.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Shapes

`round` is a status light. `square` is a swatch, a small rounded square for a colour that identifies something rather than describes its state: the department beside a callsign, the paint of a vehicle. Its corner is a quarter of its side at every size, so it never rounds into a circle.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Sizes

`xs` 6px for dense rows and inside chips, `sm` 8px (the default) beside body text, `md` 10px for a swatch or a light that has to be seen from across the screen.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Ring

A white or pale colour vanishes on a white card. `ring` lays a hairline over the edge (black at low alpha in the light themes, white in the dark ones), inside the box, so the dot keeps its size. Turn it on whenever the colour comes from data and could be light.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Pulse

`blink` is a recording light: one second on, one second off, the cadence a camera or a bodycam uses for “REC”. `ping` sends a halo out of the dot, the signal for live, on air or on duty. Both stand down under reduced motion: the blinking dot stays lit and the halo is not drawn, so the state still reads, it just holds still.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## In a roster

The two shapes side by side: a square for who the unit belongs to, a round light for what it is doing. The department colours are plain hex strings from the data, ringed because one of them is nearly white.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Accessibility

Without a `label` the dot is decorative (`aria-hidden`): the text beside it says the same thing, so it is announced once. With a label it becomes an image named by it (`role="img"`), for a mark that carries meaning nothing else on screen spells out, such as the department square beside a callsign. Never let colour be the only signal: pair a status light with its word, or give the dot a label.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## API reference

### Dot

A `<span>`, the mark itself. Every other `<span>` prop passes through (but `children` and `color`, which is the prop below); `className` is merged last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| tone | "neutral" \| "brand" \| "success" \| "warning" \| "info" \| "destructive" \| "purple" \| "pink" \| "teal" \| "orange" \| "current" | "neutral" | The colour, from a semantic role, so the dot re-themes. `current` follows the text colour around it. |
| color | string | - | Any CSS colour (`"#1d4ed8"`, `"rgb(220 38 38)"`, `"var(--x)"`). Overrides `tone`; for colours that come from data. |
| shape | "round" \| "square" | "round" | `round` is a status light; `square` a swatch, with a quarter-radius at every size. |
| size | "xs" \| "sm" \| "md" | "sm" | 6, 8 or 10px. A `size-*` utility in `className` overrides it. |
| ring | boolean | false | A hairline over the edge, so pale colours read on pale grounds. Never changes the size. |
| pulse | "none" \| "blink" \| "ping" | "none" | `blink` is 1s on, 1s off; `ping` sends out a halo. Both hold still under `prefers-reduced-motion`. Backed by the `--animate-blink` and `--animate-live-ping` tokens. |
| label | string | - | The accessible name. With it the dot is `role="img"`; without it, `aria-hidden`, so the text beside it carries the meaning. |

| Data attribute | Description |
| --- | --- |
| data-slot | `"dot"`. |
| data-tone | The tone (`"neutral"` when unset). Absent when a `color` is given. |
| data-pulse | `"blink"` or `"ping"`. Absent when the dot holds still. |

| CSS variable | Description |
| --- | --- |
| --dot-color | The one colour the fill and the halo both read. Written by `tone`, or inline by `color`. |

## FAQ

### Dot, or a Badge with dot?

A Badge with `dot` is a chip: the light plus a label, in one bordered pill. Reach for Dot on its own when the label is already there in your layout (a table cell, a list row, a callsign) and the chip's border and padding would be noise.

### How do I use a colour from my data?

Pass it to `color` as it comes: `<Dot color={unit.departmentHex} />`. Add `ring` if any of those colours can be white or pale, so the mark keeps its edge on a light card.

### Why does the blinking dot stop with reduced motion?

A flashing light is exactly the motion that setting asks you to remove. The dot stays lit, which still says recording, and the label beside it says it in words.

### Does it work in older embedded browsers?

Yes. The halo is a copy of the dot scaled with `transform` and faded with opacity, and the ring is an inset box-shadow, so neither needs `color-mix`, `:has()` or the standalone `scale` property.

---

<!-- 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>
  )
}
```

## Anatomy

```tsx
import {
  Drawer, DrawerTrigger, DrawerContent, DrawerHeader, DrawerTitle, DrawerDescription,
  DrawerBody, DrawerFooter, DrawerClose, DrawerNav, DrawerView, DrawerNavBack, DrawerNavTrigger,
} from "@/components/ui/drawer"

<Drawer>
  <DrawerTrigger />
  <DrawerContent>
    <DrawerHeader>
      <DrawerTitle />
      <DrawerDescription />
    </DrawerHeader>
    <DrawerBody />
    <DrawerFooter>
      <DrawerClose />
    </DrawerFooter>
  </DrawerContent>
</Drawer>

{/* With in-sheet navigation */}
<DrawerContent>
  <DrawerNav>
    <DrawerView>
      <DrawerHeader>
        <DrawerNavBack />
        <DrawerTitle />
      </DrawerHeader>
      <DrawerBody>
        <DrawerNavTrigger />
      </DrawerBody>
    </DrawerView>
  </DrawerNav>
</DrawerContent>
```

## 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>
  <form className="contents" onSubmit={(e) => e.preventDefault()}>
    <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 type="button" variant="ghost">Cancel</Button></DrawerClose>
      <DrawerClose asChild><Button type="submit">Save changes</Button></DrawerClose>
    </DrawerFooter>
  </form>
</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

Drawers are `compact` unless a `DensityProvider` or `density="comfortable"` opens them up: 24px padding and an 18px title instead of 16px and 16px. The content re-provides its density 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="comfortable">…</DrawerContent>
```

## API reference

### Drawer

The root, Radix `Dialog.Root`; renders no DOM. Every part that renders an element accepts `className`, merged last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| open | boolean | - | Controlled open state. |
| defaultOpen | boolean | false | Initial open state when uncontrolled. |
| onOpenChange | (open: boolean) => void | - | Called when the drawer opens or closes, including by a swipe. |
| modal | boolean | true | Trap focus, lock scroll and hide the rest of the page from screen readers while open. |

### DrawerTrigger

Opens the drawer, Radix `Dialog.Trigger`. Renders a `<button>` and forwards all its props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| asChild | boolean | false | Merge onto your own element (a `Button`) instead of rendering a `<button>`. |

| Data attribute | Description |
| --- | --- |
| data-state | `"open"` or `"closed"`. |

### DrawerContent

The panel, Radix `Dialog.Content` portalled to the body with its own scrim; forwards all its props. Re-provides its density to every part inside.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| side | "top" \| "right" \| "bottom" \| "left" | "right" | The edge it slides from. Top and bottom are sheets with a grab handle; left and right are full-height panels. |
| size | "sm" \| "md" \| "lg" \| "xl" | "md" | Caps the width of a side panel (`max-w-sm` to `max-w-xl`) or the height of a sheet (40 to 92dvh). |
| density | "comfortable" \| "compact" | "compact" | 24px padding with an 18px title, or 16px with a 16px title. Falls back to the nearest `DensityProvider`. |
| swipeToClose | boolean | true | Drag the handle or header toward the edge to dismiss: past about 45% of the panel, or on a flick. |
| showHandle | boolean | true | Show the grab handle on `top` and `bottom` sheets. |
| showClose | boolean | true | Render the built-in top-right close button. |
| closeLabel | string | "Close" | Accessible label of the built-in close button. |
| onOpenAutoFocus | (event: Event) => void | - | Called as focus moves in on open; `preventDefault()` and focus your first field instead. |
| onCloseAutoFocus | (event: Event) => void | - | Called as focus returns to the trigger on close. |
| onEscapeKeyDown | (event: KeyboardEvent) => void | - | Called on Escape; `preventDefault()` keeps the drawer open. |
| onInteractOutside | (event: Event) => void | - | Called on a pointer down or focus outside the panel; `preventDefault()` keeps it open. |

| Data attribute | Description |
| --- | --- |
| data-state | `"open"` or `"closed"`, on the panel and on the scrim. |
| data-side | The resolved `side`. |

| CSS variable | Description |
| --- | --- |
| --surface | Set to `var(--popover)`, read by nested Inputs and Selects. |

### DrawerHeader

The title block at the panel's edge, and a drag region for swipe-to-dismiss. Forwards all native `<div>` props.

### DrawerTitle

The heading the drawer is announced by, Radix `Dialog.Title` (an `<h2>`). Required for accessibility; hide it with `sr-only` when the design has none.

### DrawerDescription

Muted supporting copy, Radix `Dialog.Description` (a `<p>`).

### DrawerBody

The region between header and footer that scrolls on its own; a swipe never starts here. Forwards all native `<div>` props.

### DrawerFooter

The action row pinned to the panel's far edge: stacked and reversed on mobile, right-aligned from `sm`. Forwards all native `<div>` props.

### DrawerClose

Closes the drawer, Radix `Dialog.Close`. Renders a `<button>` and forwards all its props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| asChild | boolean | false | Merge onto your own element (a footer `Button`, a nav link) instead of rendering a `<button>`. |

### DrawerNav

An in-sheet navigation stack holding `DrawerView` pages; its height animates to the active one and it resets each time the drawer opens. Forwards all native `<div>` props except `onChange`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| defaultView* | string | - | The view shown when the drawer opens. |
| onViewChange | (view: string) => void | - | Called whenever the active view changes, on a push or a pop. |

### DrawerView

One page in the stack, rendered only while active; it pushes in from the right going forward and from the left on back. Forwards all native `<div>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| view* | string | - | The id this page is shown for. |

| Data attribute | Description |
| --- | --- |
| data-direction | `"forward"` or `"back"` after the first navigation; absent on the first view. |

### DrawerNavTrigger

Pushes a view onto the stack when clicked, unless your `onClick` calls `preventDefault()`. Forwards all native `<button>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| view* | string | - | The `DrawerView` to open. |
| asChild | boolean | false | Merge onto your own row or button instead of rendering a `<button>`. |

### DrawerNavBack

An icon button that pops the stack; renders nothing at the root view, so it can sit in a shared header. Forwards all native `<button>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| label | string | "Back" | Accessible label. |
| children | React.ReactNode | - | Replaces the default caret glyph. |

### useDrawerNav

A hook for driving the stack from anywhere inside a `DrawerNav`, e.g. after an async action. Returns `{ activeView, canGoBack, navigate(view), back() }`.

## 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}`.

### Where does focus go when a drawer opened by state closes?

With a DrawerTrigger, focus returns to the trigger. Without one (a drawer opened from a shortcut or a row action), DrawerContent returns focus to the element that had it when the drawer opened, as long as that element is still on the page, so keyboard users never land back at the top of the document. To pick the target yourself, pass `onCloseAutoFocus`, call `e.preventDefault()` and focus your own element.

### 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` sets padding and the title size instead (`compact` by default, `comfortable` for roomier marketing surfaces) 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 { GearSix as Gear, SignOut, UserCircle } from "koala-icons"
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>
  )
}
```

## Anatomy

```tsx
import {
  DropdownMenu, DropdownMenuTrigger, DropdownMenuContent, DropdownMenuLabel,
  DropdownMenuGroup, DropdownMenuItem, DropdownMenuItemText, DropdownMenuItemDescription,
  DropdownMenuShortcut, DropdownMenuCheckboxItem, DropdownMenuRadioGroup,
  DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuSub,
  DropdownMenuSubTrigger, DropdownMenuSubContent,
} from "@/components/ui/dropdown-menu"

<DropdownMenu>
  <DropdownMenuTrigger />
  <DropdownMenuContent>
    <DropdownMenuLabel />
    <DropdownMenuGroup>
      <DropdownMenuItem>
        <DropdownMenuItemText>
          <DropdownMenuItemDescription />
        </DropdownMenuItemText>
        <DropdownMenuShortcut />
      </DropdownMenuItem>
    </DropdownMenuGroup>
    <DropdownMenuCheckboxItem />
    <DropdownMenuRadioGroup>
      <DropdownMenuRadioItem />
    </DropdownMenuRadioGroup>
    <DropdownMenuSeparator />
    <DropdownMenuSub>
      <DropdownMenuSubTrigger />
      <DropdownMenuSubContent />
    </DropdownMenuSub>
  </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-brand ring-offset-2 ring-offset-background transition-transform duration-fast ease-out focus-visible:ring-2"
    >
      <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 the small gray `Kbd` chip at the row's end. It is 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>
```

## API reference

### DropdownMenu

The root, Radix `DropdownMenu.Root`; renders no DOM. Every part that renders an element accepts `className`, merged last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| open | boolean | - | Controlled open state. |
| defaultOpen | boolean | false | Initial open state when uncontrolled. |
| onOpenChange | (open: boolean) => void | - | Called when the menu opens or closes. |
| modal | boolean | true | Block pointer interaction with the page and trap focus while open. |
| dir | "ltr" \| "rtl" | - | Reading direction; flips sub-menus and arrow keys. |

### DropdownMenuTrigger

Opens the menu, Radix `DropdownMenu.Trigger`. Renders a `<button>` and forwards all its props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| asChild | boolean | false | Merge onto your own element (a `Button`, an avatar button) instead of rendering a `<button>`. |

| Data attribute | Description |
| --- | --- |
| data-state | `"open"` or `"closed"`. |
| data-disabled | Present when the trigger is disabled. |

### DropdownMenuContent

The menu surface, Radix `DropdownMenu.Content` portalled to the body (or to the full-screen element); forwards all its props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| submenu | "nested" \| "navigation" | "nested" | How every `DropdownMenuSub` opens: a flyout beside its row, or a layer that replaces the rows in place behind a Back row. |
| side | "top" \| "right" \| "bottom" \| "left" | "bottom" | Preferred side of the trigger; the menu flips when there is no room. |
| align | "start" \| "center" \| "end" | "center" | Alignment against the trigger. |
| sideOffset | number | 6 | Gap in pixels between the trigger and the menu. |
| alignOffset | number | 0 | Shift in pixels along the alignment axis. |
| collisionPadding | number | 0 | Distance in pixels kept from the viewport edge. |
| loop | boolean | false | Arrow keys wrap from the last row to the first. |
| container | HTMLElement \| null | - | Portal target. Defaults to the body, or the element that is full screen when the menu opens. |
| density | "comfortable" \| "compact" | "compact" | Row height for every row inside, 36px or 32px. Unset, the rows follow the nearest `DensityProvider`. |
| onCloseAutoFocus | (event: Event) => void | - | Called as focus returns to the trigger on close; `preventDefault()` to send it elsewhere. |
| onEscapeKeyDown | (event: KeyboardEvent) => void | - | Called on Escape; in navigation mode Escape first steps back a layer. |
| onInteractOutside | (event: Event) => void | - | Called on a pointer down or focus outside the menu; `preventDefault()` keeps it open. |

| Data attribute | Description |
| --- | --- |
| data-state | `"open"` or `"closed"`. |
| data-side | The side the menu actually opened on, after collisions. |
| data-align | `"start"`, `"center"` or `"end"`. |
| data-submenu | `"nested"` or `"navigation"`. |

| CSS variable | Description |
| --- | --- |
| --surface | Set to `var(--popover)`, read by nested Inputs and Selects. |
| --radix-dropdown-menu-trigger-width | The trigger's width, for a menu that matches it (`w-(--radix-dropdown-menu-trigger-width)`). |
| --radix-dropdown-menu-content-available-height | Height left between the trigger and the viewport edge, for capping a long menu. |
| --radix-dropdown-menu-content-transform-origin | The trigger-side origin, for a custom entrance. |

### DropdownMenuItem

A row, Radix `DropdownMenu.Item` (a `<div role="menuitem">`); forwards all its props. Put a leading icon first and a `DropdownMenuShortcut` last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| variant | "default" \| "destructive" | "default" | Destructive tints the label, the leading icon and the highlight red. |
| inset | boolean | false | Indent the text to line up with icon-bearing siblings. |
| onSelect | (event: Event) => void | - | Called when the row is chosen; `preventDefault()` keeps the menu open. |
| disabled | boolean | false | Dims the row and skips it in keyboard navigation. |
| textValue | string | - | Text used for typeahead when the row's content is not plain text. |
| asChild | boolean | false | Merge onto your own element, e.g. a `next/link`, keeping the row's styling and keys. |
| density | "comfortable" \| "compact" | "compact" | Row height, 36px or 32px. Falls back to the menu's `density`, then the nearest `DensityProvider`. |

| Data attribute | Description |
| --- | --- |
| data-highlighted | Present on the row under the pointer or keyboard focus. |
| data-disabled | Present when the row is disabled. |
| data-inset | Present on an `inset` row. |

### DropdownMenuItemText

The title and description column of a described row, placed after the leading icon. Forwards all native `<span>` props.

### DropdownMenuItemDescription

The muted sentence under a row's title, inside `DropdownMenuItemText`; the leading icon then pins to the title's line. Forwards all native `<span>` props.

### DropdownMenuCheckboxItem

A toggle row, Radix `DropdownMenu.CheckboxItem` (`role="menuitemcheckbox"`); forwards all its props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| checked | boolean \| "indeterminate" | - | The checked state. |
| onCheckedChange | (checked: boolean) => void | - | Called when the row is toggled. |
| variant | "check" \| "switch" | "check" | An ink check on the right, or a mini Switch on the same line for a setting that applies at once. |
| closeOnSelect | boolean | true | Close the menu on toggle. Defaults to `false` when `variant="switch"`. |
| disabled | boolean | false | Dims the row and skips it in keyboard navigation. |
| density | "comfortable" \| "compact" | "compact" | Row height, 36px or 32px. Falls back to the menu's `density`, then the nearest `DensityProvider`. |

| Data attribute | Description |
| --- | --- |
| data-state | `"checked"`, `"unchecked"` or `"indeterminate"`. |
| data-highlighted | Present on the row under the pointer or keyboard focus. |
| data-disabled | Present when the row is disabled. |

### DropdownMenuRadioGroup

Groups radio rows into one exclusive choice, Radix `DropdownMenu.RadioGroup`. Forwards all native `<div>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| value | string | - | The selected value. |
| onValueChange | (value: string) => void | - | Called when another row is chosen. |

### DropdownMenuRadioItem

One choice in a `DropdownMenuRadioGroup`, Radix `DropdownMenu.RadioItem`; shows the same ink check as a checkbox row. Forwards all its props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| value* | string | - | The value this row selects. |
| disabled | boolean | false | Dims the row and skips it in keyboard navigation. |
| density | "comfortable" \| "compact" | "compact" | Row height, 36px or 32px. Falls back to the menu's `density`, then the nearest `DensityProvider`. |

| Data attribute | Description |
| --- | --- |
| data-state | `"checked"` or `"unchecked"`. |
| data-highlighted | Present on the row under the pointer or keyboard focus. |
| data-disabled | Present when the row is disabled. |

### DropdownMenuLabel

A muted caption over a run of rows, Radix `DropdownMenu.Label`; not focusable. Forwards all native `<div>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| inset | boolean | false | Indent to line up with icon-bearing rows. |
| density | "comfortable" \| "compact" | "compact" | Row height, 36px or 32px. Falls back to the menu's `density`, then the nearest `DensityProvider`. |

### DropdownMenuGroup

Groups related rows (`role="group"`), Radix `DropdownMenu.Group`. Forwards all native `<div>` props.

### DropdownMenuSeparator

A hairline between groups that stops at the ring's inner edge, Radix `DropdownMenu.Separator`. Forwards all native `<div>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| density | "comfortable" \| "compact" | "compact" | Row height, 36px or 32px. Falls back to the menu's `density`, then the nearest `DensityProvider`. |

### DropdownMenuShortcut

A display-only key hint pushed to the row's end: the small gray `Kbd` chip. Forwards all `Kbd` props; it binds no key.

### DropdownMenuSub

Pairs a `DropdownMenuSubTrigger` with the `DropdownMenuSubContent` it opens, Radix `DropdownMenu.Sub`; renders no DOM.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| open | boolean | - | Controlled open state. Ignored in navigation mode, where the menu owns the open branch. |
| defaultOpen | boolean | false | Initial open state when uncontrolled; nested mode only. |
| onOpenChange | (open: boolean) => void | - | Called when the sub-menu opens or closes; nested mode only. |

### DropdownMenuSubTrigger

The row that opens a sub-menu, with a trailing caret; Radix `DropdownMenu.SubTrigger`, or a plain item in navigation mode. Forwards all its props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| inset | boolean | false | Indent the text to line up with icon-bearing siblings. |
| disabled | boolean | false | Dims the row and skips it in keyboard navigation. |
| textValue | string | - | Text used for typeahead. |
| density | "comfortable" \| "compact" | "compact" | Row height, 36px or 32px. Falls back to the menu's `density`, then the nearest `DensityProvider`. |

| Data attribute | Description |
| --- | --- |
| data-state | `"open"` or `"closed"` (nested mode). |
| data-highlighted | Present on the row under the pointer or keyboard focus. |
| data-disabled | Present when the row is disabled. |

### DropdownMenuSubContent

The sub-menu, Radix `DropdownMenu.SubContent`: a surface beside its row in nested mode, or rows that take the menu's place in navigation mode (where `className` and the positioning props do not apply).

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| backLabel | string | "Back" | Navigation mode: label of the row that returns to the parent layer. |
| sideOffset | number | 0 | Gap in pixels between the row and the flyout. |
| alignOffset | number | 0 | Shift in pixels along the row. |
| loop | boolean | false | Arrow keys wrap from the last row to the first. |
| density | "comfortable" \| "compact" | "compact" | Row height, 36px or 32px. Falls back to the menu's `density`, then the nearest `DensityProvider`. |

| Data attribute | Description |
| --- | --- |
| data-state | `"open"` or `"closed"`. |
| data-side | The side the flyout opened on. |

### DropdownMenuPortal

Radix `DropdownMenu.Portal`, exported for custom compositions; `DropdownMenuContent` already portals itself.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| container | HTMLElement \| null | document.body | Where the portal mounts. |
| forceMount | true | - | Keep the children mounted while closed. |

## 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 change the menu's row height?

Rows are compact (32px) by default. For 36px rows, set `density="comfortable"` on DropdownMenuContent and every row inside follows, sub-menus included. Without it, rows follow the nearest DensityProvider, even through the portal. A row's own `density` still wins, for a one-off. The edge line and the concentric corners stay the same 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Installation

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

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

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

Pro: `emoji-picker` comes with a [Koala UI Pro license](https://www.koalaui.com/pro). Its source is not published in these docs.

## Usage

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Anatomy

```tsx
import {
  EmojiPicker,
  EmojiPickerPopover,
  EmojiPickerTrigger,
  EmojiPickerContent,
} from "@/components/ui/emoji-picker"

<EmojiPicker />

<EmojiPickerPopover>
  <EmojiPickerTrigger />
  <EmojiPickerContent />
</EmojiPickerPopover>
```

## 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`.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Density

Density retunes the panel width, viewport height, grid gap, and glyph size, never color or radius. `compact` is the default, sized for application UI; `comfortable` opens it up for marketing pages. Without a prop it resolves from the nearest `DensityProvider`.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## API reference

### EmojiPicker

The whole picker: search, category nav, grid and preview footer. Forwards all native `<div>` props except `onSelect`; every part accepts `className`, merged last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| onEmojiSelect | (emoji: string, datum: EmojiDatum) => void | - | Called with the glyph and its `{ char, name, keywords }` record when an emoji is chosen. |
| data | EmojiCategory[] | emojiCategories | The categorized dataset; swap in a full Unicode export without touching the component. |
| presets | string[] | defaultEmojiPresets | The fixed frequently-used row pinned above the categories. |
| recent | string[] | - | Controlled recently-used list, most recent first. |
| defaultRecent | string[] | [] | Initial recents when uncontrolled; replaced by the persisted list once it loads. |
| onRecentChange | (recent: string[]) => void | - | Called whenever the recents change, controlled or not. |
| recentLimit | number | 24 | Most recents kept. |
| storageKey | string \| null | "koala-emoji-recent" | `localStorage` key that persists uncontrolled recents; `null` turns persistence off. |
| showSearch | boolean | true | Render the search row. |
| showPreview | boolean | true | Render the footer that previews the hovered or focused emoji. |
| showRecent | boolean | true | Render and track the recently-used row; off, picks are not recorded. |
| showPresets | boolean | true | Render the presets row. |
| categoriesPerPage | number | 3 | Categories mounted at first and per scroll batch; search results stream in batches of this times 16. |
| searchPlaceholder | string | "Search emoji" | Placeholder of the search field. |
| recentLabel | string | "Recently used" | Header and nav label of the recents row. |
| presetsLabel | string | "Frequently used" | Header and nav label of the presets row. |
| previewPlaceholder | string | "Pick an emoji" | Footer hint before anything is hovered or focused. |
| density | "comfortable" \| "compact" | "compact" | Width (352px or 320px), viewport height, grid gap and glyph size. Falls back to the nearest `DensityProvider`. |

| Data attribute | Description |
| --- | --- |
| data-active | `true` on the category nav button whose section is at the top of the viewport. |

| CSS variable | Description |
| --- | --- |
| --surface | Set to `var(--popover)`, so the nested search Input blends with the panel. |

### EmojiPickerPopover

The popover root, Radix `Popover.Root`; renders no DOM and lets the content close itself on select.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| open | boolean | - | Controlled open state. |
| defaultOpen | boolean | false | Initial open state when uncontrolled. |
| onOpenChange | (open: boolean) => void | - | Called when the popover opens or closes, including the close after a pick. |
| modal | boolean | false | Block outside interaction and trap focus while open. |

### EmojiPickerTrigger

The button that opens the picker, Radix `Popover.Trigger`. Renders a `<button>` and forwards all its props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| asChild | boolean | false | Merge onto your own button instead of rendering one. |

| Data attribute | Description |
| --- | --- |
| data-state | `"open"` or `"closed"`. |

### EmojiPickerContent

Radix `Popover.Content` portalled to the body, holding an `EmojiPicker`. Radix Content props (placement, collisions, focus and dismiss callbacks) go to the popover; every other prop, `EmojiPicker` options and native `div` props alike, goes to the picker. `className` styles the popover wrapper; `pickerClassName` styles the picker.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| closeOnSelect | boolean | true | Close the popover after a pick. |
| pickerClassName | string | - | Classes for the inner picker surface. |
| side | "top" \| "right" \| "bottom" \| "left" | "bottom" | Preferred side of the trigger; flips on collision. |
| sideOffset | number | 8 | Gap in pixels between the trigger and the picker. |
| align | "start" \| "center" \| "end" | "start" | Alignment against the trigger. |
| alignOffset | number | 0 | Offset in pixels from the `align` edge. |
| avoidCollisions | boolean | true | Flip and shift to stay inside the viewport. |
| collisionPadding | number \| Partial<Record<Side, number>> | 0 | Distance from the boundary edges that counts as a collision. |
| collisionBoundary | Element \| Element[] \| null | [] | Extra elements used as the collision boundary. |
| sticky | "partial" \| "always" | "partial" | Keep the picker in view while the trigger scrolls. |
| hideWhenDetached | boolean | false | Hide the picker when the trigger is fully clipped. |
| onOpenAutoFocus | (event: Event) => void | - | Fires when focus moves into the picker on open; `preventDefault()` to keep it on the trigger. |
| onCloseAutoFocus | (event: Event) => void | - | Fires when focus returns to the trigger on close. |
| onEscapeKeyDown | (event: KeyboardEvent) => void | - | Fires on Escape; `preventDefault()` keeps it open. |
| onInteractOutside | (event: Event) => void | - | Fires on a pointer or focus outside; `preventDefault()` keeps it open. `onPointerDownOutside` and `onFocusOutside` are also accepted. |
| forceMount | true | - | Keep the popover mounted while closed, for external animation control. |

| Data attribute | Description |
| --- | --- |
| data-state | `"open"` or `"closed"`. |
| data-side | The side the popover actually opened on, after collisions; drives the slide direction. |
| data-align | `"start"`, `"center"` or `"end"`. |

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Installation

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

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

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

Pro: `empty-state` comes with a [Koala UI Pro license](https://www.koalaui.com/pro). Its source is not published in these docs.

## Usage

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Anatomy

```tsx
import {
  EmptyState,
  EmptyStateMedia,
  EmptyStateTitle,
  EmptyStateDescription,
  EmptyStateActions,
} from "@/components/ui/empty-state"

<EmptyState>
  <EmptyStateMedia />
  <EmptyStateTitle />
  <EmptyStateDescription />
  <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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Illustrated states

Give each empty moment a small object that belongs to the job: an archive waiting for its first project, a mail sorter with no letters, or a search bench with an empty tray. Keep the machine quiet and let the title and description explain what happened.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Density

`density` retunes padding, the media and icon size, the title size, and the description measure, never color or the rounded brand corners. `comfortable` suits a full page or marketing surface; `compact` (the default) fits an in-panel placeholder. Without a prop it reads the nearest `DensityProvider`, so an app shell can set it once.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Without actions

The action row is optional; drop `EmptyStateActions` for a purely informational placeholder.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Inline

An empty list inside a record (no evidence, no linked vehicles) sits between sections that have content, and the stacked block would outweigh all of them. `layout="inline"` puts the same parts on one line: a small tile, the title as a muted message, and any action pushed to the end.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## API reference

### EmptyState

The root: a centered column that shares `variant` and `density` with every part through context. Forwards all native `<div>` props; every part accepts `className`, merged last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| variant | "default" \| "primary" \| "success" \| "warning" \| "info" \| "destructive" | "default" | Colors the media icon from one semantic token; the tile stays neutral in every variant. |
| density | "comfortable" \| "compact" | "compact" | Retunes padding, the media and icon size, the title size and the description measure. Falls back to the nearest `DensityProvider`. |
| layout | "stacked" \| "inline" | "stacked" | `inline` lays the parts on one left-aligned line (small tile, the title as a muted message, actions at the end) for an empty list inside a sheet or panel. Mirrored as `data-layout`. |
| asChild | boolean | false | Merge onto your own element via Radix Slot instead of rendering a `<div>`. |

### EmptyStateMedia

The neutral icon tile (hairline ring, no fill), sized by density; wrap a single icon. Rendered `aria-hidden`, and forwards all native `<div>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| asChild | boolean | false | Merge onto your own element via Radix Slot instead of rendering a `<div>`. |

### EmptyStateTitle

The balanced, semibold title. Renders a `<div>` and forwards all native `<div>` props.

### EmptyStateDescription

Muted supporting copy kept to a readable measure. Forwards all native `<p>` props.

### EmptyStateActions

The optional action row; holds one `outline` Button, since an empty state points at a single next step. Forwards all native `<div>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| size | "sm" \| "md" \| "lg" | "sm" | Control height imposed on the children, so the button needs no `size`; an explicit one still wins. |

| Data attribute | Description |
| --- | --- |
| data-control-size | The imposed control size. |

## 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 option for a full page or marketing surface, while `compact` (the default) 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 `compact`, 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/event-calendar.md -->

# Event Calendar

Month, week and day views of a schedule. Drag an event to another slot, pull an edge to change its length, or do both from the keyboard.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Installation

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

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

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

Pro: `event-calendar` comes with a [Koala UI Pro license](https://www.koalaui.com/pro). Its source is not published in these docs.

## Usage

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Anatomy

```tsx
import {
  EventCalendar,
  EventCalendarHeader,
  EventCalendarTitle,
  EventCalendarNav,
  EventCalendarViewSwitch,
  EventCalendarBody,
} from "@/components/ui/event-calendar"

<EventCalendar>
  <EventCalendarHeader>
    <EventCalendarTitle />
    <EventCalendarNav />
    <EventCalendarViewSwitch />
  </EventCalendarHeader>
  <EventCalendarBody />
</EventCalendar>
```

## Drag, resize and keys

In the week and day grid, drag an event to another time or day, or pull its top or bottom edge to change its length, in steps of `snapMinutes`. Events that overlap sit side by side. The event in hand lifts and glides from step to step, a dashed outline marks where it came from, the events around it stay put, and the grid scrolls when you reach its edge. `Escape` puts it back. A press without movement is still a click. Nothing changes until you let go: then `onEventChange` gets the updated event, and you write it back into `events`. With an event focused, the arrow keys do the same: up and down move it by `snapMinutes`, left and right by a day, and `Shift` with up or down changes its length. Click empty space to create an event through `onSlotClick`.

## Month

Timed events show as a dot, a time and a title; all-day events as a tinted bar, listed first. A day with more than `maxEventsPerDay` ends in "+N more", which opens that day. Drag an event to another cell, or move it with the arrow keys: a day sideways, a week up or down. Click a day number to open that day.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Day

One column fits a sidebar or a phone. Pass a single entry to `views` and the view switch goes away.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Read only

`editable={false}` turns off dragging and the keys; events still open through `onEventClick`. The header is made of parts: this one leaves out the view switch. `startHour`, `endHour` and `hourHeight` fit a working day into a shorter card.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Colours

`color` tints the block and its bar with one of the theme's roles, so events stay readable in all four themes. Without it, an event uses `neutral`.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## API reference

### EventCalendar

The card holding the schedule, 680px tall (an `h-*` class sets another height). With no children it renders `EventCalendarHeader` and `EventCalendarBody`. Forwards all native `<div>` props, and every part accepts `className`, merged last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| events* | CalendarEvent[] | - | `{ id, title, start, end, allDay?, color? }`. An all-day event's `end` is its last day, inclusive. |
| onEventChange | (event: CalendarEvent) => void | - | Called with the updated event when a drag, a resize or a key moves it. Write it back into `events`. |
| onEventClick | (event: CalendarEvent) => void | - | Called on a click, or Enter on a focused event. Never after a drag. |
| onSlotClick | (slot: CalendarSlot) => void | - | Called when empty space is clicked: a `snapMinutes × 2` slot in the time grid, a whole day in the month grid. |
| view | "month" \| "week" \| "day" | - | The view on show. Controlled. |
| defaultView | "month" \| "week" \| "day" | "week" | The view it opens on. Uncontrolled. |
| onViewChange | (view) => void | - | Called when the switch, a day heading or "+N more" changes the view. |
| date | Date | - | Any day inside the period on show. Controlled. |
| defaultDate | Date | today | The day it opens on. Uncontrolled; without it, the calendar opens on the browser's today. |
| onDateChange | (date: Date) => void | - | Called when the reader navigates. |
| views | EventCalendarView[] | ["month", "week", "day"] | The views the switch offers. One view hides the switch. |
| weekStartsOn | 0–6 | 1 | The first day of the week, 0 for Sunday. |
| locale | string | the browser's | BCP 47 locale for every label. |
| editable | boolean | true | Events can be dragged, resized and moved with the keyboard. |
| snapMinutes | number | 15 | Drags, resizes and keys move in steps of this many minutes. |
| hourHeight | number | 48 | The height of one hour in the time grid, in px. |
| startHour | number | 0 | The first hour the time grid shows. |
| endHour | number | 24 | The hour the time grid ends at. |
| scrollToHour | number | 8 | The hour the time grid opens scrolled to. |
| maxEventsPerDay | number | 3 | Rows a month cell fills before the last one becomes "+N more". |

| Data attribute | Description |
| --- | --- |
| data-view | `month`, `week` or `day`. |

### EventCalendarHeader

The bar above the grid. With no children: title, navigation and the view switch. Forwards all native `<div>` props.

### EventCalendarTitle

An `<h2>` naming the period, the year in the muted ink, announced politely when it changes. Forwards all native `<h2>` props.

### EventCalendarNav

Today, previous and next: an outline `Button` and two ghost icon buttons. Forwards all native `<div>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| todayLabel | string | "Today" | The label of the button that returns to today. |

### EventCalendarViewSwitch

A segmented `ToggleGroup` over the root's `views`; renders nothing with one view. Forwards `ToggleGroup` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| labels | Partial<Record<EventCalendarView, string>> | - | The label of each view. |

### EventCalendarBody

The grid for the current view. A new period fades and rises in once the reader navigates, never on load. Forwards all native `<div>` props.

## FAQ

### Does it need a date library?

No. It works on plain Date objects in the browser's time zone and formats every label with Intl, so it adds nothing to your bundle. Bring date-fns or Temporal for your own logic if you want; the calendar only reads start and end.

### Who owns the events?

You do. The calendar never changes events by itself: it calls onEventChange with the updated event and paints whatever you pass back. That is where you save to your API, refuse a move, or check for conflicts.

### Can I move events without a mouse?

Yes. Every event is a focusable button with a full label (title, day and times). The arrow keys move it, Shift with up or down changes its length, and Enter opens it. Every change a drag can make, the keys can make too.

### How do I open a dialog for an event?

Use onEventClick to open a Dialog, Sheet or Popover with your own form, and onSlotClick to create an event at the clicked time. The calendar handles the grid and leaves the forms to you.

---

<!-- 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Installation

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

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

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

Pro: `expandable-search` comes with a [Koala UI Pro license](https://www.koalaui.com/pro). Its source is not published in these docs.

## Usage

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## API reference

### ExpandableSearch

An `InputRoot` whose leading magnifier is the button that opens it; forwards all `InputRoot` props and native `<div>` props. `className` is merged last, and a width class there (default `w-64`) sets the open width only.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| open | boolean | - | Controlled open state. A controlled change never moves focus; focus the field yourself through `inputProps.ref`. |
| defaultOpen | boolean | false | Initial open state when uncontrolled; mounting open does not take focus. |
| onOpenChange | (open: boolean) => void | - | Called when the field expands or collapses. |
| size | "sm" \| "md" \| "lg" | "sm" | Height of the open field (32, 36 or 40px) and side of the closed square. Unset, it follows `density`, then the container's imposed size, then the nearest `DensityProvider` (compact `sm`, comfortable `md`). |
| density | "comfortable" \| "compact" | - | Only picks the default `size` (compact `sm`, comfortable `md`); an explicit `size` wins. |
| placeholder | string | "Search" | Placeholder of the field. |
| label | string | - | Accessible name shared by the button and the field; defaults to `placeholder`. |
| inputProps | InputFieldProps | - | Forwarded to the `<input type="search">` (`value`, `onChange`, `name`, `ref`...). Escape clears a controlled value through its own `onChange`. |
| children | ReactNode | - | Trailing content inside the open field, such as an `InputSuffix` holding a `Kbd`. |
| hasError | boolean | false | Error border and ring, as on an Input; cascades from a surrounding `Field`. |
| disabled | boolean | false | Disables the button and the field; cascades from a surrounding `Field`. |
| variant | "default" \| "inline" | "default" | The Input's chrome variant, passed through to `InputRoot`. |

| Data attribute | Description |
| --- | --- |
| data-state | `"open"` or `"closed"`. |
| data-disabled | Present when disabled. |
| data-error | Present when `hasError` is set. |

## 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>
```

## Help behind an icon

When the help is a nice-to-know rather than an instruction, and a form stacks enough fields that a line under each one doubles its height, pass it to `info` on the label instead of a `FieldHint`. It shows in a tooltip on an info icon, and screen readers still hear it as the control's description. Keep `FieldHint` for anything the person needs to read before typing, and for errors.

```tsx
<Field>
  <FieldLabel info="A short, descriptive name for the report.">Title</FieldLabel>
  <InputRoot>
    <InputField placeholder="Robbery at the Pacific Standard" />
  </InputRoot>
</Field>
```

## Validation

Put the constraint on the control: `required`, `type="email"`, `pattern`, `minLength`. Inside a `Form`, a failed submit shows the message in the field, focuses the first invalid control and shakes it. No browser bubble. `FieldError` with `match` gives each failure its own copy, and takes the hint's place while it shows.

```tsx
<Form onFormSubmit={save}>
  <Field>
    <FieldLabel required>Email</FieldLabel>
    <InputRoot>
      <InputField name="email" type="email" required />
    </InputRoot>
    <FieldHint>We send the receipt here.</FieldHint>
    <FieldError match="valueMissing">Enter your email.</FieldError>
    <FieldError match="typeMismatch">That email is missing an @ or a domain.</FieldError>
  </Field>

  <Field>
    <FieldLabel required>Postcode</FieldLabel>
    <InputRoot>
      <InputField name="postcode" required pattern="[0-9]{5}" />
    </InputRoot>
    <FieldError match="valueMissing">Enter a postcode.</FieldError>
    <FieldError match="patternMismatch">Use five digits.</FieldError>
  </Field>

  <FormActions>
    <Button type="submit">Continue</Button>
  </FormActions>
</Form>
```

Skip `FieldError` and the field shows the browser's own message. Leave out `match` and one `FieldError` shows whatever failed.

## Custom validation

`validate` runs once the native constraints pass. It gets the value and every value in the form, and returns a message, a list of them, or `null`.

```tsx
<Field
  validate={(value) => {
    const errors = []
    if (value.length < 8) errors.push("Use at least 8 characters.")
    if (!/[0-9]/.test(value)) errors.push("Add a number.")
    return errors
  }}
>
  <FieldLabel required>Password</FieldLabel>
  <InputRoot><InputField name="password" type="password" /></InputRoot>
  <FieldHint>8 characters and a number.</FieldHint>
</Field>

<Field validate={(value, values) => (value === values.password ? null : "The passwords don't match.")}>
  <FieldLabel required>Confirm password</FieldLabel>
  <InputRoot><InputField name="confirm" type="password" /></InputRoot>
</Field>
```

## Async validation

Return a promise to check against your API. Pair it with `validationDebounceTime` so a request waits for a pause in typing. A stale answer never overwrites a newer one, and a submit waits for pending checks. `data-validating` is on the Field while one runs.

```tsx
<Form validationMode="onChange" validationDebounceTime={300} onFormSubmit={claim}>
  <Field validate={checkUsername} className="group/field">
    <FieldLabel required>Username</FieldLabel>
    <InputRoot>
      <InputField name="username" />
      <InputSuffix className="hidden group-data-validating/field:flex">
        <Spinner aria-hidden />
      </InputSuffix>
    </InputRoot>
    <FieldHint>Checked as you type.</FieldHint>
  </Field>
</Form>

async function checkUsername(value) {
  const res = await fetch("/api/username?q=" + encodeURIComponent(value))
  const { taken } = await res.json()
  return taken ? "That username is taken." : null
}
```

## Field states

The Field root carries its state as data attributes, so you can style anything inside it: `data-invalid`, `data-valid`, `data-touched`, `data-dirty`, `data-filled`, `data-focused` and `data-validating`.

```tsx
<Field className="group/field">
  <FieldLabel className="group-data-focused/field:text-foreground">Email</FieldLabel>
  …
</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>
```

## Shape

Fields are rounded rectangles, not pills: sm 12, md 14 and lg 16, the same corner as an icon-only Button of that size. Any Button inside a `<form>` takes that corner too, so a submit button always matches the field beside it. The same Button outside a form stays a pill.

```tsx
<form className="flex gap-2">
  <InputRoot size="sm"><InputField placeholder="you@example.com" /></InputRoot>
  <Button size="sm">Subscribe</Button>
</form>

<form className="flex gap-2">
  <InputRoot size="md"><InputField placeholder="you@example.com" /></InputRoot>
  <Button size="md">Subscribe</Button>
</form>

<form className="flex gap-2">
  <InputRoot size="lg"><InputField placeholder="you@example.com" /></InputRoot>
  <Button size="lg">Subscribe</Button>
</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>

    <form className="contents" onSubmit={(e) => { e.preventDefault(); handleSubmit() }}>
      <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 type="button" variant="ghost">Cancel</Button>
        <Button type="submit">Create account</Button>
      </DialogFooter>
    </form>
  </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>
```

## API reference

### Field

One labelled control. Renders a `div` and forwards its props. Generates the ids, wires `aria-describedby` and `aria-invalid`, and validates the control inside.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| hasError | boolean | - | Forces the error state and wins over anything computed. Leave it unset to let native constraints, `validate` and server `errors` decide. |
| required | boolean | false | Appends a destructive asterisk to the label. Put `required` on the control too for the check itself. |
| disabled | boolean | false | Dims the label, disables the control and skips validation. |
| name | string | - | The key for this field's value and server errors. Defaults to the control's `name`. |
| validate | (value: unknown, formValues: FormValues) => string \| string[] \| null \| Promise<…> | - | Runs after native constraints pass. Return a message, several, or `null` when valid. |
| validationMode | "onSubmit" \| "onBlur" \| "onChange" | - | Overrides the Form's mode for this field. |
| validationDebounceTime | number | - | Overrides the Form's debounce for this field, in ms. |

| Data attribute | Description |
| --- | --- |
| data-invalid | Present while the field is invalid. `data-error` mirrors it. |
| data-valid | Present once the field has been validated and passed. |
| data-validating | Present while an async `validate` is pending. |
| data-touched | Present once focus has left the field. |
| data-dirty | Present when the value differs from the initial one. |
| data-filled | Present when the control has a value. |
| data-focused | Present while focus is inside the field. |
| data-disabled | Present when the field is disabled. |

### FieldLabel

The shared `Label`, wired to the field's control through `htmlFor`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| required | boolean | - | Appends the asterisk. Inherited from the Field. |
| disabled | boolean | - | Dims the label. Inherited from the Field. |
| info | ReactNode | - | Help behind an info icon after the text, in a tooltip. Screen readers get it as the control's description. |

### FieldHint

The shared `Hint`: helper text that describes the control. An error takes its place while it shows.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| hasError | boolean | - | Switches to the destructive tone. Inherited from the Field. |

### FieldError

The error message. Without one, the Field renders its own. Describes the control through `aria-describedby` while it shows.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| match | "valueMissing" \| "typeMismatch" \| "patternMismatch" \| "tooShort" \| "tooLong" \| "rangeUnderflow" \| "rangeOverflow" \| "stepMismatch" \| "badInput" \| "customError" \| boolean | - | Show only for one validity state. `customError` covers `validate` and server errors. `true` always shows. |
| children | ReactNode | - | Your copy. Without it, the field's own message (the browser's, your validator's or the server's). |

### FieldGroup

Several controls answering one question: a real `fieldset`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| hasError | boolean | false | Destructive tone on the hint, `aria-invalid` on the fieldset. |
| disabled | boolean | false | Natively disables every control inside. |
| required | boolean | false | Appends the asterisk to the legend. |

### FieldGroupLabel

The group's `legend`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| required | boolean | - | Appends the asterisk. Inherited from the group. |
| info | ReactNode | - | Help behind an info icon after the legend, in a tooltip. Describes the fieldset. |

### FieldRow

Sibling fields on one line, stacked below `sm`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| columns | 2 \| 3 | 2 | Columns from `sm` up. |

## 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.

### Does Field validate on its own?

Yes. It checks the native constraints on its control (required, type, pattern, minLength and the rest), then your validate function. Inside a Form, the Form decides when that runs and blocks a submit that fails. Outside one, a plain form's own validation still shows the message in the field.

### Do hasError and FieldHint still work?

Yes. An explicit hasError wins over anything the field computed, and the FieldHint turns destructive as before. Setting hasError also tells the field you own the message, so it does not render one of its own.

### 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.

### Why does my Button look different inside a form?

A Button inside a form element takes the field corner for its size (sm 12, md 14, lg 16) so it lines up with the inputs next to it. Outside a form, and inside a form that lives in a Popover, the same Button is a pill. Wrap a field and button row in a form to get the match; pass className="rounded-pill!" to keep a pill.

### 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Installation

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

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

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

Pro: `file-card` comes with a [Koala UI Pro license](https://www.koalaui.com/pro). Its source is not published in these docs.

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Anatomy

```tsx
import {
  FileCard,
  FileCardIcon,
  FileCardThumbnail,
  FileCardContent,
  FileCardName,
  FileCardMeta,
  FileCardProgress,
  FileCardValue,
  FileCardActions,
  FileCardStatus,
} from "@/components/ui/file-card"

<FileCard>
  <FileCardIcon />
  <FileCardThumbnail />
  <FileCardContent>
    <FileCardName />
    <FileCardMeta />
    <FileCardProgress />
  </FileCardContent>
  <FileCardValue />
  <FileCardActions />
  <FileCardStatus />
</FileCard>
```

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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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).

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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`.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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`.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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`.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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`.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## API reference

### FileCard

The root: owns the surface, layout, state and density, and shares them with every part through context. Forwards all native `<div>` props; every part accepts `className`, merged last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| layout | "row" \| "tile" | "row" | `row` is the attachment line; `tile` is a square image-grid cell where the thumbnail fills the card and the actions become a hover scrim. |
| variant | "default" \| "outline" \| "elevated" \| "ghost" | "default" | Chrome: an edge ring with a soft lift, a bare `--border` ring, a filled lifted card, or no chrome and no padding (flush in feeds). |
| state | "idle" \| "uploading" \| "success" \| "error" | "idle" | Upload state, read by `FileCardStatus` and `FileCardProgress`; `error` tints the surface with a soft destructive ring. |
| density | "comfortable" \| "compact" | "compact" | Padding, gap and media size (48px or 40px). Falls back to the nearest `DensityProvider`. |
| interactive | boolean | false | Adds the pointer, hover lift, press feedback and focus ring for a card that opens the file. |
| asChild | boolean | false | Merge onto your own element (a link, a button) instead of rendering a `<div>`. |

| Data attribute | Description |
| --- | --- |
| data-state | `"idle"`, `"uploading"`, `"success"` or `"error"`. |

| CSS variable | Description |
| --- | --- |
| --surface | Set to `var(--card)` on `elevated`, read by nested controls. |

### FileCardIcon

The leading file illustration, decorative (`aria-hidden`). Pass `children` instead of `type` to put your own glyph in a soft muted tile. Forwards all native `<div>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| type | "pdf" \| "image" \| "video" \| "audio" \| "doc" \| "sheet" \| "slides" \| "archive" \| "code" \| "design" \| "text" \| "default" | "default" | File category: picks the tone and the default band label. Derive it with `fileTypeFromName(name)`. |
| label | string | - | Text stamped on the band, e.g. the real extension `"DOCX"`. Defaults to the type's stand-in (`"PDF"`, `"XLS"`). |

### FileCardThumbnail

An image preview in the icon's footprint, clipped to the concentric radius with an inset outline. Forwards all native `<img>` props to the image.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| alt* | string | - | A meaningful description of the image. |

### FileCardContent

The column that fills the row and lets the name truncate. Forwards all native `<div>` props.

### FileCardName

The file name, truncated on one line. Forwards all native `<div>` props.

### FileCardMeta

The muted meta line (size, date) in `tabular-nums`; takes small icons. Forwards all native `<div>` props.

### FileCardValue

A trailing readout (`60%`, `2.4 MB of 8 MB`) placed beside `FileCardContent`, so a full-width progress bar runs under the name. Forwards all native `<div>` props.

### FileCardActions

Trailing buttons on the row's right edge; in `tile` layout, a blurred scrim that fades in on hover or focus. Forwards all native `<div>` props.

### FileCardProgress

An upload bar built on Progress (`size="sm"`) with an optional label and percentage above it; it turns destructive when the card's `state` is `error`. Forwards native `<div>` props except `children`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| value | number | 0 | Upload completion, 0 to 100. |
| label | React.ReactNode | - | Leading label above the bar, e.g. `"Uploading…"`. |
| hideValue | boolean | false | Drop the percentage, typically because a `FileCardValue` shows it on the row's edge. |

### FileCardStatus

A trailing status glyph: a spinner, a green check or a warning. Renders nothing while the card is `idle`. Forwards all native `<span>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| status | "uploading" \| "success" \| "error" | - | Override the glyph; by default it follows the card's `state`. |
| label | string | - | Accessible name when the glyph is the only carrier of the status: it then announces as an image and becomes focusable. Without it the glyph is `aria-hidden`. |

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Installation

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

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

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

Pro: `file-preview` comes with a [Koala UI Pro license](https://www.koalaui.com/pro). Its source is not published in these docs.

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Anatomy

```tsx
import {
  FilePreview,
  FilePreviewHeader,
  FilePreviewIcon,
  FilePreviewInfo,
  FilePreviewTitle,
  FilePreviewMeta,
  FilePreviewActions,
  FilePreviewDownload,
  FilePreviewClose,
  FilePreviewThumbnails,
  FilePreviewViewport,
  FilePreviewToolbar,
  FilePreviewThumbnailsToggle,
  FilePreviewPageNav,
  FilePreviewZoomOut,
  FilePreviewZoomMenu,
  FilePreviewZoomIn,
  FilePreviewFit,
  FilePreviewRotate,
  FilePreviewFullscreen,
} from "@/components/ui/file-preview"

<FilePreview>
  <FilePreviewHeader>
    <FilePreviewIcon />
    <FilePreviewInfo>
      <FilePreviewTitle />
      <FilePreviewMeta />
    </FilePreviewInfo>
    <FilePreviewActions>
      <FilePreviewDownload />
      <FilePreviewClose />
    </FilePreviewActions>
  </FilePreviewHeader>
  <FilePreviewThumbnails />
  <FilePreviewViewport>
    <FilePreviewToolbar>
      <FilePreviewThumbnailsToggle />
      <FilePreviewPageNav />
      <FilePreviewZoomOut />
      <FilePreviewZoomMenu />
      <FilePreviewZoomIn />
      <FilePreviewFit />
      <FilePreviewRotate />
      <FilePreviewFullscreen />
    </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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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`.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## API reference

### FilePreview

The root: resolves the file (a Blob becomes an object URL), picks the renderer, owns the view state and handles the keyboard shortcuts. Forwards native `<div>` props except `onError`; every part that renders an element accepts `className`, merged last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| file | Blob \| null | - | The file to show: a `File` from an input or a drop, or any `Blob`. |
| src | string | - | Or a URL to read it from. Ignored when `file` is set. |
| name | string | - | Display name. Defaults to the File's name, else the last segment of `src`. |
| type | string | - | MIME type. Defaults to the File's type; otherwise the name's extension decides. |
| size | number | - | Size in bytes, for the meta line. Defaults to the File's size. |
| kind | "pdf" \| "image" \| "video" \| "audio" \| "text" \| "unsupported" | - | Pick the renderer yourself instead of detecting it from the type and the name. |
| zoom | FilePreviewZoom | - | Controlled zoom: `"fit"`, `"width"`, or a scale (`1` is 100%). |
| defaultZoom | FilePreviewZoom | "fit" | Initial zoom when uncontrolled. |
| onZoomChange | (zoom: FilePreviewZoom) => void | - | Called when the zoom changes, from a control, a key or a pinch. |
| rotation | number | - | Controlled rotation in degrees, in multiples of 90. |
| defaultRotation | number | 0 | Initial rotation when uncontrolled. |
| onRotationChange | (rotation: number) => void | - | Called when the view rotates. |
| defaultPage | number | 1 | The page a PDF opens at. |
| onPageChange | (page: number) => void | - | Called as the reader moves through the pages. |
| minZoom | number | 0.1 | Lowest scale the zoom controls reach (a fit may go lower). |
| maxZoom | number | 5 | Highest scale the zoom controls reach. |
| defaultThumbnailsOpen | boolean | true | Whether the page rail starts open (it only exists from `md` up). |
| textLayer | boolean | true | Lay PDF.js's selectable text over each page, so text can be selected, copied and found. |
| pdfOptions | FilePreviewPdfOptions | - | Passed to PDF.js's `getDocument`: `cMapUrl`, `standardFontDataUrl`, `wasmUrl`, `password`, `withCredentials`. |
| onDownload | () => void | - | Replace the built-in download (an anchor with the file's name; a cross-origin URL is fetched first). |
| variant | "default" \| "outline" \| "plain" | "default" | The frame: the edge ring with the smallest lift, the bare `--border` ring, or no frame at all. |

| Data attribute | Description |
| --- | --- |
| data-kind | `"pdf"`, `"image"`, `"video"`, `"audio"`, `"text"` or `"unsupported"`. |
| data-status | `"loading"`, `"ready"` or `"error"`. |
| data-fullscreen | Present while the preview is full screen. |

### FilePreviewHeader

The identity bar across the top, ruled off from the canvas. Forwards all native `<div>` props.

### FilePreviewIcon

The file's FileIcon, its type and extension taken from the file in hand. Forwards FileIcon's props (except `type` and `extension`) and native `<svg>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| size | "sm" \| "md" \| "lg" \| "xl" | "sm" | Height: 32, 40, 48 or 64px. |
| variant | "default" \| "soft" \| "solid" | "default" | FileIcon's fill treatment. |
| label | string | - | Override the stamped text outright. |

### FilePreviewInfo

The name-over-meta column; it lets a long name truncate. Forwards all native `<div>` props.

### FilePreviewTitle

The file's name on one truncated line, the whole name on hover. Children replace it. Forwards all native `<div>` props.

### FilePreviewMeta

A line composed from what is known (format, size, then the page count, pixel size, running time or line count as the file loads). Children replace it. Forwards all native `<div>` props.

### FilePreviewActions

The trailing actions on the header's right edge. Forwards all native `<div>` props.

### FilePreviewDownload

Saves the file under its own name; icon-only unless you pass children. A Button: takes every Button prop except `iconOnly`, and `preventDefault()` in `onClick` skips the download.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| variant | ButtonProps["variant"] | "ghost" | Any Button variant. |
| size | ButtonProps["size"] | "sm" | Any Button size. |
| static | boolean | true | Kept for compatibility; controls no longer scale on press. |

### FilePreviewClose

An icon-only close button. Inside `FilePreviewDialog` it closes the dialog; anywhere else wire its `onClick`. Takes every Button prop except `iconOnly`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| variant | ButtonProps["variant"] | "ghost" | Any Button variant. |
| size | ButtonProps["size"] | "sm" | Any Button size. |
| static | boolean | true | Kept for compatibility; controls no longer scale on press. |

### FilePreviewThumbnails

The page rail beside the canvas, from `md` up, for a document with more than one page; renders nothing otherwise. Thumbnails paint as the rail scrolls. Forwards all native `<nav>` props.

| Data attribute | Description |
| --- | --- |
| data-state | `"open"` or `"closed"` (hidden), toggled by `FilePreviewThumbnailsToggle`. |
| data-active | On the current page's thumbnail, which wears the ink ring. |
| data-page-number | On each thumbnail, its 1-based page number. |

### FilePreviewViewport

The canvas: renders the file in its own focusable scroller and holds what floats over it, the toolbar first. It owns the gestures (⌘/Ctrl + wheel, pinch, drag to pan a zoomed photo, double-click). Forwards all native `<div>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| contentProps | Omit<React.ComponentProps<"div">, "ref" \| "children"> | - | Props for the scroller inside, the element that takes focus and scrolls. |

| Data attribute | Description |
| --- | --- |
| data-pannable | On the scroller while a photo is larger than the canvas and drags to pan. |

| CSS variable | Description |
| --- | --- |
| --surface | Set to `var(--muted)`, read by controls inside the canvas. |
| --file-preview-toolbar-space | Room reserved at the bottom of the scroll area while a toolbar floats over it. |

### FilePreviewToolbar

The controls' bar, a Toolbar that takes every Toolbar prop. Floats bottom centre inside the viewport, docks in the header with `variant="plain"`, and renders nothing for a file it cannot control or one that failed to load.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| variant | "floating" \| "outline" \| "plain" \| "solid" | "floating" | The Toolbar's surface. |
| size | "sm" \| "md" \| "lg" | "md" | The Toolbar's control size. |
| scrollable | boolean | true | Scroll sideways instead of overflowing a narrow canvas. |

### FilePreviewZoomOut

One zoom step out (shortcut `-`). Each control is a ToolbarButton held still on press and takes its props except `tooltip` and `shortcut`; it renders nothing when the file cannot zoom.

### FilePreviewZoomIn

One zoom step in (shortcut `+`), disabled at `maxZoom`. Takes ToolbarButton props except `tooltip` and `shortcut`.

### FilePreviewZoomMenu

The live zoom readout, which opens fit to page, fit to width and the fixed levels in a dropdown. Takes ToolbarButton props except `tooltip`, `shortcut` and `children`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| presets | number[] | ZOOM_PRESETS | The fixed levels listed under the fit modes (`1` is 100%): `[0.5, 0.75, 1, 1.25, 1.5, 2, 3, 4]`, filtered to `minZoom`/`maxZoom`. |

### FilePreviewFit

Fit to page (shortcut `0`) and fit to width as a pair of toggles; neither is pressed after a manual zoom.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| disabled | boolean | false | Disable both toggles. |

### FilePreviewRotate

A quarter turn of the view (shortcut `R`, or `⇧R` counterclockwise); the download still saves the original. Takes ToolbarButton props except `tooltip` and `shortcut`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| direction | "clockwise" \| "counterclockwise" | "clockwise" | Which way the view turns. |

### FilePreviewPageNav

Previous page, a page field that jumps on Enter (Escape restores it), the count, next page. Renders only for a paged document; takes only `className`.

### FilePreviewThumbnailsToggle

Shows or hides the page rail; renders only where the rail can exist. Takes ToolbarButton props except `tooltip` and `shortcut`.

### FilePreviewFullscreen

The whole preview full screen (shortcut `F`); renders nothing where the browser cannot go full screen. Takes ToolbarButton props except `tooltip` and `shortcut`.

### FilePreviewDialog

The preview in a modal on Radix Dialog with the Dialog's scrim: edge to edge on a phone, focus on the canvas, and it keeps the last file while fading out. Takes every `FilePreview` prop (children are the preview's parts); the inner preview defaults to `variant="plain"`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| open | boolean | - | Controlled open state. |
| defaultOpen | boolean | false | Initial open state when uncontrolled. |
| onOpenChange | (open: boolean) => void | - | Called when the dialog opens or closes (Esc, the scrim, `FilePreviewClose`). |
| title | string | the file's name | The dialog's visually hidden accessible title. |
| className | string | - | Classes for the dialog surface. |
| previewClassName | string | - | Classes for the `FilePreview` inside. |

| Data attribute | Description |
| --- | --- |
| data-state | `"open"` or `"closed"`, on the dialog surface and the overlay. |

| CSS variable | Description |
| --- | --- |
| --surface | Set to `var(--popover)` on the dialog surface. |

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Installation

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

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

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

Pro: `file-upload` comes with a [Koala UI Pro license](https://www.koalaui.com/pro). Its source is not published in these docs.

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Anatomy

```tsx
import {
  FileUpload,
  FileUploadDropzone,
  FileUploadIcon,
  FileUploadTitle,
  FileUploadLink,
  FileUploadDescription,
  FileUploadTrigger,
  FileUploadSources,
  FileUploadSource,
  FileUploadList,
  FileUploadGrid,
} from "@/components/ui/file-upload"

<FileUpload>
  <FileUploadDropzone>
    <FileUploadIcon />
    <FileUploadTitle>
      <FileUploadLink />
    </FileUploadTitle>
    <FileUploadDescription />
    <FileUploadTrigger />
    <FileUploadSources>
      <FileUploadSource />
    </FileUploadSources>
  </FileUploadDropzone>
  <FileUploadList />
  <FileUploadGrid />
</FileUpload>
```

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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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 Koala glyph.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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 and size.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## API reference

### FileUpload

The root: holds the hidden file input, validates every drop or pick, and shares the picker with its parts. It owns selection only; you keep the file list. Forwards native `<div>` props except `onError`; every part accepts `className`, merged last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| onFiles | (files: File[]) => void | - | Accepted files from a drop or browse. Fires only when at least one file passes. |
| onReject | (rejections: FileRejection[]) => void | - | Rejected files, each `{ file, reason }` with reason `"type"`, `"size"` or `"count"`. |
| accept | string | - | Native input `accept`, e.g. `"image/*,.pdf"`; also checked against dropped files. |
| multiple | boolean | false | Allow more than one file per selection; without it, extra files are rejected with `"count"`. |
| maxSize | number | - | Max size per file, in bytes. Larger files are rejected with `"size"`. |
| disabled | boolean | false | Make the whole control inert: the dropzone stops taking drops and clicks, and the link, trigger and sources disable. |
| density | "comfortable" \| "compact" | "compact" | Dropzone padding, block rhythm and glyph size. Falls back to the nearest `DensityProvider`. |

| Data attribute | Description |
| --- | --- |
| data-disabled | Present while `disabled`. |

### FileUploadDropzone

The dashed drop surface; a click anywhere opens the picker. It is not a button, so compose a `FileUploadLink` or `FileUploadTrigger` inside as the keyboard path. Forwards all native `<div>` props.

| Data attribute | Description |
| --- | --- |
| data-dragging | Present while a file is dragged over the panel. |
| data-disabled | Present while the root is `disabled`. |

### FileUploadIcon

The glyph crowning the dropzone, decorative and toned full ink while dragging. Defaults to an image placeholder; pass your own icon as `children`. Forwards all native `<div>` props.

### FileUploadTitle

The dropzone's one balanced sentence, with a `FileUploadLink` inline. Forwards all native `<div>` props.

### FileUploadDescription

Muted supporting copy, e.g. accepted types and size limit. Forwards all native `<div>` props.

### FileUploadLink

The inline picker button inside the sentence, in full ink; renders `"click here"` when it has no `children`. Forwards all native `<button>` props.

### FileUploadTrigger

A Button that opens the picker, inside the dropzone or on its own; renders `"Browse files"` when it has no `children`. Takes every Button prop.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| variant | ButtonProps["variant"] | "outline" | Any Button variant. |

### FileUploadSources

The layout-only "or import from" row of `FileUploadSource` tiles. Forwards all native `<div>` props.

### FileUploadSource

One import shortcut: the provider's mark as `children` in a bordered tile, its name beneath. Wire `onClick` to that provider's picker; it never opens the local file dialog. Forwards all native `<button>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| label* | React.ReactNode | - | The name under the mark, e.g. `"Google Drive"`; also the button's accessible name. |

### FileUploadList

A layout-only column for the resulting `FileCard` rows; the exported `formatBytes(bytes)` turns `file.size` into a meta line (`"1.8 MB"`). Forwards all native `<div>` props.

### FileUploadGrid

A layout-only grid (2 columns, 3 from `sm`) for image uploads; fill it with `<FileCard layout="tile">`. Forwards all native `<div>` props.

## 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?

An unset dropzone already renders `compact`, the tight padding for dense forms. Set `density` to `comfortable` on the root for the roomy panel, which opens up 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/floating-window.md -->

# Floating Window

A movable, resizable window over your app, the way a desktop keeps a second document at hand. Drag it by its title bar, resize it from the corner, double-click the bar to fold it away. Geometry is in rem, so it scales with the root font size, and the app keeps the state.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Installation

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

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

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

Pro: `floating-window` comes with a [Koala UI Pro license](https://www.koalaui.com/pro). Its source is not published in these docs.

## Usage

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Anatomy

```tsx
import { FloatingWindow, FloatingWindowLayer } from "@/components/ui/floating-window"

<FloatingWindowLayer>
  <FloatingWindow title="…" x={…} y={…} width={…} height={…}>
    …
  </FloatingWindow>
</FloatingWindowLayer>
```

## Managing windows

The window is controlled: it reports a drag through `onMove(x, y)` and a resize through `onResize(width, height)`, already kept inside the layer and above the minimum, and draws whatever you pass back. The z-order is yours too: give each window a `zIndex` and raise it in `onFocusWindow`, which fires when the window is pressed anywhere or focus moves into it from outside. A few lines of state are the whole window manager.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Minimize and controls

`minimized` folds the window up to its title bar, like a window shade. Its content stays mounted (a half-written note survives) and turns `inert` until it unfolds. The bar shows a control only for a handler you pass: `onToggleMinimize` adds the minimize button and the double-click on the bar, `onClose` adds the close button. Double-click the folded bar below.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Sizing in rem

`x`, `y`, `width`, `height`, `minWidth` (18 by default) and `minHeight` (4.25: the bar and 2rem of content) are all rem, so a UI that scales by changing the root font size scales its windows with it. The pointer is converted with the root font size read when a drag starts. A move keeps 6rem of the window inside the layer on the left (the controls) and 4rem on the right, and the bar never leaves the top or bottom; a resize stops half a rem short of the layer's far edges. Without a `FloatingWindowLayer` around it, a window is unbounded.

## API reference

### FloatingWindowLayer

An `absolute inset-0` `<div>` over its positioned parent, transparent to the pointer except where a window is. Its box bounds the windows inside it; a `FloatingWindow` outside a layer still works, without bounds. Every div prop is forwarded, `ref` included; `className` is merged last.

| Data attribute | Description |
| --- | --- |
| data-slot | `"floating-window-layer"`. |

### FloatingWindow

A non-modal `role="dialog"` named by its `title` (or your `aria-label`). Controlled: it reports moves and resizes and the app keeps the state, z-order included. Every other div prop is forwarded; `style` merges over the geometry and `className` is merged last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| title* | React.ReactNode | - | The window's name: shown in the bar, and the dialog's accessible name. |
| icon | React.ElementType | - | A glyph before the title: the component, not an element (`icon={Browser}`). |
| x* | number | - | Left edge inside the layer, in rem. |
| y* | number | - | Top edge inside the layer, in rem. |
| width* | number | - | Width in rem. |
| height* | number | - | Height in rem, while not minimized. |
| minimized | boolean | false | Folded to the title bar. The content stays mounted (and `inert`). |
| zIndex | number | - | Stacking order among the layer's windows. Raise it in `onFocusWindow`. |
| minWidth | number | 18 | Smallest width a resize can reach, in rem. |
| minHeight | number | 4.25 | Smallest height a resize can reach, in rem: the bar and 2rem of content. |
| onFocusWindow | () => void | - | The window was pressed, or focus moved into it: bring it to the front. |
| onMove | (x: number, y: number) => void | - | A drag of the title bar: the new `x` and `y`, in rem, already kept inside the layer. |
| onResize | (width: number, height: number) => void | - | A drag of the corner grip: the new `width` and `height`, in rem, within the limits. |
| onToggleMinimize | () => void | - | Shows the minimize button and enables double-click on the bar. |
| onClose | () => void | - | Shows the close button. |
| minimizeLabel | string | "Minimize" | The minimize button's accessible name. |
| closeLabel | string | "Close" | The close button's accessible name. |
| static | boolean | false | Kept for compatibility; controls no longer scale on press. |

| Data attribute | Description |
| --- | --- |
| data-slot | `"floating-window"`, with `floating-window-bar`, `-title`, `-controls`, `-minimize`, `-close`, `-body` and `-grip` inside. |
| data-state | `"open"` or `"minimized"`, on the window and on its body. |

| CSS variable | Description |
| --- | --- |
| --surface | Set to `var(--popover)` on the body, the ground its controls paint on. |

## FAQ

### Floating Window or Dialog?

A Dialog interrupts: it is modal, centred and closes before you go on. A Floating Window sits beside the work, non-modal, so you can keep a record open while you use the page under it, and keep several.

### Can it be moved with the keyboard?

Moving and resizing are pointer gestures. Everything inside the window is reachable with Tab, the controls included, and tabbing into a window brings it to the front.

### What about phones?

It is a desktop pattern: a small screen has no room to keep two documents side by side. On a phone, show the same content in a Sheet or a Drawer.

### Why does a minimized window keep its content?

So nothing is lost: a draft, a scroll position or a running query survive the fold. The folded content is inert, so it takes no focus and is hidden from assistive technology.

---

<!-- 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Installation

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

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

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

Pro: `form` comes with a [Koala UI Pro license](https://www.koalaui.com/pro). Its source is not published in these docs.

## 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, and the validation of the Fields inside it.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

`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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

`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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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`.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

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

Each `Field` checks its control's native constraints, then its own `validate`. The Form decides when. On a failed submit it blocks the submission, focuses the first invalid control and shakes it, with no browser bubble. [`Field`](https://www.koalaui.com/docs/components/field.md) covers the per-field side: matching messages, custom and async checks.

`validationMode` sets the timing. `onSubmit` (the default) stays quiet until the first submit, then re-checks each field as it changes. `onBlur` checks a field when focus leaves it. `onChange` checks on every keystroke.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

`onFormSubmit` receives the values as an object keyed by field `name`, and only runs when everything passes. A plain `onSubmit` still works, and also runs only once the form is valid. Pass `noValidate` to skip the native constraints and keep only your `validate` functions.

## Server errors

Pass `errors`, keyed by field `name`. Each one shows in its field and clears as soon as that value changes. It is the shape a Server Action returns, so `useActionState` plugs straight in. Submit as is to see both errors.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

Client checks run first, so the action only fires for a form that already passes. A new set of errors focuses the first field it names.

## With a form library

A library that owns its own state drives the Field through `hasError`, which wins over anything the Field computed, and puts the message in a `FieldError`. Pass `noValidate` so the library alone decides.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## API reference

### Form

A plain `form` element that forwards every native prop (`action` included). Owns the rhythm, the control height and the validation of the Fields inside.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| size | "sm" \| "md" \| "lg" | "lg" | Height of every control inside. A control's own `size` still wins. |
| density | "compact" \| "comfortable" | - | The gap between fields: 16 or 20px. Falls back to the density provider. |
| layout | "stack" \| "row" \| "plain" | "stack" | A field column, a one-line capture, or no rhythm for a form that is itself a card. |
| validationMode | "onSubmit" \| "onBlur" \| "onChange" | "onSubmit" | When fields check themselves. Every mode validates the whole form on submit. |
| validationDebounceTime | number | 0 | Wait this many ms after the last change before validating. |
| errors | Record<string, string \| string[]> | - | Server errors keyed by field `name`. Each clears when its field changes. |
| onFormSubmit | (values: FormValues, event) => void | - | Called with the values, keyed by `name`, only when every field is valid. Prevents the native submit. |
| onSubmit | (event) => void | - | The native handler. Only called once validation passes. |
| noValidate | boolean | - | Skip native constraints. `validate` functions still run. |

### FormSection

A chapter of a long form. Renders a `section`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| layout | "stack" \| "split" | "stack" | Header above the fields, or beside them (needs `FormSectionBody`). |
| density | "compact" \| "comfortable" | - | The rhythm inside the chapter. |
| size | "sm" \| "md" \| "lg" | - | A different control height for this chapter. |

### FormSectionHeader

Stacks the title and description.

### FormSectionTitle

The chapter heading, an `h3`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| asChild | boolean | false | Render your own heading element. |

### FormSectionDescription

One line under the title.

### FormSectionBody

The field column of a `split` section.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| density | "compact" \| "comfortable" | - | The rhythm between fields. |

### FormActions

The bar that closes the form.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| align | "start" \| "end" \| "between" \| "stack" | "end" | Where the buttons sit. `stack` is the full-width submit. |
| bordered | boolean | false | Rules the bar off from the fields above. |

## 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?

Yes, as a thin layer rather than a state library. Fields check native constraints and their own validate function, and the Form decides when, blocks a failed submit, focuses the first invalid control and threads server errors into the fields. It still renders a plain form element, so react-hook-form, TanStack Form or server actions keep working: drive Field's hasError from them and pass noValidate.

### 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/handheld-device.md -->

# Handheld Device

The shell of a physical gadget: a breathalyzer, a fingerprint scanner, a pager. Dark moulded plastic with a phosphor LCD, hardware keys, status LEDs, a press-and-hold sensor pad and a thermal printer that feeds a receipt out of its base. The same object in every theme.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Installation

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

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

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

Pro: `handheld-device` comes with a [Koala UI Pro license](https://www.koalaui.com/pro). Its source is not published in these docs.

## Usage

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

The shell stacks its parts in a column, and every part can be left out: a pager is a screen and a key, a scanner is LEDs and a sensor pad. Size the shell with `className` (`w-80` by default, its height from its content); `HandheldDeviceBrand` sinks to the bottom of a shell taller than its parts. Everything is presentational: your app owns the state machine (idle, measuring, result) and the parts paint it.

## Anatomy

```tsx
import {
  HandheldDevice,
  HandheldDeviceBrand,
  HandheldDeviceGrille,
  HandheldDeviceKey,
  HandheldDeviceKeys,
  HandheldDeviceLed,
  HandheldDeviceLeds,
  HandheldDeviceMeter,
  HandheldDevicePrinter,
  HandheldDeviceReadout,
  HandheldDeviceReceipt,
  HandheldDeviceScreen,
  HandheldDeviceScreenBody,
  HandheldDeviceScreenFooter,
  HandheldDeviceScreenHeader,
  HandheldDeviceSensor,
} from "@/components/ui/handheld-device"

<HandheldDevice>
  <HandheldDeviceGrille />
  <HandheldDeviceScreen>
    <HandheldDeviceScreenHeader />
    <HandheldDeviceScreenBody>
      <HandheldDeviceReadout />
      <HandheldDeviceMeter value={…} />
    </HandheldDeviceScreenBody>
    <HandheldDeviceScreenFooter />
  </HandheldDeviceScreen>
  <HandheldDeviceLeds>
    <HandheldDeviceLed />
  </HandheldDeviceLeds>
  <HandheldDeviceKeys>
    <HandheldDeviceKey />
  </HandheldDeviceKeys>
  <HandheldDeviceSensor />
  <HandheldDeviceBrand />
  <HandheldDevicePrinter>
    <HandheldDeviceReceipt />
  </HandheldDevicePrinter>
</HandheldDevice>
```

## Tones

`HandheldDeviceScreen` takes `tone`: `green` (the default phosphor, ready or ok), `yellow` (attention, a new record), `orange` (a read error) and `red` (an alarm, a positive). The tone is an ink variable that cascades: every line on the screen glows in it, and a header, a body, a footer or a readout can take its own over it.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Faults

`fault` makes the picture fail while the bezel holds still. `flicker` is a loose contact: the picture dips a few times every second and a half. `glitch` is a broken panel: it jumps, skews and drops out, its color swims, and torn bands run across it. Under reduced motion both hold still, and a broken panel keeps its bands, so the fault still reads.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Readouts

`HandheldDeviceReadout` is a run of lit text anywhere on the device. It takes a `tone` of its own, `blink` for the busy signal, `inverse` for a lit cell with the text knocked out of it (the LCD's highlight), and `dim` for a backlight that is off. It is a `<span>`; `asChild` renders your own element instead.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Block meter

`HandheldDeviceMeter` draws the bar an LCD can: `[█████─────]` over the percentage, from a `value` of 0 to 100 (`blocks` cells, 10 by default). Its size is the text size you give it. To assistive tech it is a `meter` named by `label`, and the drawing is hidden.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## LEDs and keys

`HandheldDeviceLed` is a lens with its label printed under it: off it is dark with a hint of its `tone`, `lit` it glows, and `blink` pulses it. `HandheldDeviceKey` is a real `<button>` with an engraved `label` under it, which also names it. `primary` is the big round key (64px), `secondary` the small slate one (56 by 44); both press in and give a little (`static` keeps them from giving). A `tone` lights the glyph, the way an armed key glows.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Sensor pad

`HandheldDeviceSensor` is a press-and-hold pad: a recessed glass with a glyph (its `svg` child, sized for you). It reports the hold through `onPressStart` and `onPressEnd`: a pointer going down and coming up, sliding off the pad (the way lifting a finger off a reader does), Space or Enter held on the focused pad, the window lost, or the pad disabled or unmounted mid-press. Every start gets exactly one end. It does not time the read: the app does, and hands it back as `progress`, drawn as a tint rising with a scan line on its edge. Anything else you put on the pad (an `ERROR` verdict over the glyph) is laid out against the pad: position it `absolute inset-0`. Hold the pad below until the read completes.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Scanner terminal

The other end of the reader: a terminal with its LEDs, a screen that changes with the state, and a divided header that stays green whatever the body says. Pick a state to see how each one paints.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Printer

`HandheldDevicePrinter` puts a slot in the base of the shell and feeds its children out of it when `printed`: a slow 2.5s feed at a motor's pace (`duration-feed`), pulled back quicker when it turns false, and instant under reduced motion. Until then the paper is inside the device: clipped at the slot, inert and hidden from assistive tech, however long it is. To clear a receipt at once instead of pulling it back, stop rendering it.

The feed is a pure slot: it moves whatever you give it. `HandheldDeviceReceipt` is the thermal paper if you don't bring your own: a warm white strip (the cream theme's ground) in mono, torn along the bottom. The paper hangs below the shell, out of flow, so leave room under the device for it.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## A physical object

A gadget in your hand does not change color with the room, so the shell pins the dark theme (`dark`): its plastic, keys and legends read the same under light, cream, dark and moonlight. The materials are the dark theme's ground and ink mixed by the shell itself (the `--handheld-*` variables on its root, with a breath of `--info` for the cool cast of the plastic). The display glows in the four phosphor tokens, `--phosphor`, `--phosphor-yellow`, `--phosphor-orange` and `--phosphor-red`: light sources rather than text on a ground, so like `--rating` they are the same in every theme. They are also utilities (`text-phosphor`, `bg-phosphor-red/10`) for anything you lay over the glass yourself.

## Display typeface

The glass sets its text in `font-lcd`, which reads the `--font-lcd` variable and falls back to the mono stack. These docs load Share Tech Mono into it; load the face you want and point the variable at it:

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Old engines

The device is built to run in the embedded Chromium of a game or a desktop shell (103 and up): no container queries, no `:has()`, no `subgrid`, and no standalone `translate`, `scale` or `rotate`. The key press, the sensor's read and the paper feed all ride `transform`; every gradient is a plain `linear-gradient()` with no interpolation space; and every color mix is one `color-mix()` of two colors, which a build step targeting that engine can lower to `rgb()`.

## Accessibility

Keys and the sensor are real buttons with a visible focus ring, and each is at least 44px tall. A key is named by its legend. The sensor is named by `aria-label` ("Hold to scan" by default) and reports the hold with `aria-pressed`. LEDs, the grille, the scanlines and the printer slot are decoration: say what a state means in words on the screen. The screen is not a live region, because a meter filling inside it would be read out on every step; put `aria-live="polite"` on the line whose change matters, like the verdict.

## API reference

### HandheldDevice

The shell: a `<div>`, a column of parts (`w-80 p-6 gap-6`, 40px corners at the default radius), pinned `dark`. Every div prop is forwarded. Its corner is the screen's (16px) plus its padding, so a tighter shell takes a tighter corner: `p-4 rounded-4xl`. Every part forwards its element's props and merges `className` last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| tone | "green" \| "yellow" \| "orange" \| "red" | "green" | The ink of anything lit outside a screen (LEDs, lit keys, the sensor). |
| className | string | - | Sizes the shell (`w-80 h-[34rem]`), merged last. |

| Data attribute | Description |
| --- | --- |
| data-slot | `"handheld-device"`. |
| data-tone | The tone, when set. |

| CSS variable | Description |
| --- | --- |
| --handheld-tone | The phosphor ink a `tone` sets; every part inside reads it. |

### HandheldDeviceGrille

The speaker grille along the top of the shell, a `<div>` hidden from assistive tech.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| count | number | 4 | How many speaker slots. |

| Data attribute | Description |
| --- | --- |
| data-slot | `"handheld-device-grille"`. |

### HandheldDeviceScreen

The phosphor LCD: a recessed bezel, dark glass, scanlines and glare, and a glow on every line. The children are laid out in a column on the glass.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| tone | "green" \| "yellow" \| "orange" \| "red" | - | The ink of everything on the screen. Inherits the shell's when unset. |
| fault | "none" \| "flicker" \| "glitch" | "none" | A failing picture: `flicker` is a loose contact, `glitch` a broken panel. |
| className | string | - | Sizes the bezel: 4:3 at full width by default, `aspect-auto h-64` for a fixed height. |

| Data attribute | Description |
| --- | --- |
| data-slot | `"handheld-device-screen"`; the glass is `"handheld-device-screen-panel"`. |
| data-tone | The tone, when set. |
| data-fault | `"flicker"` or `"glitch"`. Absent at `none`. |

### HandheldDeviceScreenHeader

The status row along the top of the glass, a `<div>`: its children spread to the two ends.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| tone | "green" \| "yellow" \| "orange" \| "red" | - | This row's own ink, over the screen's. |
| divided | boolean | false | A hairline in the ink between this row and the body. |

| Data attribute | Description |
| --- | --- |
| data-slot | `"handheld-device-screen-header"`. |
| data-tone | The tone, when set. |

### HandheldDeviceScreenBody

The main read-out, a `<div>`: takes the room between the header and the footer, centered.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| tone | "green" \| "yellow" \| "orange" \| "red" | - | The body's own ink, over the screen's. |

| Data attribute | Description |
| --- | --- |
| data-slot | `"handheld-device-screen-body"`. |
| data-tone | The tone, when set. |

### HandheldDeviceScreenFooter

The prompt along the bottom of the glass, a `<div>`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| tone | "green" \| "yellow" \| "orange" \| "red" | - | This row's own ink, over the screen's. |
| divided | boolean | false | A hairline in the ink between this row and the body. |

| Data attribute | Description |
| --- | --- |
| data-slot | `"handheld-device-screen-footer"`. |
| data-tone | The tone, when set. |

### HandheldDeviceReadout

A run of lit text, a `<span>`: a line on the glass in a tone of its own, a blinking prompt, a highlighted verdict, or a status line glowing straight on the plastic.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| tone | "green" \| "yellow" \| "orange" \| "red" | - | Its own ink, over whatever it sits in. |
| blink | boolean | false | Pulse: the busy signal. Steady under reduced motion. |
| dim | boolean | false | Backlight off: half-strength ink with a faint halo. |
| inverse | boolean | false | A lit cell with the text knocked out of it (a highlighted verdict). |
| asChild | boolean | false | Renders the child element instead (a `<p>`, a heading), merging the styles onto it. |

| Data attribute | Description |
| --- | --- |
| data-slot | `"handheld-device-readout"`. |
| data-tone | The tone, when set. |

### HandheldDeviceMeter

The block meter an LCD draws, `[█████─────]` over the percentage: a `meter` to assistive tech, the drawing hidden from it. Size it with the text size of `className`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| value* | number | - | 0 to 100, clamped and rounded. |
| blocks | number | 10 | How many cells the bar has. |
| label | string | "Progress" | The meter's accessible name. |

| Data attribute | Description |
| --- | --- |
| data-slot | `"handheld-device-meter"`, with `"handheld-device-meter-bar"` and `"handheld-device-meter-value"` inside. |
| data-value | The clamped, rounded value. |

### HandheldDeviceLeds

A row of LEDs across the shell, a `<div>`, spread evenly.

| Data attribute | Description |
| --- | --- |
| data-slot | `"handheld-device-leds"`. |

### HandheldDeviceLed

A status LED with its label printed under it (the children), a `<div>`. The lens is decoration: say what the state means in words on the screen.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| tone | "green" \| "yellow" \| "orange" \| "red" | - | The lens color. Inherits the shell's when unset. |
| lit | boolean | false | On: the ink with a halo. Off: a dark lens with a hint of its color. |
| blink | boolean | false | Pulse while lit. Steady under reduced motion. |

| Data attribute | Description |
| --- | --- |
| data-slot | `"handheld-device-led"`, with `"handheld-device-led-lens"` and `"handheld-device-led-label"` inside. |
| data-tone | The tone, when set. |
| data-lit | Present when `lit`. |

### HandheldDeviceKeys

A row of hardware keys, a `<div>`, spread evenly and aligned on their legends.

| Data attribute | Description |
| --- | --- |
| data-slot | `"handheld-device-keys"`. |

### HandheldDeviceKey

A hardware key: a real `<button>` (the children are its glyph) with its legend under it. Every button prop is forwarded. 64px and 44px tall, both past the 40px hit area on their own.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| variant | "primary" \| "secondary" | "primary" | `primary` is the big round key (64px), `secondary` the small slate one (56x44). |
| label | React.ReactNode | - | The legend engraved under the key. It also names the key, unless you pass `aria-label`. |
| tone | "green" \| "yellow" \| "orange" \| "red" | - | Lights the glyph in this ink (an armed key). Unlit, the glyph is the plastic's grey. |
| blink | boolean | false | Pulses the lit glyph: the busy signal. |
| static | boolean | false | No give on press (the press still sinks the shadow). |
| className | string | - | Goes to the key itself, so `size-20` makes a bigger primary key. |
| containerClassName | string | - | Classes for the column that holds the key and its legend (to place or hide the whole key). |
| type | "button" \| "submit" \| "reset" | "button" | The button's type. |

| Data attribute | Description |
| --- | --- |
| data-slot | `"handheld-device-key"`; the column is `"handheld-device-key-container"`, the legend `"handheld-device-key-label"`. |
| data-variant | `"primary"` or `"secondary"`. |
| data-tone | The tone, when lit. |

### HandheldDeviceSensor

A press-and-hold sensor pad (a fingerprint reader), a real `<button>`: the children are its glyph (an `svg`, sized for you) and anything else laid over the pad. Every button prop is forwarded. It reports the hold, it does not time it; sliding off the pad ends the press, and Space or Enter held on the focused pad press it too.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| onPressStart | () => void | - | The pad was pressed: a pointer went down on it, or Space or Enter while it has focus. |
| onPressEnd | () => void | - | The press ended: released, slid off the pad, cancelled, the window lost, or the pad disabled or unmounted mid-press. Every `onPressStart` gets exactly one. |
| progress | number \| null | - | 0 to 100: the read so far, a tint rising with a scan line on its edge. `null` or omitted for no read. |
| tone | "green" \| "yellow" \| "orange" \| "red" | - | The ink of the glyph, the halo and the read. Inherits the shell's when unset. |
| lit | boolean | true | The glyph glows in the ink. Off, it is the dead grey of a locked pad. |
| blink | boolean | false | Pulses the glyph: the busy signal (analyzing). |
| disabled | boolean | false | Locks the pad; a press in progress ends. |
| aria-label | string | "Hold to scan" | The pad's accessible name. The hold is reported with `aria-pressed`. |

| Data attribute | Description |
| --- | --- |
| data-slot | `"handheld-device-sensor"`; the read is `"handheld-device-sensor-fill"`. |
| data-tone | The tone, when set. |
| data-pressed | Present while the pad is held. |
| data-progress | The clamped read, while there is one. |

| CSS variable | Description |
| --- | --- |
| --handheld-progress | The read, 0 to 100, set inline from `progress`. |

### HandheldDeviceBrand

The brand debossed into the base of the shell, a `<div>`. Sinks to the bottom of a tall shell.

| Data attribute | Description |
| --- | --- |
| data-slot | `"handheld-device-brand"`. |

### HandheldDevicePrinter

The thermal printer, a `<div>`: a slot in the base of the shell and, under it, the paper (the children) fed out over `--duration-feed` (2.5s), instant under reduced motion. Until printed the paper is clipped at the slot, inert and hidden from assistive tech. The feed hangs below the shell, out of flow: leave room under the device.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| printed | boolean | false | Feeds the paper out. Back to `false` pulls it in again; to clear a receipt at once, stop rendering the children. |

| Data attribute | Description |
| --- | --- |
| data-slot | `"handheld-device-printer"`, with `"handheld-device-printer-slot"` and `"handheld-device-printer-paper"` inside. |
| data-printed | Present when `printed`. |

| CSS variable | Description |
| --- | --- |
| --handheld-paper-width | The paper's width, `14rem`. The slot is cut a little wider; your own paper takes `w-(--handheld-paper-width)`. |

### HandheldDeviceReceipt

A strip of thermal paper for the printer, a `<div>`: warm white, set in mono, torn along the bottom, as wide as `--handheld-paper-width` (`w-56`). Bring your own receipt instead if you have one.

| Data attribute | Description |
| --- | --- |
| data-slot | `"handheld-device-receipt"`. |

## FAQ

### Why doesn't the device follow the theme?

It is a picture of a physical object, and a breathalyzer is the same black plastic in a bright office and a dark one. It pins the dark theme for its materials, and its display inks are theme-agnostic tokens.

### How do I make a breathalyzer's mouthpiece, or a pager's belt clip?

Those belong to one gadget, not to every gadget, so they are yours to draw. Wrap the shell in a relative element and position the accessory beside it; the shell paints nothing outside its own box but its shadow and the paper.

### Does the sensor time the read?

No. It reports the press (onPressStart, onPressEnd) and draws the progress you give it. The app, or a server, decides how long a read takes and what happens when the finger lifts early.

### Why is the paper clipped at the slot instead of tucked behind the shell?

So it comes out of the device whatever the shell's height or the receipt's length, and nothing peeks out above or behind the shell before it is printed.

---

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

# Hold Button

Press and hold to confirm, for the actions a stray tap must never set off: a panic call, ending a call for everyone, wiping a device. The fill is a timed Progress running on the compositor, and letting go early cancels with a shake.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Installation

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

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

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

Pro: `hold-button` comes with a [Koala UI Pro license](https://www.koalaui.com/pro). Its source is not published in these docs.

## Usage

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Variants

`neutral` (the default) sits on the secondary surface and fills with an ink tint. `destructive` is for panic-like actions: Button's soft red at rest, a deeper tint sweeping in while held, and the solid red once it fires. Both turn solid on confirm and stay that way until released, so the hold that did it is unmistakable.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Sizes

`md` (the default) is 40px, the hit target on its own; `lg` is 48px, for the one action a panel is about. Give it `className="w-full"` to span a row.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Hold time and callbacks

`holdMs` sets how long the hold must last (1000ms by default). `onConfirm` fires the moment it has, while the button is still held; a release before that fires `onCancel(ms)` with the time held, and the control shakes. Sliding the pointer off the button, tabbing away and the window losing focus all end the hold the same way. Here the hold is two seconds.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## In a dialog

The confirm step of a destructive dialog. The dialog says what is about to go; the hold makes sure the answer was meant. Close the dialog from `onConfirm`.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Keys

`keys` picks which keys hold the focused button, as `KeyboardEvent.key` names (`"Space"` is accepted for `" "`). Space and Enter by default; `["Enter"]` leaves Space to a surrounding list that uses it, and `[]` turns the keyboard hold off for a parent that drives it.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Controlled

A parent that owns the keyboard (a tablet whose list runs on arrow keys, a game binding) drives the hold with `holding` and `onHoldingChange`, the same pair as a dialog's `open`. `true` starts a hold and `false` ends it, confirmed or cancelled exactly as a release. Controlled, the button's own gestures (pointer, keys, sliding off, a lost window) only ask through `onHoldingChange` and wait for the prop; disabling it still ends the hold. `onHoldStart` fires whenever a hold begins, in both modes. Here the page listens for H itself.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Disabled

`disabled` dims the control, and disabling it mid-hold ends the hold without confirming. A one-shot action can disable itself from `onConfirm`.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Accessibility

It is a native `<button>`: Space or Enter held on it is the same hold as a pointer, and Enter never clicks it through. The button is described by a hint, "Press and hold for 1 second" by default, phrased from `holdMs`; pass `hint` to translate it. Your own `aria-describedby` is kept after it. The fill is a [timed Progress](https://www.koalaui.com/docs/components/progress.md) hidden from assistive tech, and under reduced motion it ticks instead of gliding. Some screen readers activate a button with a single synthetic click, which can never be a hold: for an action people must be able to reach that way, offer a second path too (a menu item with a confirm dialog).

## API reference

### HoldButton

A `<button>` with `data-state="idle" | "holding" | "confirmed"`. Props: `holdMs` (default `1000`), `onConfirm()`, `onCancel(heldMs)`, `onHoldStart()`, `holding` and `onHoldingChange(holding)` (controlled hold), `keys` (default `[" ", "Enter"]`), `hint`, `variant` (`neutral` · `destructive`), `size` (`md` · `lg`) and `disabled`. Children are the label (an icon is sized like Button's). Every button prop is forwarded; `className` is merged last. The fill is a Progress inside it, reachable as `[data-slot=progress-indicator]`.

## FAQ

### Hold Button or a confirm dialog?

A dialog asks a question and takes a second step; a hold is one gesture that cannot happen by accident. Use the hold where speed matters and the action is still serious (a panic call mid-chase), and a dialog where people need to read what they are about to do.

### Hold Button or Push to Talk?

Push to Talk is live for as long as it is held and reports the hold when it ends. Hold Button fires once, when the hold reaches its time, and does nothing more until released.

### Can a hold get stuck?

No. The pointer is captured on press, so the release is always heard; sliding off the button, blurring it, switching windows and hiding the tab all end the hold.

### Why doesn't it shrink when pressed?

Being held is the state: the fill already sweeps across it. A press scale on top would be a second signal for the same gesture, as with Push to Talk.

### What happens under reduced motion?

The fill ticks in steps instead of gliding, and the fades are instant. The shake on an early release stays: it carries information.

---

<!-- 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>
  )
}
```

## Anatomy

```tsx
import {
  HoverCard,
  HoverCardTrigger,
  HoverCardContent,
  HoverCardMedia,
  HoverCardTitle,
  HoverCardDescription,
  HoverCardFooter,
} from "@/components/ui/hover-card"

<HoverCard>
  <HoverCardTrigger />
  <HoverCardContent>
    <HoverCardMedia />
    <HoverCardTitle />
    <HoverCardDescription />
    <HoverCardFooter />
  </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, Radix `HoverCard.Root`; renders no DOM. Every part that renders an element accepts `className`, merged last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| openDelay | number | 700 | Milliseconds the pointer rests on the trigger before the card opens. |
| closeDelay | number | 300 | Milliseconds after the pointer leaves before the card closes: the time it has to cross into the card. |
| open | boolean | - | Controlled open state. |
| defaultOpen | boolean | false | Initial open state when uncontrolled. |
| onOpenChange | (open: boolean) => void | - | Called when the card opens or closes. |

### HoverCardTrigger

The link being previewed, Radix `HoverCard.Trigger`. Renders an `<a>` and forwards all its props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| asChild | boolean | false | Merge onto your own link (a `Link`, a Next.js link) instead of rendering an `<a>`. |

| Data attribute | Description |
| --- | --- |
| data-state | `"open"` or `"closed"`. |

### HoverCardContent

The card, Radix `HoverCard.Content` portalled to the body; forwards all its props. Declares `--surface`, so a nested control blends with the card.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| side | "top" \| "right" \| "bottom" \| "left" | "bottom" | Preferred side of the trigger; the card flips when there is no room. |
| align | "start" \| "center" \| "end" | "center" | Alignment against the trigger. |
| sideOffset | number | 8 | Gap in pixels between the trigger and the card. |
| collisionPadding | number | 8 | Distance in pixels kept from the viewport edge. |
| showArrow | boolean | false | Render a small pointer toward the trigger. |
| density | "comfortable" \| "compact" | "compact" | Padding: 16px or 12px. Falls back to the nearest `DensityProvider`. |

| Data attribute | Description |
| --- | --- |
| data-state | `"open"` or `"closed"`. |
| data-side | The side the card actually opened on, after collisions. |
| data-align | `"start"`, `"center"` or `"end"`. |

| CSS variable | Description |
| --- | --- |
| --radix-hover-card-content-transform-origin | The trigger-side origin the card grows from. |
| --radix-hover-card-content-available-width | Width left between the trigger and the viewport edge. |
| --radix-hover-card-content-available-height | Height left between the trigger and the viewport edge. |
| --surface | Set to `var(--popover)`, read by nested Inputs and Selects. |

### HoverCardTitle

The card's heading. Forwards all native `<h4>` props.

### HoverCardDescription

Muted supporting copy under the title. Forwards all native `<p>` props.

### HoverCardMedia

One `<img>` or `<video>`, aspect-video, set 8px in from the card's edges (4px compact) with concentric corners. Put it first or last. Forwards all native `<div>` props.

### HoverCardFooter

A muted flex row inset like the media; always the last part. Forwards all native `<div>` props.

## 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/ink-tray.md -->

# Ink Tray

A whiteboard's pen tray: the tool in hand rises out from behind the bar wearing its ink, and each tool remembers its own colour and stroke size.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Installation

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

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

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

Pro: `ink-tray` comes with a [Koala UI Pro license](https://www.koalaui.com/pro). Its source is not published in these docs.

## Usage

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

The colour and size belong to the tool, not to the tray: give the marker yellow and the pen black, switch between them, and each one comes back with its own ink. That is what `inks` holds, one entry per tool `value`.

## Anatomy

```tsx
import {
  InkTray,
  InkTrayTools,
  InkTrayTool,
  InkTrayBar,
  InkTraySizes,
  InkTraySize,
  InkTraySeparator,
  InkTrayColors,
  InkTrayColor,
  InkTrayCustomColor,
} from "@/components/ui/ink-tray"

<InkTray>
  <InkTrayTools>
    <InkTrayTool />
  </InkTrayTools>
  <InkTrayBar>
    <InkTraySizes>
      <InkTraySize />
    </InkTraySizes>
    <InkTraySeparator />
    <InkTrayColors>
      <InkTrayColor />
      <InkTrayCustomColor />
    </InkTrayColors>
  </InkTrayBar>
</InkTray>
```

## Tools

Four drawings ship with it. The pen wears its ink on the nib and the clip, the marker on its chisel and a window down the barrel, the pencil on its lead and the whole barrel. The eraser has no ink, so while it is in hand the colours dim and only the size can change.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## On a canvas

Control `tool` and `inks` and read them where you draw. Here the pen and the marker paint SVG strokes in their own colour and size, the marker wider and translucent, and the eraser lifts any stroke it passes over.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## API reference

### InkTray

The root: a Radix `Toolbar.Root`, so the tools, the sizes and the colours are one Tab stop and the arrow keys walk through all of them. Holds which tool is in hand and every tool's ink. Accepts `className`, merged last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| tool | string | - | The tool in hand, controlled. |
| defaultTool | string | "" | The tool in hand when uncontrolled. |
| onToolChange | (tool: string) => void | - | Called when another tool is picked up. |
| inks | Record<string, { color?: string; size?: string }> | - | Each tool's colour and size, keyed by the tool's `value`, controlled. |
| defaultInks | Record<string, { color?: string; size?: string }> | {} | Each tool's ink when uncontrolled. |
| onInksChange | (inks) => void | - | Called with every tool's ink when the tool in hand changes colour or size. |

| Data attribute | Description |
| --- | --- |
| data-slot | `"ink-tray"`. |

### InkTrayTools

The pocket the tools stand in, tucked behind the top edge of the bar. A single-choice toggle group: picking a tool never puts the last one down twice.

| Data attribute | Description |
| --- | --- |
| data-slot | `"ink-tray-tools"`. |

### InkTrayTool

One tool, drawn with its ink. It rests low in the pocket, lifts a little on hover and stands tall while in hand. Pass children to draw your own tool in place of the built-in art.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| value* | string | - | The tool's key in `tool` and `inks`. |
| label* | string | - | Accessible name and tooltip. |
| kind | "pen" \| "marker" \| "pencil" \| "eraser" | "pen" | Which drawing to show. |
| inkless | boolean | - | Disables the colours while this tool is in hand. Defaults to `true` for the eraser. |
| shortcut | string | - | Shown beside the label in the tooltip. Bind the key yourself. |

| Data attribute | Description |
| --- | --- |
| data-state | `"on"` on the tool in hand. |
| data-kind | The `kind`. |

| CSS variable | Description |
| --- | --- |
| --ink | The tool's colour, from its ink. The nib, the clip and the barrel window are painted with it. |

### InkTrayBar

The floating bar, with the same surface as a floating Toolbar. Scrolls sideways when the viewport is narrower than it.

| Data attribute | Description |
| --- | --- |
| data-slot | `"ink-tray-bar"`. |

### InkTraySizes / InkTraySize

The stroke sizes of the tool in hand. Each size is a Toolbar toggle item showing a squiggle drawn at its own weight.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| value* | string | - | The size's key, stored in the tool's ink. |
| weight* | number | - | Stroke width of the squiggle, in a 24px box. |
| label* | string | - | Accessible name and tooltip. |

### InkTrayColors / InkTrayColor

The ink colours of the tool in hand, round swatches with the Swatch Grid's selection ring. Disabled while an inkless tool is in hand.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| color* | string | - | Any CSS colour; also the value stored in the tool's ink. |
| label* | string | - | Accessible name and tooltip. |

### InkTrayCustomColor

A colour wheel swatch that opens a Color Picker above the bar. The colour picked there becomes the tool's ink and shows as a dot inside the wheel.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| label | string | "Custom colour" | Accessible name and tooltip. |

## FAQ

### Why do the tools sit behind the bar?

The bar is the lid of the tray. Tools at rest show only their tips, so the tray reads at a glance without taking a second row, and the one in hand stands out by height alone, with no chip or outline around it.

### Do the shortcuts work out of the box?

No. shortcut only prints the key in the tooltip. Bind it in your app, where you know which keys are free, and set tool from the handler.

### Can I use my theme colours as inks?

Yes. color takes any CSS colour, including a variable. var(--foreground) is a good default ink: black on light themes and white on dark ones.

---

<!-- 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>
  )
}
```

## Anatomy

```tsx
import {
  InputLabel,
  InputRoot,
  InputPrefix,
  InputPrefixLabel,
  InputField,
  InputSuffix,
  InputSuffixButton,
  InputHint,
} from "@/components/ui/input"

<InputLabel />
<InputRoot>
  <InputPrefix />
  <InputPrefixLabel />
  <InputField />
  <InputSuffix />
  <InputSuffixButton />
</InputRoot>
<InputHint />
```

## 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 Koala Icons. 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), and `lg` (40 px). Unset, it follows the container or the density (`sm` under the default compact). 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</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>
```

## Floating label

Swap `InputField` for `InputFloatingField` and the label lives inside the frame. It rests where the placeholder would and, the moment you click in, shrinks and rises to the top edge, so the label never disappears while you type. A field that already holds a value renders floated from the first paint.

```tsx
<InputRoot>
  <InputFloatingField label="Email address" type="email" placeholder="you@example.com" />
</InputRoot>

<InputRoot>
  <InputPrefix>
    <Globe />
  </InputPrefix>
  <InputFloatingField label="Website" defaultValue="koalaui.com" />
</InputRoot>

<InputRoot hasError>
  <InputFloatingField
    label="Workspace"
    defaultValue="Koala Studio"
    aria-describedby="floating-error-hint"
  />
</InputRoot>
<InputHint id="floating-error-hint" hasError>
  Only lowercase letters, numbers and dashes.
</InputHint>
```

## API reference

### InputRoot

The bordered frame that owns size, error and disabled state and shares them with its parts. Renders a `<div>` and forwards all its props. Every part accepts `className`, merged last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| size | "sm" \| "md" \| "lg" | - | Height 32, 36 or 40px. Unset, it comes from a container (`Form` imposes `lg`) or density (`compact`, the default, is `sm`; `comfortable` is `md`). |
| variant | "default" \| "inline" | "default" | `inline` is chromeless at rest and shows its frame on hover and focus, for inline-edit fields. |
| hasError | boolean | - | Destructive border and ring, and `aria-invalid` on the input. Inherited from a surrounding `Field` when unset. |
| disabled | boolean | - | Dims and locks the frame and disables the input. Inherited from a surrounding `Field`. |
| density | "comfortable" \| "compact" | - | Only picks the default `size`. An explicit `size` wins. |

| Data attribute | Description |
| --- | --- |
| data-disabled | Present when disabled. |
| data-error | Present in the error state. |

### InputField

The `<input>` itself; forwards all its props except `size`. Inside a `Field` it takes the field's `id` and `aria-describedby`.

### InputLabel

The shared `Label`, re-exported. Place it outside `InputRoot` and point `htmlFor` at the field's `id`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| required | boolean | - | Appends a destructive asterisk and a screen-reader `(required)`. |
| disabled | boolean | - | Dims the label. |

### InputHint

The shared `Hint`, re-exported: helper or error text below the frame. Renders a `<p>`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| hasError | boolean | - | Switches to the destructive tone, so the hint reads as the error. |

### InputFloatingField

An `<input>` with its label inside the frame: the label rests where the placeholder would and floats to the top edge on focus, on a value or on autofill. Pure CSS, so `defaultValue`, controlled values and autofill all render floated with no animation on load. Use it in place of `InputField`; the frame grows to 44, 48 or 56px. Other props go to the `<input>`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| label | React.ReactNode | - | The floating label, tied to the input by `htmlFor`. |
| placeholder | string | - | Shown only once the label has floated and the focused field is still empty. |
| labelClassName | string | - | Merged onto the `<label>`; `className` goes to the `<input>`. |

### InputPrefix

A leading decorative icon, `aria-hidden`. Renders a `<span>`.

### InputSuffix

A trailing decorative icon, `aria-hidden`. Renders a `<span>`.

### InputPrefixLabel

A divided leading label inside the frame (`https://`, `$`). Renders a `<span>`.

### InputSuffixButton

A trailing icon button inside the frame (clear, copy). Renders a `<button type="button">`; pass `aria-label`, since it has no visible text.

### PasswordInput

`InputRoot`, `InputField` and a show/hide `InputSuffixButton` in one. Other props go to the `<input>`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| size | "sm" \| "md" \| "lg" | - | Height 32, 36 or 40px. Unset, it comes from a container (`Form` imposes `lg`) or density (`compact`, the default, is `sm`; `comfortable` is `md`). |
| variant | "default" \| "inline" | "default" | As on `InputRoot`. |
| hasError | boolean | - | Destructive border and ring, and `aria-invalid` on the input. Inherited from a surrounding `Field` when unset. |
| density | "comfortable" \| "compact" | - | As on `InputRoot`. |
| rootClassName | string | - | Merged onto the wrapping `InputRoot`; `className` goes to the `<input>`. |

### NumberInput

A numeric field with steppers and arrow-key increments. Other props go to the `<input>`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| value | number \| null | - | Controlled value; `null` for empty. |
| defaultValue | number \| null | - | Initial value, uncontrolled. |
| onValueChange | (value: number \| null) => void | - | Called on every committed change with the parsed number, or `null` when cleared. |
| min | number | - | Lower clamp. |
| max | number | - | Upper clamp. |
| step | number | 1 | Applied by the steppers and arrow keys. |
| layout | "stacked" \| "inline" | "stacked" | `stacked` carets on the right, or `inline` minus and plus flanking the field. |
| size | "sm" \| "md" \| "lg" | - | Height 32, 36 or 40px. Unset, it comes from a container (`Form` imposes `lg`) or density (`compact`, the default, is `sm`; `comfortable` is `md`). |
| hasError | boolean | - | Destructive border and ring, and `aria-invalid` on the input. Inherited from a surrounding `Field` when unset. |
| static | boolean | - | Kept for compatibility; controls no longer scale on press. |
| rootClassName | string | - | Merged onto the wrapping `InputRoot`; `className` goes to the `<input>`. |

### PhoneInput

A country picker with dial code and a national-number field. Other props go to the `<input>`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| country | string | - | Controlled country, an ISO 3166-1 alpha-2 code. |
| defaultCountry | string | "US" | Initial country, uncontrolled. |
| onCountryChange | (iso2: string) => void | - | Called when another country is picked. |
| value | string | - | Controlled national number. |
| defaultValue | string | - | Initial national number, uncontrolled. |
| onValueChange | (nationalNumber: string) => void | - | Called with the national number as typed. |
| onChange | (payload: PhoneChangePayload) => void | - | Called on any change with `{ country, dialCode, nationalNumber, e164 }`. Store `e164`. |
| placeholder | string | "Phone number" | The field's placeholder. |
| size | "sm" \| "md" \| "lg" | - | Height 32, 36 or 40px. Unset, it comes from a container (`Form` imposes `lg`) or density (`compact`, the default, is `sm`; `comfortable` is `md`). |
| hasError | boolean | - | Destructive border and ring, and `aria-invalid` on the input. Inherited from a surrounding `Field` when unset. |
| rootClassName | string | - | Merged onto the wrapping `InputRoot`; `className` goes to the `<input>`. |

## 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` or `lg`). Unset, it follows the container (a `Form` imposes `lg`) or the density (`sm` under the default compact, `md` under comfortable). 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>
  )
}
```

## Anatomy

```tsx
import { InputGroup, InputGroupAddon } from "@/components/ui/input-group"
import { InputRoot, InputField } from "@/components/ui/input"

<InputGroup>
  <InputGroupAddon />
  <InputRoot>
    <InputField />
  </InputRoot>
</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. Make that row the `<form>` so the button takes the field's corner.

```tsx
<form className="flex items-stretch gap-2" onSubmit={(e) => e.preventDefault()}>
  <InputRoot className="flex-1">
    <InputPrefix>
      <Envelope />
    </InputPrefix>
    <InputField type="email" placeholder="Enter your email address" aria-label="Email address" />
  </InputRoot>
  <Button>Subscribe</Button>
</form>
```

## 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
<form className="flex items-stretch gap-2" onSubmit={(e) => e.preventDefault()}>
  <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>
</form>
```

## 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 and ring. 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, and imposes it on the inner controls. Give the detached Button the matching size so every part lines up.

```tsx
<form className="flex items-stretch gap-2" onSubmit={(e) => e.preventDefault()}>
  <InputGroup size="sm" className="flex-1">
    <Select defaultValue="member">{/* ... */}</Select>
    <InputRoot size="sm">{/* ... */}</InputRoot>
  </InputGroup>
  <Button size="sm">Invite</Button>
</form>

{/* 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

### InputGroup

The shell that joins several controls into one bordered row, `role="group"`. Renders a `<div>` and forwards all its props. Every part accepts `className`, merged last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| size | "sm" \| "md" \| "lg" | - | Shell height (32, 36 or 40px), imposed on every segment inside. Unset, it comes from a container (`Form` imposes `lg`) or density (`compact`, the default, is `sm`; `comfortable` is `md`). |
| density | "comfortable" \| "compact" | - | Only picks the default `size` (`compact` is `sm`, `comfortable` is `md`). An explicit `size` wins. |
| hasError | boolean | - | Destructive border and ring. Inherited from a surrounding `Field` when unset. |
| disabled | boolean | - | Dims and locks the shell. Inherited from a surrounding `Field`; also disable the inner control for form semantics. |

| Data attribute | Description |
| --- | --- |
| data-control-size | The resolved size: `sm`, `md` or `lg`. |
| data-disabled | Present when the group is disabled. |
| data-error | Present when the group is in the error state. |

### InputGroupAddon

A static affix segment (`https://`, `$`, `.com`, an icon) in the shell's muted ink. Renders a `<span>` and forwards all its props.

## 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 and ring. 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. The group imposes its size on every segment inside, so set it once on the group and give the detached Button the same size (e.g. size="lg"): no height overrides. Density never changes a control's height; it only sets the DEFAULT size when you don't pass one (compact, the default, -> sm; comfortable -> md). A bare Button stays md everywhere, so pass the same size to the group and the Button. 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Installation

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

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

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

Pro: `island` comes with a [Koala UI Pro license](https://www.koalaui.com/pro). Its source is not published in these docs.

## Usage

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

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.

## Anatomy

```tsx
import {
  Island,
  IslandView,
  IslandSwap,
  IslandButton,
  IslandIcon,
  IslandSeparator,
  IslandTitle,
  IslandProgress,
} from "@/components/ui/island"

<Island view="…">
  <IslandView value="…">
    <IslandButton />
    <IslandIcon />
    <IslandSeparator />
    <IslandSwap view="…">
      <IslandView value="…">
        <IslandTitle />
      </IslandView>
      <IslandView value="…">
        <IslandProgress />
      </IslandView>
    </IslandSwap>
  </IslandView>
</Island>
```

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## API reference

### Island

The morphing pill and the roving-focus root, `role="toolbar"`, over Radix `Toolbar.Root` (forwards `dir`, `loop` and the rest; `orientation` is fixed horizontal). Every part accepts `className`, merged last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| view | string | - | The `value` of the `IslandView` on screen. Unset, the children are simply the contents and the pill still eases when they resize. |
| variant | "floating" \| "solid" | "floating" | `floating` is the popover surface; `solid` inverts to the foreground ink. |
| size | "sm" \| "md" \| "lg" | "md" | Control height 32, 36 or 44px; the island's own axis, not the page density. |
| tooltipPlacement | TooltipProps["placement"] | "top" | Where every control's tooltip opens. |
| aria-label | string | "Island" | Names the toolbar for assistive tech. |

| Data attribute | Description |
| --- | --- |
| data-morph-ready | Present once the pill has measured, which arms its width, height and corner transition. |

| CSS variable | Description |
| --- | --- |
| --island-height | The measured height, written by the morph. The corner is half of it, capped at `--radius-4xl` once the island grows into a card. |

### IslandView

One state of the island. Mounted while on screen; while leaving it is out of flow, `inert` and hidden from assistive tech. A row by default; `flex-col` turns the pill into a card. Forwards native `<div>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| value* | string | - | The name the nearest `Island` or `IslandSwap` shows with `view={value}`. |

| Data attribute | Description |
| --- | --- |
| data-state | `enter` while the view blurs in, `exit` while it blurs out. |

### IslandSwap

A region inside a view that swaps on its own, with its own crossfade and morph. Declare its states as `IslandView` children. Forwards native `<div>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| view | string | - | The `IslandView` on screen inside this region. A value no child answers to collapses the region to nothing. |

| Data attribute | Description |
| --- | --- |
| data-morph-ready | Present once the region has measured. |

### IslandButton

A control: one glyph makes a circle, a word a pill. Over Radix `Toolbar.Button`; forwards its props, including `disabled` and `asChild`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| tooltip | React.ReactNode | - | Hover and focus hint. A string also becomes the `aria-label` when none is set. |
| shortcut | string | - | A keycap shown in the tooltip, e.g. `"L"`. Display only. |
| pressed | boolean | - | A toggle that is on: sets `aria-pressed` and lights the chip. |
| caret | boolean | false | A trailing caret that turns while its menu is open: the menu-trigger look. |

| Data attribute | Description |
| --- | --- |
| data-pressed | Present when `pressed`. |
| data-state | `open` while a menu it triggers is open (set by the menu trigger). |

### IslandIcon

A status glyph (a spinner, a check, a live dot) on a control's square, so it lines up with the buttons. Renders a `<span>`.

### IslandSeparator

A hairline between clusters of controls. Over Radix `Toolbar.Separator`.

### IslandTitle

What you are looking at, in one line that truncates before it stretches the pill. Renders a `<span>`.

### IslandProgress

A tabular readout and a thin `Progress` bar (a real `role="progressbar"`); the readout is hidden from assistive tech. Forwards native `<div>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| value* | number \| null | - | 0 to 100, or `null` for an unknown length: the readout goes and the bar sweeps. |
| transition | "smooth" \| "none" | "smooth" | The fill's easing. Use `none` when the value follows the scroll, or the bar trails the scrollbar. |
| aria-label | string | "Progress" | Names the bar. |

## 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>
```

## API reference

### Kbd

One key. Renders a native `<kbd>` and forwards all its props. Accepts `className`, merged last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| variant | "default" \| "soft" \| "outline" \| "solid" \| "ghost" | "default" | `default` is the flat gray chip; `soft` is an alias of it. `outline` is a hairline cap, `solid` an inverted one, `ghost` just the muted glyph. |
| size | "sm" \| "md" \| "lg" | "md" | Cap height: 20, 24 or 28px. |
| asChild | boolean | false | Renders the child element as the key (Radix Slot) instead of a `<kbd>`. |

## 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>
```

## API reference

### Label

The form label above a control. Renders a native `<label>` and forwards all its props. Every part accepts `className`, merged last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| required | boolean | - | Appends a destructive asterisk plus a screen-reader `(required)`. Inherited from a surrounding `Field` when unset. |
| disabled | boolean | - | Dims the label. Inherited from a surrounding `Field` when unset. |
| htmlFor | string | - | The control's `id`. Inside a `Field` it defaults to the field's control. |

### Hint

Helper or error text below a control. Renders a native `<p>`, forwards all its props, and registers with a surrounding `Field` for `aria-describedby`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| hasError | boolean | - | Switches to the destructive tone. Inherited from a surrounding `Field` or `FieldGroup` when unset. |

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Installation

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

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

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

Pro: `layout` comes with a [Koala UI Pro license](https://www.koalaui.com/pro). Its source is not published in these docs.

## Usage

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

`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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

```tsx
import {
  Layout,
  LayoutTopbar,
  LayoutBody,
  LayoutRail,
  LayoutSidebar,
  LayoutContent,
  LayoutHeader,
  LayoutSidebarTrigger,
  LayoutMobileBar,
  LayoutMobileSidebar,
  LayoutContainer,
  LayoutPane,
  LayoutPaneHeader,
  LayoutAside,
  PageHeader,
  PageHeaderContent,
  PageHeaderHeading,
  PageHeaderDescription,
  PageHeaderActions,
} from "@/components/ui/layout"

<Layout>
  <LayoutTopbar>…</LayoutTopbar>
  <LayoutBody>
    <LayoutRail>…</LayoutRail>
    <LayoutSidebar>…</LayoutSidebar>
    <LayoutContent>
      <LayoutMobileBar>
        <LayoutMobileSidebar>…</LayoutMobileSidebar>
      </LayoutMobileBar>
      <LayoutHeader>
        <LayoutSidebarTrigger />
      </LayoutHeader>
      <LayoutContainer>
        <PageHeader>
          <PageHeaderContent>
            <PageHeaderHeading />
            <PageHeaderDescription />
          </PageHeaderContent>
          <PageHeaderActions>…</PageHeaderActions>
        </PageHeader>
      </LayoutContainer>
      {/* or a list and detail row */}
      <LayoutPane>
        <LayoutPaneHeader />
      </LayoutPane>
    </LayoutContent>
    <LayoutAside>…</LayoutAside>
  </LayoutBody>
</Layout>
```

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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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).

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

### 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

### 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).

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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 ink while you drag.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

### 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

### 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

### 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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).

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## API reference

### Layout

The app shell root: owns the density and the rail's collapse state and shares them with every part. Forwards native `<div>` props. Every part accepts `className`, merged last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| variant | "docked" \| "plain" \| "flat" | "docked" | `docked` sets a sheet into a black frame; `plain` is one background and one hairline; `flat` is the docs and reading shell, where the window scrolls. |
| density | "comfortable" \| "compact" | - | Gutters, padding and bar heights. Inherits the nearest `DensityProvider` (compact with none). |
| collapsed | boolean | - | The rail's collapsed state, controlled. |
| defaultCollapsed | boolean | false | Start with the rail collapsed, uncontrolled. |
| onCollapsedChange | (collapsed: boolean) => void | - | Called whenever the rail collapses or expands, from any source. |
| collapseShortcut | boolean | true | Binds ⌘B (Ctrl+B) to toggle the rail; it stands down while typing. Turn off when a page mounts several shells. |

| Data attribute | Description |
| --- | --- |
| data-collapsed | Present while the rail is collapsed. |

### useLayoutSidebar

`const { collapsed, setCollapsed, toggle } = useLayoutSidebar()` reads and drives the rail from anywhere inside `Layout`.

### LayoutTopbar

The top band across the window; as the first child it turns the shell into a column. A `Navbar` inside docks onto it. Forwards native `<div>` props.

### LayoutBody

The row under a `LayoutTopbar` holding the rail and the sheet side by side. Forwards native `<div>` props.

### LayoutRail

The icon strip of a two-tier rail (Slack's workspaces, an IDE's activity bar); a `Sidebar` inside always renders as icons. Forwards native `<div>` props.

### LayoutSidebar

The sticky left column, hidden below `lg`. A `Sidebar` inside docks and follows the collapse with no props. Renders a `<div>`; the landmark comes from its content.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| collapsible | "icon" \| "offcanvas" | "icon" | What collapsing does: fold to the 48px icon column, or slide shut (the panel beside a `LayoutRail`). |

| Data attribute | Description |
| --- | --- |
| data-collapsed | Present while the shell is collapsed. |
| data-collapsible | `icon` or `offcanvas`. |

### LayoutSidebarTrigger

The ghost icon button that toggles the rail, with `aria-expanded`; desktop only. Put it first in the sheet's `LayoutHeader`. Forwards `<button>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| label | string | "Toggle sidebar" | The accessible name and tooltip. |

### LayoutContent

The sheet, a `<main>`; put two or more `LayoutPane`s inside for a list and detail row.

### LayoutHeader

Straight inside `LayoutContent`, the sheet's pinned bar, as tall as the rail's switcher row. Inside `LayoutContainer`, a row that scrolls with the column. Forwards native `<div>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| sticky | boolean | false | Inside a `LayoutContainer` only: pins the row with a translucent blurred fill. The sheet's bar is always pinned. |

### LayoutContainer

The centred column with responsive padding. Forwards native `<div>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| width | "narrow" \| "default" \| "wide" \| "full" | "default" | Max width: 768px for forms and reading, 1152px for dashboards, 1280px for dense tables, or none. |

### LayoutPane

A column of the sheet that scrolls on its own; every pane after the first draws the hairline. A `<section>`: give it an `aria-label`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| width | "sm" \| "md" \| "lg" \| "fill" | "fill" | 256, 320 or 384px, or `fill` to take the rest. Give one pane in the row `fill`. |

### LayoutPaneHeader

The sticky bar across a pane's top, one height per density so side-by-side bars share a line. Forwards native `<div>` props.

### LayoutAside

The right column for an on-this-page nav, hidden below `xl`. An `<aside>` landmark: put a `<nav>` inside. Pairs with `flat`.

### LayoutMobileBar

A slim sticky bar shown below `lg`, first in `LayoutContent`, holding the drawer trigger and a brand. Forwards native `<div>` props.

### LayoutMobileSidebar

A hamburger (hidden at `lg`) that opens the same rail in a left Drawer.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| children* | React.ReactNode | - | The rail, typically the DS `Sidebar`. |
| open | boolean | - | The drawer's open state, controlled. |
| defaultOpen | boolean | - | The drawer's initial state, uncontrolled. |
| onOpenChange | (open: boolean) => void | - | Called when the drawer opens or closes. |
| triggerLabel | string | "Open navigation" | The hamburger's accessible name. |
| title | string | "Navigation" | The drawer's visually hidden title. |
| triggerClassName | string | - | Merged onto the hamburger. |
| contentClassName | string | - | Merged onto the drawer panel. |

### PageHeader

The page title band: heading and text on the left, actions on the right. Forwards native `<div>` props.

### PageHeaderContent

The heading and description column. Forwards native `<div>` props.

### PageHeaderHeading

The page title, an `<h1>`.

### PageHeaderDescription

The supporting line, a `<p>`.

### PageHeaderActions

The trailing action cluster, pushed right at `sm`. Forwards native `<div>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| size | "sm" \| "md" \| "lg" \| "xl" | "md" | The height imposed on every control in the cluster, so a field sits level with the Button beside it. |

| Data attribute | Description |
| --- | --- |
| data-control-size | The imposed size. |

### SplitLayout

A second shell: the full-viewport auth and onboarding screen, two columns from `lg`. Which side the media sits on is DOM order. Forwards native `<div>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| ratio | "even" \| "start" \| "end" | "even" | 50/50, or 3:2 favouring the first or the last column. |
| density | "comfortable" \| "compact" | - | The panes' padding. Inherits the nearest `DensityProvider` (compact with none). |

### SplitPane

The content side, a padded column. Forwards native `<div>` props; own the landmark inside.

### SplitPaneBody

The centred column inside a `SplitPane`. Forwards native `<div>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| width | "sm" \| "md" \| "lg" | "sm" | Max width: 384, 448 or 512px. |

### SplitMedia

The full-bleed media side, hidden below `lg`; drop an `absolute inset-0 object-cover` image inside. Add `aria-hidden` when decorative. Forwards native `<div>` props.

### SplitMediaOverlay

A bottom-anchored scrim for a caption or testimonial, white on a dark gradient. Forwards native `<div>` props.

## 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, shifting tone 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. On hover default dims a step and muted lifts to full ink. `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 full ink.

```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, shifting tone 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>
  )
}
```

## API reference

### Link

A text link. Renders a native `<a>` and forwards all its props. Accepts `className`, merged last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| variant | "default" \| "muted" \| "prose" | "default" | `default` and `muted` are standalone links whose trailing icon slides in on hover; `prose` is the underlined link inside a sentence. |
| underline | boolean | false | Underlines a standalone link at rest. Not available on `prose`, which is always underlined. |
| asChild | boolean | false | Renders the child element (a Next.js `Link`, say) with the link styling, via Radix Slot. |

## 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 shift tone 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 recolors it, to full ink with a matching underline. 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?

Yes. The rest color is text-foreground (or text-muted-foreground, or inherited under prose) and the hover is a foreground shade, all semantic tokens, so it reads correctly in light, dark, cream, and moonlight. It does not follow the accent, which is for buttons and focus rings only. prose hovers to --link, the text color, so the underline marks the link rather than a hue.

---

<!-- 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Installation

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

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

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

Pro: `lightbox` comes with a [Koala UI Pro license](https://www.koalaui.com/pro). Its source is not published in these docs.

## Usage

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Anatomy

```tsx
import { Lightbox, LightboxTrigger } from "@/components/ui/lightbox"

<Lightbox images={…}>
  <LightboxTrigger index={0}>…</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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Stop at the ends

Paging loops by default: the next arrow on the last image goes back to the first. Set `loop` to `false` when the order means something and wrapping around would read as starting over, like the steps of a guide or one page of a paginated gallery. The arrow at each end disappears, and the `←` / `→` keys and a swipe go no further (the image resists the drag and springs back).

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Labels

Every word the viewer speaks or shows, from the dialog name a screen reader announces to the counter and the trigger pill, comes from `labels`. Pass the keys you want to change; the rest keep their English defaults. The indexed ones are functions that receive the 0-based index and the total, so you can phrase them however your language needs.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## API reference

### Lightbox

The root: holds the images and renders the viewer over Radix Dialog (focus trap, scroll lock, Esc). With more than one image, arrows, the arrow keys, the thumbnail rail and a swipe page between them, looping unless `loop={false}`. `LightboxTrigger` accepts `className`, merged last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| images* | LightboxImage[] | - | The photos, as `{ src: string; alt?: string }`. |
| open | boolean | - | Controlled open state. Omit for uncontrolled. |
| onOpenChange | (open: boolean) => void | - | Called when the viewer opens or closes. |
| defaultIndex | number | 0 | The image shown first, uncontrolled. |
| loop | boolean | true | Wraps paging around the ends. `false` stops at the first and last image: the end arrow disappears and keys and swipes go no further. |
| labels | Partial<LightboxLabels> | - | Translatable copy. `viewer`, `close`, `previous`, `next` and `trigger` are strings; `goToImage`, `imageOf` and `counter` are `(index, total) => string`. |
| children | React.ReactNode | - | The triggers. |

### LightboxTrigger

Opens the viewer at its `index`. Renders a `<button>` and forwards all its props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| index* | number | - | Position in the `images` array to open at. |
| label | React.ReactNode | "See image" | The pill shown on hover and focus. `null` hides it; ignored with `asChild`. |
| asChild | boolean | false | Makes the child (a `GalleryItem`, say) the trigger. It draws no pill and defers to the child's affordance. |

## 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 (set `loop={false}` to stop at the first and last image), and the photo crossfades as it changes. Arrows, the rail, and swipe only apply when there is more than one image.

### How do I translate the viewer?

Pass `labels` with the strings you want to change: `viewer`, `close`, `previous`, `next` and `trigger` are plain strings, and `goToImage`, `imageOf` and `counter` are functions of the 0-based index and the total. Missing keys keep their English defaults, and a trigger's own `label` still wins over `labels.trigger`.

### 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Installation

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

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

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

Pro: `list` comes with a [Koala UI Pro license](https://www.koalaui.com/pro). Its source is not published in these docs.

## Usage

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Anatomy

```tsx
import {
  List,
  ListItem,
  ListItemMedia,
  ListItemContent,
  ListItemTitle,
  ListItemDescription,
  ListItemMeta,
} from "@/components/ui/list"

<List>
  <ListItem>
    <ListItemMedia />
    <ListItemContent>
      <ListItemTitle />
      <ListItemDescription />
    </ListItemContent>
    <ListItemMeta />
  </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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Bleed

On a `plain` list an interactive row bleeds its fill 8px past the text column (`-mx-2`, a row 1rem wider, 2px between pills), so the text stays on the column and the fill gets air: the menu look, and the default. Inside a Card's padding, or where each row is a card of its own, that bleed lands on the frame. Pass`bleed=` on the List: the row stays in the list's box, keeps its 8px inner padding, adds no gap of its own, and the spacing between rows is the container's (`gap-*` on the List).

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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 an ink 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. When the selection moves with the keyboard, see [Keyboard selection](#keyboard-selection).

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Keyboard selection

The bar is right when the current row is one landmark in a list people point at. When the selection IS the cursor, moved by arrow keys or a game binding while focus stays on the container, a full fill and a 3px bar sit too close to a hover. Pass`currentStyle="ring"` on the List: the current row takes the brand, a channel a hover never uses, as a faint brand wash and a 1px inset brand ring that follows the row's radius. Keep `"bar"` (the default) for pointer-driven lists and navigation; use `"ring"` wherever a key moves the selection.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## API reference

### List

The root. Renders a `<ul>` and forwards all its props. Every part accepts `className`, merged last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| variant | "card" \| "plain" | "card" | `card` bands the rows in a ringed surface; `plain` sits them flush on the ground. |
| divided | boolean | true | A hairline rule between rows. |
| bleed | boolean | true | `plain` only. Interactive rows bleed their fill 8px past the text column; `false` keeps them in the list's box, for rows in a Card or rows as cards. |
| currentStyle | "bar" \| "ring" | "bar" | How the `current` row is marked. `ring` suits a keyboard-driven selection. |
| asChild | boolean | false | Renders the child (an `<ol>`, say) as the root via Radix Slot. |

### ListItem

One row. Renders an `<li>` and forwards all its props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| asChild | boolean | false | Hands the row surface to a single `<a>` or `<button>` child while the `<li>` keeps the divider. Implies `interactive`. |
| interactive | boolean | - | Hover, press and focus affordance. Defaults to `asChild`. On a `plain` list the fill is a band as wide as the rules; with `divided={false}` it rounds into a pill. |
| current | boolean \| "page" \| "step" \| "location" \| "date" \| "time" | - | The row the screen is showing: a full fill, an ink bar, and `aria-current` on the row surface. |

### ListItemMedia

Leading media: a bare icon, an Avatar or a small image. Forwards native `<div>` props.

### ListItemContent

The text column holding title and description. Forwards native `<div>` props.

### ListItemTitle

The primary line. Forwards native `<div>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| lines | 1 \| 2 \| 3 \| "none" | 1 | Lines before the ellipsis, so a long title never pushes the meta off the row. `none` wraps in full. |

### ListItemDescription

The muted secondary line. Forwards native `<div>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| lines | 1 \| 2 \| 3 \| "none" | "none" | Wraps in full by default; `1` truncates, `2` or `3` clamp. |

### ListItemMeta

The trailing slot: badges, a timestamp, a chevron or a control. 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 an ink 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Installation

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

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

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

Pro: `load-more` comes with a [Koala UI Pro license](https://www.koalaui.com/pro). Its source is not published in these docs.

## Usage

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Anatomy

```tsx
import { LoadMore, LoadMoreContent, LoadMoreTrigger } from "@/components/ui/load-more"

<LoadMore>
  <LoadMoreContent>…</LoadMoreContent>
  <LoadMoreTrigger more="…" 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`.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## API reference

### LoadMore

The root that owns the expanded state (uncontrolled). Renders a `<div>` and forwards all its props. Every part accepts `className`, merged last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| collapsedHeight | string | "28rem" | The clamp, any CSS length. Pick one that cuts through a row, so the fade reads as more below. |
| defaultExpanded | boolean | false | Start revealed. |
| onExpandedChange | (expanded: boolean) => void | - | Called after each toggle. |
| align | "center" \| "start" \| "end" | "center" | Where the trigger sits under the region. |

### LoadMoreContent

The clamped region; put the long grid or list straight inside. Forwards native `<div>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| fade | boolean | true | Dissolves the cut edge while collapsed. Skipped when the content already fits. |

| Data attribute | Description |
| --- | --- |
| data-expanded | Present while the region is revealed. |

| CSS variable | Description |
| --- | --- |
| --fade-size | Depth of the dissolve, `min(16rem, 40%)` here. Override per instance, e.g. `[--fade-size:6rem]`. |

### LoadMoreTrigger

The one reveal button, with a caret that turns toward where the region moves. Forwards `Button` props (`children` aside) and wires `aria-expanded` and `aria-controls`. Renders nothing when the content fits.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| more* | React.ReactNode | - | Label while collapsed. Name what is below, e.g. "See all components". |
| less* | React.ReactNode | - | Label while expanded, e.g. "Show less". |
| variant | ButtonProps["variant"] | "outline" | Defaults to `secondary`, the solid chip, under an `onMedia` or `onInverse` tone. |

## 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/map.md -->

# Map

An interactive vector map that wears your theme. OpenStreetMap tiles with no key, painted from the theme's own tokens, re-painted in place when the theme changes, with pins, controls and the full MapLibre instance when you need it.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Installation

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

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

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

Pro: `map` comes with a [Koala UI Pro license](https://www.koalaui.com/pro). Its source is not published in these docs.

## Usage

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

Give the map a height: it fills its box. MapLibre loads on the client after the first paint, so the frame shows the theme's land colour until the tiles fade in, and nothing renders on the server.

## Anatomy

```tsx
import { Map, MapMarker, MapPin, MapControls, MapCorner } from "@/components/ui/map"

<Map>
  <MapMarker lngLat={…}>
    <MapPin />
  </MapMarker>
  <MapControls />
  <MapCorner>…</MapCorner>
</Map>
```

## Theming

The basemap is painted from the `--map-*` tokens, which mix the theme's own `--background`, `--foreground`, `--info` and `--success`. Light grounds get grey land under white streets; dark grounds flip it, with streets that brighten with their rank. Switch the theme and the map re-paints in place, without reloading tiles or touching your own layers. Re-tint one map with a utility, such as `[--map-water:var(--purple)]`.

`labels={false}` and `buildings={false}` quieten it further, for a backdrop under your own data.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Pins

`MapMarker` pins any React content to a coordinate and keeps it in your tree, so Context, state and events work as usual. `MapPin` is the canonical marker to put in it: a chip on the popover surface with the tone as a leading dot, or the dot alone without a `label` (name it with `aria-label`). It is a button only when it has something to do, an `onClick` or a Popover around it, so a pin that only marks a place stays out of the tab order. `selected` inverts it to ink.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Prices

`variant="price"` turns the pin into the chip a map of stays or listings wears: the figure alone, bolder and in tabular figures, so a dozen of them read as numbers to compare. Open one and it inverts to ink; `visited` greys the ones already seen, so the eye moves on. The hovered, focused or selected pin rises above its neighbours, so a crowded cluster never buries the one you are looking at. Format the price yourself, with `Intl.NumberFormat`, and name the pin with the place and the price.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Emoji

`variant="emoji"` marks a place by what it is instead of by a status: a café, a beach, a museum, for a map of things to do or a neighbourhood guide. The `emoji` takes the dot's place; beside a `label` it sits in its own circle, concentric with the chip, and without one it is the pin on its own (name it with `aria-label`). `labelMinZoom` sets the zoom a label shows from: further out the pin is its emoji alone and the name opens on hover and on focus. Give every pin the same zoom and the whole map changes detail at once: zoom in to read the names. The emoji is decorative: the label names the pin. `selected` and `visited` work as on every pin.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Symbols

A dispatch, fleet or incident map marks things by what they are and how urgent, not by a name on a chip. Give `MapPin` an `icon`, a sprite `src` or a `shape` and it becomes a symbol: a `circle` with a category icon, a `square` for a fixed asset, a `diamond` for a numbered priority, a `dot` for a moving unit, a `cross` for a unit of another service. Fill it with a `tone`, or with any CSS `color` straight from your data: the icon's ink is picked by contrast (set `ink` to decide it yourself).

`halo` draws a still ring (`glow`, `ring` or `dashed`, for a unit in the air), `pulse="ping"` a slow live halo for units on duty and `pulse="alert"` a fast, strong one for a panic. `caption` puts a callsign beside the symbol or a title under it. `label` names the symbol for assistive tech, and `selected` grows it and rings it in ink. Click the symbols.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

Three sizes: `sm` 22, `md` 28 and `lg` 36px for a shape that holds an icon, 12, 16 and 20px for a dot or a cross. Pass a sprite as `src` (a vehicle silhouette) and it takes the icon's place. The symbol's box is the shape alone, so MapMarker's default `center` anchor lands on its middle; the halo, the pulse and the caption spill over it. The pulses animate `transform` and `opacity` only and hold still under reduced motion, as a faint ring.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Your own layers

`useMap()` hands any child the MapLibre instance. Add sources and layers once `loaded` is true and remove them on cleanup. MapLibre reads neither `oklch()` nor `color-mix()`, so `useMapColor` resolves a token to an rgb value it can paint, and resolves it again when the theme changes: set it in an effect and your route re-paints with the basemap. Switch the theme to see it. `MapCorner` floats your own parts, such as this ETA, in a corner, inset like the controls.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Controls

`MapControls` is a floating vertical Toolbar: zoom, a compass that turns with the map and resets north and tilt, and `locate`, which asks for the visitor's position and flies there. `position` picks the corner; the tooltips open on the side away from the edge. This map starts rotated, so the compass is turned.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Any style

`mapStyle` swaps the basemap for any MapLibre style, by URL or as an object: a provider's satellite tiles, your own design from Maputnik. The theming steps aside; pins, controls and `useMap` work the same.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## API reference

### Map

A labelled `role="region"` that hosts a MapLibre map; it fills its box, so give it a height. Forwards native `<div>` props. Every part accepts `className`, merged last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| center | [number, number] | [-73.9855, 40.758] | Where the camera starts, `[longitude, latitude]`. Seeds the map once. |
| zoom | number | 12 | Starting zoom. Seeds the map once. |
| bearing | number | 0 | Starting rotation in degrees. |
| pitch | number | 0 | Starting tilt in degrees. |
| minZoom | number | - | The furthest the camera zooms out. |
| maxZoom | number | - | The closest the camera zooms in. |
| maxBounds | [[number, number], [number, number]] | - | Keeps the camera inside `[[west, south], [east, north]]`. |
| interactive | boolean | true | Pan, zoom and rotate with pointer and keyboard. |
| cooperativeGestures | boolean | false | Scroll and one-finger drag pass to the page; zoom takes Ctrl or ⌘ plus scroll. For a map in a scrolling page. |
| frame | "rounded" \| "flush" | "rounded" | `rounded` frames the map with a hairline; `flush` is for a map that is the page. |
| labels | boolean | true | Street, water and place names on the Koala basemap. |
| buildings | boolean | true | Building footprints from zoom 14. |
| mapStyle | string \| StyleSpecification | - | Any MapLibre style, a URL or an object, in place of the Koala basemap. Theming steps aside. |
| label | string | "Map" | The region's accessible name. |
| options | Partial<MapOptions> | - | Any other MapLibre option, passed at creation (`container` and `style` aside). |
| workerUrl | string | - | Where MapLibre's worker loads from. Defaults to jsDelivr at the installed version; self-host it for a strict CSP. |
| onLoad | (map: MapLibreMap) => void | - | The style has loaded: add your sources and layers here. |
| onMoveEnd | (view: MapView) => void | - | The camera came to rest, with `{ center, zoom, bearing, pitch }`. |
| onMapClick | (lngLat: [number, number], map: MapLibreMap) => void | - | A click on the map itself, not on a marker. |

| CSS variable | Description |
| --- | --- |
| --map-* | The basemap palette (`land`, `water`, `park`, `road`, `label` and the rest), mixed from the theme. Re-tint one map with a utility, e.g. `[--map-water:var(--purple)]`. |

### MapMarker

Pins any React content to a coordinate; the content stays in your tree and is portalled into the marker. Forwards native `<div>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| lngLat* | [number, number] | - | Where the marker sits. Updating it moves the marker. |
| anchor | PositionAnchor | "center" | Which point of the content touches the coordinate. |
| offset | [number, number] | - | Nudge in pixels, `[x, y]`. |
| flat | boolean | true | Keeps the marker upright and flat while the map pitches and rotates. |
| children* | React.ReactNode | - | The marker's content: a `MapPin`, an Avatar, a Popover trigger. |

### MapPin

The marker visual. A `<button>` when given `onClick` (forwards its props), otherwise a `<span>` that stays out of the tab order.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| label | React.ReactNode | - | The words on the chip. Without one the pin is the dot alone: name it with `aria-label`. |
| variant | "default" \| "price" \| "emoji" | "default" | `default` leads with the tone dot; `price` is the figure alone, bolder; `emoji` leads with `emoji`. |
| emoji | string | - | The mark the `emoji` variant shows, e.g. `"☕"`. Decorative. |
| tone | "brand" \| "neutral" \| "info" \| "success" \| "warning" \| "destructive" \| "purple" \| "teal" | "neutral" | The dot's colour, so `price` and `emoji` have none. |
| labelMinZoom | number | - | The zoom the label shows from. Below it the pin is its mark alone, opening on hover and focus. Not for `price`. |
| selected | boolean | - | The chosen pin: the chip inverts to ink and sets `aria-pressed`. |
| visited | boolean | - | A place already looked at: the chip greys to the muted step. |
| color | string | - | Any CSS colour for the dot (or the symbol), winning over `tone`. |
| icon | React.ReactNode | - | Turns the pin into a symbol: a shape holding this glyph (a dispatch blip, a fleet unit, an incident). Decorative. |
| src | string | - | Symbol: a sprite image in place of the icon. |
| shape | "circle" \| "square" \| "diamond" \| "dot" \| "cross" | "circle" | Symbol: the marker's shape. |
| size | "sm" \| "md" \| "lg" | "md" | Symbol: 22, 28 or 36px for a shape holding an icon; 12, 16 or 20px for a dot or a cross. |
| ink | string | - | Symbol: the icon's colour. Unset, it is picked by contrast (`pinInk(color)` returns the same pick). |
| halo | boolean \| "glow" \| "ring" \| "dashed" | - | Symbol: a still ring or glow around the shape (`true` is `glow`). |
| pulse | "ping" \| "alert" | - | Symbol: a live halo that grows out and fades; `alert` doubles it. Still under reduced motion. |
| caption | React.ReactNode | - | Symbol: words beside or under the shape (a callsign, an incident's title). |
| captionSide | "right" \| "bottom" | "right" | Symbol: where the caption sits. |

| Data attribute | Description |
| --- | --- |
| data-selected | Present when `selected`. |
| data-visited | Present when `visited`. |
| data-collapsed | Present while the label is folded below `labelMinZoom`. |

### MapControls

Zoom, a compass that turns with the map, and an optional locate, as a floating vertical Toolbar with tooltips. Forwards native `<div>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| position | "top-left" \| "top-right" \| "bottom-left" \| "bottom-right" | "top-right" | The corner of the map it floats in. |
| zoom | boolean | true | Zoom in and out buttons. |
| compass | boolean | true | Turns with the map; resets north and tilt. |
| locate | boolean | false | Fly to the visitor's position (asks for permission). |
| locateZoom | number | 14 | Where to land after locating. |
| onLocate | (result: GeolocationPosition \| GeolocationPositionError) => void | - | Called with the position found, or the error. |

### MapCorner

A slot floating in a corner of the map, for your own legend or buttons. Forwards native `<div>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| position | "top-left" \| "top-right" \| "bottom-left" \| "bottom-right" | "top-right" | The corner of the map it floats in. |

### useMap

Returns `{ map, lib, loaded }`: the MapLibre instance (null on the server and the first frames), the MapLibre module for `new lib.Popup()`, and whether the style has loaded. Use inside `Map`.

### useMapColor

`useMapColor(color)` resolves a CSS colour (`"var(--brand)"`) for a paint property and updates when the theme changes. `readColor(element, color)` does it once, outside React.

## FAQ

### Do I need an API key?

No. The default basemap uses OpenFreeMap's OpenStreetMap vector tiles, which are free and keyless. Keep the attribution: it is what the data licence asks for. For heavy production traffic, point mapStyle at your own tiles or a paid provider.

### Where does MapLibre's worker come from?

MapLibre 6 ships its web worker as separate files that bundlers like Next.js do not carry along, so by default the map loads them from jsDelivr, pinned to the exact MapLibre version you have installed. For a strict Content Security Policy or an offline network, serve maplibre-gl-worker.mjs and maplibre-gl-shared.mjs from node_modules/maplibre-gl/dist yourself and pass the worker's URL as workerUrl.

### Why does the map not render on the server?

MapLibre draws with WebGL, which only exists in the browser. The component imports it on the client after the first paint, and until then the frame shows the theme's land colour, so there is no white flash and no layout shift.

### How do I move the camera from my own code?

Take the instance from useMap() and call flyTo, easeTo or fitBounds. The center and zoom props only seed the map, so a re-render never yanks the camera back.

### Can the map stop hijacking the page scroll?

Pass cooperativeGestures. Scrolling and one-finger drags then pass through to the page; zooming takes Ctrl or ⌘ plus scroll, and panning takes two fingers. Every map on this page uses it.

### Do the symbols work in an older embedded browser?

Yes. They are built for engines as old as Chromium 103, the kind a game overlay or a kiosk ships: the pulses animate a raw transform and opacity (no standalone scale property), the halo fades the colour with opacity rather than color-mix, and the ink for a free colour is picked in JavaScript because contrast-color() and relative colours do not exist there. Hex and rgb() colours are read; for anything else, a var() or a named colour, the ink is white unless you pass ink.

### Is it accessible?

The map is a labelled region, its canvas is focusable with arrow keys to pan and plus or minus to zoom, the controls are a labelled toolbar with tooltips, and interactive pins are real buttons. Put anything the reader must not miss in a list beside the map as well.

---

<!-- 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>
  )
}
```

## Anatomy

```tsx
import {
  Menubar,
  MenubarMenu,
  MenubarTrigger,
  MenubarContent,
  MenubarItem,
  MenubarCheckboxItem,
  MenubarRadioGroup,
  MenubarRadioItem,
  MenubarLabel,
  MenubarSeparator,
  MenubarShortcut,
  MenubarSub,
  MenubarSubTrigger,
  MenubarSubContent,
} from "@/components/ui/menubar"

<Menubar>
  <MenubarMenu>
    <MenubarTrigger />
    <MenubarContent>
      <MenubarLabel />
      <MenubarItem>
        <MenubarShortcut />
      </MenubarItem>
      <MenubarCheckboxItem />
      <MenubarRadioGroup>
        <MenubarRadioItem />
      </MenubarRadioGroup>
      <MenubarSeparator />
      <MenubarSub>
        <MenubarSubTrigger />
        <MenubarSubContent>…</MenubarSubContent>
      </MenubarSub>
    </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 ink 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 bar, `role="menubar"`, over Radix `Menubar.Root`, and forwards its props. Every part accepts `className`, merged last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| variant | "outline" \| "plain" | "outline" | `outline` is the concentric band with an inset edge; `plain` drops it for a header that owns one. |
| value | string | - | The open menu's value, controlled. |
| defaultValue | string | - | The menu open on first render, uncontrolled. |
| onValueChange | (value: string) => void | - | Called when a menu opens or closes (an empty string when none is open). |
| loop | boolean | true | Arrow keys wrap from the last trigger to the first. |
| dir | "ltr" \| "rtl" | - | Reading direction for arrow-key navigation. |

### MenubarMenu

One menu: wraps its trigger and content. Radix `Menubar.Menu`, re-exported as is.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| value | string | - | Identifies the menu for the bar's `value`. Generated when omitted. |

### MenubarTrigger

The button that opens its menu; it lights while the menu is open. Forwards Radix `Menubar.Trigger` props.

| Data attribute | Description |
| --- | --- |
| data-state | `open` while its menu is open, otherwise `closed`. |
| data-highlighted | Present while the trigger has keyboard focus. |
| data-disabled | Present when `disabled`. |

### MenubarContent

The menu panel, portalled to the body and built from Dropdown Menu's recipe. Forwards Radix `Menubar.Content` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| align | "start" \| "center" \| "end" | "start" | Alignment against the trigger. |
| alignOffset | number | -2 | Puts the rows' text on the trigger's text line. |
| sideOffset | number | 8 | Gap from the trigger, clearing the band's padding. |
| collisionPadding | number | 8 | Keeps the panel off the viewport edge. |
| density | "comfortable" \| "compact" | - | Row height (36 or 32px). Inherits the nearest `DensityProvider` when unset. |

| Data attribute | Description |
| --- | --- |
| data-state | `open` or `closed`, for the enter and exit animation. |
| data-side | The side the panel landed on after collision handling. |
| data-align | The resolved alignment. |

| CSS variable | Description |
| --- | --- |
| --radix-menubar-content-transform-origin | The point the panel scales from, set by Radix. |
| --radix-menubar-content-available-height | Room between the trigger and the viewport edge. |

### MenubarItem

A command row. Forwards Radix `Menubar.Item` props (`onSelect`, `disabled`, `textValue`).

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| variant | "default" \| "destructive" | "default" | `destructive` turns the whole row red, icon included. |
| inset | boolean | false | Indents the text to line up with icon-bearing rows. |
| density | "comfortable" \| "compact" | - | Row height (36 or 32px). Inherits the nearest `DensityProvider` when unset. |

| Data attribute | Description |
| --- | --- |
| data-highlighted | Present while the row is highlighted by pointer or keyboard. |
| data-disabled | Present when `disabled`. |
| data-inset | Present when `inset`. |

### MenubarCheckboxItem

A toggle row. Forwards Radix `Menubar.CheckboxItem` props (`checked`, `onCheckedChange`).

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| variant | "check" \| "switch" | "check" | `check` is the ink check; `switch` is a mini Switch, for a setting that applies the moment it flips. |
| closeOnSelect | boolean | - | Closes the menu on toggle. Defaults to `true` for `check` and `false` for `switch`. |
| density | "comfortable" \| "compact" | - | Row height (36 or 32px). Inherits the nearest `DensityProvider` when unset. |

| Data attribute | Description |
| --- | --- |
| data-state | `checked`, `unchecked` or `indeterminate`. |
| data-highlighted | Present while the row is highlighted. |
| data-disabled | Present when `disabled`. |

### MenubarRadioGroup

Groups radio rows. Radix `Menubar.RadioGroup`, re-exported as is.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| value | string | - | The checked row's value. |
| onValueChange | (value: string) => void | - | Called when another row is picked. |

### MenubarRadioItem

One exclusive choice inside a `MenubarRadioGroup`, sharing the checkbox row's ink check. Forwards Radix `Menubar.RadioItem` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| value* | string | - | The value the group reports. |
| density | "comfortable" \| "compact" | - | Row height (36 or 32px). Inherits the nearest `DensityProvider` when unset. |

| Data attribute | Description |
| --- | --- |
| data-state | `checked` or `unchecked`. |
| data-highlighted | Present while the row is highlighted. |

### MenubarLabel

A non-interactive heading over a run of rows. Forwards Radix `Menubar.Label` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| inset | boolean | false | Indents the text to line up with icon-bearing rows. |
| density | "comfortable" \| "compact" | - | Row height (36 or 32px). Inherits the nearest `DensityProvider` when unset. |

### MenubarSeparator

A hairline between groups of rows. Forwards Radix `Menubar.Separator` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| density | "comfortable" \| "compact" | - | Row height (36 or 32px). Inherits the nearest `DensityProvider` when unset. |

### MenubarShortcut

The row's shortcut, a small `Kbd` chip on the right edge. Display only: bind the keys yourself. Forwards `Kbd` props.

### MenubarGroup

Groups related rows for assistive tech. Radix `Menubar.Group`, re-exported as is.

### MenubarSub

A nested menu: wraps a sub-trigger and its panel. Radix `Menubar.Sub`, re-exported as is.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| open | boolean | - | Controlled open state. |
| defaultOpen | boolean | - | Open on first render, uncontrolled. |
| onOpenChange | (open: boolean) => void | - | Called when the submenu opens or closes. |

### MenubarSubTrigger

The row that opens a submenu, with a trailing caret. Forwards Radix `Menubar.SubTrigger` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| inset | boolean | false | Indents the text to line up with icon-bearing rows. |
| density | "comfortable" \| "compact" | - | Row height (36 or 32px). Inherits the nearest `DensityProvider` when unset. |

| Data attribute | Description |
| --- | --- |
| data-state | `open` while its submenu is open, otherwise `closed`. |
| data-highlighted | Present while the row is highlighted. |

### MenubarSubContent

The submenu panel, portalled to the body. Forwards Radix `Menubar.SubContent` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| density | "comfortable" \| "compact" | - | Row height (36 or 32px). Inherits the nearest `DensityProvider` when unset. |

| Data attribute | Description |
| --- | --- |
| data-state | `open` or `closed`. |
| data-side | The side the panel landed on. |

### MenubarPortal

Radix `Menubar.Portal`, re-exported for custom panels. `MenubarContent` and `MenubarSubContent` already portal themselves.

## 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/meter.md -->

# Meter

A reading inside a known range: storage used, a plan's quota, a battery. It shares Progress's bar, and adds role="meter", locale-aware formatting and thresholds that recolour the fill.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Installation

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

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

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

Pro: `meter` comes with a [Koala UI Pro license](https://www.koalaui.com/pro). Its source is not published in these docs.

## Usage

Pass `value`, and `min` and `max` when the range is not 0 to 100. A bare `<Meter />` renders just the bar; give it an `aria-label`.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Anatomy

```tsx
import {
  Meter,
  MeterLabel,
  MeterValue,
  MeterTrack,
  MeterIndicator,
} from "@/components/ui/meter"

<Meter>
  <MeterLabel />
  <MeterValue />
  <MeterTrack>
    <MeterIndicator />
  </MeterTrack>
</Meter>
```

## Meter vs Progress

[Progress](https://www.koalaui.com/docs/components/progress.md) reports how far a task has got: an upload, an import. It only moves forward and it ends. A meter reports how much of something there is: disk used, seats taken, charge left. It can go down as well as up, and nothing is ever finished. Screen readers hear the difference (`role="progressbar"` against `role="meter"`), so pick by meaning, not by look. The two share one bar, so they always sit together cleanly.

## Plan usage

Quotas in a card. Each meter turns `warning` past 75% and `destructive` past 90%, and `MeterValue` phrases the limit next to the reading.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Thresholds

`low`, `high` and `optimum` work as on the HTML `<meter>`. They split the range into an optimal, a suboptimal and a critical region, and the fill takes `success`, `warning` and `destructive`. Put `optimum` at 0 when lower is better (a disk), at the top when higher is better (a battery). The root carries the region as `data-level`.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Formatted values

`format` takes `Intl.NumberFormat` options and drives both the readout and `aria-valuetext`. Without it, the reading is a whole percentage of the range; a `percent` style reads the share of the range too. The visitor’s locale applies after hydration, so the server render never disagrees with the browser. Pass `locale` to fix one.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Live readings

The fill glides between readings on the motion tokens, and the readout uses tabular figures so it never jitters as the number changes.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Sizes

The Progress height scale: `xs` (4px), `sm` (the default), `md` and `lg`.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Tones

For a reading with no good or bad side, pin the colour with `tone`. It wins over the thresholds.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Accessibility

The root is `role="meter"` with `aria-valuenow`, `aria-valuemin`, `aria-valuemax` and an `aria-valuetext` built from `format`. A composed `MeterLabel` names it; otherwise pass `aria-label`. `MeterValue` is hidden from assistive tech so the reading is not announced twice. Colour is never the only signal: keep the value visible when a threshold matters.

## API reference

### Meter

The root. Renders a `<div role="meter">` laid out as a two column grid: label left, value right, track across both. With no children it renders a bare track. Forwards all native `<div>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| value* | number | - | The reading. Clamped to `min` and `max` for display and for `aria-valuenow`. |
| min | number | 0 | Lower bound of the range. |
| max | number | 100 | Upper bound of the range. |
| low | number | min | Upper bound of the low region. |
| high | number | max | Lower bound of the high region. |
| optimum | number | midpoint | The ideal reading. Decides which region is optimal, as on the HTML `<meter>`. |
| format | Intl.NumberFormatOptions | - | Formats the readout and `aria-valuetext`. Without it, a whole percentage of the range. A `percent` style also reads the share of the range. |
| locale | Intl.LocalesArgument | - | Locale for the readout. Defaults to the visitor's, applied after hydration (`en-US` on the server). |
| getAriaValueText | (formattedValue: string, value: number) => string | - | Phrase the screen reader text yourself. An explicit `aria-valuetext` still wins. |
| size | "xs" \| "sm" \| "md" \| "lg" | "sm" | Bar height: 4, 6, 8 or 12px. The Progress scale. |
| tone | "brand" \| "foreground" \| "success" \| "warning" \| "destructive" \| "info" | - | Pins the indicator colour. Without it the thresholds pick one, or `foreground` when there are none. |

| Data attribute | Description |
| --- | --- |
| data-level | `"optimal"`, `"suboptimal"` or `"critical"`. Only set when `low`, `high` or `optimum` is passed. |

### MeterLabel

The visible name. When composed in, it also becomes the meter's accessible name through `aria-labelledby`. Forwards all native `<span>` props.

### MeterValue

The readout, in tabular figures and `aria-hidden` (the root already carries it as `aria-valuetext`). Forwards all native `<span>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| children | (formattedValue: string, value: number) => ReactNode | - | Phrase the readout yourself: "45.2 GB of 100 GB". Defaults to the formatted value. |

### MeterTrack

The groove, Progress's track slot. Spans both grid columns. Forwards all native `<div>` props.

### MeterIndicator

The fill, Progress's indicator slot. Its width is the reading's share of the range and it glides on change. Forwards all native `<div>` props.

| Data attribute | Description |
| --- | --- |
| data-level | Mirrors the root's level, when thresholds are set. |

## FAQ

### Should I use Meter or Progress?

Progress for a task moving toward done, Meter for a measurement within a range. If the value can go down, or the bar never finishes, it is a Meter.

### Why does my reading show 72 % instead of 72%?

The readout follows the visitor's locale, and some locales space the percent sign. Pass locale="en-US" (or any locale) to fix the format for everyone.

### Are low and high in percent?

No. They are in the same units as value, min and max. On a 0 to 512 MB meter, a warning at 60% is low={307}.

### Can I style the regions myself?

Yes. The root and the indicator carry data-level (optimal, suboptimal, critical), so a className like data-[level=critical]:bg-… on MeterIndicator restyles one region.

---

<!-- 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Installation

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

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

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

Pro: `multi-select` comes with a [Koala UI Pro license](https://www.koalaui.com/pro). Its source is not published in these docs.

## Usage

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Anatomy

```tsx
import {
  MultiSelect,
  MultiSelectTrigger,
  MultiSelectValue,
  MultiSelectContent,
  MultiSelectGroup,
  MultiSelectLabel,
  MultiSelectItem,
  MultiSelectSwitchItem,
  MultiSelectSeparator,
} from "@/components/ui/multi-select"

<MultiSelect>
  <MultiSelectTrigger>
    <MultiSelectValue />
  </MultiSelectTrigger>
  <MultiSelectContent>
    <MultiSelectGroup>
      <MultiSelectLabel />
      <MultiSelectItem value="…" />
      <MultiSelectSwitchItem value="…" />
    </MultiSelectGroup>
    <MultiSelectSeparator />
  </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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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`.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## API reference

### MultiSelect

The root that owns the `string[]` selection, over Radix `Popover.Root` (forwards `open`, `defaultOpen`, `onOpenChange`, `modal`). Every part accepts `className`, merged last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| value | string[] | - | The selection, controlled. |
| defaultValue | string[] | [] | The initial selection, uncontrolled. |
| onValueChange | (value: string[]) => void | - | Called with the full next array whenever a row is toggled. |
| size | "sm" \| "md" \| "lg" | - | Trigger height 32, 36 or 40px. Unset, it comes from a container (`Form` imposes `lg`) or density (`compact`, the default, is `sm`). |
| density | "comfortable" \| "compact" | - | Row padding in the panel, and the default `size`. Inherits the nearest `DensityProvider` when unset. |

### MultiSelectTrigger

The field-shaped button with a trailing caret. Forwards Radix `Popover.Trigger` props.

| Data attribute | Description |
| --- | --- |
| data-state | `open` or `closed`. |

### MultiSelectValue

The trigger's text: the placeholder, or a rolling count like `3 selected`. Forwards native `<span>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| placeholder | string | - | Shown when nothing is selected. |
| renderValue | (value: string[]) => React.ReactNode | - | Draws the selection yourself, e.g. Badge chips mapped from your own labels. |

### MultiSelectContent

The panel, `role="listbox"` with `aria-multiselectable`, portalled to the body; arrow keys, Home and End move between rows. Forwards Radix `Popover.Content` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| align | "start" \| "center" \| "end" | "start" | Alignment against the trigger. |
| sideOffset | number | 6 | Gap from the trigger. |
| collisionPadding | number | 8 | Keeps the panel off the viewport edge. |

| Data attribute | Description |
| --- | --- |
| data-state | `open` or `closed`, for the enter and exit animation. |
| data-side | The side the panel landed on. |

| CSS variable | Description |
| --- | --- |
| --radix-popover-trigger-width | The panel's minimum width, so it never runs narrower than the trigger. |
| --radix-popover-content-available-height | Caps the scrolling list at the room left in the viewport (20rem at most). |

### MultiSelectItem

A row, `role="option"`, with the label first and a decorative Checkbox on the right; Enter or Space toggles it. Forwards native `<div>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| value* | string | - | The value this row adds to or removes from the selection. |
| disabled | boolean | - | Skips the row in the arrow-key rotation and blocks toggling. |

### MultiSelectSwitchItem

The same row with a Switch in place of the Checkbox, for a settings feel. Forwards native `<div>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| value* | string | - | The value this row adds to or removes from the selection. |
| disabled | boolean | - | Skips the row in the arrow-key rotation and blocks toggling. |

### MultiSelectGroup

Groups related rows, `role="group"`. Forwards native `<div>` props.

### MultiSelectLabel

A muted heading over a group. Forwards native `<div>` props.

### MultiSelectSeparator

A hairline between groups. Forwards native `<div>` props.

## 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>
  )
}
```

## Anatomy

```tsx
import { NativeSelect, NativeSelectOptGroup, NativeSelectOption } from "@/components/ui/native-select"

<NativeSelect>
  <NativeSelectOption value="" disabled />
  <NativeSelectOptGroup label="…">
    <NativeSelectOption value="…" />
  </NativeSelectOptGroup>
</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. Every `<select>` prop but `multiple` (`name`, `value`, `onChange`, `ref`) goes on the select; `className` goes on the frame, so a width moves the caret with it.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| size | "sm" \| "md" \| "lg" | - | Height 32, 36 or 40px. Unset, it comes from a container (`Form` imposes `lg`) or density (`compact`, the default, is `sm`). |
| density | "comfortable" \| "compact" | - | Only picks the default `size` (`compact` is `sm`, `comfortable` is `md`). |

### NativeSelectOption

A native `<option>`; the OS draws it, so it takes text only. An empty-valued, `disabled` first option is the placeholder, read in muted ink while selected.

### NativeSelectOptGroup

A native `<optgroup>`; the OS draws its `label` as a heading in the list.

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Installation

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

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

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

Pro: `navigation-menu` comes with a [Koala UI Pro license](https://www.koalaui.com/pro). Its source is not published in these docs.

## Usage

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Anatomy

```tsx
import {
  NavigationMenu,
  NavigationMenuList,
  NavigationMenuItem,
  NavigationMenuTrigger,
  NavigationMenuContent,
  NavigationMenuGroup,
  NavigationMenuGroupLabel,
  NavigationMenuLink,
  NavigationMenuLinkIcon,
  NavigationMenuLinkMedia,
  NavigationMenuLinkText,
  NavigationMenuLinkDescription,
  NavigationMenuFooter,
  NavigationMenuSub,
  NavigationMenuSubViewport,
  NavigationMenuIndicator,
} from "@/components/ui/navigation-menu"

<NavigationMenu>
  <NavigationMenuList>
    <NavigationMenuItem>
      <NavigationMenuTrigger />
      <NavigationMenuContent>
        <NavigationMenuGroup>
          <NavigationMenuGroupLabel />
          <NavigationMenuLink>
            <NavigationMenuLinkIcon />
            <NavigationMenuLinkText>
              …
              <NavigationMenuLinkDescription />
            </NavigationMenuLinkText>
          </NavigationMenuLink>
          <NavigationMenuLink variant="card">
            <NavigationMenuLinkMedia />
            <NavigationMenuLinkText>…</NavigationMenuLinkText>
          </NavigationMenuLink>
        </NavigationMenuGroup>
        <NavigationMenuFooter />
      </NavigationMenuContent>
    </NavigationMenuItem>
    <NavigationMenuItem>
      <NavigationMenuTrigger />
      <NavigationMenuContent>
        <NavigationMenuSub>
          <NavigationMenuList>
            <NavigationMenuItem>
              <NavigationMenuTrigger />
              <NavigationMenuContent>…</NavigationMenuContent>
            </NavigationMenuItem>
          </NavigationMenuList>
          <NavigationMenuSubViewport />
        </NavigationMenuSub>
      </NavigationMenuContent>
    </NavigationMenuItem>
    <NavigationMenuItem>
      <NavigationMenuLink variant="bar" />
    </NavigationMenuItem>
    <NavigationMenuIndicator />
  </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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Timing

A trigger opens after `delayDuration` (100ms), so a cursor passing over the bar doesn't flash every menu. Reach a sibling trigger within `skipDelayDuration` (300ms) and it opens at once.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## API reference

### NavigationMenu

The root, over Radix `NavigationMenu.Root` (forwards `value`, `defaultValue`, `onValueChange`, `dir`). Every part accepts `className`, merged last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| viewport | boolean | true | Renders the shared panel every content mounts into. `false` opens each content as its own panel under its trigger. |
| density | "comfortable" \| "compact" | - | Row height for every link in the menu. Inherits the nearest `DensityProvider` (compact by default) when unset. |
| delayDuration | number | 100 | Milliseconds the pointer rests on a trigger before the first panel opens. |
| skipDelayDuration | number | 300 | Window after a close in which the next trigger opens at once. |

| Data attribute | Description |
| --- | --- |
| data-viewport | `true` or `false`, mirroring the `viewport` prop. |
| data-orientation | `horizontal`, the bar's direction. |

### NavigationMenuList

The row of entries, a `<ul>`. Also the rail inside a `NavigationMenuSub`. Forwards Radix `NavigationMenu.List` props.

| Data attribute | Description |
| --- | --- |
| data-orientation | `horizontal` in the bar, `vertical` in a Sub rail. |

### NavigationMenuItem

One entry: a trigger with its content, or a single `NavigationMenuLink variant="bar"`. Forwards Radix `NavigationMenu.Item` props, including `value`.

### NavigationMenuTrigger

The chip in the bar, with a caret that turns while its panel is open. Forwards Radix `NavigationMenu.Trigger` props.

| Data attribute | Description |
| --- | --- |
| data-state | `open` while its panel is open, otherwise `closed`. |
| data-disabled | Present when `disabled`. |

### NavigationMenuContent

One panel's contents; give its wrapper a width (`w-56`, `w-72`) to size the panel. Forwards Radix `NavigationMenu.Content` props.

| Data attribute | Description |
| --- | --- |
| data-state | `open` or `closed`. |
| data-motion | `from-start`, `from-end`, `to-start` or `to-end` as the panel switches between triggers, driving the sideways slide. |

### NavigationMenuLink

A link that closes the panel on select and joins the arrow-key focus. Forwards Radix `NavigationMenu.Link` props (`href`, `asChild`).

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| variant | "row" \| "bar" \| "card" | "row" | `row` is a row in a panel; `bar` a plain entry beside the triggers; `card` a featured block over a `NavigationMenuLinkMedia`. |
| active | boolean | - | Marks the current page: `aria-current` and the accent fill. |
| density | "comfortable" \| "compact" | - | Row height for this link. Inherits the menu's density when unset. |

| Data attribute | Description |
| --- | --- |
| data-active | Present when `active`. |

### NavigationMenuLinkText

The title and description column of a described row, after the leading icon. Renders a `<span>`.

### NavigationMenuLinkDescription

The muted sentence under a row's title; place it inside `NavigationMenuLinkText`. Renders a `<span>`.

### NavigationMenuLinkIcon

A ringed 32px tile for a row's glyph, where a brand logo keeps its colours. `aria-hidden`. Renders a `<span>`.

### NavigationMenuLinkMedia

The inset picture frame of a `card` link. Put an `<img>` inside; it owns an `aspect-video` ratio you can override.

### NavigationMenuGroup

A column of links, `role="group"`. Forwards native `<div>` props.

### NavigationMenuGroupLabel

A group's small muted heading. Optional. Forwards native `<div>` props.

### NavigationMenuFooter

The panel's foot under a hairline; the rule drops when nothing sits above it. Forwards native `<div>` props.

### NavigationMenuSub

A menu inside a panel: a `NavigationMenuList` rail, then a `NavigationMenuSubViewport`. The pane switches as the pointer moves down the rail. Forwards Radix `NavigationMenu.Sub` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| orientation | "vertical" \| "horizontal" | "vertical" | Which way the rail runs. |
| defaultValue | string | - | The pane showing the moment the panel opens. |
| value | string | - | The active pane, controlled. |
| onValueChange | (value: string) => void | - | Called when another pane is shown. |

### NavigationMenuSubViewport

Where a Sub's active pane shows, sized to it. Place it after the rail. Forwards Radix `NavigationMenu.Viewport` props.

### NavigationMenuIndicator

The tip that tracks the active trigger. Optional: drop it as the list's last child.

| Data attribute | Description |
| --- | --- |
| data-state | `visible` while a panel is open, otherwise `hidden`. |

### NavigationMenuViewport

The shared panel, which the root already renders. It sits in a positioner that centres it under the open trigger, shifts it back inside whatever clips the menu, and caps it to the room below the bar.

| Data attribute | Description |
| --- | --- |
| data-state | `open` or `closed`, for the zoom in and out. |
| data-instant | On the positioner while the first panel opens, so it lands in place; only a switch between triggers glides. |

| CSS variable | Description |
| --- | --- |
| --navigation-menu-x | On the positioner: the panel's offset from the bar's start edge. |
| --navigation-menu-origin-x | On the positioner: the open trigger's centre within the panel, the zoom's origin. |
| --navigation-menu-available-height | On the positioner: the room under the bar; a taller panel scrolls inside itself. |
| --radix-navigation-menu-viewport-width | The active content's measured width, set by Radix; the panel eases to it. |
| --radix-navigation-menu-viewport-height | The active content's measured height, set by Radix. |

## 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 (100ms) 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?

Centred under the open trigger and as wide as its content: give the content's wrapper a width (w-56, w-72) to size each panel. Near an edge it shifts back inside whatever clips the menu, and moving to another trigger glides it across as it resizes.

### 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/number-field.md -->

# Number Field

A numeric input with steppers, a scrub-to-change label, keyboard stepping and Intl formatting. It is an Input underneath, so it sizes, focuses and joins an InputGroup like any other field.

```tsx
<Field>
  <NumberField defaultValue={1250} min={0} step={50}
    format={{ style: "currency", currency: "USD" }}>
    <NumberFieldScrubArea>
      <FieldLabel>Monthly budget</FieldLabel>
      <NumberFieldScrubAreaCursor />
    </NumberFieldScrubArea>
    <NumberFieldGroup>
      <NumberFieldInput />
      <NumberFieldDecrement />
      <NumberFieldIncrement />
    </NumberFieldGroup>
  </NumberField>
  <FieldHint>Drag the label or use the arrow keys.</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 number-field
```

Manual: run `npm install radix-ui tailwind-variants tailwind-merge`, then copy the source into `components/ui/number-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

```tsx title="usage.tsx"
import {
  NumberField,
  NumberFieldGroup,
  NumberFieldInput,
  NumberFieldIncrement,
  NumberFieldDecrement,
} from "@/components/ui/number-field"
import { Field, FieldLabel } from "@/components/ui/field"

export function Example() {
  return (
    <Field>
      <FieldLabel>Seats</FieldLabel>
      <NumberField defaultValue={5} min={1} max={50}>
        <NumberFieldGroup>
          <NumberFieldInput />
          <NumberFieldDecrement />
          <NumberFieldIncrement />
        </NumberFieldGroup>
      </NumberField>
    </Field>
  )
}
```

## Anatomy

Every part but the group and the input is optional. Order the steppers however you like: trailing, or one on each side.

```tsx
<NumberField>
  <NumberFieldScrubArea>
    <FieldLabel />
    <NumberFieldScrubAreaCursor />
  </NumberFieldScrubArea>
  <NumberFieldGroup>
    <NumberFieldDecrement />
    <NumberFieldInput />
    <NumberFieldIncrement />
  </NumberFieldGroup>
</NumberField>
```

## Basic

The value is a number, never a string. Type, press the arrow keys, or press the steppers. Hold a stepper and it repeats after a short pause.

```tsx
<Field>
  <FieldLabel>Seats</FieldLabel>
  <NumberField defaultValue={5}>
    <NumberFieldGroup>
      <NumberFieldInput />
      <NumberFieldDecrement />
      <NumberFieldIncrement />
    </NumberFieldGroup>
  </NumberField>
</Field>
```

## Min, max and step

Steps clamp to `min` and `max`, and a typed value clamps on blur. The stepper at a bound disables itself. `Shift` and `PageUp`/`PageDown` take `largeStep`, `Alt` takes `smallStep`, and `Home`/`End` jump to the bounds.

```tsx
<NumberField defaultValue={60} min={0} max={100} step={5}
  smallStep={1} largeStep={25}>
  <NumberFieldGroup>
    <NumberFieldInput />
    <NumberFieldDecrement />
    <NumberFieldIncrement />
  </NumberFieldGroup>
</NumberField>
```

## Formatting

Pass `Intl.NumberFormatOptions` to `format`. Typed text is read back in the same locale, so `1.299,50 €` and `$1,299.50` both parse. A percent field stores the fraction: 25% is `0.25`.

```tsx
<NumberField defaultValue={1299.5} locale="de-DE"
  format={{ style: "currency", currency: "EUR" }}>
  …
</NumberField>

<NumberField defaultValue={0.25} step={0.01}
  format={{ style: "percent" }}>
  …
</NumberField>

<NumberField defaultValue={42}
  format={{ style: "unit", unit: "kilometer-per-hour" }}>
  …
</NumberField>
```

## Scrub area

Wrap the label in `NumberFieldScrubArea` and drag it. With a mouse the pointer locks, so the drag never runs off screen, and `NumberFieldScrubAreaCursor` draws the cursor in its place. Safari keeps the native resize cursor instead.

```tsx
<NumberField defaultValue={240} min={0} max={1440}>
  <NumberFieldScrubArea>
    <FieldLabel>Width</FieldLabel>
    <NumberFieldScrubAreaCursor />
  </NumberFieldScrubArea>
  <NumberFieldGroup>
    <NumberFieldInput />
  </NumberFieldGroup>
</NumberField>

<NumberField defaultValue={0.8} min={0} max={1} step={0.01}
  format={{ style: "percent" }}>
  <NumberFieldScrubArea direction="vertical" pixelSensitivity={4}>
    <FieldLabel>Opacity</FieldLabel>
    <NumberFieldScrubAreaCursor />
  </NumberFieldScrubArea>
  …
</NumberField>
```

## Quantity

Put the steppers on either side and center the figure for a cart or a guest count.

```tsx
<NumberField defaultValue={2} min={1} max={9}>
  <NumberFieldGroup className="w-32">
    <NumberFieldDecrement />
    <NumberFieldInput aria-label="Quantity" className="text-center" />
    <NumberFieldIncrement />
  </NumberFieldGroup>
</NumberField>
```

## Field

Inside a `Field`, the label, the description and the error state wire themselves: `FieldLabel` names the input, `FieldHint` describes it, and `hasError` turns the frame destructive.

```tsx
<Field required>
  <FieldLabel>Guests</FieldLabel>
  <NumberField defaultValue={4} min={1} max={12}>
    …
  </NumberField>
  <FieldHint>Up to 12 per booking.</FieldHint>
</Field>

<Field hasError>
  <FieldLabel>Deposit</FieldLabel>
  <NumberField defaultValue={0} format={{ style: "currency", currency: "USD" }}>
    …
  </NumberField>
  <FieldHint>Enter a deposit above $0.</FieldHint>
</Field>
```

## Input group

`NumberFieldGroup` is an Input frame, so `InputGroup` strips it into a segment. Keep `NumberField` outside the group and the group's size reaches the field.

```tsx
<NumberField defaultValue={72.5} min={0} step={0.5}>
  <InputGroup>
    <NumberFieldGroup>
      <NumberFieldInput aria-label="Weight" />
      <NumberFieldDecrement />
      <NumberFieldIncrement />
    </NumberFieldGroup>
    <InputGroupAddon>kg</InputGroupAddon>
  </InputGroup>
</NumberField>
```

## Sizes

The same three heights as Input: `sm` (32 px), `md` (36 px) and `lg` (40 px), set on `NumberFieldGroup`. Unset, it follows the container (a `Form` imposes `lg`) or the density (`sm` under compact, `md` under comfortable). The steppers scale with it.

```tsx
<NumberFieldGroup size="sm">…</NumberFieldGroup>
<NumberFieldGroup size="md">…</NumberFieldGroup>
<NumberFieldGroup size="lg">…</NumberFieldGroup>
```

## Disabled and read-only

`disabled` dims the field and drops it from the form. `readOnly` keeps it focusable and readable but fixes the value, so the steppers and the keys do nothing.

```tsx
<NumberField defaultValue={12} disabled>…</NumberField>
<NumberField defaultValue={12} readOnly>…</NumberField>
```

## Controlled

`onValueChange` fires on every keystroke and step. `onValueCommitted` fires once the change settles, which is the one to save on.

```tsx
const [value, setValue] = React.useState<number | null>(40)

<NumberField
  value={value}
  onValueChange={setValue}
  onValueCommitted={save}
  min={0}
  step={5}
  format={{ style: "currency", currency: "USD", maximumFractionDigits: 0 }}
>
  …
</NumberField>
```

## API reference

### NumberField

The root. Owns the value, the steps and the formatting, and stacks a scrub-area label over the group. Reads `id`, `disabled` and `required` from a surrounding `Field`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| value | number \| null | - | The value, controlled. `null` is an empty field. |
| defaultValue | number \| null | null | The initial value when uncontrolled. |
| onValueChange | (value: number \| null) => void | - | Fires on every change: typing, stepping, scrubbing, the wheel. |
| onValueCommitted | (value: number \| null) => void | - | Fires when a change settles: on blur, on Enter, after a key step, a press or a scrub. |
| min | number | - | The lowest value. Steps clamp to it, typed values clamp on blur, `Home` jumps to it. |
| max | number | - | The highest value. `End` jumps to it. |
| step | number | 1 | What the arrow keys and the steppers add. |
| smallStep | number | 0.1 | The step with `Alt` held. |
| largeStep | number | 10 | The step with `Shift` held, and for `PageUp` / `PageDown`. |
| format | Intl.NumberFormatOptions | - | How the value is shown: currency, percent, units, fraction digits. Typed text is parsed back with the same rules. |
| locale | string | - | The formatting locale. Unset, it is `en-US` on the server and the visitor's own after hydration. |
| disabled | boolean | false | Dims the group and ignores input. |
| readOnly | boolean | false | Keeps the value readable and focusable, but fixed. |
| required | boolean | false | Marks the input required. |
| name | string | - | Submits the raw number, not the formatted text, in a hidden input. |
| id | string | - | The input's id. Defaults to the Field's. |
| allowWheelScrub | boolean | false | Lets the mouse wheel step the value while the input has focus. |

| Data attribute | Description |
| --- | --- |
| data-disabled | Present when disabled. |
| data-readonly | Present when read-only. |
| data-required | Present when required. |
| data-scrubbing | Present while the scrub area is being dragged. |

### NumberFieldGroup

The field frame. It is an `InputRoot` and keeps its `input-root` slot, so every Input prop and every InputGroup rule applies.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| size | "sm" \| "md" \| "lg" | - | 32, 36 or 40px. Unset, it follows the container, then the density. |
| density | "compact" \| "comfortable" | - | Picks the default size: compact is `sm`, comfortable is `md`. |
| variant | "default" \| "inline" | "default" | `inline` hides the frame until hover. |
| hasError | boolean | - | The destructive border and ring. Defaults to the Field's. |

| Data attribute | Description |
| --- | --- |
| data-scrubbing | Present while the scrub area is being dragged. |

### NumberFieldInput

The text input, with `role="spinbutton"`, `aria-valuenow`, `aria-valuemin`, `aria-valuemax` and `aria-valuetext`. Takes every `input` prop except the value ones.

### NumberFieldIncrement

A small quiet button that steps up. Press and hold to repeat. It disables itself at `max` and stays out of the tab order, since the arrow keys do the same. Children replace the plus glyph.

### NumberFieldDecrement

The same button, stepping down and disabling at `min`.

### NumberFieldScrubArea

Wrap a label in it to drag the value. With a mouse it takes the pointer lock, so the drag never runs off screen.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| direction | "horizontal" \| "vertical" | "horizontal" | The drag axis. Right and up increase. |
| pixelSensitivity | number | 2 | Pixels of travel per step. Higher is slower. |

| Data attribute | Description |
| --- | --- |
| data-scrubbing | Present while dragging. |

### NumberFieldScrubAreaCursor

The cursor shown while the pointer is locked, when the system cursor is hidden. Renders nothing otherwise. Children replace the arrows glyph.

## FAQ

### How is this different from NumberInput?

`NumberInput` is a single prop-driven control with plain numbers. `NumberField` is composed from parts and adds Intl formatting, step modifiers, a scrub area and committed events. Reach for it when the number has a unit, a currency or a percent.

### Why does the formatting change after the page loads?

Without a `locale`, the server and the first client render both format in `en-US`, so hydration matches. React then re-renders once in the visitor's locale. Pass `locale` to fix it.

### What does the form receive?

With `name`, a hidden input submits the raw number (`1299.5`), never the formatted text (`$1,299.50`).

---

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

# Notebook Page

A sheet of notebook paper behind what someone writes: rules, dots or squares spaced on the text's own line height, so every line of a note sits on one. Add the red margin, the spiral binding of a pocket notebook and fields that write straight on the rules, or wrap a Rich Text Editor or plain copy.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Installation

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

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

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

Pro: `notebook-page` comes with a [Koala UI Pro license](https://www.koalaui.com/pro). Its source is not published in these docs.

## Usage

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Anatomy

```tsx
import {
  NotebookBinding,
  NotebookPage,
  NotebookPageField,
  NotebookPageTitle,
} from "@/components/ui/notebook-page"

<NotebookBinding start={…} end={…} />
<NotebookPage>
  <NotebookPageTitle />
  <NotebookPageField />
</NotebookPage>
```

## Lines

`ruled` (the default) prints a hairline at the foot of every line, where the writing rests. `dotted` sets a dot at every line and every line-width step, a bullet journal's grid; `grid` crosses the rules with columns of the same pitch; `plain` keeps the rhythm and prints nothing. The rules are the soft border role and the dots a speck of the muted ink, so every pattern re-themes with the page and never competes with what is written on it.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Sizes

The size picks the line and the type that reads well on it together: `sm` is 14px type on a 24px line, `md` (the default) 16px on 28px, `lg` 18px on 32px. The line is the `--notebook-line` custom property, the one length everything inside inherits as its line height.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Margin

`margin="left"` prints the red rule of a school notebook down the left of the sheet, one and a half lines in from the edge, and starts the writing a quarter line past it. Both are measured in `--notebook-line`, so the margin keeps its proportion at every size. The inset belongs to the margin: it outranks a plain `px-*` on the page, so the rule never ends up under the text (pad the right with `pr-*`, or move the inset on purpose with `data-[margin=left]:pl-*`). The red is the `--notebook-margin` token, the error role at under half strength.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Fields

`NotebookPageField` writes straight on the rules: a textarea with no frame, no fill and no ring, whose line height is the page's line, so every line typed sits on one and its `rows` are page lines. Focus shows as the brand caret alone, so a field that always has focus (a pocket notebook's body) never looks tinted; the placeholder is the muted ink. `asChild` puts the same style on another field (an `<input>`, a third-party textarea). `NotebookPageTitle` is the title line: one line, larger and bolder, still exactly one rule tall; an input by default, a heading with `asChild`. Neither carries a visible label, so give each an `aria-label`.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Focus tint

`focusTint` adds the accent's faintest wash over the lines while a field or the title has focus. Leave it off where one field is the page (a pocket notebook whose body is focused as soon as it opens: the tint would never go away); turn it on where several fields share a sheet and the eye has to find the one being written in.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Binding

`NotebookBinding` is the spiral along the top edge of a pocket notebook: metal rings over the shade the binding throws on the sheet, all in the `--notebook-ring*` and `--notebook-binding-shade` tokens. `rings` sets how many; unset, the strip fills with as many whole rings as fit its width, spread evenly, at any width. `start` and `end` hold a control or a hint at either end (a close button, a shortcut, a live status). Put it above the page, inside the notebook's frame.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Pocket notebook

The parts together: a binding with a close button and the shortcut at its ends, a ruled page with the margin, a title line and the note written on the rules, and the actions under the sheet. Type a note and save it: the shortcut hint gives way to a live “Saved”.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## With the Rich Text Editor

Write straight onto the page: drop the editor's frame and fill (the paper is the ground) and tell its blocks to use the line with no gap between them, so each new paragraph lands on the next rule. Content that sets its own line height or margins drifts a little further off the rules with every block; this is the one adjustment it needs.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Rows

`rows` gives the page its height in lines, like a textarea's, so a blank note still reads as a page to write on. The page grows past it with its content; unset, it hugs what it holds. Padding never knocks the lines off the text: the pattern starts at the first line of the content box and still runs through the padding.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## API reference

### NotebookPage

The sheet, a `<div>` (or, with `asChild`, the child element). It sets `--notebook-line` and the matching type size, so plain lines of text sit on the rules. Every div prop is forwarded; `className` is merged last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| lines | "ruled" \| "dotted" \| "grid" \| "plain" | "ruled" | The pattern: hairline rules, a dot grid, squared paper, or nothing printed on the same rhythm. |
| size | "sm" \| "md" \| "lg" | "md" | The line (24, 28 or 32px) and the type size that reads well on it. |
| margin | "none" \| "left" | "none" | `left` paints the red rule at `--notebook-margin-x` (1.5 lines) in `--notebook-margin` and insets the content a quarter line past it with `data-[margin=left]:pl-*`. |
| rows | number | - | The minimum height in lines, empty or not. Unset, it hugs its content. |
| asChild | boolean | false | Renders the paper onto the child element (an `<article>`, a `<section>`). |

| Data attribute | Description |
| --- | --- |
| data-slot="notebook-page" | On the root. |
| data-lines | The current `lines`. |
| data-margin | The current `margin`. |

| CSS variable | Description |
| --- | --- |
| --notebook-line | The line: the line height of everything inside and the period of the pattern. |
| --notebook-rows | Set from `rows`. |
| --notebook-margin-x | Where the margin rule sits, with `margin="left"`. |
| --notebook-margin | The margin rule's colour (a token in globals.css). |

### NotebookBinding

The spiral along the top edge of a pocket notebook, a `<div>`. Put it above a NotebookPage inside the notebook's frame. Children go between the rings and `end`. Every div prop is forwarded.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| rings | number | - | How many rings the spiral has. Unset, the strip fills with as many as fit its width. |
| start | React.ReactNode | - | A control or a hint at the leading end (a close button). Rendered in `data-slot="notebook-binding-start"`. |
| end | React.ReactNode | - | A control or a hint at the trailing end (a shortcut, a "Saved" status). Rendered in `data-slot="notebook-binding-end"`. |

| Data attribute | Description |
| --- | --- |
| data-slot="notebook-binding-rings" | The rings, `aria-hidden`. |
| data-fill | On the rings when `rings` is unset and they fill the strip. |

### NotebookPageField

A `<textarea>` written straight on the page (or, with `asChild`, the child field): transparent, no border or ring, line height `var(--notebook-line)`, `caret-brand` as the focus cue, muted placeholder. Its `rows` count page lines; an input child is one line tall. Every textarea prop is forwarded. Give it an accessible name: the placeholder is not one.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| focusTint | boolean | false | A `--ring-brand` wash on `:focus-visible`, where several fields share a page. |
| asChild | boolean | false | Styles the child field instead (an `<input>`, a third-party textarea) and renders no textarea. |

| Data attribute | Description |
| --- | --- |
| data-slot="notebook-page-field" | On the field. |

### NotebookPageTitle

The title line, an `<input type="text">` (or, with `asChild`, the child, e.g. a heading). One rule tall, type at 1.375em and semibold, `truncate`. Every input prop is forwarded.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| type | string | "text" | The input type. |
| focusTint | boolean | false | A `--ring-brand` wash on `:focus-visible`, as on the field. |
| asChild | boolean | false | Puts the title style onto the child (an `<h2>` for a page that is read, not written). |

| Data attribute | Description |
| --- | --- |
| data-slot="notebook-page-title" | On the title. |

### notebookPageVariants

The `tv` recipe behind every part, for styling a part of your own to match.

## FAQ

### Why does my text drift off the rules?

Something inside sets its own line height or a gap between blocks. Everything inside inherits the page's line, so plain paragraphs land on it; a Prose, a list with margins or the Rich Text Editor's paragraph gap need their line height set to var(--notebook-line) and their gaps to zero (or a whole number of lines).

### Does it scroll with the text?

Yes. The pattern is a local background, so when the page is its own scroll container (a fixed-height note) the rules travel with the lines instead of the text sliding over a still sheet.

### Can I change the line spacing without changing the type?

Set --notebook-line on the page, e.g. [--notebook-line:--spacing(8)], and keep the size you want for the type. The pattern, the inherited line height and rows all read that one property.

### Is it an input?

No. It is paper: put the control on it. NotebookPageField is the textarea made for it (the Rich Text Editor with its frame removed works too); the page itself takes no focus and announces nothing.

### My field's text slides off the rules when it scrolls.

A textarea that scrolls inside itself moves its text but not the page's rules. Give the field enough rows, let it grow with its content, or make the page the scroll container (a fixed height and overflow-auto on NotebookPage), whose rules scroll with the text.

### How do I write in a handwritten font?

Set the font on the page (or on a field) with className, e.g. font-[Caveat]. The line is the page's, not the font's, so any face sits on the rules; pick a size that fills the line comfortably.

---

<!-- 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Installation

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

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

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

Pro: `otp-input` comes with a [Koala UI Pro license](https://www.koalaui.com/pro). Its source is not published in these docs.

## Usage

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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`.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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).

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Disabled

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## API reference

### OTPInput

A one-time-code field: one numeric input per slot, with paste spreading and SMS autofill. Forwards native `<div>` props to the wrapper; accepts `className`, merged last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| length | number | 6 | Number of digit slots. |
| size | "sm" \| "md" \| "lg" | "md" | Slot size: 40, 48 or 56px squares. |
| value | string | - | The concatenated digits, controlled. |
| defaultValue | string | "" | The initial digits, uncontrolled. |
| onChange | (value: string) => void | - | Called on every edit with the concatenated digits. |
| onComplete | (value: string) => void | - | Called once, when the last empty slot fills: start verification here. |
| hasError | boolean | false | Destructive slots, `aria-invalid`, a destructive hint, and one shake of the row. |
| errorKey | string \| number | - | Re-arms the shake when it changes while `hasError` stays `true`. An attempt counter works. |
| disabled | boolean | false | Disables every slot. |
| label | React.ReactNode | - | Rendered above the slots and wired as the group's `aria-labelledby`. |
| hint | React.ReactNode | - | Helper text below, wired as `aria-describedby`; destructive with `hasError`. |
| required | boolean | false | Appends a destructive asterisk to the label. |
| separator | "dash" \| "dot" \| React.ReactNode | - | A mark between groups: a short line, a centred dot, or any node. Omit for an even row. |
| groupSize | number | - | Slots per group when `separator` is set. Defaults to two even halves. |
| placeholder | string | - | One character shown in empty, unfocused slots. |
| name | string | - | Renders a hidden input so the code posts with a native form. |
| autoFocus | boolean | false | Focuses the first slot on mount. |
| slotClassName | string | - | Merged onto every digit slot. |
| aria-label | string | "One-time passcode" | The group's name when there is no `label`. |

| Data attribute | Description |
| --- | --- |
| data-error | On the slot row while `hasError`. |
| data-disabled | On the slot row while disabled. |
| data-filled | On each slot holding a digit. |

| CSS variable | Description |
| --- | --- |
| --shake-distance | How far the row travels in the error shake: 2, 3 or 4px by size. |

## 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}
    />
  )
}
```

## Anatomy

```tsx
import {
  PaginationRoot,
  PaginationRowsPerPage,
  PaginationInfo,
  PaginationGoTo,
  PaginationControls,
  PaginationPrevButton,
  PaginationNextButton,
} from "@/components/ui/pagination"

<PaginationRoot page={…} pageCount={…}>
  <PaginationRowsPerPage />
  <PaginationInfo />
  <PaginationGoTo />
  <PaginationControls />
  {/* or the buttons one by one */}
  <PaginationPrevButton />
  <PaginationNextButton />
</PaginationRoot>
```

## 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>
```

## API reference

### Pagination

The ready toolbar: `PaginationRoot` with a default layout gated by `show*` toggles. Pass `children` to replace the layout. Every part accepts `className`, merged last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| page* | number | - | The current page, 1-based. Fully controlled. |
| pageCount* | number | - | Total pages, clamped to at least 1. |
| onPageChange | (page: number) => void | - | Called with the next page, already clamped into range. |
| rowsPerPage | number | - | The current rows-per-page value, needed by the rows select. |
| onRowsPerPageChange | (rows: number) => void | - | Called with the next rows-per-page value. |
| rowsPerPageOptions | number[] | [10, 20, 30, 50] | The choices the rows select offers. |
| disabled | boolean | false | Disables every control at once. |
| density | "comfortable" \| "compact" | - | One matched control height: 40px comfortable, 32px compact. Inherits the nearest `DensityProvider` (compact with none). |
| showInfo | boolean | true | The `Page X of Y` readout. |
| showControls | boolean | true | The previous and next buttons. |
| showGoTo | boolean | false | The go-to-page field. |
| showRowsPerPage | boolean | false | The rows-per-page select. |

### PaginationRoot

The state provider and `<nav aria-label="Pagination">`, for a custom layout of the parts. Forwards native `<nav>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| page* | number | - | The current page, 1-based. Fully controlled. |
| pageCount* | number | - | Total pages, clamped to at least 1. |
| onPageChange | (page: number) => void | - | Called with the next page, already clamped into range. |
| rowsPerPage | number | - | The current rows-per-page value, needed by the rows select. |
| onRowsPerPageChange | (rows: number) => void | - | Called with the next rows-per-page value. |
| rowsPerPageOptions | number[] | [10, 20, 30, 50] | The choices the rows select offers. |
| disabled | boolean | false | Disables every control at once. |
| density | "comfortable" \| "compact" | - | One matched control height: 40px comfortable, 32px compact. Inherits the nearest `DensityProvider` (compact with none). |

### PaginationInfo

The `Page X of Y` readout, `aria-live="polite"`, numbers in `tabular-nums`. `children` replace the copy, e.g. to localize. Forwards native `<p>` props.

### PaginationControls

The previous and next buttons with the cluster's spacing. Forwards native `<div>` props.

### PaginationPrevButton

The outline icon button to the previous page, disabled on the first. Forwards `Button` props but `size`, `variant` and `iconOnly`; `children` replace the caret.

### PaginationNextButton

The same button to the next page, disabled on the last.

### PaginationGoTo

A numeric field that jumps to a page on Enter or blur, clamped into range. Forwards native `<div>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| label | React.ReactNode | "Go to" | The label before the field. `null` hides it. |

### PaginationRowsPerPage

The rows-per-page select, fed by the root's `rowsPerPage` and `rowsPerPageOptions`. Forwards native `<div>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| label | React.ReactNode | "Rows per page" | The label before the select. `null` hides it. |

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Installation

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

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

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

Pro: `password-strength` comes with a [Koala UI Pro license](https://www.koalaui.com/pro). Its source is not published in these docs.

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Anatomy

```tsx
import {
  PasswordStrength,
  PasswordStrengthMeter,
  PasswordStrengthLabel,
  PasswordStrengthList,
} from "@/components/ui/password-strength"

<PasswordStrength value={…}>
  <PasswordStrengthMeter />
  <PasswordStrengthLabel />
  <PasswordStrengthList />
</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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## API reference

### PasswordStrength

The root: scores `value` against its rules on every render and shares the result with the parts. Forwards native `<div>` props. Every part accepts `className`, merged last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| value* | string | - | The current password; hand it the same state as the input. |
| rules | PasswordRule[] | defaultPasswordRules | The policy, as `{ id, label, test }`. The default asks for 8 characters, mixed case, a number and a symbol. |

| Data attribute | Description |
| --- | --- |
| data-level | `0` with nothing typed, then `1` to `4`: Weak, Fair, Good, Strong. |

### PasswordStrengthMeter

Four segments climbing red to green, `role="meter"`; any number of rules maps onto the four. Forwards native `<div>` props.

| Data attribute | Description |
| --- | --- |
| data-filled | On each lit segment. |

### PasswordStrengthLabel

The verdict (Weak, Fair, Good, Strong) in its tone, `aria-live="polite"`. Forwards native `<p>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| placeholder | string | - | Shown before anything is typed. |

### PasswordStrengthList

One row per rule; a met rule's dot rolls out as its check rolls in. Forwards native `<ul>` props.

| Data attribute | Description |
| --- | --- |
| data-met | On each row whose rule is met. |

### getPasswordStrength

`getPasswordStrength(value, rules?)` scores without rendering, returning `{ score, max, level, label, tone, rules }`. `defaultPasswordRules` is exported too.

## 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>
  )
}
```

## Anatomy

```tsx
import {
  Popover,
  PopoverTrigger,
  PopoverAnchor,
  PopoverContent,
  PopoverViewport,
  PopoverCloseButton,
  PopoverMedia,
  PopoverTitle,
  PopoverDescription,
  PopoverClose,
  PopoverFooter,
} from "@/components/ui/popover"

<Popover>
  <PopoverTrigger />
  <PopoverAnchor />
  <PopoverContent>
    <PopoverCloseButton />
    <PopoverMedia />
    <PopoverTitle />
    <PopoverDescription />
    <PopoverClose />
    <PopoverFooter />
  </PopoverContent>
</Popover>

// One popover, many triggers
<Popover>
  <PopoverTrigger payload={a} />
  <PopoverTrigger payload={b} />
  <PopoverContent>
    <PopoverViewport>{(payload) => …}</PopoverViewport>
  </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">Dimensions</Button>
  </PopoverTrigger>
  <PopoverContent className="w-80">
    <form className="space-y-3" onSubmit={(e) => e.preventDefault()}>
      {/* title + inputs */}
      <PopoverClose asChild>
        <Button type="submit" size="sm">Save</Button>
      </PopoverClose>
    </form>
  </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>
```

## Open on hover

Set `openOnHover` on the trigger (or the root, for every trigger). It opens after `delay` and stays open while the pointer crosses into the panel and rests in it. A click pins it open, and touch and keyboard keep the click behaviour.

```tsx
<Popover>
  <PopoverTrigger asChild openOnHover delay={200}>
    <Button variant="outline">Notifications</Button>
  </PopoverTrigger>
  <PopoverContent className="w-80" density="compact">
    <PopoverTitle>Notifications</PopoverTitle>
    {/* the list */}
  </PopoverContent>
</Popover>
```

Hovering a link to peek at where it goes is a [HoverCard](https://www.koalaui.com/docs/components/hover-card.md): it never takes focus and never opens on touch, so it only previews. A hover Popover is still a dialog. Its trigger is a button, a click or Enter opens it, and it can hold a form.

## Multiple triggers

Any number of triggers can open one popover. Give each a `payload` and pass the content a function of it. One panel serves the whole table, and only the active row's trigger reads as expanded.

```tsx
<Popover>
  <table>
    {members.map((member) => (
      <tr key={member.handle}>
        <td>
          <PopoverTrigger asChild payload={member}>
            <Button variant="ghost" size="sm">{member.name}</Button>
          </PopoverTrigger>
        </td>
        …
      </tr>
    ))}
  </table>
  <PopoverContent side="right" align="start">
    {(member: Member) => <MemberCard member={member} />}
  </PopoverContent>
</Popover>
```

## Detached triggers

Triggers can live outside the `Popover`, in another component. Create a handle once with `createPopoverHandle()` and pass it to the root and to each trigger. The handle also opens and closes the popover from code.

```tsx
const usage = createPopoverHandle<Usage>()

// In the toolbar
<PopoverTrigger handle={usage} payload={seats} id="usage-seats" asChild>
  <Button variant="outline">Seats</Button>
</PopoverTrigger>
<Button onClick={() => usage.open("usage-storage")}>Open storage from code</Button>

// Anywhere else
<Popover handle={usage}>
  <PopoverContent>{(item: Usage) => <UsageCard item={item} />}</PopoverContent>
</Popover>
```

To control it, pass `open` and `triggerId`, and read the new trigger from `onOpenChange`, which also fires on a switch.

```tsx title="controlled.tsx"
const [open, setOpen] = useState(false)
const [triggerId, setTriggerId] = useState<string | null>(null)

<Popover
  open={open}
  triggerId={triggerId}
  onOpenChange={(next, { triggerId }) => {
    setOpen(next)
    setTriggerId(triggerId)
  }}
>
  …
</Popover>
```

## Animating between triggers

Moving from one trigger to another never closes the panel. It glides to the new trigger, eases to the new size, and the contents slide in the direction it moved. The first open lands in place. Each payload sets its own width, here `w-64` on the card.

```tsx
<Popover openOnHover delay={200}>
  {members.map((member) => (
    <PopoverTrigger key={member.handle} payload={member} aria-label={member.name}>
      <Avatar … />
    </PopoverTrigger>
  ))}
  <PopoverContent>
    {(member: Member) => <MemberCard member={member} />}
  </PopoverContent>
</Popover>
```

A function child renders inside a `PopoverViewport`. Place one yourself to style the switch. Hide the leaving contents for a plain resize, or key off `data-activation-direction`, `data-current` and `data-previous`.

```tsx title="viewport.tsx"
<PopoverContent>
  <PopoverViewport className="[&>[data-previous]]:hidden">
    {(member: Member) => <MemberCard member={member} />}
  </PopoverViewport>
</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">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 variant="ghost" size="sm" className="flex-1">Message</Button>
      <Button size="sm" className="flex-1">Follow</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>
  <form className="flex items-center gap-2" onSubmit={(e) => e.preventDefault()}>
    <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 ? "Copied" : "Copy"}
    </Button>
  </form>
</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>
```

## API reference

### Popover

The root. Owns the open state and the active trigger. Renders no element.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| open | boolean | - | The open state, controlled. |
| defaultOpen | boolean | false | The open state on first render, uncontrolled. |
| onOpenChange | (open: boolean, details: PopoverOpenChangeDetails) => void | - | Fires on open, on close, and on a switch between triggers (still `true`). `details` carries `reason`, `triggerId` and `trigger`. |
| triggerId | string \| null | - | The active trigger, controlled. Pair with `details.triggerId`. |
| defaultTriggerId | string \| null | null | The active trigger on first render. Without one, the first trigger anchors the panel. |
| handle | PopoverHandle | - | Links triggers rendered outside this root. From `createPopoverHandle()`. |
| openOnHover | boolean | false | Open every trigger on hover. A trigger's own prop wins. |
| delay | number | 300 | Milliseconds of hover before it opens. |
| closeDelay | number | 150 | Milliseconds before it closes once the pointer leaves the trigger or the panel. Enough to cross the gap. |
| modal | boolean | false | Trap focus in the panel and block the page behind it. |

### PopoverTrigger

A button that opens the popover. Any number of them can open one popover.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| asChild | boolean | false | Render the child element as the trigger, merging props onto it. |
| payload | unknown | - | Handed to the content's render function while this trigger is active. |
| handle | PopoverHandle | - | Links a trigger outside its `Popover`. |
| id | string | - | Names the trigger for `triggerId` and `handle.open(id)`. Also its DOM id. |
| openOnHover | boolean | - | Open on hover. Inherits the root's. |
| delay | number | - | Hover delay for this trigger. Inherits the root's. |
| closeDelay | number | - | Close delay for this trigger. Inherits the root's. |

| Data attribute | Description |
| --- | --- |
| data-state | `open` on the active trigger while the panel is open, else `closed`. |
| data-popover-trigger | The trigger's id. `aria-expanded` and `aria-controls` follow the active trigger only. |

### PopoverContent

The floating panel, portalled to the body. Forwards every Radix `Popover.Content` prop.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| children | ReactNode \| (payload) => ReactNode | - | The contents, or a function of the active payload. A function renders in a `PopoverViewport`. |
| side | "top" \| "right" \| "bottom" \| "left" | "bottom" | The preferred side of the trigger. Flips on collision. |
| sideOffset | number | 8 | The gap to the trigger, in pixels. |
| align | "start" \| "center" \| "end" | "center" | Alignment along the trigger. |
| collisionPadding | number | 8 | The room kept from the viewport edge. |
| density | "comfortable" \| "compact" | "comfortable" | The padding: 16px or 12px. Inherits from a `DensityProvider`. |
| showArrow | boolean | false | Render a small pointer toward the trigger. |

| Data attribute | Description |
| --- | --- |
| data-state | `open` or `closed`. |
| data-side | The side it was placed on, after collisions. |
| data-align | The alignment it was placed with. |

| CSS variable | Description |
| --- | --- |
| --surface | The panel colour, read by nested controls so they blend with it. |
| --popover-padding | The density padding, which the viewport moves onto its contents. |
| --popover-inset-radius | The corner of inset media and footer, concentric with the panel. |
| --radix-popover-content-transform-origin | The trigger side the panel grows from. |

### PopoverViewport

The box the contents switch in. Eases to each payload's size and slides the contents in the direction the panel moved.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| children | ReactNode \| (payload) => ReactNode | - | The contents, or a function of the active payload. |

| Data attribute | Description |
| --- | --- |
| data-activation-direction | Where the new trigger sits from the old: `left`, `right`, `up` or `down`. |
| data-instant | Set until the first switch, so the first open lands at its size. |
| data-current | On the arriving contents. |
| data-previous | On the leaving contents, until their exit ends. |

### createPopoverHandle

Creates a handle shared by a root and its detached triggers. Call it once, outside render. Returns `open(triggerId?)`, `close()` and `isOpen`.

### PopoverAnchor

Anchors the panel to another element, such as a field around the trigger. Replaces the trigger anchor.

### PopoverClose

Closes the popover on click. Use `asChild` to keep your own button.

### PopoverCloseButton

A styled close button pinned to the top-right corner. Pass your icon as the child.

### PopoverTitle

The panel's heading, an `h4`.

### PopoverDescription

Muted supporting copy under the title.

### PopoverMedia

A picture or video set in from the panel's edges, with concentric corners. First or last.

### PopoverFooter

A muted well that closes the panel, inset like the media. Always last.

## 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.

### Should I use openOnHover or a HoverCard?

A HoverCard previews where a link goes: it never takes focus and never opens on touch. Use `openOnHover` when the panel is still a dialog you can reach by click or keyboard, like a notifications list or a row's details.

### How do several triggers share one popover?

Render them all inside one `Popover`, or pass the same `createPopoverHandle()` handle to the root and to triggers elsewhere. Each trigger carries a `payload`, and the content can be a function of it. Switching triggers keeps the panel open and glides it to the new one.

### 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, a chrome variant strips the track, and a duration makes it a self-running countdown.

```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>
  )
}
```

## Anatomy

```tsx
import { Progress, ProgressLabel, ProgressValue } from "@/components/ui/progress"

<Progress value={…}>
  <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 min-w-0 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>
```

## Timed

Pass `duration` (in ms) instead of a value and the bar runs itself: the countdown on an alert that closes on its own, a cooldown, the fill of a [Hold Button](https://www.koalaui.com/docs/components/hold-button.md). `onComplete` fires when the time is up. The fill is the full bar slid along the track on `transform`, a CSS animation on the compositor, so nothing re-renders and nothing is laid out while it runs, and the leading end keeps its round cap all the way. `paused` freezes it where it stands and resuming carries on with the time that was left; a new `runKey` starts it again from the top. Here the alert closes after 8 seconds unless the pointer or focus is on it.

```tsx
<Alert variant="warning" className="overflow-hidden" onPointerEnter={hold} onPointerLeave={release}>
  <Progress
    duration={8000}
    runKey={raised}
    paused={hovered || focused}
    onComplete={close}
    variant="chrome"
    size="xs"
    tone="warning"
    aria-label="Time until this alert closes"
    className="absolute inset-x-0 top-0"
  />
  <AlertIcon />
  <AlertContent>
    <AlertTitle>10-31 · Robbery in progress</AlertTitle>
    <AlertDescription>Fleeca Bank, Vinewood Blvd. Closes in 8s; hover to hold it.</AlertDescription>
  </AlertContent>
</Alert>
```

`direction="drain"` (the default) empties a full bar, the time running out; `"fill"` fills an empty one, the time building up. Changing `duration` or `direction` restarts the run as well. A timed bar reports no value to assistive tech, because a number that moves without re-rendering would be stale the moment it was read: give it a name and, where the time matters, say it in words beside the bar. Under reduced motion it ticks about once a second instead of gliding. The root carries `data-timed`, `data-paused` while paused and `data-complete` once it has run out.

```tsx
<Progress duration={4000} runKey={run} paused={paused} onComplete={…}>
  <ProgressLabel>Drain · cooldown</ProgressLabel>
</Progress>
<Progress duration={4000} direction="fill" tone="success" runKey={run} paused={paused} onComplete={…}>
  <ProgressLabel>Fill · charging</ProgressLabel>
</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"
/>
```

## API reference

### Progress

The bar, `role="progressbar"`, over Radix `Progress.Root`; forwards its props but `asChild`. Children become the row above the track. Every part accepts `className`, merged last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| value | number \| null | 0 | 0 to `max`, clamped. `null` is indeterminate: the fill sweeps. |
| max | number | 100 | The top of the scale, so `value={3} max={8}` is a step counter. |
| size | "xs" \| "sm" \| "md" \| "lg" | "sm" | Track thickness: 4, 6, 8 or 12px (its width when vertical). |
| tone | "brand" \| "foreground" \| "success" \| "warning" \| "destructive" \| "info" | "foreground" | The fill's colour. |
| variant | "default" \| "chrome" | "default" | `chrome` drops the track and squares the ends, for a full-bleed reading or loading bar. |
| transition | "smooth" \| "none" | "smooth" | `smooth` glides between steps; `none` welds the fill to a per-frame value like scroll position. |
| orientation | "horizontal" \| "vertical" | "horizontal" | `vertical` fills from the floor; give the root a height (128px by default). |
| aria-label | string | - | Names the bar when there is no `ProgressLabel`. |
| duration | number | - | Timed mode, in ms: the bar runs itself over this long and `value` is ignored. |
| direction | "drain" \| "fill" | "drain" | Timed mode: empties from full, or fills from empty. |
| paused | boolean | false | Timed mode: holds the bar where it is. |
| runKey | React.Key | - | Timed mode: change it to restart the run. |
| onComplete | () => void | - | Timed mode: called when the run reaches its end. |

| Data attribute | Description |
| --- | --- |
| data-state | `loading`, `complete`, or `indeterminate` while `value` is `null` (set by Radix). |
| data-value | The clamped value (set by Radix). |
| data-max | The `max` (set by Radix). |
| data-orientation | `horizontal` or `vertical`. |
| data-timed / data-paused / data-complete | Present in timed mode, while paused, and once the run has ended. |

| CSS variable | Description |
| --- | --- |
| --progress-track | The track's ink: a 4% foreground tint (6% in dark), so it reads on any ground. Override per instance. |

### ProgressLabel

What is progressing. Names the bar through `aria-labelledby` unless the root has its own label. Renders a `<span>`.

### ProgressValue

The readout, a whole percentage by default, `aria-hidden` since the bar already announces it. Renders a `<span>`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| children | (value: number \| null, max: number) => React.ReactNode | - | Phrases the readout yourself, e.g. `3 of 8`. `value` is `null` while indeterminate. |

### useScrollProgress

`useScrollProgress(ref?)` returns how far the document (or the referenced container) is scrolled, 0 to 100. Pair it with `transition="none"`.

## 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. A timed bar is the exception: it animates every frame for seconds at a time, so there the full-length fill slides on `transform` instead, which keeps the caps round and stays on the compositor.

### How do I count down without re-rendering every frame?

Pass `duration`. The bar runs itself as a CSS animation and a timer beside it fires `onComplete`, so React renders it once per run, not once per frame. Pause it with `paused` (hover and focus on a toast-like card, a game menu opening) and restart it with a new `runKey`.

---

<!-- 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Installation

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

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

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

Pro: `promo-card` comes with a [Koala UI Pro license](https://www.koalaui.com/pro). Its source is not published in these docs.

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Anatomy

```tsx
import {
  PromoCard,
  PromoCardClose,
  PromoCardContent,
  PromoCardEyebrow,
  PromoCardIcon,
  PromoCardTitle,
  PromoCardDescription,
  PromoCardActions,
  PromoCardMedia,
} from "@/components/ui/promo-card"

<PromoCard>
  <PromoCardClose />
  <PromoCardContent>
    <PromoCardEyebrow>
      <PromoCardIcon />
    </PromoCardEyebrow>
    <PromoCardTitle />
    <PromoCardDescription />
    <PromoCardActions>…</PromoCardActions>
  </PromoCardContent>
  <PromoCardMedia>…</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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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”.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## API reference

### PromoCard

The root: owns the surface, the density and the open state, and is a size container (it stacks the peek below 42rem of its own width). Forwards native `<div>` props. Every part accepts `className`, merged last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| variant | "default" \| "muted" \| "brand" \| "elevated" | "default" | `default` is an unfilled contour; `muted` and `brand` are tints; `elevated` floats on the card fill. |
| density | "comfortable" \| "compact" | - | Padding, resting height and type step. Inherits the nearest `DensityProvider` (compact with none). |
| open | boolean | - | Visibility, controlled. Omit for the built-in behaviour. |
| defaultOpen | boolean | true | Initial visibility, uncontrolled. |
| onOpenChange | (open: boolean) => void | - | Called when `PromoCardClose` dismisses the card: persist the choice here. The exit plays before it unmounts. |

| Data attribute | Description |
| --- | --- |
| data-state | `open`, or `closed` while the exit plays. |

### PromoCardContent

The copy column. Forwards native `<div>` props.

### PromoCardEyebrow

The product line above the title; lead it with your app's mark (`<BrandMark wordmark={false} />` in Koala). Forwards native `<div>` props.

### PromoCardIcon

A tile for another product's logo `<img>`, sized like the BrandMark tile. `aria-hidden`. Renders a `<span>`.

### PromoCardTitle

The pitch, in one line or two. Forwards native `<div>` props.

### PromoCardDescription

The supporting sentence. Forwards native `<p>` props.

### PromoCardActions

The action row. Forwards native `<div>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| size | "sm" \| "md" \| "lg" | "sm" | Control size imposed on the buttons inside; a Button's own `size` wins. |

| Data attribute | Description |
| --- | --- |
| data-control-size | The imposed size. |

### PromoCardMedia

The peek: a framed screen cropped by the card's edges, holding an `<img>` or live DS parts. `aria-hidden` and `inert` by default; pass `aria-hidden={false} inert={false}` to expose it.

### PromoCardClose

The dismiss control, top-right: a ghost icon Button. Forwards `Button` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| aria-label | string | "Dismiss" | The accessible name and tooltip. |

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Installation

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

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

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

Pro: `prose` comes with a [Koala UI Pro license](https://www.koalaui.com/pro). Its source is not published in these docs.

## Usage

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## As child

Pass `asChild` to put the styling on your own element, an `article` or a `section`, instead of a wrapping `div`.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## API reference

### Prose

Typesets the bare elements under it (headings, lists, quotes, code, tables, media). Renders a `<div>` and forwards all native `<div>` props; accepts `className`, merged last, so a descendant utility like `[&_h2]:text-brand` wins over the recipe.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| size | "sm" \| "md" \| "lg" | "md" | Type scale and rhythm: `sm` 14/24 for product UI, `md` 16/28 for docs and release notes, `lg` 17/28 for long-form articles. |
| asChild | boolean | false | Render the styling onto your own child element (`<article>`, `<section>`) instead of a `div`. |

| Data attribute | Description |
| --- | --- |
| data-size | The resolved size: `"sm"`, `"md"` or `"lg"`. |

| CSS variable | Description |
| --- | --- |
| --prose-flow | Gap between top-level blocks. Set by `size`. |
| --prose-h2 | Space above an `h1` or `h2`. |
| --prose-h3 | Space above an `h3` or `h4`. |
| --prose-after-heading | Space between a heading and the block it opens. |
| --prose-media | Space around `figure`, `pre`, `table`, `hr`, `blockquote`, `video` and `iframe`. |
| --prose-item | Gap between list items and before a nested list. |

## 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/push-to-talk.md -->

# Push to Talk

A hold-to-talk key for radios, voice notes and walkie-talkie chat. Live exactly while held, by pointer, keyboard or a global key, with a halo everyone reads as on air and a shake for a press too short to send.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Installation

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

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

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

Pro: `push-to-talk` comes with a [Koala UI Pro license](https://www.koalaui.com/pro). Its source is not published in these docs.

## Usage

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Shapes

`circle` (the default) is the icon alone, for a console where the key sits beside other controls; name it with `aria-label` and show that name in a `Tooltip`. `pill` says it in words and, while live, counts the time on air. Hold each one.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Sizes

`sm` is 32px, for a dense board: it still takes a 40px press (44px on touch) through an invisible hit box, and its halo and shake travel less. `md` (the default) is 40px, the hit target on its own; `lg` is 48px, for the main control of a console or a phone's bottom bar. The glyph steps with the size.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Variants

The idle paint. `neutral` (the default) is the ink solid: a transmit key is a tool, not a brand moment. `primary` takes the brand, for a product whose main action is talking. `outline` is a quiet bordered key, for a board where every row has one. Live is the same for all three: the destructive fill and the halo.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Dispatch board

A talk key in every unit cell. `size="sm"` with `variant="outline"` keeps the board calm at rest; the key held goes live as loudly as any other. Give each one its own `aria-label`, the unit it calls.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Minimum duration

A press shorter than `minDuration` (450ms by default) is a slip, not a message. It fires `onTalkCancel` instead of `onTalkEnd`, both with the duration, and the control shakes. Here the minimum is 600ms. `minDuration={0}` turns the check off: every hold goes out and nothing shakes.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Global shortcut

`shortcut` makes a key transmit while held anywhere on the page, the way a radio console works. It stands down while focus is in a text field, while a modifier is held and while a dialog the control is not in is open. The key also lands in `aria-keyshortcuts`.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Transmitting from a hotkey

When the transmit is handled elsewhere (a game's global push-to-talk key, a hardware button, a state pushed from the server), pass it as `live`: the key shows on air, with the destructive fill, the halo and, on the pill, the timer counting from when it turned on, without being pressed. It is a visual state only: it fires no callback, so the code that owns the transmit keeps owning it, and the pointer and keys still work on their own hold. Here the page listens for `B` and the keys only mirror it.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Labels and icons

`label` and `liveLabel` set the words; `timer={false}` drops the count. `icon` and `liveIcon` swap the glyphs, which cross-fade on the live state.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Disabled

`disabled` dims the control and turns its shortcut off. Disabling it while live ends the hold as an interruption: `onTalkEnd(ms)` fires whatever the length, never a cancel and never the shake. Unmounting it while live does the same, so a closed panel or a switched tab cannot leave the channel open: whatever `onTalkStart` opened, `onTalkEnd` (or `onTalkCancel` for a slip) closes.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## API reference

### PushToTalk

A hold-to-talk `<button>` with `aria-pressed`, live only while held. Forwards all native `<button>` props except `children` (your pointer and key handlers run first); accepts `className`, merged last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| shape | "circle" \| "pill" | "circle" | `circle` is icon only, named by `label` unless you pass `aria-label`; `pill` shows the words and, while live, the timer. |
| size | "sm" \| "md" \| "lg" | "md" | `sm` is 32px for a dense board, `md` 40px, `lg` 48px for a console's main control. |
| variant | "neutral" \| "primary" \| "outline" | "neutral" | The idle paint: the ink solid, the brand fill, or a hairline for dense boards. Live is always the destructive fill. |
| label | React.ReactNode | "Hold to talk" | The words at rest; on the circle, a string label becomes its `aria-label`. |
| liveLabel | React.ReactNode | "On air" | The words while live, before the timer (pill only). |
| timer | boolean | true | Show the time on air (`m:ss`) beside `liveLabel` (pill only). |
| minDuration | number | 450 | A hold shorter than this, in ms, is cancelled: `onTalkCancel` fires instead of `onTalkEnd` and the control shakes. |
| shortcut | string | - | A key (`KeyboardEvent.key`, case-insensitive) that transmits while held anywhere on the page. Ignored while typing, with a modifier held, or while a dialog the control is not in is open; also set as `aria-keyshortcuts`. |
| icon | React.ReactNode | <Microphone weight="fill" /> | The glyph at rest. |
| liveIcon | React.ReactNode | <Waveform weight="bold" /> | The glyph while live; the two cross-fade. |
| disabled | boolean | - | Dims the control and turns its shortcut off. Disabling it while live ends the hold. |
| live | boolean | - | Shows it on air from outside (a hotkey handled elsewhere), without a press or a callback. |
| onTalkStart | () => void | - | The hold began. |
| onTalkEnd | (durationMs: number) => void | - | The hold ended after at least `minDuration`: the message went out. Also fires, whatever the length, when a live control is disabled or unmounted. |
| onTalkCancel | (durationMs: number) => void | - | The hold ended before `minDuration`: nothing went out. |
| onTalkingChange | (talking: boolean) => void | - | Fires with `true` on start and `false` on any end, sent or cancelled. |

| Data attribute | Description |
| --- | --- |
| data-state | `"idle"` at rest, `"live"` while held. |

| CSS variable | Description |
| --- | --- |
| --shake-distance | How far the rejection shake travels. Set to `3px`. |

## FAQ

### Push to Talk or a Toggle?

A Toggle stays on after you let go. Push to Talk is on only while held, so letting go is the send. Use a Toggle for mute; use Push to Talk for a transmit key.

### Can a hold get stuck open?

No. The pointer is captured on press, so releasing anywhere ends it, and losing the window, hiding the tab, disabling it or unmounting it ends it too. An interruption (disabled or unmounted) always fires onTalkEnd, so the consumer stops transmitting.

### The transmit key is handled by the game, not the page. Can the button still light up?

Yes: pass that state as live. The button shows on air (fill, halo, timer) without being pressed and fires no callback, so your hotkey handler stays the only one opening and closing the channel.

### Does it record audio?

No. It reports the hold; your callbacks start and stop whatever captures the voice (MediaRecorder, a WebRTC track, a radio bridge).

### Why doesn't it shrink when pressed?

Being held is the state, and it already changes the fill, the glyph and adds the halo. A shrink on top would be a fourth signal for one gesture.

### What happens under reduced motion?

The halo becomes one still ring and the glyphs swap without the transition. The shake on a slip stays: it carries information.

---

<!-- 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Installation

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

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

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

Pro: `qr-code` comes with a [Koala UI Pro license](https://www.koalaui.com/pro). Its source is not published in these docs.

## Usage

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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).

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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

### QRCode

An `<svg role="img">` whose modules paint in `currentColor` over a `bg-background` quiet zone. Forwards all native `<svg>` props except `children`; accepts `className`, merged last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| value* | string | - | The text to encode (UTF-8 byte mode): a URL, plain text or an `otpauth://` URI. Throws if it exceeds QR version 40. |
| level | "L" \| "M" \| "Q" \| "H" | "M" | Error correction: `L` ~7%, `M` ~15%, `Q` ~25%, `H` ~30%. Higher survives more occlusion at the cost of a denser code. |
| size | number | 160 | Rendered width and height in pixels. Override per breakpoint with `className`. |
| margin | number | 4 | Quiet-zone width in modules. The spec asks for at least 4; lower it only when the surface already gives light padding. |
| moduleRadius | number | 0 | Corner rounding of each module as a fraction of a module, clamped to 0 (sharp squares) through 0.5 (dots). |
| title | string | "QR code" | Accessible name, set as `aria-label` and the SVG `<title>` tooltip. |

## 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>
  )
}
```

## Anatomy

```tsx
import {
  RadioGroup,
  RadioGroupItem,
  RadioSwatch,
  RadioCard,
  RadioCardTitle,
  RadioCardDescription,
} from "@/components/ui/radio-group"

<RadioGroup>
  <RadioGroupItem />
  <RadioSwatch />
  <RadioCard>
    <RadioCardTitle />
    <RadioCardDescription />
  </RadioCard>
</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 takes an ink border 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 "koala-icons"
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 takes an ink border while the flooded dot tweens in. Reached by keyboard, it keeps the same ink and adds a soft halo, so colour only ever means selection.

```tsx
import { RadioGroup, RadioCard, RadioCardTitle, RadioCardDescription } from "@/components/ui/radio-group"
import { FieldGroup, FieldGroupLabel } from "@/components/ui/field"
import { Rocket, Crown, Buildings } from "koala-icons"
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 "koala-icons"
{/* 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>
```

## API reference

### RadioGroup

The group root. Wraps Radix `RadioGroup.Root` and forwards its props; inside a Field it picks up the field's `disabled`, label and description. Every part accepts `className`, merged last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| size | "sm" \| "md" | "md" | Shared with every `RadioGroupItem` (16px or 20px, matching Checkbox) and `RadioSwatch` (24px or 32px) through context. |
| value | string | - | The selected value, controlled. Pair with `onValueChange`. |
| defaultValue | string | - | The initially selected value, uncontrolled. |
| onValueChange | (value: string) => void | - | Called when the selection changes. |
| disabled | boolean | false | Disables every item. Falls back to the surrounding Field's `disabled`. |
| required | boolean | false | Marks the group required for form submission. |
| name | string | - | The field name submitted with a form. |
| orientation | "horizontal" \| "vertical" | - | Which arrow keys move focus; both axes when unset. |
| loop | boolean | true | Whether keyboard focus wraps from the last item to the first. |

| Data attribute | Description |
| --- | --- |
| data-disabled | Present when the group is disabled. |

### RadioGroupItem

The bare circle control. Wraps Radix `RadioGroup.Item` (a `<button>`) and forwards its props; pair it with a `<label htmlFor>` for its name and a larger hit target.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| value* | string | - | The value this item selects. |
| disabled | boolean | false | Disables this item; roving focus skips it. |

| Data attribute | Description |
| --- | --- |
| data-state | `"checked"` or `"unchecked"`. |
| data-disabled | Present when the item is disabled. |

### RadioSwatch

A `RadioGroupItem` dressed as a colour chip for a product variant picker; its size follows the group's `size`. Wraps Radix `RadioGroup.Item` and forwards its props except `children`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| value* | string | - | The value this swatch selects. |
| color* | string | - | The chip's fill, any CSS colour, set inline. |
| label* | string | - | The accessible name (e.g. `"Navy"`), since the chip has no visible text. |
| disabled | boolean | false | Disables this swatch. |

| Data attribute | Description |
| --- | --- |
| data-state | `"checked"` or `"unchecked"`. |
| data-disabled | Present when the swatch is disabled. |

### RadioCard

A whole selectable card that is the radio itself, with a trailing circle mirroring its state. Wraps Radix `RadioGroup.Item` and forwards its props; children go in the card body.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| value* | string | - | The value this card selects. |
| icon | React.ReactNode | - | Optional leading glyph, muted until the card is selected, then full ink. |
| size | "sm" \| "md" | "md" | Set per card, not inherited from the group. `md` top-aligns a title and description; `sm` is a tighter, vertically centered one-line option. |
| disabled | boolean | false | Disables this card. |

| Data attribute | Description |
| --- | --- |
| data-state | `"checked"` or `"unchecked"`. |
| data-disabled | Present when the card is disabled. |

### RadioCardTitle

The card's title line. Forwards all native `<span>` props (a `<button>` may only hold phrasing content).

### RadioCardDescription

The card's supporting text under the title. Forwards all native `<span>` props.

## 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 takes an ink border 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Installation

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

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

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

Pro: `rating` comes with a [Koala UI Pro license](https://www.koalaui.com/pro). Its source is not published in these docs.

## Usage

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Sizes

`sm` (16px), `md` (20px), and `lg` (28px) line up with the rest of the control scale.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Variants

`filled` (default) is the classic solid-star look: the active glyph renders at the `fill` weight, the rest stay outline. `outline` keeps the DS rule, drawing the active star as a tinted outline instead.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Custom icon & length

Swap the star for any Koala 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"`.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Disabled

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## API reference

### Rating

Interactive, it wraps Radix `RadioGroup.Root` with one `RadioGroup.Item` per star; with `readOnly` it renders a static `<div role="img">`. Forwards native `<div>` props (except `onChange`, `defaultValue` and `dir`) and accepts `className`, merged last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| value | number | - | Controlled value. Whole numbers when interactive; fractional values (e.g. `4.3`) render when `readOnly`. |
| defaultValue | number | 0 | Uncontrolled initial value. |
| onValueChange | (value: number) => void | - | Called with the new whole-star value when a star is selected. |
| max | number | 5 | Number of stars in the scale. |
| readOnly | boolean | false | Drops the RadioGroup for a static, fraction-capable display, labelled like "Rating: 4.3 of 5". |
| disabled | boolean | false | Disables every star and fades the row. |
| name | string | - | Form field name, passed to the underlying RadioGroup so the value submits with a form. |
| icon | Icon | Star | Any Koala icon component to use instead of the star (e.g. `Heart`). It follows `variant`: solid by default, outline with `variant="outline"`. |
| aria-label | string | "Rating" | Names the group and builds each star's label, e.g. "Rating 3 of 5". |
| size | "sm" \| "md" \| "lg" | "md" | Star size: 16px, 20px or 28px. |
| variant | "filled" \| "outline" | "filled" | `filled` draws the active glyph at the `fill` weight; `outline` keeps it a tinted outline. |
| tone | "amber" \| "red" | "amber" | Hue of the active glyph: review-gold, or the love-red that suits a heart. |

| Data attribute | Description |
| --- | --- |
| data-disabled | Set by Radix on the group and each star when `disabled`. |
| data-state | On each star: `"checked"` for the selected star, `"unchecked"` otherwise (interactive only). |

## 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 the `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 Koala 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Installation

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

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

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

Pro: `resizable` comes with a [Koala UI Pro license](https://www.koalaui.com/pro). Its source is not published in these docs.

## Usage

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Anatomy

```tsx
import {
  ResizablePanelGroup,
  ResizablePanel,
  ResizableHandle,
} from "@/components/ui/resizable"

<ResizablePanelGroup>
  <ResizablePanel>...</ResizablePanel>
  <ResizableHandle />
  <ResizablePanel>...</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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Vertical

Set `direction="vertical"` to stack panels and drag a horizontal divider. The handle, cursor, and keyboard axis all flip automatically.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## API reference

### ResizablePanelGroup

The split container: compose panels and handles as direct children, alternating panel, handle, panel. Give it a height via `className` (panels fill the box). Forwards all native `<div>` props; every part accepts `className`, merged last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| direction | "horizontal" \| "vertical" | "horizontal" | Lay panels side by side or stacked. The handle, cursor and keyboard axis flip with it. |
| onLayout | (sizes: number[]) => void | - | Called with the panel weights (in DOM order) whenever a drag or key press changes the layout. |

| Data attribute | Description |
| --- | --- |
| data-direction | `"horizontal"` or `"vertical"`, mirroring `direction`. |

### ResizablePanel

One region of the split, sized by `flex-grow` weight. Forwards all native `<div>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| defaultSize | number | - | Starting weight, conventionally a percentage with all panels summing to 100. Omit it on every panel for an equal split. |
| minSize | number \| string | - | Smallest drag size. A number (or `"30%"`) is a proportional weight; a pixel string like `"240px"` is a hard bound pinned as real CSS, so it holds as the window resizes. |
| maxSize | number \| string | - | Largest drag size, as a weight or a pixel string like `"480px"`. |
| collapsible | boolean | - | Snaps the panel shut once dragged past half its `minSize`; drag back out to restore it. |
| collapsedSize | number \| string | 0 | Size the panel settles at when collapsed, as a weight or a pixel string. |
| asChild | boolean | - | Render as the child element (Radix `Slot`) instead of a `<div>`. |

| Data attribute | Description |
| --- | --- |
| data-min-size | The `minSize` value, read by the handle during a drag. |
| data-max-size | The `maxSize` value. |
| data-collapsible | Present when `collapsible`. |
| data-collapsed-size | The `collapsedSize` value. |

### ResizableHandle

The draggable divider between the two panels beside it, with `role="separator"` and live `aria-valuenow`. Arrow keys nudge 16px (Shift 48px), Home and End jump to the previous panel's min and max. Forwards all native `<div>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| withHandle | boolean | - | Shows the minimal rounded grip pill; without it the divider is a hairline that highlights on hover and focus. |
| children | React.ReactNode | - | Custom handle content centered on the divider. Replaces the `withHandle` pill while keeping the drag, keyboard and ARIA behavior. |
| disabled | boolean | - | Disables dragging and keyboard resizing, and takes the handle out of the tab order. |

| Data attribute | Description |
| --- | --- |
| data-dragging | `"true"` while a pointer drag is in progress. Style custom children with `group-data-[dragging=true]/handle:`. |
| data-disabled | `"true"` when `disabled`. |

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Installation

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

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

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

Pro: `rich-text-editor` comes with a [Koala UI Pro license](https://www.koalaui.com/pro). Its source is not published in these docs.

## Usage

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Anatomy

```tsx
import {
  RichTextEditor,
  RichTextEditorToolbar,
  RichTextEditorButton,
  RichTextEditorSeparator,
  RichTextEditorAlignGroup,
  RichTextEditorContent,
  RichTextEditorBubbleMenu,
} from "@/components/ui/rich-text-editor"

<RichTextEditor>
  <RichTextEditorToolbar>
    <RichTextEditorButton />
    <RichTextEditorSeparator />
    <RichTextEditorAlignGroup />
  </RichTextEditorToolbar>
  <RichTextEditorContent />
  <RichTextEditorBubbleMenu>
    <RichTextEditorButton />
  </RichTextEditorBubbleMenu>
</RichTextEditor>
```

## Placeholder

An empty editor shows muted ghost text. Set it with the `placeholder` prop.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Image links

People paste links to screenshots rather than upload them. With `imageLinks`, any paragraph, heading or code block that links to a `.png`, `.jpg`, `.gif`, `.webp` or `.avif` shows the picture right under it. It is a decoration, not content: the HTML you save keeps the link alone, and an expired link simply shows nothing.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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`.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

Or go chromeless: omit the top toolbar and let the bubble be the only formatting UI.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Text alignment

Alignment is opt-in. Pass `alignment` and paragraphs and headings can be set left, center, right or justified; the default toolbar gains an alignment group, with Tiptap's `Mod-Shift-L/E/R/J` shortcuts in its tooltips. Pass a list instead of `true` to offer only some of them. The alignment is written into the HTML as `style="text-align: center;"`, so it survives a save and a reload. Left is the natural flow of a line, so choosing it clears the alignment rather than writing one. Without the prop nothing changes: an editor never keeps an alignment it can't show a control for.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

In a toolbar or bubble of your own, place `RichTextEditorAlignGroup` where you want the controls (`size="sm"` in a bubble). It is a single-choice toggle group that joins the bar's arrow-key navigation, and it renders nothing while `alignment` is off.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Labels

Every string the built-in controls speak or show (the toolbar names, the tooltips that double as aria-labels, and the link editor's field and buttons) comes from `labels`. Pass the keys you want to change; the rest keep their English defaults. The ghost text stays on `placeholder`.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Extending the editor

The document model is open. `starterKit` reconfigures the built-in StarterKit key by key, over Koala's own setup: a key you set replaces that extension's options, and `false` drops the extension. Narrow the headings to the levels your HTML uses, keep typed URLs as text, or stop the editor appending an empty paragraph after a closing list (`trailingNode: false`), so a document saved elsewhere loads and saves back unchanged. `extensions` registers more Tiptap extensions after the built-in ones: a mark, a node, a plugin or, here, a keyboard shortcut that sends the reply. Their commands reach the live editor through `useRichTextEditor`. Both are read when the editor mounts, like the rest of its schema.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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`.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Read-only

Pass `editable={false}` and omit the toolbar to render stored content as styled prose, useful for previews and feeds.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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).

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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)

## API reference

### RichTextEditor

The field surface: creates the Tiptap editor (StarterKit with headings 1 to 4, links and the placeholder) and shares it with every part through context. Forwards native `<div>` props (except `onChange` and `defaultValue`); every part accepts `className`, merged last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| defaultValue | string | "" | Initial HTML content. Uncontrolled: the editor owns its document from here on. |
| onChange | (html: string) => void | - | Called with the serialized HTML on every edit. |
| placeholder | string | "Write something…" | Ghost text shown while the document is empty. |
| editable | boolean | true | Set `false` for a read-only render; toggles without remounting, so the document and selection survive. |
| density | "compact" \| "comfortable" | "compact" | Pads the writing area only (`compact` 12px by 10px, `comfortable` 16px by 12px); the toolbar holds 32px controls in both. Falls back to the nearest `DensityProvider`. |
| alignment | boolean \| RichTextEditorAlignment[] | false | Lets paragraphs and headings be aligned (Tiptap's TextAlign). `true` offers left, center, right and justify; a list offers only those. Adds an alignment group to the default toolbar. Saved as an inline `text-align` style; read when the editor mounts. |
| labels | Partial<RichTextEditorLabels> | - | Translates or rewords the built-in controls' strings. Missing keys keep the English defaults. |
| starterKit | Partial<StarterKitOptions> | - | Reconfigures the built-in StarterKit key by key (`{ heading: { levels: [1, 2] } }`); `false` drops an extension. Read when the editor mounts. |
| extensions | Extensions | - | More Tiptap extensions, registered after the built-in ones. Read when the editor mounts. |
| imageLinks | boolean | false | Shows the picture under any block that links to an image file. Display only: the saved HTML keeps just the link, and a picture that fails to load takes no room. Read when the editor mounts. |

### RichTextEditorToolbar

The formatting bar, wrapping Radix `Toolbar.Root` (roving focus, arrow keys) and forwarding its props. With no children it renders the default set: headings 1 to 4, bold, italic, underline, a link popover, and bullet and numbered lists.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| children | React.ReactNode | - | A custom set of `RichTextEditorButton`s and `RichTextEditorSeparator`s, replacing the default controls. Its buttons share one gliding tooltip. |
| orientation | "horizontal" \| "vertical" | "horizontal" | Radix arrow-key axis for roving focus. |
| loop | boolean | true | Whether keyboard focus wraps from the last control to the first. |

| Data attribute | Description |
| --- | --- |
| data-orientation | Set by Radix: `"horizontal"` or `"vertical"`. |

### RichTextEditorButton

An icon-only control wrapping Radix `Toolbar.Button` inside a `Tooltip`, and forwarding its props. Wire it to the editor with `onClick` and `pressed`, reading state through `useRichTextEditor`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| tooltip* | string | - | The accessible label and hover tooltip. |
| pressed | boolean | - | Marks the control active (e.g. the caret sits in bold text) and sets `aria-pressed`. |
| shortcut | string | - | A keycap shown in the tooltip, e.g. `"⌘B"`. Display only: it does not bind the key. |
| size | "sm" \| "md" | "md" | `md` is a 32px square for the toolbar; `sm` is 36 by 28px for the bubble menu. |
| static | boolean | false | Kept for compatibility; controls no longer scale on press. |
| disabled | boolean | - | Disables the control and skips it in roving focus. |

| Data attribute | Description |
| --- | --- |
| data-pressed | Present when `pressed`. |

### RichTextEditorSeparator

A vertical hairline that groups related controls. Wraps Radix `Toolbar.Separator`; forwards its props.

| Data attribute | Description |
| --- | --- |
| data-orientation | Set by Radix, perpendicular to the toolbar: `"vertical"` in a horizontal toolbar. |

### RichTextEditorAlignGroup

The text-alignment controls: one toggle per alignment the editor's `alignment` prop offers, as a single-choice Radix `Toolbar.ToggleGroup` in the bar's roving focus. The default toolbar places it; drop it into a custom toolbar or a bubble yourself. Choosing left clears the alignment rather than writing `text-align: left`. Renders nothing while `alignment` is off.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| size | "sm" \| "md" | "md" | `md` is a 32px square for the toolbar; `sm` is 36 by 28px for the bubble menu. |
| static | boolean | false | Kept for compatibility; controls no longer scale on press. |
| className | string | - | Merged onto the group. |

| Data attribute | Description |
| --- | --- |
| data-pressed | Present on the toggle of the current alignment (left while the block is unaligned). |

### RichTextEditorContent

The writing area: Tiptap's `EditorContent` with Koala's prose styling (muted body, foreground headings, underlined links). Forwards its props except `editor`, which comes from context.

### RichTextEditorBubbleMenu

A floating toolbar over the current selection, built on Tiptap's `BubbleMenu` (Floating UI). `className` styles the inner toolbar surface; other props go to the floating wrapper. Renders nothing until the editor mounts.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| children | React.ReactNode | - | Custom controls (use `size="sm"` buttons). Without children it renders bold, italic, underline and a link control that expands into an inline URL field. |
| options | BubbleMenuPluginProps["options"] | { placement: "top", offset: 8 } | Floating UI options (placement, offset, flip, shift...), merged over the defaults. |
| shouldShow | (props) => boolean | - | Tiptap callback deciding whether the menu shows for the current selection. |
| updateDelay | number | 250 | Milliseconds to wait before repositioning after a selection change. |

| Data attribute | Description |
| --- | --- |
| data-orientation | Set by Radix on the inner toolbar: `"horizontal"`. |

### useRichTextEditor

A hook returning the live Tiptap `Editor` from the nearest `RichTextEditor`, for custom toolbars, word counts or imperative reads and writes. Returns `null` on the first client render (the editor mounts after, to avoid a hydration mismatch).

## 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.

### How do I let people align text?

Pass `alignment` (or a list such as `["left", "center", "right"]`). It registers Tiptap's TextAlign on paragraphs and headings and adds an alignment group to the default toolbar; custom toolbars and bubbles place `RichTextEditorAlignGroup`. The alignment is saved in the HTML as an inline `text-align` style, so it round-trips through `defaultValue` and `onChange`. It is read when the editor mounts.

### How do I translate the toolbar?

Pass `labels` with the keys you want to change (`bold`, `heading1`, `alignCenter`, `linkPlaceholder`, `apply` and so on, all listed by the `RichTextEditorLabels` type). Missing keys keep their English defaults. Buttons you compose yourself take their text from their own `tooltip`.

### Does the editor honor density?

Yes. It reads `density` from the prop, then the nearest `DensityProvider`, then `compact`: `compact` keeps the writing area tight for dense app surfaces and `comfortable` opens it up. 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.

### How do I change what the document accepts, or add my own extensions?

Pass `starterKit` to reconfigure the built-in StarterKit key by key (`{ heading: { levels: [1, 2] } }`, `{ link: { autolink: false } }`), with `false` to drop an extension (`{ trailingNode: false }` stops the empty paragraph Tiptap appends after a closing list or quote). Pass `extensions` to register more Tiptap extensions after the built-in ones: marks, nodes, plugins, keyboard shortcuts. Both are read when the editor mounts.

---

<!-- 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>
```

## Focus rings

The viewport carries `scroll-p-2`: when Tab (or a `focus()`) scrolls a control into view, the browser stops 8px short of the edge rather than flush against it, so the control's focus ring (2px on a 2px offset) is never cut by the viewport. It changes where focus and `scrollIntoView` land, never the layout, and Chromium 102 honors it. The first and last controls sit against the content's own edge, which scroll padding cannot move, so give the content a little padding (`p-2` here). To change the amount, target the viewport: `[&>[data-slot=scroll-area-viewport]]:scroll-p-4`.

```tsx
<ScrollArea className="h-56">
  <div className="flex flex-col gap-1 p-2">
    {releases.map((r) => <Button key={r.version} variant="ghost">v{r.version}</Button>)}
  </div>
</ScrollArea>
```

## API reference

### ScrollArea

The root, viewport, bars and corner in one, over Radix `ScrollArea.Root`; give it a height and the viewport fills it. Forwards the Radix root props and accepts `className` (on the root), merged last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| orientation | "vertical" \| "horizontal" \| "both" | "vertical" | Which way the content scrolls, and so which bars draw. A vertical-only area unwraps Radix's table box, so `truncate` works inside. |
| fade | boolean | false | Fades the edge that still has content beyond it (the `scroll-fade` utility; vertical edges when `both`). |
| draggable | boolean | false | Lets a mouse pull the content, with a glide on release. A press that barely moves is still a click; touch and pen scroll natively. |
| viewportRef | React.Ref<HTMLDivElement> | - | A ref to the scrolling element itself, to read `scrollTop` or call `scrollTo`. |
| type | "hover" \| "scroll" \| "always" \| "auto" | "hover" | When the bar shows: while hovered, while scrolling, always, or whenever the content overflows. |
| scrollHideDelay | number | 600 | Milliseconds before the bar fades after the pointer leaves or scrolling stops. |
| dir | "ltr" \| "rtl" | - | Reading direction, which sets the side of the vertical bar. |

| Data attribute | Description |
| --- | --- |
| data-state | `visible` or `hidden`, on each scrollbar; it fades between them. |
| data-orientation | `vertical` or `horizontal`, on each scrollbar. |
| data-overflowing | On the viewport with `draggable`, while the content overflows (shows the grab cursor). |
| data-dragging | On the viewport with `draggable`, while a mouse pull is live. |

## 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 "koala-icons"
<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 "koala-icons"
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>
  )
}
```

## Anatomy

```tsx
import {
  Select,
  SelectTrigger,
  SelectValue,
  SelectContent,
  SelectGroup,
  SelectLabel,
  SelectItem,
  SelectSeparator,
} from "@/components/ui/select"

<Select>
  <SelectTrigger>
    <SelectValue />
  </SelectTrigger>
  <SelectContent>
    <SelectGroup>
      <SelectLabel />
      <SelectItem value="..." />
    </SelectGroup>
    <SelectSeparator />
  </SelectContent>
</Select>
```

## Groups and labels

Use `SelectGroup` and `SelectLabel` to group related options. Add `SelectSeparator` between groups for visual clarity.

```tsx
import { Clock } from "koala-icons"
<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 "koala-icons"
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 ink 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 "koala-icons"
<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 "koala-icons"
<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 "koala-icons"
<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 "koala-icons"
<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.

## API reference

### Select

The root, Radix `Select.Root` re-exported as is; it renders no element. Every part below that renders one accepts `className`, merged last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| value | string | - | The selected value (controlled). |
| defaultValue | string | - | The value it starts with (uncontrolled). |
| onValueChange | (value: string) => void | - | Called when an option is picked. |
| open | boolean | - | Open state of the list (controlled). |
| defaultOpen | boolean | - | Open state on mount (uncontrolled). |
| onOpenChange | (open: boolean) => void | - | Called when the list opens or closes. |
| name | string | - | Posts the value with a native form submit. |
| disabled | boolean | - | Disables the whole select. |
| required | boolean | - | Marks the value as required in a native form. |

### SelectTrigger

The button that opens the list, on Radix `Select.Trigger` with a turning caret appended. Inside a `Field` it takes the field's id, description and error state. Forwards every Radix trigger prop.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| size | "sm" \| "md" \| "lg" | - | Height: 32, 36 or 40px, the scale Button and Input share. Without it, a `Form` imposes its size, else density picks `sm` (compact) or `md` (comfortable). |
| density | "compact" \| "comfortable" | - | Picks the default `size` when none is passed: compact is `sm`, comfortable is `md`. |

| Data attribute | Description |
| --- | --- |
| data-state | `open` or `closed`. |
| data-placeholder | Present while no value is selected; the value reads lighter. |
| data-disabled | Present when the select is disabled. |

### SelectValue

Radix `Select.Value` re-exported: mirrors the chosen item (icon and label) inside the trigger.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| placeholder | React.ReactNode | - | Shown while nothing is selected. |

### SelectContent

The portalled list, on Radix `Select.Content`, with scroll arrows and a scroll fade; a popper list is capped at 20rem or the room left on screen. Forwards every Radix content prop.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| position | "popper" \| "item-aligned" | "popper" | `popper` opens below the trigger; `item-aligned` lays the current option over the trigger, for short lists. Koala's default differs from Radix's. |
| sideOffset | number | 6 | Gap (px) between trigger and list, with `popper`. |
| side | "top" \| "right" \| "bottom" \| "left" | "bottom" | Preferred side, with `popper`. |
| align | "start" \| "center" \| "end" | "start" | Alignment against the trigger, with `popper`. |
| density | "compact" \| "comfortable" | "compact" | Row height of the list. Falls back to the nearest `DensityProvider`. |

| Data attribute | Description |
| --- | --- |
| data-state | `open` or `closed`. |
| data-side | The side the list opened on, with `popper`. |
| data-align | The alignment it settled on, with `popper`. |

| CSS variable | Description |
| --- | --- |
| --radix-select-trigger-width | The trigger's width; the list is at least this wide. |
| --radix-select-content-available-height | Room left on screen; caps the popper list's height. |

### SelectItem

An option, on Radix `Select.Item`, with an ink check on the right; children are a leading icon plus label. Forwards every Radix item prop.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| value* | string | - | The value this option commits. |
| disabled | boolean | - | Skips the option in keyboard navigation and blocks picking it. |
| textValue | string | - | Text for type-ahead when the children are not plain text. |
| tooltip | React.ReactNode | - | A hint shown on hover and keyboard focus, for terse labels. |
| tooltipPlacement | TooltipProps["placement"] | "right" | The side the hint grows toward. |
| density | "compact" \| "comfortable" | "compact" | Row height. Falls back to the nearest `DensityProvider`. |

| Data attribute | Description |
| --- | --- |
| data-state | `checked` on the selected option, else `unchecked`. |
| data-highlighted | Present on the option under the pointer or keyboard. |
| data-disabled | Present on a disabled option. |

### SelectGroup

Radix `Select.Group` re-exported: groups related options under a `SelectLabel`.

### SelectLabel

A muted group heading, on Radix `Select.Label`. Takes `density` like `SelectItem`.

### SelectSeparator

A hairline between groups, on Radix `Select.Separator`. Takes `density` like `SelectItem`.

### SelectSearch

The searchable sibling, on Radix Popover and the same recipe: one value, a search field in the panel. Renders a `<div>` only when `inline`, so `className` applies only then.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| value | string | - | The selected value (controlled). |
| defaultValue | string | - | The value it starts with (uncontrolled). |
| onValueChange | (value: string) => void | - | Called when a row is picked. |
| open | boolean | - | Open state of the panel (controlled). |
| defaultOpen | boolean | false | Open state on mount (uncontrolled). |
| onOpenChange | (open: boolean) => void | - | Called when the panel opens or closes; closing clears the query. |
| inline | boolean | false | Renders the panel in the page flow under the trigger, with no fill or shadow; picking keeps it open and Escape clears the query. |
| filter | (query: string, value: string, keywords?: string[]) => number | - | Scores each row; `0` hides it. The default is a case-insensitive substring match over `textValue` and `keywords`. |
| name | string | - | Renders a hidden input so the value posts with a native form submit. |
| disabled | boolean | - | Disables the trigger. Falls back to the enclosing `Field`'s disabled state. |
| size | "sm" \| "md" \| "lg" | - | Trigger height, resolved like `SelectTrigger`'s. |
| density | "compact" \| "comfortable" | "compact" | Row height and default trigger size. Falls back to the nearest `DensityProvider`. |

### SelectSearchTrigger

The trigger `<button>`, styled like `SelectTrigger`; a leading icon may sit before the value. Inside a `Field` it takes the field's wiring. Forwards all native `<button>` props except `type`.

| Data attribute | Description |
| --- | --- |
| data-state | `open` or `closed`. |

### SelectSearchValue

The value shown in the trigger: the label picked this session, or the placeholder. Forwards all native `<span>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| placeholder | React.ReactNode | - | Shown while nothing is selected. |
| renderValue | (value: string) => React.ReactNode | - | Draws the value yourself; needed when it is seeded from outside, since rows only exist while the panel is open. |

| Data attribute | Description |
| --- | --- |
| data-placeholder | Present while nothing is selected. |

### SelectSearchContent

The panel: Radix `Popover.Content` in a portal, or a plain `<div>` when `inline`. Its width matches the trigger. Forwards the Popover content props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| align | "start" \| "center" \| "end" | "start" | Alignment against the trigger. |
| sideOffset | number | 6 | Gap (px) between trigger and panel. |

| Data attribute | Description |
| --- | --- |
| data-state | `open` or `closed` (always `open` inline). |
| data-side | The side the floating panel opened on. |

| CSS variable | Description |
| --- | --- |
| --radix-popover-trigger-width | The trigger's width; the floating panel matches it. |

### SelectSearchInput

The search field, a `role="combobox"` Input that keeps focus while the arrows rove the rows. Forwards native `<input>` props except `value`, `onChange` and `size`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| placeholder | string | "Search…" | Placeholder of the field. |
| aria-label | string | "Search options" | Accessible name of the field. |
| className | string | - | Classes for the wrapper that insets the field. |
| inputClassName | string | - | Classes for the field itself. |

### SelectSearchList

The scrolling `role="listbox"` that holds the rows. Forwards all native `<div>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| label | string | "Options" | Accessible name of the list. |

### SelectSearchItem

A row; one that does not match the query renders nothing. Forwards all native `<div>` props except `onSelect`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| value* | string | - | The value this row commits. |
| textValue | string | - | What the search matches against; defaults to `value`, so give it the visible label. |
| keywords | string[] | - | Extra terms that also match the row: a handle, a synonym, a code. |
| disabled | boolean | - | Skips the row in navigation and blocks picking it. |
| onSelect | (value: string) => void | - | Called before the row commits. |

| Data attribute | Description |
| --- | --- |
| data-state | `checked` on the selected row, else `unchecked`. |
| data-active | `true` on the highlighted row, shared by pointer and keyboard. |
| data-value | The row's `value`. |
| data-disabled | Present on a disabled row. |

### SelectSearchGroup

A `role="group"` that hides, label and all, once every row in it filters out. Forwards all native `<div>` props.

### SelectSearchLabel

A muted group heading. Forwards all native `<div>` props.

### SelectSearchSeparator

A hairline `role="separator"` between groups. Forwards all native `<div>` props.

### SelectSearchEmpty

Shown only while the list holds no row. Its `children` default to `"No results found."`. Forwards all native `<div>` props.

## 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 Koala 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>
  )
}
```

## Anatomy

```tsx
import {
  Sheet,
  SheetHandle,
  SheetHeader,
  SheetTitle,
  SheetDescription,
  SheetBody,
  SheetFooter,
} from "@/components/ui/sheet"

<Sheet>
  <SheetHandle />
  <SheetHeader>
    <SheetTitle />
    <SheetDescription />
  </SheetHeader>
  <SheetBody>...</SheetBody>
  <SheetFooter>...</SheetFooter>
</Sheet>
```

## 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

An absolute `<aside>` that measures its parent: at or above `breakpoint` it floats as a card, below it rises as a bottom sheet with three detents. Forwards all native `<aside>` props, and every part accepts `className`, merged last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| detent | "peek" \| "half" \| "full" | - | The bottom sheet's detent (controlled). |
| defaultDetent | "peek" \| "half" \| "full" | "half" | The detent it starts at when uncontrolled. |
| onDetentChange | (detent: SheetDetent) => void | - | Called when a drag, tap, key or `setDetent` moves the detent. |
| side | "left" \| "right" | "left" | The edge the floating card docks to. |
| size | "sm" \| "md" \| "lg" \| "xl" | "md" | The floating card's width on the container scale; a bottom sheet always spans the canvas. |
| breakpoint | number | 768 | Canvas width (px) at and above which the sheet floats. |
| peekHeight | number | 176 | Height (px) of the `peek` detent: the header and a row or two. |
| onInsetChange | (insets: SheetInsets) => void | - | Reports how much of the canvas the sheet covers per edge (`top`, `right`, `bottom`, `left`, in px), on every layout, detent or width change and every drag frame. |
| density | "compact" \| "comfortable" | "compact" | Padding and title size of the parts. Falls back to the nearest `DensityProvider` and passes it on to the content. |

| Data attribute | Description |
| --- | --- |
| data-layout | `floating` or `bottom`; absent for the first frame, while the canvas is measured (the sheet stays invisible). |
| data-detent | The current detent, on a bottom sheet only. |
| data-dragging | Present while a finger or pointer is dragging the sheet. |
| data-side | `left` or `right`. |

### SheetHandle

The bottom sheet's grab bar and keyboard control, a focusable `role="separator"`: ArrowUp and ArrowDown step detents, Home and End jump to the ends, Enter, Space or a tap step it up. Renders nothing while the sheet floats; forwards all native `<div>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| detentLabels | Partial<Record<SheetDetent, string>> | { peek: "Peek", half: "Half height", full: "Full height" } | What the handle announces for each detent as its `aria-valuetext`, for your language. |
| aria-label | string | "Resize the sheet" | The handle's accessible name. |

### SheetHeader

The title block. On a bottom sheet it is also a drag region, so the whole top can be grabbed. Forwards all native `<div>` props.

### SheetTitle

An `<h2>`; the sheet is labelled by it unless the Sheet gets an `aria-label` or `aria-labelledby`. Forwards all native `<h2>` props.

### SheetDescription

Muted supporting text under the title. Forwards all native `<p>` props.

### SheetBody

The scrollable content between header and footer. Forwards all native `<div>` props.

### SheetFooter

A row pinned to the sheet's bottom edge, the place for a tab bar or the primary action. A lone child fills it; give several `flex-1` to share it. Forwards all native `<div>` props.

### useSheet

A hook for anything inside the Sheet: returns `{ layout, detent, setDetent }`, where `layout` is `"floating"`, `"bottom"` or `null` before the first measure.

## 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. Compose switchers, sections and rows that carry state, then pick the shape: a list, a labeled icon rail, a rail with panels, a peeking rail or a page tree.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Installation

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

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

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

Pro: `sidebar` comes with a [Koala UI Pro license](https://www.koalaui.com/pro). Its source is not published in these docs.

## Usage

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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; wrap it in a `SidebarItemRow` when it carries its own actions. The rail and panel, peek, rich row and page tree parts compose around this same skeleton and are listed in the API reference.

```tsx
import {
  Sidebar,
  SidebarHeader,
  SidebarSwitcher,
  SidebarActions,
  SidebarContent,
  SidebarGroup,
  SidebarGroupLabel,
  SidebarGroupAction,
  SidebarGroupContent,
  SidebarItemRow,
  SidebarItem,
  SidebarItemIcon,
  SidebarItemDot,
  SidebarItemCount,
  SidebarItemActions,
  SidebarItemAction,
  SidebarCollapsible,
  SidebarSeparator,
  SidebarFooter,
} from "@/components/ui/sidebar"

<Sidebar>
  <SidebarHeader>
    <SidebarSwitcher />
    <SidebarActions>...</SidebarActions>
  </SidebarHeader>
  <SidebarContent>
    <SidebarGroup>
      <SidebarGroupLabel />
      <SidebarGroupAction />
      <SidebarGroupContent>
        <SidebarItemRow>
          <SidebarItem>
            <SidebarItemIcon /> {/* or <SidebarItemDot /> */}
            <SidebarItemCount />
          </SidebarItem>
          <SidebarItemActions>
            <SidebarItemAction />
          </SidebarItemActions>
        </SidebarItemRow>
        <SidebarCollapsible>
          <SidebarItem />
        </SidebarCollapsible>
      </SidebarGroupContent>
    </SidebarGroup>
    <SidebarSeparator />
  </SidebarContent>
  <SidebarFooter>
    <SidebarSwitcher />
  </SidebarFooter>
</Sidebar>
```

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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`.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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 `neutral`, the default, and `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 ink bar, the tiles decorate, they don’t signal selection.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Row states

Rows carry state, not just selection: `unread` brings a row to full ink and semibold, `muted` sinks it, and `SidebarItemCount` adds a quiet tabular count. Wrap a row in `SidebarItemRow` to give it hover-revealed `SidebarItemActions`, and add a `SidebarGroupAction` after a heading for a section +. In the collapsed rail unread becomes a small ink dot on the glyph, and counts and actions step aside.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

A plain count takes the row’s own ink, so a column of totals reads as one quiet figure per row and lifts only where the row is active or unread. Reach for a `Badge` when the number is a label rather than a count. For a colour where the icon goes (a mail label, a project), use `SidebarItemDot`: it fills the same 20px glyph column, so dotted and iconed rows line up (the Mail recipe below uses it for labels).

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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 ink 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Stacked (labeled icon rail)

`layout="stacked"` is the rail Slack and Teams lead with: a 72px column where every row sets its glyph in a rounded tile and keeps a short label underneath. The tile is the whole marker, lit on hover and held while active, and a `Badge` in the row pins to its corner as the unread count. Like the collapsed rail, headings go `sr-only`, sections split on a short rule and the switchers reduce to their mark. Set it beside an ordinary rail for the two-pane workspace shell: the stacked rail picks the area, the list rail carries its channels.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Bare stacked

The stacked rail lights a rounded tile behind the glyph on hover and selection, the Slack read. Pass `tile={false}` for the bare rail of Teams: no tile at all, the current row carries the ink edge bar and its glyph and label turn full ink. The glyph keeps its padded box either way, so badges and unread dots pin to the same corner.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Rail and panel

`SidebarPanels` pairs a narrow icon rail with a 240px panel for the area it selects, as in Supabase, Discord or the VS Code activity bar. The rail is a keyboard-navigable tablist, and each `SidebarPanel` is an ordinary list Sidebar with its own title and groups. Clicking the open area again folds the panel away (`collapseOnReselect`); turn that off for a console where the panel is always out.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

With `collapseOnReselect` on (the default) the rail behaves like the VS Code activity bar: click the open view and the panel folds, leaving no lit row and the whole width to the content. Opening and closing animate the panel’s width; switching areas while open is an instant swap. Drive it from anywhere inside with `useSidebarPanels()`.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Peek

`SidebarPeek` shows a rail on demand. `mode="expand"` keeps a 48px icon rail that widens over the page after a short hover or keyboard focus, so the content never moves. Pin it with `SidebarPeekPin` to dock it; the peek closes on leave, Escape or focus out, and holds while a menu inside it is open.

Two trade-offs are deliberate. While it peeks, the rail keeps its icon-rail form, so headings stay short rules and `hideWhenCollapsed` groups and nested sub-lists only appear once it is pinned. And pinning reflows the page on purpose: it is the one change that should move the content, so the column tweens to the full width.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

`mode="offcanvas"` hides the rail entirely and slides it in as a floating card from an 8px hot zone on the left edge or from a `SidebarPeekTrigger` in the content. Resting on the trigger peeks; clicking it docks the rail, and clicking again sends it away. `SidebarPeek` renders no DOM, so the trigger can live in any top bar.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Rich rows

`SidebarRichItem` is the same `SidebarItem` one size up, for rails whose rows are records: leading media, a title with a timestamp, a one-line preview and an unread count. Collapsed, only the avatars or covers remain, with a dot marking unread. The text block is a fixed two-by-two grid, so any part can be left out.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

`size="lg"` is the library row: a 48px cover, square or round by `shape`, with a `SidebarItemMeta placement="center"` for a now-playing glyph. `SidebarHeaderRow`, `SidebarTitle` and `SidebarFilters` stack a titled header, a scrolling chip row and a search row in one `SidebarHeader`.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Page tree

`SidebarTree` nests pages to any depth with a 12px step per level. On hover or focus a page’s icon turns into its caret, and its `actions` (a … menu, a +) appear at the row’s end. Rows match `SidebarItem` exactly, the keyboard model is the one `Tree` uses, and clicking a row navigates while only the caret folds.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

In the collapsed rail the tree shrinks to its top-level pages: each one a glyph with its label as a tooltip, lit while the open page sits anywhere beneath it. A section whose pages mean nothing as bare glyphs should pass `hideWhenCollapsed` to its `SidebarGroup` instead, as Favorites does here.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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).

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Recipes

Five finished rails built from the parts above, nothing bespoke: each one is plain composition of rows, states, counts and the footer. Lift one whole into an app, or use it as the reference for how the parts combine.

Teams, as in Linear: each team folds its own views under a tinted tile.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

Mail: one Compose action, folders with a column of totals, labels as colour dots.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

Usage quota: the plan’s meter and its upgrade sit at the foot, above the profile.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

Presence: direct messages lead with an avatar carrying its status dot.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

User card, as in Discord: the profile, then mute, deafen and settings at one size.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## API reference

### Sidebar

The rail: a 256px `<aside>` landmark (name it with `aria-label`) that hands density and the collapsed state to every part. Forwards all native `<aside>` props, and every part accepts `className`, merged last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| collapsed | boolean | false | Shrinks the rail to a 48px icon-only column. Inherited from an enclosing `LayoutSidebar`; an explicit value wins. |
| layout | "list" \| "stacked" | "list" | `stacked` is the labeled icon rail of Slack or Teams: a 72px column, each glyph in a rounded tile above a short label, a `Badge` pinned to the tile's corner. |
| tile | boolean | true | The stacked rail's selection marker. On, hover and the current row light a rounded tile behind the glyph (Slack); off, the rail goes bare (Teams) and the current row carries the ink edge bar. Only read by `layout="stacked"`. |
| indicator | boolean | false | One highlight that glides to the active row instead of a static chip per row. Ignored while collapsed. |
| side | "left" \| "right" | "left" | The edge it docks against; the hairline moves to the inner edge. |
| floating | boolean | false | Detaches the rail into a rounded card with a full outline and shadow. |
| docked | boolean | false | Sits the rail on the app canvas: no fill, no hairline, full width of its column. Inherited from an enclosing `LayoutSidebar`. |
| density | "compact" \| "comfortable" | "compact" | Zone padding, row height and switcher padding. Falls back to the nearest `DensityProvider`. |

| Data attribute | Description |
| --- | --- |
| data-collapsed | Present while the rail is collapsed. |
| data-layout | `list` or `stacked`. |
| data-docked | Present while the rail is docked. |

| CSS variable | Description |
| --- | --- |
| --surface | Set to `--card` (reset when docked) so nested inputs paint the rail's surface. |

### SidebarHeader

The top zone, with a hairline below, for the workspace switcher; holding a `SidebarActions` turns it into a row. Forwards all native `<div>` props.

### SidebarContent

The scroll region between header and footer; it measures the active row for the `indicator` pill. Forwards all native `<div>` props.

### SidebarFooter

The bottom zone, with a hairline above, for the profile switcher; holding a `SidebarActions` turns it into a row. Forwards all native `<div>` props.

### SidebarActions

A cluster of ghost icon buttons beside the switcher, pushed to the zone's far edge; it stacks under the mark when collapsed. Forwards all native `<div>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| size | "sm" \| "md" \| "lg" \| "xl" | "md" | The height every control in the cluster takes, so buttons and toggles land on one size instead of each control's own default. |

| Data attribute | Description |
| --- | --- |
| data-control-size | The resolved `size`. |

### SidebarGroup

A section rendered as a `<nav>` landmark; name it with `aria-label`. Forwards all native `<nav>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| hideWhenCollapsed | boolean | false | Drops the section entirely while the rail is collapsed. |
| collapsible | boolean | false | Turns `SidebarGroupLabel` into a Radix Collapsible trigger that folds `SidebarGroupContent`. Off while the rail is collapsed. |
| defaultOpen | boolean | true | Starts expanded (uncontrolled); only with `collapsible`. |
| open | boolean | - | Open state (controlled); only with `collapsible`. |
| onOpenChange | (open: boolean) => void | - | Called when a collapsible group toggles. |

### SidebarGroupLabel

The section heading: a muted `<div>`, or in a `collapsible` group a full-width `<button>` with a caret that turns on open. Screen-reader only while collapsed.

| Data attribute | Description |
| --- | --- |
| data-state | `open` or `closed`, on the button of a collapsible group. |

### SidebarGroupContent

The rows of a section. In a `collapsible` group it is the Radix Collapsible panel; otherwise an optional plain stack. Forwards all native `<div>` props.

| Data attribute | Description |
| --- | --- |
| data-state | `open` or `closed`, in a collapsible group. |

### SidebarGroupAction

The button at the end of a section heading (Slack's "Channels +"). Place it right after `SidebarGroupLabel`; it rests hidden and appears while the pointer or keyboard focus is in the section, and sits before the caret of a `collapsible` group. Dropped in an icon rail. Forwards all native `<button>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| label* | string | - | The accessible name of the icon-only button ("Add channel"). |

| Data attribute | Description |
| --- | --- |
| data-state | `open` while a menu or dialog it triggers is open; keeps it on show. |

### SidebarItem

A nav row, a `<button>` by default; lay its children out as `<Icon /> Label` with an optional trailing count. Collapsed, it keeps only the leading glyph. Forwards all native `<button>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| asChild | boolean | false | Renders the child element (an `<a>` or Next `<Link>`) as the row, through Radix Slot. |
| active | boolean | false | Marks the current page: fills the row, adds the ink bar and sets `aria-current="page"`. |
| label | string | - | The collapsed rail's hover tooltip and accessible name for the row. |
| unread | boolean | false | Something new is waiting: the label goes full ink and semibold without the active chip. In an icon rail a small ink dot marks the glyph's corner instead. Announced as "unread". |
| muted | boolean | false | A silenced row: it sinks below the rail's muted ink until hovered or current. Wins over `unread`. |

| Data attribute | Description |
| --- | --- |
| data-active | `true` on the active row. |
| data-unread | Present on an unread row (not when it is also `muted`). |
| data-muted | Present on a muted row. |

### SidebarItemCount

A trailing count, dropped last in a `SidebarItem`: right-aligned tabular figures in the row's own ink. Gone in an icon rail, and inside a `SidebarItemRow` it gives its place to the actions while they show. Forwards all native `<span>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| variant | "plain" \| "pill" | "plain" | `plain` is the quiet total; `pill` the unread capsule of a conversation row. |
| tone | "neutral" \| "brand" \| "muted" | "neutral" | The pill's fill: `neutral` (ink) for a thread that wants attention, `brand` for the accent, `muted` for a muted one. Ignored by `plain`. |
| srLabel | string | "unread" for pill, none for plain | Read after the number by screen readers, so `3` is announced as "3 unread". |

| Data attribute | Description |
| --- | --- |
| data-variant | `plain` or `pill`. |

### SidebarItemRow

Wraps a `SidebarItem` and its `SidebarItemActions` side by side (a button can't hold another button) and drives their reveal from its hover and keyboard focus. In an icon rail it renders the row alone. Forwards all native `<div>` props.

### SidebarItemActions

The trailing cluster of a `SidebarItemRow`, laid over the row's end. Hidden at rest; shown on row hover, keyboard focus in the row, or while a menu it opened is open. Dropped in an icon rail. Forwards all native `<div>` props.

### SidebarItemAction

One small ghost icon button in a `SidebarItemActions` cluster (a … menu, a +), with a 40px tall hit area. A real `<button>`, so it drops into `DropdownMenuTrigger asChild`. Forwards all native `<button>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| label* | string | - | The accessible name of the icon-only button ("Channel options"). |

| Data attribute | Description |
| --- | --- |
| data-state | `open` while its menu is open; keeps it lit. |

### SidebarItemIcon

A soft hue-tinted tile around a single icon, sized by density; decorative (`aria-hidden`). Forwards all native `<span>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| tone | "neutral" \| "brand" \| "purple" \| "pink" \| "teal" \| "orange" \| "green" \| "blue" \| "red" \| "amber" | "neutral" | The tint and glyph colour. |

### SidebarItemDot

A colour dot where a row's icon goes (a mail label, a favourite, a project), filling the same 20px glyph column so dotted and iconed rows line up. Decorative (`aria-hidden`). Forwards all native `<span>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| tone | "neutral" \| "brand" \| "purple" \| "pink" \| "teal" \| "orange" \| "green" \| "blue" \| "red" \| "amber" | "neutral" | The dot's hue. |

### SidebarCollapsible

A parent row that folds a nested list of `SidebarItem`s beneath it, on Radix Collapsible; collapsed, it falls back to a single icon row. Takes only the props below, no native props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| label* | React.ReactNode | - | The parent row's label; a string also becomes the collapsed tooltip. |
| children* | React.ReactNode | - | The nested rows; their edge bar is suppressed. |
| icon | React.ReactNode | - | Leading glyph of the parent row. |
| actions | React.ReactNode | - | Trailing content before the caret, such as a count `Badge`. |
| active | boolean | false | Lights the parent row when one of its child routes is current. |
| defaultOpen | boolean | false | Starts expanded (uncontrolled). |
| open | boolean | - | Open state (controlled). |
| onOpenChange | (open: boolean) => void | - | Called when the section toggles. |
| disabled | boolean | false | Disables the parent row and its toggle. |
| className | string | - | Classes for the parent row. |

| Data attribute | Description |
| --- | --- |
| data-state | `open` or `closed`, on the parent row and the nested list. |

### SidebarSwitcher

The identity row for the workspace or profile switcher, a real `<button>` that drops into `DropdownMenuTrigger asChild` and stays lit while the menu is open. Forwards all native `<button>` props except `title`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| title* | React.ReactNode | - | Primary line: the workspace or profile name. |
| subtitle | React.ReactNode | - | Secondary line: plan, email or role. |
| leading | React.ReactNode | - | Leading visual: an `Avatar`, a logo tile or an icon. |
| caret | boolean | true | Shows the trailing up and down caret. |
| variant | "default" \| "full" | "default" | `default` is the compact trigger; `full` the roomier identity row with a semibold title. |

### SidebarSeparator

A hairline `role="separator"` between groups. Forwards all native `<div>` props.

### SidebarRichItem

A two-line `SidebarItem` one size up, for rows that are records (a conversation, a playlist). It is a `SidebarItem` underneath, so it takes `active`, `label` and `asChild` and every native `<button>` prop. Put `SidebarItemMedia` first: the collapsed rail keeps only it.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| size | "md" \| "lg" | "md" | `md` is the conversation row (40px avatar, 64px rows); `lg` the library row (48px cover, 60px rows). |
| unread | boolean | false | The title goes semibold, and in the collapsed rail an ink dot marks the media's corner. Pair it with a `SidebarItemCount` for the number. |

| Data attribute | Description |
| --- | --- |
| data-unread | Present on an unread row. |
| data-size | `md` or `lg`. |

### SidebarItemMedia

The leading avatar, cover or glyph; a dropped-in `Avatar` or `<img>` fills the square. Forwards all native `<span>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| shape | "circle" \| "square" | "circle" | `circle` for people and artists, `square` (8px corners) for covers, groups and channels. |

### SidebarItemText

The two-line text block: a fixed two-by-two grid, so its parts can come in any order and any can be left out. Forwards all native `<span>` props.

### SidebarItemTitle

The first line: full ink, one line with an ellipsis, semibold on an unread row. Forwards all native `<span>` props.

### SidebarItemDescription

The second line: a preview or subtitle, muted, one line. Forwards all native `<span>` props.

### SidebarItemMeta

Trailing detail on the right edge: a timestamp, read receipts, a now-playing glyph. Muted and tabular. Forwards all native `<span>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| placement | "top" \| "bottom" \| "center" | "top" | Beside the title, beside the description, or centred across both lines. |

### SidebarHeaderRow

One row inside a `SidebarHeader` that stacks several (the title with its actions, a search and sort row). Forwards all native `<div>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| hideWhenCollapsed | boolean | false | Drops the row in the collapsed rail. |

### SidebarTitle

The rail's heading ("Your library"), a 16px semibold `<h2>`, kept for screen readers when collapsed. Forwards all native `<h2>` props.

### SidebarFilters

A horizontally scrolling chip row under the title, with a fade at its edges. Fill it with a `ToggleGroup type="single" size="sm"`. Hidden when collapsed. Forwards all native `<div>` props.

### SidebarPanels

The rail and panel sidebar: owns the selected area and whether its panel is out, and lays the rail and panels side by side. Forwards all native `<div>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| value | string | - | The selected area (controlled). |
| defaultValue | string | - | The area selected on mount (uncontrolled). Set it, so the rail has a tab stop. |
| onValueChange | (value: string) => void | - | Called when another area is picked. |
| open | boolean | - | Whether the panel is on show (controlled). |
| defaultOpen | boolean | true | Whether the panel starts on show (uncontrolled). |
| onOpenChange | (open: boolean) => void | - | Called when the panel opens or closes. |
| collapseOnReselect | boolean | true | Clicking the open area again folds the panel (VS Code). Turn it off for a panel that is always out (Supabase). |

| Data attribute | Description |
| --- | --- |
| data-state | `open` or `closed`: whether a panel is out. |

### SidebarPanelsList

The rail's vertical tablist, in place of a `SidebarGroup` inside the rail's `SidebarContent`; name it with `aria-label`. Up and Down move focus (wrapping), Home and End jump; Enter, Space or a click opens. Forwards all native `<div>` props.

### SidebarPanelsTrigger

A rail row that opens an area's panel: a `SidebarItem` wired as a tab, lit only while its panel is out. Takes every `SidebarItem` prop except `active`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| value* | string | - | The `value` of the `SidebarPanel` it opens. |

| Data attribute | Description |
| --- | --- |
| data-state | `open` while its panel is out, else `closed`. |
| data-active | Present while its panel is out. |

### SidebarPanel

One area's panel: a 240px list `Sidebar`, so the usual parts drop straight in. Takes every `Sidebar` prop except `collapsed` and `layout`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| value* | string | - | The `value` of its `SidebarPanelsTrigger`. |

| Data attribute | Description |
| --- | --- |
| data-state | `open` while this panel is on show, else `closed`. |

### SidebarPanelHeader

The panel's header, sized to the rail's so the two hairlines meet as one line. Forwards all native `<div>` props.

### SidebarPanelTitle

The area's name, a 16px semibold `<h2>`. Forwards all native `<h2>` props.

### useSidebarPanels

Reads and drives the panels from anywhere inside `SidebarPanels` (a hide button, a shortcut): returns `{ value, open, select, setOpen, toggle }`.

### SidebarPeek

The state owner for a rail that shows on demand. Renders no DOM, so a trigger anywhere in the content can reach the panel. Opens on a resting mouse or keyboard focus (never touch); closes on leave, Escape or focus out, and holds while a menu inside is open.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| mode | "expand" \| "offcanvas" | "expand" | `expand`: a 48px icon rail that widens over the content. `offcanvas`: a hidden rail that slides in as a floating card. |
| open | boolean | - | Whether the peek is showing (controlled). |
| defaultOpen | boolean | false | Start with the peek showing (uncontrolled). |
| onOpenChange | (open: boolean) => void | - | Called when the peek shows or hides. |
| pinned | boolean | - | Docked in the flow (controlled). Inside a `Layout`, bridge it to the shell's collapsed state so the shortcut and the pin agree. |
| defaultPinned | boolean | false | Start docked (uncontrolled). |
| onPinnedChange | (pinned: boolean) => void | - | Called when the pin or the trigger docks or undocks the rail. |
| openDelay | number | 160 | How long the pointer rests before the peek shows, in ms. |
| closeDelay | number | 160 (expand), 300 (offcanvas) | The grace after the pointer leaves before the peek hides, in ms. |

### SidebarPeekPanel

The column that holds the rail: a placeholder in the flow plus the floating panel over it. Put a normal `Sidebar` inside as its only child; in `expand` mode it stays collapsed until pinned. Forwards all native `<div>` props.

| Data attribute | Description |
| --- | --- |
| data-mode | `expand` or `offcanvas`. |
| data-state | `rest`, `peek` or `pinned`. |

### SidebarPeekPin

A ghost icon button for the rail's `SidebarActions` that docks or undocks it, with `aria-pressed`. Takes every `Button` prop except `children` and `iconOnly`.

### SidebarPeekTrigger

The control in the content that reaches an offcanvas rail: resting on or focusing it peeks, clicking docks, clicking again sends it away. Pass children to replace the glyph. Takes every `Button` prop except `iconOnly`.

### useSidebarPeek

The peek state for a bespoke control: `{ mode, open, setOpen, pinned, togglePinned }`.

### SidebarTree

A `role="tree"` page tree inside a `SidebarGroup` that owns the current page, the expansion state and the keyboard (Tree's model). Name it with `aria-label`. Forwards all native `<ul>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| value | string | - | The current page (controlled): its row takes the active chip and `aria-current`. |
| defaultValue | string | - | The initial current page (uncontrolled). |
| onValueChange | (value: string) => void | - | Called with the page the user opened (click, Enter or Space on its row). |
| expandedValues | string[] | - | Expanded page values (controlled). |
| defaultExpandedValues | string[] | - | Initially expanded page values (uncontrolled). |
| onExpandedChange | (values: string[]) => void | - | Called with the full set of expanded values when one folds or unfolds. |
| linkAs | React.ElementType | "a" | What a page with an `href` renders as: pass Next's `Link` for client routing. |

### SidebarTreeItem

A page, recursive: nest `SidebarTreeItem`s to give it subpages and a caret. Activating the row navigates; the caret, or Right and Left, folds. Forwards native `<div>` props to the row, `className` included.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| value* | string | - | Stable identity for navigation and expansion. |
| label* | React.ReactNode | - | The page title; a string also names the glyph in the collapsed rail. |
| icon | React.ReactNode | - | The page's emoji or glyph. Falls back to a page glyph, so every row keeps its column. |
| href | string | - | Makes the row a real link, rendered with the tree's `linkAs`. |
| actions | React.ReactNode | - | Trailing `SidebarItemAction`s, revealed on hover or keyboard focus. |
| disabled | boolean | false | Disables navigation, folding and focus for this page. |

| Data attribute | Description |
| --- | --- |
| data-level | The page's depth, from 0. |
| data-expanded | `true` or `false`. |
| data-active | Present on the current page. |

## 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`, `brand`, or the default `neutral`). 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 ink 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.

### How do I build a Slack-style rail?

Pass `layout="stacked"` to the `Sidebar`. Each `SidebarItem` keeps its `<Icon /> Label` markup and lays it out as a tile over a short label; a `Badge` inside the row becomes the corner count. Put an ordinary `Sidebar` beside it for the channel list, and keep each label to one short word so the 72px column never wraps.

### How do I show unread rows and counts?

Pass `unread` to the `SidebarItem`: the label goes full ink and semibold without the active chip, and in an icon rail a small ink dot marks the glyph instead. Drop a `SidebarItemCount` last in the row for the number; it takes the row's own ink and reads as "N unread" if you pass `srLabel="unread"`. `muted` sinks a row and wins over `unread`.

### Why SidebarItemActions instead of a button inside the row?

A `SidebarItem` is a `<button>` or a link, and neither can legally hold another button. `SidebarItemRow` sets the row and its `SidebarItemActions` side by side and reveals them on hover or keyboard focus, so Tab reaches them and a click on the row still navigates. The actions take the count's place while they show.

### When should I use rail and panel instead of a stacked rail?

A stacked rail beside a list rail is a static pair: you wire the two yourself. `SidebarPanels` owns the relationship: the rail is a tablist, each area has its own `SidebarPanel`, the panel animates out and folds away on a second click. Reach for it when each area has its own navigation (Supabase, VS Code); keep a stacked rail when the second column is just a channel list.

### What is the difference between a peek and the collapsed rail?

A collapsed rail stays collapsed until something toggles it, and expanding it moves the content. `SidebarPeek` opens on hover or focus over the content without moving it, and only `SidebarPeekPin` docks it into the flow. In `expand` mode the peeking rail keeps its icon-rail form, so `hideWhenCollapsed` groups and nested sub-lists appear only once it is pinned.

### When should I use SidebarRichItem over SidebarItem?

When the rows are records rather than pages: a conversation with a preview and a timestamp, a playlist with a cover. `SidebarRichItem` is a `SidebarItem` underneath, so the chip, focus ring and collapsed tooltip are the same; it adds the larger media and the second line. For navigation to pages, stay with `SidebarItem`.

### When should I use SidebarTree over SidebarCollapsible?

`SidebarCollapsible` folds one level of routes under a parent row that is only a toggle. `SidebarTree` is for user-made pages nested to any depth: every page navigates, only its caret folds, each row can carry actions, and the keyboard follows the WAI-ARIA tree model.

### Why does a focused row stop short of the scroll edge?

`SidebarContent` carries `scroll-py-2`: when Tab scrolls a row into a long nav, the browser leaves 8px between it and the edge instead of parking it flush, so the row's focus ring is never cut. It only changes where focus scrolling lands, never the layout.

### 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Installation

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

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

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

Pro: `signature` comes with a [Koala UI Pro license](https://www.koalaui.com/pro). Its source is not published in these docs.

## Usage

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## API reference

### Signature

An `<svg role="img">` whose children are the strokes, one `<path>` per pen stroke in writing order; it writes once when a tenth of it is on screen (a new `key` writes it again). Forwards all native `<svg>` props and accepts `className`, merged last; the ink is `currentColor`, so a `text-*` class recolours it.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| aria-label* | string | - | What the signature says, read out in place of the drawing. |
| viewBox | string | - | The drawing's box. Leave it out and it fits itself to its ink on the client; pass it to reserve the width from the first paint. |
| size | "sm" \| "md" \| "lg" | "md" | Height (40, 56 or 80px) and the matching pen weight. |
| speed | "fast" \| "base" \| "slow" | "base" | Time for the whole signature and the lift between strokes, from `signatureDraw` in `lib/motion.ts` (900, 1600 or 2800ms). |
| delay | number | 0 | Milliseconds the pen waits, once on screen, before it touches down. |
| static | boolean | false | Renders the finished drawing with no writing, as under reduced motion. |

| Data attribute | Description |
| --- | --- |
| data-ready | Set once the client has prepared the strokes; the signature is invisible until then. |

| CSS variable | Description |
| --- | --- |
| --signature-weight | The pen width in screen pixels, set by `size`. Override it for a heavier or lighter nib. |
| --signature-scale | Screen pixels per drawing unit, measured on the client; the stroke width divides by it. |

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Installation

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

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

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

Pro: `signature-pad` comes with a [Koala UI Pro license](https://www.koalaui.com/pro). Its source is not published in these docs.

## Usage

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Anatomy

```tsx
import {
  SignaturePad,
  SignaturePadActions,
  SignaturePadUndo,
  SignaturePadClear,
} from "@/components/ui/signature-pad"

<SignaturePad>
  <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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## API reference

### SignaturePad

A `<div role="group" tabIndex={-1}>` framing the page, 160px tall (an `h-*` class sets another height); the pen focuses it and the tab stops are Undo and Clear. Forwards all native `<div>` props, and every part accepts `className`, merged last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| value | string[] | - | The strokes, one SVG path per pen stroke in writing order (controlled). |
| defaultValue | string[] | [] | The strokes to start from (uncontrolled). |
| onValueChange | (strokes: string[]) => void | - | Called when a stroke lands, and on undo and clear, with every stroke so far. |
| name | string | - | Submits the drawing under this name as a standalone SVG document (see `signatureToSvg`). |
| placeholder | React.ReactNode | "Sign here" | The text on the baseline while the page is empty. |
| hasError | boolean | false | Paints the destructive frame. Falls back to the enclosing `Field`'s error state. |
| disabled | boolean | false | Stops the pen and dims the pad. Falls back to the enclosing `Field`'s disabled state. |

| Data attribute | Description |
| --- | --- |
| data-empty | Present while there are no strokes and the pen is up. |
| data-drawing | Present while a stroke is being written. |
| data-disabled | Present when the pad is disabled. |

### SignaturePadActions

The top-right corner holding Undo and Clear, hidden while the pad is empty. Forwards all native `<div>` props.

### SignaturePadUndo

A ghost `sm` `Button` that takes back the last stroke (also `Cmd/Ctrl+Z` while the pad has focus); disabled while the pad is empty. Forwards every `Button` prop.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| children | React.ReactNode | "Undo" | The label. |
| onClick | React.MouseEventHandler<HTMLButtonElement> | - | Runs before the undo; call `event.preventDefault()` to cancel it. |

### SignaturePadClear

A ghost `sm` `Button` that wipes the page; disabled while the pad is empty. Forwards every `Button` prop.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| children | React.ReactNode | "Clear" | The label. |
| onClick | React.MouseEventHandler<HTMLButtonElement> | - | Runs before the clear; call `event.preventDefault()` to cancel it. |

### signatureViewBox

A function returning the box around the ink, padded, as a `viewBox` string. Pass it to a `Signature` to reserve its width from the first paint.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| strokes* | string[] | - | The pad's value. |
| padding | number | 4 | Space added around the ink, in pad pixels. |

### signatureToSvg

A function returning the drawing as a standalone SVG document with `currentColor` ink: the value the pad submits under `name`. Returns `""` for no strokes.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| strokes* | string[] | - | The pad's value. |

## 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>
```

## API reference

### Skeleton

A decorative `aria-hidden` placeholder; set `aria-busy` on the loading region instead. Forwards all native `<div>` props and accepts `className`, merged last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| variant | "rectangle" \| "circle" \| "text" | "rectangle" | Shape: a rounded block, an aspect-square circle sized by one `size-*`, or a full-width line one `1lh` tall. |
| animation | "pulse" \| "shimmer" \| "none" | "pulse" | Opacity breathe, a swept highlight on the `--animate-shimmer` token, or static. Both animations stop under `prefers-reduced-motion`. |
| lines | number | - | With `variant="text"`, stacks this many lines (the last at 60% width); `className` then styles the group. Ignored for other variants and for `lines <= 1`. |

## 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" />
}
```

## Anatomy

```tsx
import {
  Slider,
  SliderInput,
  SliderInputValue,
  SliderInputTrack,
  SliderInputLabel,
} from "@/components/ui/slider"

<Slider />

<SliderInput>
  <SliderInputValue />
  <SliderInputTrack>
    <SliderInputLabel />
    <SliderInputValue />
  </SliderInputTrack>
</SliderInput>
```

## 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" />
```

## API reference

### Slider

A Radix Slider with its track, range and one thumb per value, all rendered for you. Forwards all Radix `Root` props except `asChild` (`orientation`, `step`, `minStepsBetweenThumbs`, `onValueCommit`, `inverted`, `name`, `disabled`); every part on this page accepts `className`, merged last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| value | number[] | - | The controlled values, one per thumb. Pair with `onValueChange`. |
| defaultValue | number[] | - | The initial values when uncontrolled. Two values make a range. |
| onValueChange | (value: number[]) => void | - | Fires on every change while dragging or stepping. |
| min | number | 0 | The lowest value. |
| max | number | 100 | The highest value. |
| size | "sm" \| "md" \| "lg" | "md" | Track thickness and thumb size (a 16, 20 or 24px thumb). |
| variant | "default" \| "brand" \| "success" \| "warning" \| "destructive" | "default" | Tints the range, the thumb border and the tooltip together. The focus ring stays brand. |
| shape | "round" \| "square" | "round" | `square` squares the rail and gives the thumb a fader-cap look. |
| tooltip | boolean | false | Shows a value bubble above each thumb on hover, focus and drag. |
| formatValue | (value: number) => React.ReactNode | - | Formats the tooltip value. Defaults to the raw number. |
| static | boolean | false | Kept for compatibility; controls no longer scale on press. |

| Data attribute | Description |
| --- | --- |
| data-orientation | `horizontal` or `vertical`, on the root, track, range and thumbs. A vertical slider needs a height (`h-48` by default). |
| data-disabled | Present on the root, track, range and thumbs when disabled. |

### SliderInput

The inspector slider root: holds one number and shares it with its parts. With no children it renders `SliderInputValue` then `SliderInputTrack`. Renders a `<div role="group">` and forwards its native props except `defaultValue` and `onChange`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| value | number | - | The controlled value. |
| defaultValue | number | - | The initial value when uncontrolled. Defaults to `min`. |
| onValueChange | (value: number) => void | - | Fires on every change: each drag frame, parsed keystroke and scrub step. |
| onValueCommit | (value: number) => void | - | Fires once an interaction ends: drag release, blur, or Enter in the box. |
| min | number | 0 | The lowest value. |
| max | number | 100 | The highest value. |
| step | number | 1 | Snap increment for the track, the arrow keys and the scrub; also sets the displayed precision. |
| disabled | boolean | - | Disables both halves. Inherits a surrounding `Field`'s disabled state. |
| size | "sm" \| "md" \| "lg" | - | Row height, shared with Input (32, 36 or 40px). Unsized, it follows density: `sm` under compact, `md` under comfortable. |
| variant | "default" \| "brand" | "default" | `brand` tints the fill and the pill with the accent. |
| name | string | - | Form field name, submitted through Radix's hidden input on the track. |
| formatValue | (value: number) => string | - | Text for a value: shown by the value part and announced by the thumb. Name discrete stops here. |
| id | string | - | Goes to the number box so a `<label htmlFor>` focuses it. Inside a `Field` the generated id is used. |

| Data attribute | Description |
| --- | --- |
| data-disabled | Present when disabled. |

### SliderInputValue

Beside the track, an editable, scrubbable number box; inside a track, a read-only readout. Forwards native `<input>` props except `value`, `defaultValue`, `onChange`, `type` and `size`; `className` goes on the input.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| suffix | React.ReactNode | - | A muted unit painted after the number (`%`, `px`). Never part of the typed value. |
| formatValue | (value: number) => string | - | Formats the number while not editing. Defaults to the root's `formatValue`, then the step's precision. |
| boxClassName | string | - | Classes for the box around the input. |

### SliderInputTrack

The rail and pill thumb, a Radix Slider `Root`. Value, bounds, step, `disabled` and `name` come from `SliderInput`; it forwards the remaining Radix `Root` props. Given children, it becomes the field (label inside, readout on the right).

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| ticks | boolean \| number | - | Marks along the rail: `true` for one at every `step`, a number for one every that many units. Past 64 marks none are drawn. |

| Data attribute | Description |
| --- | --- |
| data-dragging | Present on the track while a pointer drags it. |
| data-orientation | Always `horizontal`. |
| data-disabled | Present when disabled. |
| data-covered | Present on the thumb while the pill passes under the label or the readout (it fades). |
| data-filled | Present on each tick at or below the value. |

| CSS variable | Description |
| --- | --- |
| --slider-input-fraction | The value's position from 0 to 1; drives the fill width. |
| --slider-input-thumb | Width of the thumb's box, set per size; the fill and ticks end under the pill's centre. |
| --slider-input-pull-l | The rubber-band stretch past the left end while dragging, in px. |
| --slider-input-pull-r | The rubber-band stretch past the right end while dragging, in px. |
| --slider-input-label-end | In the field layout, the label's right edge in px; ticks fade around it. |
| --slider-input-value-start | In the field layout, the readout's left edge in px; ticks fade around it. |

### SliderInputLabel

The setting's name, painted inside the track on the left; it names the thumb for assistive tech unless the root has an `aria-label`. Only valid inside `SliderInputTrack`. Forwards all native `<span>` props.

## 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 /></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

### Spinner

The loading glyph: a Koala `CircleNotch`, turning. Forwards all icon props except `size` and `weight` (SVG attributes included), and accepts `className`, merged last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| size | "sm" \| "md" \| "lg" \| "xl" | - | Pins the glyph at 14, 16, 20 or 40px. Omit it to let the host size the glyph (`1em` outside any host). |
| label | string | "Loading" | Accessible name while the spinner is announced as `role="status"`. Ignored under `aria-hidden`. |
| aria-hidden | boolean | - | Drops the `status` role and the name, for a host that already announces the busy state. |

## 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/status-bar.md -->

# Status Bar

The thin instrument strip along the edge of an app shell: an IDE, a terminal, a dispatch console. Small mono read-outs in a start, a center and an end region, divided by hairlines, with figures that tick in place.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Installation

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

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

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

Pro: `status-bar` comes with a [Koala UI Pro license](https://www.koalaui.com/pro). Its source is not published in these docs.

## Usage

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Anatomy

```tsx
import {
  StatusBar,
  StatusBarItem,
  StatusBarSection,
  StatusBarSeparator,
  StatusBarSignal,
} from "@/components/ui/status-bar"

<StatusBar>
  <StatusBarSection>
    <StatusBarItem />
    <StatusBarSeparator />
    <StatusBarItem />
  </StatusBarSection>
  <StatusBarSection align="center" />
  <StatusBarSection align="end">
    <StatusBarSignal level={…} />
  </StatusBarSection>
</StatusBar>
```

## Regions

`StatusBarSection` takes `align`: `start` (the default), `center` or `end`. The bar is a three-column grid and each section claims its column, so any of them can be left out: the center stays on the true center whatever sits beside it, and an end section stays at the end with no start. Each side gets half of what the center leaves, and a section on its own takes the whole bar.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Tones

`StatusBarItem` takes `tone`. `default` is the strip's meta ink, `muted` steps back for a label in front of its value, `strong` is the value that matters, and `success` is a healthy state. A leading dot is plain markup inside the item.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Signal

`StatusBarSignal` is a four-step meter: `level` lights that many bars (rounded and clamped to 0 to 4), and a change eases between steps. It is a `meter` named by `label` ("Signal" by default), so a screen reader hears "Link, 3 of 4".

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## On the app frame

The strip paints nothing, so it takes the ground it sits on. On the near-black frame of a docked shell, pin it `dark` and it reads the same in every theme; inside a pane, give it a `border-t` and let it sit on the sheet.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Announcing a value

The bar is not a live region: a clock or a ping inside it would be read out on every tick. When one read-out deserves an announcement (a connection dropping, a build failing), put `aria-live="polite"` on that item alone.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## API reference

### StatusBar

A 24px, three-column grid (`1fr auto 1fr`) in small uppercase mono with `tabular-nums`. Read-only, and not a live region. Every div prop is forwarded; `className` is merged last (`h-7`, `px-3`, `border-t`).

| Data attribute | Description |
| --- | --- |
| data-slot | `"status-bar"`. |

### StatusBarSection

A row of read-outs, a `div`. Its `align` picks its column, so every section is droppable.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| align | "start" \| "center" \| "end" | "start" | The section's column. A section on its own spans the whole bar. |

| Data attribute | Description |
| --- | --- |
| data-slot | `"status-bar-section"`. |
| data-align | The section's `align`. |

### StatusBarItem

A `<span>` that truncates: runs of text end in an ellipsis, glyphs beside them (a dot, a `Kbd`) hold their size.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| tone | "default" \| "muted" \| "strong" \| "success" | "default" | The item's ink. |

| Data attribute | Description |
| --- | --- |
| data-slot | `"status-bar-item"`, with `status-bar-item-text` on each run of text. |

### StatusBarSeparator

A 12px hairline `span`, hidden from assistive tech.

| Data attribute | Description |
| --- | --- |
| data-slot | `"status-bar-separator"`. |

### StatusBarSignal

A four-bar `meter`, valued 0 to 4. Every span prop but `children` is forwarded.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| level* | number | - | How many of the four bars are lit, 0 to 4. Rounded and clamped. |
| label | string | "Signal" | The meter's accessible name. |

| Data attribute | Description |
| --- | --- |
| data-slot | `"status-bar-signal"`, with `status-bar-signal-bar` on each bar. |
| data-level | The clamped value, 0 to 4. |
| data-lit | On each lit bar. |

## FAQ

### Status Bar or Toolbar?

A Toolbar holds controls: buttons, toggles, menus, with roving focus. A Status Bar holds read-outs nobody presses. If an entry needs to be clicked, it belongs in the shell's bars or a Toolbar.

### What happens when the strip runs out of room?

Each side has half of what the center leaves, and its words end in an ellipsis instead of wrapping, so the bar never grows taller; dots and keys beside them keep their size. Drop the low-priority items at small widths with max-sm:hidden.

### Why monospace and uppercase?

It is instrument text: short codes and figures scanned at a glance. A fixed-width face with tabular figures keeps a ticking clock or a ping from shifting its neighbours.

### Why is it not role="status"?

A status role is a live region that re-reads its whole content on every change. Mark only the item whose change matters with aria-live.

---

<!-- 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 ? "Done" : "Next"}
</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>
  )
}
```

## Anatomy

```tsx
import {
  Stepper,
  StepperItem,
  StepperTrigger,
  StepperIndicator,
  StepperTitle,
  StepperDescription,
  StepperSeparator,
} from "@/components/ui/stepper"

<Stepper>
  <StepperItem step={1}>
    <StepperTrigger>
      <StepperIndicator />
      <StepperTitle />
      <StepperDescription />
    </StepperTrigger>
    <StepperSeparator />
  </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>

  <form className="contents" onSubmit={(e) => e.preventDefault()}>
    {/* swap the body on `step`; Back/Next move setStep */}
    <DialogFooter className="sm:justify-between">…</DialogFooter>
  </form>
</DialogContent>
```

## API reference

### Stepper

The root: holds the active step and renders a `<div role="group">`. Forwards all native `<div>` props except `onChange`; every part accepts `className`, merged last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| value | number | - | The active step (1-based), controlled. Pair with `onValueChange`. |
| defaultValue | number | 1 | The initial active step (1-based), uncontrolled. |
| onValueChange | (step: number) => void | - | Fires when a `StepperTrigger` selects its step. |
| variant | "outline" \| "solid" | "outline" | `outline` is a ringed circle with a halo on the active step; `solid` fills every state flat. |
| orientation | "horizontal" \| "vertical" | "horizontal" | A row with the label under each circle, or a column with the label beside it. |
| density | "comfortable" \| "compact" | - | Indicator size (28 or 24px) and text tier. Inherits the nearest `DensityProvider` when omitted. |

| Data attribute | Description |
| --- | --- |
| data-orientation | `horizontal` or `vertical`. |

| CSS variable | Description |
| --- | --- |
| --step-size | The indicator diameter, set per density (`1.75rem` or `1.5rem`); every connector offset derives from it. |

### StepperItem

One step. Derives its state from the root's active value and its own `step`. Forwards all native `<div>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| step* | number | - | This step's 1-based position. |
| completed | boolean | - | Forces the completed state regardless of the active step, for non-linear flows. |
| disabled | boolean | false | Blocks selection through the trigger and mutes the step. |
| loading | boolean | false | Swaps the indicator glyph for a Spinner. |

| Data attribute | Description |
| --- | --- |
| data-state | `completed` (before the active step), `active` or `inactive`. |
| data-disabled | Present when `disabled`. |
| data-loading | Present when `loading`. |

### StepperTrigger

The clickable region that selects its step; omit it for a read-only progress indicator. Renders a `<button>` and forwards all its props; sets `aria-current="step"` on the active step.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| asChild | boolean | false | Renders onto the child element via Radix `Slot` instead of a `<button>`. |
| static | boolean | false | Kept for compatibility; controls no longer scale on press. |

### StepperIndicator

The numbered circle: the step number (or `children` as a custom resting glyph), a check once completed, a spinner while loading. Forwards all native `<span>` props.

### StepperTitle

The step's label, which turns to full ink once active or completed. Forwards all native `<span>` props.

### StepperDescription

A muted secondary line under the title. Forwards all native `<span>` props.

### StepperSeparator

The connector to the next step, placed last in every item but the last; its fill grows when the step completes. Hidden from assistive tech. Forwards all native `<div>` props.

## 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 soft ink 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/swatch-grid.md -->

# Swatch Grid

A grid of pickable samples, a color or a glyph over a color, of which at most one is chosen. The arrow keys move through it in two dimensions and only a click, Enter or Space chooses, so a pick with side effects never fires on a focus move.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Installation

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

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

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

Pro: `swatch-grid` comes with a [Koala UI Pro license](https://www.koalaui.com/pro). Its source is not published in these docs.

## Usage

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Anatomy

```tsx
import { SwatchGrid, SwatchGridItem } from "@/components/ui/swatch-grid"

<SwatchGrid>
  <SwatchGridItem />
</SwatchGrid>
```

## Glyphs over a color

`size="md"` makes 2rem cells with the glyph inset 0.1875rem, for an icon, a sprite `<img>` or a Koala icon `<svg>`; `sm` (the default) makes 1.75rem cells for plain colors. Here the icon grid is painted in the color chosen above it, so every cell shows the marker as it will look. A cell without `color` paints nothing, which suits the "Automatic" way back to a default.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Translucent colors

`checkered` lays a checkerboard under the cell's color. An opaque color hides it; a translucent one lets it through, so 50% black reads as half-transparent rather than as a dim grey.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Disabled

A `disabled` cell dims, takes no press and is skipped by the arrow keys. Say why in its `label`, since that is all a screen reader gets.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Keyboard

The grid is one stop in the Tab order. Moving never chooses: a pick can cost a request, so only a deliberate key does. ↑ and ↓ read the rows from the layout, so they follow whatever column count the grid has at that width.

| Key | Action |
| --- | --- |
| `←` `→` | Move to the previous or next cell, wrapping at the ends. |
| `↑` `↓` | Move to the nearest cell in the row above or below. |
| `Home` `End` | Move to the first or last cell. |
| `Enter` `Space` | Choose the focused cell. |

## API reference

### SwatchGrid

The root: Radix `ToggleGroup.Root` with `type="single"`, laid out as a CSS grid. Set the columns with `className` (e.g. `grid-cols-8`), merged last. Name it with `aria-label`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| value | string | - | The chosen cell's value; `""` for none. |
| defaultValue | string | "" | The chosen cell when uncontrolled. |
| onValueChange | (value: string) => void | - | Called with the newly chosen cell, never with `""`: pressing the chosen cell again keeps it. Listen to the cell's `onClick` to act on a repeat press. |
| size | "sm" \| "md" | "sm" | Reaches every cell: `sm` (1.75rem) for colors, `md` (2rem, the glyph inset 0.1875rem) for glyphs. |
| disabled | boolean | false | Disables every cell. |
| loop | boolean | true | ←/→ wrap from the last cell to the first. |
| rovingFocus | boolean | true | Radix roving focus: the grid is one Tab stop and the arrow keys move inside it. |
| dir | "ltr" \| "rtl" | - | The reading direction ←/→ follow. |
| static | boolean | false | Kept for compatibility; controls no longer scale on press. |

| Data attribute | Description |
| --- | --- |
| data-slot | `"swatch-grid"`. |

### SwatchGridItem

A cell: a Radix `ToggleGroup.Item` (`role="radio"`). Every button prop is forwarded; children are a glyph (an `<img>` or an `<svg>`, sized to the cell).

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| value* | string | - | The cell's value. |
| label* | string | - | The accessible name: a swatch carries no visible text. |
| color | string | - | The fill: any CSS color, set as `--swatch`. Without it, no fill. |
| checkered | boolean | false | Lays a checkerboard under the color, so a translucent one reads as translucent, not dim. |
| disabled | boolean | false | Takes the cell out of the roving focus and dims it. |
| static | boolean | - | Kept for compatibility; controls no longer scale on press. |

| Data attribute | Description |
| --- | --- |
| data-slot | `"swatch-grid-item"`. |
| data-state | `"on"` on the chosen cell, `"off"` on the rest. |
| data-disabled | Present when the cell is disabled. |

| CSS variable | Description |
| --- | --- |
| --swatch | The cell's color, from `color`. `transparent` on the root, so a cell without one inherits nobody's. |
| --surface | Read for the gap between the cell and its selection ring: the ground the grid sits on (falls back to `--background`). |

## FAQ

### Swatch Grid or a Radio Group of RadioSwatch?

RadioSwatch is for a handful of product colors in a form, where the arrow keys choosing as they move is the radio convention. Swatch Grid is for dozens of samples where a pick has effects, so moving never chooses, ↑ and ↓ move by rows, and a cell can hold a glyph.

### Why no 40px hit area on the cells?

The cells sit 0.375rem apart. A 40px target around each would cover its neighbours, so a click would land on the wrong color. Dense pickers (the Emoji Picker included) keep each cell's own box as its target.

### How does the user clear the choice?

By choosing something else, or through a cell you provide for it (an "Automatic" or "None" swatch). Pressing the chosen cell again keeps it, so a grid never ends up empty by accident.

### How do I show the color's name?

Every cell has its label as its accessible name. For sighted users, show the chosen name beside the grid, as the examples do; hover and focus events on the cells can drive a hint line too.

---

<!-- 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 `primary` (ink) 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>
```

## API reference

### Switch

The control, Radix `Switch.Root` rendering a `<button>` with its thumb inside. Forwards all Radix `Root` props; every part accepts `className`, merged last. Inside a `Field` it takes the field's `id`, `disabled` and `aria-describedby` unless you pass your own.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| checked | boolean | - | Controlled on state. |
| defaultChecked | boolean | false | Initial on state when uncontrolled. |
| onCheckedChange | (checked: boolean) => void | - | Called when the switch toggles. |
| disabled | boolean | false | Blocks interaction and dims the control. Falls back to the surrounding `Field`. |
| required | boolean | false | Marks the hidden form input as required. |
| name | string | - | Name of the hidden input submitted with a form. |
| value | string | "on" | Value submitted with a form when on. |
| static | boolean | false | Kept for compatibility; controls no longer scale on press. |

| Data attribute | Description |
| --- | --- |
| data-state | `"checked"` or `"unchecked"`, on the track and the thumb. |
| data-disabled | Present when disabled. |

### SwitchIndicator

The switch's drawing without the control: an `aria-hidden` `<span>` for a row that owns the toggle itself (a menu checkbox item, a MultiSelect option). Forwards all native `<span>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| checked* | boolean | - | Which state to paint. |

| Data attribute | Description |
| --- | --- |
| data-state | `"checked"` or `"unchecked"`. |

### switchVariants

The `tv` recipe behind both parts, with `root` and `thumb` slots, for styling a control of your own to match.

## 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?

Nothing visible: it is kept for compatibility, since controls no longer scale on press. The track and thumb look and behave the same either way.

### 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/tab-strip.md -->

# Tab Strip

The browser-style row of open documents across the top of an app. Each tab carries an icon, a label and a close button, closes on a middle click or Delete, and the strip scrolls instead of wrapping. Presentation only: your app keeps the list, and any drag-and-drop library can reorder it.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Installation

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

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

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

Pro: `tab-strip` comes with a [Koala UI Pro license](https://www.koalaui.com/pro). Its source is not published in these docs.

## Usage

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Anatomy

```tsx
import { TabStrip, TabStripAdd, TabStripItem } from "@/components/ui/tab-strip"

<div className="flex items-center">
  <TabStrip aria-label="…">
    <TabStripItem label="…" />
  </TabStrip>
  <TabStripAdd />
</div>
```

## States

The `active` tab lifts off the bar and always shows its close button; the others show it on hover, in a slot that is always reserved, so nothing shifts. Leave out `onClose` for a tab that must stay open (no button, no middle click, no Delete). `dragging` is the look a sortable library asks for while a tab follows the pointer.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Overflow

More tabs than room: the strip scrolls sideways and never wraps. Its scrollbar is hidden, so a vertical wheel scrolls it too, and the active tab is scrolled into view whenever it changes or a tab opens. Long titles stop at 15rem and truncate. Give the strip a row that can shrink (`min-w-0`) and it scrolls once that row runs out of space, with `TabStripAdd` kept right after the last tab.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Keyboard

The strip is one stop in the Tab order: the active tab. Moving along it only moves focus; selecting is a separate key, because selecting a document usually navigates.

| Key | Action |
| --- | --- |
| `←` `→` | Move focus to the previous or next tab, wrapping at the ends. |
| `Home` `End` | Move focus to the first or last tab. |
| `Enter` `Space` | Select the focused tab (fires its onClick). |
| `Delete` `Backspace` | Close the focused tab, if it has onClose. Focus moves to the tab that takes its place. |

## Reordering

The strip doesn't own the order, so reordering is your drag-and-drop library's job. Items take `ref` and spread every other prop onto their root, which is all dnd-kit's `useSortable` needs. Three of the sortable's `attributes` would break the tab pattern, so the tab ignores them: its `role="button"` (the tab stays `role="tab"`, the only thing a tablist may hold), its `tabIndex={0}` (only the active tab is a tab stop, so Tab still enters and leaves the strip in one step and the arrow keys rove the rest) and its `aria-pressed` (a tab reports `aria-selected`). The rest pass through: `aria-roledescription` and `aria-describedby` still tell a screen reader the tab can be picked up. Put `DndContext` outside the strip, so its screen-reader announcements don't land inside the tablist, and keep a few pixels of activation distance so a click still selects.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## API reference

### TabStrip

A root `<div>` around the scrolling `role="tablist"`. Every div prop lands on the root (`className` merged last), except the two below. Children are the tabs; the active one is always scrolled into view.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| aria-label | string | - | Names the tablist, not the root. |
| aria-labelledby | string | - | Names the tablist from an element on the page. |

| Data attribute | Description |
| --- | --- |
| data-slot="tab-strip" | On the root. |
| data-slot="tab-strip-list" | On the scrolling tablist. |

### TabStripItem

A `role="tab"` `<div>` with `aria-selected`. Takes `ref`; every other div prop (`onClick`, `style`, a sortable's attributes and listeners) is forwarded.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| label* | React.ReactNode | - | The tab's text. Truncates. |
| icon | React.ElementType | - | A leading glyph: the icon component, not an element (`icon={House}`). Rendered at 14px, bold. |
| active | boolean | false | The selected tab: lifted, its close button always visible, and the strip's one tab stop. |
| dragging | boolean | false | Being dragged by a sortable library: lifted above its neighbours, with no transition. |
| onClose | () => void | - | Makes the tab closable: shows the close button, and closes on a middle click and on Delete or Backspace while focused. |
| closeLabel | string | "Close tab" | The close button's hint on hover. |
| static | boolean | false | Kept for compatibility; controls no longer scale on press. |
| role | string | - | Ignored: the tab is always `role="tab"`. |
| tabIndex | number | - | Ignored: only the active tab is a tab stop, the arrow keys rove the rest. |
| aria-pressed | boolean \| "true" \| "false" \| "mixed" | - | Ignored: a tab reports `aria-selected` instead. |

| Data attribute | Description |
| --- | --- |
| data-state | `active` or `inactive`. |
| data-active | `true` or `false`. |
| data-dragging | Present while `dragging`. |
| data-slot="tab-strip-close" | The close button, when `onClose` is set. |

### TabStripAdd

The new-tab `<button>`. Place it beside the strip: a tablist may only hold tabs. Every button prop is forwarded.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| aria-label | string | "New tab" | The button's accessible name. |
| children | React.ReactNode | - | Replaces the plus glyph. |
| static | boolean | false | Kept for compatibility; controls no longer scale on press. |

### tabStripVariants

The `tv` recipe behind every part, for styling a part of your own to match.

## FAQ

### Tab Strip or Tabs?

Tabs switches between panels of one view, and every tab is always there. Tab Strip lists documents the user opens, closes and reorders, and the page itself is rendered by your router, not by the strip.

### Why can't I Tab to the close button?

A tab's contents are presentational to assistive technology, so a focusable button inside one would be invisible to it. The close button is for the pointer; on the keyboard, Delete closes the focused tab, and the tab announces that through aria-keyshortcuts.

### Why doesn't the arrow key select the tab?

Selecting a document usually navigates, and stepping past five tabs shouldn't load five pages. The arrows move focus; Enter or Space selects.

### Does it work on touch screens?

Yes: tap selects, a swipe scrolls the strip, and the close button only takes taps once its tab is active, so a tap can't close a tab whose button it couldn't see. If you sort with dnd-kit's PointerSensor on touch, add touch-none to the items or use its TouchSensor with a delay.

---

<!-- 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Installation

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

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

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

Pro: `table-of-contents` comes with a [Koala UI Pro license](https://www.koalaui.com/pro). Its source is not published in these docs.

## Usage

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

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`.

## Anatomy

```tsx
import {
  TableOfContents,
  TableOfContentsTitle,
  TableOfContentsList,
  TableOfContentsItem,
} from "@/components/ui/table-of-contents"

<TableOfContents>
  <TableOfContentsTitle />
  <TableOfContentsList>
    <TableOfContentsItem href="#…" />
  </TableOfContentsList>
</TableOfContents>
```

## Variants

Six looks over one behaviour, so switching is a prop, never a rewrite. Line is the default: a hairline track with an ink 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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 full ink. 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## API reference

### TableOfContents

The `<nav>` and the scroll-spy. Forwards all native `<nav>` props; every part accepts `className`, merged last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| variant | "line" \| "progress" \| "pill" \| "dash" \| "plain" \| "minimap" | "line" | Six looks over one behaviour: a sliding bar, a filling track, a sliding chip, leading rules, ink alone, or a dash column that opens into a panel. |
| density | "compact" \| "comfortable" | "compact" | 32px or 40px rows (44px on touch). Falls back to the nearest `DensityProvider`. |
| numbered | boolean | false | Number the items (`1.`, and `2.1` for a level-3 item). |
| value | string | - | The active section's id, to drive the mark yourself. The spy still reports through `onValueChange`. |
| defaultValue | string | - | The section marked before the spy's first reading, so the server render already has one. |
| onValueChange | (id: string) => void | - | Called with the id of the section being read, as the reader scrolls or clicks an item. |
| container | React.RefObject<HTMLElement \| null> | - | A scroll pane to watch instead of the window; items then scroll the pane alone. |
| aria-label | string | "On this page" | The nav's accessible name; give each nav its own when a page has two. |

### TableOfContentsTitle

The overline above the list (visually hidden on `minimap`). Forwards all native `<p>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| asChild | boolean | false | Render your own element instead, such as an `<h2>`. |

### TableOfContentsList

The `<ol>`. On line, progress and pill it draws the track, bar or chip as its own `::before`, so `className="before:bg-foreground"` restyles it; on minimap it is the panel, with the dash column beside it. Forwards all native `<ol>` props.

| Data attribute | Description |
| --- | --- |
| data-indicator | `"visible"` once the sliding mark has an active item to sit on. |
| data-indicator-motion | Present once the mark may animate, so it never slides in on load. |

| CSS variable | Description |
| --- | --- |
| --toc-indicator-y | The mark's offset from the top of the list (line, progress, pill). |
| --toc-indicator-h | The mark's height; on progress it runs to the bottom of the active row. |
| --toc-rest-w | The dash column's width, the corner the minimap panel grows from. |
| --toc-rest-h | The dash column's height, the corner the minimap panel grows from. |

### TableOfContentsItem

One link in its `<li>`. The active item carries `aria-current="location"`. Forwards all native `<a>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| href* | string | - | `#` plus the heading's id, which the spy watches. A link that leaves the page is shown but not spied. |
| level | 2 \| 3 | 2 | A section, or a subsection that steps in under its parent. |

| Data attribute | Description |
| --- | --- |
| data-level | `"2"` or `"3"`. |

### useHeadings

`useHeadings(selector?, key?)` reads the matching headings from the DOM as `{ id, text, level }[]`. Levels are relative to the shallowest heading found; returns `[]` on the server and the first render.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| selector | string | "h2[id], h3[id]" | The headings to read. |
| key | unknown | - | Read again when it changes, e.g. the pathname in a persistent layout. |

### useScrollSpy

`useScrollSpy(ids, options?)` returns the id of the section being read, for a nav of your own. Starts on the first id.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| ids* | readonly string[] | - | The heading ids to watch, in document order. |
| container | React.RefObject<HTMLElement \| null> | - | Option: a scroll pane to watch instead of the window. |

### tableOfContentsVariants

The `tv` recipe behind every part, for styling a nav of your own to match.

## 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/tablet-frame.md -->

# Tablet Frame

A device that floats over a game or a full-bleed canvas. A 16:10 screen centered over everything, that closes without losing its state and lowers out of the way to show what is behind it.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Installation

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

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

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

Pro: `tablet-frame` comes with a [Koala UI Pro license](https://www.koalaui.com/pro). Its source is not published in these docs.

## Usage

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Anatomy

```tsx
import { TabletFrame, TabletFrameScreen } from "@/components/ui/tablet-frame"

<TabletFrame>
  <TabletFrameScreen />
</TabletFrame>
```

## Open and closed

`open` (true by default) shows the device. Closing it fades it out with a small drop, but never unmounts it: the tree stays mounted and laid out, so a form keeps what was typed, a map keeps its size and a tab keeps its scroll. While closed it is `inert`, so focus and the accessibility tree leave with the picture. Type a note, close the tablet and open it again.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Lowered

`lowered` drops the device by 80% of its own height, so its top edge stays in view as a handle, the way a player lowers a tablet to look at the street. Wire it to a held key or button: it eases down while held and back up on release. The drop is a share of the screen, not of the window, so it reads the same in any container.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Scaling

The screen is `112.5rem × 70.3125rem`, 1800 by 1125 at 16px, and below that it narrows with the window to keep a 1rem margin. To fill a share of any display, scale the root font size: the device, its text and its spacing grow and shrink together, and every popover, menu and tooltip stays on its trigger, which a CSS `zoom` on the device would not do.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Inside a container

The frame is `fixed` over the window. To preview it inside a box (a docs page, a storybook, a marketing shot), give the box a `transform`: it becomes the containing block, and the frame centers in it. Size the screen to the box with `className`; it keeps its 16:10 ratio. Every example on this page is built this way.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## API reference

### TabletFrame

The layer: `fixed inset-0`, transparent to the pointer, centering the screen. Closed, it is `inert`. Every div prop is forwarded; `className` is merged last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| open | boolean | true | Shows the device. Closed, it fades with a small drop and stays mounted, so its tree keeps its state. |
| lowered | boolean | false | Drops the device by 80% of its own height, so its top edge stays in view as a handle. |
| className | string | - | Merged last onto the layer. |

| Data attribute | Description |
| --- | --- |
| data-slot | `"tablet-frame"`. |
| data-state | `"open"` or `"closed"`. |
| data-open | `true` or `false`, mirroring `open`. |
| data-lowered | Present while lowered. |

### TabletFrameScreen

The device: a 16:10 column that clips its content to `rounded-2xl`, on the app canvas (`bg-canvas`, declared as `--surface`). A docked `Layout` fits it concentrically. Every div prop is forwarded.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| className | string | - | Merged last, so a `w-*` resizes the device at the same ratio. |

| Data attribute | Description |
| --- | --- |
| data-slot | `"tablet-frame-screen"`. |

| CSS variable | Description |
| --- | --- |
| --surface | Set to `var(--canvas)`, the floor a docked `Layout` sits on. |

## FAQ

### Can players still click the game around the device?

Yes. The frame's layer lets the pointer through; only the screen takes clicks. When it is lowered, everything above its top edge belongs to the game again.

### Why does closing not unmount the tablet?

Because reopening should land where the player left: the same app, the same scroll, the same half-typed report. It stays mounted and laid out, hidden and inert. Unmount it yourself if you want a fresh start.

### Why rem and not zoom?

Popovers, menus, selects and tooltips render into document.body, outside the device. A zoom on the device moves its triggers but not those layers; a scaled rem moves both.

### Does it work in a game's embedded browser?

Yes, down to older Chromium shells. It is a fixed layer, a 16:10 box sized with min() and vh, and transitions on opacity and transform: nothing depends on container queries, :has() or the standalone translate and scale properties.

### What happens under reduced motion?

Opening, closing and lowering happen at once, without the transition.

---

<!-- 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>
  )
}
```

## Anatomy

```tsx
import {
  Tabs,
  TabsList,
  TabsTrigger,
  TabsTriggerIcon,
  TabsPanels,
  TabsContent,
} from "@/components/ui/tabs"

<Tabs>
  <TabsList>
    <TabsTrigger>
      <TabsTriggerIcon icon={…} />
    </TabsTrigger>
  </TabsList>
  <TabsPanels>
    <TabsContent />
  </TabsPanels>
</Tabs>
```

## Segmented (default)

The iOS segmented control: a padded rounded-rect track with equal-width segments, and a hairline between resting segments that fades out beside the selected one.

```tsx
<Tabs defaultValue="overview">
  <TabsList>
    <TabsTrigger value="overview">Overview</TabsTrigger>
    <TabsTrigger value="activity">Activity</TabsTrigger>
    <TabsTrigger value="settings">Settings</TabsTrigger>
  </TabsList>
  …
</Tabs>
```

## Pill

A pill trough with the thumb sliding inside it, sized to each label rather than shared equally. It is also the rail a vertical Tabs stands as when no variant is named.

```tsx
<Tabs defaultValue="overview" variant="pill">
  <TabsList>
    <TabsTrigger value="overview">Overview</TabsTrigger>
    <TabsTrigger value="activity">Activity</TabsTrigger>
    <TabsTrigger value="settings">Settings</TabsTrigger>
  </TabsList>
  …
</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, PencilSimple as PencilSimpleLine, Money } from "koala-icons"
<Tabs defaultValue="home" variant="chip">
  <TabsList>
    <TabsTrigger value="home"><House />Home</TabsTrigger>
    <TabsTrigger value="blog"><PencilSimpleLine />Blog article</TabsTrigger>
    <TabsTrigger value="pricing"><Money />Pricing</TabsTrigger>
  </TabsList>
  …
</Tabs>
```

## Icons

```tsx
import { House, Pulse as ActivityIcon, GearSix as Gear } from "koala-icons"
<Tabs defaultValue="overview">
  <TabsList>
    <TabsTrigger value="overview"><House />Overview</TabsTrigger>
    <TabsTrigger value="activity"><ActivityIcon />Activity</TabsTrigger>
    <TabsTrigger value="settings"><Gear />Settings</TabsTrigger>
  </TabsList>
  …
</Tabs>
```

## Selected icon

`TabsTriggerIcon` lets the glyph mark the selection: the tab's own icon at rest, a filled check once it is the chosen one. Both stay mounted and cross-fade (opacity, scale and blur) on the trigger's state, so a quick switch back reverses mid-way instead of restarting. The check is the label's ink, not brand. Pass `activeIcon` for another mark. It suits a filter rail, where the selected chip says what the grid below is showing.

```tsx
import { House, PencilSimple as PencilSimpleLine, Money } from "koala-icons"
<Tabs defaultValue="home" variant="chip">
  <TabsList>
    <TabsTrigger value="home">
      <TabsTriggerIcon icon={<House />} />
      Home
    </TabsTrigger>
    <TabsTrigger value="blog">
      <TabsTriggerIcon icon={<PencilSimpleLine />} />
      Blog article
    </TabsTrigger>
    <TabsTrigger value="pricing">
      <TabsTriggerIcon icon={<Money />} />
      Pricing
    </TabsTrigger>
  </TabsList>
  …
</Tabs>
```

## Density

Tabs ship at one tight size (a 14px label in a 28px-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>
```

## API reference

### Tabs

The root, Radix `Tabs.Root`; shares the variant and density with every part. Forwards all Radix `Root` props; every part accepts `className`, merged last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| defaultValue | string | - | The tab selected on mount, when uncontrolled. |
| value | string | - | The selected tab, when controlled. |
| onValueChange | (value: string) => void | - | Called when the selected tab changes. |
| variant | "segmented" \| "pill" \| "folder" \| "line" \| "chip" | "segmented" (vertical: "pill") | iOS-style padded segmented control with equal-width segments, pill trough, filled tab over a sliding bar, bare sliding underline, or separate outlined chips with no indicator. |
| density | "comfortable" \| "compact" | "compact" | Tightens the pill trough and the concentric radii; the label size stays. Falls back to the nearest `DensityProvider`. |
| orientation | "horizontal" \| "vertical" | "horizontal" | `vertical` stands the rail beside the panel, with up and down arrow keys. |
| activationMode | "automatic" \| "manual" | "automatic" | Whether a tab is selected on focus or only on click and Enter. |
| dir | "ltr" \| "rtl" | - | Reading direction for arrow-key navigation. |

| Data attribute | Description |
| --- | --- |
| data-orientation | `"horizontal"` or `"vertical"`. |

### TabsList

The row of triggers, Radix `Tabs.List`, with the sliding indicator inside. Scrolls sideways with an edge fade when the tabs overflow; pass `flex-wrap` to wrap instead. Forwards all Radix `List` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| loop | boolean | true | Whether arrow keys wrap from the last tab to the first. |

| Data attribute | Description |
| --- | --- |
| data-orientation | `"horizontal"` or `"vertical"`. |

### TabsTrigger

One tab, Radix `Tabs.Trigger` rendering a `<button>`. A nested svg is sized to 16px (20px in `chip`). Forwards all Radix `Trigger` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| value* | string | - | Pairs the trigger with the `TabsContent` of the same value. |
| disabled | boolean | false | Skips the tab in keyboard navigation and blocks selection. |
| asChild | boolean | false | Merge onto your own element instead of rendering a `<button>`. |

| Data attribute | Description |
| --- | --- |
| data-state | `"active"` or `"inactive"`. |
| data-orientation | `"horizontal"` or `"vertical"`. |
| data-disabled | Present when disabled. |

### TabsTriggerIcon

A glyph that marks the selection: the tab's icon at rest, cross-fading to a check once selected. Decorative (`aria-hidden`). Forwards all native `<span>` props except `children`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| icon* | React.ReactNode | - | The tab's own glyph, shown while it is not selected. |
| activeIcon | React.ReactNode | <CheckCircle weight="fill" /> | The glyph once the tab is selected. |

### TabsPanels

Optional wrapper that eases its height to the incoming panel instead of snapping. It clips, so leave out panels that paint outside their box or grow without a ceiling. Forwards all native `<div>` props.

| Data attribute | Description |
| --- | --- |
| data-morph-ready | Present once the first height is measured; arms the transition. |

### TabsContent

One panel, Radix `Tabs.Content`; fades up when it becomes active. Forwards all Radix `Content` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| value* | string | - | Pairs the panel with the `TabsTrigger` of the same value. |
| forceMount | true | - | Keep the panel mounted while inactive, e.g. to animate it yourself. |

| Data attribute | Description |
| --- | --- |
| data-state | `"active"` or `"inactive"`. |
| data-orientation | `"horizontal"` or `"vertical"`. |

### tabsVariants

The `tv` recipe behind every part, for styling a rail of your own to match.

## 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, segmented, folder, line, and chip variants?

`segmented` (the default) is the iOS control: a padded rounded-rect track, equal-width segments and hairlines between the resting ones. `pill` is a pill trough whose thumb sizes to each label, and the rail a vertical Tabs falls back to. `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 ink 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 28px-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 Koala 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/terminal.md -->

# Terminal

A command line for your app: a title bar, a monospace scrollback and a prompt with ghost completion and a block cursor. Presentational parts on the theme's tokens; your app runs the commands, so it fits a dev console, a search console or a REPL alike.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Installation

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

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

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

Pro: `terminal` comes with a [Koala UI Pro license](https://www.koalaui.com/pro). Its source is not published in these docs.

## Usage

The parts paint; the loop is yours. A working shell is a list of lines, the text being typed, and a key handler that turns Enter into output.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Anatomy

```tsx
import {
  Terminal,
  TerminalBar,
  TerminalCaption,
  TerminalCaptionButton,
  TerminalControls,
  TerminalField,
  TerminalIndicator,
  TerminalInputLine,
  TerminalLine,
  TerminalPrompt,
  TerminalScreen,
  TerminalTab,
  TerminalTitle,
  TerminalTitleTag,
  TerminalTray,
  TerminalWatermark,
} from "@/components/ui/terminal"

<Terminal>
  {/* A faint stamp behind the scrollback */}
  <TerminalWatermark />
  {/* The title bar, and the drag handle */}
  <TerminalBar>
    {/* A tab, or the indicator and title straight in the bar */}
    <TerminalTab>
      <TerminalIndicator />
      <TerminalTitle>
        <TerminalTitleTag />
      </TerminalTitle>
    </TerminalTab>
    <TerminalControls />
    {/* Minimize, maximize, close: flush in the corner */}
    <TerminalCaption>
      <TerminalCaptionButton action="minimize" />
    </TerminalCaption>
  </TerminalBar>
  {/* The scrollback, a ScrollArea */}
  <TerminalScreen>
    <TerminalLine />
    <TerminalInputLine>
      <TerminalPrompt />
      <TerminalField />
    </TerminalInputLine>
  </TerminalScreen>
  {/* Live results, suggestions, a status line */}
  <TerminalTray />
</Terminal>
```

## Line tones

`tone` sets a line's ink. `in` is a command that was run, in the foreground ink; `out` (the default) and `raw` are output in the reading ink; `dim` is a comment in the meta grey; `err` and `ok` take the status hues' text step, which still reads on the light themes.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Clickable lines

Give a line `onClick` and it becomes a button: focusable, run by a click, Enter or Space, with a highlight that keeps the text on its column. For search results, a file listing, or a `#N` the user would otherwise have to type.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Prompt, completion and cursor

`TerminalPrompt` takes a `prefix` and a `mark` (`"> "` by default). `TerminalField` paints what is typed and a block cursor at the caret: it follows the arrow keys and sits over the character it is on. `ghost` is the grey completion after it; accepting it is your key handler's job (Tab or → here, at the end of the line). The cursor is a solid block while the field has focus and a hollow cell when it doesn't; drive `cursorVisible` from a timer to make it blink.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

A blink that restarts lit on every keystroke, and holds still under reduced motion:

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Tray

`TerminalTray` is the band under the scrollback, on a quieter tint: live results while the user types, suggestions, a status line. It holds Koala components (a `Badge`, a `Kbd`, a `Command` list) or clickable `TerminalLine`s, as here.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Window chrome

`TerminalBar` carries the `TerminalIndicator`, a `TerminalTitle` (with an optional `TerminalTitleTag`), `TerminalControls` for your own 32px buttons, and `TerminalCaption`: Windows' minimize, maximize and close, 46px wide and flush in the corner, close going red on hover. What they do is yours: here they minimize, widen and close the window, and a double-click on the bar widens it too. `movable` gives the bar a grab cursor and `dragging` holds the grabbing one while your pointer handlers move the window. `TerminalWatermark` lays a faint stamp behind the scrollback.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## API reference

### Terminal

The surface, a `div`: a Windows-style window (8px corners, popover fill, the lg shadow) every part reads its styles from. Every part is optional but the root. Forwards every `div` prop; every part merges `className` last. `terminalVariants` is the recipe.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| movable | boolean | false | The bar shows a grab cursor. Moving the window is your pointer handler on `TerminalBar`. |
| dragging | boolean | false | The grabbing cursor, and no text selection while it lasts. |

| Data attribute | Description |
| --- | --- |
| data-slot | `"terminal"`. |

| CSS variable | Description |
| --- | --- |
| --surface | Set to `var(--popover)`, so controls nested inside paint the panel's ground. |

### TerminalBar

The title bar, a `div`, and the drag handle: hang `onPointerDown` on it. Drop it for a console embedded in a page.

| Data attribute | Description |
| --- | --- |
| data-slot | `"terminal-bar"`. |

### TerminalTab

A tab in the title bar, a `div`, the way Windows Terminal draws one: put a `TerminalIndicator` and a `TerminalTitle` inside. The open tab merges into the screen below it.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| active | boolean | true | The open tab: the screen's fill and a hairline frame. Inactive tabs sit back in the strip in muted ink. |

| Data attribute | Description |
| --- | --- |
| data-slot | `"terminal-tab"`. |
| data-active | The `active` prop. |

### TerminalIndicator

The live dot before the title, a decorative `span` (`aria-hidden`).

| Data attribute | Description |
| --- | --- |
| data-slot | `"terminal-indicator"`. |

### TerminalTitle

The title, a `span` that ends a long title in an ellipsis.

| Data attribute | Description |
| --- | --- |
| data-slot | `"terminal-title"`. |

### TerminalTitleTag

The title's secondary label, a `span` after a middle dot. Goes inside `TerminalTitle`.

| Data attribute | Description |
| --- | --- |
| data-slot | `"terminal-title-tag"`. |

### TerminalControls

The window buttons at the end of the bar, a `div`. Controls inside default to the `sm` tier (32px); an explicit `size` still wins.

| Data attribute | Description |
| --- | --- |
| data-slot | `"terminal-controls"`. |
| data-control-size | `"sm"`. |

### TerminalCaption

The window buttons, a `div` flush in the bar's top-right corner: the window's corner clips the last button's fill. Goes last in `TerminalBar`, after `TerminalControls` if there are any.

| Data attribute | Description |
| --- | --- |
| data-slot | `"terminal-caption"`. |

### TerminalCaptionButton

A 46 by 40 window button, a `button` with the Windows hairline glyph and an `aria-label` from its action (override either). Wire `onClick` yourself: the window geometry is your app's.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| action* | "minimize" \| "maximize" \| "restore" \| "close" | - | Which button: its glyph and its label. `close` fills red on hover. The type is exported as `TerminalCaptionAction`. |
| children | React.ReactNode | - | Replaces the glyph. |

| Data attribute | Description |
| --- | --- |
| data-slot | `"terminal-caption-button"`. |
| data-action | The `action` prop. |

### TerminalScreen

The scrollback, on `ScrollArea`: takes its props but the axis (`orientation` and `draggable` are left out). Its content is a `role="log"`, so assistive tech announces new lines.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| fade | boolean | false | Fades the edge that still has content beyond it. |
| viewportRef | React.Ref<HTMLDivElement> | - | The scrolling element itself: use it to keep the scrollback at the bottom. |
| type | "auto" \| "always" \| "scroll" \| "hover" | "hover" | When the scrollbars show, as on `ScrollArea`. |

| Data attribute | Description |
| --- | --- |
| data-slot | `"terminal-screen"`, on the log inside the scroller. |

### TerminalWatermark

A faint stamp behind the scrollback (a logo, a seal), a decorative `img` (`aria-hidden`, not draggable). Set its opacity with `style`. Forwards every `img` prop.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| alt | string | "" | Empty by default: the image is decorative. |

| Data attribute | Description |
| --- | --- |
| data-slot | `"terminal-watermark"`. |

### TerminalLine

One line of the scrollback, a `div` that wraps long text. It needs no `Terminal` around it. `terminalLineVariants({ tone, interactive, className })` returns a line's classes for your own markup.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| tone | "in" \| "out" \| "err" \| "ok" \| "dim" \| "raw" | "out" | The line's ink. The type is exported as `TerminalTone`. |
| onClick | (e: React.MouseEvent<HTMLDivElement> \| React.KeyboardEvent<HTMLDivElement>) => void | - | Makes the line a `role="button"` in the tab order, run by click, Enter or Space. |

| Data attribute | Description |
| --- | --- |
| data-slot | `"terminal-line"`. |
| data-tone | The line's `tone`. |

### TerminalInputLine

The prompt row, a `div`: the prompt and the field on one baseline. Keep it last in the screen so the prompt scrolls with the output, the way a shell does.

| Data attribute | Description |
| --- | --- |
| data-slot | `"terminal-input-line"`. |

### TerminalPrompt

The prompt, a `span`: the prefix in full-weight ink, then the mark.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| prefix* | React.ReactNode | - | What comes before the mark: the system, the host, the unit. |
| mark | React.ReactNode | "> " | The prompt mark. Keep its trailing space. |

| Data attribute | Description |
| --- | --- |
| data-slot | `"terminal-prompt"`, with `terminal-prompt-prefix` and `terminal-prompt-mark` inside. |

### TerminalField

The prompt's field: painted text with a block cursor at the caret, under a transparent `<input>` that takes the keyboard. Every input prop goes to that input, `className` and `ref` included; spellcheck, autocomplete, autocapitalize and autocorrect are off unless you turn them on.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| value* | string | - | The controlled text. |
| ghost | string | - | The grey completion painted after the caret when it is at the end. Your key handler accepts it, usually on Tab. |
| cursorVisible | boolean | true | The blink beat while focused: drive it from a timer to blink, leave it `true` for a steady cursor. Out of focus the cursor is a still, hollow cell. |
| placeholder | string | - | Painted in the ghost's grey while the field is empty. |

| Data attribute | Description |
| --- | --- |
| data-slot | `"terminal-field"` on the wrapper, `"terminal-input"` on the input, `"terminal-cursor"` on the cursor. |
| data-visible | On the cursor: the `cursorVisible` beat. |

### TerminalTray

The band under the scrollback, a `div`: live results, suggestions, a status line. Drop it when nothing runs live.

| Data attribute | Description |
| --- | --- |
| data-slot | `"terminal-tray"`. |

## FAQ

### Terminal or Command?

Command filters a fixed list and runs the row you pick. Terminal runs whatever is typed and keeps a transcript. They combine: a Command list in the tray makes a fine live preview.

### Terminal or Code Snippet?

A transcript nobody types into is a Code Snippet with a shell listing. Reach for Terminal when the prompt is live.

### Does it run commands or parse input?

No. It paints. Your key handler decides what Enter, Tab and the arrows do, and your state holds the lines, which is what lets the same parts serve a dev console, a search console or a REPL.

### Why doesn't the cursor blink on its own?

The blink is a beat your app owns: pass cursorVisible from a timer, relight it on each keystroke and hold it still under reduced motion (the snippet above does all three). Left alone it is steady, which is also what an unfocused terminal shows.

### How do I keep the scrollback at the bottom?

Pass viewportRef to TerminalScreen and set scrollTop to scrollHeight when your lines change. To follow a tray opening under it, watch the viewport with a ResizeObserver and only follow while the reader is already at the bottom.

### Does it trap the Tab key?

Only if your handler does. Claim Tab when there is a completion to accept and let it through otherwise, so a keyboard user can always leave the terminal.

---

<!-- 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>
  )
}
```

## Anatomy

```tsx
import {
  TextareaRoot,
  TextareaField,
  TextareaFooter,
  TextareaCount,
  TextareaLabel,
  TextareaHint,
} from "@/components/ui/textarea"

<TextareaLabel />
<TextareaRoot>
  <TextareaField />
  <TextareaFooter>
    <TextareaCount current={0} />
  </TextareaFooter>
</TextareaRoot>
<TextareaHint />
```

## 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 outside a `Form` or compact density), 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 sits in the corner of the bordered box, level with the counter, inside the rounded edge.

```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>
```

## API reference

### TextareaRoot

The bordered surface; shares size, error and disabled state with every part through context. Forwards all native `<div>` props; every part accepts `className`, merged last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| size | "sm" \| "md" \| "lg" | "md" | Padding, text and minimum height. Unset, it follows a surrounding `Form`, then the ambient density (compact resolves to `sm`). |
| density | "comfortable" \| "compact" | - | Picks the default `size` (compact to `sm`, comfortable to `md`); an explicit `size` wins. |
| resize | "none" \| "vertical" \| "horizontal" \| "both" | "vertical" | The corner drag handle and the axis it resizes. `autoResize` on the field hides it. |
| hasError | boolean | false | Destructive border and focus ring, and `aria-invalid` on the field. Inherited from a surrounding `Field` when omitted. |
| disabled | boolean | false | Dims the root and disables the field. Inherited from a surrounding `Field` when omitted. |

| Data attribute | Description |
| --- | --- |
| data-disabled | Present when the textarea is disabled. |
| data-error | Present when the textarea is in the error state. |

| CSS variable | Description |
| --- | --- |
| --surface | Read for the field's opaque fill, so it matches the container; falls back to `--background`. |

### TextareaField

The `<textarea>` itself. Inside a `Field` it adopts the field's `id` and `aria-describedby`. Forwards all native `<textarea>` props, including `ref`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| autoResize | boolean | false | Grows to fit the content (CSS `field-sizing: content`, with a `scrollHeight` fallback) and pins resize to `none`. |
| showCount | boolean | false | Renders a `TextareaFooter` with a `TextareaCount` below the field, controlled or uncontrolled. Add `maxLength` to show `current / max`. |

### TextareaFooter

A row inside the border, below the field, for a note and a counter. Forwards all native `<div>` props.

### TextareaCount

A `tabular-nums` character counter, announced politely. Forwards all native `<span>` props except `children`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| current* | number | - | The current character count. |
| max | number | - | Optional limit, rendered as `current / max`; the count turns destructive once exceeded. |

| Data attribute | Description |
| --- | --- |
| data-over | Present when `current` exceeds `max`. |

### TextareaLabel

The shared `Label` primitive, placed above the root. Inside a `Field` it adopts the `id`, `required` and `disabled`. Forwards all native `<label>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| required | boolean | false | Appends a destructive asterisk with an sr-only "(required)". |
| disabled | boolean | false | Dims the label. |

### TextareaHint

The shared `Hint` primitive: helper or error text below the root. Inside a `Field` it adopts the hint `id`. Forwards all native `<p>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| hasError | boolean | false | Switches to the destructive tone. Inherited from a surrounding `Field` when omitted. |

## 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, every size switches 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 at the bottom of the screen. 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 stack
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 fight the page. 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." })
```

## Minimal

`appearance: "minimal"` trims the card to one compact row: a smaller icon, a medium-weight title and the action inline on the right. The close button rests hidden and appears on hover or focus; swipe or Esc still dismiss it. Set it on a single toast, or on `<Toaster appearance="minimal" />` to make it the default for the whole app.

```tsx
toast("Changes saved.", { appearance: "minimal" })
toast.success("Link copied to clipboard.", { appearance: "minimal" })
toast("Conversation archived.", {
  appearance: "minimal",
  action: { label: "Undo", onClick: restore },
})

// Or for every toast
<Toaster appearance="minimal" />
```

## Countdown

`countdown: true` draws a hairline along the bottom edge that drains across the toast's `duration`, in the variant's colour. It pauses whenever the toast does (hover, focus, or the window losing focus), so it always shows the time that is really left. Most useful on an Undo toast, where the window to act matters.

```tsx
toast("Message deleted.", {
  appearance: "minimal",
  countdown: true,
  duration: 8000,
  action: { label: "Undo", onClick: restore },
})

// Or for every toast
<Toaster countdown />
```

## Progress

Pass `progress` (0 to 100) for work you can measure, and raise the same `id` as it advances: the bar slides to the new value without the pop a re-raise usually plays, and the title stays put. Raise the result without `progress` when the work is done.

```tsx
const id = toast.loading("Uploading 5 files…", { progress: 0 })

onProgress((done) =>
  toast.loading("Uploading 5 files…", { id, progress: (done / 5) * 100 })
)

toast.success("Upload complete.", { id })
```

## 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 at the far bottom of the screen. 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,
})
```

## API reference

### Toaster

Renders the fixed, bottom-centered Radix Toast viewport, the anchored bubbles and a polite live region. Mount it once in the root layout. Forwards the Radix `Toast.Viewport` props and native `<ol>` props to the viewport, and `className` merges last there (move it with `bottom-6`, say). The stack keeps ownership of the viewport height; your pointer and focus handlers run alongside its expand and collapse.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| appearance | "card" \| "minimal" | "card" | Default look for every toast; a toast's own `appearance` wins. |
| countdown | boolean | false | Default for every toast: draw the draining bar along the bottom edge. |
| swipeDirection | "right" \| "left" \| "up" \| "down" | "right" | Direction a toast is swiped to dismiss it. |
| swipeThreshold | number | 50 | Distance in pixels a swipe must travel to dismiss. |
| hotkey | string[] | ["F8"] | Keys that move focus to the toast stack. |
| label | string | "Notifications ({hotkey})" | Accessible name of the viewport region; `{hotkey}` is replaced with the keys. |

| Data attribute | Description |
| --- | --- |
| data-state | On each toast: `"open"` or `"closed"` (Radix). |
| data-swipe | On each toast while swiped: `"start"`, `"move"`, `"cancel"` or `"end"` (Radix). |
| data-side | On an anchored bubble: `"top"` or `"bottom"` of its element. |

| CSS variable | Description |
| --- | --- |
| --radix-toast-swipe-move-x | Horizontal offset while a toast is being swiped; the card follows it. |
| --radix-toast-swipe-end-x | Horizontal offset where a swipe ended, for the dismiss exit. |
| --toast-duration | Set on the countdown bar: how long it takes to drain, the toast's `duration`. |

### toast()

Raises a toast from anywhere: `toast("Saved.")`, `toast("Saved.", options)` or `toast(options)`. Returns the toast's id.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| id | string | - | A stable id. Raising it again while on screen updates that toast in place and replays a pop or shake. |
| title | React.ReactNode | - | The headline. |
| description | React.ReactNode | - | Supporting text under the title. |
| variant | "default" \| "success" \| "warning" \| "destructive" \| "info" \| "loading" | "default" | The status icon. `destructive` is announced assertively, `loading` shows a spinner and persists. |
| duration | number | 5000 | Auto-dismiss delay in ms: `1500` when anchored, `Infinity` for `loading`. Pass `Infinity` to persist. |
| action | { label: string; onClick: () => void } | - | A button below the description, a Radix `Action` with the label as its `altText`. |
| appearance | "card" \| "minimal" | Toaster's | `minimal` is one compact row with the action inline and the close button revealed on hover or focus. |
| countdown | boolean | Toaster's | A hairline along the bottom edge that drains across `duration` and pauses with the toast. Ignored when the toast persists. |
| progress | number | - | 0 to 100: shows a progress bar under the text. Raise the same `id` to advance it; updates skip the pop and keep the title still. |
| anchor | HTMLElement \| null | - | Shows a small icon-and-title bubble beside this element instead of the stack (no close button, no action). Closes on scroll or resize. |

### toast.success / warning / error / info / loading

Shortcuts: `(title, options?)` with the variant set (`error` sets `destructive`). Options are the `toast()` options without `title` and `variant`. Each returns the id.

### toast.promise

`toast.promise(promise, messages, options?)`: one toast that shows `loading`, then turns into the result in place. Returns the promise, so awaiting it still yields the value or throws.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| promise* | Promise<T> \| (() => Promise<T>) | - | The work to follow. |
| messages.loading* | React.ReactNode | - | The title while pending. |
| messages.success* | ReactNode \| ToastOptions \| ((value: T) => ReactNode \| ToastOptions) | - | Shown on resolve, as a `success` toast. |
| messages.error* | ReactNode \| ToastOptions \| ((error: unknown) => ReactNode \| ToastOptions) | - | Shown on reject, as a `destructive` toast. |

### toast.dismiss

`toast.dismiss(id?)`: closes one toast by id, or every open toast when called with no id.

### useToast

Returns `{ toast, dismiss }`, the same imperative API, for use inside components.

### useToastStore

Low-level: subscribes to the queue and returns the current `ToastData[]`, for a custom renderer.

### TOAST_DURATION / ANCHORED_TOAST_DURATION

The default auto-dismiss delays in ms: `5000` for a stacked toast, `1500` for an anchored one.

## 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 bottom stack, 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 stack 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 /> Unread only
</Toggle>
<Toggle variant="ghost" iconOnly aria-label="Bookmark" defaultPressed>
  <ToggleIcon off={<BookmarkSimple />} on={<BookmarkSimple weight="fill" />} />
</Toggle>
<Toggle variant="ghost" iconOnly aria-label="Pin">
  <ToggleIcon off={<PushPin />} 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>
}
```

## Anatomy

```tsx
import { Toggle, ToggleIcon } from "@/components/ui/toggle"

<Toggle>
  <ToggleIcon off={…} on={…} />
</Toggle>
```

## Variants

`outline` (the default) is the Toggle Group pill: a framed control whose pressed state is an ink 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 /> Show grid</Toggle>
<Toggle defaultPressed><GridFour /> Show grid</Toggle>

<Toggle variant="ghost" iconOnly aria-label="Italic"><TextItalic /></Toggle>
<Toggle variant="ghost" iconOnly aria-label="Bold" defaultPressed><TextB /></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 /> Pin</Toggle>
<Toggle size="sm" iconOnly aria-label="Pin" defaultPressed><PushPin /></Toggle>
<Toggle size="md" defaultPressed><PushPin /> Pin</Toggle>
<Toggle size="md" iconOnly aria-label="Pin" defaultPressed><PushPin /></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 />} on={<BookmarkSimple weight="fill" />} />
</Toggle>
<Toggle variant="ghost" iconOnly aria-label="Like">
  <ToggleIcon off={<Heart />} on={<Heart weight="fill" className="text-destructive" />} />
</Toggle>
<Toggle variant="ghost" iconOnly aria-label="Star">
  <ToggleIcon off={<Star />} on={<Star weight="fill" className="text-warning" />} />
</Toggle>
<Toggle variant="ghost" iconOnly aria-label="Mute">
  <ToggleIcon off={<Microphone />} on={<MicrophoneSlash />} />
</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 />
    </Toggle>
  </Tooltip>
  <Tooltip content={<>Italic <Kbd size="sm">⌘I</Kbd></>}>
    <Toggle variant="ghost" size="sm" iconOnly aria-label="Italic">
      <TextItalic />
    </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 /> 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 /> Show grid</Toggle>
<Toggle disabled defaultPressed><GridFour /> Show grid</Toggle>
```

## API reference

### Toggle

A `<button>` that stays pressed, with `aria-pressed`. Forwards all Radix Toggle `Root` props; every part accepts `className`, merged last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| variant | "outline" \| "ghost" | "outline" | `outline` is the Toggle Group pill (ink border and halo when pressed); `ghost` is bare and fills with the accent chip. |
| size | "sm" \| "md" | "md" | 32px or 40px tall; `sm` grows its hit target to 40px without growing the visual. |
| iconOnly | boolean | false | Squares the control around one glyph (20px at `md`). Name it with `aria-label`. |
| pressed | boolean | - | The controlled pressed state. |
| defaultPressed | boolean | false | The initial pressed state when uncontrolled. |
| onPressedChange | (pressed: boolean) => void | - | Called when the pressed state changes. |
| disabled | boolean | false | Dims the control in either state and blocks interaction. |
| asChild | boolean | false | Renders onto its child element instead of a `<button>`. |

| Data attribute | Description |
| --- | --- |
| data-state | `"on"` while pressed, `"off"` otherwise. |
| data-disabled | Present when the toggle is disabled. |

### ToggleIcon

Two glyphs in one cell that cross-fade on the surrounding `Toggle`'s state; decorative (`aria-hidden`), so it only works inside a `Toggle`. Forwards all native `<span>` props except `children`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| off* | React.ReactNode | - | The glyph at rest. |
| on* | React.ReactNode | - | The glyph while pressed, usually the same icon in its `fill` weight. |

## 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 ink 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>
  )
}
```

## Anatomy

```tsx
import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group"

<ToggleGroup type="single">
  <ToggleGroupItem value="…" />
</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 ink 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>
```

## API reference

### ToggleGroup

The group root, with roving focus across its items. Forwards all Radix ToggleGroup `Root` props, including `ref`; every part accepts `className`, merged last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| type* | "single" \| "multiple" | - | `single` holds one value (clicking the chosen item clears it); `multiple` toggles each item independently. |
| value | string \| string[] | - | The controlled value: a `string` for `single`, a `string[]` for `multiple`. |
| defaultValue | string \| string[] | - | The initial value when uncontrolled. |
| onValueChange | (value: string) => void \| (value: string[]) => void | - | Called when the selection changes, with the shape matching `type`. |
| variant | "outline" \| "segmented" \| "ghost" | "outline" | Free-standing pills with an ink outline, one muted track with a sliding thumb, or bare labels with an underline. |
| size | "sm" \| "md" | "md" | 32px or 40px items, shared with every item through context. |
| disabled | boolean | false | Disables every item. |
| rovingFocus | boolean | true | Arrow keys move focus between items. |
| loop | boolean | true | Arrow-key focus wraps from the last item to the first. |
| orientation | "horizontal" \| "vertical" | - | The arrow keys roving focus listens to; it does not change the layout. |

| Data attribute | Description |
| --- | --- |
| data-orientation | The `orientation`, when set. |
| data-thumb | `segmented` only: `"on"` while the sliding thumb shows (exactly one item on), `"off"` when items paint their own lift. |

| CSS variable | Description |
| --- | --- |
| --surface | Read by `outline` items for their fill, so they blend into the container; falls back to `--background`. |

### ToggleGroupItem

One pressable pill. Forwards all Radix ToggleGroup `Item` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| value* | string | - | The item's value in the group. |
| disabled | boolean | false | Disables this item. |
| iconOnly | boolean | false | A square pill around one glyph (20px at `md`). Name it with `aria-label` or a string `tooltip`. |
| tooltip | React.ReactNode \| false | - | A hint on hover and focus; defaults to the `aria-label` on an `iconOnly` item, and a string names an unlabelled one. `false` opts out. |
| tooltipPlacement | TooltipProps["placement"] | "top" | Where the tooltip sits. |

| Data attribute | Description |
| --- | --- |
| data-state | `"on"` while selected, `"off"` otherwise. |
| data-disabled | Present when the item is disabled. |
| data-orientation | The group's `orientation`, when set. |

## 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 an ink outline plus a soft ink 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Installation

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

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

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

Pro: `toolbar` comes with a [Koala UI Pro license](https://www.koalaui.com/pro). Its source is not published in these docs.

## Usage

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Anatomy

```tsx
import {
  Toolbar,
  ToolbarGroup,
  ToolbarTitle,
  ToolbarButton,
  ToolbarToggleGroup,
  ToolbarToggleItem,
  ToolbarSeparator,
  ToolbarLink,
  ToolbarSpacer,
} from "@/components/ui/toolbar"

<Toolbar>
  <ToolbarTitle />
  <ToolbarGroup>
    <ToolbarButton />
  </ToolbarGroup>
  <ToolbarSeparator />
  <ToolbarToggleGroup type="multiple">
    <ToolbarToggleItem value="..." />
  </ToolbarToggleGroup>
  <ToolbarSpacer />
  <ToolbarLink />
</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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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).

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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).

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## API reference

### Toolbar

The band, with one Tab stop and arrow keys between controls. Wraps its children in a `TooltipGroup`, so every tooltip shares one gliding bubble. Forwards all Radix Toolbar `Root` props (`loop`, `dir`, ...); every part accepts `className`, merged last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| variant | "floating" \| "outline" \| "plain" \| "solid" | "floating" | The band's surface: a popover card, a bordered card, nothing, or inverted ink for overlays. |
| size | "sm" \| "md" \| "lg" | "md" | Control size (24, 28 or 36px). The toolbar's own axis: it does not read the page's `comfortable` / `compact` density. |
| orientation | "horizontal" \| "vertical" | "horizontal" | Drives both the layout and the arrow-key axis. |
| scrollable | boolean | false | Scrolls on its axis with a scroll-aware edge fade instead of wrapping when the controls overflow. |
| aria-label | string | "Toolbar" | Names the toolbar for assistive tech; set something specific. |

| Data attribute | Description |
| --- | --- |
| data-orientation | `horizontal` or `vertical` (Radix). |

| CSS variable | Description |
| --- | --- |
| --surface | Set to the band's own ground on `floating`, `outline` and `solid`, so nested controls blend with it. |

### ToolbarButton

An icon control. Lights its chip while it is the open trigger of a menu or popover. Forwards all Radix Toolbar `Button` props except `aria-pressed`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| pressed | boolean | - | Marks the control active (the filled chip) and sets `aria-pressed`. |
| variant | "default" \| "primary" | "default" | `primary` fills the control with the brand: the one action the bar exists for. |
| caret | boolean | false | Appends a chevron that flips while open and lets the control grow to fit a label: the dropdown trigger look. |
| tooltip | ReactNode | - | Hover and focus hint, shared with the bar's gliding bubble. A plain string also becomes the `aria-label` when none is set. |
| shortcut | string | - | A keycap shown as a `Kbd` chip in the tooltip (display only, e.g. `"⌘B"`). |
| tooltipPlacement | Placement | "top" | Where the tooltip opens. |
| static | boolean | false | Kept for compatibility; controls no longer scale on press. |
| asChild | boolean | false | Renders the child element instead, e.g. a menu or popover trigger. |

| Data attribute | Description |
| --- | --- |
| data-pressed | Present while `pressed` is true. |
| data-variant | `primary` on the primary control. |
| data-state | `open` while it is the open trigger of a menu or popover. |

### ToolbarToggleGroup

A cluster of controls that hold a pressed state, with `type="single" | "multiple"` and `value` / `onValueChange`. Forwards all Radix Toolbar `ToggleGroup` props.

### ToolbarToggleItem

A pressable control inside `ToolbarToggleGroup`. Forwards all Radix Toolbar `ToggleItem` props (`value` is required).

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| tooltip | ReactNode | - | Hover and focus hint, shared with the bar's gliding bubble. A plain string also becomes the `aria-label` when none is set. |
| shortcut | string | - | A keycap shown as a `Kbd` chip in the tooltip (display only, e.g. `"⌘B"`). |
| tooltipPlacement | Placement | "top" | Where the tooltip opens. |
| static | boolean | false | Kept for compatibility; controls no longer scale on press. |

| Data attribute | Description |
| --- | --- |
| data-state | `on` or `off`. |
| data-disabled | Present when disabled. |

### ToolbarSeparator

A hairline between groups; it turns horizontal in a vertical toolbar. Forwards all Radix Toolbar `Separator` props.

| Data attribute | Description |
| --- | --- |
| data-orientation | The separator's own axis, perpendicular to the toolbar (Radix). |

### ToolbarLink

A text link that lives in the bar and keeps the roving focus. Forwards all Radix Toolbar `Link` props.

### ToolbarGroup

A `role="group"` cluster; give it an `aria-label`. Forwards all native `<div>` props.

### ToolbarTitle

A non-interactive label, truncated to one line. Forwards all native `<div>` props.

### ToolbarSpacer

A flexible gap that pins the controls after it to the end. Forwards all native `<div>` props.

### ToolbarOverflow

A horizontal toolbar that shows as many controls as fit and folds the rest into a trailing three-dots menu, remeasuring on resize. Takes every `Toolbar` prop except `children`, `orientation` and `scrollable`; `className` lands on the full-width track around the bar.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| items* | ToolbarOverflowItem[] | - | The controls in order, each rendered as a bar button and as a menu row. See the item shapes below. |
| overflowLabel | string | "More" | Tooltip and accessible name of the overflow trigger; the hidden count is appended to the name. |
| menuAlign | "start" \| "center" \| "end" | "end" | Which edge the overflow menu aligns to. |

### ToolbarOverflowItem

A type: one of three descriptors. Every item takes an `id: string`; a separator is `{ type: "separator", id }` and is dropped when it would dangle in the menu.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| type* | "action" \| "toggle" \| "separator" | - | `action` is a one-shot command; `toggle` holds a pressed state (a lit chip in the bar, a checkbox row in the menu). |
| icon* | Icon | - | A Koala icon component (actions and toggles). |
| label* | string | - | The tooltip, the accessible name and the menu row text. |
| shortcut | string | - | Shown in the tooltip and, for actions, at the end of the menu row. |
| disabled | boolean | - | Disables the control in both places. |
| onSelect | () => void | - | Action only: runs on click or menu select. |
| destructive | boolean | - | Action only: styles the menu row as destructive. |
| pressed | boolean | - | Toggle only: the pressed state. |
| onPressedChange | (pressed: boolean) => void | - | Toggle only: fires with the next pressed state. |

## 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 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 "koala-icons"
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>
  )
}
```

## Anatomy

```tsx
import {
  Tooltip,
  TooltipGroup,
  TooltipHeader,
  TooltipHeaderText,
  TooltipTitle,
  TooltipDescription,
  TooltipValue,
  TooltipSeparator,
  TooltipSection,
  TooltipStat,
} from "@/components/ui/tooltip"

<TooltipGroup>
  <Tooltip content="...">
    <button />
  </Tooltip>
</TooltipGroup>

<Tooltip
  variant="graph"
  content={
    <>
      <TooltipHeader>
        <TooltipHeaderText>
          <TooltipTitle />
          <TooltipDescription />
        </TooltipHeaderText>
        <TooltipValue />
      </TooltipHeader>
      <TooltipSeparator />
      <TooltipSection>
        <TooltipStat label="..." value="..." />
      </TooltipSection>
    </>
  }
>
  <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`.

## Around an icon-only Button

An `iconOnly` Button already shows its `aria-label` as a tooltip. Wrap it in your own `Tooltip` (for a keycap, a longer hint, another placement) and the Button's hint stands down, so there is one bubble, never one above and one below. The same holds through an `asChild` trigger such as `PopoverTrigger`, for any button inside the wrapped element, and for the hints other components add on their own (ToggleGroupItem, ToolbarButton, DockItem, SidebarItem, SelectItem). No `tooltip={false}` needed.

```tsx
<Tooltip content={<>Search <Kbd size="sm">⌘K</Kbd></>}>
  <Button variant="outline" iconOnly aria-label="Search">
    <MagnifyingGlass />
  </Button>
</Tooltip>

<Popover>
  <Tooltip content="Display settings">
    <PopoverTrigger asChild>
      <Button variant="outline" iconOnly aria-label="Settings">
        <GearSix />
      </Button>
    </PopoverTrigger>
  </Tooltip>
  <PopoverContent>…</PopoverContent>
</Popover>
```

Building a component that adds a hint of its own? Pass `auto` to that Tooltip and it yields the same way. A popover's content portaled from inside the wrapped element keeps its own hints.

## 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>
    <form className="contents" onSubmit={(e) => e.preventDefault()}>
      <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 type="button" variant="ghost">Cancel</Button>
        </DialogClose>
        <Button type="submit">Create webhook</Button>
      </DialogFooter>
    </form>
  </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>
```

## API reference

### Tooltip

A hint on hover and keyboard focus, built on Tippy.js in headless mode (the documented exception to Radix first). It renders no wrapper: the bubble is a `role="tooltip"` element mounted on the body (or the full-screen element). Every part accepts `className`, merged last; here it lands on the bubble.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| content* | ReactNode | - | The bubble's contents: a label, a label plus a glyph, or the graph parts below. |
| children | ReactElement | - | The trigger: a single element that forwards its `ref` to a DOM node. Optional only with `anchor`. |
| variant | "text" \| "graph" | "text" | `text` is the inverted one-line chip; `graph` is the left-aligned popover card for multi-line data. Ignored inside a `TooltipGroup`. |
| placement | Placement | "top" | Tippy placement: `top`, `right`, `bottom`, `left`, each with `-start` or `-end`, or `auto`. |
| delay | number \| [number, number] | [150, 0] | Hover intent in ms, `[open, close]` or one number for both. Ignored inside a group. |
| offset | [number, number] | [0, 6] | `[skidding, distance]` from the trigger in px. Ignored inside a group. |
| interactive | boolean | false | Keeps the bubble open while the pointer is over it, for a single link. Ignored inside a group. |
| trigger | string | "mouseenter focus" | Space-separated events that open it. Focus opens it only when it is keyboard focus; pass `"mouseenter"` to drop focus hints. |
| hideOnClick | boolean | true | Whether clicking the trigger hides it. Pass `false` for a toggle whose label changes on click. |
| open | boolean | - | Controlled visibility. Setting it switches the trigger events off; with `anchor` it defaults to `true`. |
| anchor | { x: number; y: number; width?: number; height?: number } | - | Hangs the bubble on a point or box in viewport coordinates instead of `children` (a map pin, a chart point). Moving it re-positions the open bubble. |
| disabled | boolean | false | Keeps the tooltip from showing. Ignored inside a group. |

| Data attribute | Description |
| --- | --- |
| data-state | `visible` or `hidden` on the bubble; drives the enter and exit transition. |
| data-placement | The resolved placement on the bubble; sets the transform origin. |
| data-variant | `text` or `graph` on the bubble, so nested parts (a `Kbd`) can adapt. |

| CSS variable | Description |
| --- | --- |
| --surface | Set on the bubble to its own ground (`--foreground` for `text`, `--popover` for `graph`) so nested controls blend with it. |

### TooltipGroup

Shares one bubble across the `Tooltip`s inside it, so it glides from trigger to trigger (a Tippy singleton). Each child keeps its own `content`, `placement` and `trigger`; the rest is set here. Renders no element.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| variant | "text" \| "graph" | "text" | Shape of the shared bubble. |
| delay | number \| [number, number] | [150, 200] | Hover intent shared by the group. The 200ms close is the grace period that lets the pointer reach the next trigger. |
| offset | [number, number] | [0, 6] | `[skidding, distance]` from each trigger in px. |
| disabled | boolean | false | Keeps the shared bubble from showing. |
| className | string | - | Classes merged onto the shared bubble. |

### TooltipHeader

The header row of a `graph` bubble: a `TooltipHeaderText` column plus a trailing `TooltipValue`. Forwards all native `<div>` props.

### TooltipHeaderText

The stacked title and description column inside `TooltipHeader`. Forwards all native `<div>` props.

### TooltipTitle

The bold title line. Forwards all native `<div>` props.

### TooltipDescription

The muted line under the title. Forwards all native `<div>` props.

### TooltipValue

A tonal value pill (a time, count or amount) in `tabular-nums`. Forwards all native `<span>` props.

### TooltipSeparator

A hairline `role="separator"` between the header and the sections. Forwards all native `<div>` props.

### TooltipSection

A group of `TooltipStat` rows banded by a colored left rail. Forwards all native `<div>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| tone | "brand" \| "info" \| "success" \| "warning" \| "destructive" \| "neutral" | "neutral" | The rail color, a token role so it tracks the theme. |

### TooltipStat

One breakdown row: a label, an optional percent and a `TooltipValue` pill. Forwards all native `<div>` props except `children`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| label* | ReactNode | - | The row label, truncated to one line. |
| value* | ReactNode | - | The value shown in the trailing pill. |
| percent | ReactNode | - | A muted share shown just before the value. |
| indent | boolean | false | Nests the row one step in, for a sub-line under a total. |

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Installation

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

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

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

Pro: `tree` comes with a [Koala UI Pro license](https://www.koalaui.com/pro). Its source is not published in these docs.

## Usage

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

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.

## Anatomy

```tsx
import { Tree, TreeItem } from "@/components/ui/tree"

<Tree>
  <TreeItem value="branch" label="...">
    <TreeItem value="leaf" label="..." />
  </TreeItem>
</Tree>
```

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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 (a `<ul>`). Owns single selection, the expanded set and the roving keyboard model. Forwards all native `<ul>` props; every part accepts `className`, merged last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| value | string | - | The selected node's `value` (controlled). |
| defaultValue | string | - | The initially selected node (uncontrolled). |
| onValueChange | (value: string) => void | - | Fires when a different node is selected. |
| expandedValues | string[] | - | The expanded branch values (controlled). |
| defaultExpandedValues | string[] | - | The initially expanded branches (uncontrolled). |
| onExpandedChange | (values: string[]) => void | - | Fires with the full expanded set whenever a branch toggles. |
| guides | boolean | true | Draws the vertical rails that trace each nesting level. |
| onMove | (move: TreeMoveEvent) => void | - | Enables drag to reorder and `Alt` + arrow sibling moves. Fires `{ value, target, position }` with `position` one of `"before" \| "after" \| "inside"`; apply it to your own data. |

| CSS variable | Description |
| --- | --- |
| --tree-indent | The indent per level, set on the root (5.5 spacing steps). Override it to tighten or widen the ladder. |

### TreeItem

A node (an `<li>` holding a `role="treeitem"` row). With nested `TreeItem` children it is a branch on a Radix `Collapsible`; without, a leaf. Forwards all native `<li>` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| value* | string | - | Stable identity for selection, expansion and moves. |
| label | ReactNode | - | The row label, truncated to one line. |
| icon | ReactNode | - | Leading glyph, e.g. a folder or file icon. A bare icon is sized to 20px. |
| expandedIcon | ReactNode | icon | Leading glyph shown while the branch is open, e.g. `FolderOpen`. |
| actions | ReactNode | - | Trailing content such as a count badge or a row menu. |
| disabled | boolean | - | Removes the node from selection, expansion, focus and dragging. |
| children | ReactNode | - | Nested `TreeItem`s. Their presence makes the node a branch. |

| Data attribute | Description |
| --- | --- |
| data-selected | `"true"` on the row of the selected node, else `"false"`. |
| data-expanded | `"true"` on the row of an open branch, else `"false"`. |
| data-branch | `"true"` when the node has children. |
| data-level | The row's depth, starting at `0`. |
| data-value | The node's `value`, on the row. |
| data-dragging | Present on the row being dragged. |
| data-drop | `before`, `after` or `inside` on the row under a drag. |
| data-state | `open` or `closed` on a branch's nested group (Radix Collapsible). |

| CSS variable | Description |
| --- | --- |
| --tree-level | The depth, set inline on each row and group; drives the row inset and the guide rail position. |

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Installation

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

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

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

Pro: `video-player` comes with a [Koala UI Pro license](https://www.koalaui.com/pro). Its source is not published in these docs.

## Usage

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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
import {
  VideoPlayer,
  Video,
  VideoSpinner,
  VideoControls,
  VideoBar,
  VideoPlayButton,
  VideoSeek,
  VideoTime,
  VideoVolume,
  VideoFullscreen,
} from "@/components/ui/video-player"

<VideoPlayer>
  <Video />
  <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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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`.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## 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 |

## API reference

### VideoPlayer

The focusable frame that owns playback state (playing, time, volume, fullscreen, buffering) and shares it with every part through context. Forwards all native `<div>` props (its `onVolumeChange` is replaced by the one below); every part accepts `className`, merged last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| revealOn | "auto" \| "hover" | "auto" | `auto` keeps the controls up while paused and hides them after an idle beat during playback; `hover` shows them only while the pointer or focus is inside. |
| hideDelay | number | 2600 | Idle delay in ms before the controls auto-hide during playback (`revealOn="auto"` only). |
| labels | Partial<VideoPlayerLabels> | - | Tooltips and aria-labels: `play`, `pause`, `seek`, `mute`, `unmute`, `volume`, `enterFullscreen`, `exitFullscreen`, `buffering`. Missing keys keep the English defaults. |
| volume | number | - | Controlled volume, 0 to 1. Passing it hands the audio to you: the player stops writing volume or mute to the `<video>`. |
| onVolumeChange | (volume: number) => void | - | Called with the new level when the volume bar or an arrow key changes it. |
| muted | boolean | false | Controlled mute state, read only when `volume` is controlled. |
| onMutedChange | (muted: boolean) => void | - | Called when the mute button, the `M` key, or a drag to or from 0 flips the mute state. |

| Data attribute | Description |
| --- | --- |
| data-active | `true` while the controls are revealed, `false` while hidden (the cursor hides too). |

### Video

The real `<video>` element; clicking it toggles play. Forwards all native `<video>` props, `ref` reaches the element, and your media handlers run after the player's own.

### VideoControls

The bottom overlay with its own gradient scrim; fades in and out with the frame's `data-active`. Forwards all native `<div>` props.

### VideoBar

One row of controls inside `VideoControls`. Forwards all native `<div>` props.

### VideoPlayButton

Play and pause toggle with a rolling tooltip label; sets `aria-pressed` while playing. Forwards all native `<button>` props.

### VideoSeek

The scrubber, a Radix `Slider` with a buffered-ahead fill and a hover timecode preview. Forwards all Radix Slider `Root` props except `value` and `onValueChange`; `aria-label` names the thumb (defaults to `labels.seek`).

| Data attribute | Description |
| --- | --- |
| data-disabled | Present until the duration is known (Radix Slider). |

### VideoTime

Elapsed and total timecode, e.g. `0:42 / 3:15`, in `tabular-nums`. Forwards all native `<span>` props.

### VideoVolume

Mute toggle with a vertical Radix Slider flyout that opens on hover or focus and reads out the live percentage. Forwards all native `<div>` props.

### VideoFullscreen

Enters and exits fullscreen on the frame; sets `aria-pressed` while fullscreen. Forwards all native `<button>` props.

### VideoSpinner

A centered spinner that renders only while the media is stalled waiting for data. Forwards all native `<div>` props.

## 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`.

---

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

# Voice Roster

Who is on a voice channel and who is on air right now. The stack of members a game, dispatch or call overlay lights up as people talk, the companion of Push to Talk: a soft green fill, a ringed avatar and a running level meter on whoever has the channel.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Installation

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

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

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

Pro: `voice-roster` comes with a [Koala UI Pro license](https://www.koalaui.com/pro). Its source is not published in these docs.

## Usage

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Anatomy

```tsx
import {
  VoiceRoster,
  VoiceRosterAvatar,
  VoiceRosterContent,
  VoiceRosterDetail,
  VoiceRosterHeader,
  VoiceRosterItem,
  VoiceRosterLevel,
  VoiceRosterList,
  VoiceRosterMark,
  VoiceRosterMore,
  VoiceRosterName,
  VoiceRosterOrigin,
  VoiceRosterSupervisor,
} from "@/components/ui/voice-roster"

<VoiceRoster>
  <VoiceRosterHeader />
  <VoiceRosterList>
    <VoiceRosterItem>
      <VoiceRosterAvatar />
      <VoiceRosterMark />
      <VoiceRosterSupervisor />
      <VoiceRosterContent>
        <VoiceRosterName />
        <VoiceRosterDetail />
        <VoiceRosterOrigin />
      </VoiceRosterContent>
      <VoiceRosterLevel />
    </VoiceRosterItem>
  </VoiceRosterList>
  <VoiceRosterMore />
</VoiceRoster>
```

## Talking

An item has two states. Idle is a member who is on the channel and quiet: a neutral row and four low, still bars, their slot reserved so nothing moves when it lights. `talking` lights it all at once: the row takes a soft green fill, the avatar rings in green, the secondary line turns green and the bars run a voice waveform. Green, not Push to Talk's red: red says you are on air, and it already means a busy channel here.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Sides

`side` is the edge the roster hangs from, `left` (the default) or `right`. Everything aligns to it, items enter from it and leave toward it, so the edge facing the screen is always straight. Each row is as wide as its content above a shared minimum, so a voice that comes and goes never resizes the others; for one even column, give the list `items-stretch`. Where the roster is pinned is yours: a `fixed` corner, an `absolute` one.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## In a panel

The default `variant="overlay"` floats over a game: translucent rows, each as wide as its content up to a cap, with a lift. To set the roster inside a page instead (a column of a dispatch screen, a card, a sidebar), use `variant="panel"`: no width cap, no fill and no shadow (the rows sit on the panel's own ground, like a List), and every row the column's full width. The on-air state, the meter, the busy header and the overflow line behave the same; `side` only sets which edge rows enter from and leave toward.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Density

`comfortable` stacks the name over the secondary line and sizes an avatar at 32px; `compact` sets them on one line, for a crowded channel where every row of height counts, and drops the avatar to 24px. Leave the avatar out entirely for the tightest stack. With no `density` prop the roster follows the nearest `DensityProvider`, compact by default.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Channel header

`VoiceRosterHeader` names the channel the members are on: the name as its children, in the meta ink, and the `frequency` in the ink, because the figure is what people look for. It also names the list for a screen reader. It is optional; without it the stack starts at the first member.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

`busy` marks the whole channel busy: the name in red and a prohibited mark named by `labels.busy`. It sits on the header because the flag belongs to the channel, not to anyone in it, and it holds still: a standing state, not an alert.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Groups and supervisors

On a channel shared by several teams, `VoiceRosterMark` tells them apart: a small dot in the group's own `color` (any CSS colour, the one your app already uses for that team) named by `label` for screen readers and the tooltip. `VoiceRosterSupervisor` puts a grey star after the name of whoever leads the channel. Both stay grey and small on air: they say who someone is, and colour here means talking.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Voices from another channel

Someone heard from outside the channel (another unit, a second radio) takes `VoiceRosterOrigin` in the secondary line's place: the channel they come in on and its `frequency`. With no frequency the name alone is the answer and takes the ink. Such a voice is usually only shown while it talks: mount it `talking`, set `leaving` when it stops, and unmount it once the exit is done. The exit takes `--duration-base` and is a transition, so a voice that comes back mid-exit slides straight back in.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Overflow

A full channel would cover the screen. `max` on the list shows that many members and sums up the rest in one line, `labels.more`. The roster keeps the order it is given, so who makes the cut is yours: put the latest speaker first and a voice from below the cut still gets a row, and keeps it until others have spoken after them.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Labels

Every word the roster says on its own is in `labels`: `talking` (read after a member on air), `busy`, `supervisor` and `more`, where `{count}` becomes the number left out. Pass only the ones you change.

*Code included with [Koala UI Pro](https://www.koalaui.com/pro).*

## Accessibility

The members are a list, named by the header: a screen reader hears "Adam-12 202.0, list, 3 items". Who is talking is in the text (`labels.talking` after their name), not only in the colour. The roster is deliberately not a live region: on a channel where people talk over each other it would be read out without pause. A leaving item is hidden from assistive tech straight away. Marks and stars are images named by their `label`; the level meter is decoration. Under reduced motion nothing slides and the bars hold a still, uneven level instead of the wave.

## API reference

### VoiceRoster

The stack, a `<div>`. Display only: nothing in it takes focus or a click. Forwards every div prop; `className` is merged last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| side | "left" \| "right" | "left" | The edge the roster hangs from: everything aligns to it, enters from it and leaves toward it. |
| variant | "overlay" \| "panel" | "overlay" | `overlay` floats over a game or a page. `panel` is for a page column: no width cap, no fill, no shadow, full-width rows on the page's own ground. |
| density | "comfortable" \| "compact" | - | `comfortable` stacks name and secondary line; `compact` sets them on one line. Defaults to the nearest `DensityProvider`, else compact. |
| labels | Partial<VoiceRosterLabels> | - | Override the words the roster says itself: `talking` (`"Talking"`), `busy` (`"Busy"`), `supervisor` (`"Supervisor"`), `more` (`"+{count} more on the channel"`). |

| Data attribute | Description |
| --- | --- |
| data-slot="voice-roster" | On the root. |
| data-side | `left` or `right`. |
| data-variant | `overlay` or `panel`. |
| data-density | `comfortable` or `compact`. |

### VoiceRosterHeader

The channel, a `<div>`: its name as children. Its id names the list. Forwards every div prop.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| frequency | React.ReactNode | - | The channel's frequency (or number), shown after its name. |
| busy | boolean | false | The whole channel is busy: the busy mark and the name in red, named by `labels.busy`. |

| Data attribute | Description |
| --- | --- |
| data-busy | Present while `busy`. |

### VoiceRosterList

The members, a `<ul>` of items named by the header. Not a live region. Forwards every ul prop.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| max | number | - | Shows at most this many members and renders `VoiceRosterMore` after them with the rest. Omit it, or pass `0`, for no cap. The order is kept, so put the latest speaker first. |

### VoiceRosterItem

A member, an `<li>`. Any subset of the parts below goes inside, in this order. Forwards every li prop.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| talking | boolean | false | On air right now: lights the item and adds `labels.talking` for screen readers. |
| leaving | boolean | false | Plays the exit (fades and slides toward the edge) and hides it from assistive tech. Unmount it once the exit is done (`--duration-base`). |

| Data attribute | Description |
| --- | --- |
| data-state | `talking` or `idle`. |
| data-leaving | Present while `leaving`. |
| data-entered | Set once the entrance has played, so it never replays. |

### VoiceRosterAvatar

A Koala `Avatar` (`AvatarImage` and `AvatarFallback` inside). Rings green on air. Takes every `Avatar` prop.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| size | "xs" \| "sm" \| "md" \| "lg" \| "xl" | - | Defaults to `sm` comfortable and `xs` compact. |

### VoiceRosterMark

A small dot in the colour of the member's group or department. Forwards every span prop.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| color* | string | - | Any CSS colour (`#3b82f6`, `var(--info)`). |
| label* | string | - | The group's name: its accessible name and tooltip. |

| CSS variable | Description |
| --- | --- |
| --voice-roster-mark | Set from `color`. |

### VoiceRosterSupervisor

The star after the name: this member leads the channel. Place it anywhere in the item; it always sits after the text. Forwards every span prop.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| label | string | labels.supervisor | Its accessible name and tooltip. |
| icon | React.ReactNode | - | Replaces the star. |

### VoiceRosterContent

The text, a `<div>`: stacks the name over the detail (comfortable) or sets them on one line (compact).

### VoiceRosterName

The member's name, a `<span>`. Ends in an ellipsis.

### VoiceRosterDetail

The secondary line, a `<span>`: a rank, a role, a callsign. Ends in an ellipsis and turns green on air.

### VoiceRosterOrigin

Where a voice from outside the channel comes from, in the detail's place: the other channel as children.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| frequency | React.ReactNode | - | The frequency the voice comes in on. Without it, the name alone is the answer and takes the ink. |

| Data attribute | Description |
| --- | --- |
| data-solo | Present when there is no `frequency`. |

### VoiceRosterLevel

The four-bar meter, hidden from assistive tech. Takes no children.

| CSS variable | Description |
| --- | --- |
| --animate-voice-level-1…4 | The waveform each bar runs on air. Still at rest and under reduced motion. |

### VoiceRosterMore

The overflow line, a `<p>`. Rendered by `VoiceRosterList` when `max` cuts it; render it yourself when you cut the list first.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| count* | number | - | How many members are left out; fills `labels.more`. |
| children | React.ReactNode | - | Replaces the words. |

### voiceRosterVariants

The `tv` recipe behind every part, for styling a part of your own to match.

## FAQ

### Voice Roster or Push to Talk?

Both, side by side. Push to Talk is your transmit key; the roster shows who else is on the channel and who has it now, your own row included.

### Does it listen to the audio?

No. It shows what you tell it: set talking from your voice layer (a WebRTC track's speaking event, a radio bridge, a game's voice events). The level meter is a waveform, not a measurement.

### Why does it never remove a member itself?

Because only you know when someone left. Set leaving to play the exit and unmount the item when it is done; keep it mounted a beat longer (a linger) so a speaker who lets go and talks again straight away does not flicker.

### Who makes the cut when max is set?

The first ones you render. The roster never reorders, so a channel of three does not shuffle every time someone talks; when the channel is bigger than max, sort by who spoke last.

### Can it sit over a game?

That is what it is for. It paints its own translucent rows, nothing in it takes focus or a click (add pointer-events-none and the game keeps the mouse), and every movement rides transform and opacity, so it runs in the older embedded browsers games ship.

### Can it sit inside a page instead?

Yes: variant="panel". It drops the fill, the lift and the width cap and sets every row on the panel's own ground, full width, for a column of a dispatch screen, a card or a sidebar.