# Arc

> Arc is a React component and block library designed for AI-assisted frontend development. It provides copy-paste components, complete interface blocks, machine-readable registry metadata, AI skills, and MCP compatibility. Components and blocks share design tokens, CSS modules, and Motion. Free items install with the shadcn CLI from a public registry; Pro items are licensed and install from the token-gated @uiarc-pro registry.

Arc has 242 components and 141 blocks. 121 components and 22 blocks are free and open source (MIT); 121 components and 119 blocks are Arc Pro. Arc Pro costs $149 per year or $249 once for lifetime access, and a team plan covers up to 10 people for $799 once or $449 per year. Plans: https://uiarc.dev/pricing.

## Install

Arc items are shadcn-compatible registry items. Each one pulls in the motion presets (`arc-motion-tokens`) and any Arc components it builds on. The design tokens (`arc-foundation`, `foundation.css`) install once per app, and no item reinstalls them.

```bash
npx shadcn@latest add https://uiarc.dev/r/arc-foundation.json
npx shadcn@latest add https://uiarc.dev/r/button.json
```

Or register the namespace once in `components.json` and install by name:

```json
{ "registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" } }
```

```bash
npx shadcn@latest add @uiarc/button @uiarc/dialog
```

Import the tokens once in the root layout: `import "@/components/arc/foundation.css";`. Files install into an `arc/` folder under the `components` alias from `components.json` (for example `components/arc/button/button.tsx`, or `src/components/arc/…` in a `src/` project or a monorepo package) and import each other with relative paths, so no `tsconfig.json` change is needed. Import them from there: `import { Button } from "@/components/arc/button/button";`. Components use CSS modules and CSS variables, not Tailwind classes. Dark mode: `data-theme="dark"` on `<html>`. Accent: `data-accent` = neutral, violet, blue, green, amber, orange, coral, or rose.

### Pro items

Pro components, blocks, and templates install from the token-gated `@uiarc-pro` registry. A Pro member creates a token (`arc_pro_…`) at https://uiarc.dev/account#pro-access, sets `ARC_PRO_TOKEN` in the environment or `.env.local` (never committed), and adds the registry to `components.json`:

```json
{ "registries": { "@uiarc": "https://uiarc.dev/r/{name}.json", "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } } }
```

```bash
npx shadcn@latest add @uiarc-pro/dock
```

The MCP server unlocks Pro for a Pro account that signed in through the MCP client (OAuth), or with the same token as `Authorization: Bearer …`: `get_component` then returns Pro source and `get_install_command` returns `@uiarc-pro` commands. Without Pro access, never reconstruct a Pro item; offer a free alternative or https://uiarc.dev/pricing. Setup: https://uiarc.dev/docs/ai#pro-access

## Rules for agents

- Prefer an existing Arc component or block over writing a new one; compose blocks from Arc components.
- Read the component's markdown before using it; use only documented props.
- Keep semantic HTML, keyboard behavior, and a reduced-motion branch for every animation.
- Use the semantic tokens (`--background`, `--surface`, `--foreground`, `--text-secondary`, `--border`, `--accent`, `--success`, `--warning`, `--danger`) instead of raw colors, and check light and dark themes.
- Use motion presets from `components/arc/lib/motion-tokens.ts` (`snappy` for presses, `smooth` for panels, `morph` for shared highlights). Motion should explain cause and effect.
- Sentence case copy, regular and medium weights only, no eyebrow labels, no em dashes, no focus rings on pointer focus (keyboard focus gets the shared :focus-visible ring), no decorative gradients or glows.
- Pro items are licensed: never reconstruct their source; point people to the pricing page.

## Skills

Install every free skill file with `npx shadcn@latest add https://uiarc.dev/r/arc-skill.json`, or read them directly:

- [SKILL.md](https://uiarc.dev/r/skills/arc/SKILL.md): Entry point: workflow, principles, never-do list, and quick decisions
- [INSTRUCTIONS.md](https://uiarc.dev/r/skills/arc/INSTRUCTIONS.md): Short always-on rules for AGENTS.md, CLAUDE.md, or Cursor rules
- [checklist.md](https://uiarc.dev/r/skills/arc/checklist.md): The review loop to run before finishing, with grep sweeps
- [components.md](https://uiarc.dev/r/skills/arc/components.md): Choosing the right component or block by job, with ids
- [composition.md](https://uiarc.dev/r/skills/arc/composition.md): Page containers, dashboards, marketing sections, states, React correctness
- [copy.md](https://uiarc.dev/r/skills/arc/copy.md): Sentence case, no eyebrows or em dashes, verbs on buttons, honest claims
- [design.md](https://uiarc.dev/r/skills/arc/design.md): Color, type, surfaces, concentric radii, spacing, and icons
- [motion.md](https://uiarc.dev/r/skills/arc/motion.md): Motion tokens, spring choice, patterns with code, reduced motion
- [accessibility.md](https://uiarc.dev/r/skills/arc/accessibility.md): Focus without rings, semantics, keyboard, and announcements
- [responsive.md](https://uiarc.dev/r/skills/arc/responsive.md): Widths to check, overflow, tables, and touch targets
- [example-settings.md](https://uiarc.dev/r/skills/arc/example-settings.md): A worked account settings page
- [example-pricing.md](https://uiarc.dev/r/skills/arc/example-pricing.md): A worked pricing section with plans, comparison, and FAQ
- [example-dashboard.md](https://uiarc.dev/r/skills/arc/example-dashboard.md): A worked analytics overview with KPIs, chart, and table

Pro skills (Arc Pro, served to signed-in Pro members at https://uiarc.dev/api/skills):

- Arc Pro skill: Entry point: picks the right Pro workflow and sets up Pro access
- Full-page generation: Brief, plan region by region with every state, build, and verify a whole page, or stop at the plan
- Design system generation: A brand theme on Arc tokens with contrast checked in both themes
- Refactor to Arc: Migrate custom, shadcn/ui, MUI, or Chakra UI to Arc with parity checks
- Motion audit: Inventory every animation, assign tokens, cut motion that explains nothing
- Responsive audit: Measure five widths, fix overflow, layout, and touch, then re-measure
- Accessibility audit: A ranked audit of structure, keyboard, contrast, and motion with patches

## Guides

- [All guides](https://uiarc.dev/guides): Step-by-step builds with Arc components and blocks
- [SaaS dashboard in React](https://uiarc.dev/guides/saas-dashboard-react): Shell, metrics, tables, and states for a product dashboard
- [React motion: springs and reduced motion](https://uiarc.dev/guides/react-motion-springs-reduced-motion): Choosing springs and writing a reduced-motion branch
- [shadcn registry for AI coding tools](https://uiarc.dev/guides/shadcn-registry-ai-coding-tools): Installing Arc through the registry, MCP, and llms.txt
- [React settings page](https://uiarc.dev/guides/react-settings-page): Forms, switches, and destructive actions on one settings screen
- [Onboarding flows](https://uiarc.dev/guides/onboarding-flows): Multi-step setup with progress and in-place confirmation
- [React command menu](https://uiarc.dev/guides/react-command-menu): A keyboard-first command palette for global search and actions
- [Best React component libraries in 2026](https://uiarc.dev/guides/best-react-component-libraries): How shadcn/ui, Magic UI, Aceternity UI, React Bits, HeroUI, Mantine, MUI and Arc differ, and when to pick each
- [Best UI library for AI coding agents](https://uiarc.dev/guides/best-ui-library-for-ai-coding-agents): What makes a library agent-friendly: registry, MCP server, llms.txt, per-component markdown

## Comparisons

- [Compare Arc](https://uiarc.dev/compare): Fact tables against other React UI libraries, with the date each fact was checked
- [Arc vs Magic UI](https://uiarc.dev/compare/magic-ui): Stack, license, free and paid items, install method and AI support
- [Arc vs Aceternity UI](https://uiarc.dev/compare/aceternity-ui): Stack, license, free and paid items, install method and AI support
- [21st.dev alternative](https://uiarc.dev/compare/21st-dev): Arc compared with the 21st.dev community registry

## Templates

- [Templates](https://uiarc.dev/templates) (Pro): Complete starter apps built from Arc blocks
- [Arc CRM](https://uiarc.dev/templates/arc-crm) (Pro): Relay, a clean CRM for sales teams: companies, company records, people, a deals pipeline and a linked inbox

# Components and blocks

## Button

> A clear, responsive action with quiet secondary states.

- Type: Component (actions)
- Access: Free, open source
- Page: https://uiarc.dev/components/button
- Markdown: https://uiarc.dev/components/button/markdown
- Registry item: https://uiarc.dev/r/button.json
- Source file: `registry/components/button/button.tsx`
- Dependencies: motion
- Keywords: action, control, react button, animated button, loading button, button with spinner, button press animation, morphing button label, primary button

### When to use

- Any single action on a page, form, or dialog, such as Save, Continue, or Cancel.
- Actions whose label changes in place, like Save to Saved, where the width should spring instead of jump.
- Short async work where a spinner on the button is enough feedback, via loading.

### When not to use

- Use action-button when the button itself should show pending and success states after an async commit.
- Use split-button when one default action has two to five close variants.
- Use hold-to-confirm for destructive actions that need more than a single click.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/button
pnpm dlx shadcn@latest add @uiarc/button
yarn dlx shadcn@latest add @uiarc/button
bunx --bun shadcn@latest add @uiarc/button
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/button.json
```

#### Manual

1. Install the dependencies:

```bash
npm install motion
```

2. Copy the source into your project. Main file: `registry/components/button/button.tsx`

   The source is in the registry item: https://uiarc.dev/r/button.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

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

export function SaveBar() {
  return (
    <Button variant="primary" loading={saving} onClick={save}>
      Save changes
    </Button>
  );
}
```

### Examples

#### Label that morphs after saving

```tsx
<Button variant="secondary" loading={saving} onClick={save}>
  {saved ? "Saved" : "Save draft"}
</Button>
```

### API reference

#### Button

A native button with press feedback and a label that morphs its width when the content changes.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"primary" \| "secondary" \| "ghost" \| "danger"` | `"primary"` | Visual weight. Use one primary action per surface. |
| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Height and padding. |
| `loading` | `boolean` | `false` | Shows a spinner, sets aria-busy, and swallows clicks while keeping focus. |
| `...props` | `ButtonHTMLAttributes<HTMLButtonElement>` | – | Forwarded to the underlying button, including ref, disabled, type, and onClick. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Enter / Space | Activates the button. |

### Accessibility

- Renders a native button, so role and focus come for free.
- Loading uses aria-busy and aria-disabled instead of disabled, so keyboard focus is not lost mid-action.
- Icon-only buttons need an aria-label.
- Disabled primary buttons fade as a whole. Disabled secondary and danger buttons keep their border and take a muted fill and label, and disabled ghost buttons take a muted label, so an unavailable action still reads as a button.

### Motion

- Presses scale to about 0.97 on a snappy spring; icon-sized buttons press slightly deeper.
- A new label crossfades with a short blur while the width springs to fit.
- Reduced motion drops the press scale and swaps labels with a plain fade.

### Responsive behavior

- Size is fixed by the size prop; the button never changes layout by breakpoint, so pick lg for primary touch targets.
- Hover styles apply only on hover-capable fine pointers, so taps on touch screens do not stick in a hover state.

### Performance

- A ResizeObserver measures the label so the width can spring; one per button is cheap, but avoid hundreds in a long list.
- Label changes animate opacity, transform, and a small blur only, with no layout thrash beyond the width spring.

### Notes for AI

- Default choice for any single action. Use action-button for dense icon toolbars and split-button when one action has close alternatives.
- Pass a changing label (Save → Saved) as children to get the width morph for free.
- Wrap in a Radix trigger with asChild; the press scale turns off automatically for popup anchors.

### Related

- [Action button](https://uiarc.dev/components/action-button/markdown): A compact button for frequent toolbar actions.
- [Split button](https://uiarc.dev/components/split-button/markdown): A primary action with a menu of nearby alternatives.
- [Copy button](https://uiarc.dev/components/copy-button/markdown): Copy a value with immediate confirmation.
- [Hold to confirm](https://uiarc.dev/components/hold-to-confirm/markdown): Confirm a destructive action by holding, not tapping.

### Also in buttons

- [Button group](https://uiarc.dev/components/button-group/markdown): Related actions joined into one surface with hairline dividers: a hover highlight glides between segments, the pressed one answers in place, and an attached menu can close the row.
- [Floating button group](https://uiarc.dev/components/floating-button-group/markdown): Separate soft buttons in a quiet tray, with one shared highlight that morphs from button to button as you move, and a pressed state that settles in place.
- [Expanding button group](https://uiarc.dev/components/expanding-button-group/markdown): Icon buttons in a compact group: the one you point at or focus grows to reveal its label while its neighbours slide aside, and an action confirms in place.
- [Action swap](https://uiarc.dev/components/action-swap/markdown): Swap an action label while preserving its place and intent.
- [Icon morph](https://uiarc.dev/components/icon-morph/markdown): Icons that morph between states: menu to close, play to pause, copy to check, and more.
- [Confirm morph](https://uiarc.dev/components/confirm-morph/markdown): A destructive button that morphs into an inline confirmation, a spinner, and a result with undo.

### Guidance for AI tools

Button: A clear, responsive action with quiet secondary states. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Action button

> A compact button for frequent toolbar actions.

- Type: Component (actions)
- Access: Free, open source
- Page: https://uiarc.dev/components/action-button
- Markdown: https://uiarc.dev/components/action-button/markdown
- Registry item: https://uiarc.dev/r/action-button.json
- Source file: `registry/components/action-button/action-button.tsx`
- Dependencies: motion, lucide-react
- Keywords: action, toolbar, react action button, async button, submit button with success state, save button animation, loading to success button, cta button with arrow, publish button

### When to use

- A single async commit such as Save, Publish, or Submit where the result should appear on the button.
- Call-to-action buttons where a trailing arrow invites the next step.
- Flows where the button should reset to idle on its own after success, via resetAfterMs.

### When not to use

- Use button with loading for plain form submits that do not need a success state.
- Use action-swap when the control toggles between lasting states.
- Use hold-to-confirm when the action is destructive and needs a deliberate press.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/action-button
pnpm dlx shadcn@latest add @uiarc/action-button
yarn dlx shadcn@latest add @uiarc/action-button
bunx --bun shadcn@latest add @uiarc/action-button
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/action-button.json
```

#### Manual

1. Install the dependencies:

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

2. Copy the source into your project. Main file: `registry/components/action-button/action-button.tsx`

   The source is in the registry item: https://uiarc.dev/r/action-button.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { ActionButton } from "@/components/arc/action-button/action-button";

export function PublishButton() {
  return (
    <ActionButton
      label="Publish"
      pendingLabel="Publishing"
      successLabel="Published"
      onAction={publish}
      onActionError={error => toast.error(String(error))}
    />
  );
}
```

### API reference

#### ActionButton

A call-to-action button with a trailing arrow that runs an async action and morphs through pending and success.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` (required) | `string` | – | Idle label and accessible name. |
| `onAction` (required) | `() => void \| Promise<void>` | – | Runs on press. The pending state lasts until the promise settles. |
| `pendingLabel` | `string` | `"Saving"` | Label while onAction runs. |
| `successLabel` | `string` | `"Saved"` | Label after onAction resolves. |
| `resetAfterMs` | `number` | `2400` | Delay before returning to idle after success. 0 keeps the success state. |
| `onActionError` | `(error: unknown) => void` | – | Called when onAction rejects; the button returns to idle. |
| `...props` | `ButtonHTMLAttributes<HTMLButtonElement>` | – | Forwarded to the button, except onClick. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Enter / Space | Runs the action. |

### Accessibility

- Native button; the visible label is aria-hidden and a visually hidden copy of label names it.
- Pending sets aria-busy and aria-disabled instead of disabled, so keyboard focus stays through the save.
- A role="status" region announces the pending and success labels.

### Motion

- Changed letters rise from a soft blur while the width springs to fit; the arrow leaves forward and a check draws itself in.
- Presses scale to about 0.97 on a snappy spring.
- Reduced motion drops the press scale, width spring, and stroke draw, and swaps with an instant fade.

### Responsive behavior

- Width springs to fit pending and success labels, so keep them close in length inside tight toolbars.
- Hover shadow applies only on hover-capable fine pointers; touch gets the press scale.

### Performance

- Every letter is a motion span with layout position animation plus a small blur; fine for a few buttons, not for dense tables.
- A ResizeObserver drives the width spring.

### Notes for AI

- Use for a single async commit (save, publish, submit) where the result should show on the button itself.
- Prefer button with loading for plain forms, and action-swap when the control toggles between lasting states.
- Return the real promise from onAction; handle errors in onActionError since the button just resets.

### Related

- [Button](https://uiarc.dev/components/button/markdown): A clear, responsive action with quiet secondary states.
- [Action swap](https://uiarc.dev/components/action-swap/markdown): Swap an action label while preserving its place and intent.
- [Hold to confirm](https://uiarc.dev/components/hold-to-confirm/markdown): Confirm a destructive action by holding, not tapping.
- [Toast](https://uiarc.dev/components/toast/markdown): Brief confirmation for a completed background action.

### Also in buttons

- [Split button](https://uiarc.dev/components/split-button/markdown): A primary action with a menu of nearby alternatives.
- [Button group](https://uiarc.dev/components/button-group/markdown): Related actions joined into one surface with hairline dividers: a hover highlight glides between segments, the pressed one answers in place, and an attached menu can close the row.
- [Floating button group](https://uiarc.dev/components/floating-button-group/markdown): Separate soft buttons in a quiet tray, with one shared highlight that morphs from button to button as you move, and a pressed state that settles in place.
- [Expanding button group](https://uiarc.dev/components/expanding-button-group/markdown): Icon buttons in a compact group: the one you point at or focus grows to reveal its label while its neighbours slide aside, and an action confirms in place.
- [Copy button](https://uiarc.dev/components/copy-button/markdown): Copy a value with immediate confirmation.
- [Icon morph](https://uiarc.dev/components/icon-morph/markdown): Icons that morph between states: menu to close, play to pause, copy to check, and more.
- [Confirm morph](https://uiarc.dev/components/confirm-morph/markdown): A destructive button that morphs into an inline confirmation, a spinner, and a result with undo.

### Guidance for AI tools

Action button: A compact button for frequent toolbar actions. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Split button

> A primary action with a menu of nearby alternatives.

- Type: Component (actions)
- Access: Free, open source
- Page: https://uiarc.dev/components/split-button
- Markdown: https://uiarc.dev/components/split-button/markdown
- Registry item: https://uiarc.dev/r/split-button.json
- Source file: `registry/components/split-button/split-button.tsx`
- Dependencies: @radix-ui/react-dropdown-menu, motion, lucide-react
- Keywords: action, menu, react split button, button with dropdown, split button menu, merge button, dropdown button, primary action with options

### When to use

- One default action with a few close variants, like Merge with Squash and Rebase.
- Export or share actions where one format is the usual pick and others sit behind the chevron.
- Copy actions that swap the label to Copied in place while offering alternatives.

### When not to use

- Use dropdown-menu when there is no default action and every option is equal.
- Use button when there are no alternatives.
- Use context-menu for actions tied to a piece of content rather than a toolbar.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/split-button
pnpm dlx shadcn@latest add @uiarc/split-button
yarn dlx shadcn@latest add @uiarc/split-button
bunx --bun shadcn@latest add @uiarc/split-button
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/split-button.json
```

#### Manual

1. Install the dependencies:

```bash
npm install @radix-ui/react-dropdown-menu motion lucide-react
```

2. Copy the source into your project. Main file: `registry/components/split-button/split-button.tsx`

   The source is in the registry item: https://uiarc.dev/r/split-button.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { SplitButton } from "@/components/arc/split-button/split-button";

export function MergeButton() {
  return (
    <SplitButton
      label="Merge pull request"
      onClick={merge}
      actions={[
        { label: "Squash and merge", onSelect: squash },
        { label: "Rebase and merge", onSelect: rebase },
        { label: "Close pull request", onSelect: close, destructive: true },
      ]}
    />
  );
}
```

### API reference

#### SplitButton

A primary action joined to a chevron that opens a Radix dropdown of related actions.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` (required) | `string` | – | Main action label. Changes morph letter by letter. |
| `actions` (required) | `SplitButtonAction[]` | – | Menu items: { label, onSelect?, disabled?, destructive?, icon? }. |
| `onClick` | `() => void` | – | Runs the main action. |
| `icon` | `ReactNode` | – | Leading icon on the main half. A different icon element crossfades in. |
| `variant` | `"primary" \| "secondary"` | `"primary"` | Visual weight of both halves. |
| `disabled` | `boolean` | – | Disables both the main action and the menu trigger. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Enter / Space | Runs the main action, or opens the menu from the chevron. |
| ArrowDown / ArrowUp | Moves between menu items, looping at the ends. |
| Escape | Closes the menu and returns focus to the chevron. |

### Accessibility

- Two native buttons; the chevron is labelled "<label> more actions".
- The menu is a Radix DropdownMenu with menu and menuitem roles and focus management.
- The main label is announced through a polite live region when it changes.

### Motion

- The main label and icon morph in place while its width springs; the menu half never scales, so the menu opens from a still anchor.
- Menu items fade in with a short stagger.
- Reduced motion removes the press scale, width spring, and menu transform, leaving a quick opacity fade.

### Responsive behavior

- The menu opens aligned to the end of the button with 12px collision padding, so it stays on screen near viewport edges.
- The secondary variant sets a 142px minimum on the main half; the pair does not collapse on narrow screens, so give it its own row on mobile.

### Performance

- The main label animates per letter with a ResizeObserver-driven width spring; the menu mounts only while open through a Radix portal.

### Notes for AI

- Use when one action is the default and two to five close variants exist. For a menu with no default action use dropdown-menu.
- Keep the menu actions as variations of the main action; put unrelated commands elsewhere.
- Swap label and icon (Copy page → Copied) to show the result in place.

### Related

- [Button](https://uiarc.dev/components/button/markdown): A clear, responsive action with quiet secondary states.
- [Dropdown menu](https://uiarc.dev/components/dropdown-menu/markdown): A focused list of actions anchored to a trigger.
- [Action button](https://uiarc.dev/components/action-button/markdown): A compact button for frequent toolbar actions.
- [Copy button](https://uiarc.dev/components/copy-button/markdown): Copy a value with immediate confirmation.

### Also in buttons

- [Button group](https://uiarc.dev/components/button-group/markdown): Related actions joined into one surface with hairline dividers: a hover highlight glides between segments, the pressed one answers in place, and an attached menu can close the row.
- [Floating button group](https://uiarc.dev/components/floating-button-group/markdown): Separate soft buttons in a quiet tray, with one shared highlight that morphs from button to button as you move, and a pressed state that settles in place.
- [Expanding button group](https://uiarc.dev/components/expanding-button-group/markdown): Icon buttons in a compact group: the one you point at or focus grows to reveal its label while its neighbours slide aside, and an action confirms in place.
- [Action swap](https://uiarc.dev/components/action-swap/markdown): Swap an action label while preserving its place and intent.
- [Icon morph](https://uiarc.dev/components/icon-morph/markdown): Icons that morph between states: menu to close, play to pause, copy to check, and more.
- [Confirm morph](https://uiarc.dev/components/confirm-morph/markdown): A destructive button that morphs into an inline confirmation, a spinner, and a result with undo.

### Guidance for AI tools

Split button: A primary action with a menu of nearby alternatives. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Button group

> Related actions joined into one surface with hairline dividers: a hover highlight glides between segments, the pressed one answers in place, and an attached menu can close the row.

- Type: Component (actions)
- Access: Free, open source
- Page: https://uiarc.dev/components/button-group
- Markdown: https://uiarc.dev/components/button-group/markdown
- Registry item: https://uiarc.dev/r/button-group.json
- Source file: `registry/components/button-group/button-group.tsx`
- Dependencies: motion, @radix-ui/react-dropdown-menu, lucide-react
- Keywords: action, group, toolbar, new, button group, joined buttons, action group, segmented buttons, button bar, attached buttons, zoom controls, more actions, dropdown, split, actions

### When to use

- A small set of related actions on the same object, shown together in a header, toolbar or card footer.
- Compact tool clusters such as zoom out, the current level and zoom in, or stacked map controls.
- A primary action row, such as Reply, Reply all and Forward on a message.

### When not to use

- Use toggle-group or segmented-control when the segments are options that stay selected.
- Use split-button when there is one main action and a few variants of it.
- Use separate buttons when the actions are unrelated or one of them is much more important than the rest.
- Use tabs for switching between views.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/button-group
pnpm dlx shadcn@latest add @uiarc/button-group
yarn dlx shadcn@latest add @uiarc/button-group
bunx --bun shadcn@latest add @uiarc/button-group
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

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

#### Manual

1. Install the dependencies:

```bash
npm install motion @radix-ui/react-dropdown-menu lucide-react
```

2. Copy the source into your project. Main file: `registry/components/button-group/button-group.tsx`

   The source is in the registry item: https://uiarc.dev/r/button-group.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { Archive, Check, CopyPlus, Link, Pin, Trash2 } from "lucide-react";
import { ButtonGroup } from "@/components/arc/button-group/button-group";

export function DocumentActions({ doc }: { doc: Doc }) {
  const [copied, setCopied] = useState(false);
  return (
    <ButtonGroup
      label="Document actions"
      items={[
        {
          id: "share",
          label: copied ? "Copied" : "Share",
          reserve: ["Share", "Copied"],
          icon: copied ? <Check /> : <Link />,
          onSelect: async () => {
            await navigator.clipboard.writeText(doc.url);
            setCopied(true);
            setTimeout(() => setCopied(false), 1800);
          },
        },
        { id: "duplicate", label: "Duplicate", icon: <CopyPlus />, onSelect: () => duplicate(doc.id) },
        { id: "archive", label: "Archive", icon: <Archive />, onSelect: () => archive(doc.id) },
      ]}
      menu={{
        label: "More actions",
        items: [
          { id: "pin", label: "Pin to sidebar", icon: <Pin />, onSelect: () => pin(doc.id) },
          { id: "delete", label: "Delete", icon: <Trash2 />, destructive: true, onSelect: () => remove(doc.id) },
        ],
      }}
    />
  );
}
```

### API reference

#### ButtonGroup

Related actions joined into one surface with hairline dividers: a hover highlight glides between segments, the pressed one answers in place, and an attached menu can close the row.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `items` (required) | `{ id: string; label: string; reserve?: string[]; icon?: ReactNode; iconOnly?: boolean; content?: ReactNode; onSelect?: () => void; href?: string; disabled?: boolean }[]` | – | The segments in order. label is the visible text and the accessible name; changing it right after a press ("Share" to "Copied") crossfades in place and is announced. reserve lists every other label the segment can show, so it is sized to the widest and never resizes; a label nobody reserved springs the width instead. iconOnly shows only the icon and moves the label to aria-label and the tooltip. content replaces the visible label with a live value, such as a zoom level. href renders a link. |
| `label` (required) | `string` | – | Accessible name of the group, such as "Document actions". |
| `menu` | `{ label: string; items: { id: string; label: string; icon?: ReactNode; onSelect?: () => void; href?: string; disabled?: boolean; destructive?: boolean }[] }` | – | Adds a trailing chevron segment that opens more actions. menu.label names the chevron, such as "More actions". The menu aligns to the group's end edge (start edge when vertical). |
| `variant` | `"outline" \| "solid"` | `"outline"` | outline sits on a neutral surface with a quiet border. solid takes the primary button's fill, for the main actions of a view. |
| `size` | `"sm" \| "md"` | `"md"` | Matches the small and medium button heights. |
| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | Vertical stacks the segments, such as zoom controls on a canvas; arrow up and down then move between them. |
| `collapseLabels` | `boolean` | `true` | When a horizontal row no longer fits its container, segments with an icon drop their label and keep the icon (the label moves to aria-label and the tooltip). Labels return once the container is wide enough again. |
| `disabled` | `boolean` | `false` | Disables every segment and the menu. |
| `className` | `string` | – | Extra class on the group. |
| `style` | `CSSProperties` | – | Inline styles on the group. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Tab / Shift+Tab | Moves into, through and out of the group. Every segment is a tab stop, so the group behaves like the buttons it replaces. |
| Arrow right / Arrow left | Also moves between segments in a horizontal group, wrapping at the ends (mirrored in right to left layouts). |
| Arrow down / Arrow up | Moves between segments in a vertical group. On the chevron segment, Arrow down opens the menu instead. |
| Home / End | Moves to the first or last segment. |
| Enter / Space | Activates the focused segment. Link segments follow the link with Enter. |
| Enter / Space / Arrow down | On the chevron segment: opens the menu with the first item highlighted. |
| Arrow keys / Home / End | In the menu: moves between items, looping at the ends; disabled items are skipped. |
| Escape | Closes the menu and returns focus to the chevron. |
| Tab (menu open) | Closes the menu and moves on, since the menu is non-modal. |

### Accessibility

- The root is a div with role="group" named by label. Segments are native buttons (or links with href), so they keep their own roles and activation keys.
- Disabled segments use aria-disabled instead of the disabled attribute, so they stay focusable and are read as dimmed; their onSelect never runs. A disabled whole group uses the disabled attribute.
- Icon-only segments, segments with content and collapsed segments take their label as aria-label and as a tooltip; icons are hidden from assistive technology.
- When a segment's label changes within a second of its press, such as "Share" to "Copied", a polite live region in the group announces the new label once; the quiet return to "Share" is not announced.
- The chevron segment is a Radix dropdown trigger named by menu.label, with aria-expanded and aria-haspopup. The menu manages focus, typeahead, Escape and outside clicks, and returns focus to the chevron. It is non-modal, so opening it never locks scroll or shifts the page.
- Keyboard focus moves the same highlight the pointer does; pointer focus draws no ring and keyboard focus shows Arc's shared focus ring. A mouse click focuses without the highlight, so nothing stays lit after the pointer leaves.
- State is never carried by color alone: confirmations change the label and icon, and disabled segments are dimmed and announced.

### Motion

- One highlight lives under all segments. Moving the pointer or keyboard focus to another segment carries it there on the snappy spring; arriving from outside the group it fades in where it lands, so it only travels between segments.
- The hairline dividers on either side of the highlighted segment fade out, so the highlight reads as one soft shape inside the joined surface.
- A press dips the segment's content to 0.97 (0.9 for icon-only) and springs back, while the highlight under it deepens. The group and its neighbours never move. The chevron anchors the menu, so it answers with the deeper highlight only.
- On touch, the highlight appears under the finger while pressed and fades on release.
- Nothing in the group moves or resizes on hover, focus, press, menu open or a label change: every reserved label sits invisibly in the segment, so a confirmation crossfades inside a fixed box. The new label rises in from a soft blur while the old one lifts away.
- A label that was not reserved never snaps either: the segment springs to its width on the morph spring, and the highlight stays locked to it while it resizes.
- The highlight is measured at sub-pixel precision, so it sits exactly on its segment at rest.
- The menu grows from the group's edge with a short offset and scale and leaves faster than it arrives; the chevron turns over while it is open.
- With reduced motion, the highlight jumps between segments, the press dip and chevron turn are removed, and labels and the menu crossfade.

### Responsive behavior

- A horizontal group never exceeds its container: when it would, segments with an icon drop their label (collapseLabels), and anything still too wide scrolls sideways without a visible scrollbar. At 320px the document example collapses to icons with its names kept as tooltips and aria-labels.
- The vertical orientation suits narrow rails and canvas corners; segments stretch to the widest one.
- Segments are 34px tall at sm and 42px at md inside the border, matching the button heights. The highlight follows the pointer only for mouse and pen; touch gets it while pressed.

### Performance

- The highlight is one element moved by transforms and size motion values; segments never re-render on hover beyond a state update in the group.
- Two ResizeObservers per group keep the highlight on its segment and decide when labels collapse; each label slot has its own observer for the width morph.
- The menu renders only while open.

### Notes for AI

- Choose it for two to five related actions on one object, such as a document's Share, Duplicate and Archive, or zoom controls. Put rarely used and destructive actions in menu.
- It is an action group: every segment does something now. For choosing one or more options that stay pressed, use toggle-group or segmented-control instead.
- Give confirmations by changing an item's label and icon ("Share" to "Copied") and resetting it after a moment, and list every label in reserve so the row never resizes. Keep confirmation labels close in length to the resting label, since the segment takes the widest.
- Use iconOnly only for actions with universally understood icons (zoom, alignment, playback). The label still names the action for screen readers and the tooltip.
- Use the solid variant for the main actions of a view, at most once per screen; outline for everything else.

### Related

- [Button](https://uiarc.dev/components/button/markdown): A clear, responsive action with quiet secondary states.
- [Split button](https://uiarc.dev/components/split-button/markdown): A primary action with a menu of nearby alternatives.
- [Toggle group](https://uiarc.dev/components/toggle-group/markdown): A row of icon or text toggles, single or multiple: one pressed fill glides between options, or each fades in on its own and neighbours join, as in a formatting toolbar.
- [Segmented control](https://uiarc.dev/components/segmented-control/markdown): Switch between a small set of related views.
- [Floating button group](https://uiarc.dev/components/floating-button-group/markdown): Separate soft buttons in a quiet tray, with one shared highlight that morphs from button to button as you move, and a pressed state that settles in place.
- [Expanding button group](https://uiarc.dev/components/expanding-button-group/markdown): Icon buttons in a compact group: the one you point at or focus grows to reveal its label while its neighbours slide aside, and an action confirms in place.

### Also in buttons

- [Action button](https://uiarc.dev/components/action-button/markdown): A compact button for frequent toolbar actions.
- [Copy button](https://uiarc.dev/components/copy-button/markdown): Copy a value with immediate confirmation.
- [Action swap](https://uiarc.dev/components/action-swap/markdown): Swap an action label while preserving its place and intent.
- [Icon morph](https://uiarc.dev/components/icon-morph/markdown): Icons that morph between states: menu to close, play to pause, copy to check, and more.
- [Confirm morph](https://uiarc.dev/components/confirm-morph/markdown): A destructive button that morphs into an inline confirmation, a spinner, and a result with undo.

### Guidance for AI tools

Button group: Related actions joined into one surface with hairline dividers: a hover highlight glides between segments, the pressed one answers in place, and an attached menu can close the row. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Floating button group

> Separate soft buttons in a quiet tray, with one shared highlight that morphs from button to button as you move, and a pressed state that settles in place.

- Type: Component (actions)
- Access: Free, open source
- Page: https://uiarc.dev/components/floating-button-group
- Markdown: https://uiarc.dev/components/floating-button-group/markdown
- Registry item: https://uiarc.dev/r/floating-button-group.json
- Source file: `registry/components/floating-button-group/floating-button-group.tsx`
- Dependencies: motion, lucide-react, @radix-ui/react-tooltip
- Keywords: action, group, toolbar, new, button group, floating toolbar, action bar, editor toolbar, selection toolbar, tools rail, hover highlight, shared highlight, icon buttons

### When to use

- A floating editor or canvas toolbar with undo, redo, share and present.
- A selection toolbar that appears over text or objects.
- A vertical tools rail with zoom and insert actions.

### When not to use

- Use toggle-group for formatting toggles or alignment where the choice stays pressed.
- Use segmented-control to switch between views.
- Use split-button when there is one main action with a few alternatives.
- Use a dropdown menu when there are more actions than fit in one row.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/floating-button-group
pnpm dlx shadcn@latest add @uiarc/floating-button-group
yarn dlx shadcn@latest add @uiarc/floating-button-group
bunx --bun shadcn@latest add @uiarc/floating-button-group
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/floating-button-group.json
```

#### Manual

1. Install the dependencies:

```bash
npm install motion lucide-react @radix-ui/react-tooltip
```

2. Copy the source into your project. Main file: `registry/components/floating-button-group/floating-button-group.tsx`

   The source is in the registry item: https://uiarc.dev/r/floating-button-group.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { Link2, MessageCircle, Play, Redo2, Undo2 } from "lucide-react";
import { FloatingButtonGroup } from "@/components/arc/floating-button-group/floating-button-group";

export function BoardToolbar({ history, copied, copyLink, presenting, onPresent }: BoardToolbarProps) {
  return (
    <FloatingButtonGroup
      label="Board actions"
      variant="floating"
      items={[
        { id: "undo", label: "Undo", icon: <Undo2 />, iconOnly: true, shortcut: "⌘Z", disabled: !history.canUndo, onSelect: history.undo },
        { id: "redo", label: "Redo", icon: <Redo2 />, iconOnly: true, shortcut: "⇧⌘Z", disabled: !history.canRedo, onSelect: history.redo },
        { type: "separator" },
        { id: "comment", label: "Comment", icon: <MessageCircle />, shortcut: "C" },
        { id: "share", label: copied ? "Copied" : "Share", reserveLabels: ["Share", "Copied"], icon: <Link2 />, onSelect: copyLink },
        { type: "separator" },
        { id: "present", label: presenting ? "Stop" : "Present", reserveLabels: ["Present", "Stop"], icon: <Play />, pressed: presenting, onSelect: onPresent },
      ]}
      onAction={id => track("toolbar", id)}
    />
  );
}
```

### API reference

#### FloatingButtonGroup

Separate soft buttons in a quiet tray, with one shared highlight that morphs from button to button as you move, and a pressed state that settles in place. An action toolbar: each button does something; nothing stays selected. For a set of options where one or more stay chosen, use toggle-group.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `items` (required) | `({ id: string; label: string; icon?: ReactNode; iconOnly?: boolean; onSelect?: () => void; disabled?: boolean; pressed?: boolean; shortcut?: string; reserveLabels?: string[] } \| { type: "separator"; id?: string })[]` | – | The buttons in order. A separator draws a short rule between logical clusters. label is the visible text and the accessible name; iconOnly moves it into a tooltip. pressed marks an action that switches a mode on, such as Present, with aria-pressed and a quiet tint. shortcut is shown in the tooltip only; the component does not bind the key. reserveLabels lists the other labels an item can switch to, such as ["Share", "Copied"]: the button always has the width of the widest, so a label change never resizes the button, its neighbours or the tray. |
| `label` (required) | `string` | – | Accessible name of the toolbar, such as "Board actions". |
| `variant` | `"muted" \| "floating"` | `"muted"` | muted sits quietly on a page on the muted surface. floating raises the tray with a hairline edge and the floating shadow, for overlays such as a selection or canvas toolbar. |
| `size` | `"sm" \| "md"` | `"md"` | Button height of 30 or 36px, with matching tray padding, gaps and corner radius. |
| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | A row or a column, such as a tools rail. Arrow keys follow the orientation. |
| `iconOnly` | `boolean` | `false` | Shows every item with an icon as an icon only. An item's own iconOnly wins, so a toolbar can mix icon buttons with labelled ones. |
| `tooltipSide` | `"top" \| "bottom" \| "left" \| "right"` | `"top" for a row, "right" for a column` | Where item tooltips open. Top and bottom use the library Tooltip; left and right open beside a column without covering its neighbours. |
| `onAction` | `(id: string) => void` | – | Called with the item id after the item's own onSelect, for handling every action in one place. |
| `className` | `string` | – | Extra class on the tray. |
| `style` | `CSSProperties` | – | Inline styles on the tray. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Tab | Moves into the toolbar on one button, the last one focused, and out again. The highlight appears on the focused button. |
| Arrow left / Arrow right | In a row: moves focus to the previous or next enabled button, wrapping at the ends. The highlight follows. |
| Arrow up / Arrow down | In a column: moves focus to the previous or next enabled button, wrapping at the ends. |
| Home / End | Moves focus to the first or last enabled button. |
| Enter / Space | Runs the focused action. The highlight darkens while the key is held. |

### Accessibility

- The tray is a toolbar with aria-label and aria-orientation, and a single tab stop that roves between buttons.
- Every button has an accessible name from its label, also when it shows only an icon. Icon only buttons and buttons with a shortcut get a tooltip with the label and shortcut, which screen readers hear as the description.
- Mode actions set aria-pressed. Disabled actions use aria-disabled, stay readable with their tooltip, and are skipped by the arrow keys.
- Separators have the separator role with the orientation across the toolbar.
- Pointer focus draws no ring; keyboard focus shows Arc's shared focus ring. The shared highlight is the keyboard indicator, shown only for keyboard focus so a mouse click never leaves it behind.
- When a label changes, such as Share to Copied, the accessible name changes with it and the outgoing label is hidden from assistive technology while it fades. Reserved label ghosts are hidden from assistive technology.

### Motion

- One highlight per tray, driven by motion values so moving it never re-renders the buttons. It travels in position and size to the hovered or focused button on the morph spring, and stays put while the pointer crosses a gap or a separator.
- Appearing from nothing it lands in place and grows in from 94 percent on the snappy spring, instead of sliding from wherever it last was. It fades when the pointer leaves the tray.
- Pressing darkens the highlight and settles it to 96.5 percent in place on the snappy spring; the buttons themselves never scale, so neighbours and tooltip anchors stay still.
- A new label crossfades in place with a short rise and blur. With reserveLabels the button already has the widest label's width, so nothing around it moves; without it, the highlight re-measures and follows the new width.
- Nothing but the highlight ever moves: hover, focus, press and label changes leave the tray and every button at the same box. The highlight is measured exactly in tray coordinates, snapped to device pixels and corrected for ancestor transforms.
- The pointer leaving the tray is detected with a native listener, because React bubbles pointer events through portals and a tooltip would otherwise count as inside the tray.
- With reduced motion the highlight jumps to its button and fades briefly, and labels crossfade without travel.

### Responsive behavior

- The tray keeps its natural size and never wraps or clips a button. At narrow widths make secondary items icon only; to switch without a layout shift after hydration, render both densities and pick one with a container query, as the demo does below 360px.
- Touch shows the highlight under the finger while pressed and fades it on release; hover only tracks a mouse or pen.
- The highlight re-measures when the tray or any button resizes, so it stays aligned through font loading, label changes and container reflow.

### Performance

- The highlight moves on transform and size through motion values without React renders; only hover and focus changes re-render the buttons.
- One ResizeObserver per tray, observing the tray and its buttons. Reserved labels are plain CSS grid ghosts, measured by layout, not by script.

### Notes for AI

- Use it for actions, not selection. When one or more options stay chosen, use toggle-group or segmented-control.
- Group related actions with separators and keep a toolbar to about seven buttons. Make secondary actions icon only before dropping labels from the main one.
- Give every icon only item a specific label, such as "Zoom to fit", not "Fit".
- shortcut is a hint only. Bind the key yourself, scoped so it does not fight the page.
- Pass reserveLabels whenever an item's label changes, so the toolbar never shifts.
- Use variant floating when the toolbar sits over content such as a canvas or a text selection; use muted in a page or a panel.

### Related

- [Toggle group](https://uiarc.dev/components/toggle-group/markdown): A row of icon or text toggles, single or multiple: one pressed fill glides between options, or each fades in on its own and neighbours join, as in a formatting toolbar.
- [Button group](https://uiarc.dev/components/button-group/markdown): Related actions joined into one surface with hairline dividers: a hover highlight glides between segments, the pressed one answers in place, and an attached menu can close the row.
- [Expanding button group](https://uiarc.dev/components/expanding-button-group/markdown): Icon buttons in a compact group: the one you point at or focus grows to reveal its label while its neighbours slide aside, and an action confirms in place.
- [Split button](https://uiarc.dev/components/split-button/markdown): A primary action with a menu of nearby alternatives.
- [Segmented control](https://uiarc.dev/components/segmented-control/markdown): Switch between a small set of related views.
- [Tooltip](https://uiarc.dev/components/tooltip/markdown): Short supporting text for unfamiliar controls.

### Also in buttons

- [Button](https://uiarc.dev/components/button/markdown): A clear, responsive action with quiet secondary states.
- [Action button](https://uiarc.dev/components/action-button/markdown): A compact button for frequent toolbar actions.
- [Copy button](https://uiarc.dev/components/copy-button/markdown): Copy a value with immediate confirmation.
- [Action swap](https://uiarc.dev/components/action-swap/markdown): Swap an action label while preserving its place and intent.
- [Icon morph](https://uiarc.dev/components/icon-morph/markdown): Icons that morph between states: menu to close, play to pause, copy to check, and more.
- [Confirm morph](https://uiarc.dev/components/confirm-morph/markdown): A destructive button that morphs into an inline confirmation, a spinner, and a result with undo.

### Guidance for AI tools

Floating button group: Separate soft buttons in a quiet tray, with one shared highlight that morphs from button to button as you move, and a pressed state that settles in place. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Expanding button group

> Icon buttons in a compact group: the one you point at or focus grows to reveal its label while its neighbours slide aside, and an action confirms in place.

- Type: Component (actions)
- Access: Free, open source
- Page: https://uiarc.dev/components/expanding-button-group
- Markdown: https://uiarc.dev/components/expanding-button-group/markdown
- Registry item: https://uiarc.dev/r/expanding-button-group.json
- Source file: `registry/components/expanding-button-group/expanding-button-group.tsx`
- Dependencies: motion, lucide-react
- Keywords: action, group, toolbar, new, button group, icon buttons, expanding, reveal label, hover label, action bar, message actions, file actions, confirm in place, morph, pill

### When to use

- A compact action bar on a message, file, or card where space is tight but labels should be one glance away.
- Toolbars where actions finish in place and deserve a confirmation without a toast, such as Archive or Copy link.

### When not to use

- Use toggle-group or segmented-control when the buttons select a value instead of running an action.
- Use plain labelled buttons when there are only one or two actions and space allows; hiding labels then costs clarity.
- Use a dropdown menu for more than about six actions, or for actions that need descriptions.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/expanding-button-group
pnpm dlx shadcn@latest add @uiarc/expanding-button-group
yarn dlx shadcn@latest add @uiarc/expanding-button-group
bunx --bun shadcn@latest add @uiarc/expanding-button-group
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/expanding-button-group.json
```

#### Manual

1. Install the dependencies:

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

2. Copy the source into your project. Main file: `registry/components/expanding-button-group/expanding-button-group.tsx`

   The source is in the registry item: https://uiarc.dev/r/expanding-button-group.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { Archive, Clock3, Forward, Reply, Trash2 } from "lucide-react";
import { ExpandingButtonGroup } from "@/components/arc/expanding-button-group/expanding-button-group";

export function MessageActions({ message }: { message: Message }) {
  return (
    <ExpandingButtonGroup
      label="Message actions"
      defaultExpanded="reply"
      items={[
        { id: "reply", label: "Reply", icon: <Reply />, onSelect: () => openReply(message.id) },
        { id: "forward", label: "Forward", icon: <Forward />, onSelect: () => openForward(message.id) },
        { id: "archive", label: "Archive", doneLabel: "Archived", icon: <Archive />, onSelect: () => archive(message.id) },
        { id: "snooze", label: "Snooze", doneLabel: "Snoozed", icon: <Clock3 />, onSelect: () => snooze(message.id, "tomorrow-8am") },
        { id: "delete", label: "Delete", doneLabel: "Deleted", tone: "danger", icon: <Trash2 />, onSelect: () => moveToTrash(message.id) },
      ]}
    />
  );
}
```

### API reference

#### ExpandingButtonGroup

Icon buttons in a compact group where one action always shows its label. The one you point at or focus takes the label over while its neighbours slide aside, and an action confirms in place.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `items` (required) | `{ id: string; label: string; icon: ReactNode; onSelect?: () => void \| boolean \| Promise<void \| boolean>; doneLabel?: string; tone?: "neutral" \| "danger"; disabled?: boolean }[]` | – | The actions, in order. label is shown when the button expands and is always its accessible name. With doneLabel, a successful onSelect turns the icon into a check and the label into that word, such as "Archived". Return false or reject to skip it; a promise keeps the button busy until it settles. |
| `label` (required) | `string` | – | Accessible name of the toolbar, such as "Message actions". |
| `size` | `"sm" \| "md"` | `"md"` | Button height of 28 or 36px, with 14 or 16px icons. |
| `defaultExpanded` | `string \| null` | `First enabled action` | Id of the action whose label shows at rest, usually the primary one. One action is always expanded: pointing at or focusing another moves the expansion there, and the group returns to this one when the pointer and focus leave. |
| `onAction` | `(id: string) => void` | – | Called with the item id whenever an action runs, before the item's own onSelect. |
| `confirmDuration` | `number` | `1400` | How long the confirmation stays, in milliseconds. |
| `className` | `string` | – | Extra class on the toolbar. |
| `style` | `CSSProperties` | – | Inline styles on the toolbar. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Tab | Moves into the toolbar onto one action (the last focused, else the resting one) and out again. |
| Arrow left / Arrow right | Moves focus to the previous or next action, wrapping at the ends. The focused action expands to show its label. |
| Home / End | Moves focus to the first or last action. |
| Enter / Space | Runs the focused action. |

### Accessibility

- The root is a toolbar named by label, with one tab stop and roving arrow key focus.
- Each button keeps its full label as its accessible name while collapsed; the visible label and icon are hidden from assistive technology so nothing is read twice.
- Disabled actions use aria-disabled instead of disabled, so they stay focusable and still reveal their label, but do nothing when activated.
- A confirmation is announced through a polite live region, such as "Archived". The same word is announced again on a repeat action.
- A busy action (a promise from onSelect) sets aria-busy until it settles.
- The expansion itself is the focus indicator; pointer focus draws no ring and keyboard focus shows Arc's shared focus ring. Only keyboard focus expands, so a mouse click does not leave a label open after the pointer leaves.
- Confirmation is never color alone: the icon becomes a check and the label changes to a past tense word.

### Motion

- Each button's width springs on the morph spring between its icon size and icon plus measured label. Neighbours slide aside in normal flow and the group's own width follows, so nothing resizes in a single frame.
- The label slot always reserves the longer of label and doneLabel, so the confirmation never changes the width. The server render already shows the resting action at that exact width, so hydration moves nothing.
- Anchor the group at its start edge (not centred) and reserve its widest width in the layout, so expansion only moves buttons inside the group.
- The icon keeps the same left inset in both states; the label slides out from behind it with a short fade and blur, and tucks back faster than it came.
- A confirmation draws a check where the icon was and lifts the old word out while the new one rises in, while the width springs between the two words.
- Hover only follows real pointer movement, and moving to a neighbour needs the pointer 4px inside it, so a button that slides under a resting pointer never takes over and a pointer resting on a boundary never flips between two actions.
- Pressing shrinks the icon slightly; the button box never scales, because its width is the animation.
- With reduced motion, labels and widths change at once with a quick fade and the check appears without drawing.

### Responsive behavior

- Five medium actions with one label open take about 260 to 280px, depending on the longest label. Reserve that width in narrow layouts rather than letting the group squeeze content.
- Touch has no hover: the first tap expands an action and the second runs it. A tap outside the group closes a label opened by touch.
- Buttons are 36px tall at md and 28px at sm; use md where touch matters.

### Performance

- Each label is measured from invisible copies in its own slot (and again if its font or text changes) with a ResizeObserver; width is a Motion value, so React renders only when the expanded action changes.
- Width animation causes layout in the group only; keep the group out of large reflowing containers.

### Notes for AI

- Use it for a row of three to six related actions on one object, where icons are recognisable but labels help: message, file and card actions.
- Give every action a short verb label and a matching lucide icon. Use doneLabel only for actions that finish at once (Archive, Snooze, Copy link); leave it out for actions that open something (Reply, Rename).
- Mark at most one destructive action with tone="danger". It needs no confirm dialog when the surrounding UI offers Undo.
- One action is always expanded. Put the primary action first, or set defaultExpanded to it, so it reads as a labelled button at rest.
- This is an action group. For choosing one or several values use toggle-group or segmented-control.
- On touch the first tap reveals the label and a second tap runs it; the resting action runs on the first tap.
- Place it start aligned in a row that reserves its widest width, so the expansion never moves surrounding content.

### Related

- [Button group](https://uiarc.dev/components/button-group/markdown): Related actions joined into one surface with hairline dividers: a hover highlight glides between segments, the pressed one answers in place, and an attached menu can close the row.
- [Floating button group](https://uiarc.dev/components/floating-button-group/markdown): Separate soft buttons in a quiet tray, with one shared highlight that morphs from button to button as you move, and a pressed state that settles in place.
- [Toggle group](https://uiarc.dev/components/toggle-group/markdown): A row of icon or text toggles, single or multiple: one pressed fill glides between options, or each fades in on its own and neighbours join, as in a formatting toolbar.
- [Action button](https://uiarc.dev/components/action-button/markdown): A compact button for frequent toolbar actions.
- [Confirm morph](https://uiarc.dev/components/confirm-morph/markdown): A destructive button that morphs into an inline confirmation, a spinner, and a result with undo.
- [Swipe actions](https://uiarc.dev/components/swipe-actions/markdown): Reveal row actions with a swipe, or from the same actions in a menu.

### Also in buttons

- [Button](https://uiarc.dev/components/button/markdown): A clear, responsive action with quiet secondary states.
- [Split button](https://uiarc.dev/components/split-button/markdown): A primary action with a menu of nearby alternatives.
- [Copy button](https://uiarc.dev/components/copy-button/markdown): Copy a value with immediate confirmation.
- [Action swap](https://uiarc.dev/components/action-swap/markdown): Swap an action label while preserving its place and intent.
- [Icon morph](https://uiarc.dev/components/icon-morph/markdown): Icons that morph between states: menu to close, play to pause, copy to check, and more.

### Guidance for AI tools

Expanding button group: Icon buttons in a compact group: the one you point at or focus grows to reveal its label while its neighbours slide aside, and an action confirms in place. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Copy button

> Copy a value with immediate confirmation.

- Type: Component (actions)
- Access: Free, open source
- Page: https://uiarc.dev/components/copy-button
- Markdown: https://uiarc.dev/components/copy-button/markdown
- Registry item: https://uiarc.dev/r/copy-button.json
- Source file: `registry/components/copy-button/copy-button.tsx`
- Dependencies: motion, lucide-react
- Keywords: action, utility, react copy button, copy to clipboard, copy button animation, clipboard button, copy code button, copied feedback

### When to use

- Next to API keys, install commands, links, or code snippets.
- Icon-only copy controls in dense rows, with an accessible label.
- Any copy action that should confirm Copied or Could not copy in place.

### When not to use

- Use split-button when copying has alternatives, such as Copy link and Copy as Markdown.
- Use code-block for full code samples, which include their own copy control.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/copy-button
pnpm dlx shadcn@latest add @uiarc/copy-button
yarn dlx shadcn@latest add @uiarc/copy-button
bunx --bun shadcn@latest add @uiarc/copy-button
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/copy-button.json
```

#### Manual

1. Install the dependencies:

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

2. Copy the source into your project. Main file: `registry/components/copy-button/copy-button.tsx`

   The source is in the registry item: https://uiarc.dev/r/copy-button.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { CopyButton } from "@/components/arc/copy-button/copy-button";

export function ApiKeyRow({ apiKey }: { apiKey: string }) {
  return (
    <div className="row">
      <code>{apiKey}</code>
      <CopyButton value={apiKey} label="Copy key" iconOnly />
    </div>
  );
}
```

### API reference

#### CopyButton

Copies a string to the clipboard and crossfades its icon and label to Copied or Failed.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` (required) | `string` | – | The text to copy. |
| `label` | `string` | `"Copy"` | Idle label and accessible name. |
| `iconOnly` | `boolean` | `false` | Hides the text and shows only the icon. |
| `variant` | `"outline" \| "plain"` | `"outline"` | Bordered or borderless. |
| `disabled` | `boolean` | – | Disables the button. |
| `onCopied` | `() => void` | – | Called after a successful copy. |
| `className` | `string` | – | Extra class on the button. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Enter / Space | Copies the value. |

### Accessibility

- Native button named by label, including when iconOnly.
- A polite role="status" region announces "<label>: Copied" or "<label>: Could not copy".
- The label cell reserves the widest of its three states, so the layout never shifts.

### Motion

- The old icon and word fade out in about 100ms while the new ones fade in over about 160ms, with no blur; the check draws its stroke in.
- The label changes as one word, never letter by letter, and the same crossfade plays when it resets.
- Reduced motion swaps icon and text with an instant fade and skips the stroke draw.

### Responsive behavior

- The label reserves the width of its widest state, so the button never shifts its neighbours when it changes.
- It sizes to max-content with max-width 100%, so it stays compact in narrow rows.

### Performance

- Each copy is one short crossfade of the icon and the word (about 160ms) plus a quick stroke draw on the check; nothing animates per letter.
- Clipboard access is async and needs a secure context; failures show the Failed state rather than throwing.

### Notes for AI

- Use next to any copyable value: API keys, install commands, links, code. For a copy action that also has alternatives use split-button.
- Named export only; there is no default export.
- Clipboard state and reset timing come from lib/use-copy-feedback, so copy that file along with the component.

### Related

- [Button](https://uiarc.dev/components/button/markdown): A clear, responsive action with quiet secondary states.
- [Code block](https://uiarc.dev/components/code-block/markdown): Present code with legible hierarchy and copy access.
- [Split button](https://uiarc.dev/components/split-button/markdown): A primary action with a menu of nearby alternatives.
- [Action button](https://uiarc.dev/components/action-button/markdown): A compact button for frequent toolbar actions.

### Also in buttons

- [Button group](https://uiarc.dev/components/button-group/markdown): Related actions joined into one surface with hairline dividers: a hover highlight glides between segments, the pressed one answers in place, and an attached menu can close the row.
- [Floating button group](https://uiarc.dev/components/floating-button-group/markdown): Separate soft buttons in a quiet tray, with one shared highlight that morphs from button to button as you move, and a pressed state that settles in place.
- [Expanding button group](https://uiarc.dev/components/expanding-button-group/markdown): Icon buttons in a compact group: the one you point at or focus grows to reveal its label while its neighbours slide aside, and an action confirms in place.
- [Action swap](https://uiarc.dev/components/action-swap/markdown): Swap an action label while preserving its place and intent.
- [Icon morph](https://uiarc.dev/components/icon-morph/markdown): Icons that morph between states: menu to close, play to pause, copy to check, and more.
- [Confirm morph](https://uiarc.dev/components/confirm-morph/markdown): A destructive button that morphs into an inline confirmation, a spinner, and a result with undo.

### Guidance for AI tools

Copy button: Copy a value with immediate confirmation. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Action swap

> Swap an action label while preserving its place and intent.

- Type: Component (actions)
- Access: Free, open source
- Page: https://uiarc.dev/components/action-swap
- Markdown: https://uiarc.dev/components/action-swap/markdown
- Registry item: https://uiarc.dev/r/action-swap.json
- Source file: `registry/components/action-swap/action-swap.tsx`
- Dependencies: motion, lucide-react
- Keywords: action, motion, react toggle button, follow button, state cycling button, action swap, morphing button, send button animation, async toggle button

### When to use

- One control that cycles through related states, like Follow and Following or Send and Sent.
- Toggles that run async work on press and should show a working phase and a failure message in place.
- Short confirmations that should revert on their own after a moment, via holdFor.

### When not to use

- Use action-button for a single save or publish that ends in a success tick.
- Use button when the label never changes state.
- Use theme-switch for a light and dark toggle, since it reports the theme change for a page transition.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/action-swap
pnpm dlx shadcn@latest add @uiarc/action-swap
yarn dlx shadcn@latest add @uiarc/action-swap
bunx --bun shadcn@latest add @uiarc/action-swap
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/action-swap.json
```

#### Manual

1. Install the dependencies:

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

2. Copy the source into your project. Main file: `registry/components/action-swap/action-swap.tsx`

   The source is in the registry item: https://uiarc.dev/r/action-swap.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { ActionSwap } from "@/components/arc/action-swap/action-swap";
import { Send, Check } from "lucide-react";

export function SendInvite() {
  return (
    <ActionSwap
      states={[
        { id: "idle", label: "Send invite", icon: <Send size={16} /> },
        { id: "sent", label: "Sent", icon: <Check size={16} />, tone: "success", pendingLabel: "Sending", holdFor: 2000 },
      ]}
      onAction={next => (next.id === "sent" ? sendInvite() : undefined)}
    />
  );
}
```

### Examples

#### Follow toggle

```tsx
<ActionSwap
  states={[
    { id: "follow", label: "Follow", tone: "accent" },
    { id: "following", label: "Following", tone: "quiet", pendingLabel: "Following" },
  ]}
  onAction={next => setFollowing(next.id === "following")}
/>
```

### API reference

#### ActionSwap

A compact pill that steps through a list of states on each press, morphing icon, tone, and letters together.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `states` (required) | `ActionSwapState[]` | – | Ordered states. Each press moves to the next and wraps around. Needs at least two to be enabled. |
| `value` | `string` | – | Controlled state id. |
| `defaultValue` | `string` | – | Initial state id when uncontrolled. Defaults to the first state. |
| `onValueChange` | `(value: string, state: ActionSwapState) => void` | – | Called when the control commits to a new state. |
| `onAction` | `(next: ActionSwapState, current: ActionSwapState) => void \| PromiseLike<unknown>` | – | Runs on press. Return a promise to show a working phase; a rejection shows failureLabel and stays put. |
| `failureLabel` | `string` | `"Try again"` | Label shown for 1.8s after onAction rejects or throws. |
| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Height and padding. |
| `...props` | `ButtonHTMLAttributes<HTMLButtonElement>` | – | Forwarded to the button, except children, onClick, onChange, and value. |

#### ActionSwapState

One state in the states array.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `id` (required) | `string` | – | Stable id used by value and onValueChange. |
| `label` (required) | `string` | – | Visible label and accessible name. |
| `icon` | `ReactNode` | – | Leading icon, sized at 16px. |
| `tone` | `"neutral" \| "accent" \| "success" \| "warning" \| "quiet"` | `"neutral"` | Fill color. Success draws its icon in with a stroke wipe. |
| `pendingLabel` | `string` | – | Shown while onAction runs on the way into this state. Without it the pill folds into a round spinner. |
| `holdFor` | `number` | – | Milliseconds to hold this state before advancing on its own, for brief confirmations. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Enter / Space | Advances to the next state. |

### Accessibility

- Native button whose aria-label always matches the visible label, since the letters themselves are aria-hidden.
- The working phase sets aria-busy and aria-disabled, so focus stays on the button.
- A polite role="status" region announces each new label, pending label, and failure.

### Motion

- Width, padding, tone, and icon move on one morph spring; only the changed run of letters rises in from a soft blur.
- A working state without pendingLabel folds the pill into a circle; the working shape shows for at least 450ms.
- Reduced motion jumps width and fold and swaps icons and letters with an instant fade.

### Responsive behavior

- Width follows the current label, so keep labels similar in length to avoid shifting neighbours on narrow rows.
- Hover styles apply only on hover-capable fine pointers; on touch the press scale is the only feedback.

### Performance

- Each letter is its own motion span with layout position animation; keep labels short and avoid many swaps on one screen.
- A ResizeObserver tracks the label width for the morph spring.

### Notes for AI

- Pick this for one control that cycles through related states (Follow → Following, Send → Sent → Send). Use action-button for a single save with a success tick.
- Keep states few and labels short; the morph reads best between similar lengths.
- Do the work in onAction and return its promise; control value only when the state lives elsewhere.

### Related

- [Action button](https://uiarc.dev/components/action-button/markdown): A compact button for frequent toolbar actions.
- [Button](https://uiarc.dev/components/button/markdown): A clear, responsive action with quiet secondary states.
- [Copy button](https://uiarc.dev/components/copy-button/markdown): Copy a value with immediate confirmation.

### Also in buttons

- [Split button](https://uiarc.dev/components/split-button/markdown): A primary action with a menu of nearby alternatives.
- [Button group](https://uiarc.dev/components/button-group/markdown): Related actions joined into one surface with hairline dividers: a hover highlight glides between segments, the pressed one answers in place, and an attached menu can close the row.
- [Floating button group](https://uiarc.dev/components/floating-button-group/markdown): Separate soft buttons in a quiet tray, with one shared highlight that morphs from button to button as you move, and a pressed state that settles in place.
- [Expanding button group](https://uiarc.dev/components/expanding-button-group/markdown): Icon buttons in a compact group: the one you point at or focus grows to reveal its label while its neighbours slide aside, and an action confirms in place.
- [Icon morph](https://uiarc.dev/components/icon-morph/markdown): Icons that morph between states: menu to close, play to pause, copy to check, and more.
- [Confirm morph](https://uiarc.dev/components/confirm-morph/markdown): A destructive button that morphs into an inline confirmation, a spinner, and a result with undo.

### Guidance for AI tools

Action swap: Swap an action label while preserving its place and intent. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Icon morph

> Icons that morph between states: menu to close, play to pause, copy to check, and more.

- Type: Component (actions)
- Access: Free, open source
- Page: https://uiarc.dev/components/icon-morph
- Markdown: https://uiarc.dev/components/icon-morph/markdown
- Registry item: https://uiarc.dev/r/icon-morph.json
- Source file: `registry/components/icon-morph/icon-morph.tsx`
- Dependencies: motion
- Keywords: actions, new, react icon morph, animated icon, hamburger to close, play pause morph, copy check icon, sun moon toggle icon, like heart animation, morphing svg icon

### When to use

- Icon buttons that toggle between two states, such as a hamburger menu or a play control.
- Copy and add actions that should confirm with a check in place.
- Like and notify toggles that deserve a small moment of delight.

### When not to use

- Use copy-button for a complete copy-to-clipboard control with its own feedback.
- Use theme-switch for a labelled light and dark toggle wired to the page theme.
- Use a plain lucide icon when the icon never changes state.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/icon-morph
pnpm dlx shadcn@latest add @uiarc/icon-morph
yarn dlx shadcn@latest add @uiarc/icon-morph
bunx --bun shadcn@latest add @uiarc/icon-morph
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/icon-morph.json
```

#### Manual

1. Install the dependencies:

```bash
npm install motion
```

2. Copy the source into your project. Main file: `registry/components/icon-morph/icon-morph.tsx`

   The source is in the registry item: https://uiarc.dev/r/icon-morph.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { useState } from "react";
import { IconMorph } from "@/components/arc/icon-morph/icon-morph";

export function MenuToggle() {
  const [open, setOpen] = useState(false);
  return (
    <button type="button" aria-label="Menu" aria-expanded={open} onClick={() => setOpen(value => !value)}>
      <IconMorph name="menu" state={open} size={20} />
    </button>
  );
}
```

### API reference

#### IconMorph

One entry point for eight two-state icons that morph instead of swapping. Pick one by name and drive it with state.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `name` (required) | `"menu" \| "play" \| "plus" \| "copy" \| "theme" \| "chevron" \| "bell" \| "heart"` | – | Which icon to render. |
| `state` | `boolean` | `false` | The second state: menu to close, play to pause, plus or copy to check, sun to moon, chevron turned, bell on, heart liked. |
| `size` | `number` | `24` | Rendered size in px. |
| `strokeWidth` | `number` | `1.75` | Stroke width in the 24 unit grid. |
| `...props` | `Omit<SVGProps<SVGSVGElement>, "ref" \| "children">` | – | Forwarded to the svg. |

#### MenuIcon

Menu to close: outer lines rotate into an X and the middle line folds away. Takes the same props as IconMorph without name.

No props.

#### PlayPauseIcon

Play to pause: the triangle splits into two halves that straighten into bars.

No props.

#### PlusCheckIcon

Plus to check: each bar swings its ends into one leg of the check.

No props.

#### CopyCheckIcon

Copy to check: the sheets tuck away and a check draws in.

No props.

#### SunMoonIcon

Sun to moon: the disc grows while a shadow carves the crescent and the rays fold in.

No props.

#### ChevronIcon

A chevron that turns on a spring, for disclosure and sort controls.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `turn` | `number` | `180` | Degrees the chevron turns when state is true. 180 flips down to up; 90 turns right to down. |
| `pointing` | `"down" \| "right"` | `"down"` | Where the chevron points at rest. |

#### BellIcon

Notifications: turning on rings the bell with a lagging clapper; turning off strikes it through.

No props.

#### HeartIcon

Like: the heart fills with a pop and a ring and sparks burst once. Liked color is --icon-morph-like, default --danger.

No props.

### Accessibility

- Every icon renders aria-hidden and focusable="false"; put it inside a button that carries the accessible name.
- Reflect the state on the button with aria-pressed, aria-expanded, or a changing label, since the icon itself says nothing.

### Motion

- Lines rotate and slide, and shapes interpolate their path data, all on interruptible springs, so fast toggling reverses from wherever the icon is.
- The bell ring and heart burst are one-shot moments that replay on each turn on.
- Reduced motion makes every morph instant and skips the ring and burst.

### Responsive behavior

- Icons are fixed-size SVGs on a 24 unit grid; set size per breakpoint from the parent.
- Pair with a hit area of at least 40px on touch; the icon itself adds none.

### Performance

- Each icon animates a few SVG attributes with motion; many on one screen are cheap.
- SunMoonIcon and BellIcon use an SVG mask with a per-instance id from useId.

### Notes for AI

- Use inside icon buttons whose meaning flips between two states: menu and close, play and pause, copy and copied, like and liked.
- Import the specific icon (HeartIcon, ChevronIcon) when only one is needed; IconMorph is a name switch over the same components.
- Icons use currentColor, so color them from the parent button.
- For a whole button that changes label and state use action-swap; for theme switching with a label use theme-switch.

### Related

- [Action swap](https://uiarc.dev/components/action-swap/markdown): Swap an action label while preserving its place and intent.
- [Copy button](https://uiarc.dev/components/copy-button/markdown): Copy a value with immediate confirmation.
- [Theme switcher](https://uiarc.dev/components/theme-switch/markdown): Four smooth ways to move between light and dark appearance.
- [Reactions](https://uiarc.dev/components/reactions/markdown): Acknowledge a post in one tap, with counts that roll.
- [Button](https://uiarc.dev/components/button/markdown): A clear, responsive action with quiet secondary states.

### Also in buttons

- [Action button](https://uiarc.dev/components/action-button/markdown): A compact button for frequent toolbar actions.
- [Split button](https://uiarc.dev/components/split-button/markdown): A primary action with a menu of nearby alternatives.
- [Button group](https://uiarc.dev/components/button-group/markdown): Related actions joined into one surface with hairline dividers: a hover highlight glides between segments, the pressed one answers in place, and an attached menu can close the row.
- [Floating button group](https://uiarc.dev/components/floating-button-group/markdown): Separate soft buttons in a quiet tray, with one shared highlight that morphs from button to button as you move, and a pressed state that settles in place.
- [Expanding button group](https://uiarc.dev/components/expanding-button-group/markdown): Icon buttons in a compact group: the one you point at or focus grows to reveal its label while its neighbours slide aside, and an action confirms in place.
- [Confirm morph](https://uiarc.dev/components/confirm-morph/markdown): A destructive button that morphs into an inline confirmation, a spinner, and a result with undo.

### Guidance for AI tools

Icon morph: Icons that morph between states: menu to close, play to pause, copy to check, and more. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Confirm morph

> A destructive button that morphs into an inline confirmation, a spinner, and a result with undo.

- Type: Component (actions)
- Access: Free, open source
- Page: https://uiarc.dev/components/confirm-morph
- Markdown: https://uiarc.dev/components/confirm-morph/markdown
- Registry item: https://uiarc.dev/r/confirm-morph.json
- Source file: `registry/components/confirm-morph/confirm-morph.tsx`
- Dependencies: motion, lucide-react
- Keywords: actions, new, react confirm button, inline confirmation, delete confirmation button, confirm delete without modal, undo button, two step button, destructive action button

### When to use

- Deleting a selection in a table or file list, right where the button sits.
- Revoking access, removing a member, or discarding a draft.
- Actions that should offer Undo in place after they finish.

### When not to use

- Use dialog when the consequence needs more than one line, or when typing a name to confirm is required.
- Use action-button for safe async actions that need no question.
- Use hold-to-confirm when an accidental tap must be nearly impossible.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/confirm-morph
pnpm dlx shadcn@latest add @uiarc/confirm-morph
yarn dlx shadcn@latest add @uiarc/confirm-morph
bunx --bun shadcn@latest add @uiarc/confirm-morph
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/confirm-morph.json
```

#### Manual

1. Install the dependencies:

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

2. Copy the source into your project. Main file: `registry/components/confirm-morph/confirm-morph.tsx`

   The source is in the registry item: https://uiarc.dev/r/confirm-morph.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { Trash2 } from "lucide-react";
import { ConfirmMorph } from "@/components/arc/confirm-morph/confirm-morph";

export function DeleteSelection({ ids }: { ids: string[] }) {
  return (
    <ConfirmMorph
      label="Delete files"
      icon={<Trash2 size={16} strokeWidth={1.75} />}
      prompt={`Delete ${ids.length} files?`}
      confirmMode="hold"
      onConfirm={() => deleteFiles(ids)}
      onUndo={() => restoreFiles(ids)}
    />
  );
}
```

### API reference

#### ConfirmMorph

A button for destructive or important actions that morphs in place into an inline question, then a spinner, then a result with Undo. Answer it with a click, a press and hold, or a click and a short countdown.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` (required) | `ReactNode` | – | The resting label, such as "Delete project". |
| `icon` | `ReactNode` | – | A plain icon before the resting label. |
| `prompt` | `ReactNode` | – | The question while confirming, such as "Delete 3 files?". Defaults to the label with a question mark. |
| `confirmLabel` | `string` | `"Delete"` | Confirm button label. |
| `cancelLabel` | `string` | `"Cancel"` | Cancel button label. |
| `pendingLabel` | `string` | `"Deleting"` | Shown beside the spinner while onConfirm resolves. |
| `doneLabel` | `string` | `"Deleted"` | Result label. |
| `errorLabel` | `string` | `"Couldn’t finish"` | Error label. |
| `retryLabel` | `string` | `"Retry"` | Retry button label on the error face. |
| `undoLabel` | `string` | `"Undo"` | Undo button label. |
| `undoingLabel` | `string` | `"Restoring"` | Shown beside the spinner while onUndo resolves. |
| `tone` | `"danger" \| "neutral"` | `"danger"` | danger gives the confirm button the danger colour, for actions that destroy something; neutral gives it the accent, for important actions that can be reversed. The resting button is neutral either way. |
| `confirmMode` | `"press" \| "hold" \| "countdown"` | `"press"` | press confirms on a press. hold asks for the confirm button to be held for holdDuration while it fills. countdown confirms, then counts down countdown seconds that Cancel or Escape can still stop. |
| `holdDuration` | `number` | `1000` | Milliseconds the confirm button must be held in hold mode. |
| `countdown` | `number` | `3` | Seconds counted down before the action runs in countdown mode. |
| `countdownLabel` | `string` | – | Text before the seconds in countdown mode, such as "Deleting in". Defaults to pendingLabel followed by "in". |
| `onConfirm` | `() => void \| Promise<unknown>` | – | Runs on confirm. Return a promise to show the pending face; a rejection shows the error face with Retry. |
| `onUndo` | `() => void \| Promise<unknown>` | – | Adds Undo to the result. Return a promise to show a pending face while it runs. |
| `onCancel` | `() => void` | – | Called when the question is cancelled, including by Escape, outside press, or timeout. |
| `state` | `"idle" \| "confirming" \| "pending" \| "done" \| "error"` | – | Controlled state. Pair it with onStateChange. |
| `defaultState` | `"idle" \| "confirming" \| "pending" \| "done" \| "error"` | `"idle"` | Starting state when uncontrolled. |
| `onStateChange` | `(state: ConfirmMorphState) => void` | – | Called on every state change. |
| `confirmTimeout` | `number` | `6000` | Milliseconds before an unanswered question returns to rest. Hovering pauses it; 0 turns it off. |
| `resultTimeout` | `number` | `5000` | Milliseconds a result stays before returning to rest. Hovering pauses it; 0 turns it off. |
| `cancelOnOutsidePress` | `boolean` | `true` | A press outside the control cancels an open question. |
| `disabled` | `boolean` | `false` | Disables the resting button. |
| `className` | `string` | – | Class on the root. |
| `ref` | `Ref<HTMLDivElement>` | – | The root element, which also takes focus while the action is pending. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Enter / Space | Presses the focused face button: start, Confirm, Cancel, Undo, or Retry. In hold mode, holding Enter or Space on Confirm fills it. |
| Enter | While asking, confirms from the question (Confirm takes focus when it opens); during a countdown, runs the action now. |
| Tab / Shift+Tab | Moves between Cancel and Confirm while asking. |
| Escape | Cancels the question or the countdown, or dismisses a result back to rest. |

### Accessibility

- The question face is a group labelled by the prompt. Confirm takes focus so Enter answers yes, but a press within 280ms of opening and auto-repeated keys are ignored, so a double click or a held Enter never confirms by accident.
- Focus follows the morph: Confirm while asking, the root during a countdown or while pending (with aria-busy), Undo or Retry on a result, and the trigger back at rest.
- In hold mode the confirm button is described as "Press and hold", and letting go early announces that it needs a longer hold.
- Prompts, pending labels, results, and "Undo is available" are announced through a polite live region.
- Timeouts pause while the pointer rests on the control and while the tab is hidden.

### Motion

- Only the pill's width moves, on the morph spring growing and the smooth spring shrinking, so corners and text never scale or wobble and nothing around it jumps.
- Every face sits at its natural width against the pill's leading edge: the question starts where the label was and the springing edge reveals the rest, so text never squashes, slides, or leaves its baseline.
- The new face's parts arrive in reading order, each clearing a small blur; the old face fades out where it stood. The done check pops and draws itself, and countdown digits swap on tabular figures.
- In hold mode a solid danger copy of the button is revealed from the left as the hold fills and drains back on a spring if released early.
- Reduced motion removes the width spring, blur, and draw; faces crossfade and the spinner slows. The hold fill and countdown ring still show progress.

### Responsive behavior

- The control is as wide as its current face; leave room beside it for the question face, which is wider than the resting button.
- Hover styles apply only on hover-capable fine pointers; the control keeps the small control height, so give Cancel and Confirm some space from nearby targets on touch layouts.

### Performance

- Only the current face and the one leaving render; a ResizeObserver per face measures width for the spring.
- The timeout is a single linear motion value animation that pauses and resumes, not a timer per frame.

### Notes for AI

- Use for destructive or important actions that deserve a second press but not a modal: delete, revoke, discard.
- Return the real promise from onConfirm; rejections show the error face with Retry, which reruns the same handler.
- Offer onUndo when the action can be reversed; then consider a short confirmTimeout or skipping the question in your own flow.
- Use confirmMode="hold" for the riskiest deletes and "countdown" when there is no Undo; use dialog when the consequence needs a full explanation.
- Keep the resting button neutral; tone="danger" only colours the confirm answer, and tone="neutral" moves it to the accent for reversible actions.

### Related

- [Hold to confirm](https://uiarc.dev/components/hold-to-confirm/markdown): Confirm a destructive action by holding, not tapping.
- [Action button](https://uiarc.dev/components/action-button/markdown): A compact button for frequent toolbar actions.
- [Action morph](https://uiarc.dev/components/action-morph/markdown): A floating button that morphs into a quick-action menu, then an inline form, then back with a check.
- [Dialog](https://uiarc.dev/components/dialog/markdown): A focused surface for decisions that need attention.
- [Toast](https://uiarc.dev/components/toast/markdown): Brief confirmation for a completed background action.

### Also in buttons

- [Button](https://uiarc.dev/components/button/markdown): A clear, responsive action with quiet secondary states.
- [Split button](https://uiarc.dev/components/split-button/markdown): A primary action with a menu of nearby alternatives.
- [Button group](https://uiarc.dev/components/button-group/markdown): Related actions joined into one surface with hairline dividers: a hover highlight glides between segments, the pressed one answers in place, and an attached menu can close the row.
- [Floating button group](https://uiarc.dev/components/floating-button-group/markdown): Separate soft buttons in a quiet tray, with one shared highlight that morphs from button to button as you move, and a pressed state that settles in place.
- [Expanding button group](https://uiarc.dev/components/expanding-button-group/markdown): Icon buttons in a compact group: the one you point at or focus grows to reveal its label while its neighbours slide aside, and an action confirms in place.
- [Copy button](https://uiarc.dev/components/copy-button/markdown): Copy a value with immediate confirmation.
- [Action swap](https://uiarc.dev/components/action-swap/markdown): Swap an action label while preserving its place and intent.
- [Icon morph](https://uiarc.dev/components/icon-morph/markdown): Icons that morph between states: menu to close, play to pause, copy to check, and more.

### Guidance for AI tools

Confirm morph: A destructive button that morphs into an inline confirmation, a spinner, and a result with undo. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Hold to confirm

> Confirm a destructive action by holding, not tapping.

- Type: Component (actions)
- Access: Free, open source
- Page: https://uiarc.dev/components/hold-to-confirm
- Markdown: https://uiarc.dev/components/hold-to-confirm/markdown
- Registry item: https://uiarc.dev/r/hold-to-confirm.json
- Source file: `registry/components/hold-to-confirm/hold-to-confirm.tsx`
- Dependencies: motion, lucide-react
- Keywords: hold, long press, confirm, react hold to confirm, press and hold button, long press delete, hold to delete, destructive action button, confirm without dialog

### When to use

- Destructive actions like delete or revoke where the consequence is already visible on screen.
- Replacing a confirm dialog with a deliberate press in compact settings rows.
- Actions that should not fire on an accidental tap on touch devices.

### When not to use

- Use dialog when people need to read what will happen before confirming.
- Use button or action-button for safe, easily undone actions.
- Use swipe-actions for delete in touch lists.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/hold-to-confirm
pnpm dlx shadcn@latest add @uiarc/hold-to-confirm
yarn dlx shadcn@latest add @uiarc/hold-to-confirm
bunx --bun shadcn@latest add @uiarc/hold-to-confirm
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/hold-to-confirm.json
```

#### Manual

1. Install the dependencies:

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

2. Copy the source into your project. Main file: `registry/components/hold-to-confirm/hold-to-confirm.tsx`

   The source is in the registry item: https://uiarc.dev/r/hold-to-confirm.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { HoldToConfirm } from "@/components/arc/hold-to-confirm/hold-to-confirm";

export function DeleteProject({ onDelete }: { onDelete: () => void }) {
  return (
    <HoldToConfirm
      label="Hold to delete project"
      confirmedLabel="Deleted"
      duration={1500}
      onConfirm={onDelete}
    />
  );
}
```

### Examples

#### Keep holding hint

```tsx
const [holding, setHolding] = useState(false);

<HoldToConfirm label="Hold to revoke key" onConfirm={revoke} onHoldChange={setHolding} />
<p aria-hidden="true">{holding ? "Keep holding" : ""}</p>
```

### API reference

#### HoldToConfirm

A button that commits only after a press is held, with a fill that tracks the hold and rewinds on early release.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` (required) | `string` | – | Instruction and action, such as "Hold to delete project". |
| `onConfirm` (required) | `() => void` | – | Called once when the hold completes. |
| `confirmedLabel` | `string` | `"Done"` | Label after the hold completes. |
| `duration` | `number` | `1200` | Hold length in milliseconds. |
| `icon` | `ReactNode` | `<Trash2 />` | Leading icon. Replaced by a drawn check when done. |
| `tone` | `"danger" \| "neutral"` | `"danger"` | Fill color. |
| `confirmed` | `boolean` | – | Controls the done state. Set back to false to reset; leave undefined to let the button manage it. |
| `onHoldChange` | `(holding: boolean) => void` | – | Reports when a hold starts and ends, for hints like "Keep holding". |
| `...props` | `ButtonHTMLAttributes<HTMLButtonElement>` | – | Forwarded to the button, except children and onClick. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Space / Enter (hold) | Fills the button; releasing early rewinds it. |
| Tab away | Cancels an active hold. |

### Accessibility

- aria-describedby points to a hidden hint: "Press and hold for N seconds to confirm. With a keyboard, hold Space or Enter."
- aria-label tracks the visible label; a role="status" region announces confirmedLabel.
- Once done the button sets aria-disabled; the text is drawn twice so it changes color exactly at the fill edge.

### Motion

- The fill advances on a linear timeline while held, rewinds on a smooth spring when released, and resumes from where it was on a quick re-press.
- The button presses to about 0.97; on completion the label morphs, the width springs, and a check draws itself in. Touch devices get a short vibration.
- Reduced motion drops the press scale and rewind spring and swaps label and icon with a fade; the fill still tracks the hold.

### Responsive behavior

- Uses pointer events with capture, so mouse, pen, and touch holds all work; sliding more than 24px off the button cancels the hold.
- Touch holds trigger a short vibration on completion where the device supports it.
- Keyboard users hold Space or Enter, and a hidden hint explains the duration.

### Performance

- The fill runs on a single linear motion animation, not a React state update per frame.
- The label is drawn twice to change color at the fill edge; a ResizeObserver handles the width spring on completion.

### Notes for AI

- Use for destructive or hard-to-undo actions when the consequence is already visible on screen. Use dialog when people need to read what will happen first.
- Write the label as an instruction ("Hold to …"); pass confirmed to reset it after an undo or a failed request.
- Pair with onHoldChange to show a nearby hint while the press is held.

### Related

- [Button](https://uiarc.dev/components/button/markdown): A clear, responsive action with quiet secondary states.
- [Action button](https://uiarc.dev/components/action-button/markdown): A compact button for frequent toolbar actions.
- [Dialog](https://uiarc.dev/components/dialog/markdown): A focused surface for decisions that need attention.
- [Swipe actions](https://uiarc.dev/components/swipe-actions/markdown): Reveal row actions with a swipe, or from the same actions in a menu.

### Also in gestures

- [Reactions](https://uiarc.dev/components/reactions/markdown): Acknowledge a post in one tap, with counts that roll.

### Guidance for AI tools

Hold to confirm: Confirm a destructive action by holding, not tapping. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Swipe actions

> Reveal row actions with a swipe, or from the same actions in a menu.

- Type: Component (actions)
- Access: Free, open source
- Page: https://uiarc.dev/components/swipe-actions
- Markdown: https://uiarc.dev/components/swipe-actions/markdown
- Registry item: https://uiarc.dev/r/swipe-actions.json
- Source file: `registry/components/swipe-actions/swipe-actions.tsx`
- Dependencies: @radix-ui/react-dropdown-menu, motion, lucide-react
- Keywords: swipe, gesture, list, react swipe actions, swipe to delete, swipe to archive, ios swipe row, swipeable list item, mobile list actions, swipe gesture list

### When to use

- Touch-first triage lists such as mail, notifications, or tasks.
- Rows with one or two quick actions per side, like Archive and Mark unread.
- Lists where a full swipe should commit the main action and the row should animate away.

### When not to use

- Use context-menu or dropdown-menu for desktop-first tables.
- Use reorderable-list when rows need to be dragged vertically.
- Use hold-to-confirm for a single destructive action outside a list.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/swipe-actions
pnpm dlx shadcn@latest add @uiarc/swipe-actions
yarn dlx shadcn@latest add @uiarc/swipe-actions
bunx --bun shadcn@latest add @uiarc/swipe-actions
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/swipe-actions.json
```

#### Manual

1. Install the dependencies:

```bash
npm install @radix-ui/react-dropdown-menu motion lucide-react
```

2. Copy the source into your project. Main file: `registry/components/swipe-actions/swipe-actions.tsx`

   The source is in the registry item: https://uiarc.dev/r/swipe-actions.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { SwipeActions, SwipeActionsRow } from "@/components/arc/swipe-actions/swipe-actions";
import { Archive, MailOpen } from "lucide-react";

export function Inbox({ messages }: { messages: Message[] }) {
  return (
    <SwipeActions label="Inbox">
      {messages.map(message => (
        <SwipeActionsRow
          key={message.id}
          label={message.subject}
          leading={[{ label: "Unread", icon: <MailOpen size={18} />, tone: "accent", keepRow: true, onSelect: () => markUnread(message.id) }]}
          trailing={[{ label: "Archive", icon: <Archive size={18} />, tone: "danger", onSelect: () => archive(message.id) }]}
        >
          <MessagePreview message={message} />
        </SwipeActionsRow>
      ))}
    </SwipeActions>
  );
}
```

### API reference

#### SwipeActions

The list. Keeps one row open at a time and closes it on an outside press or Escape.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` (required) | `string` | – | Accessible name for the list. |
| `children` (required) | `ReactNode` | – | SwipeActionsRow elements. Removing one animates its height closed. |
| `className` | `string` | – | Extra class on the surface. |

#### SwipeActionsRow

One row whose actions reveal under its left and right edges on a horizontal swipe.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` (required) | `string` | – | Names the row's More actions button, for example the message subject. |
| `leading` | `SwipeAction[]` | `[]` | Actions under the left edge, revealed by swiping right. The first one commits on a full swipe. |
| `trailing` | `SwipeAction[]` | `[]` | Actions under the right edge, revealed by swiping left. The last one commits on a full swipe. |
| `fullSwipe` | `boolean` | `true` | Lets a long swipe or flick commit the outermost action. |
| `children` (required) | `ReactNode` | – | Row content. |
| `className` | `string` | – | Extra class on the row. |

#### SwipeAction

One action in leading or trailing.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` (required) | `string` | – | Shown under the icon and in the menu. |
| `icon` (required) | `ReactNode` | – | Action icon. |
| `onSelect` (required) | `() => void` | – | Runs on full swipe, tap, or menu choice. Remove the item here unless keepRow is set. |
| `tone` | `"neutral" \| "accent" \| "danger"` | `"neutral"` | Fill of the revealed action. |
| `keepRow` | `boolean` | – | Springs the row home after the action instead of sliding it away. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Enter / Space | Opens a row's More actions menu from its button. |
| ArrowDown / ArrowUp | Moves between the row's actions in the menu. |
| Escape | Closes the menu or puts away an open row. |

### Accessibility

- The list is a ul with role="list" and aria-label; each row is an li.
- Every row has a "More actions for <label>" menu with the same actions, so the gesture is never required.
- Revealed action buttons are aria-hidden and out of the tab order; after a removing action, focus moves to a neighbouring row.

### Motion

- The row tracks the finger, rubber-bands past its last stop, and settles on a spring that carries the release velocity; a flick projects its travel.
- Past the threshold the outer action stretches across the row, then the row slides out and the list closes the gap.
- Reduced motion jumps the row to its stops and fades rows in and out instead of animating height.

### Responsive behavior

- Swipes lock to the horizontal axis after the first movement, so vertical page scrolling still works on touch.
- A full swipe commits past the larger of the open width plus 48px or 56% of the row, measured with a ResizeObserver.
- Every row also has a More actions menu, so mouse and keyboard users never need the gesture.

### Performance

- Drag updates a motion value directly, so rows do not re-render while following the finger.
- Rows are not virtualized and each has its own ResizeObserver; paginate long lists.

### Notes for AI

- Use for short, triage-style lists on touch (mail, notifications, tasks). For desktop-first tables use context-menu or a row menu.
- Remove the item from state inside onSelect; set keepRow for actions that keep the item, such as mark as unread.
- Rows must be direct children of SwipeActions, keyed by item id, so removal and undo animate.

### Related

- [Context menu](https://uiarc.dev/components/context-menu/markdown): Secondary actions kept close to the selected object.
- [Hold to confirm](https://uiarc.dev/components/hold-to-confirm/markdown): Confirm a destructive action by holding, not tapping.
- [Reorderable list](https://uiarc.dev/components/reorderable-list/markdown): Organize items with direct drag and drop.
- [Dropdown menu](https://uiarc.dev/components/dropdown-menu/markdown): A focused list of actions anchored to a trigger.

### Also in gestures

- [Reactions](https://uiarc.dev/components/reactions/markdown): Acknowledge a post in one tap, with counts that roll.

### Guidance for AI tools

Swipe actions: Reveal row actions with a swipe, or from the same actions in a menu. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Reactions

> Acknowledge a post in one tap, with counts that roll.

- Type: Component (actions)
- Access: Free, open source
- Page: https://uiarc.dev/components/reactions
- Markdown: https://uiarc.dev/components/reactions/markdown
- Registry item: https://uiarc.dev/r/reactions.json
- Source file: `registry/components/reactions/reactions.tsx`
- Dependencies: @radix-ui/react-popover, motion, lucide-react
- Keywords: reactions, social, comments, react reactions, emoji reactions, reaction picker, like button with count, slack reactions, comment reactions

### When to use

- Lightweight acknowledgement on comments, posts, or release notes.
- Slack-style reaction pills with counts and a picker for new reactions.

### When not to use

- Use a reply field such as ai-composer when people need to say something specific.
- Use action-swap for a single like or follow toggle without counts.
- Use badge for static counts that people cannot change.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/reactions
pnpm dlx shadcn@latest add @uiarc/reactions
yarn dlx shadcn@latest add @uiarc/reactions
bunx --bun shadcn@latest add @uiarc/reactions
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/reactions.json
```

#### Manual

1. Install the dependencies:

```bash
npm install @radix-ui/react-popover motion lucide-react
```

2. Copy the source into your project. Main file: `registry/components/reactions/reactions.tsx`

   The source is in the registry item: https://uiarc.dev/r/reactions.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { Reactions } from "@/components/arc/reactions/reactions";
import { Heart, PartyPopper, ThumbsUp } from "lucide-react";

const options = [
  { id: "like", label: "Like", icon: ThumbsUp },
  { id: "love", label: "Love", icon: Heart },
  { id: "party", label: "Celebrate", icon: PartyPopper },
];

export function CommentReactions() {
  return <Reactions options={options} defaultValue={[{ id: "like", count: 3, reacted: false }]} onValueChange={(_, change) => save(change)} />;
}
```

### API reference

#### Reactions

A bar of reaction pills with counts and an add button that opens a picker tray.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `options` (required) | `ReactionOption[]` | – | Every reaction the picker offers: { id, label, icon: LucideIcon }. |
| `value` | `Reaction[]` | – | Controlled reactions: { id, count, reacted }. Pills keep this order; a count of zero leaves the bar. |
| `defaultValue` | `Reaction[]` | `[]` | Initial reactions when uncontrolled. |
| `onValueChange` | `(next: Reaction[], change: { id: string; reacted: boolean }) => void` | – | Called with the next list and the change that produced it. |
| `label` | `string` | `"Reactions"` | Accessible name for the bar. |
| `className` | `string` | – | Extra class on the root. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Enter / Space | Toggles your reaction on a pill, or opens the picker from the add button. |
| ArrowLeft / ArrowRight / ArrowUp / ArrowDown | Moves between options in the picker, wrapping at the ends. |
| Home / End | Jumps to the first or last option. |
| Escape | Closes the picker and returns focus to the add button. |

### Accessibility

- The bar is role="group"; each pill is a button with aria-pressed and a label like "Love, 4 reactions, including yours".
- The picker is a role="toolbar" with roving tabindex and labelled options; the add button is labelled "Add reaction".
- A role="status" region announces each change; a pill that leaves while focused hands focus to its neighbour or the add button.

### Motion

- Pills scale in from a blur and reflow on a morph spring; the icon gets a velocity kick that stacks on quick taps, and digits roll in the direction of the count.
- The picker grows out of the add button while a shared highlight glides between options.
- Reduced motion, read only after hydration, swaps everything with short fades and no layout springs.

### Responsive behavior

- The bar wraps onto new lines as pills are added, and its height springs to fit.
- The picker opens in a Radix popover, so it repositions near viewport edges.
- Hover highlights in the picker follow the mouse only; touch taps select directly.

### Performance

- Pills use layout position animation and count digits roll individually; fine for a handful of reactions per item.
- In long comment threads each bar runs its own ResizeObserver, so avoid rendering hundreds at once.

### Notes for AI

- Use for lightweight acknowledgement on comments, posts, or release notes. When people need to say something specific, add a reply field instead.
- Icons must be Lucide component types, not elements. Persist the change from onValueChange and control value when counts come from the server.

### Related

- [Badge](https://uiarc.dev/components/badge/markdown): A small label for status, category, or metadata.
- [Popover](https://uiarc.dev/components/popover/markdown): A small anchored surface for contextual information.
- [Avatar group](https://uiarc.dev/components/avatar-group/markdown): Show a team or set of contributors in a small space.
- [Animated counter](https://uiarc.dev/components/animated-counter/markdown): Give changing totals a clear sense of movement.

### Also in gestures

- [Hold to confirm](https://uiarc.dev/components/hold-to-confirm/markdown): Confirm a destructive action by holding, not tapping.
- [Swipe actions](https://uiarc.dev/components/swipe-actions/markdown): Reveal row actions with a swipe, or from the same actions in a menu.

### Guidance for AI tools

Reactions: Acknowledge a post in one tap, with counts that roll. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Dropdown menu

> A focused list of actions anchored to a trigger.

- Type: Component (actions)
- Access: Free, open source
- Page: https://uiarc.dev/components/dropdown-menu
- Markdown: https://uiarc.dev/components/dropdown-menu/markdown
- Registry item: https://uiarc.dev/r/dropdown-menu.json
- Source file: `registry/components/dropdown-menu/dropdown-menu.tsx`
- Dependencies: @radix-ui/react-dropdown-menu, motion, lucide-react
- Keywords: menu, action, react dropdown menu, actions menu, menu button, radix dropdown menu, animated dropdown, more actions menu, kebab menu

### When to use

- A list of commands behind a labelled button, such as Rename, Duplicate, and Delete.
- Row or card actions where a visible trigger is clearer than right-click.
- Short grouped menus with separators and one destructive item at the end.

### When not to use

- Use split-button when one command is the default.
- Use context-menu for right-click actions on content.
- Use user-menu for the account menu, and command-palette for searching many commands.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/dropdown-menu
pnpm dlx shadcn@latest add @uiarc/dropdown-menu
yarn dlx shadcn@latest add @uiarc/dropdown-menu
bunx --bun shadcn@latest add @uiarc/dropdown-menu
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/dropdown-menu.json
```

#### Manual

1. Install the dependencies:

```bash
npm install @radix-ui/react-dropdown-menu motion lucide-react
```

2. Copy the source into your project. Main file: `registry/components/dropdown-menu/dropdown-menu.tsx`

   The source is in the registry item: https://uiarc.dev/r/dropdown-menu.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { DropdownMenu } from "@/components/arc/dropdown-menu/dropdown-menu";
import { Pencil, Copy, Trash2 } from "lucide-react";

export function ProjectActions() {
  return (
    <DropdownMenu
      label="Actions"
      items={[
        { label: "Rename", icon: <Pencil size={15} />, onSelect: rename },
        { label: "Duplicate", icon: <Copy size={15} />, onSelect: duplicate },
        { label: "Delete", icon: <Trash2 size={15} />, onSelect: remove, destructive: true, separatorBefore: true },
      ]}
    />
  );
}
```

### API reference

#### DropdownMenu

A labelled trigger that opens a Radix menu with a single highlight gliding between items.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` (required) | `string` | – | Trigger text. A new label rises in while the trigger width springs. |
| `items` (required) | `DropdownItem[]` | – | Items: { label, onSelect?, disabled?, icon?, destructive?, separatorBefore? }. Labels double as keys, so keep them unique. |
| `icon` | `ReactNode` | – | Leading icon in the trigger. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Enter / Space / ArrowDown | Opens the menu from the trigger. |
| ArrowDown / ArrowUp | Moves between items, looping at the ends. |
| Home / End | Jumps to the first or last item. |
| Escape | Closes the menu and returns focus to the trigger. |

### Accessibility

- Built on Radix DropdownMenu: the trigger gets aria-haspopup and aria-expanded, items get menuitem roles and typeahead.
- Icons and the highlight are aria-hidden; destructive items are marked by color and should say what they destroy.
- Disabled items are skipped by the keyboard.

### Motion

- The highlight glides between items on a snappy spring for the pointer and jumps instantly for the keyboard.
- The menu scales in from the trigger and items fade in with a short stagger.
- Reduced motion removes the menu transform and highlight glide, keeping a quick opacity fade.

### Responsive behavior

- The trigger label ellipsizes within max-width 100%, so it shrinks inside narrow toolbars instead of overflowing.
- The menu uses Radix collision handling with 12px padding and a 12rem minimum width, flipping away from viewport edges.
- Hover styles apply only on fine pointers; touch taps select without a stuck highlight.

### Performance

- Menu content renders in a portal only while open; items are not virtualized, so keep lists short.
- The menu has a translucent backdrop blur, which drops to a solid surface under prefers-reduced-transparency.

### Notes for AI

- Default choice for a list of commands behind a button. Use split-button when one command is the default, and context-menu for right-click on content.
- Group items with separatorBefore; put destructive items last.
- Items are data, not children, so build the array from your actions.

### Related

- [Split button](https://uiarc.dev/components/split-button/markdown): A primary action with a menu of nearby alternatives.
- [Context menu](https://uiarc.dev/components/context-menu/markdown): Secondary actions kept close to the selected object.
- [User menu](https://uiarc.dev/components/user-menu/markdown): Your account, settings, theme, and sign out behind the avatar. Opens as a bottom sheet on phones.
- [Popover](https://uiarc.dev/components/popover/markdown): A small anchored surface for contextual information.

### Guidance for AI tools

Dropdown menu: A focused list of actions anchored to a trigger. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Context menu

> Secondary actions kept close to the selected object.

- Type: Component (actions)
- Access: Free, open source
- Page: https://uiarc.dev/components/context-menu
- Markdown: https://uiarc.dev/components/context-menu/markdown
- Registry item: https://uiarc.dev/r/context-menu.json
- Source file: `registry/components/context-menu/context-menu.tsx`
- Dependencies: motion, lucide-react
- Keywords: menu, action, react context menu, right click menu, custom context menu, file actions menu, shift f10 menu, animated context menu

### When to use

- Secondary actions on a file, card, or row where a visible menu button would add clutter.
- Desktop-style right-click menus that also open from the keyboard with Shift+F10 or the ContextMenu key.
- Short flat lists of item actions with one destructive option.

### When not to use

- Use dropdown-menu when the actions deserve a visible trigger.
- Use swipe-actions for touch-first lists like an inbox.
- Avoid it on targets that need their own click action, since a plain click on the target also opens the menu.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/context-menu
pnpm dlx shadcn@latest add @uiarc/context-menu
yarn dlx shadcn@latest add @uiarc/context-menu
bunx --bun shadcn@latest add @uiarc/context-menu
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

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

#### Manual

1. Install the dependencies:

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

2. Copy the source into your project. Main file: `registry/components/context-menu/context-menu.tsx`

   The source is in the registry item: https://uiarc.dev/r/context-menu.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { ContextMenu } from "@/components/arc/context-menu/context-menu";
import { Copy, Trash2 } from "lucide-react";

export function FileTile({ file }: { file: File }) {
  return (
    <ContextMenu
      label={`Actions for ${file.name}`}
      items={[
        { id: "copy", label: "Copy link", icon: <Copy size={15} />, onSelect: () => copyLink(file) },
        { id: "delete", label: "Delete file", icon: <Trash2 size={15} />, destructive: true, onSelect: () => remove(file) },
      ]}
    >
      <FilePreview file={file} />
    </ContextMenu>
  );
}
```

### API reference

#### ContextMenu

Wraps content and opens a menu at the pointer on right-click, or under the target on click and keyboard.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` (required) | `ReactNode` | – | The target area. |
| `items` (required) | `ContextMenuItem[]` | – | Items: { id, label, icon?, onSelect?, disabled?, destructive?, checked? }. |
| `label` | `string` | `"Context menu"` | Accessible name for both the target and the menu. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| ContextMenu / Shift+F10 | Opens the menu under the focused target. |
| ArrowDown / ArrowUp | Moves between enabled items, wrapping at the ends. |
| Home / End | Jumps to the first or last enabled item. |
| Enter / Space | Selects the focused item and closes the menu. |
| Escape | Closes the menu and returns focus to the target. |

### Accessibility

- The target is focusable with aria-haspopup="menu" and aria-expanded; the menu has role="menu" and items role="menuitem".
- Opening focuses the first enabled item; closing returns focus to the target.
- Items without an icon show a check when checked, but checked state is not exposed to assistive tech, so say it in the label if it matters.

### Motion

- The menu grows from the pointer on a snappy spring, even when clamped away from a viewport edge; reopening fades the old one out in place.
- A shared highlight glides between rows for the pointer and jumps for the keyboard.
- Reduced motion drops the scale and glide and uses a short opacity fade.

### Responsive behavior

- The menu is clamped 8px inside the viewport and capped at the viewport width minus 16px, with a max height of 300px and scrolling beyond that.
- On touch, a tap on the target opens the menu under it, so it works without a right mouse button.
- The menu closes on any scroll or resize instead of repositioning.

### Performance

- The menu mounts only while open and is positioned once from the pointer, with no scroll tracking loop.
- Items are plain buttons with one shared highlight element; there is no virtualization, so keep the list short.

### Notes for AI

- Use for secondary actions on a content object (file, card, row) where a visible menu button would add clutter. Use dropdown-menu when the commands deserve a visible trigger.
- A plain click on the target also opens the menu, so do not wrap targets that need their own click action.
- The menu closes on scroll, resize, and outside press; keep items to a short flat list.

### Related

- [Dropdown menu](https://uiarc.dev/components/dropdown-menu/markdown): A focused list of actions anchored to a trigger.
- [Swipe actions](https://uiarc.dev/components/swipe-actions/markdown): Reveal row actions with a swipe, or from the same actions in a menu.
- [Popover](https://uiarc.dev/components/popover/markdown): A small anchored surface for contextual information.
- [Command palette](https://uiarc.dev/components/blocks/command-palette/markdown): A complete keyboard driven action surface with search, grouped results, and shortcuts.

### Also in menus

- [User menu](https://uiarc.dev/components/user-menu/markdown): Your account, settings, theme, and sign out behind the avatar. Opens as a bottom sheet on phones.

### Guidance for AI tools

Context menu: Secondary actions kept close to the selected object. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## User menu

> Your account, settings, theme, and sign out behind the avatar. Opens as a bottom sheet on phones.

- Type: Component (actions)
- Access: Free, open source
- Page: https://uiarc.dev/components/user-menu
- Markdown: https://uiarc.dev/components/user-menu/markdown
- Registry item: https://uiarc.dev/r/user-menu.json
- Source file: `registry/components/user-menu/user-menu.tsx`
- Dependencies: motion, lucide-react
- Keywords: motion, product, react user menu, account menu, avatar dropdown, profile menu, user menu with status, sign out menu, presence indicator

### When to use

- The single account entry point in an app top bar.
- Menus that combine presence status, theme preference, account links, and sign out.
- Apps that want async sign out with a spinner in the menu.

### When not to use

- Use dropdown-menu for generic command lists.
- Use theme-switch for a standalone light and dark toggle.
- Use workspace-sidebar when account and workspace switching live in a side navigation.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/user-menu
pnpm dlx shadcn@latest add @uiarc/user-menu
yarn dlx shadcn@latest add @uiarc/user-menu
bunx --bun shadcn@latest add @uiarc/user-menu
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/user-menu.json
```

#### Manual

1. Install the dependencies:

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

2. Copy the source into your project. Main file: `registry/components/user-menu/user-menu.tsx`

   The source is in the registry item: https://uiarc.dev/r/user-menu.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { UserMenu } from "@/components/arc/user-menu/user-menu";
import { CreditCard, Settings, UserRound } from "lucide-react";

export function TopBarAccount({ user }: { user: { name: string; email: string } }) {
  return (
    <UserMenu
      user={{ ...user, plan: "Pro" }}
      showName
      onThemeChange={setThemePreference}
      items={[
        { label: "Profile", icon: <UserRound size={16} />, onSelect: openProfile },
        { label: "Settings", icon: <Settings size={16} />, keys: ["⌘", ","], onSelect: openSettings },
        { label: "Billing", icon: <CreditCard size={16} />, onSelect: openBilling },
      ]}
      onSignOut={() => signOut()}
    />
  );
}
```

### API reference

#### UserMenu

Account menu behind an avatar trigger: a compact identity header, a short group of account links, an inline theme switch, and sign out. Below 640px it opens as a bottom sheet.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `user` (required) | `UserMenuUser` | – | { name, email, plan?, avatarSrc?, avatarSrcSet? }. Falls back to initials without a photo. plan shows as a small accent badge. |
| `items` | `UserMenuItem[]` | `[]` | Account destinations: { label, icon?, keys?, onSelect? }. Keep it to three or four. keys show quiet shortcut hints such as ["⌘", ","]. |
| `showName` | `boolean` | `false` | Shows the name and a chevron beside the avatar from 640px up. Phones always show the avatar alone. |
| `theme` | `"light" \| "dark" \| "system"` | – | Controlled theme preference. |
| `defaultTheme` | `"light" \| "dark" \| "system"` | `"system"` | Initial theme when uncontrolled. |
| `onThemeChange` | `(theme: ThemePreference) => void` | – | Reports the choice. Applying it to the page is up to the app. The menu stays open. |
| `showTheme` | `boolean` | `true` | Shows the inline light, dark, and system switch. |
| `status` | `"available" \| "busy" \| "away"` | – | Controlled presence status. Passing status or onStatusChange adds the presence dot and an inline status switch. |
| `defaultStatus` | `"available" \| "busy" \| "away"` | `"available"` | Initial status when uncontrolled. |
| `onStatusChange` | `(status: UserStatus) => void` | – | Called when a status is chosen. The menu stays open. |
| `onSignOut` | `() => void \| Promise<unknown>` | – | Sign out handler. A returned promise keeps the menu open with a spinner until it settles. |
| `signOutKeys` | `string[]` | – | Shortcut hint for the sign out item. |
| `open` | `boolean` | – | Controlled open state. |
| `defaultOpen` | `boolean` | `false` | Initial open state when uncontrolled. A menu that starts open does not take focus. |
| `onOpenChange` | `(open: boolean) => void` | – | Called when the menu opens or closes. |
| `align` | `"start" \| "center" \| "end"` | `"end"` | Panel alignment against the trigger. |
| `portal` | `boolean` | `true` | Renders the desktop panel on the body. Pass false to keep it inside the trigger wrapper, for example in a contained preview. The mobile sheet always uses the body. |
| `ref` | `Ref<HTMLButtonElement>` | – | The trigger button, for returning focus. |
| `className` | `string` | – | Extra class on the trigger. |

#### PresenceDot

The status mark on its own, for avatars elsewhere in the app. Each status has its own shape as well as color.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `status` (required) | `"available" \| "busy" \| "away" \| "offline"` | – | Status to show. |
| `className` | `string` | – | Extra class for positioning. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Enter / Space / ArrowDown | Opens the menu from the avatar and moves to the first row. |
| ArrowUp | Opens the menu from the avatar and moves to the last row. |
| ArrowDown / ArrowUp | Moves between rows, looping at the ends. The highlight follows. |
| Home / End | Moves to the first or last row. |
| A to Z | Typeahead jumps to the next row starting with the typed letters. |
| ArrowLeft / ArrowRight | Chooses the previous or next option in the theme or status switch. |
| Enter / Space | Activates the row, or chooses a theme or status without closing. |
| Escape / Tab | Closes the menu and returns focus to the avatar. |

### Accessibility

- The trigger has aria-haspopup="menu" and aria-expanded, and is labelled "Account menu, <name>" plus the status when one is shown.
- Rows are menuitem buttons; the theme and status switches are labelled groups of menuitemradio buttons with aria-checked.
- Pointer focus draws no ring; keyboard focus shows Arc's shared focus ring. The highlight marks the keyboard position. Outside press, the scrim, and swipe down close the menu.
- Sign out sets aria-busy while an async handler runs; shortcut hints are aria-hidden.

### Motion

- The panel scales and fades out of the avatar on a spring that never overshoots; rows fade in with a short stagger, and closing is a quick fade.
- One highlight glides between rows for the pointer and the keyboard; the switch thumb slides between options.
- On phones the sheet rises from the bottom edge and follows a downward drag, closing past a short distance or a quick flick.
- Reduced motion opens and closes with a short fade, jumps the highlight, and turns off dragging.

### Responsive behavior

- The menu is 17.5rem wide, capped at the viewport width minus 24px, with 12px collision padding.
- Long names and emails ellipsize instead of widening the menu.
- The trigger is a fixed 40px avatar, and the theme row keeps a 44px minimum height for touch.

### Performance

- Content renders only while open; each opening gets a fresh layout namespace so shared indicators do not animate from stale positions.
- The avatar image decodes async and falls back to initials on error.

### Notes for AI

- Use as the single account entry point in an app top bar. For generic command lists use dropdown-menu; for a standalone light/dark toggle use theme-switch.
- Keep items to three or four account destinations; the theme switch and sign out are built in.
- onThemeChange only reports; apply the theme to the document yourself, optionally with a view transition.
- Return the sign out promise so the item shows progress and the menu closes when it settles.

### Related

- [Dropdown menu](https://uiarc.dev/components/dropdown-menu/markdown): A focused list of actions anchored to a trigger.
- [Avatar](https://uiarc.dev/components/avatar/markdown): A compact identity marker for people and accounts.
- [Theme switcher](https://uiarc.dev/components/theme-switch/markdown): Four smooth ways to move between light and dark appearance.
- [Sidebar: Workspace](https://uiarc.dev/components/blocks/sidebar/markdown): A product sidebar with a workspace switcher, live search, draggable favorites, and inline projects.

### Also in menus

- [Context menu](https://uiarc.dev/components/context-menu/markdown): Secondary actions kept close to the selected object.

### Guidance for AI tools

User menu: Your account, settings, theme, and sign out behind the avatar. Opens as a bottom sheet on phones. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Theme switcher

> Four smooth ways to move between light and dark appearance.

- Type: Component (actions)
- Access: Free, open source
- Page: https://uiarc.dev/components/theme-switch
- Markdown: https://uiarc.dev/components/theme-switch/markdown
- Registry item: https://uiarc.dev/r/theme-switch.json
- Source file: `registry/components/theme-switch/theme-switch.tsx`
- Dependencies: motion, lucide-react
- Keywords: theme, appearance, motion, react theme switch, dark mode toggle, light dark switch, theme toggle button, view transition theme, sun moon toggle

### When to use

- A single light and dark toggle in an app or marketing top bar.
- Pages that want to run their own view transition from the button's position.

### When not to use

- Use user-menu when theme choice, including system, belongs inside an account menu.
- Use theme-switch-rise for quiet product chrome, or theme-switch-eclipse for a dramatic showcase change.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/theme-switch
pnpm dlx shadcn@latest add @uiarc/theme-switch
yarn dlx shadcn@latest add @uiarc/theme-switch
bunx --bun shadcn@latest add @uiarc/theme-switch
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/theme-switch.json
```

#### Manual

1. Install the dependencies:

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

2. Copy the source into your project. Main file: `registry/components/theme-switch/theme-switch.tsx`

   The source is in the registry item: https://uiarc.dev/r/theme-switch.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { ThemeSwitch } from "@/components/arc/theme-switch/theme-switch";
import type { Theme } from "@/components/arc/theme-switch/theme-switch";

export function AppearanceToggle({ theme, setTheme }: { theme: Theme; setTheme: (next: Theme) => void }) {
  return (
    <ThemeSwitch
      theme={theme}
      iconOnly
      onThemeChange={next => {
        if (!document.startViewTransition) return setTheme(next);
        document.startViewTransition(() => setTheme(next));
      }}
    />
  );
}
```

### Examples

#### Reveal from the button

```tsx
<ThemeSwitch
  theme={theme}
  onThemeChange={(next, _variant, trigger) => {
    const { left, top, width, height } = trigger.getBoundingClientRect();
    document.documentElement.style.setProperty("--x", `${left + width / 2}px`);
    document.documentElement.style.setProperty("--y", `${top + height / 2}px`);
    document.startViewTransition(() => setTheme(next));
  }}
/>
```

### API reference

#### ThemeSwitch

A secondary Button that swaps a sun and moon icon and reports the next theme. The page transition itself is yours to run.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `theme` (required) | `"light" \| "dark"` | – | The current theme. Drives the icon and aria-pressed. |
| `onThemeChange` (required) | `(next: Theme, variant: ThemeSwitchVariant, trigger: HTMLElement) => void` | – | Called on press with the opposite theme, the variant, and the button, so the page transition can start from it. |
| `variant` | `"reveal" \| "eclipse" \| "split" \| "rise"` | `"reveal"` | Names the page transition and sets the small icon nudge that matches it. |
| `label` | `string` | – | Accessible name. Defaults to "Switch to dark mode" or "Switch to light mode". |
| `iconOnly` | `boolean` | `false` | Hides the "Switch theme" text and renders a 38px square button. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Enter / Space | Toggles the theme. |

### Accessibility

- Renders the library Button with aria-pressed set when the theme is dark.
- aria-label defaults to "Switch to dark mode" or "Switch to light mode"; pass label to override.
- The icons are aria-hidden.

### Motion

- Sun and moon trade places with a shared rotation, scale, and blur on a snappy spring; the icon also nudges in the direction of the chosen variant.
- A theme that arrives during hydration swaps without motion, so a dark page never spins its switch on load.
- Reduced motion swaps the icon with an instant fade and removes the nudge; skip the page transition too when reduced.

### Responsive behavior

- The labelled button fits a desktop top bar; pass iconOnly for a fixed 38px square on narrow headers and mobile.
- Hover styles apply only on hover-capable fine pointers, so touch taps do not leave a stuck hover state.

### Performance

- The button itself is tiny: one icon swap on a spring, and the first theme after hydration applies without animating.
- The page transition is yours; a full-page view transition snapshots the whole document, so keep it short and skip it for reduced motion.

### Notes for AI

- Use for a single light/dark toggle in a top bar. For light, dark, and system inside an account menu use user-menu.
- The component only reports the change. Apply the theme in onThemeChange, typically inside document.startViewTransition, and use trigger's rect as the transition origin.
- variant is passed back to onThemeChange so one handler can run the matching page transition (reveal, eclipse, split, rise).

### Related

- [Eclipse](https://uiarc.dev/components/theme-switch-eclipse/markdown): The next appearance crosses the page like an eclipse.
- [Split](https://uiarc.dev/components/theme-switch-split/markdown): The next appearance opens from a slim center seam.
- [Rise](https://uiarc.dev/components/theme-switch-rise/markdown): The next appearance rises into place.
- [User menu](https://uiarc.dev/components/user-menu/markdown): Your account, settings, theme, and sign out behind the avatar. Opens as a bottom sheet on phones.
- [Button](https://uiarc.dev/components/button/markdown): A clear, responsive action with quiet secondary states.

### Guidance for AI tools

Theme switcher: Four smooth ways to move between light and dark appearance. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Eclipse

> The next appearance crosses the page like an eclipse.

- Type: Component (actions)
- Access: Free, open source
- Page: https://uiarc.dev/components/theme-switch-eclipse
- Markdown: https://uiarc.dev/components/theme-switch-eclipse/markdown
- Registry item: https://uiarc.dev/r/theme-switch-eclipse.json
- Source file: `registry/components/theme-switch/theme-switch.tsx`
- Dependencies: motion, lucide-react
- Keywords: theme, appearance, motion, react theme switch, eclipse theme transition, dark mode toggle animation, view transition dark mode, theme sweep

### When to use

- Marketing or showcase pages where the theme change should feel like an event.
- Layouts where a directional sweep across the page reads naturally.

### When not to use

- Use theme-switch-rise for everyday product chrome where a calmer change fits.
- Use theme-switch-split when the button sits in the center and direction should not matter.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/theme-switch-eclipse
pnpm dlx shadcn@latest add @uiarc/theme-switch-eclipse
yarn dlx shadcn@latest add @uiarc/theme-switch-eclipse
bunx --bun shadcn@latest add @uiarc/theme-switch-eclipse
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/theme-switch-eclipse.json
```

#### Manual

1. Install the dependencies:

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

2. Copy the source into your project. Main file: `registry/components/theme-switch/theme-switch.tsx`

   The source is in the registry item: https://uiarc.dev/r/theme-switch-eclipse.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { ThemeSwitch } from "@/components/arc/theme-switch/theme-switch";

<ThemeSwitch
  theme={theme}
  variant="eclipse"
  onThemeChange={(next, variant, trigger) => runThemeTransition(next, variant, trigger)}
/>
```

### API reference

#### ThemeSwitch

A secondary Button that swaps a sun and moon icon and reports the next theme. The page transition itself is yours to run.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `theme` (required) | `"light" \| "dark"` | – | The current theme. Drives the icon and aria-pressed. |
| `onThemeChange` (required) | `(next: Theme, variant: ThemeSwitchVariant, trigger: HTMLElement) => void` | – | Called on press with the opposite theme, the variant, and the button, so the page transition can start from it. |
| `variant` | `"reveal" \| "eclipse" \| "split" \| "rise"` | `"reveal"` | Names the page transition and sets the small icon nudge that matches it. |
| `label` | `string` | – | Accessible name. Defaults to "Switch to dark mode" or "Switch to light mode". |
| `iconOnly` | `boolean` | `false` | Hides the "Switch theme" text and renders a 38px square button. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Enter / Space | Toggles the theme. |

### Accessibility

- Same button as theme-switch: aria-pressed reflects dark mode and the label names the next theme.
- Keep the eclipse sweep off for reduced motion and swap the theme directly.

### Motion

- variant="eclipse": the next appearance crosses the page like an eclipse; run it in onThemeChange with a view transition.
- The icon shifts 2px left in dark mode to lean into the sweep.
- Reduced motion removes the nudge and swaps the icon with a fade.

### Responsive behavior

- The labelled button fits a desktop top bar; pass iconOnly for a fixed 38px square on narrow headers and mobile.
- Hover styles apply only on hover-capable fine pointers, so touch taps do not leave a stuck hover state.

### Performance

- The button itself is tiny: one icon swap on a spring, and the first theme after hydration applies without animating.
- The page transition is yours; a full-page view transition snapshots the whole document, so keep it short and skip it for reduced motion.

### Notes for AI

- Select with variant="eclipse". The prop only styles the icon nudge and is passed back to onThemeChange; the page animation is your code.
- Pick eclipse for a dramatic, directional change on marketing or showcase pages; rise suits product chrome better.

### Related

- [Theme switcher](https://uiarc.dev/components/theme-switch/markdown): Four smooth ways to move between light and dark appearance.
- [Split](https://uiarc.dev/components/theme-switch-split/markdown): The next appearance opens from a slim center seam.
- [Rise](https://uiarc.dev/components/theme-switch-rise/markdown): The next appearance rises into place.

### Guidance for AI tools

Eclipse: The next appearance crosses the page like an eclipse. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Split

> The next appearance opens from a slim center seam.

- Type: Component (actions)
- Access: Free, open source
- Page: https://uiarc.dev/components/theme-switch-split
- Markdown: https://uiarc.dev/components/theme-switch-split/markdown
- Registry item: https://uiarc.dev/r/theme-switch-split.json
- Source file: `registry/components/theme-switch/theme-switch.tsx`
- Dependencies: motion, lucide-react
- Keywords: theme, appearance, motion, react theme switch, split theme transition, dark mode toggle, view transition split, theme toggle animation

### When to use

- Centered layouts where the theme should open symmetrically from a middle seam.
- Pages where the switch position varies, since the split does not depend on where the button sits.

### When not to use

- Use theme-switch for a reveal that grows from the button itself.
- Use theme-switch-rise for the calmest option in product UI.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/theme-switch-split
pnpm dlx shadcn@latest add @uiarc/theme-switch-split
yarn dlx shadcn@latest add @uiarc/theme-switch-split
bunx --bun shadcn@latest add @uiarc/theme-switch-split
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/theme-switch-split.json
```

#### Manual

1. Install the dependencies:

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

2. Copy the source into your project. Main file: `registry/components/theme-switch/theme-switch.tsx`

   The source is in the registry item: https://uiarc.dev/r/theme-switch-split.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { ThemeSwitch } from "@/components/arc/theme-switch/theme-switch";

<ThemeSwitch
  theme={theme}
  variant="split"
  onThemeChange={(next, variant, trigger) => runThemeTransition(next, variant, trigger)}
/>
```

### API reference

#### ThemeSwitch

A secondary Button that swaps a sun and moon icon and reports the next theme. The page transition itself is yours to run.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `theme` (required) | `"light" \| "dark"` | – | The current theme. Drives the icon and aria-pressed. |
| `onThemeChange` (required) | `(next: Theme, variant: ThemeSwitchVariant, trigger: HTMLElement) => void` | – | Called on press with the opposite theme, the variant, and the button, so the page transition can start from it. |
| `variant` | `"reveal" \| "eclipse" \| "split" \| "rise"` | `"reveal"` | Names the page transition and sets the small icon nudge that matches it. |
| `label` | `string` | – | Accessible name. Defaults to "Switch to dark mode" or "Switch to light mode". |
| `iconOnly` | `boolean` | `false` | Hides the "Switch theme" text and renders a 38px square button. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Enter / Space | Toggles the theme. |

### Accessibility

- Same button as theme-switch: aria-pressed reflects dark mode and the label names the next theme.
- Keep the split reveal off for reduced motion and swap the theme directly.

### Motion

- variant="split": the next appearance opens from a slim center seam; run it in onThemeChange with a view transition.
- The icon shifts 1px right in dark mode.
- Reduced motion removes the nudge and swaps the icon with a fade.

### Responsive behavior

- The labelled button fits a desktop top bar; pass iconOnly for a fixed 38px square on narrow headers and mobile.
- Hover styles apply only on hover-capable fine pointers, so touch taps do not leave a stuck hover state.

### Performance

- The button itself is tiny: one icon swap on a spring, and the first theme after hydration applies without animating.
- The page transition is yours; a full-page view transition snapshots the whole document, so keep it short and skip it for reduced motion.

### Notes for AI

- Select with variant="split". The prop only styles the icon nudge and is passed back to onThemeChange; the page animation is your code.
- Split is symmetric and does not depend on where the button sits, so it suits centered layouts.

### Related

- [Theme switcher](https://uiarc.dev/components/theme-switch/markdown): Four smooth ways to move between light and dark appearance.
- [Eclipse](https://uiarc.dev/components/theme-switch-eclipse/markdown): The next appearance crosses the page like an eclipse.
- [Rise](https://uiarc.dev/components/theme-switch-rise/markdown): The next appearance rises into place.

### Guidance for AI tools

Split: The next appearance opens from a slim center seam. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Rise

> The next appearance rises into place.

- Type: Component (actions)
- Access: Free, open source
- Page: https://uiarc.dev/components/theme-switch-rise
- Markdown: https://uiarc.dev/components/theme-switch-rise/markdown
- Registry item: https://uiarc.dev/r/theme-switch-rise.json
- Source file: `registry/components/theme-switch/theme-switch.tsx`
- Dependencies: motion, lucide-react
- Keywords: theme, appearance, motion, react theme switch, rise theme transition, dark mode toggle, icon theme toggle, view transition theme

### When to use

- Product chrome and dashboards where the theme change should be calm.
- Icon-only toggles in a top bar, as the library's own header uses it.

### When not to use

- Use theme-switch-eclipse for a dramatic change on a showcase page.
- Use user-menu when theme belongs with account settings.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/theme-switch-rise
pnpm dlx shadcn@latest add @uiarc/theme-switch-rise
yarn dlx shadcn@latest add @uiarc/theme-switch-rise
bunx --bun shadcn@latest add @uiarc/theme-switch-rise
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/theme-switch-rise.json
```

#### Manual

1. Install the dependencies:

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

2. Copy the source into your project. Main file: `registry/components/theme-switch/theme-switch.tsx`

   The source is in the registry item: https://uiarc.dev/r/theme-switch-rise.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { ThemeSwitch } from "@/components/arc/theme-switch/theme-switch";

<ThemeSwitch
  theme={theme}
  variant="rise"
  iconOnly
  onThemeChange={(next, variant, trigger) => runThemeTransition(next, variant, trigger)}
/>
```

### API reference

#### ThemeSwitch

A secondary Button that swaps a sun and moon icon and reports the next theme. The page transition itself is yours to run.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `theme` (required) | `"light" \| "dark"` | – | The current theme. Drives the icon and aria-pressed. |
| `onThemeChange` (required) | `(next: Theme, variant: ThemeSwitchVariant, trigger: HTMLElement) => void` | – | Called on press with the opposite theme, the variant, and the button, so the page transition can start from it. |
| `variant` | `"reveal" \| "eclipse" \| "split" \| "rise"` | `"reveal"` | Names the page transition and sets the small icon nudge that matches it. |
| `label` | `string` | – | Accessible name. Defaults to "Switch to dark mode" or "Switch to light mode". |
| `iconOnly` | `boolean` | `false` | Hides the "Switch theme" text and renders a 38px square button. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Enter / Space | Toggles the theme. |

### Accessibility

- Same button as theme-switch: aria-pressed reflects dark mode and the label names the next theme.
- Keep the rise off for reduced motion and swap the theme directly.

### Motion

- variant="rise": the next appearance rises into place from the bottom; run it in onThemeChange with a view transition.
- The icon lifts 2px in dark mode.
- Reduced motion removes the nudge and swaps the icon with a fade.

### Responsive behavior

- The labelled button fits a desktop top bar; pass iconOnly for a fixed 38px square on narrow headers and mobile.
- Hover styles apply only on hover-capable fine pointers, so touch taps do not leave a stuck hover state.

### Performance

- The button itself is tiny: one icon swap on a spring, and the first theme after hydration applies without animating.
- The page transition is yours; a full-page view transition snapshots the whole document, so keep it short and skip it for reduced motion.

### Notes for AI

- Select with variant="rise". The prop only styles the icon nudge and is passed back to onThemeChange; the page animation is your code.
- The calmest of the four; the library's own top bar uses it with iconOnly.

### Related

- [Theme switcher](https://uiarc.dev/components/theme-switch/markdown): Four smooth ways to move between light and dark appearance.
- [Eclipse](https://uiarc.dev/components/theme-switch-eclipse/markdown): The next appearance crosses the page like an eclipse.
- [Split](https://uiarc.dev/components/theme-switch-split/markdown): The next appearance opens from a slim center seam.

### Guidance for AI tools

Rise: The next appearance rises into place. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Input

> A single line field with clear labels and useful states.

- Type: Component (inputs)
- Access: Free, open source
- Page: https://uiarc.dev/components/input
- Markdown: https://uiarc.dev/components/input/markdown
- Registry item: https://uiarc.dev/r/input.json
- Source file: `registry/components/input/input.tsx`
- Dependencies: motion
- Keywords: field, form, react input, text field, animated form input, input with error message, form field validation, labelled input, input helper text

### When to use

- Any single-line text value in a form, such as name, email, or URL.
- Fields whose helper or error copy changes as the person types, where the message should reword in place.
- Plain form posts, since it forwards name and every native input attribute.

### When not to use

- Use textarea for multi-line text.
- Use password-field, search-field, or number-field when the value has that shape.
- Use inline-edit for a value shown as page text and edited in place.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/input
pnpm dlx shadcn@latest add @uiarc/input
yarn dlx shadcn@latest add @uiarc/input
bunx --bun shadcn@latest add @uiarc/input
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/input.json
```

#### Manual

1. Install the dependencies:

```bash
npm install motion
```

2. Copy the source into your project. Main file: `registry/components/input/input.tsx`

   The source is in the registry item: https://uiarc.dev/r/input.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { Input } from "@/components/arc/input/input";

export function EmailField() {
  const [email, setEmail] = useState("");
  return (
    <Input
      label="Email"
      type="email"
      value={email}
      onChange={(event) => setEmail(event.target.value)}
      description="We only use this for receipts."
      error={email && !email.includes("@") ? "Enter a valid email" : undefined}
    />
  );
}
```

### API reference

#### Input

A labelled text input with helper and error copy that open on a spring and reword in place.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` (required) | `string` | – | Visible label, tied to the input with htmlFor. |
| `description` | `string` | – | Helper copy under the field, linked through aria-describedby. |
| `error` | `string` | – | Error copy. Sets aria-invalid and renders in a role="alert" row. |
| `...props` | `InputHTMLAttributes<HTMLInputElement>` | – | Forwarded to the native input, including ref, type, value, onChange, and name. |

### Accessibility

- Renders a native input with a real label, so focus and form behavior are native.
- Description and error ids are merged into aria-describedby alongside any caller value.
- Errors set aria-invalid and announce through role="alert"; animated words are aria-hidden with a plain screen reader copy.

### Motion

- Helper and error rows open their height on a smooth spring, then changed words rise in and unblur while numbers roll digit by digit.
- Reduced motion mounts rows at full height and swaps words with an instant fade.

### Responsive behavior

- The field fills its grid column with min-width 0, so it shrinks inside narrow layouts without overflowing.
- Text stays at the small size on touch, unlike password-strength, so iOS may zoom on focus if your --text-sm is below 16px.
- Hover border styles apply only on hover-capable fine pointers.

### Performance

- One ResizeObserver per field measures the helper row for its height spring; cheap for a form, but avoid hundreds in a table.
- Only changed words animate, and numbers roll only the digits that changed.

### Notes for AI

- Default single-line text field. Use password-field, search-field, or number-field when the value has that shape.
- Works controlled or uncontrolled like a native input; pass name for plain form submission.
- Changing the error string rewords it in place, so derive it from state instead of toggling separate messages.

### Related

- [Textarea](https://uiarc.dev/components/textarea/markdown): A multiline field for notes, descriptions, and longer text.
- [Password field](https://uiarc.dev/components/password-field/markdown): Capture sensitive text with a visible reveal control.
- [Search field](https://uiarc.dev/components/search-field/markdown): A recognizable search entry point with clear affordances.
- [Number field](https://uiarc.dev/components/number-field/markdown): Enter a bounded number with clear increment controls.

### Also in text fields

- [Password strength](https://uiarc.dev/components/password-strength/markdown): Show how strong a new password is while it is typed.
- [Expanding search](https://uiarc.dev/components/expanding-search/markdown): An icon that morphs into a search field with results beneath it.
- [Inline edit](https://uiarc.dev/components/inline-edit/markdown): Rename in place: the text becomes a field without moving.

### Guidance for AI tools

Input: A single line field with clear labels and useful states. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Textarea

> A multiline field for notes, descriptions, and longer text.

- Type: Component (inputs)
- Access: Free, open source
- Page: https://uiarc.dev/components/textarea
- Markdown: https://uiarc.dev/components/textarea/markdown
- Registry item: https://uiarc.dev/r/textarea.json
- Source file: `registry/components/textarea/textarea.tsx`
- Dependencies: motion
- Keywords: field, form, react textarea, multi-line input, textarea with character count, animated textarea, comment field, form textarea

### When to use

- Free-form multi-line text like bios, comments, or feedback.
- Fields with a live character count, which rolls its digits in the helper row.

### When not to use

- Use input for single-line values.
- Use inline-edit with multiline for a description edited in place on a page.
- Use tag-input when the text is really a list of short values.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/textarea
pnpm dlx shadcn@latest add @uiarc/textarea
yarn dlx shadcn@latest add @uiarc/textarea
bunx --bun shadcn@latest add @uiarc/textarea
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/textarea.json
```

#### Manual

1. Install the dependencies:

```bash
npm install motion
```

2. Copy the source into your project. Main file: `registry/components/textarea/textarea.tsx`

   The source is in the registry item: https://uiarc.dev/r/textarea.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { Textarea } from "@/components/arc/textarea/textarea";

export function BioField() {
  const [bio, setBio] = useState("");
  return (
    <Textarea
      label="Bio"
      rows={4}
      value={bio}
      onChange={(event) => setBio(event.target.value)}
      description={`${280 - bio.length} characters left`}
    />
  );
}
```

### API reference

#### Textarea

A labelled multi-line field with the same animated helper and error rows as Input.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` (required) | `string` | – | Visible label, tied to the textarea with htmlFor. |
| `description` | `string` | – | Helper copy under the field, linked through aria-describedby. Counts such as "120 characters" roll their digits. |
| `error` | `string` | – | Error copy. Sets aria-invalid and renders in a role="alert" row. |
| `...props` | `TextareaHTMLAttributes<HTMLTextAreaElement>` | – | Forwarded to the native textarea, including ref, rows, value, onChange, and maxLength. |

### Accessibility

- Native textarea with a real label.
- Description and error ids are merged into aria-describedby; errors set aria-invalid and use role="alert".
- Animated copy is aria-hidden and mirrored in a visually hidden plain-text span.

### Motion

- Message rows open their height on a smooth spring; changed words rise in with a soft blur and counts roll only the digits that changed.
- Reduced motion drops the roll, blur, and height spring for instant changes.

### Responsive behavior

- It fills its column with a 110px minimum height and a vertical resize handle; it does not auto-grow with content.
- Hover border styles apply only on hover-capable fine pointers.

### Performance

- One ResizeObserver per field measures the helper row for its height spring; cheap for a form, but avoid hundreds in a table.
- Recomputing a character count on each keystroke only re-renders the helper row words that changed.

### Notes for AI

- Use for free-form, multi-line text. Use input for single lines and inline-edit for text edited in place on a page.
- A live character count in description gets the rolling-digit treatment for free.

### Related

- [Input](https://uiarc.dev/components/input/markdown): A single line field with clear labels and useful states.
- [Inline edit](https://uiarc.dev/components/inline-edit/markdown): Rename in place: the text becomes a field without moving.
- [Tag input](https://uiarc.dev/components/tag-input/markdown): Turn short text values into removable tags.

### Also in text fields

- [Password field](https://uiarc.dev/components/password-field/markdown): Capture sensitive text with a visible reveal control.
- [Password strength](https://uiarc.dev/components/password-strength/markdown): Show how strong a new password is while it is typed.
- [Search field](https://uiarc.dev/components/search-field/markdown): A recognizable search entry point with clear affordances.
- [Expanding search](https://uiarc.dev/components/expanding-search/markdown): An icon that morphs into a search field with results beneath it.

### Guidance for AI tools

Textarea: A multiline field for notes, descriptions, and longer text. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Password field

> Capture sensitive text with a visible reveal control.

- Type: Component (inputs)
- Access: Free, open source
- Page: https://uiarc.dev/components/password-field
- Markdown: https://uiarc.dev/components/password-field/markdown
- Registry item: https://uiarc.dev/r/password-field.json
- Source file: `registry/components/password-field/password-field.tsx`
- Dependencies: motion
- Keywords: field, security, react password input, show hide password, password toggle, password field with eye icon, login password field

### When to use

- Sign in forms and password confirmation fields.
- Any secret the person may want to check by revealing it.

### When not to use

- Use password-strength when creating or changing a password.
- Use input for non-secret values.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/password-field
pnpm dlx shadcn@latest add @uiarc/password-field
yarn dlx shadcn@latest add @uiarc/password-field
bunx --bun shadcn@latest add @uiarc/password-field
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/password-field.json
```

#### Manual

1. Install the dependencies:

```bash
npm install motion
```

2. Copy the source into your project. Main file: `registry/components/password-field/password-field.tsx`

   The source is in the registry item: https://uiarc.dev/r/password-field.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { PasswordField } from "@/components/arc/password-field/password-field";

export function SignInPassword() {
  return (
    <PasswordField
      label="Password"
      name="password"
      autoComplete="current-password"
      required
    />
  );
}
```

### Examples

#### Translated

```tsx
<PasswordField label="Passwort" messages={{ showPassword: "Passwort anzeigen", hidePassword: "Passwort verbergen" }} />
```

### API reference

#### PasswordField

A password input with a show and hide toggle whose eye icon is slashed by a drawn line.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` (required) | `string` | – | Visible label tied to the input. |
| `description` | `string` | – | Helper copy under the field, linked through aria-describedby. |
| `messages` | `Partial<{ showPassword: string; hidePassword: string }>` | `{ showPassword: "Show password", hidePassword: "Hide password" }` | Names of the reveal toggle, for translation. Pass only the strings you change. |
| `...props` | `Omit<InputHTMLAttributes<HTMLInputElement>, "type">` | – | Forwarded to the input, including ref, value, onChange, name, and autoComplete. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Enter / Space | On the toggle button, shows or hides the password. |

### Accessibility

- Toggle is a native button with aria-pressed and a label that switches between "Show password" and "Hide password" (messages.showPassword and messages.hidePassword).
- Description is linked through aria-describedby.
- Set autoComplete to current-password or new-password so password managers work.

### Motion

- A slash draws across the eye and masks the outline beneath it instead of swapping icons.
- After the first toggle, the value resolves through a short CSS reveal on each change; reduced motion draws the slash instantly.

### Responsive behavior

- The field fills its column; the reveal button sits inside the shell, so it never wraps below the input.
- Hover styles apply only on fine pointers.

### Performance

- One ResizeObserver per field measures the helper row for its height spring; cheap for a form, but avoid hundreds in a table.
- The reveal effect is a short CSS animation, and the slash is one drawn path.

### Notes for AI

- Use for sign in and password confirmation. Use password-strength when the user is creating a new password.
- Uncontrolled by default; pass value and onChange to control it like a native input.
- Every built-in string can be translated through messages; the label and description are your own props.

### Related

- [Password strength](https://uiarc.dev/components/password-strength/markdown): Show how strong a new password is while it is typed.
- [Input](https://uiarc.dev/components/input/markdown): A single line field with clear labels and useful states.

### Also in text fields

- [Textarea](https://uiarc.dev/components/textarea/markdown): A multiline field for notes, descriptions, and longer text.
- [Search field](https://uiarc.dev/components/search-field/markdown): A recognizable search entry point with clear affordances.
- [Expanding search](https://uiarc.dev/components/expanding-search/markdown): An icon that morphs into a search field with results beneath it.
- [Inline edit](https://uiarc.dev/components/inline-edit/markdown): Rename in place: the text becomes a field without moving.

### Guidance for AI tools

Password field: Capture sensitive text with a visible reveal control. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Password strength

> Show how strong a new password is while it is typed.

- Type: Component (inputs)
- Access: Free, open source
- Page: https://uiarc.dev/components/password-strength
- Markdown: https://uiarc.dev/components/password-strength/markdown
- Registry item: https://uiarc.dev/r/password-strength.json
- Source file: `registry/components/password-strength/password-strength.tsx`
- Dependencies: motion
- Keywords: password, strength meter, validation, react password strength, password strength meter, password requirements checklist, new password field, password validation, signup password

### When to use

- Sign up and change password forms.
- Password rules that should check off live as the person types.

### When not to use

- Use password-field for sign in.
- Use progress for measurable progress unrelated to passwords.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/password-strength
pnpm dlx shadcn@latest add @uiarc/password-strength
yarn dlx shadcn@latest add @uiarc/password-strength
bunx --bun shadcn@latest add @uiarc/password-strength
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/password-strength.json
```

#### Manual

1. Install the dependencies:

```bash
npm install motion
```

2. Copy the source into your project. Main file: `registry/components/password-strength/password-strength.tsx`

   The source is in the registry item: https://uiarc.dev/r/password-strength.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { PasswordStrength } from "@/components/arc/password-strength/password-strength";

export function NewPasswordField() {
  const [strong, setStrong] = useState(false);
  return (
    <PasswordStrength
      label="New password"
      name="password"
      autoComplete="new-password"
      onValueChange={(_, strength) => setStrong(strength.level >= 3)}
    />
  );
}
```

### Examples

#### Gate submit on strength

```tsx
const [level, setLevel] = useState(0);

<PasswordStrength
  label="New password"
  name="password"
  autoComplete="new-password"
  onValueChange={(_, strength) => setLevel(strength.level)}
/>
<Button type="submit" disabled={level < 3}>Create account</Button>
```

#### Translated, with your own length policy

```tsx
import { PasswordStrength, createPasswordRules } from "@/components/arc/password-strength/password-strength";

const rules = createPasswordRules({
  minLength: 10,
  labels: {
    length: min => `Mindestens ${min} Zeichen`,
    case: "Gross- und Kleinbuchstaben",
    number: "Mindestens eine Zahl",
    symbol: "Mindestens ein Sonderzeichen",
  },
});

export function NewPassword() {
  return (
    <PasswordStrength
      label="Neues Passwort"
      rules={rules}
      shortLength={10}
      messages={{
        levels: { tooShort: "Zu kurz", weak: "Schwach", fair: "Mittel", good: "Gut", strong: "Stark" },
        showPassword: "Passwort anzeigen",
        meterLabel: "Passwortstärke",
        noPassword: "Noch kein Passwort",
        rulesLabel: "Passwortanforderungen",
        ruleMet: ", erfüllt",
        ruleNotMet: ", nicht erfüllt",
        remainingPrefix: "noch",
        remainingSuffix: "",
        summary: ({ label, met, total }) => `Stärke: ${label}. ${met} von ${total} Anforderungen erfüllt.`,
      }}
    />
  );
}
```

### API reference

#### PasswordStrength

A new-password field with a four-segment meter, rule checklist, and a morphing strength word.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` (required) | `string` | – | Visible label tied to the input. |
| `value` | `string` | – | Controlled password. |
| `defaultValue` | `string` | `""` | Initial value when uncontrolled. |
| `onValueChange` | `(value: string, strength: PasswordStrengthResult) => void` | – | Called on every change with the value and its { level, label, met } score. |
| `rules` | `PasswordRule[]` | `defaultPasswordRules` | { id, label, test, remaining? } rules. Strength is the share met across four steps. |
| `error` | `string` | – | Error copy; sets aria-invalid and shakes the field once per new error. |
| `revealed` | `boolean` | – | Controlled show or hide state. |
| `onRevealedChange` | `(revealed: boolean) => void` | – | Called when the reveal toggle is pressed. |
| `messages` | `PasswordStrengthMessagesInput` | `defaultPasswordStrengthMessages` | Every built-in string, for translation: levels { tooShort, weak, fair, good, strong }, showPassword, meterLabel, noPassword, rulesLabel, ruleMet, ruleNotMet, remainingPrefix, remainingSuffix, and summary({ label, met, total }). Pass only what you change; the rest stay English. |
| `shortLength` | `number` | `8` | Below this many characters the meter holds at its first step and reads the tooShort word. |
| `countCharacters` | `(password: string) => number` | `countCodePoints` | How shortLength counts characters. Code points by default (an emoji counts once); pass password => password.length to match a policy that counts UTF-16 units. |
| `...props` | `Omit<InputHTMLAttributes<HTMLInputElement>, "type" \| "value" \| "defaultValue" \| "children">` | – | Forwarded to the input, including ref, name, autoComplete, and onChange. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Enter / Space | On the reveal button, shows or hides the password. |

### Accessibility

- The meter is role="meter" with aria-valuenow 0 to 4 and aria-valuetext set to the strength word.
- The rules list is linked to the input through aria-describedby along with any error; errors set aria-invalid.
- A role="status" region summarizes strength and rules met; the reveal button uses aria-pressed and aria-controls.

### Motion

- Segments fill and change tone in a staggered wave, rules check off with drawn ticks, remaining counts roll, and the word morphs up or down with strength.
- Reduced motion, applied after hydration, drops the shake, wave, and roll in favor of instant changes.

### Responsive behavior

- On coarse pointers the input grows to the base font size, so iOS does not zoom on focus.
- The four-segment meter shares the row width evenly and shrinks with the column.

### Performance

- Scoring runs on the device on every keystroke with simple rule tests; there is no dictionary check.
- One ResizeObserver per field measures the helper row for its height spring; cheap for a form, but avoid hundreds in a table.

### Notes for AI

- Use when creating or changing a password. Use password-field for sign in.
- Controlled or uncontrolled; read strength from onValueChange to gate submit. Scoring runs on the device.
- Also exports estimateStrength(password, rules, { shortLength, levels, countCharacters }), defaultPasswordRules, and createPasswordRules({ minLength, labels, countCharacters }) for server-side checks, translated rule labels, or your own length policy.
- To translate, pass messages for the component's own copy and build rules with createPasswordRules({ labels }) for the rule labels. Keep shortLength and the rules' minLength in line with your server's policy.

### Related

- [Password field](https://uiarc.dev/components/password-field/markdown): Capture sensitive text with a visible reveal control.
- [Input](https://uiarc.dev/components/input/markdown): A single line field with clear labels and useful states.
- [Progress](https://uiarc.dev/components/progress/markdown): Show how much of a known task is complete.

### Also in text fields

- [Textarea](https://uiarc.dev/components/textarea/markdown): A multiline field for notes, descriptions, and longer text.
- [Search field](https://uiarc.dev/components/search-field/markdown): A recognizable search entry point with clear affordances.
- [Expanding search](https://uiarc.dev/components/expanding-search/markdown): An icon that morphs into a search field with results beneath it.
- [Inline edit](https://uiarc.dev/components/inline-edit/markdown): Rename in place: the text becomes a field without moving.

### Guidance for AI tools

Password strength: Show how strong a new password is while it is typed. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Search field

> A recognizable search entry point with clear affordances.

- Type: Component (inputs)
- Access: Free, open source
- Page: https://uiarc.dev/components/search-field
- Markdown: https://uiarc.dev/components/search-field/markdown
- Registry item: https://uiarc.dev/r/search-field.json
- Source file: `registry/components/search-field/search-field.tsx`
- Dependencies: motion, lucide-react
- Keywords: field, search, react search input, search field, search bar with clear button, filter input, list filter search

### When to use

- Filtering a visible list or table in place.
- Toolbar search where the query should be clearable with one click.

### When not to use

- Use expanding-search for compact header search with results.
- Use combobox when the search sets a form value.
- Use filter-toolbar when search sits with other filters and sort.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/search-field
pnpm dlx shadcn@latest add @uiarc/search-field
yarn dlx shadcn@latest add @uiarc/search-field
bunx --bun shadcn@latest add @uiarc/search-field
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/search-field.json
```

#### Manual

1. Install the dependencies:

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

2. Copy the source into your project. Main file: `registry/components/search-field/search-field.tsx`

   The source is in the registry item: https://uiarc.dev/r/search-field.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { SearchField } from "@/components/arc/search-field/search-field";

export function MemberFilter() {
  const [query, setQuery] = useState("");
  return (
    <SearchField
      label="Search members"
      placeholder="Name or email"
      value={query}
      onValueChange={setQuery}
    />
  );
}
```

### API reference

#### SearchField

A controlled search input with a clear button that scales in inside a reserved slot.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` (required) | `string` | – | Visible label tied to the input. |
| `value` (required) | `string` | – | Current query. |
| `onValueChange` (required) | `(value: string) => void` | – | Called on every keystroke and with an empty string when cleared. |
| `...props` | `Omit<InputHTMLAttributes<HTMLInputElement>, "type">` | – | Forwarded to the input, including ref, placeholder, and name. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Escape | Clears the field (native type="search" behavior in most browsers). |

### Accessibility

- Native input type="search" with a real label.
- Clear button is labelled "Clear search" and returns focus to the input.
- The search icon is aria-hidden.

### Motion

- The clear button scales in from 0.8 with a slight blur on a snappy spring and presses to 0.96.
- Reduced motion fades it in and out without scale or blur; the reserved slot keeps the field width fixed either way.

### Responsive behavior

- The clear button has a reserved slot, so the field width never shifts when it appears.
- It fills its column with min-width 0 and shrinks inside narrow toolbars.

### Performance

- onValueChange fires on every keystroke; debounce expensive filtering or fetching yourself.

### Notes for AI

- Use to filter a visible list in place. Use expanding-search for a compact header search with results, and combobox to choose a value.
- Always controlled: pass value and onValueChange, and debounce expensive filtering yourself.

### Related

- [Expanding search](https://uiarc.dev/components/expanding-search/markdown): An icon that morphs into a search field with results beneath it.
- [Combobox](https://uiarc.dev/components/combobox/markdown): Search and select from a list without leaving the field.
- [Filter toolbar](https://uiarc.dev/components/filter-toolbar/markdown): Keep collection filters close and easy to reset.

### Also in text fields

- [Input](https://uiarc.dev/components/input/markdown): A single line field with clear labels and useful states.
- [Textarea](https://uiarc.dev/components/textarea/markdown): A multiline field for notes, descriptions, and longer text.
- [Password field](https://uiarc.dev/components/password-field/markdown): Capture sensitive text with a visible reveal control.
- [Password strength](https://uiarc.dev/components/password-strength/markdown): Show how strong a new password is while it is typed.
- [Inline edit](https://uiarc.dev/components/inline-edit/markdown): Rename in place: the text becomes a field without moving.

### Guidance for AI tools

Search field: A recognizable search entry point with clear affordances. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Expanding search

> An icon that morphs into a search field with results beneath it.

- Type: Component (inputs)
- Access: Free, open source
- Page: https://uiarc.dev/components/expanding-search
- Markdown: https://uiarc.dev/components/expanding-search/markdown
- Registry item: https://uiarc.dev/r/expanding-search.json
- Source file: `registry/components/expanding-search/expanding-search.tsx`
- Dependencies: motion, lucide-react
- Keywords: search, field, motion, react expanding search, search icon expand, animated search bar, header search, search with results dropdown, collapsible search

### When to use

- Header or toolbar search where a full field would crowd the layout.
- Quick navigation across local items with grouped results and recent suggestions.

### When not to use

- Use search-field to filter a visible list in place.
- Use combobox to set a form value.
- Use command-palette for searching commands across the app.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/expanding-search
pnpm dlx shadcn@latest add @uiarc/expanding-search
yarn dlx shadcn@latest add @uiarc/expanding-search
bunx --bun shadcn@latest add @uiarc/expanding-search
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/expanding-search.json
```

#### Manual

1. Install the dependencies:

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

2. Copy the source into your project. Main file: `registry/components/expanding-search/expanding-search.tsx`

   The source is in the registry item: https://uiarc.dev/r/expanding-search.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { ExpandingSearch } from "@/components/arc/expanding-search/expanding-search";

export function HeaderSearch() {
  const router = useRouter();
  return (
    <ExpandingSearch
      label="Search projects and docs"
      items={[
        { id: "p1", title: "Arc website", group: "Projects", meta: "Updated today" },
        { id: "d1", title: "Motion tokens", group: "Docs", keywords: ["spring"] },
      ]}
      onSelect={(item) => router.push(`/items/${item.id}`)}
    />
  );
}
```

### API reference

#### ExpandingSearch

An icon button that morphs into a search field with grouped, highlighted results beneath it.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` (required) | `string` | – | Names the button, field, and results, such as "Search projects and docs". |
| `items` (required) | `ExpandingSearchItem[]` | – | { id, title, meta?, group?, icon?, keywords? }. Filtered client-side by title and keywords. |
| `suggestions` | `ExpandingSearchItem[]` | `[]` | Shown before anything is typed, such as recent searches. |
| `suggestionsLabel` | `string` | `"Recent"` | Heading for suggestions. |
| `placeholder` | `string` | – | Field placeholder. Defaults to label. |
| `onSelect` | `(item: ExpandingSearchItem) => void` | – | Called when a result is chosen; the field then folds back. |
| `onExpandedChange` | `(expanded: boolean) => void` | – | Called when the field opens or folds. |
| `expandedWidth` | `number` | `360` | Widest the field grows, never past its container. |
| `maxResults` | `number` | `6` | Most results shown. |
| `anchor` | `"start" \| "end"` | `"end"` | Edge the button sits on; the field grows away from it. |
| `emptyHint` | `string` | `"Try a shorter word or check the spelling."` | Tip under the empty state. |
| `className` | `string` | – | Added to the root. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Enter / Space | On the icon button, expands the field. |
| ArrowDown / ArrowUp | Moves through results, wrapping. |
| Enter | Chooses the active result. |
| Escape | Folds the field back into the icon. |

### Accessibility

- The field is role="combobox" with aria-expanded, aria-controls, aria-autocomplete="list", and aria-activedescendant.
- Results are a role="listbox" of role="option" items inside labelled role="group" sections.
- Result counts and empty states are announced through a polite live region; the collapsed field is inert.

### Motion

- The button morphs into the field on a spring, results unfold beneath with a panel that tracks the field width, and a highlight travels between options.
- Reduced motion swaps states with fades and no width or position travel.

### Responsive behavior

- The field grows to the smaller of expandedWidth and its container, and a ResizeObserver follows container resizes.
- The results panel matches the field width and caps at min(22rem, 60vh), scrolling itself.
- The idle lane takes no pointer events, so it never blocks what sits under it on small screens.

### Performance

- Ranking is memoized and runs over all items per query; pass pre-filtered or server results for large sets.
- Result rows use layout position animation, capped by maxResults at 6 by default.

### Notes for AI

- Use in headers and toolbars where a full field would crowd the layout. Use search-field to filter a list in place and combobox to set a form value.
- Place it in the space it may grow into; it fills that space up to expandedWidth. Filtering is local, so pass pre-fetched items or update items as the query changes.
- Exported as both named and default.

### Related

- [Search field](https://uiarc.dev/components/search-field/markdown): A recognizable search entry point with clear affordances.
- [Combobox](https://uiarc.dev/components/combobox/markdown): Search and select from a list without leaving the field.
- [Morph nav](https://uiarc.dev/components/morph-nav/markdown): A navigation bar that morphs into rich menus, search, and a compact state as one surface.

### Also in text fields

- [Input](https://uiarc.dev/components/input/markdown): A single line field with clear labels and useful states.
- [Textarea](https://uiarc.dev/components/textarea/markdown): A multiline field for notes, descriptions, and longer text.
- [Password field](https://uiarc.dev/components/password-field/markdown): Capture sensitive text with a visible reveal control.
- [Password strength](https://uiarc.dev/components/password-strength/markdown): Show how strong a new password is while it is typed.
- [Inline edit](https://uiarc.dev/components/inline-edit/markdown): Rename in place: the text becomes a field without moving.

### Guidance for AI tools

Expanding search: An icon that morphs into a search field with results beneath it. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Inline edit

> Rename in place: the text becomes a field without moving.

- Type: Component (inputs)
- Access: Free, open source
- Page: https://uiarc.dev/components/inline-edit
- Markdown: https://uiarc.dev/components/inline-edit/markdown
- Registry item: https://uiarc.dev/r/inline-edit.json
- Source file: `registry/components/inline-edit/inline-edit.tsx`
- Dependencies: motion, lucide-react
- Keywords: inline edit, rename, click to edit, react inline edit, editable text, inline editing, rename in place, optimistic save field

### When to use

- Titles and descriptions read far more often than edited, like a project name.
- Single fields that save on their own with optimistic updates and rollback.

### When not to use

- Use input or textarea in a form when several fields save together.
- Use input when the field should always look editable.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/inline-edit
pnpm dlx shadcn@latest add @uiarc/inline-edit
yarn dlx shadcn@latest add @uiarc/inline-edit
bunx --bun shadcn@latest add @uiarc/inline-edit
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/inline-edit.json
```

#### Manual

1. Install the dependencies:

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

2. Copy the source into your project. Main file: `registry/components/inline-edit/inline-edit.tsx`

   The source is in the registry item: https://uiarc.dev/r/inline-edit.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { InlineEdit } from "@/components/arc/inline-edit/inline-edit";

export function ProjectTitle({ project }: { project: { id: string; name: string } }) {
  return (
    <InlineEdit
      as="h1"
      label="Project name"
      value={project.name}
      validate={(next) => (next.trim() ? null : "Name can’t be empty")}
      onSave={(next) => renameProject(project.id, next)}
    />
  );
}
```

### API reference

#### InlineEdit

Click-to-edit text that becomes a field in place with the same metrics, saves optimistically, and rolls back on failure.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` (required) | `string` | – | The saved value. Outside changes replace the text while not editing. |
| `onSave` (required) | `(next: string) => void \| Promise<unknown>` | – | Persists the value. Return a promise to show saving; reject it to roll back with a retry. |
| `label` (required) | `string` | – | Accessible name, for example "Project name". |
| `validate` | `(next: string) => string \| null \| undefined` | – | Returns an error message to block saving. |
| `placeholder` | `string` | `""` | Shown when the value is empty. |
| `multiline` | `boolean` | `false` | Wraps and grows in height; Shift+Enter adds a line break. |
| `variant` | `"title" \| "body"` | `"title"` | Type style: title for names and headings, body for descriptions. |
| `as` | `"span" \| "p" \| "h1" \| "h2" \| "h3"` | `"span"` | Element that holds the text, so a title can stay a heading. |
| `className` | `string` | – | Added to the root. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Enter / Space | On the text, starts editing. |
| Enter | Saves the draft. In multiline mode, Shift+Enter inserts a line break. |
| Escape | Cancels and rolls the text back. |
| Tab | Leaving the component saves, the way a rename does. |

### Accessibility

- The resting text is a native button labelled "<label>: <value>", so it is focusable and announced as editable.
- The field has aria-label and aria-invalid; validation and save errors render in a polite live region linked through aria-describedby.
- Save progress and results are announced through a role="status" region; save and cancel buttons are labelled.

### Motion

- Text rolls between values, a check draws once a save lands, and multiline boxes follow their height; failed saves roll back with motion.
- Reduced motion crossfades text, draws the check instantly, and replaces the spinner with a static mark.

### Responsive behavior

- Text wraps within the column and reserves 66px at the end for the save and cancel buttons.
- With multiline the box grows in height as the text wraps.
- Hover hints apply only on fine pointers; on touch a tap starts editing.

### Performance

- Two ResizeObservers size the frame; sizes are measured in a layout effect, so no frame shows a wrong width.

### Notes for AI

- Use for single fields read far more often than edited, like titles and descriptions. Use a regular form with input or textarea when several fields save together.
- value is controlled by the saved data; update it after onSave resolves. Return a promise from onSave to get saving, saved, and failed states.
- Exported as both named and default.

### Related

- [Input](https://uiarc.dev/components/input/markdown): A single line field with clear labels and useful states.
- [Textarea](https://uiarc.dev/components/textarea/markdown): A multiline field for notes, descriptions, and longer text.
- [Toast](https://uiarc.dev/components/toast/markdown): Brief confirmation for a completed background action.

### Also in text fields

- [Password field](https://uiarc.dev/components/password-field/markdown): Capture sensitive text with a visible reveal control.
- [Password strength](https://uiarc.dev/components/password-strength/markdown): Show how strong a new password is while it is typed.
- [Search field](https://uiarc.dev/components/search-field/markdown): A recognizable search entry point with clear affordances.
- [Expanding search](https://uiarc.dev/components/expanding-search/markdown): An icon that morphs into a search field with results beneath it.

### Guidance for AI tools

Inline edit: Rename in place: the text becomes a field without moving. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Number field

> Enter a bounded number with clear increment controls.

- Type: Component (inputs)
- Access: Free, open source
- Page: https://uiarc.dev/components/number-field
- Markdown: https://uiarc.dev/components/number-field/markdown
- Registry item: https://uiarc.dev/r/number-field.json
- Source file: `registry/components/number-field/number-field.tsx`
- Dependencies: motion, lucide-react
- Keywords: field, numeric, react number input, number field, stepper input, quantity selector, numeric input with buttons, scrub input, odometer number input

### When to use

- Bounded quantities like seats, items, or prices where the exact number matters.
- Values people nudge with steppers, arrow keys, or by dragging the label with scrub.
- Numbers with units, using a prefix or a pluralizing suffix function.

### When not to use

- Use slider when the approximate position matters more than the exact number.
- Use input for numeric strings like phone numbers or codes.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/number-field
pnpm dlx shadcn@latest add @uiarc/number-field
yarn dlx shadcn@latest add @uiarc/number-field
bunx --bun shadcn@latest add @uiarc/number-field
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/number-field.json
```

#### Manual

1. Install the dependencies:

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

2. Copy the source into your project. Main file: `registry/components/number-field/number-field.tsx`

   The source is in the registry item: https://uiarc.dev/r/number-field.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { NumberField } from "@/components/arc/number-field/number-field";

export function SeatsField() {
  const [seats, setSeats] = useState(5);
  return (
    <NumberField
      label="Seats"
      value={seats}
      onValueChange={setSeats}
      min={1}
      max={500}
      suffix={(n) => (n === 1 ? " seat" : " seats")}
      scrub
    />
  );
}
```

### API reference

#### NumberField

A numeric spinbutton with stepper buttons, rolling digits, hold-to-repeat, and optional label scrubbing.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` (required) | `string` | – | Visible label; also names the stepper buttons. |
| `value` | `number` | – | Controlled value. |
| `defaultValue` | `number` | `0` | Initial value when uncontrolled. |
| `onValueChange` | `(value: number) => void` | – | Called on every committed step, scrub, or valid typed draft. |
| `min` | `number` | `0` | Lower bound. |
| `max` | `number` | `Number.MAX_SAFE_INTEGER` | Upper bound. |
| `step` | `number` | `1` | Increment; its precision also sets default fraction digits. |
| `largeStep` | `number` | `step * 10` | Distance for PageUp, PageDown, and Shift with an arrow. |
| `description` | `string` | – | Helper copy under the field. |
| `disabled` | `boolean` | – | Disables the input and buttons. |
| `id` | `string` | – | Input id. Generated when omitted. |
| `prefix` | `string \| ((value: number) => string)` | – | Text before the number, such as "$". |
| `suffix` | `string \| ((value: number) => string)` | – | Text after the number; a function can pluralize, e.g. n => n === 1 ? " seat" : " seats". |
| `scrub` | `boolean` | `false` | Drag the label sideways to change the value. |
| `locale` | `string` | `"en-US"` | Formatting locale, fixed so server and client match. |
| `formatOptions` | `{ minimumFractionDigits?: number; maximumFractionDigits?: number; useGrouping?: boolean }` | – | Fraction digits and grouping. |
| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Control height, type size, and default width (164, 196, or 228px). |
| `limitHint` | `boolean \| ((edge: "min" \| "max", limit: number) => string)` | `true` | Note beside the label when a press meets a limit (about 1.5s) or a typed value passes one. Defaults to "Max 10 seats" using the prefix and suffix; false hides it. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| ArrowUp / ArrowDown | Steps by step; holding repeats and speeds up, and keeps pushing at a limit. |
| Shift + Arrow / PageUp / PageDown | Steps by largeStep. |
| Home / End | Jumps to min or max when not typing. |
| Enter | Commits a typed draft, clamped to min and max, or selects the value. |
| Escape | Reverts a typed draft to the value before editing. |

### Accessibility

- The input has role="spinbutton" with aria-valuenow, aria-valuemin, aria-valuemax, and aria-valuetext including prefix and suffix.
- Stepper buttons are labelled "Increase <label>" and "Decrease <label>" and marked aria-disabled at a limit.
- Changes are announced through a polite aria-live region, and a clamp says which limit it met ("10 seats, maximum"); rolling digits are aria-hidden.
- A typed value past a limit sets aria-invalid and adds the limit note to aria-describedby until it commits. The warning also uses copy, never color alone.
- Pointer focus draws no ring; keyboard focus shows Arc's shared focus ring. Focus darkens the shell border, and a focused stepper button takes its hover fill.

### Motion

- Digits roll on wheels in the direction of change (up rolls up, down rolls down) with tabular numerals, and affixes reword in place.
- Holding a stepper repeats after 400ms and ramps from 150ms to 40ms per step.
- At a limit the value strains a few pixels toward the press and springs home; pushes in a row strain a little further, capped like overscroll. The refused button shakes once and the limit note rises in beside the label.
- A typed value past a limit tints the shell with the warning role; on Enter or blur it springs back to the limit with a digit roll.
- Reduced motion changes the value at once and answers a press at a limit with a brief warning tint on the number instead of the strain and shake.

### Responsive behavior

- The control is min(100%, 196px) wide at md (164px at sm, 228px at lg), overridable with --number-field-width. The label row, with its limit note, follows the same width.
- Stepper buttons are 28, 34, or 40px by size with touch-action manipulation, so fast taps do not zoom.
- Scrubbing the label uses pointer capture with touch-action pan-y, so vertical scrolling still works on touch.

### Performance

- Holding a stepper repeats on timeouts that speed up, not a per-frame loop.
- Two ResizeObservers handle digit layout and the helper row; fine for forms, not for large grids.

### Notes for AI

- Use for bounded integers or decimals like quantities, seats, and prices. Use slider when the approximate position matters more than the exact number.
- Controlled with value and onValueChange or uncontrolled with defaultValue. There is no name prop; add a hidden input for plain forms.
- Set min below zero to allow negatives; the input then accepts a minus sign.
- The limit note sits at the end of the label row, so keep labels short enough to share the control's width with it, or set limitHint={false}.

### Related

- [Slider](https://uiarc.dev/components/slider/markdown): Pick a value or a range on a track that follows your finger.
- [Input](https://uiarc.dev/components/input/markdown): A single line field with clear labels and useful states.
- [Animated counter](https://uiarc.dev/components/animated-counter/markdown): Give changing totals a clear sense of movement.

### Also in special inputs

- [Money input](https://uiarc.dev/components/money-input/markdown): A currency field with live grouping, stable width, rolling digits, and minor-unit output.
- [Phone input](https://uiarc.dev/components/phone-input/markdown): A phone field with a country picker, formatting as you type, and E.164 output.
- [Scrub input](https://uiarc.dev/components/scrub-input/markdown): A Figma-style number field: drag the label to scrub, or type values, units, and arithmetic.
- [Tag input](https://uiarc.dev/components/tag-input/markdown): Turn short text values into removable tags.
- [Mention input](https://uiarc.dev/components/mention-input/markdown): A textarea with @people and #channel mentions that act as single tokens, with suggestions at the caret.
- [Shortcut recorder](https://uiarc.dev/components/shortcut-recorder/markdown): Record key combinations into key caps, with conflict warnings, Kbd, and a searchable cheatsheet.

### Guidance for AI tools

Number field: Enter a bounded number with clear increment controls. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Money input

> A currency field with live grouping, stable width, rolling digits, and minor-unit output.

- Type: Component (inputs)
- Access: Free, open source
- Page: https://uiarc.dev/components/money-input
- Markdown: https://uiarc.dev/components/money-input/markdown
- Registry item: https://uiarc.dev/r/money-input.json
- Source file: `registry/components/money-input/money-input.tsx`
- Dependencies: motion, lucide-react
- Keywords: inputs, new, react money input, currency input, amount field, price input, cents input, currency selector, formatted number input, payment amount

### When to use

- Payment, tip, transfer, or budget amounts entered by hand.
- Invoice and expense forms where the currency may change.
- Amount fields that benefit from quick add chips such as +$10.

### When not to use

- Use number-field for quantities and non currency numbers.
- Use slider or price-ladder when people pick from a range rather than type.
- Use scrub-input for design tool style drag adjustments.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/money-input
pnpm dlx shadcn@latest add @uiarc/money-input
yarn dlx shadcn@latest add @uiarc/money-input
bunx --bun shadcn@latest add @uiarc/money-input
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/money-input.json
```

#### Manual

1. Install the dependencies:

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

2. Copy the source into your project. Main file: `registry/components/money-input/money-input.tsx`

   The source is in the registry item: https://uiarc.dev/r/money-input.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { useState } from "react";
import { MoneyInput } from "@/components/arc/money-input/money-input";

export function TipAmount() {
  const [cents, setCents] = useState<number | null>(1500);
  return (
    <MoneyInput
      label="Amount"
      name="amount"
      value={cents}
      onValueChange={setCents}
      currencies={["USD"]}
      min={100}
      max={100_000}
      quickAdd={[5, 10, 20]}
    />
  );
}
```

### API reference

#### MoneyInput

A currency amount field that groups digits as you type, holds missing cents as ghosts, scales long amounts to fit, and returns minor units.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` (required) | `string` | – | Field label. |
| `hideLabel` | `boolean` | `false` | Keeps the label for screen readers only. |
| `value` | `number \| null` | – | Controlled amount in minor units (cents for USD, yen for JPY). null is empty. |
| `defaultValue` | `number \| null` | `null` | Starting amount in minor units when uncontrolled. |
| `onValueChange` | `(value: number \| null, details: MoneyInputDetails) => void` | – | Called with minor units and { currency, major, formatted }. |
| `currency` | `string` | – | Controlled ISO 4217 code, such as "USD". |
| `defaultCurrency` | `string` | `"USD"` | Starting currency when uncontrolled. |
| `onCurrencyChange` | `(currency: string) => void` | – | Called when a currency is picked. The major amount carries over. |
| `currencies` | `string[]` | `["USD", "EUR", "GBP", "JPY", "CAD", "AUD", "CHF", "INR"]` | Codes in the currency menu. Pass one code to hide the menu. |
| `min` | `number` | – | Lowest amount in minor units. Checked when the field loses focus. |
| `max` | `number` | – | Highest amount in minor units. Typing past it is refused with a nudge. |
| `quickAdd` | `number[]` | `[10, 50, 100]` | Quick add chips in major units. Pass an empty array to hide them. |
| `step` | `number` | – | Arrow keys move by this many minor units. Defaults to one major unit; Shift moves ten times as far. |
| `locale` | `string` | `"en-US"` | Formatting locale. Fixed by default so server and client render the same digits. |
| `description` | `string` | – | Hint under the field. |
| `error` | `string` | – | Replaces the built-in range message. |
| `disabled` | `boolean` | `false` | Disables the field, menu, and chips. |
| `name` | `string` | – | Adds a hidden input carrying the amount in minor units. |
| `id` | `string` | – | Id of the input. |
| `className` | `string` | – | Class on the root. |
| `onBlur` | `(event: FocusEvent<HTMLInputElement>) => void` | – | Called when the input loses focus, after the fraction settles. |
| `ref` | `Ref<HTMLInputElement>` | – | Forwarded to the input. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| ArrowUp / ArrowDown | Adds or subtracts one step (one major unit by default). |
| Shift+ArrowUp / Shift+ArrowDown | Moves ten steps. |
| PageUp / PageDown | Moves ten steps. |
| Enter | Settles the fraction, such as 12.5 to 12.50. |
| Backspace / Delete | Over a group separator, deletes the digit beside it. |
| ArrowDown / ArrowUp (on the currency button) | Opens the currency menu. |
| ArrowDown / ArrowUp / Home / End (in the menu) | Moves through currencies; typing jumps by code or name. |
| Enter / Space (in the menu) | Picks the highlighted currency. |
| Escape (in the menu) | Closes the menu and returns to the button. |

### Accessibility

- The input has role="spinbutton" with aria-valuenow in major units, aria-valuetext as the full currency string, and min and max when set.
- The animated digits are aria-hidden; the real input carries the value, so screen readers and autofill see plain text.
- The range, hint, and error are linked with aria-describedby; limits, chip adds, and currency changes are announced politely.
- The currency menu is a listbox with aria-activedescendant and typeahead.

### Motion

- Chips and arrow keys roll each digit column in the direction of change while new columns open their width; typing cuts straight to the result so the caret never lags.
- A refused change kicks the amount sideways on a bouncy spring and flashes the range.
- The currency symbol swaps with a short roll while its slot springs to the new width; long amounts scale down to fit on a spring.
- Reduced motion removes the rolls, kick, and width springs; digits fade and sizes jump.

### Responsive behavior

- Under 420px viewport width the amount text drops a size and the padding tightens.
- A ResizeObserver scales the amount down to fit its box instead of scrolling, so long numbers stay readable on phones.
- inputMode is decimal (numeric for zero decimal currencies like JPY), which brings up the number keypad on touch.

### Performance

- Intl.NumberFormat instances are cached per locale and currency.
- Each digit is its own animated column; amounts are capped at 12 integer digits, which keeps the column count small.

### Notes for AI

- Store the value in minor units (integers) to avoid floating point errors; details.major and details.formatted are for display.
- Use for money only. For plain numbers with units use number-field, and for drag-to-adjust values use scrub-input.
- Pass one code in currencies to lock the currency; the code then shows as static text.
- max refuses typing past it; min is only checked on blur, so people can type through smaller amounts on the way.

### Related

- [Number field](https://uiarc.dev/components/number-field/markdown): Enter a bounded number with clear increment controls.
- [Scrub input](https://uiarc.dev/components/scrub-input/markdown): A Figma-style number field: drag the label to scrub, or type values, units, and arithmetic.
- [Input](https://uiarc.dev/components/input/markdown): A single line field with clear labels and useful states.
- [Pricing calculator](https://uiarc.dev/components/blocks/pricing-calculator/markdown): A seat slider and billing toggle drive plan cards with rolling prices and a moving recommended badge.
- [Invoice studio](https://uiarc.dev/components/blocks/invoice-studio/markdown): An editable invoice with live totals and a clear save flow.

### Also in special inputs

- [Phone input](https://uiarc.dev/components/phone-input/markdown): A phone field with a country picker, formatting as you type, and E.164 output.
- [Tag input](https://uiarc.dev/components/tag-input/markdown): Turn short text values into removable tags.
- [Mention input](https://uiarc.dev/components/mention-input/markdown): A textarea with @people and #channel mentions that act as single tokens, with suggestions at the caret.
- [Shortcut recorder](https://uiarc.dev/components/shortcut-recorder/markdown): Record key combinations into key caps, with conflict warnings, Kbd, and a searchable cheatsheet.

### Guidance for AI tools

Money input: A currency field with live grouping, stable width, rolling digits, and minor-unit output. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Phone input

> A phone field with a country picker, formatting as you type, and E.164 output.

- Type: Component (inputs)
- Access: Free, open source
- Page: https://uiarc.dev/components/phone-input
- Markdown: https://uiarc.dev/components/phone-input/markdown
- Registry item: https://uiarc.dev/r/phone-input.json
- Source file: `registry/components/phone-input/phone-input.tsx`
- Dependencies: motion, lucide-react
- Keywords: inputs, new, react phone input, phone number field, country code picker, international phone input, e164 phone, phone number formatting, tel input with flag

### When to use

- Sign up, checkout, and contact forms that need a phone number in E.164.
- International audiences where the country and calling code must be clear.
- Two factor setup before sending an SMS code.

### When not to use

- Use input with type="tel" when you only store free text and never dial or text the number.
- Use otp-input for the verification code itself.
- Use a full metadata library if you need carrier or number type validation beyond length.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/phone-input
pnpm dlx shadcn@latest add @uiarc/phone-input
yarn dlx shadcn@latest add @uiarc/phone-input
bunx --bun shadcn@latest add @uiarc/phone-input
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/phone-input.json
```

#### Manual

1. Install the dependencies:

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

2. Copy the source into your project. Main file: `registry/components/phone-input/phone-input.tsx`

   The source is in the registry item: https://uiarc.dev/r/phone-input.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { useState } from "react";
import { PhoneInput } from "@/components/arc/phone-input/phone-input";

export function ContactPhone() {
  const [phone, setPhone] = useState("");
  const [valid, setValid] = useState(false);
  return (
    <PhoneInput
      label="Phone number"
      name="phone"
      value={phone}
      onValueChange={(value, details) => { setPhone(value); setValid(details.valid); }}
      defaultCountry="GB"
      preferredCountries={["GB", "IE", "US"]}
      description={valid ? undefined : "We only text about your order"}
    />
  );
}
```

### API reference

#### PhoneInput

A phone number field with a searchable country picker that grows out of the flag button, formatting as you type and returning E.164.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` (required) | `string` | – | Field label. |
| `hideLabel` | `boolean` | `false` | Keeps the label for screen readers only. |
| `value` | `string` | – | Controlled number in E.164, such as "+14155550132". An empty string clears the field. |
| `defaultValue` | `string` | – | Starting number when uncontrolled. |
| `onValueChange` | `(value: string, details: PhoneInputDetails) => void` | – | Fires on every edit with the E.164 number (empty without digits) and { country, formatted, status, valid }. |
| `country` | `string` | – | Controlled ISO code of the selected country. |
| `defaultCountry` | `string` | `"US"` | ISO code used until someone picks a country or enters an international number. |
| `onCountryChange` | `(iso: string) => void` | – | Called when the country changes, including from a pasted number. |
| `countries` | `string[]` | – | Limit the picker to these ISO codes. |
| `preferredCountries` | `string[]` | `["US", "CA", "GB"]` | Pinned at the top of the picker under Suggested. |
| `description` | `string` | – | Hint under the field. |
| `error` | `string` | – | Replaces the built-in validation message. |
| `validate` | `boolean` | `true` | Show a message after blur when the number has the wrong length. |
| `disabled` | `boolean` | `false` | Disables the number and the picker. |
| `required` | `boolean` | – | Marks the number input required. |
| `name` | `string` | – | Adds a hidden input carrying the E.164 value for native form submission. |
| `id` | `string` | – | Id of the number input. |
| `className` | `string` | – | Class on the root. |
| `onBlur` | `(event: FocusEvent<HTMLInputElement>) => void` | – | Called when the number input loses focus. |
| `ref` | `Ref<HTMLInputElement>` | – | Forwarded to the number input. |

#### parsePhoneNumber / formatPhoneNumber / formatNational

Helpers: parse "+44 (0)7911…" or "0044…" into { country, national }, format E.164 for display, or format national digits for a country.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `input` (required) | `string` | – | parsePhoneNumber(input, pool?) returns { country, national } or null. |
| `e164` (required) | `string` | – | formatPhoneNumber(e164) returns "+44 7400 123456", or the input when it can not be read. |
| `entry, digits` (required) | `PhoneCountry, string` | – | formatNational(entry, digits) formats national digits, keeping a typed trunk prefix. |

#### PHONE_COUNTRIES / flagOf

The built-in table of 49 countries with calling codes, patterns, trunk prefixes, and examples, and a helper that turns an ISO code into a flag emoji.

No props.

### Keyboard interactions

| Keys | Action |
| --- | --- |
| + (in the number) | Opens the picker with a calling code search. |
| ArrowDown / ArrowUp (on the country button) | Opens the picker. |
| Any letter (on the country button) | Opens the picker searching for that letter. |
| ArrowDown / ArrowUp / PageDown / PageUp | Moves through countries while searching. |
| Home / End | First or last country when the search is empty. |
| Enter | Picks the highlighted country and returns to the number. |
| Escape | Closes the picker and returns to the country button. |
| Backspace / Delete | Over a separator, deletes the digit beside it. |

### Accessibility

- The search is a combobox with aria-activedescendant over a listbox of options grouped into Suggested and All countries.
- The country button reads "Country, <name> +<code>"; picks, pasted country changes, and result counts are announced politely.
- The number input is type="tel" with autocomplete="tel"; errors are linked with aria-describedby and shown with role="alert" after blur.
- A valid number is announced as "Valid <country> number" while a check appears.

### Motion

- One surface springs its width, height, and corner radius from the country button into the list, and back when closing.
- The flag and code roll in the direction of the list when the country changes; the highlight glides between rows.
- Messages open on a height spring with a small rise and blur; the valid check pops in.
- Reduced motion jumps the surface to size and replaces rolls, blurs, and glides with short fades.

### Responsive behavior

- The open list is as wide as the field up to 340px, measured with a ResizeObserver, so it fits phones without covering the page.
- The number input uses inputMode="tel" for the phone keypad; hover styles apply only on fine pointers.

### Performance

- The country table is about 50 entries inline, with no network request; search filters it on each keystroke.
- The morph animates width and height on one element; keep one picker open at a time.

### Notes for AI

- Store the E.164 value; format it for display with formatPhoneNumber. details.valid tells you when the length matches the country.
- Validation checks length per country only; confirm ownership with an OTP step (otp-input) when it matters.
- Pasted or autofilled international numbers choose their own country, and +1 splits into Canada by area code.
- Restrict countries with countries and pin the likely ones with preferredCountries; the table ships inline with no metadata download.

### Related

- [Input](https://uiarc.dev/components/input/markdown): A single line field with clear labels and useful states.
- [OTP input](https://uiarc.dev/components/blocks/otp-input/markdown): A six digit verification flow with paste support and keyboard navigation.
- [Combobox](https://uiarc.dev/components/combobox/markdown): Search and select from a list without leaving the field.
- [Select](https://uiarc.dev/components/select/markdown): A compact choice field with a keyboard friendly menu.
- [Login and sign up: Sign up](https://uiarc.dev/components/blocks/login/markdown): An account creation flow with field validation, password strength, and a clear completion state.

### Also in special inputs

- [Number field](https://uiarc.dev/components/number-field/markdown): Enter a bounded number with clear increment controls.
- [Money input](https://uiarc.dev/components/money-input/markdown): A currency field with live grouping, stable width, rolling digits, and minor-unit output.
- [Scrub input](https://uiarc.dev/components/scrub-input/markdown): A Figma-style number field: drag the label to scrub, or type values, units, and arithmetic.
- [Tag input](https://uiarc.dev/components/tag-input/markdown): Turn short text values into removable tags.
- [Mention input](https://uiarc.dev/components/mention-input/markdown): A textarea with @people and #channel mentions that act as single tokens, with suggestions at the caret.
- [Shortcut recorder](https://uiarc.dev/components/shortcut-recorder/markdown): Record key combinations into key caps, with conflict warnings, Kbd, and a searchable cheatsheet.

### Guidance for AI tools

Phone input: A phone field with a country picker, formatting as you type, and E.164 output. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Scrub input

> A Figma-style number field: drag the label to scrub, or type values, units, and arithmetic.

- Type: Component (inputs)
- Access: Free, open source
- Page: https://uiarc.dev/components/scrub-input
- Markdown: https://uiarc.dev/components/scrub-input/markdown
- Registry item: https://uiarc.dev/r/scrub-input.json
- Source file: `registry/components/scrub-input/scrub-input.tsx`
- Dependencies: motion
- Keywords: inputs, new, react scrub input, drag to change number, scrubbable number field, inspector input, figma number input, math expression input, unit input

### When to use

- Position, size, rotation, and opacity fields in an inspector panel.
- Dense settings where typing exact values and dragging both matter.
- Values with units such as px, %, or deg that people type mixed.

### When not to use

- Use number-field for a normal form with stepper buttons and a visible label.
- Use slider when the range and position matter more than the exact number.
- Use money-input for currency amounts.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/scrub-input
pnpm dlx shadcn@latest add @uiarc/scrub-input
yarn dlx shadcn@latest add @uiarc/scrub-input
bunx --bun shadcn@latest add @uiarc/scrub-input
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/scrub-input.json
```

#### Manual

1. Install the dependencies:

```bash
npm install motion
```

2. Copy the source into your project. Main file: `registry/components/scrub-input/scrub-input.tsx`

   The source is in the registry item: https://uiarc.dev/r/scrub-input.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { useState } from "react";
import { ScrubInput } from "@/components/arc/scrub-input/scrub-input";

export function LayerInspector() {
  const [width, setWidth] = useState(240);
  const [opacity, setOpacity] = useState(100);
  return (
    <div style={{ display: "grid", gridTemplateColumns: "1fr 1fr", gap: 8 }}>
      <ScrubInput label="W" value={width} onValueChange={setWidth} min={0} units={["px", "%"]} resetValue={240} />
      <ScrubInput label="Opacity" value={opacity} onValueChange={setOpacity} min={0} max={100} unit="%" />
    </div>
  );
}
```

### Examples

#### Rotation that wraps

```tsx
<ScrubInput label="R" min={0} max={360} wrap unit="°" units={["°"]} fineStep={0.1} onValueCommit={value => setRotation(value)} />
```

### API reference

#### ScrubInput

A compact number field for inspectors: drag the label to scrub, or type values with arithmetic and units, with rubber-band limits.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` (required) | `ReactNode` | – | Text or a 16px icon. It is the scrub handle. Icon labels need aria-label. |
| `value` | `number` | – | Controlled value. |
| `defaultValue` | `number` | `0` | Starting value when uncontrolled. |
| `onValueChange` | `(value: number, details: ScrubInputChangeDetails) => void` | – | Fires for every change, including each scrub step. details is { source: "scrub" \| "type" \| "key" \| "reset", unit }. |
| `onValueCommit` | `(value: number, details: ScrubInputChangeDetails) => void` | – | Fires once when a change settles: a scrub ends, Enter or blur commits typing, or a key step lands. |
| `min` | `number` | `-Infinity` | Lower limit. |
| `max` | `number` | `Infinity` | Upper limit. |
| `step` | `number` | `1` | One step for arrows and scrubbing. |
| `fineStep` | `number` | `step / 10` | Step with Alt held. |
| `coarseStep` | `number` | `step * 10` | Step with Shift held. Coarse steps snap to the coarse grid. |
| `precision` | `number` | – | Decimal places kept. Defaults to the precision of step or fineStep. |
| `pixelsPerStep` | `number` | `2` | Pointer travel in px for one step while scrubbing. |
| `wrap` | `boolean` | `false` | Wraps from max to min, as rotation does. Needs both limits. |
| `unit` | `string` | – | Controlled unit shown after the number. With more than one entry in units it becomes a button that cycles them. |
| `defaultUnit` | `string` | – | Starting unit when uncontrolled. Defaults to unit or the first of units. |
| `units` | `readonly string[]` | – | Units a typed value may carry, such as ["px", "%"]. Defaults to the current unit. |
| `onUnitChange` | `(unit: string) => void` | – | Called when a typed unit or the unit button changes the unit. |
| `resetValue` | `number` | – | Double click the label to return here. |
| `track` | `boolean` | `true when min and max are set` | Shows where the value sits between min and max as a quiet fill. |
| `size` | `"sm" \| "md"` | `"md"` | Field height: 30px, or the small control height. |
| `pointerLock` | `boolean` | `true` | Locks the mouse pointer while scrubbing when the browser allows it. |
| `className` | `string` | – | Class on the root. |
| `...props` | `InputHTMLAttributes<HTMLInputElement>` | – | Forwarded to the input, except value, defaultValue, onChange, type, size, min, max, step, and prefix. |
| `ref` | `Ref<HTMLInputElement>` | – | The input element. |

#### evaluateScrubExpression

Evaluates + - * / and parentheses over numbers that may carry a unit. Returns { value, unit? }, or null for anything else or an unknown unit.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `text` (required) | `string` | – | The typed expression, such as "(100-24)/2" or "50%". Commas read as decimal points. |
| `units` (required) | `readonly string[]` | – | Allowed units. deg and ° are aliases. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| ArrowUp / ArrowDown | Steps the value; Shift steps ten times coarser, Alt ten times finer. |
| Enter | Commits typed text, including arithmetic such as 12*2. |
| Escape | Restores the last value while typing, or cancels a scrub back to where it started. |
| Shift / Alt (while scrubbing) | Switches to coarse or fine steps mid-drag and shows the multiplier. |

### Accessibility

- The input is role="spinbutton" with aria-valuenow, finite aria-valuemin and aria-valuemax, and aria-valuetext that spells out percent and degrees.
- The label is a real label for the input; clicking it focuses and selects the value.
- Invalid typed text sets aria-invalid for 900ms and keeps the previous value.
- The unit cycle button is labelled Unit: <unit>. Change unit.

### Motion

- Past min or max the field strains with rubber-band resistance, up to 12px, and springs back on release; the number leans with it.
- The track fill follows a drag one to one and glides to typed or stepped values.
- Invalid input and steps against a limit kick the field with a short shake; unit changes rise from a small blur.
- Reduced motion removes the strain, shake, and glide, and swaps the unit with a fade.

### Responsive behavior

- The field fills its column; set --scrub-input-width to size it.
- Touch scrubs through pointer capture on the label, with touch-action: pan-y so vertical page scroll still works; pointer lock is mouse only.
- With the pointer locked, a stand-in cursor portaled to the body wraps at the window edges so a long drag never runs out of screen.

### Performance

- Scrubbing writes motion values directly and emits only when the rounded value changes.
- One ResizeObserver per field tracks its width for the strain scale.

### Notes for AI

- Use in design tool inspectors, property panels, and editors where people tune values by feel.
- Save on onValueCommit, not onValueChange, which fires on every scrub step.
- Set min and max for bounded values to get the track fill; set wrap for angles.
- For a labelled form field with plus and minus buttons use number-field; for a range with a thumb use slider.

### Related

- [Number field](https://uiarc.dev/components/number-field/markdown): Enter a bounded number with clear increment controls.
- [Slider](https://uiarc.dev/components/slider/markdown): Pick a value or a range on a track that follows your finger.
- [Input](https://uiarc.dev/components/input/markdown): A single line field with clear labels and useful states.
- [Money input](https://uiarc.dev/components/money-input/markdown): A currency field with live grouping, stable width, rolling digits, and minor-unit output.
- [Color picker](https://uiarc.dev/components/color-picker/markdown): A swatch that grows into a picker with format morphing, eyedropper, saved swatches, and contrast readout.

### Also in special inputs

- [Phone input](https://uiarc.dev/components/phone-input/markdown): A phone field with a country picker, formatting as you type, and E.164 output.
- [Tag input](https://uiarc.dev/components/tag-input/markdown): Turn short text values into removable tags.
- [Mention input](https://uiarc.dev/components/mention-input/markdown): A textarea with @people and #channel mentions that act as single tokens, with suggestions at the caret.
- [Shortcut recorder](https://uiarc.dev/components/shortcut-recorder/markdown): Record key combinations into key caps, with conflict warnings, Kbd, and a searchable cheatsheet.

### Guidance for AI tools

Scrub input: A Figma-style number field: drag the label to scrub, or type values, units, and arithmetic. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Tag input

> Turn short text values into removable tags.

- Type: Component (inputs)
- Access: Free, open source
- Page: https://uiarc.dev/components/tag-input
- Markdown: https://uiarc.dev/components/tag-input/markdown
- Registry item: https://uiarc.dev/r/tag-input.json
- Source file: `registry/components/tag-input/tag-input.tsx`
- Dependencies: motion, lucide-react
- Keywords: field, tags, react tag input, tags input, chip input, multi value input, email chips input, keyword input

### When to use

- Free-form lists of short values like tags, keywords, or emails.
- Fields where people add values by pressing Enter or comma.

### When not to use

- Use multi-select or chip-group when values come from a fixed list.
- Use input for a single value.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/tag-input
pnpm dlx shadcn@latest add @uiarc/tag-input
yarn dlx shadcn@latest add @uiarc/tag-input
bunx --bun shadcn@latest add @uiarc/tag-input
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/tag-input.json
```

#### Manual

1. Install the dependencies:

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

2. Copy the source into your project. Main file: `registry/components/tag-input/tag-input.tsx`

   The source is in the registry item: https://uiarc.dev/r/tag-input.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { TagInput } from "@/components/arc/tag-input/tag-input";

export function TopicsField() {
  const [topics, setTopics] = useState(["design", "motion"]);
  return (
    <TagInput
      label="Topics"
      value={topics}
      onValueChange={setTopics}
      description="Press Enter or comma to add."
    />
  );
}
```

### API reference

#### TagInput

A field that turns typed text into removable tags, with keyboard picking and a gliding selection ring.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` (required) | `string` | – | Visible label tied to the text input. |
| `value` | `string[]` | – | Controlled tags. |
| `defaultValue` | `string[]` | `[]` | Initial tags when uncontrolled. |
| `onValueChange` | `(value: string[]) => void` | – | Called with the full list after each add or remove. |
| `placeholder` | `string` | `"Add a tag"` | Shown while there are no tags. |
| `description` | `string` | – | Helper copy under the field. |
| `id` | `string` | – | Input id. Generated when omitted. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Enter / , | Adds the typed text as a tag. Duplicates (case-insensitive) pulse the existing tag instead. |
| Backspace | At the start of the input, picks the last tag; pressed again, removes the picked tag. |
| Delete | Removes the picked tag. |
| ArrowLeft / ArrowRight | Moves the pick between tags and back to the input. |
| Escape | Clears the pick. |

### Accessibility

- Each tag has a remove button labelled "Remove <tag>".
- Adds, removals, picks, and duplicates are announced in a polite aria-live region.
- Blurring the input commits any typed draft as a tag.

### Motion

- New tags blur and scale in where the text was typed; removed tags leave and the rest glide on the morph spring. The shell follows wrapped rows on a smooth spring.
- A ring glides between picked tags. Reduced motion removes layout travel, scale, and blur, keeping fades.

### Responsive behavior

- Tags wrap onto new rows and the shell height follows on a spring, so the field never scrolls horizontally.
- The text input keeps an 80px minimum, dropping to its own row when the last row is full.

### Performance

- Every tag is a motion element with layout position animation; fine for dozens of tags, not hundreds.
- Two ResizeObservers track the content and message heights.

### Notes for AI

- Use for free-form values like tags, emails, or keywords. Use multi-select or chip-group when values come from a fixed list.
- Controlled or uncontrolled. Tags are plain strings; validate or normalize in onValueChange.

### Related

- [Multi-select](https://uiarc.dev/components/multi-select/markdown): Select several values while keeping the field readable.
- [Chip group](https://uiarc.dev/components/chip-group/markdown): Filter by a few facets with chips that morph as you pick them.
- [Input](https://uiarc.dev/components/input/markdown): A single line field with clear labels and useful states.

### Also in special inputs

- [Number field](https://uiarc.dev/components/number-field/markdown): Enter a bounded number with clear increment controls.
- [Money input](https://uiarc.dev/components/money-input/markdown): A currency field with live grouping, stable width, rolling digits, and minor-unit output.
- [Phone input](https://uiarc.dev/components/phone-input/markdown): A phone field with a country picker, formatting as you type, and E.164 output.
- [Scrub input](https://uiarc.dev/components/scrub-input/markdown): A Figma-style number field: drag the label to scrub, or type values, units, and arithmetic.
- [Mention input](https://uiarc.dev/components/mention-input/markdown): A textarea with @people and #channel mentions that act as single tokens, with suggestions at the caret.
- [Shortcut recorder](https://uiarc.dev/components/shortcut-recorder/markdown): Record key combinations into key caps, with conflict warnings, Kbd, and a searchable cheatsheet.

### Guidance for AI tools

Tag input: Turn short text values into removable tags. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Mention input

> A textarea with @people and #channel mentions that act as single tokens, with suggestions at the caret.

- Type: Component (inputs)
- Access: Free, open source
- Page: https://uiarc.dev/components/mention-input
- Markdown: https://uiarc.dev/components/mention-input/markdown
- Registry item: https://uiarc.dev/r/mention-input.json
- Source file: `registry/components/mention-input/mention-input.tsx`
- Dependencies: motion, lucide-react
- Keywords: inputs, new, react mention input, at mention textarea, mentions autocomplete, tag people in comment, channel mention, slack style mentions, mention suggestions, textarea with mentions

### When to use

- Comment and reply boxes where people are tagged with @ and should be notified by id.
- Chat or task composers that link #channels or projects inline.
- Any text field whose stored value needs structured references alongside the plain text.

### When not to use

- Use textarea for plain notes with no references.
- Use tag-input when the tokens are a separate list rather than part of a sentence.
- Use rich-text-editor when the text also needs headings, lists, or links.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/mention-input
pnpm dlx shadcn@latest add @uiarc/mention-input
yarn dlx shadcn@latest add @uiarc/mention-input
bunx --bun shadcn@latest add @uiarc/mention-input
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/mention-input.json
```

#### Manual

1. Install the dependencies:

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

2. Copy the source into your project. Main file: `registry/components/mention-input/mention-input.tsx`

   The source is in the registry item: https://uiarc.dev/r/mention-input.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { useState } from "react";
import { MentionInput, serializeMentions, type MentionValue } from "@/components/arc/mention-input/mention-input";

const people = [
  { id: "u1", name: "Maya Chen", role: "Design lead" },
  { id: "u2", name: "Theo Park", role: "Engineer" },
];
const channels = [{ id: "c1", name: "launch", description: "Release planning", members: 14 }];

export function CommentBox({ onPost }: { onPost: (body: string) => void }) {
  const [value, setValue] = useState<MentionValue>({ text: "", mentions: [] });
  return (
    <MentionInput
      aria-label="Comment"
      placeholder="Write a comment, @ to mention"
      people={people}
      channels={channels}
      value={value}
      onChange={setValue}
      submitOnEnter
      onSubmit={next => {
        onPost(serializeMentions(next));
        setValue({ text: "", mentions: [] });
      }}
    />
  );
}
```

### API reference

#### MentionInput

An autosizing textarea with @ people and # channel mentions. Mentions are atomic tokens, and the value carries plain text plus a structured mentions array with offsets.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `MentionValue` | – | Controlled value: { text, mentions }. Each mention has kind, id, label, start, and end offsets into text. |
| `defaultValue` | `MentionValue` | – | Initial value when uncontrolled. Defaults to empty text and no mentions. |
| `onChange` | `(value: MentionValue) => void` | – | Called on every edit with the new text and the mentions moved or dropped to match it. |
| `people` | `MentionPerson[]` | – | People offered after @. Each has id, name, and optional role and avatar. Leave it out to turn person mentions off. |
| `channels` | `MentionChannel[]` | – | Channels offered after #. Each has id, name, and optional description and members count. Leave it out to turn channel mentions off. |
| `onMentionAdd` | `(mention: Mention) => void` | – | Called when a suggestion is chosen and becomes a mention. |
| `onSubmit` | `(value: MentionValue) => void` | – | Called on Enter when submitOnEnter is set and the text is not blank. |
| `submitOnEnter` | `boolean` | `false` | Enter submits and Shift+Enter adds a line. Enter during IME composition never submits. |
| `placeholder` | `string` | – | Placeholder text for the empty field. |
| `minRows` | `number` | `1` | Starting height in rows. |
| `maxRows` | `number` | `8` | The field grows to this many rows, then scrolls. |
| `placement` | `"auto" \| "top" \| "bottom"` | `"auto"` | Where suggestions open. auto flips above the caret when there is less than 300px below it and more room above. |
| `maxSuggestions` | `number` | `6` | Most suggestions shown at once, best matches first. |
| `disabled` | `boolean` | – | Disables the textarea and dims the field. |
| `name` | `string` | – | Forwarded to the textarea. The form value is the plain text; use serializeMentions to keep ids. |
| `id` | `string` | – | Forwarded to the textarea, for an external label. |
| `aria-label` | `string` | – | Accessible name when there is no visible label. |
| `aria-describedby` | `string` | – | Id of help or error text for the textarea. |
| `className` | `string` | – | Extra class on the root. |

#### MentionInputHandle

Methods on the ref.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `focus` | `() => void` | – | Focuses the textarea. |
| `insert` | `(text: string) => void` | – | Inserts text at the caret as if typed, so it joins the native undo stack. |
| `openSuggestions` | `(kind: MentionKind) => void` | – | Types @ or # at the caret so suggestions open, adding a space first when needed. Useful for a mention button. |
| `clear` | `() => void` | – | Empties the text and mentions. |
| `textarea` | `HTMLTextAreaElement \| null` | – | The underlying textarea. |

#### serializeMentions

Turns a value into storage friendly text, <@id> for people and <#id> for channels by default.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` (required) | `MentionValue` | – | The value to serialize. |
| `format` | `(mention: Mention) => string` | – | Custom token for each mention, such as a markdown link. |

#### mentionText

Returns the visible text of a mention, @label or #label.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `kind` (required) | `MentionKind` | – | "person" or "channel". |
| `label` (required) | `string` | – | The mention label. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| @ / # | Opens people or channel suggestions after a space, line start, or opening bracket or quote. |
| Arrow Down / Arrow Up | Moves through suggestions, wrapping at the ends. |
| Enter / Tab | Turns the highlighted suggestion into a mention. |
| Escape | Dismisses suggestions for the current trigger without leaving the field. |
| Backspace / Delete | Next to a mention, one press removes the whole token. |
| Arrow Left / Arrow Right | Steps over a mention as one unit. |
| Enter / Shift+Enter | With submitOnEnter, Enter submits and Shift+Enter adds a line. |

### Accessibility

- The textarea is a combobox with aria-autocomplete="list", aria-expanded, aria-controls, and aria-activedescendant pointing at the highlighted option.
- Suggestions are a listbox labelled People or Channels, with options marked aria-selected.
- A polite live region announces the result count, such as 3 people or No matches.
- Mention tints come from an aria-hidden mirror behind a transparent textarea, so assistive tech reads the plain text.
- Choosing a suggestion types through execCommand insertText, so native undo keeps working.

### Motion

- The field height springs to its content between minRows and maxRows.
- Suggestions pop in from the caret with a small scale and a snappy spring; the highlight glides between rows and the panel height springs as results change.
- Reduced motion jumps the height and highlight and fades the panel without scale or offset.

### Responsive behavior

- Fills its container width. The suggestion panel is 272px wide, capped to the field width, and clamped so it never runs past the right edge.
- With placement auto the panel flips above the caret near the bottom of the viewport, which suits composers pinned to the bottom of a mobile screen.
- Options use pointer events and click, so touch taps choose a suggestion without a hover state.

### Performance

- Each edit rebuilds a mirror of the text to draw token tints and reconciles mention offsets with a prefix and suffix diff; fine for messages, not for pages of text.
- Two ResizeObservers drive the field and panel height springs; ranking runs over the full people and channels arrays each keystroke, so pass a pre-filtered list past a few thousand entries.

### Notes for AI

- Choose it for comment boxes, message composers, and task descriptions that tag people or channels. Use textarea for plain multi-line text and tag-input for a list of chips outside the text.
- Store serializeMentions(value) or the mentions array, not only value.text, so renamed people still resolve by id.
- Filter people on the server by passing a fresh people array per keystroke; ranking is prefix, then word start, then substring, then role or description.
- Hook a toolbar @ button to ref.openSuggestions("person").

### Related

- [Textarea](https://uiarc.dev/components/textarea/markdown): A multiline field for notes, descriptions, and longer text.
- [Tag input](https://uiarc.dev/components/tag-input/markdown): Turn short text values into removable tags.
- [Combobox](https://uiarc.dev/components/combobox/markdown): Search and select from a list without leaving the field.
- [Chat thread](https://uiarc.dev/components/chat-thread/markdown): A chat thread with grouped messages, reactions, read receipts, typing, and a composer with attachments.
- [Rich text editor](https://uiarc.dev/components/rich-text-editor/markdown): A lightweight editor with markdown shortcuts, a floating toolbar, a slash menu, and HTML and markdown output.

### Also in special inputs

- [Number field](https://uiarc.dev/components/number-field/markdown): Enter a bounded number with clear increment controls.
- [Money input](https://uiarc.dev/components/money-input/markdown): A currency field with live grouping, stable width, rolling digits, and minor-unit output.
- [Phone input](https://uiarc.dev/components/phone-input/markdown): A phone field with a country picker, formatting as you type, and E.164 output.
- [Scrub input](https://uiarc.dev/components/scrub-input/markdown): A Figma-style number field: drag the label to scrub, or type values, units, and arithmetic.
- [Shortcut recorder](https://uiarc.dev/components/shortcut-recorder/markdown): Record key combinations into key caps, with conflict warnings, Kbd, and a searchable cheatsheet.

### Guidance for AI tools

Mention input: A textarea with @people and #channel mentions that act as single tokens, with suggestions at the caret. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Shortcut recorder

> Record key combinations into key caps, with conflict warnings, Kbd, and a searchable cheatsheet.

- Type: Component (inputs)
- Access: Free, open source
- Page: https://uiarc.dev/components/shortcut-recorder
- Markdown: https://uiarc.dev/components/shortcut-recorder/markdown
- Registry item: https://uiarc.dev/r/shortcut-recorder.json
- Source file: `registry/components/shortcut-recorder/shortcut-recorder.tsx`
- Dependencies: motion, lucide-react
- Keywords: inputs, new, react shortcut recorder, keyboard shortcut input, hotkey recorder, keybinding editor, kbd component, keyboard shortcuts cheatsheet, record hotkey

### When to use

- Settings pages where people remap keyboard shortcuts.
- A keyboard shortcut cheatsheet or help dialog, with ShortcutList.
- Inline key hints in menus, tooltips, and docs, with ShortcutKbd or ShortcutKeys.

### When not to use

- Use ShortcutKbd alone when shortcuts are fixed and only need to be shown.
- Use command-palette to let people run actions by name rather than bind keys.
- Avoid it on touch-only products where no hardware keyboard is expected.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/shortcut-recorder
pnpm dlx shadcn@latest add @uiarc/shortcut-recorder
yarn dlx shadcn@latest add @uiarc/shortcut-recorder
bunx --bun shadcn@latest add @uiarc/shortcut-recorder
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/shortcut-recorder.json
```

#### Manual

1. Install the dependencies:

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

2. Copy the source into your project. Main file: `registry/components/shortcut-recorder/shortcut-recorder.tsx`

   The source is in the registry item: https://uiarc.dev/r/shortcut-recorder.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { useEffect, useState } from "react";
import { ShortcutRecorder, matchesShortcut, usePlatform } from "@/components/arc/shortcut-recorder/shortcut-recorder";

export function SearchShortcut() {
  const platform = usePlatform();
  const [shortcut, setShortcut] = useState<string | null>("mod+k");

  useEffect(() => {
    if (!shortcut) return;
    const onKey = (event: KeyboardEvent) => {
      if (matchesShortcut(event, shortcut, platform)) { event.preventDefault(); openSearch(); }
    };
    window.addEventListener("keydown", onKey);
    return () => window.removeEventListener("keydown", onKey);
  }, [platform, shortcut]);

  return (
    <ShortcutRecorder
      label="Open search"
      value={shortcut}
      onValueChange={setShortcut}
      resetValue="mod+k"
      bindings={[{ shortcut: "mod+p", label: "Print" }]}
    />
  );
}
```

### API reference

#### ShortcutRecorder

A field that records a keyboard shortcut, lights held keys as caps, and asks before taking a combination already in use.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` (required) | `string` | – | Field label. |
| `hideLabel` | `boolean` | `false` | Keeps the label for screen readers only. |
| `value` | `string \| null` | – | Controlled shortcut, such as "mod+shift+k". mod is Command on Apple platforms and Ctrl elsewhere. |
| `defaultValue` | `string \| null` | `null` | Starting shortcut when uncontrolled. |
| `onValueChange` | `(value: string \| null, details: { replaced?: ShortcutBinding }) => void` | – | Called with the new shortcut; replaced is the binding it was taken from after Use anyway. |
| `resetValue` | `string \| null` | – | What the reset button restores. Defaults to defaultValue. |
| `bindings` | `ShortcutBinding[]` | `[]` | Shortcuts already in use: { shortcut, label }. Recording one asks before taking it. |
| `warnReserved` | `boolean` | `true` | Also warn about combinations the browser or system keeps, such as ⌘W and ⌘C. |
| `requireModifier` | `boolean` | `true` | Require ⌘, Ctrl, or ⌥. Function keys are always allowed. |
| `platform` | `"mac" \| "other"` | – | Overrides the detected platform. |
| `placeholder` | `string` | `"Record shortcut"` | Shown when there is no shortcut. |
| `description` | `string` | – | Hint under the field. |
| `disabled` | `boolean` | `false` | Disables recording. |
| `id` | `string` | – | Id of the recorder button. |
| `className` | `string` | – | Class on the root. |

#### ShortcutList

A searchable, grouped shortcut cheatsheet. Holding a modifier lights its caps and fades rows that do not use it.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `groups` (required) | `ShortcutListGroup[]` | – | Groups: { label, items: { label, shortcut, keywords? }[] }. |
| `label` | `string` | `"Keyboard shortcuts"` | Accessible name of the list. |
| `searchable` | `boolean` | `true` | Shows the search field. |
| `searchPlaceholder` | `string` | `"Search shortcuts"` | Search placeholder and label. |
| `highlightPressed` | `boolean` | `true` | Light caps as keys are held and fade rows that do not use the held modifiers. |
| `platform` | `"mac" \| "other"` | – | Overrides the detected platform. |
| `className` | `string` | – | Class on the root. |

#### ShortcutKeys

A shortcut drawn as key caps in platform order, with a spoken label.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `shortcut` (required) | `string` | – | Such as "mod+k". |
| `platform` | `"mac" \| "other"` | – | Overrides the detected platform. |
| `pressed` | `ReadonlySet<string>` | – | Held key ids from usePressedKeys; matching caps light up. |
| `size` | `"sm" \| "md"` | `"md"` | Cap size. |
| `className` | `string` | – | Class on the wrapper. |

#### ShortcutKbd

A single key cap for inline copy and menus. Also exported as Kbd, a deprecated alias.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` (required) | `ReactNode` | – | The key label. |
| `pressed` | `boolean` | `false` | Draws the key pushed down and lit. |
| `size` | `"sm" \| "md"` | `"md"` | Cap size. |
| `...props` | `HTMLAttributes<HTMLElement>` | – | Forwarded to the kbd element. |

#### matchesShortcut / formatShortcut / usePlatform / usePressedKeys

Helpers: test a keydown against a stored shortcut, format it as "⌘⇧K" or "Ctrl+Shift+K" with a spoken form, read the platform, and track held keys.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `event, shortcut, platform` (required) | `KeyboardEvent, string, Platform` | – | matchesShortcut returns true when the keydown is this shortcut. |
| `shortcut, platform` (required) | `string, Platform` | – | formatShortcut returns { text, spoken }. |
| `override` | `Platform` | – | usePlatform(override?) returns "mac" or "other"; the server assumes mac. |
| `enabled` | `boolean` | `true` | usePressedKeys(enabled?) returns the set of held key ids. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Enter / Space | Starts recording. |
| Any combination (while recording) | Records it; held modifiers show as caps as you build the chord. |
| Escape (while recording) | Cancels recording. |
| Backspace / Delete | Clears the shortcut, while recording or while the field has focus. |
| Tab (while recording) | Stops recording and moves on without recording Tab. |
| Escape (in list search) | Clears the ShortcutList search. |

### Accessibility

- The recorder is a button with aria-pressed while recording, named by the label plus the spoken shortcut, such as "Command Shift K".
- Recording, results, conflicts, and clears are announced through a polite live region; the message row is linked with aria-describedby.
- Key caps are aria-hidden inside the recorder; ShortcutKeys uses role="img" with a spoken aria-label.
- Conflicts offer Use anyway and Cancel as real buttons, and focus returns to the recorder after either.

### Motion

- Caps pop in with a small scale and blur, staggered when a finished shortcut settles, and slide on a snappy layout spring as the chord changes.
- A recording dot pulses; the message row opens on a height spring.
- In ShortcutList, groups and rows collapse on a height spring as search filters them.
- Reduced motion removes the scale, stagger, layout slide, and height springs; caps and messages fade.

### Responsive behavior

- ShortcutList is a container with a query at 520px that puts groups in two columns; below that they stack.
- The recorder keeps a fixed height and caps wrap within it; hover styles apply only on fine pointers.

### Performance

- usePressedKeys adds window keydown and keyup listeners only while enabled; turn off highlightPressed for lists that do not need it.
- ShortcutList filters on every keystroke by building token strings per row; it suits lists of a few hundred shortcuts.

### Notes for AI

- Store shortcuts as normalized strings with mod ("mod+shift+k"); they read as ⌘ on Mac and Ctrl elsewhere without a second binding.
- Run bound actions with matchesShortcut in a keydown listener; it compares physical keys, so ⌥K matches "alt+k" rather than "˚".
- Pass every existing binding in bindings, and use details.replaced from onValueChange to unbind the old owner after Use anyway.
- Use ShortcutList for a help sheet and ShortcutKbd for inline hints such as in menus or command-palette rows.

### Related

- [Command palette](https://uiarc.dev/components/blocks/command-palette/markdown): A complete keyboard driven action surface with search, grouped results, and shortcuts.
- [Input](https://uiarc.dev/components/input/markdown): A single line field with clear labels and useful states.
- [Tooltip](https://uiarc.dev/components/tooltip/markdown): Short supporting text for unfamiliar controls.
- [Dropdown menu](https://uiarc.dev/components/dropdown-menu/markdown): A focused list of actions anchored to a trigger.
- [Settings page](https://uiarc.dev/components/blocks/settings-page/markdown): Account settings with a gliding section nav and a save bar that morphs in as you edit.

### Also in special inputs

- [Number field](https://uiarc.dev/components/number-field/markdown): Enter a bounded number with clear increment controls.
- [Money input](https://uiarc.dev/components/money-input/markdown): A currency field with live grouping, stable width, rolling digits, and minor-unit output.
- [Phone input](https://uiarc.dev/components/phone-input/markdown): A phone field with a country picker, formatting as you type, and E.164 output.
- [Scrub input](https://uiarc.dev/components/scrub-input/markdown): A Figma-style number field: drag the label to scrub, or type values, units, and arithmetic.
- [Tag input](https://uiarc.dev/components/tag-input/markdown): Turn short text values into removable tags.
- [Mention input](https://uiarc.dev/components/mention-input/markdown): A textarea with @people and #channel mentions that act as single tokens, with suggestions at the caret.

### Guidance for AI tools

Shortcut recorder: Record key combinations into key caps, with conflict warnings, Kbd, and a searchable cheatsheet. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Select

> A compact choice field with a keyboard friendly menu.

- Type: Component (inputs)
- Access: Free, open source
- Page: https://uiarc.dev/components/select
- Markdown: https://uiarc.dev/components/select/markdown
- Registry item: https://uiarc.dev/r/select.json
- Source file: `registry/components/select/select.tsx`
- Dependencies: @radix-ui/react-select, motion, lucide-react
- Keywords: field, form, react select, dropdown select, radix select, animated select, select menu, form select field

### When to use

- A short fixed list where typing is not needed, such as region or sort order.
- Form fields that should submit natively through Radix's hidden select via name.

### When not to use

- Use combobox for long or searchable lists.
- Use multi-select when several values can be chosen.
- Use segmented-control for two to four choices that should stay visible.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/select
pnpm dlx shadcn@latest add @uiarc/select
yarn dlx shadcn@latest add @uiarc/select
bunx --bun shadcn@latest add @uiarc/select
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/select.json
```

#### Manual

1. Install the dependencies:

```bash
npm install @radix-ui/react-select motion lucide-react
```

2. Copy the source into your project. Main file: `registry/components/select/select.tsx`

   The source is in the registry item: https://uiarc.dev/r/select.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { Select } from "@/components/arc/select/select";

export function RegionSelect() {
  const [region, setRegion] = useState("eu");
  return (
    <Select
      label="Region"
      value={region}
      onValueChange={setRegion}
      options={[
        { value: "us", label: "United States" },
        { value: "eu", label: "Europe" },
        { value: "ap", label: "Asia Pacific", disabled: true },
      ]}
    />
  );
}
```

### API reference

#### Select

A labelled Radix select whose shown value rolls in the direction of the list.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` (required) | `string` | – | Visible label for the trigger. |
| `options` (required) | `{ value: string; label: string; disabled?: boolean }[]` | – | Items in list order. |
| `placeholder` | `string` | `"Select an option"` | Shown when no value is selected. |
| `description` | `string` | – | Helper copy under the trigger, linked through aria-describedby. |
| `id` | `string` | – | Trigger id. Generated when omitted. |
| `className` | `string` | – | Added to the trigger. |
| `...props` | `Omit<SelectPrimitive.SelectProps, "children">` | – | Radix Select root props: value, defaultValue, onValueChange, open, onOpenChange, name, required, disabled. ref goes to the trigger button. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Enter / Space / ArrowDown | Opens the list from the trigger. |
| ArrowUp / ArrowDown | Moves between enabled items. |
| Enter / Space | Selects the highlighted item and closes. |
| Escape | Closes without changing the value. |
| Type a letter | Jumps to the next item starting with it (Radix typeahead). |

### Accessibility

- Built on Radix Select, so the trigger, listbox, and options get the right roles and focus handling.
- The real value renders in a visually hidden Radix Value; the animated copy is aria-hidden.
- Label is linked with htmlFor, and description through aria-describedby.

### Motion

- A later option rises in from below and an earlier one drops from above, with a soft blur.
- Reduced motion swaps the value with an instant crossfade.

### Responsive behavior

- The menu matches the trigger width, caps at min(24rem, 100vw minus 20px), and at 320px or the available height, then scrolls.
- Long labels ellipsize in the trigger instead of widening it.
- The trigger never scales on press, so Radix measures a stable anchor on touch.

### Performance

- The menu renders in a Radix portal only while open; items are not virtualized, so keep the list short.
- The translucent menu drops its backdrop blur under prefers-reduced-transparency.

### Notes for AI

- Pick for a short fixed list where typing is not needed. Use combobox for long or searchable lists, multi-select for several values, and segmented-control for two to four visible choices.
- Controlled with value and onValueChange, or uncontrolled with defaultValue; pass name to submit with a form.

### Related

- [Combobox](https://uiarc.dev/components/combobox/markdown): Search and select from a list without leaving the field.
- [Multi-select](https://uiarc.dev/components/multi-select/markdown): Select several values while keeping the field readable.
- [Segmented control](https://uiarc.dev/components/segmented-control/markdown): Switch between a small set of related views.
- [Radio group](https://uiarc.dev/components/radio-group/markdown): Choose one option from a visible set.

### Also in selects

- [Morph select](https://uiarc.dev/components/morph-select/markdown): A select whose trigger grows into the list, with a gliding highlight and type-ahead.
- [Chip group](https://uiarc.dev/components/chip-group/markdown): Filter by a few facets with chips that morph as you pick them.

### Guidance for AI tools

Select: A compact choice field with a keyboard friendly menu. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Combobox

> Search and select from a list without leaving the field.

- Type: Component (inputs)
- Access: Free, open source
- Page: https://uiarc.dev/components/combobox
- Markdown: https://uiarc.dev/components/combobox/markdown
- Registry item: https://uiarc.dev/r/combobox.json
- Source file: `registry/components/combobox/combobox.tsx`
- Dependencies: motion, lucide-react
- Keywords: field, search, react combobox, autocomplete, searchable select, typeahead dropdown, filterable select, autocomplete input

### When to use

- Single-choice fields with long lists, such as time zones or countries.
- Lists where people know the name and want to type, including aliases via keywords.

### When not to use

- Use select for a short list where typing adds nothing.
- Use multi-select when several values can be chosen.
- Use expanding-search when the search navigates instead of setting a value.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/combobox
pnpm dlx shadcn@latest add @uiarc/combobox
yarn dlx shadcn@latest add @uiarc/combobox
bunx --bun shadcn@latest add @uiarc/combobox
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/combobox.json
```

#### Manual

1. Install the dependencies:

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

2. Copy the source into your project. Main file: `registry/components/combobox/combobox.tsx`

   The source is in the registry item: https://uiarc.dev/r/combobox.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { Combobox } from "@/components/arc/combobox/combobox";

const timezones = [
  { value: "utc", label: "UTC" },
  { value: "cet", label: "Central European", keywords: ["zurich", "berlin"] },
  { value: "pst", label: "Pacific", keywords: ["san francisco"] },
];

export function TimezoneField() {
  const [zone, setZone] = useState("");
  return <Combobox label="Time zone" options={timezones} value={zone} onValueChange={setZone} />;
}
```

### API reference

#### Combobox

A searchable single-select field: type to filter, pick from a listbox that follows its height on a spring.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` (required) | `string` | – | Visible label, also used to name the listbox. |
| `options` (required) | `ComboboxOption[]` | – | { value, label, disabled?, keywords? }. Keywords also match the query. |
| `value` | `string` | – | Controlled selected value. Empty string means none. |
| `defaultValue` | `string` | `""` | Initial value when uncontrolled. |
| `onValueChange` | `(value: string) => void` | – | Called with the new value, or an empty string when cleared. |
| `description` | `string` | – | Helper copy under the field, linked through aria-describedby. |
| `placeholder` | `string` | `"Search or select…"` | Shown when nothing is selected. While searching, the chosen label shows here instead. |
| `emptyMessage` | `string` | `"No matches found"` | Shown in a status row when the filter matches nothing. |
| `className` | `string` | – | Added to the control wrapper. |
| `...props` | `Omit<InputHTMLAttributes<HTMLInputElement>, "value" \| "defaultValue" \| "onChange" \| "placeholder">` | – | Forwarded to the input, including ref, id, name, disabled, and onFocus. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| ArrowDown / ArrowUp | Opens the list, then moves through enabled options, wrapping at the ends. |
| Enter | Selects the active option. |
| Escape | Closes the list and discards the query. |

### Accessibility

- Input has role="combobox" with aria-expanded, aria-controls, aria-autocomplete="list", and aria-activedescendant.
- Options use role="option" with aria-selected and aria-disabled; the list is labelled "<label> options".
- The empty state is a role="status" row; the clear button is labelled "Clear selection".

### Motion

- The popover springs in from slightly above and the listbox height follows filtering on a smooth spring.
- A chosen label rises into the field with a soft blur; the clear button scales in.
- Reduced motion keeps opacity-only fades and instant height changes.

### Responsive behavior

- The popover spans the field width and the listbox caps at min(300px, 40vh), scrolling with contained overscroll.
- It closes on any pointerdown outside, so a tap elsewhere dismisses it on touch.

### Performance

- Filtering is memoized and runs on every keystroke across all options; results are not virtualized, so pre-filter very large lists.
- A ResizeObserver drives the listbox height spring while filtering.

### Notes for AI

- Use for long or searchable single-choice lists. Use select for short lists, multi-select for several values, and expanding-search for search that navigates.
- Controlled with value and onValueChange, or uncontrolled with defaultValue. The input shows the label, not the value, so pair name with a hidden input if you post a form.
- Add keywords to options for synonyms and aliases.

### Related

- [Select](https://uiarc.dev/components/select/markdown): A compact choice field with a keyboard friendly menu.
- [Multi-select](https://uiarc.dev/components/multi-select/markdown): Select several values while keeping the field readable.
- [Expanding search](https://uiarc.dev/components/expanding-search/markdown): An icon that morphs into a search field with results beneath it.
- [Search field](https://uiarc.dev/components/search-field/markdown): A recognizable search entry point with clear affordances.

### Also in selects

- [Morph select](https://uiarc.dev/components/morph-select/markdown): A select whose trigger grows into the list, with a gliding highlight and type-ahead.
- [Chip group](https://uiarc.dev/components/chip-group/markdown): Filter by a few facets with chips that morph as you pick them.

### Guidance for AI tools

Combobox: Search and select from a list without leaving the field. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Multi-select

> Select several values while keeping the field readable.

- Type: Component (inputs)
- Access: Free, open source
- Page: https://uiarc.dev/components/multi-select
- Markdown: https://uiarc.dev/components/multi-select/markdown
- Registry item: https://uiarc.dev/r/multi-select.json
- Source file: `registry/components/multi-select/multi-select.tsx`
- Dependencies: motion, lucide-react
- Keywords: field, choice, react multi select, multiselect dropdown, select multiple options, multi select chips, tag select, checkbox dropdown

### When to use

- Picking several values from a fixed list in a compact field, such as labels or assignees.
- Filters where the chosen values should show in the field with a +N overflow.

### When not to use

- Use chip-group when every option should stay visible.
- Use tag-input for free-form values.
- Use select for a single value.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/multi-select
pnpm dlx shadcn@latest add @uiarc/multi-select
yarn dlx shadcn@latest add @uiarc/multi-select
bunx --bun shadcn@latest add @uiarc/multi-select
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/multi-select.json
```

#### Manual

1. Install the dependencies:

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

2. Copy the source into your project. Main file: `registry/components/multi-select/multi-select.tsx`

   The source is in the registry item: https://uiarc.dev/r/multi-select.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { MultiSelect } from "@/components/arc/multi-select/multi-select";

export function LabelPicker() {
  const [labels, setLabels] = useState<string[]>(["bug"]);
  return (
    <MultiSelect
      label="Labels"
      value={labels}
      onValueChange={setLabels}
      options={[
        { value: "bug", label: "Bug" },
        { value: "feature", label: "Feature" },
        { value: "docs", label: "Docs" },
      ]}
    />
  );
}
```

### API reference

#### MultiSelect

A dropdown that picks several values, showing them as chips with a rolling +N overflow count.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` (required) | `string` | – | Visible label, also names the listbox. |
| `options` (required) | `MultiSelectOption[]` | – | { value, label, disabled? } in list order. |
| `value` | `string[]` | – | Controlled selected values. |
| `defaultValue` | `string[]` | `[]` | Initial values when uncontrolled. |
| `onValueChange` | `(value: string[]) => void` | – | Called with the full new selection. |
| `placeholder` | `string` | `"Select options"` | Shown when nothing is selected. |
| `description` | `string` | – | Helper copy under the field. |
| `maxVisible` | `number` | `2` | Chips shown in the trigger before the rest collapse into +N. |
| `disabled` | `boolean` | `false` | Disables the trigger and hides the clear button. |
| `className` | `string` | – | Added to the root. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Enter / Space | Opens or closes the list; Enter toggles the active option while open. |
| ArrowDown / ArrowUp | Opens the list and moves through enabled options, wrapping. |
| Escape | Closes the list. |

### Accessibility

- Trigger has aria-haspopup="listbox", aria-expanded, and aria-labelledby combining the label and a hidden list of selected labels.
- The menu is role="listbox" with aria-multiselectable; options carry aria-selected and aria-disabled.
- Clear button is labelled "Clear selections"; chips are aria-hidden in favor of the spoken summary.

### Motion

- Chips open their slot width on a smooth spring and grow in from 0.9 with a blur; the +N count rolls up or down.
- Checks draw in the menu; the menu springs in from slightly above.
- Reduced motion turns every change into a short crossfade with no scale or width travel.

### Responsive behavior

- Chips cap at 9rem and ellipsize, and maxVisible limits how many show before +N, so the trigger holds one line.
- The menu spans the field width and has no max height or scroll, so keep option lists short on small screens.

### Performance

- Options are not virtualized and the menu does not scroll; for long lists use combobox instead.
- Chips animate slot width and scale per change; fine for a few selections.

### Notes for AI

- Use for picking several values from a fixed list in a compact field. Use chip-group when all options should stay visible and tag-input for free-form values.
- Controlled with value and onValueChange or uncontrolled with defaultValue. There is no name prop, so serialize the array yourself for forms.

### Related

- [Select](https://uiarc.dev/components/select/markdown): A compact choice field with a keyboard friendly menu.
- [Combobox](https://uiarc.dev/components/combobox/markdown): Search and select from a list without leaving the field.
- [Chip group](https://uiarc.dev/components/chip-group/markdown): Filter by a few facets with chips that morph as you pick them.
- [Tag input](https://uiarc.dev/components/tag-input/markdown): Turn short text values into removable tags.

### Also in selects

- [Morph select](https://uiarc.dev/components/morph-select/markdown): A select whose trigger grows into the list, with a gliding highlight and type-ahead.

### Guidance for AI tools

Multi-select: Select several values while keeping the field readable. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Morph select

> A select whose trigger grows into the list, with a gliding highlight and type-ahead.

- Type: Component (inputs)
- Access: Free, open source
- Page: https://uiarc.dev/components/morph-select
- Markdown: https://uiarc.dev/components/morph-select/markdown
- Registry item: https://uiarc.dev/r/morph-select.json
- Source file: `registry/components/morph-select/morph-select.tsx`
- Dependencies: motion, lucide-react
- Keywords: inputs, new, react select, animated select, morphing dropdown, listbox, select with search, grouped select, custom select component, type-ahead select

### When to use

- Form fields and property panels where one value is picked from a known list.
- Grouped lists like time zones, assignees, or projects, with optional icons and meta.
- Compact toolbars where the picker should look like a pill until opened.

### When not to use

- Use combobox when users type free text or the list is very long and remote.
- Use multi-select when more than one value can be chosen.
- Use dropdown-menu for actions rather than a stored value.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/morph-select
pnpm dlx shadcn@latest add @uiarc/morph-select
yarn dlx shadcn@latest add @uiarc/morph-select
bunx --bun shadcn@latest add @uiarc/morph-select
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/morph-select.json
```

#### Manual

1. Install the dependencies:

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

2. Copy the source into your project. Main file: `registry/components/morph-select/morph-select.tsx`

   The source is in the registry item: https://uiarc.dev/r/morph-select.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { useState } from "react";
import { MorphSelect } from "@/components/arc/morph-select/morph-select";

export function TimezoneField() {
  const [zone, setZone] = useState<string | null>("europe/zurich");
  return (
    <MorphSelect
      label="Time zone"
      name="timezone"
      value={zone}
      onValueChange={setZone}
      items={[
        { label: "Europe", options: [
          { value: "europe/london", label: "London", meta: "UTC+0" },
          { value: "europe/zurich", label: "Zurich", meta: "UTC+1", keywords: "switzerland" },
        ] },
        { label: "Americas", options: [
          { value: "america/new_york", label: "New York", meta: "UTC−5" },
          { value: "america/los_angeles", label: "Los Angeles", meta: "UTC−8" },
        ] },
      ]}
    />
  );
}
```

### API reference

#### MorphSelect

A select whose trigger grows into the option list, with groups, type-ahead, optional search, and a label that flies back into the trigger.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` (required) | `string` | – | Visible label, also the accessible name of the trigger and the list. |
| `hideLabel` | `boolean` | `false` | Keeps the label for assistive technology only. |
| `items` (required) | `MorphSelectItem[]` | – | Options { value, label, icon?, meta?, keywords?, disabled? } or groups { label, options }, in display order. |
| `value` | `string \| null` | – | Controlled selected value. |
| `defaultValue` | `string \| null` | `null` | Uncontrolled starting value. |
| `onValueChange` | `(value: string, option: MorphSelectOption) => void` | – | Called with the new value and its option. |
| `placeholder` | `string` | `"Select"` | Trigger text with no selection. |
| `searchable` | `boolean \| "auto"` | `"auto"` | Shows a search field in place of the trigger when open. auto turns it on above eight options. |
| `searchPlaceholder` | `string` | – | Search field placeholder. Defaults to the selected label, then "Search". |
| `panelWidth` | `number` | `272` | Width of the open surface in px. Never narrower than the trigger. |
| `maxListHeight` | `number` | `296` | Tallest the option list gets before it scrolls, in px. |
| `align` | `"start" \| "end"` | `"start"` | Which edge of the trigger stays put while the surface grows. |
| `name` | `string` | – | Adds a hidden input for native form submission. |
| `disabled` | `boolean` | `false` | Disables the trigger. |
| `className` | `string` | – | Extra class on the root. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Enter / Space / ArrowDown / ArrowUp | Opens the list on the selected option; Enter or Space picks the active option when open. |
| ArrowDown / ArrowUp | Moves the active option, skipping disabled ones. |
| PageDown / PageUp | Moves eight options at a time. |
| Home / End | Moves to the first or last option; when closed, opens on it. |
| Alt + ArrowUp | Picks the active option and closes. |
| Printable characters | Type-ahead jumps to a matching label, or starts a search when search is on. |
| Escape | Closes and returns focus to the trigger. |
| Tab | Closes and moves focus on without picking. |

### Accessibility

- The trigger is a role="combobox" with aria-haspopup="listbox", aria-expanded, and aria-activedescendant pointing at the active option.
- With search on, the input takes over as the combobox with aria-autocomplete="list", and the trigger turns inert.
- Options are role="option" with aria-selected and aria-disabled; groups are role="group" labelled by their heading.
- A polite status announces the number of search results or No matches.

### Motion

- The trigger surface grows into the list on a physical spring with slight bounce and folds back without overshoot; the corner radius morphs with it.
- One highlight glides between options; the chosen label lifts out of the list and flies into the trigger while the trigger width springs.
- Values in the trigger roll up or down depending on whether the new option is later or earlier in the list.
- Reduced motion jumps the size, removes the fly and roll, and uses short fades.

### Responsive behavior

- The closed trigger sizes to its label up to min(20rem, 100vw - 2rem); the open list is max(trigger width, min(panelWidth, 100vw - 2rem)).
- Set align="end" for triggers near the right edge so the surface grows leftward.
- Hover highlight follows the mouse only; on touch a tap picks directly, and hover styles apply only on fine pointers.

### Performance

- A hidden measuring copy and a ResizeObserver size the trigger and list; the surface animates width, height, and radius through motion values.
- All options render; there is no virtualization, so keep lists to a few hundred items.
- Search filters in memory on label, meta, and keywords.

### Notes for AI

- Use for compact property pickers and form fields with up to a few hundred options, including avatars or icons.
- Add keywords to options so search matches synonyms; meta shows trailing detail like counts or offsets.
- Pass name to submit with a native form; the hidden input carries the value.
- Use combobox when people mostly type free text, and multi-select for several values.

### Related

- [Select](https://uiarc.dev/components/select/markdown): A compact choice field with a keyboard friendly menu.
- [Combobox](https://uiarc.dev/components/combobox/markdown): Search and select from a list without leaving the field.
- [Multi-select](https://uiarc.dev/components/multi-select/markdown): Select several values while keeping the field readable.
- [Dropdown menu](https://uiarc.dev/components/dropdown-menu/markdown): A focused list of actions anchored to a trigger.

### Also in selects

- [Chip group](https://uiarc.dev/components/chip-group/markdown): Filter by a few facets with chips that morph as you pick them.

### Guidance for AI tools

Morph select: A select whose trigger grows into the list, with a gliding highlight and type-ahead. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Chip group

> Filter by a few facets with chips that morph as you pick them.

- Type: Component (inputs)
- Access: Free, open source
- Page: https://uiarc.dev/components/chip-group
- Markdown: https://uiarc.dev/components/chip-group/markdown
- Registry item: https://uiarc.dev/r/chip-group.json
- Source file: `registry/components/chip-group/chip-group.tsx`
- Dependencies: motion, lucide-react
- Keywords: chips, filter, toggle, react chip group, filter chips, toggle chips, tag filter, selectable chips, chip select

### When to use

- Facet filters people toggle often, like topics or categories.
- Single clearable choices shown as chips, via multiple={false}.
- Long option sets folded behind a +N more chip with maxVisible.

### When not to use

- Use multi-select when space is tight.
- Use checkbox in forms.
- Use segmented-control for one choice among a few views.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/chip-group
pnpm dlx shadcn@latest add @uiarc/chip-group
yarn dlx shadcn@latest add @uiarc/chip-group
bunx --bun shadcn@latest add @uiarc/chip-group
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/chip-group.json
```

#### Manual

1. Install the dependencies:

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

2. Copy the source into your project. Main file: `registry/components/chip-group/chip-group.tsx`

   The source is in the registry item: https://uiarc.dev/r/chip-group.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { ChipGroup } from "@/components/arc/chip-group/chip-group";

export function TopicFilter() {
  const [topics, setTopics] = useState<string[]>([]);
  return (
    <ChipGroup
      label="Topics"
      value={topics}
      onValueChange={setTopics}
      maxVisible={4}
      options={["Design", "Motion", "Code", "Research", "Writing"].map((t) => ({ value: t.toLowerCase(), label: t }))}
    />
  );
}
```

### API reference

#### ChipGroup

Toggleable filter chips that morph when selected and fold long sets behind a +N more chip.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `options` (required) | `{ value: string; label: string }[]` | – | Chips in order. |
| `value` (required) | `string[]` | – | Selected values. |
| `onValueChange` (required) | `(value: string[]) => void` | – | Called with the new selection, in option order. |
| `label` (required) | `string` | – | Accessible name of the group, such as "Topics". |
| `multiple` | `boolean` | `true` | Allow several chips. In single mode the selected chip can still be cleared. |
| `maxVisible` | `number` | `Infinity` | Chips shown before the rest fold. Selected chips always stay in view. |
| `className` | `string` | – | Added to the group. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Arrow keys | Move focus between chips and the more chip, wrapping. |
| Home / End | Focus the first or last chip. |
| Enter / Space | Toggles the focused chip or opens the overflow. |

### Accessibility

- The group has role="group" and aria-label; each chip is a button with aria-pressed.
- Roving tabindex keeps one chip in the tab order; the more chip uses aria-expanded.
- Check icons and surfaces are aria-hidden.

### Motion

- Selecting grows a check in, slides the label over, and springs the chip edge while neighbours glide to new places, even across lines. Revealed chips stagger in and the group height morphs.
- Reduced motion replaces the morphs with short fades.

### Responsive behavior

- Chips wrap onto new lines and the frame height follows on a spring.
- Selected chips always stay visible, even beyond maxVisible, so folding never hides active filters.

### Performance

- Every chip has layout position animation and its own ResizeObserver; keep sets to a few dozen and fold the rest.
- Revealed chips stagger in, capped at 0.3s total.

### Notes for AI

- Use for facet filters people toggle often. Use multi-select when space is tight and checkbox in forms.
- Always controlled. Set multiple={false} for a single, clearable choice.
- Exported as both named and default.

### Related

- [Multi-select](https://uiarc.dev/components/multi-select/markdown): Select several values while keeping the field readable.
- [Filter toolbar](https://uiarc.dev/components/filter-toolbar/markdown): Keep collection filters close and easy to reset.
- [Segmented control](https://uiarc.dev/components/segmented-control/markdown): Switch between a small set of related views.
- [Tag input](https://uiarc.dev/components/tag-input/markdown): Turn short text values into removable tags.

### Also in selects

- [Select](https://uiarc.dev/components/select/markdown): A compact choice field with a keyboard friendly menu.
- [Combobox](https://uiarc.dev/components/combobox/markdown): Search and select from a list without leaving the field.
- [Morph select](https://uiarc.dev/components/morph-select/markdown): A select whose trigger grows into the list, with a gliding highlight and type-ahead.

### Guidance for AI tools

Chip group: Filter by a few facets with chips that morph as you pick them. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Radio cards

> Selectable option cards with a sliding selection ring, price and description slots, and radio keyboard behavior.

- Type: Component (inputs)
- Access: Free, open source
- Page: https://uiarc.dev/components/radio-cards
- Markdown: https://uiarc.dev/components/radio-cards/markdown
- Registry item: https://uiarc.dev/r/radio-cards.json
- Source file: `registry/components/radio-cards/radio-cards.tsx`
- Dependencies: motion
- Keywords: inputs, new, react radio cards, selectable cards, radio card group, plan selector, shipping options, option cards, card radio buttons

### When to use

- Choices where each option needs a description, price, or estimate to decide.
- Plan, shipping, region, or size pickers inside checkout and setup flows.
- Options that may be unavailable and need a visible reason.

### When not to use

- Use radio-group for short text-only options.
- Use segmented-control for two to four view modes that switch content instantly.
- Use select or combobox for long lists.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/radio-cards
pnpm dlx shadcn@latest add @uiarc/radio-cards
yarn dlx shadcn@latest add @uiarc/radio-cards
bunx --bun shadcn@latest add @uiarc/radio-cards
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/radio-cards.json
```

#### Manual

1. Install the dependencies:

```bash
npm install motion
```

2. Copy the source into your project. Main file: `registry/components/radio-cards/radio-cards.tsx`

   The source is in the registry item: https://uiarc.dev/r/radio-cards.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { RadioCards } from "@/components/arc/radio-cards/radio-cards";

export function ShippingSpeed() {
  return (
    <RadioCards
      aria-label="Shipping speed"
      name="shipping"
      layout="list"
      defaultValue="standard"
      options={[
        { value: "standard", label: "Standard", description: "4 to 6 business days", meta: "Free" },
        { value: "express", label: "Express", description: "2 business days", meta: "$12" },
        { value: "overnight", label: "Overnight", meta: "$29", disabled: true, disabledReason: "Not available for this address" },
      ]}
    />
  );
}
```

### API reference

#### RadioCards

Selectable option cards for choices that need more than a label. One selection ring glides from card to card, and the group behaves as a native radio group.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `options` (required) | `RadioCardOption[]` | – | Choices: { value, label, description?, meta?, icon?, disabled?, disabledReason? }. |
| `value` | `string \| null` | – | Selected value (controlled). |
| `defaultValue` | `string \| null` | `null` | Initial value when uncontrolled. |
| `onValueChange` | `(value: string) => void` | – | Called when a new card is selected. |
| `layout` | `"grid" \| "list"` | `"grid"` | "grid" places cards in responsive columns; "list" stacks full-width rows with meta at the end. |
| `minColumnWidth` | `number` | `180` | Narrowest a grid column may get before the grid drops a column, in px. |
| `name` | `string` | – | Form field name. Renders a hidden input with the selected value. |
| `required` | `boolean` | – | Marks the group and hidden input as required. |
| `disabled` | `boolean` | `false` | Disables every card. |
| `...props` | `HTMLAttributes<HTMLDivElement>` | – | Forwarded to the radiogroup, including ref, aria-label, and className. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Tab | Focuses the selected card, or the first enabled one. One tab stop for the group. |
| Arrow keys | Move to the next or previous enabled card and select it, wrapping. Left and right flip in RTL. |
| Home / End | Select the first or last enabled card. |
| Enter / Space | Selects the focused card. |

### Accessibility

- role="radiogroup" with role="radio" cards, aria-checked, and aria-disabled; give the group an aria-label or aria-labelledby.
- Each card is labelled by its label and described by its description, or by disabledReason when disabled.
- Selection is shown by a ring and a filled indicator dot, not color alone.

### Motion

- One ring springs to the selected card's box and its size; resizes snap it without replaying the glide.
- The indicator dot scales in on the snappy spring.
- Reduced motion jumps the ring and dot to their final state.

### Responsive behavior

- The grid uses auto-fill columns with a minimum of minColumnWidth, so it drops to one column in narrow containers.
- List layout keeps the indicator, text, and meta on one row and truncates nothing; long descriptions wrap.

### Performance

- One ResizeObserver on the group keeps the ring aligned; the ring moves with motion values without re-rendering cards.

### Notes for AI

- Choose it for three to six options that each need a description or price: plans, shipping speeds, regions, instance sizes.
- Pass name to submit with a native form; the value is carried by a hidden input.
- Use disabledReason to explain why an option is unavailable instead of hiding it.

### Related

- [Radio group](https://uiarc.dev/components/radio-group/markdown): Choose one option from a visible set.
- [Segmented control](https://uiarc.dev/components/segmented-control/markdown): Switch between a small set of related views.
- [Billing toggle](https://uiarc.dev/components/billing-toggle/markdown): A monthly and yearly switch with a savings badge and prices that roll to the new amount.

### Also in toggles

- [Checkbox](https://uiarc.dev/components/checkbox/markdown): A binary choice with a precise, legible state.
- [Switch](https://uiarc.dev/components/switch/markdown): A tactile toggle for settings that take effect immediately.
- [Rating](https://uiarc.dev/components/rating/markdown): A simple, accessible way to capture a numeric opinion.
- [Toggle group](https://uiarc.dev/components/toggle-group/markdown): A row of icon or text toggles, single or multiple: one pressed fill glides between options, or each fades in on its own and neighbours join, as in a formatting toolbar.

### Guidance for AI tools

Radio cards: Selectable option cards with a sliding selection ring, price and description slots, and radio keyboard behavior. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Billing toggle

> A monthly and yearly switch with a savings badge and prices that roll to the new amount.

- Type: Component (inputs)
- Access: Free, open source
- Page: https://uiarc.dev/components/billing-toggle
- Markdown: https://uiarc.dev/components/billing-toggle/markdown
- Registry item: https://uiarc.dev/r/billing-toggle.json
- Source file: `registry/components/billing-toggle/billing-toggle.tsx`
- Dependencies: motion
- Keywords: inputs, new, react billing toggle, monthly yearly switch, pricing period toggle, annual billing discount, save 20 percent badge, animated price, pricing toggle

### When to use

- The billing period switch at the top of a pricing page.
- Any price display that should roll to a new amount when a period or plan changes, using BillingPrice.
- A small plan picker with a savings note, such as yearly versus lifetime.

### When not to use

- Use segmented-control for switching views or filters with no pricing meaning.
- Use radio-group when options need descriptions or a vertical layout.
- Use switch for a single on or off setting.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/billing-toggle
pnpm dlx shadcn@latest add @uiarc/billing-toggle
yarn dlx shadcn@latest add @uiarc/billing-toggle
bunx --bun shadcn@latest add @uiarc/billing-toggle
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/billing-toggle.json
```

#### Manual

1. Install the dependencies:

```bash
npm install motion
```

2. Copy the source into your project. Main file: `registry/components/billing-toggle/billing-toggle.tsx`

   The source is in the registry item: https://uiarc.dev/r/billing-toggle.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { useState } from "react";
import { BillingPrice, BillingToggle } from "@/components/arc/billing-toggle/billing-toggle";

export function ProPrice() {
  const [period, setPeriod] = useState("monthly");
  const yearly = period === "yearly";
  return (
    <div>
      <BillingToggle
        value={period}
        onValueChange={setPeriod}
        options={[
          { value: "monthly", label: "Monthly" },
          { value: "yearly", label: "Yearly", badge: "Save 20%", activeBadge: "You save $48" },
        ]}
      />
      <BillingPrice amount={yearly ? 16 : 20} was={yearly ? 20 : undefined} period={yearly ? "per month, billed yearly" : "per month"} />
    </div>
  );
}
```

### API reference

#### BillingToggle

A billing period switch. One thumb glides between the options, and the savings note on the cheaper period tints and rewrites itself in place once it is chosen. Set --billing-accent on any ancestor to recolor the note (defaults to --success).

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` (required) | `string` | – | Value of the selected option. Controlled only. |
| `onValueChange` (required) | `(value: string) => void` | – | Called with the chosen option's value on click or arrow key. |
| `options` | `BillingToggleOption[]` | `Monthly and Yearly with a Save 20% badge` | Options in order. Each has value, label, and optional badge and activeBadge. |
| `label` | `string` | `"Billing period"` | Accessible name of the radio group. |
| `size` | `"md" \| "lg"` | `"md"` | md is 36px tall per option, lg is 44px with larger text. |
| `className` | `string` | – | Extra class on the radio group. |

#### BillingToggleOption

One option of the toggle.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` (required) | `string` | – | Value passed to onValueChange. Also the React key. |
| `label` (required) | `string` | – | Visible option text. |
| `badge` | `string` | – | Short savings note, such as Save 20%. |
| `activeBadge` | `string` | – | Badge text once this option is selected, such as You save $48. Defaults to badge. |

#### BillingPrice

A price that rolls to its new amount when the billing period changes, with an optional struck-through old price and a period that swaps in place.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `amount` (required) | `number` | – | The price to show. |
| `currency` | `string` | `"$"` | Symbol before the amount and the old price. |
| `period` | `string` | – | Text after the price, such as per month. Swaps with a short fade when it changes. |
| `was` | `number` | – | Previous price. Shown struck through only when it is higher than amount. |
| `decimals` | `number` | `0` | Decimal places for amount and was. |
| `className` | `string` | – | Extra class on the price. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Tab | Moves focus to the selected option only (roving tabindex). |
| Arrow Right / Arrow Down | Selects and focuses the next option, wrapping at the end. |
| Arrow Left / Arrow Up | Selects and focuses the previous option, wrapping at the start. |
| Home / End | Selects the first or last option. |

### Accessibility

- The toggle is role="radiogroup" labelled by label. Each option is a button with role="radio" and aria-checked.
- Badges are part of the option text, so the saving is read with the option name.
- The sliding thumb is aria-hidden.
- BillingPrice uses del for the old price. The rolling digits come from AnimatedCounter.

### Motion

- One thumb is measured from the selected option and glides to its x and width on a critically damped spring (0.34s, no bounce).
- When an option with a badge is selected, the badge takes a faint --billing-accent tint and its text crossfades with a short rise. Every candidate text reserves space, so the badge never changes width.
- BillingPrice rolls digits to the new amount, fades the old price in from the left, and swaps the period text in place.
- Reduced motion jumps the thumb and swaps badge text without travel.

### Responsive behavior

- The group is inline-flex and capped at 100% width. Options do not wrap, so keep labels and badges short on phones.
- Hover color only applies on devices with a fine pointer. Tap highlight is removed on touch.

### Performance

- Only the thumb and badge text animate. One ResizeObserver re-measures the thumb when the group resizes.
- BillingPrice renders one AnimatedCounter; keep it to a few per page section.

### Notes for AI

- Choose it for the monthly or yearly switch above pricing cards. Use segmented-control for general view switching that has nothing to do with price.
- It is controlled only. Keep the period in state and derive every price from it so all cards update together.
- Put the concrete saving in activeBadge, and a percentage in badge, so the confirmed number appears once chosen.
- Recolor the savings note with --billing-accent on any ancestor, for example --billing-accent: var(--accent) in a wrapper's CSS.
- Use BillingPrice for each card's amount so the digits roll together when the period flips.
- More than two options work, such as monthly, yearly, and lifetime.

### Related

- [Segmented control](https://uiarc.dev/components/segmented-control/markdown): Switch between a small set of related views.
- [Animated counter](https://uiarc.dev/components/animated-counter/markdown): Give changing totals a clear sense of movement.
- [Radio group](https://uiarc.dev/components/radio-group/markdown): Choose one option from a visible set.

### Also in toggles

- [Radio cards](https://uiarc.dev/components/radio-cards/markdown): Selectable option cards with a sliding selection ring, price and description slots, and radio keyboard behavior.
- [Checkbox](https://uiarc.dev/components/checkbox/markdown): A binary choice with a precise, legible state.
- [Switch](https://uiarc.dev/components/switch/markdown): A tactile toggle for settings that take effect immediately.
- [Rating](https://uiarc.dev/components/rating/markdown): A simple, accessible way to capture a numeric opinion.
- [Toggle group](https://uiarc.dev/components/toggle-group/markdown): A row of icon or text toggles, single or multiple: one pressed fill glides between options, or each fades in on its own and neighbours join, as in a formatting toolbar.

### Guidance for AI tools

Billing toggle: A monthly and yearly switch with a savings badge and prices that roll to the new amount. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Checkbox

> A binary choice with a precise, legible state.

- Type: Component (inputs)
- Access: Free, open source
- Page: https://uiarc.dev/components/checkbox
- Markdown: https://uiarc.dev/components/checkbox/markdown
- Registry item: https://uiarc.dev/r/checkbox.json
- Source file: `registry/components/checkbox/checkbox.tsx`
- Dependencies: @radix-ui/react-checkbox, motion
- Keywords: field, form, react checkbox, animated checkbox, indeterminate checkbox, radix checkbox, checkbox with description, terms checkbox

### When to use

- Independent on and off choices confirmed by a submit, such as accepting terms.
- Parent rows that show a partial selection through the indeterminate state.

### When not to use

- Use switch for settings that apply immediately.
- Use radio-group when only one option can be chosen.
- Use chip-group for filter facets people toggle often.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/checkbox
pnpm dlx shadcn@latest add @uiarc/checkbox
yarn dlx shadcn@latest add @uiarc/checkbox
bunx --bun shadcn@latest add @uiarc/checkbox
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/checkbox.json
```

#### Manual

1. Install the dependencies:

```bash
npm install @radix-ui/react-checkbox motion
```

2. Copy the source into your project. Main file: `registry/components/checkbox/checkbox.tsx`

   The source is in the registry item: https://uiarc.dev/r/checkbox.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { Checkbox } from "@/components/arc/checkbox/checkbox";

export function TermsCheckbox() {
  const [accepted, setAccepted] = useState(false);
  return (
    <Checkbox
      label="I agree to the terms"
      description="You can export your data at any time."
      checked={accepted}
      onCheckedChange={(next) => setAccepted(next === true)}
    />
  );
}
```

### API reference

#### Checkbox

A Radix checkbox whose check morphs into the indeterminate dash and back.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` | `string` | – | Visible label. Without it, pass aria-label; the fallback name is "Checkbox". |
| `description` | `string` | – | Secondary copy under the label, linked through aria-describedby. |
| `checked` | `boolean \| "indeterminate"` | – | Controlled state. |
| `defaultChecked` | `boolean \| "indeterminate"` | `false` | Initial state when uncontrolled. |
| `onCheckedChange` | `(checked: boolean \| "indeterminate") => void` | – | Called on every toggle. |
| `...props` | `ComponentPropsWithoutRef<typeof CheckboxPrimitive.Root>` | – | Radix Checkbox root props, including ref, name, value, required, and disabled. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Space | Toggles the checkbox. |

### Accessibility

- Radix renders a button with role="checkbox" and aria-checked, including "mixed" for indeterminate.
- The label is a real label element tied by id; description is linked through aria-describedby.
- The drawn mark is aria-hidden.

### Motion

- The fill scales in on a snappy spring while the check path draws; switching to indeterminate morphs the same path into a dash.
- Reduced motion applies every state change instantly.

### Responsive behavior

- The hit box is a full control-height square, so it stays easy to tap even though the drawn box is smaller.
- The label and description wrap beside the box; the box stays top-aligned with the first line.

### Performance

- A single spring on the fill and a path draw per toggle; long lists of checkboxes are fine.

### Notes for AI

- Use for independent on/off choices in forms. Use switch for settings that apply immediately and chip-group for filter facets.
- Set checked="indeterminate" on a parent checkbox when only some children are selected.
- Radix renders a hidden native input when name is set, so it submits with forms.

### Related

- [Switch](https://uiarc.dev/components/switch/markdown): A tactile toggle for settings that take effect immediately.
- [Radio group](https://uiarc.dev/components/radio-group/markdown): Choose one option from a visible set.
- [Chip group](https://uiarc.dev/components/chip-group/markdown): Filter by a few facets with chips that morph as you pick them.

### Also in toggles

- [Radio cards](https://uiarc.dev/components/radio-cards/markdown): Selectable option cards with a sliding selection ring, price and description slots, and radio keyboard behavior.
- [Billing toggle](https://uiarc.dev/components/billing-toggle/markdown): A monthly and yearly switch with a savings badge and prices that roll to the new amount.
- [Segmented control](https://uiarc.dev/components/segmented-control/markdown): Switch between a small set of related views.
- [Rating](https://uiarc.dev/components/rating/markdown): A simple, accessible way to capture a numeric opinion.
- [Toggle group](https://uiarc.dev/components/toggle-group/markdown): A row of icon or text toggles, single or multiple: one pressed fill glides between options, or each fades in on its own and neighbours join, as in a formatting toolbar.

### Guidance for AI tools

Checkbox: A binary choice with a precise, legible state. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Radio group

> Choose one option from a visible set.

- Type: Component (inputs)
- Access: Free, open source
- Page: https://uiarc.dev/components/radio-group
- Markdown: https://uiarc.dev/components/radio-group/markdown
- Registry item: https://uiarc.dev/r/radio-group.json
- Source file: `registry/components/radio-group/radio-group.tsx`
- Dependencies: motion
- Keywords: field, choice, react radio group, radio buttons, radio cards, plan picker, animated radio, radio with description

### When to use

- Two to six mutually exclusive options that need descriptions, such as plans.
- Form choices that should submit natively through name.

### When not to use

- Use segmented-control for short inline view options.
- Use select for longer lists.
- Use checkbox when several options can be on at once.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/radio-group
pnpm dlx shadcn@latest add @uiarc/radio-group
yarn dlx shadcn@latest add @uiarc/radio-group
bunx --bun shadcn@latest add @uiarc/radio-group
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/radio-group.json
```

#### Manual

1. Install the dependencies:

```bash
npm install motion
```

2. Copy the source into your project. Main file: `registry/components/radio-group/radio-group.tsx`

   The source is in the registry item: https://uiarc.dev/r/radio-group.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { RadioGroup } from "@/components/arc/radio-group/radio-group";

export function PlanPicker() {
  const [plan, setPlan] = useState("team");
  return (
    <RadioGroup
      label="Plan"
      name="plan"
      value={plan}
      onValueChange={setPlan}
      options={[
        { value: "solo", label: "Solo", description: "One seat" },
        { value: "team", label: "Team", description: "Up to 20 seats" },
      ]}
    />
  );
}
```

### API reference

#### RadioGroup

A fieldset of native radios where one highlight glides to the chosen row.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` (required) | `string` | – | Rendered as the fieldset legend. |
| `options` (required) | `{ value: string; label: string; description?: string }[]` | – | Rows in order, each with optional secondary copy. |
| `value` (required) | `string` | – | Selected value. |
| `onValueChange` (required) | `(value: string) => void` | – | Called with the chosen value. |
| `name` | `string` | – | Native radio name for form submission. Generated when omitted. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Arrow keys | Move the selection between options (native radio behavior). |
| Tab | Enters and leaves the group at the selected option. |

### Accessibility

- Uses a fieldset and legend with native radio inputs wrapped in labels.
- The highlight and dot are aria-hidden decoration.

### Motion

- One highlight glides to the chosen row on the morph spring while the new dot springs in and the old one shrinks away.
- Reduced motion places the highlight and dot instantly; resizes never animate.

### Responsive behavior

- Rows stack vertically and stretch to the column, so long descriptions wrap cleanly on narrow screens.
- A ResizeObserver re-places the highlight on resize without animating it.

### Performance

- One shared highlight moves between rows instead of a layout animation per row.

### Notes for AI

- Use for two to six mutually exclusive options that need descriptions. Use segmented-control for short inline choices and select for longer lists.
- Always controlled: value and onValueChange are required. Pass name to submit with a form.

### Related

- [Segmented control](https://uiarc.dev/components/segmented-control/markdown): Switch between a small set of related views.
- [Select](https://uiarc.dev/components/select/markdown): A compact choice field with a keyboard friendly menu.
- [Checkbox](https://uiarc.dev/components/checkbox/markdown): A binary choice with a precise, legible state.

### Also in toggles

- [Radio cards](https://uiarc.dev/components/radio-cards/markdown): Selectable option cards with a sliding selection ring, price and description slots, and radio keyboard behavior.
- [Billing toggle](https://uiarc.dev/components/billing-toggle/markdown): A monthly and yearly switch with a savings badge and prices that roll to the new amount.
- [Switch](https://uiarc.dev/components/switch/markdown): A tactile toggle for settings that take effect immediately.
- [Rating](https://uiarc.dev/components/rating/markdown): A simple, accessible way to capture a numeric opinion.
- [Toggle group](https://uiarc.dev/components/toggle-group/markdown): A row of icon or text toggles, single or multiple: one pressed fill glides between options, or each fades in on its own and neighbours join, as in a formatting toolbar.

### Guidance for AI tools

Radio group: Choose one option from a visible set. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Switch

> A tactile toggle for settings that take effect immediately.

- Type: Component (inputs)
- Access: Free, open source
- Page: https://uiarc.dev/components/switch
- Markdown: https://uiarc.dev/components/switch/markdown
- Registry item: https://uiarc.dev/r/switch.json
- Source file: `registry/components/switch/switch.tsx`
- Dependencies: @radix-ui/react-switch, motion
- Keywords: toggle, settings, react switch, toggle switch, ios toggle, radix switch, settings toggle, animated switch

### When to use

- Settings that take effect as soon as they are flipped, like notifications.
- Settings lists where each row is one on and off preference.

### When not to use

- Use checkbox when the choice waits for a submit button.
- Use segmented-control for a choice between named options.
- Use theme-switch for a light and dark toggle.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/switch
pnpm dlx shadcn@latest add @uiarc/switch
yarn dlx shadcn@latest add @uiarc/switch
bunx --bun shadcn@latest add @uiarc/switch
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/switch.json
```

#### Manual

1. Install the dependencies:

```bash
npm install @radix-ui/react-switch motion
```

2. Copy the source into your project. Main file: `registry/components/switch/switch.tsx`

   The source is in the registry item: https://uiarc.dev/r/switch.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { Switch } from "@/components/arc/switch/switch";

export function NotificationsToggle() {
  const [enabled, setEnabled] = useState(true);
  return <Switch label="Email notifications" checked={enabled} onCheckedChange={setEnabled} />;
}
```

### API reference

#### Switch

A Radix switch whose thumb stretches while pressed and travels on a spring.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` | `string` | – | Visible label inside the switch; also used as aria-label when none is passed. |
| `checked` | `boolean` | – | Controlled state. |
| `defaultChecked` | `boolean` | `false` | Initial state when uncontrolled. |
| `onCheckedChange` | `(checked: boolean) => void` | – | Called on every toggle. |
| `...props` | `ComponentPropsWithoutRef<typeof SwitchPrimitive.Root>` | – | Radix Switch root props, including ref, name, disabled, and aria-label. Pointer and key handlers are chained, not replaced. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Space / Enter | Toggles the switch. Holding Space stretches the thumb until release. |

### Accessibility

- Radix renders a button with role="switch" and aria-checked.
- The label prop becomes aria-label unless one is passed; icon-only usage needs an aria-label.

### Motion

- Pressing stretches the thumb toward the other side like a held finger; releasing sends it across on a snappy spring.
- Reduced motion removes the stretch and moves the thumb instantly; CSS transitions are also disabled.

### Responsive behavior

- The switch is inline and keeps a control-height minimum, so the whole label is a touch target.
- Hover styles apply only on fine pointers; touch gets the press stretch.

### Performance

- Motion is CSS transitions on the track and thumb, with no observers or per-frame work.

### Notes for AI

- Use for settings that take effect immediately. Use checkbox for choices confirmed by a submit button.
- Exported both as a named and a default export.
- Pass name to submit with a form through Radix's hidden input.

### Related

- [Checkbox](https://uiarc.dev/components/checkbox/markdown): A binary choice with a precise, legible state.
- [Segmented control](https://uiarc.dev/components/segmented-control/markdown): Switch between a small set of related views.
- [Theme switcher](https://uiarc.dev/components/theme-switch/markdown): Four smooth ways to move between light and dark appearance.

### Also in toggles

- [Radio cards](https://uiarc.dev/components/radio-cards/markdown): Selectable option cards with a sliding selection ring, price and description slots, and radio keyboard behavior.
- [Billing toggle](https://uiarc.dev/components/billing-toggle/markdown): A monthly and yearly switch with a savings badge and prices that roll to the new amount.
- [Radio group](https://uiarc.dev/components/radio-group/markdown): Choose one option from a visible set.
- [Rating](https://uiarc.dev/components/rating/markdown): A simple, accessible way to capture a numeric opinion.
- [Toggle group](https://uiarc.dev/components/toggle-group/markdown): A row of icon or text toggles, single or multiple: one pressed fill glides between options, or each fades in on its own and neighbours join, as in a formatting toolbar.

### Guidance for AI tools

Switch: A tactile toggle for settings that take effect immediately. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Segmented control

> Switch between a small set of related views.

- Type: Component (inputs)
- Access: Free, open source
- Page: https://uiarc.dev/components/segmented-control
- Markdown: https://uiarc.dev/components/segmented-control/markdown
- Registry item: https://uiarc.dev/r/segmented-control.json
- Source file: `registry/components/segmented-control/segmented-control.tsx`
- Dependencies: motion
- Keywords: control, choice, react segmented control, segmented button, toggle group, ios segmented control, view switcher, sliding pill toggle

### When to use

- Two to five short view options like Day, Week, and Month.
- Toolbar toggles between layouts or modes that apply immediately.

### When not to use

- Use tabs when each option swaps a panel of content.
- Use radio-group in forms or when options need descriptions.
- Use switch for a single on and off setting.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/segmented-control
pnpm dlx shadcn@latest add @uiarc/segmented-control
yarn dlx shadcn@latest add @uiarc/segmented-control
bunx --bun shadcn@latest add @uiarc/segmented-control
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/segmented-control.json
```

#### Manual

1. Install the dependencies:

```bash
npm install motion
```

2. Copy the source into your project. Main file: `registry/components/segmented-control/segmented-control.tsx`

   The source is in the registry item: https://uiarc.dev/r/segmented-control.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import SegmentedControl from "@/components/arc/segmented-control/segmented-control";

export function RangeToggle() {
  const [range, setRange] = useState("week");
  return (
    <SegmentedControl
      label="Range"
      value={range}
      onValueChange={setRange}
      options={[
        { value: "day", label: "Day" },
        { value: "week", label: "Week" },
        { value: "month", label: "Month" },
      ]}
    />
  );
}
```

### API reference

#### SegmentedControl

A row of toggle buttons with one selection pill that slides between them. Default export.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `options` (required) | `{ value: string; label: string; accessory?: ReactNode }[]` | – | Segments in order. An accessory, such as a badge, renders after the label. |
| `value` (required) | `string` | – | Selected value. |
| `onValueChange` (required) | `(value: string) => void` | – | Called with the chosen segment's value, from a click or the arrow, Home and End keys. |
| `label` | `string` | – | aria-label for the group. |
| `onOptionIntent` | `(value: string) => void` | – | Called when the pointer or focus reaches a segment before it is chosen, to start loading what it shows. |
| `className` | `string` | – | Extra class on the root. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Tab | Moves focus into the control, onto the selected segment, and out again. |
| Arrow keys | Select and focus the previous or next segment, wrapping at the ends. |
| Home / End | Select the first or last segment. |

### Accessibility

- Renders role="group" labelled by label, with native buttons using aria-pressed for the selected segment. Only the selected segment is a tab stop.
- The sliding pill is aria-hidden.

### Motion

- A shared layoutId pill slides to the selected segment on the morph spring, scoped per instance by a LayoutGroup.
- Reduced motion moves the pill instantly and disables button transitions.

### Responsive behavior

- The row is inline with max-width 100% and scrolls horizontally with a hidden scrollbar when segments do not fit.
- Segments never shrink or wrap, so keep labels short on mobile.

### Performance

- One shared layoutId pill per instance, scoped by a LayoutGroup; no observers.

### Notes for AI

- Use for two to five short, mutually exclusive view options like time ranges or layouts. Use tabs when each option swaps a panel, and radio-group in forms.
- Always controlled. Import it as a default export.

### Related

- [Tabs](https://uiarc.dev/components/tabs/markdown): Switch between related content in the same context.
- [Radio group](https://uiarc.dev/components/radio-group/markdown): Choose one option from a visible set.
- [Switch](https://uiarc.dev/components/switch/markdown): A tactile toggle for settings that take effect immediately.
- [Liquid tab bar](https://uiarc.dev/components/liquid-tab-bar/markdown): Tabs with a lens selection that slides between them, swaps labels cleanly, and fills in icons as it passes.

### Also in toggles

- [Radio cards](https://uiarc.dev/components/radio-cards/markdown): Selectable option cards with a sliding selection ring, price and description slots, and radio keyboard behavior.
- [Billing toggle](https://uiarc.dev/components/billing-toggle/markdown): A monthly and yearly switch with a savings badge and prices that roll to the new amount.
- [Checkbox](https://uiarc.dev/components/checkbox/markdown): A binary choice with a precise, legible state.
- [Rating](https://uiarc.dev/components/rating/markdown): A simple, accessible way to capture a numeric opinion.
- [Toggle group](https://uiarc.dev/components/toggle-group/markdown): A row of icon or text toggles, single or multiple: one pressed fill glides between options, or each fades in on its own and neighbours join, as in a formatting toolbar.

### Guidance for AI tools

Segmented control: Switch between a small set of related views. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Rating

> A simple, accessible way to capture a numeric opinion.

- Type: Component (inputs)
- Access: Free, open source
- Page: https://uiarc.dev/components/rating
- Markdown: https://uiarc.dev/components/rating/markdown
- Registry item: https://uiarc.dev/r/rating.json
- Source file: `registry/components/rating/rating.tsx`
- Dependencies: motion, lucide-react
- Keywords: input, feedback, react star rating, rating component, half star rating, review stars, accessible rating, 5 star rating

### When to use

- Collecting a 1 to N score in reviews or feedback forms.
- Displaying average scores, with readOnly and allowHalf.
- Forms that submit natively, via name.

### When not to use

- Use slider for continuous values.
- Use reactions for emoji feedback on content.
- Use radio-group when options are labelled choices rather than a scale.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/rating
pnpm dlx shadcn@latest add @uiarc/rating
yarn dlx shadcn@latest add @uiarc/rating
bunx --bun shadcn@latest add @uiarc/rating
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/rating.json
```

#### Manual

1. Install the dependencies:

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

2. Copy the source into your project. Main file: `registry/components/rating/rating.tsx`

   The source is in the registry item: https://uiarc.dev/r/rating.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { Rating } from "@/components/arc/rating/rating";

export function ReviewForm() {
  const [stars, setStars] = useState(0);
  return (
    <form>
      <Rating label="Overall experience" value={stars} onChange={setStars} name="rating" />
    </form>
  );
}
```

### API reference

#### Rating

A star rating built as a radio group, with half stars, scrubbing, clearing, and a rolling value label.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` (required) | `string` | – | Visible label and accessible name of the group. |
| `value` | `number` | – | Controlled value. 0 means not rated. |
| `defaultValue` | `number` | `0` | Initial value when uncontrolled. |
| `onChange` | `(value: number) => void` | – | Receives the committed value; 0 means cleared. |
| `max` | `number` | `5` | Number of stars. |
| `readOnly` | `boolean` | `false` | Renders a static image with an aria-label instead of radios. |
| `disabled` | `boolean` | `false` | Disables interaction. |
| `description` | `string` | – | Hint under the stars, linked with aria-describedby. |
| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Star size. |
| `allowHalf` | `boolean` | `false` | Pointer, touch, and arrow keys move in half stars. |
| `allowClear` | `boolean` | `true` | Choosing the current value again clears it; Backspace and Delete clear from the keyboard. |
| `showValue` | `boolean` | `true` | Shows the word or number for the previewed value beside the stars. |
| `valueLabels` | `readonly string[]` | – | One word per whole star. Five whole stars default to Poor through Excellent. |
| `emptyLabel` | `string` | `"Not rated"` | Shown when the value is 0. |
| `name` | `string` | – | Submits the value with a surrounding form via a hidden input. |
| `className` | `string` | – | Class on the field wrapper. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| ArrowRight / ArrowUp | Increases by one step (half a star with allowHalf). |
| ArrowLeft / ArrowDown | Decreases by one step. |
| Home / End | Jumps to the lowest or highest value. |
| 1-9 | Sets that many stars. |
| Backspace / Delete | Clears the rating when allowClear is on. |

### Accessibility

- Interactive ratings are role="radiogroup" with one role="radio" per step and a roving tab stop on the checked value.
- Each radio is labelled like "Great, 4 of 5 stars"; commits are announced in a polite live region.
- readOnly renders role="img" with an aria-label such as "Quality: 4 out of 5".

### Motion

- The fill sweeps star by star with a small stagger in the direction the value moved; a commit pops the stars in a wave.
- Pressed stars dip to 0.86 scale and the value word rolls in the direction of change.
- Reduced motion sets fills instantly and drops the pop, press scale, and word roll.

### Responsive behavior

- Stars sit in 36px cells for easy touch targets, and the value label wraps under the stars when space runs out.
- Touch presses scrub across stars with pointer capture; touch-action pan-y keeps vertical scrolling working.

### Performance

- Fills and pops are short motion animations per star; fine for a form, but use readOnly for long lists of scores.

### Notes for AI

- Use for collecting or showing a 1 to N score. Use slider for continuous values and reactions for emoji feedback.
- Pass name to submit with a native form. Use readOnly to display averages; combine with allowHalf for fractional values.

### Related

- [Slider](https://uiarc.dev/components/slider/markdown): Pick a value or a range on a track that follows your finger.
- [Reactions](https://uiarc.dev/components/reactions/markdown): Acknowledge a post in one tap, with counts that roll.
- [Radio group](https://uiarc.dev/components/radio-group/markdown): Choose one option from a visible set.

### Also in toggles

- [Radio cards](https://uiarc.dev/components/radio-cards/markdown): Selectable option cards with a sliding selection ring, price and description slots, and radio keyboard behavior.
- [Billing toggle](https://uiarc.dev/components/billing-toggle/markdown): A monthly and yearly switch with a savings badge and prices that roll to the new amount.
- [Checkbox](https://uiarc.dev/components/checkbox/markdown): A binary choice with a precise, legible state.
- [Switch](https://uiarc.dev/components/switch/markdown): A tactile toggle for settings that take effect immediately.
- [Segmented control](https://uiarc.dev/components/segmented-control/markdown): Switch between a small set of related views.
- [Toggle group](https://uiarc.dev/components/toggle-group/markdown): A row of icon or text toggles, single or multiple: one pressed fill glides between options, or each fades in on its own and neighbours join, as in a formatting toolbar.

### Guidance for AI tools

Rating: A simple, accessible way to capture a numeric opinion. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Toggle group

> A row of icon or text toggles, single or multiple: one pressed fill glides between options, or each fades in on its own and neighbours join, as in a formatting toolbar.

- Type: Component (inputs)
- Access: Free, open source
- Page: https://uiarc.dev/components/toggle-group
- Markdown: https://uiarc.dev/components/toggle-group/markdown
- Registry item: https://uiarc.dev/r/toggle-group.json
- Source file: `registry/components/toggle-group/toggle-group.tsx`
- Dependencies: motion
- Keywords: input, toggle, toolbar, new, toggle group, toggle buttons, formatting, bold italic underline, text alignment, icon buttons, pressed, multi select, button group

### When to use

- Formatting toolbars: bold, italic and underline as multiple, alignment as single.
- Compact view options on a canvas, map or editor, such as grid or list, or which layers to show.
- Any short row of icon toggles that apply immediately.

### When not to use

- Use segmented-control for switching between views, ranges or tabs of content.
- Use checkbox or switch for settings in a form that are saved together.
- Use chip-group for filters with long text labels or many options that wrap.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/toggle-group
pnpm dlx shadcn@latest add @uiarc/toggle-group
yarn dlx shadcn@latest add @uiarc/toggle-group
bunx --bun shadcn@latest add @uiarc/toggle-group
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/toggle-group.json
```

#### Manual

1. Install the dependencies:

```bash
npm install motion
```

2. Copy the source into your project. Main file: `registry/components/toggle-group/toggle-group.tsx`

   The source is in the registry item: https://uiarc.dev/r/toggle-group.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { ToggleGroup, ToggleGroupItem } from "@/components/arc/toggle-group/toggle-group";
import { AlignCenter, AlignLeft, AlignRight, Bold, Italic, Underline } from "lucide-react";

export function FormatBar() {
  const [marks, setMarks] = useState<string[]>([]);
  const [align, setAlign] = useState("left");
  return (
    <div style={{ display: "flex", gap: 8 }}>
      <ToggleGroup type="multiple" label="Text style" value={marks} onValueChange={setMarks}>
        <ToggleGroupItem value="bold" label="Bold"><Bold /></ToggleGroupItem>
        <ToggleGroupItem value="italic" label="Italic"><Italic /></ToggleGroupItem>
        <ToggleGroupItem value="underline" label="Underline"><Underline /></ToggleGroupItem>
      </ToggleGroup>
      <ToggleGroup label="Alignment" value={align} onValueChange={setAlign}>
        <ToggleGroupItem value="left" label="Align left"><AlignLeft /></ToggleGroupItem>
        <ToggleGroupItem value="center" label="Align center"><AlignCenter /></ToggleGroupItem>
        <ToggleGroupItem value="right" label="Align right"><AlignRight /></ToggleGroupItem>
      </ToggleGroup>
    </div>
  );
}
```

### API reference

#### ToggleGroup

A row of toggle buttons on a flat bordered strip. In single mode one tinted fill glides from option to option; in multiple mode each option's fill fades and settles in place, and neighbours that are both on join into one shape. Also exported as the default export.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `type` | `"single" \| "multiple"` | `"single"` | single keeps at most one option pressed, like a radio group; choosing the pressed option again keeps it. multiple lets each option toggle on its own. |
| `value` | `string \| null (single) \| readonly string[] (multiple)` | – | Pressed value or values, for a controlled group. |
| `defaultValue` | `string \| null (single) \| readonly string[] (multiple)` | – | Starting value for an uncontrolled group. |
| `onValueChange` | `(value: string) => void (single) \| (value: string[]) => void (multiple)` | – | Called with the new value or the new list of values. |
| `label` (required) | `string` | – | Accessible name of the group, such as Text style or Alignment. |
| `size` | `"sm" \| "md"` | `"md"` | Items 28 or 36px tall; the strip is 36 or 44px. |
| `disabled` | `boolean` | `false` | Disables every item. |
| `children` (required) | `ReactNode` | – | ToggleGroupItem elements, as direct children so neighbouring fills can join. |
| `className` | `string` | – | Class on the group element. |

#### ToggleGroupItem

One toggle. Holds an icon, text or both; icons are sized to 16px (14px at sm). Also available as ToggleGroup.Item.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` (required) | `string` | – | Value this item adds or selects. |
| `label` | `string` | – | Accessible name and native tooltip. Required when the item shows only an icon. |
| `disabled` | `boolean` | – | Disables this item and removes it from arrow key movement. |
| `children` (required) | `ReactNode` | – | Icon, text or both. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Tab | Moves into the group on one item (the last focused, else the first pressed, else the first) and out again. |
| Arrow keys | Move focus to the previous or next item, wrapping at the ends. Focus moves without pressing, as in a toolbar. |
| Home / End | Focus the first or last item. |
| Space / Enter | Toggle the focused item, or select it in single mode. |

### Accessibility

- Single mode renders role="radiogroup" with role="radio" items and aria-checked; multiple mode renders role="group" with aria-pressed buttons. Both are labelled by label.
- Roving tabindex: only one item is a tab stop, so a toolbar with several groups stays quick to cross with Tab.
- Icon only items take their accessible name and tooltip from label. Pressed state is shown by fill and text contrast, and exposed through aria-checked or aria-pressed.
- The fills are aria-hidden decoration.

### Motion

- Single: one fill with a shared layoutId moves to the chosen item on the morph spring, scoped per group by a LayoutGroup; its radius is scale corrected so it keeps its shape between items of different widths.
- Multiple: every item owns a fill that fades in over 180ms while it settles from 86% scale on the spring curve. When two neighbours are on, the fills close the gap and square off their inner corners, so a run of pressed items reads as one shape.
- Pressing an item gives its icon and label a small 92% press and spring back; the item box never scales, so neighbours never shift.
- Reduced motion moves the single fill instantly and replaces fades and presses with instant color changes.

### Responsive behavior

- The strip stays on one line and sizes to its items; place groups in a wrapping flex row so they stack at 320px.
- Items are at least 36px square at md; use md on touch screens and sm in dense desktop toolbars.

### Performance

- Single mode runs one Motion layout animation per change; multiple mode is pure CSS transitions on opacity, transform and inset.
- Item order for the roving tab stop is read from the DOM once per render of the group.

### Notes for AI

- Choose ToggleGroup for tool-like options that act on something else, often icon only: text formatting, view options, filters on a canvas. Choose segmented-control for a tab-like choice between views or ranges.
- Use type="multiple" for independent on/off options (bold, italic) and the default single type for mutually exclusive ones (alignment).
- Give every icon only item a label. Keep items as direct children; wrapping each in another element stops neighbouring fills from joining.
- Place several groups side by side with an 8px gap to build a toolbar; each group stays one tab stop.

### Related

- [Segmented control](https://uiarc.dev/components/segmented-control/markdown): Switch between a small set of related views.
- [Radio group](https://uiarc.dev/components/radio-group/markdown): Choose one option from a visible set.
- [Checkbox](https://uiarc.dev/components/checkbox/markdown): A binary choice with a precise, legible state.
- [Switch](https://uiarc.dev/components/switch/markdown): A tactile toggle for settings that take effect immediately.
- [Chip group](https://uiarc.dev/components/chip-group/markdown): Filter by a few facets with chips that morph as you pick them.
- [Rich text editor](https://uiarc.dev/components/rich-text-editor/markdown): A lightweight editor with markdown shortcuts, a floating toolbar, a slash menu, and HTML and markdown output.

### Also in toggles

- [Radio cards](https://uiarc.dev/components/radio-cards/markdown): Selectable option cards with a sliding selection ring, price and description slots, and radio keyboard behavior.
- [Billing toggle](https://uiarc.dev/components/billing-toggle/markdown): A monthly and yearly switch with a savings badge and prices that roll to the new amount.
- [Rating](https://uiarc.dev/components/rating/markdown): A simple, accessible way to capture a numeric opinion.

### Guidance for AI tools

Toggle group: A row of icon or text toggles, single or multiple: one pressed fill glides between options, or each fades in on its own and neighbours join, as in a formatting toolbar. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Slider

> Pick a value or a range on a track that follows your finger.

- Type: Component (inputs)
- Access: Free, open source
- Page: https://uiarc.dev/components/slider
- Markdown: https://uiarc.dev/components/slider/markdown
- Registry item: https://uiarc.dev/r/slider.json
- Source file: `registry/components/slider/slider.tsx`
- Dependencies: motion
- Keywords: slider, range, input, react slider, range slider, dual thumb slider, price range slider, slider with marks, animated slider

### When to use

- Approximate values like volume, opacity, or a price range.
- Ranges with two thumbs, labelled marks, and a formatted readout.

### When not to use

- Use number-field when the exact number matters.
- Use progress to show a value people cannot change.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/slider
pnpm dlx shadcn@latest add @uiarc/slider
yarn dlx shadcn@latest add @uiarc/slider
bunx --bun shadcn@latest add @uiarc/slider
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/slider.json
```

#### Manual

1. Install the dependencies:

```bash
npm install motion
```

2. Copy the source into your project. Main file: `registry/components/slider/slider.tsx`

   The source is in the registry item: https://uiarc.dev/r/slider.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { Slider } from "@/components/arc/slider/slider";

export function PriceFilter() {
  const [range, setRange] = useState<[number, number]>([20, 80]);
  return (
    <Slider
      label="Price"
      value={range}
      onValueChange={setRange}
      step={5}
      format={(v) => `$${v}`}
      thumbLabels={["Minimum price", "Maximum price"]}
    />
  );
}
```

### API reference

#### Slider

A single or range slider with momentum dragging, marks, a value bubble, and a rolling readout.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` (required) | `string` | – | Visible label; names the thumbs unless thumbLabels is set. |
| `value` | `number \| [number, number]` | – | Controlled value. A pair renders a range with two thumbs. |
| `defaultValue` | `number \| [number, number]` | – | Initial value when uncontrolled. |
| `onValueChange` | `(value: T) => void` | – | Called on every step while dragging or pressing keys. |
| `onValueCommit` | `(value: T) => void` | – | Called once when a drag is released or a key changes the value. |
| `min` | `number` | `0` | Lower bound. |
| `max` | `number` | `100` | Upper bound. |
| `step` | `number` | `1` | Increment. |
| `largeStep` | `number` | `a tenth of the range` | Distance for PageUp, PageDown, and Shift with an arrow. |
| `marks` | `(number \| { value: number; label?: string })[]` | – | Ticks on the track; labelled marks print under it and are clickable. |
| `minStepsBetweenThumbs` | `number` | `0` | Closest two range thumbs may sit, in steps. |
| `format` | `(value: number) => string` | – | Formats the readout, bubble, and spoken value. |
| `showValue` | `boolean` | `true` | Show the readout beside the label. |
| `thumbLabels` | `[string, string]` | – | Accessible names for the two range thumbs. |
| `start` | `ReactNode` | – | Content before the track, such as an icon. |
| `end` | `ReactNode` | – | Content after the track. |
| `name` | `string` | – | Submits the value with a form, one hidden input per thumb. |
| `disabled` | `boolean` | – | Disables dragging and keys. |
| `className` | `string` | – | Added to the root. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| ArrowRight / ArrowUp | Increases by step. |
| ArrowLeft / ArrowDown | Decreases by step. |
| Shift + Arrow / PageUp / PageDown | Moves by largeStep. |
| Home / End | Moves to the lowest or highest allowed value for that thumb. |

### Accessibility

- Each thumb is role="slider" with aria-valuemin, aria-valuemax, aria-valuenow, aria-valuetext from format, and aria-orientation.
- Thumbs are named by label, or by thumbLabels for ranges.
- The readout, bubble, and marks are aria-hidden because the thumbs carry the value.

### Motion

- Released drags carry a little momentum before snapping; the bubble springs up over an active thumb and digits roll in the readout. At a limit the thumb strains toward the key press and springs back.
- Reduced motion removes momentum, the strain, and digit rolling, and turns off CSS transitions.

### Responsive behavior

- It fills its column; the track uses touch-action pan-y, so horizontal drags move the thumb while vertical swipes scroll the page.
- On coarse pointers the value bubble sits higher so the finger does not cover it.
- The bubble and end mark labels clamp inside the track so they never overflow the edges.

### Performance

- Drags write motion values with pointer capture, so the thumb follows 1:1 without React re-renders per frame.
- onValueChange fires on every step; put fetching or heavy work in onValueCommit.

### Notes for AI

- Use for approximate values and ranges like volume, price filters, or opacity. Use number-field when the exact number matters.
- Controlled or uncontrolled; pass a tuple for a range. Put heavy work such as fetching in onValueCommit, not onValueChange.
- Pass name to submit through hidden inputs. Exported as both named and default.

### Related

- [Number field](https://uiarc.dev/components/number-field/markdown): Enter a bounded number with clear increment controls.
- [Progress](https://uiarc.dev/components/progress/markdown): Show how much of a known task is complete.
- [Filter toolbar](https://uiarc.dev/components/filter-toolbar/markdown): Keep collection filters close and easy to reset.

### Also in sliders

- [Elastic slider](https://uiarc.dev/components/elastic-slider/markdown): A slider that stretches like rubber past its ends, with a swaying value tag and detents the thumb clicks into.
- [Range histogram slider](https://uiarc.dev/components/range-histogram-slider/markdown): A price range over a live histogram of the data, lighting the bars inside the range and settling on bar edges.
- [Ruler slider](https://uiarc.dev/components/ruler-slider/markdown): A tape of ticks that slides under a fixed needle, with momentum, snapping, and a rolling readout.

### Guidance for AI tools

Slider: Pick a value or a range on a track that follows your finger. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Elastic slider

> A slider that stretches like rubber past its ends, with a swaying value tag and detents the thumb clicks into.

- Type: Component (inputs)
- Access: Free, open source
- Page: https://uiarc.dev/components/elastic-slider
- Markdown: https://uiarc.dev/components/elastic-slider/markdown
- Registry item: https://uiarc.dev/r/elastic-slider.json
- Source file: `registry/components/elastic-slider/elastic-slider.tsx`
- Dependencies: motion
- Keywords: inputs, new, elastic slider, rubber band slider, react slider, volume slider, slider with detents, stretchy slider, ios slider, animated range input

### When to use

- A single setting people drag to taste, such as volume, brightness, or opacity.
- Media and creative tools where a physical, tactile control fits the product.
- Values with a few common stops that should feel like detents.

### When not to use

- Use slider for dense forms and settings pages where a quiet control fits better.
- Use range-histogram-slider to pick a min and max over data.
- Use number-field or ruler-slider when the exact number matters more than the feel.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/elastic-slider
pnpm dlx shadcn@latest add @uiarc/elastic-slider
yarn dlx shadcn@latest add @uiarc/elastic-slider
bunx --bun shadcn@latest add @uiarc/elastic-slider
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/elastic-slider.json
```

#### Manual

1. Install the dependencies:

```bash
npm install motion
```

2. Copy the source into your project. Main file: `registry/components/elastic-slider/elastic-slider.tsx`

   The source is in the registry item: https://uiarc.dev/r/elastic-slider.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { ElasticSlider } from "@/components/arc/elastic-slider/elastic-slider";
import { Volume1, Volume2 } from "lucide-react";

export function VolumeControl() {
  const [volume, setVolume] = useState(60);
  return (
    <ElasticSlider
      label="Volume"
      value={volume}
      onValueChange={setVolume}
      marks={[0, { value: 50, label: "50%" }, 100]}
      format={value => `${value}%`}
      startIcon={<Volume1 size={16} />}
      endIcon={<Volume2 size={16} />}
    />
  );
}
```

### API reference

#### ElasticSlider

A single value slider that stretches like rubber past either end, swells the thumb under the finger, hangs a value tag that sways with speed, and treats marks as detents the thumb clicks into.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` (required) | `string` | – | Visible label. It also names the thumb. |
| `value` | `number` | – | Controlled value. Leave it out for uncontrolled use. |
| `defaultValue` | `number` | `min` | Initial value when uncontrolled. |
| `onValueChange` | `(value: number) => void` | – | Called on every change while dragging or pressing keys. |
| `onValueCommit` | `(value: number) => void` | – | Called once a drag is released, a key changes the value, or a mark label is clicked. |
| `min` | `number` | `0` | Lowest value. |
| `max` | `number` | `100` | Highest value. |
| `step` | `number` | `1` | Value increment. Values snap to it. |
| `largeStep` | `number` | – | Distance for PageUp, PageDown, and Shift with an arrow. Defaults to a tenth of the range. |
| `marks` | `(number \| { value: number; label?: string })[]` | – | Detents. A dragged thumb clicks into each one and holds for about 7px. Labelled marks print under the track and can be clicked. |
| `format` | `(value: number) => string` | – | Formats the readout, the value tag, and aria-valuetext. |
| `showValue` | `boolean` | `true` | Shows the value beside the label. The tag over the thumb still appears while dragging or using keys. |
| `startIcon` | `ReactNode` | – | Icon before the track. It is pushed outward when the track is pulled past the start. |
| `endIcon` | `ReactNode` | – | Icon after the track. It is pushed outward when the track is pulled past the end. |
| `name` | `string` | – | Submits the value with a form through a hidden input. |
| `disabled` | `boolean` | `false` | Blocks pointer and keyboard input and removes the thumb from the tab order. |
| `className` | `string` | – | Extra class on the root. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| ArrowRight / ArrowUp | Increases by one step. |
| ArrowLeft / ArrowDown | Decreases by one step. |
| Shift + Arrow / PageUp / PageDown | Moves by largeStep. |
| Home / End | Goes to min or max. At a limit, the track stretches toward the press and snaps back. |

### Accessibility

- The thumb is role="slider" with aria-valuemin, aria-valuemax, aria-valuenow, and aria-valuetext from format.
- The thumb is labelled by the visible label through aria-labelledby.
- The readout, value tag, icons, and mark labels are aria-hidden; the slider carries the value for assistive tech.
- Clicking a mark label is a pointer shortcut; the same values are reachable with keys.

### Motion

- The track rubber-bands past either end with iOS-style resistance and springs back with the release velocity.
- The thumb swells to 1.28x while dragged; the value tag trails it on a soft spring and tilts with its speed.
- Detents pop their tick and, on touch devices that support it, give a short vibration.
- Reduced motion removes the stretch, sway, and tick pop; the thumb jumps to its value and the tag fades.

### Responsive behavior

- The track fills its container; icons and the header stay on one row at any width.
- Touch drags use pointer capture, and detents add a short vibration where supported.
- Mark labels at the ends align to the track edges so they stay inside narrow containers.

### Performance

- Thumb, fill, stretch, and tag are driven by motion values, so dragging does not re-render React per frame.
- Track width is measured with one ResizeObserver.

### Notes for AI

- Choose it for one continuous value where the feel matters: volume, brightness, zoom, playback speed.
- Pass marks for values people aim for (0, 50, 100); they act as soft snaps without blocking values in between.
- Use onValueChange for live previews and onValueCommit for saves or network requests.
- For two thumbs or a range, use slider or range-histogram-slider instead.

### Related

- [Slider](https://uiarc.dev/components/slider/markdown): Pick a value or a range on a track that follows your finger.
- [Range histogram slider](https://uiarc.dev/components/range-histogram-slider/markdown): A price range over a live histogram of the data, lighting the bars inside the range and settling on bar edges.
- [Ruler slider](https://uiarc.dev/components/ruler-slider/markdown): A tape of ticks that slides under a fixed needle, with momentum, snapping, and a rolling readout.
- [Scrub input](https://uiarc.dev/components/scrub-input/markdown): A Figma-style number field: drag the label to scrub, or type values, units, and arithmetic.
- [Number field](https://uiarc.dev/components/number-field/markdown): Enter a bounded number with clear increment controls.

### Guidance for AI tools

Elastic slider: A slider that stretches like rubber past its ends, with a swaying value tag and detents the thumb clicks into. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Range histogram slider

> A price range over a live histogram of the data, lighting the bars inside the range and settling on bar edges.

- Type: Component (inputs)
- Access: Free, open source
- Page: https://uiarc.dev/components/range-histogram-slider
- Markdown: https://uiarc.dev/components/range-histogram-slider/markdown
- Registry item: https://uiarc.dev/r/range-histogram-slider.json
- Source file: `registry/components/range-histogram-slider/range-histogram-slider.tsx`
- Dependencies: motion
- Keywords: inputs, new, range slider with histogram, price range filter, airbnb price slider, dual thumb slider, histogram slider, react range slider, min max slider, distribution filter

### When to use

- Marketplace and search filters for price, size, or distance where the distribution guides the choice.
- Analytics filters that trim outliers from a numeric column.
- Any min and max choice where people benefit from seeing how many results fall inside.

### When not to use

- Use slider for a plain range without data behind it.
- Use elastic-slider or slider for a single value.
- Use number-field pairs when people type exact bounds more often than they drag.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/range-histogram-slider
pnpm dlx shadcn@latest add @uiarc/range-histogram-slider
yarn dlx shadcn@latest add @uiarc/range-histogram-slider
bunx --bun shadcn@latest add @uiarc/range-histogram-slider
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/range-histogram-slider.json
```

#### Manual

1. Install the dependencies:

```bash
npm install motion
```

2. Copy the source into your project. Main file: `registry/components/range-histogram-slider/range-histogram-slider.tsx`

   The source is in the registry item: https://uiarc.dev/r/range-histogram-slider.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { RangeHistogramSlider } from "@/components/arc/range-histogram-slider/range-histogram-slider";

export function PriceFilter({ prices }: { prices: number[] }) {
  const [range, setRange] = useState<[number, number]>([80, 320]);
  return (
    <RangeHistogramSlider
      label="Price per night"
      data={prices}
      min={0}
      max={500}
      step={5}
      bins={25}
      value={range}
      onValueChange={setRange}
      onValueCommit={range => refetchListings(range)}
      format={value => `$${value}`}
    />
  );
}
```

### API reference

#### RangeHistogramSlider

A two thumb range over a histogram of the data it filters. Bars inside the range light up, thumbs never cross, rubber-band at the ends, and settle on bar edges when released.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` (required) | `string` | – | Visible label. The thumbs are named from it unless thumbLabels is set. |
| `data` (required) | `number[]` | – | Raw values the histogram counts, such as every listing's price. |
| `value` | `[number, number]` | – | Controlled range. Leave it out for uncontrolled use. |
| `defaultValue` | `[number, number]` | `[min, max]` | Initial range when uncontrolled. |
| `onValueChange` | `(value: [number, number]) => void` | – | Called on every change while dragging or pressing keys. |
| `onValueCommit` | `(value: [number, number]) => void` | – | Called once a drag is released or a key changes the range. |
| `min` | `number` | – | Lower bound. Defaults to the smallest data value (or 0). |
| `max` | `number` | – | Upper bound. Defaults to the largest data value. |
| `step` | `number` | `1` | Value increment. |
| `bins` | `number` | `32` | How many bars the histogram draws. |
| `snapToBins` | `boolean` | `true` | A released thumb near a bar edge settles on it, so the range never cuts a bar in half. |
| `minStepsBetweenThumbs` | `number` | `1` | Closest the two thumbs may sit, in steps. |
| `format` | `(value: number) => string` | – | Formats the readout and aria-valuetext. |
| `thumbLabels` | `[string, string]` | – | Accessible names for the two thumbs. Defaults to "<label>, minimum" and "<label>, maximum". |
| `name` | `string` | – | Submits the range with a form, one hidden input per thumb. |
| `disabled` | `boolean` | `false` | Blocks input and removes the thumbs from the tab order. |
| `className` | `string` | – | Extra class on the root. |

#### histogram

Helper that counts values into equal bars between min and max. The last bar keeps max itself.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `(data, min, max, bins)` | `(number[], number, number, number) => number[]` | – | Returns one count per bar. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Tab | Moves between the minimum and maximum thumbs. |
| ArrowRight / ArrowUp | Increases the focused thumb by one step. |
| ArrowLeft / ArrowDown | Decreases the focused thumb by one step. |
| Shift + Arrow / PageUp / PageDown | Moves the focused thumb to the next bar edge in that direction. |
| Home / End | Moves the focused thumb to its lowest or highest allowed value. |

### Accessibility

- Each thumb is role="slider" with its own name, aria-valuetext, and aria-valuemin/max that reflect the other thumb, so the pair never reads as crossing.
- The histogram and the readout are aria-hidden; the thumbs carry the values.
- Pass thumbLabels in the product's language when the defaults do not fit.

### Motion

- Lit bars and the track fill are clipped by one path, so both cut exactly at each thumb on the same frame.
- Thumbs follow the pointer 1:1, rubber-band a few pixels past their limit, and settle with the release velocity; momentum can carry them at most one bar.
- Pressing the histogram or track springs the nearest thumb to that spot.
- Reduced motion removes the stretch and springs; thumbs jump to their values.

### Responsive behavior

- Chart and track fill the container width; bars shrink with it, so lower bins on narrow screens.
- Touch drags use pointer capture; thumbs keep a large hit area.
- The readout sits on the label row and uses tabular numbers.

### Performance

- Histogram counts are computed once per data, min, max, and bins change.
- Thumbs and clipping are motion values, so dragging does not re-render the bars.
- Bars render twice (base and lit copy); keep bins under about 60.

### Notes for AI

- Choose it for price, size, or duration filters where showing the data distribution helps people pick a sensible range.
- Pass the unfiltered values as data and filter your list on onValueCommit to avoid refetching on every frame.
- Keep data to the values the filter applies to; histogram counts are memoized on data, min, max, and bins.
- When the two thumbs sit together, the first drag direction decides which one moves.

### Related

- [Slider](https://uiarc.dev/components/slider/markdown): Pick a value or a range on a track that follows your finger.
- [Elastic slider](https://uiarc.dev/components/elastic-slider/markdown): A slider that stretches like rubber past its ends, with a swaying value tag and detents the thumb clicks into.
- [Filter toolbar](https://uiarc.dev/components/filter-toolbar/markdown): Keep collection filters close and easy to reset.
- [Date range picker](https://uiarc.dev/components/date-range-picker/markdown): A range picker that grows from its trigger into two months with presets and a stretching range highlight.
- [Ruler slider](https://uiarc.dev/components/ruler-slider/markdown): A tape of ticks that slides under a fixed needle, with momentum, snapping, and a rolling readout.

### Guidance for AI tools

Range histogram slider: A price range over a live histogram of the data, lighting the bars inside the range and settling on bar edges. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Ruler slider

> A tape of ticks that slides under a fixed needle, with momentum, snapping, and a rolling readout.

- Type: Component (inputs)
- Access: Free, open source
- Page: https://uiarc.dev/components/ruler-slider
- Markdown: https://uiarc.dev/components/ruler-slider/markdown
- Registry item: https://uiarc.dev/r/ruler-slider.json
- Source file: `registry/components/ruler-slider/ruler-slider.tsx`
- Dependencies: motion
- Keywords: inputs, new, ruler slider, tape measure input, height picker, weight picker, scrollable ruler, momentum slider, measurement input, react ruler picker

### When to use

- Onboarding and profile flows that ask for body measurements or goals.
- Mobile-first inputs where dragging a scale is easier than typing.
- Wide ranges with fine steps that a short slider track cannot resolve.

### When not to use

- Use number-field when people know the exact number and prefer to type it.
- Use slider or elastic-slider when the value is relative, like volume.
- Use range-histogram-slider to pick a range.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/ruler-slider
pnpm dlx shadcn@latest add @uiarc/ruler-slider
yarn dlx shadcn@latest add @uiarc/ruler-slider
bunx --bun shadcn@latest add @uiarc/ruler-slider
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/ruler-slider.json
```

#### Manual

1. Install the dependencies:

```bash
npm install motion
```

2. Copy the source into your project. Main file: `registry/components/ruler-slider/ruler-slider.tsx`

   The source is in the registry item: https://uiarc.dev/r/ruler-slider.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { RulerSlider } from "@/components/arc/ruler-slider/ruler-slider";

export function HeightField() {
  const [height, setHeight] = useState(172);
  return (
    <RulerSlider
      label="Height"
      unit="cm"
      min={120}
      max={220}
      value={height}
      onValueChange={setHeight}
      onValueCommit={saveHeight}
    />
  );
}
```

### API reference

#### RulerSlider

A precise value input shaped like a tape measure. A ruler of ticks slides under a fixed needle; drag it, flick it to coast onto a tick, tap to glide there, or scroll horizontally. The readout rolls each digit.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` (required) | `string` | – | Visible label. It also names the control. |
| `value` | `number` | – | Controlled value. Leave it out for uncontrolled use. |
| `defaultValue` | `number` | `min` | Initial value when uncontrolled. |
| `onValueChange` | `(value: number) => void` | – | Called whenever a tick passes the needle, including while coasting. |
| `onValueCommit` | `(value: number) => void` | – | Called once the tape comes to rest after a drag, flick, tap, scroll, or key. |
| `min` | `number` | `0` | Lowest value. |
| `max` | `number` | `100` | Highest value. |
| `step` | `number` | `1` | Value of one small tick. The tape always rests on a tick. |
| `largeStep` | `number` | – | Distance for PageUp, PageDown, and Shift with an arrow. Defaults to one labelled tick (step × majorEvery). |
| `majorEvery` | `number` | `10` | Small ticks between labelled ticks. |
| `spacing` | `number` | `10` | Pixels between small ticks. Wider spacing gives finer control. |
| `format` | `(value: number) => string` | – | Formats the readout, the tick labels, and aria-valuetext. |
| `unit` | `string` | – | Unit shown after the readout and spoken with the value, such as "cm". |
| `name` | `string` | – | Submits the value with a form through a hidden input. |
| `disabled` | `boolean` | `false` | Blocks input and removes the control from the tab order. |
| `className` | `string` | – | Extra class on the root. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| ArrowRight / ArrowUp | Moves one tick up. |
| ArrowLeft / ArrowDown | Moves one tick down. |
| Shift + Arrow / PageUp / PageDown | Moves one labelled tick (largeStep). |
| Home / End | Goes to min or max. |

### Accessibility

- The tape viewport is role="slider" with aria-valuemin, aria-valuemax, aria-valuenow, and aria-valuetext that includes the unit.
- It is labelled by the visible label through aria-labelledby.
- The rolling readout and needle are aria-hidden; the slider announces the value.
- Horizontal trackpad scrolling moves the tape; vertical scrolling is left to the page.

### Motion

- Dragging moves the tape 1:1; a flick coasts with scroll-like deceleration and lands on a tick.
- Pulling past either end rubber-bands, and releasing pulls the tape home with the throw's speed.
- Taps and keys glide on a spring that keeps any speed already in the tape; grabbing a coasting tape catches it in place.
- Each digit of the readout rolls on its own column as ticks pass the needle.
- Reduced motion removes coasting, rubber-banding, and glides; the tape jumps to the nearest tick.

### Responsive behavior

- The viewport fills its container and fades the tape at both edges; the needle stays centered at any width.
- Touch drags, flicks, and taps work the same as mouse; small moves under 4px count as a tap.
- Horizontal trackpad scrolling moves the tape without capturing vertical page scroll.

### Performance

- Ticks are drawn with CSS gradients, not one element per tick, so long ranges stay cheap.
- Only labelled ticks are elements; keep (max - min) / (step × majorEvery) to a few hundred.
- Tape position is a motion value, so dragging and coasting do not re-render per frame.

### Notes for AI

- Choose it for measurements and precise values on touch: height, weight, temperature, tip amount, zoom level.
- Set step to the precision you store and majorEvery so labelled ticks land on round numbers (10 for cm, 5 or 10 for kg).
- Increase spacing when people need finer control on small screens.
- Use onValueCommit for saves: onValueChange fires on every tick while the tape coasts.

### Related

- [Elastic slider](https://uiarc.dev/components/elastic-slider/markdown): A slider that stretches like rubber past its ends, with a swaying value tag and detents the thumb clicks into.
- [Slider](https://uiarc.dev/components/slider/markdown): Pick a value or a range on a track that follows your finger.
- [Scrub input](https://uiarc.dev/components/scrub-input/markdown): A Figma-style number field: drag the label to scrub, or type values, units, and arithmetic.
- [Number field](https://uiarc.dev/components/number-field/markdown): Enter a bounded number with clear increment controls.
- [Time dial](https://uiarc.dev/components/time-dial/markdown): Spin a dial to pick an hour and see which team cities are at work.

### Also in sliders

- [Range histogram slider](https://uiarc.dev/components/range-histogram-slider/markdown): A price range over a live histogram of the data, lighting the bars inside the range and settling on bar edges.

### Guidance for AI tools

Ruler slider: A tape of ticks that slides under a fixed needle, with momentum, snapping, and a rolling readout. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Calendar

> Browse dates in a clear, compact month view.

- Type: Component (inputs)
- Access: Free, open source
- Page: https://uiarc.dev/components/calendar
- Markdown: https://uiarc.dev/components/calendar/markdown
- Registry item: https://uiarc.dev/r/calendar.json
- Source file: `registry/components/calendar/calendar.tsx`
- Dependencies: motion, lucide-react
- Keywords: date, field, react calendar, date calendar, month calendar, inline date picker, booking calendar, animated calendar

### When to use

- Inline date picking where the month should stay visible, such as booking pages.
- Picking one date with blocked days via minDate, maxDate, and disabledDates.

### When not to use

- Use date-picker for a form field that opens a calendar popover.
- Use time-picker for times of day.
- Use booking-pill for a full compact booking flow.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/calendar
pnpm dlx shadcn@latest add @uiarc/calendar
yarn dlx shadcn@latest add @uiarc/calendar
bunx --bun shadcn@latest add @uiarc/calendar
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/calendar.json
```

#### Manual

1. Install the dependencies:

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

2. Copy the source into your project. Main file: `registry/components/calendar/calendar.tsx`

   The source is in the registry item: https://uiarc.dev/r/calendar.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

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

export function DeliveryDate() {
  const [date, setDate] = useState<Date>();
  return (
    <Calendar
      value={date}
      onChange={setDate}
      minDate={new Date()}
      disabledDates={(day) => day.getDay() === 0}
      showToday
    />
  );
}
```

### API reference

#### Calendar

A month grid for picking one date, with sliding month changes and a gliding selection.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `Date` | – | Selected date. |
| `onChange` | `(date: Date) => void` | – | Called when a day is picked. |
| `month` | `Date` | – | Controlled visible month. |
| `onMonthChange` | `(month: Date) => void` | – | Called with the first of the new month when navigating. |
| `minDate` | `Date` | – | Earliest selectable day. |
| `maxDate` | `Date` | – | Latest selectable day. |
| `disabledDates` | `(date: Date) => boolean` | – | Return true to block a day, such as weekends. |
| `locale` | `string` | `"en-US"` | Month, weekday, and day names. |
| `className` | `string` | – | Added to the root section. |
| `showToday` | `boolean` | `false` | Adds a Today button that returns to the current month and selects today when allowed. |

#### useToday

Hook returning the viewer's local date, undefined during SSR and hydration, and updating across midnight.

No props.

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Arrow keys | Move by one day or one week, skipping blocked days and crossing months. |
| Home / End | Move to the start or end of the week. |
| PageUp / PageDown | Move by one month; with Shift, by one year. |
| Enter / Space | Selects the focused day. |

### Accessibility

- Days sit in a role="grid" with role="row" and role="gridcell" buttons carrying full date aria-labels, aria-selected, and aria-current="date" for today.
- Roving tabindex keeps one day in the tab order; month changes are announced through a polite live region.
- Previous and next buttons are labelled and use aria-disabled at the min or max month.

### Motion

- Months slide in the direction of travel while the title letters and year digits roll; the selection highlight glides between days on the morph spring.
- Reduced motion, applied after hydration, swaps months and moves the highlight instantly.

### Responsive behavior

- The calendar is min(100%, 328px) wide and days are square cells that scale with it.
- The header is a container query: below 260px the title takes its own row and the controls move under it.

### Performance

- Only the incoming month is observed with a ResizeObserver, to morph between four, five, and six rows.
- Each day is a button, so a month is about 42 cells; render one calendar rather than many side by side.

### Notes for AI

- Use inline where the calendar is always visible, such as booking pages. Use date-picker for a form field that opens a calendar popover.
- value is controlled only; month can be controlled or left internal.
- Also exports date helpers addDays, addMonths, sameDay, and startOfDay, and the CalendarDateMatcher type.

### Related

- [Date picker](https://uiarc.dev/components/date-picker/markdown): Choose a date without losing context.
- [Time picker](https://uiarc.dev/components/time-picker/markdown): Choose a time with sensible keyboard behavior.
- [Booking pill](https://uiarc.dev/components/booking-pill/markdown): One pill that reshapes through party size, date, time, and a ticket.

### Also in pickers

- [Date range picker](https://uiarc.dev/components/date-range-picker/markdown): A range picker that grows from its trigger into two months with presets and a stretching range highlight.
- [Color picker](https://uiarc.dev/components/color-picker/markdown): A swatch that grows into a picker with format morphing, eyedropper, saved swatches, and contrast readout.
- [Emoji picker](https://uiarc.dev/components/emoji-picker/markdown): A full emoji picker with instant search, scroll-synced categories, skin tones, recently used emoji, and a virtualized, keyboard-navigable grid.

### Guidance for AI tools

Calendar: Browse dates in a clear, compact month view. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Date picker

> Choose a date without losing context.

- Type: Component (inputs)
- Access: Free, open source
- Page: https://uiarc.dev/components/date-picker
- Markdown: https://uiarc.dev/components/date-picker/markdown
- Registry item: https://uiarc.dev/r/date-picker.json
- Source file: `registry/components/date-picker/date-picker.tsx`
- Dependencies: motion, lucide-react
- Keywords: date, field, react date picker, datepicker, date input with calendar, calendar popover, form date field, animated date picker

### When to use

- A date field in a form, such as a start or due date.
- Dates with limits or blocked days, shown in a locale format.

### When not to use

- Use calendar inline when the grid should stay visible.
- Use time-picker for times, and pair it with this for a full timestamp.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/date-picker
pnpm dlx shadcn@latest add @uiarc/date-picker
yarn dlx shadcn@latest add @uiarc/date-picker
bunx --bun shadcn@latest add @uiarc/date-picker
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/date-picker.json
```

#### Manual

1. Install the dependencies:

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

2. Copy the source into your project. Main file: `registry/components/date-picker/date-picker.tsx`

   The source is in the registry item: https://uiarc.dev/r/date-picker.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { DatePicker } from "@/components/arc/date-picker/date-picker";

export function StartDateField() {
  const [start, setStart] = useState<Date>();
  return (
    <DatePicker
      label="Start date"
      value={start}
      onChange={setStart}
      minDate={new Date()}
      showToday
    />
  );
}
```

### API reference

#### DatePicker

A field button that opens Calendar in a popover and shows the date with per-part rolling.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` (required) | `string` | – | Visible label tied to the trigger. |
| `value` | `Date` | – | Selected date. |
| `onChange` | `(date: Date \| undefined) => void` | – | Called on pick and with undefined from the Clear button. |
| `description` | `string` | – | Helper copy under the field. |
| `placeholder` | `string` | `"Select a date"` | Shown with no value. |
| `minDate` | `Date` | – | Earliest selectable day. |
| `maxDate` | `Date` | – | Latest selectable day. |
| `disabledDates` | `(date: Date) => boolean` | – | Return true to block a day. |
| `locale` | `string` | `"en-US"` | Formatting and calendar locale. |
| `format` | `Intl.DateTimeFormatOptions` | `{ month: "short", day: "numeric", year: "numeric" }` | How the value is shown. |
| `showToday` | `boolean` | – | Adds a Today button to the calendar header. |
| `...props` | `Omit<ButtonHTMLAttributes<HTMLButtonElement>, "value" \| "onChange">` | – | Forwarded to the trigger button, including id, disabled, and className (applied to the root). |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Enter / Space / ArrowDown | Opens the calendar and focuses the selected or current day. |
| Escape | Closes the popover and returns focus to the trigger. |
| Calendar keys | Arrows, Home, End, PageUp, and PageDown navigate days as in Calendar. |

### Accessibility

- Trigger has aria-haspopup="dialog" and aria-expanded; the popover is role="dialog" labelled "<label> calendar".
- The formatted value lives in a visually hidden span; the rolling text is aria-hidden.
- Tabbing out or clicking outside closes it, and focus returns to the trigger when it was inside.

### Motion

- Changed date parts roll up for a later date and down for an earlier one; the popover springs in and closes about 240 ms after a pick so the highlight can land.
- Reduced motion crossfades the value and closes immediately after a pick.

### Responsive behavior

- The popover is min(320px, 100vw minus 32px) wide, left-aligned to the field.
- Below 360px of viewport the popover stretches to both field edges.
- It closes on any pointerdown outside, so a tap elsewhere dismisses it.

### Performance

- The calendar mounts only while open, and changed date parts roll with layout position animation.

### Notes for AI

- Use for a date field in forms. Use calendar inline when the grid should stay visible, and time-picker for times.
- value is controlled only. There is no name prop; serialize the Date into a hidden input for plain forms.

### Related

- [Calendar](https://uiarc.dev/components/calendar/markdown): Browse dates in a clear, compact month view.
- [Time picker](https://uiarc.dev/components/time-picker/markdown): Choose a time with sensible keyboard behavior.
- [Input](https://uiarc.dev/components/input/markdown): A single line field with clear labels and useful states.

### Also in pickers

- [Date range picker](https://uiarc.dev/components/date-range-picker/markdown): A range picker that grows from its trigger into two months with presets and a stretching range highlight.
- [Color picker](https://uiarc.dev/components/color-picker/markdown): A swatch that grows into a picker with format morphing, eyedropper, saved swatches, and contrast readout.
- [Emoji picker](https://uiarc.dev/components/emoji-picker/markdown): A full emoji picker with instant search, scroll-synced categories, skin tones, recently used emoji, and a virtualized, keyboard-navigable grid.

### Guidance for AI tools

Date picker: Choose a date without losing context. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Date range picker

> A range picker that grows from its trigger into two months with presets and a stretching range highlight.

- Type: Component (inputs)
- Access: Free, open source
- Page: https://uiarc.dev/components/date-range-picker
- Markdown: https://uiarc.dev/components/date-range-picker/markdown
- Registry item: https://uiarc.dev/r/date-range-picker.json
- Source file: `registry/components/date-range-picker/date-range-picker.tsx`
- Dependencies: motion, lucide-react
- Keywords: inputs, new, react date range picker, date range, calendar range selection, analytics date filter, start and end date, date presets, booking date picker

### When to use

- Analytics and reporting filters that need presets like Last 7 days or This quarter.
- Booking or leave requests where a start and end day are picked together.
- Toolbars where the picker must stay compact until opened.

### When not to use

- Use date-picker for a single date.
- Use calendar when the month should stay visible on the page.
- Use time-picker when the user chooses a time of day rather than days.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/date-range-picker
pnpm dlx shadcn@latest add @uiarc/date-range-picker
yarn dlx shadcn@latest add @uiarc/date-range-picker
bunx --bun shadcn@latest add @uiarc/date-range-picker
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/date-range-picker.json
```

#### Manual

1. Install the dependencies:

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

2. Copy the source into your project. Main file: `registry/components/date-range-picker/date-range-picker.tsx`

   The source is in the registry item: https://uiarc.dev/r/date-range-picker.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { useState } from "react";
import { DateRangePicker } from "@/components/arc/date-range-picker/date-range-picker";
import type { DateRange } from "@/components/arc/date-range-picker/date-range-picker";

export function ReportRange() {
  const [range, setRange] = useState<DateRange | null>(null);
  return (
    <DateRangePicker
      label="Report period"
      value={range}
      onChange={setRange}
      weekStartsOn={1}
      maxDate={new Date()}
    />
  );
}
```

### API reference

#### DateRangePicker

A trigger that grows into a panel with one or two months and a preset rail, then shrinks back with the applied range.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `DateRange \| null` | – | Controlled value, { start, end } as inclusive whole days. Pass null for no selection. |
| `defaultValue` | `DateRange \| null` | `null` | Uncontrolled starting value. |
| `onChange` | `(range: DateRange) => void` | – | Called with the range on Apply. |
| `label` | `string` | `"Date range"` | Accessible name of the trigger and the dialog. |
| `placeholder` | `string` | `"Select dates"` | Trigger text with no selection. |
| `presets` | `DateRangePreset[]` | `defaultDateRangePresets` | Shortcuts: { label, range: (today) => DateRange }. Defaults to Today through Year to date. |
| `minDate` | `Date` | – | Earliest selectable day. |
| `maxDate` | `Date` | – | Latest selectable day. |
| `weekStartsOn` | `0 \| 1` | `0` | 0 is Sunday, 1 is Monday. |
| `locale` | `string` | `"en-US"` | Locale for Intl.DateTimeFormat labels and month titles. |
| `months` | `"auto" \| 1 \| 2` | `"auto"` | Force one or two months. auto shows two when the boundary is at least 712px wide. |
| `boundary` | `() => HTMLElement \| null` | – | Element the panel should stay inside. Defaults to the viewport. |
| `className` | `string` | – | Extra class on the root. |

#### useToday

Hook returning the viewer's local date, or undefined during server render and hydration. Updates at local midnight and when the tab becomes visible.

No props.

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Enter / Space | Opens the panel from the trigger; picks a start or end day in the grid. |
| Arrow keys | Move by day or week in the grid, extending the range preview once a start is picked. |
| Home / End | Jump to the start or end of the week. |
| PageUp / PageDown | Move by month; add Shift to move by year. |
| ArrowUp / ArrowDown | Move between presets in the rail; ArrowLeft and ArrowRight in the compact row. |
| Escape | Closes without applying and returns focus to the trigger. |

### Accessibility

- The trigger has aria-haspopup="dialog", aria-expanded, and a label that includes the current range.
- Each month is a role="grid" labelled by its title, with columnheaders and gridcells using aria-selected for days in range and aria-current="date" for today.
- Days have full date labels and a roving tabindex; months that are leaving turn inert so focus only finds the current set.
- A polite live region announces the start day, then the range and its length.

### Motion

- The trigger surface grows into the panel on a physical spring and shrinks back on Apply while the formatted label flies into the trigger with a shared layoutId.
- The range highlight is one bar per week that stretches as you hover, and the two ends glide between days.
- Months slide in the direction of travel, and label words roll up or down with time's direction.
- Reduced motion jumps the surface size, drops the shared layout and slide, and uses short opacity fades.

### Responsive behavior

- months="auto" shows two months beside a vertical preset rail when the boundary is at least 712px wide, otherwise one month under a scrolling preset row.
- In compact mode the panel width is min(352px, available) and day cells size between 32 and 42px to fit.
- The panel shifts horizontally to stay 8px inside the boundary, and recomputes on window resize.

### Performance

- ResizeObservers on the trigger and panel feed the size springs; updates are batched through a microtask.
- Each week's highlight and each end is a motion value animation, so hovering does not re-render the grid beyond the range change.
- Intl.DateTimeFormat instances are memoized per locale.

### Notes for AI

- Use when a start and end date are chosen together: report filters, analytics periods, bookings.
- Selection is draft until Apply; onChange fires only on Apply. Cancel, Escape, or an outside click discards the draft.
- Pass custom presets as { label, range: today => ({ start, end }) }; today is the viewer's local date.
- The trigger is disabled until hydration because today is unknown on the server.
- For a single date use date-picker; for an always-visible month use calendar.

### Related

- [Date picker](https://uiarc.dev/components/date-picker/markdown): Choose a date without losing context.
- [Calendar](https://uiarc.dev/components/calendar/markdown): Browse dates in a clear, compact month view.
- [Time picker](https://uiarc.dev/components/time-picker/markdown): Choose a time with sensible keyboard behavior.
- [Filter toolbar](https://uiarc.dev/components/filter-toolbar/markdown): Keep collection filters close and easy to reset.

### Also in pickers

- [Color picker](https://uiarc.dev/components/color-picker/markdown): A swatch that grows into a picker with format morphing, eyedropper, saved swatches, and contrast readout.
- [Emoji picker](https://uiarc.dev/components/emoji-picker/markdown): A full emoji picker with instant search, scroll-synced categories, skin tones, recently used emoji, and a virtualized, keyboard-navigable grid.

### Guidance for AI tools

Date range picker: A range picker that grows from its trigger into two months with presets and a stretching range highlight. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Time picker

> Choose a time with sensible keyboard behavior.

- Type: Component (inputs)
- Access: Free, open source
- Page: https://uiarc.dev/components/time-picker
- Markdown: https://uiarc.dev/components/time-picker/markdown
- Registry item: https://uiarc.dev/r/time-picker.json
- Source file: `registry/components/time-picker/time-picker.tsx`
- Dependencies: motion, lucide-react
- Keywords: time, field, react time picker, time select, time input, meeting time picker, 12 hour time picker, time dropdown

### When to use

- Picking a time of day at a fixed interval, such as meetings or reminders.
- Fields that show 12-hour times but store 24-hour HH:mm values.

### When not to use

- Use date-picker for dates, pairing the two for a timestamp.
- Use time-dial for a more tactile, showcase time selection.
- Use select when only a few named times are allowed.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/time-picker
pnpm dlx shadcn@latest add @uiarc/time-picker
yarn dlx shadcn@latest add @uiarc/time-picker
bunx --bun shadcn@latest add @uiarc/time-picker
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/time-picker.json
```

#### Manual

1. Install the dependencies:

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

2. Copy the source into your project. Main file: `registry/components/time-picker/time-picker.tsx`

   The source is in the registry item: https://uiarc.dev/r/time-picker.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { TimePicker } from "@/components/arc/time-picker/time-picker";

export function MeetingTime() {
  const [time, setTime] = useState("14:30");
  return <TimePicker label="Start time" value={time} onChange={setTime} minuteStep={30} />;
}
```

### API reference

#### TimePicker

A trigger with a scrolling listbox of times at a fixed minute step; the shown time rolls like a clock.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` (required) | `string` | – | Visible label. |
| `value` | `string` | – | Controlled time as "HH:mm" (24-hour). |
| `defaultValue` | `string` | `"09:00"` | Initial time when uncontrolled. |
| `onChange` | `(value: string) => void` | – | Called with the new "HH:mm" value. |
| `description` | `string` | – | Helper copy under the field. |
| `placeholder` | `string` | `"Select a time"` | Shown when the value is empty. |
| `minuteStep` | `1 \| 5 \| 10 \| 15 \| 30` | `15` | Spacing between options. |
| `format` | `"12h" \| "24h"` | `"12h"` | Display format. Values stay 24-hour. |
| `disabled` | `boolean` | `false` | Disables the trigger. |
| `className` | `string` | – | Added to the root. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Enter / Space | Opens the list, or selects the active time when open. |
| ArrowDown / ArrowUp | Opens the list, then moves through times, wrapping. |
| Escape | Closes the list. |

### Accessibility

- Trigger has aria-haspopup="listbox", aria-expanded, aria-controls, and aria-labelledby combining the label and a hidden value.
- The menu is role="listbox" with role="option" items carrying aria-selected.
- The list opens centered on the selected time and scrolls only itself, never the page.

### Motion

- A later time rises in from below and an earlier one drops from above with a soft blur; the menu springs in from slightly above.
- Reduced motion crossfades the value and opens the menu with opacity only.

### Responsive behavior

- The list spans the field width and caps at 250px, scrolling itself with contained overscroll.
- It closes on any pointerdown outside the field.

### Performance

- All options at the chosen step render at once; minuteStep 1 means 1,440 rows, so prefer 5 or more.

### Notes for AI

- Use for picking a time of day at a fixed interval. Pair with date-picker for a full timestamp.
- Controlled or uncontrolled; values are always 24-hour "HH:mm" strings regardless of display format.

### Related

- [Date picker](https://uiarc.dev/components/date-picker/markdown): Choose a date without losing context.
- [Calendar](https://uiarc.dev/components/calendar/markdown): Browse dates in a clear, compact month view.
- [Select](https://uiarc.dev/components/select/markdown): A compact choice field with a keyboard friendly menu.
- [Time dial](https://uiarc.dev/components/time-dial/markdown): Spin a dial to pick an hour and see which team cities are at work.

### Also in pickers

- [Date range picker](https://uiarc.dev/components/date-range-picker/markdown): A range picker that grows from its trigger into two months with presets and a stretching range highlight.
- [Color picker](https://uiarc.dev/components/color-picker/markdown): A swatch that grows into a picker with format morphing, eyedropper, saved swatches, and contrast readout.
- [Emoji picker](https://uiarc.dev/components/emoji-picker/markdown): A full emoji picker with instant search, scroll-synced categories, skin tones, recently used emoji, and a virtualized, keyboard-navigable grid.

### Guidance for AI tools

Time picker: Choose a time with sensible keyboard behavior. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Color picker

> A swatch that grows into a picker with format morphing, eyedropper, saved swatches, and contrast readout.

- Type: Component (inputs)
- Access: Free, open source
- Page: https://uiarc.dev/components/color-picker
- Markdown: https://uiarc.dev/components/color-picker/markdown
- Registry item: https://uiarc.dev/r/color-picker.json
- Source file: `registry/components/color-picker/color-picker.tsx`
- Dependencies: motion, lucide-react
- Keywords: inputs, new, react color picker, hex color input, oklch color picker, hsl picker, eyedropper, color contrast checker, color swatches, alpha color picker

### When to use

- Theme editors and brand settings where users choose an exact color.
- Design tools that need hex, RGB, HSL, and OKLCH input plus opacity.
- Any color choice where contrast against a background should be visible while picking.

### When not to use

- Use segmented-control or radio-group when the choice is between a few fixed colors.
- Use input for a plain hex field with no visual picking.
- Use chip-group for tagging items with a small preset palette.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/color-picker
pnpm dlx shadcn@latest add @uiarc/color-picker
yarn dlx shadcn@latest add @uiarc/color-picker
bunx --bun shadcn@latest add @uiarc/color-picker
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/color-picker.json
```

#### Manual

1. Install the dependencies:

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

2. Copy the source into your project. Main file: `registry/components/color-picker/color-picker.tsx`

   The source is in the registry item: https://uiarc.dev/r/color-picker.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { useState } from "react";
import { ColorPicker } from "@/components/arc/color-picker/color-picker";
import type { ColorSwatch } from "@/components/arc/color-picker/color-picker";

export function BrandColor() {
  const [color, setColor] = useState("#2F6BFF");
  const [swatches, setSwatches] = useState<ColorSwatch[]>([
    { id: "ink", color: "#17171A" },
    { id: "sky", color: "#3A8DFF" },
  ]);

  return (
    <ColorPicker
      label="Accent"
      value={color}
      onValueChange={setColor}
      background="#FFFFFF"
      swatches={swatches}
      onSwatchesChange={setSwatches}
    />
  );
}
```

### API reference

#### ColorPicker

A swatch trigger that grows into a picker with a saturation area, hue and opacity sliders, a typed value, contrast readout, and saved swatches.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `string` | – | Controlled color in hex, rgb(), hsl(), or oklch(). |
| `defaultValue` | `string` | `"#2F6BFF"` | Uncontrolled starting color. |
| `onValueChange` | `(hex: string) => void` | – | Receives the color as uppercase hex, with two alpha digits when it is not opaque. |
| `background` | `string` | `"#FFFFFF"` | The background the color will sit on, for the WCAG contrast readout. |
| `label` | `string` | `"Color"` | Name shown on the swatch, such as "Accent". |
| `swatches` | `ColorSwatch[]` | – | Controlled saved swatches: { id, color }. |
| `defaultSwatches` | `ColorSwatch[]` | – | Uncontrolled starting swatches. Defaults to none. |
| `onSwatchesChange` | `(swatches: ColorSwatch[]) => void` | – | Called when swatches are added, reordered, or removed. |
| `maxSwatches` | `number` | `7` | Most saved swatches. Saving past it drops the oldest. |
| `defaultFormat` | `"hex" \| "rgb" \| "hsl" \| "oklch"` | `"hex"` | Format shown in the text field first. |
| `className` | `string` | – | Extra class on the root. |

#### parseColor

Reads hex, rgb(), hsl(), and oklch() in modern or comma syntax into { h, s, v, a }. Returns null for anything else.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `input` (required) | `string` | – | Color text. |
| `hue` | `number` | `0` | Hue to keep for grays, where hue is undefined. |

#### toHex

Formats { h, s, v, a } as uppercase hex, adding alpha digits below full opacity.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `hsva` (required) | `Hsva` | – | Hue in degrees, saturation, value, and alpha from 0 to 1. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Arrow keys | Move the saturation and brightness thumb in 2D, or the focused hue or opacity slider; Shift takes steps of ten. |
| PageUp / PageDown | Step a slider by ten. |
| Home / End | Move a slider to its minimum or maximum; in the swatch row, jump to the first or last swatch. |
| Enter | Applies the typed value in the text field; an invalid value shakes the field and shows an error. |
| Alt + ArrowLeft / ArrowRight | Moves the focused swatch. |
| Delete / Backspace | Removes the focused swatch. |
| Escape | Discards a typed draft first, then closes the panel and returns focus to the trigger. |

### Accessibility

- The trigger has aria-haspopup="dialog" and aria-expanded; the panel is a labelled dialog that turns inert while closing.
- The area thumb is a role="slider" with aria-roledescription="2D slider" and a value text naming saturation and brightness; hue and opacity are sliders with degree and percent value texts.
- The text field sets aria-invalid and points to a polite error message; the contrast ratio and its WCAG grade are also written out for screen readers.
- Saved swatches are a horizontal listbox with a roving tabindex, aria-selected on the current color, and labels that explain move and delete.

### Motion

- The panel grows out of the swatch with an animated clip-path inset on a spring, and its drop shadow follows the clipped shape.
- Thumbs chase the pointer on a quick spring with slight bounce, and the contrast ratio counts to its new value.
- The format button morphs the text between hex, RGB, HSL, and OKLCH with text-morph; swatches pop in and reorder with layout springs.
- Reduced motion jumps the thumbs, fades the panel instead of clipping it, and skips the format morph and shake.

### Responsive behavior

- The panel is min(19rem, 100vw - 32px) wide and opens down and to the right of the swatch, so leave room there.
- Below 360px viewport width the "against background" caption hides to keep the contrast row on one line.
- The area and sliders use touch-action: none with pointer capture, so dragging on touch never scrolls the page.

### Performance

- Colors are converted in plain math (HSV, HSL, OKLCH) with no color library.
- The panel mounts only while open, and a ResizeObserver measures it for the clip-path animation.
- Thumbs animate motion values, so dragging does not re-render the slider tracks.

### Notes for AI

- Use for picking a single brand or theme color with an alpha channel. onValueChange always returns hex; parse it elsewhere if you need another format.
- Pass the real surface color as background so the contrast readout reflects where the color will be used.
- The eyedropper button appears only where window.EyeDropper exists (Chromium desktop).
- Imports TextMorph from the Arc text-morph component, so install that alongside it.

### Related

- [Text morph](https://uiarc.dev/components/text-morph/markdown): Morph a label into its next state, letter by letter.
- [Slider](https://uiarc.dev/components/slider/markdown): Pick a value or a range on a track that follows your finger.
- [Popover](https://uiarc.dev/components/popover/markdown): A small anchored surface for contextual information.
- [Segmented control](https://uiarc.dev/components/segmented-control/markdown): Switch between a small set of related views.

### Also in pickers

- [Calendar](https://uiarc.dev/components/calendar/markdown): Browse dates in a clear, compact month view.
- [Date picker](https://uiarc.dev/components/date-picker/markdown): Choose a date without losing context.
- [Date range picker](https://uiarc.dev/components/date-range-picker/markdown): A range picker that grows from its trigger into two months with presets and a stretching range highlight.
- [Time picker](https://uiarc.dev/components/time-picker/markdown): Choose a time with sensible keyboard behavior.
- [Emoji picker](https://uiarc.dev/components/emoji-picker/markdown): A full emoji picker with instant search, scroll-synced categories, skin tones, recently used emoji, and a virtualized, keyboard-navigable grid.

### Guidance for AI tools

Color picker: A swatch that grows into a picker with format morphing, eyedropper, saved swatches, and contrast readout. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Emoji picker

> A full emoji picker with instant search, scroll-synced categories, skin tones, recently used emoji, and a virtualized, keyboard-navigable grid.

- Type: Component (inputs)
- Access: Arc Pro
- Page: https://uiarc.dev/components/emoji-picker
- Markdown: https://uiarc.dev/components/emoji-picker/markdown
- Source file: `registry/components/emoji-picker/emoji-picker.tsx`
- Dependencies: motion, lucide-react
- Keywords: input, picker, emoji, new, emoji picker, emoji keyboard, smiley, emoticon, skin tone, recent emoji, frequently used, chat, composer, insert emoji, reaction picker

### When to use

- Message composers, comment boxes, and chat inputs.
- Choosing an emoji for a status, a project, a page icon, or a label.
- Any text field where people expect the full emoji set with search.

### When not to use

- Use reactions for a small, fixed set of quick responses on a post or comment.
- Use combobox or a select when the choices are a short, known list.
- Do not use it as an icon picker; emoji render differently on every platform.

### Installation

Emoji picker is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/emoji-picker
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { EmojiPicker } from "@/components/arc/emoji-picker/emoji-picker";
import { Popover, PopoverContent, PopoverTrigger } from "@/components/arc/popover/popover";

export function EmojiButton({ onInsert }: { onInsert: (emoji: string) => void }) {
  const [open, setOpen] = useState(false);
  return (
    <Popover open={open} onOpenChange={setOpen}>
      <PopoverTrigger aria-label="Add emoji"><SmilePlus /></PopoverTrigger>
      <PopoverContent side="top" style={{ padding: 0, width: "min(22rem, calc(100vw - 20px))" }}>
        <EmojiPicker
          onSelect={(selection, event) => {
            onInsert(selection.emoji);
            if (!event.shiftKey) setOpen(false);
          }}
        />
      </PopoverContent>
    </Popover>
  );
}
```

### API reference

#### EmojiPicker

A full emoji picker: instant search over names and keywords, category tabs whose indicator follows your scroll, skin tones, recently used emoji remembered on the device, a preview row with the emoji name, and a virtualized grid that is fully usable from the keyboard. Ships its own dataset of every emoji up to Emoji 15.0. It has no chrome of its own, so it drops into a popover, sheet, or card.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `onSelect` | `(selection: EmojiSelection, event: MouseEvent \| KeyboardEvent) => void` | – | Called when an emoji is chosen by click, Enter, or Space. selection has emoji (with the skin tone applied), base, name, and skinTone. Check event.shiftKey to keep a popover open for several picks. |
| `skinTone` | `0 \| 1 \| 2 \| 3 \| 4 \| 5` | – | Controlled skin tone: 0 is the default yellow, 1 to 5 go from light to dark. |
| `defaultSkinTone` | `0 \| 1 \| 2 \| 3 \| 4 \| 5` | – | Skin tone before anything has been stored. |
| `onSkinToneChange` | `(tone: SkinTone) => void` | – | Called when a tone is chosen in the tone menu. |
| `storageKey` | `string \| null` | `"arc-emoji-picker"` | localStorage key for recent emoji and the tone. Pass null to keep them in memory for this page only. Blocked storage falls back to memory automatically. |
| `recentLimit` | `number` | `27` | How many recently used emoji to keep. |
| `defaultRecent` | `string[]` | `18 popular emoji` | Shown under Popular until something has been picked. |
| `columns` | `number` | – | Emoji per row. Defaults to as many 36px cells as fit, at least 6. |
| `autoFocus` | `boolean` | `false` | Focuses the search field on mount. Popovers and dialogs usually focus it already. |
| `searchPlaceholder` | `string` | `"Search emoji"` | Placeholder of the search field. |
| `label` | `string` | `"Emoji picker"` | Accessible name of the picker group. |
| `className` | `string` | – | Class on the root. Set --emoji-picker-width and --emoji-picker-height to size it (352px by 408px by default). |
| `style` | `CSSProperties` | – | Styles on the root. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Type | Filters every emoji by name and keyword; the best match is ready for Enter. Typing while the grid has focus goes to the search field. |
| Enter | In the search field, picks the highlighted emoji. In the grid, picks the active emoji. |
| Arrow Down | From the search field, moves into the grid. |
| Arrow keys | Move through the grid. Up and down keep the column across sections; Up from the first row returns to search. |
| Home / End | First or last emoji in the row. With Ctrl or Cmd, first or last emoji overall. |
| Page Up / Page Down | Moves a screen of rows. |
| Space | Picks the active emoji in the grid. |
| Arrow Left / Arrow Right | In the category bar, moves between categories; Enter jumps to one. In the tone menu, moves between tones. |
| Escape | Closes the tone menu, then clears the search, then closes the surrounding popover. |

### Accessibility

- The grid is role="grid" with rows and gridcells named after each emoji; section names are column headers. The active cell is exposed with aria-activedescendant from the search field while searching, and from the grid while it has focus, so the active emoji is announced as it moves.
- Only the rows in view are rendered, plus the active row, so aria-activedescendant always points at a real element. Rows carry aria-rowindex and the grid aria-rowcount.
- The number of results is announced in a polite live region while searching, including when nothing matches.
- The category bar is a toolbar with one tab stop; the category in view is marked with aria-current. The tone control is a button with aria-expanded that opens a radiogroup of six named tones.
- Escape is handled on window in the capture phase and marked as handled only when it closes the tone menu or clears the search, so the first Escape never closes a surrounding Radix popover by accident.
- The preview row repeats the active emoji's name for sighted users and is hidden from assistive technology.

### Motion

- The category indicator slides to the category under the top edge on the morph spring as you scroll. When a tab is pressed it goes straight there and waits while the list scrolls smoothly to the category, instead of stepping through every category in between.
- The skin tone menu unrolls leftward out of the tone button on a clip-path inset, and rolls back into it; the inset is a CSS transition, so a quick close reverses mid-way.
- The preview emoji settles in from a slight scale on each change; a pressed emoji dips and springs back.
- Search results appear instantly, with no animation, so typing always feels immediate.
- With reduced motion the indicator and tone menu move at once, scrolling to a category jumps, and the preview does not scale.

### Responsive behavior

- The grid picks its column count from the width, keeping cells at least 36px, so it goes from 9 columns at 352px to 7 in a narrow phone popover.
- The default size is 352 by 408px and it never exceeds its container; set --emoji-picker-width and --emoji-picker-height to change it.
- Hover previews only follow a mouse pointer; on touch a tap picks the emoji directly.

### Performance

- The dataset is about 73 kB of compact strings (1,870 emoji with names, keywords, and skin tone positions) parsed once on first use, then shared by every picker on the page.
- The grid is virtualized: only the rows in view plus a small overscan are rendered, so scrolling the whole set stays light.
- Search scans precomputed lowercase strings and is memoized per query.
- Skin tones are applied when a cell renders, so there is no second dataset for toned variants.

### Notes for AI

- Put it in a popover next to the input it fills. Remember the input's selection and insert at it, then move the caret after the emoji; see the composer demo.
- The picker has no border, background, or padding of its own. Give the popover padding: 0 so the grid runs edge to edge.
- Keep the popover open when Shift is held for several picks in a row, and close it otherwise.
- The dataset covers Emoji 15.0, which renders on current Apple, Google, and Microsoft platforms. Older systems may show a few newer emoji as boxes.
- Use onSkinToneChange with skinTone to sync the tone with a user profile; otherwise it is remembered in localStorage with the recent emoji.

### Related

- [Reactions](https://uiarc.dev/components/reactions/markdown): Acknowledge a post in one tap, with counts that roll.
- [Popover](https://uiarc.dev/components/popover/markdown): A small anchored surface for contextual information.
- [Combobox](https://uiarc.dev/components/combobox/markdown): Search and select from a list without leaving the field.
- [Textarea](https://uiarc.dev/components/textarea/markdown): A multiline field for notes, descriptions, and longer text.
- [Mention input](https://uiarc.dev/components/mention-input/markdown): A textarea with @people and #channel mentions that act as single tokens, with suggestions at the caret.
- [Rich text editor](https://uiarc.dev/components/rich-text-editor/markdown): A lightweight editor with markdown shortcuts, a floating toolbar, a slash menu, and HTML and markdown output.

### Also in pickers

- [Calendar](https://uiarc.dev/components/calendar/markdown): Browse dates in a clear, compact month view.
- [Date picker](https://uiarc.dev/components/date-picker/markdown): Choose a date without losing context.
- [Date range picker](https://uiarc.dev/components/date-range-picker/markdown): A range picker that grows from its trigger into two months with presets and a stretching range highlight.
- [Time picker](https://uiarc.dev/components/time-picker/markdown): Choose a time with sensible keyboard behavior.
- [Color picker](https://uiarc.dev/components/color-picker/markdown): A swatch that grows into a picker with format morphing, eyedropper, saved swatches, and contrast readout.

### Guidance for AI tools

Emoji picker: A full emoji picker with instant search, scroll-synced categories, skin tones, recently used emoji, and a virtualized, keyboard-navigable grid. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Rich text editor

> A lightweight editor with markdown shortcuts, a floating toolbar, a slash menu, and HTML and markdown output.

- Type: Component (inputs)
- Access: Free, open source
- Page: https://uiarc.dev/components/rich-text-editor
- Markdown: https://uiarc.dev/components/rich-text-editor/markdown
- Registry item: https://uiarc.dev/r/rich-text-editor.json
- Source file: `registry/components/rich-text-editor/rich-text-editor.tsx`
- Dependencies: motion, lucide-react
- Keywords: inputs, new, react rich text editor, markdown editor, wysiwyg editor, slash command menu, floating formatting toolbar, contenteditable editor, notion style editor, lightweight text editor

### When to use

- Comments, notes, and posts where people expect markdown shortcuts and a selection toolbar.
- Forms that need Markdown or clean HTML out without pulling in a full editor framework.
- Short to medium documents with headings, lists, quotes, and code blocks.

### When not to use

- Use textarea for plain text, or mention-input when the only rich part is tagging people.
- Use inline-edit for a single line edited in place.
- Use code-block to display code, not to write prose.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/rich-text-editor
pnpm dlx shadcn@latest add @uiarc/rich-text-editor
yarn dlx shadcn@latest add @uiarc/rich-text-editor
bunx --bun shadcn@latest add @uiarc/rich-text-editor
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/rich-text-editor.json
```

#### Manual

1. Install the dependencies:

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

2. Copy the source into your project. Main file: `registry/components/rich-text-editor/rich-text-editor.tsx`

   The source is in the registry item: https://uiarc.dev/r/rich-text-editor.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { useState } from "react";
import { RichTextEditor, type RichTextValue } from "@/components/arc/rich-text-editor/rich-text-editor";

export function PostEditor() {
  const [doc, setDoc] = useState<RichTextValue | null>(null);
  return (
    <>
      <RichTextEditor
        aria-label="Post body"
        placeholder="Write your update"
        defaultMarkdown={"# Release notes\n\n- Faster search\n- New **dark** theme"}
        onChange={setDoc}
      />
      <button type="button" disabled={!doc || doc.empty} onClick={() => save(doc!.markdown)}>
        Publish
      </button>
    </>
  );
}

declare function save(markdown: string): void;
```

### Examples

#### Controlled HTML with custom undo buttons

```tsx
const editor = useRef<RichTextEditorHandle>(null);
const [html, setHtml] = useState("<p>Draft</p>");
const [history, setHistory] = useState({ canUndo: false, canRedo: false });

<>
  <button type="button" disabled={!history.canUndo} onClick={() => editor.current?.undo()}>Undo</button>
  <button type="button" disabled={!history.canRedo} onClick={() => editor.current?.redo()}>Redo</button>
  <RichTextEditor ref={editor} value={html} onChange={value => setHtml(value.html)} onHistoryChange={setHistory} />
</>
```

### API reference

#### RichTextEditor

A light rich text editor on contentEditable with markdown shortcuts, a floating selection toolbar that morphs into a link field, a slash menu for blocks, its own undo history, and HTML plus Markdown output.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `string` | – | Controlled HTML. The editor only rewrites its content when this differs from what it last emitted. |
| `defaultValue` | `string` | – | Initial HTML when uncontrolled. Sanitized on load. |
| `defaultMarkdown` | `string` | – | Initial content as Markdown, used when no HTML value is given. |
| `onChange` | `(value: RichTextValue) => void` | – | Called after each edit with { html, markdown, text, empty }. HTML is clean: canonical tags and only href attributes. |
| `onHistoryChange` | `(state: { canUndo: boolean; canRedo: boolean }) => void` | – | Reports whether undo and redo are available, for your own toolbar. |
| `placeholder` | `string` | `"Start writing"` | Shown when the editor is empty. |
| `blockHint` | `string` | `"Type / for blocks"` | The hint on an empty line while the caret is in it. |
| `readOnly` | `boolean` | `false` | Turns off editing, the toolbar, and shortcuts. |
| `autoFocus` | `boolean` | `false` | Focuses the editor on mount with the caret at the end. |
| `aria-label` | `string` | `"Editor"` | Accessible name of the textbox. |
| `className` | `string` | – | Extra class on the root. |
| `style` | `CSSProperties` | – | Inline style on the root. |

#### RichTextEditorHandle

Methods on the ref.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `focus` | `() => void` | – | Focuses the editor. |
| `getHTML` | `() => string` | – | Clean HTML of the current content. |
| `getMarkdown` | `() => string` | – | Current content as Markdown. |
| `getText` | `() => string` | – | Plain text, one block per line. |
| `setHTML` | `(html: string) => void` | – | Replaces the content with sanitized HTML as one undo step. |
| `setMarkdown` | `(markdown: string) => void` | – | Replaces the content from Markdown as one undo step. |
| `clear` | `() => void` | – | Empties the editor as one undo step. |
| `undo` | `() => void` | – | Steps back in the editor's own history. |
| `redo` | `() => void` | – | Steps forward in the editor's own history. |
| `element` | `HTMLDivElement \| null` | – | The contentEditable element. |

#### markdownToHtml

Converts Markdown to the editor's HTML: headings (levels four to six become h3), lists with nesting, quotes, fenced code, rules, and inline bold, italic, strike, code, and links.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `markdown` (required) | `string` | – | Markdown source. |

#### htmlToMarkdown

Converts editor HTML, or an element, to Markdown. Browser only.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `input` (required) | `string \| HTMLElement` | – | HTML string or element. |

#### sanitizeHtml

Keeps only the tags the editor understands and drops every attribute except safe link hrefs (http, https, mailto, tel, relative, hash). Bold and italic spans from other editors become marks. Browser only.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `html` (required) | `string` | – | Untrusted HTML. |

#### normalizeUrl

Adds a scheme to bare input: example.com/docs becomes https://example.com/docs and an email becomes a mailto link.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `input` (required) | `string` | – | What the person typed. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Cmd/Ctrl+B | Toggles bold. |
| Cmd/Ctrl+I | Toggles italic. |
| Cmd/Ctrl+Shift+X | Toggles strikethrough. |
| Cmd/Ctrl+E | Toggles inline code within one block. |
| Cmd/Ctrl+K | Opens the link field for the selection or the link under the caret. |
| Cmd/Ctrl+Z / Cmd/Ctrl+Shift+Z / Cmd/Ctrl+Y | Undo and redo in the editor's own history. Underline (Cmd/Ctrl+U) is blocked. |
| / | After a space or at line start, opens the block menu. Type to filter; Arrow Up and Down move, Enter or Tab chooses, Escape closes. |
| Tab / Shift+Tab | Indents or outdents a list item; in a code block Tab inserts two spaces. |
| Enter / Shift+Enter | New block or a line break. Enter on an empty list item or quote leaves it; two Enters at the end of a code block exit it. |
| Backspace | At the start of a heading, quote, code block, or list item, turns it back into a paragraph or outdents it; after a divider, removes the divider. |
| Alt+F10 | Moves focus into the floating toolbar while it is open. Arrow Left and Right move between buttons; Escape returns to the text. |

### Accessibility

- The editing surface has role textbox with aria-multiline and aria-label, and aria-readonly when read-only.
- The slash menu is a listbox wired to the textbox with aria-controls and aria-activedescendant.
- The floating toolbar has role toolbar with toggle buttons using aria-pressed; titles show shortcuts.
- A polite live region announces Formatted, Link added, Undone, and similar results.
- Toolbar buttons prevent mousedown so the text selection survives clicks.

### Motion

- The toolbar glides with the selection and its surface springs between the formatting face and the link face, which slide and blur across each other.
- The slash menu pops from the slash, its highlight glides between rows, and its height springs as results filter.
- Reduced motion jumps the toolbar position and size, crossfades the faces, and fades menus without scale or offset.

### Responsive behavior

- The root is an inline-size container; under 330px wide the toolbar hides its heading and quote buttons and keeps the inline marks.
- The toolbar and slash menu flip above or below based on the nearest scrolling or clipping ancestor, and the toolbar is clamped inside the editor width.
- Enter, Backspace, and undo go through beforeinput, so mobile keyboards and IME composition behave the same as hardware keys.

### Performance

- Each selection change is batched to one requestAnimationFrame; each edit clones the DOM once to produce HTML, Markdown, and text for onChange.
- Undo keeps up to 300 HTML snapshots, merging typing within one second; very long documents make each snapshot and the per-edit clone more costly.
- No editor framework: only motion and lucide-react icons ship with it.

### Notes for AI

- Choose it for comments, notes, posts, and descriptions that need headings, lists, quotes, code, and links. Use textarea for plain text and mention-input when the only structure is @ mentions.
- Store onChange markdown or html; both are clean. The value prop is HTML and only rewrites the DOM when it differs from the last emitted HTML, so feeding onChange html back is safe.
- Supported blocks are p, h1 to h3, ul, ol, blockquote, pre, and hr; inline marks are strong, em, s, code, and a. Images, tables, and underline are not supported.
- Paste runs through sanitizeHtml, and markdown-looking plain text is converted, so content from docs and other editors stays tidy.
- Build your own undo buttons with onHistoryChange and ref.undo and ref.redo.

### Related

- [Textarea](https://uiarc.dev/components/textarea/markdown): A multiline field for notes, descriptions, and longer text.
- [Mention input](https://uiarc.dev/components/mention-input/markdown): A textarea with @people and #channel mentions that act as single tokens, with suggestions at the caret.
- [Code block](https://uiarc.dev/components/code-block/markdown): Present code with legible hierarchy and copy access.
- [Inline edit](https://uiarc.dev/components/inline-edit/markdown): Rename in place: the text becomes a field without moving.

### Also in editors

- [Signature pad](https://uiarc.dev/components/signature-pad/markdown): Smooth ink that thins with speed, with undo, replay, and PNG or SVG export.
- [File dropzone](https://uiarc.dev/components/file-dropzone/markdown): A generous target for dropping one or more files.
- [Avatar upload](https://uiarc.dev/components/avatar-upload/markdown): Click or drop a photo onto the avatar to crop it in place with drag, pinch and zoom. It uploads through a progress ring and settles, with clear errors and retry.

### Guidance for AI tools

Rich text editor: A lightweight editor with markdown shortcuts, a floating toolbar, a slash menu, and HTML and markdown output. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Signature pad

> Smooth ink that thins with speed, with undo, replay, and PNG or SVG export.

- Type: Component (inputs)
- Access: Free, open source
- Page: https://uiarc.dev/components/signature-pad
- Markdown: https://uiarc.dev/components/signature-pad/markdown
- Registry item: https://uiarc.dev/r/signature-pad.json
- Source file: `registry/components/signature-pad/signature-pad.tsx`
- Dependencies: motion, lucide-react
- Keywords: inputs, new, react signature pad, signature capture, draw signature, e-signature field, pressure sensitive ink, signature to png, sign here component

### When to use

- Contracts, delivery confirmations, and consent forms that need a drawn signature.
- Initials or quick sketches where pen pressure and natural stroke width matter.
- Flows that need a clean, cropped PNG or SVG of the signature.

### When not to use

- Use input for a typed name when a legal drawn signature is not required.
- Use file-upload when the user already has a scanned signature image.
- Use hold-to-confirm for a simple deliberate confirmation without a signature artifact.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/signature-pad
pnpm dlx shadcn@latest add @uiarc/signature-pad
yarn dlx shadcn@latest add @uiarc/signature-pad
bunx --bun shadcn@latest add @uiarc/signature-pad
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/signature-pad.json
```

#### Manual

1. Install the dependencies:

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

2. Copy the source into your project. Main file: `registry/components/signature-pad/signature-pad.tsx`

   The source is in the registry item: https://uiarc.dev/r/signature-pad.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { useState } from "react";
import { SignaturePad, signatureToSvg } from "@/components/arc/signature-pad/signature-pad";
import type { InkStroke } from "@/components/arc/signature-pad/signature-pad";

export function SignContract() {
  const [strokes, setStrokes] = useState<InkStroke[]>([]);

  return (
    <form onSubmit={event => { event.preventDefault(); submit(signatureToSvg(strokes)); }}>
      <SignaturePad signer="Ada Lovelace" fileName="ada-signature" onChange={setStrokes} />
      <button type="submit" disabled={!strokes.length}>Sign</button>
    </form>
  );
}
```

### API reference

#### SignaturePad

A signature field with pressure-sensitive ink, undo and redo, a wipe to clear, replay, and PNG or SVG export.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `signer` | `string` | – | Printed under the baseline, such as the signer's name. |
| `hint` | `string` | `"Sign here"` | Resting hint on the baseline before the first stroke. |
| `defaultColor` | `"black" \| "blue" \| "violet"` | `"black"` | Starting ink color. |
| `defaultWidth` | `"fine" \| "medium" \| "bold"` | `"medium"` | Starting nib width. |
| `onChange` | `(strokes: InkStroke[]) => void` | – | Receives the strokes after every change, including undo, redo, and clear. |
| `fileName` | `string` | `"signature"` | File name for exports, without extension. |
| `label` | `string` | `"Signature pad"` | Accessible name of the drawing surface. |
| `className` | `string` | – | Extra class on the root. |

#### signatureToSvg

Returns a standalone SVG string of the strokes, cropped to the ink with print ink colors. Empty string for no strokes.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `strokes` (required) | `InkStroke[]` | – | Strokes as received from onChange. |

#### signatureToPng

Resolves to a transparent PNG Blob cropped to the ink. Rejects when there are no strokes.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `strokes` (required) | `InkStroke[]` | – | Strokes as received from onChange. |
| `scale` | `number` | `3` | Multiple of the 600 by 260 pad resolution. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Mod + Z | Undoes the last change while the pad is focused. |
| Shift + Mod + Z / Mod + Y | Redoes. |
| Delete / Backspace | Clears the signature with the wipe; undo brings it back. |
| Escape | Stops a replay in progress. |
| Arrow keys | Move between ink colors or nib widths inside each radio group. |

### Accessibility

- The pad is focusable with role="img", aria-roledescription="signature pad", and a label that states the stroke count.
- Keyboard shortcuts are described through aria-describedby on a visually hidden paragraph.
- Ink color and width are radio groups with roving tabindex; toolbar icon buttons carry aria-label and title.
- A polite status region announces strokes added, undo, redo, clear, replay, and export results.

### Motion

- Clear sweeps a squeegee edge across the pad while a clip-path wipe removes the ink over 0.56s.
- Replay redraws each stroke in its original rhythm with a nib dot, capping gaps between strokes and fitting the whole replay into about 3.2s.
- The hint fades up from a soft blur; the selected color and width highlight glides with a shared layout spring.
- Reduced motion skips the wipe and blur and uses short opacity fades.

### Responsive behavior

- The pad keeps a 600 / 260 aspect ratio at every width, and strokes scale with it.
- touch-action: none on the pad keeps finger strokes from scrolling the page; coalesced pointer events capture fast strokes on touch and pen.
- The toolbar wraps on narrow widths; hover styles apply only on hover-capable fine pointers.

### Performance

- The live stroke writes its SVG path directly to the DOM on each pointer move, without a React render.
- History keeps the last 60 states; replay runs a rAF loop that re-renders the visible strokes each frame, so very long signatures cost more to replay.
- PNG export draws to an offscreen canvas at 3x by default.

### Notes for AI

- Use for capturing a handwritten signature or initials. Store the InkStroke[] from onChange, or convert it with signatureToSvg or signatureToPng on submit.
- Strokes are stored in a 600 by 260 coordinate space (PAD_WIDTH, PAD_HEIGHT), so they scale with the pad and can be replayed later.
- getStrokeOutline, outlineToPath, and strokePath are also exported if you need the raw outline math.
- The pad is uncontrolled; to reset it, remount it with a new key.

### Related

- [File upload](https://uiarc.dev/components/blocks/file-upload/markdown): A complete file selection flow with constraints, progress, and error feedback.
- [Multi-step form](https://uiarc.dev/components/blocks/multi-step-form/markdown): A guided form that presents one decision at a time and preserves progress.
- [Hold to confirm](https://uiarc.dev/components/hold-to-confirm/markdown): Confirm a destructive action by holding, not tapping.
- [Input](https://uiarc.dev/components/input/markdown): A single line field with clear labels and useful states.

### Also in editors

- [Rich text editor](https://uiarc.dev/components/rich-text-editor/markdown): A lightweight editor with markdown shortcuts, a floating toolbar, a slash menu, and HTML and markdown output.
- [File dropzone](https://uiarc.dev/components/file-dropzone/markdown): A generous target for dropping one or more files.
- [Avatar upload](https://uiarc.dev/components/avatar-upload/markdown): Click or drop a photo onto the avatar to crop it in place with drag, pinch and zoom. It uploads through a progress ring and settles, with clear errors and retry.

### Guidance for AI tools

Signature pad: Smooth ink that thins with speed, with undo, replay, and PNG or SVG export. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## File dropzone

> A generous target for dropping one or more files.

- Type: Component (inputs)
- Access: Free, open source
- Page: https://uiarc.dev/components/file-dropzone
- Markdown: https://uiarc.dev/components/file-dropzone/markdown
- Registry item: https://uiarc.dev/r/file-dropzone.json
- Source file: `registry/components/file-dropzone/file-dropzone.tsx`
- Dependencies: motion, lucide-react
- Keywords: field, files, react file upload, file dropzone, drag and drop upload, upload with progress, file uploader, dropzone component, multi file upload

### When to use

- Attachments and uploads with drag and drop plus a file picker.
- Uploads that need per-file progress, retry, and cancel through onUpload.

### When not to use

- Use input with type file only when a native picker with no list is enough.
- Use empty-state when the drop area is the only thing on an empty page and needs a larger call to action.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/file-dropzone
pnpm dlx shadcn@latest add @uiarc/file-dropzone
yarn dlx shadcn@latest add @uiarc/file-dropzone
bunx --bun shadcn@latest add @uiarc/file-dropzone
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/file-dropzone.json
```

#### Manual

1. Install the dependencies:

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

2. Copy the source into your project. Main file: `registry/components/file-dropzone/file-dropzone.tsx`

   The source is in the registry item: https://uiarc.dev/r/file-dropzone.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { FileDropzone } from "@/components/arc/file-dropzone/file-dropzone";

export function AttachmentUpload() {
  return (
    <FileDropzone
      accept=".pdf,image/*"
      maxFiles={3}
      maxSize={10 * 1024 * 1024}
      onUpload={async (item, { onProgress, signal }) => {
        await uploadFile(item.file!, { onProgress, signal });
      }}
    />
  );
}
```

### Examples

#### Folding prompt with a size limit

```tsx
<FileDropzone
  label="Add receipts"
  accept="image/*,.pdf"
  maxFiles={10}
  maxSize={5 * 1024 * 1024}
  compactAt={2}
  listPlacement="inside"
  onFilesChange={setFiles}
/>
```

### API reference

#### FileDropzone

A drop target and file picker with a file list that can run uploads with progress, retry, and removal.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `accept` | `string` | – | Accepted types, as in the native accept attribute (".pdf", "image/*"). Others are rejected with an error. |
| `multiple` | `boolean` | `true` | Allow several files. |
| `maxFiles` | `number` | `5` | Most files the list holds. |
| `onFilesChange` | `(files: File[]) => void` | – | Called with the selected File objects whenever the list changes. |
| `label` | `string` | `"Add files"` | Main prompt on the drop target. |
| `description` | `string` | `"Drop files here or choose from your device"` | Secondary prompt. |
| `defaultItems` | `FileDropzoneItem[]` | – | Rows present at mount, such as earlier uploads. They render without an entrance. |
| `onUpload` | `(item: FileDropzoneItem, options: { onProgress: (percent: number) => void; signal: AbortSignal }) => Promise<void>` | – | Uploads each added file. Report progress, resolve on success, reject with an Error whose message becomes the row's reason. Removing a row aborts the signal. |
| `maxSize` | `number` | – | Bytes. Larger files fail with a size reason and never upload. |
| `listPlacement` | `"below" \| "inside"` | `"below"` | Render the list under the target or inside its edge. |
| `note` | `string` | – | Replaces the small line under the description (defaults to accepted types or the file limit). |
| `dropLabel` | `string` | – | Label while files hover over the target. |
| `compactAt` | `number` | – | Once the list holds this many files, the prompt folds to a slim bar. |

#### FileDropzoneItem

One row in the list, used by defaultItems and onUpload.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `id` (required) | `string` | – | Stable id. |
| `name` (required) | `string` | – | File name; its extension picks the type icon. |
| `size` (required) | `number` | – | Bytes. |
| `status` | `FileDropzoneStatus` | – | Upload state of the row. |
| `progress` | `number` | – | Upload percent. |
| `error` | `string` | – | Failure reason shown on the row. |
| `retryable` | `boolean` | – | Shows a retry button when failed. |
| `file` | `File` | – | The File, for items the visitor added. |
| `preview` | `string` | – | Thumbnail URL shown instead of the type icon. Image files added by the visitor get an object URL automatically, revoked when the row is removed or the component unmounts. Falls back to the icon if the image fails. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Enter / Space | On the drop target, opens the native file picker. |
| ArrowUp / ArrowDown | In the file list, moves focus to the same action (remove or retry) on the adjacent row. |
| Delete / Backspace | In the file list, removes the focused row. |
| ⌘ + V / Ctrl + V | Pastes files from the clipboard, such as a screenshot, while the pointer is over the dropzone or focus is inside it. Ignored inside text fields. |

### Accessibility

- The target is a native button; the hidden file input is removed from the tab order.
- Uploading rows expose role="progressbar" with aria-valuenow; remove and retry buttons are labelled with the file name.
- Additions, completions, and failures are announced through a polite role="status" region; rejection errors use role="alert".
- Removing a row moves focus to a neighbouring row so keyboard users are not dropped.

### Motion

- The icon lifts while files hover, the edge animates, rows enter and collapse on a smooth spring, and progress bars ease toward their target.
- Reduced motion replaces height and lift animations with short fades and keeps progress changes instant.

### Responsive behavior

- The file list is a container query: below 440px retry becomes icon-only, and below 300px the file icon hides.
- File names and failure reasons ellipsize instead of wrapping.
- The whole target is one tap area that opens the native picker, so it works without drag and drop on touch.

### Performance

- The dashed edge is refitted by a ResizeObserver, plus a rAF loop only while the corner radius is transitioning.
- Rows are not virtualized and maxFiles defaults to 5; row entrances stagger up to eight steps.

### Notes for AI

- Use for file attachments and uploads. Without onUpload the list shows plain selections; read them from onFilesChange and submit yourself.
- Files can be dropped, picked, or pasted. Pass preview on defaultItems (for example a stored thumbnail URL) to show earlier image uploads as thumbnails.
- With onUpload, the component manages per-file status, retry, and abort; wire it to fetch or XHR and pass signal through.
- Also exports formatFileSize(bytes) and the FileDropzoneItem, FileDropzoneStatus, and FileDropzoneUpload types.

### Related

- [Progress](https://uiarc.dev/components/progress/markdown): Show how much of a known task is complete.
- [Input](https://uiarc.dev/components/input/markdown): A single line field with clear labels and useful states.
- [Empty state](https://uiarc.dev/components/empty-state/markdown): A useful next step when there is nothing to show yet.

### Also in editors

- [Rich text editor](https://uiarc.dev/components/rich-text-editor/markdown): A lightweight editor with markdown shortcuts, a floating toolbar, a slash menu, and HTML and markdown output.
- [Signature pad](https://uiarc.dev/components/signature-pad/markdown): Smooth ink that thins with speed, with undo, replay, and PNG or SVG export.
- [Avatar upload](https://uiarc.dev/components/avatar-upload/markdown): Click or drop a photo onto the avatar to crop it in place with drag, pinch and zoom. It uploads through a progress ring and settles, with clear errors and retry.

### Guidance for AI tools

File dropzone: A generous target for dropping one or more files. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Avatar upload

> Click or drop a photo onto the avatar to crop it in place with drag, pinch and zoom. It uploads through a progress ring and settles, with clear errors and retry.

- Type: Component (inputs)
- Access: Arc Pro
- Page: https://uiarc.dev/components/avatar-upload
- Markdown: https://uiarc.dev/components/avatar-upload/markdown
- Source file: `registry/components/avatar-upload/avatar-upload.tsx`
- Dependencies: motion, lucide-react
- Keywords: input, upload, image, new, avatar upload, profile photo, profile picture, photo upload, image upload, crop, circular crop, zoom, pinch, drag and drop, progress ring, upload progress, initials, account settings, change photo

### When to use

- Profile, account and team member settings where a person sets their own photo.
- Workspace or organization logos that display in a circle.
- Onboarding steps that ask for a photo and should show upload progress in place.

### When not to use

- Several files or documents at once: use file-dropzone.
- Free form crops with aspect ratios, rotation or a large canvas: use image-cropper.
- Showing an avatar without editing: use avatar.

### Installation

Avatar upload is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/avatar-upload
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { AvatarUpload } from "@/components/arc/avatar-upload/avatar-upload";

export function ProfilePhoto({ user }: { user: User }) {
  return (
    <AvatarUpload
      name={user.name}
      src={user.avatarUrl}
      onUpload={async (image, { report, signal }) => {
        const { uploadUrl, publicUrl } = await api.createAvatarUpload();
        await putWithProgress(uploadUrl, image, { onProgress: report, signal });
        await api.saveAvatar(publicUrl);
        return publicUrl;
      }}
      onRemove={() => api.removeAvatar()}
    />
  );
}
```

### API reference

#### AvatarUpload

A profile photo control. Click or drop an image on the avatar and the avatar itself grows into a circular crop stage, with the rest of the photo dimmed around the mask. Drag to reposition, scroll, pinch or use the slider to zoom, then save: the circle shrinks back with the cropped photo inset inside a progress ring, and when the upload resolves the ring closes and lets go as the photo settles to full size. Too large, wrong type and failed uploads are explained in place, with retry. Initials show when there is no photo.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `name` (required) | `string` | – | Person's name, used for the initials fallback. |
| `src` | `string` | – | Current photo URL. Changing it replaces the shown photo. |
| `onUpload` (required) | `(image: Blob, context: { report: (progress: number) => void; signal: AbortSignal; original: File }) => Promise<string \| void>` | – | Receives the cropped square image. Call report with 0 to 1 as bytes go out to fill the ring; until you do, the ring turns without a value. Resolve with the stored URL, or with nothing to keep showing the local crop. Reject to show the error message and a Try again button. signal aborts when the person cancels. |
| `onRemove` | `() => void` | – | Called after Remove. Without it the Remove button is hidden. |
| `onError` | `(error: { code: "type" \| "size" \| "decode" \| "upload"; message: string }) => void` | – | Called whenever an error message is shown, for logging or analytics. |
| `accept` | `string[]` | `["image/png", "image/jpeg", "image/webp"]` | Accepted MIME types. The default hint lists them. |
| `maxSize` | `number` | `5242880` | Largest file in bytes, 5 MB by default. Checked before the image is decoded. |
| `size` | `number` | `88` | Avatar diameter in px while not cropping. The crop circle is 184px. |
| `outputSize` | `number` | `512` | Side of the square image passed to onUpload, in px. PNGs stay PNG to keep transparency; everything else becomes JPEG at 92% quality. |
| `label` | `string` | `"Profile photo"` | Heading beside the avatar and the group's accessible name. |
| `hint` | `ReactNode` | – | Helper copy. Defaults to the accepted types and the size limit, such as PNG, JPG or WebP, up to 5 MB. |
| `disabled` | `boolean` | – | Blocks picking, dropping and removing. |
| `className` | `string` | – | Class on the root element. |
| `style` | `CSSProperties` | – | Inline styles on the root element. |
| `ref` | `Ref<AvatarUploadHandle>` | – | open() shows the file picker; selectFile(file) runs a file through the same checks as a pick or drop and opens the cropper, for your own buttons, paste handlers or camera capture. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Tab | Moves to the avatar, then Upload photo or Replace photo, then Remove. While cropping: the crop area, zoom out, the zoom slider, zoom in, Save photo, Cancel. |
| Enter / Space | On the avatar, opens the file picker. |
| Arrow keys | In the crop area, move the photo by 2% of the circle; hold Shift for 10%. |
| + / - | In the crop area, zoom in or out. |
| 0 | In the crop area, reset zoom and position. |
| Enter | In the crop area, save and upload. |
| Escape | In the crop area, cancel and return to the current photo. |

### Accessibility

- The component is a group named by its label. The avatar is a button named Change profile photo or Upload profile photo.
- Opening the cropper moves focus to the crop area, a focusable group whose name gives the zoom and every key. Saving, canceling and removing return focus to the upload button.
- The zoom slider is a native range with aria-valuetext in percent, flanked by Zoom out and Zoom in buttons.
- Errors, the uploading state, Photo updated and Photo removed appear in a polite live region; progress is announced in 25% steps. Errors pair an icon with a sentence that says what to do next.
- The photo, the dimmed overflow and the rings are decorative; the state they show is always in text as well.
- Pointer focus draws no ring; keyboard focus shows Arc's shared focus ring. Keyboard focus on the avatar shows the same camera overlay as hover.

### Motion

- Opening the cropper grows the avatar itself into the 184px crop circle with a layout animation on the smooth spring, while a tinted stage fades in behind it and the new photo fades in. The layout reflows once and the circle travels to its new place; the block's height follows on the same spring.
- Dragging tracks the pointer one to one. Past an edge the photo follows at a falling rate and never more than a quarter of the circle, then springs back inside the bounds on release. The dimmed overflow brightens while you drag, zoom or scrub the slider.
- Wheel, trackpad pinch and two finger pinch zoom toward the pointer or between the fingers, so the point you aim at stays still. The slider zooms around the centre.
- Saving shrinks the circle back, insets the cropped photo to 90% under a dim scrim and draws a 2px ring outside it. The ring turns while waiting, then fills with reported progress on the smooth spring.
- On success the ring closes, then a second full ring widens by 12% and fades over 480ms while the photo springs back to full size on the snappy spring and the scrim lifts.
- A failed upload stops the ring where it was and turns it to the danger color, keeping the pending photo inset until you retry or discard.
- With reduced motion the circle resizes at once, the photo snaps to its bounds, the settle ring is skipped and the waiting ring turns slowly.

### Responsive behavior

- At rest the avatar sits beside its label, message and buttons at every width down to 320px; below 400px the spacing tightens so Replace photo and Remove stay on one row.
- While cropping, the 248px stage sits beside the controls on wide containers and stacks above them below 480px, measured with a container query so it adapts to narrow cards as well as phones.
- The crop stage uses touch-action: none so dragging and pinching never scroll the page; the wheel is captured only over the stage.

### Performance

- The cropper moves two copies of the photo with a single transform each, in percentages of their own size, so the photo stays correct while the circle resizes and no layout runs per frame.
- The crop is drawn once into a canvas at outputSize when you save; the original file is never re-encoded before that.
- Size and type are checked before decoding, so a 12 MB file is rejected without being read into an image.

### Notes for AI

- Wire onUpload to your storage and call report from your upload progress events; the ring is only as honest as the progress you report.
- Resolve with the stored URL so the avatar shows the canonical file; object URLs made by the component are revoked when replaced and on unmount.
- Reject with an Error whose message says what happened and what is unchanged; it is shown as is.
- Keep accept and maxSize in line with your backend. The default hint is generated from them.
- Use the ref's selectFile to accept pasted images or photos from your own camera capture; they pass the same checks as a drop.
- Real portraits in the gallery demo come from public/media/people/portrait; the demo uploads nothing.

### Related

- [Avatar](https://uiarc.dev/components/avatar/markdown): A compact identity marker for people and accounts.
- [File dropzone](https://uiarc.dev/components/file-dropzone/markdown): A generous target for dropping one or more files.
- [Avatar group](https://uiarc.dev/components/avatar-group/markdown): Show a team or set of contributors in a small space.

### Also in editors

- [Rich text editor](https://uiarc.dev/components/rich-text-editor/markdown): A lightweight editor with markdown shortcuts, a floating toolbar, a slash menu, and HTML and markdown output.
- [Signature pad](https://uiarc.dev/components/signature-pad/markdown): Smooth ink that thins with speed, with undo, replay, and PNG or SVG export.

### Guidance for AI tools

Avatar upload: Click or drop a photo onto the avatar to crop it in place with drag, pinch and zoom. It uploads through a progress ring and settles, with clear errors and retry. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Tabs

> Switch between related content in the same context.

- Type: Component (disclosure)
- Access: Free, open source
- Page: https://uiarc.dev/components/tabs
- Markdown: https://uiarc.dev/components/tabs/markdown
- Registry item: https://uiarc.dev/r/tabs.json
- Source file: `registry/components/tabs/tabs.tsx`
- Dependencies: @radix-ui/react-tabs, motion, lucide-react
- Keywords: navigation, layout, react tabs, animated tabs, radix tabs, tab component, sliding tab indicator, scrollable tabs, tabs with animation

### When to use

- Peer views of the same object, such as Overview, Activity, and Settings.
- Panels with different heights, where the container should spring between them.
- Long tab sets that need to scroll horizontally with edge buttons.

### When not to use

- Use segmented-control for a compact value toggle not tied to panels.
- Use accordion for stacked sections people read in order.
- Use liquid-tab-bar or morph-nav for app-level navigation between routes.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/tabs
pnpm dlx shadcn@latest add @uiarc/tabs
yarn dlx shadcn@latest add @uiarc/tabs
bunx --bun shadcn@latest add @uiarc/tabs
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/tabs.json
```

#### Manual

1. Install the dependencies:

```bash
npm install @radix-ui/react-tabs motion lucide-react
```

2. Copy the source into your project. Main file: `registry/components/tabs/tabs.tsx`

   The source is in the registry item: https://uiarc.dev/r/tabs.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { Tabs, TabsContent, TabsList, TabsTrigger } from "@/components/arc/tabs/tabs";

export function ProjectTabs() {
  return (
    <Tabs defaultValue="overview">
      <TabsList aria-label="Project">
        <TabsTrigger value="overview">Overview</TabsTrigger>
        <TabsTrigger value="activity">Activity</TabsTrigger>
      </TabsList>
      <TabsContent value="overview">Summary and stats</TabsContent>
      <TabsContent value="activity">Recent events</TabsContent>
    </Tabs>
  );
}
```

### API reference

#### Tabs

Radix Tabs root that tracks direction so panels slide the way the selection moved.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `string` | – | Controlled active tab value. |
| `defaultValue` | `string` | – | Initial active tab when uncontrolled. |
| `onValueChange` | `(value: string) => void` | – | Called when the active tab changes. |
| `...props` | `ComponentPropsWithoutRef<typeof TabsPrimitive.Root>` | – | Other Radix root props such as activationMode and className. |

#### TabsList

Scrollable tab strip. Shows edge scroll buttons when triggers overflow and keeps the active tab in view.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `...props` | `ComponentPropsWithoutRef<typeof TabsPrimitive.List>` | – | Radix list props, including aria-label and loop. |

#### TabsTrigger

A tab with a shared selection pill that glides between triggers.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` (required) | `string` | – | Matches a TabsContent value. |
| `...props` | `ComponentPropsWithoutRef<typeof TabsPrimitive.Trigger>` | – | Radix trigger props such as disabled. |

#### TabsContent

Panel that slides in and morphs its height from the previous panel.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` (required) | `string` | – | Matches a TabsTrigger value. |
| `forceMount` | `true` | – | Keeps the panel mounted and skips the enter and exit animation. |
| `...props` | `ComponentPropsWithoutRef<typeof TabsPrimitive.Content>` | – | Radix content props such as className. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| ArrowLeft / ArrowRight | Moves between tabs and activates them. |
| Home / End | Jumps to the first or last tab. |
| Tab | Moves focus from the tab list into the active panel. |

### Accessibility

- Radix provides role="tablist", role="tab", role="tabpanel", aria-selected, and aria-controls.
- The outgoing panel is made inert while it fades so it cannot take focus.
- Overflow scroll buttons are labelled "Scroll tabs left" and "Scroll tabs right"; give TabsList an aria-label.

### Motion

- The selection pill glides between triggers on a morph spring, scoped to one Tabs instance.
- Panels slide 8px in the direction of travel while the height springs from the previous panel.
- Reduced motion swaps the pill instantly and crossfades panels in place without height animation.

### Responsive behavior

- The tab list keeps max-width 100% and scrolls horizontally when triggers overflow, with scroll buttons at the edges.
- Focusing a tab scrolls it into view, so keyboard navigation works on narrow screens.
- Triggers keep a 5.5rem minimum width, so many tabs overflow sooner on mobile.

### Performance

- ResizeObservers track list overflow and the active panel height; one per Tabs instance is cheap.
- The selection pill is a shared layout animation scoped to one Tabs; avoid dozens of tab sets on one screen.

### Notes for AI

- Use for peer views of the same object. Use segmented-control for a compact value toggle that is not tied to panels, and accordion for stacked sections.
- Every TabsTrigger value needs a matching TabsContent. Long lists scroll horizontally on their own.

### Related

- [Segmented control](https://uiarc.dev/components/segmented-control/markdown): Switch between a small set of related views.
- [Accordion](https://uiarc.dev/components/accordion/markdown): Progressively reveal supporting information in place.
- [Liquid tab bar](https://uiarc.dev/components/liquid-tab-bar/markdown): Tabs with a lens selection that slides between them, swaps labels cleanly, and fills in icons as it passes.
- [Morph nav](https://uiarc.dev/components/morph-nav/markdown): A navigation bar that morphs into rich menus, search, and a compact state as one surface.

### Also in navigation

- [Breadcrumb](https://uiarc.dev/components/breadcrumb/markdown): Show where a page sits in a hierarchy.
- [Pagination](https://uiarc.dev/components/pagination/markdown): Move through a long collection with clear bounds.
- [Mega menu morph](https://uiarc.dev/components/mega-menu-morph/markdown): A site header whose menus share one floating panel. Moving between sections morphs its size, slides the next menu in from that side and glides the caret under the new trigger, with hover intent, a safe triangle and an accordion sheet on narrow screens.
- [Table of contents progress](https://uiarc.dev/components/toc-progress/markdown): A table of contents that reads along with you: a line bends through the nested headings, fills as you scroll, and carries a marker to the current section, with smooth jumps and a time-left countdown.

### Guidance for AI tools

Tabs: Switch between related content in the same context. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Breadcrumb

> Show where a page sits in a hierarchy.

- Type: Component (disclosure)
- Access: Free, open source
- Page: https://uiarc.dev/components/breadcrumb
- Markdown: https://uiarc.dev/components/breadcrumb/markdown
- Registry item: https://uiarc.dev/r/breadcrumb.json
- Source file: `registry/components/breadcrumb/breadcrumb.tsx`
- Dependencies: motion, lucide-react
- Keywords: navigation, wayfinding, react breadcrumb, breadcrumb navigation, animated breadcrumb, page path, nextjs breadcrumb, hierarchy navigation

### When to use

- Showing where a page sits in a hierarchy, such as Workspace, Settings, Billing.
- Client-side paths like a file browser, where crumbs call onClick instead of navigating.
- Paths that grow as people drill in, where new crumbs should slide in.

### When not to use

- Use tree-view when people need to browse the whole hierarchy.
- Use tabs for switching between sibling views.
- Use pagination for moving through pages of a list.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/breadcrumb
pnpm dlx shadcn@latest add @uiarc/breadcrumb
yarn dlx shadcn@latest add @uiarc/breadcrumb
bunx --bun shadcn@latest add @uiarc/breadcrumb
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/breadcrumb.json
```

#### Manual

1. Install the dependencies:

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

2. Copy the source into your project. Main file: `registry/components/breadcrumb/breadcrumb.tsx`

   The source is in the registry item: https://uiarc.dev/r/breadcrumb.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { Breadcrumb } from "@/components/arc/breadcrumb/breadcrumb";

export function SettingsPath() {
  return (
    <Breadcrumb
      items={[
        { label: "Workspace", href: "/" },
        { label: "Settings", href: "/settings" },
        { label: "Billing" },
      ]}
    />
  );
}
```

### API reference

#### Breadcrumb

A path of links where the last item is the current page. Crumbs added later slide in.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `items` (required) | `{ label: string; href?: string; onClick?: (event: MouseEvent<HTMLElement>) => void }[]` | – | Path from root to current page. Items with href render a plain a, or the link component set with ArcProvider (such as next/link or a locale-aware Link); items with only onClick render buttons. |
| `ariaLabel` | `string` | `"Breadcrumb"` | Label for the nav landmark. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Tab | Moves between crumb links and buttons. |
| Enter | Follows the focused crumb. |

### Accessibility

- Renders a nav landmark with an ordered list.
- The last item is a span with aria-current="page" and is never a link.
- Chevron separators are aria-hidden.

### Motion

- Crumbs present on first render stay still; new crumbs slide in 8px from the left out of a blur while siblings shift on a smooth spring.
- Reduced motion adds and removes crumbs without movement.

### Responsive behavior

- The list wraps onto new lines on narrow screens; individual crumbs never wrap internally.
- It does not truncate or collapse long paths, so keep labels short or shorten the path on mobile yourself.

### Performance

- Crumbs use layout position animation only when the path changes; static paths do not animate.

### Notes for AI

- Use for hierarchical page location. For client-side paths such as a file browser, pass onClick without href.
- Links are plain anchors by default. For client-side navigation, wrap the app once in ArcProvider from @/components/arc/lib/arc-provider with your router's Link: <ArcProvider link={Link}>.
- Keep labels short; the component does not truncate or collapse long paths.

### Related

- [Tree view](https://uiarc.dev/components/tree-view/markdown): Navigate nested folders and structured content.
- [Pagination](https://uiarc.dev/components/pagination/markdown): Move through a long collection with clear bounds.
- [Tabs](https://uiarc.dev/components/tabs/markdown): Switch between related content in the same context.

### Also in navigation

- [Mega menu morph](https://uiarc.dev/components/mega-menu-morph/markdown): A site header whose menus share one floating panel. Moving between sections morphs its size, slides the next menu in from that side and glides the caret under the new trigger, with hover intent, a safe triangle and an accordion sheet on narrow screens.
- [Table of contents progress](https://uiarc.dev/components/toc-progress/markdown): A table of contents that reads along with you: a line bends through the nested headings, fills as you scroll, and carries a marker to the current section, with smooth jumps and a time-left countdown.

### Guidance for AI tools

Breadcrumb: Show where a page sits in a hierarchy. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Pagination

> Move through a long collection with clear bounds.

- Type: Component (data)
- Access: Free, open source
- Page: https://uiarc.dev/components/pagination
- Markdown: https://uiarc.dev/components/pagination/markdown
- Registry item: https://uiarc.dev/r/pagination.json
- Source file: `registry/components/pagination/pagination.tsx`
- Dependencies: motion, lucide-react
- Keywords: data, navigation, react pagination, pagination component, page numbers, table pagination, animated pagination, next previous pages

### When to use

- Paged server results and long tables.
- Lists where the page should live in the URL or state and fetch on change.

### When not to use

- Use carousel for browsing slides.
- Use timeline with maxHeight for a scrolling feed instead of pages.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/pagination
pnpm dlx shadcn@latest add @uiarc/pagination
yarn dlx shadcn@latest add @uiarc/pagination
bunx --bun shadcn@latest add @uiarc/pagination
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/pagination.json
```

#### Manual

1. Install the dependencies:

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

2. Copy the source into your project. Main file: `registry/components/pagination/pagination.tsx`

   The source is in the registry item: https://uiarc.dev/r/pagination.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { useState } from "react";
import { Pagination } from "@/components/arc/pagination/pagination";

export function Results() {
  const [page, setPage] = useState(1);
  return <Pagination page={page} pageCount={12} onPageChange={setPage} />;
}
```

### API reference

#### Pagination

Previous and next buttons around a sliding five page window with a traveling current page mark.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `page` (required) | `number` | – | Current page, 1-based. Clamped to the range. |
| `pageCount` (required) | `number` | – | Total pages. Zero renders an empty nav. |
| `onPageChange` (required) | `(page: number) => void` | – | Called with the requested page. |
| `label` | `string` | `"Pagination"` | Accessible name for the nav landmark. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Tab | Moves between the previous, page, and next buttons. |
| Enter / Space | Goes to that page. |

### Accessibility

- Renders a nav landmark with the label as its name.
- Page buttons are labelled "Page 3" and the current one has aria-current="page".
- Previous and next are disabled at the ends and carry aria-labels.

### Motion

- The current page mark springs to the selected button.
- When the window shifts, numbers slide like a belt by the number of slots moved.
- Reduced motion jumps the mark and swaps numbers without sliding.

### Responsive behavior

- It always shows a five page window plus arrows, so it stays the same width on any screen.
- The row wraps if its container is narrower than the buttons, and the current mark re-measures on resize.

### Performance

- Only five page buttons render regardless of pageCount; one ResizeObserver repositions the current mark.

### Notes for AI

- Use for paged server results and long tables. Use carousel for browsing slides.
- It is fully controlled: keep page in state or the URL and fetch on onPageChange.

### Related

- [Sortable data table](https://uiarc.dev/components/sortable-data-table/markdown): Compare structured records with sortable columns.
- [Filter toolbar](https://uiarc.dev/components/filter-toolbar/markdown): Keep collection filters close and easy to reset.
- [Carousel](https://uiarc.dev/components/carousel/markdown): Browse a row of slides by dragging, flicking, or arrowing through them.

### Also in navigation

- [Tabs](https://uiarc.dev/components/tabs/markdown): Switch between related content in the same context.
- [Breadcrumb](https://uiarc.dev/components/breadcrumb/markdown): Show where a page sits in a hierarchy.
- [Mega menu morph](https://uiarc.dev/components/mega-menu-morph/markdown): A site header whose menus share one floating panel. Moving between sections morphs its size, slides the next menu in from that side and glides the caret under the new trigger, with hover intent, a safe triangle and an accordion sheet on narrow screens.
- [Table of contents progress](https://uiarc.dev/components/toc-progress/markdown): A table of contents that reads along with you: a line bends through the nested headings, fills as you scroll, and carries a marker to the current section, with smooth jumps and a time-left countdown.

### Guidance for AI tools

Pagination: Move through a long collection with clear bounds. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Mega menu morph

> A site header whose menus share one floating panel. Moving between sections morphs its size, slides the next menu in from that side and glides the caret under the new trigger, with hover intent, a safe triangle and an accordion sheet on narrow screens.

- Type: Component (disclosure)
- Access: Arc Pro
- Page: https://uiarc.dev/components/mega-menu-morph
- Markdown: https://uiarc.dev/components/mega-menu-morph/markdown
- Source file: `registry/components/mega-menu-morph/mega-menu-morph.tsx`
- Dependencies: motion, lucide-react
- Keywords: navigation, menu, motion, new, mega menu, site header, navigation bar, navbar, dropdown, morphing dropdown, shared layout, stripe menu, hover intent, safe triangle, menu aim, caret, accordion menu, mobile menu, marketing header

### When to use

- A marketing site header with product, solution, developer and company sections that each need a rich menu.
- A documentation or platform site whose top sections deserve descriptions, a featured story or a status line.
- Anywhere visitors browse several menus in a row and repeated open and close animations would feel busy.

### When not to use

- Use morph-nav for a compact floating pill navigation with search built in.
- Use dropdown-menu for a single list of actions or links behind one button.
- Use tabs or a docs-sidebar style navigation for moving between views inside a product.

### Installation

Mega menu morph is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/mega-menu-morph
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { MegaMenuMorph } from "@/components/arc/mega-menu-morph/mega-menu-morph";
import type { MegaMenuItem } from "@/components/arc/mega-menu-morph/mega-menu-morph";
import { BookOpen, CreditCard, Repeat, Zap } from "lucide-react";

const items: MegaMenuItem[] = [
  {
    value: "products",
    label: "Products",
    groups: [{ title: "Payments", links: [
      { label: "Checkout", description: "Hosted pages in 46 currencies", icon: <CreditCard />, href: "/checkout" },
      { label: "Billing", description: "Subscriptions, usage and invoices", icon: <Repeat />, href: "/billing" },
    ] }],
    feature: { title: "Instant payouts in the EU", description: "Sellers now get paid in seconds.", cta: "Read the announcement", href: "/blog/instant-payouts" },
  },
  {
    value: "developers",
    label: "Developers",
    groups: [{ title: "Documentation", links: [
      { label: "Quickstart", icon: <Zap />, href: "/docs/quickstart" },
      { label: "API reference", icon: <BookOpen />, href: "/docs/api" },
    ] }],
    footer: <span>All systems normal</span>,
  },
  { value: "pricing", label: "Pricing", href: "/pricing" },
];

export function SiteHeader() {
  const router = useRouter();
  const pathname = usePathname();
  return (
    <MegaMenuMorph
      items={items}
      brand={{ name: "Tally", mark: <TallyMark />, href: "/" }}
      actions={[{ label: "Sign in", href: "/login" }, { label: "Start now", href: "/signup", variant: "primary" }]}
      current={pathname.startsWith("/docs") ? "developers" : undefined}
      onNavigate={destination => destination.href && router.push(destination.href)}
    />
  );
}
```

### API reference

#### MegaMenuMorph

A site header whose menus share one floating surface. Moving from one section to the next morphs the surface to the new menu's width and height, glides it and its caret under the new trigger and slides the content in from the side you came from, instead of closing one menu and opening another. A highlight follows the pointer across the triggers, a muted footer band grows and shrinks with the panel, hover intent and a safe triangle keep diagonal moves toward the open menu from switching sections, and a header too narrow for its row folds into a full width accordion sheet.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `items` | `MegaMenuItem[]` | `megaMenuSampleItems` | Sections of the header, in order. An item with groups or a feature opens a menu; an item without them is a plain link. Each item is { value, label, href?, groups?: { title?, links: { label, description?, icon?, href?, badge? }[] }[], feature?: { title, description?, cta?, href?, media? }, footer? }. |
| `brand` | `{ name: string; mark?: ReactNode; href?: string }` | `Tally sample brand` | Mark and name at the start of the header. Choosing it calls onNavigate. |
| `actions` | `MegaMenuAction[]` | `Sign in and Start now` | Actions at the end of the header, each { label, href?, onClick?, variant?: "primary" \| "quiet" }. When the header folds, primary actions stay in the bar and quiet ones move to the bottom of the sheet. |
| `value` | `string \| null` | – | The open menu, controlled. null keeps every menu closed. Pair with onValueChange. |
| `defaultValue` | `string \| null` | `null` | The menu open on first render when uncontrolled. |
| `onValueChange` | `(value: string \| null) => void` | – | Called with the menu that should open, or null when menus close, from hover, click, keyboard, Escape, focus leaving or an outside press. |
| `current` | `string` | – | Value of the section that holds the current page. Its trigger carries a short accent mark and plain links get aria-current="page". |
| `openDelay` | `number` | `90` | How long in ms the pointer rests on a trigger before the first menu opens. Once a menu is open, moving to another trigger switches at once unless the pointer is heading into the open menu. |
| `closeDelay` | `number` | `240` | Grace period in ms after the pointer leaves the header and the menu before the menu closes. Re-entering cancels it. |
| `collapseBelow` | `number \| "auto"` | `"auto"` | Header width in px below which the sections fold into the accordion sheet. "auto" measures the natural width of the full row and folds exactly when it stops fitting. |
| `showSafeArea` | `boolean` | `false` | Draws the safe triangle from the pointer to the top corners of the open menu, tinted with the accent while it is holding a switch back. A development aid for tuning hover behavior. |
| `onNavigate` | `(destination: MegaMenuDestination) => void` | – | Called with { label, href?, section? } for every destination: links, feature cards, plain sections, actions and the brand. When set, the default link navigation is prevented so you can route yourself; menus and the sheet close either way. |
| `label` | `string` | `"Main"` | Accessible name of the navigation landmark. |
| `className` | `string` | – | Class on the root element. |
| `style` | `CSSProperties` | – | Inline styles on the root element. Set --mm-bar-h to change the bar height and --mm-sheet-max to cap the folded sheet in a small host. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Tab | Moves through the brand, the sections and the actions. From a trigger whose menu is open, Tab enters that menu; Tab from its last link moves on to the next section and closes it. |
| Arrow Left / Arrow Right | On the triggers, moves between sections. If a menu is open it follows focus, sliding in from that side. Inside a menu, switches to the previous or next menu and focuses its first link. |
| Home / End | On the triggers, moves to the first or last section. |
| Enter / Space | Toggles the menu of the focused trigger; follows a focused link. |
| Arrow Down | On a trigger, opens its menu and focuses the first link. Inside a menu, moves to the next link. |
| Arrow Up | Inside a menu, moves to the previous link; from the first link, returns to the trigger. |
| Escape | Closes the open menu and returns focus to its trigger, or closes the folded sheet and returns focus to the menu button. |

### Accessibility

- The header is a nav landmark named by label. Triggers are buttons with aria-expanded and aria-controls pointing at the open menu; plain sections are links, with aria-current="page" when they hold the current page.
- Menus follow the disclosure navigation pattern rather than role="menu": links stay links, Tab order runs from a trigger into its menu, and focus leaving the header closes it.
- The current section is marked with aria-current or its label, never only by the accent mark.
- The folded header uses a menu button with aria-expanded and aria-controls, named Open menu or Close menu. Sections in the sheet are accordion buttons with aria-expanded controlling labelled regions.
- The measuring copy of the row, the highlight, the caret, the band and the safe area overlay are hidden from assistive technology; the measuring copy is also inert.
- Outside presses and Escape close the menu and the sheet from anywhere on the page. Pointer focus draws no ring; keyboard focus shows Arc's shared focus ring. Focused links show the same quiet fill as hover.

### Motion

- One surface serves every menu. Its position, width and height are springs restated as stiffness and damping, so retargeting mid flight keeps the velocity it has: growing carries a trace of overshoot, shrinking never overshoots, and the caret glides with the position to stay under the trigger.
- Menus hang from the top left of the surface at their natural size. The next menu slides in 36px from the side of the trigger you moved to and the previous one leaves the other way, both with a short opacity and 2px blur crossfade.
- A footer is drawn on a muted band anchored to the bottom edge. The band's height springs with the panel, so a status row grows out of it instead of fading in, and a menu without a footer folds it away.
- Opening from closed lands the surface in place and fades it in with a short drop and a scale from the caret; closing fades it up and away. Reopening while it closes picks up where it is.
- The trigger highlight glides between triggers on a spring with a little life; it appears in place when the pointer enters the row and fades where it is when the pointer leaves. Chevrons turn on the shared spring curve.
- The folded sheet grows its height on the smooth spring and staggers its rows in; accordion sections open with height and opacity together.
- With reduced motion every size and position change lands at once, menus crossfade in 140ms without travel or blur, the highlight jumps and the sheet fades.

### Responsive behavior

- The root is an inline size container. The full row is measured from an invisible copy at its natural width, and the header folds exactly when it stops fitting, into a bar with the brand, the primary action and a menu button.
- The folded sheet spans the header, never runs past the viewport (or --mm-sheet-max), scrolls inside itself and opens one accordion section at a time.
- Menus clamp to the header with an 8px inset; their groups wrap onto new rows when the header is narrower than a menu's natural width, and the caret stays over the trigger.
- Hover behavior only runs for mouse and pen. On touch, triggers toggle on tap and a tap outside closes the menu.

### Performance

- Only the open menu and, during a switch, the leaving menu are mounted. Menus are measured with a ResizeObserver, and the surface animates width, height and a transform on one absolutely positioned element, so no page layout is touched.
- The highlight and caret are transforms driven by motion values; React renders only when the open section, the hovered trigger or the fold changes.
- Pointer positions are kept in a short ring of samples, and the safe triangle is a single point in triangle test on pointer entry to another trigger.

### Notes for AI

- Use it as the top navigation of a marketing or product site with three to six sections, where each section holds several destinations worth describing. For a single dropdown use dropdown-menu; for app navigation use a sidebar.
- Keep menus different in shape on purpose: a wide menu with two groups and a feature next to a narrow single list is what makes the morph read. Keep descriptions to one line of five or six words.
- Put only live, meaningful information in footer, such as system status or an announcement; the band's growth draws attention to it.
- Pass onNavigate in a client router so links do not reload the page, and pass current so the accent mark follows the route.
- Give the header room: it folds automatically when the row stops fitting. Use collapseBelow with a number only when the fold must match other breakpoints on the page.
- Place it at the top of a relatively positioned page area; menus and the sheet float over the content below and never push it down.

### Related

- [Morph nav](https://uiarc.dev/components/morph-nav/markdown): A navigation bar that morphs into rich menus, search, and a compact state as one surface.
- [Dropdown menu](https://uiarc.dev/components/dropdown-menu/markdown): A focused list of actions anchored to a trigger.
- [Site header](https://uiarc.dev/components/blocks/site-header/markdown): A sticky website header that turns solid on scroll, with a gliding active link, mega menu panels, and a mobile sheet.
- [Tabs](https://uiarc.dev/components/tabs/markdown): Switch between related content in the same context.

### Also in navigation

- [Breadcrumb](https://uiarc.dev/components/breadcrumb/markdown): Show where a page sits in a hierarchy.
- [Pagination](https://uiarc.dev/components/pagination/markdown): Move through a long collection with clear bounds.
- [Table of contents progress](https://uiarc.dev/components/toc-progress/markdown): A table of contents that reads along with you: a line bends through the nested headings, fills as you scroll, and carries a marker to the current section, with smooth jumps and a time-left countdown.

### Guidance for AI tools

Mega menu morph: A site header whose menus share one floating panel. Moving between sections morphs its size, slides the next menu in from that side and glides the caret under the new trigger, with hover intent, a safe triangle and an accordion sheet on narrow screens. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Table of contents progress

> A table of contents that reads along with you: a line bends through the nested headings, fills as you scroll, and carries a marker to the current section, with smooth jumps and a time-left countdown.

- Type: Component (disclosure)
- Access: Arc Pro
- Page: https://uiarc.dev/components/toc-progress
- Markdown: https://uiarc.dev/components/toc-progress/markdown
- Source file: `registry/components/toc-progress/toc-progress.tsx`
- Dependencies: motion, lucide-react
- Keywords: navigation, scroll, motion, new, table of contents, toc, on this page, scroll spy, reading progress, scrollspy, article navigation, docs navigation, anchor links, section indicator, progress line, time left, reading time

### When to use

- A documentation page, guide or blog post long enough that readers jump between sections.
- An engineering write up or policy where knowing how much is left helps readers commit to it.
- Any long article in its own scroll container, such as a help panel or a reader view.

### When not to use

- Use tabs when sections are alternatives rather than parts of one document.
- Use scroll-progress-ring for a compact overall progress indicator without navigation.
- Skip it for pages with fewer than four headings; a plain list of anchors is enough.

### Installation

Table of contents progress is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/toc-progress
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { TocProgress } from "@/components/arc/toc-progress/toc-progress";

const headings = [
  { id: "overview", label: "Overview" },
  { id: "install", label: "Installation" },
  { id: "install-cli", label: "With the CLI", level: 2 },
  { id: "install-manual", label: "By hand", level: 2 },
  { id: "configure", label: "Configuration" },
] as const;

export function DocsPage({ children }: { children: React.ReactNode }) {
  return (
    <div className="page">
      <article>{children}</article>
      <aside className="toc">
        {/* Sticky header is 64px tall: headings count as reached just below it. */}
        <TocProgress items={[...headings]} offset={88} onNavigate={id => history.replaceState(null, "", `#${id}`)} />
      </aside>
    </div>
  );
}
```

### API reference

#### TocProgress

A table of contents that reads along with you. A thin line runs down the headings and bends through their indentation with a smooth S between levels. The part you have read fills in with the accent as you scroll, section by section, and a marker rides the tip of the line, lighting each heading as it arrives. Choosing a heading scrolls the article there smoothly while the line traces the way, and the time left beside the title counts down, then reads Finished.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `items` (required) | `TocProgressItem[]` | – | Headings in document order, each { id, label, level?: 1 \| 2 \| 3 }. id is the id of the heading element in the article; level sets the lane the line bends into and the label indent. |
| `scrollContainer` | `RefObject<HTMLElement \| null> \| HTMLElement \| null` | – | The element that scrolls the article. Defaults to the nearest scrolling ancestor of the first heading, or the page when there is none. |
| `offset` | `number` | `96` | Distance in px from the top of the scroll viewport at which a heading counts as reached, usually the height of a sticky header plus a little air. Headings scroll to this line when chosen. |
| `activeId` | `string` | – | The current heading, controlled. By default the current heading follows the reading position; the line keeps following the scroll either way. |
| `onActiveChange` | `(id: string) => void` | – | Called with the heading id when the marker reaches a new heading, while reading or while a chosen heading scrolls into place. |
| `onNavigate` | `(id: string) => void` | – | Called with the heading id when a heading in the list is chosen, before the article scrolls. Use it to update the URL hash or analytics. |
| `readingTime` | `number` | – | Reading time of the whole article in minutes. Defaults to an estimate from the words in the scroll container at 230 words a minute. |
| `title` | `string` | `"On this page"` | Heading above the list and the accessible name of the navigation. Pass an empty string to hide it. |
| `showTimeLeft` | `boolean` | `true` | Shows the minutes left beside the title, rolling to each new value and ending on Finished with a check. |
| `label` | `string` | `"On this page"` | Accessible name of the navigation when title is empty. |
| `className` | `string` | – | Class on the root element. Set --toc-accent to recolor the read line and the marker. |
| `style` | `CSSProperties` | – | Inline styles on the root element. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Tab | Moves through the headings in the list; each is a link. |
| Arrow Down / Arrow Up | Moves focus to the next or previous heading in the list. |
| Home / End | Moves focus to the first or last heading in the list. |
| Enter | Scrolls the article to the heading and moves focus to it without a second scroll jump, so reading and tabbing continue from there. |

### Accessibility

- The list is a nav landmark named by the title, with an ordered list of links whose href points at each heading, so it works as plain anchors before hydration.
- The current heading carries aria-current="location"; read, current and upcoming headings also differ in text contrast, never by the line alone.
- Choosing a heading gives the target heading tabindex="-1" if it has none and focuses it with preventScroll, so screen reader and keyboard users land where the article scrolled.
- The line, the fill and the marker are one SVG hidden from assistive technology. The time left is plain text beside the title and is not announced on every change.
- Pointer focus draws no ring; keyboard focus shows Arc's shared focus ring. A focused heading shows a quiet fill.

### Motion

- The reading position is a section index plus how far through that section you are, from where its heading crosses the offset line to where the next one does. It follows the scroll on a critically damped spring, so a wheel step glides instead of jumping and the marker never points past the section you are in.
- Each section fills the stretch of line from its heading to the next, bends included, so the fill always meets a heading exactly when that heading is reached. The marker rides the tip of the fill along the same points the line is drawn from.
- Near the end of the article the reading line eases from the offset down to the bottom edge of the viewport, so short last sections are still reached when the scroll bottoms out.
- A chosen heading scrolls smoothly and the line traces there through every section in between. If the heading cannot reach the top because the article ends, it stays current until the reader scrolls on.
- Heading colors change over 240ms. The time left rolls up to its new value with a short blur, on the snappy spring, and ends on Finished.
- With reduced motion the fill and marker follow the scroll directly, chosen headings jump into place, colors change at once and the time left crossfades.

### Responsive behavior

- The list takes the width of its column and labels wrap; the line follows each row's measured height, so wrapped labels keep the bends between rows.
- Rows, the line and the heading positions are re-measured with ResizeObserver whenever the list, the article or the scroll container resizes, including font loading and images.
- Works with the page scroll or any scroll container, including one inside a preview frame or a dialog.
- Touch targets are the full row width; on narrow screens place the component above the article.

### Performance

- Scroll handling is passive and does arithmetic on cached heading positions; layout is read only when something resizes.
- The line is a single polyline path and its fill is the same path with a stroke dash, animated through motion values; the marker is one transform. React renders only when the current heading or the rounded time left changes.
- Keep items to a few dozen headings; the line is rebuilt in one pass when the list resizes.

### Notes for AI

- Use it beside long form content with real headings: documentation pages, engineering write ups, guides, policies and changelogs. Pass the heading ids that already exist in the article.
- Keep to two levels for most articles, three at most; the line bends at every level change, so alternating levels on every row makes it zigzag.
- Set offset to the height of any sticky header plus 16 to 32px, and use the same value as scroll-margin-top on the headings for anchor links.
- When the article scrolls inside its own container, pass scrollContainer; otherwise it finds the nearest scrolling ancestor of the first heading, or the page.
- Pass readingTime when you already know it; the default estimate counts every word in the scroll container, including code.
- Put it in a sticky aside on wide screens. On phones, show it above the article or in a sheet rather than beside it.

### Related

- [Sidebar: Docs](https://uiarc.dev/components/blocks/sidebar/markdown): A docs layout with a live filtering nav tree, version switcher, and a gliding on this page outline.
- [Tabs](https://uiarc.dev/components/tabs/markdown): Switch between related content in the same context.

### Also in navigation

- [Breadcrumb](https://uiarc.dev/components/breadcrumb/markdown): Show where a page sits in a hierarchy.
- [Pagination](https://uiarc.dev/components/pagination/markdown): Move through a long collection with clear bounds.
- [Mega menu morph](https://uiarc.dev/components/mega-menu-morph/markdown): A site header whose menus share one floating panel. Moving between sections morphs its size, slides the next menu in from that side and glides the caret under the new trigger, with hover intent, a safe triangle and an accordion sheet on narrow screens.

### Guidance for AI tools

Table of contents progress: A table of contents that reads along with you: a line bends through the nested headings, fills as you scroll, and carries a marker to the current section, with smooth jumps and a time-left countdown. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Scroll area

> A native scroll container with thin overlay scrollbars and edge fades that appear only when content overflows.

- Type: Component (disclosure)
- Access: Free, open source
- Page: https://uiarc.dev/components/scroll-area
- Markdown: https://uiarc.dev/components/scroll-area/markdown
- Registry item: https://uiarc.dev/r/scroll-area.json
- Source file: `registry/components/scroll-area/scroll-area.tsx`
- Keywords: disclosure, new, react scroll area, custom scrollbar, overlay scrollbar, scroll fade edges, horizontal scroll container, scroll snap container, scrollable panel

### When to use

- Panels, sidebars, and popovers whose content can outgrow their box.
- Horizontal strips of cards or chips that need mouse-wheel scrolling and snap points.
- Places where platform scrollbars look heavy but native scrolling must be kept.

### When not to use

- Use carousel when items should page one at a time with controls.
- Do not wrap the whole page; let the document scroll natively.
- Use data-grid for large tabular data; it virtualizes its own scroll.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/scroll-area
pnpm dlx shadcn@latest add @uiarc/scroll-area
yarn dlx shadcn@latest add @uiarc/scroll-area
bunx --bun shadcn@latest add @uiarc/scroll-area
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/scroll-area.json
```

#### Manual

1. No packages are needed beyond React and Next.js.

2. Copy the source into your project. Main file: `registry/components/scroll-area/scroll-area.tsx`

   The source is in the registry item: https://uiarc.dev/r/scroll-area.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { ScrollArea } from "@/components/arc/scroll-area/scroll-area";

export function ActivityPanel({ events }: { events: { id: string; text: string }[] }) {
  return (
    <ScrollArea maxHeight={320} label="Recent activity">
      <ul>{events.map(event => <li key={event.id}>{event.text}</li>)}</ul>
    </ScrollArea>
  );
}
```

### Examples

#### Horizontal strip with snap

```tsx
<ScrollArea orientation="horizontal" snap="x mandatory" label="Templates">
  <div style={{ display: "flex", gap: 12 }}>
    {templates.map(item => <TemplateCard key={item.id} {...item} style={{ scrollSnapAlign: "start" }} />)}
  </div>
</ScrollArea>
```

### API reference

#### ScrollArea

A native scroll container with thin overlay scrollbars that appear while scrolling or on hover, and edge fades that grow with the content left beyond each edge.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `orientation` | `"vertical" \| "horizontal" \| "both"` | `"vertical"` | Axes that scroll. |
| `fade` | `number` | `28` | Length of the edge fade in px. 0 turns the fades off. |
| `scrollbars` | `"auto" \| "always"` | `"auto"` | "auto" shows scrollbars while scrolling or hovering; "always" keeps them visible when content overflows. |
| `hideDelay` | `number` | `900` | How long scrollbars linger after scrolling stops, in ms. |
| `maxHeight` | `CSSProperties["maxHeight"]` | – | Maximum viewport height, for vertical areas that grow with their content. |
| `snap` | `CSSProperties["scrollSnapType"]` | – | Passed to the viewport's scroll-snap-type, for example "x mandatory". Children set their own scroll-snap-align. |
| `label` | `string` | – | Accessible name. The viewport becomes a labelled region. |
| `wheelToHorizontal` | `boolean` | `true` | Turns vertical wheel movement into horizontal scrolling for horizontal areas. |
| `viewportClassName` | `string` | – | Extra class on the scrolling viewport. |
| `viewportStyle` | `CSSProperties` | – | Inline style on the viewport. |
| `viewportRef` | `Ref<HTMLDivElement>` | – | The scrolling element, for programmatic scrolling. |
| `onScroll` | `(event: UIEvent<HTMLDivElement>) => void` | – | Viewport scroll handler. |
| `onEdgeChange` | `(edges: ScrollAreaEdges) => void` | – | Called when content starts or stops extending past an edge: { top, bottom, left, right }. |
| `...props` | `HTMLAttributes<HTMLDivElement>` | – | Forwarded to the root, including ref and className. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Tab | The viewport is focusable (tabIndex 0). |
| Arrow keys / Page Up / Page Down / Home / End / Space | Scroll natively once the viewport has focus. |

### Accessibility

- Scrolling stays native, so keyboard, screen reader, and touch behavior match the platform.
- With label, the viewport is a named region; without one, give it context another way.
- The overlay tracks and thumbs are aria-hidden; the hidden native scrollbar remains the real control.

### Motion

- Scrollbars fade in while scrolling or on hover and fade out after hideDelay; the thumb thickens under the pointer.
- Pressing the track pages 90% of the viewport toward the pointer with smooth scrolling, or instantly under reduced motion.
- Reduced motion removes scrollbar transitions.

### Responsive behavior

- Touch keeps native momentum scrolling; the overlay bars only appear while scrolling.
- Thumbs only thicken on hover-capable fine pointers.
- Content changes and resizes are tracked with ResizeObserver and MutationObserver, so fades and thumbs stay correct as layouts reflow.

### Performance

- Fades and thumb positions are written straight to the DOM on each scroll event; scrolling never re-renders React.
- Horizontal wheel conversion only captures the wheel while there is room to scroll, so the page still scrolls at the ends.
- Edge fades use CSS mask-image, which is cheap but still composited; set fade={0} in very long lists if you see cost.

### Notes for AI

- Use it wherever content scrolls inside a fixed box: sidebars, panels, menus, horizontal card strips.
- Give vertical areas a height or maxHeight; the viewport scrolls only when it has a constrained size.
- Use onEdgeChange to show a "more below" affordance or to load more when bottom becomes false.

### Related

- [Resizable panels](https://uiarc.dev/components/resizable-panels/markdown): Trade space between panes by dragging the divider between them.
- [Carousel](https://uiarc.dev/components/carousel/markdown): Browse a row of slides by dragging, flicking, or arrowing through them.
- [Data grid](https://uiarc.dev/components/data-grid/markdown): A spreadsheet grid with range selection, inline editing, a fill handle, and animated sorting.
- [Tree view](https://uiarc.dev/components/tree-view/markdown): Navigate nested folders and structured content.

### Also in expand

- [Accordion](https://uiarc.dev/components/accordion/markdown): Progressively reveal supporting information in place.
- [Expandable card](https://uiarc.dev/components/expandable-card/markdown): Give a dense card more room when requested.
- [Expandable text](https://uiarc.dev/components/expandable-text/markdown): Long text clamped to a few lines with a soft fade that glides open with Read more and closes with Show less, shown only when the text overflows.

### Guidance for AI tools

Scroll area: A native scroll container with thin overlay scrollbars and edge fades that appear only when content overflows. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Accordion

> Progressively reveal supporting information in place.

- Type: Component (disclosure)
- Access: Free, open source
- Page: https://uiarc.dev/components/accordion
- Markdown: https://uiarc.dev/components/accordion/markdown
- Registry item: https://uiarc.dev/r/accordion.json
- Source file: `registry/components/accordion/accordion.tsx`
- Dependencies: @radix-ui/react-accordion, motion, lucide-react
- Keywords: disclosure, layout, react accordion, faq accordion, collapsible sections, animated accordion, radix accordion, expand collapse list, faq component

### When to use

- FAQ sections where only one answer should be open at a time.
- Settings or help pages that group long content under short, scannable questions.
- Page-level FAQs that need larger type, via size="lg".

### When not to use

- Use expandable-card for a single standalone disclosure such as a plan or order summary.
- Use tabs when sections are peer views that people switch between.
- Use onboarding-checklist when the rows are setup tasks to complete.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/accordion
pnpm dlx shadcn@latest add @uiarc/accordion
yarn dlx shadcn@latest add @uiarc/accordion
bunx --bun shadcn@latest add @uiarc/accordion
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/accordion.json
```

#### Manual

1. Install the dependencies:

```bash
npm install @radix-ui/react-accordion motion lucide-react
```

2. Copy the source into your project. Main file: `registry/components/accordion/accordion.tsx`

   The source is in the registry item: https://uiarc.dev/r/accordion.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { Accordion } from "@/components/arc/accordion/accordion";

export function Faq() {
  return (
    <Accordion
      size="lg"
      items={[
        { title: "Can I cancel anytime?", content: "Yes. Your plan stays active until the period ends." },
        { title: "Do you offer refunds?", content: "Within 14 days of purchase, no questions asked." },
      ]}
    />
  );
}
```

### API reference

#### Accordion

A single-open, collapsible list of question and answer rows built on Radix Accordion.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `items` (required) | `{ title: string; content: ReactNode }[]` | – | Rows in order. The title is the trigger label; content fills the panel. |
| `defaultOpen` | `number` | `0` | Index of the row open on first render. Pass -1 to start with every row closed. |
| `size` | `"md" \| "lg"` | `"md"` | "lg" sets questions at the large text size for page-level FAQs. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Enter / Space | Toggles the focused row. |
| ArrowDown / ArrowUp | Moves focus between row triggers. |
| Home / End | Jumps to the first or last trigger. |

### Accessibility

- Radix wires aria-expanded, aria-controls, and region labelling between each trigger and panel.
- Closed panels stay mounted but switch to visibility hidden once collapsed, so they leave the accessibility tree.
- Triggers sit inside heading elements; the chevron is aria-hidden.

### Motion

- Panel height springs without overshoot while the answer slides down 6px out of a subtle blur; the chevron rotates on a snappy spring.
- A toggle mid-flight retargets from the current height instead of restarting.
- Reduced motion applies the same end states in one step.

### Responsive behavior

- Rows fill their container width; the lg size caps answers at 62ch for readable line length.
- Below 520px the lg size drops to a 68px row and smaller answer text with tighter right padding.
- Hover color changes apply only on hover-capable fine pointers.

### Performance

- Closed panels stay mounted and hidden, so every answer is in the DOM; keep very heavy content lazy inside the panel.
- Height springs through motion on the one row that changes, with no layout observers.

### Notes for AI

- Use for FAQs and settings groups where only one section should be open. Use expandable-card for a single standalone disclosure and tabs when sections are peers.
- Content is plain data; pass rich ReactNode answers directly. Only single mode is supported.

### Related

- [Expandable card](https://uiarc.dev/components/expandable-card/markdown): Give a dense card more room when requested.
- [Tabs](https://uiarc.dev/components/tabs/markdown): Switch between related content in the same context.
- [Onboarding checklist](https://uiarc.dev/components/onboarding-checklist/markdown): Guide a new workspace through setup, one step at a time.

### Also in expand

- [Scroll area](https://uiarc.dev/components/scroll-area/markdown): A native scroll container with thin overlay scrollbars and edge fades that appear only when content overflows.
- [Resizable panels](https://uiarc.dev/components/resizable-panels/markdown): Trade space between panes by dragging the divider between them.
- [Expandable text](https://uiarc.dev/components/expandable-text/markdown): Long text clamped to a few lines with a soft fade that glides open with Read more and closes with Show less, shown only when the text overflows.

### Guidance for AI tools

Accordion: Progressively reveal supporting information in place. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Expandable card

> Give a dense card more room when requested.

- Type: Component (disclosure)
- Access: Free, open source
- Page: https://uiarc.dev/components/expandable-card
- Markdown: https://uiarc.dev/components/expandable-card/markdown
- Registry item: https://uiarc.dev/r/expandable-card.json
- Source file: `registry/components/expandable-card/expandable-card.tsx`
- Dependencies: motion, lucide-react
- Keywords: disclosure, layout, react expandable card, collapsible card, expand card animation, disclosure card, show more card, card with details

### When to use

- A single summary card with optional details, like a plan, order, or log entry.
- Cards whose summary line updates and should roll changed words in place.

### When not to use

- Use accordion for a list of mutually exclusive sections.
- Use card when there is nothing to reveal.
- Use card-stack for browsing several cards in one spot.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/expandable-card
pnpm dlx shadcn@latest add @uiarc/expandable-card
yarn dlx shadcn@latest add @uiarc/expandable-card
bunx --bun shadcn@latest add @uiarc/expandable-card
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/expandable-card.json
```

#### Manual

1. Install the dependencies:

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

2. Copy the source into your project. Main file: `registry/components/expandable-card/expandable-card.tsx`

   The source is in the registry item: https://uiarc.dev/r/expandable-card.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { ExpandableCard } from "@/components/arc/expandable-card/expandable-card";

export function PlanDetails() {
  return (
    <ExpandableCard title="Pro plan" description="Billed yearly, renews March 4" width={400} expandedWidth={600}>
      <ul>
        <li>Unlimited projects</li>
        <li>Priority support</li>
      </ul>
    </ExpandableCard>
  );
}
```

### API reference

#### ExpandableCard

A card whose header toggles a details panel beneath it.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` (required) | `string` | – | Card heading, shown in the toggle. |
| `description` | `string` | – | Summary line. Changed words roll in when it updates. |
| `children` (required) | `ReactNode` | – | Details revealed when expanded. |
| `defaultExpanded` | `boolean` | `false` | Starts expanded. |
| `width` | `number` | – | Collapsed width cap in px. The card is centered and never wider than its container. Fills the container when omitted. |
| `expandedWidth` | `number` | – | Expanded width cap in px, so the card grows sideways into more room when opened. Defaults to width. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Enter / Space | Toggles the card from its header button. |
| Escape | Closes the card while focus is inside it and returns focus to the header. |

### Accessibility

- The header is a native button with aria-expanded and aria-controls pointing at the panel.
- The rolling description keeps a screen-reader-only copy of the full text; animated words are aria-hidden.
- The collapsed panel is inert, so its content is not reachable by keyboard or screen readers while closed.

### Motion

- Open and close are one morph: width and height move together on the smooth spring, which never overshoots, and the arrow turns on the same spring.
- Details fade in once the box has made room and fade out before it shrinks. They are laid out at their open width throughout, so text never reflows or stretches.
- Clicking again mid-animation reverses from the current size with its velocity. Changed words in the description rise in; unchanged words hold still.
- Reduced motion applies end states instantly and swaps the description without animation.

### Responsive behavior

- Without width caps the card fills its container. With width and expandedWidth it stays centered and grows sideways to the open cap, never wider than its container, so on a phone it simply uses the full width.
- The whole header is the toggle with a 64px minimum height, so it is an easy touch target.

### Performance

- The panel stays mounted but inert at zero height when collapsed, so a second click mid-animation reverses smoothly.
- Width and height are animated for real on one spring rather than scaled, so text and corners never stretch; keep the details short.
- The description splits into one span per word for the roll; keep it to a short line.

### Notes for AI

- Use for a single standalone expandable summary such as a plan, order, or log entry. Use accordion for a list of mutually exclusive sections.
- State is internal; there is no controlled prop.

### Related

- [Accordion](https://uiarc.dev/components/accordion/markdown): Progressively reveal supporting information in place.
- [Card](https://uiarc.dev/components/card/markdown): A contained group of related content and actions.
- [Card stack](https://uiarc.dev/components/card-stack/markdown): Review a deck one card at a time, with a throw and an undo.

### Also in expand

- [Scroll area](https://uiarc.dev/components/scroll-area/markdown): A native scroll container with thin overlay scrollbars and edge fades that appear only when content overflows.
- [Resizable panels](https://uiarc.dev/components/resizable-panels/markdown): Trade space between panes by dragging the divider between them.
- [Expandable text](https://uiarc.dev/components/expandable-text/markdown): Long text clamped to a few lines with a soft fade that glides open with Read more and closes with Show less, shown only when the text overflows.

### Guidance for AI tools

Expandable card: Give a dense card more room when requested. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Resizable panels

> Trade space between panes by dragging the divider between them.

- Type: Component (disclosure)
- Access: Free, open source
- Page: https://uiarc.dev/components/resizable-panels
- Markdown: https://uiarc.dev/components/resizable-panels/markdown
- Registry item: https://uiarc.dev/r/resizable-panels.json
- Source file: `registry/components/resizable-panels/resizable-panels.tsx`
- Dependencies: motion, lucide-react
- Keywords: split view, resizable, panes, react resizable panels, resizable sidebar, draggable divider, split pane, collapsible panel, resizable layout

### When to use

- Editor, mail, or dashboard layouts where people trade space between side-by-side panes.
- Sidebars that should collapse by dragging or flicking toward the edge.
- Layouts whose pane sizes should persist between visits via onLayoutChange.

### When not to use

- Use drawer for a panel that slides over the page.
- Use tabs when only one pane needs to be visible at a time.
- Avoid it for vertical splits, since it is horizontal only.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/resizable-panels
pnpm dlx shadcn@latest add @uiarc/resizable-panels
yarn dlx shadcn@latest add @uiarc/resizable-panels
bunx --bun shadcn@latest add @uiarc/resizable-panels
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/resizable-panels.json
```

#### Manual

1. Install the dependencies:

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

2. Copy the source into your project. Main file: `registry/components/resizable-panels/resizable-panels.tsx`

   The source is in the registry item: https://uiarc.dev/r/resizable-panels.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { ResizablePanel, ResizablePanels } from "@/components/arc/resizable-panels/resizable-panels";

export function MailLayout() {
  return (
    <div style={{ height: 480 }}>
      <ResizablePanels label="Mail" onLayoutChange={saveLayout}>
        <ResizablePanel id="folders" label="Folders" defaultSize={22} minSize={160} collapsible>
          <FolderList />
        </ResizablePanel>
        <ResizablePanel id="messages" label="Messages" defaultSize={78}>
          <MessageList />
        </ResizablePanel>
      </ResizablePanels>
    </div>
  );
}
```

### API reference

#### ResizablePanels

A horizontal split view with draggable, keyboard-operable dividers between panes. Needs a definite height.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` (required) | `ReactNode` | – | ResizablePanel elements in order. The set of panes should stay stable. |
| `label` | `string` | – | aria-label for the group. |
| `onLayoutChange` | `(sizes: number[]) => void` | – | Called with each pane's share in percent after a resize settles. |
| `className` | `string` | – | Class on the group element. |

#### ResizablePanel

Configuration for one pane. The group renders it.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `id` (required) | `string` | – | Stable id, used by the divider's aria-controls. |
| `label` (required) | `string` | – | Names the pane for its divider. |
| `defaultSize` (required) | `number` | – | Starting share of the group. Shares are relative and need not sum to 100. |
| `minSize` | `number` | `80` | Width in px where the pane starts to resist. Content clips and fades below it. |
| `maxSize` | `number` | – | Maximum width in px. |
| `collapsible` | `boolean` | – | Dragging well past the minimum or flicking toward the edge snaps the pane closed. |
| `defaultCollapsed` | `boolean` | – | Starts collapsed. Requires collapsible. |
| `className` | `string` | – | Class on the pane. |
| `children` | `ReactNode` | – | Pane content. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| ArrowLeft / ArrowRight | Moves the focused divider 16px; with Shift, 64px. Past a limit, collapses a collapsible pane. |
| Home / End | Moves the divider to its minimum or maximum. |
| Enter | Collapses or restores a collapsible neighbouring pane. |
| Escape | During a drag, returns the divider to where it started. |

### Accessibility

- Each divider is a focusable role="separator" with aria-orientation, aria-controls, aria-valuenow, min, and max in percent.
- aria-valuetext announces the share, or that a pane is hidden and Enter shows it.
- Collapsed panes are inert. The group has role="group"; pass label to name it.

### Motion

- Dividers follow the pointer 1:1, rubber-band past limits, and spring to rest; flicks toward an edge collapse a pane. Double-click resets the layout.
- Pane content fades as it is squeezed below its minimum and a restore tab pops in on a snappy spring.
- Reduced motion jumps panes to their targets and fades the restore tab.

### Responsive behavior

- Panes do not stack on narrow screens; on mobile, render a single pane or switch to tabs yourself.
- Dividers use pointer capture with touch-action none, so touch, pen, and mouse drags all work.
- The group needs a definite height from its parent.

### Performance

- A ResizeObserver on the group refits pane widths when the container resizes.
- Dragging sets widths directly and springs only on release or collapse; pane content is never re-rendered by the drag itself.

### Notes for AI

- Use for editor, mail, or dashboard layouts where people trade space between side-by-side panes. Horizontal only.
- Give the parent a definite height and persist onLayoutChange shares to restore via defaultSize.

### Related

- [Drawer](https://uiarc.dev/components/drawer/markdown): A temporary side surface for focused work.
- [Tree view](https://uiarc.dev/components/tree-view/markdown): Navigate nested folders and structured content.
- [Tabs](https://uiarc.dev/components/tabs/markdown): Switch between related content in the same context.

### Also in expand

- [Scroll area](https://uiarc.dev/components/scroll-area/markdown): A native scroll container with thin overlay scrollbars and edge fades that appear only when content overflows.
- [Accordion](https://uiarc.dev/components/accordion/markdown): Progressively reveal supporting information in place.
- [Expandable card](https://uiarc.dev/components/expandable-card/markdown): Give a dense card more room when requested.
- [Expandable text](https://uiarc.dev/components/expandable-text/markdown): Long text clamped to a few lines with a soft fade that glides open with Read more and closes with Show less, shown only when the text overflows.

### Guidance for AI tools

Resizable panels: Trade space between panes by dragging the divider between them. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Expandable text

> Long text clamped to a few lines with a soft fade that glides open with Read more and closes with Show less, shown only when the text overflows.

- Type: Component (disclosure)
- Access: Free, open source
- Page: https://uiarc.dev/components/expandable-text
- Markdown: https://uiarc.dev/components/expandable-text/markdown
- Registry item: https://uiarc.dev/r/expandable-text.json
- Source file: `registry/components/expandable-text/expandable-text.tsx`
- Dependencies: motion, lucide-react
- Keywords: disclosure, text, motion, new, read more, show more, show less, truncate, line clamp, clamp, collapse text, expand text, see more, review, description, fade out text

### When to use

- A list of user reviews or comments where some entries are long.
- A product, listing, or profile description that should not push the rest of the page down.
- Any card where long text would make the cards uneven.

### When not to use

- Use accordion for a set of titled sections or an FAQ.
- Use expandable-card when the hidden part is structured content rather than running text.
- Use scroll-area when the full text must stay in a fixed height box.
- Do not clamp content people must read, such as legal terms or error details.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/expandable-text
pnpm dlx shadcn@latest add @uiarc/expandable-text
yarn dlx shadcn@latest add @uiarc/expandable-text
bunx --bun shadcn@latest add @uiarc/expandable-text
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/expandable-text.json
```

#### Manual

1. Install the dependencies:

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

2. Copy the source into your project. Main file: `registry/components/expandable-text/expandable-text.tsx`

   The source is in the registry item: https://uiarc.dev/r/expandable-text.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { ExpandableText } from "@/components/arc/expandable-text/expandable-text";

export function ReviewBody({ review }: { review: Review }) {
  return (
    <ExpandableText lines={2}>
      {review.paragraphs.map(paragraph => <p key={paragraph}>{paragraph}</p>)}
    </ExpandableText>
  );
}
```

### API reference

#### ExpandableText

Long text clamped to a few lines with a soft fade over the last one. Read more opens it smoothly to its full height and Show less closes it again. The toggle only appears when the text really overflows.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` (required) | `ReactNode` | – | The text. Strings, paragraphs, and inline links all work. The whole text stays in the accessibility tree while clamped. |
| `lines` | `number` | `3` | Lines shown while collapsed, measured in the text's own line height. |
| `expanded` | `boolean` | – | Controlled open state. |
| `defaultExpanded` | `boolean` | `false` | Starts open when uncontrolled. |
| `onExpandedChange` | `(expanded: boolean) => void` | – | Called when the toggle, or focus moving to a hidden link, opens or closes the text. |
| `moreLabel` | `string` | `"Read more"` | Toggle label while collapsed. |
| `lessLabel` | `string` | `"Show less"` | Toggle label while open. |
| `...props` | `HTMLAttributes<HTMLDivElement>` | – | Passed to the root element, including className and style. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Tab | Moves to links inside the text, then to the toggle. Focusing a link hidden below the clamp opens the text. |
| Enter / Space | Opens or closes the text from the toggle. |

### Accessibility

- The clamp is visual only: the full text stays in the accessibility tree, so screen readers read all of it without pressing the toggle.
- The toggle is a native button with aria-expanded and aria-controls pointing at the text.
- The two labels crossfade in one grid cell; the hidden one is aria-hidden, so the button's name is always just the current label.
- Links or buttons inside the clamped part open the text when they receive keyboard focus, so focus is never hidden.

### Motion

- Height, the fade mask, and the chevron all follow one progress value, so they always move in step and a click mid-way reverses from the current height.
- Opening takes 500 to 600ms and closing 400 to 450ms, growing gently with the distance, on a soft ease out (0.32, 0.5, 0.2, 1) that answers at once and spends most of its time settling. It never overshoots.
- The fade over the last line dissolves as the text opens and only returns as it nears the clamp. While moving, newly revealed lines rise through the soft edge instead of being uncovered by a hard line.
- Read more and Show less crossfade with a short drift and a brief blur, without changing the button's width.
- Closing from far down the page scrolls the start of the text back into view together with the collapse.
- At rest the clamp is plain CSS (max-height in lh units), so width and font changes need no JavaScript. With reduced motion the text opens and closes at once.

### Responsive behavior

- The clamp is measured in lines, so narrower screens show the same number of lines with fewer words; the toggle appears or disappears as wrapping changes.
- The toggle sits under the text, left aligned, with a 28px tall hit area that works on touch.

### Performance

- One ResizeObserver per instance, watching the text and a zero width probe that is exactly the clamp height.
- Only height and a mask gradient change while moving; at rest there is no inline height and, once open, no mask.
- The server renders the toggle, assuming long text; short text drops it on the first measurement.

### Notes for AI

- Use it for reviews, product descriptions, bios, comments, and release notes where the first lines are enough for most readers.
- Pick lines by context: 2 in dense lists such as reviews, 3 to 4 for a product or profile description.
- Keep one line height inside the text. Headings or large images inside break the line based clamp; use expandable-card or accordion for structured content.
- Nothing needs measuring by the caller: a ResizeObserver decides whether the toggle is shown and keeps that correct as the layout changes.

### Related

- [Expandable card](https://uiarc.dev/components/expandable-card/markdown): Give a dense card more room when requested.
- [Accordion](https://uiarc.dev/components/accordion/markdown): Progressively reveal supporting information in place.
- [Scroll area](https://uiarc.dev/components/scroll-area/markdown): A native scroll container with thin overlay scrollbars and edge fades that appear only when content overflows.

### Also in expand

- [Resizable panels](https://uiarc.dev/components/resizable-panels/markdown): Trade space between panes by dragging the divider between them.

### Guidance for AI tools

Expandable text: Long text clamped to a few lines with a soft fade that glides open with Read more and closes with Show less, shown only when the text overflows. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Dialog

> A focused surface for decisions that need attention.

- Type: Component (disclosure)
- Access: Free, open source
- Page: https://uiarc.dev/components/dialog
- Markdown: https://uiarc.dev/components/dialog/markdown
- Registry item: https://uiarc.dev/r/dialog.json
- Source file: `registry/components/dialog/dialog.tsx`
- Dependencies: @radix-ui/react-dialog, motion, lucide-react
- Keywords: modal, overlay, react dialog, animated modal, radix dialog, confirm dialog, modal window, popup dialog

### When to use

- Confirmations and decisions that must interrupt, such as Delete project.
- Short forms like rename or invite that fit in one focused panel.
- Flows where the dialog title changes between steps and should crossfade in place.

### When not to use

- Use drawer for long forms or detail panels that keep the page in context.
- Use bottom-sheet for mobile-first secondary tasks with snap heights.
- Use popover for light, non-modal content anchored to a trigger.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/dialog
pnpm dlx shadcn@latest add @uiarc/dialog
yarn dlx shadcn@latest add @uiarc/dialog
bunx --bun shadcn@latest add @uiarc/dialog
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/dialog.json
```

#### Manual

1. Install the dependencies:

```bash
npm install @radix-ui/react-dialog motion lucide-react
```

2. Copy the source into your project. Main file: `registry/components/dialog/dialog.tsx`

   The source is in the registry item: https://uiarc.dev/r/dialog.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { Dialog, DialogClose, DialogContent, DialogTrigger } from "@/components/arc/dialog/dialog";
import { Button } from "@/components/arc/button/button";

export function RenameProject() {
  return (
    <Dialog>
      <DialogTrigger asChild><Button>Rename</Button></DialogTrigger>
      <DialogContent title="Rename project" description="This changes the URL too.">
        <input defaultValue="Arc" aria-label="Project name" />
        <DialogClose asChild><Button>Save</Button></DialogClose>
      </DialogContent>
    </Dialog>
  );
}
```

### Examples

#### Confirm with a custom cancel

```tsx
<Dialog open={open} onOpenChange={setOpen}>
  <DialogContent title="Delete project?" description="This cannot be undone.">
    <DialogClose asChild><Button variant="secondary">Cancel</Button></DialogClose>
    <Button onClick={remove}>Delete</Button>
  </DialogContent>
</Dialog>
```

### API reference

#### Dialog

Root that tracks open state so the content can animate out. Controlled or uncontrolled.

| 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. |
| `...props` | `ComponentPropsWithoutRef<typeof DialogPrimitive.Root>` | – | Other Radix Dialog root props, such as modal. |

#### DialogTrigger

Radix Dialog.Trigger. Use asChild to wrap your own button.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `...props` | `ComponentPropsWithoutRef<typeof DialogPrimitive.Trigger>` | – | Radix trigger props, including asChild. |

#### DialogContent

Portaled overlay and panel with a titled header and built-in close button.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` (required) | `string` | – | Dialog title, rendered as Radix Dialog.Title. Changes crossfade while open. |
| `description` | `string` | – | Optional supporting line, rendered as Dialog.Description. |
| `children` (required) | `ReactNode` | – | Body content, usually a form or actions. |
| `...props` | `ComponentPropsWithoutRef<typeof DialogPrimitive.Content>` | – | Radix content props such as className, onEscapeKeyDown, and onPointerDownOutside. |

#### DialogClose

Radix Dialog.Close for custom cancel or confirm buttons.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `...props` | `ComponentPropsWithoutRef<typeof DialogPrimitive.Close>` | – | Radix close props, including asChild. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Escape | Closes the dialog and returns focus to the trigger. |
| Tab / Shift+Tab | Cycles focus within the dialog. |

### Accessibility

- Radix renders role="dialog" with aria-modal, traps focus, and restores it to the trigger on close.
- title and description are wired to aria-labelledby and aria-describedby.
- The close button carries aria-label="Close dialog".

### Motion

- The overlay fades while the panel rises 8px and scales from 0.96 on a smooth spring; closing is shorter and retargets from the current state.
- Title and description changes rise in with a soft blur.
- Reduced motion uses a plain opacity fade, including the CSS keyframe fallback for bare Radix roots.

### Responsive behavior

- The panel is min(100vw minus a 32px gutter, 440px) wide and centered, so it fits phones without extra CSS.
- Height caps at the viewport minus a gutter and the panel scrolls beyond that.

### Performance

- The overlay uses a 7px backdrop blur, which can cost frames on low-end devices over busy pages.
- Content renders in a portal only while open and unmounts after the exit animation.

### Notes for AI

- Use for decisions that must interrupt: confirmations, short forms. Use drawer for side panels, bottom-sheet for mobile-first secondary tasks, popover for light non-modal content.
- Always compose Dialog > DialogTrigger + DialogContent. Wrap your own buttons with asChild.

### Related

- [Drawer](https://uiarc.dev/components/drawer/markdown): A temporary side surface for focused work.
- [Bottom sheet](https://uiarc.dev/components/bottom-sheet/markdown): A sheet that rests at a peek or full height and follows your finger.
- [Popover](https://uiarc.dev/components/popover/markdown): A small anchored surface for contextual information.
- [Hold to confirm](https://uiarc.dev/components/hold-to-confirm/markdown): Confirm a destructive action by holding, not tapping.

### Also in overlays

- [Hover card](https://uiarc.dev/components/hover-card/markdown): Preview a person or link on hover or focus without leaving the page.
- [Tooltip](https://uiarc.dev/components/tooltip/markdown): Short supporting text for unfamiliar controls.
- [Share access](https://uiarc.dev/components/share-access/markdown): A share panel: invite people as validated email chips with suggestions, change roles from a compact menu, remove with undo, switch link access and copy the link, with every change landing in place.
- [Confirm popover](https://uiarc.dev/components/confirm-popover/markdown): A destructive button that grows into a small confirmation card, with the consequence, optional type-to-confirm, progress on the Confirm button, and a check or error before folding back.

### Guidance for AI tools

Dialog: A focused surface for decisions that need attention. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Drawer

> A temporary side surface for focused work.

- Type: Component (disclosure)
- Access: Free, open source
- Page: https://uiarc.dev/components/drawer
- Markdown: https://uiarc.dev/components/drawer/markdown
- Registry item: https://uiarc.dev/r/drawer.json
- Source file: `registry/components/drawer/drawer.tsx`
- Dependencies: @radix-ui/react-dialog, motion, lucide-react
- Keywords: overlay, surface, react drawer, side panel, slide over panel, sheet component, draggable drawer, radix dialog drawer, filters drawer

### When to use

- Side panels for filters, settings, or record details that keep the page in context.
- Forms that are too long for a dialog but should not leave the current view.
- Panels from any edge, via side, with drag-to-dismiss on the header.

### When not to use

- Use dialog for short decisions and confirmations.
- Use bottom-sheet for mobile-first sheets with snap points.
- Use popover for small anchored content that does not need a modal overlay.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/drawer
pnpm dlx shadcn@latest add @uiarc/drawer
yarn dlx shadcn@latest add @uiarc/drawer
bunx --bun shadcn@latest add @uiarc/drawer
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/drawer.json
```

#### Manual

1. Install the dependencies:

```bash
npm install @radix-ui/react-dialog motion lucide-react
```

2. Copy the source into your project. Main file: `registry/components/drawer/drawer.tsx`

   The source is in the registry item: https://uiarc.dev/r/drawer.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { Drawer, DrawerTrigger, DrawerContent, DrawerClose } from "@/components/arc/drawer/drawer";
import { Button } from "@/components/arc/button/button";

export function FiltersDrawer() {
  return (
    <Drawer>
      <DrawerTrigger asChild><Button variant="secondary">Filters</Button></DrawerTrigger>
      <DrawerContent title="Filters" description="Narrow the list of projects.">
        <FilterForm />
        <DrawerClose asChild><Button>Apply</Button></DrawerClose>
      </DrawerContent>
    </Drawer>
  );
}
```

### API reference

#### Drawer

Root. A Radix Dialog root that keeps the panel mounted while it slides out and closes it after a drag.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `open` | `boolean` | – | Controlled open state. |
| `defaultOpen` | `boolean` | `false` | Initial state when uncontrolled. |
| `onOpenChange` | `(open: boolean) => void` | – | Called when the drawer opens or closes. |
| `...props` | `ComponentPropsWithoutRef<typeof DialogPrimitive.Root>` | – | Other Radix Dialog root props, such as modal and children. |

#### DrawerTrigger

Radix Dialog.Trigger. Use asChild to wrap your own button.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `...props` | `ComponentPropsWithoutRef<typeof DialogPrimitive.Trigger>` | – | Radix trigger props, including asChild. |

#### DrawerContent

Overlay and panel with a titled header that doubles as the drag handle, a close button, and a scrolling body.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` (required) | `string` | – | Rendered as the dialog title. A new title rises in while open. |
| `description` | `string` | – | Rendered as the dialog description under the title. |
| `side` | `"left" \| "right" \| "top" \| "bottom"` | `"right"` | Edge the panel attaches to and slides from. |
| `children` (required) | `ReactNode` | – | Body content. |
| `...props` | `ComponentPropsWithoutRef<typeof DialogPrimitive.Content>` | – | Radix content props such as className, onInteractOutside, and onEscapeKeyDown. |

#### DrawerClose

Radix Dialog.Close for extra close buttons in the body or footer.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `...props` | `ComponentPropsWithoutRef<typeof DialogPrimitive.Close>` | – | Radix close props, including asChild. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Escape | Closes the drawer and returns focus to the trigger. |
| Tab / Shift+Tab | Cycles focus within the panel while it is open. |

### Accessibility

- Radix Dialog provides role="dialog", aria-modal, focus trapping, and focus return.
- title and description are wired to Dialog.Title and Dialog.Description, so the panel is always named.
- The header close button is labelled "Close drawer"; dragging is optional and never the only way to close.

### Motion

- The panel springs in from its edge and leaves faster on a tween; a drag past a third of the panel or a quick flick closes it and keeps the release velocity.
- Dragging the header away from the edge rubber-bands; the overlay fades in and out.
- Reduced motion disables dragging and replaces the slide with a short opacity fade.

### Responsive behavior

- Left and right panels are min(30rem, 100vw minus a gutter) wide; below 40rem they grow to nearly full width with tighter padding.
- Top and bottom panels span the full width and cap at min(32rem, 100dvh).
- The header is the drag handle with touch-action none, so a touch drag moves the panel while the body still scrolls normally.

### Performance

- The overlay uses a 4px backdrop blur, which can cost frames on low-end devices over busy pages.
- Drag runs on motion pan handlers with no React re-render per frame; the panel stays mounted only while sliding out.

### Notes for AI

- Use for side panels with forms, filters, settings, or detail views that keep the page in context. Use dialog for short decisions and bottom-sheet for mobile-first sheets.
- Always compose Drawer as the root; under a bare Radix Dialog root the panel falls back to CSS keyframes and loses drag.
- Control open when the drawer must close after an async submit.

### Related

- [Dialog](https://uiarc.dev/components/dialog/markdown): A focused surface for decisions that need attention.
- [Bottom sheet](https://uiarc.dev/components/bottom-sheet/markdown): A sheet that rests at a peek or full height and follows your finger.
- [Popover](https://uiarc.dev/components/popover/markdown): A small anchored surface for contextual information.
- [Button](https://uiarc.dev/components/button/markdown): A clear, responsive action with quiet secondary states.

### Also in overlays

- [Hover card](https://uiarc.dev/components/hover-card/markdown): Preview a person or link on hover or focus without leaving the page.
- [Tooltip](https://uiarc.dev/components/tooltip/markdown): Short supporting text for unfamiliar controls.
- [Share access](https://uiarc.dev/components/share-access/markdown): A share panel: invite people as validated email chips with suggestions, change roles from a compact menu, remove with undo, switch link access and copy the link, with every change landing in place.
- [Confirm popover](https://uiarc.dev/components/confirm-popover/markdown): A destructive button that grows into a small confirmation card, with the consequence, optional type-to-confirm, progress on the Confirm button, and a check or error before folding back.

### Guidance for AI tools

Drawer: A temporary side surface for focused work. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Bottom sheet

> A sheet that rests at a peek or full height and follows your finger.

- Type: Component (disclosure)
- Access: Free, open source
- Page: https://uiarc.dev/components/bottom-sheet
- Markdown: https://uiarc.dev/components/bottom-sheet/markdown
- Registry item: https://uiarc.dev/r/bottom-sheet.json
- Source file: `registry/components/bottom-sheet/bottom-sheet.tsx`
- Dependencies: @radix-ui/react-dialog, motion, lucide-react
- Keywords: overlay, gesture, motion, react bottom sheet, mobile bottom sheet, draggable sheet, ios sheet, snap points sheet, detents, swipe up panel

### When to use

- Mobile-first secondary tasks such as details, filters, or share options.
- Content that benefits from a peek height before expanding to nearly full screen.
- Maps and media views where the sheet should be dragged between detents.

### When not to use

- Use dialog for interrupting decisions on any screen size.
- Use drawer for side panels on wide desktop layouts.
- Use popover for small anchored content that should not dim the page.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/bottom-sheet
pnpm dlx shadcn@latest add @uiarc/bottom-sheet
yarn dlx shadcn@latest add @uiarc/bottom-sheet
bunx --bun shadcn@latest add @uiarc/bottom-sheet
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/bottom-sheet.json
```

#### Manual

1. Install the dependencies:

```bash
npm install @radix-ui/react-dialog motion lucide-react
```

2. Copy the source into your project. Main file: `registry/components/bottom-sheet/bottom-sheet.tsx`

   The source is in the registry item: https://uiarc.dev/r/bottom-sheet.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { BottomSheet, BottomSheetClose } from "@/components/arc/bottom-sheet/bottom-sheet";
import { Button } from "@/components/arc/button/button";

export function TripSheet() {
  return (
    <BottomSheet
      trigger={<Button>Trip details</Button>}
      title="Lisbon, 3 nights"
      description="Oct 12 to Oct 15"
      detents={[0.4, 0.9]}
    >
      <p>Flights, hotel, and bookings.</p>
      <BottomSheetClose asChild><Button variant="secondary">Done</Button></BottomSheetClose>
    </BottomSheet>
  );
}
```

### Examples

#### Controlled sheet with detent tracking

```tsx
<BottomSheet
  open={open}
  onOpenChange={setOpen}
  title="Filters"
  detents={[0.5]}
  onDetentChange={index => track("detent", index)}
>
  <FilterList />
</BottomSheet>
```

### API reference

#### BottomSheet

A modal sheet that rises from the bottom edge and rests at one or more detents, with drag, flick, and keyboard control.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` (required) | `string` | – | Sheet title, rendered as Dialog.Title. |
| `children` (required) | `ReactNode` | – | Scrollable sheet content. |
| `trigger` | `ReactNode` | – | Control that opens the sheet. Rendered with asChild; focus returns to it on close. |
| `open` | `boolean` | – | Controlled open state. |
| `defaultOpen` | `boolean` | `false` | Initial open state when uncontrolled. |
| `onOpenChange` | `(open: boolean) => void` | – | Called when the sheet opens or closes. |
| `description` | `string` | – | Supporting line, rendered as Dialog.Description. |
| `detents` | `number[]` | `[0.45, 0.92]` | Resting heights as fractions of the viewport height. |
| `initialDetent` | `number` | `0` | Index into the sorted detents the sheet opens at. |
| `onDetentChange` | `(index: number) => void` | – | Called when the sheet settles on a different detent. |
| `closeLabel` | `string` | `"Close"` | aria-label of the close button. |
| `className` | `string` | – | Class on the sheet surface. |

#### BottomSheetClose

Radix Dialog.Close for buttons inside the sheet.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `...props` | `ComponentPropsWithoutRef<typeof DialogPrimitive.Close>` | – | Radix close props, including asChild. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| ArrowUp / ArrowDown | On the grabber, moves one detent up or down. |
| Home / End | On the grabber, jumps to the tallest or smallest detent. |
| Enter / Space | On the grabber, toggles between smallest and tallest detent. |
| ArrowDown / PageDown / Space | On the sheet, expands to full height first, then scrolls the content. |
| Escape | Closes the sheet. |

### Accessibility

- Built on Radix Dialog: role="dialog", focus trap, and focus return to the trigger. Initial focus lands on the sheet itself.
- The grabber is a button with aria-expanded and an Expand or Collapse sheet label.
- Detent changes are announced through a polite live region.
- Tabbing into content below the fold expands the sheet so focused elements are visible.

### Motion

- One motion value drives the sheet: drags follow the finger 1:1, rubber-band past the tallest detent, and releases project velocity to pick a detent or dismiss.
- The backdrop dim is a function of sheet position, so it tracks drags instead of running on a timer.
- Reduced motion jumps between detents and fades the sheet in and out.

### Responsive behavior

- The sheet is min(100%, 36rem) wide and detents are fractions of the dynamic viewport height, so it adapts to mobile browser chrome.
- Below 40rem the header and body use tighter side padding.
- Touch drags on the content move the sheet until it is fully open, then the content scrolls; mouse and pen drag from the header.

### Performance

- One motion value drives position and backdrop, so drags do not re-render React per frame.
- A ResizeObserver re-fits detents on viewport changes; content is not virtualized, so paginate long lists inside it.

### Notes for AI

- Use for mobile-first secondary tasks where a peek helps: details, filters, share options. Use dialog for interrupting decisions and drawer for side panels on wide layouts.
- Pass a trigger or control open yourself. Use a single-value detents array for a fixed-height sheet.

### Related

- [Drawer](https://uiarc.dev/components/drawer/markdown): A temporary side surface for focused work.
- [Dialog](https://uiarc.dev/components/dialog/markdown): A focused surface for decisions that need attention.
- [Popover](https://uiarc.dev/components/popover/markdown): A small anchored surface for contextual information.

### Also in overlays

- [Hover card](https://uiarc.dev/components/hover-card/markdown): Preview a person or link on hover or focus without leaving the page.
- [Tooltip](https://uiarc.dev/components/tooltip/markdown): Short supporting text for unfamiliar controls.
- [Share access](https://uiarc.dev/components/share-access/markdown): A share panel: invite people as validated email chips with suggestions, change roles from a compact menu, remove with undo, switch link access and copy the link, with every change landing in place.
- [Confirm popover](https://uiarc.dev/components/confirm-popover/markdown): A destructive button that grows into a small confirmation card, with the consequence, optional type-to-confirm, progress on the Confirm button, and a check or error before folding back.

### Guidance for AI tools

Bottom sheet: A sheet that rests at a peek or full height and follows your finger. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Popover

> A small anchored surface for contextual information.

- Type: Component (disclosure)
- Access: Free, open source
- Page: https://uiarc.dev/components/popover
- Markdown: https://uiarc.dev/components/popover/markdown
- Registry item: https://uiarc.dev/r/popover.json
- Source file: `registry/components/popover/popover.tsx`
- Dependencies: @radix-ui/react-popover
- Keywords: overlay, menu, react popover, radix popover, floating panel, click popover, animated popover, anchored popup

### When to use

- Click-opened panels with interactive content, like share settings or a small filter form.
- Non-modal helpers that should stay open while people interact with the rest of the page.
- Custom pickers built from your own controls anchored to a button.

### When not to use

- Use tooltip for short hover labels.
- Use hover-card for read-only previews that open on hover.
- Use dialog when the choice must block the page, and dropdown-menu for a list of commands.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/popover
pnpm dlx shadcn@latest add @uiarc/popover
yarn dlx shadcn@latest add @uiarc/popover
bunx --bun shadcn@latest add @uiarc/popover
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/popover.json
```

#### Manual

1. Install the dependencies:

```bash
npm install @radix-ui/react-popover
```

2. Copy the source into your project. Main file: `registry/components/popover/popover.tsx`

   The source is in the registry item: https://uiarc.dev/r/popover.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { Popover, PopoverContent, PopoverTrigger } from "@/components/arc/popover/popover";
import { Button } from "@/components/arc/button/button";

export function ShareMenu() {
  return (
    <Popover>
      <PopoverTrigger asChild><Button variant="secondary">Share</Button></PopoverTrigger>
      <PopoverContent>
        <p>Anyone with the link can view.</p>
      </PopoverContent>
    </Popover>
  );
}
```

### API reference

#### Popover

Radix Popover.Root. Holds open state.

| 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` | Traps focus and blocks outside interaction when true. |

#### PopoverTrigger

Radix trigger that opts out of press-scale so the panel does not shift on open.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `...props` | `ComponentPropsWithoutRef<typeof PopoverPrimitive.Trigger>` | – | Radix trigger props, including asChild and ref. |

#### PopoverContent

Portaled floating panel anchored to the trigger.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `align` | `"start" \| "center" \| "end"` | `"start"` | Alignment against the trigger. |
| `sideOffset` | `number` | `6` | Gap from the trigger in px. |
| `collisionPadding` | `number` | `10` | Minimum distance from viewport edges in px. |
| `...props` | `ComponentPropsWithoutRef<typeof PopoverPrimitive.Content>` | – | Radix content props such as side, className, and onOpenAutoFocus. |

#### PopoverClose

Radix Popover.Close for an explicit dismiss button.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `...props` | `ComponentPropsWithoutRef<typeof PopoverPrimitive.Close>` | – | Radix close props, including asChild. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Enter / Space | Opens the popover from the trigger. |
| Escape | Closes the popover and returns focus to the trigger. |

### Accessibility

- Radix sets aria-expanded, aria-controls, and aria-haspopup="dialog" on the trigger.
- Focus moves into the content on open and back to the trigger on close.
- Content is non-modal by default; give it a heading or aria-label when it holds controls.

### Motion

- CSS transitions: the panel fades and settles from 5px toward its trigger at 0.97 scale on a spring; it leaves in 140ms.
- Transitions instead of keyframes, so a reopen mid-close reverses from where the panel is.
- Reduced motion drops the transform and keeps a short opacity fade.

### Responsive behavior

- The panel is at least 12rem and at most min(22rem, 100vw minus 20px), so it never overflows a phone screen.
- Radix collision handling keeps it 10px from viewport edges by default and flips sides when needed.

### Performance

- Pure CSS transitions with no motion runtime; content mounts in a portal only while open.

### Notes for AI

- Use for click-opened, non-modal panels with interactive content. Use tooltip for short hover labels, hover-card for read-only previews, dialog when the choice must block.
- Compose Popover > PopoverTrigger asChild + PopoverContent. Pass side for placement.

### Related

- [Tooltip](https://uiarc.dev/components/tooltip/markdown): Short supporting text for unfamiliar controls.
- [Hover card](https://uiarc.dev/components/hover-card/markdown): Preview a person or link on hover or focus without leaving the page.
- [Dialog](https://uiarc.dev/components/dialog/markdown): A focused surface for decisions that need attention.
- [Dropdown menu](https://uiarc.dev/components/dropdown-menu/markdown): A focused list of actions anchored to a trigger.

### Also in overlays

- [Drawer](https://uiarc.dev/components/drawer/markdown): A temporary side surface for focused work.
- [Bottom sheet](https://uiarc.dev/components/bottom-sheet/markdown): A sheet that rests at a peek or full height and follows your finger.
- [Share access](https://uiarc.dev/components/share-access/markdown): A share panel: invite people as validated email chips with suggestions, change roles from a compact menu, remove with undo, switch link access and copy the link, with every change landing in place.
- [Confirm popover](https://uiarc.dev/components/confirm-popover/markdown): A destructive button that grows into a small confirmation card, with the consequence, optional type-to-confirm, progress on the Confirm button, and a check or error before folding back.

### Guidance for AI tools

Popover: A small anchored surface for contextual information. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Hover card

> Preview a person or link on hover or focus without leaving the page.

- Type: Component (disclosure)
- Access: Free, open source
- Page: https://uiarc.dev/components/hover-card
- Markdown: https://uiarc.dev/components/hover-card/markdown
- Registry item: https://uiarc.dev/r/hover-card.json
- Source file: `registry/components/hover-card/hover-card.tsx`
- Dependencies: @radix-ui/react-popover, motion
- Keywords: preview, people, popover, react hover card, profile preview, user hover card, mention preview, link preview popup, radix hover card

### When to use

- Previews of people behind mentions, avatars, or author names.
- Link or reference previews where the click must stay free for navigation.
- Dense lists where moving between triggers should open cards almost instantly.

### When not to use

- Use tooltip for a plain text label.
- Use popover when the content has buttons or inputs.
- Use user-menu for the account menu on your own avatar.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/hover-card
pnpm dlx shadcn@latest add @uiarc/hover-card
yarn dlx shadcn@latest add @uiarc/hover-card
bunx --bun shadcn@latest add @uiarc/hover-card
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/hover-card.json
```

#### Manual

1. Install the dependencies:

```bash
npm install @radix-ui/react-popover motion
```

2. Copy the source into your project. Main file: `registry/components/hover-card/hover-card.tsx`

   The source is in the registry item: https://uiarc.dev/r/hover-card.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { HoverCard, HoverCardProfile } from "@/components/arc/hover-card/hover-card";

export function Mention() {
  return (
    <HoverCard
      content={<HoverCardProfile name="Maya Chen" role="Product designer, Payments" stats={[{ label: "Projects", value: 12 }]} />}
    >
      <button type="button">@maya</button>
    </HoverCard>
  );
}
```

### API reference

#### HoverCard

A read-only preview that opens after a short hover or keyboard focus and stays open while the pointer travels into it.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` (required) | `ReactElement` | – | The trigger, such as a mention button or link. Must accept a ref and be focusable. |
| `content` (required) | `ReactNode` | – | The preview. HoverCardProfile covers people. |
| `side` | `"top" \| "bottom" \| "left" \| "right"` | `"bottom"` | Preferred side of the trigger. |
| `align` | `"start" \| "center" \| "end"` | `"start"` | Alignment against the trigger. |
| `openDelay` | `number` | `500` | Milliseconds of hover before the first card opens. |
| `closeDelay` | `number` | `140` | Grace in milliseconds after the pointer leaves. |
| `className` | `string` | – | Class on the card surface. |

#### HoverCardProfile

A person preview: portrait, name, role, bio, stats, and a footer line.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `name` (required) | `string` | – | Full name. Initials are derived from it when there is no avatar. |
| `role` | `string` | – | Role and team. |
| `avatar` | `string \| ReactNode` | – | Portrait URL or your own image element such as next/image. |
| `bio` | `string` | – | Short bio paragraph. |
| `stats` | `{ label: string; value: string \| number }[]` | `[]` | Rendered as a definition list. |
| `meta` | `ReactNode` | – | Footer line such as location and local time. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Tab | Keyboard focus on the trigger opens the card immediately. |
| Enter | Opens the card without the hover delay. |
| Escape | Closes the card and keeps it closed while the pointer rests on the trigger. |

### Accessibility

- The card has role="tooltip" and the trigger gets aria-describedby while it is open.
- Focus never moves into the card, so keep its content read only.
- On touch, a tap toggles the card instead of relying on hover.

### Motion

- Grows from the trigger edge: scale from 0.96 and a 4px offset on a smooth spring, with a separate fade. Mid-exit returns retarget instead of jumping.
- Within 300ms of another card, the next opens after 80ms with a fade only. Profile rows settle in with a small stagger.
- Reduced motion drops scale and travel and keeps a short fade.

### Responsive behavior

- The card is 18.5rem wide, capped at the space Radix reports as available or the viewport minus 24px.
- On touch, a tap toggles the card instead of waiting for hover.
- Long names and roles ellipsize and stats wrap onto new lines.

### Performance

- Only one hover card is open on the page, and it mounts in a portal only while open.
- Open and close use timers, not pointer tracking loops; the profile avatar decodes async.

### Notes for AI

- Use for previews of people, links, or references where the click must stay free for navigation. Use tooltip for plain labels and popover for interactive content.
- Only one hover card is open at a time on the page. Anything actionable belongs behind the trigger itself.

### Related

- [Tooltip](https://uiarc.dev/components/tooltip/markdown): Short supporting text for unfamiliar controls.
- [Popover](https://uiarc.dev/components/popover/markdown): A small anchored surface for contextual information.
- [Avatar](https://uiarc.dev/components/avatar/markdown): A compact identity marker for people and accounts.
- [User menu](https://uiarc.dev/components/user-menu/markdown): Your account, settings, theme, and sign out behind the avatar. Opens as a bottom sheet on phones.

### Also in overlays

- [Dialog](https://uiarc.dev/components/dialog/markdown): A focused surface for decisions that need attention.
- [Drawer](https://uiarc.dev/components/drawer/markdown): A temporary side surface for focused work.
- [Bottom sheet](https://uiarc.dev/components/bottom-sheet/markdown): A sheet that rests at a peek or full height and follows your finger.
- [Share access](https://uiarc.dev/components/share-access/markdown): A share panel: invite people as validated email chips with suggestions, change roles from a compact menu, remove with undo, switch link access and copy the link, with every change landing in place.
- [Confirm popover](https://uiarc.dev/components/confirm-popover/markdown): A destructive button that grows into a small confirmation card, with the consequence, optional type-to-confirm, progress on the Confirm button, and a check or error before folding back.

### Guidance for AI tools

Hover card: Preview a person or link on hover or focus without leaving the page. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Tooltip

> Short supporting text for unfamiliar controls.

- Type: Component (disclosure)
- Access: Free, open source
- Page: https://uiarc.dev/components/tooltip
- Markdown: https://uiarc.dev/components/tooltip/markdown
- Registry item: https://uiarc.dev/r/tooltip.json
- Source file: `registry/components/tooltip/tooltip.tsx`
- Dependencies: @radix-ui/react-tooltip, motion
- Keywords: hint, overlay, react tooltip, radix tooltip, icon button tooltip, hover label, animated tooltip, tooltip component

### When to use

- One-line labels on icon-only buttons in toolbars.
- Revealing the full text of truncated labels on hover or focus.
- Dense toolbars where moving between icons should show labels instantly after the first one.

### When not to use

- Use popover for anything with links or controls inside.
- Use hover-card for rich previews such as a person or link.
- Avoid it for information people must see on touch devices, where hover does not exist.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/tooltip
pnpm dlx shadcn@latest add @uiarc/tooltip
yarn dlx shadcn@latest add @uiarc/tooltip
bunx --bun shadcn@latest add @uiarc/tooltip
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/tooltip.json
```

#### Manual

1. Install the dependencies:

```bash
npm install @radix-ui/react-tooltip motion
```

2. Copy the source into your project. Main file: `registry/components/tooltip/tooltip.tsx`

   The source is in the registry item: https://uiarc.dev/r/tooltip.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { Tooltip } from "@/components/arc/tooltip/tooltip";

export function ArchiveButton() {
  return (
    <Tooltip content="Archive">
      <button type="button" aria-label="Archive">
        <ArchiveIcon />
      </button>
    </Tooltip>
  );
}
```

### API reference

#### Tooltip

A short label on hover or focus that opens without delay when moving between tooltips.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `content` (required) | `ReactNode` | – | Tooltip content. Strings and numbers crossfade and resize when they change while open. |
| `children` (required) | `ReactElement` | – | The trigger. Rendered with asChild, so it must accept a ref and be focusable. |
| `side` | `"top" \| "bottom"` | `"top"` | Preferred side of the trigger. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Tab | Focusing the trigger opens the tooltip. |
| Escape | Closes the tooltip. |

### Accessibility

- Radix links the content to the trigger with aria-describedby and renders role="tooltip".
- Content is supplemental: icon-only triggers still need their own aria-label.
- Do not put interactive elements inside; use popover instead.

### Motion

- Opens after 250ms with a 3px rise from 0.97 scale; within 300ms of another tooltip it opens instantly with a fade only.
- Changing string content rises in with a blur while the bubble springs to the new size.
- Reduced motion removes the transform and keeps a 90ms opacity fade.

### Responsive behavior

- The bubble caps at 15rem and wraps longer text; Radix flips it to the other side near viewport edges.
- It opens on hover and keyboard focus, so touch users rarely see it; never hide essential information in one.

### Performance

- Each tooltip brings its own provider and mounts content in a portal only while open.
- A ResizeObserver measures the text only to spring the bubble size when content changes while open.

### Notes for AI

- Use for one-line labels on icon buttons and truncated text. Use hover-card for rich previews and popover for anything interactive.
- Each Tooltip brings its own provider; no app-level wrapper is needed.

### Related

- [Popover](https://uiarc.dev/components/popover/markdown): A small anchored surface for contextual information.
- [Hover card](https://uiarc.dev/components/hover-card/markdown): Preview a person or link on hover or focus without leaving the page.
- [Action button](https://uiarc.dev/components/action-button/markdown): A compact button for frequent toolbar actions.

### Also in overlays

- [Dialog](https://uiarc.dev/components/dialog/markdown): A focused surface for decisions that need attention.
- [Drawer](https://uiarc.dev/components/drawer/markdown): A temporary side surface for focused work.
- [Bottom sheet](https://uiarc.dev/components/bottom-sheet/markdown): A sheet that rests at a peek or full height and follows your finger.
- [Share access](https://uiarc.dev/components/share-access/markdown): A share panel: invite people as validated email chips with suggestions, change roles from a compact menu, remove with undo, switch link access and copy the link, with every change landing in place.
- [Confirm popover](https://uiarc.dev/components/confirm-popover/markdown): A destructive button that grows into a small confirmation card, with the consequence, optional type-to-confirm, progress on the Confirm button, and a check or error before folding back.

### Guidance for AI tools

Tooltip: Short supporting text for unfamiliar controls. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Share access

> A share panel: invite people as validated email chips with suggestions, change roles from a compact menu, remove with undo, switch link access and copy the link, with every change landing in place.

- Type: Component (disclosure)
- Access: Arc Pro
- Page: https://uiarc.dev/components/share-access
- Markdown: https://uiarc.dev/components/share-access/markdown
- Source file: `registry/components/share-access/share-access.tsx`
- Dependencies: motion, lucide-react, @radix-ui/react-dropdown-menu
- Keywords: overlay, sharing, permissions, new, share, access, invite, email chips, roles, can edit, can view, link sharing, copy link, collaborators, google docs share, popover

### When to use

- A Share button on a document, board or project that controls who can open it and what they can do.
- Inviting teammates by email with suggestions from a workspace directory.
- Managing link sharing next to per person access in one place.

### When not to use

- Use the invite-people block for inviting people to a whole workspace with seats and plans.
- Use copy-button alone when there is only a public link to share.
- Use a full settings page with a data table for organisations with hundreds of members and groups.

### Installation

Share access is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/share-access
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import * as Popover from "@radix-ui/react-popover";
import { ShareAccess } from "@/components/arc/share-access/share-access";

export function ShareButton({ doc }: { doc: Doc }) {
  const [open, setOpen] = useState(false);
  const { data: members, mutate } = useMembers(doc.id);

  return (
    <Popover.Root open={open} onOpenChange={setOpen}>
      <Popover.Trigger>Share</Popover.Trigger>
      <Popover.Portal>
        <Popover.Content align="end" sideOffset={8}>
          <ShareAccess
            title={doc.title}
            members={members}
            onMembersChange={next => mutate(api.setMembers(doc.id, next), { optimisticData: next })}
            directory={workspace.people}
            link={doc.url}
            selfId={me.id}
            onInvite={(people, role) => api.invite(doc.id, people, role)}
            onDone={() => setOpen(false)}
          />
        </Popover.Content>
      </Popover.Portal>
    </Popover.Root>
  );
}
```

### API reference

#### ShareAccess

A share panel for a document, board or project. Type names or emails and they become chips: people from your directory show their photo, and an address that is not valid turns red with a message under the field. Suggestions with avatars appear as you type. Pick the role for the invite and send; the new people slide into the list with a brief highlight. Each person's role changes from a compact menu whose label morphs to its new width, Remove access folds the row away with an undo, general access switches between restricted and anyone with the link, and Copy link confirms in place without changing width.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` | `string` | `"Q3 launch plan"` | Name of what is being shared, used in the heading Share “title” and the accessible name. |
| `members` | `readonly ShareAccessMember[]` | – | People with access: { id, email, name?, src?, role: "owner" \| "editor" \| "commenter" \| "viewer", pending? }. Pass with onMembersChange to control the list. |
| `defaultMembers` | `readonly ShareAccessMember[]` | `[]` | Initial members when uncontrolled. |
| `onMembersChange` | `(members: ShareAccessMember[]) => void` | – | Called with the new list after an invite, a role change, a removal or an undo. |
| `access` | `"restricted" \| "link"` | – | Who can open it without an invite. Pass with onAccessChange to control it. |
| `defaultAccess` | `"restricted" \| "link"` | `"restricted"` | Initial general access when uncontrolled. |
| `onAccessChange` | `(access: ShareGeneralAccess) => void` | – | Called when general access changes. |
| `linkRole` | `"viewer" \| "commenter" \| "editor"` | – | What anyone with the link can do. Its menu slides in beside general access when the link is open. |
| `defaultLinkRole` | `ShareRole` | `"viewer"` | Initial link role when uncontrolled. |
| `onLinkRoleChange` | `(role: ShareRole) => void` | – | Called when the link role changes. |
| `directory` | `readonly ShareAccessContact[]` | `[]` | People to suggest while typing: { email, name?, src? }. Matches the start of any name part or the email; people who already have access or are already chips are left out. Typing a directory name exactly also resolves to that person. |
| `link` | `string` | – | The link Copy link puts on the clipboard. |
| `selfId` | `string` | – | Id of the member using the app, marked (you). |
| `defaultInviteRole` | `ShareRole` | `"editor"` | Role preselected for new invites. |
| `onInvite` | `(people: ShareAccessContact[], role: ShareRole) => void \| Promise<void>` | – | Called with the valid chips and role when Invite is pressed. Return a promise to show Sending; if it rejects, the chips stay and a message explains it. Once it resolves the people join the list as pending. |
| `onCopyLink` | `(link: string) => void` | – | Called after the link is on the clipboard. |
| `onDone` | `() => void` | – | Shows a Done button that calls this, for example to close the popover. |
| `className` | `string` | – | Class on the panel. |
| `style` | `CSSProperties` | – | Inline styles on the panel. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Type, then Enter | Adds the highlighted suggestion, or turns what you typed into a chip. With chips and nothing typed, Enter sends the invite. |
| Comma / Semicolon / Tab | Turns what you typed into a chip. Space does too once the text contains an @. |
| Arrow Down / Arrow Up | Moves through suggestions. |
| Backspace | In an empty field, the first press marks the last chip and the second removes it. |
| Escape | Clears the text and closes suggestions; in a menu, closes the menu and returns focus to its trigger. |
| Enter / Space on a role | Opens the role menu; arrows move, Enter picks, and typing a letter jumps to an option. |

### Accessibility

- The panel is a section named Share “title”. The field is a combobox with a listbox of suggestions, aria-activedescendant for the highlighted one and aria-expanded.
- An invalid address sets aria-invalid, is marked with an icon as well as color, and its message is linked with aria-describedby.
- Each chip has a Remove button named with the person. Each role trigger is named with the person and the current role, such as Role for Nathan Cole: Can edit.
- Role and access menus are Radix dropdown menus with radio items, so the current choice is announced as checked and focus returns to the trigger.
- Adding and removing chips, invites, role changes, removals, undo, access changes and copying are announced in a polite live region.
- Copy link keeps its width across Copy link, Link copied and Couldn’t copy, and the failure state pairs an icon with text.
- Pointer focus draws no ring; keyboard focus shows Arc's shared focus ring. Hovered and focused triggers and rows take a muted background.

### Motion

- Chips pop in from 80 percent scale on the snappy spring and the field reflows around them with layout transforms, so the caret slides to its new spot.
- Suggestions open under the field with a short scale and fade, and the highlight slides between rows as a shared layout element.
- The error line and the invite row expand and collapse in height on the smooth spring, which never overshoots.
- New people expand into the list with a brief accent tint that fades over a second. A removed row folds its height to zero while the rows below slide up, and the undo bar slides in beneath.
- Role labels crossfade vertically while the trigger's width follows the new label on the morph spring, so the chevron glides instead of jumping. The count of people rolls.
- The lock turns into a globe with a small rotation, the description rolls to its new line and the link role menu slides in from the right without moving anything else.
- Copy link swaps to a check and Link copied in place, then back after 1.8 seconds.
- With reduced motion all of it applies at once: no pops, rolls, slides or height animation.

### Responsive behavior

- The panel is up to 440px wide and fills narrower containers. At 420px and below padding tightens and the link role moves under the general access line.
- Long names and emails truncate with an ellipsis in rows and chips; the full value is in the accessible name.
- Chips wrap onto new lines inside the field as it grows; menus stay inside the viewport with collision padding.

### Performance

- Everything that moves is a transform or opacity except row and message heights, which animate only when they appear or leave.
- Suggestions filter a directory array in memory; for very large directories, pass a pre filtered directory from your search.
- Menus mount only while open.

### Notes for AI

- Use it as the content of a share popover or dialog for any object with per person access: documents, boards, projects, folders.
- Control members and persist every change; the component emits the whole next list. Use optimistic updates so rows land instantly.
- Return a promise from onInvite for the server call. Reject it to keep the chips so the person can retry.
- Pass directory from your workspace so people are suggested with photos. Anyone else can still be invited by email.
- Owner rows cannot be changed or removed. Map any other permission scheme to the three roles or fork ROLES in the source.
- The panel draws its own floating surface; when placing it inside a popover primitive, keep that popover's content unstyled.

### Related

- [Popover](https://uiarc.dev/components/popover/markdown): A small anchored surface for contextual information.
- [Tag input](https://uiarc.dev/components/tag-input/markdown): Turn short text values into removable tags.
- [Dropdown menu](https://uiarc.dev/components/dropdown-menu/markdown): A focused list of actions anchored to a trigger.
- [Copy button](https://uiarc.dev/components/copy-button/markdown): Copy a value with immediate confirmation.
- [Presence stack](https://uiarc.dev/components/presence-stack/markdown): Avatars of the people here now: joins pop in as the stack reflows, a counter rolls past the limit, dots show typing and idle, and hover fans it out with a gliding name label.
- [Combobox](https://uiarc.dev/components/combobox/markdown): Search and select from a list without leaving the field.

### Also in overlays

- [Dialog](https://uiarc.dev/components/dialog/markdown): A focused surface for decisions that need attention.
- [Drawer](https://uiarc.dev/components/drawer/markdown): A temporary side surface for focused work.
- [Bottom sheet](https://uiarc.dev/components/bottom-sheet/markdown): A sheet that rests at a peek or full height and follows your finger.
- [Hover card](https://uiarc.dev/components/hover-card/markdown): Preview a person or link on hover or focus without leaving the page.
- [Tooltip](https://uiarc.dev/components/tooltip/markdown): Short supporting text for unfamiliar controls.
- [Confirm popover](https://uiarc.dev/components/confirm-popover/markdown): A destructive button that grows into a small confirmation card, with the consequence, optional type-to-confirm, progress on the Confirm button, and a check or error before folding back.

### Guidance for AI tools

Share access: A share panel: invite people as validated email chips with suggestions, change roles from a compact menu, remove with undo, switch link access and copy the link, with every change landing in place. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Confirm popover

> A destructive button that grows into a small confirmation card, with the consequence, optional type-to-confirm, progress on the Confirm button, and a check or error before folding back.

- Type: Component (disclosure)
- Access: Arc Pro
- Page: https://uiarc.dev/components/confirm-popover
- Markdown: https://uiarc.dev/components/confirm-popover/markdown
- Source file: `registry/components/confirm-popover/confirm-popover.tsx`
- Dependencies: motion, lucide-react
- Keywords: overlay, confirm, motion, new, confirmation, popover, delete, destructive, danger zone, are you sure, type to confirm, progress, inline confirm, morph, revoke, remove, alertdialog

### When to use

- A danger zone in settings: delete project, transfer ownership, revoke a member.
- A row action in a table where a modal would lose the row's context.
- Any destructive action that needs a sentence of consequence and a visible result without leaving the page.

### When not to use

- Reversible removals such as archiving; use undo-toast so the action is instant and recoverable.
- A one word inline confirmation in a toolbar; use confirm-morph, which morphs horizontally inside the button's row.
- Long forms or several decisions; use dialog.

### Installation

Confirm popover is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/confirm-popover
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { Trash2 } from "lucide-react";
import { ConfirmPopover } from "@/components/arc/confirm-popover/confirm-popover";

export function DeleteProject({ project }: { project: Project }) {
  return (
    <ConfirmPopover
      icon={<Trash2 size={16} />}
      align="end"
      title={`Delete ${project.name}?`}
      description={`This permanently deletes ${project.deployments} deployments and every log. It can't be undone.`}
      confirmText={project.slug}
      confirmLabel="Delete project"
      errorTitle={`Couldn't delete ${project.name}`}
      onConfirm={async ({ setProgress, signal }) => {
        for await (const step of api.deleteProject(project.id, { signal })) setProgress(step.done / step.total);
      }}
      onDone={() => router.push("/projects")}
    >
      Delete
    </ConfirmPopover>
  );
}
```

### API reference

#### ConfirmPopover

A destructive button that asks in place. Pressing it grows the button itself, as one surface, into a small floating card that states the consequence, with Cancel and Confirm and an optional phrase to type first. Confirm is also the progress bar: it widens as Cancel folds away and fills with the action's progress, its label inverting exactly at the fill edge. On success the card folds back into the button's shape with a check; on failure it stays open, shakes once and shows the error with Try again. Escape and a press outside cancel; focus moves into the card and back to the button.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` (required) | `ReactNode` | – | The trigger label, such as Delete project. |
| `title` (required) | `ReactNode` | – | The question, such as Delete Atlas?. It names the dialog. |
| `description` | `ReactNode` | – | The consequence in one or two short sentences. It describes the dialog. |
| `icon` | `ReactNode` | – | A plain 16px icon before the trigger label. |
| `confirmText` | `string` | – | A phrase to type before Confirm unlocks, such as the project name. Matching ignores case and outer spaces. Confirm fills in the tone color as the typed prefix matches, and a wrong submit shakes the card. |
| `confirmLabel` | `string` | `"Delete"` | Label of the confirm button. |
| `cancelLabel` | `string` | `"Cancel"` | Label of the cancel button. |
| `pendingLabel` | `string` | `"Deleting"` | Label on the progress bar while onConfirm runs, followed by the percentage when progress is reported. |
| `successLabel` | `string` | `"Deleted"` | Shown with a check in the button's shape once onConfirm resolves. Keep it no longer than the trigger label so the width holds. |
| `errorTitle` | `ReactNode` | `"That didn't work"` | Heading of the failure. The rejection's message is shown under it. |
| `retryLabel` | `string` | `"Try again"` | Label of the confirm button after a failure. |
| `tone` | `"danger" \| "neutral"` | `"danger"` | danger tints the trigger and fills Confirm in the danger color. neutral uses the foreground, for serious but reversible actions. |
| `onConfirm` | `(ctx: ConfirmPopoverContext) => void \| Promise<unknown>` | – | Runs the action. ctx.setProgress(0 to 1) drives the bar; without it the bar sweeps. ctx.signal aborts if the component unmounts. A rejection shows the failure. |
| `onCancel` | `() => void` | – | Called when the question is dismissed by Cancel, Escape or a press outside. |
| `onDone` | `() => void` | – | Called once the success state has been shown and the button is back at rest. |
| `onError` | `(error: unknown) => void` | – | Called with the rejection when onConfirm fails. |
| `open` | `boolean` | – | Controlled open state of the question. Pair with onOpenChange. |
| `defaultOpen` | `boolean` | `false` | Opens on mount when uncontrolled. |
| `onOpenChange` | `(open: boolean) => void` | – | Called when the question opens, is dismissed, or closes after success. |
| `onPhaseChange` | `(phase: ConfirmPopoverPhase) => void` | – | Called with idle, confirming, working, success or error. |
| `align` | `"start" \| "center" \| "end"` | `"start"` | Which edge of the button the card keeps. end grows toward the start, for buttons at the end of a row. The card shifts to stay 16px inside the window either way. |
| `side` | `"bottom" \| "top" \| "auto"` | `"auto"` | Grow downward, upward, or upward only when there is not room below. |
| `width` | `number` | `320` | Width of the open card in px, never wider than the window less 32px. |
| `resultDuration` | `number` | `1600` | Milliseconds the success state holds before the button returns to rest. |
| `disabled` | `boolean` | – | Disables the trigger. |
| `className` | `string` | – | Class on the root element. |
| `style` | `CSSProperties` | – | Inline styles on the root element. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Enter / Space | On the button, opens the question. Focus moves to the phrase field when there is one, otherwise to Cancel. |
| Tab / Shift+Tab | Cycles through the field, Cancel and Confirm while the card is open. |
| Enter | In the phrase field, confirms once the phrase matches; otherwise the card shakes and focus stays in the field. |
| Escape | Cancels the question or dismisses a failure, and returns focus to the button once the card has folded back. |

### Accessibility

- The trigger has aria-haspopup="dialog" and aria-expanded. The open card is a non modal alertdialog named by the title and described by the consequence.
- The phrase field has a visible label that includes the phrase; it is marked aria-invalid while the typed text does not match.
- While the action runs the card is aria-busy and holds focus; a polite live region reads the pending label and the percentage, then the success label or the failure. The failure is also a role="alert" paragraph and focus moves to Try again.
- Confirm stays in the tab order while locked and says so with aria-disabled, so people can reach it and hear why it does nothing yet.
- The trigger is kept in place, invisible, while the card covers it, and takes focus back only after the card has folded into it, so focus is never lost to the page.

### Motion

- One surface: at rest it is drawn exactly over the button, then its width, height and corner radius spring to the card on the morph spring (a hint of bounce) and back on the smooth spring. The edge nearest the button stays still, and the content is pinned to that edge, so the card is revealed in place rather than sliding.
- The button face fades out in 100ms as the card content fades up 6px from a 4px blur, 60ms later. Tint, border and floating shadow crossfade from the button's look to the card's.
- Typing the phrase fills Confirm on the snappy spring to the share of the phrase matched so far; a second copy of the label in the fill's ink is clipped to the fill, so the text inverts exactly at its edge.
- Confirming folds Cancel away on the smooth spring while Confirm widens to the full row; the fill drops to zero and then follows reported progress, or a soft sweep runs when there is none.
- Success fills the bar, then the card folds back to the button's size with the check rotating in. Failure refills the bar as Try again, opens the error on a height spring and shakes the card once with a damped keyframe.
- With reduced motion the size changes are instant and only the faces crossfade; there is no shake and the sweep becomes a static tint.

### Responsive behavior

- The card is 320px wide by default and never wider than the window less 32px; it shifts horizontally to stay 16px from either edge, so it works from a 320px phone upward.
- It grows downward unless there is not enough room below the button, then upward, keeping the button's edge still.
- The phrase field disables autocorrect, autocapitalise and spellcheck, so phones do not change what is typed.

### Performance

- Only one surface is mounted while the question is open, and nothing is mounted at rest besides the button.
- The fill and its inverted label use a clip-path driven by a motion value, so typing and progress updates do not re-render the component.
- Width and height animate on a single absolutely positioned layer, which does not reflow the page around it.

### Notes for AI

- Use it for irreversible or serious actions where the consequence should be read before confirming: deleting a project, revoking access, rotating keys, cancelling a subscription.
- Write the description as the consequence, with numbers when you have them: This deletes 14 deployments and every log. It can't be undone.
- Add confirmText only for the most destructive actions; typing the resource name is friction by design.
- Report progress from onConfirm with ctx.setProgress when the action has steps; otherwise the bar sweeps until the promise settles. Throw an Error with a human message to show it under the error title.
- Keep successLabel short, such as Deleted or Removed, so the button does not change width at rest.
- The card floats over the page with position absolute inside the component. Do not place it in an ancestor with overflow hidden that is smaller than the card.

### Related

- [Confirm morph](https://uiarc.dev/components/confirm-morph/markdown): A destructive button that morphs into an inline confirmation, a spinner, and a result with undo.
- [Hold to confirm](https://uiarc.dev/components/hold-to-confirm/markdown): Confirm a destructive action by holding, not tapping.
- [Dialog](https://uiarc.dev/components/dialog/markdown): A focused surface for decisions that need attention.
- [Undo toast](https://uiarc.dev/components/undo-toast/markdown): Archive or delete rows with a second chance: the gap closes, a countdown toast merges repeat actions, and Undo or ⌘Z puts every row back exactly where it was.

### Also in overlays

- [Drawer](https://uiarc.dev/components/drawer/markdown): A temporary side surface for focused work.
- [Bottom sheet](https://uiarc.dev/components/bottom-sheet/markdown): A sheet that rests at a peek or full height and follows your finger.
- [Popover](https://uiarc.dev/components/popover/markdown): A small anchored surface for contextual information.
- [Hover card](https://uiarc.dev/components/hover-card/markdown): Preview a person or link on hover or focus without leaving the page.
- [Tooltip](https://uiarc.dev/components/tooltip/markdown): Short supporting text for unfamiliar controls.
- [Share access](https://uiarc.dev/components/share-access/markdown): A share panel: invite people as validated email chips with suggestions, change roles from a compact menu, remove with undo, switch link access and copy the link, with every change landing in place.

### Guidance for AI tools

Confirm popover: A destructive button that grows into a small confirmation card, with the consequence, optional type-to-confirm, progress on the Confirm button, and a check or error before folding back. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Alert

> A persistent message that helps people recover or continue.

- Type: Component (feedback)
- Access: Free, open source
- Page: https://uiarc.dev/components/alert
- Markdown: https://uiarc.dev/components/alert/markdown
- Registry item: https://uiarc.dev/r/alert.json
- Source file: `registry/components/alert/alert.tsx`
- Dependencies: motion, lucide-react
- Keywords: status, message, react alert, alert banner, inline notification, warning message, animated alert, dismissible alert, callout

### When to use

- Persistent, in-flow messages about a page or form, such as an expiring card.
- Status that changes over time, where one alert should morph between tones.
- Dismissible notices that should collapse and close the gap below them.

### When not to use

- Use toast or toast-stack for transient results of an action.
- Use empty-state when there is no content to show.
- Use dialog when people must respond before continuing.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/alert
pnpm dlx shadcn@latest add @uiarc/alert
yarn dlx shadcn@latest add @uiarc/alert
bunx --bun shadcn@latest add @uiarc/alert
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/alert.json
```

#### Manual

1. Install the dependencies:

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

2. Copy the source into your project. Main file: `registry/components/alert/alert.tsx`

   The source is in the registry item: https://uiarc.dev/r/alert.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { Alert } from "@/components/arc/alert/alert";

export function BillingNotice() {
  return (
    <Alert tone="warning" title="Card expires soon" onDismiss={() => track("dismissed")}>
      Update your payment method before March 1 to avoid interruption.
    </Alert>
  );
}
```

### API reference

#### Alert

An inline message with a tone icon, title, and optional details that morph when they change.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` (required) | `string` | – | Headline. A new title rises in over the old one. |
| `tone` | `"info" \| "success" \| "warning" \| "danger"` | `"info"` | Colour and icon. Danger uses role="alert"; the rest use role="status". |
| `children` | `ReactNode` | – | Details under the title. String children crossfade when they change. |
| `open` | `boolean` | – | Controls presence. Hiding collapses the height and fades it out. |
| `onDismiss` | `() => void` | – | Shows a dismiss button. Uncontrolled alerts collapse first, then call this. |
| `...props` | `HTMLAttributes<HTMLDivElement>` | – | Forwarded to the alert element, such as className and id. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Enter / Space | Activates the dismiss button when present. |

### Accessibility

- Danger alerts use role="alert" and interrupt; other tones use role="status" and announce politely.
- Outgoing copies are aria-hidden while they fade, so the live region reads only the current text.
- The dismiss button is labelled "Dismiss: <title>"; the tone icon is aria-hidden.

### Motion

- Presence collapses or expands the height on a smooth spring with a fade, so content below closes the gap.
- Tone changes morph the icon through a small scale and blur; copy changes rise in while the height springs to fit.
- Reduced motion swaps content with short fades and no height animation.

### Responsive behavior

- The alert fills its container and the copy wraps; the icon and dismiss button keep fixed sizes.
- Hover styles on the dismiss button apply only on hover-capable fine pointers.

### Performance

- A ResizeObserver lets the height spring when copy changes; keep only a few alerts mounted per page.

### Notes for AI

- Use for persistent, in-flow messages tied to a page or form. Use toast or toast-stack for transient results of an action.
- Keep one Alert mounted and change tone, title, and children to morph between states instead of swapping components.

### Related

- [Toast](https://uiarc.dev/components/toast/markdown): Brief confirmation for a completed background action.
- [Toast stack](https://uiarc.dev/components/toast-stack/markdown): Stack short results at the edge until you reach for them.
- [Empty state](https://uiarc.dev/components/empty-state/markdown): A useful next step when there is nothing to show yet.

### Also in messages

- [Announcement bar](https://uiarc.dev/components/announcement-bar/markdown): A top banner that rotates messages, counts down, and collapses smoothly when dismissed.
- [Cookie consent](https://uiarc.dev/components/cookie-consent/markdown): A consent bar that morphs into preferences and folds into a reopen button.
- [Undo toast](https://uiarc.dev/components/undo-toast/markdown): Archive or delete rows with a second chance: the gap closes, a countdown toast merges repeat actions, and Undo or ⌘Z puts every row back exactly where it was.

### Guidance for AI tools

Alert: A persistent message that helps people recover or continue. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Toast

> Brief confirmation for a completed background action.

- Type: Component (feedback)
- Access: Free, open source
- Page: https://uiarc.dev/components/toast
- Markdown: https://uiarc.dev/components/toast/markdown
- Registry item: https://uiarc.dev/r/toast.json
- Source file: `registry/components/toast/toast.tsx`
- Dependencies: motion, lucide-react
- Keywords: status, message, react toast, toast notification, success toast, swipe to dismiss toast, animated toast, snackbar

### When to use

- A single success confirmation, like Changes saved, controlled with local state.
- Demos or small apps that do not need a toast queue.

### When not to use

- Use toast-stack for app-wide notifications with types, actions, updates, and stacking.
- Use alert for persistent messages that should stay in the page flow.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/toast
pnpm dlx shadcn@latest add @uiarc/toast
yarn dlx shadcn@latest add @uiarc/toast
bunx --bun shadcn@latest add @uiarc/toast
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/toast.json
```

#### Manual

1. Install the dependencies:

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

2. Copy the source into your project. Main file: `registry/components/toast/toast.tsx`

   The source is in the registry item: https://uiarc.dev/r/toast.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import Toast from "@/components/arc/toast/toast";

export function SavedToast() {
  const [open, setOpen] = useState(false);
  return (
    <>
      <button type="button" onClick={() => setOpen(true)}>Save</button>
      <Toast open={open} onOpenChange={setOpen} title="Changes saved" description="Synced to all devices." />
    </>
  );
}
```

### API reference

#### Toast

A single swipeable notification with a drawn check, auto-dismiss, and morphing copy. Default export.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` (required) | `string` | – | Headline. Changes crossfade while shown. |
| `description` | `string` | – | Supporting line. |
| `open` | `boolean` | `true` | Whether the toast is shown. Setting it true again after a dismiss re-raises it. |
| `onOpenChange` | `(open: boolean) => void` | – | Called with false on close, swipe, or timeout. Auto-dismiss only runs when this is provided. |
| `duration` | `number` | `4500` | Milliseconds before auto-dismiss. 0 or less disables it. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Tab then Enter | Reaches and activates the dismiss button. |

### Accessibility

- Renders role="status" with aria-live="polite" and aria-atomic, so new content is announced without stealing focus.
- The dismiss button is labelled "Dismiss notification"; the check icon is aria-hidden.
- Positioning is up to the caller; the auto-dismiss timer does not pause on hover, so keep messages short.

### Motion

- Enters rising 16px from 0.96 scale on a morph spring while the check draws in; a swipe past 80px or 480px/s throws it off with its release velocity.
- Closing sinks it 8px and fades. Copy changes rise in while the height springs to fit.
- Reduced motion uses opacity fades and disables dragging.

### Responsive behavior

- The toast is min(100%, 26rem) wide and the title ellipsizes on one line.
- Positioning is up to you; fix it to the bottom center on phones so it clears the thumb zone edges.
- It swipes horizontally on touch and mouse; drag is disabled under reduced motion.

### Performance

- Drag and throw run on motion values, and a ResizeObserver springs the height when copy changes.
- The auto-dismiss timer does not pause on hover, so keep messages short.

### Notes for AI

- Use for a single success confirmation you control with local state. Use toast-stack for an app-wide queue with types, actions, updates, and stacking.
- Import as a default export. Position it yourself, for example fixed to the bottom of the viewport.

### Related

- [Toast stack](https://uiarc.dev/components/toast-stack/markdown): Stack short results at the edge until you reach for them.
- [Alert](https://uiarc.dev/components/alert/markdown): A persistent message that helps people recover or continue.

### Also in messages

- [Announcement bar](https://uiarc.dev/components/announcement-bar/markdown): A top banner that rotates messages, counts down, and collapses smoothly when dismissed.
- [Cookie consent](https://uiarc.dev/components/cookie-consent/markdown): A consent bar that morphs into preferences and folds into a reopen button.
- [Undo toast](https://uiarc.dev/components/undo-toast/markdown): Archive or delete rows with a second chance: the gap closes, a countdown toast merges repeat actions, and Undo or ⌘Z puts every row back exactly where it was.

### Guidance for AI tools

Toast: Brief confirmation for a completed background action. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Toast stack

> Stack short results at the edge until you reach for them.

- Type: Component (feedback)
- Access: Free, open source
- Page: https://uiarc.dev/components/toast-stack
- Markdown: https://uiarc.dev/components/toast-stack/markdown
- Registry item: https://uiarc.dev/r/toast-stack.json
- Source file: `registry/components/toast-stack/toast-stack.tsx`
- Dependencies: motion, lucide-react
- Keywords: toast, notification, sonner, react toast stack, toast notifications, sonner alternative, stacked toasts, notification queue, promise toast, undo toast

### When to use

- App-wide notifications for async results, errors, and undo.
- Loading toasts that morph into success or error when work finishes.
- Toasts with an action button, like View or Undo.

### When not to use

- Use toast for a single locally controlled confirmation.
- Use alert for persistent messages tied to a page.
- Use notification-center for a history people can come back to.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/toast-stack
pnpm dlx shadcn@latest add @uiarc/toast-stack
yarn dlx shadcn@latest add @uiarc/toast-stack
bunx --bun shadcn@latest add @uiarc/toast-stack
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/toast-stack.json
```

#### Manual

1. Install the dependencies:

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

2. Copy the source into your project. Main file: `registry/components/toast-stack/toast-stack.tsx`

   The source is in the registry item: https://uiarc.dev/r/toast-stack.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { ToastStack, ToastStackProvider, useToastStack } from "@/components/arc/toast-stack/toast-stack";

function PublishButton() {
  const { toast, update } = useToastStack();
  async function publish() {
    const id = toast({ type: "loading", title: "Publishing" });
    await api.publish();
    update(id, { type: "success", title: "Published", action: { label: "View", onClick: openSite } });
  }
  return <button type="button" onClick={publish}>Publish</button>;
}

export function App() {
  return <ToastStackProvider><PublishButton /><ToastStack /></ToastStackProvider>;
}
```

### Examples

#### Undo action

```tsx
const { toast, dismiss } = useToastStack();

toast({
  type: "info",
  title: "Message archived",
  action: { label: "Undo", onClick: id => { restore(); dismiss(id); } },
});
```

### API reference

#### ToastStackProvider

Scopes a toast queue to its subtree. Wrap the app or panel once.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` (required) | `ReactNode` | – | Subtree that can raise toasts. |
| `duration` | `number` | `5000` | Base lifetime in ms. Warnings and errors stay 1.6 times longer; loading waits for an update. |
| `limit` | `number` | `12` | Oldest toasts beyond this count are dropped. |

#### ToastStack

The viewport. Toasts rise from the bottom, tuck behind each other, and fan out on hover or focus.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` | `string` | `"Notifications"` | Accessible name of the region. |
| `position` | `"bottom-right" \| "bottom-center" \| "bottom-left"` | `"bottom-right"` | Corner of the viewport. |
| `contained` | `boolean` | `false` | Pins the stack inside the nearest positioned ancestor instead of the window. |
| `visibleToasts` | `number` | `3` | How many toasts show at once. |
| `hotkey` | `boolean` | `true` | Alt+T moves focus into the stack. |
| `className` | `string` | – | Class on the region. |

#### useToastStack

Hook returning { toast, update, dismiss, count }. Must be called inside ToastStackProvider.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `toast` | `(options: ToastOptions) => string` | – | Shows a toast and returns its id. Options: id, type ("success" \| "info" \| "warning" \| "error" \| "loading"), title, description, action { label, onClick(id) }, duration. |
| `update` | `(id: string, patch: Partial<Omit<ToastOptions, "id">>) => void` | – | Morphs a toast in place and restarts its timer. Pass action: undefined to remove the action. |
| `dismiss` | `(id?: string) => void` | – | Dismisses one toast, or all when called without an id. |
| `count` | `number` | – | How many toasts are queued. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Alt+T | Moves focus to the front toast and fans out the stack. |
| Tab | Moves between toast actions and dismiss buttons. |
| Escape | Dismisses the focused toast. |

### Accessibility

- The viewport is a labelled section with aria-live="polite" and aria-relevant="additions text", so new and updated toasts are announced.
- Each toast prefixes a screen-reader-only type label such as "Error:"; outgoing copy is aria-hidden while it fades.
- Hidden and leaving toasts are inert. When a focused toast closes, keyboard focus moves to the next toast or back to where it came from.
- Timers pause while the stack is hovered, focused, dragged, or the tab is hidden.

### Motion

- New toasts rise from their own height below the edge; older ones tuck behind at 14px peeks and 0.05 scale steps, and fan out on a morph spring.
- Swiping right follows the finger and throws with velocity; left rubber-bands. Updates morph the icon, copy, height, and action width in place.
- Reduced motion jumps positions and uses short opacity fades.

### Responsive behavior

- The viewport is min(22.5rem, 100% minus a 32px gutter) wide; below 30rem it centers at the bottom regardless of position.
- Below a 21rem toast width the action button drops under the copy instead of squeezing it.
- On touch, a tap fans out the stack, and a right swipe dismisses a toast.

### Performance

- At most 12 toasts are kept by default and only 3 show; each has its own ResizeObserver for height.
- Timers pause while hovered, focused, dragged, or when the tab is hidden.

### Notes for AI

- Default for app-wide notifications, async results, and undo. Use toast for a single locally controlled confirmation and alert for persistent inline messages.
- Render ToastStack once inside ToastStackProvider and call useToastStack anywhere below. Reuse an id or call update to morph loading into success or error.

### Related

- [Toast](https://uiarc.dev/components/toast/markdown): Brief confirmation for a completed background action.
- [Alert](https://uiarc.dev/components/alert/markdown): A persistent message that helps people recover or continue.
- [Hold to confirm](https://uiarc.dev/components/hold-to-confirm/markdown): Confirm a destructive action by holding, not tapping.

### Also in messages

- [Announcement bar](https://uiarc.dev/components/announcement-bar/markdown): A top banner that rotates messages, counts down, and collapses smoothly when dismissed.
- [Cookie consent](https://uiarc.dev/components/cookie-consent/markdown): A consent bar that morphs into preferences and folds into a reopen button.
- [Undo toast](https://uiarc.dev/components/undo-toast/markdown): Archive or delete rows with a second chance: the gap closes, a countdown toast merges repeat actions, and Undo or ⌘Z puts every row back exactly where it was.

### Guidance for AI tools

Toast stack: Stack short results at the edge until you reach for them. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Announcement bar

> A top banner that rotates messages, counts down, and collapses smoothly when dismissed.

- Type: Component (feedback)
- Access: Free, open source
- Page: https://uiarc.dev/components/announcement-bar
- Markdown: https://uiarc.dev/components/announcement-bar/markdown
- Registry item: https://uiarc.dev/r/announcement-bar.json
- Source file: `registry/components/announcement-bar/announcement-bar.tsx`
- Dependencies: motion, lucide-react
- Keywords: feedback, new, react announcement bar, top banner, promo banner, site notice bar, dismissible banner, rotating announcements, sale countdown banner

### When to use

- Site-wide promotions, launches, or maintenance notices at the top of every page.
- Rotating two to four short announcements in one slim bar.
- A sale banner with a live countdown to its end.

### When not to use

- Use alert for a message tied to one section or form.
- Use toast for feedback on something the visitor just did.
- Use cookie-consent for consent choices.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/announcement-bar
pnpm dlx shadcn@latest add @uiarc/announcement-bar
yarn dlx shadcn@latest add @uiarc/announcement-bar
bunx --bun shadcn@latest add @uiarc/announcement-bar
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/announcement-bar.json
```

#### Manual

1. Install the dependencies:

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

2. Copy the source into your project. Main file: `registry/components/announcement-bar/announcement-bar.tsx`

   The source is in the registry item: https://uiarc.dev/r/announcement-bar.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { AnnouncementBar } from "@/components/arc/announcement-bar/announcement-bar";

export function SiteBanner() {
  return (
    <AnnouncementBar
      id="fall-sale-2026"
      tone="inverted"
      messages={[
        { id: "sale", message: "Fall sale: 30% off annual plans.", countdown: { to: "2026-10-01T00:00:00Z", label: "Ends in" }, action: { label: "See plans", href: "/pricing" } },
        { id: "launch", message: "Workflows are now in beta.", action: { label: "Read more", href: "/blog/workflows" } },
      ]}
    />
  );
}
```

### API reference

#### AnnouncementBar

A slim top-of-page bar that rotates messages with a timer ring, supports a call to action and live countdown, and remembers dismissal.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `messages` (required) | `Announcement[]` | – | Messages: { id, message, action?, countdown? }. action is { label, href?, onClick? }; countdown is { to, label? }. |
| `id` | `string` | – | Remembers dismissal in localStorage under arc-announcement:<id>. Change it to show a new campaign again. |
| `open` | `boolean` | – | Controlled visibility. Stored dismissal is ignored when set. |
| `defaultOpen` | `boolean` | `true` | Starting visibility when uncontrolled. |
| `onOpenChange` | `(open: boolean) => void` | – | Called with false when the visitor dismisses the bar. |
| `index` | `number` | – | Controlled index of the visible message. |
| `defaultIndex` | `number` | `0` | Starting message when uncontrolled. |
| `onIndexChange` | `(index: number) => void` | – | Called when rotation or the arrows change the message. |
| `interval` | `number` | `6000` | Milliseconds each message stays before the next one. |
| `autoPlay` | `boolean` | `true` | Rotates automatically. Off when the visitor prefers reduced motion. |
| `controls` | `boolean` | `false` | Shows previous, next, and the pause ring when there are several messages. Off by default: only the close button shows and messages still rotate. |
| `dismissible` | `boolean` | `true` | Shows the dismiss button. |
| `tone` | `"neutral" \| "inverted"` | `"neutral"` | Muted surface, or foreground-colored bar with background text. |
| `onAction` | `(announcement: Announcement) => void` | – | Called when a message's call to action is pressed, after its own onClick. |
| `onCountdownEnd` | `(announcement: Announcement) => void` | – | Called once when a message's countdown reaches zero. |
| `label` | `string` | `"Announcements"` | Accessible name of the region. |
| `className` | `string` | – | Class on the section. |
| `ref` | `Ref<HTMLElement>` | – | The section element. |

#### clearAnnouncementDismissal

Forgets a remembered dismissal so the bar with this id shows again.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `id` (required) | `string` | – | The id passed to AnnouncementBar. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Tab | Moves through the call to action and dismiss button, plus previous, pause, and next when controls is on. Focus inside pauses rotation. |
| Enter / Space | Presses the focused control. |

### Accessibility

- The bar is a labelled section; with several messages it is a carousel and each message a slide labelled n of total.
- The viewport is aria-live off while rotating and polite while paused, so auto-rotation is not read aloud.
- With controls, the pause ring is a toggle button with aria-pressed and previous and next buttons control the slides region. Without controls, rotation still pauses on hover and focus.
- Countdowns are role="timer" with aria-live off and a spoken label in hours and minutes.
- Rotation pauses on hover, keyboard focus inside, or a hidden tab.

### Motion

- Next messages rise from below and leave upward (previous runs the other way) while the viewport springs to the new height.
- With controls, the ring around the pause button fills linearly over the interval, stops where it is on pause, and finishes the rest on resume.
- Countdown digits drop in from above; dismissing collapses the bar's height so the page below eases up.
- Reduced motion turns rotation off, swaps messages and digits with fades, and removes the height collapse.

### Responsive behavior

- Wide bars mirror the controls with an empty column so the message stays centered on the page.
- The bar is an inline-size container; at 560px and below messages align to the start edge instead of centering.
- Messages wrap on small screens and the viewport springs to the wrapped height; icon buttons are 32px.

### Performance

- One linear motion value drives the ring; it stops while paused, hidden, or dismissed.
- A countdown ticks with one timeout per second, waking just after each whole second.

### Notes for AI

- Place it above the site header. With an id, dismissal persists; call clearAnnouncementDismissal(id) or change the id to show it again.
- Keep messages to one short sentence; the call to action is a link when href is set, a button otherwise.
- For a standalone countdown elsewhere on the page use countdown; this bar has its own lighter timer.

### Related

- [Countdown](https://uiarc.dev/components/countdown/markdown): A launch countdown with rolling digits that morphs into a live state at zero.
- [Cookie consent](https://uiarc.dev/components/cookie-consent/markdown): A consent bar that morphs into preferences and folds into a reopen button.
- [Alert](https://uiarc.dev/components/alert/markdown): A persistent message that helps people recover or continue.
- [Toast](https://uiarc.dev/components/toast/markdown): Brief confirmation for a completed background action.
- [Badge](https://uiarc.dev/components/badge/markdown): A small label for status, category, or metadata.

### Also in messages

- [Toast stack](https://uiarc.dev/components/toast-stack/markdown): Stack short results at the edge until you reach for them.
- [Undo toast](https://uiarc.dev/components/undo-toast/markdown): Archive or delete rows with a second chance: the gap closes, a countdown toast merges repeat actions, and Undo or ⌘Z puts every row back exactly where it was.

### Guidance for AI tools

Announcement bar: A top banner that rotates messages, counts down, and collapses smoothly when dismissed. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Cookie consent

> A consent bar that morphs into preferences and folds into a reopen button.

- Type: Component (feedback)
- Access: Free, open source
- Page: https://uiarc.dev/components/cookie-consent
- Markdown: https://uiarc.dev/components/cookie-consent/markdown
- Registry item: https://uiarc.dev/r/cookie-consent.json
- Source file: `registry/components/cookie-consent/cookie-consent.tsx`
- Dependencies: motion, lucide-react
- Keywords: feedback, new, react cookie consent, cookie banner, gdpr consent, cookie preferences, consent manager, privacy banner, tracking consent

### When to use

- Asking for cookie or tracking consent on a marketing site or app.
- Sites that need per-category choices with a way to reopen them later.

### When not to use

- Use announcement-bar for a site-wide promotion or notice that needs no choice.
- Use toast for a one-off message that dismisses itself.
- Use dialog when the page must block until the visitor decides.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/cookie-consent
pnpm dlx shadcn@latest add @uiarc/cookie-consent
yarn dlx shadcn@latest add @uiarc/cookie-consent
bunx --bun shadcn@latest add @uiarc/cookie-consent
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/cookie-consent.json
```

#### Manual

1. Install the dependencies:

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

2. Copy the source into your project. Main file: `registry/components/cookie-consent/cookie-consent.tsx`

   The source is in the registry item: https://uiarc.dev/r/cookie-consent.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { useRef } from "react";
import { CookieConsent, type CookieConsentHandle } from "@/components/arc/cookie-consent/cookie-consent";

export function Consent() {
  const consent = useRef<CookieConsentHandle>(null);
  return (
    <>
      <CookieConsent
        ref={consent}
        storageKey="acme-consent"
        policy={{ label: "Cookie policy", href: "/cookies" }}
        onChange={value => { if (value?.analytics) loadAnalytics(); }}
      />
      <button type="button" onClick={() => consent.current?.openPreferences()}>Cookie settings</button>
    </>
  );
}
```

### API reference

#### CookieConsent

A consent bar that morphs into a preferences panel and then folds into a small reopen button, with optional localStorage memory.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `categories` | `CookieCategory[]` | `defaultCookieCategories` | Groups: { id, label, description?, required?, defaultEnabled? }. Required ones are always on. |
| `value` | `CookieConsentValue \| null` | – | Controlled saved choice (category id to allowed). null means the visitor has not decided. |
| `defaultValue` | `CookieConsentValue \| null` | `null` | Starting choice when uncontrolled. |
| `onChange` | `(value: CookieConsentValue \| null, detail: { action: CookieConsentAction; updatedAt: Date }) => void` | – | Called on accept-all, reject-all, save, or reset. Load optional scripts from here. |
| `storageKey` | `string` | – | Remembers the choice in localStorage under this key. Read it elsewhere with readCookieConsent. |
| `version` | `string` | `"1"` | Bump when categories or policy change; a stored choice for another version is ignored and the bar asks again. |
| `preferencesOpen` | `boolean` | – | Controlled open state of the preferences panel. |
| `defaultPreferencesOpen` | `boolean` | `false` | Opens the panel on first render when uncontrolled. |
| `onPreferencesOpenChange` | `(open: boolean) => void` | – | Called when the panel opens or closes. |
| `policy` | `{ label: string; href?: string; onClick?: () => void }` | – | Link to the full policy, shown in the bar and panel. Renders a button when href is missing. |
| `position` | `"bottom" \| "bottom-left" \| "bottom-right"` | `"bottom"` | Where the bar sits along the bottom edge. |
| `strategy` | `"fixed" \| "absolute"` | `"fixed"` | fixed pins to the viewport; absolute fills the nearest positioned ancestor, for previews. |
| `showReopenButton` | `boolean` | `true` | Keeps a 44px cookie button after a choice so visitors can change their mind. |
| `reopenSide` | `"left" \| "right"` | – | Corner for the reopen button. Defaults to the bar's side, or left when centered. |
| `labels` | `Partial<CookieConsentLabels>` | – | Overrides for message, customize, acceptAll, rejectAll, save, preferencesTitle, preferencesDescription, reopen, alwaysOn, and close. |
| `className` | `string` | – | Class on the layer. |
| `ref` | `Ref<CookieConsentHandle>` | – | Imperative handle: openPreferences(), closePreferences(), reset(). |

#### readCookieConsent

Reads a saved choice as { value, version, updatedAt }, or null when there is none or it was saved for another version. Safe on the server.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `storageKey` (required) | `string` | – | The same key passed to CookieConsent. |
| `version` | `string` | `"1"` | The version the choice must match. |

#### defaultCookieCategories

The default categories: Strictly necessary (required), Preferences, Analytics, and Marketing.

No props.

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Tab | Moves through the bar or panel buttons and switches. |
| Space | Toggles the focused category switch. |
| Escape | Closes the preferences panel without saving and returns focus to the bar or reopen button. |

### Accessibility

- The bar and panel are non-modal dialogs; the bar is described by its message and the panel is labelled by its heading.
- Opening the panel focuses its heading; saving focuses the reopen button, which has aria-haspopup="dialog" and the reopen label.
- Each switch is labelled by its category and described by its hint; required categories show Always on text instead of a switch.
- Save is described by a hidden count such as 2 of 3 optional categories allowed.
- Reject all sits beside Accept all at the same weight, so refusing is as easy as accepting.

### Motion

- One surface springs its position, width, height, and radius between the bar, the panel, and the 44px reopen button; faces rise from a short blur.
- Growing uses a slightly bouncy spring and shrinking a flat one, so the surface never overshoots when it folds away.
- The surface enters rising 24px and scaling from 0.98.
- Reduced motion jumps the surface to each shape and swaps faces with a plain fade.

### Responsive behavior

- The bar is at most 660px and the panel 420px wide, both clamped to the layer, which sits 16px from the viewport edges.
- Below a 560px bar width the message stacks above the actions; panel actions go on one row at a 340px container width.
- The layer ignores pointer input, so only the surface blocks clicks on the page behind it.

### Performance

- Nothing renders until hydration and the stored choice are read, so a decided visitor never sees the bar flash.
- One ResizeObserver tracks the layer width and one tracks the current face; motion runs only when the shape changes.

### Notes for AI

- Mount once near the root layout. Gate optional scripts on onChange or on readCookieConsent(storageKey, version) at startup.
- Bump version whenever categories or the policy change to ask everyone again.
- Wire a footer Cookie settings link to ref.openPreferences(). Set showReopenButton={false} if that link is the only way back.
- Use strategy="absolute" inside a positioned preview frame, not for production.

### Related

- [Switch](https://uiarc.dev/components/switch/markdown): A tactile toggle for settings that take effect immediately.
- [Button](https://uiarc.dev/components/button/markdown): A clear, responsive action with quiet secondary states.
- [Announcement bar](https://uiarc.dev/components/announcement-bar/markdown): A top banner that rotates messages, counts down, and collapses smoothly when dismissed.
- [Toast](https://uiarc.dev/components/toast/markdown): Brief confirmation for a completed background action.
- [Dialog](https://uiarc.dev/components/dialog/markdown): A focused surface for decisions that need attention.

### Also in messages

- [Alert](https://uiarc.dev/components/alert/markdown): A persistent message that helps people recover or continue.
- [Toast stack](https://uiarc.dev/components/toast-stack/markdown): Stack short results at the edge until you reach for them.
- [Undo toast](https://uiarc.dev/components/undo-toast/markdown): Archive or delete rows with a second chance: the gap closes, a countdown toast merges repeat actions, and Undo or ⌘Z puts every row back exactly where it was.

### Guidance for AI tools

Cookie consent: A consent bar that morphs into preferences and folds into a reopen button. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Undo toast

> Archive or delete rows with a second chance: the gap closes, a countdown toast merges repeat actions, and Undo or ⌘Z puts every row back exactly where it was.

- Type: Component (feedback)
- Access: Arc Pro
- Page: https://uiarc.dev/components/undo-toast
- Markdown: https://uiarc.dev/components/undo-toast/markdown
- Source file: `registry/components/undo-toast/undo-toast.tsx`
- Dependencies: motion, lucide-react
- Keywords: feedback, toast, undo, new, snackbar, archive, delete, trash, inbox, list, remove, restore, countdown, cmd z, ctrl z, optimistic, batch, gmail undo

### When to use

- An inbox, notification list, task list or file list where archiving or deleting should be one click with a way back.
- Bulk triage, where people remove several items quickly and one toast should summarise them all.
- Anywhere a confirmation dialog would slow down a routine, reversible action.

### When not to use

- Irreversible destruction such as deleting a project or revoking keys; use confirm-popover so the consequence is stated first.
- General app notifications that are not tied to removing list items; use toast-stack.
- Lists of hundreds of visible rows animating at once; virtualise the list and remove through the ref handle instead.

### Installation

Undo toast is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/undo-toast
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { Archive, Trash2 } from "lucide-react";
import { UndoToast, UndoToastRow, UndoToastRowAction } from "@/components/arc/undo-toast/undo-toast";

export function Inbox({ threads, setThreads }: { threads: Thread[]; setThreads: (t: Thread[]) => void }) {
  return (
    <UndoToast
      label="Conversations"
      items={threads}
      onItemsChange={setThreads}
      getKey={thread => thread.id}
      noun={["conversation", "conversations"]}
      onCommit={entries => api.apply(entries.map(e => ({ id: e.key, action: e.kind })))}
      style={{ paddingBottom: 76 }}
      renderItem={(thread, { remove }) => (
        <UndoToastRow
          label={`${thread.from}, ${thread.subject}`}
          leading={<Avatar src={thread.avatar} />}
          title={thread.from}
          description={thread.subject}
          meta={thread.time}
          shortcuts={{ e: () => remove("archive"), Backspace: () => remove("delete") }}
          actions={<>
            <UndoToastRowAction label="Archive" icon={<Archive size={16} />} onClick={() => remove("archive")} />
            <UndoToastRowAction label="Delete" icon={<Trash2 size={16} />} onClick={() => remove("delete")} />
          </>}
        />
      )}
    />
  );
}
```

### API reference

#### UndoToast

A list whose rows can be archived or deleted with a second chance. The removed row fades and slips aside while its gap closes on a spring, and a toast rises from the bottom with a countdown ring that drains around the seconds left. Removing more rows merges them into the same toast: the count rolls up, the ring refills and the toast gives a small nudge. Undo, or Cmd/Ctrl+Z, opens every row again in its exact original place, top to bottom, with a brief accent glow, and the toast turns into a check with the restored count. Hovering or focusing the toast pauses the countdown. When it runs out the batch is committed; if the commit fails the rows come back and the toast says so.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `getKey` (required) | `(item: T) => string` | – | A stable key for each item. Rows are tracked by key, so an item removed and restored keeps its identity. |
| `renderItem` (required) | `(item: T, ctx: UndoRowContext) => ReactNode` | – | Renders one row. ctx.remove(kind) removes it with an action kind, ctx.removed is true while it is folded away and ctx.restoredAt changes each time it is put back. |
| `label` (required) | `string` | – | Accessible name of the list. |
| `items` | `readonly T[]` | – | Controlled items. Removed rows stay in this array, folded away, until the batch is committed; then onItemsChange receives the list without them. |
| `defaultItems` | `readonly T[]` | – | Starting items when uncontrolled. |
| `onItemsChange` | `(items: T[]) => void` | – | Called with the new list when a batch is committed, never while it can still be undone. |
| `actions` | `Record<string, UndoAction>` | `archive and delete` | The kinds of removal. Each has a label ("Archive", used in failure copy), done ("archived", used in the toast) and an optional icon. The first key is the default kind for ctx.remove(). |
| `noun` | `readonly [string, string]` | `["item", "items"]` | Singular and plural nouns for the toast: "Conversation archived", "3 conversations archived". Mixed batches read "2 archived, 1 deleted". |
| `duration` | `number` | `6000` | Milliseconds the undo window stays open. It refills whenever another row joins the batch and pauses while the toast is hovered or focused or the tab is hidden. |
| `onRemove` | `(entries: UndoEntry<T>[]) => void` | – | Called as soon as a row is removed, for optimistic server updates. Pair it with onUndo to reverse them. |
| `onUndo` | `(entries: UndoEntry<T>[]) => void \| Promise<unknown>` | – | Called on undo. Return a promise to show Restoring with a spinner; a rejection keeps the rows removed, says Couldn't undo, try again, and restarts the countdown. |
| `onCommit` | `(entries: UndoEntry<T>[]) => void \| Promise<unknown>` | – | Called when the undo window closes, with every entry in the batch and its original index. Return a promise; a rejection opens the rows again and shows Couldn't archive conversation. |
| `undoShortcut` | `boolean` | `true` | Cmd+Z on Apple devices and Ctrl+Z elsewhere undo the pending batch, unless focus is in a text field that has its own undo. The Undo button shows the shortcut on devices with a pointer. |
| `pauseOnHover` | `boolean` | `true` | Hovering or focusing the toast pauses the countdown. |
| `empty` | `ReactNode` | – | Shown, fading up, once every row is gone. |
| `toastPlacement` | `"container" \| "viewport"` | `"container"` | container floats the toast over the bottom of the component, so reserve padding at the bottom of the list. viewport fixes it to the bottom of the window. |
| `ref` | `Ref<UndoToastHandle>` | – | remove(key, kind), undo() and commit() for toolbars, bulk actions and tests. |
| `className` | `string` | – | Class on the root element. |
| `style` | `CSSProperties` | – | Inline styles on the root element. |

#### UndoToastRow

A ready made row: leading media, a title and description, and metadata that gives way to the action buttons on hover and focus without reflowing. The row is focusable and runs single key shortcuts while focused.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` (required) | `ReactNode` | – | The first line, truncated with an ellipsis. |
| `leading` | `ReactNode` | – | Media before the text, such as an avatar. |
| `description` | `ReactNode` | – | The second line, truncated with an ellipsis. |
| `meta` | `ReactNode` | – | Right aligned metadata such as a time. It fades out while the actions are shown. |
| `actions` | `ReactNode` | – | Row buttons, usually UndoToastRowAction. Shown on hover and focus, and always on touch screens. |
| `shortcuts` | `Record<string, () => void>` | – | Single key shortcuts on the focused row, such as { e: archive, Backspace: remove }. |
| `label` | `string` | – | Accessible name of the row, such as the sender and subject. |
| `unread` | `boolean` | – | Sets the title in medium weight. |
| `className` | `string` | – | Class on the row. |

#### UndoToastRowAction

A round icon button for a row action, named by its label.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` (required) | `string` | – | Accessible name and tooltip, such as Archive. |
| `icon` (required) | `ReactNode` | – | A 16px lucide icon. |
| `onClick` (required) | `() => void` | – | Usually ctx.remove(kind). The click does not bubble to the row. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Tab | Moves through the rows, their actions and the Undo button. |
| E / Backspace / Delete | With UndoToastRow shortcuts, archive or delete the focused row. Focus moves to the same control on the next row, or the previous one at the end of the list. |
| Cmd+Z / Ctrl+Z | Undoes the pending batch from anywhere on the page, except inside a text field. |
| Enter / Space | On Undo, restores the batch. |
| Escape | With focus in the toast, closes the undo window now and commits the batch. |

### Accessibility

- The list is a labelled ul. A folded row is aria-hidden and inert, so it leaves the tab order and the accessibility tree the moment it is removed and returns when it is restored.
- Removing a focused row hands focus to the same control on the next row, or the previous one; when the list is empty focus moves to Undo. Undoing from the toast moves focus to the first restored row.
- A polite live region announces each change in words: Conversation archived. Press Command Z or the Undo button to undo; 3 conversations restored; Couldn't archive conversation.
- The toast is a labelled group that describes itself with the live text. The Undo button carries aria-keyshortcuts. The countdown ring and seconds are decorative; hovering or focusing the toast pauses them so there is time to act.
- State never relies on color: the toast pairs a countdown, check or alert icon with a sentence.

### Motion

- Remove: the row content fades and slips 28px aside with a small scale and blur in 180ms while the row height closes on the smooth spring, so rows below glide up to fill the gap.
- The toast rises 18px from a slightly smaller, blurred state on the morph spring, from its bottom edge. It leaves by dropping and fading on the exit curve.
- Merge: the message crossfades vertically when its shape changes, the count rolls digit by digit, the ring springs back to full and the toast gets a velocity nudge on its scale.
- The countdown ring is an SVG path whose length follows a linear motion value; the seconds inside roll on each whole second. Hover, focus and a hidden tab pause the same animation, so the ring stops exactly where it was.
- Undo: restored rows reopen top to bottom with a 35ms stagger, their content slides back in on the snappy spring after the height starts to open, and a faint accent glow marks where they returned. The ring turns into a check with a small rotation.
- Everything is interruptible: removing again mid collapse, undoing mid collapse or removing during an undo all retarget from the current values.
- With reduced motion rows open and close at once, the toast only fades, digits swap without rolling and the ring refills instantly; the countdown itself still drains so the time limit stays visible.

### Responsive behavior

- Rows truncate their title and description with an ellipsis at any width; the time and the actions share one cell so nothing reflows on hover.
- On touch screens the row actions are always visible and the shortcut hint on Undo is hidden.
- The toast is at most 372px wide and keeps 12px from the component edges, so it fits a 320px phone; the message truncates before the Undo button shrinks.

### Performance

- Only removed and restored rows animate. Row height is the one layout property that moves, because closing the gap is the information; the content moves with transforms and opacity.
- The countdown is one motion value drained by a linear animation, not a timer tick; React re-renders once per whole second for the digit.
- Rows render through a small child component, so a toast update does not re-render every row's content.

### Notes for AI

- Use UndoToast instead of a confirmation dialog for reversible removals: archive, delete to trash, remove from a list, mark done. It lets people act fast and recover.
- Choose one pattern for the server: deferred (do nothing until onCommit, then send the batch) or optimistic (send in onRemove, reverse in onUndo). Deferred is simpler and needs no reversal endpoint.
- Keep items controlled when the list lives in your store. Removed rows stay in your array until onItemsChange fires on commit, which is what lets undo put them back at the same index.
- Reserve space under the list for the toast in container placement (about 76px), or use toastPlacement="viewport" for full page lists.
- Name the noun so the toast reads naturally: noun={["file", "files"]}. Give each action a label and past tense if you add kinds beyond archive and delete.
- Use your own row markup freely; UndoToastRow is a convenience. Call ctx.remove from buttons, swipe actions or keyboard shortcuts.

### Related

- [Toast stack](https://uiarc.dev/components/toast-stack/markdown): Stack short results at the edge until you reach for them.
- [Toast](https://uiarc.dev/components/toast/markdown): Brief confirmation for a completed background action.
- [Swipe actions](https://uiarc.dev/components/swipe-actions/markdown): Reveal row actions with a swipe, or from the same actions in a menu.
- [Confirm morph](https://uiarc.dev/components/confirm-morph/markdown): A destructive button that morphs into an inline confirmation, a spinner, and a result with undo.
- [Hold to confirm](https://uiarc.dev/components/hold-to-confirm/markdown): Confirm a destructive action by holding, not tapping.

### Also in messages

- [Alert](https://uiarc.dev/components/alert/markdown): A persistent message that helps people recover or continue.
- [Announcement bar](https://uiarc.dev/components/announcement-bar/markdown): A top banner that rotates messages, counts down, and collapses smoothly when dismissed.
- [Cookie consent](https://uiarc.dev/components/cookie-consent/markdown): A consent bar that morphs into preferences and folds into a reopen button.

### Guidance for AI tools

Undo toast: Archive or delete rows with a second chance: the gap closes, a countdown toast merges repeat actions, and Undo or ⌘Z puts every row back exactly where it was. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Progress

> Show how much of a known task is complete.

- Type: Component (feedback)
- Access: Free, open source
- Page: https://uiarc.dev/components/progress
- Markdown: https://uiarc.dev/components/progress/markdown
- Registry item: https://uiarc.dev/r/progress.json
- Source file: `registry/components/progress/progress.tsx`
- Dependencies: motion, lucide-react
- Keywords: status, loading, react progress bar, animated progress bar, upload progress, loading bar, percentage bar, progress indicator

### When to use

- Determinate progress for uploads, imports, or long tasks.
- Progress with a visible percentage and a check at completion, via showValue.

### When not to use

- Use skeleton while content is loading with no progress to report.
- Use usage-meter for quota against a limit, and gauge for dashboard metrics.
- Use stepper to show position in a multi-step flow.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/progress
pnpm dlx shadcn@latest add @uiarc/progress
yarn dlx shadcn@latest add @uiarc/progress
bunx --bun shadcn@latest add @uiarc/progress
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/progress.json
```

#### Manual

1. Install the dependencies:

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

2. Copy the source into your project. Main file: `registry/components/progress/progress.tsx`

   The source is in the registry item: https://uiarc.dev/r/progress.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { Progress } from "@/components/arc/progress/progress";

export function UploadProgress({ sent, size }: { sent: number; size: number }) {
  return <Progress label="Uploading report.pdf" value={sent} max={size} showValue />;
}
```

### API reference

#### Progress

A linear progress bar with an optional label and a counted percentage that matches the fill.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `number` | `0` | Current value, clamped between 0 and max. |
| `max` | `number` | `100` | Value that counts as complete. |
| `label` | `string` | – | Visible label and aria-label. Falls back to "Progress" for assistive tech. |
| `showValue` | `boolean` | `false` | Shows the counted percentage and a check at 100%. |
| `...props` | `Omit<HTMLAttributes<HTMLDivElement>, "children">` | – | Forwarded to the progressbar element, such as className. |

### Accessibility

- Renders role="progressbar" with aria-valuemin, aria-valuemax, aria-valuenow, and a percentage aria-valuetext.
- Label changes crossfade; outgoing copies are aria-hidden while they fade.
- It is not a live region; announce completion separately if it matters.

### Motion

- One smooth spring drives both the fill and the counted number, so they always agree. The fill slides in from the left to keep its rounded end.
- At 100% the fill turns to the success colour and a check settles in beside the count.
- Reduced motion jumps the fill and count to the new value.

### Responsive behavior

- The bar fills its container width, so it works in cards, rows, and full-width layouts.

### Performance

- One spring drives both the fill and the counted number; no observers or timers.
- It is not a live region, so announce completion separately if it matters.

### Notes for AI

- Use for determinate task progress. Use skeleton while content has no progress to report, gauge or activity-rings for dashboard metrics, and usage-meter for quota against a limit.
- Pass raw value and max; the percentage is computed and clamped for you.

### Related

- [Usage meter](https://uiarc.dev/components/usage-meter/markdown): Show what fills an allowance and how close it is to the limit.
- [Skeleton](https://uiarc.dev/components/skeleton/markdown): Reserve space while content is still loading.
- [Gauge](https://uiarc.dev/components/gauge/markdown): Show a value against a known range.
- [Stepper](https://uiarc.dev/components/stepper/markdown): Show where a person is in a multi-step flow and what is done.

### Also in progress

- [Countdown](https://uiarc.dev/components/countdown/markdown): A launch countdown with rolling digits that morphs into a live state at zero.
- [Onboarding checklist](https://uiarc.dev/components/onboarding-checklist/markdown): Guide a new workspace through setup, one step at a time.

### Guidance for AI tools

Progress: Show how much of a known task is complete. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Skeleton

> Reserve space while content is still loading.

- Type: Component (feedback)
- Access: Free, open source
- Page: https://uiarc.dev/components/skeleton
- Markdown: https://uiarc.dev/components/skeleton/markdown
- Registry item: https://uiarc.dev/r/skeleton.json
- Source file: `registry/components/skeleton/skeleton.tsx`
- Dependencies: motion
- Keywords: loading, status, react skeleton, skeleton loader, loading placeholder, content placeholder, shimmer loading, skeleton screen

### When to use

- Loading states for content whose shape is known, like a profile or comment.
- Swapping a placeholder into real content with a crossfade and height spring.

### When not to use

- Use progress when you can report a percentage.
- Use empty-state when loading finished and there is nothing to show.
- Use text-shimmer for an AI thinking or status line.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/skeleton
pnpm dlx shadcn@latest add @uiarc/skeleton
yarn dlx shadcn@latest add @uiarc/skeleton
bunx --bun shadcn@latest add @uiarc/skeleton
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/skeleton.json
```

#### Manual

1. Install the dependencies:

```bash
npm install motion
```

2. Copy the source into your project. Main file: `registry/components/skeleton/skeleton.tsx`

   The source is in the registry item: https://uiarc.dev/r/skeleton.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { Skeleton } from "@/components/arc/skeleton/skeleton";

export function Profile({ user }: { user?: User }) {
  return (
    <Skeleton avatar lines={2} loading={!user}>
      {user && <ProfileCard user={user} />}
    </Skeleton>
  );
}
```

### API reference

#### Skeleton

A pulsing placeholder of text lines and an optional avatar that can crossfade into the loaded content.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` | `string` | `"Loading content"` | aria-label of the loading status. |
| `lines` | `number` | `3` | Number of text lines, clamped to 1-6. |
| `avatar` | `boolean` | `false` | Adds a round avatar placeholder. |
| `children` | `ReactNode` | – | Content to reveal once loading finishes. With children the placeholder crossfades into them. |
| `loading` | `boolean` | `true` | Keeps the placeholder visible while true. Only used with children. |
| `className` | `string` | – | Class on the outer element. |

### Accessibility

- The placeholder is role="status" with aria-busy and an aria-label; its shapes are aria-hidden.
- With children, the wrapper sets aria-busy while loading.

### Motion

- Blocks pulse in a staggered wave, each a beat after the one above.
- On load the placeholder fades out, content rises 4px into place, and the height springs from placeholder to content.
- Reduced motion stops the pulse and swaps with short fades and no height animation.

### Responsive behavior

- Lines are percentages of the container width, so the placeholder scales with its slot.
- It only draws text lines and an avatar; build custom shapes for grids or media.

### Performance

- The pulse is a CSS animation that stops under reduced motion.
- A ResizeObserver springs the height from placeholder to content; avoid hundreds of skeletons at once.

### Notes for AI

- Use while fetching content whose shape is known. Use progress when you can report a percentage, and empty-state when there is nothing to show.
- Wrap the real content as children and drive loading to get the crossfade; without children it renders only the placeholder.

### Related

- [Progress](https://uiarc.dev/components/progress/markdown): Show how much of a known task is complete.
- [Empty state](https://uiarc.dev/components/empty-state/markdown): A useful next step when there is nothing to show yet.
- [Card](https://uiarc.dev/components/card/markdown): A contained group of related content and actions.

### Also in progress

- [Stepper](https://uiarc.dev/components/stepper/markdown): Show where a person is in a multi-step flow and what is done.
- [Countdown](https://uiarc.dev/components/countdown/markdown): A launch countdown with rolling digits that morphs into a live state at zero.
- [Usage meter](https://uiarc.dev/components/usage-meter/markdown): Show what fills an allowance and how close it is to the limit.
- [Onboarding checklist](https://uiarc.dev/components/onboarding-checklist/markdown): Guide a new workspace through setup, one step at a time.

### Guidance for AI tools

Skeleton: Reserve space while content is still loading. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Stepper

> Show where a person is in a multi-step flow and what is done.

- Type: Component (feedback)
- Access: Free, open source
- Page: https://uiarc.dev/components/stepper
- Markdown: https://uiarc.dev/components/stepper/markdown
- Registry item: https://uiarc.dev/r/stepper.json
- Source file: `registry/components/stepper/stepper.tsx`
- Dependencies: motion
- Keywords: motion, product, react stepper, step indicator, progress steps, wizard steps, checkout steps, vertical stepper, multi step progress

### When to use

- Showing position in a strict multi-step flow like checkout or account setup.
- Flows where people can jump back to completed steps, via onStepSelect.
- Vertical timelines of steps with descriptions and error states.

### When not to use

- Use multi-step-form when you also want the step content, navigation, and success state.
- Use onboarding-checklist for loosely ordered tasks.
- Use progress when a single percentage is enough.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/stepper
pnpm dlx shadcn@latest add @uiarc/stepper
yarn dlx shadcn@latest add @uiarc/stepper
bunx --bun shadcn@latest add @uiarc/stepper
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/stepper.json
```

#### Manual

1. Install the dependencies:

```bash
npm install motion
```

2. Copy the source into your project. Main file: `registry/components/stepper/stepper.tsx`

   The source is in the registry item: https://uiarc.dev/r/stepper.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { Stepper } from "@/components/arc/stepper/stepper";

export function CheckoutSteps({ step, goTo }: { step: number; goTo: (index: number) => void }) {
  return (
    <Stepper
      current={step}
      onStepSelect={goTo}
      steps={[
        { id: "cart", label: "Cart" },
        { id: "shipping", label: "Shipping", description: "Address and delivery" },
        { id: "payment", label: "Payment" },
      ]}
    />
  );
}
```

### API reference

#### Stepper

A horizontal or vertical steps indicator driven by the current index, with optional navigation back to completed steps.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `steps` (required) | `{ id: string; label: string; description?: string; error?: string }[]` | – | Steps in order. error morphs the marker into an alert and replaces the description. |
| `current` (required) | `number` | – | Index of the step in progress. steps.length marks the flow complete. |
| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | Layout direction. |
| `onStepSelect` | `(index: number) => void` | – | Called with the index of a completed step when chosen. Without it the stepper is read only. |
| `details` | `"all" \| "current"` | `"all"` | "current" shows only the active step's description. Errors always show. |
| `compact` | `boolean` | `false` | Markers only. Horizontal steppers switch to this below 30rem on their own. |
| `label` | `string` | `"Progress"` | Accessible name for the stepper. |
| `completeLabel` | `string` | `"All steps complete"` | Announced, and shown in the compact caption, once every step is complete. |
| `className` | `string` | – | Class on the root. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| ArrowLeft / ArrowRight / ArrowUp / ArrowDown | With onStepSelect, moves focus between reachable steps (RTL aware). |
| Home / End | Jumps to the first or the current step. |
| Enter / Space | Selects a completed step. |

### Accessibility

- Renders a labelled nav when interactive, otherwise role="group"; the current step has aria-current="step".
- Each step appends screen-reader-only status text: Completed, Not started, or Error.
- Step changes are announced in a polite live region as "Step 2 of 4: Shipping".
- Upcoming steps are aria-disabled and removed from the tab order.

### Motion

- Connectors fill one after another when progress jumps several steps; the ring then grows around the new current marker.
- Numbers morph into drawn checks or alerts; descriptions rise in while their slot springs to the new height.
- Reduced motion applies all changes instantly.

### Responsive behavior

- Horizontal steppers switch to markers only with a caption below a 30rem container width.
- Set orientation to vertical for sidebars or narrow columns where labels and descriptions should stay visible.
- Labels and descriptions wrap with overflow-wrap, so long words do not overflow.

### Performance

- The stepper only indicates; it renders markers and text, with a ResizeObserver for the description slot height.

### Notes for AI

- Use to show position in a strict multi-step flow such as checkout or setup. Use onboarding-checklist for loosely ordered tasks.
- The stepper only indicates; render the step content yourself and drive current. Set current to steps.length when done.

### Related

- [Onboarding checklist](https://uiarc.dev/components/onboarding-checklist/markdown): Guide a new workspace through setup, one step at a time.
- [Progress](https://uiarc.dev/components/progress/markdown): Show how much of a known task is complete.
- [Tabs](https://uiarc.dev/components/tabs/markdown): Switch between related content in the same context.
- [Breadcrumb](https://uiarc.dev/components/breadcrumb/markdown): Show where a page sits in a hierarchy.

### Also in progress

- [Skeleton](https://uiarc.dev/components/skeleton/markdown): Reserve space while content is still loading.
- [Countdown](https://uiarc.dev/components/countdown/markdown): A launch countdown with rolling digits that morphs into a live state at zero.
- [Usage meter](https://uiarc.dev/components/usage-meter/markdown): Show what fills an allowance and how close it is to the limit.

### Guidance for AI tools

Stepper: Show where a person is in a multi-step flow and what is done. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Countdown

> A launch countdown with rolling digits that morphs into a live state at zero.

- Type: Component (feedback)
- Access: Free, open source
- Page: https://uiarc.dev/components/countdown
- Markdown: https://uiarc.dev/components/countdown/markdown
- Registry item: https://uiarc.dev/r/countdown.json
- Source file: `registry/components/countdown/countdown.tsx`
- Dependencies: motion
- Keywords: feedback, new, react countdown, countdown timer, launch countdown, event timer, digit roll animation, deadline timer, time zone countdown

### When to use

- A launch page or event hero counting to a keynote.
- A compact deadline pill in a table row or banner.
- Sale or registration windows that should flip to a Live now state on their own.

### When not to use

- Use stopwatch for time counting up from a start.
- Use announcement-bar when the countdown sits inside a site-wide banner with a call to action.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/countdown
pnpm dlx shadcn@latest add @uiarc/countdown
yarn dlx shadcn@latest add @uiarc/countdown
bunx --bun shadcn@latest add @uiarc/countdown
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/countdown.json
```

#### Manual

1. Install the dependencies:

```bash
npm install motion
```

2. Copy the source into your project. Main file: `registry/components/countdown/countdown.tsx`

   The source is in the registry item: https://uiarc.dev/r/countdown.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { Countdown } from "@/components/arc/countdown/countdown";

export function LaunchCountdown() {
  return (
    <Countdown
      target="2026-10-06T10:00:00"
      timeZone="America/Los_Angeles"
      label="Keynote starts in"
      onComplete={() => router.refresh()}
    />
  );
}
```

### Examples

#### Compact hours and minutes

```tsx
<Countdown variant="compact" units={["hours", "minutes"]} target={saleEndsAt} completeLabel="Ended" />
```

### API reference

#### Countdown

A countdown to a fixed moment with rolling digit wheels, in a large display form or a compact pill.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `target` (required) | `Date \| number \| string` | – | The moment to count to. Numbers are epoch ms; ISO strings with Z or an offset are exact; strings without an offset are wall time in timeZone, or UTC. |
| `timeZone` | `string` | – | IANA zone for a target string without an offset, such as "America/Los_Angeles". Daylight saving is resolved for the target date. |
| `units` | `CountdownUnit[]` | `["days", "hours", "minutes", "seconds"]` | Units to show, sorted largest first. The largest unit absorbs the rest, so hours can pass 24 when days are left out. |
| `variant` | `"large" \| "compact"` | `"large"` | Large digits with unit labels, or one compact line for banners and table cells. |
| `completeLabel` | `ReactNode` | `"Live now"` | Shown once the target passes, with a pulsing live dot. The digits morph into it. |
| `onComplete` | `() => void` | – | Fires once when the countdown reaches zero while mounted, on time even in a hidden tab. |
| `label` | `string` | `"Time remaining"` | Accessible name, such as "Keynote starts in". |
| `clock` | `() => number` | `Date.now` | Clock source in epoch ms. Pass a server-synced clock when device time cannot be trusted. |
| `ref` | `Ref<HTMLDivElement>` | – | The root element. |
| `className` | `string` | – | Class on the root. |

#### toEpoch

Resolves a countdown target to epoch ms without reading the device time zone. Returns NaN for an unparseable string.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `target` (required) | `Date \| number \| string` | – | Same forms as the target prop. |
| `timeZone` | `string` | – | IANA zone for strings without an offset. |

### Accessibility

- The root is role="timer" named by label; the visible digits are aria-hidden.
- A hidden text reads the remaining time in words, dropping seconds until under a minute so it does not chatter.
- When complete, a string completeLabel is read; other nodes read as Complete.

### Motion

- Each digit is a clipped wheel that turns the short way, so 00 to 59 is one step down and the window feathers the edges.
- Digits roll in with a small stagger on first reveal, and the shell springs its width and height when a unit column appears or drops.
- At zero the digits blur and scale out into the complete label, and the live dot pulses.
- Reduced motion jumps the wheels, sizes the shell instantly, swaps with a fade, and stops the pulse.

### Responsive behavior

- The large variant is a container: digits size to clamp(1.75rem, 12.5cqi, text-5xl), so four groups fit at 320px.
- The compact variant is an inline pill with 32px minimum height that springs its width as units drop.

### Performance

- A single timeout wakes just after each whole second; it pauses while the tab is hidden or the countdown is off screen.
- A separate long timeout still fires onComplete on time when the tab is hidden.
- Each digit renders its whole wheel (10 or fewer glyphs), so keep a page to a few countdowns.

### Notes for AI

- Use for a fixed moment people wait for: a launch, a live event, a sale ending. For elapsed time use stopwatch.
- Give targets an offset or a timeZone so every visitor counts to the same instant; never rely on the visitor's zone.
- Pass clock from a server time offset when device clocks may be wrong, such as ticketed drops.
- Use variant="compact" inside announcement bars, table cells, and badges.

### Related

- [Animated counter](https://uiarc.dev/components/animated-counter/markdown): Give changing totals a clear sense of movement.
- [Announcement bar](https://uiarc.dev/components/announcement-bar/markdown): A top banner that rotates messages, counts down, and collapses smoothly when dismissed.
- [Badge](https://uiarc.dev/components/badge/markdown): A small label for status, category, or metadata.

### Also in progress

- [Progress](https://uiarc.dev/components/progress/markdown): Show how much of a known task is complete.
- [Skeleton](https://uiarc.dev/components/skeleton/markdown): Reserve space while content is still loading.
- [Stepper](https://uiarc.dev/components/stepper/markdown): Show where a person is in a multi-step flow and what is done.
- [Usage meter](https://uiarc.dev/components/usage-meter/markdown): Show what fills an allowance and how close it is to the limit.
- [Onboarding checklist](https://uiarc.dev/components/onboarding-checklist/markdown): Guide a new workspace through setup, one step at a time.

### Guidance for AI tools

Countdown: A launch countdown with rolling digits that morphs into a live state at zero. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Usage meter

> Show what fills an allowance and how close it is to the limit.

- Type: Component (feedback)
- Access: Free, open source
- Page: https://uiarc.dev/components/usage-meter
- Markdown: https://uiarc.dev/components/usage-meter/markdown
- Registry item: https://uiarc.dev/r/usage-meter.json
- Source file: `registry/components/usage-meter/usage-meter.tsx`
- Dependencies: motion, lucide-react
- Keywords: meter, usage, storage, react usage meter, storage usage bar, quota meter, plan limit indicator, segmented progress bar, billing usage

### When to use

- Quota against a fixed allowance, such as storage, seats, or API calls.
- Billing pages that should show what takes the space and how close the plan is to full.
- Plans that can go over the limit, where the overage should be clear without relying on color.

### When not to use

- Use progress for task completion.
- Use bar-chart to compare categories without a limit.
- Use gauge or stat-card for a single headline metric.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/usage-meter
pnpm dlx shadcn@latest add @uiarc/usage-meter
yarn dlx shadcn@latest add @uiarc/usage-meter
bunx --bun shadcn@latest add @uiarc/usage-meter
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/usage-meter.json
```

#### Manual

1. Install the dependencies:

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

2. Copy the source into your project. Main file: `registry/components/usage-meter/usage-meter.tsx`

   The source is in the registry item: https://uiarc.dev/r/usage-meter.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { UsageMeter } from "@/components/arc/usage-meter/usage-meter";

export function StorageCard() {
  return (
    <UsageMeter
      label="Workspace storage"
      unit="GB"
      limit={50}
      segments={[
        { id: "files", label: "Files", value: 21.4 },
        { id: "media", label: "Media", value: 14.2 },
        { id: "backups", label: "Backups", value: 6.8 },
      ]}
    />
  );
}
```

### API reference

#### UsageMeter

A segmented bar showing what uses a fixed allowance, with a rolling total, status badge, and interactive legend.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` (required) | `string` | – | What is measured, such as "Workspace storage". |
| `segments` (required) | `{ id: string; label: string; value: number }[]` | – | Used amounts in display order. Keep ids stable so segments re-flow. Up to four read clearly. |
| `limit` (required) | `number` | – | The plan limit, in the same unit as the segments. |
| `unit` | `string` | `""` | Unit shown after numbers, such as "GB". |
| `decimals` | `number` | `1` | Digits after the decimal point. |
| `freeLabel` | `string` | `"Free"` | Legend label for remaining space. |
| `overLabel` | `string` | `"Over limit"` | Legend label for the overage. |
| `warnAt` | `number` | `0.9` | Share of the limit at which the badge warns that it is almost full. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| ArrowLeft / ArrowRight / ArrowUp / ArrowDown | Moves between legend items (roving tab stop). |
| Home / End | Jumps to the first or last legend item. |
| Enter / Space | Pins or unpins the focused category. |
| Escape | Clears the pinned category. |

### Accessibility

- The meter is a role="group" labelled by its title; the bar is role="img" with a full text summary of every segment and the status.
- Rolling numbers are aria-hidden with screen-reader-only text alongside.
- Status changes (near limit, over limit, growing overage) are announced in a polite live region.
- Legend items are buttons with aria-pressed and labels like "Media, 14.2 GB".

### Motion

- Segments grow in left to right once scrolled into view, then re-flow on one spring each when values change; crossing the limit fades in a hatched overage and limit marker.
- Digits roll like an odometer in the direction the number moved; the status badge springs to its new width.
- Reduced motion jumps values and swaps text with short fades.

### Responsive behavior

- The legend is an auto-fit grid of 108px minimum columns, so it wraps to fewer columns on narrow cards.
- Hovering the bar highlights a category on mouse; on touch a tap pins it instead.
- The caption ellipsizes on one line, so long labels do not push the layout.

### Performance

- Segments animate in once via useInView at 40% visibility, then re-flow on springs when values change.
- A ResizeObserver tracks the bar width; up to four segments read clearly.

### Notes for AI

- Use for quota against a fixed allowance: storage, seats, API calls. Use progress for task completion and bar-chart for comparing categories without a limit.
- Keep segment ids stable across renders so updates animate instead of remounting.

### Related

- [Progress](https://uiarc.dev/components/progress/markdown): Show how much of a known task is complete.
- [Bar chart](https://uiarc.dev/components/bar-chart/markdown): Compare one measure across days and scrub any bar for its value.
- [Gauge](https://uiarc.dev/components/gauge/markdown): Show a value against a known range.

### Also in progress

- [Skeleton](https://uiarc.dev/components/skeleton/markdown): Reserve space while content is still loading.
- [Stepper](https://uiarc.dev/components/stepper/markdown): Show where a person is in a multi-step flow and what is done.
- [Countdown](https://uiarc.dev/components/countdown/markdown): A launch countdown with rolling digits that morphs into a live state at zero.
- [Onboarding checklist](https://uiarc.dev/components/onboarding-checklist/markdown): Guide a new workspace through setup, one step at a time.

### Guidance for AI tools

Usage meter: Show what fills an allowance and how close it is to the limit. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Onboarding checklist

> Guide a new workspace through setup, one step at a time.

- Type: Component (feedback)
- Access: Free, open source
- Page: https://uiarc.dev/components/onboarding-checklist
- Markdown: https://uiarc.dev/components/onboarding-checklist/markdown
- Registry item: https://uiarc.dev/r/onboarding-checklist.json
- Source file: `registry/components/onboarding-checklist/onboarding-checklist.tsx`
- Dependencies: motion, lucide-react
- Keywords: onboarding, checklist, getting started, react onboarding checklist, getting started checklist, setup checklist, user onboarding, progress checklist, task list onboarding

### When to use

- A one-time getting-started card with three to eight loosely ordered steps.
- Setup steps that run async actions, like Connect GitHub, and check off when they resolve.
- Checklists people can hide and come back to, with state persisted through callbacks.

### When not to use

- Use stepper when the order is strict and steps map to screens.
- Use multi-step-form when every step collects form input.
- Use accordion for plain collapsible content without completion.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/onboarding-checklist
pnpm dlx shadcn@latest add @uiarc/onboarding-checklist
yarn dlx shadcn@latest add @uiarc/onboarding-checklist
bunx --bun shadcn@latest add @uiarc/onboarding-checklist
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/onboarding-checklist.json
```

#### Manual

1. Install the dependencies:

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

2. Copy the source into your project. Main file: `registry/components/onboarding-checklist/onboarding-checklist.tsx`

   The source is in the registry item: https://uiarc.dev/r/onboarding-checklist.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { OnboardingChecklist } from "@/components/arc/onboarding-checklist/onboarding-checklist";

export function GettingStarted() {
  return (
    <OnboardingChecklist
      title="Set up your workspace"
      defaultCompleted={savedIds}
      onCompletedChange={saveIds}
      steps={[
        { id: "invite", title: "Invite your team", actionLabel: "Invite", onAction: openInvite },
        { id: "connect", title: "Connect GitHub", description: "Sync issues and PRs.", actionLabel: "Connect", onAction: connectGithub },
        { id: "profile", title: "Add a profile photo" },
      ]}
    />
  );
}
```

### API reference

#### OnboardingChecklist

A getting-started card with a progress ring, expandable steps with actions, and a folding completed group.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` (required) | `string` | – | Card title while steps remain. |
| `steps` (required) | `{ id: string; title: string; description?: string; actionLabel?: string; onAction?: () => void \| Promise<void> }[]` | – | Steps in order. onAction resolving checks the step; throwing an Error keeps it open and shows the message. |
| `doneTitle` | `string` | `"You’re all set"` | Title once every step is done. |
| `defaultCompleted` | `string[]` | `[]` | Step ids that start completed. |
| `onCompletedChange` | `(completed: string[]) => void` | – | Called with completed ids in step order whenever they change. |
| `defaultHidden` | `boolean` | `false` | Starts with the body collapsed. |
| `onHiddenChange` | `(hidden: boolean) => void` | – | Called when the Hide or Show toggle is used. |
| `className` | `string` | – | Class on the card. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| ArrowDown / ArrowUp | Moves between step titles. |
| Home / End | Jumps to the first or last step title. |
| Enter / Space | Expands a step, toggles its checkbox, or runs its action. |

### Accessibility

- Each step has a role="checkbox" button with aria-checked, and a title button with aria-expanded controlling a labelled region.
- The ring is role="progressbar" with aria-valuetext like "3 of 5 steps done"; progress and errors are announced via role="status" and role="alert".
- When a focused step finishes, focus moves to the next step's action; leaving rows and the hidden body are inert.

### Motion

- Checks fill from the center and draw their tick; after 720ms the finished step folds into the completed group while the ring and count roll forward.
- Rows and panels open and close on a non-overshooting spring; the title morphs to doneTitle and a tick draws in the ring at 100%.
- Reduced motion removes height and scale animation and keeps short fades.

### Responsive behavior

- The card is a container query context; below 380px the Hide button collapses to an icon.
- Step titles and checkboxes keep 40px targets, and the completed group toggle is 44px tall.

### Performance

- Steps are not virtualized; the component is built for short lists.
- Each finished step waits 720ms on a timer before folding into the completed group.

### Notes for AI

- Use for a short, one-time setup of three to eight loosely ordered steps. Use stepper when the order is strict and steps map to screens.
- Make onAction async and throw an Error with a readable message on failure. Persist onCompletedChange and onHiddenChange to restore state via the default props.

### Related

- [Stepper](https://uiarc.dev/components/stepper/markdown): Show where a person is in a multi-step flow and what is done.
- [Progress](https://uiarc.dev/components/progress/markdown): Show how much of a known task is complete.
- [Accordion](https://uiarc.dev/components/accordion/markdown): Progressively reveal supporting information in place.
- [Checkbox](https://uiarc.dev/components/checkbox/markdown): A binary choice with a precise, legible state.

### Also in progress

- [Skeleton](https://uiarc.dev/components/skeleton/markdown): Reserve space while content is still loading.
- [Countdown](https://uiarc.dev/components/countdown/markdown): A launch countdown with rolling digits that morphs into a live state at zero.
- [Usage meter](https://uiarc.dev/components/usage-meter/markdown): Show what fills an allowance and how close it is to the limit.

### Guidance for AI tools

Onboarding checklist: Guide a new workspace through setup, one step at a time. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Avatar

> A compact identity marker for people and accounts.

- Type: Component (data)
- Access: Free, open source
- Page: https://uiarc.dev/components/avatar
- Markdown: https://uiarc.dev/components/avatar/markdown
- Registry item: https://uiarc.dev/r/avatar.json
- Source file: `registry/components/avatar/avatar.tsx`
- Dependencies: motion
- Keywords: identity, people, react avatar, avatar component, user avatar with initials, profile picture, avatar with status, online indicator avatar

### When to use

- Showing one person next to their name, comment, or record.
- Presence in a header or list, via the online or offline status dot.
- Places where a photo may be missing and initials should stand in.

### When not to use

- Use avatar-group for several people with an overflow count.
- Use user-menu when the avatar is the trigger for account actions.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/avatar
pnpm dlx shadcn@latest add @uiarc/avatar
yarn dlx shadcn@latest add @uiarc/avatar
bunx --bun shadcn@latest add @uiarc/avatar
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/avatar.json
```

#### Manual

1. Install the dependencies:

```bash
npm install motion
```

2. Copy the source into your project. Main file: `registry/components/avatar/avatar.tsx`

   The source is in the registry item: https://uiarc.dev/r/avatar.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { Avatar } from "@/components/arc/avatar/avatar";

export function Owner() {
  return <Avatar name="Maya Chen" src="/people/maya.jpg" size="lg" status="online" />;
}
```

### API reference

#### Avatar

A round portrait that falls back to initials and can show an online or offline dot.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `name` (required) | `string` | – | Full name. Used for the accessible label and the first two initials. |
| `src` | `string` | – | Image URL. Renders a plain img, or the image component set with ArcProvider (such as next/image). Falls back to initials if it fails to load. |
| `size` | `"sm" \| "md" \| "lg" \| "xl"` | `"md"` | Diameter, from 28px to 88px. |
| `status` | `"online" \| "offline"` | – | Adds a presence dot and appends the status to the label. |
| `...props` | `HTMLAttributes<HTMLSpanElement>` | – | Forwarded to the root span, including className. |

### Accessibility

- The root is role="img" with an aria-label of the name plus status, such as "Maya Chen, online".
- The image and initials are decorative, so the name is read once.
- The status dot is hidden from assistive tech; the label carries the state.

### Motion

- A photo still loading fades in from a soft blur; a cached one shows at once.
- The status dot pops in and out on a snappy spring.
- Reduced motion swaps the dot instantly and drops the image fade.

### Responsive behavior

- Size is fixed by the size prop, from 28px to 88px, and never changes by breakpoint.
- It passes a sizes hint per size, so with next/image (through ArcProvider) phones never download a larger photo than the circle shows.

### Performance

- The photo is a plain lazy img by default. Pass next/image through ArcProvider to optimize it; remote hosts then need next.config images settings.
- A cached photo shows at once; only a still-loading photo runs the short blur fade.

### Notes for AI

- Use for a single person. For a row of people with an overflow count use avatar-group.
- Renders a plain img, so any host works in any React app. To use next/image or your own image component, wrap the app once in ArcProvider from @/components/arc/lib/arc-provider: <ArcProvider image={Image}>. With next/image, remote hosts must be allowed in next.config images.

### Related

- [Avatar group](https://uiarc.dev/components/avatar-group/markdown): Show a team or set of contributors in a small space.
- [User menu](https://uiarc.dev/components/user-menu/markdown): Your account, settings, theme, and sign out behind the avatar. Opens as a bottom sheet on phones.
- [Card](https://uiarc.dev/components/card/markdown): A contained group of related content and actions.
- [Timeline](https://uiarc.dev/components/timeline/markdown): Follow what happened, newest first, grouped by day.

### Also in avatars

- [Badge](https://uiarc.dev/components/badge/markdown): A small label for status, category, or metadata.
- [Presence stack](https://uiarc.dev/components/presence-stack/markdown): Avatars of the people here now: joins pop in as the stack reflows, a counter rolls past the limit, dots show typing and idle, and hover fans it out with a gliding name label.

### Guidance for AI tools

Avatar: A compact identity marker for people and accounts. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Avatar group

> Show a team or set of contributors in a small space.

- Type: Component (data)
- Access: Free, open source
- Page: https://uiarc.dev/components/avatar-group
- Markdown: https://uiarc.dev/components/avatar-group/markdown
- Registry item: https://uiarc.dev/r/avatar-group.json
- Source file: `registry/components/avatar-group/avatar-group.tsx`
- Dependencies: motion
- Keywords: identity, people, react avatar group, avatar stack, overlapping avatars, team members avatars, avatar overflow count, collaborators list

### When to use

- Showing who owns or edits something in a header, card, or table cell.
- Collaborator stacks where people join and leave while the page is open.
- Long member lists that should collapse into a +N chip.

### When not to use

- Use avatar for a single person.
- Use a list or sortable-data-table when people need to see every name and role.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/avatar-group
pnpm dlx shadcn@latest add @uiarc/avatar-group
yarn dlx shadcn@latest add @uiarc/avatar-group
bunx --bun shadcn@latest add @uiarc/avatar-group
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/avatar-group.json
```

#### Manual

1. Install the dependencies:

```bash
npm install motion
```

2. Copy the source into your project. Main file: `registry/components/avatar-group/avatar-group.tsx`

   The source is in the registry item: https://uiarc.dev/r/avatar-group.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { AvatarGroup } from "@/components/arc/avatar-group/avatar-group";

const team = [
  { name: "Maya Chen", src: "/people/maya.jpg", status: "online" as const },
  { name: "Leo Park" },
  { name: "Sara Ruiz" },
  { name: "Tom Hale" },
  { name: "Ines Ma" },
];

export function Collaborators() {
  return <AvatarGroup members={team} max={3} label="Editors" />;
}
```

### API reference

#### AvatarGroup

An overlapping stack of avatars with a +N overflow chip.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `members` (required) | `{ name: string; src?: string; status?: "online" \| "offline" }[]` | – | People in display order. Names double as keys, so keep them unique. |
| `max` | `number` | `4` | Avatars shown before the rest collapse into the overflow count. |
| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Size passed to each avatar and the overflow chip. |
| `label` | `string` | `"Team members"` | Accessible name for the group, also used in the overflow label. |

### Accessibility

- Renders role="group" with the label as its name.
- The overflow chip is role="img" labelled like "2 more editors".
- Each avatar keeps its own name and status label.

### Motion

- Joining or leaving members open and close their slot on a spring, so the stack slides instead of jumping.
- The overflow count rolls up when it grows and down when it shrinks.
- Avatars never move on hover or focus; the hovered person gets a stronger ring and a name tip. Reduced motion swaps counts with a plain fade.

### Responsive behavior

- The stack is inline-flex and does not wrap; lower max on narrow rows so it stays compact.
- The hover ring and name tip apply only on hover-capable fine pointers; the stack never spreads or shifts.

### Performance

- Only max avatars render; the rest collapse into one overflow chip, so long member lists stay cheap.
- Joins and leaves animate slot width on a spring; hover only changes a ring and a tip in CSS.

### Notes for AI

- Use for presence and ownership in headers, cards, and table cells. Use avatar for one person.
- Pass the full member list and let max handle truncation; do not slice it yourself or the overflow count is lost.

### Related

- [Avatar](https://uiarc.dev/components/avatar/markdown): A compact identity marker for people and accounts.
- [Card](https://uiarc.dev/components/card/markdown): A contained group of related content and actions.
- [User menu](https://uiarc.dev/components/user-menu/markdown): Your account, settings, theme, and sign out behind the avatar. Opens as a bottom sheet on phones.

### Also in avatars

- [Badge](https://uiarc.dev/components/badge/markdown): A small label for status, category, or metadata.
- [Presence stack](https://uiarc.dev/components/presence-stack/markdown): Avatars of the people here now: joins pop in as the stack reflows, a counter rolls past the limit, dots show typing and idle, and hover fans it out with a gliding name label.

### Guidance for AI tools

Avatar group: Show a team or set of contributors in a small space. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Badge

> A small label for status, category, or metadata.

- Type: Component (data)
- Access: Free, open source
- Page: https://uiarc.dev/components/badge
- Markdown: https://uiarc.dev/components/badge/markdown
- Registry item: https://uiarc.dev/r/badge.json
- Source file: `registry/components/badge/badge.tsx`
- Dependencies: motion
- Keywords: label, status, react badge, status badge, status pill, animated badge, tag component, label pill, badge with icon

### When to use

- Short statuses next to titles or in table cells, such as Live, Draft, or Failed.
- Counts or states that change in place and should morph instead of jump.
- Tagging a row with one tone plus an optional icon.

### When not to use

- Use alert or toast when the message needs a full sentence.
- Use chip-group when people toggle the values.
- Use stat-card for a headline number with a trend.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/badge
pnpm dlx shadcn@latest add @uiarc/badge
yarn dlx shadcn@latest add @uiarc/badge
bunx --bun shadcn@latest add @uiarc/badge
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/badge.json
```

#### Manual

1. Install the dependencies:

```bash
npm install motion
```

2. Copy the source into your project. Main file: `registry/components/badge/badge.tsx`

   The source is in the registry item: https://uiarc.dev/r/badge.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { Check } from "lucide-react";
import { Badge } from "@/components/arc/badge/badge";

export function DeployStatus({ live }: { live: boolean }) {
  return (
    <Badge tone={live ? "success" : "neutral"} icon={live ? <Check size={12} /> : undefined}>
      {live ? "Live" : "Draft"}
    </Badge>
  );
}
```

### API reference

#### Badge

A small status label in five status tones and six categorical colours whose label and icon morph in place when they change.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `tone` | `"neutral" \| "success" \| "info" \| "warning" \| "danger"` | `"neutral"` | Status role. Every tone is a soft tint of its semantic token (--success, --info, --warning, --danger) with the tone as text. |
| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Height 20, 24 or 28 px with 11, 12 or 14 px text. |
| `icon` | `ReactNode` | – | Leading icon, sized to the badge (12, 14 or 16 px) and drawn in the tone colour. A different icon component crossfades in. |
| `dot` | `boolean` | `false` | Leading status dot in the tone colour. Ignored when icon is set. |
| `color` | `"teal" \| "sky" \| "orchid" \| "violet" \| "rose" \| "amber"` | – | Categorical colour from the shared --tone-* palette, for labels such as method tags. Overrides tone. |
| `outline` | `boolean` | `false` | Hairline border in the tone colour. Off by default. |
| `pill` | `boolean` | `false` | Fully rounded ends instead of the default 5, 6 or 7 px corners. |
| `children` | `ReactNode` | – | Label. String or number children get the rolling text swap; other nodes render as is. |
| `...props` | `HTMLAttributes<HTMLSpanElement>` | – | Forwarded to the root span. |

### Accessibility

- Renders a plain span, so it is read inline with surrounding text.
- The icon is aria-hidden; the label must state the status on its own, not rely on tone color.
- Outgoing labels are hidden from assistive tech while they fade, so only the current text is read.
- It does not announce changes. Put it inside a live region if a status update must be spoken.

### Motion

- A new label rises in with a short blur while the old one lifts away, and the pill width springs to fit.
- Passive reflows such as font swaps resize instantly; only a content change springs.
- Reduced motion swaps the label with a quick fade and snaps the width.

### Responsive behavior

- The pill sizes to its label and never wraps, so keep labels to a word or two in narrow cells.
- Hover styles apply only on hover-capable fine pointers.

### Performance

- Each badge has a ResizeObserver for the width spring; fine per row, but avoid thousands in one table.
- Font swaps and passive reflows resize instantly; only content changes animate.

### Notes for AI

- Use for short statuses and counts next to titles or in table cells. Use alert or toast for messages with sentences.
- Use dot for live states (online, syncing, down) and an icon when the shape adds meaning; the label is optically centred either way.
- Use tone for status and color for categories (GET teal, POST sky, PUT orchid, PATCH violet, DELETE rose); never use a categorical colour to mean success or failure.
- Keep the badge mounted and change its children to get the morph; remounting with a new key loses it.

### Related

- [Alert](https://uiarc.dev/components/alert/markdown): A persistent message that helps people recover or continue.
- [Sortable data table](https://uiarc.dev/components/sortable-data-table/markdown): Compare structured records with sortable columns.

### Also in avatars

- [Avatar](https://uiarc.dev/components/avatar/markdown): A compact identity marker for people and accounts.
- [Avatar group](https://uiarc.dev/components/avatar-group/markdown): Show a team or set of contributors in a small space.
- [Presence stack](https://uiarc.dev/components/presence-stack/markdown): Avatars of the people here now: joins pop in as the stack reflows, a counter rolls past the limit, dots show typing and idle, and hover fans it out with a gliding name label.

### Guidance for AI tools

Badge: A small label for status, category, or metadata. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Presence stack

> Avatars of the people here now: joins pop in as the stack reflows, a counter rolls past the limit, dots show typing and idle, and hover fans it out with a gliding name label.

- Type: Component (data)
- Access: Arc Pro
- Page: https://uiarc.dev/components/presence-stack
- Markdown: https://uiarc.dev/components/presence-stack/markdown
- Source file: `registry/components/presence-stack/presence-stack.tsx`
- Dependencies: motion, @radix-ui/react-popover
- Keywords: data, avatar, realtime, new, presence, avatars, avatar stack, facepile, who is here, online, collaboration, multiplayer, typing indicator, idle, status, join, leave, overflow, roster

### When to use

- A document, board or design file header that shows who is here right now.
- A call or meeting roster where people come and go and some are talking or idle.
- Any realtime surface where joins, leaves and typing should be felt, not just counted.

### When not to use

- Use avatar-group for a static list of owners, assignees or members that does not change while you look at it.
- Use live-cursors when you also need cursors and selections on a canvas; it includes its own small stack.
- Use a plain count for very large rooms, such as a livestream with thousands of viewers.

### Installation

Presence stack is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/presence-stack
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { PresenceStack, type PresencePerson } from "@/components/arc/presence-stack/presence-stack";

export function DocumentHeader({ doc, me }: { doc: Doc; me: User }) {
  // From your realtime layer: Liveblocks, PartyKit, Supabase Realtime or your own socket.
  const others = useOthers();
  const people: PresencePerson[] = [
    { id: me.id, name: me.name, src: me.avatar, status: "active" },
    ...others.map(other => ({
      id: other.id,
      name: other.name,
      src: other.avatar,
      status: other.typing ? "typing" : other.idle ? "idle" : "active",
      detail: other.section ? `Editing ${other.section}` : undefined,
    })),
  ];

  return (
    <header className="flex items-center justify-between">
      <h1>{doc.title}</h1>
      <PresenceStack people={people} selfId={me.id} align="end" onPersonSelect={person => followCursor(person.id)} />
    </header>
  );
}
```

### API reference

#### PresenceStack

Overlapping avatars of the people here now. A person joining pops into their slot on a spring while the others slide to make room; someone leaving shrinks away and the gap closes. Past max the rest collapse into a +N counter that rolls up or down. Each face carries a status: a green dot for active, a dimmed portrait with a grey dot for idle, and a dot that stretches into a tiny typing indicator while they type. Hover or keyboard focus never moves the stack; one name label glides between the faces, its width following each name on a spring. Clicking opens a list of everyone with what they are doing.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `people` (required) | `readonly PresencePerson[]` | – | Everyone here now, in display order: { id, name, src?, status?: "active" \| "idle" \| "typing", detail? }. Add, remove, reorder or change a status and the stack animates to match. Ids key the avatars, so the same person keeps their place. |
| `max` | `number` | `4` | Faces shown before the rest collapse into the +N counter. |
| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Avatar diameter: 28, 36 or 44px. The overlap, status dot and label scale with it. |
| `align` | `"start" \| "end"` | `"start"` | The side the stack is anchored to. The component reserves the width of a full stack; with end the faces sit against the right edge and grow to the left, which suits a header next to a Share button. |
| `selfId` | `string` | – | Id of the person using the app. Marked (you) in the hover label and the list. |
| `label` | `string` | `"People here now"` | Accessible name of the stack button. The count of people is added to it. |
| `heading` | `string` | `"Here now"` | Heading of the list, shown with a rolling count. |
| `open` | `boolean` | – | Whether the list of everyone is open. Pass with onOpenChange to control it. |
| `defaultOpen` | `boolean` | `false` | Initial open state when uncontrolled. |
| `onOpenChange` | `(open: boolean) => void` | – | Called when the list opens or closes, from a click, Escape or a click outside. |
| `onPersonSelect` | `(person: PresencePerson) => void` | – | Makes each row in the list a button, for example to follow that person's cursor or jump to where they are. The list closes after a pick. |
| `announce` | `boolean` | `true` | Announces joins and leaves in a polite live region, such as Emma Collins joined. |
| `className` | `string` | – | Class on the root element. |
| `style` | `CSSProperties` | – | Inline styles on the root element. Set --presence-ring to the color behind the stack so the cut out rings match it. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Tab | Focuses the stack. It stays in place; arrow keys name each face. |
| Arrow Left / Arrow Right | Moves the name label from face to face while the stack has focus. |
| Enter / Space | Opens the list of everyone; focus moves into it. |
| Tab (in the list) | Moves between rows when onPersonSelect makes them buttons. |
| Escape | Closes the list and returns focus to the stack. |

### Accessibility

- The stack is one button named with the label and the count, such as People here now, 6 people, with aria-haspopup and aria-expanded from the popover.
- The faces, status marks and hover label are decorative; the list repeats every name with their status or detail in text, so nothing depends on color or on the typing animation.
- Joins and leaves are announced in a polite live region. Status changes are not announced to avoid chatter; they are in the list.
- The list is a labelled dialog from Radix Popover: focus moves in on open, Escape and a click outside close it, and focus returns to the stack.
- Rows are plain content unless onPersonSelect is set, then each is a button named with the person and what they are doing.
- Pointer focus draws no ring; keyboard focus shows Arc's shared focus ring. Keyboard focus shows through the name label, which arrow keys move between faces.

### Motion

- Faces are positioned with transforms only. Reflow after a join or leave rides the smooth spring, so a burst of changes blends into one movement instead of queueing.
- A joining face pops in from 40 percent scale on the morph spring, with a hint of overshoot; a leaving face shrinks and fades in 160ms while its neighbours already close the gap.
- The +N counter rolls the way it moved: up for more people, down for fewer. Its number is nudged into the visible part of the chip.
- Hover keeps the 68 percent overlap and never spreads the stack; the hovered face lifts 2px, and one name label glides between faces on the morph spring while its width follows the new name. The label takes its first width at once so it never grows from nothing.
- The status dot scales into a small typing pill whose three dots rise in turn; idle dims the portrait with a fade.
- The list opens from the stack with a short scale and fade; rows expand and collapse in height as people come and go, and the count and detail lines roll.
- With reduced motion every change applies at once: no pop, slide, roll or bouncing dots, and the list simply appears.

### Responsive behavior

- The stack reserves its rest width, so it fits beside a title even at 320px. Hover never changes its width, so it never pushes content.
- On touch there is no hover; a tap opens the list, which carries the same names and statuses.
- The list is 288px wide and stays inside the viewport with collision padding; it scrolls past about six rows.

### Performance

- Only transforms and opacity animate for the stack. Photos render at the exact size, as plain img elements unless ArcProvider sets an image component such as next/image.
- Motion springs are interruptible and stop when settled; nothing runs at rest except the three typing dots, which are a compositor animation and stop with reduced motion.
- Diffing joins and leaves for the live region is a single pass over the ids per update.

### Notes for AI

- Use it wherever a realtime app shows who else is here: a document or board header, a call roster, a shared dashboard.
- Map your presence data to people on every change and pass the whole array; do not animate anything yourself. Keep ids stable across updates.
- Put the current user first and pass selfId so the label and list say (you). Put the most recently active people next so they stay visible before the +N counter.
- Use align="end" in a right aligned header. The component reserves the width of max faces plus the counter so neighbours never shift as people join.
- Use detail for the specific place, such as Editing Pricing; it falls back to Active now, Idle or Typing.
- Set --presence-ring on the component to the surface color behind it so the rings around faces and dots cut out cleanly.

### Related

- [Avatar group](https://uiarc.dev/components/avatar-group/markdown): Show a team or set of contributors in a small space.
- [Avatar](https://uiarc.dev/components/avatar/markdown): A compact identity marker for people and accounts.
- [Popover](https://uiarc.dev/components/popover/markdown): A small anchored surface for contextual information.

### Also in avatars

- [Badge](https://uiarc.dev/components/badge/markdown): A small label for status, category, or metadata.

### Guidance for AI tools

Presence stack: Avatars of the people here now: joins pop in as the stack reflows, a counter rolls past the limit, dots show typing and idle, and hover fans it out with a gliding name label. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Card

> A contained group of related content and actions.

- Type: Component (data)
- Access: Free, open source
- Page: https://uiarc.dev/components/card
- Markdown: https://uiarc.dev/components/card/markdown
- Registry item: https://uiarc.dev/r/card.json
- Source file: `registry/components/card/card.tsx`
- Dependencies: motion, @radix-ui/react-dialog, lucide-react
- Keywords: surface, layout, react card, card component, card with image, expand card to modal, quick look card, shared layout card, project card

### When to use

- Browsable items in a grid, such as projects, listings, or posts.
- Items that should open into a larger quick look dialog without leaving the page, via details.
- Content with media, an owner byline, and a status line that updates in place.

### When not to use

- Use expandable-card for inline disclosure without a dialog.
- Use stat-card or metric-card for numbers.
- Use dialog when the content has no card to grow from.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/card
pnpm dlx shadcn@latest add @uiarc/card
yarn dlx shadcn@latest add @uiarc/card
bunx --bun shadcn@latest add @uiarc/card
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/card.json
```

#### Manual

1. Install the dependencies:

```bash
npm install motion @radix-ui/react-dialog lucide-react
```

2. Copy the source into your project. Main file: `registry/components/card/card.tsx`

   The source is in the registry item: https://uiarc.dev/r/card.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { Card } from "@/components/arc/card/card";
import { Avatar } from "@/components/arc/avatar/avatar";

export function ProjectCard() {
  return (
    <Card
      title="Harbour redesign"
      description="New booking flow and room pages."
      media={<img src="/harbour.jpg" alt="" />}
      avatar={<Avatar name="Maya Chen" size="sm" />}
      meta="Maya Chen"
      status="Updated 2 hours ago"
      details={<p>Scope, milestones, and open questions.</p>}
    />
  );
}
```

### API reference

#### Card

A content card with optional media, byline, and action that can grow into a quick look dialog.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` (required) | `string` | – | Card heading. Becomes the dialog trigger when details is set. |
| `description` | `string` | – | Supporting line under the title. |
| `media` | `ReactNode` | – | Image or visual at the top. Zooms slightly on hover. |
| `action` | `ReactNode` | – | Trailing footer control, such as a button. |
| `avatar` | `ReactNode` | – | Small leading visual in the footer, such as the owner's avatar. |
| `meta` | `ReactNode` | – | Who the card belongs to, shown in the byline. |
| `status` | `string` | – | Short status under the meta, such as "Updated 2 hours ago". Changes roll in word by word and are announced politely. |
| `details` | `ReactNode` | – | Quick look content. When set, the card opens into a larger Radix dialog. |
| `open` | `boolean` | – | Controlled quick look state. |
| `defaultOpen` | `boolean` | `false` | Initial quick look state when uncontrolled. |
| `onOpenChange` | `(open: boolean) => void` | – | Called when the quick look opens or closes. |
| `children` | `ReactNode` | – | Extra body content between the description and footer. |
| `...props` | `HTMLAttributes<HTMLElement>` | – | Forwarded to the root article. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Enter / Space | On the title, opens the quick look when details is set. |
| Escape | Closes the quick look and returns focus to the title. |
| Tab | Stays trapped inside the open quick look. |

### Accessibility

- Renders an article with an h3 title; the quick look uses Radix Dialog with the title and description wired as its label and description.
- Only the title becomes a button, so nested actions stay separately focusable.
- Status changes are read through a role="status" region.
- Give media images alt text or an empty alt when decorative, and an aria-label to icon-only actions.

### Motion

- Hover lifts the card 2px and slowly zooms the media.
- The quick look shares layout ids with the card, so surface, photo, title, and byline travel on one spring; details fade in after.
- Reduced motion drops the lift, zoom, and morph, and the dialog simply fades.

### Responsive behavior

- The card fills its grid cell with min-width 0; the quick look panel is min(30rem, 100vw minus a gutter) wide and capped at the viewport height.
- Hover lift and media zoom run only for a mouse; touch and pen never lift.

### Performance

- The quick look shares layout ids with the card, so the morph animates several elements; the dialog mounts only while open.
- The overlay uses a 7px backdrop blur, which can cost frames on low-end devices over busy pages.

### Notes for AI

- Use for browsable items in a grid: projects, listings, posts. Use expandable-card for inline disclosure without a dialog, and stat-card or metric-card for numbers.
- Add details only when there is real extra content; without it the card is a static article.
- Keep status short and change it in place to get the rolling update.

### Related

- [Expandable card](https://uiarc.dev/components/expandable-card/markdown): Give a dense card more room when requested.
- [Dialog](https://uiarc.dev/components/dialog/markdown): A focused surface for decisions that need attention.
- [Avatar](https://uiarc.dev/components/avatar/markdown): A compact identity marker for people and accounts.
- [Photo grid](https://uiarc.dev/components/photo-grid/markdown): Pinch through zoom levels and open any photo straight from its cell.

### Also in cards

- [Metric card](https://uiarc.dev/components/metric-card/markdown): A compact summary for a number that needs context.
- [Empty state](https://uiarc.dev/components/empty-state/markdown): A useful next step when there is nothing to show yet.
- [Metric ticker](https://uiarc.dev/components/metric-ticker/markdown): A strip of live KPIs that roll to new values digit by digit and flash their change; rest on one to pause the strip and open its recent trend as a sparkline.

### Guidance for AI tools

Card: A contained group of related content and actions. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Metric card

> A compact summary for a number that needs context.

- Type: Component (data)
- Access: Free, open source
- Page: https://uiarc.dev/components/metric-card
- Markdown: https://uiarc.dev/components/metric-card/markdown
- Registry item: https://uiarc.dev/r/metric-card.json
- Source file: `registry/components/metric-card/metric-card.tsx`
- Dependencies: motion
- Keywords: data, summary, react metric card, kpi card, odometer number, rolling number card, dashboard metric, stat tile

### When to use

- A single plain number with odometer style rolling digits, such as uptime or orders.
- Numbers that update live and should roll in the direction they moved.

### When not to use

- Use stat-card for preformatted strings, trend arrows, tones, and icons.
- Use sparkline when the trend over time matters more than the latest value.
- Use animated-counter for a number without a card around it.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/metric-card
pnpm dlx shadcn@latest add @uiarc/metric-card
yarn dlx shadcn@latest add @uiarc/metric-card
bunx --bun shadcn@latest add @uiarc/metric-card
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/metric-card.json
```

#### Manual

1. Install the dependencies:

```bash
npm install motion
```

2. Copy the source into your project. Main file: `registry/components/metric-card/metric-card.tsx`

   The source is in the registry item: https://uiarc.dev/r/metric-card.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { MetricCard } from "@/components/arc/metric-card/metric-card";

export function Uptime() {
  return <MetricCard label="Uptime" value={99.9} suffix="%" context="Last 30 days" change="+0.2%" />;
}
```

### API reference

#### MetricCard

A compact card with a label, an odometer style number, context line, and optional change chip.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` (required) | `string` | – | What is measured. |
| `value` (required) | `number` | – | The number. Rolls up from zero on first view, then between values. |
| `suffix` | `string` | – | Text after the number, such as "%" or " ms". |
| `context` (required) | `string` | – | Line under the number, such as "vs last week". |
| `change` | `string` | – | Chip in the top corner, such as "+12%". Omit to hide it. |

### Accessibility

- Renders an article; the number is read as plain text through a visually hidden copy.
- The change chip is plain text, so write the direction into it (+ or -) rather than relying on color.
- It does not announce updates; wrap it in a live region if values change while people watch.

### Motion

- The value uses animated-counter: digits roll on view and turn the way the number moved.
- Label, context, and change copy roll in from the direction the number moved, and the chip width springs.
- Reduced motion jumps the digits and swaps copy with a quick fade.

### Responsive behavior

- Below 380px the padding tightens and the change chip wraps under the label instead of crowding it.
- Copy lines stay on one line and clip, so keep label and context short.

### Performance

- Digits roll with animated-counter and a ResizeObserver drives the chip width spring; a dashboard row of cards is fine.

### Notes for AI

- Use when the value is a plain number and you want the rolling digits. Use stat-card for preformatted strings, trend arrows, tones, and icons.
- value must be a number; put units in suffix and formatting-free context in context.

### Related

- [Animated counter](https://uiarc.dev/components/animated-counter/markdown): Give changing totals a clear sense of movement.
- [Sparkline](https://uiarc.dev/components/sparkline/markdown): Show a compact trend beside a value.
- [Gauge](https://uiarc.dev/components/gauge/markdown): Show a value against a known range.

### Also in cards

- [Card](https://uiarc.dev/components/card/markdown): A contained group of related content and actions.
- [Empty state](https://uiarc.dev/components/empty-state/markdown): A useful next step when there is nothing to show yet.
- [Metric ticker](https://uiarc.dev/components/metric-ticker/markdown): A strip of live KPIs that roll to new values digit by digit and flash their change; rest on one to pause the strip and open its recent trend as a sparkline.

### Guidance for AI tools

Metric card: A compact summary for a number that needs context. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Empty state

> A useful next step when there is nothing to show yet.

- Type: Component (data)
- Access: Free, open source
- Page: https://uiarc.dev/components/empty-state
- Markdown: https://uiarc.dev/components/empty-state/markdown
- Registry item: https://uiarc.dev/r/empty-state.json
- Source file: `registry/components/empty-state/empty-state.tsx`
- Dependencies: motion, lucide-react
- Keywords: data, guidance, react empty state, no results, empty list placeholder, zero state, blank slate, first run empty view

### When to use

- Empty lists, zero search results, and first-run views.
- A view that should morph between states, such as empty and success, by changing props.

### When not to use

- Use skeleton while data is still loading.
- Use alert for errors inside a page that still has content.
- Use onboarding-checklist when first-run needs several steps.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/empty-state
pnpm dlx shadcn@latest add @uiarc/empty-state
yarn dlx shadcn@latest add @uiarc/empty-state
bunx --bun shadcn@latest add @uiarc/empty-state
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/empty-state.json
```

#### Manual

1. Install the dependencies:

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

2. Copy the source into your project. Main file: `registry/components/empty-state/empty-state.tsx`

   The source is in the registry item: https://uiarc.dev/r/empty-state.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { Search } from "lucide-react";
import { Button } from "@/components/arc/button/button";
import { EmptyState } from "@/components/arc/empty-state/empty-state";

export function NoResults({ onClear }: { onClear: () => void }) {
  return (
    <EmptyState
      icon={<Search size={24} />}
      title="No matches"
      description="Try a shorter search or clear the filters."
      action={<Button variant="secondary" onClick={onClear}>Clear filters</Button>}
    />
  );
}
```

### API reference

#### EmptyState

A centered icon, title, description, and optional action for empty views.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` (required) | `string` | – | Headline. A new title rises in while the old one leaves. |
| `description` (required) | `string` | – | One or two sentences on why it is empty and what to do. |
| `action` | `ReactNode` | – | Call to action, usually a button. |
| `icon` | `ReactNode` | `<Folder />` | Leading icon. A different icon component crossfades in. |
| `className` | `string` | – | Class for the root section. |
| `label` | `string` | – | Accessible name for the section region. |

### Accessibility

- Renders a section with an h3 title; pass label to name the region.
- The icon is aria-hidden.
- Outgoing copy is hidden from assistive tech while it fades.

### Motion

- Changing title or description rolls the copy in place while the block height springs to fit.
- A new icon pops in with a short blur.
- Reduced motion swaps copy with a fade and snaps height; the icon's idle animation stops.

### Responsive behavior

- Padding scales with the viewport between fixed bounds, and the description caps at 18rem so lines stay short.
- Actions wrap and center, so two buttons stack on narrow screens.

### Performance

- One ResizeObserver drives the height spring; the icon's idle animation is CSS and stops under reduced motion.

### Notes for AI

- Use for empty lists, zero search results, and first-run views. Use skeleton while data is loading.
- Keep it mounted and change its props to morph between states such as empty and success.

### Related

- [Skeleton](https://uiarc.dev/components/skeleton/markdown): Reserve space while content is still loading.
- [Alert](https://uiarc.dev/components/alert/markdown): A persistent message that helps people recover or continue.
- [Onboarding checklist](https://uiarc.dev/components/onboarding-checklist/markdown): Guide a new workspace through setup, one step at a time.
- [Sortable data table](https://uiarc.dev/components/sortable-data-table/markdown): Compare structured records with sortable columns.

### Also in cards

- [Card](https://uiarc.dev/components/card/markdown): A contained group of related content and actions.
- [Metric card](https://uiarc.dev/components/metric-card/markdown): A compact summary for a number that needs context.
- [Metric ticker](https://uiarc.dev/components/metric-ticker/markdown): A strip of live KPIs that roll to new values digit by digit and flash their change; rest on one to pause the strip and open its recent trend as a sparkline.

### Guidance for AI tools

Empty state: A useful next step when there is nothing to show yet. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Metric ticker

> A strip of live KPIs that roll to new values digit by digit and flash their change; rest on one to pause the strip and open its recent trend as a sparkline.

- Type: Component (data)
- Access: Arc Pro
- Page: https://uiarc.dev/components/metric-ticker
- Markdown: https://uiarc.dev/components/metric-ticker/markdown
- Source file: `registry/components/metric-ticker/metric-ticker.tsx`
- Dependencies: motion, lucide-react
- Keywords: data, metric, realtime, new, ticker, kpi, metrics, live, stock ticker, marquee, strip, odometer, rolling digits, delta, sparkline, dashboard header, status, trend

### When to use

- A compact live readout of several KPIs above a dashboard, a status page or a trading view.
- Wall screens and operations views where values change on their own and people glance at them.
- A header strip that must fit anywhere from a phone to a wide monitor without redesign.

### When not to use

- Use metric-card or stat-card for one or two headline numbers with room for context.
- Use line-chart or sparkline when the trend over time is the main content, not a detail.
- Avoid it for values that change once a day; the live treatment would promise more than it delivers.

### Installation

Metric ticker is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/metric-ticker
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { MetricTicker, type TickerMetric } from "@/components/arc/metric-ticker/metric-ticker";

export function HealthStrip({ stats }: { stats: LiveStats }) {
  const metrics: TickerMetric[] = [
    { id: "mrr", label: "Monthly recurring revenue", value: stats.mrr, format: { style: "currency", currency: "USD", maximumFractionDigits: 0 } },
    { id: "active", label: "Active now", value: stats.activeUsers },
    { id: "conversion", label: "Trial conversion", value: stats.conversion, format: { style: "percent", maximumFractionDigits: 1 }, delta: "absolute", caption: "Rolling 7 days" },
    { id: "latency", label: "API p95", value: stats.p95, format: { style: "unit", unit: "millisecond" }, positive: "down", delta: "absolute", history: stats.p95History },
  ];

  return <MetricTicker metrics={metrics} label="Product health" />;
}
```

### API reference

#### MetricTicker

A strip of live KPIs for the top of a dashboard. Each value rolls to its new reading digit by digit, ones first and each higher place a beat later like a mechanical counter, and its change flashes beside it as an arrow and an amount, green or red by whether the move is good news for that metric, before settling into a quieter tone. Rest on a metric, focus it or tap it and a floating panel grows out of it with a sparkline of recent values that draws itself in, the trend and the low and high; moving to the next metric glides the same panel across. When the metrics do not fit, the strip becomes a slow marquee that glides to a stop under the pointer, can be dragged or flicked and eases back into its drift, or a plain horizontal scroll.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `metrics` | `readonly TickerMetric[]` | – | The metrics in order: { id, label, value, format?, delta?, positive?, history?, caption? }. Pass a new array whenever a value changes; changes are matched by id. |
| `metrics[].format` | `Intl.NumberFormatOptions` | – | Number format for the value, such as currency, percent or a unit like { style: "unit", unit: "millisecond" }. Defaults to whole numbers. |
| `metrics[].delta` | `"percent" \| "absolute"` | `"percent"` | How the change reads: relative to the previous value, or as the raw difference in the metric's own format. Absolute changes of a percent metric read in points, such as 0.3 pts. |
| `metrics[].positive` | `"up" \| "down"` | `"up"` | Which direction is good news. Set down for latency, error rate or churn so a rise flashes red. |
| `metrics[].history` | `readonly number[]` | – | Recent values, oldest first, for the sparkline. Leave it out and the ticker keeps its own history from the values it has seen. |
| `metrics[].caption` | `string` | – | Context at the top of the panel, such as Rolling 7 days. Defaults to Last n updates. |
| `overflow` | `"marquee" \| "scroll"` | `"marquee"` | What happens when the metrics do not fit: a slow marquee that pauses on hover, focus and while a panel is open, or plain horizontal scrolling with snap points. Metrics that fit simply share the width. |
| `speed` | `number` | `32` | Marquee drift in pixels per second. |
| `flashDuration` | `number` | `1600` | How long a change stays emphasised before the delta settles to its resting tone, in milliseconds. |
| `historyLength` | `number` | `24` | Points kept for the sparkline when history is not passed. |
| `locale` | `string` | `"en-US"` | Formatting locale. Fixed by default so server and client render the same digits. |
| `label` | `string` | `"Live metrics"` | Accessible name of the strip. |
| `className` | `string` | – | Class on the root element. |
| `style` | `CSSProperties` | – | Inline styles on the root element. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Tab | Moves focus into the strip, onto the last focused metric. Focus opens its panel and pauses the marquee, bringing the metric into view. |
| Arrow Left / Arrow Right | Moves focus to the previous or next metric, wrapping at the ends; the panel glides with it. |
| Home / End | Moves focus to the first or last metric. |
| Enter / Space | Pins the panel open, or closes a pinned panel. |
| Escape | Closes the panel. |

### Accessibility

- The strip is a labelled region with a list of metrics. Each metric is a button named with its label, formatted value and change, such as API p95, 214 ms, up 2 ms, with aria-expanded and aria-controls pointing at the panel.
- Only one metric is a tab stop (roving tab index), so the strip costs one Tab however many metrics it holds.
- Changes pair an arrow and a signed amount with color, so good and bad news never rely on color alone.
- Values are not announced on every tick, which would flood a screen reader on a live strip; they are read when a metric is focused.
- The repeated copy that makes the marquee seamless is hidden from assistive technology and out of the tab order.
- The sparkline is decorative; the panel states the trend in words and the low and high as text.

### Motion

- Digits roll like an odometer on the smooth spring, turning the way the value moved and wrapping 9 to 0. The ones settle first and each higher place follows 25ms later, so a change ripples right to left. A new digit column or a wider delta opens on a spring, never in one frame.
- A change flashes for flashDuration: the delta's tint deepens, its arrow slides in from the direction of travel and a thin ring expands and fades once. Then the tint drains and the delta rests in a quieter tone until the next change.
- The marquee eases its speed rather than stopping dead: resting on the strip glides it to a halt in about half a second, leaving lets it pick up again gently. Drag to scrub it; release hands your flick back to the loop, which decays into the steady drift.
- The panel grows out of the metric that opened it on a morph spring, scaling from the metric's center. It follows its metric every frame, and moving to another metric glides it across while its content crossfades.
- The sparkline draws itself in, the area fades up under it and the last point pops in once the line arrives.
- Focusing a metric inside a moving marquee pulls it into view on the shortest path around the loop.
- With reduced motion there is no marquee (overflow falls back to horizontal scroll), digits change in place, the panel fades without scaling and the sparkline appears drawn.

### Responsive behavior

- Metrics that fit share the width equally. When they no longer fit, the strip becomes a marquee (or a snapping horizontal scroll with overflow="scroll"); the switch is measured with a ResizeObserver, not a breakpoint.
- The marquee feathers its ends with a mask while the border stays crisp.
- Below 420px values drop to the base size and metrics tighten their padding.
- The panel is at most 248px wide and is kept inside the component's box; leave room under the strip or let it float over the content below.
- Touch: a tap pins a panel and pauses the strip; a press anywhere outside closes it. Horizontal drags scrub the marquee while vertical page scrolling still works.

### Performance

- The marquee is one requestAnimationFrame loop writing a single transform. It stops entirely when the strip is offscreen, when the tab is hidden and when the marquee is not needed.
- The panel follows its metric with a frame loop that runs only while a panel is open.
- Digit wheels, the flash and the panel are transforms and opacity only. The sparkline is one small SVG path redrawn when its data changes.

### Notes for AI

- Use it as the live headline of a dashboard, status page or trading style view: four to eight metrics people glance at while doing something else.
- Set positive: "down" on any metric where lower is better (latency, errors, churn, cost). Getting this wrong flashes good news red.
- Use delta: "absolute" for rates and durations, where 0.3 points or 8 ms means more than a percent of a percent; keep the default percent for money and counts.
- Pass history when you already have a series from your backend; otherwise the ticker builds one from what it sees since mount.
- Keep labels to two or three words. The strip is for scanning; the panel caption can carry the context.
- Batch updates. One to a few changes a second reads as live; a new array every frame just flickers.

### Related

- [Metric card](https://uiarc.dev/components/metric-card/markdown): A compact summary for a number that needs context.
- [Sparkline](https://uiarc.dev/components/sparkline/markdown): Show a compact trend beside a value.
- [Animated counter](https://uiarc.dev/components/animated-counter/markdown): Give changing totals a clear sense of movement.
- [Line chart](https://uiarc.dev/components/line-chart/markdown): A multi-series line chart with a gliding crosshair, legend toggles, and paths that morph between ranges.

### Also in cards

- [Card](https://uiarc.dev/components/card/markdown): A contained group of related content and actions.
- [Empty state](https://uiarc.dev/components/empty-state/markdown): A useful next step when there is nothing to show yet.

### Guidance for AI tools

Metric ticker: A strip of live KPIs that roll to new values digit by digit and flash their change; rest on one to pause the strip and open its recent trend as a sparkline. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Line chart

> A multi-series line chart with a gliding crosshair, legend toggles, and paths that morph between ranges.

- Type: Component (data)
- Access: Free, open source
- Page: https://uiarc.dev/components/line-chart
- Markdown: https://uiarc.dev/components/line-chart/markdown
- Registry item: https://uiarc.dev/r/line-chart.json
- Source file: `registry/components/line-chart/line-chart.tsx`
- Dependencies: motion
- Keywords: data, new, react line chart, time series chart, animated line chart, chart with crosshair, trend chart, multi series line chart, dashboard chart, accessible chart

### When to use

- Traffic, revenue, or latency over days or weeks in a dashboard card.
- Comparing this period against a previous period or target with a dashed series.
- Charts that switch ranges (7d, 30d, 90d) and should morph rather than redraw.

### When not to use

- Use sparkline for a tiny inline trend with no axes or tooltip.
- Use bar-chart for discrete categories or counts per bucket.
- Use donut-chart when the question is the share of a whole, not change over time.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/line-chart
pnpm dlx shadcn@latest add @uiarc/line-chart
yarn dlx shadcn@latest add @uiarc/line-chart
bunx --bun shadcn@latest add @uiarc/line-chart
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/line-chart.json
```

#### Manual

1. Install the dependencies:

```bash
npm install motion
```

2. Copy the source into your project. Main file: `registry/components/line-chart/line-chart.tsx`

   The source is in the registry item: https://uiarc.dev/r/line-chart.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { LineChart } from "@/components/arc/line-chart/line-chart";

const data = [
  { key: "2026-09-01", label: "Tue, Sep 1", axisLabel: "Sep 1", values: { signups: 120, previous: 98 } },
  { key: "2026-09-02", label: "Wed, Sep 2", values: { signups: 142, previous: 104 } },
  { key: "2026-09-03", label: "Thu, Sep 3", axisLabel: "Sep 3", values: { signups: 131, previous: 110 } },
];

export function SignupsChart() {
  return (
    <LineChart
      label="Signups"
      data={data}
      series={[
        { key: "signups", label: "This period" },
        { key: "previous", label: "Previous period", dashed: true },
      ]}
    />
  );
}
```

### Examples

#### Headline readout driven by the crosshair

```tsx
const [active, setActive] = useState<LineChartDatum | null>(null);

<p>{(active ?? data[data.length - 1]).values.signups}</p>
<LineChart label="Signups" data={data} series={series} onActiveChange={(_, datum) => setActive(datum)} />
```

### API reference

#### LineChart

An SVG line chart with a scrubbable crosshair, series toggles, morphing data changes, and a screen reader data table.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `data` (required) | `LineChartDatum[]` | – | Points: { key, label, axisLabel?, values }. values maps series keys to numbers; a missing value counts as zero. |
| `series` (required) | `LineChartSeries[]` | – | Lines: { key, label, color?, dashed?, area? }. area defaults to true for the first series. |
| `label` (required) | `string` | – | What is measured, such as "Signups". Names the chart for assistive technology. |
| `unit` | `string` | `""` | Unit after each value in the tooltip and table, such as "ms". |
| `height` | `number` | `220` | Plot height in pixels. The width follows the container. |
| `formatValue` | `(value: number, series: LineChartSeries) => string` | – | Formats values in the tooltip and data table. Defaults to grouped numbers with one decimal. |
| `formatTick` | `(value: number) => string` | `compact format` | Formats the value axis, such as 1.2K. |
| `hiddenSeries` | `string[]` | – | Controlled hidden series keys. |
| `defaultHiddenSeries` | `string[]` | – | Hidden series keys on first render when uncontrolled. |
| `onHiddenSeriesChange` | `(hidden: string[]) => void` | – | Called when a legend toggle changes the hidden keys. |
| `onActiveChange` | `(index: number \| null, datum: LineChartDatum \| null) => void` | – | Called as the crosshair moves, and with null when it leaves. Use it to drive a headline readout. |
| `loading` | `boolean` | `false` | Dims the current lines while the next range loads, or shows a skeleton when there is no data. |
| `emptyLabel` | `string` | `"No data for this range"` | Shown when there are no points. |
| `legend` | `boolean` | – | Series toggles above the plot. Shown by default when there is more than one series. |
| `categoryLabel` | `string` | `"Date"` | Header of the first column in the screen reader table, and part of the plot's slider label. |
| `curve` | `"smooth" \| "linear"` | `"smooth"` | Monotone curves that never swing past the data, or straight segments. |
| `ref` | `Ref<HTMLElement>` | – | The figure element. |
| `className` | `string` | – | Class on the figure. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| ArrowLeft / ArrowDown | Moves the crosshair to the previous point. |
| ArrowRight / ArrowUp | Moves to the next point; from rest it starts on the latest point. |
| PageUp / PageDown | Jumps about a sixth of the range. |
| Home / End | Jumps to the first or last point. |
| Escape | Lets go of the crosshair. |

### Accessibility

- The figure is named by label; the plot is a role="slider" whose aria-valuetext reads the date and every visible series value.
- A visually hidden summary gives the range and latest values, and a hidden table lists every point for screen readers.
- Legend toggles are buttons with aria-pressed; a hidden live region says Loading while loading is true.
- The SVG and tooltip are aria-hidden, so values are never read twice.

### Motion

- Lines draw left to right the first time the chart scrolls into view.
- New data morphs every line from the shape on screen, sampled on shared x positions, and the value scale springs to its new range while gridlines slide.
- A hidden series flattens into the baseline as it fades; the crosshair glides between points and the tooltip follows on its own spring, flipping sides near the edge.
- Reduced motion skips the draw, morphs, and glides, and stops the loading pulse.

### Responsive behavior

- Width follows the container through a ResizeObserver; the plot redraws in its own pixels, and axis labels thin to one per 76px.
- Touch scrubs with pointer capture and releases on lift; touch-action: pan-y keeps vertical page scroll working over the plot.
- A mouse scrubs on hover and releases on leave. The value gutter is a fixed 48px column.

### Performance

- Paths are written straight to the DOM from motion values, not React state, so scrubbing and morphs do not re-render the tree.
- Smooth curves are sampled up to 16 points per segment (about 192 per line); keep data to a few hundred points per series.
- One ResizeObserver per chart; the draw-in waits for useInView.

### Notes for AI

- Use for one to three measures over time when the trend shape matters. For category comparison use bar-chart; for parts of a whole use donut-chart.
- Keep series and datum keys stable across range changes so lines morph instead of redrawing.
- Set axisLabel only on the dates you want on the axis; the chart thins them further to one per 76px, always keeping the newest.
- Drive a headline number from onActiveChange, as in metric-card or stat-card layouts.

### Related

- [Bar chart](https://uiarc.dev/components/bar-chart/markdown): Compare one measure across days and scrub any bar for its value.
- [Sparkline](https://uiarc.dev/components/sparkline/markdown): Show a compact trend beside a value.
- [Donut chart](https://uiarc.dev/components/donut-chart/markdown): A donut whose arcs morph between datasets, with the active value rolling into the center.
- [Metric card](https://uiarc.dev/components/metric-card/markdown): A compact summary for a number that needs context.

### Also in charts

- [Streamgraph](https://uiarc.dev/components/streamgraph/markdown): Layered streams on a wiggle baseline that morph between ranges, with a layer you can isolate and read week by week.
- [Brush chart](https://uiarc.dev/components/brush-chart/markdown): A dense time series with an overview strip: drag a window to zoom, resize it by its handles, and read events in place.
- [Waffle chart](https://uiarc.dev/components/waffle-chart/markdown): A ten by ten unit chart where every cell is one percent, and cells fly to their new group when the data changes.
- [Slope chart](https://uiarc.dev/components/slope-chart/markdown): Before and after on two axes: lines draw in, rank moves sit beside each value, and switching datasets slides every line to its new slope.
- [Gauge](https://uiarc.dev/components/gauge/markdown): Show a value against a known range.
- [Activity heatmap](https://uiarc.dev/components/activity-heatmap/markdown): See a year of activity at a glance, one square per day.
- [Animated counter](https://uiarc.dev/components/animated-counter/markdown): Give changing totals a clear sense of movement.
- [Ridgeline](https://uiarc.dev/components/ridgeline/markdown): Overlapping distributions, one ridge per group: hover to lift a ridge and read its quartiles, switch datasets and every curve morphs.
- [Treemap](https://uiarc.dev/components/treemap/markdown): A squarified treemap: click to drill and the tiles grow to fill the view, with a breadcrumb back and metrics that morph every tile.
- [Split bar](https://uiarc.dev/components/split-bar/markdown): A single 100% bar split into shares: rest on a segment to widen it and read its exact figures, toggle segments from the legend and the rest reflow, with labels inside when they fit and on leader lines when they don't.

### Guidance for AI tools

Line chart: A multi-series line chart with a gliding crosshair, legend toggles, and paths that morph between ranges. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Bar chart

> Compare one measure across days and scrub any bar for its value.

- Type: Component (data)
- Access: Free, open source
- Page: https://uiarc.dev/components/bar-chart
- Markdown: https://uiarc.dev/components/bar-chart/markdown
- Registry item: https://uiarc.dev/r/bar-chart.json
- Source file: `registry/components/bar-chart/bar-chart.tsx`
- Dependencies: motion
- Keywords: chart, bar, data, react bar chart, column chart, animated bar chart, svg bar chart, scrubbable chart, daily activity chart

### When to use

- One measure across days, weeks, or months, with an average line.
- Charts with a range switch, where stable keys let bars morph between ranges.

### When not to use

- Use sparkline for a compact trend.
- Use activity-heatmap for daily rhythm over a year.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/bar-chart
pnpm dlx shadcn@latest add @uiarc/bar-chart
yarn dlx shadcn@latest add @uiarc/bar-chart
bunx --bun shadcn@latest add @uiarc/bar-chart
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/bar-chart.json
```

#### Manual

1. Install the dependencies:

```bash
npm install motion
```

2. Copy the source into your project. Main file: `registry/components/bar-chart/bar-chart.tsx`

   The source is in the registry item: https://uiarc.dev/r/bar-chart.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { BarChart } from "@/components/arc/bar-chart/bar-chart";

const week = [
  { key: "2026-09-14", label: "Mon, Sep 14", axisLabel: "M", value: 32 },
  { key: "2026-09-15", label: "Tue, Sep 15", axisLabel: "T", value: 48 },
  { key: "2026-09-16", label: "Wed, Sep 16", axisLabel: "W", value: 27 },
];

export function ActiveMinutes() {
  return <BarChart data={week} label="Active minutes" period="Sep 14–16, 2026" unit="min" />;
}
```

### API reference

#### BarChart

A single series column chart with an average line and a scrubbable headline value.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `data` (required) | `{ key: string; label: string; axisLabel?: string; value: number }[]` | – | Bars in order. A surviving key keeps its bar, so range switches morph. |
| `label` (required) | `string` | – | What is measured, such as "Active minutes". |
| `period` (required) | `string` | – | Range on show, under the headline. |
| `unit` | `string` | `""` | Unit after each value, such as "min". |
| `averageLabel` | `string` | `"Daily average"` | Headline label at rest. |
| `valueLabel` | `string` | `"Total"` | Headline label while a bar is scrubbed. |
| `categoryLabel` | `string` | `"Day"` | First column header in the screen reader table. |
| `showAverage` | `boolean` | `true` | Draws the average as a reference line. |
| `height` | `number` | `176` | Plot height in pixels. |
| `formatValue` | `(value: number) => string` | – | Formats values and ticks. Defaults to a grouped number. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| ArrowLeft / ArrowRight | Moves between bars (ArrowDown and ArrowUp too). |
| PageDown / PageUp | Moves up to seven bars. |
| Home / End | Jumps to the first or last bar. |
| Escape | Stops scrubbing and returns to the average. |

### Accessibility

- The SVG is role="img" with a summary of average, highest, and lowest.
- A focusable role="slider" scrubber reads each bar as its label and value.
- A visually hidden table lists every value, and range changes are announced politely.

### Motion

- Bars grow in with a stagger on first view; new ranges morph bars, ticks, and the average line.
- Scrubbing moves a cursor and rolls the headline value.
- Reduced motion shows bars at once and swaps values without movement.

### Responsive behavior

- The plot measures its width with a ResizeObserver and bars cap at 28px, so wide containers get spacing rather than fat bars.
- Scrubbing uses touch-action pan-y, so a horizontal drag scrubs while vertical swipes scroll the page.

### Performance

- Bars, ticks, and the average line animate with motion values; one series and many bars per view is the intended load.
- A visually hidden table renders every value, so very long ranges double the DOM.

### Notes for AI

- Use for one measure across days, weeks, or months. Use sparkline for a compact trend and activity-heatmap for daily rhythm over a year.
- Use stable keys such as ISO dates so switching ranges morphs instead of redrawing.

### Related

- [Sparkline](https://uiarc.dev/components/sparkline/markdown): Show a compact trend beside a value.
- [Activity heatmap](https://uiarc.dev/components/activity-heatmap/markdown): See a year of activity at a glance, one square per day.
- [Segmented control](https://uiarc.dev/components/segmented-control/markdown): Switch between a small set of related views.

### Also in charts

- [Line chart](https://uiarc.dev/components/line-chart/markdown): A multi-series line chart with a gliding crosshair, legend toggles, and paths that morph between ranges.
- [Donut chart](https://uiarc.dev/components/donut-chart/markdown): A donut whose arcs morph between datasets, with the active value rolling into the center.
- [Streamgraph](https://uiarc.dev/components/streamgraph/markdown): Layered streams on a wiggle baseline that morph between ranges, with a layer you can isolate and read week by week.
- [Brush chart](https://uiarc.dev/components/brush-chart/markdown): A dense time series with an overview strip: drag a window to zoom, resize it by its handles, and read events in place.
- [Waffle chart](https://uiarc.dev/components/waffle-chart/markdown): A ten by ten unit chart where every cell is one percent, and cells fly to their new group when the data changes.
- [Slope chart](https://uiarc.dev/components/slope-chart/markdown): Before and after on two axes: lines draw in, rank moves sit beside each value, and switching datasets slides every line to its new slope.
- [Gauge](https://uiarc.dev/components/gauge/markdown): Show a value against a known range.
- [Animated counter](https://uiarc.dev/components/animated-counter/markdown): Give changing totals a clear sense of movement.
- [Ridgeline](https://uiarc.dev/components/ridgeline/markdown): Overlapping distributions, one ridge per group: hover to lift a ridge and read its quartiles, switch datasets and every curve morphs.
- [Treemap](https://uiarc.dev/components/treemap/markdown): A squarified treemap: click to drill and the tiles grow to fill the view, with a breadcrumb back and metrics that morph every tile.
- [Split bar](https://uiarc.dev/components/split-bar/markdown): A single 100% bar split into shares: rest on a segment to widen it and read its exact figures, toggle segments from the legend and the rest reflow, with labels inside when they fit and on leader lines when they don't.

### Guidance for AI tools

Bar chart: Compare one measure across days and scrub any bar for its value. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Donut chart

> A donut whose arcs morph between datasets, with the active value rolling into the center.

- Type: Component (data)
- Access: Free, open source
- Page: https://uiarc.dev/components/donut-chart
- Markdown: https://uiarc.dev/components/donut-chart/markdown
- Registry item: https://uiarc.dev/r/donut-chart.json
- Source file: `registry/components/donut-chart/donut-chart.tsx`
- Dependencies: motion
- Keywords: data, new, react donut chart, pie chart, ring chart, share of total chart, animated donut, chart with legend, category breakdown, accessible pie chart

### When to use

- Traffic by source, spend by category, or storage by file type.
- A dashboard card where the total and one highlighted share matter most.
- Switching between datasets, such as this month and last month, with the same categories.

### When not to use

- Use bar-chart when precise comparison between parts matters or there are many parts.
- Use gauge or usage-meter for a single value against a limit.
- Use line-chart for change over time.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/donut-chart
pnpm dlx shadcn@latest add @uiarc/donut-chart
yarn dlx shadcn@latest add @uiarc/donut-chart
bunx --bun shadcn@latest add @uiarc/donut-chart
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/donut-chart.json
```

#### Manual

1. Install the dependencies:

```bash
npm install motion
```

2. Copy the source into your project. Main file: `registry/components/donut-chart/donut-chart.tsx`

   The source is in the registry item: https://uiarc.dev/r/donut-chart.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { DonutChart } from "@/components/arc/donut-chart/donut-chart";

export function TrafficSources() {
  return (
    <DonutChart
      label="Visits by source"
      unit="visits"
      data={[
        { key: "search", label: "Search", value: 4210 },
        { key: "direct", label: "Direct", value: 2380 },
        { key: "social", label: "Social", value: 1190 },
        { key: "email", label: "Email", value: 640 },
        { key: "ads", label: "Ads", value: 120 },
        { key: "other", label: "Referral", value: 90 },
      ]}
    />
  );
}
```

### API reference

#### DonutChart

A donut chart with a synced legend that shows and hides segments, a rolling center readout, automatic Other grouping, and arcs that morph between datasets.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `data` (required) | `DonutChartDatum[]` | – | Parts: { key, label, value, color? }. Values of zero or less are left out. |
| `label` (required) | `string` | – | What the whole is, such as "Visits by source". Names the chart for assistive technology. |
| `unit` | `string` | `""` | Unit after values, such as "visits". Shown under the total at rest. |
| `formatValue` | `(value: number) => string` | `grouped number` | Formats values in the center, legend, and table. |
| `totalLabel` | `string` | `"Total"` | Center label at rest, above the total. |
| `size` | `number` | `208` | Diameter in pixels. The chart scales down to fit narrower containers. |
| `thickness` | `number` | `24` | Ring thickness in pixels. |
| `groupBelow` | `number` | `0.04` | Parts below this share of the total join Other, when at least two would. |
| `maxSegments` | `number` | `6` | The most segments drawn, counting Other. The smallest parts beyond it are grouped. |
| `otherLabel` | `string` | `"Other"` | Label of the grouped segment. |
| `activeKey` | `string \| null` | – | Controlled selected segment key. Hover and focus preview other segments without changing it. |
| `defaultActiveKey` | `string \| null` | `null` | Selected segment on first render when uncontrolled. |
| `onActiveChange` | `(key: string \| null) => void` | – | Called when a segment is pinned or unpinned by clicking the ring, or a legend row when legendAction is select. |
| `hiddenKeys` | `string[]` | – | Controlled hidden segment keys. A hidden segment closes and the rest of the ring redistributes. |
| `defaultHiddenKeys` | `string[]` | `[]` | Hidden segments on first render when uncontrolled. |
| `onHiddenKeysChange` | `(keys: string[]) => void` | – | Called when a legend row shows or hides its segment. |
| `legendAction` | `"toggle" \| "select"` | `"toggle"` | What clicking a legend row does: show or hide its segment, or pin it as the selected segment. |
| `legend` | `boolean` | `true` | The synced legend beside or below the ring. |
| `emptyLabel` | `string` | `"No data yet"` | Center text when the total is zero. |
| `ref` | `Ref<HTMLElement>` | – | The figure element. |
| `className` | `string` | – | Class on the figure. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| ArrowDown / ArrowRight | Moves to the next legend row, looping at the end. |
| ArrowUp / ArrowLeft | Moves to the previous legend row. |
| Home / End | Jumps to the first or last row. |
| Enter / Space | Shows or hides the focused segment; with legendAction select, pins or unpins it. |
| Escape | Clears the pinned segment. |
| Arrow keys on the ring | Without a legend the ring takes focus: arrows walk the segments, Enter pins one, and each is announced. |

### Accessibility

- The legend is the keyboard path: each row is a button with aria-pressed (shown, or pinned with legendAction select) and a label giving value, share, and grouped members.
- Showing or hiding a segment is announced in a polite live region with the new total. Without a legend the ring is focusable and announces each segment as the arrows reach it.
- The ring and center readout are aria-hidden; a hidden summary and table list every part, including the members of Other.
- Keyboard focus previews a segment in the ring; hover previews with a mouse only. Pointer focus draws no ring; keyboard focus shows Arc's shared focus ring.

### Motion

- One sweep the first time the chart scrolls into view: every segment leaves the top together and each trailing edge follows a beat behind the one before.
- New data and hidden segments morph start and end angles, never paths, from wherever each arc is on screen. Springs keep their velocity, so an interrupted change continues smoothly. Segments keep their order and never remount mid-morph.
- The active segment slides out along its middle and thickens slightly while the others dim. One pointer handler hit-tests the angle, so crossing a gap never drops the hover.
- The center readout rolls like a drum toward the active segment with tabular numbers in a fixed cell; totals and shares count to new values.
- Reduced motion jumps arcs, lifts, and text to their final state.

### Responsive behavior

- The figure is a container: at 460px and wider the legend sits beside the ring, below that it stacks under it.
- The ring scales down from size to fit narrower containers while keeping its aspect ratio.
- Legend hover styles only apply on hover-capable fine pointers; taps pin a segment.

### Performance

- Arc angles and lifts are motion values; one batched paint per frame writes every path d and transform straight to the DOM, with no React render per frame.
- Counting numbers write their text directly; center readouts stay mounted, so hovering never mounts or unmounts nodes.

### Notes for AI

- Use for two to six parts of one whole. With more parts, lean on groupBelow and maxSegments or use bar-chart.
- Keep keys stable between datasets so arcs morph in place.
- Leave color out to get the shared --series-1 to --series-4 palette in data order, then neutral steps; a key keeps its color across datasets. Pass colors only when they carry meaning.
- Legend rows show and hide segments by default; set legendAction to select for the older pin behavior.
- Drive activeKey from a table or filter to highlight the same category elsewhere.

### Related

- [Bar chart](https://uiarc.dev/components/bar-chart/markdown): Compare one measure across days and scrub any bar for its value.
- [Line chart](https://uiarc.dev/components/line-chart/markdown): A multi-series line chart with a gliding crosshair, legend toggles, and paths that morph between ranges.
- [Gauge](https://uiarc.dev/components/gauge/markdown): Show a value against a known range.
- [Usage meter](https://uiarc.dev/components/usage-meter/markdown): Show what fills an allowance and how close it is to the limit.

### Also in charts

- [Streamgraph](https://uiarc.dev/components/streamgraph/markdown): Layered streams on a wiggle baseline that morph between ranges, with a layer you can isolate and read week by week.
- [Brush chart](https://uiarc.dev/components/brush-chart/markdown): A dense time series with an overview strip: drag a window to zoom, resize it by its handles, and read events in place.
- [Waffle chart](https://uiarc.dev/components/waffle-chart/markdown): A ten by ten unit chart where every cell is one percent, and cells fly to their new group when the data changes.
- [Slope chart](https://uiarc.dev/components/slope-chart/markdown): Before and after on two axes: lines draw in, rank moves sit beside each value, and switching datasets slides every line to its new slope.
- [Sparkline](https://uiarc.dev/components/sparkline/markdown): Show a compact trend beside a value.
- [Activity heatmap](https://uiarc.dev/components/activity-heatmap/markdown): See a year of activity at a glance, one square per day.
- [Animated counter](https://uiarc.dev/components/animated-counter/markdown): Give changing totals a clear sense of movement.
- [Ridgeline](https://uiarc.dev/components/ridgeline/markdown): Overlapping distributions, one ridge per group: hover to lift a ridge and read its quartiles, switch datasets and every curve morphs.
- [Treemap](https://uiarc.dev/components/treemap/markdown): A squarified treemap: click to drill and the tiles grow to fill the view, with a breadcrumb back and metrics that morph every tile.
- [Split bar](https://uiarc.dev/components/split-bar/markdown): A single 100% bar split into shares: rest on a segment to widen it and read its exact figures, toggle segments from the legend and the rest reflow, with labels inside when they fit and on leader lines when they don't.

### Guidance for AI tools

Donut chart: A donut whose arcs morph between datasets, with the active value rolling into the center. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Streamgraph

> Layered streams on a wiggle baseline that morph between ranges, with a layer you can isolate and read week by week.

- Type: Component (data)
- Access: Free, open source
- Page: https://uiarc.dev/components/streamgraph
- Markdown: https://uiarc.dev/components/streamgraph/markdown
- Registry item: https://uiarc.dev/r/streamgraph.json
- Source file: `registry/components/streamgraph/streamgraph.tsx`
- Dependencies: motion
- Keywords: data, chart, new, streamgraph, stream graph react, stacked area chart, wiggle chart, theme river, stacked stream chart, layered area chart, animated streamgraph

### When to use

- Showing the changing share of topics, channels, or genres week by week.
- Storytelling dashboards where the shape of seasonality and spikes is the point.
- Comparing ranges where a morph between them explains what changed.

### When not to use

- Use line-chart when exact values or comparisons between series matter.
- Use bar-chart for a few periods or categories.
- Avoid it for data with negative values; streams stack magnitudes.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/streamgraph
pnpm dlx shadcn@latest add @uiarc/streamgraph
yarn dlx shadcn@latest add @uiarc/streamgraph
bunx --bun shadcn@latest add @uiarc/streamgraph
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/streamgraph.json
```

#### Manual

1. Install the dependencies:

```bash
npm install motion
```

2. Copy the source into your project. Main file: `registry/components/streamgraph/streamgraph.tsx`

   The source is in the registry item: https://uiarc.dev/r/streamgraph.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { Streamgraph } from "@/components/arc/streamgraph/streamgraph";

const series = [{ key: "bugs", label: "Bugs" }, { key: "billing", label: "Billing" }, { key: "onboarding", label: "Onboarding" }];
const data = weeks.map(week => ({ key: week.iso, label: `Week of ${week.name}`, axisLabel: week.monthStart ? week.month : undefined, values: week.tickets }));

export function TicketsByTopic() {
  return <Streamgraph data={data} series={series} label="Support tickets by topic" unit="tickets" categoryLabel="Week" />;
}
```

### API reference

#### Streamgraph

Layers stacked on a wiggle baseline that flow over time. Switching ranges morphs every layer; hovering one isolates it and reads every layer at that point.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `data` (required) | `{ key: string; label: string; axisLabel?: string; values: Record<string, number \| undefined> }[]` | – | Points in time. Datasets of any length morph into each other. |
| `series` (required) | `{ key: string; label: string; color?: string }[]` | – | Layers from the centre out: the first runs through the middle and the rest alternate above and below it. |
| `label` (required) | `string` | – | Names the chart for assistive technology. |
| `unit` | `string` | `""` | Unit after each value. |
| `height` | `number` | `260` | Plot height in pixels. |
| `offset` | `"wiggle" \| "silhouette" \| "zero"` | `"wiggle"` | Wiggle minimises layer slopes, silhouette centres the stack, zero stacks from a flat baseline. |
| `formatValue` | `(value: number, series) => string` | – | Formats values in the tooltip and table. |
| `hiddenSeries` | `string[]` | – | Controlled hidden layers. A hidden layer thins to nothing and the rest reflow. |
| `defaultHiddenSeries` | `string[]` | – | Initial hidden layers when uncontrolled. |
| `onHiddenSeriesChange` | `(hidden: string[]) => void` | – | Called when a legend toggle is pressed. |
| `onActiveChange` | `(index: number \| null, seriesKey: string \| null) => void` | – | Called as the reading moves between points and layers. |
| `legend` | `boolean` | `true` | Layer toggles above the plot. |
| `directLabels` | `boolean` | `true` | Names each layer at its thickest stretch when the text fits. |
| `categoryLabel` | `string` | `"Date"` | Header of the first column in the screen reader table. |
| `emptyLabel` | `string` | `"No data for this range"` | Shown when there are no points. |
| `className` | `string` | – | Extra class on the figure. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Tab | Focuses the plot and reads the latest point. |
| ArrowLeft / ArrowRight | Moves through time. |
| ArrowUp / ArrowDown | Moves the isolated layer up or down the stack. |
| PageUp / PageDown / Home / End | Jumps by a sixth of the range, or to the first or last point. |
| Escape | Clears the reading. |

### Accessibility

- The plot is a focusable group; each reading is announced with the point, the isolated layer's value, and the total.
- Legend toggles are buttons with aria-pressed; hovering or focusing one isolates its layer.
- A visually hidden table lists every point and layer value.
- Layers are separated by a 2px surface gap and named in place, so identity never rests on shade alone.

### Motion

- The stream swells out of a hairline along its centre the first time it is seen.
- New data blends every layer on a shared grid, so ranges of different lengths morph without redrawing.
- Hidden layers thin to nothing while the rest reflow; the crosshair and tooltip glide on springs.
- Reduced motion jumps to the final shapes and keeps the crosshair and tooltip without travel.

### Responsive behavior

- The plot fills its container; axis labels thin out to one per 72px, counted back from the latest.
- Direct labels hide where a layer is too thin or the plot too narrow; the tooltip and legend still name it.
- Touch drags scrub through time with pointer capture while vertical page scroll stays free.

### Performance

- Each layer is resampled once per data change onto 161 points; paint recomputes the baseline and writes paths directly.
- Hover state re-renders only the tooltip and a few attributes; morphs never re-render React per frame.

### Notes for AI

- Choose it for how a mix changes over time when the overall rhythm matters more than exact totals.
- Put the most important layer first; it runs through the middle of the stream.
- Use offset="zero" when people need to read totals against a baseline, like a stacked area chart.
- Keep layers to about eight; fold the rest into Other.

### Related

- [Line chart](https://uiarc.dev/components/line-chart/markdown): A multi-series line chart with a gliding crosshair, legend toggles, and paths that morph between ranges.
- [Brush chart](https://uiarc.dev/components/brush-chart/markdown): A dense time series with an overview strip: drag a window to zoom, resize it by its handles, and read events in place.
- [Bar chart](https://uiarc.dev/components/bar-chart/markdown): Compare one measure across days and scrub any bar for its value.
- [Sankey flow](https://uiarc.dev/components/sankey-flow/markdown): Flows between stages as ribbons with drifting particles; hover any node or ribbon to pour its share through the whole journey.

### Also in charts

- [Donut chart](https://uiarc.dev/components/donut-chart/markdown): A donut whose arcs morph between datasets, with the active value rolling into the center.
- [Waffle chart](https://uiarc.dev/components/waffle-chart/markdown): A ten by ten unit chart where every cell is one percent, and cells fly to their new group when the data changes.
- [Slope chart](https://uiarc.dev/components/slope-chart/markdown): Before and after on two axes: lines draw in, rank moves sit beside each value, and switching datasets slides every line to its new slope.
- [Sparkline](https://uiarc.dev/components/sparkline/markdown): Show a compact trend beside a value.
- [Gauge](https://uiarc.dev/components/gauge/markdown): Show a value against a known range.
- [Activity heatmap](https://uiarc.dev/components/activity-heatmap/markdown): See a year of activity at a glance, one square per day.
- [Animated counter](https://uiarc.dev/components/animated-counter/markdown): Give changing totals a clear sense of movement.
- [Ridgeline](https://uiarc.dev/components/ridgeline/markdown): Overlapping distributions, one ridge per group: hover to lift a ridge and read its quartiles, switch datasets and every curve morphs.
- [Treemap](https://uiarc.dev/components/treemap/markdown): A squarified treemap: click to drill and the tiles grow to fill the view, with a breadcrumb back and metrics that morph every tile.
- [Split bar](https://uiarc.dev/components/split-bar/markdown): A single 100% bar split into shares: rest on a segment to widen it and read its exact figures, toggle segments from the legend and the rest reflow, with labels inside when they fit and on leader lines when they don't.

### Guidance for AI tools

Streamgraph: Layered streams on a wiggle baseline that morph between ranges, with a layer you can isolate and read week by week. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Brush chart

> A dense time series with an overview strip: drag a window to zoom, resize it by its handles, and read events in place.

- Type: Component (data)
- Access: Free, open source
- Page: https://uiarc.dev/components/brush-chart
- Markdown: https://uiarc.dev/components/brush-chart/markdown
- Registry item: https://uiarc.dev/r/brush-chart.json
- Source file: `registry/components/brush-chart/brush-chart.tsx`
- Dependencies: motion
- Keywords: data, chart, new, brush chart, zoomable time series, chart with overview, range selector chart, focus and context chart, stock chart brush, d3 brush react, annotated line chart

### When to use

- Product analytics with a year or more of daily data.
- Incident reviews where events need to be read against a metric.
- Any chart where people ask to zoom into a stretch without losing context.

### When not to use

- Use line-chart for a few weeks of data or several series.
- Use sparkline for a small inline trend without interaction.
- Avoid it for data that dips below zero or needs a log scale.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/brush-chart
pnpm dlx shadcn@latest add @uiarc/brush-chart
yarn dlx shadcn@latest add @uiarc/brush-chart
bunx --bun shadcn@latest add @uiarc/brush-chart
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/brush-chart.json
```

#### Manual

1. Install the dependencies:

```bash
npm install motion
```

2. Copy the source into your project. Main file: `registry/components/brush-chart/brush-chart.tsx`

   The source is in the registry item: https://uiarc.dev/r/brush-chart.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { useState } from "react";
import { BrushChart } from "@/components/arc/brush-chart/brush-chart";

export function ActiveUsers({ days }: { days: { date: number; value: number }[] }) {
  const [range, setRange] = useState<[number, number]>([days[days.length - 90].date, days[days.length - 1].date]);
  return <BrushChart data={days} label="Daily active users" unit="users" range={range} onRangeChange={setRange}
    annotations={[{ date: Date.UTC(2026, 2, 24), label: "v2", description: "Offline mode and shared spaces" }]} />;
}
```

### API reference

#### BrushChart

A detailed time series with an overview strip. Drag the window to pan, its handles to resize, or across empty track to draw a new one; double click resets. Zoomed out, a seven point average and band replace the raw line.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `data` (required) | `{ date: Date \| number; value: number }[]` | – | Points in ascending time order. |
| `label` (required) | `string` | – | Names the chart for assistive technology. |
| `unit` | `string` | `""` | Unit after values in the tooltip and table. |
| `formatValue` | `(value: number) => string` | – | Formats values in the tooltip and table. |
| `formatTick` | `(value: number) => string` | – | Formats the value axis. Defaults to a compact number. |
| `formatDate` | `(date: Date) => string` | – | Formats dates in the tooltip and announcements. |
| `annotations` | `{ date: Date \| number; label: string; description?: string }[]` | `[]` | Events drawn as markers on both charts; labels show where they fit. |
| `range` | `[number, number]` | – | Controlled window as epoch milliseconds. A new value glides the window there. |
| `defaultRange` | `[number, number]` | – | Initial window when uncontrolled. Defaults to the whole series. |
| `onRangeChange` | `(range: [number, number]) => void` | – | Called while the window is dragged, resized, stepped, or reset. |
| `minSpan` | `number` | `7 days` | Smallest window in milliseconds. |
| `height` | `number` | `240` | Main plot height in pixels. |
| `overviewHeight` | `number` | `52` | Overview strip height in pixels. |
| `emptyLabel` | `string` | `"No data yet"` | Shown with fewer than two points. |
| `className` | `string` | – | Extra class on the figure. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| ArrowLeft / ArrowRight (plot) | Moves the crosshair between points in view. |
| ArrowLeft / ArrowRight (window) | Pans by a tenth of the window; Shift or PageUp and PageDown pan by half. |
| + / - (window) | Zooms in or out around the window's centre. |
| ArrowLeft / ArrowRight (handles) | Moves that edge by one point; Shift moves by ten. |
| Home / End | Moves the window or edge to the start or end. |
| Escape / 0 | Resets the window to the whole series. |

### Accessibility

- The window and both handles are sliders with dates as aria-valuetext.
- The plot is a focusable group; each reading is announced with its date, value, and any event on that day.
- A visually hidden table lists every point in the window with its event.
- Event markers pair the second series hue with a text label or tooltip; they never rely on color alone.

### Motion

- The line draws in from the left once, the first time it is seen.
- Dragging tracks the pointer 1:1; presets, resets, and controlled changes glide the window on a spring.
- The value axis springs to the tallest point in view, and the raw line crossfades with the smoothed trend as density changes.
- Reduced motion places the window directly and keeps the crosshair without travel.

### Responsive behavior

- Both charts fill their container; date ticks pick days, weeks, months, or years to fit the width.
- Handles have a 28 by 44px hit area for touch, and the strip keeps vertical page scroll free.
- Event labels are placed left to right and skip themselves when they would collide.

### Performance

- Past two points per pixel, each pixel column keeps only its low and high, so spikes survive and paths stay small.
- The overview path is built once per width; the rolling average is computed once per data change.
- Window moves re-render one component; a few thousand points stay smooth.

### Notes for AI

- Choose it for long daily or hourly series where people need both the whole history and a close look.
- Control range to sync presets (30D, 90D, 1Y) or other charts with the window.
- Use annotations for launches, incidents, and pricing changes; keep labels to a word or two.
- The value axis starts at zero, so it suits counts and totals rather than prices that hover far from zero.

### Related

- [Line chart](https://uiarc.dev/components/line-chart/markdown): A multi-series line chart with a gliding crosshair, legend toggles, and paths that morph between ranges.
- [Streamgraph](https://uiarc.dev/components/streamgraph/markdown): Layered streams on a wiggle baseline that morph between ranges, with a layer you can isolate and read week by week.
- [Sparkline](https://uiarc.dev/components/sparkline/markdown): Show a compact trend beside a value.
- [Date range picker](https://uiarc.dev/components/date-range-picker/markdown): A range picker that grows from its trigger into two months with presets and a stretching range highlight.

### Also in charts

- [Bar chart](https://uiarc.dev/components/bar-chart/markdown): Compare one measure across days and scrub any bar for its value.
- [Donut chart](https://uiarc.dev/components/donut-chart/markdown): A donut whose arcs morph between datasets, with the active value rolling into the center.
- [Waffle chart](https://uiarc.dev/components/waffle-chart/markdown): A ten by ten unit chart where every cell is one percent, and cells fly to their new group when the data changes.
- [Slope chart](https://uiarc.dev/components/slope-chart/markdown): Before and after on two axes: lines draw in, rank moves sit beside each value, and switching datasets slides every line to its new slope.
- [Gauge](https://uiarc.dev/components/gauge/markdown): Show a value against a known range.
- [Activity heatmap](https://uiarc.dev/components/activity-heatmap/markdown): See a year of activity at a glance, one square per day.
- [Animated counter](https://uiarc.dev/components/animated-counter/markdown): Give changing totals a clear sense of movement.
- [Ridgeline](https://uiarc.dev/components/ridgeline/markdown): Overlapping distributions, one ridge per group: hover to lift a ridge and read its quartiles, switch datasets and every curve morphs.
- [Treemap](https://uiarc.dev/components/treemap/markdown): A squarified treemap: click to drill and the tiles grow to fill the view, with a breadcrumb back and metrics that morph every tile.
- [Split bar](https://uiarc.dev/components/split-bar/markdown): A single 100% bar split into shares: rest on a segment to widen it and read its exact figures, toggle segments from the legend and the rest reflow, with labels inside when they fit and on leader lines when they don't.

### Guidance for AI tools

Brush chart: A dense time series with an overview strip: drag a window to zoom, resize it by its handles, and read events in place. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Waffle chart

> A ten by ten unit chart where every cell is one percent, and cells fly to their new group when the data changes.

- Type: Component (data)
- Access: Free, open source
- Page: https://uiarc.dev/components/waffle-chart
- Markdown: https://uiarc.dev/components/waffle-chart/markdown
- Registry item: https://uiarc.dev/r/waffle-chart.json
- Source file: `registry/components/waffle-chart/waffle-chart.tsx`
- Dependencies: motion
- Keywords: data, chart, new, waffle chart, unit chart, square pie chart, percentage grid, part to whole chart, react waffle chart, animated waffle, isotype chart

### When to use

- Showing shares of one whole where people should be able to count units.
- Comparing the same categories across a few datasets, such as countries or years.
- Replacing a pie or donut when small shares need to stay visible.

### When not to use

- Use line-chart or streamgraph for how shares change over time.
- Use bar-chart when exact comparison of many categories matters more than the whole.
- Use sunburst for nested parts of a whole.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/waffle-chart
pnpm dlx shadcn@latest add @uiarc/waffle-chart
yarn dlx shadcn@latest add @uiarc/waffle-chart
bunx --bun shadcn@latest add @uiarc/waffle-chart
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/waffle-chart.json
```

#### Manual

1. Install the dependencies:

```bash
npm install motion
```

2. Copy the source into your project. Main file: `registry/components/waffle-chart/waffle-chart.tsx`

   The source is in the registry item: https://uiarc.dev/r/waffle-chart.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { WaffleChart } from "@/components/arc/waffle-chart/waffle-chart";

const mix = [
  { key: "wind-solar", label: "Wind and solar", value: 218 },
  { key: "hydro", label: "Hydro", value: 20 },
  { key: "gas", label: "Gas", value: 76 },
  { key: "coal", label: "Coal", value: 132 },
  { key: "other", label: "Other", value: 61 },
];

export function PowerMix() {
  return <WaffleChart data={mix} label="Electricity generation, 2023" unit="TWh" />;
}
```

### API reference

#### WaffleChart

A unit chart where every cell is one share of the whole. When the data changes, cells keep following their category and fly to their new block with a staggered spring, and the shares in the legend roll to their new values.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `data` (required) | `WaffleCategory[]` | – | Categories in fill order: { key, label, value, color? }. The first fills from the bottom-left corner, column by column. Shares come from the total. |
| `label` (required) | `string` | – | What the whole is, such as "Electricity generation, 2023". Names the chart, the summary, and the table. |
| `unit` | `string` | `""` | Unit after raw values in the tooltip and table, such as "TWh". |
| `formatValue` | `(value: number, category: WaffleCategory) => string` | – | Formats raw values. Shares are always percentages. |
| `rows` | `number` | `10` | Grid rows. rows × columns cells make the whole. |
| `columns` | `number` | `10` | Grid columns. 10 × 10 means one cell per percent. |
| `accentKey` | `string \| null` | `first key` | The category painted in the first series hue, derived from the accent. The next three take the supporting series and later ones fall back to neutral steps. |
| `activeKey` | `string \| null` | – | Controlled focused category. Other cells dim while one is focused. |
| `defaultActiveKey` | `string \| null` | `null` | Initial focused category when uncontrolled. |
| `onActiveChange` | `(key: string \| null) => void` | – | Called when a legend item is pinned or released. |
| `legend` | `boolean` | `true` | Category list with rolling shares. It sits beside the grid from 420px and below it on narrower containers. |
| `decimals` | `number` | `0` | Decimal places for shares. |
| `emptyLabel` | `string` | `"No data"` | Message when the data is empty or sums to zero. |
| `ref` | `Ref<HTMLElement>` | – | Forwarded to the figure. |
| `className` | `string` | – | Extra class on the figure. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Tab | Focuses the grid, then each legend item. |
| Arrow keys | Move the reading cell by cell across the grid. |
| PageUp / PageDown | Jump to the first cell of the previous or next category. |
| Home / End | Go to the first or last filled cell. |
| Escape | Clears the reading. |
| Enter / Space on a legend item | Pins or releases that category. |

### Accessibility

- The grid is a focusable group with a roledescription and instructions; cells are decorative and aria-hidden.
- A polite live region reads the category, share, and value under the keyboard cursor.
- A visually hidden summary and a table list every category with its value, share, and cell count.
- Legend items are toggle buttons with aria-pressed; identity never relies on colour alone because every category is named in the legend.

### Motion

- Cells are persistent: a data change keeps as many cells in place as possible and flies the rest to their new block, staggered by position so the grid refills like a wave.
- A travelling cell dips in scale mid-flight and changes colour with the same delay, so it reads as lifting out of one group and landing in another.
- Shares in the legend roll to their new values on a critically damped spring.
- The first time the chart is seen, cells pop in from the bottom-left corner.
- Reduced motion places cells and shares immediately and drops the dip, pop, and stagger.

### Responsive behavior

- The grid is square and fills up to 300px; the legend moves beside it from 420px of container width.
- Legend labels truncate with an ellipsis; the full name stays in the tooltip, the live region, and the table.
- Touch reads cells with a press and drag; the page still scrolls vertically.

### Performance

- One element per cell, 100 by default, animated with transforms only.
- Hover is resolved from pointer position arithmetic, not per-cell listeners.
- Grid size is measured with one ResizeObserver.

### Notes for AI

- Choose it for part-to-whole with four to eight categories where countable units help, such as energy mix, survey answers, or budget split.
- Keep categories in a meaningful order; the fill order is the reading order.
- Use accentKey for the category the story is about and leave the rest neutral.
- Switching datasets with the same keys is where it shines: cells travel instead of repainting.

### Related

- [Donut chart](https://uiarc.dev/components/donut-chart/markdown): A donut whose arcs morph between datasets, with the active value rolling into the center.
- [Sunburst](https://uiarc.dev/components/sunburst/markdown): A hierarchy in rings: click a segment and every arc swings around it as the new centre, with a breadcrumb back and a rolling total.
- [Bar chart](https://uiarc.dev/components/bar-chart/markdown): Compare one measure across days and scrub any bar for its value.
- [Usage meter](https://uiarc.dev/components/usage-meter/markdown): Show what fills an allowance and how close it is to the limit.
- [Funnel chart](https://uiarc.dev/components/funnel-chart/markdown): A tapered conversion funnel with drop-off at every step, a device split that morphs the band, and dots that stream through it.

### Also in charts

- [Line chart](https://uiarc.dev/components/line-chart/markdown): A multi-series line chart with a gliding crosshair, legend toggles, and paths that morph between ranges.
- [Streamgraph](https://uiarc.dev/components/streamgraph/markdown): Layered streams on a wiggle baseline that morph between ranges, with a layer you can isolate and read week by week.
- [Brush chart](https://uiarc.dev/components/brush-chart/markdown): A dense time series with an overview strip: drag a window to zoom, resize it by its handles, and read events in place.
- [Slope chart](https://uiarc.dev/components/slope-chart/markdown): Before and after on two axes: lines draw in, rank moves sit beside each value, and switching datasets slides every line to its new slope.
- [Sparkline](https://uiarc.dev/components/sparkline/markdown): Show a compact trend beside a value.
- [Gauge](https://uiarc.dev/components/gauge/markdown): Show a value against a known range.
- [Activity heatmap](https://uiarc.dev/components/activity-heatmap/markdown): See a year of activity at a glance, one square per day.
- [Animated counter](https://uiarc.dev/components/animated-counter/markdown): Give changing totals a clear sense of movement.
- [Ridgeline](https://uiarc.dev/components/ridgeline/markdown): Overlapping distributions, one ridge per group: hover to lift a ridge and read its quartiles, switch datasets and every curve morphs.
- [Treemap](https://uiarc.dev/components/treemap/markdown): A squarified treemap: click to drill and the tiles grow to fill the view, with a breadcrumb back and metrics that morph every tile.
- [Split bar](https://uiarc.dev/components/split-bar/markdown): A single 100% bar split into shares: rest on a segment to widen it and read its exact figures, toggle segments from the legend and the rest reflow, with labels inside when they fit and on leader lines when they don't.

### Guidance for AI tools

Waffle chart: A ten by ten unit chart where every cell is one percent, and cells fly to their new group when the data changes. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Slope chart

> Before and after on two axes: lines draw in, rank moves sit beside each value, and switching datasets slides every line to its new slope.

- Type: Component (data)
- Access: Free, open source
- Page: https://uiarc.dev/components/slope-chart
- Markdown: https://uiarc.dev/components/slope-chart/markdown
- Registry item: https://uiarc.dev/r/slope-chart.json
- Source file: `registry/components/slope-chart/slope-chart.tsx`
- Dependencies: motion
- Keywords: data, chart, new, slope chart, slopegraph, before after chart, react slope chart, rank change chart, two period comparison, bump chart, animated slope chart

### When to use

- Showing which items rose, which fell, and how the order changed between two periods.
- Replacing a grouped bar chart when the change is the story.

### When not to use

- Use line-chart for three or more moments.
- Use bar-chart when only the latest values matter.
- Avoid more than about ten items; labels start to crowd.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/slope-chart
pnpm dlx shadcn@latest add @uiarc/slope-chart
yarn dlx shadcn@latest add @uiarc/slope-chart
bunx --bun shadcn@latest add @uiarc/slope-chart
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/slope-chart.json
```

#### Manual

1. Install the dependencies:

```bash
npm install motion
```

2. Copy the source into your project. Main file: `registry/components/slope-chart/slope-chart.tsx`

   The source is in the registry item: https://uiarc.dev/r/slope-chart.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { SlopeChart } from "@/components/arc/slope-chart/slope-chart";

const channels = [
  { key: "email", label: "Email", start: 3.1, end: 4.6 },
  { key: "search", label: "Organic search", start: 3.4, end: 3.6 },
  { key: "social", label: "Paid social", start: 1.9, end: 1.3 },
];

export function Channels() {
  return <SlopeChart data={channels} label="Conversion by channel" startLabel="Q1" endLabel="Q2" highlightKey="email" formatValue={value => `${value.toFixed(1)}%`} />;
}
```

### API reference

#### SlopeChart

Before and after for several items on two shared axes. Lines draw in on first view, labels spread apart to avoid overlaps with a hairline back to their point, rank moves sit beside each end value, and switching datasets slides every line to its new slope.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `data` (required) | `SlopeItem[]` | – | Items: { key, label, start, end }. Keys keep lines stable across datasets. |
| `label` (required) | `string` | – | What is measured. Names the chart, the summary, and the table. |
| `startLabel` (required) | `string` | – | First column heading, such as "Q1". |
| `endLabel` (required) | `string` | – | Second column heading, such as "Q2". |
| `formatValue` | `(value: number) => string` | – | Formats values beside the points, in the tooltip, and in the table. |
| `formatChange` | `(change: number, item: SlopeItem) => string` | – | Formats the change in the tooltip, such as "+1.5 pts". |
| `height` | `number` | `44px per item` | Plot height in pixels. |
| `highlightKey` | `string \| null` | `null` | The item drawn in the first series hue, derived from the accent. |
| `activeKey` | `string \| null` | – | Controlled item in focus. The others fade. |
| `onActiveChange` | `(key: string \| null) => void` | – | Called as the item in focus changes. |
| `ranks` | `boolean` | `true` | Rank movement beside each end value. |
| `emptyLabel` | `string` | `"No data"` | Message when there are no items. |
| `ref` | `Ref<HTMLElement>` | – | Forwarded to the figure. |
| `className` | `string` | – | Extra class on the figure. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Tab | Focuses the chart and reads the top item by end value. |
| ArrowDown / ArrowRight | Next item in end order. |
| ArrowUp / ArrowLeft | Previous item. |
| Home / End | First or last item. |
| Escape | Clears the reading. |

### Accessibility

- The chart is a focusable group with a roledescription and instructions; lines and labels are aria-hidden.
- A polite live region reads both values, the change, and the rank move for the item in focus.
- A visually hidden summary and a table list every item in end order.
- Rank moves use an arrow glyph and a number, never colour alone.

### Motion

- On first view each line draws from start to end with a small stagger, and the end dots and labels arrive as it lands.
- Switching datasets moves lines, dots, labels, and leader hairlines on the shared morph spring; rank numbers roll in the direction they moved.
- The item in focus comes forward while the others fade; the tooltip glides to the middle of its line.
- Reduced motion shows every line drawn and moves it immediately.

### Responsive behavior

- Label columns narrow below 440px and names truncate with an ellipsis; the full name stays in the tooltip and table.
- Overlapping labels spread apart with a hairline to their point instead of colliding.
- Touch reads the nearest line with a press and drag.

### Performance

- SVG lines and HTML labels animated with springs; around ten items render in a few dozen nodes.
- One ResizeObserver measures the container.

### Notes for AI

- Choose it for exactly two moments and three to ten items: before and after a launch, quarter over quarter, last year against this year.
- Use highlightKey for the item the story is about.
- Give the columns short headings; names sit on the left only, values on both sides.
- For more than two moments use line-chart.

### Related

- [Line chart](https://uiarc.dev/components/line-chart/markdown): A multi-series line chart with a gliding crosshair, legend toggles, and paths that morph between ranges.
- [Bar chart](https://uiarc.dev/components/bar-chart/markdown): Compare one measure across days and scrub any bar for its value.
- [Radar chart](https://uiarc.dev/components/radar-chart/markdown): Two or three profiles on one web: shapes morph when you swap a profile, and a sweep across the axes compares values in place.
- [Streamgraph](https://uiarc.dev/components/streamgraph/markdown): Layered streams on a wiggle baseline that morph between ranges, with a layer you can isolate and read week by week.
- [Sortable data table](https://uiarc.dev/components/sortable-data-table/markdown): Compare structured records with sortable columns.

### Also in charts

- [Donut chart](https://uiarc.dev/components/donut-chart/markdown): A donut whose arcs morph between datasets, with the active value rolling into the center.
- [Brush chart](https://uiarc.dev/components/brush-chart/markdown): A dense time series with an overview strip: drag a window to zoom, resize it by its handles, and read events in place.
- [Waffle chart](https://uiarc.dev/components/waffle-chart/markdown): A ten by ten unit chart where every cell is one percent, and cells fly to their new group when the data changes.
- [Sparkline](https://uiarc.dev/components/sparkline/markdown): Show a compact trend beside a value.
- [Gauge](https://uiarc.dev/components/gauge/markdown): Show a value against a known range.
- [Activity heatmap](https://uiarc.dev/components/activity-heatmap/markdown): See a year of activity at a glance, one square per day.
- [Animated counter](https://uiarc.dev/components/animated-counter/markdown): Give changing totals a clear sense of movement.
- [Ridgeline](https://uiarc.dev/components/ridgeline/markdown): Overlapping distributions, one ridge per group: hover to lift a ridge and read its quartiles, switch datasets and every curve morphs.
- [Treemap](https://uiarc.dev/components/treemap/markdown): A squarified treemap: click to drill and the tiles grow to fill the view, with a breadcrumb back and metrics that morph every tile.
- [Split bar](https://uiarc.dev/components/split-bar/markdown): A single 100% bar split into shares: rest on a segment to widen it and read its exact figures, toggle segments from the legend and the rest reflow, with labels inside when they fit and on leader lines when they don't.

### Guidance for AI tools

Slope chart: Before and after on two axes: lines draw in, rank moves sit beside each value, and switching datasets slides every line to its new slope. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Sparkline

> Show a compact trend beside a value.

- Type: Component (data)
- Access: Free, open source
- Page: https://uiarc.dev/components/sparkline
- Markdown: https://uiarc.dev/components/sparkline/markdown
- Registry item: https://uiarc.dev/r/sparkline.json
- Source file: `registry/components/sparkline/sparkline.tsx`
- Dependencies: motion
- Keywords: data, chart, react sparkline, mini line chart, trend line, inline chart, scrubbable chart, svg sparkline

### When to use

- A compact trend inside a card, table row, or KPI tile.
- Small charts people can scrub by pointer or keyboard to read past values.

### When not to use

- Use bar-chart for comparing discrete periods with axes.
- Use stat-card or metric-card when only the latest value matters.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/sparkline
pnpm dlx shadcn@latest add @uiarc/sparkline
yarn dlx shadcn@latest add @uiarc/sparkline
bunx --bun shadcn@latest add @uiarc/sparkline
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/sparkline.json
```

#### Manual

1. Install the dependencies:

```bash
npm install motion
```

2. Copy the source into your project. Main file: `registry/components/sparkline/sparkline.tsx`

   The source is in the registry item: https://uiarc.dev/r/sparkline.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { Sparkline } from "@/components/arc/sparkline/sparkline";

export function Signups() {
  return (
    <Sparkline
      label="Signups"
      data={[12, 18, 15, 22, 30, 27, 34]}
      labels={["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"]}
      value="34"
      change="+26%"
      tone="success"
    />
  );
}
```

### API reference

#### Sparkline

A small line chart with a headline value that can be scrubbed by pointer or keyboard.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `data` (required) | `number[]` | – | Points in order, oldest first. |
| `label` (required) | `string` | – | What is measured. Names the chart. |
| `value` | `string` | – | Headline value at rest. While scrubbing it shows the point under the cursor. |
| `change` | `string` | – | Aside text at rest, such as "+4.1%". |
| `tone` | `"accent" \| "success" \| "warning" \| "danger"` | `"accent"` | Line and change color. |
| `width` | `number` | `160` | Drawing width in SVG units. |
| `height` | `number` | `52` | Drawing height in SVG units. |
| `labels` | `string[]` | – | One label per point, such as a date, shown while scrubbing. |
| `formatValue` | `(value: number, index: number) => string` | – | Formats a scrubbed point. Defaults to a grouped number. |
| `area` | `boolean` | `true` | Quiet fill under the line. |
| `interactive` | `boolean` | `true` | Enables pointer and keyboard scrubbing. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| ArrowLeft / ArrowRight | Moves the cursor one point back or forward (ArrowDown and ArrowUp too). |
| PageDown / PageUp | Moves about a sixth of the series. |
| Home / End | Jumps to the first or last point. |
| Escape | Stops scrubbing and returns to the latest value. |

### Accessibility

- The figure has an aria-label describing the series; the SVG is hidden.
- When interactive, the plot is a focusable role="slider" whose aria-valuetext reads the point label and value.
- Pass labels so scrubbed points read as dates rather than positions.

### Motion

- The line draws in on first view and the end dot appears as it lands.
- While scrubbing, the cursor springs between points, later points dim, and headline copy rolls.
- Reduced motion shows the full line at once and moves the cursor without springing.

### Responsive behavior

- The plot measures its width with a ResizeObserver and redraws to fill its container.
- Scrubbing uses touch-action pan-y, so a horizontal drag scrubs while vertical swipes still scroll the page.
- On touch the readout returns to the latest value when the finger lifts.

### Performance

- Each chart has its own ResizeObservers and an in-view draw; set interactive to false in dense tables to drop tab stops and handlers.

### Notes for AI

- Use for a compact trend inside a card or table row. Use bar-chart for comparing discrete periods with axes.
- Pass value as the formatted latest reading; formatValue should match it so scrubbed values look consistent.
- Set interactive to false in dense tables to avoid many tab stops.

### Related

- [Bar chart](https://uiarc.dev/components/bar-chart/markdown): Compare one measure across days and scrub any bar for its value.
- [Metric card](https://uiarc.dev/components/metric-card/markdown): A compact summary for a number that needs context.
- [Gauge](https://uiarc.dev/components/gauge/markdown): Show a value against a known range.

### Also in charts

- [Line chart](https://uiarc.dev/components/line-chart/markdown): A multi-series line chart with a gliding crosshair, legend toggles, and paths that morph between ranges.
- [Donut chart](https://uiarc.dev/components/donut-chart/markdown): A donut whose arcs morph between datasets, with the active value rolling into the center.
- [Streamgraph](https://uiarc.dev/components/streamgraph/markdown): Layered streams on a wiggle baseline that morph between ranges, with a layer you can isolate and read week by week.
- [Brush chart](https://uiarc.dev/components/brush-chart/markdown): A dense time series with an overview strip: drag a window to zoom, resize it by its handles, and read events in place.
- [Waffle chart](https://uiarc.dev/components/waffle-chart/markdown): A ten by ten unit chart where every cell is one percent, and cells fly to their new group when the data changes.
- [Slope chart](https://uiarc.dev/components/slope-chart/markdown): Before and after on two axes: lines draw in, rank moves sit beside each value, and switching datasets slides every line to its new slope.
- [Activity heatmap](https://uiarc.dev/components/activity-heatmap/markdown): See a year of activity at a glance, one square per day.
- [Animated counter](https://uiarc.dev/components/animated-counter/markdown): Give changing totals a clear sense of movement.
- [Ridgeline](https://uiarc.dev/components/ridgeline/markdown): Overlapping distributions, one ridge per group: hover to lift a ridge and read its quartiles, switch datasets and every curve morphs.
- [Treemap](https://uiarc.dev/components/treemap/markdown): A squarified treemap: click to drill and the tiles grow to fill the view, with a breadcrumb back and metrics that morph every tile.
- [Split bar](https://uiarc.dev/components/split-bar/markdown): A single 100% bar split into shares: rest on a segment to widen it and read its exact figures, toggle segments from the legend and the rest reflow, with labels inside when they fit and on leader lines when they don't.

### Guidance for AI tools

Sparkline: Show a compact trend beside a value. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Gauge

> Show a value against a known range.

- Type: Component (data)
- Access: Free, open source
- Page: https://uiarc.dev/components/gauge
- Markdown: https://uiarc.dev/components/gauge/markdown
- Registry item: https://uiarc.dev/r/gauge.json
- Source file: `registry/components/gauge/gauge.tsx`
- Dependencies: motion
- Keywords: data, chart, react gauge, gauge chart, radial meter, progress ring, threshold gauge, dashboard gauge

### When to use

- One value against a known range, such as disk quota or health score.
- Values with labelled bands, like Healthy, Filling up, and Critical.

### When not to use

- Use progress for task completion.
- Use usage-meter for plan limits and activity-rings for several goals at once.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/gauge
pnpm dlx shadcn@latest add @uiarc/gauge
yarn dlx shadcn@latest add @uiarc/gauge
bunx --bun shadcn@latest add @uiarc/gauge
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/gauge.json
```

#### Manual

1. Install the dependencies:

```bash
npm install motion
```

2. Copy the source into your project. Main file: `registry/components/gauge/gauge.tsx`

   The source is in the registry item: https://uiarc.dev/r/gauge.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { Gauge } from "@/components/arc/gauge/gauge";

export function DiskUsage() {
  return (
    <Gauge
      label="Disk usage"
      value={72}
      detail="360 of 500 GB"
      thresholds={[
        { from: 0, tone: "success", label: "Healthy" },
        { from: 70, tone: "warning", label: "Filling up" },
        { from: 90, tone: "danger", label: "Critical" },
      ]}
    />
  );
}
```

### API reference

#### Gauge

A 270 degree ring meter with a percent readout and optional labelled threshold bands.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` (required) | `number` | – | Current value within min and max. |
| `min` | `number` | `0` | Lower bound. |
| `max` | `number` | `100` | Upper bound. |
| `label` (required) | `string` | – | What is measured. |
| `detail` | `string` | – | Secondary caption line. |
| `tone` | `"accent" \| "success" \| "warning" \| "danger"` | `"accent"` | Ring color when no threshold applies. |
| `thresholds` | `{ from: number; tone: "accent" \| "success" \| "warning" \| "danger"; label: string }[]` | – | Bands by starting value. The highest band reached sets the tone and shows its label. |

### Accessibility

- The ring is role="meter" with aria-valuemin, aria-valuemax, aria-valuenow, and an aria-valuetext including the band label.
- Threshold labels name the state in text, so it never rests on color alone.
- The SVG and animated readout are aria-hidden.

### Motion

- The ring fills once when half in view without overshoot, then springs to new values while the percent counts.
- The band color and label change exactly as the count crosses a threshold.
- Reduced motion lands on the value at once.

### Responsive behavior

- The ring is min(100%, 176px) wide and keeps its aspect ratio, so it shrinks in narrow columns.

### Performance

- It fills once when half in view, then springs to new values; it is one SVG arc with no running loop.

### Notes for AI

- Use for one value against a known range, such as quota or health. Use progress for task completion and usage-meter for plan limits.
- Always add thresholds with labels when tone carries meaning.

### Related

- [Progress](https://uiarc.dev/components/progress/markdown): Show how much of a known task is complete.
- [Usage meter](https://uiarc.dev/components/usage-meter/markdown): Show what fills an allowance and how close it is to the limit.
- [Activity rings](https://uiarc.dev/components/activity-rings/markdown): Daily goals as tick rings that sweep, count up, and trace a second lap past 100%.

### Also in charts

- [Line chart](https://uiarc.dev/components/line-chart/markdown): A multi-series line chart with a gliding crosshair, legend toggles, and paths that morph between ranges.
- [Bar chart](https://uiarc.dev/components/bar-chart/markdown): Compare one measure across days and scrub any bar for its value.
- [Donut chart](https://uiarc.dev/components/donut-chart/markdown): A donut whose arcs morph between datasets, with the active value rolling into the center.
- [Streamgraph](https://uiarc.dev/components/streamgraph/markdown): Layered streams on a wiggle baseline that morph between ranges, with a layer you can isolate and read week by week.
- [Brush chart](https://uiarc.dev/components/brush-chart/markdown): A dense time series with an overview strip: drag a window to zoom, resize it by its handles, and read events in place.
- [Waffle chart](https://uiarc.dev/components/waffle-chart/markdown): A ten by ten unit chart where every cell is one percent, and cells fly to their new group when the data changes.
- [Slope chart](https://uiarc.dev/components/slope-chart/markdown): Before and after on two axes: lines draw in, rank moves sit beside each value, and switching datasets slides every line to its new slope.
- [Sparkline](https://uiarc.dev/components/sparkline/markdown): Show a compact trend beside a value.
- [Activity heatmap](https://uiarc.dev/components/activity-heatmap/markdown): See a year of activity at a glance, one square per day.
- [Animated counter](https://uiarc.dev/components/animated-counter/markdown): Give changing totals a clear sense of movement.
- [Ridgeline](https://uiarc.dev/components/ridgeline/markdown): Overlapping distributions, one ridge per group: hover to lift a ridge and read its quartiles, switch datasets and every curve morphs.
- [Treemap](https://uiarc.dev/components/treemap/markdown): A squarified treemap: click to drill and the tiles grow to fill the view, with a breadcrumb back and metrics that morph every tile.
- [Split bar](https://uiarc.dev/components/split-bar/markdown): A single 100% bar split into shares: rest on a segment to widen it and read its exact figures, toggle segments from the legend and the rest reflow, with labels inside when they fit and on leader lines when they don't.

### Guidance for AI tools

Gauge: Show a value against a known range. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Activity heatmap

> See a year of activity at a glance, one square per day.

- Type: Component (data)
- Access: Free, open source
- Page: https://uiarc.dev/components/activity-heatmap
- Markdown: https://uiarc.dev/components/activity-heatmap/markdown
- Registry item: https://uiarc.dev/r/activity-heatmap.json
- Source file: `registry/components/activity-heatmap/activity-heatmap.tsx`
- Dependencies: motion
- Keywords: data, chart, calendar, react activity heatmap, contribution graph, github calendar heatmap, calendar heatmap, streak chart, activity calendar

### When to use

- Daily rhythm over a long range, like contributions or workouts.
- Views where streaks and quiet weeks matter more than exact comparison.

### When not to use

- Use bar-chart when the exact comparison is the point.
- Use calendar to pick dates.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/activity-heatmap
pnpm dlx shadcn@latest add @uiarc/activity-heatmap
yarn dlx shadcn@latest add @uiarc/activity-heatmap
bunx --bun shadcn@latest add @uiarc/activity-heatmap
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/activity-heatmap.json
```

#### Manual

1. Install the dependencies:

```bash
npm install motion
```

2. Copy the source into your project. Main file: `registry/components/activity-heatmap/activity-heatmap.tsx`

   The source is in the registry item: https://uiarc.dev/r/activity-heatmap.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { useState } from "react";
import { ActivityHeatmap } from "@/components/arc/activity-heatmap/activity-heatmap";

export function Contributions({ days }: { days: { date: string; count: number }[] }) {
  const [selected, setSelected] = useState<string | null>(null);
  return (
    <ActivityHeatmap days={days} label="Contributions in 2026" period="2026" selectedDate={selected} onSelectDate={setSelected} />
  );
}
```

### API reference

#### ActivityHeatmap

A contribution style calendar with one tinted square per day and a hover or focus tooltip.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `days` (required) | `{ date: string; count: number }[]` | – | One entry per day as YYYY-MM-DD, oldest first. Missing days count as zero. |
| `label` (required) | `string` | – | Accessible name for the grid, such as "Contributions in 2025". |
| `period` (required) | `string` | – | Finishes the summary: "1,284 contributions in {period}". |
| `unit` | `{ one: string; other: string }` | `{ one: "contribution", other: "contributions" }` | Nouns for the count. |
| `thresholds` | `[number, number, number]` | – | Upper bounds for levels one to three. Defaults to quarters of the busiest day. |
| `weekStartsOn` | `0 \| 1` | `0` | Sunday or Monday as the first row. |
| `selectedDate` | `string \| null` | `null` | Day drawn with a selection ring. |
| `onSelectDate` | `(date: string) => void` | – | Called on click, Enter, or Space. |
| `actions` | `ReactNode` | – | Controls beside the summary, such as a range switch. |
| `locale` | `string` | `"en-US"` | Formatting locale. |
| `className` | `string` | – | Class for the root. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| ArrowUp / ArrowDown | Moves one day back or forward. |
| ArrowLeft / ArrowRight | Moves one week back or forward. |
| Home / End | Jumps to the first or last day. |
| Enter / Space | Selects the focused day. |
| Escape | Hides the tooltip. |

### Accessibility

- The grid is role="grid" with labelled gridcells and a hidden legend explaining the levels.
- Legend swatches are toggle buttons with aria-pressed that highlight days of one level.
- The total and hovered day are announced through status and polite live regions; the tooltip itself is aria-hidden.

### Motion

- Cells wave in once on view and a new range recolors the grid in a sweep.
- The tooltip glides between cells and its text rolls; the total counts to new values.
- Reduced motion drops the wave, sweep, and glide in favor of short fades.

### Responsive behavior

- Cells scale between 9px and 15px with the container, then the grid scrolls horizontally from the newest week.
- Below a 440px container the caption switches to a short form.
- On touch the tooltip lingers after a tap instead of hiding at once.

### Performance

- Every day is its own cell, so a year is about 370 elements; the reveal wave is capped in total time.
- One shared tooltip serves the whole grid.

### Notes for AI

- Use when rhythm, streaks, and quiet weeks matter more than exact comparison. Use bar-chart when the exact comparison is the point.
- Pass a range switch through actions and swap days to change the period.

### Related

- [Bar chart](https://uiarc.dev/components/bar-chart/markdown): Compare one measure across days and scrub any bar for its value.
- [Calendar](https://uiarc.dev/components/calendar/markdown): Browse dates in a clear, compact month view.
- [Activity rings](https://uiarc.dev/components/activity-rings/markdown): Daily goals as tick rings that sweep, count up, and trace a second lap past 100%.
- [Sparkline](https://uiarc.dev/components/sparkline/markdown): Show a compact trend beside a value.

### Also in charts

- [Line chart](https://uiarc.dev/components/line-chart/markdown): A multi-series line chart with a gliding crosshair, legend toggles, and paths that morph between ranges.
- [Donut chart](https://uiarc.dev/components/donut-chart/markdown): A donut whose arcs morph between datasets, with the active value rolling into the center.
- [Streamgraph](https://uiarc.dev/components/streamgraph/markdown): Layered streams on a wiggle baseline that morph between ranges, with a layer you can isolate and read week by week.
- [Brush chart](https://uiarc.dev/components/brush-chart/markdown): A dense time series with an overview strip: drag a window to zoom, resize it by its handles, and read events in place.
- [Waffle chart](https://uiarc.dev/components/waffle-chart/markdown): A ten by ten unit chart where every cell is one percent, and cells fly to their new group when the data changes.
- [Slope chart](https://uiarc.dev/components/slope-chart/markdown): Before and after on two axes: lines draw in, rank moves sit beside each value, and switching datasets slides every line to its new slope.
- [Gauge](https://uiarc.dev/components/gauge/markdown): Show a value against a known range.
- [Animated counter](https://uiarc.dev/components/animated-counter/markdown): Give changing totals a clear sense of movement.
- [Ridgeline](https://uiarc.dev/components/ridgeline/markdown): Overlapping distributions, one ridge per group: hover to lift a ridge and read its quartiles, switch datasets and every curve morphs.
- [Treemap](https://uiarc.dev/components/treemap/markdown): A squarified treemap: click to drill and the tiles grow to fill the view, with a breadcrumb back and metrics that morph every tile.
- [Split bar](https://uiarc.dev/components/split-bar/markdown): A single 100% bar split into shares: rest on a segment to widen it and read its exact figures, toggle segments from the legend and the rest reflow, with labels inside when they fit and on leader lines when they don't.

### Guidance for AI tools

Activity heatmap: See a year of activity at a glance, one square per day. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Animated counter

> Give changing totals a clear sense of movement.

- Type: Component (data)
- Access: Free, open source
- Page: https://uiarc.dev/components/animated-counter
- Markdown: https://uiarc.dev/components/animated-counter/markdown
- Registry item: https://uiarc.dev/r/animated-counter.json
- Source file: `registry/components/animated-counter/animated-counter.tsx`
- Dependencies: motion
- Keywords: data, motion, react animated counter, number ticker, odometer counter, rolling digits, count up animation, animated number

### When to use

- Standalone numbers that change, such as totals, prices, or live counts.
- Hero stats that roll up from zero when they scroll into view, via animateOnView.

### When not to use

- Use metric-card or stat-card when the number needs a card around it.
- Use text-morph for words rather than numbers.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/animated-counter
pnpm dlx shadcn@latest add @uiarc/animated-counter
yarn dlx shadcn@latest add @uiarc/animated-counter
bunx --bun shadcn@latest add @uiarc/animated-counter
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/animated-counter.json
```

#### Manual

1. Install the dependencies:

```bash
npm install motion
```

2. Copy the source into your project. Main file: `registry/components/animated-counter/animated-counter.tsx`

   The source is in the registry item: https://uiarc.dev/r/animated-counter.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { AnimatedCounter } from "@/components/arc/animated-counter/animated-counter";

export function Raised({ amount }: { amount: number }) {
  return <AnimatedCounter label="Raised" value={amount} prefix="$" animateOnView />;
}
```

### API reference

#### AnimatedCounter

An odometer style number whose digit columns roll to each new value.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` (required) | `number` | – | The number to show. |
| `label` | `string` | – | Small label above the number. |
| `prefix` | `string` | `""` | Text before the number, such as "$". |
| `suffix` | `string` | `""` | Text after the number, such as "%". |
| `decimals` | `number` | `0` | Fixed fraction digits. |
| `animateOnView` | `boolean` | `false` | Rolls every digit up from zero the first time it scrolls into view. |
| `locale` | `string` | `"en-US"` | Formatting locale. Fixed by default so server and client match. |

### Accessibility

- A visually hidden copy holds the full formatted text; the rolling digits are aria-hidden.
- It does not announce changes; wrap it in a live region if updates must be spoken.

### Motion

- Each digit column turns in the direction the whole number moved, wrapping 9 to 0, with a slight stagger on first reveal.
- Columns and separators slide in or out when the digit count changes.
- Reduced motion jumps digits into place.

### Responsive behavior

- It sizes to its digits, and columns slide in or out when the digit count changes, so neighbours shift slightly.

### Performance

- Each digit is its own motion column; fine for a few counters, not for every cell of a table.
- The first reveal waits for 60% visibility through useInView.

### Notes for AI

- Use for standalone numbers that change: totals, prices, counts. Use metric-card or stat-card when the number needs a card around it.
- Pass a raw number and let decimals, prefix, and suffix format it; do not pass preformatted strings.

### Related

- [Metric card](https://uiarc.dev/components/metric-card/markdown): A compact summary for a number that needs context.
- [Text morph](https://uiarc.dev/components/text-morph/markdown): Morph a label into its next state, letter by letter.

### Also in charts

- [Line chart](https://uiarc.dev/components/line-chart/markdown): A multi-series line chart with a gliding crosshair, legend toggles, and paths that morph between ranges.
- [Bar chart](https://uiarc.dev/components/bar-chart/markdown): Compare one measure across days and scrub any bar for its value.
- [Donut chart](https://uiarc.dev/components/donut-chart/markdown): A donut whose arcs morph between datasets, with the active value rolling into the center.
- [Streamgraph](https://uiarc.dev/components/streamgraph/markdown): Layered streams on a wiggle baseline that morph between ranges, with a layer you can isolate and read week by week.
- [Brush chart](https://uiarc.dev/components/brush-chart/markdown): A dense time series with an overview strip: drag a window to zoom, resize it by its handles, and read events in place.
- [Waffle chart](https://uiarc.dev/components/waffle-chart/markdown): A ten by ten unit chart where every cell is one percent, and cells fly to their new group when the data changes.
- [Slope chart](https://uiarc.dev/components/slope-chart/markdown): Before and after on two axes: lines draw in, rank moves sit beside each value, and switching datasets slides every line to its new slope.
- [Sparkline](https://uiarc.dev/components/sparkline/markdown): Show a compact trend beside a value.
- [Gauge](https://uiarc.dev/components/gauge/markdown): Show a value against a known range.
- [Activity heatmap](https://uiarc.dev/components/activity-heatmap/markdown): See a year of activity at a glance, one square per day.
- [Ridgeline](https://uiarc.dev/components/ridgeline/markdown): Overlapping distributions, one ridge per group: hover to lift a ridge and read its quartiles, switch datasets and every curve morphs.
- [Treemap](https://uiarc.dev/components/treemap/markdown): A squarified treemap: click to drill and the tiles grow to fill the view, with a breadcrumb back and metrics that morph every tile.
- [Split bar](https://uiarc.dev/components/split-bar/markdown): A single 100% bar split into shares: rest on a segment to widen it and read its exact figures, toggle segments from the legend and the rest reflow, with labels inside when they fit and on leader lines when they don't.

### Guidance for AI tools

Animated counter: Give changing totals a clear sense of movement. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Ridgeline

> Overlapping distributions, one ridge per group: hover to lift a ridge and read its quartiles, switch datasets and every curve morphs.

- Type: Component (data)
- Access: Free, open source
- Page: https://uiarc.dev/components/ridgeline
- Markdown: https://uiarc.dev/components/ridgeline/markdown
- Registry item: https://uiarc.dev/r/ridgeline.json
- Source file: `registry/components/ridgeline/ridgeline.tsx`
- Dependencies: motion
- Keywords: data, chart, new, ridgeline, joy plot, joyplot, density plot, distribution, kde, quartiles

### When to use

- Seasonal or categorical distributions such as temperatures by month or response times by region.
- Showing where two groups differ in shape, such as bimodal winters.

### When not to use

- Use beeswarm when each individual observation matters.
- Use bar-chart when only one summary number per group matters.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/ridgeline
pnpm dlx shadcn@latest add @uiarc/ridgeline
yarn dlx shadcn@latest add @uiarc/ridgeline
bunx --bun shadcn@latest add @uiarc/ridgeline
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/ridgeline.json
```

#### Manual

1. Install the dependencies:

```bash
npm install motion
```

2. Copy the source into your project. Main file: `registry/components/ridgeline/ridgeline.tsx`

   The source is in the registry item: https://uiarc.dev/r/ridgeline.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { Ridgeline } from "@/components/arc/ridgeline/ridgeline";

export function Latency({ regions }: { regions: { id: string; label: string; values: number[] }[] }) {
  return <Ridgeline series={regions} label="API latency by region" unit=" ms" />;
}
```

### API reference

#### Ridgeline

A ridgeline (joy) plot: one smoothed distribution per row, overlapping like mountain ridges, tinted by median. Hover lifts a ridge above its neighbours to read its quartiles; switching datasets morphs every curve.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `series` (required) | `{ id: string; label: string; values: number[] }[]` | – | One ridge per series, drawn top to bottom. Values are raw observations; the ridge is their kernel density. |
| `label` (required) | `string` | – | What is measured. Names the chart for assistive technology. |
| `unit` | `string` | – | Unit after each value, such as "°" or " ms". |
| `formatValue` | `(value: number) => string` | – | Formats values. Overrides unit. |
| `domain` | `[number, number]` | – | Value range of the axis. Fix it to keep the axis still across datasets. Defaults to the data with room on each side. |
| `overlap` | `number` | `2.4` | How far the tallest ridge rises into the rows above, in row heights. |
| `rowHeight` | `number` | `30` | Height of one row in pixels. |
| `bandwidth` | `number` | – | Smoothing in value units. Defaults to Silverman's rule per series. |
| `tint` | `boolean` | `true` | Shades each ridge by its median, from a light tint to the full first series color, with a stepped scale under the axis. |
| `active` | `string \| null` | – | Controlled id of the lifted ridge. |
| `defaultActive` | `string \| null` | `null` | Initial lifted ridge when uncontrolled. |
| `onActiveChange` | `(id: string \| null) => void` | – | Called when the lifted ridge changes. |
| `emptyLabel` | `string` | `"No data yet"` | Shown when there are no values. |
| `className` | `string` | – | Extra class on the root figure. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| ArrowUp / ArrowDown | Lifts the previous or next ridge. |
| ArrowLeft / ArrowRight | Moves the reading cursor along the values by one axis step. |
| Home / End | Lifts the first or last ridge. |
| Escape | Lowers the ridge and clears the reading. |

### Accessibility

- The plot is a focusable group; the lifted ridge's median, middle half, range, and count are announced through a polite live region.
- A visually hidden table lists median, quartiles, extremes, and count for every series.
- Every row is labelled in text; the median tint is backed by the table and tooltip.

### Motion

- Curves are sampled on a shared grid, so a new dataset or domain interpolates every point: ridges swell, slide, and split in one spring.
- The first reveal rolls the ridges in from the top row down.
- The lifted ridge is a copy drawn above the others that rises 6px on a spring, with its middle half shaded and its median marked.
- The tooltip glides after the pointer and stays inside the chart. Reduced motion draws final shapes immediately.

### Responsive behavior

- Label gutter and tick count adapt to width; the plot redraws at the measured size so strokes stay crisp.
- Touch taps lift a ridge and read at the tapped value.

### Performance

- Densities are computed once per dataset (96 samples per ridge); animation interpolates arrays and writes path strings directly.
- Suitable for up to a few thousand observations per series.

### Notes for AI

- Choose it to compare the shape of many distributions: spread, skew, and bimodality, not just averages.
- Pass raw observations, at least 20 per series, and fix domain when switching datasets so shapes move on a still axis.
- Keep rows to about 20; beyond that, use small multiples or a box plot.
- Colors come from the shared --series-1 to --series-4 tokens in foundation.css: series 1 is the accent itself and series 2 to 4 rotate its hue, validated all-pairs for color vision deficiency across every accent in light and dark. Override the tokens on any ancestor to rebrand.

### Related

- [Streamgraph](https://uiarc.dev/components/streamgraph/markdown): Layered streams on a wiggle baseline that morph between ranges, with a layer you can isolate and read week by week.
- [Line chart](https://uiarc.dev/components/line-chart/markdown): A multi-series line chart with a gliding crosshair, legend toggles, and paths that morph between ranges.
- [Activity heatmap](https://uiarc.dev/components/activity-heatmap/markdown): See a year of activity at a glance, one square per day.

### Also in charts

- [Bar chart](https://uiarc.dev/components/bar-chart/markdown): Compare one measure across days and scrub any bar for its value.
- [Donut chart](https://uiarc.dev/components/donut-chart/markdown): A donut whose arcs morph between datasets, with the active value rolling into the center.
- [Brush chart](https://uiarc.dev/components/brush-chart/markdown): A dense time series with an overview strip: drag a window to zoom, resize it by its handles, and read events in place.
- [Waffle chart](https://uiarc.dev/components/waffle-chart/markdown): A ten by ten unit chart where every cell is one percent, and cells fly to their new group when the data changes.
- [Slope chart](https://uiarc.dev/components/slope-chart/markdown): Before and after on two axes: lines draw in, rank moves sit beside each value, and switching datasets slides every line to its new slope.
- [Sparkline](https://uiarc.dev/components/sparkline/markdown): Show a compact trend beside a value.
- [Gauge](https://uiarc.dev/components/gauge/markdown): Show a value against a known range.
- [Animated counter](https://uiarc.dev/components/animated-counter/markdown): Give changing totals a clear sense of movement.
- [Treemap](https://uiarc.dev/components/treemap/markdown): A squarified treemap: click to drill and the tiles grow to fill the view, with a breadcrumb back and metrics that morph every tile.
- [Split bar](https://uiarc.dev/components/split-bar/markdown): A single 100% bar split into shares: rest on a segment to widen it and read its exact figures, toggle segments from the legend and the rest reflow, with labels inside when they fit and on leader lines when they don't.

### Guidance for AI tools

Ridgeline: Overlapping distributions, one ridge per group: hover to lift a ridge and read its quartiles, switch datasets and every curve morphs. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Treemap

> A squarified treemap: click to drill and the tiles grow to fill the view, with a breadcrumb back and metrics that morph every tile.

- Type: Component (data)
- Access: Free, open source
- Page: https://uiarc.dev/components/treemap
- Markdown: https://uiarc.dev/components/treemap/markdown
- Registry item: https://uiarc.dev/r/treemap.json
- Source file: `registry/components/treemap/treemap.tsx`
- Dependencies: motion
- Keywords: data, chart, new, treemap, tree map, squarified, hierarchy, part to whole, drill down, zoomable treemap

### When to use

- Many parts where the biggest ones matter and people drill for detail.
- Showing size and a second measure at once.

### When not to use

- Use bar-chart when exact comparisons between similar values matter.
- Use sunburst when the depth of the hierarchy is the story.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/treemap
pnpm dlx shadcn@latest add @uiarc/treemap
yarn dlx shadcn@latest add @uiarc/treemap
bunx --bun shadcn@latest add @uiarc/treemap
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/treemap.json
```

#### Manual

1. Install the dependencies:

```bash
npm install motion
```

2. Copy the source into your project. Main file: `registry/components/treemap/treemap.tsx`

   The source is in the registry item: https://uiarc.dev/r/treemap.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { Treemap } from "@/components/arc/treemap/treemap";

const data = {
  id: "all", label: "All regions",
  children: [
    { id: "na", label: "North America", children: [{ id: "us", label: "United States", value: 18400, color: 24 }, { id: "ca", label: "Canada", value: 2350, color: 19 }] },
    { id: "eu", label: "Europe", children: [{ id: "de", label: "Germany", value: 4120, color: 28 }] },
  ],
};

export function Revenue() {
  return <Treemap data={data} label="ARR" colorLabel="Growth" formatColor={value => `+${value}%`} />;
}
```

### API reference

#### Treemap

A squarified treemap of a hierarchy. Click a branch and its tile grows to fill the view while its children open inside; the breadcrumb zooms back out. Switching the size or shading measure morphs every tile.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `data` (required) | `TreemapNode` | – | The root: { id, label, value?, color?, children? }. A branch's value is the sum of its children. |
| `label` (required) | `string` | – | What the whole is. Names the chart for assistive technology. |
| `formatValue` | `(value: number) => string` | – | Formats sizes on tiles, the total, and the tooltip. |
| `colorLabel` | `string` | – | Names the shading measure, such as "Growth". Tiles take the hue of their top level branch and deepen with the measure. Leave it out for one depth. |
| `formatColor` | `(value: number) => string` | – | Formats the shading measure. |
| `colorDomain` | `[number, number]` | – | Range of the shading measure. Defaults to the range of the leaves. |
| `focus` | `string` | – | Controlled id of the node that fills the view. |
| `defaultFocus` | `string` | – | Initial focus when uncontrolled. Defaults to the root. |
| `onFocusChange` | `(id: string) => void` | – | Called when people drill in or out. |
| `height` | `number` | `420` | Height of the tiles in pixels. |
| `emptyLabel` | `string` | `"No data yet"` | Shown when every value is zero. |
| `className` | `string` | – | Extra class on the root figure. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Arrow keys | Move to the nearest top level tile in that direction. |
| Home / End | Move to the first or last tile. |
| Enter / Space | Zooms into the tile in focus. |
| Escape / Backspace | Zooms out one level. |

### Accessibility

- The tiles form a focusable group with a description of its keys; the breadcrumb is a nav with aria-current on the current level.
- The tile in focus is announced with its path, value, share of parent, and shading measure through a polite live region.
- A visually hidden table lists every node's path, value, share, and measure.

### Motion

- Drilling in carries every tile through one affine zoom: the chosen tile grows to fill the view, its siblings fly outward, and its children open inside it.
- Zooming out reverses the same path, so each level shrinks back into the tile it came from.
- Changing a measure re-lays out the same ids, so tiles resize and recolor in place; totals roll and breadcrumbs slide.
- Text never scales: tiles are sized each frame and labels appear only where they fit. Reduced motion places tiles immediately.

### Responsive behavior

- The layout squarifies to the measured width, so tiles stay close to square on any screen; headers and labels hide where they would not fit.
- Tap a tile to read it, tap a branch to drill in.

### Performance

- Layouts are computed per focus; animation interpolates rects and writes transforms and sizes directly. Comfortable up to a few hundred nodes.

### Notes for AI

- Choose it for part-to-whole across a hierarchy with many leaves, such as revenue by region, country, and plan.
- Give nodes stable ids so switching the size measure morphs rather than rebuilds.
- The shading measure should be a magnitude (growth, margin), not identity; identity comes from the top level hue.
- Colors come from the shared --series-1 to --series-4 tokens in foundation.css: series 1 is the accent itself and series 2 to 4 rotate its hue, validated all-pairs for color vision deficiency across every accent in light and dark. Override the tokens on any ancestor to rebrand.

### Related

- [Sunburst](https://uiarc.dev/components/sunburst/markdown): A hierarchy in rings: click a segment and every arc swings around it as the new centre, with a breadcrumb back and a rolling total.
- [Donut chart](https://uiarc.dev/components/donut-chart/markdown): A donut whose arcs morph between datasets, with the active value rolling into the center.
- [Bar chart](https://uiarc.dev/components/bar-chart/markdown): Compare one measure across days and scrub any bar for its value.
- [Waffle chart](https://uiarc.dev/components/waffle-chart/markdown): A ten by ten unit chart where every cell is one percent, and cells fly to their new group when the data changes.

### Also in charts

- [Line chart](https://uiarc.dev/components/line-chart/markdown): A multi-series line chart with a gliding crosshair, legend toggles, and paths that morph between ranges.
- [Streamgraph](https://uiarc.dev/components/streamgraph/markdown): Layered streams on a wiggle baseline that morph between ranges, with a layer you can isolate and read week by week.
- [Brush chart](https://uiarc.dev/components/brush-chart/markdown): A dense time series with an overview strip: drag a window to zoom, resize it by its handles, and read events in place.
- [Slope chart](https://uiarc.dev/components/slope-chart/markdown): Before and after on two axes: lines draw in, rank moves sit beside each value, and switching datasets slides every line to its new slope.
- [Sparkline](https://uiarc.dev/components/sparkline/markdown): Show a compact trend beside a value.
- [Gauge](https://uiarc.dev/components/gauge/markdown): Show a value against a known range.
- [Activity heatmap](https://uiarc.dev/components/activity-heatmap/markdown): See a year of activity at a glance, one square per day.
- [Animated counter](https://uiarc.dev/components/animated-counter/markdown): Give changing totals a clear sense of movement.
- [Ridgeline](https://uiarc.dev/components/ridgeline/markdown): Overlapping distributions, one ridge per group: hover to lift a ridge and read its quartiles, switch datasets and every curve morphs.
- [Split bar](https://uiarc.dev/components/split-bar/markdown): A single 100% bar split into shares: rest on a segment to widen it and read its exact figures, toggle segments from the legend and the rest reflow, with labels inside when they fit and on leader lines when they don't.

### Guidance for AI tools

Treemap: A squarified treemap: click to drill and the tiles grow to fill the view, with a breadcrumb back and metrics that morph every tile. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Split bar

> A single 100% bar split into shares: rest on a segment to widen it and read its exact figures, toggle segments from the legend and the rest reflow, with labels inside when they fit and on leader lines when they don't.

- Type: Component (data)
- Access: Arc Pro
- Page: https://uiarc.dev/components/split-bar
- Markdown: https://uiarc.dev/components/split-bar/markdown
- Source file: `registry/components/split-bar/split-bar.tsx`
- Dependencies: motion
- Keywords: data, chart, motion, new, split bar, stacked bar, 100% bar, part to whole, share, proportion, percent, traffic sources, budget, storage bar, legend toggle, leader lines, segment, breakdown

### When to use

- A compact part to whole view that fits in a card row or a dashboard header.
- Comparing shares where people also want exact figures on demand and the option to leave a category out.
- Showing how a mix changes between periods or filters with one continuous reflow.

### When not to use

- Use bar-chart to compare absolute values across many categories.
- Use donut-chart when the total in the middle is the headline, or waffle-chart for a count of units.
- Use a stacked chart over time when the trend of each share matters more than today's split.

### Installation

Split bar is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/split-bar
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { SplitBar, type SplitSegment } from "@/components/arc/split-bar/split-bar";

const budget: SplitSegment[] = [
  { id: "payroll", label: "Payroll", value: 412_000 },
  { id: "cloud", label: "Cloud", value: 96_500 },
  { id: "marketing", label: "Marketing", value: 74_200 },
  { id: "tools", label: "Software", value: 18_900 },
  { id: "other", label: "Other", value: 9_300 },
];

export function BudgetSplit() {
  const [hidden, setHidden] = useState<string[]>([]);
  return (
    <SplitBar
      title="Q4 budget"
      segments={budget}
      format={{ style: "currency", currency: "USD", maximumFractionDigits: 0 }}
      hidden={hidden}
      onHiddenChange={setHidden}
    />
  );
}
```

### API reference

#### SplitBar

One 100% bar split into shares, for traffic sources, budgets, storage or votes. Rest on a segment and it widens a little (small ones widen enough to show their own label) while the others give way proportionally and dim, and the readout above names it precisely: share, value and unit. Labels sit inside a segment when they fit, as name and percent or percent alone, and otherwise move to a lane under the bar with soft leader lines, pushed apart so they never overlap. The legend switches segments off and on: a hidden segment collapses in place and the rest reflow to fill the bar on springs, their percentages rolling to the new shares. New data does the same, so switching a period is one continuous reflow.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `segments` | `readonly SplitSegment[]` | – | The shares in display order: { id, label, value, color? }. Shares are each value over the total of the visible segments; zero and negative values are left out. Segments are matched by id when the data changes. |
| `segments[].color` | `string` | – | Any CSS color. Defaults to --series-1 to --series-4, then two neutrals meant for catch-all shares such as Referral or Other. |
| `title` | `string` | – | Heading above the bar and the accessible name unless label is set. |
| `description` | `string` | – | One line under the title. |
| `format` | `Intl.NumberFormatOptions` | – | Number format for values in the readout, such as currency for a budget. Shares always read as percentages with one decimal. |
| `unit` | `string` | – | Word after values in the readout, such as sessions. |
| `totalLabel` | `string` | `"Total"` | Label of the readout when nothing is highlighted. |
| `hidden` | `readonly string[]` | – | Ids of segments that are switched off (controlled). |
| `defaultHidden` | `readonly string[]` | `[]` | Ids switched off at first (uncontrolled). |
| `onHiddenChange` | `(hidden: string[]) => void` | – | Called with the new list when the legend or the keyboard switches a segment. |
| `legend` | `boolean` | `true` | Show the legend. Each item toggles its segment and highlights it on hover. |
| `locale` | `string` | `"en-US"` | Formatting locale. Fixed by default so server and client render the same digits. |
| `label` | `string` | – | Accessible name. Defaults to the title. |
| `className` | `string` | – | Class on the root element. |
| `style` | `CSSProperties` | – | Inline styles on the root element. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Tab | Focuses the bar, then each legend item. |
| Arrow Right / Arrow Down | On the bar: highlights the next visible segment, widening it and reading it out. |
| Arrow Left / Arrow Up | On the bar: highlights the previous visible segment. |
| Home / End | On the bar: highlights the first or last visible segment. |
| Enter / Space | On the bar: switches the highlighted segment off. On a legend item: switches its segment off or back on. |
| Escape | Clears the highlight. |

### Accessibility

- The bar is a focusable group with the role description split bar, named with every visible share (Organic search 41.6%, Direct 24.8% and so on) and how to read each one.
- Moving through segments with the arrow keys announces the segment's name, share and value in a polite live region; switching a segment off or on is announced too.
- Legend items are toggle buttons with aria-pressed, named with the segment and its share or hidden. An off segment is also shown without color: a hollow swatch, struck through name and the word Off.
- The last visible segment cannot be switched off; the legend item gives a small shake and the reason is announced.
- Inside labels, outside labels, leader lines and rolling digits are hidden from assistive technology; the group name and readout carry the same numbers as text.
- Segments use the shared chart palette, validated for color vision deficiency in both themes, and every segment is named in the legend, so color is never the only key.

### Motion

- Each segment is a full width layer cut to its share with an animated clip-path, and its edges ride the smooth spring. Reflow never touches layout, and a new target mid flight retargets from where the edges are.
- Hovering or arrowing onto a segment widens it by about 4.5% of the bar, or enough to fit its name and share when it is small, while the others give way proportionally and dim, so the bar always stays at 100%.
- Labels live inside the clipped layer, so they slide with their segment and are cut cleanly at its edge instead of spilling into a neighbour. When a segment grows or shrinks, its name opens or closes on a spring beside the percentage.
- Outside labels glide to their new places and fade in and out; their leader lines are S curves that morph with them. The label lane opens and closes smoothly when the first label moves outside or the last one comes back.
- Percentages, values and the total roll digit by digit like an odometer, in the direction they changed.
- The readout above the bar crossfades between the total and the highlighted segment with a short rise and a little blur.
- With reduced motion segments and labels move at once, digits change in place, readouts swap without travel and the refusal shake is skipped.

### Responsive behavior

- The bar spans its container. Its width is measured with a ResizeObserver and label fitting is recalculated, so the same data shows more labels inside on a wide card and moves more of them outside on a phone.
- The readout wraps under the title on narrow screens; the legend wraps to as many rows as it needs.
- On touch, a tap on a segment highlights it and a tap elsewhere clears it; vertical page scrolling is never captured.

### Performance

- Label fitting uses canvas text metrics cached per font, so it never reads layout while animating.
- Segment edges, caps and labels are driven by motion values; React renders only when the data, the hidden set or the highlighted segment changes.
- Segments animate clip-path and transform only.

### Notes for AI

- Use it for a part to whole split of two to eight categories where people compare shares at a glance: traffic sources, budget lines, storage by file type, survey answers, device mix.
- Order segments by size or by a meaningful sequence, and put catch-all shares such as Other last so they take the neutral colors.
- Set unit or format so the readout gives the exact figure, not only the percentage.
- Keep labels short. Long names only show inside wide segments; everything else moves to the outside lane.
- Pass new segments with the same ids to animate between periods or filters; the bar reflows instead of redrawing.

### Related

- [Donut chart](https://uiarc.dev/components/donut-chart/markdown): A donut whose arcs morph between datasets, with the active value rolling into the center.
- [Waffle chart](https://uiarc.dev/components/waffle-chart/markdown): A ten by ten unit chart where every cell is one percent, and cells fly to their new group when the data changes.
- [Treemap](https://uiarc.dev/components/treemap/markdown): A squarified treemap: click to drill and the tiles grow to fill the view, with a breadcrumb back and metrics that morph every tile.
- [Bar chart](https://uiarc.dev/components/bar-chart/markdown): Compare one measure across days and scrub any bar for its value.
- [Usage meter](https://uiarc.dev/components/usage-meter/markdown): Show what fills an allowance and how close it is to the limit.

### Also in charts

- [Line chart](https://uiarc.dev/components/line-chart/markdown): A multi-series line chart with a gliding crosshair, legend toggles, and paths that morph between ranges.
- [Streamgraph](https://uiarc.dev/components/streamgraph/markdown): Layered streams on a wiggle baseline that morph between ranges, with a layer you can isolate and read week by week.
- [Brush chart](https://uiarc.dev/components/brush-chart/markdown): A dense time series with an overview strip: drag a window to zoom, resize it by its handles, and read events in place.
- [Slope chart](https://uiarc.dev/components/slope-chart/markdown): Before and after on two axes: lines draw in, rank moves sit beside each value, and switching datasets slides every line to its new slope.
- [Sparkline](https://uiarc.dev/components/sparkline/markdown): Show a compact trend beside a value.
- [Gauge](https://uiarc.dev/components/gauge/markdown): Show a value against a known range.
- [Activity heatmap](https://uiarc.dev/components/activity-heatmap/markdown): See a year of activity at a glance, one square per day.
- [Animated counter](https://uiarc.dev/components/animated-counter/markdown): Give changing totals a clear sense of movement.
- [Ridgeline](https://uiarc.dev/components/ridgeline/markdown): Overlapping distributions, one ridge per group: hover to lift a ridge and read its quartiles, switch datasets and every curve morphs.

### Guidance for AI tools

Split bar: A single 100% bar split into shares: rest on a segment to widen it and read its exact figures, toggle segments from the legend and the rest reflow, with labels inside when they fit and on leader lines when they don't. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Sunburst

> A hierarchy in rings: click a segment and every arc swings around it as the new centre, with a breadcrumb back and a rolling total.

- Type: Component (data)
- Access: Arc Pro
- Page: https://uiarc.dev/components/sunburst
- Markdown: https://uiarc.dev/components/sunburst/markdown
- Source file: `registry/components/sunburst/sunburst.tsx`
- Dependencies: motion
- Keywords: data, chart, new, sunburst chart, zoomable sunburst, hierarchical pie chart, radial treemap, drill down chart, multi level donut, cloud cost breakdown, react sunburst

### When to use

- Drilling into where a total comes from, one level at a time.
- Showing the share of each part within its parent and within the whole.
- Dashboards where a compact, explorable overview beats a long table.

### When not to use

- Use donut-chart for a single level of parts.
- Use tree-table when people need to compare exact values across many rows.
- Avoid it for more than about 150 leaves; thin slivers stop being readable.

### Installation

Sunburst is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/sunburst
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { Sunburst } from "@/components/arc/sunburst/sunburst";

const spend = {
  id: "all", label: "All teams",
  children: [
    { id: "platform", label: "Platform", children: [
      { id: "platform/compute", label: "Compute", children: [{ id: "api", label: "api-cluster", value: 18910 }, { id: "batch", label: "batch-workers", value: 8160 }] },
      { id: "platform/storage", label: "Storage", value: 8670 },
    ] },
    { id: "data", label: "Data", children: [{ id: "data/warehouse", label: "Warehouse", value: 31020 }] },
  ],
};

export function CloudSpend() {
  return <Sunburst data={spend} label="Cloud spend, September" formatValue={value => `$${(value / 1000).toFixed(1)}K`} />;
}
```

### API reference

#### Sunburst

A hierarchy drawn as rings. Clicking a segment swings every arc around it as the new centre, the breadcrumb follows, and the centre label rolls to the new total.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `data` (required) | `SunburstNode` | – | The root: { id, label, value?, children? }. A branch's value is the sum of its children. |
| `label` (required) | `string` | – | Names the chart for assistive technology. |
| `formatValue` | `(value: number) => string` | – | Formats the centre value, legend, tooltip, and table. |
| `depth` | `number` | `3` | Rings shown around the centre at once. Fewer levels below a zoomed node fill the full radius. |
| `size` | `number` | `340` | Largest diameter in pixels. The chart scales down to fit its container. |
| `focus` | `string` | – | Controlled id of the node in the centre. |
| `defaultFocus` | `string` | – | Initial centre when uncontrolled. Defaults to the root. |
| `onFocusChange` | `(id: string) => void` | – | Called when a segment, breadcrumb, legend row, or the centre zooms. |
| `legend` | `boolean` | `true` | Lists the children of the centre with values and shares, synced with the arcs. |
| `emptyLabel` | `string` | `"No data yet"` | Shown in the centre when the total is zero. |
| `className` | `string` | – | Extra class on the figure. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Tab | Focuses the chart and highlights the first segment. |
| ArrowLeft / ArrowRight | Moves between sibling segments. |
| ArrowDown / ArrowUp | Moves to the first child or back to the parent segment. |
| Enter / Space | Zooms into the highlighted segment. |
| Escape / Backspace | Zooms out one level. |

### Accessibility

- The chart is a focusable group; the highlighted segment is announced with its path, value, and share of its parent.
- The breadcrumb is a nav landmark with the current level marked aria-current.
- Legend rows are buttons that name the segment, its value and share, and whether it zooms in.
- A visually hidden table lists every node's full path, value, and share of its parent.

### Motion

- Zooming interpolates every arc's angles and ring from where it is on screen to its place around the new centre, on one spring.
- Rings re-share the radius as levels appear or run out, so a shallow branch fills the chart as it zooms.
- The centre value rolls digit by digit; labels rise in from a soft blur; the breadcrumb slides and reflows.
- Reduced motion jumps arcs to their final place and swaps text with a short fade.

### Responsive behavior

- The ring scales to its container; the legend sits beside it when there is room and below it on narrow screens.
- Arc labels follow the ring's curve and appear only where the arc can hold them.
- Touch taps zoom; the centre is a large target to zoom back out.

### Performance

- Partitioning runs once per data change; arcs are painted by writing path attributes, not by re-rendering React each frame.
- Label fit is measured per arc during paint; keep the tree under a few hundred nodes.

### Notes for AI

- Choose it for exploring a two to four level hierarchy by share: spend, storage, headcount, time.
- Give every node a stable, unique id so switching datasets morphs the arcs.
- Keep top level branches to about eight; each takes the next series hue derived from the accent and its children step lighter; past four they fall back to ink.
- Control focus when a URL or another view should drive the zoom.

### Related

- [Donut chart](https://uiarc.dev/components/donut-chart/markdown): A donut whose arcs morph between datasets, with the active value rolling into the center.
- [Sankey flow](https://uiarc.dev/components/sankey-flow/markdown): Flows between stages as ribbons with drifting particles; hover any node or ribbon to pour its share through the whole journey.
- [Tree table](https://uiarc.dev/components/tree-table/markdown): A table with nested rows, tri-state selection, hierarchy-preserving sort, and lazy-loaded children.
- [Tree view](https://uiarc.dev/components/tree-view/markdown): Navigate nested folders and structured content.

### Also in advanced charts

- [Funnel chart](https://uiarc.dev/components/funnel-chart/markdown): A tapered conversion funnel with drop-off at every step, a device split that morphs the band, and dots that stream through it.
- [Radar chart](https://uiarc.dev/components/radar-chart/markdown): Two or three profiles on one web: shapes morph when you swap a profile, and a sweep across the axes compares values in place.
- [Realtime stream](https://uiarc.dev/components/realtime-stream/markdown): A live line that scrolls at 60fps as readings arrive, holds still on hover to read, and pops a marker on every anomaly.
- [Race bar chart](https://uiarc.dev/components/race-bar-chart/markdown): A ranking over time: bars overtake each other on springs, values count up, and a timeline you can play or scrub.
- [Data grid](https://uiarc.dev/components/data-grid/markdown): A spreadsheet grid with range selection, inline editing, a fill handle, and animated sorting.

### Guidance for AI tools

Sunburst: A hierarchy in rings: click a segment and every arc swings around it as the new centre, with a breadcrumb back and a rolling total. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Sankey flow

> Flows between stages as ribbons with drifting particles; hover any node or ribbon to pour its share through the whole journey.

- Type: Component (data)
- Access: Arc Pro
- Page: https://uiarc.dev/components/sankey-flow
- Markdown: https://uiarc.dev/components/sankey-flow/markdown
- Source file: `registry/components/sankey-flow/sankey-flow.tsx`
- Dependencies: motion
- Keywords: data, chart, new, sankey diagram, sankey chart react, flow diagram, funnel flow, user journey chart, alluvial diagram, particle flow chart, conversion flow

### When to use

- Showing how a total splits and recombines across three to five stages.
- Explaining where a funnel leaks, with the share at each step one hover away.
- Comparing two periods of the same flow by switching data.

### When not to use

- Use bar-chart for a simple linear funnel with no branches.
- Use sunburst for a strict hierarchy where each part has one parent.
- Avoid more than about 12 nodes per column; small flows become unreadable slivers.

### Installation

Sankey flow is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/sankey-flow
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { SankeyFlow } from "@/components/arc/sankey-flow/sankey-flow";

const nodes = [
  { id: "organic", label: "Organic" }, { id: "paid", label: "Paid" },
  { id: "activated", label: "Activated" }, { id: "inactive", label: "Not activated" },
  { id: "free", label: "Free" }, { id: "pro", label: "Pro" },
];
const links = [
  { source: "organic", target: "activated", value: 3380 }, { source: "organic", target: "inactive", value: 1820 },
  { source: "paid", target: "activated", value: 1990 }, { source: "paid", target: "inactive", value: 1910 },
  { source: "activated", target: "free", value: 3860 }, { source: "activated", target: "pro", value: 1510 },
];

export function SignupJourney() {
  return <SankeyFlow nodes={nodes} links={links} label="Signup journey" columns={["Source", "Activation", "Plan"]} unit="people" totalLabel="signups" />;
}
```

### API reference

#### SankeyFlow

A Sankey diagram with smooth ribbons, values on every node, and fine particles drifting along each flow. Hovering a node or ribbon pours the share of every flow that passes through it, end to end. Sources wear the series palette derived from the accent, and a trace pours in its source's hue.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `nodes` (required) | `{ id: string; label: string; column?: number }[]` | – | Nodes in the order they stack within each column. Columns default to each node's distance from a source. |
| `links` (required) | `{ source: string; target: string; value: number }[]` | – | Flows between node ids. A node's value is the larger of what flows in and out. |
| `label` (required) | `string` | – | Names the chart for assistive technology. |
| `columns` | `string[]` | – | Stage names printed above each column. Hidden when a name would not fit, and in the upright layout. |
| `unit` | `string` | `""` | Unit after values in the tooltip and table, such as "people". |
| `totalLabel` | `string` | `"the total"` | What the first column adds up to, used in shares such as "21% of signups". |
| `formatValue` | `(value: number) => string` | – | Formats node values, the tooltip, and the table. |
| `height` | `number` | `340` | Plot height in pixels. The upright layout below 420px wide uses at least 480. |
| `particles` | `boolean` | – | Controlled particles along the ribbons. |
| `defaultParticles` | `boolean` | `true` | Initial particles state when uncontrolled. |
| `onParticlesChange` | `(on: boolean) => void` | – | Called when the built in toggle is pressed. |
| `particleToggle` | `boolean` | `true` | Shows the Flow toggle under the plot. |
| `emptyLabel` | `string` | `"No flows yet"` | Shown when there are no positive links. |
| `className` | `string` | – | Extra class on the figure. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Tab | Focuses the diagram and highlights the first node. |
| ArrowUp / ArrowDown | Moves between nodes in a column (left and right in the upright layout). |
| ArrowLeft / ArrowRight | Steps to the nearest node in the previous or next column (up and down in the upright layout). |
| Home / End | Jumps to the first or last column. |
| Escape | Clears the highlight. |

### Accessibility

- The plot is one focusable group; the node in focus is announced with its value, share of the total, and where it flows next.
- A visually hidden table lists every flow with its value and share of the source.
- Labels, particles, and ribbons are aria-hidden; the table and announcements carry the data.
- Highlighting uses the accent plus dimming of everything else, never color alone; values are printed on nodes.

### Motion

- Nodes and ribbons grow in from their centres on first view, and morph from the layout on screen to the new one when data changes.
- Focus pours the traced share into each ribbon on a short spring and drains it back out when focus leaves.
- Particles move at one constant speed on a canvas and pause when the chart is off screen.
- Reduced motion jumps to the final layout and removes particles and the toggle.

### Responsive behavior

- Below 420px wide the diagram turns upright: stages run top to bottom and labels sit under each node at full width.
- On wide layouts the last column labels to its right in a gutter sized to its labels, so no two labels share a gap.
- Touch taps a node or ribbon to trace it and taps again to clear; the tooltip stays inside the plot.

### Performance

- Layout is computed once per data and size change; morphs interpolate numbers and write path attributes directly.
- Particles draw on one canvas, capped at 34 per ribbon, and stop when the chart leaves the viewport.
- Tracing walks each column once, so it stays instant for a few hundred links.

### Notes for AI

- Choose it for funnels that split and merge: acquisition to activation to plan, budget sources to spend, traffic between pages.
- Keep node ids stable across datasets so switching periods morphs instead of redrawing.
- Order nodes within a column the way people read them, such as good outcomes on top; the layout keeps that order.
- Tracing assumes each node mixes what reaches it, which fits aggregates. Say so if exact per person paths matter.

### Related

- [Sunburst](https://uiarc.dev/components/sunburst/markdown): A hierarchy in rings: click a segment and every arc swings around it as the new centre, with a breadcrumb back and a rolling total.
- [Streamgraph](https://uiarc.dev/components/streamgraph/markdown): Layered streams on a wiggle baseline that morph between ranges, with a layer you can isolate and read week by week.
- [Bar chart](https://uiarc.dev/components/bar-chart/markdown): Compare one measure across days and scrub any bar for its value.
- [Donut chart](https://uiarc.dev/components/donut-chart/markdown): A donut whose arcs morph between datasets, with the active value rolling into the center.

### Also in advanced charts

- [Funnel chart](https://uiarc.dev/components/funnel-chart/markdown): A tapered conversion funnel with drop-off at every step, a device split that morphs the band, and dots that stream through it.
- [Radar chart](https://uiarc.dev/components/radar-chart/markdown): Two or three profiles on one web: shapes morph when you swap a profile, and a sweep across the axes compares values in place.
- [Realtime stream](https://uiarc.dev/components/realtime-stream/markdown): A live line that scrolls at 60fps as readings arrive, holds still on hover to read, and pops a marker on every anomaly.
- [Race bar chart](https://uiarc.dev/components/race-bar-chart/markdown): A ranking over time: bars overtake each other on springs, values count up, and a timeline you can play or scrub.
- [Data grid](https://uiarc.dev/components/data-grid/markdown): A spreadsheet grid with range selection, inline editing, a fill handle, and animated sorting.

### Guidance for AI tools

Sankey flow: Flows between stages as ribbons with drifting particles; hover any node or ribbon to pour its share through the whole journey. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Funnel chart

> A tapered conversion funnel with drop-off at every step, a device split that morphs the band, and dots that stream through it.

- Type: Component (data)
- Access: Arc Pro
- Page: https://uiarc.dev/components/funnel-chart
- Markdown: https://uiarc.dev/components/funnel-chart/markdown
- Source file: `registry/components/funnel-chart/funnel-chart.tsx`
- Dependencies: motion
- Keywords: data, chart, new, funnel chart, conversion funnel, react funnel chart, drop-off chart, checkout funnel, animated funnel, segment comparison funnel, growth funnel

### When to use

- Conversion through a fixed sequence of steps.
- Comparing how two segments convert through the same steps.
- A hero chart on a growth or analytics page where the drop-off is the story.

### When not to use

- Use sankey-flow when people can branch, skip, or loop between steps.
- Use bar-chart for unordered categories.
- Use line-chart for conversion over time.

### Installation

Funnel chart is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/funnel-chart
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { FunnelChart } from "@/components/arc/funnel-chart/funnel-chart";

const segments = [{ key: "mobile", label: "Mobile" }, { key: "desktop", label: "Desktop" }];
const stages = [
  { key: "visit", label: "Visited store", values: { mobile: 68420, desktop: 31580 } },
  { key: "cart", label: "Added to cart", values: { mobile: 9140, desktop: 7280 } },
  { key: "purchase", label: "Purchased", values: { mobile: 1540, desktop: 2050 } },
];

export function Checkout() {
  const [view, setView] = useState("total");
  return <FunnelChart stages={stages} segments={segments} view={view} label="Checkout funnel" unit="sessions" />;
}
```

### API reference

#### FunnelChart

A conversion funnel drawn as one smooth tapered band: flat across each step and eased between them, with drop-off at every boundary. Segments can be isolated or split with a 2px gap, and every change morphs the band. Optional dots stream through it and the share that leaves at each step falls out.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `stages` (required) | `FunnelStage[]` | – | Ordered steps: { key, label, value? , values? }. Use value without segments, values keyed by segment with them. |
| `segments` | `FunnelSegment[]` | – | Parts of every step, such as devices: { key, label }. Leave it out for one total per step. |
| `label` (required) | `string` | – | What is counted. Names the chart, the summary, and the table. |
| `unit` | `string` | `""` | Noun after counts in the tooltip and table, such as "sessions". |
| `view` | `"total" \| "split" \| string` | `"total"` | "total" draws one band, "split" stacks every segment with a gap, and a segment key isolates it and rescales the band to fill the height. |
| `flow` | `boolean` | `true` | Dots that stream through the band. Each decides up front where it leaves, so the falling share matches the real drop-off. |
| `orientation` | `"auto" \| "horizontal" \| "vertical"` | `"auto"` | Auto turns the funnel vertical below 420px of container width, with steps listed down the side. |
| `height` | `number` | `200` | Band area thickness in pixels when horizontal. |
| `formatValue` | `(value: number) => string` | – | Formats counts. Defaults to compact numbers in headings and full numbers in the tooltip. |
| `activeIndex` | `number \| null` | – | Controlled step in focus. |
| `onActiveChange` | `(index: number \| null) => void` | – | Called as the step in focus changes. |
| `emptyLabel` | `string` | `"No data"` | Message when the first step is zero. |
| `ref` | `Ref<HTMLElement>` | – | Forwarded to the figure. |
| `className` | `string` | – | Extra class on the figure. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Tab | Focuses the funnel and reads the first step. |
| ArrowRight / ArrowDown | Next step. |
| ArrowLeft / ArrowUp | Previous step. |
| Home / End | First or last step. |
| Escape | Clears the reading. |

### Accessibility

- The chart is a focusable group with a roledescription and instructions; the band, dots, and headings are aria-hidden.
- A polite live region reads the step, its count, the share kept from the previous step, and the share of the first.
- A visually hidden summary and a table list every step per segment with both rates.
- Drop-off uses an arrow glyph and a number, never colour alone.

### Motion

- Switching views morphs the band from the shape on screen with a spring; the split gap opens and closes with the same spring.
- Counts and rates roll to their new values.
- A soft column and an accent clip glide to the step in focus; the tooltip follows on its own spring and stays inside the chart.
- The band grows out of its centre line the first time it is seen.
- Dots run on a canvas at the display rate, pause off screen and in hidden tabs, and are never drawn with reduced motion, where the morphs also land immediately.

### Responsive behavior

- Horizontal from 420px of container width, vertical below with step names down the right side.
- The tooltip flips and clamps so it never leaves the chart.
- Touch reads steps with a press and drag; the page still scrolls vertically.

### Performance

- Band paths are rewritten from a single paint function; React does not re-render during morphs.
- Dots are drawn on one canvas and stop when the chart leaves the viewport.
- Around 40 dots are alive at once.

### Notes for AI

- Choose it for ordered steps where each keeps part of the previous one: signup, checkout, onboarding, sales pipeline.
- Pass segments and drive view from a segmented control to compare devices, plans, or channels.
- Keep stage labels short; they wrap to two lines above the band.
- Turn flow off for dense dashboards where motion would distract.

### Related

- [Sankey flow](https://uiarc.dev/components/sankey-flow/markdown): Flows between stages as ribbons with drifting particles; hover any node or ribbon to pour its share through the whole journey.
- [Bar chart](https://uiarc.dev/components/bar-chart/markdown): Compare one measure across days and scrub any bar for its value.
- [Waffle chart](https://uiarc.dev/components/waffle-chart/markdown): A ten by ten unit chart where every cell is one percent, and cells fly to their new group when the data changes.
- [Stepper](https://uiarc.dev/components/stepper/markdown): Show where a person is in a multi-step flow and what is done.

### Also in advanced charts

- [Sunburst](https://uiarc.dev/components/sunburst/markdown): A hierarchy in rings: click a segment and every arc swings around it as the new centre, with a breadcrumb back and a rolling total.
- [Radar chart](https://uiarc.dev/components/radar-chart/markdown): Two or three profiles on one web: shapes morph when you swap a profile, and a sweep across the axes compares values in place.
- [Realtime stream](https://uiarc.dev/components/realtime-stream/markdown): A live line that scrolls at 60fps as readings arrive, holds still on hover to read, and pops a marker on every anomaly.
- [Race bar chart](https://uiarc.dev/components/race-bar-chart/markdown): A ranking over time: bars overtake each other on springs, values count up, and a timeline you can play or scrub.
- [Data grid](https://uiarc.dev/components/data-grid/markdown): A spreadsheet grid with range selection, inline editing, a fill handle, and animated sorting.

### Guidance for AI tools

Funnel chart: A tapered conversion funnel with drop-off at every step, a device split that morphs the band, and dots that stream through it. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Radar chart

> Two or three profiles on one web: shapes morph when you swap a profile, and a sweep across the axes compares values in place.

- Type: Component (data)
- Access: Arc Pro
- Page: https://uiarc.dev/components/radar-chart
- Markdown: https://uiarc.dev/components/radar-chart/markdown
- Source file: `registry/components/radar-chart/radar-chart.tsx`
- Dependencies: motion
- Keywords: data, chart, new, radar chart, spider chart, web chart, react radar chart, comparison chart, animated radar chart, profile comparison, polar chart

### When to use

- Comparing the profile of a few options across shared measures.
- Showing strengths and gaps at a glance, such as scores or ratings.

### When not to use

- Use bar-chart when the precise difference on one measure matters.
- Use plan-matrix for feature comparisons with yes or no values.
- Avoid more than three profiles; the shapes stop being readable.

### Installation

Radar chart is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/radar-chart
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { RadarChart } from "@/components/arc/radar-chart/radar-chart";

const axes = [
  { key: "talent", label: "Talent pool" },
  { key: "afford", label: "Affordability" },
  { key: "transit", label: "Transit" },
  { key: "life", label: "Quality of life" },
  { key: "tax", label: "Tax climate" },
];

export function Offices({ rival }: { rival: RadarSeries }) {
  return <RadarChart axes={axes} series={[lisbon, rival]} label="Office locations" />;
}
```

### API reference

#### RadarChart

Two or three profiles on one web of five to eight measures. Profiles are drawn by position, so replacing one morphs its shape into the next. Moving across the web picks the nearest axis and compares every profile's value there.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `axes` (required) | `RadarAxis[]` | – | Measures around the web, clockwise from the top: { key, label, max? }. At least three. |
| `series` (required) | `RadarSeries[]` | – | Up to three profiles: { key, label, values }. They take the series hues in order, the first derived from the accent; replacing the series at a position morphs that shape. |
| `label` (required) | `string` | – | What is compared. Names the chart, the summary, and the table. |
| `max` | `number` | `100` | Default top of every axis. |
| `rings` | `number` | `4` | Concentric guides. |
| `size` | `number` | `320` | Largest web diameter in pixels. It shrinks to fit narrow containers. |
| `formatValue` | `(value: number, axis: RadarAxis) => string` | – | Formats values in the tooltip and table. |
| `activeAxis` | `string \| null` | – | Controlled axis in focus. |
| `onActiveAxisChange` | `(key: string \| null) => void` | – | Called as the axis in focus changes. |
| `legend` | `boolean` | `true` | Profile names with a line key. Hovering or pressing one brings its shape forward. |
| `emptyLabel` | `string` | `"No data"` | Message with fewer than three axes or no series. |
| `ref` | `Ref<HTMLElement>` | – | Forwarded to the figure. |
| `className` | `string` | – | Extra class on the figure. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Tab | Focuses the web and reads the first axis, then the legend. |
| ArrowRight / ArrowDown | Next axis, clockwise. |
| ArrowLeft / ArrowUp | Previous axis. |
| Home / End | First or last axis. |
| Escape | Clears the reading. |

### Accessibility

- The web is a focusable group with a roledescription and instructions; shapes and labels are aria-hidden.
- A polite live region reads the axis and every profile's value there.
- A visually hidden summary and a table list every value by measure and profile.
- Profiles are named in the legend and the tooltip with a line key, so identity never relies on colour alone.

### Motion

- Swapping a profile morphs its shape from the one on screen with a gently bouncing spring.
- The web unfolds from the centre the first time it is seen.
- Vertex markers and the tooltip glide between axes on springs; the tooltip sits past the axis label so the label and vertices stay visible.
- Reduced motion swaps shapes and moves markers immediately.

### Responsive behavior

- The web shrinks to the container and the label ring tightens below 360px; axis labels wrap.
- The tooltip clamps inside the chart at every width.
- Touch reads axes with a press and drag.

### Performance

- Shapes are rewritten from one paint function during morphs; React renders once per change.
- One ResizeObserver measures the container.

### Notes for AI

- Choose it for the overall shape of two or three profiles on the same five to eight measures: products, plans, locations, candidates.
- Put the subject of the story first so it takes the accent derived first series, and drive the second position from a picker to get the morph.
- Every axis must point the same way, higher is better, or the shape misleads.
- For exact comparison of values, pair it with a table or use bar-chart.

### Related

- [Bar chart](https://uiarc.dev/components/bar-chart/markdown): Compare one measure across days and scrub any bar for its value.
- [Slope chart](https://uiarc.dev/components/slope-chart/markdown): Before and after on two axes: lines draw in, rank moves sit beside each value, and switching datasets slides every line to its new slope.
- [Donut chart](https://uiarc.dev/components/donut-chart/markdown): A donut whose arcs morph between datasets, with the active value rolling into the center.

### Also in advanced charts

- [Sunburst](https://uiarc.dev/components/sunburst/markdown): A hierarchy in rings: click a segment and every arc swings around it as the new centre, with a breadcrumb back and a rolling total.
- [Sankey flow](https://uiarc.dev/components/sankey-flow/markdown): Flows between stages as ribbons with drifting particles; hover any node or ribbon to pour its share through the whole journey.
- [Funnel chart](https://uiarc.dev/components/funnel-chart/markdown): A tapered conversion funnel with drop-off at every step, a device split that morphs the band, and dots that stream through it.
- [Realtime stream](https://uiarc.dev/components/realtime-stream/markdown): A live line that scrolls at 60fps as readings arrive, holds still on hover to read, and pops a marker on every anomaly.
- [Race bar chart](https://uiarc.dev/components/race-bar-chart/markdown): A ranking over time: bars overtake each other on springs, values count up, and a timeline you can play or scrub.
- [Data grid](https://uiarc.dev/components/data-grid/markdown): A spreadsheet grid with range selection, inline editing, a fill handle, and animated sorting.

### Guidance for AI tools

Radar chart: Two or three profiles on one web: shapes morph when you swap a profile, and a sweep across the axes compares values in place. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Realtime stream

> A live line that scrolls at 60fps as readings arrive, holds still on hover to read, and pops a marker on every anomaly.

- Type: Component (data)
- Access: Arc Pro
- Page: https://uiarc.dev/components/realtime-stream
- Markdown: https://uiarc.dev/components/realtime-stream/markdown
- Source file: `registry/components/realtime-stream/realtime-stream.tsx`
- Dependencies: motion
- Keywords: data, chart, live, new, realtime chart, live chart, streaming chart, react live line chart, monitoring chart, scrolling chart, anomaly chart, 60fps chart

### When to use

- Live monitoring panels and status pages.
- A hero on an infrastructure or observability page where motion shows the system is alive.

### When not to use

- Use line-chart for static time series.
- Use brush-chart for long histories people zoom into.
- Use sparkline for a tiny trend inside a stat.

### Installation

Realtime stream is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/realtime-stream
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { RealtimeStream, type StreamPoint } from "@/components/arc/realtime-stream/realtime-stream";

export function Latency({ socket }: { socket: WebSocket }) {
  const [points, setPoints] = useState<StreamPoint[]>([]);
  useEffect(() => {
    const onMessage = (event: MessageEvent) => {
      const { t, p95 } = JSON.parse(event.data);
      setPoints(list => [...list.slice(-200), { t, value: p95, anomaly: p95 > 300 ? "Spike" : undefined }]);
    };
    socket.addEventListener("message", onMessage);
    return () => socket.removeEventListener("message", onMessage);
  }, [socket]);
  return <RealtimeStream points={points} label="p95 latency" unit="ms" interval={500} />;
}
```

### API reference

#### RealtimeStream

A live line chart on a canvas that scrolls continuously at the display rate. It draws one interval behind the newest reading so each point slides in, eases its value axis, pops a marker for anomalies, and holds still on hover so a point can be read while new ones queue.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `points` (required) | `StreamPoint[]` | – | Append-only feed in ascending time: { t, value, anomaly? }. A string anomaly becomes the marker tag. |
| `label` (required) | `string` | – | What is measured. Names the chart, the current value, and the table. |
| `unit` | `string` | `""` | Unit after values, such as "ms". |
| `windowMs` | `number` | `30000` | Visible span of time. |
| `interval` | `number` | `1000` | Typical time between points. The view trails the newest point by this much. |
| `height` | `number` | `200` | Plot height in pixels. |
| `formatValue` | `(value: number) => string` | – | Formats values in the readout, tooltip, and table. |
| `formatTime` | `(t: number) => string` | `HH:MM:SS` | Formats times in the tooltip and table. |
| `paused` | `boolean` | – | Controlled pause. |
| `defaultPaused` | `boolean` | `false` | Initial pause when uncontrolled. |
| `onPausedChange` | `(paused: boolean) => void` | – | Called when the status button or Space toggles the pause. |
| `pauseOnHover` | `boolean` | `true` | Holds the view while the pointer is over the plot. |
| `min` | `number` | – | Fixed bottom of the value axis. Leave it out to follow the data. |
| `max` | `number` | – | Fixed top of the value axis. |
| `emptyLabel` | `string` | `"Waiting for data"` | Shown before the first point. |
| `ref` | `Ref<HTMLElement>` | – | Forwarded to the figure. |
| `className` | `string` | – | Extra class on the figure. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Tab | Focuses the plot, holds the view, and reads the newest visible point. |
| ArrowLeft / ArrowRight | Previous or next point. |
| PageUp / PageDown | Ten points back or forward. |
| Home / End | Oldest or newest visible point. |
| Space / Enter | Pauses or resumes the stream. |
| Escape | Clears the reading and resumes. |

### Accessibility

- The current value is text with an accessible name; the rolling digits are aria-hidden.
- The status button is a toggle with aria-pressed and shows live or paused with a shape and a label, never colour alone.
- Anomalies are announced once in a polite live region as they arrive; point readings are announced as the keyboard moves.
- A visually hidden table lists the latest twenty readings with their notes.

### Motion

- The line scrolls continuously at the display rate; the head interpolates between readings, so new points slide in rather than pop.
- The value axis eases toward the visible range, so gridlines slide instead of jumping.
- Anomaly markers and tags pop in with one overshoot as the head reaches them.
- Resuming glides from the held view back to live.
- Reduced motion stops the scroll: the chart redraws only when a reading arrives, without interpolation or pops.

### Responsive behavior

- The canvas fills its container at the device pixel ratio and redraws on resize.
- Time labels thin out as the plot narrows.
- Touch reads points with a press and drag, which also holds the view.

### Performance

- One canvas, one requestAnimationFrame loop, stopped off screen and in hidden tabs.
- Only points inside the window are drawn, found by binary search.
- Theme tokens are resolved from hidden probes a few times a second, not every frame.

### Notes for AI

- Choose it for one live measure where the last seconds or minutes matter: latency, throughput, queue depth, active users.
- Set interval to the feed's cadence and windowMs to a few dozen points; trim the array to a few windows.
- Flag anomalies on the data itself with a short tag; the chart does not detect them.
- For history or several series, use line-chart or brush-chart instead.

### Related

- [Line chart](https://uiarc.dev/components/line-chart/markdown): A multi-series line chart with a gliding crosshair, legend toggles, and paths that morph between ranges.
- [Brush chart](https://uiarc.dev/components/brush-chart/markdown): A dense time series with an overview strip: drag a window to zoom, resize it by its handles, and read events in place.
- [Sparkline](https://uiarc.dev/components/sparkline/markdown): Show a compact trend beside a value.
- [Animated counter](https://uiarc.dev/components/animated-counter/markdown): Give changing totals a clear sense of movement.

### Also in advanced charts

- [Sunburst](https://uiarc.dev/components/sunburst/markdown): A hierarchy in rings: click a segment and every arc swings around it as the new centre, with a breadcrumb back and a rolling total.
- [Sankey flow](https://uiarc.dev/components/sankey-flow/markdown): Flows between stages as ribbons with drifting particles; hover any node or ribbon to pour its share through the whole journey.
- [Funnel chart](https://uiarc.dev/components/funnel-chart/markdown): A tapered conversion funnel with drop-off at every step, a device split that morphs the band, and dots that stream through it.
- [Radar chart](https://uiarc.dev/components/radar-chart/markdown): Two or three profiles on one web: shapes morph when you swap a profile, and a sweep across the axes compares values in place.
- [Race bar chart](https://uiarc.dev/components/race-bar-chart/markdown): A ranking over time: bars overtake each other on springs, values count up, and a timeline you can play or scrub.
- [Data grid](https://uiarc.dev/components/data-grid/markdown): A spreadsheet grid with range selection, inline editing, a fill handle, and animated sorting.

### Guidance for AI tools

Realtime stream: A live line that scrolls at 60fps as readings arrive, holds still on hover to read, and pops a marker on every anomaly. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Race bar chart

> A ranking over time: bars overtake each other on springs, values count up, and a timeline you can play or scrub.

- Type: Component (data)
- Access: Arc Pro
- Page: https://uiarc.dev/components/race-bar-chart
- Markdown: https://uiarc.dev/components/race-bar-chart/markdown
- Source file: `registry/components/race-bar-chart/race-bar-chart.tsx`
- Dependencies: motion, lucide-react
- Keywords: data, chart, new, bar chart race, racing bars, ranking over time, animated bar chart, leaderboard, timeline, data story

### When to use

- Showing how the leaders of a ranking change across many periods.
- A launch or recap moment where the motion itself is the point.
- Letting people scrub to any period and read exact values.

### When not to use

- Use line-chart when exact trends over time matter more than rank.
- Use bar-chart for a single period's comparison.
- Avoid for dashboards people glance at; autoplay competes with other content.

### Installation

Race bar chart is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/race-bar-chart
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { RaceBarChart } from "@/components/arc/race-bar-chart/race-bar-chart";

const items = [
  { id: "chair", label: "Oak lounge chair", group: "furniture" },
  { id: "lamp", label: "Mushroom lamp", group: "lighting" },
];
const frames = [
  { period: "January", values: { chair: 14000, lamp: 66000 } },
  { period: "February", values: { chair: 30000, lamp: 128000 } },
];

export function ProductRace() {
  return <RaceBarChart items={items} frames={frames} groups={[{ id: "furniture", label: "Furniture" }, { id: "lighting", label: "Lighting" }]} label="Revenue by product" highlight="chair" />;
}
```

### API reference

#### RaceBarChart

A bar chart race: bars overtake each other on springs as values grow, numbers count continuously, the period rolls in large type, and a timeline plays, pauses, and scrubs through time.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `items` (required) | `{ id: string; label: string; group?: string }[]` | – | The things being ranked. A stable id keeps each bar's identity across frames. |
| `frames` (required) | `{ period: string; values: Record<string, number> }[]` | – | One frame per period, in order. Missing ids count as zero. |
| `label` (required) | `string` | – | What is ranked. Names the chart for assistive technology. |
| `groups` | `{ id: string; label: string }[]` | – | Names and order of the groups. The first four take the series hues and a legend appears; without groups every bar takes the first hue. |
| `formatValue` | `(value: number) => string` | – | Formats values on bars, in the tooltip, and in the table. Defaults to a compact number. |
| `formatTick` | `(value: number) => string` | – | Formats the value axis. |
| `bars` | `number` | `8` | Bars shown at once. Items below the cut slide out of view. |
| `frame` | `number` | – | Controlled frame index. A new value glides the race there. |
| `defaultFrame` | `number` | `0` | Initial frame when uncontrolled. |
| `onFrameChange` | `(index: number) => void` | – | Called when the shown period changes. |
| `playing` | `boolean` | – | Controlled playback. |
| `defaultPlaying` | `boolean` | `false` | Initial playback when uncontrolled. |
| `onPlayingChange` | `(playing: boolean) => void` | – | Called when playback starts or stops. |
| `autoPlay` | `boolean` | `true` | Starts playing the first time the chart scrolls into view. Ignored with reduced motion. |
| `frameDuration` | `number` | `1400` | Milliseconds per period while playing. |
| `loop` | `boolean` | `false` | Rewinds to the first period after the last and keeps playing. |
| `highlight` | `string` | – | Item id whose name and value are emphasized, such as your own product. |
| `className` | `string` | – | Extra class on the root figure. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Space / Enter | Plays or pauses. At the end, replays from the start. |
| ArrowLeft / ArrowRight | Steps one period back or forward; the race glides there. |
| ArrowUp / ArrowDown | Moves the reading through the bars by rank and shows the tooltip. |
| Home / End | Jumps to the first or last period. |
| Escape | Clears the reading. |

### Accessibility

- The plot is a focusable group with a description of its keys; the timeline is role="slider" with the period as aria-valuetext.
- Stepping announces the period and the leader through a polite live region; reading a bar announces its name, rank, and value.
- A visually hidden table lists every item's value for every period.
- Group hue is never the only cue: every bar carries its name and value.

### Motion

- Time is continuous: values interpolate between periods, so bars grow smoothly and numbers count rather than jump.
- Rank changes move each row on its own spring, so overtakes read as one continuous slide; bars entering the top set rise from below and fade in.
- The drawn clock follows the requested time on a critically damped spring, so steps glide and a replay sweeps back through every period.
- Axis ticks glide with the scale and crossfade when the step changes; the period label rolls in with a short blur.
- Playback pauses while the chart is off screen. Reduced motion skips autoplay, steps periods without interpolation, and places bars immediately.

### Responsive behavior

- Below 400px names move inside the bars so bar length keeps its room; values sit past the name when a bar is short.
- The tick count adapts to the plot width and the period label steps down a size on small screens.
- The timeline is a 36px tall touch target and scrubs with a finger.

### Performance

- One requestAnimationFrame loop writes transforms, widths, and text straight to the DOM; React renders only on period changes.
- The loop sleeps when paused and settled.

### Notes for AI

- Choose it for a ranking that changes over time, told as a story: top products, cities, or accounts month by month.
- Pass cumulative values (year to date) for a race that only grows, or raw values for a ranking that rises and falls.
- Keep items to about 20 and bars to 6 to 10; the table carries the rest.
- Colors come from the shared --series-1 to --series-4 tokens in foundation.css: series 1 is the accent itself and series 2 to 4 rotate its hue, validated all-pairs for color vision deficiency across every accent in light and dark. Override the tokens on any ancestor to rebrand.

### Related

- [Bar chart](https://uiarc.dev/components/bar-chart/markdown): Compare one measure across days and scrub any bar for its value.
- [Line chart](https://uiarc.dev/components/line-chart/markdown): A multi-series line chart with a gliding crosshair, legend toggles, and paths that morph between ranges.
- [Streamgraph](https://uiarc.dev/components/streamgraph/markdown): Layered streams on a wiggle baseline that morph between ranges, with a layer you can isolate and read week by week.
- [Slope chart](https://uiarc.dev/components/slope-chart/markdown): Before and after on two axes: lines draw in, rank moves sit beside each value, and switching datasets slides every line to its new slope.

### Also in advanced charts

- [Sunburst](https://uiarc.dev/components/sunburst/markdown): A hierarchy in rings: click a segment and every arc swings around it as the new centre, with a breadcrumb back and a rolling total.
- [Sankey flow](https://uiarc.dev/components/sankey-flow/markdown): Flows between stages as ribbons with drifting particles; hover any node or ribbon to pour its share through the whole journey.
- [Funnel chart](https://uiarc.dev/components/funnel-chart/markdown): A tapered conversion funnel with drop-off at every step, a device split that morphs the band, and dots that stream through it.
- [Radar chart](https://uiarc.dev/components/radar-chart/markdown): Two or three profiles on one web: shapes morph when you swap a profile, and a sweep across the axes compares values in place.
- [Realtime stream](https://uiarc.dev/components/realtime-stream/markdown): A live line that scrolls at 60fps as readings arrive, holds still on hover to read, and pops a marker on every anomaly.
- [Data grid](https://uiarc.dev/components/data-grid/markdown): A spreadsheet grid with range selection, inline editing, a fill handle, and animated sorting.

### Guidance for AI tools

Race bar chart: A ranking over time: bars overtake each other on springs, values count up, and a timeline you can play or scrub. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Data grid

> A spreadsheet grid with range selection, inline editing, a fill handle, and animated sorting.

- Type: Component (data)
- Access: Arc Pro
- Page: https://uiarc.dev/components/data-grid
- Markdown: https://uiarc.dev/components/data-grid/markdown
- Source file: `registry/components/data-grid/data-grid.tsx`
- Dependencies: motion, lucide-react, @radix-ui/react-dropdown-menu, @radix-ui/react-popover
- Keywords: data, table, spreadsheet, editing, react data grid, spreadsheet component, editable table, excel like grid, inline cell editing, copy paste from excel, fill handle, virtualized table, pinned columns, column filters

### When to use

- Editing many values in place like a spreadsheet, such as budgets, price lists, or inventory.
- Data people move to and from Excel or Google Sheets with copy and paste.
- Work that needs range selection, a fill handle, fill down, and undo.
- Large tables, up to tens of thousands of rows, that people filter, sort, group with subtotals, and total.
- Server data too large to send at once, loaded in blocks as people scroll through a dataSource.
- Finance tables with many period columns, date columns, and exports people open in Excel.
- Bulk work on checked rows: copy, CSV export, delete, or your own actions.

### When not to use

- Use sortable-data-table for read-only records with sorting and row selection.
- Use a form when people edit one record at a time.
- Use a card list or card grid when each record needs rich content like images or long text.

### Installation

Data grid is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/data-grid
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { useState } from "react";
import { Archive } from "lucide-react";
import { DataGrid, type DataGridColumn, type DataGridRow, type DataGridSort } from "@/components/arc/data-grid/data-grid";

const columns: DataGridColumn[] = [
  { key: "item", label: "Item", width: 180, pinned: true },
  { key: "status", label: "Status", type: "select", options: ["Planned", "Active", "Done"] },
  { key: "q1", label: "Q1", type: "currency" },
  { key: "q2", label: "Q2", type: "currency" },
  { key: "margin", label: "Margin", type: "percent", decimals: 1, editable: false },
  { key: "notes", label: "Notes", hidden: true, aggregate: "count" },
];

export function Budget() {
  const [rows, setRows] = useState<DataGridRow[]>([
    { id: "r1", item: "Design", status: "Active", q1: 12000, q2: 14500, margin: 32.5, notes: "" },
    { id: "r2", item: "Hosting", status: "Planned", q1: 3200, q2: 3400, margin: 18, notes: "Annual plan" },
  ]);
  const [sort, setSort] = useState<DataGridSort[]>([{ key: "q1", dir: "desc" }]);
  return (
    <DataGrid
      label="Budget"
      columns={columns}
      rows={rows}
      onRowsChange={setRows}
      sort={sort}
      onSortChange={setSort}
      maxHeight={480}
      exportFileName="budget-2026"
      bulkActions={[{ label: "Archive", icon: <Archive size={16} aria-hidden />, onAction: checked => console.log(checked.map(r => r.id)) }]}
    />
  );
}
```

### API reference

#### DataGrid

A spreadsheet grid for editing tabular data in place. It has range selection, a fill handle, Excel and Sheets clipboard, undo, multi-column sort, a filter row, pinned and hidden columns, row checks with bulk actions, a totals row, and virtualized rows. Every piece of view state works controlled or uncontrolled.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `columns` (required) | `DataGridColumn[]` | – | Column definitions in definition order. Pinned columns are drawn first. |
| `label` (required) | `string` | – | Accessible name for the grid. Also names the exported CSV file. |
| `rows` | `DataGridRow[]` | – | Controlled rows. Pair with onRowsChange. |
| `defaultRows` | `DataGridRow[]` | – | Starting rows when uncontrolled. |
| `onRowsChange` | `(rows: DataGridRow[]) => void` | – | Called with the full row list after every edit, fill, paste, cut, clear, delete, undo, or redo. |
| `maxHeight` | `number` | `400` | Tallest the scrolling area grows before it scrolls, in px. |
| `sort` | `DataGridSort[]` | – | Controlled sort keys in priority order. |
| `defaultSort` | `DataGridSort[]` | `[]` | Starting sort keys when uncontrolled. |
| `onSortChange` | `(sort: DataGridSort[]) => void` | – | Called when a header click, Shift-click, or header menu changes the sort. |
| `filters` | `DataGridFilters` | – | Controlled column filters, keyed by column key. |
| `defaultFilters` | `DataGridFilters` | `{}` | Starting filters when uncontrolled. The filter row starts open when any filter is set. |
| `onFiltersChange` | `(filters: DataGridFilters) => void` | – | Called when a filter changes or all filters are cleared. |
| `selectedRowIds` | `string[]` | – | Controlled checked row ids. |
| `defaultSelectedRowIds` | `string[]` | `[]` | Starting checked row ids when uncontrolled. |
| `onSelectedRowIdsChange` | `(ids: string[]) => void` | – | Called with checked ids in data order. |
| `hiddenColumns` | `string[]` | – | Controlled hidden column keys. |
| `defaultHiddenColumns` | `string[]` | – | Starting hidden keys. Defaults to columns with hidden: true. |
| `onHiddenColumnsChange` | `(keys: string[]) => void` | – | Called when the columns menu or a header menu hides or shows a column. |
| `pinnedColumns` | `string[]` | – | Controlled pinned column keys. |
| `defaultPinnedColumns` | `string[]` | – | Starting pinned keys. Defaults to columns with pinned: true, or the first column when no column sets pinned. |
| `onPinnedColumnsChange` | `(keys: string[]) => void` | – | Called when a header menu pins or unpins a column. |
| `density` | `"compact" \| "standard" \| "comfortable"` | – | Controlled row density: 32, 40, or 48px rows. |
| `defaultDensity` | `"compact" \| "standard" \| "comfortable"` | `"standard"` | Starting density when uncontrolled. |
| `onDensityChange` | `(density: DataGridDensity) => void` | – | Called when the density menu changes. |
| `rowSelection` | `boolean` | `true` | Shows the row gutter with row numbers and checkboxes. |
| `rowNumbers` | `boolean` | `true` | Shows the row number in the gutter. When false the gutter narrows to 40px and its checkboxes always show. With rowSelection off there is no gutter either way. |
| `selectionStats` | `boolean` | `true` | Shows the active cell address and the Count, Sum, and Average of the selected cells in the status bar. Status messages, such as Undo after a delete, show either way. |
| `toolbar` | `boolean` | `true` | Shows the toolbar with search, undo and redo, filters, columns, density, and export. |
| `totals` | `boolean` | `true` | Shows the sticky totals row. It always covers every row the filters keep, including rows inside collapsed groups. |
| `groupBy` | `string[]` | – | Controlled group-by column keys, outermost first. Each group row shows a toggle, its value and row count, and a subtotal under every column whose aggregate is not none. |
| `defaultGroupBy` | `string[]` | `[]` | Starting group-by keys when uncontrolled. |
| `onGroupByChange` | `(keys: string[]) => void` | – | Called when a header menu starts or stops grouping by a column. |
| `exportFormats` | `("csv" \| "xlsx")[]` | `["csv"]` | Formats Export offers. With more than one, Export opens a menu. xlsx keeps number, currency, percent, and date formats, column widths, a frozen header and pinned columns, bold totals, and groups as outlined rows with SUBTOTAL formulas. |
| `dataSource` | `DataGridDataSource` | – | Loads rows from a server one block at a time as people scroll, instead of rows. Sort, filters, and search are sent with each request. Keep it stable with useMemo. A grid with a data source is read only, does not group, hides select all, and exports only checked rows. |
| `bulkActions` | `DataGridBulkAction[]` | – | Extra actions for checked rows, shown between Export and Delete. |
| `canDeleteRows` | `boolean` | `true` | Shows Delete for checked rows. Deleting can be undone. |
| `exportFileName` | `string` | – | Export file name without the extension. Defaults to a slug of label. |
| `loading` | `boolean` | `false` | Shows six placeholder rows and sets aria-busy. |
| `emptyMessage` | `string` | `"No rows yet"` | Shown when there are no rows at all. Filtered-out rows show "No rows match" with Clear filters. |

#### DataGridColumn

One column definition.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `key` (required) | `string` | – | Row field this column reads and writes. |
| `label` (required) | `string` | – | Header text. Also used in CSV and copied headers. |
| `width` | `number` | `140` | Starting width in px. The last column absorbs spare width on a wide grid. |
| `minWidth` | `number` | `72` | Narrowest a resize can reach. Resizing stops at 560px. |
| `type` | `"text" \| "number" \| "currency" \| "percent" \| "select" \| "date"` | `"text"` | Number, currency, and percent align right, parse typed numbers, and total in the footer. Select picks from options. Date stores an ISO day string such as "2026-01-31", shows it formatted, edits with a calendar, and refuses text that is not a real day. |
| `dateFormat` | `Intl.DateTimeFormatOptions` | `{ month: "short", day: "numeric", year: "numeric" }` | How a date column shows its days, in en-US and UTC so a day never shifts with the time zone. |
| `decimals` | `number` | `0` | Decimal places when formatting numeric values. |
| `editable` | `boolean` | `true` | false makes the column read only. Edits, pastes, fills, and clears skip it. |
| `options` | `string[]` | – | Choices for a select column. Defaults to the distinct values already in the column. Also sets the sort order. |
| `pinned` | `boolean` | – | Starts pinned to the left edge. When no column sets this, the first column is pinned. |
| `hidden` | `boolean` | – | Starts hidden. People can show it again from the columns menu. |
| `aggregate` | `"sum" \| "average" \| "min" \| "max" \| "count" \| "none"` | – | What the totals row shows. Defaults to sum for number and currency, average for percent, none otherwise. |
| `sortable` | `boolean` | `true` | false disables the header sort button and the sort menu items. |
| `filterable` | `boolean` | `true` | false leaves the filter cell empty and drops Filter from the header menu. |
| `groupable` | `boolean` | – | Offers Group by in the header menu. Defaults to true for text, select, and date columns and false for numeric ones. |

#### DataGridBulkAction

An extra toolbar action for checked rows.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` (required) | `string` | – | Button text. Also the React key, so keep it unique. |
| `icon` | `ReactNode` | – | Icon before the label. The label hides below 640px of grid width. |
| `tone` | `"danger"` | – | Draws the button in the danger color. |
| `onAction` (required) | `(rows: DataGridRow[]) => void` | – | Receives the checked rows in data order. |

#### DataGridDataSource

Server rows for DataGrid. The grid asks for the blocks that cover the rows in view, keeps up to 40 blocks, and starts over when sort, filters, or search change.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `getRows` (required) | `(request: DataGridRowsRequest) => Promise<DataGridRowsResult>` | – | Returns one block. request has start (inclusive), end (exclusive), sort, filters, search, and an AbortSignal that fires when the query changes. Resolve with rows, rowCount for the whole filtered set, and optional totals keyed by column key. |
| `blockSize` | `number` | `100` | Rows per request. |

#### Types

Exported from data-grid.tsx.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `DataGridValue` | `string \| number \| null` | – | A cell value. Empty number cells store null. |
| `DataGridRow` | `{ id: string; [key: string]: DataGridValue }` | – | A row. id must be unique and stable. |
| `DataGridSort` | `{ key: string; dir: "asc" \| "desc" }` | – | One sort key. |
| `DataGridFilters` | `Record<string, string \| string[]>` | – | Text and number columns take a query string. Select columns take the list of values to keep. |
| `DataGridColumnType` | `"text" \| "number" \| "currency" \| "percent" \| "select" \| "date"` | – | Column type. |
| `DataGridRowsRequest` | `{ start: number; end: number; sort: DataGridSort[]; filters: DataGridFilters; search: string; signal: AbortSignal }` | – | What a data source is asked for. |
| `DataGridRowsResult` | `{ rows: DataGridRow[]; rowCount: number; totals?: Record<string, number \| null> }` | – | What a data source returns for one block. |
| `DataGridExportFormat` | `"csv" \| "xlsx"` | – | An export format. |
| `DataGridExportNode` | `DataGridRow \| { label: string; children: DataGridExportNode[] }` | – | A row or a group of rows for toXlsx. |
| `DataGridAggregate` | `"sum" \| "average" \| "min" \| "max" \| "count" \| "none"` | – | Totals row aggregate. |
| `DataGridDensity` | `"compact" \| "standard" \| "comfortable"` | – | Row density. |
| `DataGridProps` | `interface` | – | Props of DataGrid. |

#### data-grid-model helpers

Pure functions exported from data-grid-model.ts, usable on the server or in tests.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `format` | `(value: DataGridValue \| undefined, column: DataGridColumn) => string` | – | Display text: en-US grouping, $ for currency, % for percent, a true minus sign for negatives. |
| `parse` | `(text: string, column: DataGridColumn, options?: string[]) => { ok: true; value: DataGridValue } \| { ok: false }` | – | Reads typed or pasted text. Numbers accept $, %, commas, spaces, and accounting parentheses. Select values match options without case. |
| `parseDay / formatDay / isIsoDay` | `(text: string) => string \| null / (iso: string, options?) => string / (value: unknown) => boolean` | – | Date helpers. parseDay reads 2026-01-31, 2026/1/31, Jan 31 2026, or 31 January 2026 and refuses all-number forms like 01/02/2026, which read differently by country. |
| `dateFilter` | `(expression: string) => ((iso: string) => boolean) \| null \| "invalid"` | – | Parses a day, month (2026-03), or year (2026) with > >= < <= = !=, or a range like 2026-01-01..2026-03-31. |
| `toXlsx` | `(columns: DataGridColumn[], nodes: DataGridExportNode[], options?: DataGridXlsxOptions) => Uint8Array` | – | From data-grid-xlsx.ts. Writes an .xlsx workbook with no dependencies. options: sheetName, freezeColumns, totals, widths. Files are stored without compression. |
| `numberFilter` | `(expression: string) => ((value: number) => boolean) \| null \| "invalid"` | – | Parses >100, >=100, <5, !=0, =12, 12, or a range like 10..50. |
| `rowMatcher` | `(columns, filters, search, searchColumns?) => ((row: DataGridRow) => boolean) \| null` | – | One predicate for all filters and the quick search. |
| `sortRows` | `(rows: DataGridRow[], sort: DataGridSort[], columns: DataGridColumn[]) => DataGridRow[]` | – | Stable multi-key sort. Empty cells sink to the bottom either way. |
| `aggregate / defaultAggregate` | `(rows, column, kind) => number \| null / (column) => DataGridAggregate` | – | The totals row math and its default per column type. |
| `toTsv / parseTsv / toHtml / parseHtmlTable` | `(matrix: string[][]) => string / (text: string) => string[][] / ...` | – | Clipboard formats that match Excel and Google Sheets, including quoted cells with tabs or line breaks. |
| `toCsv` | `(columns: DataGridColumn[], rows: DataGridRow[]) => string` | – | RFC 4180 CSV with a byte order mark so Excel reads UTF-8. |
| `extend` | `(source: DataGridValue[], count: number, forward: boolean, type?: DataGridColumnType) => DataGridValue[]` | – | Fill handle values. An evenly spaced number run continues its series. In a date column, days continue by days, or by months when they share a day of the month or are all month ends. Anything else repeats. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Arrow keys | Move the active cell. |
| Shift + arrows | Extend the range from the active cell. |
| Cmd/Ctrl + arrows | Jump to the first or last row or column. Add Shift to extend the range. |
| Home / End | Move to the first or last column in the row. |
| Cmd/Ctrl + Home / End | Move to the first or last cell of the grid. |
| PageUp / PageDown | Move by one visible page of rows. |
| Cmd/Ctrl + A | Select every cell. |
| Ctrl + Space | Extend the range to the whole of its columns. |
| Shift + Space | Check or uncheck the rows in the range. Needs rowSelection. |
| Enter / F2 | Edit the active cell, keeping its value. Arrow keys then move the caret. |
| Any character | Start editing and replace the value. Arrow keys then commit and move, like Excel. |
| Alt + ArrowDown | On a select cell, open its option list. |
| Enter / Shift + Enter (editing) | Commit and move down or up. An invalid value stays open and is marked. |
| Tab / Shift + Tab (editing) | Commit and move right or left. |
| ArrowUp / ArrowDown (option list) | Move through select options. Enter or Tab picks the highlighted one. |
| Alt + ArrowDown (date editing) | Open the calendar and move focus into it. Arrow keys pick a day, Enter saves it, Escape returns to the text. |
| Escape (editing) | Close the option list or calendar, or cancel the edit. |
| Escape | Collapse the range to the active cell, or else clear checked rows. |
| Delete / Backspace | Clear the range. Read-only cells are skipped. |
| Cmd/Ctrl + D | Fill down: copy the top row of the range into the rows below. |
| Cmd/Ctrl + C / X / V | Copy, cut, or paste. Works with Excel, Google Sheets, and Numbers. |
| Cmd/Ctrl + Z | Undo. |
| Cmd/Ctrl + Shift + Z / Cmd/Ctrl + Y | Redo. |
| Shift + click header | Add the column as the next sort key. Plain click cycles ascending, descending, off. |
| Alt + ArrowLeft / ArrowRight (header) | Narrow or widen the column by 16px. |
| Enter / ArrowDown (search or filter input) | Return focus to the grid. |
| Escape (search or filter input) | Clear the input, or return to the grid when it is empty. |

### Accessibility

- The grid is one focusable role="grid" with aria-multiselectable, aria-rowcount, aria-colcount, and aria-busy while loading. The active cell is exposed through aria-activedescendant, not moving focus.
- Rows and cells carry aria-rowindex and aria-colindex, so counts stay right while rows are virtualized. The active and editing rows stay mounted when scrolled away.
- Cells report aria-selected and aria-readonly. Rows report aria-selected when checked.
- Headers are role="columnheader" with aria-sort. The sort button label names the direction, the sort priority, and the Alt + arrow resize keys.
- The cell editor is labelled by column and row name and sets aria-invalid on a bad value. On select columns it is a combobox that controls a listbox, with aria-activedescendant on the highlighted option.
- Row checkboxes are role="checkbox" and stay out of the tab order; the select-all box in the header is tabbable and shows a mixed state.
- Number filter inputs describe their syntax and set aria-invalid on an unreadable expression. Select filters open a labelled checklist.
- Edits, sorts, checks, copies, pastes, fills, undo, and redo are announced in a polite live region. The row count is also a polite live region.
- Totals cells carry a full aria-label, such as "Q1 sum $15,200".
- With groupBy the grid becomes role="treegrid". Group rows carry aria-level and aria-expanded, their toggle is a button that names the group, row count, and action, and subtotal cells carry full labels. Data rows carry aria-level too.
- The date editor is a combobox with a dialog popup. The calendar opens in a portal so the grid never clips it, and focus returns to the cell when it closes.
- Scrolling columns outside the view are not rendered, but every cell keeps its aria-colindex, and the active and editing cells stay mounted.
- With a data source, rows still loading render as placeholder rows with aria-busy.

### Motion

- The selection rectangle and active cell spring between ranges on motionTokens.spring.snappy. Scrolling moves them at once, and resizing a column snaps them.
- After a sort, rows slide to their new place on the spring curve for 700ms, and rows arriving from off screen fade in.
- Pasted, filled, undone, and redone cells flash a wash that fades out over 0.9s.
- The toolbar swaps to bulk actions with a short slide, fade, and blur. Status messages enter the same way.
- Totals, the selection summary, and the checked count roll with animated-counter.
- An invalid edit shakes once. Menus and the option list fade and scale in from their anchor.
- A group's chevron turns on the spring curve as it opens and closes.
- Reduced motion jumps the selection, drops the row slide, the shake, the press scales, the chevron turn, and the skeleton pulse, and keeps short fades.

### Responsive behavior

- The grid scrolls in both directions inside maxHeight. The header and totals row stay sticky, and pinned columns and the row gutter stay on the left.
- Pinned columns are scaled down to about half of the grid width so a narrow grid still shows scrolling columns.
- Layout reacts to the grid's own width with container queries. Below 640px toolbar buttons become icons. Below 460px the row count and undo and redo buttons hide. Below 480px the status message wraps to its own line.
- On touch a pan scrolls the grid. A tap selects a cell on release, a second tap edits it, and only the fill handle takes over a touch drag.
- Row checkboxes and header menu buttons are always visible on devices without hover.

### Performance

- Rows are virtualized: only the visible rows plus 6 above and below render, each positioned with translateY. Rows are memoized, so scrolling and typing re-render only the rows they touch.
- Filters and search use useDeferredValue, so typing a filter stays responsive on large data.
- The sorted and filtered view is recomputed only when sort, filters, search, visible columns, or the set of row ids change, not on every edit.
- Select column options are derived from up to 200 distinct values when options is not given; pass options for large or wide data.
- Columns are virtualized too: pinned columns always render, and scrolling columns render only within about 240px of the view, updated every 64px of horizontal scroll.
- Group rows are computed with the view, not on every edit, so an edited row stays in its group until the next sort, filter, or grouping change. Subtotals update at once.
- A dataSource keeps up to 40 blocks and aborts requests that a sort, filter, or search change makes stale. Undo holds up to 100 full row snapshots.

### Notes for AI

- Choose it when people edit many values in place like a spreadsheet. Use sortable-data-table for read-only records. For rows that roll up under a shared value, such as journal lines by account and period, use groupBy.
- Every row needs a unique, stable id. Column keys map to row fields. Keep rows from onRowsChange to persist edits.
- Use number, currency, or percent for numeric data so parsing, right alignment, totals, and the status bar sum work. Store raw numbers, not formatted strings.
- Mark computed or locked columns editable: false. Give select columns options so pasted and typed values are checked against them.
- Copy writes tab separated text plus an HTML table with formatted values, so Excel and Sheets read typed numbers. Paste reads an HTML table first, then TSV with quoted cells. A selection that is a whole multiple of the clipboard is tiled; values that do not parse are skipped and reported.
- The bulk Copy button copies checked rows with a header row through navigator.clipboard, and Export downloads CSV of checked rows. The toolbar Export downloads all filtered rows in view order.
- A sort reorders once, like a spreadsheet. Editing a value does not re-sort or re-filter, so rows never jump under the cursor.
- Undo keeps 100 steps and covers edits, fills, pastes, clears, and row deletes. Sort, filter, and column changes are view state and are not undone.
- Text filters match accent-insensitive substrings; prefix = for an exact match or ! to exclude. The quick search matches every word across visible columns.
- Filtering, sorting, and grouping run on the client over the rows you pass. For data too large to send at once, pass a dataSource: the grid asks for blocks of rows as people scroll and sends sort, filters, and search with each request.
- Use a date column for days. Values stay ISO day strings, so they round-trip with no time zone shift; sort and filter compare them as days, and the fill handle continues a daily or monthly series.
- Grouping reuses each column's aggregate for its subtotals, so one setting drives the group rows and the totals row. A grouped .xlsx export writes SUBTOTAL formulas, so Excel never counts a subtotal twice.
- For a small form table, turn off rowNumbers when rows already carry their own number, and selectionStats when the address and counts mean nothing to the reader.

### Related

- [Sortable data table](https://uiarc.dev/components/sortable-data-table/markdown): Compare structured records with sortable columns.
- [Filter toolbar](https://uiarc.dev/components/filter-toolbar/markdown): Keep collection filters close and easy to reset.
- [Date picker](https://uiarc.dev/components/date-picker/markdown): Choose a date without losing context.
- [Animated counter](https://uiarc.dev/components/animated-counter/markdown): Give changing totals a clear sense of movement.
- [Pagination](https://uiarc.dev/components/pagination/markdown): Move through a long collection with clear bounds.

### Also in advanced charts

- [Sunburst](https://uiarc.dev/components/sunburst/markdown): A hierarchy in rings: click a segment and every arc swings around it as the new centre, with a breadcrumb back and a rolling total.
- [Sankey flow](https://uiarc.dev/components/sankey-flow/markdown): Flows between stages as ribbons with drifting particles; hover any node or ribbon to pour its share through the whole journey.
- [Funnel chart](https://uiarc.dev/components/funnel-chart/markdown): A tapered conversion funnel with drop-off at every step, a device split that morphs the band, and dots that stream through it.
- [Radar chart](https://uiarc.dev/components/radar-chart/markdown): Two or three profiles on one web: shapes morph when you swap a profile, and a sweep across the axes compares values in place.
- [Realtime stream](https://uiarc.dev/components/realtime-stream/markdown): A live line that scrolls at 60fps as readings arrive, holds still on hover to read, and pops a marker on every anomaly.
- [Race bar chart](https://uiarc.dev/components/race-bar-chart/markdown): A ranking over time: bars overtake each other on springs, values count up, and a timeline you can play or scrub.

### Guidance for AI tools

Data grid: A spreadsheet grid with range selection, inline editing, a fill handle, and animated sorting. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Sortable data table

> Compare structured records with sortable columns.

- Type: Component (data)
- Access: Free, open source
- Page: https://uiarc.dev/components/sortable-data-table
- Markdown: https://uiarc.dev/components/sortable-data-table/markdown
- Registry item: https://uiarc.dev/r/sortable-data-table.json
- Source file: `registry/components/sortable-data-table/sortable-data-table.tsx`
- Dependencies: motion, lucide-react
- Keywords: data, table, react data table, sortable table, table with row selection, animated table sort, responsive table, checkbox table

### When to use

- Tabular records people sort and select, such as projects, invoices, or users.
- Tables that need Shift-click range selection and a count line with Clear.

### When not to use

- Use data-grid when people edit cells like a spreadsheet.
- Use timeline for chronological activity.
- Use reorderable-list when people set the order by hand.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/sortable-data-table
pnpm dlx shadcn@latest add @uiarc/sortable-data-table
yarn dlx shadcn@latest add @uiarc/sortable-data-table
bunx --bun shadcn@latest add @uiarc/sortable-data-table
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/sortable-data-table.json
```

#### Manual

1. Install the dependencies:

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

2. Copy the source into your project. Main file: `registry/components/sortable-data-table/sortable-data-table.tsx`

   The source is in the registry item: https://uiarc.dev/r/sortable-data-table.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { SortableDataTable } from "@/components/arc/sortable-data-table/sortable-data-table";

const projects = [
  { id: "p1", name: "Harbour", owner: "Maya", budget: 42000 },
  { id: "p2", name: "Atlas", owner: "Leo", budget: 18500 },
];

export function Projects() {
  return (
    <SortableDataTable
      rows={projects}
      rowKey="id"
      caption="Projects"
      columns={[{ key: "name", label: "Name" }, { key: "owner", label: "Owner" }, { key: "budget", label: "Budget" }]}
      defaultSort={{ key: "name", direction: "asc" }}
      selectable
      itemName={{ one: "project", other: "projects" }}
    />
  );
}
```

### API reference

#### SortableDataTable

A generic table with sortable columns, optional row selection, and rows that glide when re-sorted.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `rows` (required) | `T[]` | – | Row objects. |
| `columns` (required) | `{ key: string; label: string; sortable?: boolean; render?: (value: unknown, row: T) => ReactNode; numeric?: boolean; width?: number \| string }[]` | – | Column definitions. Columns are sortable unless sortable is false; numeric is detected when every value is a number. |
| `rowKey` (required) | `keyof T \| ((row: T) => string)` | – | Stable key per row. |
| `caption` | `string` | `"Data table"` | Table caption, used as its accessible name. |
| `emptyMessage` | `string` | `"No rows to show"` | Shown when rows is empty. |
| `defaultSort` | `{ key: string; direction: "asc" \| "desc" }` | – | Sort applied on first render. |
| `onSortChange` | `(sort: SortState) => void` | – | Called when a header is pressed. |
| `selectable` | `boolean` | `false` | Adds a checkbox column, row click selection, and a count line with Clear. |
| `selectedKeys` | `string[]` | – | Controlled selection. |
| `defaultSelectedKeys` | `string[]` | – | Initial selection when uncontrolled. |
| `onSelectionChange` | `(keys: string[]) => void` | – | Called with the new selection. |
| `itemName` | `{ one: string; other: string }` | `{ one: "row", other: "rows" }` | Noun for the count line, as in "6 projects". |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| ArrowLeft / ArrowRight | Moves between sortable headers. |
| ArrowUp / ArrowDown | Moves between row checkboxes; down from Select all enters the rows. |
| Home / End | Jumps to the first or last header or row checkbox. |
| Enter / Space | Sorts by a header or toggles a checkbox. |
| Shift + click | Selects a range of rows. |
| Escape | Clears the selection. |

### Accessibility

- A native table with caption, scoped headers, and aria-sort on sortable columns.
- Sort buttons are labelled like "Sort by Budget, currently ascending"; the select all checkbox shows a mixed state.
- Sort and selection changes are announced through a role="status" region.

### Motion

- Rows glide to their new positions on a spring when the sort changes; the sort arrow flips.
- The selection count rolls and Clear fades in with a short blur.
- Reduced motion reorders instantly and fades the count.

### Responsive behavior

- Wider layouts scroll horizontally inside the table instead of the page.
- Below 620px each row folds into two lines, and the header becomes a scrolling strip of sort buttons with Select all pinned.
- Hover row fills apply only on hover-capable fine pointers.

### Performance

- Rows are not virtualized and each uses position layout animation for re-sorts; paginate long lists with pagination.
- Sorting runs client side over the rows you pass.

### Notes for AI

- Use for tabular records people sort and select. Use timeline for chronological activity and a plain list for simple items.
- Sorting is client side over the given rows; for server sorting, control defaultSort per fetch and page with pagination.
- Use render for badges, avatars, or formatted numbers inside cells.

### Related

- [Filter toolbar](https://uiarc.dev/components/filter-toolbar/markdown): Keep collection filters close and easy to reset.
- [Pagination](https://uiarc.dev/components/pagination/markdown): Move through a long collection with clear bounds.
- [Badge](https://uiarc.dev/components/badge/markdown): A small label for status, category, or metadata.
- [Empty state](https://uiarc.dev/components/empty-state/markdown): A useful next step when there is nothing to show yet.
- [Checkbox](https://uiarc.dev/components/checkbox/markdown): A binary choice with a precise, legible state.

### Also in tables

- [Tree table](https://uiarc.dev/components/tree-table/markdown): A table with nested rows, tri-state selection, hierarchy-preserving sort, and lazy-loaded children.
- [Tree view](https://uiarc.dev/components/tree-view/markdown): Navigate nested folders and structured content.
- [Reorderable list](https://uiarc.dev/components/reorderable-list/markdown): Organize items with direct drag and drop.
- [Code block](https://uiarc.dev/components/code-block/markdown): Present code with legible hierarchy and copy access.
- [JSON viewer](https://uiarc.dev/components/json-viewer/markdown): A collapsible JSON tree with search, paging for long arrays, and copy value or path.

### Guidance for AI tools

Sortable data table: Compare structured records with sortable columns. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Tree table

> A table with nested rows, tri-state selection, hierarchy-preserving sort, and lazy-loaded children.

- Type: Component (data)
- Access: Free, open source
- Page: https://uiarc.dev/components/tree-table
- Markdown: https://uiarc.dev/components/tree-table/markdown
- Registry item: https://uiarc.dev/r/tree-table.json
- Source file: `registry/components/tree-table/tree-table.tsx`
- Dependencies: motion, lucide-react, @radix-ui/react-checkbox
- Keywords: data, new, react tree table, treegrid, nested table rows, expandable table, hierarchical data table, tri-state checkbox tree, lazy load tree rows, file tree table

### When to use

- File or folder listings with size, owner, and modified columns.
- Budgets, org charts, or accounts where totals roll up through nested rows.
- Large trees whose deeper levels should load from the server on demand.

### When not to use

- Use tree-view for navigation trees without columns.
- Use data-grid or sortable-data-table for flat records.
- Use accordion when each item opens into free form content rather than child rows.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/tree-table
pnpm dlx shadcn@latest add @uiarc/tree-table
yarn dlx shadcn@latest add @uiarc/tree-table
bunx --bun shadcn@latest add @uiarc/tree-table
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/tree-table.json
```

#### Manual

1. Install the dependencies:

```bash
npm install motion lucide-react @radix-ui/react-checkbox
```

2. Copy the source into your project. Main file: `registry/components/tree-table/tree-table.tsx`

   The source is in the registry item: https://uiarc.dev/r/tree-table.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { TreeTable } from "@/components/arc/tree-table/tree-table";
import type { TreeTableColumn, TreeTableRow } from "@/components/arc/tree-table/tree-table";

type Item = { name: string; size: number; owner: string };

const columns: TreeTableColumn<Item>[] = [
  { id: "name", header: "Name", cell: item => item.name, sortValue: item => item.name, width: "minmax(0, 2fr)" },
  { id: "size", header: "Size", cell: item => `${item.size} MB`, sortValue: item => item.size, align: "end", width: "96px" },
  { id: "owner", header: "Owner", cell: item => item.owner, hideBelow: 520 },
];

export function Files({ rows }: { rows: TreeTableRow<Item>[] }) {
  return (
    <TreeTable
      label="Files"
      rows={rows}
      columns={columns}
      selectable
      rowLabel={item => item.name}
      defaultExpanded={["design"]}
      loadChildren={row => fetchChildren(row.id)}
      maxHeight={480}
    />
  );
}
```

### API reference

#### TreeTable

A table whose rows nest, with spring expand and collapse, indent guides, tri-state selection, hierarchy safe sorting, and lazy children.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `rows` (required) | `TreeTableRow<T>[]` | – | Top level rows: { id, data, children?, hasChildren? }. |
| `columns` (required) | `TreeTableColumn<T>[]` | – | Columns: { id, header, cell(data, context), sortValue?, width?, align?, hideBelow? }. The first shown column holds the tree. |
| `label` (required) | `string` | – | Accessible name of the table. |
| `expanded` | `string[]` | – | Controlled ids of expanded rows. |
| `defaultExpanded` | `string[]` | `[]` | Rows expanded at first when uncontrolled. |
| `onExpandedChange` | `(ids: string[]) => void` | – | Called when rows expand or collapse. |
| `selectable` | `boolean` | `false` | Adds a checkbox column. Checking a parent checks everything under it. |
| `selected` | `string[]` | – | Controlled ids of selected rows. |
| `defaultSelected` | `string[]` | `[]` | Rows selected at first when uncontrolled. |
| `onSelectedChange` | `(ids: string[]) => void` | – | Called with the new selection. Parents are added or removed to match their children. |
| `sort` | `TreeTableSort \| null` | – | Controlled sort: { columnId, direction: "ascending" \| "descending" }. |
| `defaultSort` | `TreeTableSort \| null` | `null` | Starting sort when uncontrolled. |
| `onSortChange` | `(sort: TreeTableSort \| null) => void` | – | Called as a header cycles ascending, descending, and off. |
| `loadChildren` | `(row: TreeTableRow<T>) => Promise<TreeTableRow<T>[]>` | – | Loads children of a row with hasChildren on first expand. A rejection shows a retry row. |
| `rowLabel` | `(data: T) => string` | – | Names a row for its checkbox, such as the file or team name. |
| `onRowActivate` | `(row: TreeTableRow<T>) => void` | – | Called when a row without children is clicked or gets Enter. Parent rows toggle instead. |
| `maxHeight` | `number \| string` | – | Caps the height; the header stays pinned while the body scrolls. |
| `emptyState` | `ReactNode` | `"Nothing to show"` | Shown when there are no rows. |
| `className` | `string` | – | Class on the root. |
| `ref` | `Ref<HTMLDivElement>` | – | The root element. |

#### collectExpandableIds

Returns the ids of every row whose children are known, for an external expand all.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `rows` (required) | `TreeTableRow<T>[]` | – | The tree to walk. |
| `loaded` | `Record<string, TreeTableRow<T>[]>` | – | Children loaded so far, keyed by parent id. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| ArrowDown / ArrowUp | Moves between visible rows. |
| ArrowRight | Expands a row, or moves to its first child when already open. |
| ArrowLeft | Collapses a row, or moves to its parent. |
| Home / End | Moves to the first or last visible row. |
| PageDown / PageUp | Moves ten rows. |
| * | Expands every sibling of the focused row. |
| Space | Toggles selection when selectable. |
| Enter | Toggles a parent, retries a failed load, or activates a leaf row. |
| Cmd/Ctrl+A | Selects or clears all rows when selectable. |

### Accessibility

- Follows the treegrid pattern: rows carry aria-level, aria-posinset, aria-setsize, and aria-expanded, with a single roving tabindex.
- Sortable headers expose aria-sort; checkboxes are named from rowLabel and show the indeterminate state for partly selected parents.
- Loading, load errors, sorting, and expand all are announced through a polite live region.
- If the focused row disappears (its parent collapsed), focus moves to the nearest visible ancestor.

### Motion

- Rows open and close on a height spring with a short stagger per sibling; sorting moves rows with a position layout animation.
- The chevron rotates on a snappy spring and the indent guide of the hovered or focused branch lights up.
- Reduced motion removes the height spring, stagger, and rotation; rows appear with an instant fade.

### Responsive behavior

- A ResizeObserver on the root hides any column whose hideBelow is wider than the table.
- Column widths are grid tracks, so minmax tracks shrink and the tree column truncates instead of overflowing.
- Hover styles apply only on hover-capable fine pointers; touch taps toggle and activate rows directly.

### Performance

- Every visible row renders and animates; it is not virtualized, so keep expanded trees to a few hundred rows.
- Selection normalization walks the whole known tree on each change; very large preloaded trees should load lazily.

### Notes for AI

- Use when hierarchical rows also need columns: file sizes, budgets by team, nested tasks. For a plain nested list with no columns use tree-view.
- Give every row a stable id. For lazy data, set hasChildren and leave children undefined, then pass loadChildren.
- Sort by giving columns a sortValue; siblings sort within their parent so the tree never breaks.
- Use hideBelow on secondary columns so narrow containers keep the tree column readable.

### Related

- [Tree view](https://uiarc.dev/components/tree-view/markdown): Navigate nested folders and structured content.
- [Data grid](https://uiarc.dev/components/data-grid/markdown): A spreadsheet grid with range selection, inline editing, a fill handle, and animated sorting.
- [Sortable data table](https://uiarc.dev/components/sortable-data-table/markdown): Compare structured records with sortable columns.
- [Checkbox](https://uiarc.dev/components/checkbox/markdown): A binary choice with a precise, legible state.

### Also in tables

- [Reorderable list](https://uiarc.dev/components/reorderable-list/markdown): Organize items with direct drag and drop.
- [Filter toolbar](https://uiarc.dev/components/filter-toolbar/markdown): Keep collection filters close and easy to reset.
- [Code block](https://uiarc.dev/components/code-block/markdown): Present code with legible hierarchy and copy access.
- [JSON viewer](https://uiarc.dev/components/json-viewer/markdown): A collapsible JSON tree with search, paging for long arrays, and copy value or path.

### Guidance for AI tools

Tree table: A table with nested rows, tri-state selection, hierarchy-preserving sort, and lazy-loaded children. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Tree view

> Navigate nested folders and structured content.

- Type: Component (data)
- Access: Free, open source
- Page: https://uiarc.dev/components/tree-view
- Markdown: https://uiarc.dev/components/tree-view/markdown
- Registry item: https://uiarc.dev/r/tree-view.json
- Source file: `registry/components/tree-view/tree-view.tsx`
- Dependencies: motion, lucide-react
- Keywords: data, navigation, react tree view, file tree, file explorer component, nested tree, folder tree, treeview keyboard navigation

### When to use

- Files, folders, and nested categories people expand and select.
- Side panels next to code-block or a detail view where selection drives content.
- Hierarchies that need full keyboard navigation with arrow keys.

### When not to use

- Use accordion for a few collapsible sections of content.
- Use breadcrumb to show the path to the current page.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/tree-view
pnpm dlx shadcn@latest add @uiarc/tree-view
yarn dlx shadcn@latest add @uiarc/tree-view
bunx --bun shadcn@latest add @uiarc/tree-view
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/tree-view.json
```

#### Manual

1. Install the dependencies:

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

2. Copy the source into your project. Main file: `registry/components/tree-view/tree-view.tsx`

   The source is in the registry item: https://uiarc.dev/r/tree-view.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { TreeView, type TreeNode } from "@/components/arc/tree-view/tree-view";

const files: TreeNode[] = [
  { id: "app", label: "app", children: [
    { id: "page", label: "page.tsx" },
    { id: "layout", label: "layout.tsx" },
  ] },
  { id: "readme", label: "README.md" },
];

export function Files() {
  return <TreeView nodes={files} defaultExpandedIds={["app"]} onSelect={node => open(node.id)} />;
}
```

### API reference

#### TreeView

A keyboard navigable file tree with animated expand and a gliding selection.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `nodes` (required) | `{ id: string; label: string; children?: TreeNode[]; icon?: ReactNode }[]` | – | Root nodes. Nodes with children are folders. |
| `defaultExpandedIds` | `string[]` | `[]` | Folders open on first render when uncontrolled. |
| `expandedIds` | `string[]` | – | Controlled open folders. |
| `onExpandedChange` | `(expandedIds: string[]) => void` | – | Called with the new open set. |
| `onSelect` | `(node: TreeNode) => void` | – | Called when a row is clicked or activated. |
| `aria-label` | `string` | `"File tree"` | Accessible name for the tree. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| ArrowDown / ArrowUp | Moves to the next or previous visible row. |
| ArrowRight | Opens a folder, or moves to its first child if open. |
| ArrowLeft | Closes an open folder, or moves to the parent. |
| Home / End | Moves to the first or last visible row. |
| Enter / Space | Selects the row and toggles a folder. |

### Accessibility

- Uses role="tree" and role="treeitem" with aria-level, aria-posinset, aria-setsize, aria-expanded, and aria-selected.
- Roving tabindex keeps one row in the tab order.
- Icons, chevrons, and branch lines are aria-hidden.

### Motion

- Opening a folder grows the space and staggers its children in; closing collapses rows smoothly.
- The selection highlight glides between rows and the chevron rotates on a snappy spring.
- Reduced motion shows and hides rows instantly.

### Responsive behavior

- Rows are a fixed 36px and labels ellipsize, so deep paths clip rather than overflow on narrow panels.
- Each level indents 18px, so very deep trees lose label space on mobile.
- Hover highlights apply only on hover-capable fine pointers.

### Performance

- Every visible row renders with position layout animation; nodes are not virtualized, so keep open folders reasonable.
- Closed folders do not render their children.

### Notes for AI

- Use for hierarchical data such as files or nested categories. Use accordion for a few collapsible sections of content.
- IDs must be unique across the whole tree. Control expandedIds when the open set must persist or sync with routing.

### Related

- [Accordion](https://uiarc.dev/components/accordion/markdown): Progressively reveal supporting information in place.
- [Code block](https://uiarc.dev/components/code-block/markdown): Present code with legible hierarchy and copy access.
- [Breadcrumb](https://uiarc.dev/components/breadcrumb/markdown): Show where a page sits in a hierarchy.

### Also in tables

- [Sortable data table](https://uiarc.dev/components/sortable-data-table/markdown): Compare structured records with sortable columns.
- [Tree table](https://uiarc.dev/components/tree-table/markdown): A table with nested rows, tri-state selection, hierarchy-preserving sort, and lazy-loaded children.
- [Reorderable list](https://uiarc.dev/components/reorderable-list/markdown): Organize items with direct drag and drop.
- [Filter toolbar](https://uiarc.dev/components/filter-toolbar/markdown): Keep collection filters close and easy to reset.
- [JSON viewer](https://uiarc.dev/components/json-viewer/markdown): A collapsible JSON tree with search, paging for long arrays, and copy value or path.

### Guidance for AI tools

Tree view: Navigate nested folders and structured content. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Reorderable list

> Organize items with direct drag and drop.

- Type: Component (data)
- Access: Free, open source
- Page: https://uiarc.dev/components/reorderable-list
- Markdown: https://uiarc.dev/components/reorderable-list/markdown
- Registry item: https://uiarc.dev/r/reorderable-list.json
- Source file: `registry/components/reorderable-list/reorderable-list.tsx`
- Dependencies: motion, lucide-react
- Keywords: data, interaction, react reorderable list, drag and drop list, sortable list, drag to reorder, keyboard reorder, framer motion reorder

### When to use

- Short user-ordered lists such as priorities or a playlist.
- Lists that must be reorderable by keyboard as well as by drag.

### When not to use

- Use sortable-data-table when order comes from a column.
- Use swipe-actions when rows need quick actions rather than reordering.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/reorderable-list
pnpm dlx shadcn@latest add @uiarc/reorderable-list
yarn dlx shadcn@latest add @uiarc/reorderable-list
bunx --bun shadcn@latest add @uiarc/reorderable-list
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/reorderable-list.json
```

#### Manual

1. Install the dependencies:

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

2. Copy the source into your project. Main file: `registry/components/reorderable-list/reorderable-list.tsx`

   The source is in the registry item: https://uiarc.dev/r/reorderable-list.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { useState } from "react";
import { ReorderableList } from "@/components/arc/reorderable-list/reorderable-list";

export function Priorities() {
  const [items, setItems] = useState([
    { id: "a", title: "Ship pricing page", detail: "Due Friday" },
    { id: "b", title: "Fix login redirect" },
    { id: "c", title: "Write changelog" },
  ]);
  return <ReorderableList items={items} onReorder={setItems} label="Priorities" />;
}
```

### API reference

#### ReorderableList

A vertical list reordered by dragging a grip handle or with arrow keys.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `items` (required) | `{ id: string; title: string; detail?: string }[]` | – | Items in their current order. |
| `onReorder` (required) | `(items: ReorderableItem[]) => void` | – | Called with the new order on drag or keyboard move. |
| `label` | `string` | `"Reorder items"` | Accessible name for the list. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| ArrowUp / ArrowDown | On a handle, moves that item one place up or down. |

### Accessibility

- Each handle is a button labelled like "Reorder Ship pricing page. Position 1 of 3. Use arrow keys."
- Focus stays on the moved item's handle after a keyboard move.
- Only the handle starts a drag, so text in rows stays selectable.

### Motion

- Rows lift slightly on press and neighbors slide on a spring while dragging.
- The position number rolls in the direction the row moved.
- Reduced motion keeps pointer following but lands rows instantly without lift.

### Responsive behavior

- Only the 36px grip starts a drag and it sets touch-action none, so the rest of the row scrolls the page normally on touch.
- Rows fill the width and keep a 56px minimum height.

### Performance

- Built on motion Reorder with layout animation per row; not virtualized, so keep lists short.

### Notes for AI

- Use for short, user-ordered lists such as priorities or playlist order. Use sortable-data-table when order comes from a column.
- It is controlled: store items in state and persist the order from onReorder.

### Related

- [Sortable data table](https://uiarc.dev/components/sortable-data-table/markdown): Compare structured records with sortable columns.
- [Swipe actions](https://uiarc.dev/components/swipe-actions/markdown): Reveal row actions with a swipe, or from the same actions in a menu.
- [Onboarding checklist](https://uiarc.dev/components/onboarding-checklist/markdown): Guide a new workspace through setup, one step at a time.

### Also in tables

- [Tree table](https://uiarc.dev/components/tree-table/markdown): A table with nested rows, tri-state selection, hierarchy-preserving sort, and lazy-loaded children.
- [Tree view](https://uiarc.dev/components/tree-view/markdown): Navigate nested folders and structured content.
- [Filter toolbar](https://uiarc.dev/components/filter-toolbar/markdown): Keep collection filters close and easy to reset.
- [Code block](https://uiarc.dev/components/code-block/markdown): Present code with legible hierarchy and copy access.
- [JSON viewer](https://uiarc.dev/components/json-viewer/markdown): A collapsible JSON tree with search, paging for long arrays, and copy value or path.

### Guidance for AI tools

Reorderable list: Organize items with direct drag and drop. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Filter toolbar

> Keep collection filters close and easy to reset.

- Type: Component (data)
- Access: Free, open source
- Page: https://uiarc.dev/components/filter-toolbar
- Markdown: https://uiarc.dev/components/filter-toolbar/markdown
- Registry item: https://uiarc.dev/r/filter-toolbar.json
- Source file: `registry/components/filter-toolbar/filter-toolbar.tsx`
- Dependencies: motion, lucide-react
- Keywords: data, filter, react filter toolbar, filter chips, add filter menu, faceted filters, filter bar, removable chips, table filters

### When to use

- Faceted filtering above tables and lists, with removable chips.
- Adding filters through a two step field then value menu.
- Views that pair with sortable-data-table and pagination for a full list page.

### When not to use

- Use chip-group for a fixed set of toggles.
- Use search-field for free text search.
- Use multi-select when one field takes several values in a form.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/filter-toolbar
pnpm dlx shadcn@latest add @uiarc/filter-toolbar
yarn dlx shadcn@latest add @uiarc/filter-toolbar
bunx --bun shadcn@latest add @uiarc/filter-toolbar
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/filter-toolbar.json
```

#### Manual

1. Install the dependencies:

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

2. Copy the source into your project. Main file: `registry/components/filter-toolbar/filter-toolbar.tsx`

   The source is in the registry item: https://uiarc.dev/r/filter-toolbar.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { useState } from "react";
import { FilterToolbar, type FilterChip } from "@/components/arc/filter-toolbar/filter-toolbar";

const fields = [
  { id: "status", label: "Status", options: ["Open", "Closed"] },
  { id: "owner", label: "Owner", options: ["Maya", "Leo"] },
];

export function IssueFilters() {
  const [filters, setFilters] = useState<FilterChip[]>([]);
  return (
    <FilterToolbar
      filters={filters}
      onRemove={id => setFilters(f => f.filter(x => x.id !== id))}
      onClearAll={() => setFilters([])}
      addFilter={{ fields, onAdd: chip => setFilters(f => [...f.filter(x => x.id !== chip.id), chip]) }}
    />
  );
}
```

### API reference

#### FilterToolbar

A row of removable filter chips with Clear all and an optional Add filter menu.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `filters` (required) | `{ id: string; label: string; value?: string }[]` | – | Applied filters, shown as chips. |
| `onRemove` (required) | `(id: string) => void` | – | Called when a chip's remove button is pressed. |
| `onClearAll` | `() => void` | – | Called by Clear all, which appears while any filter is applied. |
| `addFilter` | `{ fields: FilterField[]; onAdd: (filter: FilterChip, field: FilterField) => void; label?: string; align?: "start" \| "end" }` | – | Adds an Add filter trigger that opens a two step field and value menu. |
| `children` | `ReactNode` | – | Extra actions next to the Add filter trigger. |
| `label` | `string` | `"Active filters"` | Accessible name for the toolbar group. |

#### FilterMenu

The Add filter trigger and its two step menu, usable on its own.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `fields` (required) | `{ id: string; label: string; icon?: ReactNode; options: (string \| { value: string; label?: string; hint?: string \| number; icon?: ReactNode })[] }[]` | – | Filterable fields and their values. |
| `onSelect` (required) | `(filter: FilterChip, field: FilterField) => void` | – | Receives a chip whose id is the field id, so a second pick for a field replaces the first. |
| `active` | `FilterChip[]` | `[]` | Applied filters, used to mark current values. |
| `label` | `string` | `"Add filter"` | Trigger text. |
| `align` | `"start" \| "end"` | `"end"` | Trigger edge the panel lines up with. Flips when there is no room. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| ArrowDown / ArrowUp | On the trigger, opens the menu at the first or last item; inside, moves between items. |
| Home / End | Moves to the first or last menu item. |
| ArrowRight / ArrowLeft | Drills into a field's values, or goes back to fields. |
| Letters | Typeahead jumps to the matching item. |
| Escape | Closes the menu and returns focus to the trigger. |

### Accessibility

- The toolbar is role="group"; the menu panel is a labelled role="dialog" holding a role="menu" of checkable items.
- Remove buttons are labelled like "Remove Status: Open", and removing a chip moves focus to its neighbor or the Add filter trigger.
- Additions and removals are announced through a role="status" region.

### Motion

- Chips open and close their slot on a spring so neighbors glide; values morph in place.
- The Add filter trigger morphs into the menu surface and steps slide between fields and values.
- Reduced motion replaces the morphs and slides with instant changes and short fades.

### Responsive behavior

- Below 520px the toolbar stacks into a column with actions aligned to the end.
- The menu panel is min(16rem, 100vw minus a gutter) wide, flips its edge when there is no room, and its list caps at min(20rem, 55vh).
- Hover highlights apply only on hover-capable fine pointers.

### Performance

- Several ResizeObservers measure chips and the menu for morphs; menu options are not virtualized, so keep value lists short.

### Notes for AI

- Use above tables and lists for faceted filtering. Use chip-group for a fixed set of toggles and search-field for free text.
- Keep one chip per field: onAdd receives a chip keyed by field id, so replace any existing chip with that id.
- Pair with sortable-data-table and pagination for a full list view.

### Related

- [Sortable data table](https://uiarc.dev/components/sortable-data-table/markdown): Compare structured records with sortable columns.
- [Chip group](https://uiarc.dev/components/chip-group/markdown): Filter by a few facets with chips that morph as you pick them.
- [Search field](https://uiarc.dev/components/search-field/markdown): A recognizable search entry point with clear affordances.
- [Multi-select](https://uiarc.dev/components/multi-select/markdown): Select several values while keeping the field readable.
- [Pagination](https://uiarc.dev/components/pagination/markdown): Move through a long collection with clear bounds.

### Also in tables

- [Tree table](https://uiarc.dev/components/tree-table/markdown): A table with nested rows, tri-state selection, hierarchy-preserving sort, and lazy-loaded children.
- [Tree view](https://uiarc.dev/components/tree-view/markdown): Navigate nested folders and structured content.
- [Reorderable list](https://uiarc.dev/components/reorderable-list/markdown): Organize items with direct drag and drop.
- [Code block](https://uiarc.dev/components/code-block/markdown): Present code with legible hierarchy and copy access.
- [JSON viewer](https://uiarc.dev/components/json-viewer/markdown): A collapsible JSON tree with search, paging for long arrays, and copy value or path.

### Guidance for AI tools

Filter toolbar: Keep collection filters close and easy to reset. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Code block

> Present code with legible hierarchy and copy access.

- Type: Component (data)
- Access: Free, open source
- Page: https://uiarc.dev/components/code-block
- Markdown: https://uiarc.dev/components/code-block/markdown
- Registry item: https://uiarc.dev/r/code-block.json
- Source file: `registry/components/code-block/code-block.tsx`
- Dependencies: motion, lucide-react
- Keywords: content, developer, react code block, syntax highlighting, code snippet component, copy code block, collapsible code, code viewer

### When to use

- Documentation snippets and install commands with a copy button.
- Long files that should collapse to a few lines with Show all, via maxLines.

### When not to use

- Use copy-button alone for a one-line value such as an API key.
- Use text-stream for code arriving from an AI response in progress.
- Use a full highlighter library when you need many languages.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/code-block
pnpm dlx shadcn@latest add @uiarc/code-block
yarn dlx shadcn@latest add @uiarc/code-block
bunx --bun shadcn@latest add @uiarc/code-block
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/code-block.json
```

#### Manual

1. Install the dependencies:

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

2. Copy the source into your project. Main file: `registry/components/code-block/code-block.tsx`

   The source is in the registry item: https://uiarc.dev/r/code-block.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { CodeBlock } from "@/components/arc/code-block/code-block";

const snippet = `export function hello() {
  return "world";
}`;

export function Example() {
  return <CodeBlock code={snippet} filename="hello.ts" language="ts" maxLines={12} />;
}
```

### API reference

#### CodeBlock

A source viewer with filename header, light syntax highlighting, copy button, and optional collapse.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `code` (required) | `string` | – | Source shown and copied. |
| `filename` | `string` | – | File name in the header. Defaults to "Source code". |
| `language` | `string` | `"tsx"` | Header label and highlighter mode. |
| `maxLines` | `number` | – | Collapses longer sources to this many lines with a Show all toggle. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Tab | Focuses the copy button, the scrollable source, and the expand toggle. |
| Enter / Space | Copies the code or toggles the expanded state. |

### Accessibility

- The block is a section labelled like "hello.ts source code"; the pre is focusable so keyboard users can scroll it.
- The expand toggle uses aria-expanded and aria-controls pointing at the source.
- Copy feedback comes from copy-button.

### Motion

- Expanding or collapsing springs the source height; new code fades up in place.
- The toggle label rolls and its chevron rotates.
- Reduced motion snaps height and swaps text without movement.

### Responsive behavior

- Long lines scroll horizontally inside the block, never the page.
- Below 420px the padding and font shrink and the copy button becomes icon-only.

### Performance

- The built-in highlighter is a small regex pass with no language bundles.
- ResizeObservers measure the source for the height spring; many blocks on one page each run their own.

### Notes for AI

- Use for documentation snippets and install commands. The highlighter is lightweight; use a full highlighter for many languages.
- Set maxLines for long files so pages stay scannable.

### Related

- [Copy button](https://uiarc.dev/components/copy-button/markdown): Copy a value with immediate confirmation.
- [Tree view](https://uiarc.dev/components/tree-view/markdown): Navigate nested folders and structured content.

### Also in tables

- [Sortable data table](https://uiarc.dev/components/sortable-data-table/markdown): Compare structured records with sortable columns.
- [Tree table](https://uiarc.dev/components/tree-table/markdown): A table with nested rows, tri-state selection, hierarchy-preserving sort, and lazy-loaded children.
- [Reorderable list](https://uiarc.dev/components/reorderable-list/markdown): Organize items with direct drag and drop.
- [Filter toolbar](https://uiarc.dev/components/filter-toolbar/markdown): Keep collection filters close and easy to reset.
- [JSON viewer](https://uiarc.dev/components/json-viewer/markdown): A collapsible JSON tree with search, paging for long arrays, and copy value or path.

### Guidance for AI tools

Code block: Present code with legible hierarchy and copy access. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## JSON viewer

> A collapsible JSON tree with search, paging for long arrays, and copy value or path.

- Type: Component (data)
- Access: Free, open source
- Page: https://uiarc.dev/components/json-viewer
- Markdown: https://uiarc.dev/components/json-viewer/markdown
- Registry item: https://uiarc.dev/r/json-viewer.json
- Source file: `registry/components/json-viewer/json-viewer.tsx`
- Dependencies: motion, lucide-react
- Keywords: data, new, react json viewer, json tree, json inspector, collapsible json, json explorer, copy json path, search json, api response viewer

### When to use

- Inspecting a JSON payload in a developer dashboard, such as webhooks or API logs.
- Large nested objects where search and copy path save time.
- Arrays with hundreds of items, which load in pages of pageSize.

### When not to use

- Use code-block to show JSON as formatted source for copying whole.
- Use tree-view for folders, navigation, or other non-JSON hierarchies.
- Use data-grid when the data is a flat list of records.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/json-viewer
pnpm dlx shadcn@latest add @uiarc/json-viewer
yarn dlx shadcn@latest add @uiarc/json-viewer
bunx --bun shadcn@latest add @uiarc/json-viewer
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/json-viewer.json
```

#### Manual

1. Install the dependencies:

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

2. Copy the source into your project. Main file: `registry/components/json-viewer/json-viewer.tsx`

   The source is in the registry item: https://uiarc.dev/r/json-viewer.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { JsonViewer } from "@/components/arc/json-viewer/json-viewer";

export function WebhookPayload({ payload }: { payload: unknown }) {
  return (
    <JsonViewer
      data={payload}
      rootName="event"
      defaultExpandDepth={2}
      maxHeight={360}
      onCopy={({ kind }) => toast(kind === "path" ? "Path copied" : "Value copied")}
    />
  );
}
```

### API reference

#### JsonViewer

A collapsible JSON tree with type colors, search that opens matching branches, paged long branches, and copy value or path per row.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `data` (required) | `unknown` | – | Any JSON-like value. |
| `rootName` | `string` | `"root"` | Name of the root in paths, as in root.users[0].name. |
| `defaultExpandDepth` | `number` | `1` | Levels open on first render when defaultExpanded is not set. 1 opens the root. |
| `expanded` | `string[]` | – | Controlled paths of open branches. |
| `defaultExpanded` | `string[]` | – | Open branch paths on first render when uncontrolled. |
| `onExpandedChange` | `(paths: string[]) => void` | – | Called when branches open or close. |
| `searchable` | `boolean` | `true` | Shows the search field. |
| `query` | `string` | – | Controlled search text. |
| `defaultQuery` | `string` | `""` | Starting search text when uncontrolled. |
| `onQueryChange` | `(query: string) => void` | – | Called as the search text changes. |
| `pageSize` | `number` | `50` | Children shown per page in a long array or object. |
| `copyable` | `boolean` | `true` | Shows copy value and copy path actions. |
| `onCopy` | `(detail: JsonViewerCopyDetail) => void` | – | Called after a copy with { kind: "value" \| "path", path, text }. |
| `onSelect` | `(detail: { path: string; value: unknown; type: JsonValueType }) => void` | – | Called when a row becomes the current one. |
| `showPath` | `boolean` | `true` | Shows the current row's path under the tree. |
| `maxHeight` | `number \| string` | `420` | Height of the scrolling tree area. Numbers are pixels. |
| `label` | `string` | `"JSON"` | Accessible name of the tree. |
| `className` | `string` | – | Class on the root. |
| `ref` | `Ref<HTMLDivElement>` | – | The root element. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| ArrowDown / ArrowUp | Moves to the next or previous visible row. |
| ArrowRight | Opens a closed branch, or moves into an open one. |
| ArrowLeft | Closes an open branch, or moves to the parent. |
| Home / End | Jumps to the first or last visible row. |
| Enter / Space | Toggles a branch, or loads the next page on a Show more row. |
| Cmd/Ctrl + C | Copies the focused row's value; add Shift to copy its path. Ignored while text is selected. |
| / | Focuses the search field. |
| Enter / Shift + Enter (in search) | Jumps to the next or previous match. |
| Escape (in search) | Clears the query. |
| ArrowDown (in search) | Moves focus into the tree. |

### Accessibility

- Follows the WAI-ARIA tree pattern: role="tree" with treeitems carrying aria-level, aria-posinset, aria-setsize, aria-expanded, and aria-selected.
- One row is tabbable at a time; each row's label reads its key and value, or its type and item count.
- The match counter is aria-live polite, and a status region announces copies and failures.
- Row copy buttons are out of the tab order; use Cmd or Ctrl with C, or the path bar's copy button, from the keyboard.

### Motion

- Each row unfolds its own height, so opening a branch, loading a page, or expanding all share one motion.
- The current-row highlight glides between rows with a shared layout id, and the tree scroll springs to where the row will sit once rows settle.
- Copy glyphs swap to a check or cross with a small scale and blur.
- Reduced motion, or more than 400 visible rows, makes row changes instant; reduced motion also jumps the scroll and highlight.

### Responsive behavior

- The tree scrolls inside maxHeight; long keys and values truncate with an ellipsis and strings over 40 characters show in full on hover.
- At 420px viewport width and below the indent drops from 16px to 12px, keys cap at 40% of the row, and the path type hides.
- Row copy actions show on hover with a fine pointer; on touch they show on the current row.

### Performance

- Rows are a flat list rebuilt only when data, open branches, pages, or search change; nothing is virtualized, so paging keeps the DOM small.
- Above 400 visible rows the height animations switch off to keep expand all fast.
- Search walks the whole value on each keystroke; for multi-megabyte payloads control query and debounce it.

### Notes for AI

- Use for API responses, webhook payloads, logs, and config inspection in developer tools.
- Search matches keys and primitive values case-insensitively, opens the branches that hold them, and stops at 2000 matches.
- Control expanded to persist open branches across reloads, or to open a path from elsewhere in the page.
- For formatted source code use code-block; for tabular data use data-grid.

### Related

- [Tree view](https://uiarc.dev/components/tree-view/markdown): Navigate nested folders and structured content.
- [Code block](https://uiarc.dev/components/code-block/markdown): Present code with legible hierarchy and copy access.
- [Search field](https://uiarc.dev/components/search-field/markdown): A recognizable search entry point with clear affordances.
- [Copy button](https://uiarc.dev/components/copy-button/markdown): Copy a value with immediate confirmation.

### Also in tables

- [Sortable data table](https://uiarc.dev/components/sortable-data-table/markdown): Compare structured records with sortable columns.
- [Tree table](https://uiarc.dev/components/tree-table/markdown): A table with nested rows, tri-state selection, hierarchy-preserving sort, and lazy-loaded children.
- [Reorderable list](https://uiarc.dev/components/reorderable-list/markdown): Organize items with direct drag and drop.
- [Filter toolbar](https://uiarc.dev/components/filter-toolbar/markdown): Keep collection filters close and easy to reset.

### Guidance for AI tools

JSON viewer: A collapsible JSON tree with search, paging for long arrays, and copy value or path. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Timeline

> Follow what happened, newest first, grouped by day.

- Type: Component (data)
- Access: Free, open source
- Page: https://uiarc.dev/components/timeline
- Markdown: https://uiarc.dev/components/timeline/markdown
- Registry item: https://uiarc.dev/r/timeline.json
- Source file: `registry/components/timeline/timeline.tsx`
- Dependencies: motion, lucide-react
- Keywords: data, feed, activity, react timeline, activity feed, audit log, vertical timeline, event feed, changelog timeline

### When to use

- Project history, audit logs, and deploy streams where recency matters.
- Live feeds where new updates slide in at the top.
- Rows that expand in place to show logs or detail.

### When not to use

- Use sortable-data-table when people sort or compare.
- Use stepper for progress through fixed steps.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/timeline
pnpm dlx shadcn@latest add @uiarc/timeline
yarn dlx shadcn@latest add @uiarc/timeline
bunx --bun shadcn@latest add @uiarc/timeline
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/timeline.json
```

#### Manual

1. Install the dependencies:

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

2. Copy the source into your project. Main file: `registry/components/timeline/timeline.tsx`

   The source is in the registry item: https://uiarc.dev/r/timeline.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { Timeline } from "@/components/arc/timeline/timeline";

const events = [
  { id: "e1", at: "2026-09-22T09:12:00Z", actor: "Maya", title: "merged Checkout redesign into main", meta: "PR #482" },
  { id: "e2", at: "2026-09-22T08:40:00Z", title: "Deploy failed", tone: "danger" as const, detail: <pre>Build step exited 1</pre> },
];

export function Activity({ now }: { now: number }) {
  return <Timeline events={events} now={now} label="Project activity" maxHeight={420} />;
}
```

### API reference

#### Timeline

A vertical activity feed grouped by day with pinned day labels and rows that expand in place.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `events` (required) | `{ id: string; at: string \| number; actor?: string; title: string; meta?: string; detail?: ReactNode; avatar?: string; icon?: ReactNode; tone?: "neutral" \| "success" \| "danger" }[]` | – | Updates in any order; newest shows first. Rows with detail are expandable. |
| `now` (required) | `number` | – | Reference time in epoch ms for relative labels and day groups. Pass a ticking clock to keep labels fresh. |
| `label` (required) | `string` | – | Accessible name for the feed. |
| `timeZone` | `string` | `"UTC"` | Time zone for day groups and clock times. |
| `locale` | `string` | `"en-US"` | Formatting locale. |
| `maxHeight` | `number \| string` | – | Height of the scrolling area. Without it the feed grows with the page. |
| `scrollToNew` | `boolean` | `true` | Scrolls back to the top when a new update arrives. |
| `defaultExpanded` | `string[]` | `[]` | Event ids expanded on mount. |
| `headingLevel` | `2 \| 3 \| 4 \| 5 \| 6` | `3` | Heading level for day labels. |
| `className` | `string` | – | Class for the root. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| ArrowDown / ArrowUp | Moves between expandable rows. |
| Home / End | Jumps to the first or last expandable row. |
| Enter / Space | Expands or collapses the focused row. |

### Accessibility

- The feed is a labelled role="region"; day labels are headings at headingLevel with a hidden update count.
- Expandable rows are buttons with aria-expanded and aria-controls; rows without detail are not interactive.
- Times use a time element with the full date in hidden text, and new updates are announced in a status region.
- Say the outcome in the title, since tone is color only.

### Motion

- The connecting line draws as rows come into view and markers pop in.
- New updates slide in at the top while the rest glide down; details expand on a spring.
- Reduced motion replaces travel with short fades and instant height changes.

### Responsive behavior

- Day labels stay pinned while updates scroll under them, inside maxHeight or the page.
- Below 420px row padding tightens so text keeps its width.

### Performance

- Events are not virtualized; set maxHeight for long feeds and trim old events.
- Pass a now that ticks about once a minute rather than every second, since it re-renders every row.

### Notes for AI

- Use for project history, audit logs, and deploy streams where order and recency matter. Use sortable-data-table when people sort or compare.
- Pass a ticking now (for example updated every minute) so relative times stay current, and a fixed timeZone to avoid hydration mismatches.

### Related

- [Sortable data table](https://uiarc.dev/components/sortable-data-table/markdown): Compare structured records with sortable columns.
- [Avatar](https://uiarc.dev/components/avatar/markdown): A compact identity marker for people and accounts.
- [Badge](https://uiarc.dev/components/badge/markdown): A small label for status, category, or metadata.
- [Stepper](https://uiarc.dev/components/stepper/markdown): Show where a person is in a multi-step flow and what is done.

### Also in activity

- [Comment thread](https://uiarc.dev/components/comment-thread/markdown): Threaded comments with replies, reactions, mentions, inline edit, and resolve.
- [Chat thread](https://uiarc.dev/components/chat-thread/markdown): A chat thread with grouped messages, reactions, read receipts, typing, and a composer with attachments.

### Guidance for AI tools

Timeline: Follow what happened, newest first, grouped by day. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Comment thread

> Threaded comments with replies, reactions, mentions, inline edit, and resolve.

- Type: Component (data)
- Access: Free, open source
- Page: https://uiarc.dev/components/comment-thread
- Markdown: https://uiarc.dev/components/comment-thread/markdown
- Registry item: https://uiarc.dev/r/comment-thread.json
- Source file: `registry/components/comment-thread/comment-thread.tsx`
- Dependencies: motion, lucide-react
- Keywords: data, new, react comment thread, threaded comments, comment replies, resolve thread, mentions in comments, comment reactions, review comments component

### When to use

- Review threads on documents, designs, tickets, or pull requests.
- Discussions that need replies, reactions, mentions, and a resolved state.
- Sidebars of feedback attached to one object.

### When not to use

- Use chat-thread for real-time back-and-forth conversation.
- Use ai-chat for assistant conversations with streaming replies.
- Use mention-input alone when you only need a composer.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/comment-thread
pnpm dlx shadcn@latest add @uiarc/comment-thread
yarn dlx shadcn@latest add @uiarc/comment-thread
bunx --bun shadcn@latest add @uiarc/comment-thread
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/comment-thread.json
```

#### Manual

1. Install the dependencies:

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

2. Copy the source into your project. Main file: `registry/components/comment-thread/comment-thread.tsx`

   The source is in the registry item: https://uiarc.dev/r/comment-thread.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { CommentThread, type ThreadComment } from "@/components/arc/comment-thread/comment-thread";

export function HeadlineDiscussion({ initial, me }: { initial: ThreadComment[]; me: { id: string; name: string; avatar?: string } }) {
  return (
    <CommentThread
      title="Hero headline"
      currentUser={me}
      defaultComments={initial}
      onCommentsChange={(_, event) => syncComment(event)}
      onResolvedChange={resolved => setThreadResolved("hero", resolved)}
    />
  );
}
```

### API reference

#### CommentThread

A threaded discussion: nested replies that collapse, reactions with rolling counts, in-place edit and delete, @mention autocomplete, and resolving that folds the thread into a chip.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `comments` | `ThreadComment[]` | – | The comment tree (controlled). |
| `defaultComments` | `ThreadComment[]` | `[]` | Initial tree when uncontrolled. |
| `onCommentsChange` | `(comments: ThreadComment[], event: CommentThreadEvent) => void` | – | Called with the full next tree and what changed: reply, edit, delete, or react. |
| `currentUser` (required) | `CommentAuthor` | – | The person writing. Their comments can be edited and deleted. |
| `people` | `CommentAuthor[]` | – | People who can be mentioned. Defaults to everyone in the thread. |
| `resolved` | `boolean` | – | Resolved state (controlled). |
| `defaultResolved` | `boolean` | `false` | Initial resolved state. |
| `onResolvedChange` | `(resolved: boolean) => void` | – | Called on Resolve and Reopen. |
| `title` | `ReactNode` | – | What the thread is about, shown in the header, such as "Hero headline". |
| `reactions` | `string[]` | `["👍", "❤️", "🎉", "👀", "🚀", "✅"]` | Emoji offered by the reaction picker. |
| `placeholder` | `string` | – | Composer placeholder. |
| `maxDepth` | `number` | `2` | Replies deeper than this attach to the deepest allowed parent. |
| `nowLabel` | `string` | – | createdAt label for comments written now. |
| `labels` | `CommentThreadLabels` | – | Words for localization, every visible word and accessible name: reply, edit, delete, cancel, send, save, resolve, resolved, reopen, empty, edited, deleteConfirm, deletedText, deletedComment, editComment, hideReplies, cancelReply, addReaction, closeReactions, reactions, mentions and thread. Words with a count or a name are functions: commentCount, peopleCount, showReplies, replyingTo, reactWith and reactionCount. Any key left out keeps its English default. |
| `className` | `string` | – | Extra class on the section. |
| `ref` | `Ref<HTMLElement>` | – | The section element. |

#### ThreadComment

One comment in the tree.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `id` (required) | `string` | – | Stable id. |
| `author` (required) | `{ id: string; name: string; avatar?: string }` | – | Author. Initials show without an avatar. |
| `body` (required) | `string` | – | Plain text. "@Full Name" mentions of known people are highlighted. |
| `createdAt` (required) | `string` | – | Display label such as "2h" or "Sep 18". |
| `edited` | `boolean` | – | Shows an edited mark. |
| `deleted` | `boolean` | – | A deleted comment with replies stays as a quiet placeholder. |
| `reactions` | `{ emoji: string; users: string[] }[]` | – | Reactions and who gave them. |
| `replies` | `ThreadComment[]` | – | Nested replies. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| ⌘ + Enter / Ctrl + Enter | Sends the composer. |
| @ | Opens mention suggestions in the composer. |
| ArrowUp / ArrowDown | Move through mention suggestions. |
| Enter / Tab | Insert the active mention. |
| Escape | Closes suggestions, then cancels an edit or reply; also closes the reaction picker or delete confirmation. |

### Accessibility

- The composer is a combobox with a listbox of people and aria-activedescendant.
- Each comment is an article labelled with author and time; deleted ones read "Deleted comment".
- Reaction chips are toggle buttons with aria-pressed and a label like "👍 3, including you".
- Reply toggles expose aria-expanded; icon-only actions have specific labels.

### Motion

- The thread height springs when replies expand, comments arrive, or the thread folds into the resolved chip.
- Reaction counts roll to the new value; chips move with layout animation as they are added or removed.
- Edit, confirm, and picker rows slide in from the side.
- Reduced motion swaps content without travel and turns off transitions.

### Responsive behavior

- Below 420px the composer hides its avatar and nested replies indent less (12px).
- Hover styles only apply on fine pointers; every action is a visible button on touch.

### Performance

- Each change rebuilds the tree immutably and renders every comment; paginate or collapse very long threads.
- Reply nesting is capped by maxDepth, which keeps indentation and render depth bounded.

### Notes for AI

- Choose it for comments attached to a document, design, or record. Persist changes with the event passed to onCommentsChange rather than diffing trees.
- currentUser decides which comments show Edit and Delete; enforce the same rule on your server.
- Deleting a comment with replies keeps a placeholder so the thread structure survives.

### Related

- [Chat thread](https://uiarc.dev/components/chat-thread/markdown): A chat thread with grouped messages, reactions, read receipts, typing, and a composer with attachments.
- [Mention input](https://uiarc.dev/components/mention-input/markdown): A textarea with @people and #channel mentions that act as single tokens, with suggestions at the caret.
- [Reactions](https://uiarc.dev/components/reactions/markdown): Acknowledge a post in one tap, with counts that roll.
- [Avatar](https://uiarc.dev/components/avatar/markdown): A compact identity marker for people and accounts.
- [Inline edit](https://uiarc.dev/components/inline-edit/markdown): Rename in place: the text becomes a field without moving.

### Also in activity

- [Timeline](https://uiarc.dev/components/timeline/markdown): Follow what happened, newest first, grouped by day.

### Guidance for AI tools

Comment thread: Threaded comments with replies, reactions, mentions, inline edit, and resolve. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Chat thread

> A chat thread with grouped messages, reactions, read receipts, typing, and a composer with attachments.

- Type: Component (data)
- Access: Free, open source
- Page: https://uiarc.dev/components/chat-thread
- Markdown: https://uiarc.dev/components/chat-thread/markdown
- Registry item: https://uiarc.dev/r/chat-thread.json
- Source file: `registry/components/chat-thread/chat-thread.tsx`
- Dependencies: motion, lucide-react
- Keywords: data, new, react chat, chat thread, messaging ui, support chat widget, chat bubbles, read receipts, typing indicator, message reactions, chat composer with attachments

### When to use

- Customer support or in-app messaging with read receipts and typing state.
- Team or DM threads that need reactions and image or file attachments.
- Comment threads on an object where replies arrive live.

### When not to use

- Use log-stream for streaming system or build output.
- Use timeline for an activity history rather than a two-way conversation.
- Use textarea or mention-input when you only need the input box inside your own layout.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/chat-thread
pnpm dlx shadcn@latest add @uiarc/chat-thread
yarn dlx shadcn@latest add @uiarc/chat-thread
bunx --bun shadcn@latest add @uiarc/chat-thread
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/chat-thread.json
```

#### Manual

1. Install the dependencies:

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

2. Copy the source into your project. Main file: `registry/components/chat-thread/chat-thread.tsx`

   The source is in the registry item: https://uiarc.dev/r/chat-thread.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { ChatThread, type ChatMessage } from "@/components/arc/chat-thread/chat-thread";

const participants = [
  { id: "me", name: "Alex Rivera" },
  { id: "sam", name: "Sam Lee", avatar: "/avatars/sam.jpg" },
];

const messages: ChatMessage[] = [
  { id: "m1", authorId: "sam", text: "Is the build green?", createdAt: "2026-09-23T09:12:00Z" },
  { id: "m2", authorId: "me", text: "Yes, shipping now.", createdAt: "2026-09-23T09:13:00Z", status: "delivered" },
];

export function SupportChat() {
  return (
    <div style={{ height: 520 }}>
      <ChatThread
        participants={participants}
        currentUserId="me"
        defaultMessages={messages}
        readBy={{ sam: "m2" }}
        typing={["sam"]}
        onSend={draft => console.log(draft.text, draft.files)}
      />
    </div>
  );
}
```

### API reference

#### ChatThread

A chat or support thread with grouped messages, day separators, reactions, read receipts, a typing indicator, and a composer. It stays pinned to the newest message and shows a pill when new messages land out of view.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `participants` (required) | `ChatParticipant[]` | – | Everyone in the thread: id, name, and optional avatar URL. Initials show without an avatar. |
| `currentUserId` (required) | `string` | – | Id of the viewer. Their messages sit on the right in the accent color. |
| `messages` | `ChatMessage[]` | – | Controlled messages, oldest first. Leave it out to let the thread keep its own list. |
| `defaultMessages` | `ChatMessage[]` | – | Initial messages when uncontrolled. |
| `typing` | `string[]` | `[]` | Participant ids currently typing. The current user is ignored. |
| `readBy` | `Record<string, string>` | – | The last message each participant has read, by participant id. Their avatar sits under that message and glides as it moves. |
| `onSend` | `(draft: ChatDraft) => void \| Promise<void>` | – | Called with the composer's text and files. Uncontrolled threads also append the message themselves with status sent. |
| `onReact` | `(messageId: string, emoji: string) => void` | – | Called when a reaction is picked or toggled. Uncontrolled threads update counts themselves. |
| `onRetry` | `(messageId: string) => void` | – | Shows a Retry button under the last own message when its status is failed. |
| `reactions` | `string[]` | `["👍", "❤️", "😂", "🎉", "👀", "🙏"]` | Emoji offered by the reaction picker. |
| `placeholder` | `string` | `"Message"` | Composer placeholder, also its accessible name. |
| `composer` | `boolean` | `true` | Show the composer. Turn it off for a read-only transcript. |
| `allowAttachments` | `boolean` | `true` | Allow files by button, paste, or drop in the composer. |
| `accept` | `string` | – | File types the attach button offers, as for <input accept>. |
| `groupWindow` | `number` | `300000` | Messages from one person closer together than this, in ms, share a group. Defaults to five minutes. |
| `locale` | `string` | `"en-US"` | Locale for times and day labels. |
| `label` | `string` | `"Conversation"` | Accessible name of the message log. |
| `labels` | `ChatThreadLabels` | – | Words for localization: sending, sent, delivered, read, failed, retry, today, yesterday, jumpToLatest, unknownAuthor, addReaction, reactions, and the composer's send, attach and attachments. Words with a count or names are functions: readBy, typing, newMessages, reactWith, reactionCount and removeFile. Any key left out keeps its English default; today and yesterday default to the locale's own words. |
| `className` | `string` | – | Extra class on the root. |

#### ChatThreadHandle

Methods on the ref.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `scrollToBottom` | `(smooth?: boolean) => void` | – | Scrolls to the newest message and pins the thread there. Smooth by default, instant with reduced motion. |
| `focusComposer` | `() => void` | – | Focuses the composer textarea. |

#### ChatComposer

The message box on its own: autosizing text up to six lines, attachments by button, paste, or drop, and a send button that lifts its arrow on send.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `onSend` (required) | `(draft: ChatDraft) => void` | – | Called with trimmed text and the attached files. The composer clears itself after. |
| `placeholder` | `string` | `"Message"` | Placeholder and accessible name of the textarea. |
| `allowAttachments` | `boolean` | `true` | Show the attach button and accept pasted or dropped files, up to ten at a time. |
| `accept` | `string` | – | File types the attach button offers. |
| `disabled` | `boolean` | – | Disables the textarea and attach button. |
| `labels` | `ChatComposerLabels` | – | Words for localization: send, attach, attachments, and removeFile(name). Any key left out keeps its English default. |
| `className` | `string` | – | Extra class on the composer. |

#### ChatMessage

Shape of one message.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `id` (required) | `string` | – | Stable id. Also the key used by readBy and onReact. |
| `authorId` (required) | `string` | – | Participant id of the author. |
| `text` | `string` | – | Message body, rendered as plain text with line breaks kept. |
| `createdAt` (required) | `Date \| string \| number` | – | Send time. Drives grouping, day separators, and the time label. |
| `attachments` | `ChatAttachment[]` | – | Images (kind image with url) show in a gallery of up to four with a +N tile; everything else shows as a download row. Pass width and height to reserve space for a single image. |
| `reactions` | `ChatReaction[]` | – | Emoji, count, and mine for reactions the viewer added. |
| `status` | `"sending" \| "sent" \| "delivered" \| "read" \| "failed"` | – | Delivery state of the viewer's own messages. Shown under their latest message only. |

#### formatBytes

Formats a byte count as B, KB, or MB, as used on file rows.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `bytes` | `number` | `0` | Size in bytes. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Enter | Sends the message from the composer. Ignored during IME composition. |
| Shift+Enter | Adds a line in the composer. |
| Tab | Reaches the add reaction button of each message; it shows on focus within the row. |
| Arrow Left / Arrow Right | Moves between emoji in an open reaction picker, wrapping at the ends. |
| Escape | Closes the reaction picker and returns focus to its button. |

### Accessibility

- Messages are an ordered list with role log, aria-live polite, and aria-relevant additions, so new messages are read out.
- Typing is announced in a separate status region, such as Sam is typing; the visual dots are aria-hidden.
- Reaction chips are toggle buttons with aria-pressed and labels like 👍 3, including you.
- Read receipts carry an aria-label listing who read the message; avatars are decorative.
- The picker focuses its first emoji on open and uses a roving tabindex.

### Motion

- New messages rise in from their own side with a small scale on a smooth spring, and the list glides up by the added height instead of jumping.
- Reader avatars share a layoutId, so a receipt travels to the newly read message.
- Reaction chips pop in, counts roll up or down, and the reaction row and attachment tray spring open.
- The send arrow lifts out and a new one rises in on each send; the jump to latest pill springs in from below.
- Reduced motion turns these into short fades, stops the typing dots, and scrolls to the bottom instantly.

### Responsive behavior

- Bubbles are capped at min(78%, 34rem); below 420px the content padding tightens to 12px and bubbles may reach 84%.
- On touch devices (hover none) the add reaction button stays visible at reduced opacity instead of waiting for hover.
- The reaction picker opens above the bubble unless that would pass the top of the scroller, then opens below.

### Performance

- Every message renders; there is no virtualization, so page older history in chunks past a few hundred messages.
- A ResizeObserver on the content keeps the list pinned and drives the glide; images take width and height to avoid layout shift.
- Uncontrolled sends create object URLs for attached files and never revoke them; controlled threads should upload and pass real URLs.

### Notes for AI

- Choose it for support widgets, DMs, and team chat. Use log-stream for machine output and timeline for dated events that are not a conversation.
- Give the parent a fixed height; the root is a flex column at height 100% with its own scroller.
- For a server-backed thread, pass messages and append an optimistic message with status sending in onSend, then update status or set failed and handle onRetry.
- Keep readBy in sync from your realtime source; only the furthest read message marks the viewer's latest message as Read.
- Use ChatComposer alone when messages render elsewhere, such as an AI chat.

### Related

- [Mention input](https://uiarc.dev/components/mention-input/markdown): A textarea with @people and #channel mentions that act as single tokens, with suggestions at the caret.
- [Reactions](https://uiarc.dev/components/reactions/markdown): Acknowledge a post in one tap, with counts that roll.
- [File dropzone](https://uiarc.dev/components/file-dropzone/markdown): A generous target for dropping one or more files.
- [Avatar](https://uiarc.dev/components/avatar/markdown): A compact identity marker for people and accounts.
- [Textarea](https://uiarc.dev/components/textarea/markdown): A multiline field for notes, descriptions, and longer text.

### Also in activity

- [Timeline](https://uiarc.dev/components/timeline/markdown): Follow what happened, newest first, grouped by day.
- [Comment thread](https://uiarc.dev/components/comment-thread/markdown): Threaded comments with replies, reactions, mentions, inline edit, and resolve.

### Guidance for AI tools

Chat thread: A chat thread with grouped messages, reactions, read receipts, typing, and a composer with attachments. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Image compare

> Drag a divider across two images to see what changed.

- Type: Component (data)
- Access: Free, open source
- Page: https://uiarc.dev/components/image-compare
- Markdown: https://uiarc.dev/components/image-compare/markdown
- Registry item: https://uiarc.dev/r/image-compare.json
- Source file: `registry/components/image-compare/image-compare.tsx`
- Dependencies: motion, lucide-react
- Keywords: before after, comparison, image, react image compare, before after slider, image comparison slider, compare images, photo diff slider

### When to use

- Before and after visuals such as photo edits, redesigns, or cleanup results.
- Top and bottom comparisons, via orientation vertical.

### When not to use

- Use carousel to browse many images.
- Use resizable-panels to split live content rather than images.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/image-compare
pnpm dlx shadcn@latest add @uiarc/image-compare
yarn dlx shadcn@latest add @uiarc/image-compare
bunx --bun shadcn@latest add @uiarc/image-compare
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/image-compare.json
```

#### Manual

1. Install the dependencies:

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

2. Copy the source into your project. Main file: `registry/components/image-compare/image-compare.tsx`

   The source is in the registry item: https://uiarc.dev/r/image-compare.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { ImageCompare } from "@/components/arc/image-compare/image-compare";

export function Retouch() {
  return (
    <ImageCompare
      before={<img src="/photo-raw.jpg" alt="Unedited photo" />}
      after={<img src="/photo-edit.jpg" alt="Retouched photo" />}
      aspectRatio="4 / 3"
    />
  );
}
```

### API reference

#### ImageCompare

A before and after slider with a draggable divider over two stacked images.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `before` (required) | `ReactNode` | – | Original, shown left or top. Pass an image with its own alt text. |
| `after` (required) | `ReactNode` | – | Result, shown right or bottom. |
| `position` | `number` | – | Controlled divider position in percent from the left or top. |
| `defaultPosition` | `number` | `50` | Initial position when uncontrolled. |
| `onPositionChange` | `(position: number) => void` | – | Called when the divider settles on a new position. |
| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | Vertical stacks images top and bottom; changing it swings the divider. |
| `labels` | `[string, string] \| false` | `["Before", "After"]` | Captions over each side. False hides them. |
| `label` | `string` | `"Before and after"` | Accessible name of the divider. |
| `aspectRatio` | `string` | `"3 / 2"` | Frame proportions as a CSS aspect-ratio. |
| `className` | `string` | – | Class for the root. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Arrow keys | Moves the divider by 1 percent, or 10 with Shift. |
| PageUp / PageDown | Moves the divider by 10 percent. |
| Home / End | Shows all of the before or all of the after image. |
| Double click | On the handle, recenters the divider. |

### Accessibility

- The handle is a focusable role="slider" with aria-orientation and aria-valuetext like "40% after".
- Caption chips are aria-hidden; give both images meaningful alt text.
- Dragging works anywhere on the frame, not only on the handle.

### Motion

- The divider follows the pointer and settles with release velocity; the handle stretches into a capsule while dragging.
- Keyboard presses at an edge give a small bump; captions fade as the divider reaches them.
- Reduced motion jumps the divider and handle without springs.

### Responsive behavior

- The frame is full width with a fixed aspect ratio, so it scales to any column.
- On touch the photo waits for a sideways drag before moving the divider, so vertical swipes still scroll the page; a tap jumps the divider there.

### Performance

- The divider runs on motion values and one ResizeObserver, with no React re-render per drag frame.
- Both images stay mounted and stacked, so size them for the frame.

### Notes for AI

- Use for visual diffs: photo edits, redesigns, before and after results. Use carousel to browse many images.
- Both images should share the same crop and size so the reveal lines up.

### Related

- [Carousel](https://uiarc.dev/components/carousel/markdown): Browse a row of slides by dragging, flicking, or arrowing through them.
- [Photo grid](https://uiarc.dev/components/photo-grid/markdown): Pinch through zoom levels and open any photo straight from its cell.
- [Slider](https://uiarc.dev/components/slider/markdown): Pick a value or a range on a track that follows your finger.
- [Resizable panels](https://uiarc.dev/components/resizable-panels/markdown): Trade space between panes by dragging the divider between them.

### Also in media

- [Card stack](https://uiarc.dev/components/card-stack/markdown): Review a deck one card at a time, with a throw and an undo.

### Guidance for AI tools

Image compare: Drag a divider across two images to see what changed. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Carousel

> Browse a row of slides by dragging, flicking, or arrowing through them.

- Type: Component (data)
- Access: Free, open source
- Page: https://uiarc.dev/components/carousel
- Markdown: https://uiarc.dev/components/carousel/markdown
- Registry item: https://uiarc.dev/r/carousel.json
- Source file: `registry/components/carousel/carousel.tsx`
- Dependencies: motion, lucide-react
- Keywords: carousel, slider, gallery, react carousel, image slider, swipe carousel, autoplay carousel, accessible carousel, slideshow component

### When to use

- A short set of peer items where neighbouring slides hint at more.
- Galleries browsed by drag, flick, trackpad swipe, or keys.
- Rotating highlights with a visible pause control, via interval.

### When not to use

- Use cover-flow for a showpiece gallery and photo-grid to show everything at once.
- Use card-stack for deciding on items one at a time.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/carousel
pnpm dlx shadcn@latest add @uiarc/carousel
yarn dlx shadcn@latest add @uiarc/carousel
bunx --bun shadcn@latest add @uiarc/carousel
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/carousel.json
```

#### Manual

1. Install the dependencies:

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

2. Copy the source into your project. Main file: `registry/components/carousel/carousel.tsx`

   The source is in the registry item: https://uiarc.dev/r/carousel.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { Carousel } from "@/components/arc/carousel/carousel";

export function Suites() {
  return (
    <Carousel label="Harbour suites" interval={5000}>
      <img src="/suite-1.jpg" alt="Sea view suite" />
      <img src="/suite-2.jpg" alt="Garden suite" />
      <img src="/suite-3.jpg" alt="Loft suite" />
    </Carousel>
  );
}
```

### API reference

#### Carousel

A centered slide row browsed by drag, flick, trackpad swipe, arrow keys, or pill indicators, with optional rotation.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` (required) | `string` | – | Names the carousel for assistive technology. |
| `children` (required) | `ReactNode` | – | One child per slide. |
| `index` | `number` | – | Controlled active slide. Pair with onIndexChange. |
| `defaultIndex` | `number` | `0` | Initial slide when uncontrolled. |
| `onIndexChange` | `(index: number) => void` | – | Called when the active slide changes. |
| `slideSize` | `string` | `"min(80cqw, 340px)"` | Width of one slide as a CSS length. |
| `slideLabel` | `(index: number, count: number) => string` | `"2 of 5"` | Names each slide and its indicator. |
| `interval` | `number` | – | Milliseconds per slide. Adds a play control for rotation. |
| `autoplay` | `boolean` | `false` | Starts rotating on mount. |
| `className` | `string` | – | Class for the root section. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| ArrowLeft / ArrowRight | Moves to the previous or next slide. |
| Home / End | Jumps to the first or last slide. |
| Tab | Moves between the slide area, play control, active indicator, and arrows. |

### Accessibility

- The root is a section with aria-roledescription="carousel"; slides are labelled tabpanels and the indicators a role="tablist".
- Inactive slides are inert, so their links are not focusable.
- Slide changes are announced in a polite live region.
- Rotation pauses on hover, keyboard focus, and drag, and has a visible pause control.

### Motion

- Slides follow the finger and settle with momentum; neighbors shrink and dim with distance.
- The indicator stretches into a pill that tracks the slides, and drains to show rotation time.
- Reduced motion jumps between slides and disables rotation.

### Responsive behavior

- Slides default to min(80cqw, 340px), so they size to the carousel's container rather than the viewport.
- Controls tighten when the container is under 340px.

### Performance

- All slides stay mounted; inactive ones are inert, so keep the set short.
- Rotation pauses offscreen via IntersectionObserver and in hidden tabs via visibilitychange.

### Notes for AI

- Use for a short set of peer items where neighbors should hint at more. Use cover-flow for a showpiece gallery and photo-grid to show everything at once.
- Give each slide a stable key if the list can change, and write a specific label.
- Keep autoplay off unless rotation is essential.

### Related

- [Cover flow](https://uiarc.dev/components/cover-flow/markdown): A depth rail of images you can throw, with soft grounded shadows and a quiet reflection.
- [Photo grid](https://uiarc.dev/components/photo-grid/markdown): Pinch through zoom levels and open any photo straight from its cell.
- [Card stack](https://uiarc.dev/components/card-stack/markdown): Review a deck one card at a time, with a throw and an undo.
- [Image compare](https://uiarc.dev/components/image-compare/markdown): Drag a divider across two images to see what changed.

### Guidance for AI tools

Carousel: Browse a row of slides by dragging, flicking, or arrowing through them. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Card stack

> Review a deck one card at a time, with a throw and an undo.

- Type: Component (data)
- Access: Free, open source
- Page: https://uiarc.dev/components/card-stack
- Markdown: https://uiarc.dev/components/card-stack/markdown
- Registry item: https://uiarc.dev/r/card-stack.json
- Source file: `registry/components/card-stack/card-stack.tsx`
- Dependencies: motion, lucide-react
- Keywords: gesture, motion, triage, react card stack, swipe cards, tinder swipe, swipeable card deck, card triage, swipe left right

### When to use

- One-by-one triage such as shortlisting, review queues, or onboarding picks.
- Decks where swiping left or right should be undoable.

### When not to use

- Use a list or sortable-data-table when people compare items side by side.
- Use carousel to browse items without deciding.
- Use swipe-actions for quick actions on rows in a list.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/card-stack
pnpm dlx shadcn@latest add @uiarc/card-stack
yarn dlx shadcn@latest add @uiarc/card-stack
bunx --bun shadcn@latest add @uiarc/card-stack
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/card-stack.json
```

#### Manual

1. Install the dependencies:

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

2. Copy the source into your project. Main file: `registry/components/card-stack/card-stack.tsx`

   The source is in the registry item: https://uiarc.dev/r/card-stack.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { CardStack } from "@/components/arc/card-stack/card-stack";

const cities = [{ id: "lis", name: "Lisbon" }, { id: "osl", name: "Oslo" }, { id: "kyo", name: "Kyoto" }];

export function Shortlist() {
  return (
    <CardStack
      items={cities}
      getKey={city => city.id}
      getLabel={city => city.name}
      renderCard={city => <h3>{city.name}</h3>}
      labels={{ left: "Skip", right: "Shortlist" }}
      onDecide={(city, decision) => save(city.id, decision)}
    />
  );
}
```

### API reference

#### CardStack

A deck reviewed one card at a time by swiping left or right, with buttons, undo, and reset.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `items` (required) | `T[]` | – | Cards in order. |
| `getKey` (required) | `(item: T) => string` | – | Stable key per item. |
| `getLabel` (required) | `(item: T) => string` | – | Short name for labels and announcements, such as "Lisbon". |
| `renderCard` (required) | `(item: T) => ReactNode` | – | Card content. |
| `onDecide` | `(item: T, decision: "left" \| "right") => void` | – | Called when a card is swiped or decided by button or key. |
| `onUndo` | `(item: T, decision: "left" \| "right") => void` | – | Called when the last decision is undone. |
| `onReset` | `() => void` | – | Called when all cards come back. |
| `labels` | `{ left: string; right: string }` | `{ left: "Pass", right: "Keep" }` | Action names on the buttons and drag stamps. |
| `outcomes` | `{ left: string; right: string }` | – | Past tense of each action for announcements, such as "skipped". |
| `label` | `string` | `"Cards"` | Accessible name for the stack. |
| `renderEmpty` | `(reset: () => void) => ReactNode` | – | Shown once every card is decided. Defaults to a Start over button. |
| `className` | `string` | – | Class for the root. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| ArrowLeft / ArrowRight | Decides the top card left or right when the stack is focused. |
| Backspace / Cmd+Z / Ctrl+Z | Undoes the last decision. |

### Accessibility

- The stage is a focusable role="group" with aria-roledescription="card stack" and a hidden hint describing drag and keys.
- Each card is labelled like "Lisbon, 1 of 3".
- Decisions, undo, and reset are announced in a polite status region.
- Buttons mirror every gesture, so swiping is never required.

### Motion

- The top card follows the drag with tilt and stamps; a flick or far drag throws it off with its velocity.
- Cards beneath rise into place, and undo flies a card back from where it left.
- Reduced motion fades cards out and in at home without travel.

### Responsive behavior

- The stage is min(100%, 20rem) wide; below 26rem the cards get shorter, and below 22.5rem Undo becomes icon-only.
- Cards use touch-action pan-y, so vertical swipes still scroll the page.

### Performance

- Only the top four cards render in the stage, however long the deck.
- Drag and throw run on motion values without per-frame React updates.

### Notes for AI

- Use for one-by-one triage: shortlisting, review queues, onboarding picks. Use a list or sortable-data-table when people compare items side by side.
- Persist decisions from onDecide and reverse them in onUndo.

### Related

- [Swipe actions](https://uiarc.dev/components/swipe-actions/markdown): Reveal row actions with a swipe, or from the same actions in a menu.
- [Carousel](https://uiarc.dev/components/carousel/markdown): Browse a row of slides by dragging, flicking, or arrowing through them.
- [Wallet stack](https://uiarc.dev/components/wallet-stack/markdown): Fan a stack of cards and lift one out to see its activity.

### Also in media

- [Image compare](https://uiarc.dev/components/image-compare/markdown): Drag a divider across two images to see what changed.

### Guidance for AI tools

Card stack: Review a deck one card at a time, with a throw and an undo. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Text reveal

> Reveal a short piece of content with restrained motion.

- Type: Component (text)
- Access: Free, open source
- Page: https://uiarc.dev/components/text-reveal
- Markdown: https://uiarc.dev/components/text-reveal/markdown
- Registry item: https://uiarc.dev/r/text-reveal.json
- Source file: `registry/components/text-reveal/text-reveal.tsx`
- Keywords: text, motion, content, react text reveal, headline animation, hero text animation, word by word reveal, blur text reveal, css text animation

### When to use

- Above-the-fold hero headlines that animate on page load.
- Landing page intros where text must appear on first paint even if scripts are slow.

### When not to use

- Use in-view-title for section titles further down the page.
- Use scroll-highlight for a key paragraph that reveals with scroll.
- Use word-rotate when one word in the headline should cycle.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/text-reveal
pnpm dlx shadcn@latest add @uiarc/text-reveal
yarn dlx shadcn@latest add @uiarc/text-reveal
bunx --bun shadcn@latest add @uiarc/text-reveal
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/text-reveal.json
```

#### Manual

1. No packages are needed beyond React and Next.js.

2. Copy the source into your project. Main file: `registry/components/text-reveal/text-reveal.tsx`

   The source is in the registry item: https://uiarc.dev/r/text-reveal.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { TextReveal } from "@/components/arc/text-reveal/text-reveal";

export function Hero() {
  return <TextReveal as="h1" text={"Ship interfaces\nthat feel precise"} delay={0.1} />;
}
```

### API reference

#### TextReveal

Reveals a headline once on mount: each word rises out of its own clip while it sharpens from a soft blur. Runs in CSS, so it starts on first paint.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `text` (required) | `string` | – | The copy to reveal. Use \n for a deliberate line break. |
| `as` | `"h1" \| "h2" \| "h3" \| "p"` | `"h2"` | Rendered element. p uses a softer blur. |
| `delay` | `number` | `0` | Seconds before the first word rises. |
| `className` | `string` | – | Merged onto the rendered element. |
| `id` | `string` | – | Forwarded to the rendered element, e.g. for aria-labelledby. |

### Accessibility

- A heading carries the full text as its aria-label and the animated words are aria-hidden, so screen readers and crawlers read one clean sentence. A p keeps a visually hidden copy instead, since a paragraph cannot take a label.
- Line breaks are read as spaces.
- Pick the heading level with as so the page outline stays correct.

### Motion

- Words rise out of a clip and sharpen from blur on a per-word stagger; total stagger is capped so long text never drags.
- The entrance is pure CSS, so text is never left hidden when scripts load slowly.
- Reduced motion drops the clip and rise and fades the words in quickly.

### Responsive behavior

- The element caps at 24ch with balanced wrapping, so lines stay even on any width.
- Use \n only for breaks that work on every width, since forced breaks apply on mobile too.

### Performance

- Pure CSS keyframes, no JavaScript animation or observers.
- Total stagger is capped, so long text does not lengthen the entrance; each word still gets its own blur filter.

### Notes for AI

- Use for above-the-fold headlines that should animate on page load. For titles further down the page use in-view-title; for body copy worth slowing down on use scroll-highlight.
- It plays once per mount. Change the element's key to replay it.

### Related

- [In-view title](https://uiarc.dev/components/in-view-title/markdown): Bring a section title in as it scrolls into view.
- [Text morph](https://uiarc.dev/components/text-morph/markdown): Morph a label into its next state, letter by letter.

### Also in text effects

- [Text shimmer](https://uiarc.dev/components/text-shimmer/markdown): Show ongoing work with a calm light across the words.

### Guidance for AI tools

Text reveal: Reveal a short piece of content with restrained motion. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## In-view title

> Bring a section title in as it scrolls into view.

- Type: Component (text)
- Access: Free, open source
- Page: https://uiarc.dev/components/in-view-title
- Markdown: https://uiarc.dev/components/in-view-title/markdown
- Registry item: https://uiarc.dev/r/in-view-title.json
- Source file: `registry/components/in-view-title/in-view-title.tsx`
- Dependencies: motion
- Keywords: text, motion, heading, react scroll animation title, animate on scroll heading, in view text animation, section title reveal, scroll reveal text, framer motion heading

### When to use

- Section headings that should animate once they scroll into view.
- Feature pages where each section title needs a consistent entrance style.
- Headings that should replay on each entry, via once={false}.

### When not to use

- Use text-reveal for hero copy that animates on load.
- Use scroll-highlight for a paragraph that follows scroll progress.
- Use text-shimmer for status lines, not headings.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/in-view-title
pnpm dlx shadcn@latest add @uiarc/in-view-title
yarn dlx shadcn@latest add @uiarc/in-view-title
bunx --bun shadcn@latest add @uiarc/in-view-title
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/in-view-title.json
```

#### Manual

1. Install the dependencies:

```bash
npm install motion
```

2. Copy the source into your project. Main file: `registry/components/in-view-title/in-view-title.tsx`

   The source is in the registry item: https://uiarc.dev/r/in-view-title.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { InViewTitle } from "@/components/arc/in-view-title/in-view-title";

export function FeaturesHeader() {
  return (
    <InViewTitle
      variant="line"
      text="Everything your team needs to ship"
      lines={["Everything your team", "needs to ship"]}
    />
  );
}
```

### API reference

#### InViewTitle

A section title that reveals itself once it scrolls into view, with five reveal styles.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `text` (required) | `string` | – | The title copy. |
| `variant` | `"word" \| "line" \| "blur" \| "tracking" \| "wipe"` | `"blur"` | Reveal style. blur suits most headings; word and line rise from a clip; tracking opens letter spacing; wipe uncovers left to right. |
| `as` | `"h1" \| "h2" \| "h3"` | `"h2"` | Heading level. |
| `lines` | `string[]` | – | Explicit line breaks for the line variant. Falls back to one line of text. |
| `once` | `boolean` | `true` | Set false to replay the reveal on every entry. |
| `className` | `string` | – | Merged onto the wrapper. |
| `id` | `string` | – | Forwarded to the heading. |

### Accessibility

- The heading carries aria-label with the full text; the animated parts are aria-hidden.
- Titles already scrolled past show immediately, and server-rendered titles appear on their own if scripts are slow.
- Choose as to match the page's heading outline.

### Motion

- Triggers when 45% of the title is visible. Opacity leads, blur clears next, and the transform settles last, so text is readable before it fully arrives.
- Hiding (with once={false}) is a quick fade with no stagger.
- Reduced motion shows the title instantly with no transform, blur, or mask.

### Responsive behavior

- Word, blur, and tracking variants wrap naturally at any width.
- The line variant uses your explicit lines, which do not rewrap, so keep each line short enough for mobile.

### Performance

- One IntersectionObserver per title via useInView, triggering at 45% visibility.
- Each word or line is a motion span with blur and transform; fine for headings, not for long body text.

### Notes for AI

- Default choice for section headings that should animate on scroll. Use text-reveal for on-load hero copy and scroll-highlight for a key paragraph.
- Pass lines only with variant="line"; the other variants split on words.

### Related

- [Text reveal](https://uiarc.dev/components/text-reveal/markdown): Reveal a short piece of content with restrained motion.
- [Text shimmer](https://uiarc.dev/components/text-shimmer/markdown): Show ongoing work with a calm light across the words.

### Also in text effects

- [Text morph](https://uiarc.dev/components/text-morph/markdown): Morph a label into its next state, letter by letter.

### Guidance for AI tools

In-view title: Bring a section title in as it scrolls into view. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Text morph

> Morph a label into its next state, letter by letter.

- Type: Component (text)
- Access: Free, open source
- Page: https://uiarc.dev/components/text-morph
- Markdown: https://uiarc.dev/components/text-morph/markdown
- Registry item: https://uiarc.dev/r/text-morph.json
- Source file: `registry/components/text-morph/text-morph.tsx`
- Dependencies: motion
- Keywords: text, motion, status, react text morph, morphing text, animated label, text transition, letter morph animation, shared letter animation

### When to use

- Status words that change a few letters at a time, such as Follow and Following.
- Custom buttons or badges that need a morphing label without the rest of the button.
- Inline counters or short state labels that should glide instead of jump.

### When not to use

- Use word-rotate for a sentence with one cycling word.
- Use button or action-swap when you want the morph plus button behaviour.
- Avoid it for text that wraps, since it always renders a single line.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/text-morph
pnpm dlx shadcn@latest add @uiarc/text-morph
yarn dlx shadcn@latest add @uiarc/text-morph
bunx --bun shadcn@latest add @uiarc/text-morph
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/text-morph.json
```

#### Manual

1. Install the dependencies:

```bash
npm install motion
```

2. Copy the source into your project. Main file: `registry/components/text-morph/text-morph.tsx`

   The source is in the registry item: https://uiarc.dev/r/text-morph.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { TextMorph } from "@/components/arc/text-morph/text-morph";

export function PublishButton({ state }: { state: "idle" | "busy" | "done" }) {
  const label = state === "idle" ? "Publish" : state === "busy" ? "Publishing" : "Published";
  return (
    <button type="button">
      <TextMorph>{label}</TextMorph>
    </button>
  );
}
```

### API reference

#### TextMorph

Morphs one short label into the next in place. Shared letters glide, new ones sharpen in, removed ones blur away, and the width springs to fit.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` (required) | `string` | – | The current label. Change it to morph. |
| `as` | `"span" \| "div" \| "p" \| "strong" \| "h1" \| "h2" \| "h3"` | `"span"` | Rendered element. |
| `className` | `string` | – | Applied to the rendered element. |
| `id` | `string` | – | Forwarded to the rendered element. |

### Accessibility

- The plain label is in a visually hidden span; the animated glyphs are aria-hidden.
- It does not announce changes. Wrap it in your own aria-live region if a status change must be announced.

### Motion

- Letters are matched by character and occurrence, so shared letters glide to their new positions on a spring while new letters stagger in with a blur.
- The frame width springs to the new label; font loading or resizes follow immediately without animating.
- Reduced motion swaps the label and width instantly.

### Responsive behavior

- The frame width springs to each label, and a ResizeObserver follows font loading and container resizes without animating.
- The label never wraps, so keep it short in narrow layouts.

### Performance

- Every character is a motion span with layout animation; keep labels to a few words.

### Notes for AI

- Use for status words that change a few letters at a time (Follow / Following, Save / Saved). For a sentence with a cycling word use word-rotate.
- Keep labels to one short line; it never wraps.

### Related

- [Button](https://uiarc.dev/components/button/markdown): A clear, responsive action with quiet secondary states.
- [Action swap](https://uiarc.dev/components/action-swap/markdown): Swap an action label while preserving its place and intent.
- [Text shimmer](https://uiarc.dev/components/text-shimmer/markdown): Show ongoing work with a calm light across the words.

### Also in text effects

- [Text reveal](https://uiarc.dev/components/text-reveal/markdown): Reveal a short piece of content with restrained motion.
- [In-view title](https://uiarc.dev/components/in-view-title/markdown): Bring a section title in as it scrolls into view.

### Guidance for AI tools

Text morph: Morph a label into its next state, letter by letter. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Text shimmer

> Show ongoing work with a calm light across the words.

- Type: Component (text)
- Access: Free, open source
- Page: https://uiarc.dev/components/text-shimmer
- Markdown: https://uiarc.dev/components/text-shimmer/markdown
- Registry item: https://uiarc.dev/r/text-shimmer.json
- Source file: `registry/components/text-shimmer/text-shimmer.tsx`
- Dependencies: motion
- Keywords: text, motion, loading, react text shimmer, shimmer text, ai thinking text, loading text animation, shiny text, gradient text sweep

### When to use

- AI thinking or loading labels such as Generating summary.
- Short status lines that should show ongoing work and settle when done.

### When not to use

- Use text-stream for the response text itself.
- Use skeleton for content placeholders and progress for measurable progress.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/text-shimmer
pnpm dlx shadcn@latest add @uiarc/text-shimmer
yarn dlx shadcn@latest add @uiarc/text-shimmer
bunx --bun shadcn@latest add @uiarc/text-shimmer
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/text-shimmer.json
```

#### Manual

1. Install the dependencies:

```bash
npm install motion
```

2. Copy the source into your project. Main file: `registry/components/text-shimmer/text-shimmer.tsx`

   The source is in the registry item: https://uiarc.dev/r/text-shimmer.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { TextShimmer } from "@/components/arc/text-shimmer/text-shimmer";

export function AssistantStatus({ busy }: { busy: boolean }) {
  return (
    <TextShimmer active={busy}>
      {busy ? "Generating summary" : "Summary ready"}
    </TextShimmer>
  );
}
```

### API reference

#### TextShimmer

A calm light sweep across a short status line to show that work is ongoing. When active turns false the band glides off and the text settles to solid.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` (required) | `string` | – | The status text. Keep it to one short line. A new value rises in place. |
| `active` | `boolean` | `true` | Sweep while work is ongoing. |
| `duration` | `number` | `1.8` | Seconds for one sweep across the text. |
| `as` | `"span" \| "p" \| "div" \| "h2" \| "h3" \| "h4"` | `"span"` | Rendered element. |
| `className` | `string` | – | Merged onto the rendered element. |
| `id` | `string` | – | Forwarded to the rendered element. |

### Accessibility

- Sets aria-busy while active; the text itself stays real, readable text.
- Announce completion from your own aria-live region; the component does not.

### Motion

- A bell-shaped highlight band in the current text color sweeps linearly over a muted base, pausing briefly between passes.
- The sweep only runs while active, in view, and the page is visible; a paused band resumes where it stopped. A changed label rises in with a soft blur.
- Reduced motion stops the sweep and swaps labels with a plain fade.

### Responsive behavior

- Keeps max-width 100%, but the band is tuned for one short line, so avoid wrapping text.
- In forced-colors mode the gradient is removed and the text renders in the system color.

### Performance

- The sweep runs only while active, within 64px of the viewport, and while the page is visible.
- It animates a background-clip gradient on one element, with no per-letter spans.

### Notes for AI

- Use for AI thinking or loading labels. Pair with text-stream for the response itself, and use skeleton or progress for content placeholders.
- Flip active to false when work finishes instead of unmounting, so the text settles smoothly.

### Related

- [Text morph](https://uiarc.dev/components/text-morph/markdown): Morph a label into its next state, letter by letter.
- [Skeleton](https://uiarc.dev/components/skeleton/markdown): Reserve space while content is still loading.
- [Progress](https://uiarc.dev/components/progress/markdown): Show how much of a known task is complete.

### Also in text effects

- [Text reveal](https://uiarc.dev/components/text-reveal/markdown): Reveal a short piece of content with restrained motion.
- [In-view title](https://uiarc.dev/components/in-view-title/markdown): Bring a section title in as it scrolls into view.

### Guidance for AI tools

Text shimmer: Show ongoing work with a calm light across the words. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Share sheet

> A Share button that opens into a panel with copy link, access level, channels, and people to send to.

- Type: Component (special)
- Access: Arc Pro
- Page: https://uiarc.dev/components/share-sheet
- Markdown: https://uiarc.dev/components/share-sheet/markdown
- Source file: `registry/components/share-sheet/share-sheet.tsx`
- Dependencies: motion, lucide-react
- Keywords: special, new, react share sheet, share button, share dialog, copy link, share with people, link access level, morphing share panel, share to slack

### When to use

- A Share button on a document, design, or board header where people share often.
- Sharing flows that combine copy link, access level, and sending to a few recent people.
- Posting to a small set of channels, such as Slack or email, with in-place pending and done feedback.

### When not to use

- Use copy-button when all you need is to copy a URL.
- Use dialog when sharing needs a full form, such as roles per person or an email search.
- Use popover for a small menu of share targets with no people picker.

### Installation

Share sheet is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/share-sheet
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { ShareSheet } from "@/components/arc/share-sheet/share-sheet";
import { Globe, Lock, Mail, MessageSquare } from "lucide-react";

export function DocumentShare() {
  return (
    <ShareSheet
      title="Q3 roadmap"
      link="https://example.com/d/q3-roadmap"
      people={[
        { id: "ana", name: "Ana Ruiz", avatar: "/avatars/ana.jpg" },
        { id: "sam", name: "Sam Lee", avatar: "/avatars/sam.jpg" },
      ]}
      access={[
        { value: "team", label: "Team", description: "Anyone on the team can view", icon: <Lock size={16} /> },
        { value: "public", label: "Anyone with the link", description: "Can view and comment", icon: <Globe size={16} /> },
      ]}
      channels={[
        { id: "slack", label: "Slack", doneLabel: "Posted", icon: <MessageSquare size={16} /> },
        { id: "email", label: "Email", doneLabel: "Sent", icon: <Mail size={16} /> },
      ]}
      onSend={({ people, access }) => api.share(people.map(person => person.id), access)}
      onChannel={channel => api.post(channel)}
    />
  );
}
```

### API reference

#### ShareSheet

A Share button that springs open into a share panel (copy link, access level, channels, recent people) and folds into a sent confirmation.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` (required) | `string` | – | Name of the thing being shared, shown in the panel title as Share "title". |
| `link` (required) | `string` | – | The URL shown in the link row and written to the clipboard by Copy. |
| `people` (required) | `SharePerson[]` | – | Recent people: { id, name, avatar }. Picking one flies its avatar up into the Send to row. |
| `access` (required) | `ShareSheetAccess[]` | – | Access levels: { value, label, description, icon } (the type was ShareAccess, kept as a deprecated alias). Shown in a listbox under the link. |
| `channels` | `ShareChannel[]` | `[]` | Channel buttons: { id, label, icon, doneLabel }. doneLabel is shown once onChannel resolves; keep it about as long as label. |
| `defaultAccess` | `string` | – | Starting access value. Defaults to the first entry in access. |
| `onSend` | `(submission: ShareSubmission) => void \| Promise<unknown>` | – | Receives { people, access }. A returned promise holds the sending state; a rejection keeps the panel open with an error. |
| `onChannel` | `(channel: string) => void \| Promise<unknown>` | – | Called with the channel id. A promise holds that button's pending state; a rejection shows Failed on it. |
| `onCopy` | `(access: string) => void` | – | Called after the link is copied, with the access level it was copied under. |
| `label` | `string` | `"Share"` | Trigger button text. |
| `align` | `"start" \| "end" \| "center"` | `"end"` | Which edge of the button stays put while the panel grows. center grows it evenly around the button and folds it back the same way. |
| `sheetOnPhones` | `boolean` | `true` | Up to 520px wide the panel opens as a bottom sheet over a dimmed backdrop: it slides up, drags down from its grabber, and closes on Esc, a tap outside or Done. |
| `className` | `string` | – | Class on the root. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Enter / Space | Opens the panel from the Share button, or presses the focused control. |
| Escape | Closes the access list first, then folds the panel back into the button and returns focus to it. |
| ArrowUp / ArrowDown / ArrowLeft / ArrowRight | Moves between access options in the open list, looping at the ends. |
| Tab | Moves through the copy, access, channel, people, and send controls. |

### Accessibility

- The trigger has aria-haspopup="dialog"; the open panel is role="dialog" labelled by its title.
- Opening moves focus to Copy, sending moves it to Done, and closing returns it to the Share button.
- Access options are a listbox of role="option" buttons with aria-selected and roving tabindex.
- People are toggle buttons with aria-pressed; chips have a Remove <name> button.
- A polite status region announces copies, picks, removals, channel results, and who a share was sent to.
- A press outside the component closes the panel without stealing focus.

### Motion

- One shape springs its width, height, and corner radius between the button, the panel, and the confirmation; faces cross with a short blur and scale.
- A picked avatar flies from the recent row to its chip on a separate layer, so the scrolling chips row never clips it.
- Send with nobody picked shakes the Send to row on a spring; the count in the send button rolls one digit up or down.
- Reduced motion jumps the shape to size, swaps faces with a plain fade, skips the avatar flight and the shake, and slows the spinner.

### Responsive behavior

- The panel is min(24rem, 100vw - 2rem) wide; set --share-sheet-width on an ancestor to fit a narrower container. It is a container, so its rows adapt to that width.
- The panel is min(24rem, 100vw - 2rem) wide and the confirmation min(19rem, 100vw - 2rem), so both fit a 320px phone.
- align="start" grows the panel from the left edge of the button; use it when the button sits near the left of the viewport.
- Hover styles apply only on hover-capable fine pointers; the trigger uses touch-action: manipulation for fast taps.

### Performance

- Each face runs a ResizeObserver while it is current, and the shape animates three motion values; nothing runs while closed.
- Avatars are plain img tags from your URLs; pass small, pre-sized images since each person renders at up to 80px.

### Notes for AI

- Use for sharing a document, board, or file from a toolbar without leaving the page.
- Wire onSend and onChannel to your API and return the promise; the component handles pending, error, and done states itself.
- people is a short list of recent collaborators, not a directory search. For inviting by email use the invite-people block.
- The root reserves only the button's size; the panel floats over the page, so leave room below or pick align to grow away from an edge.

### Related

- [Popover](https://uiarc.dev/components/popover/markdown): A small anchored surface for contextual information.
- [Copy button](https://uiarc.dev/components/copy-button/markdown): Copy a value with immediate confirmation.
- [Avatar group](https://uiarc.dev/components/avatar-group/markdown): Show a team or set of contributors in a small space.
- [Dialog](https://uiarc.dev/components/dialog/markdown): A focused surface for decisions that need attention.
- [Toast](https://uiarc.dev/components/toast/markdown): Brief confirmation for a completed background action.

### Also in docks and tabs

- [Action morph](https://uiarc.dev/components/action-morph/markdown): A floating button that morphs into a quick-action menu, then an inline form, then back with a check.
- [Morph nav](https://uiarc.dev/components/morph-nav/markdown): A navigation bar that morphs into rich menus, search, and a compact state as one surface.
- [Dock](https://uiarc.dev/components/dock/markdown): A floating tool dock with a gliding label, a springy selection, and trays that grow out of it.
- [Liquid tab bar](https://uiarc.dev/components/liquid-tab-bar/markdown): Tabs with a lens selection that slides between them, swaps labels cleanly, and fills in icons as it passes.
- [Orbit menu](https://uiarc.dev/components/orbit-menu/markdown): Hold a button and its actions orbit out, ready to pick with a drag.

### Guidance for AI tools

Share sheet: A Share button that opens into a panel with copy link, access level, channels, and people to send to. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Action morph

> A floating button that morphs into a quick-action menu, then an inline form, then back with a check.

- Type: Component (special)
- Access: Arc Pro
- Page: https://uiarc.dev/components/action-morph
- Markdown: https://uiarc.dev/components/action-morph/markdown
- Source file: `registry/components/action-morph/action-morph.tsx`
- Dependencies: motion, lucide-react
- Keywords: special, new, react floating action button, fab menu, quick actions, morphing fab, inline composer, speed dial, quick create button

### When to use

- Quick capture of tasks, notes, or comments without leaving the page.
- Apps with a few frequent create actions that deserve a persistent button.
- Mobile layouts where a corner button should expand into a small form.

### When not to use

- Use dialog or drawer for longer forms with several fields.
- Use dropdown-menu when actions run immediately and need no input.
- Use action-button for one async save on a button in place.

### Installation

Action morph is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/action-morph
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { CheckSquare, StickyNote } from "lucide-react";
import { ActionMorph } from "@/components/arc/action-morph/action-morph";

export function QuickCreate() {
  return (
    <div style={{ position: "fixed", right: 24, bottom: 24 }}>
      <ActionMorph
        label="Create"
        actions={[
          {
            id: "task",
            label: "New task",
            description: "Add to your list",
            icon: <CheckSquare strokeWidth={1.75} />,
            shortcut: "t",
            composer: {
              title: "New task",
              placeholder: "What needs doing?",
              choices: { label: "Due", options: ["Today", "Tomorrow", "Next week"] },
              submitLabel: "Add",
              successLabel: "Task added",
            },
          },
          {
            id: "note",
            label: "New note",
            icon: <StickyNote strokeWidth={1.75} />,
            shortcut: "n",
            composer: { title: "New note", placeholder: "Write a note", multiline: true, submitLabel: "Save", successLabel: "Note saved" },
          },
        ]}
        onSubmit={({ action, text, choice }) => save(action, text, choice)}
      />
    </div>
  );
}
```

### API reference

#### ActionMorph

A floating action button that springs into a quick action menu, slides into an inline composer, and folds back with a check on success.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `actions` (required) | `ActionMorphAction[]` | – | Actions: { id, label, description?, icon, shortcut?, composer }. composer is { title, placeholder, multiline?, choices?, submitLabel, successLabel, emptyHint? }. |
| `label` | `string` | `"Create"` | Accessible name of the button and the title of the menu. |
| `onSubmit` | `(submission: ActionMorphSubmission) => void \| Promise<unknown>` | – | Receives { action, text, choice? }. Return a promise to hold the sending state; a rejection keeps the composer open with the draft and an error. |
| `corner` | `"end" \| "start"` | `"end"` | Which bottom corner the button sits in. The surface grows away from it. |
| `resetAfter` | `number` | `1600` | Milliseconds the check stays before the button returns to its plus. |
| `className` | `string` | – | Extra class on the root, for example to position it fixed. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Enter / Space | Opens the menu from the button and focuses the first action. |
| ArrowDown / ArrowUp | Moves between menu actions, wrapping at the ends; Home and End jump to the first or last. |
| Letter shortcut | Opens that action's composer while the menu is open. |
| Enter | Submits a one line composer. |
| Mod + Enter | Submits a multiline composer. |
| Arrow keys | Move between choices in the composer's radio group. |
| Escape | Goes back from a composer to the menu, or closes the menu and returns focus to the button. |

### Accessibility

- The button has aria-haspopup="menu"; after success its label adds the success message.
- The menu is role="menu" labelled by its title, with role="menuitem" buttons and aria-keyshortcuts for letter shortcuts.
- Composer fields set aria-invalid and aria-describedby on an empty or failed submit; the form sets aria-busy while sending.
- A polite status region announces the success label, and focus moves into each new face and back to the button on close.

### Motion

- One surface animates width, height, and corner radius on physical springs: growing carries a little bounce, folding settles without overshoot.
- Going deeper slides the new face in from the right and pushes the old one left; menu rows stagger in; a highlight glides between actions.
- Submitting folds the composer into the button, which tints to success while a check draws itself, then the plus rotates back in.
- Reduced motion jumps the size, swaps faces with fades, drops the press scale and shake, and slows the spinner.

### Responsive behavior

- The menu is min(16rem, 100vw - 2rem) wide and the composer min(20rem, 100vw - 2rem), so both fit narrow phones.
- corner="start" grows the surface to the right for bottom-left placement.
- The button is 56px with touch-action: manipulation; hover styles apply only on hover-capable fine pointers.

### Performance

- Each face reports its size through a ResizeObserver only while it is current; the shape animates from those sizes.
- Only the current face and the one leaving are mounted.

### Notes for AI

- Use for the two or three things people create most often on a page, such as a task, note, or event.
- Return the real promise from onSubmit; on rejection the draft stays and a retry message shows.
- Drafts are kept per action while the component is mounted, so going back and forth does not lose text.
- The component does not position itself; wrap it in a fixed container at the matching corner.
- For a single async commit use action-button; for longer forms use dialog or drawer.

### Related

- [Action button](https://uiarc.dev/components/action-button/markdown): A compact button for frequent toolbar actions.
- [Orbit menu](https://uiarc.dev/components/orbit-menu/markdown): Hold a button and its actions orbit out, ready to pick with a drag.
- [Dropdown menu](https://uiarc.dev/components/dropdown-menu/markdown): A focused list of actions anchored to a trigger.
- [Dialog](https://uiarc.dev/components/dialog/markdown): A focused surface for decisions that need attention.
- [Toast](https://uiarc.dev/components/toast/markdown): Brief confirmation for a completed background action.

### Also in docks and tabs

- [Share sheet](https://uiarc.dev/components/share-sheet/markdown): A Share button that opens into a panel with copy link, access level, channels, and people to send to.
- [Morph nav](https://uiarc.dev/components/morph-nav/markdown): A navigation bar that morphs into rich menus, search, and a compact state as one surface.
- [Dock](https://uiarc.dev/components/dock/markdown): A floating tool dock with a gliding label, a springy selection, and trays that grow out of it.
- [Liquid tab bar](https://uiarc.dev/components/liquid-tab-bar/markdown): Tabs with a lens selection that slides between them, swaps labels cleanly, and fills in icons as it passes.

### Guidance for AI tools

Action morph: A floating button that morphs into a quick-action menu, then an inline form, then back with a check. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Morph nav

> A navigation bar that morphs into rich menus, search, and a compact state as one surface.

- Type: Component (special)
- Access: Arc Pro
- Page: https://uiarc.dev/components/morph-nav
- Markdown: https://uiarc.dev/components/morph-nav/markdown
- Source file: `registry/components/morph-nav/morph-nav.tsx`
- Dependencies: motion, lucide-react
- Keywords: special, navigation, morph, tabs, react navigation bar, react morph nav, mega menu, animated navbar, site header with dropdown, navbar with search, stripe style navigation

### When to use

- The top navigation of a marketing or product site with a few sections that each hold several destinations.
- Headers where search should grow out of the bar instead of opening a separate modal.
- Sites that want one primary action, such as Sign up, pinned to the end of the bar.

### When not to use

- Use liquid-tab-bar for an app-style switcher between a handful of peer sections.
- Use tabs for switching views inside a page.
- Use dropdown-menu when you only need one menu of commands, not site navigation.

### Installation

Morph nav is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/morph-nav
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { MorphNav } from "@/components/arc/morph-nav/morph-nav";

export function SiteHeader({ scrolled }: { scrolled: boolean }) {
  return (
    <MorphNav
      brand={{ name: "Arc", mark: <Logo />, href: "/" }}
      items={[
        { value: "product", label: "Product", links: [
          { label: "Components", description: "Motion-first building blocks", href: "/components" },
          { label: "Blocks", description: "Full sections", href: "/blocks" },
        ] },
        { value: "pricing", label: "Pricing", href: "/pricing" },
      ]}
      search={{ items: [{ label: "Dialog", group: "Components", href: "/components/dialog" }] }}
      action={{ label: "Sign up", href: "/sign-up" }}
      current="product"
      compact={scrolled}
    />
  );
}
```

### Examples

#### Tighten on scroll

```tsx
const [scrolled, setScrolled] = useState(false);
useEffect(() => {
  const onScroll = () => setScrolled(window.scrollY > 24);
  window.addEventListener("scroll", onScroll, { passive: true });
  return () => window.removeEventListener("scroll", onScroll);
}, []);

<MorphNav items={items} current={section} compact={scrolled} onNavigate={d => d.href && router.push(d.href)} />
```

### API reference

#### MorphNav

A site navigation bar made of one continuous surface: a highlight glides between items, items with links grow the bar into a dropdown panel, and search morphs out of the bar itself.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `items` (required) | `{ value: string; label: string; href?: string; links?: { label: string; description?: string; icon?: ReactNode; href?: string }[]; columns?: 1 \| 2; feature?: ReactNode; footer?: ReactNode }[]` | – | Top level destinations. Items with links or a feature open a panel; other items act as plain links. columns defaults to 2 when there are more than three links. Clicking a link or button inside feature closes the panel. |
| `brand` | `{ name: string; mark: ReactNode; href?: string }` | – | Brand button at the start of the bar. |
| `action` | `{ label: string; icon?: ReactNode; href?: string; onClick?: () => void }` | – | The one primary action at the end of the bar. |
| `search` | `{ placeholder?: string; items: { label: string; description?: string; group?: string; icon?: ReactNode; href?: string; keywords?: string }[] }` | – | Search entries. Leave it out to hide search. |
| `current` | `string` | – | Value of the item that holds the current page. |
| `compact` | `boolean` | `false` | Tightens the bar, for example once the page scrolls. |
| `collapseBelow` | `number` | `720` | Below this container width in px the items fold into one menu. |
| `onNavigate` | `(destination: { label: string; href?: string; section?: string }) => void` | – | Called for every destination: links, search results, plain items, and the brand. |
| `label` | `string` | `"Main"` | Accessible name of the nav landmark. |
| `className` | `string` | – | Extra class on the nav element. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| ArrowLeft / ArrowRight | Moves between top level items, wrapping; an open panel follows to the new item. |
| Home / End | Focuses the first or last item. |
| ArrowDown / Enter / Space | On an item with a panel, opens it and moves focus to its first link. If the panel is already open, moves focus into it. |
| ArrowUp / ArrowDown | Inside a panel, moves between links; ArrowUp on the first link returns to the trigger. In search, moves the active result. |
| Enter | In search, opens the active result. |
| Escape | Closes search or the open panel and returns focus to where it came from. |

### Accessibility

- Renders a nav landmark; the current item carries aria-current="page" and panel triggers use aria-expanded and aria-controls.
- Open panels are regions labelled by their trigger; the panel closes when focus leaves the nav.
- Search is a combobox driving a listbox with aria-activedescendant, and the result count is announced politely. With an empty query it lists the first five entries as Suggested.
- A pointer down outside the nav closes the panel or search.

### Motion

- The surface springs to each panel's size, with a little bounce when it grows and none when it shrinks. Moving to a neighbour slides the new panel in from that side while a highlight glides between items.
- Hover opens a panel after a 60ms intent delay and leaving the nav closes it after 180ms, so crossing a gap does not flicker it shut.
- Search grows out of the same surface as the bar fades and blurs away; compact and narrow states retune the bar.
- Reduced motion drops travel, scale, and blur and keeps short fades.

### Responsive behavior

- The root is a container; below collapseBelow (720px of its own width by default) the items fold into one menu.
- Panels and search cap at the container width minus a gutter, and below 420px viewport width link panels drop to one column.
- Hover-to-open only reacts to mouse pointers, so touch opens panels on tap without a hover flash.

### Performance

- The bar uses a 22px backdrop blur, which falls back to a solid surface under prefers-reduced-transparency and prefers-contrast.
- Two ResizeObservers track the container and the open panel size; only the open panel is mounted.
- Search ranks entries in memory on each keystroke and shows at most six results, so large indexes should be pre-filtered.

### Notes for AI

- Choose it for the top navigation of a marketing or product site with a handful of sections that each hold several destinations. Use tabs for in-page view switching and liquid-tab-bar for an app-style section switcher.
- Pass current from the router and compact from a scroll listener. Route in onNavigate for client-side navigation; plain items and links with href also work as anchors.

### Related

- [Tabs](https://uiarc.dev/components/tabs/markdown): Switch between related content in the same context.
- [Liquid tab bar](https://uiarc.dev/components/liquid-tab-bar/markdown): Tabs with a lens selection that slides between them, swaps labels cleanly, and fills in icons as it passes.
- [Dropdown menu](https://uiarc.dev/components/dropdown-menu/markdown): A focused list of actions anchored to a trigger.
- [Search field](https://uiarc.dev/components/search-field/markdown): A recognizable search entry point with clear affordances.
- [Popover](https://uiarc.dev/components/popover/markdown): A small anchored surface for contextual information.

### Also in docks and tabs

- [Share sheet](https://uiarc.dev/components/share-sheet/markdown): A Share button that opens into a panel with copy link, access level, channels, and people to send to.
- [Action morph](https://uiarc.dev/components/action-morph/markdown): A floating button that morphs into a quick-action menu, then an inline form, then back with a check.
- [Dock](https://uiarc.dev/components/dock/markdown): A floating tool dock with a gliding label, a springy selection, and trays that grow out of it.
- [Orbit menu](https://uiarc.dev/components/orbit-menu/markdown): Hold a button and its actions orbit out, ready to pick with a drag.

### Guidance for AI tools

Morph nav: A navigation bar that morphs into rich menus, search, and a compact state as one surface. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Dock

> A floating tool dock with a gliding label, a springy selection, and trays that grow out of it.

- Type: Component (special)
- Access: Arc Pro
- Page: https://uiarc.dev/components/dock
- Markdown: https://uiarc.dev/components/dock/markdown
- Source file: `registry/components/dock/dock.tsx`
- Dependencies: motion
- Keywords: special, dock, toolbar, react dock, floating toolbar, tool switcher, canvas toolbar, macos dock, toolbar with tray, reorderable toolbar

### When to use

- A floating tool or mode switcher, such as the tools of a canvas or whiteboard editor.
- Toolbars where related tools share one slot and open a tray, like shape variants.
- Tool sets people may reorder by drag or Alt with the arrow keys.

### When not to use

- Use segmented-control for two to four inline options.
- Use action-button for one-off actions that do not stay selected.
- Use liquid-tab-bar for switching between app sections rather than tools.

### Installation

Dock is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/dock
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { Dock } from "@/components/arc/dock/dock";
import { Hand, MousePointer2, Pencil, Square, Circle } from "lucide-react";

export function CanvasTools() {
  const [tool, setTool] = useState("select");
  const [items, setItems] = useState([
    { id: "select", label: "Select", icon: <MousePointer2 />, shortcut: "V" },
    { id: "hand", label: "Hand", icon: <Hand />, shortcut: "H" },
    { id: "shapes", label: "Shapes", icon: <Square />, items: [
      { id: "rect", label: "Rectangle", icon: <Square />, shortcut: "R" },
      { id: "ellipse", label: "Ellipse", icon: <Circle />, shortcut: "O" },
    ] },
    { id: "pen", label: "Pen", icon: <Pencil />, shortcut: "P" },
  ]);
  return <Dock items={items} value={tool} onValueChange={setTool} onItemsChange={next => setItems(next)} />;
}
```

### API reference

#### Dock

A floating command dock for the tools or modes someone switches between all day. A label glides between items, a calm accent tint springs to the chosen one, and groups grow a tray out of the dock surface, all inside one hairline outline.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `items` (required) | `{ id: string; label: string; icon: ReactNode; shortcut?: string; badge?: number; items?: DockItem[] }[]` | – | Items in order. shortcut is a display-only key hint, badge a rolling count that leaves at 0, and items turns the entry into a group with a tray. |
| `value` | `string \| null` | `null` | Id of the selected item or group member. |
| `onValueChange` | `(id: string) => void` | – | Called when an item or group member is chosen. |
| `onItemsChange` | `(items: DockItem[], change: { type: "move"; id: string; index: number }) => void` | – | Enables drag to reorder and Alt with the arrow keys. Receives the next list and what moved. |
| `label` | `string` | `"Tools"` | Accessible name of the toolbar. |
| `className` | `string` | – | Extra class on the root. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| ArrowLeft / ArrowRight | Moves focus along the dock, wrapping; in an open tray, moves between members. |
| Home / End | Focuses the first or last item. |
| Enter / Space | Chooses an item. On a group, selects the member it shows and opens or closes its tray. In a tray, chooses the member, closes the tray, and returns focus to the group. |
| ArrowUp | On a group, opens its tray and focuses the chosen member. |
| ArrowDown | In a tray, closes it and returns focus to the group. |
| Tab | In a tray, closes it and moves on. |
| Alt + ArrowLeft / ArrowRight | Moves the focused item when onItemsChange is set. |
| Escape | Closes the open tray and returns focus to its group. |

### Accessibility

- Items sit in a horizontal toolbar with a roving tabindex; plain items use aria-pressed for selection.
- Groups use aria-haspopup, aria-expanded, and aria-controls pointing at the tray, which is a labelled group that stays inert while closed.
- Accessible names include the shortcut hint and badge count, such as "Pen, P". A group reads as its label and shown member, such as "Shapes: Ellipse, O", plus "selected" when it holds the value.
- The floating label is aria-hidden. It shows on mouse hover and on keyboard focus, not on touch.
- A pointer down outside the dock closes an open tray.

### Motion

- The label glides between items after a short first hover delay and stays warm so the next one follows at once; the accent tint springs between items with a shared layoutId whose corner radius is corrected, so it never distorts.
- A group's glyph crossfades with a short blur when its member changes; a press dips the item on a quick spring and releases with a little overshoot.
- Opening a group grows a tab of the same material out of the dock with members staggering in; dragged items lift and neighbours reflow on a layout spring.
- Reduced motion makes the label, tray, and selection jump and keeps short fades.

### Responsive behavior

- The dock sizes to its items at a fixed 40px slot and caps at max-width 100%; it does not shrink items, so keep the count small on phones.
- The tray and label rise above the dock on purpose, so leave room over it in the layout.
- Labels only appear for mouse hover and keyboard focus; touch shows no label, so pick icons that read on their own.
- Item slots use touch-action pan-y, so a vertical swipe over the dock still scrolls the page while sideways drags reorder when onItemsChange is set.

### Performance

- Selection is one shared layoutId element and drag uses Reorder, so only the moved items reflow.
- A single ResizeObserver measures the bar. The tray mounts when a group first opens and then stays mounted, inert, for the last opened group.

### Notes for AI

- Choose it for a floating tool or mode switcher, such as the tools of a canvas editor. Use segmented-control for two to four inline options and action-button for one-off toolbar actions.
- Control value and handle shortcut keys on the page; the dock only displays them. Use items on an entry to group related tools under one slot.
- Pass onItemsChange only if people may reorder the dock.

### Related

- [Segmented control](https://uiarc.dev/components/segmented-control/markdown): Switch between a small set of related views.
- [Action button](https://uiarc.dev/components/action-button/markdown): A compact button for frequent toolbar actions.
- [Liquid tab bar](https://uiarc.dev/components/liquid-tab-bar/markdown): Tabs with a lens selection that slides between them, swaps labels cleanly, and fills in icons as it passes.
- [Reorderable list](https://uiarc.dev/components/reorderable-list/markdown): Organize items with direct drag and drop.
- [Orbit menu](https://uiarc.dev/components/orbit-menu/markdown): Hold a button and its actions orbit out, ready to pick with a drag.

### Also in docks and tabs

- [Share sheet](https://uiarc.dev/components/share-sheet/markdown): A Share button that opens into a panel with copy link, access level, channels, and people to send to.
- [Action morph](https://uiarc.dev/components/action-morph/markdown): A floating button that morphs into a quick-action menu, then an inline form, then back with a check.
- [Morph nav](https://uiarc.dev/components/morph-nav/markdown): A navigation bar that morphs into rich menus, search, and a compact state as one surface.

### Guidance for AI tools

Dock: A floating tool dock with a gliding label, a springy selection, and trays that grow out of it. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Liquid tab bar

> Tabs with a lens selection that slides between them, swaps labels cleanly, and fills in icons as it passes.

- Type: Component (special)
- Access: Arc Pro
- Page: https://uiarc.dev/components/liquid-tab-bar
- Markdown: https://uiarc.dev/components/liquid-tab-bar/markdown
- Source file: `registry/components/liquid-tab-bar/liquid-tab-bar.tsx`
- Dependencies: motion
- Keywords: special, tabs, navigation, react tab bar, liquid glass tabs, animated tab bar, ios tab bar, bottom navigation, tab bar with badges, gooey tabs

### When to use

- Switching between a handful of peer sections with icons, such as an app's main areas.
- Bottom or top bars on mobile-style layouts where the selection should feel physical.
- Tabs that carry badge counts for new items.

### When not to use

- Use tabs for text-only panels inside a page.
- Use segmented-control for compact filters or view toggles.
- Use morph-nav for site navigation with dropdown panels.

### Installation

Liquid tab bar is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/liquid-tab-bar
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { LiquidTabBar, liquidPanelId, liquidTabId } from "@/components/arc/liquid-tab-bar/liquid-tab-bar";
import { Home, Library, Radio } from "lucide-react";

export function Sections() {
  const [tab, setTab] = useState("home");
  return (
    <>
      <LiquidTabBar id="nav" value={tab} onValueChange={setTab} tabs={[
        { value: "home", label: "Home", icon: <Home /> },
        { value: "radio", label: "Radio", icon: <Radio />, badge: 2, badgeLabel: "2 new" },
        { value: "library", label: "Library", icon: <Library /> },
      ]} />
      <section id={liquidPanelId("nav", tab)} role="tabpanel" aria-labelledby={liquidTabId("nav", tab)}>{/* ... */}</section>
    </>
  );
}
```

### API reference

#### LiquidTabBar

Horizontal navigation for a handful of peer sections. The selection is a lens that slides to the new tab on the morph spring and redraws what passes under it inverted, so outline icons fill in.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `tabs` (required) | `{ value: string; label: string; icon: ReactNode; activeIcon?: ReactNode; badge?: number; badgeLabel?: string }[]` | – | Tabs in order. activeIcon is drawn inside the lens (defaults to icon filled in); badge is a rolling count and badgeLabel what screen readers hear with it. |
| `value` (required) | `string` | – | Selected tab value. |
| `onValueChange` (required) | `(value: string) => void` | – | Called when a tab is chosen by tap, drag, or keyboard. |
| `labels` | `"active" \| "always" \| "none"` | `"active"` | Which tabs show their label: the selected one, every tab, or none. |
| `label` | `string` | `"Sections"` | Accessible name of the tab list. |
| `id` | `string` | – | Base id for tab and panel ids. Defaults to a generated id. |
| `className` | `string` | – | Extra class on the tab list. |

#### liquidTabId / liquidPanelId

Helpers that return a tab's id and the panel id its aria-controls points at, so panels can be wired up.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `id` (required) | `string` | – | The base id passed to LiquidTabBar. |
| `value` (required) | `string` | – | The tab value. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| ArrowLeft / ArrowRight | Selects the previous or next tab and moves focus to it, wrapping at the ends. |
| Home / End | Selects the first or last tab. |

### Accessibility

- Uses the tablist and tab roles with aria-selected, aria-controls, and a roving tabindex.
- Each tab's accessible name includes its badge, using badgeLabel when given.
- The inverted copy inside the lens is decorative; only one set of tabs is exposed.

### Motion

- The lens slides and resizes to the new tab on the morph spring as one shape, with no stretch or squash; it leans slightly toward a hovered tab.
- The label being left fades out at once and the new label fades in only as the lens arrives, so two labels never show together; icons, labels, and badges keep their places.
- Grab the lens on the selected tab and drag or throw it; it lands where its momentum reaches, a quick flick always moves at least one tab, and it resists past either end. The selected tab's label opens on a spring and badge digits roll.
- Reduced motion jumps the lens and labels to their places without travel or lean.

### Responsive behavior

- Slots are a fixed 44px plus the open label, and the bar caps at max-width 100%; set labels to none when space is tight.
- The bar uses touch-action pan-y, so dragging the lens sideways works on touch without blocking page scroll.
- Hover lean follows the mouse only; touch selects on tap or throw.

### Performance

- The lens animates a clip-path over an inverted copy of the tabs, so every tab is rendered twice.
- Label widths are measured from hidden copies whenever tabs change; keep the tab count to a handful.

### Notes for AI

- Choose it for switching between a handful of peer sections with icons, such as an app's main areas. Use tabs for text-only in-page panels and segmented-control for compact filters.
- It is controlled: keep value in state. Wire panels with liquidPanelId and liquidTabId using the same id prop.

### Related

- [Tabs](https://uiarc.dev/components/tabs/markdown): Switch between related content in the same context.
- [Segmented control](https://uiarc.dev/components/segmented-control/markdown): Switch between a small set of related views.
- [Morph nav](https://uiarc.dev/components/morph-nav/markdown): A navigation bar that morphs into rich menus, search, and a compact state as one surface.
- [Dock](https://uiarc.dev/components/dock/markdown): A floating tool dock with a gliding label, a springy selection, and trays that grow out of it.

### Also in docks and tabs

- [Share sheet](https://uiarc.dev/components/share-sheet/markdown): A Share button that opens into a panel with copy link, access level, channels, and people to send to.
- [Action morph](https://uiarc.dev/components/action-morph/markdown): A floating button that morphs into a quick-action menu, then an inline form, then back with a check.
- [Orbit menu](https://uiarc.dev/components/orbit-menu/markdown): Hold a button and its actions orbit out, ready to pick with a drag.

### Guidance for AI tools

Liquid tab bar: Tabs with a lens selection that slides between them, swaps labels cleanly, and fills in icons as it passes. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Orbit menu

> Hold a button and its actions orbit out, ready to pick with a drag.

- Type: Component (special)
- Access: Arc Pro
- Page: https://uiarc.dev/components/orbit-menu
- Markdown: https://uiarc.dev/components/orbit-menu/markdown
- Source file: `registry/components/orbit-menu/orbit-menu.tsx`
- Dependencies: motion, lucide-react
- Keywords: special, motion, react radial menu, orbit menu, fan menu, arc menu, floating action menu, press and drag menu, circular menu

### When to use

- Three to six quick actions on one object, such as a note or photo.
- Touch-first surfaces where press, drag, and release should fire an action in one gesture.

### When not to use

- Use dropdown-menu or context-menu for longer or text-heavy lists.
- Use dock for tools that stay selected.
- Use action-button for a single action.

### Installation

Orbit menu is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/orbit-menu
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { OrbitMenu } from "@/components/arc/orbit-menu/orbit-menu";
import { Pin, Share2, Trash2 } from "lucide-react";

export function NoteActions({ onAction }: { onAction: (id: string) => void }) {
  return (
    <OrbitMenu
      label="Note actions"
      onAction={onAction}
      actions={[
        { id: "pin", label: "Pin", icon: <Pin size={18} />, done: "Pinned" },
        { id: "share", label: "Share", icon: <Share2 size={18} /> },
        { id: "delete", label: "Delete", icon: <Trash2 size={18} />, tone: "danger" },
      ]}
    />
  );
}
```

### API reference

#### OrbitMenu

A round button that bursts into an arc of actions. Press, drag onto an action, and release to fire it, or tap to keep the arc open and tap again to close it.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `actions` (required) | `{ id: string; label: string; icon: ReactNode; done?: string; tone?: "neutral" \| "danger" }[]` | – | Three to six actions. done is the short confirmation shown after firing and defaults to the label. |
| `onAction` (required) | `(id: string) => void` | – | Called with the fired action's id. |
| `label` | `string` | `"Actions"` | Accessible name of the button and menu, also shown while the arc is open and nothing is targeted. |
| `radius` | `number` | `104` | Distance from the button center to each action, in px. |
| `spread` | `number` | `150` | Degrees the arc spans. |
| `direction` | `number` | `-90` | Degrees the arc opens toward: -90 up, 0 right, 90 down, 180 left. |
| `disabled` | `boolean` | `false` | Disables the trigger and closes the arc. |
| `announce` | `boolean` | `true` | Announces confirmations in a polite status region. |
| `onOpenChange` | `(open: boolean) => void` | – | Called when the arc opens or closes. |
| `className` | `string` | – | Class on the root element. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Arrow keys | On the trigger, open the arc and focus the first action (Arrow Up focuses the last). On an action, move around the arc. |
| Home / End | Focus the first or last action. |
| Enter / Space | Fire the focused action. On the trigger, open the arc and focus the first action, or close it if open. |
| Escape | Close the arc and return focus to the trigger. |
| Tab | Close the arc and move on. |

### Accessibility

- The trigger has aria-haspopup="menu", aria-expanded, and aria-controls; actions are role="menuitem" buttons named by their label.
- The closed menu is inert, and a roving tabindex keeps one action in the tab order.
- Confirmations such as "Pinned" are read from a role="status" region when announce is on.

### Motion

- Actions swirl out along the arc in reading order and fold back in reverse; a lens glides between targeted actions and nearby actions lean toward the pointer.
- The trigger glyph morphs between ellipsis, close, and check, and a label pill springs to fit its text. It names the targeted action, shows Release to cancel when a drag leaves the arc, and shows the done text for about 1.4 seconds after firing.
- Targeting goes by angle, like a pie menu: the pointer only has to head toward an action, outside a 34px dead zone around the trigger. Releasing off the arc, or a hold without a drag, folds it away without firing.
- Reduced motion drops the swirl, blur, and magnet pull, leaving short fades and instant position changes.

### Responsive behavior

- The arc is 104px from the trigger by default and is not clamped to the viewport; set direction and radius so it opens into free space.
- Trigger and actions use touch-action none so drag-to-select works on touch; pointer magnet effects skip touch.

### Performance

- The open trigger and the label pill use backdrop blur, removed under prefers-reduced-transparency. Actions use a near solid material, so six moving items never stack blurs.
- The closed menu stays mounted but inert; with six actions the cost is small.

### Notes for AI

- Use for three to six quick actions on one object (a note, a photo) where a dropdown is too heavy and a toolbar too loud. Use dropdown-menu or context-menu for longer or text-heavy lists.
- Give each action a done string for the confirmation pill, mark destructive actions tone="danger", and set direction so the arc opens into free space.

### Related

- [Dropdown menu](https://uiarc.dev/components/dropdown-menu/markdown): A focused list of actions anchored to a trigger.
- [Context menu](https://uiarc.dev/components/context-menu/markdown): Secondary actions kept close to the selected object.
- [Action button](https://uiarc.dev/components/action-button/markdown): A compact button for frequent toolbar actions.
- [Dock](https://uiarc.dev/components/dock/markdown): A floating tool dock with a gliding label, a springy selection, and trays that grow out of it.

### Also in docks and tabs

- [Share sheet](https://uiarc.dev/components/share-sheet/markdown): A Share button that opens into a panel with copy link, access level, channels, and people to send to.
- [Action morph](https://uiarc.dev/components/action-morph/markdown): A floating button that morphs into a quick-action menu, then an inline form, then back with a check.
- [Morph nav](https://uiarc.dev/components/morph-nav/markdown): A navigation bar that morphs into rich menus, search, and a compact state as one surface.
- [Liquid tab bar](https://uiarc.dev/components/liquid-tab-bar/markdown): Tabs with a lens selection that slides between them, swaps labels cleanly, and fills in icons as it passes.

### Guidance for AI tools

Orbit menu: Hold a button and its actions orbit out, ready to pick with a drag. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Glass menu

> A glass action menu whose trigger morphs into the panel, with a highlight pill that glides between rows, one in-place submenu, and full keyboard support.

- Type: Component (special)
- Access: Arc Pro
- Page: https://uiarc.dev/components/glass-menu
- Markdown: https://uiarc.dev/components/glass-menu/markdown
- Source file: `registry/components/glass-menu/glass-menu.tsx`
- Dependencies: motion, lucide-react
- Keywords: special, glass, menu, new, glass menu, dropdown, context menu, action menu, liquid glass, frosted, shared layout, morph, submenu

### When to use

- Actions for a photo, file, or card shown over an image or a colorful canvas.
- A title menu in an editor or viewer, where the title itself opens the actions.

### When not to use

- Plain settings pages with no imagery behind the menu. Use dropdown-menu on a neutral surface.
- Navigation between pages. Use morph-nav or tabs.
- Deep hierarchies. Use a command palette or a dedicated screen.

### Installation

Glass menu is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/glass-menu
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { Copy, FolderInput, Trash2 } from "lucide-react";
import { GlassMenu } from "@/components/arc/glass-menu/glass-menu";

export function PhotoActions() {
  return (
    <GlassMenu
      label="Photo actions"
      onSelect={id => console.log(id)}
      groups={[
        { id: "edit", items: [
          { id: "duplicate", label: "Duplicate", icon: <Copy size={16} />, shortcut: "⌘D" },
          { id: "move", label: "Move to", icon: <FolderInput size={16} />, items: [
            { id: "lisbon", label: "Lisbon trip" },
            { id: "archive", label: "Archive" },
          ] },
        ] },
        { id: "danger", items: [{ id: "delete", label: "Delete", icon: <Trash2 size={16} />, danger: true }] },
      ]}
    >
      Pool house
    </GlassMenu>
  );
}
```

### API reference

#### GlassMenu

A glass action menu. The trigger morphs into the panel on a spring, a glass pill slides between rows, one submenu slides in place, and the panel morphs back into the trigger on close.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `groups` (required) | `GlassMenuGroup[]` | – | Rows in groups: `{ id, label?, items }`. Groups are separated by a hairline; `label` adds a quiet heading. |
| `children` (required) | `ReactNode` | – | Trigger content, usually a short label and a chevron or an icon. |
| `label` | `string` | `"Actions"` | Accessible name of the menu. |
| `triggerLabel` | `string` | – | Accessible name of the trigger when it only shows an icon. |
| `open` | `boolean` | – | Controlled open state. |
| `defaultOpen` | `boolean` | `false` | Initial open state when uncontrolled. |
| `onOpenChange` | `(open: boolean) => void` | – | Called when the menu opens or closes. |
| `onSelect` | `(id: string, item: GlassMenuItem) => void` | – | Called with the chosen row. Rows with `items` open their submenu instead. |
| `align` | `"start" \| "end"` | `"start"` | Which edge of the trigger the panel grows from. |
| `width` | `number` | `256` | Panel width in px, capped to the viewport. |
| `className` | `string` | – | Extra class on the root. |
| `style` | `CSSProperties` | – | Inline styles on the root. |

#### GlassMenuItem

One row.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `id` (required) | `string` | – | Stable id passed to `onSelect`. |
| `label` (required) | `string` | – | Row text. Also used for typeahead. |
| `icon` | `ReactNode` | – | A 16px icon. It takes the accent color while the row is highlighted. |
| `shortcut` | `string` | – | Shortcut hint on the right, such as "⌘D". Display only. |
| `checked` | `boolean` | – | Makes the row a checkbox item with an accent check. Leave undefined for plain actions. |
| `danger` | `boolean` | – | Uses the danger color for destructive actions. |
| `disabled` | `boolean` | – | Skipped by the keyboard and ignores clicks. |
| `items` | `GlassMenuItem[]` | – | Nested rows. The submenu slides in place with a back row, one level deep. |
| `keepOpen` | `boolean` | – | Keeps the menu open after the row is chosen. Handy for checkable rows. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Enter / Space / ArrowDown | On the trigger, open the menu with the first row highlighted. |
| ArrowUp | On the trigger, open the menu with the last row highlighted. |
| ArrowDown / ArrowUp | Move the highlight, skipping disabled rows and wrapping at the ends. |
| Home / End | Jump to the first or last row. |
| Enter / Space | Choose the highlighted row, or open its submenu. |
| ArrowRight | Open the submenu of the highlighted row. |
| ArrowLeft | In a submenu, go back to the parent row. |
| Escape | Leave the submenu, or close the menu and return focus to the trigger. |
| Tab | Close the menu and return focus to the trigger. |
| Letters | Typeahead: jump to the next row whose label starts with what you type. |

### Accessibility

- The trigger has `aria-haspopup="menu"`, `aria-expanded`, and `aria-controls` pointing at the open menu.
- Rows are `menuitem`, or `menuitemcheckbox` with `aria-checked` when `checked` is set; rows with a submenu carry `aria-haspopup`.
- Focus moves to the highlighted row, so screen readers announce it; with no row highlighted the menu itself holds focus.
- Pressing outside closes the menu without stealing focus from what was pressed.
- Pointer focus draws no ring; keyboard focus shows Arc's shared focus ring. The highlight pill marks the active row for keyboard and pointer alike.

### Motion

- The trigger's glass and the panel's glass share a layout id, so opening is one spring morph from the trigger's box to the panel's, and closing morphs back.
- Rows fade and sharpen in a beat after the glass starts to grow, so text never shows outside the glass.
- The highlight pill glides between rows on the shared morph spring.
- The submenu slides in the direction of travel while the panel height follows on a critically damped spring.
- With reduced motion the panel and submenu appear in place and the pill jumps.

### Responsive behavior

- The panel width is capped to the viewport, and the submenu slides in place instead of flying out to the side.
- Touch opens on tap; rows are 36px tall with a full width hit area.

### Performance

- The open and close morph is a transform on one element; the backdrop blur is the main paint cost, on a single layer.
- The menu mounts only while open.

### Notes for AI

- Use for a compact action menu on media, cards, or toolbars that sit over imagery, where the glass reads against the content behind it.
- Put the most common actions first, keep shortcuts accurate, and put destructive rows in their own last group with `danger`.
- Only one submenu level is supported, by design; it slides in place so it works at 320px.
- For checkable rows, pass `checked` from your state and `keepOpen` so people can toggle without reopening.

### Related

- [Dropdown menu](https://uiarc.dev/components/dropdown-menu/markdown): A focused list of actions anchored to a trigger.
- [Orbit menu](https://uiarc.dev/components/orbit-menu/markdown): Hold a button and its actions orbit out, ready to pick with a drag.
- [Morph nav](https://uiarc.dev/components/morph-nav/markdown): A navigation bar that morphs into rich menus, search, and a compact state as one surface.

### Also in glass

- [Glass segmented](https://uiarc.dev/components/glass-segmented/markdown): A glass segmented control whose liquid indicator stretches between segments and can be dragged and flung.
- [Glass card](https://uiarc.dev/components/glass-card/markdown): A glass info panel over a photo whose rim catches a pointer-following highlight while the card tilts; tap to morph it into a detail sheet.
- [Glass tab bar](https://uiarc.dev/components/glass-tabbar/markdown): A floating Liquid Glass tab bar that refracts what scrolls beneath it, with a glass lens that glides, magnifies and can be dragged between tabs, and an optional search bubble; it compacts on scroll down.

### Guidance for AI tools

Glass menu: A glass action menu whose trigger morphs into the panel, with a highlight pill that glides between rows, one in-place submenu, and full keyboard support. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Glass segmented

> A glass segmented control whose liquid indicator stretches between segments and can be dragged and flung.

- Type: Component (special)
- Access: Arc Pro
- Page: https://uiarc.dev/components/glass-segmented
- Markdown: https://uiarc.dev/components/glass-segmented/markdown
- Source file: `registry/components/glass-segmented/glass-segmented.tsx`
- Dependencies: motion
- Keywords: special, glass, input, new, segmented control, liquid glass, toggle group, tabs, gooey indicator, stretch, frosted, drag

### When to use

- Switching the view of a photo, map, or media surface.
- A compact filter over imagery, such as day, week, month on a hero chart.

### When not to use

- Plain forms on neutral surfaces. Use segmented-control.
- More than five options or long labels. Use tabs or a select.

### Installation

Glass segmented is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/glass-segmented
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { useState } from "react";
import { GlassSegmented } from "@/components/arc/glass-segmented/glass-segmented";

export function MapMode() {
  const [mode, setMode] = useState("explore");
  return (
    <GlassSegmented
      label="Map mode"
      value={mode}
      onValueChange={setMode}
      options={[
        { value: "explore", label: "Explore" },
        { value: "drive", label: "Drive" },
        { value: "transit", label: "Transit" },
      ]}
    />
  );
}
```

### API reference

#### GlassSegmented

A glass segmented control with a liquid indicator: the leading edge races ahead and the trailing edge catches up, so the drop stretches and thins between segments. Drag the selected segment to slide it.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `options` (required) | `GlassSegmentedOption[]` | – | Segments: `{ value, label, icon?, badge?, disabled? }`. `badge` shows a small count in the accent color. |
| `label` (required) | `string` | – | Accessible name of the group. |
| `value` | `string` | – | Controlled value. |
| `defaultValue` | `string` | – | Initial value when uncontrolled. Defaults to the first enabled option. |
| `onValueChange` | `(value: string) => void` | – | Called when a segment is chosen by click, keys, or a drag. |
| `size` | `"sm" \| "md"` | `"md"` | 36px or 44px tall. |
| `fullWidth` | `boolean` | `false` | Stretches to the container width with equal segments. |
| `className` | `string` | – | Extra class on the root. |
| `style` | `CSSProperties` | – | Inline styles on the root. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Tab | Focus the selected segment. |
| Arrow keys | Select the previous or next segment, wrapping at the ends. |
| Home / End | Select the first or last segment. |

### Accessibility

- The control is a `radiogroup` with a roving tab stop; each segment is a `radio` with `aria-checked`.
- The indicator is decorative SVG and hidden from assistive tech.
- Selection is also shown by label color, not only by the indicator.

### Motion

- Each edge of the indicator has its own spring: the edge facing the travel is quick, the other lags, so the drop stretches and then settles.
- The drop thins as it stretches, like liquid keeping its volume.
- Drag the selected segment and the drop follows with the same liquid lag; on release, velocity is projected to pick where it lands.
- With reduced motion the indicator jumps and dragging tracks directly.

### Responsive behavior

- `fullWidth` gives equal segments that fill the container at 320px.
- Touch drag uses `touch-action: pan-y`, so vertical scroll still works over the control.

### Performance

- The indicator is an SVG rect whose attributes update from motion values, so the stretch is paint only with no layout.
- Segment positions are measured once and on resize.

### Notes for AI

- Use for two to five short, mutually exclusive views on top of imagery or maps, where the glass reads against the content.
- Use `fullWidth` on mobile or inside a card; keep labels to one or two words.
- Drag only starts on the selected segment, so taps elsewhere stay plain clicks.

### Related

- [Segmented control](https://uiarc.dev/components/segmented-control/markdown): Switch between a small set of related views.
- [Liquid tab bar](https://uiarc.dev/components/liquid-tab-bar/markdown): Tabs with a lens selection that slides between them, swaps labels cleanly, and fills in icons as it passes.
- [Billing toggle](https://uiarc.dev/components/billing-toggle/markdown): A monthly and yearly switch with a savings badge and prices that roll to the new amount.

### Also in glass

- [Glass menu](https://uiarc.dev/components/glass-menu/markdown): A glass action menu whose trigger morphs into the panel, with a highlight pill that glides between rows, one in-place submenu, and full keyboard support.
- [Glass card](https://uiarc.dev/components/glass-card/markdown): A glass info panel over a photo whose rim catches a pointer-following highlight while the card tilts; tap to morph it into a detail sheet.
- [Glass tab bar](https://uiarc.dev/components/glass-tabbar/markdown): A floating Liquid Glass tab bar that refracts what scrolls beneath it, with a glass lens that glides, magnifies and can be dragged between tabs, and an optional search bubble; it compacts on scroll down.

### Guidance for AI tools

Glass segmented: A glass segmented control whose liquid indicator stretches between segments and can be dragged and flung. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Glass card

> A glass info panel over a photo whose rim catches a pointer-following highlight while the card tilts; tap to morph it into a detail sheet.

- Type: Component (special)
- Access: Arc Pro
- Page: https://uiarc.dev/components/glass-card
- Markdown: https://uiarc.dev/components/glass-card/markdown
- Source file: `registry/components/glass-card/glass-card.tsx`
- Dependencies: motion
- Keywords: special, glass, card, new, glass card, glassmorphism card, profile card, tilt card, specular highlight, frosted glass, expandable card, shared layout

### When to use

- Profile, host, or creator cards on a landing page or in a discovery grid.
- A featured product or stay where the photo sells and the details can wait for a tap.

### When not to use

- Dense grids of many cards; tilt and glass on every tile gets busy. Use card.
- Cards that should open a full page; use card-to-article.

### Installation

Glass card is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/glass-card
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { GlassCard } from "@/components/arc/glass-card/glass-card";

export function Host() {
  return (
    <GlassCard image="/people/jasmine.jpg" imageAlt="Portrait of Jasmine Brooks" title="Jasmine Brooks" subtitle="Design lead, Lisbon" aside="4.9">
      <p>Leads design systems at Meridian.</p>
      <button type="button">Follow</button>
    </GlassCard>
  );
}
```

### API reference

#### GlassCard

A photo card with a glass info panel. The panel's rim catches a specular highlight under the pointer, the card tilts a few degrees toward it, and a tap morphs the panel up into a detail sheet.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `image` (required) | `string` | – | Photo behind the glass. |
| `imageAlt` (required) | `string` | – | Alt text for the photo. Pass an empty string when it is decorative. |
| `title` (required) | `string` | – | Main line in the glass panel, such as a name or a product. |
| `subtitle` | `ReactNode` | – | Second line under the title. |
| `aside` | `ReactNode` | – | Small element at the end of the header, such as a price, a rating, or a status. |
| `children` | `ReactNode` | – | Detail content revealed when the card expands. Buttons inside stay interactive and do not toggle the card. |
| `open` | `boolean` | – | Controlled expanded state. |
| `defaultOpen` | `boolean` | `false` | Initial expanded state when uncontrolled. |
| `onOpenChange` | `(open: boolean) => void` | – | Called when the card expands or collapses. |
| `tilt` | `number` | `6` | Maximum tilt in degrees. 0 turns tilt off. |
| `className` | `string` | – | Extra class on the card. Set its width here; the card keeps a 4 by 5 ratio. |
| `style` | `CSSProperties` | – | Inline style on the card. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Tab | Moves to the header button, then into the detail content when open. |
| Enter / Space | On the header, expands or collapses the card. |
| Escape | Collapses the card and returns focus to the header. |

### Accessibility

- The glass header is a real button with aria-expanded and aria-controls pointing at the detail region.
- Clicking anywhere on the photo is a pointer shortcut for the same toggle; keyboard users use the header.
- Detail content is removed from the DOM when collapsed, so hidden buttons are never focusable.
- Under prefers-reduced-transparency the glass turns solid.

### Motion

- Tilt and highlight follow the pointer through springs, so the card eases into position and settles back when the pointer leaves. Touch input skips the tilt.
- Expanding is one shared-layout spring on the panel; the header keeps its position and the details fade up with a short blur.
- The photo scales up slightly and the floor shade deepens while open.
- Reduced motion removes tilt and the morph; the panel switches size and the details fade.

### Responsive behavior

- Fills its container width and keeps a 4 by 5 ratio, so it works from 280px up.
- Touch devices get the tap to expand and skip the pointer tilt.

### Performance

- Pointer tracking writes springs and CSS variables only, with no React renders per frame.
- One backdrop filter on the panel. The highlight is a masked gradient, not a filter.

### Notes for AI

- Use it for one featured entity over a strong photo: a person, a stay, a product. Put the essentials in title, subtitle, and aside, and the rest in children.
- Keep detail content short: a line of text, three stats, and one or two actions. Longer content belongs on a page.
- Give the card a width through className; it sets its own height from the 4 by 5 ratio.
- The accent belongs in the detail actions or a rating icon, not on the glass itself.

### Related

- [Holo card](https://uiarc.dev/components/holo-card/markdown): A member card that tilts toward you with a holographic foil and flips to its back.
- [Expandable card](https://uiarc.dev/components/expandable-card/markdown): Give a dense card more room when requested.
- [Card to article](https://uiarc.dev/components/card-to-article/markdown): Story cards that open into full articles with one seamless morph and shrink back into their exact slot when dragged down.

### Also in glass

- [Glass menu](https://uiarc.dev/components/glass-menu/markdown): A glass action menu whose trigger morphs into the panel, with a highlight pill that glides between rows, one in-place submenu, and full keyboard support.
- [Glass segmented](https://uiarc.dev/components/glass-segmented/markdown): A glass segmented control whose liquid indicator stretches between segments and can be dragged and flung.
- [Glass tab bar](https://uiarc.dev/components/glass-tabbar/markdown): A floating Liquid Glass tab bar that refracts what scrolls beneath it, with a glass lens that glides, magnifies and can be dragged between tabs, and an optional search bubble; it compacts on scroll down.

### Guidance for AI tools

Glass card: A glass info panel over a photo whose rim catches a pointer-following highlight while the card tilts; tap to morph it into a detail sheet. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Glass tab bar

> A floating Liquid Glass tab bar that refracts what scrolls beneath it, with a glass lens that glides, magnifies and can be dragged between tabs, and an optional search bubble; it compacts on scroll down.

- Type: Component (special)
- Access: Arc Pro
- Page: https://uiarc.dev/components/glass-tabbar
- Markdown: https://uiarc.dev/components/glass-tabbar/markdown
- Source file: `registry/components/glass-tabbar/glass-tabbar.tsx`
- Dependencies: motion
- Keywords: special, glass, navigation, new, liquid glass, glass tab bar, floating tab bar, bottom navigation, mobile tab bar, ios tab bar, refraction, lens indicator, draggable tab indicator, collapsing tab bar, hide on scroll, glassmorphism navigation

### When to use

- Mobile web apps and PWAs with three to five top level sections and one global action such as search.
- Content feeds where the bar should step aside while reading and come back on scroll up.

### When not to use

- Desktop layouts with many sections; use a sidebar or morph-nav.
- Switching views inside a card; use segmented-control or tabs.

### Installation

Glass tab bar is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/glass-tabbar
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { GlassTabBar } from "@/components/arc/glass-tabbar/glass-tabbar";
import { Bookmark, Compass, House, Search, UserRound } from "lucide-react";

export function AppShell() {
  const [tab, setTab] = useState("home");
  return (
    <GlassTabBar
      className="tabbar"
      value={tab}
      onValueChange={setTab}
      items={[
        { value: "home", label: "Home", icon: <House /> },
        { value: "explore", label: "Explore", icon: <Compass /> },
        { value: "saved", label: "Saved", icon: <Bookmark />, badge: 3 },
        { value: "profile", label: "Profile", icon: <UserRound /> },
      ]}
      action={{ value: "search", label: "Search", icon: <Search /> }}
    />
  );
}
```

### API reference

#### GlassTabBar

A floating Liquid Glass tab bar. The bar refracts what scrolls under it, and the selected tab sits under a glass lens that glides, lifts, and magnifies as it moves and can be dragged across the tabs. An optional round action bubble sits beside it, and the bar shrinks to a compact pill of icons on scroll down.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `items` (required) | `GlassTabBarItem[]` | – | Tabs with value, label, icon, and an optional badge. |
| `value` | `string` | – | Controlled active tab. A value that matches no tab, or the action, hides the lens. |
| `defaultValue` | `string` | – | Initial active tab when uncontrolled. Defaults to the first item. |
| `onValueChange` | `(value: string) => void` | – | Called when a tab or the action is chosen by tap, drag, or keyboard. |
| `action` | `GlassTabBarItem` | – | A separate round glass tab beside the bar, such as search. It takes part in selection and keyboard order like any tab. |
| `compact` | `boolean` | – | Controlled compact state. |
| `defaultCompact` | `boolean` | `false` | Initial compact state when uncontrolled. |
| `onCompactChange` | `(compact: boolean) => void` | – | Called when the bar shrinks or grows. |
| `scrollRef` | `RefObject<HTMLElement \| null>` | – | Scroll container to watch. Leave it out to watch the window. |
| `collapseOnScroll` | `boolean` | `true` | Shrink on scroll down and grow on scroll up. |
| `label` | `string` | `"Tabs"` | Accessible name of the navigation and its tab list. |
| `className` | `string` | – | Extra class on the nav. Position the bar here, usually fixed or absolute at the bottom. |
| `style` | `CSSProperties` | – | Inline style on the nav. |

#### GlassTabBarItem

One tab, or the action.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` (required) | `string` | – | Unique value. |
| `label` (required) | `string` | – | Visible label and accessible name. The action shows only its icon and uses the label as its name. |
| `icon` (required) | `ReactNode` | – | Icon at 22px; lucide icons are sized automatically. |
| `badge` | `number \| string` | – | Count shown as an accent badge on the icon. 0 or empty hides it. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Tab | Moves focus to the selected tab; the tab list is one stop. |
| Arrow left / Arrow right | Moves to and selects the previous or next tab, including the action, wrapping around. |
| Home / End | Selects the first tab or the last one. |
| Enter / Space | Selects the focused tab and grows the bar if it is compact. |

### Accessibility

- Renders a nav landmark around a tablist; every tab, including the action, has role="tab" and aria-selected, with a roving tabindex.
- Labels stay in the accessibility tree when the bar is compact, so each tab keeps its name.
- Badges carry hidden text such as "3 new" for screen readers.
- Selection is carried by the lens, the accent tint, and aria-selected, never by color alone.
- Reduced transparency swaps the glass for a solid raised surface; increased contrast strengthens the tint, border, and ink.
- Pointer focus draws no ring; keyboard focus shows Arc's shared focus ring.

### Motion

- The lens glides on the smooth spring, which never overshoots. Its speed lifts it off the bar: it grows, stretches along the direction of travel, and turns into a clear lens that magnifies the icons under it, then settles back into a soft fill.
- Each tab's tint and icon scale follow the lens position, so the accent glides with it instead of switching.
- Press the selected tab and the lens lifts; drag past a few pixels and it follows the pointer across the bar; release snaps it to the nearest tab and selects it.
- One spring drives the compact morph: slot width, bar height, icon lift, and label fade all read from it, so the lens stays on its tab mid morph.
- Reduced motion moves the lens and the size instantly, with no lift, stretch, or magnification.

### Responsive behavior

- Tabs share the available width, from 78px down to 56px each, so five tabs and an action fit a 390px screen. Compact tabs are 50px.
- The bar and lens take touch with pan-y, so vertical scrolling that starts on the bar still works.

### Performance

- Motion values drive every frame; React renders only on tab, compact, or size changes. Nothing animates at rest.
- Chromium gets real refraction: an SVG displacement filter inside backdrop-filter bends the backdrop at the rim, with a slight per channel dispersion. Safari and Firefox are detected and keep a blur and saturation glass.
- The lens refraction is a fixed layer clipped to the lens; while it moves, only the clip and the filter's map rectangle update.

### Notes for AI

- Use it as the primary navigation of a mobile web app. Keep it to three to five tabs with short labels, plus at most one action.
- Pass the page's scroll container as scrollRef when the app scrolls inside an element instead of the window.
- Place it with position fixed or absolute at the bottom; the component centers itself and only the glass takes pointer events.
- Put photos or colorful content behind it; the material is designed to be seen over real content, not a flat page.
- Leave content room at the bottom (about 110px) so the last item is not hidden behind the bar.

### Related

- [Liquid tab bar](https://uiarc.dev/components/liquid-tab-bar/markdown): Tabs with a lens selection that slides between them, swaps labels cleanly, and fills in icons as it passes.
- [Morph nav](https://uiarc.dev/components/morph-nav/markdown): A navigation bar that morphs into rich menus, search, and a compact state as one surface.
- [Dock](https://uiarc.dev/components/dock/markdown): A floating tool dock with a gliding label, a springy selection, and trays that grow out of it.
- [Tabs](https://uiarc.dev/components/tabs/markdown): Switch between related content in the same context.

### Also in glass

- [Glass menu](https://uiarc.dev/components/glass-menu/markdown): A glass action menu whose trigger morphs into the panel, with a highlight pill that glides between rows, one in-place submenu, and full keyboard support.
- [Glass segmented](https://uiarc.dev/components/glass-segmented/markdown): A glass segmented control whose liquid indicator stretches between segments and can be dragged and flung.
- [Glass card](https://uiarc.dev/components/glass-card/markdown): A glass info panel over a photo whose rim catches a pointer-following highlight while the card tilts; tap to morph it into a detail sheet.

### Guidance for AI tools

Glass tab bar: A floating Liquid Glass tab bar that refracts what scrolls beneath it, with a glass lens that glides, magnifies and can be dragged between tabs, and an optional search bubble; it compacts on scroll down. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Sheet stack

> Nested sheets that stack with depth, drag to dismiss, and become stacked dialogs on wide screens.

- Type: Component (special)
- Access: Arc Pro
- Page: https://uiarc.dev/components/sheet-stack
- Markdown: https://uiarc.dev/components/sheet-stack/markdown
- Source file: `registry/components/sheet-stack/sheet-stack.tsx`
- Dependencies: motion, lucide-react
- Keywords: special, new, react sheet stack, nested bottom sheets, stacked modals, drill down sheet, ios sheet stack, nested dialogs, draggable sheet, sheet navigation

### When to use

- Mobile settings where each row opens a deeper page and back should feel spatial.
- Nested pickers, such as choosing a workspace and then a project inside it.
- Flows that should be a bottom sheet on phones and a centered dialog on desktop from one declaration.

### When not to use

- Use dialog for a single confirmation or form with no nested steps.
- Use bottom-sheet for one sheet with snap points.
- Use multi-step-form when steps are sequential rather than drill-down.

### Installation

Sheet stack is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/sheet-stack
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { Sheet, SheetStack, SheetTrigger, useSheetStack } from "@/components/arc/sheet-stack/sheet-stack";

function SaveButton() {
  const { close } = useSheetStack();
  return <button type="button" onClick={close}>Save</button>;
}

export function Settings() {
  return (
    <SheetStack>
      <SheetTrigger sheet="settings">Settings</SheetTrigger>

      <Sheet id="settings" title="Settings">
        <SheetTrigger sheet="notifications">Notifications</SheetTrigger>
      </Sheet>

      <Sheet id="notifications" title="Notifications" footer={<SaveButton />}>
        <label><input type="checkbox" defaultChecked /> Email me about mentions</label>
      </Sheet>
    </SheetStack>
  );
}
```

### API reference

#### SheetStack

Holds the stack of open sheets and renders the layer they appear in. Declare every Sheet inside one SheetStack.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` (required) | `ReactNode` | – | Page content, triggers, and Sheet declarations. |
| `stack` | `string[]` | – | Controlled ids of open sheets, bottom first. Leave undefined for uncontrolled use. |
| `defaultStack` | `string[]` | `[]` | Sheets open at first when uncontrolled. |
| `onStackChange` | `(stack: string[]) => void` | – | Called when sheets are pushed or popped. |
| `mode` | `"auto" \| "sheet" \| "dialog"` | `"auto"` | auto picks bottom sheets below breakpoint and centered dialogs above it. |
| `breakpoint` | `number` | `640` | Width in px of the viewport, or the container when contained, where auto switches to dialogs. |
| `contained` | `boolean` | `false` | Fill the nearest positioned ancestor instead of the viewport. |

#### Sheet

One level of the stack. Renders nothing until its id is pushed.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `id` (required) | `string` | – | Id used by push, popTo, SheetTrigger, and the stack array. |
| `title` (required) | `string` | – | Heading and accessible name. |
| `description` | `string` | – | A line under the title, wired as the dialog description. |
| `children` (required) | `ReactNode` | – | Scrolling body content. |
| `footer` | `ReactNode` | – | A row pinned under the scrolling body, such as the primary action. |
| `backLabel` | `string` | – | Label for the back button of a sheet opened from this one. Defaults to title. |
| `dismissible` | `boolean` | `true` | Allow drag and fling to dismiss. |
| `className` | `string` | – | Class on the panel. |
| `ref` | `Ref<HTMLDivElement>` | – | The panel element. |

#### SheetTrigger

A button that opens a sheet on top of the stack. Takes every button attribute.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `sheet` (required) | `string` | – | Id of the sheet to push. |
| `ref` | `Ref<HTMLButtonElement>` | – | The button element. |
| `...props` | `ButtonHTMLAttributes<HTMLButtonElement>` | – | Forwarded to the button. Call preventDefault in onClick to skip the push. |

#### useSheetStack

Returns { stack, push, pop, popTo, close } for buttons inside or beside the sheets. Throws outside SheetStack.

No props.

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Escape | Closes the top sheet only. |
| Tab / Shift+Tab | Cycles focus inside the top sheet. |
| Enter / Space | Runs back, close, and trigger buttons. |

### Accessibility

- Each panel is a dialog labelled by its title and described by description; only the top one is aria-modal, lower ones are inert.
- Opening moves focus into the new sheet; popping returns focus to the element that opened it.
- The back button names the sheet it returns to; the close button reads "Close all" when more than one sheet is open.
- Page scroll is locked while any sheet is open, unless contained.

### Motion

- A new sheet rises from the bottom edge (or eases in as a dialog) while the one below scales back 5%, dims, and peeks above it.
- The top sheet follows a vertical drag with rubber banding upward; the sheets below ease back up as it goes and a fling past 35% or 450px/s pops it.
- Height changes spring as content changes, and all springs keep velocity when interrupted.
- Reduced motion removes the depth scale, lift, and drag physics; sheets fade in and out.

### Responsive behavior

- mode="auto" measures the layer with a ResizeObserver: under breakpoint (640px) sheets rise from the bottom; at or above it they are centered dialogs.
- Each level loses room for the peek (10px per level for sheets, 14px for dialogs), and bodies scroll inside past that height.
- Drag to dismiss works with any pointer; a drag starting in a scrolled body scrolls instead of dragging.

### Performance

- Transforms and dims come from motion values, so drags and depth changes do not rerender React per frame.
- Each open sheet has a ResizeObserver on its content; the stack is meant for a handful of levels, not dozens.

### Notes for AI

- Use for short drill-down flows (settings, filters, account steps) where each level should keep its parent in view.
- Declare every Sheet once inside the SheetStack; open with SheetTrigger or useSheetStack().push. Pushing an open id pops back to it.
- Add data-sheet-no-drag to content that handles its own vertical drags, such as sliders or maps.
- For a single sheet with no nesting use bottom-sheet or drawer.

### Related

- [Bottom sheet](https://uiarc.dev/components/bottom-sheet/markdown): A sheet that rests at a peek or full height and follows your finger.
- [Drawer](https://uiarc.dev/components/drawer/markdown): A temporary side surface for focused work.
- [Dialog](https://uiarc.dev/components/dialog/markdown): A focused surface for decisions that need attention.
- [Settings page](https://uiarc.dev/components/blocks/settings-page/markdown): Account settings with a gliding section nav and a save bar that morphs in as you edit.
- [Multi-step form](https://uiarc.dev/components/blocks/multi-step-form/markdown): A guided form that presents one decision at a time and preserves progress.

### Also in surfaces

- [Wallet stack](https://uiarc.dev/components/wallet-stack/markdown): Fan a stack of cards and lift one out to see its activity.
- [Control center](https://uiarc.dev/components/control-center/markdown): Workspace quick settings: tiles that morph into detail, a duration dial, and rubber-banded meters.
- [Holo card](https://uiarc.dev/components/holo-card/markdown): A member card that tilts toward you with a holographic foil and flips to its back.
- [Card to article](https://uiarc.dev/components/card-to-article/markdown): Story cards that open into full articles with one seamless morph and shrink back into their exact slot when dragged down.
- [Link unfurl](https://uiarc.dev/components/link-unfurl/markdown): A composer where pasting a URL shows a loading shimmer on the link, then unfurls it into a rich preview card with title, image and favicon in one morph, which can be collapsed back to the inline link or removed.

### Guidance for AI tools

Sheet stack: Nested sheets that stack with depth, drag to dismiss, and become stacked dialogs on wide screens. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Wallet stack

> Fan a stack of cards and lift one out to see its activity.

- Type: Component (special)
- Access: Arc Pro
- Page: https://uiarc.dev/components/wallet-stack
- Markdown: https://uiarc.dev/components/wallet-stack/markdown
- Source file: `registry/components/wallet-stack/wallet-stack.tsx`
- Dependencies: motion, lucide-react
- Keywords: special, wallet, cards, react wallet, credit card stack, apple wallet ui, payment cards component, card stack animation, fintech card ui

### When to use

- A few payment cards, passes, or memberships where people open one to see its balance and activity.
- Fintech or wallet screens that want a physical card metaphor with realistic materials.

### When not to use

- Use card-stack for generic swipeable content that is not a card wallet.
- Use a plain list or data-grid for many accounts.
- Use expandable-card when one card just needs to grow in place.

### Installation

Wallet stack is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/wallet-stack
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { WalletStack } from "@/components/arc/wallet-stack/wallet-stack";

export function Cards() {
  return (
    <WalletStack
      cards={[
        { id: "debit", issuer: "Northbank", product: "Everyday debit", lastFour: "4821", holder: "Ada Lovelace", expires: "09/29", variant: "metal",
          balance: 2480.5, balanceLabel: "Available",
          transactions: [{ id: "t1", merchant: "Blue Bottle", detail: "Coffee · Today", amount: -6.5 }] },
        { id: "travel", issuer: "Northbank", product: "Travel credit", lastFour: "0917", holder: "Ada Lovelace", expires: "03/28", variant: "color", tint: "oklch(42% .15 262)",
          balance: 812.4, balanceLabel: "Spent this month", transactions: [] },
      ]}
      onSelectedChange={card => console.log(card?.id)}
    />
  );
}
```

### API reference

#### WalletStack

A stack of payment cards with real materials and depth: brushed metal, a guilloche black card, frosted glass, and deep color, each with an EMV chip, contactless mark, embossed number, and a light that follows the pointer or device tilt. Hover to fan the stack, drag or use the arrow keys to cycle cards, and choose a card to lift it into its balance and recent activity.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `cards` (required) | `{ id: string; issuer: string; product: string; lastFour: string; holder: string; variant?: "metal" \| "black" \| "glass" \| "color"; tint?: string; expires?: string; network?: ReactNode; image?: string; balance: number; balanceLabel: string; transactions: { id: string; merchant: string; detail: string; amount: number; icon?: ReactNode; avatar?: string }[] }[]` | – | Cards in stack order, the first in front. variant picks the material (metal by default); tint is any CSS color for the color variant; expires shows as Valid thru; network replaces the built-in fictional Halo mark, or null hides it; image is optional artwork under the finish. Amounts are negative for spending and positive for money in; avatar replaces the icon for transfers between people. The older finish field still works: paper maps to metal, graphite to black, clay and photo to color. |
| `label` | `string` | `"Wallet"` | Heading above the stack, also its accessible name. |
| `currency` | `string` | `"USD"` | ISO currency code for balances and amounts. |
| `locale` | `string` | `"en-US"` | Locale for number formatting. |
| `onSelectedChange` | `(card: WalletStackCard \| null) => void` | – | Called with the opened card, or null when it goes back into the stack. |
| `className` | `string` | – | Extra class on the root. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Arrow keys | Down or Right brings the next card to the front, Up or Left the previous one. While a card is open they switch the open card. Home and End jump to the first and last card. |
| Enter / Space | Opens the front card into its balance and activity, or puts the open card back. |
| Escape | Puts the open card back into the stack and returns focus to it. |

### Accessibility

- The stack is a labelled group with a described keyboard hint. Only the front card is in the tab order (roving tabindex); each card is a button named by issuer, product, last four digits, position, and balance, with aria-expanded while open.
- The masked digits and decorative artwork are hidden from assistive technology; only the last four digits are read.
- The activity region is inert until a card is open; the header switches from the card count to an All cards button that closes it.
- Cycling and opening are announced in a polite live region, and focus returns to the card when it goes back into the stack.

### Motion

- Every card's transform is one pure function of a continuous stack position, the open amount, and the fan amount, so springs, drags, and interruptions all move the same shape. Z order never changes, so cards never pop over one another.
- Hovering fans the stack upward on a no-overshoot spring; the hovered card rises out of the fan and its shadow deepens. The front card tilts up to 5 degrees and a specular highlight follows the pointer, or device tilt on phones that report it.
- Dragging down pushes the front card into the pocket at the bottom and brings the next one forward one to one under the pointer; dragging up pulls it back. A flick lands where its momentum projects, one card at a time, with rubber banding past the first and last card.
- Choosing a card lifts it to the top on one critically damped spring while the others tuck into the pocket; its balance counts up and three transactions stagger in. Pull the open card down to put it back, or flick it.
- Only transform and opacity animate: shadows fade their opacity, the light moves a pre-painted layer. MotionConfig and a reduced motion branch remove travel, tilt, and the light; state changes apply instantly.

### Responsive behavior

- The wallet is min(100%, 18.5rem) wide. Cards keep the ID-1 ratio of 85.6 by 53.98 and every detail is sized in container units, so the card scales as one object; the stage height follows the card height.
- The stage uses touch-action pan-x, so a vertical drag cycles cards while horizontal page gestures still work. An open card switches to touch-action none so it can be pulled down by touch.
- Pointer tilt and the fan react to mouse only; on phones that report device orientation the light follows the tilt of the device instead.

### Performance

- Position, open amount, fan, and stage size are motion values, so gestures and springs never re-render React; the stage is measured once before paint and on resize.
- Only transform and opacity animate. Shadows and the specular light are painted once and faded or moved; the stage clips vertically instead of masking so the glass card's backdrop blur stays cheap and correct.
- Every card renders its artwork and transactions; keep the stack to a handful of cards.

### Notes for AI

- Choose it for a few payment cards, passes, or memberships where people open one at a time to see its activity. Use card-stack for generic swipeable content and a plain list for many accounts.
- Pass fully shaped cards including balanceLabel and transactions, and a variant per card so the materials read as different cards. Selection is managed internally and reported through onSelectedChange.
- The network mark is fictional. Never pass real card numbers; only lastFour is shown.

### Related

- [Card stack](https://uiarc.dev/components/card-stack/markdown): Review a deck one card at a time, with a throw and an undo.
- [Expandable card](https://uiarc.dev/components/expandable-card/markdown): Give a dense card more room when requested.

### Also in surfaces

- [Sheet stack](https://uiarc.dev/components/sheet-stack/markdown): Nested sheets that stack with depth, drag to dismiss, and become stacked dialogs on wide screens.
- [Control center](https://uiarc.dev/components/control-center/markdown): Workspace quick settings: tiles that morph into detail, a duration dial, and rubber-banded meters.
- [Holo card](https://uiarc.dev/components/holo-card/markdown): A member card that tilts toward you with a holographic foil and flips to its back.
- [Card to article](https://uiarc.dev/components/card-to-article/markdown): Story cards that open into full articles with one seamless morph and shrink back into their exact slot when dragged down.
- [Link unfurl](https://uiarc.dev/components/link-unfurl/markdown): A composer where pasting a URL shows a loading shimmer on the link, then unfurls it into a rich preview card with title, image and favicon in one morph, which can be collapsed back to the inline link or removed.

### Guidance for AI tools

Wallet stack: Fan a stack of cards and lift one out to see its activity. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Control center

> Workspace quick settings: tiles that morph into detail, a duration dial, and rubber-banded meters.

- Type: Component (special)
- Access: Arc Pro
- Page: https://uiarc.dev/components/control-center
- Markdown: https://uiarc.dev/components/control-center/markdown
- Source file: `registry/components/control-center/control-center.tsx`
- Dependencies: motion, lucide-react
- Keywords: special, settings, control center, react control center, quick settings panel, ios control center, settings toggles, focus mode ui, volume slider panel

### When to use

- A quick settings panel with a handful of toggles and levels for a web workspace.
- Focus session controls with a duration dial and allowed people.
- Notification channel toggles grouped behind one tile.

### When not to use

- Use switch, slider, and radio-group directly in a regular settings form.
- Use time-dial to pick a time across time zones.
- Use dropdown-menu for a short list of commands.

### Installation

Control center is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/control-center
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { ControlCenter } from "@/components/arc/control-center/control-center";
import { Moon, Briefcase } from "lucide-react";

export function QuickSettings() {
  return (
    <ControlCenter
      focusModes={[
        { id: "deep", label: "Deep work", icon: Briefcase, description: "Silences everything but mentions", defaultMinutes: 50 },
        { id: "rest", label: "Rest", icon: Moon, description: "Silences all alerts", defaultMinutes: 30 },
      ]}
      channels={[{ id: "mentions", label: "Mentions", defaultOn: true }, { id: "deploys", label: "Deploys" }]}
      onStateChange={state => saveSettings(state)}
    />
  );
}
```

### API reference

#### ControlCenter

Quick settings for a web workspace: focus sessions, notification channels, presenting mode, alert volume, and text size.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `focusModes` (required) | `{ id: string; label: string; icon: LucideIcon; description: string; defaultMinutes: number }[]` | – | Focus modes offered in the focus detail. defaultMinutes seeds the session dial. |
| `channels` (required) | `{ id: string; label: string; description?: string; defaultOn?: boolean }[]` | – | Notification channels toggled in the notifications detail. |
| `people` | `{ id: string; name: string; avatar: string }[]` | `[]` | People who can still reach you during a focus session. |
| `defaultVolume` | `number` | `60` | Initial alert volume, 0 to 100. |
| `defaultTextSize` | `number` | `100` | Initial text size as a percent of the base, 85 to 130. |
| `formatTime` | `(date: Date) => string` | – | Formats the end of a session. Defaults to a short en-US clock time. |
| `onStateChange` | `(state: { focus: { mode: string; minutes: number; until: string } \| null; notifications: boolean; channels: Record<string, boolean>; presenting: boolean; volume: number; textSize: number }) => void` | – | Called with the full settings state after any change, including each step while a meter is dragged. Focus detail edits apply only on Start or Update session. |
| `label` | `string` | `"Quick settings"` | Accessible name of the panel. |
| `className` | `string` | – | Extra class on the panel. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Enter / Space | Toggles a tile or opens its detail from the chevron. On the Focus tile with no session, starts the first mode at its default length. |
| Arrow keys | Adjust the meters by one step (1% volume, 5% text size) and the session dial by 5 minutes. |
| PageUp / PageDown | Adjust meters by four steps and the dial by 15 minutes. |
| Home / End | Set a meter to its limit, or the dial to 5 or 120 minutes. |
| Escape | Closes the open detail and returns focus to its chevron. |
| Tab | Cycles focus inside the open detail. |

### Accessibility

- Tiles are toggle buttons with aria-pressed; chevrons open a modal dialog with a focus trap and aria-haspopup.
- Meters and the session dial are sliders with formatted aria-valuetext; channel toggles use role="switch".
- Focus modes are a radiogroup, and the grid behind an open detail is inert. Clicking the scrim closes the detail.

### Motion

- A tile grows into its detail with a shared element morph, and meters follow the pointer 1:1 from where they were grabbed, with rubber-banded edges. A tap without a drag jumps the meter to that spot, and the track swells slightly while held.
- The session dial counts minutes as the knob travels, keeps counting across twelve o'clock, resists past 5 and 120 minutes, and snaps to 5 minute steps on release.
- Icons and status text swap with a short blur; the dial knob springs to snapped values.
- Reduced motion is applied through MotionConfig, removing travel and keeping fades.

### Responsive behavior

- The panel is min(100%, 22.5rem) wide with a fixed height, sized for a popover or side column.
- Below 360px viewport width padding tightens and the session dial shrinks from 164px to 150px.
- Meters keep touch-action pan-y so the page still scrolls, while the dial uses none so it can be turned by touch.

### Performance

- Tiles morph into details through shared layoutIds; only one detail is mounted at a time.
- Meters follow the pointer through motion values, so drags do not re-render the panel per frame.

### Notes for AI

- Choose it for a quick settings panel with a handful of toggles and levels. For ordinary forms use switch, slider, and radio-group directly.
- It is uncontrolled: seed it with defaults and persist through onStateChange. Pass lucide icon components (not elements) for focus modes.

### Related

- [Switch](https://uiarc.dev/components/switch/markdown): A tactile toggle for settings that take effect immediately.
- [Slider](https://uiarc.dev/components/slider/markdown): Pick a value or a range on a track that follows your finger.
- [Radio group](https://uiarc.dev/components/radio-group/markdown): Choose one option from a visible set.
- [Time dial](https://uiarc.dev/components/time-dial/markdown): Spin a dial to pick an hour and see which team cities are at work.
- [Dialog](https://uiarc.dev/components/dialog/markdown): A focused surface for decisions that need attention.

### Also in surfaces

- [Sheet stack](https://uiarc.dev/components/sheet-stack/markdown): Nested sheets that stack with depth, drag to dismiss, and become stacked dialogs on wide screens.
- [Wallet stack](https://uiarc.dev/components/wallet-stack/markdown): Fan a stack of cards and lift one out to see its activity.
- [Holo card](https://uiarc.dev/components/holo-card/markdown): A member card that tilts toward you with a holographic foil and flips to its back.
- [Card to article](https://uiarc.dev/components/card-to-article/markdown): Story cards that open into full articles with one seamless morph and shrink back into their exact slot when dragged down.
- [Link unfurl](https://uiarc.dev/components/link-unfurl/markdown): A composer where pasting a URL shows a loading shimmer on the link, then unfurls it into a rich preview card with title, image and favicon in one morph, which can be collapsed back to the inline link or removed.

### Guidance for AI tools

Control center: Workspace quick settings: tiles that morph into detail, a duration dial, and rubber-banded meters. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Holo card

> A member card that tilts toward you with a holographic foil and flips to its back.

- Type: Component (special)
- Access: Arc Pro
- Page: https://uiarc.dev/components/holo-card
- Markdown: https://uiarc.dev/components/holo-card/markdown
- Source file: `registry/components/holo-card/holo-card.tsx`
- Dependencies: motion
- Keywords: special, motion, new, holographic card, holo card, foil card, pokemon card effect, tilt card, 3d card flip, membership card, gyroscope tilt, shiny card

### When to use

- A membership or subscription card on an account or welcome page.
- A shareable profile, badge, or achievement that people will screenshot.
- A collectible or reward reveal.

### When not to use

- Use card for ordinary content; the effect is too loud for lists.
- Use depth-cards when several items need a subtle parallax.
- Avoid it for text people need to read carefully; the sheen moves over the content.

### Installation

Holo card is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/holo-card
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { HoloCard } from "@/components/arc/holo-card/holo-card";

export function MemberCard() {
  return (
    <HoloCard
      label="Jasmine Brooks, member card"
      front={<div className="front">...</div>}
      back={<div className="back">...</div>}
    />
  );
}
```

### API reference

#### HoloCard

A collectible style card that leans toward the pointer with a holographic foil, a glitter layer, and a glare that follow the angle. Click or press Enter to spin it to its back; on phones it can follow device tilt.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `front` (required) | `ReactNode` | – | The face. Fill the whole card; it is clipped to the rounded shape. |
| `back` | `ReactNode` | – | The back. Leave it out for a tilt only card that is not a button. |
| `flipped` | `boolean` | – | Controlled flipped state. |
| `defaultFlipped` | `boolean` | `false` | Initial flipped state when uncontrolled. |
| `onFlippedChange` | `(flipped: boolean) => void` | – | Called when the card is flipped. |
| `maxTilt` | `number` | `14` | Largest lean in degrees. |
| `intensity` | `number` | `1` | Strength of foil, glitter, and glare from 0 to 1. |
| `gyroscope` | `boolean` | `true` | Follows device tilt on touch screens. On iOS permission is asked on the first tap. |
| `label` | `string` | – | Accessible name. Defaults to the text on the card. |
| `className` | `string` | – | Class on the root. Set width here; the card keeps a 5:7 ratio. |
| `style` | `CSSProperties` | – | Inline style on the root. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Tab | Focuses the card when it has a back. |
| Enter / Space | Flips the card. |

### Accessibility

- With a back, the card is role="button" with aria-roledescription="flip card" and aria-pressed for the flipped state.
- The hidden face is aria-hidden, so assistive tech reads only the side that is showing.
- Foil, glitter, and glare layers are decorative and aria-hidden.
- prefers-reduced-transparency removes the foil and glitter.

### Motion

- Tilt follows the pointer on a lightly underdamped spring, and the light position trails on a softer one, so the sheen lags the lean just enough to feel physical.
- The foil slides and shifts hue with the angle; glitter drifts against the tilt and only sparkles near the glare.
- Each flip adds half a turn toward the side that was pressed on a spring with a little bounce, and the foil sweeps across the card mid spin.
- A floating shadow moves opposite the lean.
- Reduced motion removes tilt, spin, and glitter; the faces cross fade.

### Responsive behavior

- The root is width limited to 300px by default and keeps a 5:7 ratio, so it fits a 320px screen.
- On touch screens tilt comes from the device when available; otherwise dragging a finger over the card tilts it.
- Hover lift and tilt only react to real pointer movement; taps flip.

### Performance

- All tilt and light values are motion values written to transform and CSS variables, with no React render per frame.
- Foil, glitter, and glare are three blended layers per face; keep one or two cards on screen, not a grid.
- Glitter is a small tiled SVG data URI.

### Notes for AI

- Choose it for one hero object: a membership card, a conference badge, an achievement, or a gift card reveal.
- Design the front edge to edge; the card clips it to its radius and adds the foil on top.
- Dark or saturated card stock shows the foil best; on very light stock lower intensity.
- Leave out back for a tilt only card, for example inside a link.
- Gyroscope needs HTTPS and, on iOS, a tap to grant permission; the first tap that flips also asks.

### Related

- [Sticker peel](https://uiarc.dev/components/sticker-peel/markdown): Peel stickers off a surface with a real curl, move them around, and stick them back down.
- [Wallet stack](https://uiarc.dev/components/wallet-stack/markdown): Fan a stack of cards and lift one out to see its activity.
- [Cover flow](https://uiarc.dev/components/cover-flow/markdown): A depth rail of images you can throw, with soft grounded shadows and a quiet reflection.

### Also in surfaces

- [Sheet stack](https://uiarc.dev/components/sheet-stack/markdown): Nested sheets that stack with depth, drag to dismiss, and become stacked dialogs on wide screens.
- [Control center](https://uiarc.dev/components/control-center/markdown): Workspace quick settings: tiles that morph into detail, a duration dial, and rubber-banded meters.
- [Card to article](https://uiarc.dev/components/card-to-article/markdown): Story cards that open into full articles with one seamless morph and shrink back into their exact slot when dragged down.
- [Link unfurl](https://uiarc.dev/components/link-unfurl/markdown): A composer where pasting a URL shows a loading shimmer on the link, then unfurls it into a rich preview card with title, image and favicon in one morph, which can be collapsed back to the inline link or removed.

### Guidance for AI tools

Holo card: A member card that tilts toward you with a holographic foil and flips to its back. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Card to article

> Story cards that open into full articles with one seamless morph and shrink back into their exact slot when dragged down.

- Type: Component (special)
- Access: Arc Pro
- Page: https://uiarc.dev/components/card-to-article
- Markdown: https://uiarc.dev/components/card-to-article/markdown
- Source file: `registry/components/card-to-article/card-to-article.tsx`
- Dependencies: motion, lucide-react
- Keywords: special, layout, gesture, new, app store card, card expand, shared element transition, card to detail, magic motion, expanding card, blog grid, article modal

### When to use

- Blogs, journals, and changelogs where each entry has a strong image.
- Case study and portfolio grids.
- Editorial landing sections that preview stories without leaving the page.

### When not to use

- Use a normal link to a page when articles are long or need their own URL and SEO.
- Use expandable-card for small inline details.
- Text only lists with no imagery.

### Installation

Card to article is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/card-to-article
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { CardToArticle } from "@/components/arc/card-to-article/card-to-article";

const posts = [
  {
    id: "glass-house",
    tag: "Case study",
    title: "A glass house that stays cool in August",
    meta: "5 min read",
    image: "/media/photos/pool-house.jpg",
    imageAlt: "A modern glass house beside a long pool",
    body: <p>The brief was simple and a little unreasonable...</p>,
  },
];

export function Journal() {
  return <CardToArticle items={posts} />;
}
```

### API reference

#### CardToArticle

A grid of story cards; a card opens into a full scrolling article with a shared element morph and closes back into its slot.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `items` (required) | `ArticleItem[]` | – | Each item has id, title, image, imageAlt, body, and optional tag and meta. |
| `value` | `string \| null` | – | Id of the open article. Leave it out for uncontrolled use. |
| `defaultValue` | `string \| null` | `null` | Initially open article when uncontrolled. |
| `onValueChange` | `(id: string \| null) => void` | – | Called when an article opens or closes. |
| `aspectRatio` | `number` | `4 / 3` | Ratio of the card and the article hero. They match, so the morph is a pure scale with no distortion. |
| `closeLabel` | `string` | `"Close article"` | Accessible name of the close button. |
| `className` | `string` | – | Extra class on the root. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Enter / Space | Opens the focused card. |
| Escape | Closes the article and returns focus to its card. |
| Tab | Stays inside the open article. |

### Accessibility

- Cards are buttons with aria-haspopup="dialog" and aria-expanded.
- The open article is a modal dialog labelled by its title, with focus moved to the close button and trapped inside.
- Closing returns focus to the card it came from.
- Page scroll is locked while the article is open, keeping the scrollbar's space so nothing shifts.

### Motion

- The card itself becomes the article: its box and corners spring to the sheet while the hero scales as one piece, so image and title never distort.
- The body rises in after the morph; the close button pops in last.
- Drag down on touch, drag the hero with a mouse, or pull past the top with a trackpad: the sheet shrinks and drops with the gesture and closes past a threshold or on a flick.
- Closing re-measures the card's slot and lands flush in it, no bounce. A reading progress bar tracks the scroll.
- Reduced motion opens and closes without travel.

### Responsive behavior

- Two columns, then one below 520px of container width.
- The article fills the screen with a 12px margin on phones and caps at 680px wide on desktop.
- Title and tag sizes follow the hero's own width through container units.

### Performance

- The morph is one layout animation plus a scale corrected hero; nothing else re-lays out.
- The pull gesture is transform only and runs from motion values.

### Notes for AI

- Keep every image the same ratio as aspectRatio so the hero scales cleanly.
- Titles are drawn on the photo in white over a legibility scrim; pick photos with calm lower areas.
- Use onValueChange to sync the open article with the URL for deep links.

### Related

- [Expandable card](https://uiarc.dev/components/expandable-card/markdown): Give a dense card more room when requested.
- [Lightbox gallery](https://uiarc.dev/components/lightbox-gallery/markdown): A masonry grid where photos zoom from their slot into a viewer you can swipe, pinch, and drag away.
- [Photo grid](https://uiarc.dev/components/photo-grid/markdown): Pinch through zoom levels and open any photo straight from its cell.
- [Dialog](https://uiarc.dev/components/dialog/markdown): A focused surface for decisions that need attention.

### Also in surfaces

- [Sheet stack](https://uiarc.dev/components/sheet-stack/markdown): Nested sheets that stack with depth, drag to dismiss, and become stacked dialogs on wide screens.
- [Wallet stack](https://uiarc.dev/components/wallet-stack/markdown): Fan a stack of cards and lift one out to see its activity.
- [Control center](https://uiarc.dev/components/control-center/markdown): Workspace quick settings: tiles that morph into detail, a duration dial, and rubber-banded meters.
- [Holo card](https://uiarc.dev/components/holo-card/markdown): A member card that tilts toward you with a holographic foil and flips to its back.
- [Link unfurl](https://uiarc.dev/components/link-unfurl/markdown): A composer where pasting a URL shows a loading shimmer on the link, then unfurls it into a rich preview card with title, image and favicon in one morph, which can be collapsed back to the inline link or removed.

### Guidance for AI tools

Card to article: Story cards that open into full articles with one seamless morph and shrink back into their exact slot when dragged down. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Link unfurl

> A composer where pasting a URL shows a loading shimmer on the link, then unfurls it into a rich preview card with title, image and favicon in one morph, which can be collapsed back to the inline link or removed.

- Type: Component (special)
- Access: Arc Pro
- Page: https://uiarc.dev/components/link-unfurl
- Markdown: https://uiarc.dev/components/link-unfurl/markdown
- Source file: `registry/components/link-unfurl/link-unfurl.tsx`
- Dependencies: motion, lucide-react
- Keywords: special, composer, link-preview, morph, motion, new, link preview, unfurl, open graph, og image, rich link, embed, url preview, chat input, slack, paste link

### When to use

- A message or comment composer where pasted links should show what they point to before sending.
- Product marketing that shows how a chat or notes app handles links.

### When not to use

- Use hover-card to preview a link someone reads, not writes.
- Use mention-input when the tokens are people or records rather than web links, and rich-text-editor for long formatted documents.

### Installation

Link unfurl is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/link-unfurl
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { LinkUnfurl, type LinkUnfurlPreview } from "@/components/arc/link-unfurl/link-unfurl";

export function ChannelComposer({ channel, post }: { channel: string; post: (text: string) => Promise<void> }) {
  return <LinkUnfurl
    label={`Message #${channel}`}
    placeholder={`Message #${channel}`}
    defaultValue=""
    samples={[]}
    autoPlay={false}
    resolve={async (url, signal) => {
      const res = await fetch(`/api/unfurl?url=${encodeURIComponent(url)}`, { signal });
      return res.ok ? (await res.json()) as LinkUnfurlPreview : null;
    }}
    onSend={message => post(message.text)}
  />;
}
```

### API reference

#### LinkUnfurl

A message composer that unfurls links. Paste an address and it becomes an inline link with a soft loading sweep; once the preview resolves, the favicon and title roll in and the link unrolls into a rich card with site, title, description, and image in one continuous morph. The card's corner grows out of the link itself, width first and height after, lifting on a shadow while it travels. Click the link, press the collapse button, or drag the card up to fold it back into the text; remove it to take the link out of the message.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` | `string` | `"Message #lisbon-offsite"` | Accessible name of the message field. |
| `placeholder` | `string` | `"Message #lisbon-offsite"` | Shown while the message is empty. |
| `defaultValue` | `string` | `"Found a place for the offsite, take a look"` | Starting text of the message. |
| `samples` | `LinkUnfurlPreview[]` | – | Sample links offered as buttons under the field; the built in resolver answers with their previews. Once a sample is in the message its button shows or collapses its card. Pass an empty array to hide them. |
| `resolve` | `(url: string, signal: AbortSignal) => Promise<LinkUnfurlPreview \| null>` | – | Fetches the preview for a pasted address, usually from your own unfurl endpoint. Return null when there is none; the link then stays in the text without a card and can be clicked to try again. Without it, samples resolve by address and other links get a plain preview built from the address after a 1.15s simulated fetch. |
| `autoExpand` | `boolean` | `true` | Unfurls a card as soon as its preview resolves. When false the link only gains its favicon and title, and opens on click. |
| `autoPlay` | `boolean` | `true` | Pastes the first sample the first time the composer scrolls into view, unless someone has already interacted. |
| `speed` | `number` | `1` | Multiplier for the morph and the simulated fetch. |
| `paused` | `boolean` | `false` | Opens and folds cards instantly without the morph and turns autoplay off. |
| `accent` | `string` | – | Color of an unfurled link and its tie to its card. Defaults to the accent. |
| `sendLabel` | `string` | `"Send message"` | Accessible name of the send button. |
| `onSend` | `(message: LinkUnfurlMessage) => void \| Promise<unknown>` | – | Called on Enter or the send button with the text (links written out as addresses) and the resolved previews. Return a promise to hold the composer while it is pending; a rejection shows its message under the composer. On success the composer clears and the button confirms with a check. |
| `className` | `string` | – | Extra class on the root element. |
| `style` | `CSSProperties` | – | Inline styles on the root element. |

### Accessibility

- The message is a contenteditable element with role="textbox", aria-multiline, a label, and a description of its keys. Pasting inserts plain text, and a pasted or typed address (followed by a space) becomes an atomic link that deletes as one unit.
- Keyboard: Enter sends, Shift+Enter adds a line, and Alt+Enter shows or collapses the preview of the link before the caret. Every card has a named collapse button and a named remove button, and its title is a real link.
- A folded card is inert and hidden from assistive technology, so only open previews are in the tab order.
- A polite live region announces a link being added and loading, the preview opening with its site and title, collapsing, removal, a failed preview, and the sent message. Send errors use role="alert".
- Loading is shown by the sweep and by muted text and a globe instead of a favicon, and announced, never by color alone.
- Pointer focus draws no ring; keyboard focus shows Arc's shared focus ring. Focused controls take a muted fill.

### Motion

- One rAF loop drives every card from a critically damped spring, writing only transforms, clip paths, opacity, and the plate size; React renders once per state change, never per frame.
- The card is clipped to the exact rectangle of its inline link, with the favicons aligned, and translated onto it. As the spring runs the clip widens first and deepens after, while the translation eases home, so the link reads as unrolling into the card. A plate under the card carries its border and a shadow that lifts only mid flight.
- The lane grows with the card's height on the same progress, so the toolbar below glides instead of jumping. The body fades in after the header, and the image settles from a slight zoom.
- When a preview resolves, the link's width morphs to fit the title while the title rolls up and the favicon pops in.
- Collapsing runs the same path backwards on a quicker spring. Dragging a card up folds it with the pointer; releasing past about 40% or with an upward flick folds it, otherwise it springs back.
- The loop sleeps once cards settle, and cards land instantly when the composer is offscreen or the tab is hidden; the loading sweep pauses with them. Reduced motion and paused open and fold cards instantly and show a still tint instead of the sweep.

### Responsive behavior

- The composer sizes itself from its own width with container queries: padding steps up from 560px, and the Try label hides below 360px so the sample buttons and send button stay on one row.
- Cards are at most 440px wide and fill narrower composers; images keep the 1.91 : 1 Open Graph ratio. Links truncate at 16em with the full title in the card and the accessible name.
- On touch only the card header drags, so the page still scrolls over the card body and image.

### Performance

- Each frame reads all geometry first and then writes, so the loop costs one layout pass. Nothing is created or removed while animating.
- Preview images are decoded before the card opens, so the morph never reveals an empty frame.

### Notes for AI

- Use it in chat, comments, and notes where links are shared and a preview helps people decide whether to open them.
- Unfurl on your server (Open Graph and oEmbed) and return site, title, description, image, and favicon through resolve. Honor the abort signal; it fires when the link is removed or the message is sent.
- The favicon slot in the link and the card are aligned on purpose; keep favicons square.
- Brand marks in the samples are sample content, not endorsements.

### Related

- [Mention input](https://uiarc.dev/components/mention-input/markdown): A textarea with @people and #channel mentions that act as single tokens, with suggestions at the caret.
- [Rich text editor](https://uiarc.dev/components/rich-text-editor/markdown): A lightweight editor with markdown shortcuts, a floating toolbar, a slash menu, and HTML and markdown output.
- [Hover card](https://uiarc.dev/components/hover-card/markdown): Preview a person or link on hover or focus without leaving the page.
- [Chat thread](https://uiarc.dev/components/chat-thread/markdown): A chat thread with grouped messages, reactions, read receipts, typing, and a composer with attachments.

### Also in surfaces

- [Sheet stack](https://uiarc.dev/components/sheet-stack/markdown): Nested sheets that stack with depth, drag to dismiss, and become stacked dialogs on wide screens.
- [Wallet stack](https://uiarc.dev/components/wallet-stack/markdown): Fan a stack of cards and lift one out to see its activity.
- [Control center](https://uiarc.dev/components/control-center/markdown): Workspace quick settings: tiles that morph into detail, a duration dial, and rubber-banded meters.
- [Holo card](https://uiarc.dev/components/holo-card/markdown): A member card that tilts toward you with a holographic foil and flips to its back.
- [Card to article](https://uiarc.dev/components/card-to-article/markdown): Story cards that open into full articles with one seamless morph and shrink back into their exact slot when dragged down.

### Guidance for AI tools

Link unfurl: A composer where pasting a URL shows a loading shimmer on the link, then unfurls it into a rich preview card with title, image and favicon in one morph, which can be collapsed back to the inline link or removed. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Product gallery

> A product gallery with a hover magnifier, gliding thumbnails, and color and size variants that crossfade photos.

- Type: Component (special)
- Access: Arc Pro
- Page: https://uiarc.dev/components/product-gallery
- Markdown: https://uiarc.dev/components/product-gallery/markdown
- Source file: `registry/components/product-gallery/product-gallery.tsx`
- Dependencies: motion, lucide-react
- Keywords: special, new, react product gallery, product image zoom, ecommerce gallery, image magnifier, variant picker, color and size selector, product detail page, fullscreen image viewer

### When to use

- Product detail pages with several photos per color and a size picker.
- Stores where shoppers need to zoom into fabric, texture, or small print.
- Variants that sell out per color and should be struck through, not hidden.

### When not to use

- Use lightbox-gallery for a photo grid that opens into a viewer, with no variants.
- Use carousel for marketing slides or cards.
- Use photo-grid for a masonry of images without a main photo.

### Installation

Product gallery is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/product-gallery
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { useState } from "react";
import { ProductGallery } from "@/components/arc/product-gallery/product-gallery";
import Button from "@/components/arc/button/button";

export function ProductPage() {
  const [size, setSize] = useState<string | null>(null);
  return (
    <ProductGallery
      label="Field jacket"
      colors={[
        { value: "olive", label: "Olive", swatch: "#6b6a4a", images: [{ src: "/jacket/olive-1.jpg", alt: "Olive jacket, front" }, { src: "/jacket/olive-2.jpg", alt: "Olive jacket, back" }] },
        { value: "navy", label: "Navy", swatch: "#27304a", images: [{ src: "/jacket/navy-1.jpg", alt: "Navy jacket, front" }] },
      ]}
      sizes={[
        { value: "s", label: "S" },
        { value: "m", label: "M", soldOut: ["navy"] },
        { value: "l", label: "L" },
      ]}
      size={size}
      onSizeChange={setSize}
      header={<><h1>Field jacket</h1><p>$240</p></>}
      footer={<Button disabled={!size}>Add to bag</Button>}
    />
  );
}
```

### API reference

#### ProductGallery

A product media gallery with a hover magnifier, a thumbnail rail, swipe on touch, a fullscreen zoom viewer, and a color and size picker.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `colors` (required) | `ProductGalleryColor[]` | – | Colors: { value, label, swatch, images, soldOut? }. Each carries its own images: { src, alt, srcSet? }. |
| `sizes` | `ProductGallerySize[]` | – | Sizes: { value, label, soldOut? }. soldOut is true for every color or a list of color values. |
| `color` | `string` | – | Controlled color value. |
| `defaultColor` | `string` | – | Starting color when uncontrolled. Defaults to the first color. |
| `onColorChange` | `(color: string) => void` | – | Called when a swatch is chosen. |
| `size` | `string \| null` | – | Controlled size value, or null for none. |
| `defaultSize` | `string \| null` | `null` | Starting size when uncontrolled. |
| `onSizeChange` | `(size: string \| null) => void` | – | Called when a size is chosen or cleared, including when a color change sells it out. |
| `index` | `number` | – | Controlled index of the photo on show. |
| `defaultIndex` | `number` | `0` | Starting photo when uncontrolled. |
| `onIndexChange` | `(index: number) => void` | – | Called when the photo changes. |
| `zoom` | `number` | `2.4` | Magnification of the hover lens and the fullscreen zoom. |
| `magnifier` | `boolean` | `true` | Turns the hover lens on or off. |
| `aspectRatio` | `number` | `4 / 5` | Aspect ratio of the main photo and thumbnails, as width / height. |
| `label` | `string` | `"Product photos"` | Product name, used to name the gallery and its viewer. |
| `header` | `ReactNode` | – | Content above the picker, such as the name and price. |
| `footer` | `ReactNode` | – | Content under the picker, such as add to bag. |
| `className` | `string` | – | Class on the root. |
| `ref` | `Ref<HTMLDivElement>` | – | The root element. |

#### isSoldOut

Whether a size is sold out in a given color.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size` (required) | `ProductGallerySize` | – | The size entry. |
| `color` (required) | `string` | – | The color value. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| ArrowLeft / ArrowRight | Steps photos on the main photo, the thumbnail rail, and in the viewer. |
| Arrow keys / Home / End | Move and select within the thumbnail rail, swatches, and sizes; sold-out sizes are skipped. |
| Enter / Space | Opens the fullscreen viewer from the main photo. |
| Escape | Zooms out in the viewer, then closes it and returns focus to the photo. |
| Tab | Cycles within the viewer's buttons while it is open. |

### Accessibility

- The main photo is a button labelled with the photo's alt text, its position, and Open fullscreen.
- Thumbnails are a tablist; swatches and sizes are radiogroups with roving tabindex, and sold-out sizes use aria-disabled.
- The viewer is a modal dialog that focuses Close on open, traps Tab, locks body scroll, and announces the photo count politely.
- Every image needs a meaningful alt; thumbnails and the lens are decorative copies.

### Motion

- The photo track springs to the photo on show and follows a finger one to one, with rubber-band edges; one flick moves one photo.
- The lens rides a spring behind the pointer; rail, swatch, and size highlights glide to the active option.
- The viewer grows out of the photo's own rectangle with counter-scaled corners and returns to it on close; zoom scales on a spring and pans after the pointer.
- Changing color crossfades every photo from a blur. Reduced motion jumps the track, lens, and zoom, and replaces the viewer flight with a fade.

### Responsive behavior

- The root is a container: photos and details sit side by side above 680px, stack at 680px and below, and the rail moves under the photo at 520px and below.
- On touch screens (hover: none) the photo shows dots and a permanent expand icon; the lens is mouse only.
- The viewer frame sizes to fit the viewport at the photo's ratio, with 12px padding under 640px and 48px above; it refits on resize.

### Performance

- Only the photo on show loads eagerly; the rest and every thumbnail are lazy with async decoding.
- Each highlight (rail, swatches, sizes) and the stage run one ResizeObserver; the lens reuses the current image at zoom size.
- The viewer is portaled to the body only while open.

### Notes for AI

- Use on a product detail page. Put the name, price, and reviews in header and purchase buttons in footer.
- Give each color its own photos; if a size is sold out in the new color, the selection clears through onSizeChange.
- Photos are plain img tags; pass optimized src and srcSet URLs. Set magnifier={false} for photos without fine detail.
- For a general photo grid with a lightbox use lightbox-gallery; for a simple slide rotation use carousel.

### Related

- [Lightbox gallery](https://uiarc.dev/components/lightbox-gallery/markdown): A masonry grid where photos zoom from their slot into a viewer you can swipe, pinch, and drag away.
- [Carousel](https://uiarc.dev/components/carousel/markdown): Browse a row of slides by dragging, flicking, or arrowing through them.
- [Photo grid](https://uiarc.dev/components/photo-grid/markdown): Pinch through zoom levels and open any photo straight from its cell.
- [Segmented control](https://uiarc.dev/components/segmented-control/markdown): Switch between a small set of related views.
- [Radio group](https://uiarc.dev/components/radio-group/markdown): Choose one option from a visible set.

### Also in galleries

- [Cover flow](https://uiarc.dev/components/cover-flow/markdown): A depth rail of images you can throw, with soft grounded shadows and a quiet reflection.

### Guidance for AI tools

Product gallery: A product gallery with a hover magnifier, gliding thumbnails, and color and size variants that crossfade photos. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Lightbox gallery

> A masonry grid where photos zoom from their slot into a viewer you can swipe, pinch, and drag away.

- Type: Component (special)
- Access: Arc Pro
- Page: https://uiarc.dev/components/lightbox-gallery
- Markdown: https://uiarc.dev/components/lightbox-gallery/markdown
- Source file: `registry/components/lightbox-gallery/lightbox-gallery.tsx`
- Dependencies: motion, lucide-react
- Keywords: special, gallery, lightbox, images, react lightbox, image gallery, masonry gallery, photo lightbox, fullscreen image viewer, zoomable gallery, next image gallery

### When to use

- Photo collections people browse and inspect up close, such as trips, portfolios, or listings.
- Mixed portrait and landscape sets that should keep their aspect ratios in a masonry grid.

### When not to use

- Use photo-grid for a square grid with pinch zoom between densities.
- Use carousel for a single inline row without a viewer.
- Use dialog to show one arbitrary piece of content.

### Installation

Lightbox gallery is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/lightbox-gallery
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { LightboxGallery } from "@/components/arc/lightbox-gallery/lightbox-gallery";

const photos = [
  { src: "/trip/harbor.jpg", width: 1600, height: 1067, alt: "Boats in a harbor at dawn", title: "Harbor", caption: "May 2026" },
  { src: "/trip/alley.jpg", width: 1067, height: 1600, alt: "Narrow alley with lanterns", title: "Old town" },
  { src: "/trip/cliffs.jpg", width: 1600, height: 1200, alt: "Cliffs over the sea" },
];

export function TripPhotos() {
  return <LightboxGallery images={photos} label="Trip photos" minColumnWidth={180} />;
}
```

### API reference

#### LightboxGallery

A masonry grid of photos that open in a fullscreen viewer. The tapped photo zooms out of its grid slot and flies back to the slot of whichever photo is showing when the viewer closes.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `images` (required) | `{ src: string; width: number; height: number; alt: string; title?: string; caption?: string }[]` | – | Photos in reading order. width and height are the intrinsic size, which sets the aspect ratio in the grid, zoom, and return flight. title and caption are the two caption lines. |
| `minColumnWidth` | `number` | `150` | Columns are added while each stays at least this wide, in px. There are always at least two. |
| `gap` | `number` | `8` | Gap between photos in px. |
| `label` | `string` | `"Photo gallery"` | Accessible name of the gallery and its viewer. |
| `className` | `string` | – | Class on the root region. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Enter / Space | Open the focused photo in the viewer. |
| Arrow Left / Arrow Right | Previous or next photo in the viewer. |
| + / - / 0 | Zoom in, zoom out, or reset zoom. |
| Escape | Close the viewer; focus returns to the matching grid photo. |
| Tab | Cycles within the viewer's controls while it is open. |

### Accessibility

- The grid is a labelled region of buttons named like "Open Harbor, photo 1 of 3"; the viewer is a portalled role="dialog" with aria-modal and a focus trap, and focus starts on Close.
- Only the current slide is exposed to assistive tech, and a polite live counter reads "2 of 12" as photos change.
- Zoom is an aria-pressed toggle, previous and next are disabled at the ends, and the thumbnail strip marks the current photo with aria-current.

### Motion

- Opening flies the photo from its grid slot to fit the stage on a spring with a constant corner radius; closing flies it back to the current photo's slot while the backdrop fades.
- Drag down to dismiss with resistance, swipe between photos with momentum, and pinch, Ctrl+scroll, or double click to zoom around the pointer.
- Reduced motion skips the flight and swiping springs, fades the viewer in and out, and jumps zoom and slides into place.

### Responsive behavior

- Columns are computed from the gallery's own width and minColumnWidth, with at least two.
- Below 640px viewport width the side arrows hide and swipe navigates; pinch, drag to dismiss, and double tap zoom work on touch.

### Performance

- Grid images pass responsive sizes hints and viewer slides load lazily except the current one. Images are plain img elements unless ArcProvider sets an image component such as next/image.
- The grid is not virtualized, so paginate very large collections.
- With next/image set through ArcProvider, remote image hosts must be allowed in next.config.

### Notes for AI

- Use for a photo collection people browse and inspect up close, such as trips, portfolios, or listings. Use photo-grid for a grid without a fullscreen viewer, carousel for a single inline row with no zoom, and dialog to show one arbitrary piece of content.
- Always pass real width, height, and alt for every image so the masonry and flights keep aspect ratios; images render as plain img elements unless you pass next/image (or your own image component) through ArcProvider from @/components/arc/lib/arc-provider.

### Related

- [Photo grid](https://uiarc.dev/components/photo-grid/markdown): Pinch through zoom levels and open any photo straight from its cell.
- [Carousel](https://uiarc.dev/components/carousel/markdown): Browse a row of slides by dragging, flicking, or arrowing through them.
- [Dialog](https://uiarc.dev/components/dialog/markdown): A focused surface for decisions that need attention.
- [Cover flow](https://uiarc.dev/components/cover-flow/markdown): A depth rail of images you can throw, with soft grounded shadows and a quiet reflection.

### Also in galleries

- [Product gallery](https://uiarc.dev/components/product-gallery/markdown): A product gallery with a hover magnifier, gliding thumbnails, and color and size variants that crossfade photos.

### Guidance for AI tools

Lightbox gallery: A masonry grid where photos zoom from their slot into a viewer you can swipe, pinch, and drag away. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Photo grid

> Pinch through zoom levels and open any photo straight from its cell.

- Type: Component (special)
- Access: Arc Pro
- Page: https://uiarc.dev/components/photo-grid
- Markdown: https://uiarc.dev/components/photo-grid/markdown
- Source file: `registry/components/photo-grid/photo-grid.tsx`
- Dependencies: motion, lucide-react
- Keywords: special, photos, gallery, react photo grid, photo library, pinch to zoom grid, ios photos grid, image gallery with viewer, album grid, photo viewer

### When to use

- A browsable photo library or album where people zoom between column counts.
- Galleries that need favorites and a full-screen viewer with a filmstrip.
- Touch and trackpad users who expect pinch to change density.

### When not to use

- Use lightbox-gallery for a masonry layout that keeps each photo's aspect ratio.
- Use carousel for a short inline slideshow.
- Use image-compare for before and after pairs.

### Installation

Photo grid is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/photo-grid
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { PhotoGrid, type GridPhoto } from "@/components/arc/photo-grid/photo-grid";

export function Album({ photos }: { photos: GridPhoto[] }) {
  return (
    <PhotoGrid
      title="September"
      photos={photos}
      defaultColumns={4}
      onFavoriteChange={(id, favorite) => saveFavorite(id, favorite)}
    />
  );
}
```

### API reference

#### PhotoGrid

A photo library grid with pinch or button zoom between column counts, favorites, and a full-screen viewer that grows from the tapped cell.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `photos` (required) | `{ id: string; src: string; srcSet?: string; alt: string; width: number; height: number; title: string; detail?: string }[]` | – | Photos in order. width and height are the intrinsic size; detail is a short line in the viewer, such as the date. |
| `title` (required) | `string` | – | Names the library, such as a month or album. |
| `zoomLevels` | `number[]` | `[5, 3, 2]` | Column counts the zoom steps between. |
| `defaultColumns` | `number` | `3` | Initial column count. |
| `onColumnsChange` | `(columns: number) => void` | – | Called when the zoom level changes. |
| `defaultFavorites` | `string[]` | – | Ids favorited at mount. |
| `onFavoriteChange` | `(id: string, favorite: boolean) => void` | – | Called when a photo is favorited or unfavorited. |
| `onViewerChange` | `(id: string \| null) => void` | – | Called with the photo id when the viewer opens and null as it starts to close. |
| `className` | `string` | – | Extra class on the root. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Arrow keys | Move focus between photos in the grid. |
| PageUp / PageDown / Home / End | Jump by three rows or to the first or last photo. |
| + / - | Zoom in or out a level around the focused photo. |
| Enter / Space | Opens the focused photo in the viewer. |
| ArrowLeft / ArrowRight / Home / End | In the viewer, change photo. |
| Escape | Closes the viewer. |

### Accessibility

- The grid is a labelled list of buttons named by each photo's alt text, with ", favorite" appended when favorited.
- Zoom buttons use aria-pressed; the viewer is a labelled dialog and its filmstrip is a slider with the photo title in aria-valuetext.
- Viewer changes are announced in a polite status region.

### Motion

- Pinch zoom scales live and reflows around the photo under the fingers; the viewer grows from the tapped cell and can be dragged down to dismiss.
- Counters and favorite icons roll or pop in with a short blur.
- Reduced motion removes layout travel and keeps fades.

### Responsive behavior

- Columns come from zoomLevels, not breakpoints; the root is a container and needs a height, with a 320px minimum.
- Below 480px the header and filmstrip shrink, previous and next buttons hide, and swipe or the filmstrip pages instead.
- Previous and next arrows are hidden on hover-less devices, where swipe is the main gesture.

### Performance

- The grid is not virtualized; every photo renders a thumbnail, so paginate very large libraries.
- The viewer only mounts photos near the current one, and passing srcSet keeps thumbnails light.
- The header and viewer use backdrop blur, which drops to solid surfaces under prefers-reduced-transparency.

### Notes for AI

- Choose it for a browsable photo library or album. Use carousel for a short slideshow and image-compare for before/after.
- Always pass width and height so the viewer and filmstrip can fit each photo without layout shift; pass srcSet for sharp thumbnails.

### Related

- [Carousel](https://uiarc.dev/components/carousel/markdown): Browse a row of slides by dragging, flicking, or arrowing through them.
- [Image compare](https://uiarc.dev/components/image-compare/markdown): Drag a divider across two images to see what changed.
- [Cover flow](https://uiarc.dev/components/cover-flow/markdown): A depth rail of images you can throw, with soft grounded shadows and a quiet reflection.
- [Dialog](https://uiarc.dev/components/dialog/markdown): A focused surface for decisions that need attention.

### Also in galleries

- [Product gallery](https://uiarc.dev/components/product-gallery/markdown): A product gallery with a hover magnifier, gliding thumbnails, and color and size variants that crossfade photos.
- [Lightbox gallery](https://uiarc.dev/components/lightbox-gallery/markdown): A masonry grid where photos zoom from their slot into a viewer you can swipe, pinch, and drag away.

### Guidance for AI tools

Photo grid: Pinch through zoom levels and open any photo straight from its cell. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Cover flow

> A depth rail of images you can throw, with soft grounded shadows and a quiet reflection.

- Type: Component (special)
- Access: Arc Pro
- Page: https://uiarc.dev/components/cover-flow
- Markdown: https://uiarc.dev/components/cover-flow/markdown
- Source file: `registry/components/cover-flow/cover-flow.tsx`
- Dependencies: motion
- Keywords: special, cover flow, carousel, react cover flow, coverflow carousel, 3d carousel, album carousel, image rail, itunes cover flow

### When to use

- Six to twelve visual items where looking at one at a time is the point, such as albums, places, or collections.
- Showcase rails that should respond to drag, throw, and sideways trackpad scroll.

### When not to use

- Use carousel for general slides or content cards.
- Use photo-grid or lightbox-gallery for a large library.
- Use depth-cards for about three rich choices that open into detail.

### Installation

Cover flow is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/cover-flow
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { CoverFlow } from "@/components/arc/cover-flow/cover-flow";

export function Hikes() {
  return (
    <CoverFlow
      label="Hikes for this fall"
      items={[
        { id: "ridge", title: "Ridge Loop", subtitle: "Mount Tam", meta: "8 km", image: "/hikes/ridge.jpg" },
        { id: "falls", title: "Cataract Falls", subtitle: "Marin", meta: "5 km", image: "/hikes/falls.jpg" },
      ]}
      onIndexChange={setIndex}
    />
  );
}
```

### API reference

#### CoverFlow

A depth rail for browsing a short collection of images one at a time. The front card stands forward while the rest recede to either side, and each image drifts inside its frame as the rail moves.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `items` (required) | `{ id: string; title: string; subtitle?: string; meta?: string; image: string; imagePosition?: string; alt?: string }[]` | – | Cards in order. alt defaults to the title. Generic: extra fields on your items are passed back to renderCaption. |
| `label` (required) | `string` | – | Accessible name of the carousel, such as "Hikes for this fall". |
| `index` | `number` | – | Controlled front card. Pair with onIndexChange. |
| `defaultIndex` | `number` | `0` | Initial front card when uncontrolled. |
| `onIndexChange` | `(index: number) => void` | – | Called when a different card settles in front, and while a drag passes over one. |
| `renderCaption` | `(item: T, index: number) => ReactNode` | – | Replaces the caption under the rail. It changes with the front card. |
| `className` | `string` | – | Extra class on the root. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| ArrowLeft / ArrowRight | Steps one card while the rail has focus. |
| Home / End | Jumps to the first or last card. |

### Accessibility

- The root is labelled with aria-roledescription="carousel"; each card is a group with aria-roledescription="slide" and a label like "2 of 8: Ridge Loop".
- Cards away from the front are aria-hidden, and position ticks are labelled "Show <title>" with aria-current on the front one. Ticks are out of the tab order; the rail itself takes focus and handles the keys.
- The front card is announced in a polite live region.

### Motion

- Drag or throw the rail and it lands on the card its momentum reaches, on a spring tuned to the release speed; a quick flick always moves at least one card. The ends rubber-band.
- Sideways trackpad scrolls move the rail directly, then settle on a card with the swipe's momentum. Clicking a card beside the front one brings it forward.
- Cards scale, dim, turn toward the center, and recede with distance while each image drifts inside its frame; the caption rises in from the direction of travel.
- Reduced motion jumps between cards, turns off the drift and the turn, and keeps short fades. A drag past 40px or one trackpad swipe steps one card.

### Responsive behavior

- Cards size with the container at clamp(168px, 38cqw, 272px), so the rail scales from phones to wide sections.
- The stage uses touch-action pan-y, so vertical swipes still scroll the page and sideways ones move the rail.

### Performance

- Every card is rendered, but cards far from the front get visibility hidden; keep the collection to a few dozen at most.
- Transforms and image drift run on motion values, and one ResizeObserver reads the card width.

### Notes for AI

- Choose it for six to twelve visual items where one at a time is the point (places, albums, collections). Use carousel for general slides and photo-grid for a large library.
- Items are generic, so pass your own records and render extra fields through renderCaption.

### Related

- [Carousel](https://uiarc.dev/components/carousel/markdown): Browse a row of slides by dragging, flicking, or arrowing through them.
- [Card stack](https://uiarc.dev/components/card-stack/markdown): Review a deck one card at a time, with a throw and an undo.
- [Photo grid](https://uiarc.dev/components/photo-grid/markdown): Pinch through zoom levels and open any photo straight from its cell.

### Also in galleries

- [Product gallery](https://uiarc.dev/components/product-gallery/markdown): A product gallery with a hover magnifier, gliding thumbnails, and color and size variants that crossfade photos.
- [Lightbox gallery](https://uiarc.dev/components/lightbox-gallery/markdown): A masonry grid where photos zoom from their slot into a viewer you can swipe, pinch, and drag away.

### Guidance for AI tools

Cover flow: A depth rail of images you can throw, with soft grounded shadows and a quiet reflection. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Voice orb

> A voice mode orb that listens, thinks, and speaks, with a live transcript and call controls.

- Type: Component (special)
- Access: Arc Pro
- Page: https://uiarc.dev/components/voice-orb
- Markdown: https://uiarc.dev/components/voice-orb/markdown
- Source file: `registry/components/voice-orb/voice-orb.tsx`
- Dependencies: motion, lucide-react
- Keywords: special, new, react voice orb, voice assistant ui, ai voice mode, audio visualizer orb, microphone level, speaking animation, voice chat controls, live transcript

### When to use

- A voice mode for an assistant where the user needs to see whether it is listening, thinking, or speaking.
- Hands-free or call-like flows that need start, mute, a running clock, and end in one compact control.
- Live captions under a speaking agent, via VoiceTranscript.

### When not to use

- Use voice-recorder when the user records a clip to send or save.
- Use chat-thread with text-stream for typed chat where no audio is involved.
- Use progress or skeleton for a generic loading state; the orb implies a voice session.

### Installation

Voice orb is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/voice-orb
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { useEffect, useState } from "react";
import { VoiceControls, VoiceOrb, VoiceTranscript, useMicLevel } from "@/components/arc/voice-orb/voice-orb";
import type { VoiceOrbState } from "@/components/arc/voice-orb/voice-orb";

export function VoiceMode() {
  const [active, setActive] = useState(false);
  const [muted, setMuted] = useState(false);
  const [state, setState] = useState<VoiceOrbState>("idle");
  const [elapsed, setElapsed] = useState(0);
  const mic = useMicLevel(active && !muted);

  useEffect(() => {
    if (!active) return;
    const timer = window.setInterval(() => setElapsed(value => value + 1), 1000);
    return () => window.clearInterval(timer);
  }, [active]);

  return (
    <div style={{ display: "grid", justifyItems: "center", gap: 24 }}>
      <VoiceOrb state={state} inputLevel={mic.level} muted={muted} />
      <VoiceTranscript text="How can I help?" turn={1} complete />
      <VoiceControls
        active={active}
        muted={muted}
        elapsed={elapsed}
        onStart={() => { setActive(true); setState("listening"); }}
        onMuteChange={setMuted}
        onEnd={() => { setActive(false); setState("idle"); setElapsed(0); }}
      />
    </div>
  );
}
```

### API reference

#### VoiceOrb

A luminous fluid sphere in the accent colour, drawn with WebGL, that morphs between idle, listening, thinking, and speaking and reacts to live audio levels. Idle breathes, listening ripples outward with the microphone, thinking orbits a band of light around its rim, and speaking brightens with the voice. Pauses offscreen, falls back to a canvas gradient without WebGL, and draws still frames under reduced motion.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `state` (required) | `"idle" \| "listening" \| "thinking" \| "speaking"` | – | Current voice state. Every shape parameter springs toward the new state, so changes blend mid-motion. |
| `inputLevel` | `MotionValue<number>` | – | Microphone level from 0 to 1, read every frame while listening, such as useMicLevel().level. Simulated when omitted. |
| `outputLevel` | `MotionValue<number>` | – | Voice level from 0 to 1 while speaking. A deterministic speech envelope is used when omitted. |
| `muted` | `boolean` | `false` | Calms and desaturates the orb while listening and ignores the input level. |
| `size` | `number` | `208` | Rendered width and height in px. The sphere fills about 60% of it; the rest holds its light and ripples. Colours follow --accent, or --voice-orb-tint and --voice-orb-tint-2 on any ancestor. |
| `label` | `string` | – | Accessible description. Defaults to a sentence about the state, or "Muted" while listening muted. |
| `className` | `string` | – | Extra class on the canvas. |

#### useMicLevel

Hook that reads the microphone level as a motion value while enabled. Returns { level, source }. Falls back to a simulated voice when the microphone is denied or missing. Nothing is recorded.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `enabled` (required) | `boolean` | – | Asks for the microphone when it turns true and stops every track when it turns false. |

#### VoiceTranscript

One line of live transcript. Words settle in from a soft blur, two lines are kept, and a new turn crossfades in.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `text` (required) | `string` | – | Transcript text so far. Words are split on whitespace. |
| `turn` | `string \| number` | `0` | Change it when a new turn begins so the old line crossfades out. |
| `speaker` | `"user" \| "assistant" \| "system"` | `"assistant"` | Assistant reads in the foreground color, the person in secondary, system smaller and muted. |
| `complete` | `boolean` | `false` | Set when the turn is finished to announce it to screen readers. |
| `className` | `string` | – | Extra class on the wrapper. |

#### VoiceControls

Call controls in one pill: a start button at rest, and mute, a running clock, and end once the session is live.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `active` (required) | `boolean` | – | Whether a session is live. |
| `muted` | `boolean` | `false` | Pressed state of the mute button. |
| `elapsed` | `number` | `0` | Seconds since the session began, shown as m:ss with tabular numerals. |
| `onStart` | `() => void` | – | Called by the start button. |
| `onMuteChange` | `(muted: boolean) => void` | – | Called with the next muted value. |
| `onEnd` | `() => void` | – | Called by the end button. |
| `startLabel` | `ReactNode` | `"Start voice chat"` | Content of the start button. |
| `className` | `string` | – | Extra class on the pill. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Enter / Space | Starts the session, toggles mute, or ends the call from the focused control. |

### Accessibility

- The orb is a canvas with role="img" and an aria-label that follows the state (Listening, Thinking, Speaking, Muted).
- VoiceTranscript hides the animated words and announces only the completed turn through a polite live region.
- The mute button uses aria-pressed and switches its label between Mute and Unmute microphone; the clock is role="timer" with a spoken minutes and seconds label.
- Focus moves to mute when a session starts and back to start when it ends, so keyboard users never lose their place.

### Motion

- Nine shape parameters (breath, wobble, swirl, tint, ring, and more) follow the state on a hand-rolled spring each frame, so state changes interrupt cleanly.
- Listening swells with the input level and draws two ripple rings; speaking pulses with the output level; thinking contracts into a slow swirl.
- The controls pill springs its width to fit while the start button and live controls crossfade with a small scale and blur.
- Reduced motion stops the rAF loop and draws one still frame per state; transcript and controls fall back to short opacity fades.

### Responsive behavior

- The orb has a fixed pixel size from the size prop; pick a smaller value such as 144 on narrow screens.
- The transcript caps at 30rem wide and two lines tall, with a top fade mask so older lines lift away.
- Hover styles on the controls apply only on hover-capable fine pointers; buttons are 40px round for touch.

### Performance

- One requestAnimationFrame loop per orb draws a 96-point blob and gradients on a canvas capped at 2x device pixel ratio.
- An IntersectionObserver and visibilitychange stop the loop while offscreen or in a background tab; a MutationObserver rereads theme colors.
- useMicLevel runs its own rAF loop over a 1024-sample AnalyserNode and closes the AudioContext when disabled.

### Notes for AI

- Use for a voice assistant surface. Feed useMicLevel().level to inputLevel while listening and your TTS analyser level to outputLevel while speaking.
- The orb only visualises; map your session events to the four states yourself (idle, listening, thinking, speaking).
- The body uses --foreground; the inner light uses the brand gradient (--arc-gradient-from and --arc-gradient-to, falling back to --accent). Set --voice-orb-tint and optionally --voice-orb-tint-2 on a parent to recolor it; with only --voice-orb-tint set, both lights use it.
- For recording and saving audio clips use voice-recorder instead; this component never records.

### Related

- [Voice recorder](https://uiarc.dev/components/voice-recorder/markdown): Record with a live waveform, review and scrub, then send the take into the thread.
- [Chat thread](https://uiarc.dev/components/chat-thread/markdown): A chat thread with grouped messages, reactions, read receipts, typing, and a composer with attachments.

### Also in audio and video

- [Now playing](https://uiarc.dev/components/now-playing/markdown): Grow a mini player into the full player in one continuous morph.

### Guidance for AI tools

Voice orb: A voice mode orb that listens, thinks, and speaks, with a live transcript and call controls. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Now playing

> Grow a mini player into the full player in one continuous morph.

- Type: Component (special)
- Access: Arc Pro
- Page: https://uiarc.dev/components/now-playing
- Markdown: https://uiarc.dev/components/now-playing/markdown
- Source file: `registry/components/now-playing/now-playing.tsx`
- Dependencies: motion, lucide-react
- Keywords: special, media, music, react music player, now playing bar, mini player, audio player component, spotify style player, waveform scrubber

### When to use

- Media that keeps playing while people browse, such as music, podcasts, or audio lessons.
- A mini player bar that expands into a full player with artwork and a scrubber.

### When not to use

- Use bottom-sheet or dialog for a one-off overlay that is not a player.
- Use voice-recorder for recording and playing back short voice notes.
- Use slider for a plain seek bar without the player chrome.

### Installation

Now playing is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/now-playing
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { useRef, useState } from "react";
import { NowPlaying } from "@/components/arc/now-playing/now-playing";

const tracks = [
  { id: "1", title: "Night Drive", artist: "Arc Ensemble", duration: 212, artwork: "/covers/night-drive.jpg", src: "/audio/night-drive.mp3" },
  { id: "2", title: "Low Tide", artist: "Harbor", duration: 185, artwork: "/covers/low-tide.jpg", src: "/audio/low-tide.mp3" },
];

export function Player() {
  const audio = useRef<HTMLAudioElement>(null);
  const [index, setIndex] = useState(0);
  const [playing, setPlaying] = useState(false);
  const [time, setTime] = useState(0);

  return (
    <>
      <audio ref={audio} src={tracks[index].src} autoPlay={playing} onTimeUpdate={event => setTime(event.currentTarget.currentTime)} />
      <NowPlaying
        tracks={tracks}
        index={index}
        onIndexChange={setIndex}
        playing={playing}
        onPlayingChange={next => { setPlaying(next); if (next) audio.current?.play(); else audio.current?.pause(); }}
        currentTime={time}
        onSeek={seconds => { if (audio.current) audio.current.currentTime = seconds; }}
      />
    </>
  );
}
```

### API reference

#### NowPlaying

A compact player that grows from a mini bar into a full player in one continuous morph, with a waveform scrubber and artwork that slides in the direction you skip.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `tracks` (required) | `{ id: string; title: string; artist: string; duration: number; artwork: string; artworkAlt?: string }[]` | – | The queue. duration is in seconds. |
| `index` | `number` | – | Controlled position in the queue. |
| `defaultIndex` | `number` | `0` | Initial position when uncontrolled. |
| `onIndexChange` | `(index: number) => void` | – | Called when the track changes by skip or when a track ends. The queue wraps at both ends. |
| `playing` | `boolean` | – | Controlled playback state. |
| `defaultPlaying` | `boolean` | `false` | Initial playback state when uncontrolled. |
| `onPlayingChange` | `(playing: boolean) => void` | – | Called on play and pause. |
| `currentTime` | `number` | – | Position in seconds from real audio, such as audio.currentTime on timeupdate. The built-in clock keeps the waveform moving between updates, and each new value corrects it. Ignored while the waveform is being dragged. |
| `onSeek` | `(seconds: number) => void` | – | Called with the new position in seconds when a waveform drag ends, on each keyboard seek, and when Previous restarts the track. Set audio.currentTime here. |
| `defaultExpanded` | `boolean` | `false` | Starts as the full player. |
| `label` | `string` | `"Now playing"` | Accessible name of the player section. |
| `className` | `string` | – | Extra class on the root. |

#### NowPlayingLevels

Three small level bars that dance while a track plays and rest while paused.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `playing` (required) | `boolean` | – | Bars move only while true. |
| `className` | `string` | – | Extra class on the bars. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Enter / Space | Expands or collapses the player and activates play, pause, and skip. |
| ArrowLeft / ArrowRight / ArrowUp / ArrowDown | On the waveform, seeks 5 seconds back or forward. |
| PageUp / PageDown | On the waveform, seeks 30 seconds. |
| Home / End | On the waveform, jumps to the start or end. |
| Escape | Collapses the full player. |

### Accessibility

- The waveform is a slider with aria-valuetext such as "1:05 of 3:32".
- Expand and collapse buttons report aria-expanded. Focus moves to the collapse button on open and back to the mini bar on close.
- Previous restarts the current track when more than 3 seconds have played, and skips back otherwise. A restart calls onSeek(0).
- The current track and play state are announced in a polite live region; artwork is decorative unless artworkAlt is set.

### Motion

- The mini bar morphs into the full player with shared layout while the shell height springs to fit. In the full player, pulling the artwork down more than 70px or flicking it closes the player; an upward pull rubber-bands.
- Artwork slides and blurs in the direction you skip; the waveform stretches under a scrub and level bars dance while playing.
- MotionConfig follows the user's reduced motion setting, replacing travel with short fades; the level bars hold still.

### Responsive behavior

- The shell is min(100%, 21rem) wide; below 360px viewport width the mini bar hides the next button to fit.
- The expanded artwork uses touch-action none for the pull-down gesture, while the waveform keeps pan-y so the page still scrolls.

### Performance

- Playback is an internal useAnimationFrame clock that ticks every frame; it returns early while paused but the frame callback stays registered.
- The waveform is 54 bars and one ResizeObserver; wire a real audio element through the callbacks rather than the internal clock for long sessions.

### Notes for AI

- Choose it for media that keeps playing while people browse. For a one-off overlay use bottom-sheet or dialog.
- Playback runs on an internal clock, so it works without audio; wire onPlayingChange and onIndexChange to a real audio element when needed.

### Related

- [Bottom sheet](https://uiarc.dev/components/bottom-sheet/markdown): A sheet that rests at a peek or full height and follows your finger.
- [Cover flow](https://uiarc.dev/components/cover-flow/markdown): A depth rail of images you can throw, with soft grounded shadows and a quiet reflection.
- [Slider](https://uiarc.dev/components/slider/markdown): Pick a value or a range on a track that follows your finger.
- [Voice recorder](https://uiarc.dev/components/voice-recorder/markdown): Record with a live waveform, review and scrub, then send the take into the thread.

### Also in audio and video

- [Voice orb](https://uiarc.dev/components/voice-orb/markdown): A voice mode orb that listens, thinks, and speaks, with a live transcript and call controls.

### Guidance for AI tools

Now playing: Grow a mini player into the full player in one continuous morph. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Voice recorder

> Record with a live waveform, review and scrub, then send the take into the thread.

- Type: Component (special)
- Access: Arc Pro
- Page: https://uiarc.dev/components/voice-recorder
- Markdown: https://uiarc.dev/components/voice-recorder/markdown
- Source file: `registry/components/voice-recorder/voice-recorder.tsx`
- Dependencies: motion, lucide-react
- Keywords: special, motion, react voice recorder, voice message, audio recorder ui, whatsapp voice note, record audio button, voice memo

### When to use

- Voice notes in chats, comments, or field notes where speaking beats typing.
- A thread of voice bubbles with playback and scrubbing.

### When not to use

- Use now-playing for music or long-form audio.
- Use hold-to-confirm for press-and-hold actions that do not record.
- Use stopwatch to time something without audio.

### Installation

Voice recorder is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/voice-recorder
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { VoiceRecorder, voicePeaks } from "@/components/arc/voice-recorder/voice-recorder";

const history = [
  { id: "m1", duration: 7, peaks: voicePeaks(1, 7), from: "Sam", avatar: "/people/sam.jpg", meta: "9:41 AM" },
];

export function Thread() {
  return <VoiceRecorder defaultMessages={history} maxDuration={30} onSend={message => console.log("sent", message.id)} />;
}
```

### API reference

#### VoiceRecorder

A voice note composer and thread. Tap the mic to record into a live bar with a scrolling waveform and timer, stop into a review you can play and scrub, then send the take into the thread as a voice bubble.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `defaultMessages` | `{ id: string; duration: number; peaks: number[]; from?: string; avatar?: string; meta?: string }[]` | `[]` | Messages already in the thread, oldest first. peaks are bar heights from 0 to 1 (the exported voicePeaks makes deterministic data); from and avatar mark incoming messages. |
| `onSend` | `(message: VoiceMessage) => void` | – | Called with each sent take. Recording is simulated, so wire this to real audio capture. |
| `onCancel` | `() => void` | – | Called when a take is discarded with the trash button or Escape. |
| `maxDuration` | `number` | `60` | Seconds before recording stops on its own and moves to review. |
| `sentMeta` | `string` | `"Just now"` | Meta line under messages you send. |
| `label` | `string` | `"Voice messages"` | Accessible name of the whole recorder. |
| `className` | `string` | – | Class on the root section. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Enter / Space | Activate the focused control: record, stop, send, play, or discard. Focus follows from mic to stop to send and back. |
| Escape | Discard the take while recording or reviewing. |

### Accessibility

- The recorder is a labelled section with a labelled message list; every control is a native button with an aria-label, such as "Stop recording at 0:04" or "Play voice message from Sam, 0:07".
- Recording, review, send, and discard are announced in a polite live region that also describes the mic.
- Waveforms, the live canvas, and timers are aria-hidden; the button labels carry the durations.

### Motion

- Mic, recording bar, review, and sent bubble share one layout id, so a take morphs from the mic into the thread on a spring.
- The live waveform scrolls on a canvas and playback fills the bars left to right; side buttons pop in and content crossfades with a slight blur.
- Motion follows the user's reduced motion setting: layout morphs are skipped, the waveform steps instead of growing, and the thread scrolls without smoothing.

### Responsive behavior

- The recorder fills its container width, and the review waveform flexes its bars between 1.5px and 3px to fit.
- Waveforms keep touch-action pan-y, so scrubbing by tap works without blocking scroll.

### Performance

- Recording is simulated; the live waveform is painted to a canvas each frame only while recording.
- Each message runs its own frame callback that returns early unless playing; long threads are not virtualized.

### Notes for AI

- Use for voice notes in chats, comments, or field notes where speaking beats typing. Audio is simulated; add MediaRecorder capture and upload in onSend before shipping.
- Seed history with voicePeaks for deterministic bars. Messages live in internal state, so persist them from onSend and pass them back as defaultMessages.

### Related

- [Now playing](https://uiarc.dev/components/now-playing/markdown): Grow a mini player into the full player in one continuous morph.
- [Slider](https://uiarc.dev/components/slider/markdown): Pick a value or a range on a track that follows your finger.
- [Hold to confirm](https://uiarc.dev/components/hold-to-confirm/markdown): Confirm a destructive action by holding, not tapping.

### Also in audio and video

- [Voice orb](https://uiarc.dev/components/voice-orb/markdown): A voice mode orb that listens, thinks, and speaks, with a live transcript and call controls.

### Guidance for AI tools

Voice recorder: Record with a live waveform, review and scrub, then send the take into the thread. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Booking pill

> One pill that reshapes through party size, date, time, and a ticket.

- Type: Component (special)
- Access: Arc Pro
- Page: https://uiarc.dev/components/booking-pill
- Markdown: https://uiarc.dev/components/booking-pill/markdown
- Source file: `registry/components/booking-pill/booking-pill.tsx`
- Dependencies: motion, lucide-react
- Keywords: special, motion, react booking widget, table reservation, restaurant booking ui, date and time picker flow, reservation pill, booking flow

### When to use

- Venue or service pages where booking a table or slot is the one action people came for.
- Mobile-first flows that walk through party size, date, time, and confirm in one surface.

### When not to use

- Use date-picker and time-picker inside a regular form for multi-field checkouts.
- Use stepper or multi-step-form for longer flows with many fields.
- Use calendar when people need to see a whole month.

### Installation

Booking pill is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/booking-pill
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { BookingPill, type Booking } from "@/components/arc/booking-pill/booking-pill";

export function ReserveBar({ today, book }: { today: string; book: (booking: Booking) => Promise<void> }) {
  return (
    <BookingPill
      venue="Osteria Nove"
      venueDetail="12 Harbour Street"
      startDate={today}
      hourCycle={24}
      isAvailable={(date, time, party) => !(party > 6 && time > "20:00")}
      onConfirm={book}
    />
  );
}
```

### API reference

#### BookingPill

One floating pill that reshapes itself through a booking flow: party size, a draggable date strip, a time grid, a ticket to confirm, and a booked state.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `venue` (required) | `string` | – | Venue name printed on the ticket. |
| `venueDetail` | `string` | – | Second ticket line, such as the address. |
| `startDate` (required) | `string` | – | First day on the strip as an ISO date. Pass it from data so server and client agree. |
| `days` | `number` | `21` | Days on the strip. |
| `times` | `string[]` | `["17:00", "17:30", … "22:30"]` | Seating times as "HH:MM", in order, shown four to a row. The default runs every half hour from 17:00 to 22:30. |
| `isAvailable` | `(date: string, time: string, partySize: number) => boolean` | – | Whether a time is free. Everything is free by default. |
| `preferredTime` | `string` | `"19:30"` | Preselected when free, otherwise the nearest free time, as "HH:MM". |
| `minPartySize` | `number` | `1` | Smallest party. |
| `maxPartySize` | `number` | `12` | Largest party. |
| `defaultPartySize` | `number` | `2` | Starting party size. |
| `onConfirm` | `(booking: { date: string; time: string; partySize: number }) => Promise<void> \| void` | – | Books the table. Resolve to show the booked state, reject to keep the ticket open with an error. Defaults to a short simulated wait. |
| `onStepChange` | `(step: "start" \| "party" \| "date" \| "time" \| "review" \| "booked") => void` | – | Called on every step, for example to let the page recede while the pill is open. |
| `hourCycle` | `12 \| 24` | `12` | Clock used for displayed times, such as 7:30 PM or 19:30. times, preferredTime, and onConfirm always use "HH:MM". |
| `label` | `string` | `"Book a table"` | Label of the closed pill. |
| `className` | `string` | – | Class on the root element. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Arrow keys | Move a day on the date strip, or between free times in the grid. |
| Page Up / Page Down | Move a week on the date strip. |
| Home / End | First or last day, or first or last free time. |
| Enter | Confirm the date on the strip and continue. |
| Escape | Go back one step. |

### Accessibility

- The date strip is a role="slider" with a spoken aria-valuetext; times are a role="radiogroup" with unavailable times marked aria-disabled.
- Every round icon button has an aria-label (Back, Fewer guests, Next, choose a date).
- Step changes are announced in a polite live region, and booking errors use role="alert".

### Motion

- The pill's shape springs to fit each step while content slides in a beat later in the direction of travel.
- The date strip follows drags 1:1, rubber-bands at the ends, and flicks glide to a day; party count digits roll.
- Reduced motion jumps the strip, drops slides and blurs, and swaps faces with fades.

### Responsive behavior

- The root is a container; each step's face is capped at the container width minus 24px, up to 340 to 420px.
- The date strip drags horizontally with touch-action pan-y, so vertical page scroll still works on touch.

### Performance

- The pill uses a 24px backdrop blur; the date strip renders every day in days, 21 by default.
- ResizeObservers track each face for the shape spring, and only the current step is mounted.

### Notes for AI

- Use on a venue or service page where booking is the one action people came for. Use date-picker and time-picker in a regular form for multi-field checkouts.
- Anchor it to the bottom of its container, pass startDate from the server, and wire isAvailable and onConfirm to your backend. Set hourCycle for display only; data stays in "HH:MM".

### Related

- [Date picker](https://uiarc.dev/components/date-picker/markdown): Choose a date without losing context.
- [Time picker](https://uiarc.dev/components/time-picker/markdown): Choose a time with sensible keyboard behavior.
- [Calendar](https://uiarc.dev/components/calendar/markdown): Browse dates in a clear, compact month view.
- [Number field](https://uiarc.dev/components/number-field/markdown): Enter a bounded number with clear increment controls.
- [Stepper](https://uiarc.dev/components/stepper/markdown): Show where a person is in a multi-step flow and what is done.

### Also in data

- [Activity rings](https://uiarc.dev/components/activity-rings/markdown): Daily goals as tick rings that sweep, count up, and trace a second lap past 100%.
- [Time dial](https://uiarc.dev/components/time-dial/markdown): Spin a dial to pick an hour and see which team cities are at work.
- [Date reel](https://uiarc.dev/components/date-reel/markdown): A 3D wheel date and time picker (like iOS reels) with momentum scrolling, snapping, curved perspective, and full keyboard support.

### Guidance for AI tools

Booking pill: One pill that reshapes through party size, date, time, and a ticket. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Activity rings

> Daily goals as tick rings that sweep, count up, and trace a second lap past 100%.

- Type: Component (special)
- Access: Arc Pro
- Page: https://uiarc.dev/components/activity-rings
- Markdown: https://uiarc.dev/components/activity-rings/markdown
- Source file: `registry/components/activity-rings/activity-rings.tsx`
- Dependencies: motion, lucide-react
- Keywords: special, activity, rings, react activity rings, apple watch rings, fitness rings, goal progress rings, concentric progress, habit tracker rings

### When to use

- Daily goals that fill up and can be exceeded, like move, exercise, and stand.
- Fitness or habit dashboards with a week picker to compare days.

### When not to use

- Use progress or gauge for a single value.
- Use usage-meter for quotas and limits.
- Use activity-heatmap for streaks across many weeks.

### Installation

Activity rings is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/activity-rings
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { ActivityRings } from "@/components/arc/activity-rings/activity-rings";

export function Today() {
  return (
    <ActivityRings
      metrics={[
        { id: "move", label: "Move", unit: "kcal", goal: 500 },
        { id: "exercise", label: "Exercise", unit: "min", goal: 30 },
        { id: "stand", label: "Stand", unit: "hr", goal: 12 },
      ]}
      days={week}
      onRingClose={(metric, day) => celebrate(metric, day)}
    />
  );
}
```

### API reference

#### ActivityRings

Daily goals drawn as concentric tick rings. Arcs sweep to each day's value, a second lap traces the inside edge past 100%, and numbers count to their new amounts.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `metrics` (required) | `{ id: string; label: string; unit: string; goal: number; color?: string }[]` | – | One ring per metric, from the outside in. color falls back to the built in indigo, amber, and sage. |
| `days` (required) | `{ id: string; label: string; short: string; values: Record<string, number> }[]` | – | Days with values keyed by metric id. label is the full date for assistive technology; short is shown under the day. |
| `day` | `string` | – | Controlled selected day id. |
| `defaultDay` | `string` | – | Initial day when uncontrolled. Defaults to the last day. |
| `onDayChange` | `(day: string) => void` | – | Called when a day is picked. |
| `focused` | `string \| null` | – | Controlled isolated metric id. |
| `defaultFocused` | `string \| null` | `null` | Initial isolated metric when uncontrolled. |
| `onFocusedChange` | `(metric: string \| null) => void` | – | Called when a goal is selected or cleared from the legend. |
| `onRingClose` | `(metric: string, day: string) => void` | – | Called when a value on the same day crosses its goal. |
| `label` | `string` | `"Activity"` | Accessible name of the section. |
| `className` | `string` | – | Extra class on the root. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Arrow keys | In the week picker, pick the previous or next day. |
| Home / End | In the week picker, pick the first or last day. |
| Enter / Space | On a legend row, isolates that goal or clears it. |

### Accessibility

- The rings are an img whose label lists each goal's percent for the day.
- Legend rows are toggle buttons with aria-pressed and a spoken summary such as "Move, 420 of 500 kcal, 84 percent".
- The week picker is a radiogroup with a roving tabindex, named by each day's full label.

### Motion

- Every change sweeps from what is on screen to the new values, so a quick second change redirects mid flight; past 100% a second lap traces the inside edge.
- Hovering or selecting a goal dims the others, and numbers count to their new amounts.
- MotionConfig follows the user's reduced motion setting, and values jump without the sweep.

### Responsive behavior

- The root is a container up to 38rem; from 30rem wide the legend moves beside the rings as a list.
- Narrower containers stack the rings above a compact legend.

### Performance

- The rings are SVG arcs driven by motion values, with no animation loop between changes.
- Each metric adds one ring; three to four stay legible within the fixed 220 unit viewBox.

### Notes for AI

- Choose it for daily goals that fill up and can be exceeded. Use progress or gauge for a single value and usage-meter for quotas.
- Keep metric ids stable and use them as keys in each day's values. Control day when another view drives the date.

### Related

- [Progress](https://uiarc.dev/components/progress/markdown): Show how much of a known task is complete.
- [Gauge](https://uiarc.dev/components/gauge/markdown): Show a value against a known range.
- [Usage meter](https://uiarc.dev/components/usage-meter/markdown): Show what fills an allowance and how close it is to the limit.
- [Activity heatmap](https://uiarc.dev/components/activity-heatmap/markdown): See a year of activity at a glance, one square per day.
- [Animated counter](https://uiarc.dev/components/animated-counter/markdown): Give changing totals a clear sense of movement.

### Also in data

- [Booking pill](https://uiarc.dev/components/booking-pill/markdown): One pill that reshapes through party size, date, time, and a ticket.
- [Time dial](https://uiarc.dev/components/time-dial/markdown): Spin a dial to pick an hour and see which team cities are at work.
- [Date reel](https://uiarc.dev/components/date-reel/markdown): A 3D wheel date and time picker (like iOS reels) with momentum scrolling, snapping, curved perspective, and full keyboard support.

### Guidance for AI tools

Activity rings: Daily goals as tick rings that sweep, count up, and trace a second lap past 100%. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Time dial

> Spin a dial to pick an hour and see which team cities are at work.

- Type: Component (special)
- Access: Arc Pro
- Page: https://uiarc.dev/components/time-dial
- Markdown: https://uiarc.dev/components/time-dial/markdown
- Source file: `registry/components/time-dial/time-dial.tsx`
- Dependencies: motion, lucide-react
- Keywords: special, motion, react time zone picker, world clock dial, meeting time planner, timezone converter ui, rotary time picker, time zone dial

### When to use

- Planning a moment across two to five cities, such as calls, releases, or handovers.
- Distributed teams that need to see at a glance who is inside working hours.

### When not to use

- Use time-picker for a single local time.
- Use date-picker or calendar when the day matters more than the hour.
- Use slider for a plain numeric range.

### Installation

Time dial is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/time-dial
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { useState } from "react";
import { TimeDial } from "@/components/arc/time-dial/time-dial";

const cities = [
  { id: "nyc", name: "New York", code: "NYC", offset: -240 },
  { id: "lon", name: "London", code: "LON", offset: 60 },
  { id: "tyo", name: "Tokyo", code: "TYO", offset: 540 },
];

export function CallPlanner() {
  const [time, setTime] = useState(15 * 60);
  return <TimeDial cities={cities} value={time} onValueChange={setTime} hourCycle={24} workingHours={[480, 1020]} label="Call time" />;
}
```

### API reference

#### TimeDial

A 24 hour rotary dial for choosing a time across time zones. Every city rides the dial at its own local time, a shaded band marks working hours, and the home city reads out in the center.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `cities` (required) | `{ id: string; name: string; code: string; offset: number }[]` | – | Two to five cities. offset is minutes from UTC in steps of 15; code is two or three letters shown on the dial. |
| `value` | `number` | – | Controlled time in UTC minutes from midnight on the reference day. May leave 0 to 1439 to reach adjacent days. |
| `defaultValue` | `number` | `0` | Initial time when uncontrolled. |
| `onValueChange` | `(value: number) => void` | – | Fires with the destination as soon as the dial is released or stepped, before it comes to rest. |
| `homeId` | `string` | – | Controlled id of the city the dial reads in. Defaults to the first city. |
| `defaultHomeId` | `string` | – | Initial home city when uncontrolled. |
| `onHomeChange` | `(id: string) => void` | – | Called when a city is chosen from the list. |
| `min` | `number` | `-Infinity` | Earliest time in UTC minutes. The dial stretches past it and springs back. |
| `max` | `number` | `Infinity` | Latest time in UTC minutes. |
| `weekday` | `number` | `1` | Weekday of the reference day in UTC, 0 for Sunday. |
| `hourCycle` | `12 \| 24` | `12` | Clock for the readout: 12 reads 9:30 AM, 24 reads 09:30. |
| `workingHours` | `[start: number, end: number]` | `[540, 1080]` | Local working hours in minutes from midnight, drawn as a band on the dial. A city inside the band is at work. Defaults to 9:00 to 18:00. |
| `label` | `string` | `"Time"` | Accessible name of the dial. |
| `className` | `string` | – | Class on the root element. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Arrow Right / Arrow Up | Step forward a quarter hour. |
| Arrow Left / Arrow Down | Step back a quarter hour. |
| Page Up / Page Down | Step an hour forward or back. |
| Home / End | Jump to the start or last quarter hour of the home city's day. |

### Accessibility

- The dial is a focusable role="slider" with aria-valuenow in home-city minutes and a spoken aria-valuetext.
- The city list uses buttons with aria-pressed for the home city.
- Changes are announced through a polite live region; the SVG face and readout are aria-hidden.

### Motion

- Drags have soft quarter-hour detents, flicks coast on a spring into the nearest quarter hour, and bounds rubber-band.
- Readout digits roll like an odometer, city marks swap between knob and dot as the home city changes, and the sun and moon turn over at the day/night boundary.
- Reduced motion removes flick coasting and replaces rises and blurs with plain fades.

### Responsive behavior

- The root is a container up to 720px; from 600px the dial and city list sit side by side, below that they stack.
- The dial is min(100%, 256px) with touch-action none, so dragging it on touch never scrolls the page.
- Below 360px of container width the city rows tighten.

### Performance

- The face is one SVG and rotation runs on motion values, so drags do not re-render city rows.
- Offsets are fixed per city; there is no time zone database, so pass DST-correct offsets yourself.

### Notes for AI

- Use to plan a moment across two to five offices (calls, releases, handovers). For a single local time use time-picker.
- Store the value in UTC minutes and convert per city yourself; offsets are fixed, so pass DST-correct offsets for the date in question.
- Set workingHours to the team's shared day so the band shows at a glance who would be at work, and hourCycle to match the locale.

### Related

- [Time picker](https://uiarc.dev/components/time-picker/markdown): Choose a time with sensible keyboard behavior.
- [Date picker](https://uiarc.dev/components/date-picker/markdown): Choose a date without losing context.
- [Calendar](https://uiarc.dev/components/calendar/markdown): Browse dates in a clear, compact month view.
- [Slider](https://uiarc.dev/components/slider/markdown): Pick a value or a range on a track that follows your finger.

### Also in data

- [Booking pill](https://uiarc.dev/components/booking-pill/markdown): One pill that reshapes through party size, date, time, and a ticket.
- [Activity rings](https://uiarc.dev/components/activity-rings/markdown): Daily goals as tick rings that sweep, count up, and trace a second lap past 100%.
- [Date reel](https://uiarc.dev/components/date-reel/markdown): A 3D wheel date and time picker (like iOS reels) with momentum scrolling, snapping, curved perspective, and full keyboard support.

### Guidance for AI tools

Time dial: Spin a dial to pick an hour and see which team cities are at work. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Date reel

> A 3D wheel date and time picker (like iOS reels) with momentum scrolling, snapping, curved perspective, and full keyboard support.

- Type: Component (special)
- Access: Arc Pro
- Page: https://uiarc.dev/components/date-reel
- Markdown: https://uiarc.dev/components/date-reel/markdown
- Source file: `registry/components/date-reel/date-reel.tsx`
- Dependencies: motion, lucide-react
- Keywords: special, input, date, gesture, new, date picker, time picker, wheel picker, reel, drum picker, ios picker, scroll picker, momentum, snap, schedule send, reminder, birthday, 3d

### When to use

- Scheduling a send, reminder or post where a phone-style wheel is familiar and faster than a calendar grid.
- Touch-first flows and mobile web, where flicking a reel beats typing a date.
- Birthdays and other dates far from today, using date mode with its month, day and year reels.

### When not to use

- Use date-picker or date-range-picker when people need to see a whole month or pick a range.
- Use time-picker for a compact field inside a dense form.
- Use time-dial to compare times across cities.

### Installation

Date reel is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/date-reel
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { DateReel } from "@/components/arc/date-reel/date-reel";

export function SendLater({ onSchedule }: { onSchedule: (at: Date) => Promise<void> }) {
  return (
    <DateReel
      title="Send later"
      today={new Date(2026, 8, 24)}
      defaultValue={new Date(2026, 8, 25, 9, 0)}
      onConfirm={onSchedule}
    />
  );
}
```

### API reference

#### DateReel

A 3D reel date and time picker, like the wheels on a phone. Each column is a curved drum laid on a real cylinder: flick it and it keeps your momentum, glides and snaps into a glass lens, and a drag past the first or last entry stretches like rubber. A summary above reads the moment back in words as the reels turn ("Tomorrow at 9:00 AM"), quick picks spin every reel to a preset, and an optional confirm button settles in place.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `mode` | `"datetime" \| "date" \| "time"` | `"datetime"` | Which reels to show: day, hour, minute and AM or PM; month, day and year; or time only. |
| `value` | `Date` | – | Controlled value. When it changes from outside, every reel spins to it along the short way around. |
| `defaultValue` | `Date` | `Sep 24, 2026 9:30 AM` | Starting value when uncontrolled. Pass a fixed date so the first render matches on server and client. |
| `onChange` | `(value: Date) => void` | – | Called once when the reels come to rest on a new moment, not on every frame. |
| `today` | `Date` | `Day of the first value` | Start of today, used for the Today entry and relative words such as Tomorrow or In 12 days. Pass new Date() after mount in an app. |
| `minDate` | `Date` | `30 days before today (100 years in date mode)` | Earliest selectable day. The day and year reels stop here with a rubber band. |
| `maxDate` | `Date` | `A year after today (10 years in date mode)` | Latest selectable day. |
| `minuteStep` | `1 \| 5 \| 10 \| 15 \| 30` | `5` | Minutes between entries on the minute reel. |
| `hourCycle` | `12 \| 24` | `12` | 12 hour clock with an AM or PM reel, or a 24 hour clock. |
| `locale` | `string` | `"en-US"` | BCP 47 locale for day and month names, the time format, the AM and PM words and relative phrases. |
| `presets` | `{ label: string; value: Date \| ((today: Date) => Date) }[] \| false` | `This evening, Tomorrow, Monday` | Quick picks under the reels. Choosing one spins every reel to it with a small stagger. The chip that matches the current value is marked pressed. false hides them. |
| `title` | `string` | – | Optional heading above the summary, such as "Send later". |
| `onConfirm` | `(value: Date) => void \| Promise<void>` | – | Adds a primary button. Return a promise to show pending, success and failure in place without changing its width. |
| `labels` | `DateReelLabels` | – | Words for localization: reel names (day, month, date, year, hour, minute, period), the at joiner, the quick picks group name and the confirm button states. |
| `intro` | `boolean` | `true` | Spins the reels into place, one after another, the first time the picker scrolls into view. |
| `speed` | `number` | `1` | Multiplies the speed of glides, snaps and the intro. |
| `paused` | `boolean` | `false` | Stops automatic motion. Reels still follow a drag and land on the nearest entry at once. |
| `accent` | `string` | – | Any CSS color for the active reel in the lens and the chosen quick pick. Defaults to the theme accent. |
| `label` | `string` | `"Date and time"` | Accessible name of the picker group. |
| `className` | `string` | – | Class on the root element. |
| `style` | `CSSProperties` | – | Inline styles on the root element. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Tab | Moves between reels, the quick picks and the confirm button. |
| Arrow up / Arrow down | Turns the focused reel one entry. |
| Page up / Page down | Turns by a larger step: a week of days, 3 or 6 hours, 15 minutes, 10 years. |
| Home / End | Jumps to the first or last entry of the reel. |
| Arrow left / Arrow right | Moves focus to the neighbouring reel. |
| Type a number or letters | Jumps to the matching entry, such as 4 for 4 o'clock, 45 for :45, p for PM or ma for March. |

### Accessibility

- The picker is a named group; each reel is a role="spinbutton" with its own name (Day, Hour, Minute, AM or PM) and aria-valuetext that reads the entry, such as "Fri, Sep 25".
- A polite live region announces the full moment once the reels come to rest after a change, and again when the confirm button succeeds or fails.
- Pointer focus draws no ring; keyboard focus shows Arc's shared focus ring. The focused reel shows its entry in the accent color inside the lens, and quick picks use aria-pressed.
- Dates that do not exist, such as February 30, are dimmed on the reel and the day reel turns back to the last real day by itself.
- Drawn entries and the visual summary are hidden from assistive technology so a moving reel never floods the reader.

### Motion

- One requestAnimationFrame loop runs only while a reel moves and writes transforms, opacity and text straight to recycled DOM nodes; React re-renders only when a value is committed.
- Each reel is projected onto a cylinder: entries rise on a sine curve, compress with the cosine of their angle and fade toward the edges, and a second copy clipped to the lens shows the crisp selected text.
- A flick keeps its measured velocity on an exponential glide that is solved to land exactly on an entry, then hands the last half row to a critically damped spring; drags past the ends stretch like rubber and bounce back.
- Keyboard steps, taps, wheel scrolling and quick picks all spin on the same spring, so pressing again mid-spin adds to the motion instead of restarting it.
- The loop stops when the picker leaves the viewport or the tab is hidden and resumes where it left off. With reduced motion every change lands at once and there is no intro.

### Responsive behavior

- A container query sets the row height and type size, so the reels fit a 320px phone and read larger on desktop without changing proportions.
- Reels size to their widest entry and sit centered under one lens that spans the full width.
- Below about 480px the confirm button moves under the quick picks at full width and 44px tall.
- Reels use touch-action pan-x, so a vertical swipe turns the reel and does not scroll the page.

### Performance

- Eleven recycled nodes per reel (twice, for the lens), regardless of how many days or years the range holds.
- Text is written only when a node shows a new entry; the loop sleeps when every reel is at rest.
- Wheel scrolling is attached as a non-passive listener only on the reels.

### Notes for AI

- Use it where choosing a moment is the task: schedule send, reminders, booking a slot, a birthday on sign up.
- Pass today and defaultValue as fixed dates for server rendering, then update today after mount if you need the real clock.
- onChange fires when the reels rest, so it is safe to save or validate there. For a confirm flow return the promise from onConfirm.

### Related

- [Time picker](https://uiarc.dev/components/time-picker/markdown): Choose a time with sensible keyboard behavior.
- [Date picker](https://uiarc.dev/components/date-picker/markdown): Choose a date without losing context.
- [Time dial](https://uiarc.dev/components/time-dial/markdown): Spin a dial to pick an hour and see which team cities are at work.

### Also in data

- [Booking pill](https://uiarc.dev/components/booking-pill/markdown): One pill that reshapes through party size, date, time, and a ticket.
- [Activity rings](https://uiarc.dev/components/activity-rings/markdown): Daily goals as tick rings that sweep, count up, and trace a second lap past 100%.

### Guidance for AI tools

Date reel: A 3D wheel date and time picker (like iOS reels) with momentum scrolling, snapping, curved perspective, and full keyboard support. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Keycap keyboard

> Mechanical keycaps that sink and light up as you type, with the text above the board.

- Type: Component (special)
- Access: Arc Pro
- Page: https://uiarc.dev/components/keycap-keyboard
- Markdown: https://uiarc.dev/components/keycap-keyboard/markdown
- Source file: `registry/components/keycap-keyboard/keycap-keyboard.tsx`
- Dependencies: lucide-react
- Keywords: special, keyboard, motion, new, mechanical keyboard, keycap animation, 3d keyboard react, keyboard component, typing animation, key press effect, virtual keyboard

### When to use

- Landing pages for keyboard-first products and developer tools.
- Onboarding that teaches shortcuts by lighting the keys they use.
- Playful empty states and easter eggs.

### When not to use

- Form input; use a real text field.
- On-screen keyboards for accessibility needs; use the platform's.

### Installation

Keycap keyboard is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/keycap-keyboard
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { KeycapKeyboard } from "@/components/arc/keycap-keyboard/keycap-keyboard";

export function TypeToTry() {
  return <KeycapKeyboard listen="window" placeholder="Type anything" />;
}

// Letters only
<KeycapKeyboard layout="letters" />

// A four key macro pad
<KeycapKeyboard rows={[["a", "r", "c", "backspace"]]} showOutput={false} />
```

### API reference

#### KeycapKeyboard

A board of sculpted mechanical keycaps. Physical typing and clicks press the matching cap into its housing, bloom a faint light under it, and add the character to a wrapping text area above the board.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `string` | – | Controlled text. |
| `defaultValue` | `string` | `""` | Initial text when uncontrolled. |
| `onValueChange` | `(value: string) => void` | – | Called with the new text after every key. |
| `layout` | `"compact" \| "letters"` | `"compact"` | Compact is a full 60% board with numbers, punctuation, and modifiers. Letters is three letter rows with shift, delete, and a space bar. |
| `rows` | `string[][]` | – | Custom rows that override layout. Single characters, plus "space", "backspace", "enter", "shift", "tab", and "caps". |
| `maxLength` | `number` | `280` | Longest text kept. Older characters drop off the start. |
| `listen` | `"focus" \| "window"` | `"focus"` | Where physical keys are heard. "window" listens across the page but ignores other text fields and shortcuts with Command, Control, or Alt. |
| `placeholder` | `string` | `"Start typing"` | Shown while the text is empty. |
| `showOutput` | `boolean` | `true` | Hides the typed text area when you render the value yourself. |
| `label` | `string` | `"Keyboard"` | Accessible name for the board. |
| `className` | `string` | – | Extra class on the root. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Any printable key | Types the character and holds the matching cap down while the key is held. Caps match on physical position, so every layout lights the right cap. |
| Backspace | Deletes the last character; holding it repeats. |
| Enter | Starts a new line. |
| Shift, Tab, Caps, modifiers | Light their caps. Tab still moves focus. |
| Tab to a cap, then Enter or Space | Presses that cap as a button. Shift latches for the next character. |

### Accessibility

- Every cap is a real button named by its character or function (Space, Delete, Return, Shift).
- The typed text is a read-only, multiline textbox named Typed text; focusing it lets physical keys type in focus mode.
- Shortcuts with Command, Control, or Alt pass through untouched, and window mode never captures keys typed into other fields.

### Motion

- A cap drops 92% of its travel in 35ms on key down and returns in 200ms with a small lift past rest, so each press feels crisp.
- A faint light blooms on the board under the cap and fades over 700ms; fast typing leaves a soft trail.
- The caret holds still while you type and starts blinking again after 600ms idle. New characters fade in over 140ms.
- Reduced motion removes cap travel, character fades, and the blink; the light and legend color still respond.

### Responsive behavior

- One size unit comes from a container query so the widest row always fits, from 320px up to a 54px cap on wide screens.
- Travel, gaps, corner radii, and legends all scale from the same unit.
- Taps press caps on touch down; pointer capture keeps a cap down until the finger lifts.

### Performance

- Caps are memoized with stable props and never re-render while typing; a press flips one data attribute on one button.
- One native keydown and keyup listener on the window or the board. No layout reads on the key path.
- Travel and light are CSS transitions on transform and opacity only. A burst of 15 keys a second holds 16.7ms frames.
- The text area stays pinned to its newest line through column-reverse layout, with no scroll code.

### Notes for AI

- Use it as a playful hero or a try-it moment: keyboard-first products, typing tests, launch pages.
- listen="window" makes the page feel alive immediately; use "focus" when other inputs share the page.
- Pass rows to build a macro pad or a single word, such as [["a", "r", "c"]].
- It is not a replacement for a real text field in forms.

### Related

- [Shortcut recorder](https://uiarc.dev/components/shortcut-recorder/markdown): Record key combinations into key caps, with conflict warnings, Kbd, and a searchable cheatsheet.
- [Command palette](https://uiarc.dev/components/blocks/command-palette/markdown): A complete keyboard driven action surface with search, grouped results, and shortcuts.
- [Hold to confirm](https://uiarc.dev/components/hold-to-confirm/markdown): Confirm a destructive action by holding, not tapping.

### Also in type

- [Slot text](https://uiarc.dev/components/slot-text/markdown): Text and numbers that spin into their new value on staggered slot machine reels.
- [Sand text](https://uiarc.dev/components/sand-text/markdown): A headline made of sand that pours into the letters, crumbles where the cursor digs, and heals itself.
- [Typewriter terminal](https://uiarc.dev/components/typewriter-terminal/markdown): A terminal that types a scripted CLI session with a seeded human cadence, colors the shell syntax, and streams output lines, progress bars and spinners, with a scrubber, play/pause and replay controls.

### Guidance for AI tools

Keycap keyboard: Mechanical keycaps that sink and light up as you type, with the text above the board. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Slot text

> Text and numbers that spin into their new value on staggered slot machine reels.

- Type: Component (special)
- Access: Free, open source
- Page: https://uiarc.dev/components/slot-text
- Markdown: https://uiarc.dev/components/slot-text/markdown
- Registry item: https://uiarc.dev/r/slot-text.json
- Source file: `registry/components/slot-text/slot-text.tsx`
- Dependencies: motion
- Keywords: special, text, numbers, new, slot machine text, rolling number, number ticker, odometer react, slot text animation, price animation, animated digits

### When to use

- Pricing toggles, KPI cards, dashboards changing period.
- Launch moments, raffles, and reveals.

### When not to use

- Values that update several times a second.
- Long sentences; reels are for short values.

### Installation

#### CLI

Run one of these in a project set up with `shadcn init`:

```bash
npx shadcn@latest add @uiarc/slot-text
pnpm dlx shadcn@latest add @uiarc/slot-text
yarn dlx shadcn@latest add @uiarc/slot-text
bunx --bun shadcn@latest add @uiarc/slot-text
```

The `@uiarc` name needs `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`. Without it, use the full URL:

```bash
npx shadcn@latest add https://uiarc.dev/r/slot-text.json
```

#### Manual

1. Install the dependencies:

```bash
npm install motion
```

2. Copy the source into your project. Main file: `registry/components/slot-text/slot-text.tsx`

   The source is in the registry item: https://uiarc.dev/r/slot-text.json

3. Arc imports use the `@/` alias for `registry/` and `lib/`. Keep the same folders or update the import paths.

### Usage

```tsx
import { SlotText } from "@/components/arc/slot-text/slot-text";

<SlotText value={revenue} format={value => `$${value.toLocaleString("en-US")}`} announce />

<SlotText value={live ? "Live now" : "Soon"} spins={2} />
```

### API reference

#### SlotText

Text or a number where every character is a reel. On change, digits count through the wheel in the direction the number moved, letters shuffle through the alphabet, and reels land left to right without overshoot.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` (required) | `string \| number` | – | The value to show. Numbers pass through format. |
| `format` | `(value: number) => string` | – | Formats number values. Defaults to en-US grouping (12,480). |
| `duration` | `number` | `0.9` | Seconds the first reel spins. |
| `stagger` | `number` | `0.07` | Seconds between reels stopping, left to right. |
| `spins` | `number` | `1` | Extra full turns before landing. 0 rolls straight to the new digit. |
| `align` | `"start" \| "end"` | – | Which end reels are matched from when the length changes. Numbers default to end, strings to start. |
| `announce` | `boolean` | `false` | Announces new values politely to screen readers. |
| `className` | `string` | – | Extra class on the root. Font size and color come from the parent. |

### Accessibility

- The full value is real text in a visually hidden span; the reels are aria-hidden.
- announce adds a polite live region for values that change without user action.

### Motion

- Each reel spins with a fast start and a long, soft landing that never passes the target.
- Reels stop one after another left to right; blur follows each reel's speed, so fast spins smear and landings are sharp.
- A reel's width follows its new character on a critically damped spring, and new characters grow in while removed ones collapse.
- Leading symbols such as a currency sign stay on their own reels, and separators stay aligned from the end, so 999 to 1,000 only spins digits.
- Changing the value mid-spin restarts from the cell on screen, keeping its offset, so nothing jumps.
- Reduced motion swaps values instantly.

### Responsive behavior

- It is inline text and scales with its font size; reels are measured in em.

### Performance

- Each reel is one transform on a motion value; React re-renders only when the value changes.
- Blur is removed when a reel is still.

### Notes for AI

- Use it where a change deserves a beat: prices switching plans, stats changing period, a launch status flipping.
- Put it inside text you style; it inherits font, size, weight, and color. Digits use tabular numerals.
- For values that tick every second, use a counter with spins={0} or animated-counter; long spins on every tick get tiring.

### Related

- [Animated counter](https://uiarc.dev/components/animated-counter/markdown): Give changing totals a clear sense of movement.
- [Countdown](https://uiarc.dev/components/countdown/markdown): A launch countdown with rolling digits that morphs into a live state at zero.
- [Text morph](https://uiarc.dev/components/text-morph/markdown): Morph a label into its next state, letter by letter.
- [Billing toggle](https://uiarc.dev/components/billing-toggle/markdown): A monthly and yearly switch with a savings badge and prices that roll to the new amount.

### Also in type

- [Keycap keyboard](https://uiarc.dev/components/keycap-keyboard/markdown): Mechanical keycaps that sink and light up as you type, with the text above the board.
- [Sand text](https://uiarc.dev/components/sand-text/markdown): A headline made of sand that pours into the letters, crumbles where the cursor digs, and heals itself.
- [Typewriter terminal](https://uiarc.dev/components/typewriter-terminal/markdown): A terminal that types a scripted CLI session with a seeded human cadence, colors the shell syntax, and streams output lines, progress bars and spinners, with a scrubber, play/pause and replay controls.

### Guidance for AI tools

Slot text: Text and numbers that spin into their new value on staggered slot machine reels. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Sand text

> A headline made of sand that pours into the letters, crumbles where the cursor digs, and heals itself.

- Type: Component (special)
- Access: Arc Pro
- Page: https://uiarc.dev/components/sand-text
- Markdown: https://uiarc.dev/components/sand-text/markdown
- Source file: `registry/components/sand-text/sand-text.tsx`
- Dependencies: motion
- Keywords: text, canvas, physics, new, sand, falling sand, cellular automaton, particles, text effect, headline, crumble, hourglass

### When to use

- A hero headline or section title that should be fun to touch.
- Short words that change on a selection, like a product name or theme.

### When not to use

- Body copy or long headings; use in-view-title or text-reveal.
- Text that must stay readable while people interact near it, like form labels.

### Installation

Sand text is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/sand-text
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { SandText } from "@/components/arc/sand-text/sand-text";

export function Hero() {
  return <SandText as="h1" text="Dunes" />;
}
```

### API reference

#### SandText

A headline made of sand. Grains pour in and pack into the letters, the pointer digs through them and throws grains that tumble and pile, and at rest the letters heal while the extra sand drifts away. Changing the text collapses the old word into sand.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `text` (required) | `string` | – | The text to form. Keep it to one short line. Changing it collapses the old word and pours the new one. |
| `grain` | `number` | `2` | Grain size in CSS px. |
| `radius` | `number` | `14` | Radius the pointer digs through, in CSS px. |
| `palette` | `string[]` | – | Grain colors. Each grain picks one and varies it slightly. Defaults to the text color. |
| `as` | `"h1" \| "h2" \| "h3" \| "p"` | `"h2"` | Element for the visually hidden text. |
| `className` | `string` | – | Extra class on the root. Set font-size here to size the letters. |
| `style` | `CSSProperties` | – | Inline styles on the root. |

### Accessibility

- The real text is rendered in a visually hidden heading, so screen readers and search read it as text.
- The canvas is aria-hidden. Digging is decorative and never removes the text from the accessibility tree.

### Motion

- Letters fill bottom first like jars. Dug grains fly with the pointer's velocity and settle with a falling sand automaton.
- Grains that come to rest inside a letter stick again, missing grains pour back in once the pointer rests, and loose sand outside the letters drifts away.
- A new word turns the old letters loose, so the old text collapses while the new one pours in.
- Reduced motion shows the letters formed, turns digging off, and swaps words instantly.

### Responsive behavior

- The grid is derived from the box size and the text is fitted to 94 percent of the width, so it works at 320px.
- Touch: dragging a finger digs; vertical scroll still works.

### Performance

- One grid cell per grain, drawn as a small ImageData scaled up without smoothing. A 700px wide headline is about 50,000 cells.
- The loop sleeps once every grain has settled and the pointer is gone.

### Notes for AI

- Use for one short headline. Size it with font-size on className; the box is 1.55em tall to leave room for piles.
- Pass palette for tinted sand, but the default text color matches Arc surfaces in both themes.

### Also in type

- [Keycap keyboard](https://uiarc.dev/components/keycap-keyboard/markdown): Mechanical keycaps that sink and light up as you type, with the text above the board.
- [Slot text](https://uiarc.dev/components/slot-text/markdown): Text and numbers that spin into their new value on staggered slot machine reels.
- [Typewriter terminal](https://uiarc.dev/components/typewriter-terminal/markdown): A terminal that types a scripted CLI session with a seeded human cadence, colors the shell syntax, and streams output lines, progress bars and spinners, with a scrubber, play/pause and replay controls.

### Guidance for AI tools

Sand text: A headline made of sand that pours into the letters, crumbles where the cursor digs, and heals itself. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Typewriter terminal

> A terminal that types a scripted CLI session with a seeded human cadence, colors the shell syntax, and streams output lines, progress bars and spinners, with a scrubber, play/pause and replay controls.

- Type: Component (special)
- Access: Arc Pro
- Page: https://uiarc.dev/components/typewriter-terminal
- Markdown: https://uiarc.dev/components/typewriter-terminal/markdown
- Source file: `registry/components/typewriter-terminal/typewriter-terminal.tsx`
- Dependencies: motion, lucide-react
- Keywords: special, motion, terminal, new, typewriter, cli, install, command line, shell, typing animation, npm, developer tools, replay, scrubber

### When to use

- A landing page hero or install section for a developer tool, SDK, or CLI.
- Docs quick starts that show what each command prints before people run it.
- Changelog or launch posts that show a new command in action.

### When not to use

- Use code-block for commands and source that people need to read and copy without waiting.
- Use log-stream for real, live output from a running process.
- Use code-magic-move to show how a file changes between versions.

### Installation

Typewriter terminal is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/typewriter-terminal
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { TypewriterTerminal } from "@/components/arc/typewriter-terminal/typewriter-terminal";

export function InstallHero() {
  return (
    <TypewriterTerminal
      title="Install"
      steps={[
        {
          command: "npm install @acme/sdk",
          output: [
            { kind: "progress", label: "Fetching packages", duration: 1.2 },
            { text: "Added 12 packages in 1.8s", tone: "success" },
          ],
        },
        {
          command: "npx acme login",
          output: [
            { kind: "task", label: "Opening the browser", done: "0.3s" },
            "Signed in as dana@acme.dev",
          ],
        },
      ]}
      rows={8}
    />
  );
}
```

### API reference

#### TypewriterTerminal

A terminal window that types a scripted CLI session with a human cadence. Each command is colored as shell syntax while it is typed: the program, flags, strings, paths and packages, operators, and env assignments. Output streams in underneath as plain lines, progress bars that fill with a realistic stall, and spinners that resolve to a tick with a timing. The screen follows the newest line on a spring, and a scrubber under the window rewinds and replays the whole session, so the text untypes and retypes under your finger.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `steps` | `{ command: string; output?: TypewriterTerminalOutput[]; cwd?: string; pause?: number }[]` | `A create-next-app, shadcn add, and npm run dev session` | The session in order. cwd changes the working directory shown in this prompt and every later one. pause is the rest in seconds after the output. |
| `TypewriterTerminalOutput` | `string \| { text, tone?, delay? } \| { kind: "progress", label, duration? } \| { kind: "task", label, done?, duration? }` | – | A string prints a plain line and an empty string a blank line. tone is default, muted, success, warning, danger, or accent; success, warning, and danger add a matching icon. URLs in text are shown as links. A progress line fills a bar with a percentage. A task shows a spinner, then a tick and its done text, such as 0.4s. |
| `title` | `string` | `"zsh"` | Window title in the title bar. |
| `cwd` | `string` | `"~"` | Working directory shown in the prompt until a step sets its own. |
| `symbol` | `string` | `"$"` | Prompt symbol after the working directory. |
| `speed` | `number` | `1` | Multiplies the playback pace. At 1 the default session takes about sixteen seconds. The cadence itself is seeded from the commands, so it is identical in every replay and on the server. |
| `paused` | `boolean` | `false` | Holds playback where it is, easing to rest instead of stopping in one frame. |
| `loop` | `boolean` | `true` | After a short rest the screen clears upward and the session plays again while the scrubber glides back to the start. When false, playback stops on the final prompt and the play button replays. |
| `rows` | `number` | `11` | Visible rows. The window keeps this height and older lines scroll up as the session grows. |
| `copyable` | `boolean` | `true` | Shows a copy button in the title bar that copies every command, one per line. |
| `accent` | `string` | – | Color of the caret, progress fills, spinners, links, and the scrubber. Defaults to the accent token. |
| `label` | `string` | `"Terminal session"` | Accessible name of the figure. |
| `caption` | `ReactNode` | – | Optional visible caption under the terminal, rendered as a figcaption. |
| `className` | `string` | – | Extra class on the root figure. |
| `style` | `CSSProperties` | – | Inline styles on the root figure. |

### Accessibility

- The root is a figure named by label. The animated screen is hidden from assistive technology, and a visually hidden ordered list gives the full transcript: every command and what it printed.
- The scrubber is a real slider with role="slider", its value in seconds, and a value text that names the current step and command. Arrow keys and Page keys jump to the previous or next command, Home and End go to the start and end, and Space or K plays and pauses.
- Play, pause, and replay are real buttons with specific names. Seeking, pausing, and replaying are announced in a polite live region. Autoplay is not announced, so the loop never floods a screen reader.
- Status never relies on color alone: success, warning, and danger lines carry an icon, tasks show a tick, and progress shows a percentage.
- Pointer focus draws no ring; keyboard focus shows Arc's shared focus ring.

### Motion

- One rAF loop derives the whole screen from a single session time and writes attributes, text, transforms, and opacity straight to the DOM, only when a value changed. React does not render per frame.
- Typing follows a seeded human cadence: a short think before the first key, quick bursts inside words, small stalls on shifted keys and word breaks. The caret stays solid while keys land and blinks softly while it waits.
- Each output line rises a few pixels and fades in. Progress bars fill with a quick start, a stall around the middle, and a steady finish, with a tabular percentage. Spinners cycle braille frames and resolve to a tick.
- The screen follows the newest line on a critically damped spring, and only measures when the visible text changes. The top edge feathers lines away as they scroll off.
- Scrubbing is direct: the session follows the pointer exactly, text untypes and retypes, and a release within a few pixels of a command start settles onto it. Keyboard jumps and replay glide through time on an ease in out curve, so replay visibly rewinds the session.
- Play and pause ease the playback rate on a spring instead of stopping in one frame. The loop clears upward while the scrubber glides back, so it never jumps. The loop stops off screen and in hidden tabs. With reduced motion the finished session shows at once, the caret stops blinking, and the scrubber still jumps between steps.

### Responsive behavior

- The window fills its container and keeps a fixed height in rows. A container query drops the text to the small size and tightens padding below 560px, and hides the time readout below 400px.
- Long commands and output wrap character by character like a real terminal, and the screen still follows the newest line.
- The scrubber and buttons keep 44px touch targets at every width.

### Performance

- The session is compiled once per script into timings. Each frame only compares cached values, so an idle frame writes nothing.
- The loop rests when playback is paused and settled, off screen, and in hidden tabs.

### Notes for AI

- Use it for install instructions, CLI marketing, and quick starts where seeing the commands run sells the product.
- Keep commands real and copyable, since the copy button copies them verbatim. Keep each command under about fifty characters so it fits one line on wide screens; longer ones wrap.
- Two to four steps with two to four output lines each read best. Use tasks and progress lines for work that takes time, and one success line to end each step.
- Everything shown is a simulation. Say so if it could be read as a live session.

### Related

- [Code block](https://uiarc.dev/components/code-block/markdown): Present code with legible hierarchy and copy access.
- [Hero section](https://uiarc.dev/components/blocks/hero-section/markdown): Three full screen SaaS heroes: a live dashboard rising from the bottom edge over a drifting mesh, a workflow graph that routes sample events node by node, and editorial type over a mesh gradient.

### Also in type

- [Keycap keyboard](https://uiarc.dev/components/keycap-keyboard/markdown): Mechanical keycaps that sink and light up as you type, with the text above the board.
- [Slot text](https://uiarc.dev/components/slot-text/markdown): Text and numbers that spin into their new value on staggered slot machine reels.
- [Sand text](https://uiarc.dev/components/sand-text/markdown): A headline made of sand that pours into the letters, crumbles where the cursor digs, and heals itself.

### Guidance for AI tools

Typewriter terminal: A terminal that types a scripted CLI session with a seeded human cadence, colors the shell syntax, and streams output lines, progress bars and spinners, with a scrubber, play/pause and replay controls. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Stretch refresh

> Pull a feed down and a line stretches to tell you when to let go.

- Type: Component (special)
- Access: Arc Pro
- Page: https://uiarc.dev/components/stretch-refresh
- Markdown: https://uiarc.dev/components/stretch-refresh/markdown
- Source file: `registry/components/stretch-refresh/stretch-refresh.tsx`
- Dependencies: motion, lucide-react
- Keywords: special, motion, react pull to refresh, pull to refresh, refresh feed, rubber band refresh, mobile pull down refresh, feed refresh animation

### When to use

- Timelines, inboxes, and activity feeds where new entries arrive at the top.
- Panels that should support pull to refresh by touch, mouse drag, and trackpad scroll.

### When not to use

- Use a plain list for static content that never refreshes.
- Use pagination for paging through older items.
- Use timeline for a static history of events.

### Installation

Stretch refresh is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/stretch-refresh
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { StretchRefresh } from "@/components/arc/stretch-refresh/stretch-refresh";

export function Inbox() {
  const [messages, setMessages] = useState(initial);
  return (
    <StretchRefresh
      title="Inbox"
      items={messages}
      getKey={m => m.id}
      renderItem={m => <MessageRow message={m} />}
      onRefresh={async () => {
        const fresh = await fetchNew();
        setMessages(prev => [...fresh, ...prev]);
        return `${fresh.length} new messages`;
      }}
    />
  );
}
```

### Examples

#### Fill the height of a sidebar

```tsx
<aside style={{ display: "flex", flexDirection: "column", height: "100dvh" }}>
  <StretchRefresh
    title="Activity"
    items={events}
    getKey={e => e.id}
    renderItem={e => <EventRow event={e} />}
    onRefresh={reload}
    className="grow"
  />
</aside>
```

### API reference

#### StretchRefresh

A feed that refreshes when pulled down past its top edge. The sheet rubber-bands while rows spread apart, a line in the gap stretches to show when to let go, then runs while the work happens.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` (required) | `string` | – | Heading above the feed. |
| `subtitle` | `string` | – | Short status under the heading, such as "Updated 14 min ago". A change rises in. |
| `items` (required) | `readonly T[]` | – | Rows in the feed. |
| `getKey` (required) | `(item: T) => string` | – | Stable key for each row. |
| `renderItem` (required) | `(item: T) => ReactNode` | – | Renders one row. |
| `onRefresh` (required) | `() => Promise<string \| void>` | – | Runs after a pull past the threshold or a press of the refresh button. Update items before it resolves; resolve with a short result such as "3 new updates". |
| `threshold` | `number` | `72` | Pull distance in px, after resistance, that arms a refresh. |
| `doneLabel` | `string` | `"Up to date"` | Result shown when onRefresh resolves without one. |
| `errorLabel` | `string` | `"Couldn’t refresh"` | Result shown when onRefresh rejects. |
| `refreshLabel` | `string` | `"Refresh"` | Accessible name of the refresh button. |
| `className` | `string` | – | Extra class on the root. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Enter / Space | On the refresh button, runs a refresh without pulling. |

### Accessibility

- A refresh button gives keyboard and switch users the same path as the pull gesture, with aria-disabled while busy.
- The feed is a labelled, focusable region and the list sets aria-busy while refreshing.
- "Refreshing" and the result are announced in a polite status region.

### Motion

- The sheet rubber-bands with growing resistance while rows spread apart; scrolling up again at the top also pulls.
- A line in the gap reaches full length exactly at the threshold, runs while refreshing, then gives way to the result as new rows settle in from the top.
- Reduced motion keeps the same states and only fades.

### Responsive behavior

- The root is a flex column with min-height 0, so give it a sized parent; the feed scrolls inside it.
- Touch pulls use native listeners and only take over once the feed is at the top, so normal scrolling is untouched.

### Performance

- Rows are not virtualized and use layout position animation; keep the feed to what one panel shows plus a page or so.
- Wheel and touchmove listeners are non-passive so the pull can prevent scrolling, but they return early unless pulling.

### Notes for AI

- Choose it for timelines, inboxes, and activity feeds where new entries arrive at the top. For static lists use a plain list, and for paging use pagination.
- Update items inside onRefresh before it resolves, and keep the call at least half a second so the running line reads as work.

### Related

- [Timeline](https://uiarc.dev/components/timeline/markdown): Follow what happened, newest first, grouped by day.
- [Skeleton](https://uiarc.dev/components/skeleton/markdown): Reserve space while content is still loading.
- [Toast](https://uiarc.dev/components/toast/markdown): Brief confirmation for a completed background action.
- [Reorderable list](https://uiarc.dev/components/reorderable-list/markdown): Organize items with direct drag and drop.

### Also in loaders

- [Morph loader](https://uiarc.dev/components/morph-loader/markdown): Tiny loaders that morph between shapes and fold into a check or a cross when done.
- [Skeleton morph](https://uiarc.dev/components/skeleton-morph/markdown): Loading skeletons that grow into the real content, block by block, instead of swapping.
- [Black hole](https://uiarc.dev/components/black-hole/markdown): A delete transition that pulls the chosen items into a tiny singularity while the rest of the list bends around it; undo spins them back out.
- [Charge session](https://uiarc.dev/components/charge-session/markdown): An EV or device charging card. Energy packets flow from a charger along the cable into the battery pack, which fills toward a draggable charge limit. The charge curve tapers near full, and power, energy, time to limit and cost update live. Stop charging drains the flow.

### Guidance for AI tools

Stretch refresh: Pull a feed down and a line stretches to tell you when to let go. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Morph loader

> Tiny loaders that morph between shapes and fold into a check or a cross when done.

- Type: Component (special)
- Access: Arc Pro
- Page: https://uiarc.dev/components/morph-loader
- Markdown: https://uiarc.dev/components/morph-loader/markdown
- Source file: `registry/components/morph-loader/morph-loader.tsx`
- Dependencies: motion
- Keywords: special, loading, new, loader, spinner, loading indicator, morphing loader, success check, error cross, loading to check, svg spinner

### When to use

- Inline progress inside a button, row, or field where the result should appear in the same spot.
- Short operations that end in a clear success or failure, such as save, publish, or upload.
- Any spinner where a tiny, crisp, brand-consistent mark matters.

### When not to use

- Use progress when the percentage is known.
- Use skeleton when content is loading into a layout.
- Use action-button when the whole button should morph its label too.

### Installation

Morph loader is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/morph-loader
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { MorphLoader } from "@/components/arc/morph-loader/morph-loader";

export function PublishStatus({ state }: { state: "loading" | "success" | "error" }) {
  return <MorphLoader variant="ring" status={state} size={20} successLabel="Published" errorLabel="Publish failed" />;
}
```

### API reference

#### MorphLoader

A tiny loader drawn from four strokes that morph between dots, bars, ring, and square shapes, then into a check or a cross when status changes.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"dots" \| "bars" \| "ring" \| "square"` | `"dots"` | Loading shape. Changing it while loading morphs the strokes into the new shape. |
| `status` | `"loading" \| "success" \| "error"` | `"loading"` | success folds the strokes into a check, error into a cross, loading gathers them back. |
| `size` | `number` | `24` | Rendered size in px. The drawing uses a 24 unit grid. |
| `strokeWidth` | `number` | `2.5` | Stroke thickness in grid units for ring, square, check, and cross. |
| `tone` | `boolean` | `true` | Colors the check with --success and the cross with --danger. Off keeps currentColor. |
| `label` | `string` | `"Loading"` | Announced while loading. |
| `successLabel` | `string` | `"Done"` | Announced on success. |
| `errorLabel` | `string` | `"Failed"` | Announced on error. |
| `decorative` | `boolean` | `false` | Drops the status role and text, for loaders inside a control that announces its own state. |
| `className` | `string` | – | Extra class on the root. |
| `style` | `CSSProperties` | – | Inline styles on the root. |

### Accessibility

- The root is role="status" with visually hidden text that changes to label, successLabel, or errorLabel.
- The drawing is aria-hidden; completion is never shown by color alone because the shape becomes a check or a cross.
- Set decorative inside buttons that already announce progress, so the state is not read twice.

### Motion

- Each stroke is a center, length, direction, bend, and width, each on its own spring, so any shape can morph into any other and interruptions keep velocity.
- Dots bounce in a wave, bars grow in sequence, the ring turns while its arcs breathe, and the square tumbles a quarter turn at a time while its corners open.
- On success or error the loop fades, the drawing turns forward to upright, the strokes draw the mark in order, and the mark pops once.
- Reduced motion shows a static shape per state and swaps instantly.

### Responsive behavior

- Vector drawing at any size; 16 to 32px suit inline use and 48px or more suit empty states.
- The footprint is fixed to size, so state changes never shift layout.

### Performance

- Four SVG paths; one animation frame loop runs only while loading or settling.
- Path data is built from motion values without React renders.

### Notes for AI

- Drive it with one prop: set status from your request state. Keep variant fixed per product for consistency.
- It inherits currentColor, so place it inside buttons and text without extra styling.
- At 16px use strokeWidth 3 for weight that matches 1.75px icon strokes.
- Return status to loading to reuse the same loader for the next request; the strokes gather back into the variant.

### Related

- [Progress](https://uiarc.dev/components/progress/markdown): Show how much of a known task is complete.
- [Skeleton](https://uiarc.dev/components/skeleton/markdown): Reserve space while content is still loading.
- [Action button](https://uiarc.dev/components/action-button/markdown): A compact button for frequent toolbar actions.
- [Icon morph](https://uiarc.dev/components/icon-morph/markdown): Icons that morph between states: menu to close, play to pause, copy to check, and more.

### Also in loaders

- [Stretch refresh](https://uiarc.dev/components/stretch-refresh/markdown): Pull a feed down and a line stretches to tell you when to let go.
- [Skeleton morph](https://uiarc.dev/components/skeleton-morph/markdown): Loading skeletons that grow into the real content, block by block, instead of swapping.
- [Black hole](https://uiarc.dev/components/black-hole/markdown): A delete transition that pulls the chosen items into a tiny singularity while the rest of the list bends around it; undo spins them back out.
- [Charge session](https://uiarc.dev/components/charge-session/markdown): An EV or device charging card. Energy packets flow from a charger along the cable into the battery pack, which fills toward a draggable charge limit. The charge curve tapers near full, and power, energy, time to limit and cost update live. Stop charging drains the flow.

### Guidance for AI tools

Morph loader: Tiny loaders that morph between shapes and fold into a check or a cross when done. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Skeleton morph

> Loading skeletons that grow into the real content, block by block, instead of swapping.

- Type: Component (special)
- Access: Arc Pro
- Page: https://uiarc.dev/components/skeleton-morph
- Markdown: https://uiarc.dev/components/skeleton-morph/markdown
- Source file: `registry/components/skeleton-morph/skeleton-morph.tsx`
- Dependencies: motion
- Keywords: special, loading, motion, new, skeleton loader, loading skeleton, skeleton morph, shared layout loading, content placeholder, shimmer loading, react skeleton animation

### When to use

- Profile cards, feeds, and lists that load in under a few seconds.
- Dashboards where the layout is known before the data arrives.
- Places where a hard swap from gray boxes to content would feel jarring.

### When not to use

- Use skeleton for long lists of hundreds of rows; layout animation there is costly.
- Use a progress indicator when loading takes more than a few seconds.
- Avoid it when the loaded layout is unknown in advance.

### Installation

Skeleton morph is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/skeleton-morph
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { MorphBlock, SkeletonMorph } from "@/components/arc/skeleton-morph/skeleton-morph";

export function ProfileCard({ user }: { user?: User }) {
  return (
    <SkeletonMorph loading={!user} className="card">
      <MorphBlock radius="circle" width={48} height={48}>
        <img src={user?.avatar} alt="" width={48} height={48} />
      </MorphBlock>
      <MorphBlock width={120} lines={1} lineHeight={20}><p style={{ lineHeight: "20px" }}>{user?.name}</p></MorphBlock>
      <MorphBlock lines={3} lineHeight={20}><p style={{ lineHeight: "20px" }}>{user?.bio}</p></MorphBlock>
    </SkeletonMorph>
  );
}
```

### API reference

#### SkeletonMorph

A loading region whose skeleton blocks become the real content. It marks itself busy while loading and eases to the new height when blocks change size.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `loading` (required) | `boolean` | – | While true, blocks show their skeletons and the region is aria-busy. |
| `children` (required) | `ReactNode` | – | The loaded layout, with each visible piece wrapped in a MorphBlock. |
| `stagger` | `number` | `0.04` | Seconds between blocks as they resolve in reading order. |
| `loadingLabel` | `string` | `"Loading"` | Status text read by screen readers while loading. |
| `as` | `ElementType` | `"div"` | The root element. Style it as the card so its border follows the eased height. |
| `className` | `string` | – | Extra class on the root. |
| `style` | `CSSProperties` | – | Inline styles on the root. |

#### MorphBlock

One piece of the layout. It is a size-matched skeleton while loading; on resolve the placeholder stretches to the content's measured box and fades while the content sharpens in, in place.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | – | The loaded content. It is not rendered while loading. |
| `width` | `number \| string` | `"100%"` | Skeleton width. |
| `height` | `number \| string` | `12px, or the lines height` | Skeleton height. |
| `radius` | `number \| string \| "circle"` | `6` | Skeleton corner radius. circle makes a round avatar placeholder. |
| `lines` | `number` | – | Shows a text skeleton with this many lines, each a bar centred in its line box; the last of several is shorter. Use lines={1} for single line text. |
| `lineHeight` | `number` | `20` | Line height of the text in px, so the skeleton is exactly as tall as the loaded text. |
| `as` | `"div" \| "span" \| "p" \| "li" \| "section" \| "article" \| "header" \| "footer" \| "h2" \| "h3" \| "h4"` | `"div"` | The block element. |
| `className` | `string` | – | Extra class on the block. |
| `style` | `CSSProperties` | – | Inline styles on the block. |

### Accessibility

- The root is aria-busy while loading and carries a visually hidden status with loadingLabel.
- Skeleton shapes are aria-hidden; content is not rendered until it is ready, so nothing half loaded is read.
- Blocks keep reading order, so focus order is the same before and after loading.

### Motion

- Blocks resolve one after another in DOM order, 40ms apart by default.
- Each placeholder stretches from its skeleton box to the content's measured box on a critically damped spring while it fades; the content sharpens out of a 4px blur underneath. Blocks change in place and never travel across the layout.
- The shell eases to its new height and clips while it does, so the card border never jumps.
- A calm opacity pulse runs on the skeletons while loading and stops when they resolve.
- Going back to loading is immediate, so fast reloads never leave a block stuck halfway.
- Reduced motion removes the pulse and the stretch and uses a short crossfade.

### Responsive behavior

- Blocks size to their content once loaded, so layouts reflow naturally at any width.
- Skeleton widths accept percentages for fluid placeholders.

### Performance

- Each block measures itself once when it resolves; there is no shared layout projection, so it stays cheap in long cards.
- The height ease uses one ResizeObserver per region.
- The sweep is a CSS transform animation on a pseudo-element.

### Notes for AI

- Wrap every visible piece of the loaded layout in a MorphBlock; unwrapped elements change without animation.
- Size skeletons to the real content: give text an explicit px line-height and pass the same lineHeight and lines, and set width near the typical text width.
- Put the card styles on SkeletonMorph itself so the border follows the eased height.
- For a simple placeholder without the morph, use skeleton.

### Related

- [Skeleton](https://uiarc.dev/components/skeleton/markdown): Reserve space while content is still loading.
- [Morph loader](https://uiarc.dev/components/morph-loader/markdown): Tiny loaders that morph between shapes and fold into a check or a cross when done.
- [Empty state](https://uiarc.dev/components/empty-state/markdown): A useful next step when there is nothing to show yet.

### Also in loaders

- [Stretch refresh](https://uiarc.dev/components/stretch-refresh/markdown): Pull a feed down and a line stretches to tell you when to let go.
- [Black hole](https://uiarc.dev/components/black-hole/markdown): A delete transition that pulls the chosen items into a tiny singularity while the rest of the list bends around it; undo spins them back out.
- [Charge session](https://uiarc.dev/components/charge-session/markdown): An EV or device charging card. Energy packets flow from a charger along the cable into the battery pack, which fills toward a draggable charge limit. The charge curve tapers near full, and power, energy, time to limit and cost update live. Stop charging drains the flow.

### Guidance for AI tools

Skeleton morph: Loading skeletons that grow into the real content, block by block, instead of swapping. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Black hole

> A delete transition that pulls the chosen items into a tiny singularity while the rest of the list bends around it; undo spins them back out.

- Type: Component (special)
- Access: Arc Pro
- Page: https://uiarc.dev/components/black-hole
- Markdown: https://uiarc.dev/components/black-hole/markdown
- Source file: `registry/components/black-hole/black-hole.tsx`
- Dependencies: motion
- Keywords: special, motion, webgl, new, delete animation, archive transition, black hole, singularity, gravitational lensing, spiral, undo, remove items, list delete

### When to use

- Deleting or archiving a handful of selected rows, cards, or files, with an Undo right after.
- Emptying a trash, clearing notifications, or dismissing a batch where the removal should feel final.

### When not to use

- High frequency deletes such as clearing a single chip or tag. Use a quick height collapse instead.
- Irreversible actions without undo. The spectacle should not stand in for a confirmation.
- Very long lists that scroll; the effect paints the visible wrapper, so wrap only the scrolling viewport.

### Installation

Black hole is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/black-hole
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { useLayoutEffect, useRef, useState } from "react";
import { BlackHole } from "@/components/arc/black-hole/black-hole";
import type { BlackHoleHandle } from "@/components/arc/black-hole/black-hole";

export function Inbox({ initial }: { initial: Mail[] }) {
  const hole = useRef<BlackHoleHandle>(null);
  const rows = useRef(new Map<string, HTMLLIElement>());
  const [items, setItems] = useState(initial);
  const [selected, setSelected] = useState<string[]>([]);

  async function remove() {
    await hole.current?.swallow(selected.map(id => rows.current.get(id)!));
    setItems(current => current.filter(item => !selected.includes(item.id)));
    setSelected([]);
  }

  return (
    <BlackHole ref={hole}>
      <ul>
        {items.map(item => (
          <li key={item.id} ref={el => { if (el) rows.current.set(item.id, el); }}>{item.subject}</li>
        ))}
      </ul>
    </BlackHole>
  );
}
```

### API reference

#### BlackHole

Wraps a list or grid. Its ref exposes `swallow` and `release`, which run a GPU transition: the chosen items spiral into a tiny singularity while the rest of the content is gravitationally lensed around it, then the hole collapses with a soft shockwave.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` (required) | `ReactNode` | – | The content that holds the items you remove. It is painted to a texture for the length of the effect. |
| `ref` | `Ref<BlackHoleHandle>` | – | Gives access to `swallow` and `release`. |
| `className` | `string` | – | Extra class on the root. |
| `style` | `CSSProperties` | – | Inline styles on the root. |

#### BlackHoleHandle

Imperative methods on the ref. Calls queue, so a release requested during a swallow waits its turn.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `swallow` | `(targets: Element[], options?: BlackHoleOptions) => Promise<void>` | – | Pulls the elements in. They stay hidden afterwards; remove them from your data when the promise resolves so the list closes the gap. |
| `release` | `(targets: Element[], options?: BlackHoleOptions) => Promise<void>` | – | The reverse. Call it in a layout effect right after the items are back in the DOM: they are hidden at once, the list makes room, then they spiral out into place. |

#### BlackHoleOptions

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `origin` | `{ x: number; y: number }` | – | Where the hole opens, in viewport coordinates. Defaults to the centre of the targets. Pass the delete button's centre to pull items toward it. |
| `duration` | `number` | `1.3` | Length of the effect in seconds. The reverse runs a little faster. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| None of its own | The component has no controls. Wire Delete or Backspace to your own selection, as the demo does. |

### Accessibility

- The canvas is aria-hidden and only covers the content while the effect runs; the real DOM is back in place the moment it ends.
- Announce the result yourself (for example "2 conversations deleted" with an Undo button in a live region). The effect is visual only.
- Pointer events are not blocked on the rest of the page; disable the trigger while a transition runs to avoid double deletes.

### Motion

- Items fall along a logarithmic spiral. Points nearer the hole start earlier, so the inner edge falls faster than the outer one and rows stretch into arms.
- The rest of the content is lensed with the Einstein ring relation, so text near the hole bends and briefly mirrors around it.
- The hole opens with a slight overshoot, grows a little as it eats, then collapses and sends out one soft shockwave ring. Undo plays the same path backwards.
- With reduced motion, or without WebGL2, the items fade out in 200ms and fade back in on release.

### Responsive behavior

- Measures the wrapper at the start of every run, so it works at any width including 320px.
- The hole and lensing scale with device pixel ratio, capped at 2x.

### Performance

- Painting the wrapper to two textures takes a few milliseconds for a typical list; the shaders and context are prepared while the page is idle.
- Drawing is three passes on the GPU per frame (lensed content, a 5px mesh for the falling items, and the hole), well within a frame at 120Hz.
- Textures and buffers are released after each run; one WebGL2 context is kept per instance.

### Notes for AI

- Use for destructive or archive actions on a list, grid, or board where a moment of drama is welcome and undo is offered.
- Keep refs to the item elements (a Map keyed by id works well) and pass the selected ones to `swallow`. Remove the data only after the promise resolves.
- For undo, restore the data, then call `release` with the re-inserted elements in `useLayoutEffect` so they never flash. Pair the list with height exit and enter animations so gaps close and reopen smoothly.
- The painter handles backgrounds, borders, radii, text, images and inline SVG icons. Box shadows, gradients, pseudo elements and cross origin images are not painted.

### Related

- [Swipe actions](https://uiarc.dev/components/swipe-actions/markdown): Reveal row actions with a swipe, or from the same actions in a menu.
- [Toast stack](https://uiarc.dev/components/toast-stack/markdown): Stack short results at the edge until you reach for them.

### Also in loaders

- [Stretch refresh](https://uiarc.dev/components/stretch-refresh/markdown): Pull a feed down and a line stretches to tell you when to let go.
- [Morph loader](https://uiarc.dev/components/morph-loader/markdown): Tiny loaders that morph between shapes and fold into a check or a cross when done.
- [Skeleton morph](https://uiarc.dev/components/skeleton-morph/markdown): Loading skeletons that grow into the real content, block by block, instead of swapping.
- [Charge session](https://uiarc.dev/components/charge-session/markdown): An EV or device charging card. Energy packets flow from a charger along the cable into the battery pack, which fills toward a draggable charge limit. The charge curve tapers near full, and power, energy, time to limit and cost update live. Stop charging drains the flow.

### Guidance for AI tools

Black hole: A delete transition that pulls the chosen items into a tiny singularity while the rest of the list bends around it; undo spins them back out. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Charge session

> An EV or device charging card. Energy packets flow from a charger along the cable into the battery pack, which fills toward a draggable charge limit. The charge curve tapers near full, and power, energy, time to limit and cost update live. Stop charging drains the flow.

- Type: Component (special)
- Access: Arc Pro
- Page: https://uiarc.dev/components/charge-session
- Markdown: https://uiarc.dev/components/charge-session/markdown
- Source file: `registry/components/charge-session/charge-session.tsx`
- Dependencies: lucide-react
- Keywords: special, motion, progress, energy, new, ev charging, charging, battery, charge session, electric vehicle, charge limit, charge curve, time to full, kwh, cost, fleet, charger, power

### When to use

- An EV or fleet app that shows a live charging session with a charge limit.
- A charge point operator console where staff watch power, energy and cost for one bay.
- A product page that demonstrates how your charging network reports time to full and cost.

### When not to use

- Use usage-meter or progress for a static quota or a simple percentage.
- Use gauge for a single live reading without a session, curve or cost.
- Use a table or a chart block to compare many sessions at once.

### Installation

Charge session is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/charge-session
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { ChargeSession } from "@/components/arc/charge-session/charge-session";

export function DepotCharger() {
  return (
    <ChargeSession
      title="Bay 12, depot charger"
      location="North yard, 350 kW"
      capacity={98}
      maxPower={350}
      startCharge={22}
      defaultLimit={85}
      rate={0.38}
      currency="EUR"
      locale="de-DE"
      onLimitChange={limit => api.setChargeLimit("bay-12", limit)}
      onStateChange={(state, detail) => state === "stopped" && api.stopSession("bay-12", detail)}
    />
  );
}
```

### API reference

#### ChargeSession

A live charging session card for an EV or any device. Energy packets travel from a brushed metal charger along the cable and through the pack to the fill front, where each one lands. The pack fills toward a draggable charge limit, the charge curve tapers near full with the live point riding on it, and power, energy added, time to limit and cost roll every frame. Stop charging drains the flow: the power falls to zero, the last packets land and the point drops to the baseline.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` | `string` | `"Fast charger 4"` | Name of the charger or device, shown as the card heading. |
| `location` | `string` | `"Harbor Street hub, 150 kW"` | Secondary line under the title. Pass an empty string to hide it. |
| `capacity` | `number` | `77` | Usable battery capacity in kWh. Sets how fast the pack fills and how much energy each percent is worth. |
| `maxPower` | `number` | `150` | Peak charging power in kW, reached on the flat part of the curve. |
| `startCharge` | `number` | `34` | State of charge in percent when the session starts, and where Start new session returns to. |
| `defaultLimit` | `number` | `80` | Charge limit in percent to start with. The component owns it after mount; read it with onLimitChange. |
| `minLimit` | `number` | `50` | Lowest limit the marker can be set to, in percent. |
| `taperAt` | `number` | `50` | State of charge in percent where the power starts to taper toward full. |
| `rate` | `number` | `0.42` | Price per kWh in the session currency. |
| `currency` | `string` | `"USD"` | ISO 4217 currency code for the cost. |
| `locale` | `string` | `"en-US"` | Locale used to format the cost. |
| `speed` | `number` | `1` | Multiplies simulated time. At 1, one second on screen is forty seconds of charging. 0 holds the session still while the flow keeps moving. |
| `paused` | `boolean` | `false` | Holds the session and the flow on their current frame. The limit and the button still work. |
| `accent` | `string` | – | Any CSS color for the energy, the fill and the traveled curve. Defaults to the accent. |
| `onStateChange` | `(state: "charging" \| "stopped" \| "complete", detail: ChargeSessionDetail) => void` | – | Called when charging stops, resumes, reaches the limit or a new session starts, with the charge, energy, cost and limit at that moment. |
| `onLimitChange` | `(limit: number) => void` | – | Called with the new limit in percent when a drag or key press settles. |
| `label` | `string` | – | Accessible name of the card. Defaults to the title. |
| `className` | `string` | – | Class on the root element. |
| `style` | `CSSProperties` | – | Inline styles on the root element. |

### Accessibility

- The card is a labelled group with a real heading. Power, energy added, time to limit and cost are a description list, so each value is read with its name.
- The limit marker is a focusable role="slider" named Charge limit, with aria-valuetext such as Charge limit 80%, about 23 minutes to go. Arrows move it by 1%, Shift with an arrow or Page Up and Page Down by 10%, Home and End jump to the minimum and to 100%. The drag hint is linked with aria-describedby.
- Stopping, resuming, reaching the limit, starting a new session and a settled limit change are announced in a polite live region with the charge, energy and cost at that moment.
- The action button keeps one accessible label at a time (Stop charging, Resume charging, Start new session) and its width never changes.
- The scene and the curve plot are hidden from assistive technology; every value they show is also in the stats, the header or the slider.
- State never relies on color: the header pairs an icon with Charging, Stopped or Charged to limit, and time to limit reads Paused or Done.

### Motion

- One requestAnimationFrame loop advances the session and writes SVG attributes, CSS variables and text directly; React renders only when the session state changes.
- Packets move along an arc length table of the cable curve, so they travel at an even pace, ease out of the charger, glide through the nub and slow as they meet the fill front, where each landing briefly brightens the front.
- Power follows the charge curve times an availability level that ramps up on start and drains exponentially on stop, so the numbers, the LED, the cable core, the packet pace and the live point on the curve all fall away together.
- Dragging the limit is one to one with the pointer; the pill lifts slightly while held. Raising the limit after the pack is full resumes charging, lowering it below the charge completes the session.
- The loop stops offscreen, in background tabs, when paused, and once the flow has fully drained.
- With reduced motion the session holds still: packets sit at even spacing along the path to show direction, values are current, and stop, resume and the limit all update at once.

### Responsive behavior

- The scene is one SVG with a fixed aspect ratio that scales to any width, so the charger, cable and pack keep their proportions; the limit pill is HTML placed in container units, so its text and 44px touch target keep their real size.
- The curve stretches to its container with non scaling strokes; its labels and live point are HTML so they stay crisp and round.
- Above 640px the curve sits beside a two by two stats grid and the percentage grows to the display size. Below 420px padding tightens, the stats shrink one step and the action button spans the card.
- Dragging uses touch-action pan-y on the scene and the curve, so vertical page scroll still works on phones.

### Performance

- A frame evaluates the power curve, a 48 step time to limit integral and 18 packets, well under a millisecond.
- Every write goes through a cache, so unchanged attributes and text are never touched; pointer math reads the target rectangle once per press.
- No canvas, no layout reads in the loop, and the loop idles completely once the flow has drained.

### Notes for AI

- Use it for EV charging apps, fleet and depot dashboards, charge point operator consoles, or any device charging flow where time to full and cost matter.
- The session is simulated from capacity, maxPower, taperAt and rate. For a real session, map your live state of charge onto startCharge and keep speed low, or say clearly that the view is an estimate.
- Keep the title to the charger or vehicle name and put the site and peak power in location.
- Stopping in the demo is local; wire onStateChange to your backend before calling it a real stop.

### Related

- [Usage meter](https://uiarc.dev/components/usage-meter/markdown): Show what fills an allowance and how close it is to the limit.
- [Progress](https://uiarc.dev/components/progress/markdown): Show how much of a known task is complete.
- [Gauge](https://uiarc.dev/components/gauge/markdown): Show a value against a known range.
- [Slider](https://uiarc.dev/components/slider/markdown): Pick a value or a range on a track that follows your finger.

### Also in loaders

- [Stretch refresh](https://uiarc.dev/components/stretch-refresh/markdown): Pull a feed down and a line stretches to tell you when to let go.
- [Morph loader](https://uiarc.dev/components/morph-loader/markdown): Tiny loaders that morph between shapes and fold into a check or a cross when done.
- [Skeleton morph](https://uiarc.dev/components/skeleton-morph/markdown): Loading skeletons that grow into the real content, block by block, instead of swapping.
- [Black hole](https://uiarc.dev/components/black-hole/markdown): A delete transition that pulls the chosen items into a tiny singularity while the rest of the list bends around it; undo spins them back out.

### Guidance for AI tools

Charge session: An EV or device charging card. Energy packets flow from a charger along the cable into the battery pack, which fills toward a draggable charge limit. The charge curve tapers near full, and power, energy, time to limit and cost update live. Stop charging drains the flow. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Sticker peel

> Peel stickers off a surface with a real curl, move them around, and stick them back down.

- Type: Component (special)
- Access: Arc Pro
- Page: https://uiarc.dev/components/sticker-peel
- Markdown: https://uiarc.dev/components/sticker-peel/markdown
- Source file: `registry/components/sticker-peel/sticker-peel.tsx`
- Dependencies: motion
- Keywords: special, motion, new, sticker peel, peel effect, sticker drag, page curl, laptop stickers, draggable stickers, react sticker, peel off animation

### When to use

- A personal or team page where people arrange badges, achievements, or brand stickers.
- A launch or marketing moment that invites people to play with the product's marks.
- A reward screen where earned stickers are placed on a surface.

### When not to use

- Use reorderable-list or a sortable grid when the order of items carries meaning.
- Use note-stack for content people need to read and rearrange.
- Avoid it on dense work screens; it is a delight surface, not an input.

### Installation

Sticker peel is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/sticker-peel
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { useState } from "react";
import { StickerPeel } from "@/components/arc/sticker-peel/sticker-peel";
import type { StickerPlacement } from "@/components/arc/sticker-peel/sticker-peel";

const stickers = [
  { id: "ship", label: "Ship it sticker", shape: "pill" as const, x: .3, y: .35, rotate: -6, content: <span className="ship">Ship it</span> },
  { id: "hello", label: "Hello sticker", shape: "circle" as const, x: .68, y: .6, rotate: 8, content: <span className="hello">hello</span> },
];

export function Lid() {
  const [positions, setPositions] = useState<Record<string, StickerPlacement>>();
  return <StickerPeel className="lid" stickers={stickers} positions={positions} onPositionsChange={setPositions} label="Laptop lid" />;
}
```

### API reference

#### StickerPeel

A surface of stickers. Hovering lifts the nearest corner a few pixels, pulling folds the sticker back along a real fold with its backing showing, pulling far enough peels it off to carry around, and letting go settles it back down.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `stickers` (required) | `StickerPeelItem[]` | – | The stickers, each with an id, label, content, starting center (x and y from 0 to 1), optional rotate in degrees, and shape. |
| `positions` | `Record<string, StickerPlacement>` | – | Controlled placements by id. Each is { x, y, rotate } with x and y from 0 to 1. |
| `onPositionsChange` | `(positions: Record<string, StickerPlacement>) => void` | – | Called once a sticker settles somewhere new, with every placement. Works with or without positions. |
| `label` | `string` | `"Stickers"` | Accessible name of the surface. |
| `children` | `ReactNode` | – | Content drawn on the surface under the stickers. |
| `className` | `string` | – | Class on the surface. Give it a size and background here. |
| `style` | `CSSProperties` | – | Inline style on the surface. |

#### StickerPeelItem

One sticker.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `id` (required) | `string` | – | Stable id, used as the key in positions. |
| `label` (required) | `string` | – | Accessible name, such as "Arc logo sticker". |
| `content` (required) | `ReactNode` | – | The printed face inside the white die cut border. Give it a fixed size. |
| `x` (required) | `number` | – | Starting center across the surface, from 0 to 1. |
| `y` (required) | `number` | – | Starting center down the surface, from 0 to 1. |
| `rotate` | `number` | `0` | Starting rotation in degrees. |
| `shape` | `"circle" \| "rounded" \| "pill"` | `"rounded"` | Outline of the die cut. The peel starts from the real edge of this shape. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Tab | Moves between stickers. Leaving a sticker you are carrying sticks it down. |
| Enter / Space | Picks the focused sticker up, or sticks it down where it is. |
| Arrow keys | Moves a sticker you are carrying by 10px, or 40px with Shift. |
| Escape | Puts a carried sticker back where it was picked up. |

### Accessibility

- The surface is a labelled group; each sticker is a button with aria-roledescription="sticker", its label, and aria-pressed while carried.
- A visually hidden description explains the keyboard path, and a polite status region announces peeled off, picked up, stuck down, and put back.
- Sticker artwork is aria-hidden; the label carries the meaning.
- Pointer focus draws no ring; keyboard focus shows Arc's shared focus ring. The lift and shadow of a carried sticker show which one is active.

### Motion

- The peel is a real fold: the pulled part is mirrored across the fold line with clip-path and foreshortened a touch, showing a plain paper backing with one soft shade at the bend and a light shadow that always falls downward.
- Circles peel from the point of the rim nearest the pointer; rounded shapes and pills peel from a corner along its diagonal. The fold may lean at most 35 degrees, so it is always a short, clean corner.
- Hovering with a mouse lifts the nearest corner a few pixels past the outline. Moving to another corner lays the first one flat before lifting the next.
- All springs are critically damped: the paper trails the finger slightly and settles without overshoot, bounce, or swing.
- It comes off once the fold passes the middle, sooner on a quick tug, or once the hand has clearly carried it away. It then rises 3% with a soft shadow and follows the hand at its own angle.
- Dropping lands it exactly where it is on screen and the shadow fades in 200ms. Grabbing it again while it settles catches it in place.
- Reduced motion skips the peel and hover lift; pressing picks the sticker up directly and it follows the pointer 1:1.

### Responsive behavior

- Placements are fractions of the surface, so the arrangement scales with its container and survives resizes.
- Touch drags use pointer capture with touch-action none on stickers only, so the page still scrolls from the surface.
- Carried stickers rubber-band at the surface edges and are clamped inside on drop, accounting for their angle.

### Performance

- Peel geometry is written straight to clip-path and transform on three elements per sticker from motion value events, with no React render per frame.
- Body movement and lift are motion values on transform only; nothing runs per frame while stickers are at rest.

### Notes for AI

- Choose it for one playful, tactile moment: a profile page, a launch page, a team wall, or a collectible badge shelf.
- Give each sticker content a fixed size; the die cut border and shape are added for you.
- Store onPositionsChange output to persist the arrangement, and pass it back as positions.
- Changing positions from outside, such as a reset, glides each sticker to its new spot.
- Keep it under about a dozen stickers so the surface stays readable.

### Related

- [Holo card](https://uiarc.dev/components/holo-card/markdown): A member card that tilts toward you with a holographic foil and flips to its back.

### Also in playful

- [Ticket tear](https://uiarc.dev/components/ticket-tear/markdown): Pull a ticket stub and it tears along the perforation hole by hole, then drops away.
- [Page curl](https://uiarc.dev/components/page-curl/markdown): A small magazine you read by dragging page corners, with a real fold, lit curl, and flick to turn.
- [Orbit logos](https://uiarc.dev/components/orbit-logos/markdown): An integrations showcase with brand logos orbiting your product mark on tilted rings. Hover or focus one to rest the orbit, draw a connection, and see what it does.
- [Prize wheel](https://uiarc.dev/components/prize-wheel/markdown): A referral or promo prize wheel you flick to spin, with real angular momentum, a flexible pointer that ticks against each peg, weighted segments set by the host, a slow suspenseful settle, and the won segment lifting into a reward card with a copyable code.

### Guidance for AI tools

Sticker peel: Peel stickers off a surface with a real curl, move them around, and stick them back down. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Ticket tear

> Pull a ticket stub and it tears along the perforation hole by hole, then drops away.

- Type: Component (special)
- Access: Arc Pro
- Page: https://uiarc.dev/components/ticket-tear
- Markdown: https://uiarc.dev/components/ticket-tear/markdown
- Source file: `registry/components/ticket-tear/ticket-tear.tsx`
- Dependencies: motion
- Keywords: special, gesture, ticket, new, ticket tear, tear off stub, perforated ticket, event ticket, boarding pass, coupon tear, react ticket, tear animation

### When to use

- Event tickets, boarding passes, and coupons that are used once.
- A playful confirmation step where tearing means committing.

### When not to use

- Use hold-to-confirm or a dialog for destructive actions that need clear wording.
- Use a plain card for tickets that are only displayed, not redeemed.

### Installation

Ticket tear is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/ticket-tear
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { TicketTear } from "@/components/arc/ticket-tear/ticket-tear";

export function Ticket() {
  const [torn, setTorn] = useState(false);
  return (
    <TicketTear torn={torn} onTornChange={setTorn} label="Tear off stub to check in"
      stub={<div className="stub">Row F, seat 12</div>}>
      <div className="ticket">
        <p>Arc Conf</p>
        <p>Teatro Tivoli, Lisbon</p>
      </div>
    </TicketTear>
  );
}
```

### API reference

#### TicketTear

An event ticket with a perforated stub. Pulling the stub rips it along the dotted line from the top with ragged, fibrous edges; torn through or flicked, the rip races to the bottom and the stub peels away with a spin.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` (required) | `ReactNode` | – | The main ticket body. |
| `stub` (required) | `ReactNode` | – | The stub right of the perforation. |
| `torn` | `boolean` | – | Controlled torn state. Setting it back to false puts a fresh stub on; setting it to true tears it off. |
| `defaultTorn` | `boolean` | `false` | Initial state when uncontrolled. |
| `onTornChange` | `(torn: boolean) => void` | – | Called once the stub comes off. |
| `stubWidth` | `number` | `104` | Stub width in px. |
| `label` | `string` | `"Tear off stub"` | Accessible name of the stub control. |
| `className` | `string` | – | Extra class on the root. |
| `style` | `CSSProperties` | – | Inline styles on the root. Set --ticket-paper to change the paper color. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Tab | Focuses the stub. |
| Enter / Space | Tears the stub all the way and drops it. |

### Accessibility

- The stub is role="button" with the label as its name.
- The flap copy of the stub used for the bend is aria-hidden, so the stub is read once.
- A polite status announces "Stub torn off".

### Motion

- Pulling down or away tears the perforation from the top, tracking the pointer directly; the tear only grows, like real paper.
- The edge passes through the center of each hole and wanders between them, coarse and fine, with loose paper fibers just past it on both sides.
- The loose flap follows the pull on a spring, so it has weight, and springs most of the way back when released mid-tear.
- Enter, Space or the torn prop rip the rest on their own, accelerating like a perforation that has started to give; a flick finishes it even faster.
- Freed, the stub pops up a hair, falls with gravity, drifts with the release speed, spins on a spring, and fades in about half a second.
- Touch devices get a tiny vibration as the tear crosses each hole, where supported.
- Reduced motion removes the bend, the fibers and the fall; the stub fades out.

### Responsive behavior

- The ticket fills its width; the stub keeps a fixed width and the body shrinks, down to 320px screens.
- Pointer capture keeps the tear tracking outside the stub, and touch-action is disabled on the stub only.

### Performance

- The tear is clip-path polygons driven by motion values; React does not re-render while dragging.
- Notches and holes are CSS masks, so the paper stays one element per piece.

### Notes for AI

- Choose it for check-in, redeeming a pass, or any one-time confirmation that should feel final.
- Keep the stub content short: a seat, a gate, a code.
- Control torn to reset it (a New ticket button) or to tear it from a server event.

### Related

- [Hold to confirm](https://uiarc.dev/components/hold-to-confirm/markdown): Confirm a destructive action by holding, not tapping.
- [Swipe actions](https://uiarc.dev/components/swipe-actions/markdown): Reveal row actions with a swipe, or from the same actions in a menu.
- [Sticker peel](https://uiarc.dev/components/sticker-peel/markdown): Peel stickers off a surface with a real curl, move them around, and stick them back down.

### Also in playful

- [Page curl](https://uiarc.dev/components/page-curl/markdown): A small magazine you read by dragging page corners, with a real fold, lit curl, and flick to turn.
- [Orbit logos](https://uiarc.dev/components/orbit-logos/markdown): An integrations showcase with brand logos orbiting your product mark on tilted rings. Hover or focus one to rest the orbit, draw a connection, and see what it does.
- [Prize wheel](https://uiarc.dev/components/prize-wheel/markdown): A referral or promo prize wheel you flick to spin, with real angular momentum, a flexible pointer that ticks against each peg, weighted segments set by the host, a slow suspenseful settle, and the won segment lifting into a reward card with a copyable code.

### Guidance for AI tools

Ticket tear: Pull a ticket stub and it tears along the perforation hole by hole, then drops away. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Page curl

> A small magazine you read by dragging page corners, with a real fold, lit curl, and flick to turn.

- Type: Component (special)
- Access: Arc Pro
- Page: https://uiarc.dev/components/page-curl
- Markdown: https://uiarc.dev/components/page-curl/markdown
- Source file: `registry/components/page-curl/page-curl.tsx`
- Dependencies: motion
- Keywords: special, gesture, book, new, page curl, page flip, flipbook, turn page animation, book component, magazine viewer, react page flip, page turn

### When to use

- Editorial and brand showcases where paper is part of the story.
- Menus, catalogs, and yearbooks with a handful of spreads.

### When not to use

- Use carousel or a scrolling page for long content or content people search.
- Use a document viewer for dense text that needs zoom and selection.

### Installation

Page curl is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/page-curl
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { PageCurl } from "@/components/arc/page-curl/page-curl";

export function Lookbook() {
  return (
    <PageCurl
      label="Autumn lookbook"
      style={{ width: 540 }}
      pages={[<Cover key="cover" />, <Intro key="intro" />, <Plate key="plate" />]}
    />
  );
}
```

### API reference

#### PageCurl

A small book or magazine that opens on its cover. On first view the cover corner curls up and settles next to a "Drag the corner" hint. Tap the right page to go forward and the left page to go back, or drag a page: it folds along a line that follows the pointer, showing its back, a lit curl, and a shadow on the page below. A page count with previous and next controls sits underneath.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `pages` (required) | `ReactNode[]` | – | Page contents in reading order. Page one is the cover and sits alone on the right. |
| `spread` | `number` | – | Controlled spread. 0 shows the cover; spread n shows pages 2n and 2n + 1 (one-based). |
| `defaultSpread` | `number` | `0` | Initial spread when uncontrolled. |
| `onSpreadChange` | `(spread: number) => void` | – | Called when a page finishes turning. |
| `pageAspect` | `number` | `0.72` | Page width divided by height. |
| `label` | `string` | `"Book"` | Accessible name of the book. |
| `tease` | `boolean` | `true` | Curls the cover corner once when the book first comes into view, and a little on hover until the first turn. |
| `hint` | `ReactNode \| null` | `"Drag the corner"` | Hint under the lower outer corner, shown until the first interaction. Pass null to hide it. |
| `controls` | `boolean` | `true` | Shows the page count with previous and next buttons under the book. |
| `className` | `string` | – | Extra class on the root. Its width holds two pages side by side. |
| `style` | `CSSProperties` | – | Inline styles on the root. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| ArrowRight / PageDown | Turns to the next spread. |
| ArrowLeft / PageUp | Turns to the previous spread. |
| Tab | Moves from the book to the previous and next page buttons. |

### Accessibility

- The book is a focusable group with aria-roledescription="book" and the label as its name.
- A polite status reads the visible pages, such as "Page 2 and 3 of 8".
- Only the resting pages are in the accessibility tree; the turning copies are aria-hidden.
- Previous and next are real buttons with labels and disable at the covers. The visible count and the hint are decorative duplicates of the status.

### Motion

- The fold line is the perpendicular bisector between the corner and the pointer, so the page follows the finger from where it was grabbed.
- The corner is held within a page width of the spine, like paper bound on one side.
- The flap is a mirror of the sheet across the fold with a lit curl at the crease; the page below gets a soft shadow at the fold.
- Release projects the pointer's momentum: past the middle or a flick turns the page on a spring that keeps the release velocity; otherwise it lays back down.
- The first time the book is mostly in view, the cover corner lifts about a quarter of the page on a soft spring, holds, and lays back down. Until the first turn, entering the book with a mouse repeats it at half the size, at most every 2.5 seconds.
- Hovering a corner lifts it. Hovering a page shows a chevron at its outer edge for the direction a tap turns. Taps, arrow keys, and the buttons turn along a lifted arc.
- The hint fades out for good after the first drag, tap, key, or button press.
- The closed book slides to center on its cover and back cover.
- Reduced motion swaps spreads without the curl and skips the tease.

### Responsive behavior

- Page size derives from the root width, so a 288px wide book still shows two readable pages.
- Each page is one tap and drag target with touch-action pan-y, so vertical swipes still scroll the page on touch.

### Performance

- Fold geometry is computed once per frame from two motion values; clip paths and a matrix update without React renders.
- Up to three copies of a page render while it turns; only the resting spread renders otherwise.

### Notes for AI

- Choose it for short, visual sequences: lookbooks, menus, reports, zines, and portfolios.
- Keep pages simple and fixed in size; each page renders into a slot of the same width and aspect ratio.
- An even number of pages ends on a back cover alone on the left.
- Make page one a real cover with a title, so the closed book reads as something to open.

### Related

- [Cover flow](https://uiarc.dev/components/cover-flow/markdown): A depth rail of images you can throw, with soft grounded shadows and a quiet reflection.
- [Carousel](https://uiarc.dev/components/carousel/markdown): Browse a row of slides by dragging, flicking, or arrowing through them.
- [Lightbox gallery](https://uiarc.dev/components/lightbox-gallery/markdown): A masonry grid where photos zoom from their slot into a viewer you can swipe, pinch, and drag away.

### Also in playful

- [Sticker peel](https://uiarc.dev/components/sticker-peel/markdown): Peel stickers off a surface with a real curl, move them around, and stick them back down.
- [Ticket tear](https://uiarc.dev/components/ticket-tear/markdown): Pull a ticket stub and it tears along the perforation hole by hole, then drops away.
- [Orbit logos](https://uiarc.dev/components/orbit-logos/markdown): An integrations showcase with brand logos orbiting your product mark on tilted rings. Hover or focus one to rest the orbit, draw a connection, and see what it does.
- [Prize wheel](https://uiarc.dev/components/prize-wheel/markdown): A referral or promo prize wheel you flick to spin, with real angular momentum, a flexible pointer that ticks against each peg, weighted segments set by the host, a slow suspenseful settle, and the won segment lifting into a reward card with a copyable code.

### Guidance for AI tools

Page curl: A small magazine you read by dragging page corners, with a real fold, lit curl, and flick to turn. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Orbit logos

> An integrations showcase with brand logos orbiting your product mark on tilted rings. Hover or focus one to rest the orbit, draw a connection, and see what it does.

- Type: Component (special)
- Access: Arc Pro
- Page: https://uiarc.dev/components/orbit-logos
- Markdown: https://uiarc.dev/components/orbit-logos/markdown
- Source file: `registry/components/orbit-logos/orbit-logos.tsx`
- Keywords: special, motion, integrations, logos, new, orbit logos, integration hero, logo orbit, orbiting logos, integrations page, connect apps, ecosystem, partners, tech stack

### When to use

- An integrations or ecosystem hero on a marketing site.
- An integrations settings screen where people browse, read about, and connect tools.
- A launch page showing everything a product plugs into.

### When not to use

- Use a logo marquee for a long list of customer logos.
- Use a searchable grid or table for catalogs larger than about twenty integrations.

### Installation

Orbit logos is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/orbit-logos
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { OrbitLogos } from "@/components/arc/orbit-logos/orbit-logos";

// Path data from Simple Icons (CC0) follows the text color; image URLs keep full brand color.
const integrations = [
  { name: "Stripe", icon: "/logos/stripe-color.svg", category: "Payments", description: "Starts trials and bills usage", href: "https://docs.stripe.com" },
  { name: "Vercel", icon: "m12 1.608 12 20.784H0Z", category: "Dev", description: "Comments preview links on builds", connected: true },
  { name: "Slack", icon: "/logos/slack-color.svg", category: "Comms", description: "Posts deploy alerts to your channels" },
];

export function Integrations() {
  return <OrbitLogos
    logos={integrations}
    center={<ProductMark />}
    onConnect={logo => api.connect(logo.id ?? logo.name)}
  />;
}
```

### API reference

#### OrbitLogos

An integrations orbit: your product mark at the center with brand logos on two flat rings that turn slowly and hold still whenever the pointer or keyboard focus is inside. Category chips turn the matching logos toward the detail side and dim the rest. Choosing a logo springs its ring so the logo glides to a fixed focus spot, draws an accent connector from the center, and morphs a detail card out of the chip with a description, status, a Connect action, Docs, and previous and next.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `logos` (required) | `{ id?: string; name: string; icon: string \| ReactNode; color?: string; category?: string; description?: string; connected?: boolean; href?: string }[]` | – | Logos to show. icon is SVG path data on a 24 by 24 viewBox (the Simple Icons format) painted in color, an image URL for a full color mark, or any ReactNode. Leave color out for black and white brands so the mark follows the text color. category builds the filter chips, description is the line in the card, connected sets the starting status, and href adds a Docs link. |
| `center` | `ReactNode` | – | Content of the center disc, such as your product mark. Defaults to a simple mark in the accent color. |
| `onSelect` | `(logo: OrbitLogo \| null, index: number) => void` | – | Called when a logo opens, when previous or next steps to another, and with null and -1 when the card closes. |
| `onConnect` | `(logo, index) => void \| Promise<unknown>` | – | Called by the Connect button. Return a promise to hold the connecting state until it settles; a rejection shows Try again. Without a promise the card simulates a short connection. |
| `defaultSelected` | `string \| null` | `null` | Id (or name) of the logo open on first render. |
| `selected` | `string \| null` | – | Controlled id (or name) of the open logo; null closes the card. Pair it with onSelect. |
| `speed` | `number` | `1` | Multiplies the rotation speed. At 1 the inner ring turns once every 64s and the outer ring every 88s. 0 holds the orbit still. |
| `paused` | `boolean` | `false` | Holds the orbit still, for a page level motion control. |
| `allLabel` | `string` | `"All"` | Label of the first category chip. |
| `label` | `string` | `"Integrations"` | Accessible name of the logo list and the idle panel title. |
| `className` | `string` | – | Extra class on the root. |
| `style` | `CSSProperties` | – | Inline styles on the root. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Tab | Moves into the category chips, then to one logo in the orbit, then into the card. The orbit holds still while focus is inside. |
| Arrow keys | Step to the previous or next logo in the current category. With a card open, the card and the ring follow. |
| Home / End | Jump to the first or last logo in the current category. |
| Enter / Space | Opens the focused logo, or closes it if it is already open. |
| Escape | Closes the card and returns focus to its logo. |

### Accessibility

- Logos are a labelled list of toggle buttons with aria-pressed; each name includes the category and whether it is connected.
- Only one logo is in the tab order (roving tabindex), so the orbit is a single stop between the chips and the card.
- The card is a labelled region with real buttons and a Docs link; opening, stepping, and filtering are announced in a polite live region.
- Connected status is shown as text and an icon in the card, not by the green dot alone.
- Pointer focus draws no ring; keyboard focus shows Arc's shared focus ring. Focus shows as the lifted chip and its name tag.

### Motion

- One rAF loop writes chip translations and the connector; React does not render per frame, and the loop stops when everything is at rest, off screen, or the tab is hidden.
- The turn eases to rest on a critically damped spring whenever the pointer or focus enters, a category is picked, or a card is open, so nothing moves while you aim.
- Opening a logo springs its ring the short way to the focus spot, with a touch of overshoot. When an outer logo parks, the inner ring steps aside so the connector stays clear.
- The card morphs out of the chip: it starts at the chip's box as a circle and springs to its own box, then its content fades in. Previous and next slide the content in the direction of travel.
- The category highlight is a shared layout pill on the morph spring; chips scale and dim on CSS springs.
- Reduced motion stops the rotation, places rings and the connector at once, and skips the morph and slides.

### Responsive behavior

- From 760px wide the orbit sits beside the detail panel and the chosen logo parks on the right; below that the card sits under the orbit and the logo parks at the bottom.
- Chips are 48 to 56px on desktop and 44px on phones, and the orbit fills the width up to 460px.
- Category chips scroll sideways in one row on narrow screens.
- Name tags only appear on hover or keyboard focus, never on touch.

### Performance

- Positions are transform only writes from a single rAF loop that sleeps when nothing moves.
- Visual states (hover, dim, selected) are CSS transitions on each chip's face, not per frame work.
- Image marks are plain img elements, so each SVG file is fetched once and cached.

### Notes for AI

- Use it as the hero of an integrations page or an in-app integrations screen, with your product mark in the center.
- Ten to sixteen logos read best across two rings. Give every logo a category so the filter chips appear, and a one line description.
- Wire onConnect to your real flow and return its promise; the card shows Connecting until it settles and Try again if it rejects.
- Brand marks are sample content. Show only integrations that exist and follow each brand's trademark rules.

### Related

- [Logo marquee](https://uiarc.dev/components/blocks/logo-marquee/markdown): A quiet, continuously moving row of brand marks with a pause control.
- [Hover card](https://uiarc.dev/components/hover-card/markdown): Preview a person or link on hover or focus without leaving the page.
- [Orbit menu](https://uiarc.dev/components/orbit-menu/markdown): Hold a button and its actions orbit out, ready to pick with a drag.
- [Chip group](https://uiarc.dev/components/chip-group/markdown): Filter by a few facets with chips that morph as you pick them.

### Also in playful

- [Sticker peel](https://uiarc.dev/components/sticker-peel/markdown): Peel stickers off a surface with a real curl, move them around, and stick them back down.
- [Ticket tear](https://uiarc.dev/components/ticket-tear/markdown): Pull a ticket stub and it tears along the perforation hole by hole, then drops away.
- [Page curl](https://uiarc.dev/components/page-curl/markdown): A small magazine you read by dragging page corners, with a real fold, lit curl, and flick to turn.
- [Prize wheel](https://uiarc.dev/components/prize-wheel/markdown): A referral or promo prize wheel you flick to spin, with real angular momentum, a flexible pointer that ticks against each peg, weighted segments set by the host, a slow suspenseful settle, and the won segment lifting into a reward card with a copyable code.

### Guidance for AI tools

Orbit logos: An integrations showcase with brand logos orbiting your product mark on tilted rings. Hover or focus one to rest the orbit, draw a connection, and see what it does. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Prize wheel

> A referral or promo prize wheel you flick to spin, with real angular momentum, a flexible pointer that ticks against each peg, weighted segments set by the host, a slow suspenseful settle, and the won segment lifting into a reward card with a copyable code.

- Type: Component (special)
- Access: Arc Pro
- Page: https://uiarc.dev/components/prize-wheel
- Markdown: https://uiarc.dev/components/prize-wheel/markdown
- Source file: `registry/components/prize-wheel/prize-wheel.tsx`
- Dependencies: motion, lucide-react
- Keywords: special, gesture, physics, new, prize wheel, spin the wheel, wheel of fortune, referral, promo code, coupon, reward, giveaway, gamification, spinner, momentum

### When to use

- A referral or launch page that rewards a signup with a discount code.
- An in-product moment that grants one of several perks, such as a milestone reward.

### When not to use

- Use a plain coupon card or copy button when everyone gets the same reward.
- Avoid it in serious flows such as billing or checkout, where chance feels out of place.

### Installation

Prize wheel is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/prize-wheel
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { PrizeWheel } from "@/components/arc/prize-wheel/prize-wheel";

export function ReferralReward({ drawnIndex }: { drawnIndex: number }) {
  return <PrizeWheel
    once
    pickWinner={() => drawnIndex}
    segments={[
      { label: "10% off", detail: "Off your first year", code: "REF-10OFF", weight: 40 },
      { label: "Free month", detail: "One month on us", code: "REF-MONTH", weight: 25 },
      { label: "20% off", detail: "Off your first year", code: "REF-20OFF", weight: 20 },
      { label: "Extra seat", detail: "One more teammate for a year", code: "REF-SEAT", weight: 14 },
      { label: "Lifetime", detail: "Pro for life", code: "REF-LIFE", weight: 1, featured: true },
    ]}
    onResult={segment => console.log("won", segment.label)}
  />;
}
```

### API reference

#### PrizeWheel

A promo or referral prize wheel with real momentum. Flick the wheel and it keeps the angular velocity you gave it, or hold the metal Spin hub to wind the wheel back while an accent ring fills, then let go to throw it. A flexible pointer bends against every peg and snaps back with a small wobble, the wheel slows into a long, suspenseful settle, and it lands on a segment drawn by weight. The won segment fills with the accent and lifts into a reward card with a copyable code, while the odds list beside the wheel shows every prize with its chance.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `segments` | `{ id?: string; label: string; detail?: string; code?: string; weight?: number; featured?: boolean }[]` | `Eight launch rewards` | Prizes clockwise from the top, two to twelve. label is drawn on the wheel (keep it to about 14 characters), detail and code appear in the reward card, weight is the relative chance (defaults to 1), and featured marks the rare top prize with the accent. |
| `title` | `string` | `"Spin for a reward"` | Heading beside the wheel before the first spin. |
| `description` | `string` | `"Every spin wins something. Your code works at checkout."` | One line under the heading. |
| `labels` | `{ spin?; again?; done?; copy?; copied?; copyFailed?; odds?; hint?; weak? }` | – | Visible words for localization: the hub label, Spin again, the locked hub label, the copy button states, the odds heading, the gesture hint, and the hint after a flick that was too slow. |
| `pickWinner` | `(segments) => number` | – | Returns the winning index when a spin starts, such as a result your server already drew. Without it the wheel draws by weight in the browser, which suits a demo but not a real prize. |
| `onResult` | `(segment, index) => void` | – | Called once when the wheel comes to rest on a prize. |
| `once` | `boolean` | `false` | Allows a single spin. The wheel locks on the prize, the hub reads Claimed, and Spin again is hidden. |
| `sizing` | `"equal" \| "weight"` | `"equal"` | Equal slices, or slice angles proportional to weight so the wheel itself shows the odds. Slices too thin for a label drop it; the odds list still names them. |
| `showOdds` | `boolean` | `true` | Shows the list of prizes with their chance beside the wheel. |
| `speed` | `number` | `1` | Multiplies the slow idle drift before a spin. 0 holds the wheel still. |
| `paused` | `boolean` | `false` | Holds the idle drift. A spin the visitor starts still runs to the end. |
| `accent` | `string` | – | Color of the pointer, the featured prize, the charge ring, and the won segment. Defaults to the accent token. |
| `label` | `string` | `"Prize wheel"` | Accessible name of the component. The wheel image adds every prize and its chance. |
| `className` | `string` | – | Extra class on the root. |
| `style` | `CSSProperties` | – | Inline styles on the root. |

### Accessibility

- The Spin hub is a real button with a specific name. Enter or Space pressed and held winds the wheel up; releasing spins it. A screen reader activation without a press spins at a medium strength.
- The wheel is one element with role="img" whose label lists every prize with its chance, so the odds are never visual only.
- A polite live region announces Spinning, the prize won with its code spelled out, and copy success or failure.
- While a spin runs the hub is aria-disabled instead of disabled, so focus stays on it. The hidden reward card is inert until a prize lands.
- The winner is never shown by color alone: the card names it, the odds row lights up, and the announcement repeats it.
- Pointer focus draws no ring; keyboard focus shows Arc's shared focus ring.

### Motion

- One rAF loop writes the wheel rotation, the pointer rotation, and the charge ring straight to the DOM, only when a value changed; React renders only when a spin starts and when it lands.
- The wheel rotates as a composited HTML layer, so the SVG face never repaints per frame. A static metal sheen sits above it so the light stays still while the wheel turns under it.
- A drag follows the pointer angle around the hub; the release velocity from the last 100ms becomes the spin. The winner is drawn by weight, then the travel is chosen as the landing spot nearest the distance that velocity would naturally carry, so the wheel leaves your hand at the speed you threw it.
- The spin follows 1 - (1 - t)^3: velocity decays smoothly with no seam and the last turn crawls past the final pegs.
- The pointer is a stiff, lightly damped spring that collides with the pegs as a tapered capsule: it only moves when a peg actually touches it, bends about 30 degrees until the peg clears its tip, then snaps back with a short wobble. The collision runs in substeps that follow the wheel, so no peg skips through it at full speed; fast spins rattle it and the settle ticks peg by peg.
- A spin thrown from the hub or Spin again builds its speed over a few frames instead of jumping to full speed, and winding up eases in and out. A flick keeps the exact speed of your hand.
- The reward card flies from the segment under the pointer to its place on a spring with a little life, one continuous movement.
- The loop stops when idle, off screen, and in hidden tabs. Reduced motion removes the drift, the pointer wobble, and the flight: a spin lands at once on the prize and the card appears in place.

### Responsive behavior

- The wheel is an SVG viewBox inside a square stage, so the face, pegs, and pointer scale to any width with crisp hairlines.
- Container queries place the reward panel beside the wheel from 736px and below it on narrower layouts, where the odds list folds into two columns.
- The wheel captures touch for dragging while the rest of the component scrolls normally.

### Performance

- About sixty static SVG elements rotate as one composited layer; nothing is measured per frame.
- The pointer spring runs four small substeps per frame and stops as soon as it rests.

### Notes for AI

- Use it for a referral reward, a launch promo, or a signup incentive where the moment itself is the point.
- For real prizes, draw the result on the server and pass pickWinner so the browser cannot choose its own reward. Pair it with once.
- Keep labels short and the segment count between six and ten. Mark only the rarest prize as featured.
- Keep showOdds on for promotions that must disclose chances.

### Related

- [Slot text](https://uiarc.dev/components/slot-text/markdown): Text and numbers that spin into their new value on staggered slot machine reels.
- [Wallet stack](https://uiarc.dev/components/wallet-stack/markdown): Fan a stack of cards and lift one out to see its activity.
- [Copy button](https://uiarc.dev/components/copy-button/markdown): Copy a value with immediate confirmation.

### Also in playful

- [Sticker peel](https://uiarc.dev/components/sticker-peel/markdown): Peel stickers off a surface with a real curl, move them around, and stick them back down.
- [Ticket tear](https://uiarc.dev/components/ticket-tear/markdown): Pull a ticket stub and it tears along the perforation hole by hole, then drops away.
- [Page curl](https://uiarc.dev/components/page-curl/markdown): A small magazine you read by dragging page corners, with a real fold, lit curl, and flick to turn.
- [Orbit logos](https://uiarc.dev/components/orbit-logos/markdown): An integrations showcase with brand logos orbiting your product mark on tilted rings. Hover or focus one to rest the orbit, draw a connection, and see what it does.

### Guidance for AI tools

Prize wheel: A referral or promo prize wheel you flick to spin, with real angular momentum, a flexible pointer that ticks against each peg, weighted segments set by the host, a slow suspenseful settle, and the won segment lifting into a reward card with a copyable code. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Dot grid

> A dot field that bulges around the cursor like a lens and ripples from every click.

- Type: Component (special)
- Access: Arc Pro
- Page: https://uiarc.dev/components/dot-grid
- Markdown: https://uiarc.dev/components/dot-grid/markdown
- Source file: `registry/components/dot-grid/dot-grid.tsx`
- Dependencies: motion
- Keywords: special, motion, new, dot grid, interactive dot background, dot field, magnetic dots, ripple background, hero background, canvas dots, lens effect

### When to use

- A landing page hero that should feel alive without video.
- A background for an empty state, a sign in panel, or a launch countdown.
- A playful section divider people can poke at.

### When not to use

- Behind dense text or data; the moving dots compete with reading.
- Use a static CSS dot pattern when no interaction is wanted.
- Avoid stacking several on one screen; one reactive background is enough.

### Installation

Dot grid is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/dot-grid
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { DotGrid } from "@/components/arc/dot-grid/dot-grid";

export function Hero() {
  return (
    <DotGrid style={{ height: 480 }}>
      <h1>Interfaces with a pulse</h1>
    </DotGrid>
  );
}
```

### API reference

#### DotGrid

A canvas field of dots that bulge away from the pointer like a lens, wobble back on a spring, and ripple outward from every click. Content placed inside sits on top and stays interactive.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `gap` | `number` | `22` | Distance between dots in px. Lower is denser. |
| `dotSize` | `number` | `1.4` | Dot radius in px at rest. |
| `radius` | `number` | `150` | Lens radius around the pointer in px. |
| `strength` | `number` | `16` | How far dots are pushed at the strongest point of the lens, in px. |
| `ripple` | `boolean` | `true` | Clicks and taps send a ripple through the field. |
| `fade` | `boolean` | `true` | Fades the field toward its edges. |
| `color` | `string` | – | Dot color at rest. Defaults to the strong border token. |
| `activeColor` | `string` | – | Color dots take under the lens and in ripples. Defaults to the accent token. |
| `children` | `ReactNode` | – | Content drawn over the field, such as a hero headline. |
| `className` | `string` | – | Class on the root. Give it a height or let children size it. |
| `style` | `CSSProperties` | – | Inline style on the root. |

### Accessibility

- The canvas is aria-hidden and not focusable; the field is decoration and adds nothing to the reading order.
- Children render as normal DOM above the canvas, so links and buttons keep their semantics and pointer events.
- With reduced motion dots never move; the lens only tints dots near the pointer and clicks do not ripple.

### Motion

- Each dot rides its own damped spring toward the lens and ripple offsets, so the field wobbles and settles instead of snapping.
- The lens peaks a third of the way out and fades to nothing at its rim, and it trails the pointer slightly and fades in and out.
- Ripples travel at about 620px per second, fade over 1.5s, and up to six can overlap.
- Dots under the lens and in a ripple grow and take the active color.

### Responsive behavior

- The grid rebuilds on resize and centers itself in the box.
- On touch screens the lens appears only while a finger is down, and every tap ripples.
- Device pixel ratio is capped at 2.

### Performance

- Dot state lives in typed arrays; resting dots draw in a single path fill.
- The loop stops when the pointer leaves and all dots settle, and pauses when the field is off screen.
- A 720 by 420 field at gap 22 is about 650 dots; gap 14 is about 1,600.

### Notes for AI

- Choose it as a hero or section background that reacts to the visitor.
- Put the headline and actions inside as children; the field listens to the pointer across the whole root.
- Raise gap for large areas and low powered devices; 22 to 32 suits full width heroes.
- Pass color and activeColor to match a brand; any CSS color works, including var() values resolved on the root.

### Related

- [Stretch refresh](https://uiarc.dev/components/stretch-refresh/markdown): Pull a feed down and a line stretches to tell you when to let go.

### Also in cursor

- [Image trail](https://uiarc.dev/components/image-trail/markdown): Moving the pointer leaves a curated trail of photos that pop in, lean, and fade away.
- [Gravity well](https://uiarc.dev/components/gravity-well/markdown): A grid of tiles that bends toward the cursor like spacetime, with a click that sends a shockwave through it.
- [Ink fluid](https://uiarc.dev/components/ink-fluid/markdown): A real time fluid simulation behind your hero: the cursor stirs soft ink that swirls, settles and fades; calm when left alone.

### Guidance for AI tools

Dot grid: A dot field that bulges around the cursor like a lens and ripples from every click. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Image trail

> Moving the pointer leaves a curated trail of photos that pop in, lean, and fade away.

- Type: Component (special)
- Access: Arc Pro
- Page: https://uiarc.dev/components/image-trail
- Markdown: https://uiarc.dev/components/image-trail/markdown
- Source file: `registry/components/image-trail/image-trail.tsx`
- Dependencies: motion
- Keywords: special, media, cursor, new, image trail, cursor image trail, mouse trail photos, hover photo trail, portfolio hero effect, image cursor follow, react image trail

### When to use

- A portfolio or agency hero that should feel alive on first move.
- Travel, food, or product stories told through a sequence of photos.
- Launch pages that want an instantly playful surface.

### When not to use

- Use photo-grid or lightbox-gallery when people need to look at each photo.
- Use hover-image-list to preview one image per row in a list.
- Avoid it behind long text that people need to read.

### Installation

Image trail is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/image-trail
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { ImageTrail } from "@/components/arc/image-trail/image-trail";

const images = [
  { src: "/photos/tram.jpg", alt: "A yellow tram in Lisbon" },
  { src: "/photos/rooftops.jpg", alt: "Terracotta rooftops" },
  { src: "/photos/sea.jpg", alt: "The sea at dusk" },
];

export function Hero() {
  return (
    <ImageTrail images={images} style={{ height: 420 }}>
      <h1>Lisbon, in passing</h1>
    </ImageTrail>
  );
}
```

### API reference

#### ImageTrail

An area that leaves a trail of photos behind the pointer. Photos pop in at the pointer, lean toward the direction of travel, drift on with its momentum, and fade.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `images` (required) | `{ src: string; alt?: string }[]` | – | Photos shown in order along the trail. Pass small renditions; a photo is never shown larger than size. |
| `children` | `ReactNode` | – | Content laid over the trail, such as a headline. Links and buttons inside stay clickable. |
| `spacing` | `number` | `90` | Pointer travel between photos, in px. |
| `lifetime` | `number` | `700` | How long a photo stays before it fades, in ms. |
| `size` | `number` | `168` | Photo width in px. |
| `aspectRatio` | `number` | `4 / 5` | Photo width divided by height. |
| `maxTilt` | `number` | `10` | Largest lean in degrees at full pointer speed. |
| `poolSize` | `number` | `14` | How many photos can be on screen at once. |
| `intro` | `boolean` | `false` | Plays one short S-curve sweep of photos the first time the area scrolls into view, hinting at the effect. Skipped with reduced motion or once the pointer has moved in. |
| `disabled` | `boolean` | `false` | Stops new photos and gives touch scrolling back to the page. |
| `className` | `string` | – | Extra class on the root. Give the root a height. |
| `style` | `CSSProperties` | – | Inline styles on the root. |

### Accessibility

- Trail photos are decorative and aria-hidden; put anything people need in children.
- Children stay in normal reading order and remain interactive.
- The effect is pointer only and adds nothing a keyboard or screen reader user misses.

### Motion

- A new photo appears only after the pointer has travelled spacing px, and never faster than every 40ms, so the trail stays curated.
- Each photo enters on the shared spring curve from 60% scale, leans with horizontal speed plus a small fixed variation, then drifts along the pointer's path as it shrinks and fades.
- Photos are pooled DOM nodes animated with the Web Animations API on transform and opacity only.
- Reduced motion keeps the trail as a calm crossfade in place, with no scale, tilt, or drift, and wider spacing.

### Responsive behavior

- Works at any size; the demo drops to 360px tall and a smaller headline on phones.
- Touch drags draw the trail with the finger; taps do nothing.

### Performance

- A fixed pool of image nodes is reused, so a long trail never grows the DOM.
- Images are preloaded on mount. Animations run on the compositor through WAAPI.

### Notes for AI

- Choose it for portfolio, travel, or studio heroes where photos are the story.
- Pass 8 to 14 small images (about 384px wide) in a deliberate order; the trail shows them in sequence.
- Give the root a height. A white headline with mix-blend-mode: difference reads over the photos in both themes.
- The area sets touch-action: none so a finger drag draws the trail; keep it to a hero sized block, or set disabled on small screens if scrolling matters more.

### Related

- [Photo grid](https://uiarc.dev/components/photo-grid/markdown): Pinch through zoom levels and open any photo straight from its cell.
- [Lightbox gallery](https://uiarc.dev/components/lightbox-gallery/markdown): A masonry grid where photos zoom from their slot into a viewer you can swipe, pinch, and drag away.

### Also in cursor

- [Dot grid](https://uiarc.dev/components/dot-grid/markdown): A dot field that bulges around the cursor like a lens and ripples from every click.
- [Gravity well](https://uiarc.dev/components/gravity-well/markdown): A grid of tiles that bends toward the cursor like spacetime, with a click that sends a shockwave through it.
- [Ink fluid](https://uiarc.dev/components/ink-fluid/markdown): A real time fluid simulation behind your hero: the cursor stirs soft ink that swirls, settles and fades; calm when left alone.

### Guidance for AI tools

Image trail: Moving the pointer leaves a curated trail of photos that pop in, lean, and fade away. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Gravity well

> A grid of tiles that bends toward the cursor like spacetime, with a click that sends a shockwave through it.

- Type: Component (special)
- Access: Arc Pro
- Page: https://uiarc.dev/components/gravity-well
- Markdown: https://uiarc.dev/components/gravity-well/markdown
- Source file: `registry/components/gravity-well/gravity-well.tsx`
- Dependencies: motion
- Keywords: special, grid, physics, new, gravity, spacetime, magnetic, lens, shockwave, ripple, tiles, springs

### When to use

- A team, customer, or moodboard wall where playfulness is the point.
- Landing page sections that show breadth: many logos, avatars, or photos at once.

### When not to use

- Grids people must scan or click precisely, like file pickers; use a plain grid.
- Large collections; use infinite-moodboard or photo-grid.

### Installation

Gravity well is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/gravity-well
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { GravityWell } from "@/components/arc/gravity-well/gravity-well";

export function Team({ people }: { people: { name: string; src: string }[] }) {
  return (
    <GravityWell label="Team">
      {people.map(person => <img key={person.src} src={person.src} alt={person.name} />)}
    </GravityWell>
  );
}
```

### API reference

#### GravityWell

A grid of tiles that bends toward the pointer like spacetime around a mass. Tiles near the well lean in, shrink, and dim on their own springs; a click sends a shockwave rolling outward through the grid.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` (required) | `ReactNode` | – | One tile per child. Photos, avatars, icons, or any small content. |
| `columns` | `number` | – | Fixed column count. Leave it out to fit as many columns as minTileSize allows. |
| `minTileSize` | `number` | `56` | Smallest tile width in px when columns is not set. |
| `gap` | `number` | `8` | Gap between tiles in px. |
| `radius` | `number` | `150` | Reach of the well in px. |
| `strength` | `number` | `1` | Pull strength from 0 to about 1.5. |
| `onPulse` | `(origin: { x: number; y: number }) => void` | – | Called when a click or key sends a shockwave, with its origin in px from the top left of the grid. |
| `label` | `string` | `"Gravity well"` | Accessible name for the grid. |
| `className` | `string` | – | Extra class on the root. |
| `style` | `CSSProperties` | – | Inline styles on the root. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Tab | Focuses the grid and places the well on the current tile. |
| Arrow keys | Moves the well from tile to tile. |
| Home / End | Moves the well to the first or last tile. |
| Space or Enter | Sends a shockwave from the current tile. |

### Accessibility

- The root is a named group with aria-roledescription="gravity well". Tile content keeps its own semantics and alt text.
- Motion is decorative: tiles keep their grid slot and only move with transform, so reading order never changes.
- Pointer focus draws no ring; keyboard focus shows Arc's shared focus ring. The well itself shows where keyboard focus is.

### Motion

- The well follows the pointer on a critically damped spring, and each tile follows the field on an underdamped spring, so fast moves leave a jelly wake.
- Tiles deeper in the well shrink, dim, and slide under their neighbours.
- A click drops a shockwave that travels at 900 px/s and rings each tile once as it passes.
- Reduced motion leaves the grid static.

### Responsive behavior

- Columns fit the width with minTileSize, or stay fixed with columns.
- Touch: a tap sends a shockwave and dragging pulls the well; vertical scroll keeps working.

### Performance

- One transform, opacity, and z-index write per tile per frame, with no layout reads during animation.
- The loop stops once every spring is at rest.

### Notes for AI

- Use a uniform set of square tiles, around 30 to 60. Content is wrapped in square cells; set object-fit: cover on images.
- Tie onPulse to something meaningful, like shuffling or selecting, or leave it as pure delight.

### Related

- [Dot grid](https://uiarc.dev/components/dot-grid/markdown): A dot field that bulges around the cursor like a lens and ripples from every click.
- [Photo grid](https://uiarc.dev/components/photo-grid/markdown): Pinch through zoom levels and open any photo straight from its cell.

### Also in cursor

- [Image trail](https://uiarc.dev/components/image-trail/markdown): Moving the pointer leaves a curated trail of photos that pop in, lean, and fade away.
- [Ink fluid](https://uiarc.dev/components/ink-fluid/markdown): A real time fluid simulation behind your hero: the cursor stirs soft ink that swirls, settles and fades; calm when left alone.

### Guidance for AI tools

Gravity well: A grid of tiles that bends toward the cursor like spacetime, with a click that sends a shockwave through it. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Ink fluid

> A real time fluid simulation behind your hero: the cursor stirs soft ink that swirls, settles and fades; calm when left alone.

- Type: Component (special)
- Access: Arc Pro
- Page: https://uiarc.dev/components/ink-fluid
- Markdown: https://uiarc.dev/components/ink-fluid/markdown
- Source file: `registry/components/ink-fluid/ink-fluid.tsx`
- Dependencies: motion
- Keywords: special, background, webgl, new, fluid simulation, ink, smoke, hero background, stable fluids, interactive background, cursor effect, navier stokes

### When to use

- A landing hero or sign in screen that should feel alive without a video.
- Empty states and waiting screens where a gentle, interactive background rewards curiosity.

### When not to use

- Dense product surfaces such as tables and forms. Movement behind data distracts.
- More than one per page; each instance runs its own simulation.

### Installation

Ink fluid is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/ink-fluid
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { InkFluid } from "@/components/arc/ink-fluid/ink-fluid";

export function Hero() {
  return (
    <InkFluid className="hero">
      <h1>Ship interfaces that feel alive</h1>
      <p>Components with motion that explains every change.</p>
    </InkFluid>
  );
}
```

### API reference

#### InkFluid

A real time stable fluids simulation behind your content. The pointer stirs soft ink tinted with the accent colour, which settles to neutral as it spreads; left alone a slow, calm stir keeps it alive.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | – | Content drawn above the ink, such as a hero heading and actions. |
| `intensity` | `number` | `0.5` | How dark the ink gets, from 0 to 1. |
| `tint` | `number` | `0.8` | How much fresh ink takes `--accent`, from 0 to 1. The tinted share hands itself to the neutral share as it spreads. |
| `force` | `number` | `0.5` | How hard the pointer stirs, from 0 to 1. |
| `ambient` | `boolean` | `true` | A slow stir while nobody interacts, starting 1.2s after the last pointer move. |
| `interactive` | `boolean` | `true` | Lets the pointer stir the ink. |
| `quality` | `"low" \| "medium" \| "high"` | `"medium"` | Simulation grid (96, 128 or 192 cells on the short side) and ink texture resolution. |
| `className` | `string` | – | Extra class on the root. Give it a size, a background and a radius. |
| `style` | `CSSProperties` | – | Inline styles on the root. |

### Accessibility

- The canvas is aria-hidden and ignores pointer hits; content inside stays fully interactive and readable.
- Ink is capped at a low opacity so text over it keeps its contrast in both themes.
- With reduced motion it renders one composed still frame and stops.

### Motion

- Semi Lagrangian advection, vorticity confinement and a 20 step pressure solve on a small grid, drawn with linear upscaling and a soft light term from the ink gradient so wisps read silky.
- Pointer velocity drives the force; the amount of ink scales with speed so slow moves leave faint trails and quick flicks bloom.
- Ink fades over a couple of seconds; accent tinted ink turns neutral as it spreads, so fresh strokes carry colour and old ones go grey.
- It pauses when scrolled out of view or when the tab is hidden, and resumes where it left off.

### Responsive behavior

- Resizes its simulation with the element, debounced by 120ms.
- Touch devices stir while a finger is down; `touch-action: pan-y` keeps vertical scrolling working.

### Performance

- About 30 small GPU passes per frame on a 128 cell grid; well under 2ms on integrated graphics.
- Device pixel ratio is capped at 1.5 for the output canvas; the ink texture is 512 cells on the short side at medium quality.
- Stops its animation frame loop off screen and in background tabs.

### Notes for AI

- Use as a hero or empty state background. Give the root a min height, a background colour and a border radius; the ink draws on transparent pixels over it.
- Colours come from `--foreground` (ink) and `--accent` (tint) on the root, so it follows the theme and accent switcher automatically. Override `--ink-color` or `--ink-accent` on the root to change them.
- Put buttons inside with `pointer-events: auto`; the root listens to pointer moves so stirring works over text too.
- Falls back to a plain background when WebGL2 or float render targets are unavailable.

### Related

- [Dot grid](https://uiarc.dev/components/dot-grid/markdown): A dot field that bulges around the cursor like a lens and ripples from every click.
- [Image trail](https://uiarc.dev/components/image-trail/markdown): Moving the pointer leaves a curated trail of photos that pop in, lean, and fade away.

### Also in cursor

- [Gravity well](https://uiarc.dev/components/gravity-well/markdown): A grid of tiles that bends toward the cursor like spacetime, with a click that sends a shockwave through it.

### Guidance for AI tools

Ink fluid: A real time fluid simulation behind your hero: the cursor stirs soft ink that swirls, settles and fades; calm when left alone. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Agent status

> A compact live status pill for a running AI agent: the agent's mark in a live ring, the current activity and an elapsed timer, opening into the steps so far.

- Type: Component (special)
- Access: Arc Pro
- Page: https://uiarc.dev/components/agent-status
- Markdown: https://uiarc.dev/components/agent-status/markdown
- Source file: `registry/components/agent-status/agent-status.tsx`
- Dependencies: motion, lucide-react
- Keywords: special, motion, ai, new, agent status, ai agent, status pill, run status, live indicator, approval, human in the loop, coding agent, research agent, elapsed timer, progress, dynamic island, agent run, claude, tool calls

### When to use

- An app header, title bar or composer that needs to show at a glance that an agent is running, what it is doing and for how long.
- Coding, research or browser agents that pause for approval, so the person can approve or deny without opening a full run view.
- Background runs that people check on occasionally: the pill stays small, and the panel shows recent steps and controls on demand.

### When not to use

- Use agent-run or research-run when the run itself is the page and every step, tool call and output needs room.
- Use agent-approvals to review a queue of pending approvals across several agents.
- Use agent-orchestrator or agent-tasks to compare many agents or runs at once.
- Use text-shimmer alone for a single inline working label without a timer, steps or controls.

### Installation

Agent status is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/agent-status
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { AgentStatus } from "@/components/arc/agent-status/agent-status";
import { FileSearch, FilePen, FlaskConical } from "lucide-react";

export function RunHeader({ run, agent }) {
  return (
    <AgentStatus
      status={run.status}               // "working" | "needs-input" | "paused" | "done" | ...
      startedAt={run.startedAt}
      agent={{ name: "Claude Sonnet 5.5", mark: <ClaudeMark style={{ color: "#D97757" }} /> }}
      activity={{ label: "Running tests", icon: FlaskConical, progress: { value: 8, total: 12 } }}
      steps={[
        { id: "read", label: "Read 12 files", icon: FileSearch, status: "done", durationMs: 1900 },
        { id: "edit", label: "Edited src/billing/invoice.ts", icon: FilePen, status: "done", durationMs: 2500 },
        { id: "tests", label: "Running tests", icon: FlaskConical, status: "active", startedAt: run.stepStartedAt },
        { id: "push", label: "Push the branch", status: "pending" },
      ]}
      onPause={() => agent.pause(run.id)}
      onResume={() => agent.resume(run.id)}
      onStop={() => agent.cancel(run.id)}
      onApprove={() => agent.approve(run.id)}
      onDeny={() => agent.deny(run.id)}
      onRetry={() => agent.retry(run.id)}
      onOpenRun={() => router.push(`/runs/${run.id}`)}
    />
  );
}

// With no props it plays the simulated coding run.
<AgentStatus />
```

### API reference

#### AgentStatus

A compact live status pill for a running AI agent, made for an app header or the space above a composer. Collapsed it shows the agent's mark inside a thin live ring, the current activity with a matching icon, and an elapsed timer in tabular numerals. Each new activity rolls in from below while the pill's width follows on a spring. A click expands the pill in place into a small floating panel with the latest steps (icon, text, duration), a thin step progress bar and Pause, Stop and Open run controls; Escape or a press outside closes it. It covers idle (Ready), working, needs input (an accent dot with inline Approve and Deny), paused, done (the ring closes and the mark morphs into a check, then it settles back to Ready), failed (with Retry) and stopped. With no props it plays a simulated coding run.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `status` | `"idle" \| "working" \| "needs-input" \| "paused" \| "done" \| "failed" \| "stopped"` | – | The run's state. Leave it out to play the built in simulated coding run (Claude Sonnet 5.5) with working controls. |
| `activity` | `{ label: string; icon?: AgentIcon; progress?: { value: number; total: number } }` | – | What the agent is doing now, in the present tense ("Reading 12 files", "Editing src/billing/invoice.ts"). The icon rolls in with the label. Progress ticks in place as "8 of 12" without rolling the label. In needs input it is the request ("Needs your approval to run git push"), in done the outcome appended to "Done in 1m 12s" ("6 files changed"), and in failed the failure ("Tests failed · 2 errors"). |
| `steps` | `AgentStep[]` | `[]` | Every step of the run, pending ones included so the progress bar knows the total. Each step has id, label, optional icon, status ("pending" \| "active" \| "waiting" \| "done" \| "failed" \| "skipped"), startedAt for a live step and durationMs for a finished one. Write active labels in the present tense and finished ones in the past tense ("Running tests" then "Passed 12 of 12 tests"), so the text itself carries the status. |
| `startedAt` | `number \| Date` | – | When the run started. The timer counts from here and leaves out time spent paused or failed, so it never jumps when the run resumes. |
| `endedAt` | `number \| Date` | – | When the run ended. Defaults to the moment the status turned done or stopped. |
| `agent` | `{ name: string; mark?: ReactNode }` | `{ name: "Agent" }` | The model or agent and its brand mark, drawn at 12px inside the live ring. Give a mono mark its brand color, for example the Claude mark in #D97757. |
| `onPause` | `() => void` | – | Shows Pause in the panel while working. |
| `onResume` | `() => void` | – | Shows Resume in the panel while paused. Pause and Resume share one button, so focus stays put. |
| `onStop` | `() => void` | – | Shows Stop in the panel while working or paused. |
| `onApprove` | `() => void` | – | Shows Approve in the accent color, inline in the pill and in the panel, while the status is needs-input. |
| `onDeny` | `() => void` | – | Shows Deny next to Approve while the status is needs-input. |
| `onRetry` | `() => void` | – | Shows Retry in the accent color, inline and in the panel, when the run failed. |
| `onOpenRun` | `() => void` | – | Shows an Open run button in the panel for a full log or trace view. It confirms with a check for a moment after it is pressed. |
| `settleAfter` | `number \| null` | `4000` | Milliseconds after done or stopped before the pill settles back to Ready. The panel keeps the last run's steps. Null keeps the result on screen. |
| `align` | `"start" \| "center" \| "end"` | `"center"` | Which edge the panel grows from. Use start or end when the pill sits against a header edge. |
| `expanded` | `boolean` | – | Controls the panel. Pair with onExpandedChange. |
| `defaultExpanded` | `boolean` | `false` | Opens the panel on first render when uncontrolled. |
| `onExpandedChange` | `(expanded: boolean) => void` | – | Called when the pill is pressed, Escape is pressed or a press lands outside the open panel. |
| `maxSteps` | `number` | `5` | How many of the latest steps the panel lists. Older steps slide out at the top as new ones arrive. |
| `notice` | `string` | – | A one-off message for screen readers, such as the result of an action. It joins the automatic status announcement. |
| `className` | `string` | – | Class on the root element. |

#### useAgentRunSimulation

The scripted runs behind the preview, exported for prototypes and tests. Returns every AgentStatus prop for a run plus replay(). Nothing runs for real: approvals, pushes, searches and Open run only update local state and say so through notice.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `scenarioId` | `"coding" \| "research"` | `"coding"` | Coding is Claude Sonnet 5.5 fixing a proration bug, ending on an approval to run git push. Research is Gemini 4 Argon comparing vendor pricing; one fetch times out on the first try so Retry can be seen. |
| `startDelay` | `number` | `900` | Milliseconds of Ready before the run starts. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Tab | Moves to the pill, then to the inline Deny and Approve or Retry buttons when they show. With the panel open, Tab moves through Pause or Resume, Stop or Deny, and Open run. |
| Enter, Space | On the pill, opens or closes the panel. On a button, activates it. |
| Escape | Closes the panel from anywhere inside it and returns focus to the pill. |

### Accessibility

- The pill is a button with aria-expanded and aria-controls pointing at the panel, and an accessible name that reads the agent, the activity, the count and the elapsed time.
- A polite status region announces each new activity and the outcome ("Claude Sonnet 5.5: done in 14 seconds, 6 files changed"), not every tick of a count or the timer. Pass notice to add the result of an action.
- Status never relies on color: every state pairs the ring and glyph with words (Ready, Paused, Needs your approval, Done in, Failed, Stopped after), and steps use present tense while running and past tense once finished.
- The step progress bar is a progressbar with a value text such as "4 of 6 steps finished".
- Pause and Resume, and Approve and the Pause that follows it, share one button, so keyboard focus stays in place. If a focused control disappears with a state change, focus moves to the pill instead of the page.
- In narrow containers the inline Approve, Deny and Retry and the Open run button become icon buttons with accessible names. A truncated activity stays readable in full through the pill's name and the panel's step list.
- Pointer focus draws no ring; keyboard focus shows Arc's shared focus ring, inset on the pill.

### Motion

- A new activity rolls in vertically in about 180ms while the old one leaves upward; the pill's width follows on the morph spring, and the label fades at its right edge only while it is wider than its room, so nothing snaps or wraps.
- Opening the panel springs width and height together on the smooth spring from the pill's own footprint; the header row stays where it is and the panel content fades in after a beat. Closing reverses it with a faster fade.
- The live ring spins a short arc while working, freezes in place when paused, gives way to an accent dot with one soft ping when input is needed, and closes around the glyph as the mark morphs into a drawn check (done) or cross (failed).
- The working label carries a calm shimmer that stops in every other state. Counts and the timer change in place with tabular numerals.
- New steps fade in at the bottom of the panel while older ones slide up; segments of the progress bar fill from the left.
- Reduced motion swaps every spring for an instant change, drops the roll, the spin, the ping and the shimmer, and keeps all states, text, focus and announcements.

### Responsive behavior

- The pill sizes to its content and never exceeds its parent's width; a long activity fades out at its right edge instead of wrapping.
- Below 400px of available width the inline actions become icon buttons, the timer steps aside while they show, and Open run in the panel becomes an icon button.
- The panel opens at 384px or the pill's width, whichever is wider, capped by the parent, and floats over the page with a shadow so nothing below moves.
- Step labels in the panel wrap rather than truncate, so long file paths stay readable on a phone.

### Performance

- The timer runs on a small per-instance clock that ticks four times a second only while the run is live and stops when paused, done or idle.
- Width and height animate motion values directly; natural widths come from two hidden, inert measuring rows watched by a ResizeObserver, so the pill never measures in the middle of an animation.
- The spinner and shimmer are CSS animations that pause or stop outside the working state.

### Notes for AI

- Drive it from your agent's event stream: set status, keep activity to the latest tool call or phase in the present tense, and append steps as they finish. Keep the pill's label short; the panel carries the history.
- Keep startedAt fixed for the whole run; the component freezes paused and failed time itself. Pass endedAt from your backend when you have it.
- Use needs-input for any approval gate (shell commands, pushes, payments, emails) and phrase activity.label as the request: "Needs your approval to run git push".
- For done, put only the outcome in activity.label ("6 files changed"); the component writes "Done in 1m 12s · 6 files changed".
- Pass only the handlers your backend supports; each control appears only when its handler exists.
- Place it in a container that sets its width, such as a header slot or a flex row: the pill measures its parent to truncate cleanly and to size the panel.

### Related

- [Agent run](https://uiarc.dev/components/blocks/agent-run/markdown): A single card that follows one AI coding agent through a task: steps stream in with the live one shimmering, tool calls open in place, and the agent stops on a two-file diff for you to approve or send back before it writes. When the run ends, the steps fold into one line and a result shows the files changed, the checks that passed and a pull request button.
- [Agent approvals](https://uiarc.dev/components/blocks/agent-approvals/markdown): One approval card for agents: the waiting tool call reads like a permission prompt with the tool's mark, the agent's reason and its arguments, and you approve, deny or allow it from now on.
- [AI composer](https://uiarc.dev/components/blocks/ai-composer/markdown): The prompt box at the bottom of an AI app: files upload in place, / opens commands, @ inserts mentions, a model and effort menu sits in the toolbar, and the send button turns into a stop control ringed by the reply's progress.
- [Research run](https://uiarc.dev/components/blocks/research-run/markdown): Deep research that plans searches, reads sources with their marks, and streams a cited answer where every chip lights up the sentence it supports.
- [Tool call](https://uiarc.dev/components/tool-call/markdown): A tool call row for agent transcripts: the tool's mark and the call in plain words, a live state while it runs, and the input and output a click away, with approval and retry when needed.
- [Agent plan](https://uiarc.dev/components/agent-plan/markdown): The plan an agent writes before it acts: edit, reorder or add steps while it is a draft, then watch it work through them as a live checklist.
- [Text shimmer](https://uiarc.dev/components/text-shimmer/markdown): Show ongoing work with a calm light across the words.

### Also in ai

- [Agent timeline](https://uiarc.dev/components/agent-timeline/markdown): A compact timeline of one orchestrated agent run: the orchestrator and its subagents share a time axis, handoffs draw in between rows, and a playhead replays thinking, tool calls and waiting while the header counts time, tokens and cost. Hover a span for what it did, or click it to trace its handoff path.
- [Context window](https://uiarc.dev/components/context-window/markdown): An AI context window as a grid of 200 cells: the system prompt, tools, files, summary and messages fill it in order, a threshold row marks where compaction starts, and sending a message, attaching a file or compacting shows exactly how much still fits.
- [Reasoning block](https://uiarc.dev/components/reasoning-block/markdown): The collapsible thinking block of an AI reply. While the model thinks, a shimmering label counts the seconds and the latest reasoning streams underneath. When it finishes, it folds to "Thought for 7s" and opens to show the full reasoning as calm steps with headings.
- [Source cards](https://uiarc.dev/components/source-cards/markdown): A row of cited sources under an AI answer where cards stream in with real site marks while the model searches, the overflow collapses into a stack of favicons, hovering lifts a preview with the passage, and an inline [n] citation highlights its card.
- [Model card](https://uiarc.dev/components/model-card/markdown): A model details card where switching models rolls every price, limit and score in place, a token slider estimates monthly cost live, and benchmark bars show each model's rank on hover. Compare crossfades to a side-by-side table against any rival with the better values marked, and the card never changes size.
- [AI workflow](https://uiarc.dev/components/ai-workflow/markdown): A Linear-style AI workflow card where a Gmail trigger, a Claude step, a branch and Slack and Linear actions sit on one hairline rail, and a test run glides down it, opening each step's output inline. Steps are added from a compact command menu with real app marks.
- [Code suggestion](https://uiarc.dev/components/code-suggestion/markdown): An AI code edit suggestion where the model's proposed changes stream into a small editor panel as inline diff hunks, and you accept or reject each one, or all at once with Cmd+Enter. Accepted hunks fold into the file with a smooth height change.
- [Ghost text](https://uiarc.dev/components/ghost-text/markdown): An inline AI autocomplete where muted ghost text continues your sentence exactly at the caret and Tab turns it solid in place. Cmd+Right takes it one word at a time, Escape fades it away, and a calm chip shows the model behind it.
- [Image generation](https://uiarc.dev/components/image-generation/markdown): An image studio where each image forms on a dot matrix: a soft halftone wave breathes across the grid, the dots take the colours of the coming photo and grow into a coloured halftone, then blur away into the sharp photo. One large canvas with a mono size label, a filmstrip of four variations, a prompt bar with model and ratio, and upscale with a sweeping dot band, vary or download, with real provider marks and a built-in simulation.
- [Dictation button](https://uiarc.dev/components/dictation-button/markdown): A chat composer with voice input, where the mic springs into a recording pill with a smooth live waveform, a timer, and cancel and insert buttons. Words stream into the field as you speak, muted until the recognizer settles them.
- [Speech player](https://uiarc.dev/components/speech-player/markdown): A read-aloud player for AI replies. The Read aloud button in the message's action row turns into a compact player with play, a scrubbable progress bar, speed and a voice picker, and a highlight follows the spoken word through the reply, karaoke style.
- [Meeting summary](https://uiarc.dev/components/meeting-summary/markdown): An AI meeting notes card: the header shows the Google Meet or Zoom mark, the attendees and the duration. Summary, Decisions and Action items stream in after a short summarizing pass. Hover any line to see the transcript quote it came from, then check off action items or send them to Linear or Notion.
- [Reply draft](https://uiarc.dev/components/reply-draft/markdown): An AI email reply drafter where Claude streams a reply under a received Gmail message. Quick replies steer a fresh draft, tone and length rewrite it with a single crossfade, and you can edit the finished draft before you insert it.
- [Agent handoff](https://uiarc.dev/components/agent-handoff/markdown): A support conversation where an AI assistant hands off to a person. When it transfers, a card shows the summary it passes to the team and the typical wait. The person then joins and takes over, and a thin timeline on the left marks each step.
- [PII redaction](https://uiarc.dev/components/pii-redaction/markdown): A guardrail card where personal data is redacted before the prompt reaches the model. Scan marks each name, email, phone number and card with its type and swaps it for a placeholder like [EMAIL_1]. The safe prompt travels to Claude, and the reply comes back with the original values put back for the person.
- [Response feedback](https://uiarc.dev/components/response-feedback/markdown): A feedback control for AI replies where thumbs down opens an inline panel with reason chips and an optional note, thumbs up fills and asks what was good, and a submit shows a short thank-you before folding back into the row.
- [LLM cost calculator](https://uiarc.dev/components/llm-cost-calculator/markdown): A pricing calculator for LLM workloads. Set tokens per request, requests per day and prompt caching, and eight current models re-rank by monthly cost. Bars glide and prices roll as you drag.
- [Provider keys](https://uiarc.dev/components/provider-keys/markdown): A settings card for bring-your-own-key AI products. Each provider row shows its real mark, the masked key, a status and when the key was last used. You can reveal a key for five seconds, copy, rotate or remove it with undo. Adding or rotating a key opens an inline form that checks the format as you type, then tests the connection before saving.
- [Generation stats](https://uiarc.dev/components/generation-stats/markdown): A live stats strip for a streaming LLM response where time to first token, speed with a sparkline, output tokens and cost count up in tabular numerals beside the model's real mark, then settle and open into a latency and token cost breakdown.
- [AI translate](https://uiarc.dev/components/ai-translate/markdown): A message card where picking a language streams the AI translation in place, sentence by sentence over the dimmed original, with a detected-language chip, a Show original toggle and a status line credited to the model's mark.
- [TL;DR toggle](https://uiarc.dev/components/tldr-toggle/markdown): An article card with a Full, Summary and Key points switch and a length slider. Switching streams an AI summary in place of the article as the card's height springs to fit, and each key point links back to the paragraph it came from, which gets scrolled to and highlighted.
- [Connector setup](https://uiarc.dev/components/connector-setup/markdown): A "Connect your tools" card for an AI assistant. Each app connects inline: it redirects, authorizes and runs a first sync with a progress hairline, then lists the scopes it was granted and offers Disconnect with an inline confirm.
- [Smart form fill](https://uiarc.dev/components/smart-form-fill/markdown): A paste-to-fill form card where AI reads an email signature or messy notes and fills a contact field by field. Each value flashes in with a confidence dot, its source lights up in the pasted text, low-confidence guesses ask for review, and Undo puts the old values back.
- [Enrich column](https://uiarc.dev/components/enrich-column/markdown): An AI enrichment column for a data table, where one prompt runs down every row and each cell shimmers while it works, then settles into a value with its source or a failure you can retry.
- [Ticket router](https://uiarc.dev/components/ticket-router/markdown): A support ticket router where messages from Gmail, Intercom, Slack and Zendesk come in one at a time. An AI classifier labels each one with intent, sentiment and confidence, and the ticket moves into a team lane with an assignee. Low confidence tickets wait in a review lane, and one click there routes them to the suggested team.
- [Ask your data](https://uiarc.dev/components/ask-your-data/markdown): A natural language to chart card: you ask a question, PostgreSQL streams into a collapsible, syntax highlighted panel, the query runs with a rolling row count, and the answer builds as stacked bars, lines or a table, with a one line insight streamed in underneath.
- [Agent cursor](https://uiarc.dev/components/agent-cursor/markdown): A live document where Claude edits like a collaborator. Its labeled cursor comes out of its avatar, selects a paragraph and streams in a rewrite, adds a heading and fixes a typo, while a teammate's cursor reads along. Changes stay tinted until someone accepts or undoes them from a floating review bar.
- [Provider status](https://uiarc.dev/components/provider-status/markdown): A status card for the AI providers your product depends on. Each row shows the provider's real mark, its health as an icon and label, p50 latency and a 30-day uptime bar with a tooltip for each day. An incident row expands into its timeline of updates, and the card checks again on a visible countdown.
- [Training run](https://uiarc.dev/components/training-run/markdown): A fine-tuning job card where a live train and validation loss curve draws across a fixed step axis that doubles as the epoch progress bar. It shows the learning rate, elapsed time, ETA and the latest evals and checkpoints, has Pause and Cancel while it runs, and ends in results with a Deploy button.
- [AI command](https://uiarc.dev/components/ai-command/markdown): A Cmd+K command palette with an AI mode. Search pages and actions, or press Tab to ask a question: the answer streams inside the palette with numbered sources, and the next steps it suggests, like filing a Linear issue or opening a Notion doc, run straight from the list.
- [Starter prompts](https://uiarc.dev/components/starter-prompts/markdown): A greeting and a grid of starter cards for the empty state of an AI app. The cards are grouped into Write, Code, Analyze and Plan tabs, and a shuffle swaps them with a short staggered crossfade. Picking a card fills the composer, and cards that use a connected app show its mark (Gmail, GitHub, Notion, Linear, Google Calendar).
- [AI mascot](https://uiarc.dev/components/ai-mascot/markdown): A small assistant character, a soft pebble with pill eyes and a companion dot, that shows what the AI is doing. It breathes and glances when idle, leans in to listen, looks up while the dot orbits its head, reads along the line it writes, squints with a sparkle when done and shakes once with worried brows on an error.
- [Image reveal](https://uiarc.dev/components/image-reveal/markdown): An image generation canvas where a soft, blurred preview made from the image's own colors sharpens top to bottom behind a soft-edged band. It works the way ChatGPT, Midjourney and Gemini show images forming, with fine film grain, a translucent progress pill and calm queued and error states.
- [AI spark](https://uiarc.dev/components/ai-spark/markdown): A brand-quality animated spark mark. Four tapered rays and four lighter diagonals breathe at rest, ripple while thinking, pulse like a heartbeat while writing, then gather and settle when done. Every status change blends from the pose the mark is already in.
- [Pixel mascot](https://uiarc.dev/components/pixel-mascot/markdown): A pixel-art robot that shows what an AI assistant is doing. It idles, thinks, types, celebrates and errors in frame-stepped sprite animations, and stays crisp at every integer size from 24px to 192px.
- [Ghost mascot](https://uiarc.dev/components/ghost-mascot/markdown): A floating ghost mascot whose soft sheet ripples at the hem while it hovers. It blinks when idle, turns toward you to listen, fades a little translucent while thinking, draws a tiny pen line while writing, smiles with a sparkle when done and wobbles once on an error.
- [Cube mascot](https://uiarc.dev/components/cube-mascot/markdown): An isometric cube mascot where three shaded faces and a painted-on face show what the assistant is doing. It turns a quarter turn in eased steps while thinking, prints lines onto the floor while writing, settles with a sparkle when done, and shakes once on error.
- [Tone tuner](https://uiarc.dev/components/tone-tuner/markdown): A brand voice card where two sliders (formality and detail) and Friendly, Confident and Empathetic chips rewrite a customer reply. Each changed sentence crossfades in place, new words can be highlighted against the original, and Copy takes the current version.
- [Upgrade prompt](https://uiarc.dev/components/upgrade-prompt/markdown): An upgrade nudge for the moment someone hits a limit. It shows a usage meter at 50 of 50 AI credits, a rolling price with a monthly and yearly toggle, three concrete unlocks with real model marks, and Upgrade or Maybe later. Upgrading leads into a success state with the new limits, and the card never changes size between states.
- [Referral card](https://uiarc.dev/components/referral-card/markdown): A give-and-get referral card where people copy or share their invite link, invite friends by email as chips, and watch invites move from invited to signed up to earned, with the credit total counting up and a milestone reward unlocking.
- [Trial banner](https://uiarc.dev/components/trial-banner/markdown): A trial status banner where a ring counts down the days left, the copy names what the workspace loses, and the upgrade path is one click away. It comes as a slim banner, a sidebar card or a header pill. It shifts to a warning tone in the last days, has expired and upgraded states, and folds into the pill when dismissed or snoozed.
- [Team switcher](https://uiarc.dev/components/team-switcher/markdown): A workspace switcher like Linear, Vercel or Slack. The trigger shows the current workspace's logo and plan. The menu has search, your role in each workspace and a Cmd+1 to 9 shortcut for each, and lets you create or join a workspace inline. A highlight glides between rows, and switching crossfades the trigger through a short loading state.
- [Live visitors](https://uiarc.dev/components/live-visitors/markdown): A realtime visitors card where the live count rolls digit by digit, new arrivals ping in on a dotted world map, the top pages reorder with bars, and signups and upgrades tick in with country flags.
- [Social proof toast](https://uiarc.dev/components/social-proof-toast/markdown): A stack of social proof notifications for landing and pricing pages, where recent trials, upgrades and verified purchases from people and companies arrive every few seconds. The stack pauses and fans out on hover, and visitors can dismiss any toast.
- [Install snippet](https://uiarc.dev/components/install-snippet/markdown): A "get started in 30 seconds" card where framework tabs, three numbered steps and highlighted snippets take a developer from install to first event. Generate key wipes a fresh API key into the placeholder in place.

### Guidance for AI tools

Agent status: A compact live status pill for a running AI agent: the agent's mark in a live ring, the current activity and an elapsed timer, opening into the steps so far. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Tool call

> A tool call row for agent transcripts: the tool's mark and the call in plain words, a live state while it runs, and the input and output a click away, with approval and retry when needed.

- Type: Component (special)
- Access: Arc Pro
- Page: https://uiarc.dev/components/tool-call
- Markdown: https://uiarc.dev/components/tool-call/markdown
- Source file: `registry/components/tool-call/tool-call.tsx`
- Dependencies: motion, lucide-react
- Keywords: special, motion, ai, new, tool call, tool use, function call, agent transcript, ai chat, used tools, approval, human in the loop, retry, tool result, mcp, agent, llm tools, inline approval

### When to use

- Showing what tools an AI agent used inside a chat or agent transcript, with the arguments and results one click away.
- Human in the loop actions where a call must be allowed or denied inline before it runs, such as posting a message or writing to a database.
- Making failures recoverable in place: a timed out query with its reason and a Retry button.
- Debug and audit views where developers need to copy exact tool inputs and outputs.

### When not to use

- Use agent-run for a full multi step run with a plan, a timeline and live logs rather than inline rows in a message.
- Use agent-approvals for a queue of pending approvals across many agents and runs.
- Use research-run when the work is mostly web research with sources and a streamed report.
- Use mcp-servers to manage which tools an agent can reach, not to show individual calls.

### Installation

Tool call is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/tool-call
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { ToolCall, ToolCallGroup } from "@/components/arc/tool-call/tool-call";

// One call on its own
<ToolCall
  tool="github"
  title="Searched issues in arc-ui/web"
  titles={{ running: "Searching issues in arc-ui/web" }}
  status="success"
  input={{ repo: "arc-ui/web", query: "is:open label:release-blocker" }}
  output={{ type: "list", items: [{ lead: "#1284", title: "Checkout button stays disabled after a coupon is removed", tag: "checkout" }] }}
  durationMs={1180}
/>

// Every call from one assistant turn, wired to your agent loop
export function ToolCalls({ calls, working, agent }) {
  return (
    <ToolCallGroup
      calls={calls}
      active={working}
      onApprove={call => agent.approve(call.id)}
      onDeny={call => agent.deny(call.id)}
      onRetry={call => agent.retry(call.id)}
    />
  );
}
```

### API reference

#### ToolCall

One inline tool call for an agent or chat transcript: the tool's mark, a verb phrase, quiet meta and a status icon. Clicking the row springs it open into Input (the arguments) and Output (a readable result), each with a copy button. Awaiting approval it shows inline Allow and Deny; on an error it shows the reason and Retry. With no props it renders a sample GitHub search.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` | – | Stable id for the call. A group uses it as the React key, so a call that changes status keeps its row and its open state. |
| `tool` | `"github" \| "linear" \| "postgres" \| "slack" \| "gmail" \| "web" \| { name: string; mark: ReactNode }` | – | Which tool ran. The built in ids draw the real brand mark (web draws a globe for web search); a custom tool passes its own name and a 16px mark. |
| `title` | `string` | – | The settled verb phrase, such as "Searched issues in arc-ui/web". Keep it to one line; it truncates. |
| `titles` | `Partial<Record<ToolCallStatus, string>>` | – | Phrasing per status, such as { running: "Searching issues in arc-ui/web", approval: "Post a summary to #release" }. Falls back to title. |
| `status` | `"running" \| "success" \| "error" \| "approval" \| "denied"` | – | Running shimmers the title with a spinner; success shows a check, the summary and the duration; error shows the reason and Retry; approval shows Allow and Deny on an accent outline; denied shows that the call never ran. |
| `input` | `Record<string, ToolCallValue>` | – | The arguments the model passed, shown as a mono key and value list with a copy button. |
| `output` | `{ type: "list"; items } \| { type: "table"; columns; rows } \| { type: "json"; value } \| { type: "text"; text }` | – | What came back. Lists show a number, a title and a tag per row; tables and JSON (with a syntax tint) fold after five rows or ten lines behind "Show 18 more lines". Copy gives JSON, lines or tab separated rows. |
| `summary` | `string` | – | Quiet meta before the duration, such as "4 results". Derived from the output when left out (results, rows, fields). |
| `message` | `string` | – | One line under the title: the error reason, or what allowing the call will do. |
| `durationMs` | `number` | – | How long the call took, shown as 640ms or 1.2s with tabular numerals. The group header shows the total. |
| `defaultOpen` | `boolean` | `false` | Opens the Input and Output panel on first render. |
| `open` | `boolean` | – | Controls the panel. Pair with onOpenChange. |
| `onOpenChange` | `(open: boolean) => void` | – | Called when the row is opened or closed. |
| `onApprove` | `() => void` | – | Allow on a call awaiting approval. Update status yourself (usually to running, then success). Without it the preview simulates the call and says so to assistive technology. |
| `onDeny` | `() => void` | – | Deny on a call awaiting approval. Without it the call is marked denied locally. |
| `onRetry` | `() => void` | – | Retry on a failed call. Without it the preview simulates a successful retry. |
| `renderOutput` | `(call: ToolCallData) => ReactNode \| undefined` | – | Draws a custom result for a successful call inside the Output well, such as a chart or a file preview. Return undefined to fall back to the built in view. |
| `className` | `string` | – | Class on the call's outer element. |

#### ToolCallGroup

Several calls from one assistant turn under a quiet header, "Used 4 tools", with an overlapping stack of the tools' marks and the total duration. Opening it staggers the rows in; while the agent works the header reads "Using 3 tools" with a shimmer. A call that needs a decision opens a closed group, and the group folds itself away once every call has finished unless the person has opened or closed anything.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `calls` | `ToolCallData[]` | `four settled sample calls` | The calls in order, each with id, tool, title, status and optional titles, input, output, summary, message and durationMs. Append to the array as the agent starts new calls; each new row grows in. |
| `active` | `boolean` | `any call running` | The agent is still working in this turn, so the header keeps saying "Using" between calls instead of flickering to "Used". |
| `defaultOpen` | `boolean` | `open while any call is running, waiting or failed` | Whether the list is open on first render. A finished transcript starts folded. |
| `open` | `boolean` | – | Controls the list. Pair with onOpenChange. Calls that need a decision only open the group on their own when it is uncontrolled. |
| `onOpenChange` | `(open: boolean) => void` | – | Called when the header is toggled or the group folds itself. |
| `autoCollapse` | `boolean` | `true` | Folds the list 450ms after every call has finished, so the answer reads right under "Used 4 tools". Skipped once the person has opened or closed the group or any row. |
| `onApprove` | `(call: ToolCallData) => void` | – | Allow on a call awaiting approval. |
| `onDeny` | `(call: ToolCallData) => void` | – | Deny on a call awaiting approval. |
| `onRetry` | `(call: ToolCallData) => void` | – | Retry on a failed call. |
| `renderOutput` | `(call: ToolCallData) => ReactNode \| undefined` | – | Custom result renderer applied to every successful call in the group. |
| `className` | `string` | – | Class on the group's outer element. |

#### ToolCallData

The shape of one call, shared by ToolCall props and ToolCallGroup calls.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `id` (required) | `string` | – | Stable id for the call. A group uses it as the React key, so a call that changes status keeps its row and its open state. |
| `tool` (required) | `"github" \| "linear" \| "postgres" \| "slack" \| "gmail" \| "web" \| { name: string; mark: ReactNode }` | – | Which tool ran. The built in ids draw the real brand mark (web draws a globe for web search); a custom tool passes its own name and a 16px mark. |
| `title` (required) | `string` | – | The settled verb phrase, such as "Searched issues in arc-ui/web". Keep it to one line; it truncates. |
| `titles` | `Partial<Record<ToolCallStatus, string>>` | – | Phrasing per status, such as { running: "Searching issues in arc-ui/web", approval: "Post a summary to #release" }. Falls back to title. |
| `status` (required) | `"running" \| "success" \| "error" \| "approval" \| "denied"` | – | Running shimmers the title with a spinner; success shows a check, the summary and the duration; error shows the reason and Retry; approval shows Allow and Deny on an accent outline; denied shows that the call never ran. |
| `input` | `Record<string, ToolCallValue>` | – | The arguments the model passed, shown as a mono key and value list with a copy button. |
| `output` | `{ type: "list"; items } \| { type: "table"; columns; rows } \| { type: "json"; value } \| { type: "text"; text }` | – | What came back. Lists show a number, a title and a tag per row; tables and JSON (with a syntax tint) fold after five rows or ten lines behind "Show 18 more lines". Copy gives JSON, lines or tab separated rows. |
| `summary` | `string` | – | Quiet meta before the duration, such as "4 results". Derived from the output when left out (results, rows, fields). |
| `message` | `string` | – | One line under the title: the error reason, or what allowing the call will do. |
| `durationMs` | `number` | – | How long the call took, shown as 640ms or 1.2s with tabular numerals. The group header shows the total. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Tab | Moves through the group header, each call row, a row's Allow, Deny or Retry buttons, and inside an open row its copy buttons and the show more control. |
| Enter, Space | On the group header, opens or closes the list. On a call row, opens or closes Input and Output. On Allow, Deny, Retry, copy and show more, activates them. |

### Accessibility

- The group header and every call row are real buttons with aria-expanded and aria-controls; a row's name reads the tool, the verb phrase and the status, such as "GitHub: Searched issues in arc-ui/web Done, 4 results, 1.2s".
- Status is never color alone: each status has its own icon shape (spinner, check, alert, shield, ban), failed and waiting calls show a reason line, and the row name spells the status out.
- Each call announces its status changes through a polite live region, including that the preview only simulates an action when no handler is passed.
- Allow, Deny and Retry are labelled with the call they act on, such as "Allow: Post a summary to #release".
- The input list is a description list; tables keep table semantics with column headers. Folded rows and lines are hidden from assistive technology until shown.
- Copy buttons confirm success or failure in place and through a live region, without changing width.
- Pointer focus draws no ring; keyboard focus shows Arc's shared ring, inset inside rows so it is never clipped.

### Motion

- Opening a row, opening the group and showing more lines animate height on the critically damped smooth spring, with a short opacity fade; chevrons turn on the shared CSS spring.
- Opening the group staggers its rows in 20ms apart with a 6px settle. Rows appended by a live run grow in from zero height instead, so nothing below them jumps.
- A row's height follows its content on the same spring when a reason line or wrapped actions appear, so a status change never resizes in one frame.
- Status icons trade places with a snappy scale and fade; the success check draws itself once. The running title uses the text shimmer and settles to solid when the call finishes.
- The mark stack widens on the morph spring as a new tool joins, so the header label glides instead of jumping.
- Reduced motion removes the stagger, spinner rotation, shimmer travel and springs. Panels, rows and statuses change immediately and every label, announcement and focus path stays.

### Responsive behavior

- Rows are container aware: below 440px the meta keeps only the duration, the reason line wraps, and Allow, Deny and Retry move under the reason so the title keeps its width.
- Under 440px the Input and Output panel drops its title indent and uses the full row width; wide JSON and tables scroll inside their own well, never the page.
- Rows are 40px tall and inline actions grow to 32px on touch screens. The whole row is the tap target for opening it.

### Performance

- Folded outputs use fixed row heights, so folding and unfolding never measures the DOM.
- Input and Output mount only while a row is open; a closed group unmounts its rows.
- Height follows content through one ResizeObserver per row, and width changes from the container cut straight to the new height without animating.
- No dependencies beyond motion and lucide-react; brand marks are inline SVG.

### Notes for AI

- Use ToolCallGroup for the tool calls of one assistant turn and ToolCall for a single call shown on its own. Render the group between the assistant's intro sentence and its answer.
- Append calls to the array as the agent starts them and change status in place; keep ids stable. Pass active while the agent is still working so the header does not flicker between calls.
- Give each call a past tense title and a present tense titles.running, and for approval calls an imperative titles.approval ("Post a summary to #release") plus a message saying what allowing will do.
- Pick the output type that reads best: list for search results and issues, table for SQL rows, json for structured API responses, text for a sent message or a short log. Use renderOutput for anything richer.
- Approve, deny and retry handlers should update the call's status; the component never changes status itself when a handler is passed. Without handlers it simulates locally, which suits previews only.
- Brand marks are sample content and never imply endorsement. For tools without a built in mark pass { name, mark } with a 16px inline SVG.

### Related

- [AI chat](https://uiarc.dev/components/blocks/ai-chat/markdown): A full-screen AI chat where answers stream in as markdown with folding reasoning, tool chips and cited sources. People can switch chats and models, edit or retry a message into versions, rate replies and stop a reply mid-stream.
- [Agent run](https://uiarc.dev/components/blocks/agent-run/markdown): A single card that follows one AI coding agent through a task: steps stream in with the live one shimmering, tool calls open in place, and the agent stops on a two-file diff for you to approve or send back before it writes. When the run ends, the steps fold into one line and a result shows the files changed, the checks that passed and a pull request button.
- [Agent approvals](https://uiarc.dev/components/blocks/agent-approvals/markdown): One approval card for agents: the waiting tool call reads like a permission prompt with the tool's mark, the agent's reason and its arguments, and you approve, deny or allow it from now on.
- [Agent loop](https://uiarc.dev/components/agent-loop/markdown): An illustration of the agent loop: gather context, take action, verify, repeat, with a bright head circling three stations around the model.
- [Research run](https://uiarc.dev/components/blocks/research-run/markdown): Deep research that plans searches, reads sources with their marks, and streams a cited answer where every chip lights up the sentence it supports.
- [MCP servers](https://uiarc.dev/components/blocks/mcp-servers/markdown): Manage the MCP servers that give an agent its tools: see what the enabled tools cost in context, connect or pause a server, and switch single tools on or off.
- [Text shimmer](https://uiarc.dev/components/text-shimmer/markdown): Show ongoing work with a calm light across the words.

### Also in ai

- [Agent status](https://uiarc.dev/components/agent-status/markdown): A compact live status pill for a running AI agent: the agent's mark in a live ring, the current activity and an elapsed timer, opening into the steps so far.
- [Agent plan](https://uiarc.dev/components/agent-plan/markdown): The plan an agent writes before it acts: edit, reorder or add steps while it is a draft, then watch it work through them as a live checklist.
- [Agent timeline](https://uiarc.dev/components/agent-timeline/markdown): A compact timeline of one orchestrated agent run: the orchestrator and its subagents share a time axis, handoffs draw in between rows, and a playhead replays thinking, tool calls and waiting while the header counts time, tokens and cost. Hover a span for what it did, or click it to trace its handoff path.
- [Context window](https://uiarc.dev/components/context-window/markdown): An AI context window as a grid of 200 cells: the system prompt, tools, files, summary and messages fill it in order, a threshold row marks where compaction starts, and sending a message, attaching a file or compacting shows exactly how much still fits.
- [Reasoning block](https://uiarc.dev/components/reasoning-block/markdown): The collapsible thinking block of an AI reply. While the model thinks, a shimmering label counts the seconds and the latest reasoning streams underneath. When it finishes, it folds to "Thought for 7s" and opens to show the full reasoning as calm steps with headings.
- [Source cards](https://uiarc.dev/components/source-cards/markdown): A row of cited sources under an AI answer where cards stream in with real site marks while the model searches, the overflow collapses into a stack of favicons, hovering lifts a preview with the passage, and an inline [n] citation highlights its card.
- [Model card](https://uiarc.dev/components/model-card/markdown): A model details card where switching models rolls every price, limit and score in place, a token slider estimates monthly cost live, and benchmark bars show each model's rank on hover. Compare crossfades to a side-by-side table against any rival with the better values marked, and the card never changes size.
- [AI workflow](https://uiarc.dev/components/ai-workflow/markdown): A Linear-style AI workflow card where a Gmail trigger, a Claude step, a branch and Slack and Linear actions sit on one hairline rail, and a test run glides down it, opening each step's output inline. Steps are added from a compact command menu with real app marks.
- [Code suggestion](https://uiarc.dev/components/code-suggestion/markdown): An AI code edit suggestion where the model's proposed changes stream into a small editor panel as inline diff hunks, and you accept or reject each one, or all at once with Cmd+Enter. Accepted hunks fold into the file with a smooth height change.
- [Ghost text](https://uiarc.dev/components/ghost-text/markdown): An inline AI autocomplete where muted ghost text continues your sentence exactly at the caret and Tab turns it solid in place. Cmd+Right takes it one word at a time, Escape fades it away, and a calm chip shows the model behind it.
- [Image generation](https://uiarc.dev/components/image-generation/markdown): An image studio where each image forms on a dot matrix: a soft halftone wave breathes across the grid, the dots take the colours of the coming photo and grow into a coloured halftone, then blur away into the sharp photo. One large canvas with a mono size label, a filmstrip of four variations, a prompt bar with model and ratio, and upscale with a sweeping dot band, vary or download, with real provider marks and a built-in simulation.
- [Dictation button](https://uiarc.dev/components/dictation-button/markdown): A chat composer with voice input, where the mic springs into a recording pill with a smooth live waveform, a timer, and cancel and insert buttons. Words stream into the field as you speak, muted until the recognizer settles them.
- [Speech player](https://uiarc.dev/components/speech-player/markdown): A read-aloud player for AI replies. The Read aloud button in the message's action row turns into a compact player with play, a scrubbable progress bar, speed and a voice picker, and a highlight follows the spoken word through the reply, karaoke style.
- [Meeting summary](https://uiarc.dev/components/meeting-summary/markdown): An AI meeting notes card: the header shows the Google Meet or Zoom mark, the attendees and the duration. Summary, Decisions and Action items stream in after a short summarizing pass. Hover any line to see the transcript quote it came from, then check off action items or send them to Linear or Notion.
- [Reply draft](https://uiarc.dev/components/reply-draft/markdown): An AI email reply drafter where Claude streams a reply under a received Gmail message. Quick replies steer a fresh draft, tone and length rewrite it with a single crossfade, and you can edit the finished draft before you insert it.
- [Agent handoff](https://uiarc.dev/components/agent-handoff/markdown): A support conversation where an AI assistant hands off to a person. When it transfers, a card shows the summary it passes to the team and the typical wait. The person then joins and takes over, and a thin timeline on the left marks each step.
- [PII redaction](https://uiarc.dev/components/pii-redaction/markdown): A guardrail card where personal data is redacted before the prompt reaches the model. Scan marks each name, email, phone number and card with its type and swaps it for a placeholder like [EMAIL_1]. The safe prompt travels to Claude, and the reply comes back with the original values put back for the person.
- [Response feedback](https://uiarc.dev/components/response-feedback/markdown): A feedback control for AI replies where thumbs down opens an inline panel with reason chips and an optional note, thumbs up fills and asks what was good, and a submit shows a short thank-you before folding back into the row.
- [LLM cost calculator](https://uiarc.dev/components/llm-cost-calculator/markdown): A pricing calculator for LLM workloads. Set tokens per request, requests per day and prompt caching, and eight current models re-rank by monthly cost. Bars glide and prices roll as you drag.
- [Provider keys](https://uiarc.dev/components/provider-keys/markdown): A settings card for bring-your-own-key AI products. Each provider row shows its real mark, the masked key, a status and when the key was last used. You can reveal a key for five seconds, copy, rotate or remove it with undo. Adding or rotating a key opens an inline form that checks the format as you type, then tests the connection before saving.
- [Generation stats](https://uiarc.dev/components/generation-stats/markdown): A live stats strip for a streaming LLM response where time to first token, speed with a sparkline, output tokens and cost count up in tabular numerals beside the model's real mark, then settle and open into a latency and token cost breakdown.
- [AI translate](https://uiarc.dev/components/ai-translate/markdown): A message card where picking a language streams the AI translation in place, sentence by sentence over the dimmed original, with a detected-language chip, a Show original toggle and a status line credited to the model's mark.
- [TL;DR toggle](https://uiarc.dev/components/tldr-toggle/markdown): An article card with a Full, Summary and Key points switch and a length slider. Switching streams an AI summary in place of the article as the card's height springs to fit, and each key point links back to the paragraph it came from, which gets scrolled to and highlighted.
- [Connector setup](https://uiarc.dev/components/connector-setup/markdown): A "Connect your tools" card for an AI assistant. Each app connects inline: it redirects, authorizes and runs a first sync with a progress hairline, then lists the scopes it was granted and offers Disconnect with an inline confirm.
- [Smart form fill](https://uiarc.dev/components/smart-form-fill/markdown): A paste-to-fill form card where AI reads an email signature or messy notes and fills a contact field by field. Each value flashes in with a confidence dot, its source lights up in the pasted text, low-confidence guesses ask for review, and Undo puts the old values back.
- [Enrich column](https://uiarc.dev/components/enrich-column/markdown): An AI enrichment column for a data table, where one prompt runs down every row and each cell shimmers while it works, then settles into a value with its source or a failure you can retry.
- [Ticket router](https://uiarc.dev/components/ticket-router/markdown): A support ticket router where messages from Gmail, Intercom, Slack and Zendesk come in one at a time. An AI classifier labels each one with intent, sentiment and confidence, and the ticket moves into a team lane with an assignee. Low confidence tickets wait in a review lane, and one click there routes them to the suggested team.
- [Ask your data](https://uiarc.dev/components/ask-your-data/markdown): A natural language to chart card: you ask a question, PostgreSQL streams into a collapsible, syntax highlighted panel, the query runs with a rolling row count, and the answer builds as stacked bars, lines or a table, with a one line insight streamed in underneath.
- [Agent cursor](https://uiarc.dev/components/agent-cursor/markdown): A live document where Claude edits like a collaborator. Its labeled cursor comes out of its avatar, selects a paragraph and streams in a rewrite, adds a heading and fixes a typo, while a teammate's cursor reads along. Changes stay tinted until someone accepts or undoes them from a floating review bar.
- [Provider status](https://uiarc.dev/components/provider-status/markdown): A status card for the AI providers your product depends on. Each row shows the provider's real mark, its health as an icon and label, p50 latency and a 30-day uptime bar with a tooltip for each day. An incident row expands into its timeline of updates, and the card checks again on a visible countdown.
- [Training run](https://uiarc.dev/components/training-run/markdown): A fine-tuning job card where a live train and validation loss curve draws across a fixed step axis that doubles as the epoch progress bar. It shows the learning rate, elapsed time, ETA and the latest evals and checkpoints, has Pause and Cancel while it runs, and ends in results with a Deploy button.
- [AI command](https://uiarc.dev/components/ai-command/markdown): A Cmd+K command palette with an AI mode. Search pages and actions, or press Tab to ask a question: the answer streams inside the palette with numbered sources, and the next steps it suggests, like filing a Linear issue or opening a Notion doc, run straight from the list.
- [Starter prompts](https://uiarc.dev/components/starter-prompts/markdown): A greeting and a grid of starter cards for the empty state of an AI app. The cards are grouped into Write, Code, Analyze and Plan tabs, and a shuffle swaps them with a short staggered crossfade. Picking a card fills the composer, and cards that use a connected app show its mark (Gmail, GitHub, Notion, Linear, Google Calendar).
- [AI mascot](https://uiarc.dev/components/ai-mascot/markdown): A small assistant character, a soft pebble with pill eyes and a companion dot, that shows what the AI is doing. It breathes and glances when idle, leans in to listen, looks up while the dot orbits its head, reads along the line it writes, squints with a sparkle when done and shakes once with worried brows on an error.
- [Image reveal](https://uiarc.dev/components/image-reveal/markdown): An image generation canvas where a soft, blurred preview made from the image's own colors sharpens top to bottom behind a soft-edged band. It works the way ChatGPT, Midjourney and Gemini show images forming, with fine film grain, a translucent progress pill and calm queued and error states.
- [AI spark](https://uiarc.dev/components/ai-spark/markdown): A brand-quality animated spark mark. Four tapered rays and four lighter diagonals breathe at rest, ripple while thinking, pulse like a heartbeat while writing, then gather and settle when done. Every status change blends from the pose the mark is already in.
- [Pixel mascot](https://uiarc.dev/components/pixel-mascot/markdown): A pixel-art robot that shows what an AI assistant is doing. It idles, thinks, types, celebrates and errors in frame-stepped sprite animations, and stays crisp at every integer size from 24px to 192px.
- [Ghost mascot](https://uiarc.dev/components/ghost-mascot/markdown): A floating ghost mascot whose soft sheet ripples at the hem while it hovers. It blinks when idle, turns toward you to listen, fades a little translucent while thinking, draws a tiny pen line while writing, smiles with a sparkle when done and wobbles once on an error.
- [Cube mascot](https://uiarc.dev/components/cube-mascot/markdown): An isometric cube mascot where three shaded faces and a painted-on face show what the assistant is doing. It turns a quarter turn in eased steps while thinking, prints lines onto the floor while writing, settles with a sparkle when done, and shakes once on error.
- [Tone tuner](https://uiarc.dev/components/tone-tuner/markdown): A brand voice card where two sliders (formality and detail) and Friendly, Confident and Empathetic chips rewrite a customer reply. Each changed sentence crossfades in place, new words can be highlighted against the original, and Copy takes the current version.
- [Upgrade prompt](https://uiarc.dev/components/upgrade-prompt/markdown): An upgrade nudge for the moment someone hits a limit. It shows a usage meter at 50 of 50 AI credits, a rolling price with a monthly and yearly toggle, three concrete unlocks with real model marks, and Upgrade or Maybe later. Upgrading leads into a success state with the new limits, and the card never changes size between states.
- [Referral card](https://uiarc.dev/components/referral-card/markdown): A give-and-get referral card where people copy or share their invite link, invite friends by email as chips, and watch invites move from invited to signed up to earned, with the credit total counting up and a milestone reward unlocking.
- [Trial banner](https://uiarc.dev/components/trial-banner/markdown): A trial status banner where a ring counts down the days left, the copy names what the workspace loses, and the upgrade path is one click away. It comes as a slim banner, a sidebar card or a header pill. It shifts to a warning tone in the last days, has expired and upgraded states, and folds into the pill when dismissed or snoozed.
- [Team switcher](https://uiarc.dev/components/team-switcher/markdown): A workspace switcher like Linear, Vercel or Slack. The trigger shows the current workspace's logo and plan. The menu has search, your role in each workspace and a Cmd+1 to 9 shortcut for each, and lets you create or join a workspace inline. A highlight glides between rows, and switching crossfades the trigger through a short loading state.
- [Live visitors](https://uiarc.dev/components/live-visitors/markdown): A realtime visitors card where the live count rolls digit by digit, new arrivals ping in on a dotted world map, the top pages reorder with bars, and signups and upgrades tick in with country flags.
- [Social proof toast](https://uiarc.dev/components/social-proof-toast/markdown): A stack of social proof notifications for landing and pricing pages, where recent trials, upgrades and verified purchases from people and companies arrive every few seconds. The stack pauses and fans out on hover, and visitors can dismiss any toast.
- [Install snippet](https://uiarc.dev/components/install-snippet/markdown): A "get started in 30 seconds" card where framework tabs, three numbered steps and highlighted snippets take a developer from install to first event. Generate key wipes a fresh API key into the placeholder in place.

### Guidance for AI tools

Tool call: A tool call row for agent transcripts: the tool's mark and the call in plain words, a live state while it runs, and the input and output a click away, with approval and retry when needed. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Agent plan

> The plan an agent writes before it acts: edit, reorder or add steps while it is a draft, then watch it work through them as a live checklist.

- Type: Component (special)
- Access: Arc Pro
- Page: https://uiarc.dev/components/agent-plan
- Markdown: https://uiarc.dev/components/agent-plan/markdown
- Source file: `registry/components/agent-plan/agent-plan.tsx`
- Dependencies: motion, lucide-react
- Keywords: special, motion, ai, new, agent plan, plan mode, todo list, task plan, checklist, approve plan, coding agent, ai agent, step list, reorder, drag and drop, progress, retry, human in the loop, claude

### When to use

- An agent should show and get approval for its plan before it edits code, runs commands or touches production.
- A person needs to adjust the agent's plan (rename, reorder, remove or add steps) and then watch the same plan execute.
- A side panel or chat message that tracks a multi-step task with a live current step, failures that need a decision, and a final summary.

### When not to use

- Use agent-run for a streaming transcript of everything the agent did, with tool calls and output, rather than a checklist of steps.
- Use agent-approvals when the person approves individual risky actions one at a time instead of a whole plan up front.
- Use agent-tasks for a queue of independent tasks across agents rather than one ordered plan.
- Use research-run for search and reading progress that ends in a cited answer.

### Installation

Agent plan is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/agent-plan
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { AgentPlan, type AgentPlanStep } from "@/components/arc/agent-plan/agent-plan";

// With no props it shows a sample plan and simulates the run.
export function PlanDemo() {
  return <AgentPlan />;
}

// Driven by your agent.
export function AgentPlanPanel({ run }) {
  return (
    <AgentPlan
      goal={run.goal}
      steps={run.steps}           // [{ id, title, state, substeps, note, error, duration }]
      status={run.status}         // "draft" | "running" | "paused" | "done"
      summary={run.summary}
      model={{ name: "Claude Sonnet 5.5", mark: <ClaudeMark /> }}
      onChange={steps => run.updateDraft(steps)}
      onKeepPlanning={() => run.suggestStep()}
      onApprove={steps => run.start(steps)}
      onPauseChange={paused => (paused ? run.pause() : run.resume())}
      onStepAction={({ type, step }) => (type === "retry" ? run.retry(step.id) : run.skip(step.id))}
    />
  );
}

// A step the agent is working on, and one it inserted.
const steps: AgentPlanStep[] = [
  { id: "store", title: "Keep request counters in Redis with a 60 second TTL", state: "active", substeps: ["Read lib/redis.ts", "Ran 6 tests"] },
  { id: "fallback", title: "Fall back to in-memory counters when Redis is down", note: "Added by agent" },
];
```

### API reference

#### AgentPlan

The plan an agent writes before it acts, then works through as a live checklist. A header shows the model mark, "Plan · 6 steps" and the goal. While the plan is a draft every step can be renamed in place, dragged or moved with Alt and the arrow keys, removed, or added to, and Keep planning streams one more suggested step in before the last one. Approve plan locks it: the grips become status rings, the header counts "3 of 6" over a thin progress line, the current step shimmers beside a small spinner with its activity lines underneath, and a finished step draws its check and settles to secondary text with its time on the right. The agent can insert a step mid-run (it slides in with an "Added by agent" note), a failed step offers Retry and Skip, the run can be paused and resumed, and the footer ends with a one line summary and the total time. Without `status` it runs a simulated agent so the whole journey can be tried in place.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `steps` | `AgentPlanStep[]` | `sampleSteps` | The plan. Each step has an id and a title, and optionally a state ("pending", "active", "done", "failed" or "skipped"), substeps (short activity lines; the first word, such as Read, Edited, Created, Searched or Ran, picks the icon), a note ("Added by agent"), an error for a failed step, and a duration in seconds for a done step. A new array replaces the plan on screen. |
| `status` | `"draft" \| "running" \| "paused" \| "done"` | – | Where the plan stands. Pass it to drive the plan from your agent: the component then never changes status or steps on its own and reports every action through the callbacks. Leave it out to run the built-in simulation. |
| `goal` | `string` | `"Add rate limiting to the public API"` | What the plan is for, shown under the header and used in the plan's accessible name. |
| `model` | `{ name: string; mark?: ReactNode }` | `{ name: "Claude Opus 5.5", mark: <ClaudeBrandMark /> }` | The model that wrote the plan. The 16px mark sits in the header and before agent notes; the name shows in the header while the plan is a draft. |
| `summary` | `string` | – | One line shown after "Done in 4m 35s." when the plan finishes. It streams in. The total time is the sum of the done steps' durations. |
| `onApprove` | `(steps: AgentPlanStep[]) => void` | – | Called by Approve plan with the steps in their final order, titles trimmed and empty steps removed. Start your agent here and set status to "running". |
| `onChange` | `(steps: AgentPlanStep[]) => void` | – | Called after each draft edit: a rename (on Enter or blur), a reorder (on drop or key press), a removal, an added step, or a suggested step that finished streaming. |
| `onStepAction` | `(action: { type: "retry" \| "skip"; step: AgentPlanStep }) => void` | – | Called when someone retries or skips a failed step. Focus is handled for you; update the step's state in `steps`. |
| `onKeepPlanning` | `() => void` | – | Called by Keep planning. Ask the agent for one more step and add it to `steps`. |
| `onPauseChange` | `(paused: boolean) => void` | – | Called by Pause (true) and Resume (false). Pause your agent and set status to "paused", or back to "running". |
| `className` | `string` | – | Class on the root element. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Tab | In a draft, moves through each step's grip, title and remove button, then Add step, Keep planning and Approve plan. While running, reaches Retry and Skip on a failed step and Pause or Resume. |
| Alt + Arrow up / Arrow down | In a step title, moves that step up or down and keeps the caret in place. |
| Arrow up / Arrow down | On a step's grip, moves that step up or down. |
| Enter | In a step title, saves the rename without leaving the field. |
| Escape | In a step title, undoes the rename since the field was focused. |
| Backspace | In an empty step title, removes the step and moves focus to the step above. |

### Accessibility

- The plan is a section named after the model and the goal; the steps are an ordered list, so a screen reader announces the count and each position.
- Every step announces its state in words (Pending, In progress, Done, Failed, Skipped) before its title. Each state also has its own shape, a ring, a spinning arc, two bars, a disc with a check, a disc with an exclamation mark or a dashed ring, so it never rests on color.
- A failed step shows the word Failed with its reason and two labelled buttons. Skipped steps say Skipped beside the title.
- Titles are labelled text areas described by a hidden hint that explains Alt plus the arrow keys and Escape. Grips and remove buttons are named after their step and position.
- Edits, approval, each finished step, an inserted step, a failure, pause and the final summary are announced through one polite status region, including that the preview is a simulation.
- Focus follows the action: a moved step keeps focus, a removed step hands it to its neighbour, Approve plan hands it to Pause, and Retry or Skip hand it back to Pause.
- The progress line is a progressbar with a text value ("2 of 6 steps finished"), hidden while the plan is a draft.
- Pointer focus draws no ring; keyboard focus shows Arc's shared focus ring, inset on controls inside clipped rows.

### Motion

- Reorders, inserts, removals and activity lines move on a critically damped spring (about 260ms, no bounce), so rows slide and grow without overshoot.
- Completing a step draws its check as a stroke over about 220ms while the disc fades up beneath it, and the title color settles from primary to secondary.
- The current step's title shimmers with Arc's text shimmer beside a spinning arc; pausing stops both and swaps the arc for a pause glyph.
- A suggested step streams its title in chunks of a few words every 34ms, each chunk only fading in. A step the agent inserts arrives with a faint accent wash that fades out over about 1.8s.
- Counts roll with tabular digits in a reserved width. The header label, footer actions and status icons swap with one short crossfade, and the footer's height follows on the same spring.
- Reduced motion keeps every state, label, focus move and announcement but drops travel, the spinner, the stroke draw, the wash and the chunk fades.

### Responsive behavior

- A container query tightens padding below 420px; the step grid keeps a fixed lead and trail column so titles wrap the same way in draft and while running and never shift on approve.
- Draft footer buttons share the row equally on narrow containers, and the done summary wraps above Start over.
- With a mouse the remove button appears on hover or focus; on touch it stays visible. Grips accept touch drags without scrolling the page.
- Reads well from 320px to about 760px wide; the demo caps it at 560px.

### Performance

- The simulation schedules exactly one timer per state change, so pausing simply drops it and nothing runs while the plan is idle.
- Streaming uses one requestAnimationFrame clock with catch-up and appends spans; settled chunks never re-render or re-mount.
- Only transform and opacity animate on rows, except the brief height spring when a row or activity line enters or leaves.
- The shimmer runs only on the active step and only while it is on screen and the page is visible.

### Notes for AI

- Use it for the plan step of a coding or operations agent: the agent proposes steps, a person edits and approves, then the same card tracks execution. It is not an onboarding checklist and not a run log.
- Write step titles as instructions ("Add a sliding window limiter to the API middleware"). Keep substeps to short past-tense activity starting with a verb such as Read, Edited, Created, Searched, Found, Ran or Measured; the verb picks the icon.
- Pass `status` when wiring a real agent. Then the component is fully controlled by `steps` and `status`: set one step to "active" at a time, append substeps as the agent reports them, set "done" with a duration in seconds, and set "failed" with an error to show Retry and Skip.
- Insert steps the agent adds mid-run with `note: "Added by agent"`; they slide in where you place them in the array.
- Keep planning calls onKeepPlanning; add the agent's suggestion to `steps` yourself. In the simulation it streams one of three sample suggestions in before the last step.
- The default model is Claude Opus 5.5 with its brand mark. Pass `model` with your own name and a 16px mark for another model.

### Related

- [Agent run](https://uiarc.dev/components/blocks/agent-run/markdown): A single card that follows one AI coding agent through a task: steps stream in with the live one shimmering, tool calls open in place, and the agent stops on a two-file diff for you to approve or send back before it writes. When the run ends, the steps fold into one line and a result shows the files changed, the checks that passed and a pull request button.
- [Agent tasks](https://uiarc.dev/components/blocks/agent-tasks/markdown): A home for background coding agents: start a task on a repository and branch, watch each card move from queued to running to ready for review, and open a pull request from the result.
- [Agent approvals](https://uiarc.dev/components/blocks/agent-approvals/markdown): One approval card for agents: the waiting tool call reads like a permission prompt with the tool's mark, the agent's reason and its arguments, and you approve, deny or allow it from now on.
- [Agent loop](https://uiarc.dev/components/agent-loop/markdown): An illustration of the agent loop: gather context, take action, verify, repeat, with a bright head circling three stations around the model.
- [AI chat](https://uiarc.dev/components/blocks/ai-chat/markdown): A full-screen AI chat where answers stream in as markdown with folding reasoning, tool chips and cited sources. People can switch chats and models, edit or retry a message into versions, rate replies and stop a reply mid-stream.
- [Text shimmer](https://uiarc.dev/components/text-shimmer/markdown): Show ongoing work with a calm light across the words.

### Also in ai

- [Agent status](https://uiarc.dev/components/agent-status/markdown): A compact live status pill for a running AI agent: the agent's mark in a live ring, the current activity and an elapsed timer, opening into the steps so far.
- [Tool call](https://uiarc.dev/components/tool-call/markdown): A tool call row for agent transcripts: the tool's mark and the call in plain words, a live state while it runs, and the input and output a click away, with approval and retry when needed.
- [Agent timeline](https://uiarc.dev/components/agent-timeline/markdown): A compact timeline of one orchestrated agent run: the orchestrator and its subagents share a time axis, handoffs draw in between rows, and a playhead replays thinking, tool calls and waiting while the header counts time, tokens and cost. Hover a span for what it did, or click it to trace its handoff path.
- [Context window](https://uiarc.dev/components/context-window/markdown): An AI context window as a grid of 200 cells: the system prompt, tools, files, summary and messages fill it in order, a threshold row marks where compaction starts, and sending a message, attaching a file or compacting shows exactly how much still fits.
- [Reasoning block](https://uiarc.dev/components/reasoning-block/markdown): The collapsible thinking block of an AI reply. While the model thinks, a shimmering label counts the seconds and the latest reasoning streams underneath. When it finishes, it folds to "Thought for 7s" and opens to show the full reasoning as calm steps with headings.
- [Source cards](https://uiarc.dev/components/source-cards/markdown): A row of cited sources under an AI answer where cards stream in with real site marks while the model searches, the overflow collapses into a stack of favicons, hovering lifts a preview with the passage, and an inline [n] citation highlights its card.
- [Model card](https://uiarc.dev/components/model-card/markdown): A model details card where switching models rolls every price, limit and score in place, a token slider estimates monthly cost live, and benchmark bars show each model's rank on hover. Compare crossfades to a side-by-side table against any rival with the better values marked, and the card never changes size.
- [AI workflow](https://uiarc.dev/components/ai-workflow/markdown): A Linear-style AI workflow card where a Gmail trigger, a Claude step, a branch and Slack and Linear actions sit on one hairline rail, and a test run glides down it, opening each step's output inline. Steps are added from a compact command menu with real app marks.
- [Code suggestion](https://uiarc.dev/components/code-suggestion/markdown): An AI code edit suggestion where the model's proposed changes stream into a small editor panel as inline diff hunks, and you accept or reject each one, or all at once with Cmd+Enter. Accepted hunks fold into the file with a smooth height change.
- [Ghost text](https://uiarc.dev/components/ghost-text/markdown): An inline AI autocomplete where muted ghost text continues your sentence exactly at the caret and Tab turns it solid in place. Cmd+Right takes it one word at a time, Escape fades it away, and a calm chip shows the model behind it.
- [Image generation](https://uiarc.dev/components/image-generation/markdown): An image studio where each image forms on a dot matrix: a soft halftone wave breathes across the grid, the dots take the colours of the coming photo and grow into a coloured halftone, then blur away into the sharp photo. One large canvas with a mono size label, a filmstrip of four variations, a prompt bar with model and ratio, and upscale with a sweeping dot band, vary or download, with real provider marks and a built-in simulation.
- [Dictation button](https://uiarc.dev/components/dictation-button/markdown): A chat composer with voice input, where the mic springs into a recording pill with a smooth live waveform, a timer, and cancel and insert buttons. Words stream into the field as you speak, muted until the recognizer settles them.
- [Speech player](https://uiarc.dev/components/speech-player/markdown): A read-aloud player for AI replies. The Read aloud button in the message's action row turns into a compact player with play, a scrubbable progress bar, speed and a voice picker, and a highlight follows the spoken word through the reply, karaoke style.
- [Meeting summary](https://uiarc.dev/components/meeting-summary/markdown): An AI meeting notes card: the header shows the Google Meet or Zoom mark, the attendees and the duration. Summary, Decisions and Action items stream in after a short summarizing pass. Hover any line to see the transcript quote it came from, then check off action items or send them to Linear or Notion.
- [Reply draft](https://uiarc.dev/components/reply-draft/markdown): An AI email reply drafter where Claude streams a reply under a received Gmail message. Quick replies steer a fresh draft, tone and length rewrite it with a single crossfade, and you can edit the finished draft before you insert it.
- [Agent handoff](https://uiarc.dev/components/agent-handoff/markdown): A support conversation where an AI assistant hands off to a person. When it transfers, a card shows the summary it passes to the team and the typical wait. The person then joins and takes over, and a thin timeline on the left marks each step.
- [PII redaction](https://uiarc.dev/components/pii-redaction/markdown): A guardrail card where personal data is redacted before the prompt reaches the model. Scan marks each name, email, phone number and card with its type and swaps it for a placeholder like [EMAIL_1]. The safe prompt travels to Claude, and the reply comes back with the original values put back for the person.
- [Response feedback](https://uiarc.dev/components/response-feedback/markdown): A feedback control for AI replies where thumbs down opens an inline panel with reason chips and an optional note, thumbs up fills and asks what was good, and a submit shows a short thank-you before folding back into the row.
- [LLM cost calculator](https://uiarc.dev/components/llm-cost-calculator/markdown): A pricing calculator for LLM workloads. Set tokens per request, requests per day and prompt caching, and eight current models re-rank by monthly cost. Bars glide and prices roll as you drag.
- [Provider keys](https://uiarc.dev/components/provider-keys/markdown): A settings card for bring-your-own-key AI products. Each provider row shows its real mark, the masked key, a status and when the key was last used. You can reveal a key for five seconds, copy, rotate or remove it with undo. Adding or rotating a key opens an inline form that checks the format as you type, then tests the connection before saving.
- [Generation stats](https://uiarc.dev/components/generation-stats/markdown): A live stats strip for a streaming LLM response where time to first token, speed with a sparkline, output tokens and cost count up in tabular numerals beside the model's real mark, then settle and open into a latency and token cost breakdown.
- [AI translate](https://uiarc.dev/components/ai-translate/markdown): A message card where picking a language streams the AI translation in place, sentence by sentence over the dimmed original, with a detected-language chip, a Show original toggle and a status line credited to the model's mark.
- [TL;DR toggle](https://uiarc.dev/components/tldr-toggle/markdown): An article card with a Full, Summary and Key points switch and a length slider. Switching streams an AI summary in place of the article as the card's height springs to fit, and each key point links back to the paragraph it came from, which gets scrolled to and highlighted.
- [Connector setup](https://uiarc.dev/components/connector-setup/markdown): A "Connect your tools" card for an AI assistant. Each app connects inline: it redirects, authorizes and runs a first sync with a progress hairline, then lists the scopes it was granted and offers Disconnect with an inline confirm.
- [Smart form fill](https://uiarc.dev/components/smart-form-fill/markdown): A paste-to-fill form card where AI reads an email signature or messy notes and fills a contact field by field. Each value flashes in with a confidence dot, its source lights up in the pasted text, low-confidence guesses ask for review, and Undo puts the old values back.
- [Enrich column](https://uiarc.dev/components/enrich-column/markdown): An AI enrichment column for a data table, where one prompt runs down every row and each cell shimmers while it works, then settles into a value with its source or a failure you can retry.
- [Ticket router](https://uiarc.dev/components/ticket-router/markdown): A support ticket router where messages from Gmail, Intercom, Slack and Zendesk come in one at a time. An AI classifier labels each one with intent, sentiment and confidence, and the ticket moves into a team lane with an assignee. Low confidence tickets wait in a review lane, and one click there routes them to the suggested team.
- [Ask your data](https://uiarc.dev/components/ask-your-data/markdown): A natural language to chart card: you ask a question, PostgreSQL streams into a collapsible, syntax highlighted panel, the query runs with a rolling row count, and the answer builds as stacked bars, lines or a table, with a one line insight streamed in underneath.
- [Agent cursor](https://uiarc.dev/components/agent-cursor/markdown): A live document where Claude edits like a collaborator. Its labeled cursor comes out of its avatar, selects a paragraph and streams in a rewrite, adds a heading and fixes a typo, while a teammate's cursor reads along. Changes stay tinted until someone accepts or undoes them from a floating review bar.
- [Provider status](https://uiarc.dev/components/provider-status/markdown): A status card for the AI providers your product depends on. Each row shows the provider's real mark, its health as an icon and label, p50 latency and a 30-day uptime bar with a tooltip for each day. An incident row expands into its timeline of updates, and the card checks again on a visible countdown.
- [Training run](https://uiarc.dev/components/training-run/markdown): A fine-tuning job card where a live train and validation loss curve draws across a fixed step axis that doubles as the epoch progress bar. It shows the learning rate, elapsed time, ETA and the latest evals and checkpoints, has Pause and Cancel while it runs, and ends in results with a Deploy button.
- [AI command](https://uiarc.dev/components/ai-command/markdown): A Cmd+K command palette with an AI mode. Search pages and actions, or press Tab to ask a question: the answer streams inside the palette with numbered sources, and the next steps it suggests, like filing a Linear issue or opening a Notion doc, run straight from the list.
- [Starter prompts](https://uiarc.dev/components/starter-prompts/markdown): A greeting and a grid of starter cards for the empty state of an AI app. The cards are grouped into Write, Code, Analyze and Plan tabs, and a shuffle swaps them with a short staggered crossfade. Picking a card fills the composer, and cards that use a connected app show its mark (Gmail, GitHub, Notion, Linear, Google Calendar).
- [AI mascot](https://uiarc.dev/components/ai-mascot/markdown): A small assistant character, a soft pebble with pill eyes and a companion dot, that shows what the AI is doing. It breathes and glances when idle, leans in to listen, looks up while the dot orbits its head, reads along the line it writes, squints with a sparkle when done and shakes once with worried brows on an error.
- [Image reveal](https://uiarc.dev/components/image-reveal/markdown): An image generation canvas where a soft, blurred preview made from the image's own colors sharpens top to bottom behind a soft-edged band. It works the way ChatGPT, Midjourney and Gemini show images forming, with fine film grain, a translucent progress pill and calm queued and error states.
- [AI spark](https://uiarc.dev/components/ai-spark/markdown): A brand-quality animated spark mark. Four tapered rays and four lighter diagonals breathe at rest, ripple while thinking, pulse like a heartbeat while writing, then gather and settle when done. Every status change blends from the pose the mark is already in.
- [Pixel mascot](https://uiarc.dev/components/pixel-mascot/markdown): A pixel-art robot that shows what an AI assistant is doing. It idles, thinks, types, celebrates and errors in frame-stepped sprite animations, and stays crisp at every integer size from 24px to 192px.
- [Ghost mascot](https://uiarc.dev/components/ghost-mascot/markdown): A floating ghost mascot whose soft sheet ripples at the hem while it hovers. It blinks when idle, turns toward you to listen, fades a little translucent while thinking, draws a tiny pen line while writing, smiles with a sparkle when done and wobbles once on an error.
- [Cube mascot](https://uiarc.dev/components/cube-mascot/markdown): An isometric cube mascot where three shaded faces and a painted-on face show what the assistant is doing. It turns a quarter turn in eased steps while thinking, prints lines onto the floor while writing, settles with a sparkle when done, and shakes once on error.
- [Tone tuner](https://uiarc.dev/components/tone-tuner/markdown): A brand voice card where two sliders (formality and detail) and Friendly, Confident and Empathetic chips rewrite a customer reply. Each changed sentence crossfades in place, new words can be highlighted against the original, and Copy takes the current version.
- [Upgrade prompt](https://uiarc.dev/components/upgrade-prompt/markdown): An upgrade nudge for the moment someone hits a limit. It shows a usage meter at 50 of 50 AI credits, a rolling price with a monthly and yearly toggle, three concrete unlocks with real model marks, and Upgrade or Maybe later. Upgrading leads into a success state with the new limits, and the card never changes size between states.
- [Referral card](https://uiarc.dev/components/referral-card/markdown): A give-and-get referral card where people copy or share their invite link, invite friends by email as chips, and watch invites move from invited to signed up to earned, with the credit total counting up and a milestone reward unlocking.
- [Trial banner](https://uiarc.dev/components/trial-banner/markdown): A trial status banner where a ring counts down the days left, the copy names what the workspace loses, and the upgrade path is one click away. It comes as a slim banner, a sidebar card or a header pill. It shifts to a warning tone in the last days, has expired and upgraded states, and folds into the pill when dismissed or snoozed.
- [Team switcher](https://uiarc.dev/components/team-switcher/markdown): A workspace switcher like Linear, Vercel or Slack. The trigger shows the current workspace's logo and plan. The menu has search, your role in each workspace and a Cmd+1 to 9 shortcut for each, and lets you create or join a workspace inline. A highlight glides between rows, and switching crossfades the trigger through a short loading state.
- [Live visitors](https://uiarc.dev/components/live-visitors/markdown): A realtime visitors card where the live count rolls digit by digit, new arrivals ping in on a dotted world map, the top pages reorder with bars, and signups and upgrades tick in with country flags.
- [Social proof toast](https://uiarc.dev/components/social-proof-toast/markdown): A stack of social proof notifications for landing and pricing pages, where recent trials, upgrades and verified purchases from people and companies arrive every few seconds. The stack pauses and fans out on hover, and visitors can dismiss any toast.
- [Install snippet](https://uiarc.dev/components/install-snippet/markdown): A "get started in 30 seconds" card where framework tabs, three numbered steps and highlighted snippets take a developer from install to first event. Generate key wipes a fresh API key into the placeholder in place.

### Guidance for AI tools

Agent plan: The plan an agent writes before it acts: edit, reorder or add steps while it is a draft, then watch it work through them as a live checklist. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Agent timeline

> A compact timeline of one orchestrated agent run: the orchestrator and its subagents share a time axis, handoffs draw in between rows, and a playhead replays thinking, tool calls and waiting while the header counts time, tokens and cost. Hover a span for what it did, or click it to trace its handoff path.

- Type: Component (special)
- Access: Arc Pro
- Page: https://uiarc.dev/components/agent-timeline
- Markdown: https://uiarc.dev/components/agent-timeline/markdown
- Source file: `registry/components/agent-timeline/agent-timeline.tsx`
- Dependencies: motion, lucide-react
- Keywords: special, motion, ai, new, agent timeline, multi-agent, orchestrator, subagents, agent trace, gantt, handoff, tool calls, run replay, playhead, scrubber, tokens, cost, parallel agents, llm

### When to use

- Showing how an orchestrator split work across subagents and how long each part took, in a run history, a trace viewer or a debugging panel.
- Replaying a finished agent run in a product demo or changelog, with real numbers for time, tokens and cost.
- Following a multi-agent run live as events stream in from your backend.

### When not to use

- Use agent-orchestrator for a full screen of agent lanes with streaming text and messages; this timeline is the compact, reusable view of timing.
- Use observability-trace for distributed request tracing across services rather than agents.
- Use agent-run or research-run when people need the agent's steps, sources and answer, not the timing.
- Use tool-call for the detail of a single tool invocation, and agent-status for one agent's current state.

### Installation

Agent timeline is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/agent-timeline
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { AgentTimeline } from "@/components/arc/agent-timeline/agent-timeline";

// The sample run, replaying.
<AgentTimeline />

// A finished run from your traces renders complete, ready to replay.
<AgentTimeline
  run={{
    title: "Weekly churn report",
    agents: [
      { id: "lead", name: "Orchestrator", model: "Claude Opus 5.5", price: 8 },
      { id: "sql", name: "Analyst", model: "Claude Haiku 5.5", price: 0.2 },
    ],
    spans: [
      { agentId: "lead", kind: "thinking", start: 0, end: 1.4, label: "Planned the report", tokens: 1200 },
      { agentId: "lead", kind: "waiting", start: 1.4, end: 6.2, label: "Waiting on the analyst" },
      { agentId: "sql", kind: "tool", tool: "PostgreSQL", start: 1.7, end: 4.1, label: "Pulled churn by plan", tokens: 2400 },
      { agentId: "sql", kind: "thinking", start: 4.1, end: 5.9, label: "Summarized the numbers", tokens: 900 },
    ],
    handoffs: [
      { from: "lead", to: "sql", at: 1.4, label: "Churn by plan, last 8 weeks" },
      { from: "sql", to: "lead", at: 6.2, label: "Churn is up on the Team plan" },
    ],
  }}
  onSpanSelect={span => console.log(span?.label)}
/>

// Live: keep appending events to the run, leave end off open spans.
<AgentTimeline run={liveRun} live={status === "running"} />
```

### API reference

#### AgentTimeline

A compact timeline of one orchestrated agent run. Each row is an agent with a color dot, its name and its model with the provider mark, the orchestrator on top. Spans on a shared time axis show thinking (a tint of the agent color), tool calls (solid) and waiting (hatched), and thin elbow connectors show work handed to a subagent and results coming back, with a dot where they meet the orchestrator. The run replays live: a playhead sweeps, the active span grows with a square leading edge and a short shine, connectors draw in as handoffs happen, and the header counts elapsed time, tokens and cost until it settles into a summary such as "5 agents · 26.4s · 1.5x faster than sequential · $0.16". Hover or focus a span for a card with what it did, its tool, duration, tokens and handoffs; click to pin it and dim everything off its handoff path. A failed tool call turns into a cross with a Failed label when it ends, and its retry shows a retry icon. Play, pause, restart, a speed control and scrubbing along the axis drive the replay; passing a finished run renders it complete, and live mode follows a run in progress.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `run` | `AgentTimelineRun` | `sampleRun` | The run: { title?, agents, spans, handoffs?, duration?, startedAt? }. Rows follow agents in order and the first agent is the orchestrator. Defaults to a sample incident investigation with five agents, a failed query and a retry. |
| `agents` | `AgentTimelineAgent[]` | – | Overrides run.agents. Each agent is { id, name, model?, role?, color?, mark?, price? }. color defaults to neutral for the first agent and --series-1 to --series-4 after it; mark is inferred from the model name for Claude, GPT and Gemini; price is a blended USD rate per million tokens used for cost. |
| `spans` | `AgentTimelineSpan[]` | – | Overrides run.spans. Each span is { id?, agentId, kind: "thinking" \| "tool" \| "waiting", start, end?, label, detail?, tool?, tokens?, cost?, status?: "ok" \| "failed", retry? } with times in seconds from the start of the run. tool is a name (GitHub, Web search, PostgreSQL and Notion have built-in marks) or { name, mark }. Leave end out while a span is open in a live run. |
| `handoffs` | `AgentTimelineHandoff[]` | – | Overrides run.handoffs. Each handoff is { from, to, at, label? }. The connector shape is inferred: a dispatch drops from the source at `at` and enters the target's next span, a result leaves the end of the source's last span and rises into the target. |
| `title` | `string` | – | Heading. Defaults to run.title, then "Agent run". |
| `autoPlay` | `boolean` | `true for the sample, false with data` | Replay from zero when the timeline scrolls into view. Without it a run renders finished, ready to replay. Reduced motion always starts finished until the person presses play. |
| `speed` | `number` | `1` | Starting playback speed. 1 is real time. |
| `speeds` | `number[]` | `[1, 2]` | Options in the speed control. The control hides when only one speed remains. |
| `live` | `boolean` | `false` | Follow a run in progress: the clock runs from run.startedAt (epoch ms) or from mount, open spans grow to now, the axis extends in calm steps and the playback controls hide. Append spans and handoffs as events arrive and set live to false when the run ends; the timeline settles on the summary. |
| `onSpanSelect` | `(span: AgentTimelineSpan \| null) => void` | – | Called when a span is pinned, with the span, or unpinned, with null. |
| `onComplete` | `() => void` | – | Called once each time a replay reaches the end or a live run ends. |
| `className` | `string` | – | Class on the root element. |
| `style` | `CSSProperties` | – | Inline style on the root, for example to override --series-1 to --series-4. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Tab | Moves to the timeline's spans (one tab stop), the time scrubber, then play or pause, restart and the speed control. |
| Arrow left / Arrow right | On a span, moves to the previous or next span in the same row. On the scrubber, steps time by half a second; with Shift, by five seconds. |
| Arrow up / Arrow down | On a span, moves to the nearest span in the row above or below. |
| Home / End | On a span, jumps to the first or last span in its row. On the scrubber, jumps to the start or the end of the run. |
| Page up / Page down | On the scrubber, steps time by five seconds. |
| Enter, Space | On a span, pins it and highlights its handoff path; again to unpin. |
| Escape | Unpins the pinned span. |

### Accessibility

- The root is a labelled section. Each row of spans is a group named by its agent label, and every span is a button whose name reads the agent, the kind, the tool, failure, what it did, its time range and tokens; aria-pressed marks the pinned span.
- Spans use a roving tab index, so the chart is one tab stop and arrow keys move between spans by row and by time.
- The scrubber is a slider with a value text such as "12.4s of 26.4s" and full keyboard support; dragging anywhere on the axis moves it.
- Status is never color alone: a failed call shows a cross icon and the word Failed in its card and the legend, a retry shows a retry icon and its note, and the finished state shows a check with the summary.
- A polite live region announces replay, pause and the finished summary. The counting status line is not live, so it never floods a screen reader.
- The span card repeats what the span's accessible name already says, so it is hidden from assistive technology.
- Pointer focus draws no ring; keyboard focus shows Arc's shared focus ring on spans, the scrubber thumb and the controls.

### Motion

- Bars and the playhead read one CSS variable for the current time, updated every animation frame, so spans grow smoothly without React rendering per frame; React updates counters and states about twenty times a second.
- An active span has a square, solid leading edge and a short shine that stops when it ends; its corner rounds off as it completes. A failed call changes to its failed look with a quick color fade when it returns.
- Connectors draw in with a clip reveal from the side the handoff leaves, about 360ms, and the port dot pops in at the start of a dispatch or after a result lands.
- The span card glides between spans on the morph spring, crossfades its content and springs to its new height; the status line and play button swap with one minimal crossfade.
- When the run ends the playhead fades out and the status settles into the summary.
- Reduced motion starts on the finished run and drops the shine, the connector draw, the card glide and the status crossfades. Playback still works when the person asks for it.

### Responsive behavior

- Fills its container up to the canvas width. Below a 520px container the label column narrows to dot and name, and the model moves into the span card.
- When the plot would be narrower than 300px it scrolls horizontally inside its own frame with the agent labels pinned, and the replay keeps the playhead in view unless the person has just scrolled.
- The status line wraps after a separator, never before, and the counters reserve the width of their final value, so the header never shifts while it counts.
- Hover cards are anchored inside the component and flip below the row when there is no room above.

### Performance

- The run is normalized once per data change: spans sorted, connector shapes and totals memoized.
- Per frame the clock writes one CSS variable; widths, the playhead and connectors are pure CSS from it. React re-renders at most about twenty times a second while playing, and memoized span buttons only update when their state changes.
- The replay clock only runs while the timeline is in view, and stops when the run ends.
- Handles a few hundred spans comfortably; for long traces, pass a window of the run or aggregate tiny spans.

### Notes for AI

- Choose it to show one orchestrated multi-agent run as a timeline: which agent did what, when, in parallel, with handoffs. It fits a card 360 to 760px wide.
- Put the orchestrator first. Order subagents so connectors pass through idle rows: the agent that returns first sits right under the orchestrator, and dispatches go to the deepest row first.
- Give each handoff a time that matches the spans around it: a dispatch just before the target's first span, a result just after the source's last span. The shape is inferred from those gaps.
- Use kind "waiting" for an agent that is blocked on others, so parallelism and idle time read at a glance and the summary's speedup counts only real work.
- Mark a failed tool call with status "failed" and a detail message, and the call that retried it with retry: true.
- Real model and tool marks are built in by name; pass mark for anything else. Brand marks are sample content, never implied endorsements.

### Related

- [Agent orchestrator](https://uiarc.dev/components/blocks/agent-orchestrator/markdown): A lead agent splits a goal into a plan, fans the subtasks out to parallel worker lanes and merges what comes back, with each lane's model, progress and result in view.
- [Agent run](https://uiarc.dev/components/blocks/agent-run/markdown): A single card that follows one AI coding agent through a task: steps stream in with the live one shimmering, tool calls open in place, and the agent stops on a two-file diff for you to approve or send back before it writes. When the run ends, the steps fold into one line and a result shows the files changed, the checks that passed and a pull request button.
- [Research run](https://uiarc.dev/components/blocks/research-run/markdown): Deep research that plans searches, reads sources with their marks, and streams a cited answer where every chip lights up the sentence it supports.
- [Tool call](https://uiarc.dev/components/tool-call/markdown): A tool call row for agent transcripts: the tool's mark and the call in plain words, a live state while it runs, and the input and output a click away, with approval and retry when needed.
- [Agent status](https://uiarc.dev/components/agent-status/markdown): A compact live status pill for a running AI agent: the agent's mark in a live ring, the current activity and an elapsed timer, opening into the steps so far.
- [Agent plan](https://uiarc.dev/components/agent-plan/markdown): The plan an agent writes before it acts: edit, reorder or add steps while it is a draft, then watch it work through them as a live checklist.
- [Context window](https://uiarc.dev/components/context-window/markdown): An AI context window as a grid of 200 cells: the system prompt, tools, files, summary and messages fill it in order, a threshold row marks where compaction starts, and sending a message, attaching a file or compacting shows exactly how much still fits.

### Also in ai

- [Reasoning block](https://uiarc.dev/components/reasoning-block/markdown): The collapsible thinking block of an AI reply. While the model thinks, a shimmering label counts the seconds and the latest reasoning streams underneath. When it finishes, it folds to "Thought for 7s" and opens to show the full reasoning as calm steps with headings.
- [Source cards](https://uiarc.dev/components/source-cards/markdown): A row of cited sources under an AI answer where cards stream in with real site marks while the model searches, the overflow collapses into a stack of favicons, hovering lifts a preview with the passage, and an inline [n] citation highlights its card.
- [Model card](https://uiarc.dev/components/model-card/markdown): A model details card where switching models rolls every price, limit and score in place, a token slider estimates monthly cost live, and benchmark bars show each model's rank on hover. Compare crossfades to a side-by-side table against any rival with the better values marked, and the card never changes size.
- [AI workflow](https://uiarc.dev/components/ai-workflow/markdown): A Linear-style AI workflow card where a Gmail trigger, a Claude step, a branch and Slack and Linear actions sit on one hairline rail, and a test run glides down it, opening each step's output inline. Steps are added from a compact command menu with real app marks.
- [Code suggestion](https://uiarc.dev/components/code-suggestion/markdown): An AI code edit suggestion where the model's proposed changes stream into a small editor panel as inline diff hunks, and you accept or reject each one, or all at once with Cmd+Enter. Accepted hunks fold into the file with a smooth height change.
- [Ghost text](https://uiarc.dev/components/ghost-text/markdown): An inline AI autocomplete where muted ghost text continues your sentence exactly at the caret and Tab turns it solid in place. Cmd+Right takes it one word at a time, Escape fades it away, and a calm chip shows the model behind it.
- [Image generation](https://uiarc.dev/components/image-generation/markdown): An image studio where each image forms on a dot matrix: a soft halftone wave breathes across the grid, the dots take the colours of the coming photo and grow into a coloured halftone, then blur away into the sharp photo. One large canvas with a mono size label, a filmstrip of four variations, a prompt bar with model and ratio, and upscale with a sweeping dot band, vary or download, with real provider marks and a built-in simulation.
- [Dictation button](https://uiarc.dev/components/dictation-button/markdown): A chat composer with voice input, where the mic springs into a recording pill with a smooth live waveform, a timer, and cancel and insert buttons. Words stream into the field as you speak, muted until the recognizer settles them.
- [Speech player](https://uiarc.dev/components/speech-player/markdown): A read-aloud player for AI replies. The Read aloud button in the message's action row turns into a compact player with play, a scrubbable progress bar, speed and a voice picker, and a highlight follows the spoken word through the reply, karaoke style.
- [Meeting summary](https://uiarc.dev/components/meeting-summary/markdown): An AI meeting notes card: the header shows the Google Meet or Zoom mark, the attendees and the duration. Summary, Decisions and Action items stream in after a short summarizing pass. Hover any line to see the transcript quote it came from, then check off action items or send them to Linear or Notion.
- [Reply draft](https://uiarc.dev/components/reply-draft/markdown): An AI email reply drafter where Claude streams a reply under a received Gmail message. Quick replies steer a fresh draft, tone and length rewrite it with a single crossfade, and you can edit the finished draft before you insert it.
- [Agent handoff](https://uiarc.dev/components/agent-handoff/markdown): A support conversation where an AI assistant hands off to a person. When it transfers, a card shows the summary it passes to the team and the typical wait. The person then joins and takes over, and a thin timeline on the left marks each step.
- [PII redaction](https://uiarc.dev/components/pii-redaction/markdown): A guardrail card where personal data is redacted before the prompt reaches the model. Scan marks each name, email, phone number and card with its type and swaps it for a placeholder like [EMAIL_1]. The safe prompt travels to Claude, and the reply comes back with the original values put back for the person.
- [Response feedback](https://uiarc.dev/components/response-feedback/markdown): A feedback control for AI replies where thumbs down opens an inline panel with reason chips and an optional note, thumbs up fills and asks what was good, and a submit shows a short thank-you before folding back into the row.
- [LLM cost calculator](https://uiarc.dev/components/llm-cost-calculator/markdown): A pricing calculator for LLM workloads. Set tokens per request, requests per day and prompt caching, and eight current models re-rank by monthly cost. Bars glide and prices roll as you drag.
- [Provider keys](https://uiarc.dev/components/provider-keys/markdown): A settings card for bring-your-own-key AI products. Each provider row shows its real mark, the masked key, a status and when the key was last used. You can reveal a key for five seconds, copy, rotate or remove it with undo. Adding or rotating a key opens an inline form that checks the format as you type, then tests the connection before saving.
- [Generation stats](https://uiarc.dev/components/generation-stats/markdown): A live stats strip for a streaming LLM response where time to first token, speed with a sparkline, output tokens and cost count up in tabular numerals beside the model's real mark, then settle and open into a latency and token cost breakdown.
- [AI translate](https://uiarc.dev/components/ai-translate/markdown): A message card where picking a language streams the AI translation in place, sentence by sentence over the dimmed original, with a detected-language chip, a Show original toggle and a status line credited to the model's mark.
- [TL;DR toggle](https://uiarc.dev/components/tldr-toggle/markdown): An article card with a Full, Summary and Key points switch and a length slider. Switching streams an AI summary in place of the article as the card's height springs to fit, and each key point links back to the paragraph it came from, which gets scrolled to and highlighted.
- [Connector setup](https://uiarc.dev/components/connector-setup/markdown): A "Connect your tools" card for an AI assistant. Each app connects inline: it redirects, authorizes and runs a first sync with a progress hairline, then lists the scopes it was granted and offers Disconnect with an inline confirm.
- [Smart form fill](https://uiarc.dev/components/smart-form-fill/markdown): A paste-to-fill form card where AI reads an email signature or messy notes and fills a contact field by field. Each value flashes in with a confidence dot, its source lights up in the pasted text, low-confidence guesses ask for review, and Undo puts the old values back.
- [Enrich column](https://uiarc.dev/components/enrich-column/markdown): An AI enrichment column for a data table, where one prompt runs down every row and each cell shimmers while it works, then settles into a value with its source or a failure you can retry.
- [Ticket router](https://uiarc.dev/components/ticket-router/markdown): A support ticket router where messages from Gmail, Intercom, Slack and Zendesk come in one at a time. An AI classifier labels each one with intent, sentiment and confidence, and the ticket moves into a team lane with an assignee. Low confidence tickets wait in a review lane, and one click there routes them to the suggested team.
- [Ask your data](https://uiarc.dev/components/ask-your-data/markdown): A natural language to chart card: you ask a question, PostgreSQL streams into a collapsible, syntax highlighted panel, the query runs with a rolling row count, and the answer builds as stacked bars, lines or a table, with a one line insight streamed in underneath.
- [Agent cursor](https://uiarc.dev/components/agent-cursor/markdown): A live document where Claude edits like a collaborator. Its labeled cursor comes out of its avatar, selects a paragraph and streams in a rewrite, adds a heading and fixes a typo, while a teammate's cursor reads along. Changes stay tinted until someone accepts or undoes them from a floating review bar.
- [Provider status](https://uiarc.dev/components/provider-status/markdown): A status card for the AI providers your product depends on. Each row shows the provider's real mark, its health as an icon and label, p50 latency and a 30-day uptime bar with a tooltip for each day. An incident row expands into its timeline of updates, and the card checks again on a visible countdown.
- [Training run](https://uiarc.dev/components/training-run/markdown): A fine-tuning job card where a live train and validation loss curve draws across a fixed step axis that doubles as the epoch progress bar. It shows the learning rate, elapsed time, ETA and the latest evals and checkpoints, has Pause and Cancel while it runs, and ends in results with a Deploy button.
- [AI command](https://uiarc.dev/components/ai-command/markdown): A Cmd+K command palette with an AI mode. Search pages and actions, or press Tab to ask a question: the answer streams inside the palette with numbered sources, and the next steps it suggests, like filing a Linear issue or opening a Notion doc, run straight from the list.
- [Starter prompts](https://uiarc.dev/components/starter-prompts/markdown): A greeting and a grid of starter cards for the empty state of an AI app. The cards are grouped into Write, Code, Analyze and Plan tabs, and a shuffle swaps them with a short staggered crossfade. Picking a card fills the composer, and cards that use a connected app show its mark (Gmail, GitHub, Notion, Linear, Google Calendar).
- [AI mascot](https://uiarc.dev/components/ai-mascot/markdown): A small assistant character, a soft pebble with pill eyes and a companion dot, that shows what the AI is doing. It breathes and glances when idle, leans in to listen, looks up while the dot orbits its head, reads along the line it writes, squints with a sparkle when done and shakes once with worried brows on an error.
- [Image reveal](https://uiarc.dev/components/image-reveal/markdown): An image generation canvas where a soft, blurred preview made from the image's own colors sharpens top to bottom behind a soft-edged band. It works the way ChatGPT, Midjourney and Gemini show images forming, with fine film grain, a translucent progress pill and calm queued and error states.
- [AI spark](https://uiarc.dev/components/ai-spark/markdown): A brand-quality animated spark mark. Four tapered rays and four lighter diagonals breathe at rest, ripple while thinking, pulse like a heartbeat while writing, then gather and settle when done. Every status change blends from the pose the mark is already in.
- [Pixel mascot](https://uiarc.dev/components/pixel-mascot/markdown): A pixel-art robot that shows what an AI assistant is doing. It idles, thinks, types, celebrates and errors in frame-stepped sprite animations, and stays crisp at every integer size from 24px to 192px.
- [Ghost mascot](https://uiarc.dev/components/ghost-mascot/markdown): A floating ghost mascot whose soft sheet ripples at the hem while it hovers. It blinks when idle, turns toward you to listen, fades a little translucent while thinking, draws a tiny pen line while writing, smiles with a sparkle when done and wobbles once on an error.
- [Cube mascot](https://uiarc.dev/components/cube-mascot/markdown): An isometric cube mascot where three shaded faces and a painted-on face show what the assistant is doing. It turns a quarter turn in eased steps while thinking, prints lines onto the floor while writing, settles with a sparkle when done, and shakes once on error.
- [Tone tuner](https://uiarc.dev/components/tone-tuner/markdown): A brand voice card where two sliders (formality and detail) and Friendly, Confident and Empathetic chips rewrite a customer reply. Each changed sentence crossfades in place, new words can be highlighted against the original, and Copy takes the current version.
- [Upgrade prompt](https://uiarc.dev/components/upgrade-prompt/markdown): An upgrade nudge for the moment someone hits a limit. It shows a usage meter at 50 of 50 AI credits, a rolling price with a monthly and yearly toggle, three concrete unlocks with real model marks, and Upgrade or Maybe later. Upgrading leads into a success state with the new limits, and the card never changes size between states.
- [Referral card](https://uiarc.dev/components/referral-card/markdown): A give-and-get referral card where people copy or share their invite link, invite friends by email as chips, and watch invites move from invited to signed up to earned, with the credit total counting up and a milestone reward unlocking.
- [Trial banner](https://uiarc.dev/components/trial-banner/markdown): A trial status banner where a ring counts down the days left, the copy names what the workspace loses, and the upgrade path is one click away. It comes as a slim banner, a sidebar card or a header pill. It shifts to a warning tone in the last days, has expired and upgraded states, and folds into the pill when dismissed or snoozed.
- [Team switcher](https://uiarc.dev/components/team-switcher/markdown): A workspace switcher like Linear, Vercel or Slack. The trigger shows the current workspace's logo and plan. The menu has search, your role in each workspace and a Cmd+1 to 9 shortcut for each, and lets you create or join a workspace inline. A highlight glides between rows, and switching crossfades the trigger through a short loading state.
- [Live visitors](https://uiarc.dev/components/live-visitors/markdown): A realtime visitors card where the live count rolls digit by digit, new arrivals ping in on a dotted world map, the top pages reorder with bars, and signups and upgrades tick in with country flags.
- [Social proof toast](https://uiarc.dev/components/social-proof-toast/markdown): A stack of social proof notifications for landing and pricing pages, where recent trials, upgrades and verified purchases from people and companies arrive every few seconds. The stack pauses and fans out on hover, and visitors can dismiss any toast.
- [Install snippet](https://uiarc.dev/components/install-snippet/markdown): A "get started in 30 seconds" card where framework tabs, three numbered steps and highlighted snippets take a developer from install to first event. Generate key wipes a fresh API key into the placeholder in place.

### Guidance for AI tools

Agent timeline: A compact timeline of one orchestrated agent run: the orchestrator and its subagents share a time axis, handoffs draw in between rows, and a playhead replays thinking, tool calls and waiting while the header counts time, tokens and cost. Hover a span for what it did, or click it to trace its handoff path. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Context window

> An AI context window as a grid of 200 cells: the system prompt, tools, files, summary and messages fill it in order, a threshold row marks where compaction starts, and sending a message, attaching a file or compacting shows exactly how much still fits.

- Type: Component (special)
- Access: Arc Pro
- Page: https://uiarc.dev/components/context-window
- Markdown: https://uiarc.dev/components/context-window/markdown
- Source file: `registry/components/context-window/context-window.tsx`
- Dependencies: motion, lucide-react, @radix-ui/react-dropdown-menu
- Keywords: special, ai, tokens, chart, motion, new, context window, token usage, llm context, compaction, summarize conversation, prompt tokens, mcp tools tokens, output reserve, ai session, token budget

### When to use

- Showing developers or power users what fills a model's context and when it will compact.
- Agent and coding tools that compact long sessions and want the effect to be understandable.
- Docs and onboarding that explain context windows, compaction and output reserves.

### When not to use

- A simple quota or plan usage bar; use usage-meter.
- Choosing a model; use model-picker.
- Billing or spend over time; use usage-billing.

### Installation

Context window is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/context-window
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { ContextWindow } from "@/components/arc/context-window/context-window";

export function SessionContext({ items }) {
  return (
    <ContextWindow
      items={items}
      threshold={0.8}
      onCompact={({ folded, summary }) => console.log(`Folded ${folded} tokens into ${summary}`)}
    />
  );
}
```

### API reference

#### ContextWindow

A model's context window shown as a fixed budget of 200 cells that fills in reading order: system prompt, tools, files and memory, a summary, then the conversation, followed by free space, with the output reserve held as outlined cells at the end. A dashed line marks the compaction threshold. Send message and Attach file add tokens; crossing the threshold, switching to a smaller model or pressing Compact now folds the older messages into a short summary and the space comes back. A legend lists every part with tokens and percent, adding up to 100%.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `models` | `ContextModel[]` | `sampleModels` | Models to switch between, each { id, name, window, reserve, mark, color? } with window and reserve in tokens. The sample uses Claude Opus 5.5's real 1M window; reserves and the other two models are sample settings. |
| `defaultModelId` | `string` | – | The model shown first. Defaults to the first model. |
| `onModelChange` | `(model: ContextModel) => void` | – | Called when someone switches models. |
| `items` | `ContextItem[]` | `sampleItems` | What is in the window: { id, category, label, tokens } with category "system", "tools", "files", "summary" or "messages". Items are grouped by category for the grid, so their order only matters within a category. |
| `threshold` | `number` | `0.8` | Fraction of the window at which compaction runs on its own. |
| `turns` | `ContextTurn[]` | `sampleTurns` | Turns that Send message adds, in order, each { label, tokens }: a message plus the tool results and reply it produced. |
| `files` | `ContextTurn[]` | `sampleFiles` | Files that Attach file adds, in order. |
| `summarize` | `(folded: ContextItem[]) => number` | – | Returns the summary size in tokens for the folded messages. Defaults to about 6% of them, between 4K and 24K. |
| `onCompact` | `(compaction: ContextCompaction) => void` | – | Called after each compaction with { folded, summary, before, after, automatic }. |
| `onItemsChange` | `(items: ContextItem[]) => void` | – | Called with the new items after a send, an attachment or a compaction. |
| `className` | `string` | – | Class on the root section. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Tab | Moves through the model menu, Send message, Attach file and Compact now. |
| Enter, Space | Opens the model menu or runs an action. |
| Arrow up / Arrow down, Enter | In the model menu, moves between models and chooses one. |
| Escape | Closes the model menu and returns focus to its trigger. |

### Accessibility

- The grid is one image with a full text description: model, tokens used, every category with its tokens, and the threshold.
- The legend is a list with tokens and percent for each part, so nothing depends on color.
- Every send, attachment, model switch and compaction is announced through a polite status line with an icon and text.
- The model menu is a Radix dropdown with radio items; the trigger names the model and its window.
- Pointer focus draws no ring; keyboard focus shows Arc's shared ring.

### Motion

- New tokens fill cells in a short wave from where the change happened, about 4 to 9ms per cell and never more than 360ms in total.
- Compaction dims the messages in one sweep from oldest to newest, then the summary lands right after the files and the freed cells turn back to free space in the same wave.
- Switching models re-scales every cell in one quick pass from the first cell.
- Token counts and percentages roll to their new values; status lines crossfade in place.
- Pointing at a legend row lights its cells and quiets the rest.
- Reduced motion changes cells and numbers at once and keeps every status line.

### Responsive behavior

- On wide containers the legend sits beside the grid; below 640px it moves under the grid and the cells tighten.
- Below 420px the header stacks, with the model menu under the token readout.
- Cells are square and fluid, so the grid always fills its column without horizontal scroll.

### Performance

- 200 cells are plain spans whose color changes through CSS transitions with a per-cell delay; nothing re-renders per frame except the rolling numbers.
- The layout is recomputed only when the items or the model change.

### Notes for AI

- Feed it the real token usage of a session: system prompt, tool definitions (for example MCP servers), attached files and memory, any summary and the messages.
- Keep reserve equal to the max output you request, so the grid shows the space the reply needs.
- Use onCompact to run your own summarization when the threshold is crossed; pass summarize to report the real summary size.
- The 200 cell grid is fixed, so each cell is window / 200 tokens; the note under the grid says how many.

### Related

- [Model picker](https://uiarc.dev/components/blocks/model-picker/markdown): A model picker in one quiet pill: open it to choose from featured models with a one line note each, set the reasoning effort, or browse every other model by provider, and the pill swaps to your choice in place.
- [AI composer](https://uiarc.dev/components/blocks/ai-composer/markdown): The prompt box at the bottom of an AI app: files upload in place, / opens commands, @ inserts mentions, a model and effort menu sits in the toolbar, and the send button turns into a stop control ringed by the reply's progress.
- [Agent run](https://uiarc.dev/components/blocks/agent-run/markdown): A single card that follows one AI coding agent through a task: steps stream in with the live one shimmering, tool calls open in place, and the agent stops on a two-file diff for you to approve or send back before it writes. When the run ends, the steps fold into one line and a result shows the files changed, the checks that passed and a pull request button.
- [Usage meter](https://uiarc.dev/components/usage-meter/markdown): Show what fills an allowance and how close it is to the limit.
- [AI chat](https://uiarc.dev/components/blocks/ai-chat/markdown): A full-screen AI chat where answers stream in as markdown with folding reasoning, tool chips and cited sources. People can switch chats and models, edit or retry a message into versions, rate replies and stop a reply mid-stream.

### Also in ai

- [Agent status](https://uiarc.dev/components/agent-status/markdown): A compact live status pill for a running AI agent: the agent's mark in a live ring, the current activity and an elapsed timer, opening into the steps so far.
- [Tool call](https://uiarc.dev/components/tool-call/markdown): A tool call row for agent transcripts: the tool's mark and the call in plain words, a live state while it runs, and the input and output a click away, with approval and retry when needed.
- [Agent plan](https://uiarc.dev/components/agent-plan/markdown): The plan an agent writes before it acts: edit, reorder or add steps while it is a draft, then watch it work through them as a live checklist.
- [Agent timeline](https://uiarc.dev/components/agent-timeline/markdown): A compact timeline of one orchestrated agent run: the orchestrator and its subagents share a time axis, handoffs draw in between rows, and a playhead replays thinking, tool calls and waiting while the header counts time, tokens and cost. Hover a span for what it did, or click it to trace its handoff path.
- [Reasoning block](https://uiarc.dev/components/reasoning-block/markdown): The collapsible thinking block of an AI reply. While the model thinks, a shimmering label counts the seconds and the latest reasoning streams underneath. When it finishes, it folds to "Thought for 7s" and opens to show the full reasoning as calm steps with headings.
- [Source cards](https://uiarc.dev/components/source-cards/markdown): A row of cited sources under an AI answer where cards stream in with real site marks while the model searches, the overflow collapses into a stack of favicons, hovering lifts a preview with the passage, and an inline [n] citation highlights its card.
- [Model card](https://uiarc.dev/components/model-card/markdown): A model details card where switching models rolls every price, limit and score in place, a token slider estimates monthly cost live, and benchmark bars show each model's rank on hover. Compare crossfades to a side-by-side table against any rival with the better values marked, and the card never changes size.
- [AI workflow](https://uiarc.dev/components/ai-workflow/markdown): A Linear-style AI workflow card where a Gmail trigger, a Claude step, a branch and Slack and Linear actions sit on one hairline rail, and a test run glides down it, opening each step's output inline. Steps are added from a compact command menu with real app marks.
- [Code suggestion](https://uiarc.dev/components/code-suggestion/markdown): An AI code edit suggestion where the model's proposed changes stream into a small editor panel as inline diff hunks, and you accept or reject each one, or all at once with Cmd+Enter. Accepted hunks fold into the file with a smooth height change.
- [Ghost text](https://uiarc.dev/components/ghost-text/markdown): An inline AI autocomplete where muted ghost text continues your sentence exactly at the caret and Tab turns it solid in place. Cmd+Right takes it one word at a time, Escape fades it away, and a calm chip shows the model behind it.
- [Image generation](https://uiarc.dev/components/image-generation/markdown): An image studio where each image forms on a dot matrix: a soft halftone wave breathes across the grid, the dots take the colours of the coming photo and grow into a coloured halftone, then blur away into the sharp photo. One large canvas with a mono size label, a filmstrip of four variations, a prompt bar with model and ratio, and upscale with a sweeping dot band, vary or download, with real provider marks and a built-in simulation.
- [Dictation button](https://uiarc.dev/components/dictation-button/markdown): A chat composer with voice input, where the mic springs into a recording pill with a smooth live waveform, a timer, and cancel and insert buttons. Words stream into the field as you speak, muted until the recognizer settles them.
- [Speech player](https://uiarc.dev/components/speech-player/markdown): A read-aloud player for AI replies. The Read aloud button in the message's action row turns into a compact player with play, a scrubbable progress bar, speed and a voice picker, and a highlight follows the spoken word through the reply, karaoke style.
- [Meeting summary](https://uiarc.dev/components/meeting-summary/markdown): An AI meeting notes card: the header shows the Google Meet or Zoom mark, the attendees and the duration. Summary, Decisions and Action items stream in after a short summarizing pass. Hover any line to see the transcript quote it came from, then check off action items or send them to Linear or Notion.
- [Reply draft](https://uiarc.dev/components/reply-draft/markdown): An AI email reply drafter where Claude streams a reply under a received Gmail message. Quick replies steer a fresh draft, tone and length rewrite it with a single crossfade, and you can edit the finished draft before you insert it.
- [Agent handoff](https://uiarc.dev/components/agent-handoff/markdown): A support conversation where an AI assistant hands off to a person. When it transfers, a card shows the summary it passes to the team and the typical wait. The person then joins and takes over, and a thin timeline on the left marks each step.
- [PII redaction](https://uiarc.dev/components/pii-redaction/markdown): A guardrail card where personal data is redacted before the prompt reaches the model. Scan marks each name, email, phone number and card with its type and swaps it for a placeholder like [EMAIL_1]. The safe prompt travels to Claude, and the reply comes back with the original values put back for the person.
- [Response feedback](https://uiarc.dev/components/response-feedback/markdown): A feedback control for AI replies where thumbs down opens an inline panel with reason chips and an optional note, thumbs up fills and asks what was good, and a submit shows a short thank-you before folding back into the row.
- [LLM cost calculator](https://uiarc.dev/components/llm-cost-calculator/markdown): A pricing calculator for LLM workloads. Set tokens per request, requests per day and prompt caching, and eight current models re-rank by monthly cost. Bars glide and prices roll as you drag.
- [Provider keys](https://uiarc.dev/components/provider-keys/markdown): A settings card for bring-your-own-key AI products. Each provider row shows its real mark, the masked key, a status and when the key was last used. You can reveal a key for five seconds, copy, rotate or remove it with undo. Adding or rotating a key opens an inline form that checks the format as you type, then tests the connection before saving.
- [Generation stats](https://uiarc.dev/components/generation-stats/markdown): A live stats strip for a streaming LLM response where time to first token, speed with a sparkline, output tokens and cost count up in tabular numerals beside the model's real mark, then settle and open into a latency and token cost breakdown.
- [AI translate](https://uiarc.dev/components/ai-translate/markdown): A message card where picking a language streams the AI translation in place, sentence by sentence over the dimmed original, with a detected-language chip, a Show original toggle and a status line credited to the model's mark.
- [TL;DR toggle](https://uiarc.dev/components/tldr-toggle/markdown): An article card with a Full, Summary and Key points switch and a length slider. Switching streams an AI summary in place of the article as the card's height springs to fit, and each key point links back to the paragraph it came from, which gets scrolled to and highlighted.
- [Connector setup](https://uiarc.dev/components/connector-setup/markdown): A "Connect your tools" card for an AI assistant. Each app connects inline: it redirects, authorizes and runs a first sync with a progress hairline, then lists the scopes it was granted and offers Disconnect with an inline confirm.
- [Smart form fill](https://uiarc.dev/components/smart-form-fill/markdown): A paste-to-fill form card where AI reads an email signature or messy notes and fills a contact field by field. Each value flashes in with a confidence dot, its source lights up in the pasted text, low-confidence guesses ask for review, and Undo puts the old values back.
- [Enrich column](https://uiarc.dev/components/enrich-column/markdown): An AI enrichment column for a data table, where one prompt runs down every row and each cell shimmers while it works, then settles into a value with its source or a failure you can retry.
- [Ticket router](https://uiarc.dev/components/ticket-router/markdown): A support ticket router where messages from Gmail, Intercom, Slack and Zendesk come in one at a time. An AI classifier labels each one with intent, sentiment and confidence, and the ticket moves into a team lane with an assignee. Low confidence tickets wait in a review lane, and one click there routes them to the suggested team.
- [Ask your data](https://uiarc.dev/components/ask-your-data/markdown): A natural language to chart card: you ask a question, PostgreSQL streams into a collapsible, syntax highlighted panel, the query runs with a rolling row count, and the answer builds as stacked bars, lines or a table, with a one line insight streamed in underneath.
- [Agent cursor](https://uiarc.dev/components/agent-cursor/markdown): A live document where Claude edits like a collaborator. Its labeled cursor comes out of its avatar, selects a paragraph and streams in a rewrite, adds a heading and fixes a typo, while a teammate's cursor reads along. Changes stay tinted until someone accepts or undoes them from a floating review bar.
- [Provider status](https://uiarc.dev/components/provider-status/markdown): A status card for the AI providers your product depends on. Each row shows the provider's real mark, its health as an icon and label, p50 latency and a 30-day uptime bar with a tooltip for each day. An incident row expands into its timeline of updates, and the card checks again on a visible countdown.
- [Training run](https://uiarc.dev/components/training-run/markdown): A fine-tuning job card where a live train and validation loss curve draws across a fixed step axis that doubles as the epoch progress bar. It shows the learning rate, elapsed time, ETA and the latest evals and checkpoints, has Pause and Cancel while it runs, and ends in results with a Deploy button.
- [AI command](https://uiarc.dev/components/ai-command/markdown): A Cmd+K command palette with an AI mode. Search pages and actions, or press Tab to ask a question: the answer streams inside the palette with numbered sources, and the next steps it suggests, like filing a Linear issue or opening a Notion doc, run straight from the list.
- [Starter prompts](https://uiarc.dev/components/starter-prompts/markdown): A greeting and a grid of starter cards for the empty state of an AI app. The cards are grouped into Write, Code, Analyze and Plan tabs, and a shuffle swaps them with a short staggered crossfade. Picking a card fills the composer, and cards that use a connected app show its mark (Gmail, GitHub, Notion, Linear, Google Calendar).
- [AI mascot](https://uiarc.dev/components/ai-mascot/markdown): A small assistant character, a soft pebble with pill eyes and a companion dot, that shows what the AI is doing. It breathes and glances when idle, leans in to listen, looks up while the dot orbits its head, reads along the line it writes, squints with a sparkle when done and shakes once with worried brows on an error.
- [Image reveal](https://uiarc.dev/components/image-reveal/markdown): An image generation canvas where a soft, blurred preview made from the image's own colors sharpens top to bottom behind a soft-edged band. It works the way ChatGPT, Midjourney and Gemini show images forming, with fine film grain, a translucent progress pill and calm queued and error states.
- [AI spark](https://uiarc.dev/components/ai-spark/markdown): A brand-quality animated spark mark. Four tapered rays and four lighter diagonals breathe at rest, ripple while thinking, pulse like a heartbeat while writing, then gather and settle when done. Every status change blends from the pose the mark is already in.
- [Pixel mascot](https://uiarc.dev/components/pixel-mascot/markdown): A pixel-art robot that shows what an AI assistant is doing. It idles, thinks, types, celebrates and errors in frame-stepped sprite animations, and stays crisp at every integer size from 24px to 192px.
- [Ghost mascot](https://uiarc.dev/components/ghost-mascot/markdown): A floating ghost mascot whose soft sheet ripples at the hem while it hovers. It blinks when idle, turns toward you to listen, fades a little translucent while thinking, draws a tiny pen line while writing, smiles with a sparkle when done and wobbles once on an error.
- [Cube mascot](https://uiarc.dev/components/cube-mascot/markdown): An isometric cube mascot where three shaded faces and a painted-on face show what the assistant is doing. It turns a quarter turn in eased steps while thinking, prints lines onto the floor while writing, settles with a sparkle when done, and shakes once on error.
- [Tone tuner](https://uiarc.dev/components/tone-tuner/markdown): A brand voice card where two sliders (formality and detail) and Friendly, Confident and Empathetic chips rewrite a customer reply. Each changed sentence crossfades in place, new words can be highlighted against the original, and Copy takes the current version.
- [Upgrade prompt](https://uiarc.dev/components/upgrade-prompt/markdown): An upgrade nudge for the moment someone hits a limit. It shows a usage meter at 50 of 50 AI credits, a rolling price with a monthly and yearly toggle, three concrete unlocks with real model marks, and Upgrade or Maybe later. Upgrading leads into a success state with the new limits, and the card never changes size between states.
- [Referral card](https://uiarc.dev/components/referral-card/markdown): A give-and-get referral card where people copy or share their invite link, invite friends by email as chips, and watch invites move from invited to signed up to earned, with the credit total counting up and a milestone reward unlocking.
- [Trial banner](https://uiarc.dev/components/trial-banner/markdown): A trial status banner where a ring counts down the days left, the copy names what the workspace loses, and the upgrade path is one click away. It comes as a slim banner, a sidebar card or a header pill. It shifts to a warning tone in the last days, has expired and upgraded states, and folds into the pill when dismissed or snoozed.
- [Team switcher](https://uiarc.dev/components/team-switcher/markdown): A workspace switcher like Linear, Vercel or Slack. The trigger shows the current workspace's logo and plan. The menu has search, your role in each workspace and a Cmd+1 to 9 shortcut for each, and lets you create or join a workspace inline. A highlight glides between rows, and switching crossfades the trigger through a short loading state.
- [Live visitors](https://uiarc.dev/components/live-visitors/markdown): A realtime visitors card where the live count rolls digit by digit, new arrivals ping in on a dotted world map, the top pages reorder with bars, and signups and upgrades tick in with country flags.
- [Social proof toast](https://uiarc.dev/components/social-proof-toast/markdown): A stack of social proof notifications for landing and pricing pages, where recent trials, upgrades and verified purchases from people and companies arrive every few seconds. The stack pauses and fans out on hover, and visitors can dismiss any toast.
- [Install snippet](https://uiarc.dev/components/install-snippet/markdown): A "get started in 30 seconds" card where framework tabs, three numbered steps and highlighted snippets take a developer from install to first event. Generate key wipes a fresh API key into the placeholder in place.

### Guidance for AI tools

Context window: An AI context window as a grid of 200 cells: the system prompt, tools, files, summary and messages fill it in order, a threshold row marks where compaction starts, and sending a message, attaching a file or compacting shows exactly how much still fits. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Reasoning block

> The collapsible thinking block of an AI reply. While the model thinks, a shimmering label counts the seconds and the latest reasoning streams underneath. When it finishes, it folds to "Thought for 7s" and opens to show the full reasoning as calm steps with headings.

- Type: Component (special)
- Access: Arc Pro
- Page: https://uiarc.dev/components/reasoning-block
- Markdown: https://uiarc.dev/components/reasoning-block/markdown
- Source file: `registry/components/reasoning-block/reasoning-block.tsx`
- Dependencies: motion, lucide-react
- Keywords: special, ai, new, reasoning, thinking, thought for, extended thinking, chain of thought, reasoning summary, collapsible, ai reply, claude, streaming, llm

### When to use

- Showing a reasoning model's thinking above its answer in a chat or agent transcript.
- Letting people audit why an assistant reached a recommendation without crowding the reply.
- Restoring past messages where the reasoning should stay folded with its original thinking time.

### When not to use

- Tool or function calls with inputs and outputs: use ToolCall.
- A multi step agent plan with checkable tasks: use Agent plan.
- A one line busy indicator with no reasoning to show: use TextShimmer on its own.

### Installation

Reasoning block is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/reasoning-block
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { ReasoningBlock } from "@/components/arc/reasoning-block/reasoning-block";

// While streaming: pass the growing text, then flip status when the answer starts.
<ReasoningBlock
  reasoning={thinkingText}
  status={done ? "done" : "thinking"}
  onStop={() => controller.abort()}
/>

// A finished message from history.
<ReasoningBlock reasoning={message.reasoning} status="done" seconds={message.thinkingSeconds} />
```

### API reference

#### ReasoningBlock

The collapsible thinking block of an AI reply. While the model thinks, a shimmering "Thinking" label counts the seconds and the latest reasoning streams under it in muted text, two lines tall. When it finishes it collapses to "Thought for 7s" with a chevron; opening it shows the full reasoning as steps with headings on a quiet rail. With no props it plays a simulated Claude session on a loop.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `reasoning` | `string \| ReasoningStep[]` | – | The reasoning so far. Pass the growing string while the model streams: blank lines split paragraphs, and a line written as **Heading** or ## Heading starts a new step (a half streamed heading never shows raw asterisks). Or pass { title?, text }[] steps. |
| `status` | `"thinking" \| "done" \| "stopped" \| "error"` | `"done" when reasoning is passed` | thinking shimmers the label, counts seconds and streams the latest line; done collapses to "Thought for 7s"; stopped reads "Stopped after 4s"; error shows an alert icon with "Thinking interrupted" and the reason inside. |
| `seconds` | `number` | – | Seconds spent thinking, shown as 7s or 1m 12s. Left out, the block measures from the moment status turns thinking. Done without a measurement reads "Thought process". |
| `model` | `{ name: string; mark?: ReactNode }` | `{ name: "Claude Opus 5.5" }` | Who is thinking. The name labels the block for assistive technology; the mark is an 18px glyph at the left and defaults to the Claude mark in its brand color. |
| `open` | `boolean` | – | Controls whether the full reasoning shows. Pair with onOpenChange. |
| `defaultOpen` | `boolean` | `false` | Opens the full reasoning on first render. |
| `onOpenChange` | `(open: boolean) => void` | – | Called when the header is pressed. |
| `onStop` | `() => void` | – | Shows a compact Stop action while thinking. Abort your request, then set status to stopped. |
| `onRetry` | `() => void` | – | Shows Retry in the header when status is error. |
| `error` | `string` | – | The reason shown at the end of the reasoning when status is error. |
| `variant` | `"card" \| "plain"` | `"card"` | card draws a quiet bordered surface; plain drops the border and padding so the block sits flush inside a message bubble. |
| `className` | `string` | – | Class on the root. |

#### parseReasoning

The parser the block uses, exported for tests or for showing a step count elsewhere. Turns a streamed string into { title?, text }[] steps.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `reasoning` (required) | `string \| ReasoningStep[] \| undefined` | – | Raw streamed reasoning or steps. |

#### ClaudeMark

The Claude mark (Simple Icons, CC0) in its brand color. Pass mono to draw it with currentColor.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` | `string` | `"Claude"` | Accessible name. |
| `mono` | `boolean` | `false` | Draws with currentColor instead of #D97757. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Tab | Moves to the header, then to Stop or Retry when shown, then to Copy reasoning inside the open block. |
| Enter / Space | Opens or closes the full reasoning from the header. |

### Accessibility

- The header is a real button with aria-expanded and aria-controls; its name is the visible label, such as "Thought for 7s".
- A polite live region announces status changes only (thinking, thought for 7 seconds, stopped, interrupted), never each streamed chunk or each second.
- The two line live preview is aria-hidden because the same text is in the full reasoning region, which carries aria-busy while streaming.
- Status is never color alone: errors pair an alert icon with "Thinking interrupted", and the footer pairs a check, square or alert with Done, Stopped or the reason.
- The no props preview says "Simulated, nothing was sent to a model" to assistive technology.

### Motion

- Streaming is chunked: each appended chunk fades in once over 140ms. No blur, slide or per word springs.
- Stop and Retry overflow a fixed 20px row, so the header is 44px in every state and never shifts when an action appears.
- The live preview stays anchored to its newest line; when a line wraps, the text glides up with a bounce free spring (0.24s) instead of jumping.
- Label swaps (Thinking to Thought for 7s) are a single crossfade: out in 100ms, in over 160ms with a 2px rise. The seconds counter rolls in tabular numerals inside a reserved width.
- Opening, closing and the preview collapsing all animate measured height with one critically damped spring (0.26s) and one opacity fade. Only what streams in while open (a new step, paragraph or chunk) fades on its own, so nothing animates twice.
- The shimmer and the self-playing loop pause off screen and in background tabs. Reduced motion keeps every end state, drops the shimmer, the glide and the chunk fades, and cuts heights instantly.

### Responsive behavior

- Fills its container from 320px up; the header never wraps and long labels truncate.
- The live preview stays two lines at every width, so streaming never changes the block's height.
- Paragraphs wrap with text-wrap: pretty and break long identifiers instead of scrolling sideways.
- On touch, the whole header and live preview are one press target of at least 44px.

### Performance

- Streamed text is appended as spans that never re-render once on screen; finished messages render plain text.
- Only the open block mounts its full reasoning, so long transcripts of collapsed blocks stay light.
- The preview glide is one transform on one element driven by a ResizeObserver, with no layout animation on text.

### Notes for AI

- Use it above the answer in an assistant message whenever the model streams reasoning (extended thinking, reasoning summaries). Feed it the raw thinking text and switch status to done as soon as answer tokens start.
- Do not pass seconds while streaming unless your server measures it; the block counts by itself and freezes the value when status leaves thinking. Store that number with the message so history shows the same "Thought for 7s".
- Keep reasoning out of the answer text. For tool calls made during reasoning, render ToolCall rows after the block instead of inside it.
- Use variant="plain" inside a message bubble that already has its own surface, so you never nest cards.
- Swap the mark for another provider by passing model={{ name, mark }} with an 18px SVG.

### Related

- [Tool call](https://uiarc.dev/components/tool-call/markdown): A tool call row for agent transcripts: the tool's mark and the call in plain words, a live state while it runs, and the input and output a click away, with approval and retry when needed.
- [Agent status](https://uiarc.dev/components/agent-status/markdown): A compact live status pill for a running AI agent: the agent's mark in a live ring, the current activity and an elapsed timer, opening into the steps so far.
- [Text shimmer](https://uiarc.dev/components/text-shimmer/markdown): Show ongoing work with a calm light across the words.
- [Agent plan](https://uiarc.dev/components/agent-plan/markdown): The plan an agent writes before it acts: edit, reorder or add steps while it is a draft, then watch it work through them as a live checklist.

### Also in ai

- [Agent timeline](https://uiarc.dev/components/agent-timeline/markdown): A compact timeline of one orchestrated agent run: the orchestrator and its subagents share a time axis, handoffs draw in between rows, and a playhead replays thinking, tool calls and waiting while the header counts time, tokens and cost. Hover a span for what it did, or click it to trace its handoff path.
- [Context window](https://uiarc.dev/components/context-window/markdown): An AI context window as a grid of 200 cells: the system prompt, tools, files, summary and messages fill it in order, a threshold row marks where compaction starts, and sending a message, attaching a file or compacting shows exactly how much still fits.
- [Source cards](https://uiarc.dev/components/source-cards/markdown): A row of cited sources under an AI answer where cards stream in with real site marks while the model searches, the overflow collapses into a stack of favicons, hovering lifts a preview with the passage, and an inline [n] citation highlights its card.
- [Model card](https://uiarc.dev/components/model-card/markdown): A model details card where switching models rolls every price, limit and score in place, a token slider estimates monthly cost live, and benchmark bars show each model's rank on hover. Compare crossfades to a side-by-side table against any rival with the better values marked, and the card never changes size.
- [AI workflow](https://uiarc.dev/components/ai-workflow/markdown): A Linear-style AI workflow card where a Gmail trigger, a Claude step, a branch and Slack and Linear actions sit on one hairline rail, and a test run glides down it, opening each step's output inline. Steps are added from a compact command menu with real app marks.
- [Code suggestion](https://uiarc.dev/components/code-suggestion/markdown): An AI code edit suggestion where the model's proposed changes stream into a small editor panel as inline diff hunks, and you accept or reject each one, or all at once with Cmd+Enter. Accepted hunks fold into the file with a smooth height change.
- [Ghost text](https://uiarc.dev/components/ghost-text/markdown): An inline AI autocomplete where muted ghost text continues your sentence exactly at the caret and Tab turns it solid in place. Cmd+Right takes it one word at a time, Escape fades it away, and a calm chip shows the model behind it.
- [Image generation](https://uiarc.dev/components/image-generation/markdown): An image studio where each image forms on a dot matrix: a soft halftone wave breathes across the grid, the dots take the colours of the coming photo and grow into a coloured halftone, then blur away into the sharp photo. One large canvas with a mono size label, a filmstrip of four variations, a prompt bar with model and ratio, and upscale with a sweeping dot band, vary or download, with real provider marks and a built-in simulation.
- [Dictation button](https://uiarc.dev/components/dictation-button/markdown): A chat composer with voice input, where the mic springs into a recording pill with a smooth live waveform, a timer, and cancel and insert buttons. Words stream into the field as you speak, muted until the recognizer settles them.
- [Speech player](https://uiarc.dev/components/speech-player/markdown): A read-aloud player for AI replies. The Read aloud button in the message's action row turns into a compact player with play, a scrubbable progress bar, speed and a voice picker, and a highlight follows the spoken word through the reply, karaoke style.
- [Meeting summary](https://uiarc.dev/components/meeting-summary/markdown): An AI meeting notes card: the header shows the Google Meet or Zoom mark, the attendees and the duration. Summary, Decisions and Action items stream in after a short summarizing pass. Hover any line to see the transcript quote it came from, then check off action items or send them to Linear or Notion.
- [Reply draft](https://uiarc.dev/components/reply-draft/markdown): An AI email reply drafter where Claude streams a reply under a received Gmail message. Quick replies steer a fresh draft, tone and length rewrite it with a single crossfade, and you can edit the finished draft before you insert it.
- [Agent handoff](https://uiarc.dev/components/agent-handoff/markdown): A support conversation where an AI assistant hands off to a person. When it transfers, a card shows the summary it passes to the team and the typical wait. The person then joins and takes over, and a thin timeline on the left marks each step.
- [PII redaction](https://uiarc.dev/components/pii-redaction/markdown): A guardrail card where personal data is redacted before the prompt reaches the model. Scan marks each name, email, phone number and card with its type and swaps it for a placeholder like [EMAIL_1]. The safe prompt travels to Claude, and the reply comes back with the original values put back for the person.
- [Response feedback](https://uiarc.dev/components/response-feedback/markdown): A feedback control for AI replies where thumbs down opens an inline panel with reason chips and an optional note, thumbs up fills and asks what was good, and a submit shows a short thank-you before folding back into the row.
- [LLM cost calculator](https://uiarc.dev/components/llm-cost-calculator/markdown): A pricing calculator for LLM workloads. Set tokens per request, requests per day and prompt caching, and eight current models re-rank by monthly cost. Bars glide and prices roll as you drag.
- [Provider keys](https://uiarc.dev/components/provider-keys/markdown): A settings card for bring-your-own-key AI products. Each provider row shows its real mark, the masked key, a status and when the key was last used. You can reveal a key for five seconds, copy, rotate or remove it with undo. Adding or rotating a key opens an inline form that checks the format as you type, then tests the connection before saving.
- [Generation stats](https://uiarc.dev/components/generation-stats/markdown): A live stats strip for a streaming LLM response where time to first token, speed with a sparkline, output tokens and cost count up in tabular numerals beside the model's real mark, then settle and open into a latency and token cost breakdown.
- [AI translate](https://uiarc.dev/components/ai-translate/markdown): A message card where picking a language streams the AI translation in place, sentence by sentence over the dimmed original, with a detected-language chip, a Show original toggle and a status line credited to the model's mark.
- [TL;DR toggle](https://uiarc.dev/components/tldr-toggle/markdown): An article card with a Full, Summary and Key points switch and a length slider. Switching streams an AI summary in place of the article as the card's height springs to fit, and each key point links back to the paragraph it came from, which gets scrolled to and highlighted.
- [Connector setup](https://uiarc.dev/components/connector-setup/markdown): A "Connect your tools" card for an AI assistant. Each app connects inline: it redirects, authorizes and runs a first sync with a progress hairline, then lists the scopes it was granted and offers Disconnect with an inline confirm.
- [Smart form fill](https://uiarc.dev/components/smart-form-fill/markdown): A paste-to-fill form card where AI reads an email signature or messy notes and fills a contact field by field. Each value flashes in with a confidence dot, its source lights up in the pasted text, low-confidence guesses ask for review, and Undo puts the old values back.
- [Enrich column](https://uiarc.dev/components/enrich-column/markdown): An AI enrichment column for a data table, where one prompt runs down every row and each cell shimmers while it works, then settles into a value with its source or a failure you can retry.
- [Ticket router](https://uiarc.dev/components/ticket-router/markdown): A support ticket router where messages from Gmail, Intercom, Slack and Zendesk come in one at a time. An AI classifier labels each one with intent, sentiment and confidence, and the ticket moves into a team lane with an assignee. Low confidence tickets wait in a review lane, and one click there routes them to the suggested team.
- [Ask your data](https://uiarc.dev/components/ask-your-data/markdown): A natural language to chart card: you ask a question, PostgreSQL streams into a collapsible, syntax highlighted panel, the query runs with a rolling row count, and the answer builds as stacked bars, lines or a table, with a one line insight streamed in underneath.
- [Agent cursor](https://uiarc.dev/components/agent-cursor/markdown): A live document where Claude edits like a collaborator. Its labeled cursor comes out of its avatar, selects a paragraph and streams in a rewrite, adds a heading and fixes a typo, while a teammate's cursor reads along. Changes stay tinted until someone accepts or undoes them from a floating review bar.
- [Provider status](https://uiarc.dev/components/provider-status/markdown): A status card for the AI providers your product depends on. Each row shows the provider's real mark, its health as an icon and label, p50 latency and a 30-day uptime bar with a tooltip for each day. An incident row expands into its timeline of updates, and the card checks again on a visible countdown.
- [Training run](https://uiarc.dev/components/training-run/markdown): A fine-tuning job card where a live train and validation loss curve draws across a fixed step axis that doubles as the epoch progress bar. It shows the learning rate, elapsed time, ETA and the latest evals and checkpoints, has Pause and Cancel while it runs, and ends in results with a Deploy button.
- [AI command](https://uiarc.dev/components/ai-command/markdown): A Cmd+K command palette with an AI mode. Search pages and actions, or press Tab to ask a question: the answer streams inside the palette with numbered sources, and the next steps it suggests, like filing a Linear issue or opening a Notion doc, run straight from the list.
- [Starter prompts](https://uiarc.dev/components/starter-prompts/markdown): A greeting and a grid of starter cards for the empty state of an AI app. The cards are grouped into Write, Code, Analyze and Plan tabs, and a shuffle swaps them with a short staggered crossfade. Picking a card fills the composer, and cards that use a connected app show its mark (Gmail, GitHub, Notion, Linear, Google Calendar).
- [AI mascot](https://uiarc.dev/components/ai-mascot/markdown): A small assistant character, a soft pebble with pill eyes and a companion dot, that shows what the AI is doing. It breathes and glances when idle, leans in to listen, looks up while the dot orbits its head, reads along the line it writes, squints with a sparkle when done and shakes once with worried brows on an error.
- [Image reveal](https://uiarc.dev/components/image-reveal/markdown): An image generation canvas where a soft, blurred preview made from the image's own colors sharpens top to bottom behind a soft-edged band. It works the way ChatGPT, Midjourney and Gemini show images forming, with fine film grain, a translucent progress pill and calm queued and error states.
- [AI spark](https://uiarc.dev/components/ai-spark/markdown): A brand-quality animated spark mark. Four tapered rays and four lighter diagonals breathe at rest, ripple while thinking, pulse like a heartbeat while writing, then gather and settle when done. Every status change blends from the pose the mark is already in.
- [Pixel mascot](https://uiarc.dev/components/pixel-mascot/markdown): A pixel-art robot that shows what an AI assistant is doing. It idles, thinks, types, celebrates and errors in frame-stepped sprite animations, and stays crisp at every integer size from 24px to 192px.
- [Ghost mascot](https://uiarc.dev/components/ghost-mascot/markdown): A floating ghost mascot whose soft sheet ripples at the hem while it hovers. It blinks when idle, turns toward you to listen, fades a little translucent while thinking, draws a tiny pen line while writing, smiles with a sparkle when done and wobbles once on an error.
- [Cube mascot](https://uiarc.dev/components/cube-mascot/markdown): An isometric cube mascot where three shaded faces and a painted-on face show what the assistant is doing. It turns a quarter turn in eased steps while thinking, prints lines onto the floor while writing, settles with a sparkle when done, and shakes once on error.
- [Tone tuner](https://uiarc.dev/components/tone-tuner/markdown): A brand voice card where two sliders (formality and detail) and Friendly, Confident and Empathetic chips rewrite a customer reply. Each changed sentence crossfades in place, new words can be highlighted against the original, and Copy takes the current version.
- [Upgrade prompt](https://uiarc.dev/components/upgrade-prompt/markdown): An upgrade nudge for the moment someone hits a limit. It shows a usage meter at 50 of 50 AI credits, a rolling price with a monthly and yearly toggle, three concrete unlocks with real model marks, and Upgrade or Maybe later. Upgrading leads into a success state with the new limits, and the card never changes size between states.
- [Referral card](https://uiarc.dev/components/referral-card/markdown): A give-and-get referral card where people copy or share their invite link, invite friends by email as chips, and watch invites move from invited to signed up to earned, with the credit total counting up and a milestone reward unlocking.
- [Trial banner](https://uiarc.dev/components/trial-banner/markdown): A trial status banner where a ring counts down the days left, the copy names what the workspace loses, and the upgrade path is one click away. It comes as a slim banner, a sidebar card or a header pill. It shifts to a warning tone in the last days, has expired and upgraded states, and folds into the pill when dismissed or snoozed.
- [Team switcher](https://uiarc.dev/components/team-switcher/markdown): A workspace switcher like Linear, Vercel or Slack. The trigger shows the current workspace's logo and plan. The menu has search, your role in each workspace and a Cmd+1 to 9 shortcut for each, and lets you create or join a workspace inline. A highlight glides between rows, and switching crossfades the trigger through a short loading state.
- [Live visitors](https://uiarc.dev/components/live-visitors/markdown): A realtime visitors card where the live count rolls digit by digit, new arrivals ping in on a dotted world map, the top pages reorder with bars, and signups and upgrades tick in with country flags.
- [Social proof toast](https://uiarc.dev/components/social-proof-toast/markdown): A stack of social proof notifications for landing and pricing pages, where recent trials, upgrades and verified purchases from people and companies arrive every few seconds. The stack pauses and fans out on hover, and visitors can dismiss any toast.
- [Install snippet](https://uiarc.dev/components/install-snippet/markdown): A "get started in 30 seconds" card where framework tabs, three numbered steps and highlighted snippets take a developer from install to first event. Generate key wipes a fresh API key into the placeholder in place.

### Guidance for AI tools

Reasoning block: The collapsible thinking block of an AI reply. While the model thinks, a shimmering label counts the seconds and the latest reasoning streams underneath. When it finishes, it folds to "Thought for 7s" and opens to show the full reasoning as calm steps with headings. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Source cards

> A row of cited sources under an AI answer where cards stream in with real site marks while the model searches, the overflow collapses into a stack of favicons, hovering lifts a preview with the passage, and an inline [n] citation highlights its card.

- Type: Component (special)
- Access: Arc Pro
- Page: https://uiarc.dev/components/source-cards
- Markdown: https://uiarc.dev/components/source-cards/markdown
- Source file: `registry/components/source-cards/source-cards.tsx`
- Dependencies: motion, lucide-react
- Keywords: special, ai, new, sources, citations, ai search, perplexity, references, web search, favicon, cited answer, rag, search progress

### When to use

- Citations under an AI search or docs assistant answer.
- Showing live search progress ("Searching 3 of 8") while an agent browses.
- Linking inline [n] references in generated text to the pages they came from.

### When not to use

- A full search results page with many results and filters; use a list layout instead.
- Tool calls with arguments and outputs; use tool-call.
- A single link preview inside prose; use a tooltip or hover card.

### Installation

Source cards is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/source-cards
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { SourceCards, SourceCitation } from "@/components/arc/source-cards/source-cards";

<SourceCards
  sources={results}            // [{ title, url, snippet, published }]
  status={searching ? "searching" : "done"}
  total={8}
  query="stripe webhook signature verification"
  duration={2100}
  onSourceClick={(source) => openReader(source.url)}
>
  <p>
    Read the raw body with <code>await request.text()</code> before parsing it <SourceCitation n={1} />
    <SourceCitation n={2} />.
  </p>
</SourceCards>
```

### API reference

#### SourceCards

A row of cited sources under an AI answer. Each card shows the site's mark, its domain, the citation number and a two line title. While searching, cards stream into reserved slots under "Searching 3 of 7"; past `max` the rest collapse into a stack of overlapping marks ("+4 more"). Hovering or focusing a card lifts a preview with the passage, and a SourceCitation in the answer highlights its card. With no `sources` it renders a self-playing demo.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `sources` | `SourceCardsSource[]` | – | The sources in citation order: source 1 is cited as [1]. Append as results arrive; each new card fades into its slot. Leave out for the self-playing demo. |
| `status` | `"searching" \| "done" \| "error"` | `"done"` | Searching shows a spinner, a shimmering "Searching", a rolling count and reserved slots. Done shows "7 sources" and the time. Error keeps what arrived and shows "Search failed" with Retry. Done with no sources shows "No sources found". |
| `total` | `number` | – | How many sources the search will return. Drives "Searching 3 of 7" and reserves that many slots, so the row never shifts while it fills. |
| `query` | `string` | – | The search query, shown muted after the status while searching or when nothing was found. |
| `duration` | `number` | – | Search time in ms, shown after the count when done ("7 sources · 2.1s"). |
| `max` | `number` | `3` | Cards shown before the rest collapse into the stack. The grid has max + 1 columns on wide containers and two below 540px. |
| `expanded` | `boolean` | – | Controls whether the stack is open. Pair with onExpandedChange. |
| `defaultExpanded` | `boolean` | `false` | Opens the stack on first render. |
| `onExpandedChange` | `(expanded: boolean) => void` | – | Called from the stack, the Show all toggle, or a citation that points into the stack. |
| `highlighted` | `number \| null` | – | Controlled highlighted source number (1-based). Uncontrolled, a citation click highlights its card for 2.6s. |
| `onHighlightChange` | `(n: number \| null) => void` | – | Called when a SourceCitation is clicked. |
| `onSourceClick` | `(source: SourceCardsSource, n: number) => void` | – | Makes cards buttons and calls this instead of navigating, for an in-app reader or analytics. Without it cards are links that open in a new tab. |
| `onRetry` | `() => void` | – | Shows Retry on error and Search again when nothing was found. |
| `error` | `string` | – | Detail shown after "Search failed", such as "The search provider timed out after 8s." |
| `hideStatus` | `boolean` | `false` | Hides the status line when your UI already shows search progress. |
| `children` | `ReactNode` | – | The answer, rendered between the status line and the cards. Its height springs as it streams so the cards glide down. SourceCitation inside it is linked to the cards. |
| `label` | `string` | `"Sources"` | Accessible name of the source list. |
| `className` | `string` | – | Class on the root element. |

#### SourceCitation

An inline [n] chip for the answer text, styled like the number on each card. Inside SourceCards it names its source for screen readers, turns accent while its card is highlighted, and highlights the card on click (opening the stack when needed).

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `n` (required) | `number` | – | The 1-based source number. |
| `onClick` | `(event: MouseEvent<HTMLButtonElement>) => void` | – | Extra click handler, for example to scroll the cards into view. |
| `className` | `string` | – | Class on the chip. |

#### SourceCardsSource

One source.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` (required) | `string` | – | Page title as the search result shows it. Clamped to two lines on the card. |
| `url` (required) | `string` | – | Full URL. The host becomes the domain and picks the mark: github.com, developer.mozilla.org, stripe.com, vercel.com, wikipedia.org and stackoverflow.com draw their real marks; anything else gets a lettered disc. |
| `id` | `string` | – | Stable key. Defaults to the URL. |
| `site` | `string` | – | Readable site name for the preview and the stack, such as "Stripe Docs". |
| `snippet` | `string` | – | The passage the answer relied on, shown in the hover preview (four lines). |
| `published` | `string` | – | Short date label, such as "Oct 9, 2026". |
| `mark` | `"github" \| "mdn" \| "stripe" \| "vercel" \| "wikipedia" \| "stackoverflow"` | – | Forces a built in mark when the URL does not match. |
| `icon` | `ReactNode` | – | Custom favicon, drawn at 14px on the card and 16px in the preview. |

#### SourceCardsSimulation

The demo SourceCards renders without sources, exported for docs and previews.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `scenario` | `"live" \| "error" \| "empty"` | `"live"` | Live searches, streams a cited answer and tours two citations, looping until someone interacts. Error fails after two sources with Retry. Empty finds nothing and offers Search again. |
| `className` | `string` | – | Class on the demo panel. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Tab | Moves through citations, the Show all toggle, each card and the stack. A focused card shows its preview. |
| Enter / Space | Opens a card (or calls onSourceClick), opens the stack, or highlights a citation's card. |
| Escape | Closes the open preview. |

### Accessibility

- The cards are a labelled list (aria-label "Sources") marked aria-busy while searching; skeleton slots are hidden from assistive technology.
- A polite live region announces status changes once: searching for the query, the number found, no sources, or the failure. Counts do not announce on every card.
- Each card's name reads number, title and domain, and says when it opens in a new tab. The preview is a tooltip linked with aria-describedby while open.
- SourceCitation is a real button named "Source 2: Request: text() method, developer.mozilla.org"; its highlighted state is never color alone because the card also gains an outline.
- Status always pairs an icon with words: spinner and Searching, globe and the count, alert and Search failed, crossed search and No sources found.
- The demo says in a live region that the search is simulated and that card clicks open nothing.

### Motion

- Cards fade in with a 4px rise in 180ms as they arrive; skeletons crossfade out in 120ms. Nothing bounces.
- Collapsing the stack or a failed search dropping its reserved slots fades the leaving slots in place (120ms) while the stack or card taking their cell fades in, and the row height glides once. Skeleton bars sit on the same 18px lines as the text that replaces them.
- Counts roll 5px with tabular numerals in a reserved width; status icons and labels crossfade (100ms out, 160ms in).
- The answer's height springs (bounce 0) as it streams so the cards glide down instead of stepping one line at a time; a width change cuts straight to the new height.
- Previews open after a 320ms hover intent, then switch instantly between cards; they fade and rise 4px with a 0.98 scale in 160ms.
- Reduced motion keeps every end state and highlight but drops the rise, scale and skeleton pulse. The demo pauses off screen.

### Responsive behavior

- Wide containers show max + 1 equal columns; below 540px (container query) the grid becomes two columns, with the stack as the last tile.
- Previews align to the card's left or right edge so they never leave the component, and drop below the card when there is no room above.
- On touch there is no hover preview; tapping a card opens it. Citation chips have an enlarged hit area.

### Performance

- Cards are plain elements with CSS transitions; motion only drives arrivals, the preview and number rolls.
- One ResizeObserver per auto height box; the demo's timers stop off screen through an IntersectionObserver.
- Built in marks are inline SVG paths with no network requests.

### Notes for AI

- Use under an assistant message that cites web or docs sources. Keep sources in citation order so [n] maps to card n.
- Stream results by appending to sources with status "searching" and a total; switch to "done" when the model starts answering.
- Put the answer inside SourceCards as children when it contains SourceCitation chips; otherwise render SourceCards alone under your own answer and drive highlighted yourself.
- Pass onSourceClick for in-app reading; omit it for plain new-tab links. Do not wrap cards in your own links.
- Known hosts draw real marks automatically; pass icon for other favicons rather than inventing a logo.

### Related

- [Tool call](https://uiarc.dev/components/tool-call/markdown): A tool call row for agent transcripts: the tool's mark and the call in plain words, a live state while it runs, and the input and output a click away, with approval and retry when needed.
- [Agent status](https://uiarc.dev/components/agent-status/markdown): A compact live status pill for a running AI agent: the agent's mark in a live ring, the current activity and an elapsed timer, opening into the steps so far.
- [Text shimmer](https://uiarc.dev/components/text-shimmer/markdown): Show ongoing work with a calm light across the words.
- [Tooltip](https://uiarc.dev/components/tooltip/markdown): Short supporting text for unfamiliar controls.
- [Copy button](https://uiarc.dev/components/copy-button/markdown): Copy a value with immediate confirmation.

### Also in ai

- [Agent plan](https://uiarc.dev/components/agent-plan/markdown): The plan an agent writes before it acts: edit, reorder or add steps while it is a draft, then watch it work through them as a live checklist.
- [Agent timeline](https://uiarc.dev/components/agent-timeline/markdown): A compact timeline of one orchestrated agent run: the orchestrator and its subagents share a time axis, handoffs draw in between rows, and a playhead replays thinking, tool calls and waiting while the header counts time, tokens and cost. Hover a span for what it did, or click it to trace its handoff path.
- [Context window](https://uiarc.dev/components/context-window/markdown): An AI context window as a grid of 200 cells: the system prompt, tools, files, summary and messages fill it in order, a threshold row marks where compaction starts, and sending a message, attaching a file or compacting shows exactly how much still fits.
- [Reasoning block](https://uiarc.dev/components/reasoning-block/markdown): The collapsible thinking block of an AI reply. While the model thinks, a shimmering label counts the seconds and the latest reasoning streams underneath. When it finishes, it folds to "Thought for 7s" and opens to show the full reasoning as calm steps with headings.
- [Model card](https://uiarc.dev/components/model-card/markdown): A model details card where switching models rolls every price, limit and score in place, a token slider estimates monthly cost live, and benchmark bars show each model's rank on hover. Compare crossfades to a side-by-side table against any rival with the better values marked, and the card never changes size.
- [AI workflow](https://uiarc.dev/components/ai-workflow/markdown): A Linear-style AI workflow card where a Gmail trigger, a Claude step, a branch and Slack and Linear actions sit on one hairline rail, and a test run glides down it, opening each step's output inline. Steps are added from a compact command menu with real app marks.
- [Code suggestion](https://uiarc.dev/components/code-suggestion/markdown): An AI code edit suggestion where the model's proposed changes stream into a small editor panel as inline diff hunks, and you accept or reject each one, or all at once with Cmd+Enter. Accepted hunks fold into the file with a smooth height change.
- [Ghost text](https://uiarc.dev/components/ghost-text/markdown): An inline AI autocomplete where muted ghost text continues your sentence exactly at the caret and Tab turns it solid in place. Cmd+Right takes it one word at a time, Escape fades it away, and a calm chip shows the model behind it.
- [Image generation](https://uiarc.dev/components/image-generation/markdown): An image studio where each image forms on a dot matrix: a soft halftone wave breathes across the grid, the dots take the colours of the coming photo and grow into a coloured halftone, then blur away into the sharp photo. One large canvas with a mono size label, a filmstrip of four variations, a prompt bar with model and ratio, and upscale with a sweeping dot band, vary or download, with real provider marks and a built-in simulation.
- [Dictation button](https://uiarc.dev/components/dictation-button/markdown): A chat composer with voice input, where the mic springs into a recording pill with a smooth live waveform, a timer, and cancel and insert buttons. Words stream into the field as you speak, muted until the recognizer settles them.
- [Speech player](https://uiarc.dev/components/speech-player/markdown): A read-aloud player for AI replies. The Read aloud button in the message's action row turns into a compact player with play, a scrubbable progress bar, speed and a voice picker, and a highlight follows the spoken word through the reply, karaoke style.
- [Meeting summary](https://uiarc.dev/components/meeting-summary/markdown): An AI meeting notes card: the header shows the Google Meet or Zoom mark, the attendees and the duration. Summary, Decisions and Action items stream in after a short summarizing pass. Hover any line to see the transcript quote it came from, then check off action items or send them to Linear or Notion.
- [Reply draft](https://uiarc.dev/components/reply-draft/markdown): An AI email reply drafter where Claude streams a reply under a received Gmail message. Quick replies steer a fresh draft, tone and length rewrite it with a single crossfade, and you can edit the finished draft before you insert it.
- [Agent handoff](https://uiarc.dev/components/agent-handoff/markdown): A support conversation where an AI assistant hands off to a person. When it transfers, a card shows the summary it passes to the team and the typical wait. The person then joins and takes over, and a thin timeline on the left marks each step.
- [PII redaction](https://uiarc.dev/components/pii-redaction/markdown): A guardrail card where personal data is redacted before the prompt reaches the model. Scan marks each name, email, phone number and card with its type and swaps it for a placeholder like [EMAIL_1]. The safe prompt travels to Claude, and the reply comes back with the original values put back for the person.
- [Response feedback](https://uiarc.dev/components/response-feedback/markdown): A feedback control for AI replies where thumbs down opens an inline panel with reason chips and an optional note, thumbs up fills and asks what was good, and a submit shows a short thank-you before folding back into the row.
- [LLM cost calculator](https://uiarc.dev/components/llm-cost-calculator/markdown): A pricing calculator for LLM workloads. Set tokens per request, requests per day and prompt caching, and eight current models re-rank by monthly cost. Bars glide and prices roll as you drag.
- [Provider keys](https://uiarc.dev/components/provider-keys/markdown): A settings card for bring-your-own-key AI products. Each provider row shows its real mark, the masked key, a status and when the key was last used. You can reveal a key for five seconds, copy, rotate or remove it with undo. Adding or rotating a key opens an inline form that checks the format as you type, then tests the connection before saving.
- [Generation stats](https://uiarc.dev/components/generation-stats/markdown): A live stats strip for a streaming LLM response where time to first token, speed with a sparkline, output tokens and cost count up in tabular numerals beside the model's real mark, then settle and open into a latency and token cost breakdown.
- [AI translate](https://uiarc.dev/components/ai-translate/markdown): A message card where picking a language streams the AI translation in place, sentence by sentence over the dimmed original, with a detected-language chip, a Show original toggle and a status line credited to the model's mark.
- [TL;DR toggle](https://uiarc.dev/components/tldr-toggle/markdown): An article card with a Full, Summary and Key points switch and a length slider. Switching streams an AI summary in place of the article as the card's height springs to fit, and each key point links back to the paragraph it came from, which gets scrolled to and highlighted.
- [Connector setup](https://uiarc.dev/components/connector-setup/markdown): A "Connect your tools" card for an AI assistant. Each app connects inline: it redirects, authorizes and runs a first sync with a progress hairline, then lists the scopes it was granted and offers Disconnect with an inline confirm.
- [Smart form fill](https://uiarc.dev/components/smart-form-fill/markdown): A paste-to-fill form card where AI reads an email signature or messy notes and fills a contact field by field. Each value flashes in with a confidence dot, its source lights up in the pasted text, low-confidence guesses ask for review, and Undo puts the old values back.
- [Enrich column](https://uiarc.dev/components/enrich-column/markdown): An AI enrichment column for a data table, where one prompt runs down every row and each cell shimmers while it works, then settles into a value with its source or a failure you can retry.
- [Ticket router](https://uiarc.dev/components/ticket-router/markdown): A support ticket router where messages from Gmail, Intercom, Slack and Zendesk come in one at a time. An AI classifier labels each one with intent, sentiment and confidence, and the ticket moves into a team lane with an assignee. Low confidence tickets wait in a review lane, and one click there routes them to the suggested team.
- [Ask your data](https://uiarc.dev/components/ask-your-data/markdown): A natural language to chart card: you ask a question, PostgreSQL streams into a collapsible, syntax highlighted panel, the query runs with a rolling row count, and the answer builds as stacked bars, lines or a table, with a one line insight streamed in underneath.
- [Agent cursor](https://uiarc.dev/components/agent-cursor/markdown): A live document where Claude edits like a collaborator. Its labeled cursor comes out of its avatar, selects a paragraph and streams in a rewrite, adds a heading and fixes a typo, while a teammate's cursor reads along. Changes stay tinted until someone accepts or undoes them from a floating review bar.
- [Provider status](https://uiarc.dev/components/provider-status/markdown): A status card for the AI providers your product depends on. Each row shows the provider's real mark, its health as an icon and label, p50 latency and a 30-day uptime bar with a tooltip for each day. An incident row expands into its timeline of updates, and the card checks again on a visible countdown.
- [Training run](https://uiarc.dev/components/training-run/markdown): A fine-tuning job card where a live train and validation loss curve draws across a fixed step axis that doubles as the epoch progress bar. It shows the learning rate, elapsed time, ETA and the latest evals and checkpoints, has Pause and Cancel while it runs, and ends in results with a Deploy button.
- [AI command](https://uiarc.dev/components/ai-command/markdown): A Cmd+K command palette with an AI mode. Search pages and actions, or press Tab to ask a question: the answer streams inside the palette with numbered sources, and the next steps it suggests, like filing a Linear issue or opening a Notion doc, run straight from the list.
- [Starter prompts](https://uiarc.dev/components/starter-prompts/markdown): A greeting and a grid of starter cards for the empty state of an AI app. The cards are grouped into Write, Code, Analyze and Plan tabs, and a shuffle swaps them with a short staggered crossfade. Picking a card fills the composer, and cards that use a connected app show its mark (Gmail, GitHub, Notion, Linear, Google Calendar).
- [AI mascot](https://uiarc.dev/components/ai-mascot/markdown): A small assistant character, a soft pebble with pill eyes and a companion dot, that shows what the AI is doing. It breathes and glances when idle, leans in to listen, looks up while the dot orbits its head, reads along the line it writes, squints with a sparkle when done and shakes once with worried brows on an error.
- [Image reveal](https://uiarc.dev/components/image-reveal/markdown): An image generation canvas where a soft, blurred preview made from the image's own colors sharpens top to bottom behind a soft-edged band. It works the way ChatGPT, Midjourney and Gemini show images forming, with fine film grain, a translucent progress pill and calm queued and error states.
- [AI spark](https://uiarc.dev/components/ai-spark/markdown): A brand-quality animated spark mark. Four tapered rays and four lighter diagonals breathe at rest, ripple while thinking, pulse like a heartbeat while writing, then gather and settle when done. Every status change blends from the pose the mark is already in.
- [Pixel mascot](https://uiarc.dev/components/pixel-mascot/markdown): A pixel-art robot that shows what an AI assistant is doing. It idles, thinks, types, celebrates and errors in frame-stepped sprite animations, and stays crisp at every integer size from 24px to 192px.
- [Ghost mascot](https://uiarc.dev/components/ghost-mascot/markdown): A floating ghost mascot whose soft sheet ripples at the hem while it hovers. It blinks when idle, turns toward you to listen, fades a little translucent while thinking, draws a tiny pen line while writing, smiles with a sparkle when done and wobbles once on an error.
- [Cube mascot](https://uiarc.dev/components/cube-mascot/markdown): An isometric cube mascot where three shaded faces and a painted-on face show what the assistant is doing. It turns a quarter turn in eased steps while thinking, prints lines onto the floor while writing, settles with a sparkle when done, and shakes once on error.
- [Tone tuner](https://uiarc.dev/components/tone-tuner/markdown): A brand voice card where two sliders (formality and detail) and Friendly, Confident and Empathetic chips rewrite a customer reply. Each changed sentence crossfades in place, new words can be highlighted against the original, and Copy takes the current version.
- [Upgrade prompt](https://uiarc.dev/components/upgrade-prompt/markdown): An upgrade nudge for the moment someone hits a limit. It shows a usage meter at 50 of 50 AI credits, a rolling price with a monthly and yearly toggle, three concrete unlocks with real model marks, and Upgrade or Maybe later. Upgrading leads into a success state with the new limits, and the card never changes size between states.
- [Referral card](https://uiarc.dev/components/referral-card/markdown): A give-and-get referral card where people copy or share their invite link, invite friends by email as chips, and watch invites move from invited to signed up to earned, with the credit total counting up and a milestone reward unlocking.
- [Trial banner](https://uiarc.dev/components/trial-banner/markdown): A trial status banner where a ring counts down the days left, the copy names what the workspace loses, and the upgrade path is one click away. It comes as a slim banner, a sidebar card or a header pill. It shifts to a warning tone in the last days, has expired and upgraded states, and folds into the pill when dismissed or snoozed.
- [Team switcher](https://uiarc.dev/components/team-switcher/markdown): A workspace switcher like Linear, Vercel or Slack. The trigger shows the current workspace's logo and plan. The menu has search, your role in each workspace and a Cmd+1 to 9 shortcut for each, and lets you create or join a workspace inline. A highlight glides between rows, and switching crossfades the trigger through a short loading state.
- [Live visitors](https://uiarc.dev/components/live-visitors/markdown): A realtime visitors card where the live count rolls digit by digit, new arrivals ping in on a dotted world map, the top pages reorder with bars, and signups and upgrades tick in with country flags.
- [Social proof toast](https://uiarc.dev/components/social-proof-toast/markdown): A stack of social proof notifications for landing and pricing pages, where recent trials, upgrades and verified purchases from people and companies arrive every few seconds. The stack pauses and fans out on hover, and visitors can dismiss any toast.
- [Install snippet](https://uiarc.dev/components/install-snippet/markdown): A "get started in 30 seconds" card where framework tabs, three numbered steps and highlighted snippets take a developer from install to first event. Generate key wipes a fresh API key into the placeholder in place.

### Guidance for AI tools

Source cards: A row of cited sources under an AI answer where cards stream in with real site marks while the model searches, the overflow collapses into a stack of favicons, hovering lifts a preview with the passage, and an inline [n] citation highlights its card. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Model card

> A model details card where switching models rolls every price, limit and score in place, a token slider estimates monthly cost live, and benchmark bars show each model's rank on hover. Compare crossfades to a side-by-side table against any rival with the better values marked, and the card never changes size.

- Type: Component (special)
- Access: Arc Pro
- Page: https://uiarc.dev/components/model-card
- Markdown: https://uiarc.dev/components/model-card/markdown
- Source file: `registry/components/model-card/model-card.tsx`
- Dependencies: motion, lucide-react, @radix-ui/react-switch, @radix-ui/react-dropdown-menu
- Keywords: special, ai, new, model card, model details, model picker, llm, ai model, compare models, benchmark, context window, pricing per token, cost estimator, token cost calculator, tokens, claude, gpt, gemini, grok, copy model id, marketplace

### When to use

- The detail pane of a model picker, showing what the highlighted model can do and what it costs before someone selects it.
- Model pages in docs or a marketplace, with limits, prices and a quick benchmark read against close rivals.
- Settings where a team picks a default model and wants a side by side check against an alternative.

### When not to use

- Use model-picker to choose between many models; pair it with this card for the details.
- Use context-window to show how full a live conversation's context is.
- Use a pricing table for plan pricing; this card shows per token API prices.
- Do not use it for official benchmark leaderboards with many models; the bar list shows three models.

### Installation

Model card is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/model-card
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { ModelCard, type ModelCardModel } from "@/components/arc/model-card/model-card";
import { ClaudeMark, OpenaiMark } from "@/components/arc/model-card/model-card-marks";

const sonnet: ModelCardModel = {
  id: "claude-sonnet-5-5",
  name: "Claude Sonnet 5.5",
  provider: "Anthropic",
  mark: <ClaudeMark aria-hidden style={{ color: "#D97757" }} />,
  summary: "The balanced Claude for everyday coding, agents and analysis at scale.",
  modalities: ["text", "image", "pdf", "tools", "reasoning"],
  contextWindow: 1_000_000,
  maxOutput: 64_000,
  knowledgeCutoff: "2026-03",
  pricing: { input: 3, output: 15, cachedInput: 0.3 },
  scores: { "swe-bench": 82.1, gpqa: 85.4 },
};

export function ModelDetails({ rivals, current, onPick }: { rivals: ModelCardModel[]; current: string; onPick: (id: string) => void }) {
  return (
    <ModelCard
      model={sonnet}
      rivals={rivals}
      benchmarks={[
        { id: "swe-bench", name: "SWE-bench Verified", shortName: "SWE-bench", description: "real GitHub issues resolved" },
        { id: "gpqa", name: "GPQA Diamond", shortName: "GPQA", description: "graduate level science questions" },
      ]}
      defaultMonthlyTokens={50_000_000}
      sample={false}
      selected={current === sonnet.id}
      onSelect={model => onPick(model.id)}
      onCopyId={id => console.log("copied", id)}
    />
  );
}
```

### API reference

#### ModelCard

A model details card for a model picker, docs or a marketplace that keeps one size in every state. The header shows the provider mark, the model name and the provider, with a Compare switch. The details view has a two line summary, all seven modality chips (unsupported ones dashed and muted), context window, max output and knowledge cutoff with a context gauge that reads as pages (1M tokens fits about 1,500 pages), input, output and cached prices per million tokens, a monthly volume slider that rolls the estimated monthly cost live, and benchmark bars against two rivals where hovering or focusing a row shows the exact score, its rank and the gap to the leader. The footer shows the API model id with Copy model id. Compare crossfades to a side by side table against any rival, including the cost at the chosen volume, with a check and the margin (+2.3, −20%, 2x) on the better value and a tally of who leads. Details, compare, loading and error are stacked in one grid cell, so switching models, views or benchmarks never moves the card. Ships with sample data for Claude Opus 5.5 against GPT-6.1 Sol, Gemini 4 Argon and Grok 4.7; prices and scores are labeled as samples.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `model` | `ModelCardModel` | `Claude Opus 5.5 (sample)` | The model the card describes: { id, name, provider, mark?, summary?, modalities?, contextWindow?, maxOutput?, knowledgeCutoff?, pricing?, scores? }. contextWindow and maxOutput are token counts (1_000_000 reads as 1M). knowledgeCutoff is an ISO month such as "2026-03" (shown as Mar 2026); any other string is shown as is. pricing is { input, output, cachedInput? } per million tokens. scores maps benchmark ids to numbers. A missing value reads as Not listed. |
| `rivals` | `ModelCardModel[]` | `GPT-6.1 Sol, Gemini 4 Argon, Grok 4.7 (sample)` | Other models. The first two appear under the model in the benchmark rows, ranks count every rival with a score, and every rival can be picked in the compare view. The model itself is filtered out, so one shared pool works for every model. Pass [] to hide the Compare switch. |
| `benchmarks` | `ModelCardBenchmark[]` | `SWE-bench Verified, GPQA Diamond, Terminal-Bench 2.0` | Benchmarks in order: { id, name, shortName?, description?, max?, unit? }. shortName labels the switcher, description follows the name in the caption, max fills a bar (default 100) and unit follows each score (default %). Only benchmarks the model has a score for are offered; with none the section hides. |
| `view` | `"details" \| "compare"` | – | Controlled view. Pair it with onViewChange. |
| `defaultView` | `"details" \| "compare"` | `"details"` | Starting view when uncontrolled. |
| `onViewChange` | `(view: ModelCardView) => void` | – | Called when the Compare switch changes. |
| `compareWith` | `string` | – | Controlled id of the rival in the compare view. Pair it with onCompareWithChange. |
| `defaultCompareWith` | `string` | `first rival` | Starting rival when uncontrolled. |
| `onCompareWithChange` | `(id: string) => void` | – | Called when a rival is picked from the compare menu. |
| `defaultBenchmark` | `string` | `first scored benchmark` | Benchmark shown first. |
| `onBenchmarkChange` | `(id: string) => void` | – | Called when the benchmark switcher changes. |
| `defaultMonthlyTokens` | `number` | `100_000_000` | Monthly token volume the cost estimator starts at. Snaps to the nearest stop: 1M, 5M, 10M, 25M, 50M, 100M, 250M, 500M or 1B. |
| `onMonthlyTokensChange` | `(tokens: number) => void` | – | Called with the new monthly volume as the slider moves. |
| `inputShare` | `number` | `0.75` | Share of the monthly volume billed at the input price; the rest is billed at the output price. |
| `currency` | `string` | `"USD"` | ISO 4217 currency for prices. |
| `sample` | `boolean` | `true` | Labels prices and scores as samples in the benchmark caption and the compare footnote. Set it to false once you wire real figures. |
| `loading` | `boolean` | `false` | Shows a skeleton of the card, disables Compare and sets aria-busy. |
| `error` | `string` | – | Replaces the body with an error message. The header still shows the model. |
| `onRetry` | `() => void` | – | Adds a Retry button to the error state. |
| `onCopyId` | `(id: string) => void` | – | Called after Copy model id writes the id to the clipboard. |
| `onSelect` | `(model: ModelCardModel) => void` | – | Adds a primary Use model button to the footer, for model pickers. |
| `selected` | `boolean` | `false` | Shows the select button as Selected with a check and aria-pressed. |
| `selectLabel` | `string` | `"Use model"` | Label for the select button. |
| `className` | `string` | – | Class on the root article. |
| `style` | `CSSProperties` | – | Inline style on the root article. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Tab | Moves through the Compare switch, the monthly volume slider, the benchmark switcher, each benchmark row (focus shows its score and rank), or the rival menu in the compare view, then Copy model id and Use model when present. Hidden views are inert, so Tab never lands in them. |
| Arrow keys / Page up / Home / End | On the volume slider, step through the monthly volumes; the estimated cost rolls to the new value. |
| Space / Enter | Toggles Compare, copies the model id or selects the model. |
| Arrow left / Arrow right | Moves between benchmarks in the switcher. |
| Enter / Arrow down | On the rival menu, opens it; arrows move between rivals and Enter picks one. Escape closes it. |

### Accessibility

- The card is an article labelled by the model name. Specs and prices are description lists, so each value is read with its label.
- The compare view is a table with column headers for the two models and a row header per spec. The better value carries a check icon and the text "better" for screen readers, so the comparison never relies on color.
- A polite status region says what changed when you switch views, rivals or benchmarks (for example "Comparing Claude Opus 5.5 with Gemini 4 Argon"). Copy model id announces Copied on its own.
- Benchmark bars are hidden from assistive technology; each row is focusable and labelled with the full readout (score, rank and gap to the leader). Marks are decorative and hidden, since the name is always written next to them.
- Modality chips say supported or not supported to screen readers; unsupported chips are dashed as well as muted, so the difference never relies on color.
- While loading, the card is aria-busy, the skeleton is hidden, Compare is disabled and the status region says Loading model details. An error is announced with role alert. Inactive panels are inert and aria-hidden.
- During a text swap the outgoing value is hidden from assistive technology, so names and values are never read twice.
- Pointer focus draws no ring; keyboard focus uses Arc's shared focus outline.

### Motion

- The card never changes size. Details, compare, loading and error are panels stacked in one grid cell, so the card is always as tall as the tallest panel; switching fades the old panel out in 100ms and the new one in over 160ms. Inside a panel every slot is reserved: two summary lines, all seven chips, every spec and price cell, a fixed number of benchmark rows and a readout that holds its lines.
- Switching models crossfades every text value in place and rolls prices, the estimated cost, page counts and scores to their new values in tabular numerals inside reserved widths. Bars and the context gauge slide on a critically damped spring (visualDuration 0.24, no bounce).
- Dragging the volume slider rolls the estimated cost live; the compare table's cost row follows the same volume.
- Hovering or focusing a benchmark row tints it, fades the other rows to half opacity and crossfades the readout to its score, rank and gap, all within 160ms.
- The bars grow from zero once, the first time the card is mostly in view, 40ms apart.
- Reduced motion keeps every end state and drops travel: views, bars, numbers and values change in place, and the skeleton holds still.

### Responsive behavior

- The card is fluid up to 640px and reads its own width with container queries, so it works in a narrow side pane as well as a page.
- Below a 480px card, specs and prices become rows of label and value under hairlines, the cost estimate drops under the slider, the benchmark switcher drops under its heading and the readout reserves three lines. Below 420px the summary reserves three lines. Below 360px each bar moves under its name.
- From a 520px card the compare table has a label column beside the two model columns and shows margins on the better value; narrower, each label sits above its two values and the mini bars and margins hide.
- The footer wraps the copy and select buttons under the model id when space runs out. It holds at 320px without horizontal scroll.

### Performance

- Bars animate transform only (scaleX) and numbers are written in place during the roll, so React renders once per change, not per frame.
- No measuring: the stacked grid cell reserves the height in CSS, so there is no ResizeObserver and no height animation.
- Nothing runs while idle: no loops apart from the CSS skeleton pulse while loading. Hidden panels stay mounted (inert) so values are ready the moment a view switches.

### Notes for AI

- Use real figures from your model catalog and set sample={false}; leave sample on while the numbers are placeholders. The bundled data is a plausible October 2026 sample, not official pricing or results.
- Keep the summary to one sentence of about 90 characters; the card reserves two lines (three on narrow cards) and clamps anything longer.
- Give scores for the same benchmark ids on the model and its rivals. A row without a score shows None and the compare table shows Not listed, so rows never appear or disappear.
- Pass one shared pool as rivals when the model changes (the card filters out the current model), so the benchmark rows and ranks stay stable while values roll.
- Copy marks from model-card-marks.tsx (Claude, OpenAI, Gemini, Grok) or pass any SVG with aria-hidden. Mono marks follow the text color; set style={{ color }} for a brand color, as the Claude mark does. Brand marks are sample content, never an implied endorsement.
- Price cells read per million tokens. Omit cachedInput to show two price cells.
- For a list of many models, render a compact picker and show one ModelCard for the highlighted model; the card is a detail view, not a row.

### Related

- [Model picker](https://uiarc.dev/components/blocks/model-picker/markdown): A model picker in one quiet pill: open it to choose from featured models with a one line note each, set the reasoning effort, or browse every other model by provider, and the pill swaps to your choice in place.
- [Context window](https://uiarc.dev/components/context-window/markdown): An AI context window as a grid of 200 cells: the system prompt, tools, files, summary and messages fill it in order, a threshold row marks where compaction starts, and sending a message, attaching a file or compacting shows exactly how much still fits.
- [Copy button](https://uiarc.dev/components/copy-button/markdown): Copy a value with immediate confirmation.
- [Segmented control](https://uiarc.dev/components/segmented-control/markdown): Switch between a small set of related views.
- [Switch](https://uiarc.dev/components/switch/markdown): A tactile toggle for settings that take effect immediately.
- [Dropdown menu](https://uiarc.dev/components/dropdown-menu/markdown): A focused list of actions anchored to a trigger.
- [Slider](https://uiarc.dev/components/slider/markdown): Pick a value or a range on a track that follows your finger.

### Also in ai

- [Agent status](https://uiarc.dev/components/agent-status/markdown): A compact live status pill for a running AI agent: the agent's mark in a live ring, the current activity and an elapsed timer, opening into the steps so far.
- [Tool call](https://uiarc.dev/components/tool-call/markdown): A tool call row for agent transcripts: the tool's mark and the call in plain words, a live state while it runs, and the input and output a click away, with approval and retry when needed.
- [Agent plan](https://uiarc.dev/components/agent-plan/markdown): The plan an agent writes before it acts: edit, reorder or add steps while it is a draft, then watch it work through them as a live checklist.
- [Agent timeline](https://uiarc.dev/components/agent-timeline/markdown): A compact timeline of one orchestrated agent run: the orchestrator and its subagents share a time axis, handoffs draw in between rows, and a playhead replays thinking, tool calls and waiting while the header counts time, tokens and cost. Hover a span for what it did, or click it to trace its handoff path.
- [Reasoning block](https://uiarc.dev/components/reasoning-block/markdown): The collapsible thinking block of an AI reply. While the model thinks, a shimmering label counts the seconds and the latest reasoning streams underneath. When it finishes, it folds to "Thought for 7s" and opens to show the full reasoning as calm steps with headings.
- [Source cards](https://uiarc.dev/components/source-cards/markdown): A row of cited sources under an AI answer where cards stream in with real site marks while the model searches, the overflow collapses into a stack of favicons, hovering lifts a preview with the passage, and an inline [n] citation highlights its card.
- [AI workflow](https://uiarc.dev/components/ai-workflow/markdown): A Linear-style AI workflow card where a Gmail trigger, a Claude step, a branch and Slack and Linear actions sit on one hairline rail, and a test run glides down it, opening each step's output inline. Steps are added from a compact command menu with real app marks.
- [Code suggestion](https://uiarc.dev/components/code-suggestion/markdown): An AI code edit suggestion where the model's proposed changes stream into a small editor panel as inline diff hunks, and you accept or reject each one, or all at once with Cmd+Enter. Accepted hunks fold into the file with a smooth height change.
- [Ghost text](https://uiarc.dev/components/ghost-text/markdown): An inline AI autocomplete where muted ghost text continues your sentence exactly at the caret and Tab turns it solid in place. Cmd+Right takes it one word at a time, Escape fades it away, and a calm chip shows the model behind it.
- [Image generation](https://uiarc.dev/components/image-generation/markdown): An image studio where each image forms on a dot matrix: a soft halftone wave breathes across the grid, the dots take the colours of the coming photo and grow into a coloured halftone, then blur away into the sharp photo. One large canvas with a mono size label, a filmstrip of four variations, a prompt bar with model and ratio, and upscale with a sweeping dot band, vary or download, with real provider marks and a built-in simulation.
- [Dictation button](https://uiarc.dev/components/dictation-button/markdown): A chat composer with voice input, where the mic springs into a recording pill with a smooth live waveform, a timer, and cancel and insert buttons. Words stream into the field as you speak, muted until the recognizer settles them.
- [Speech player](https://uiarc.dev/components/speech-player/markdown): A read-aloud player for AI replies. The Read aloud button in the message's action row turns into a compact player with play, a scrubbable progress bar, speed and a voice picker, and a highlight follows the spoken word through the reply, karaoke style.
- [Meeting summary](https://uiarc.dev/components/meeting-summary/markdown): An AI meeting notes card: the header shows the Google Meet or Zoom mark, the attendees and the duration. Summary, Decisions and Action items stream in after a short summarizing pass. Hover any line to see the transcript quote it came from, then check off action items or send them to Linear or Notion.
- [Reply draft](https://uiarc.dev/components/reply-draft/markdown): An AI email reply drafter where Claude streams a reply under a received Gmail message. Quick replies steer a fresh draft, tone and length rewrite it with a single crossfade, and you can edit the finished draft before you insert it.
- [Agent handoff](https://uiarc.dev/components/agent-handoff/markdown): A support conversation where an AI assistant hands off to a person. When it transfers, a card shows the summary it passes to the team and the typical wait. The person then joins and takes over, and a thin timeline on the left marks each step.
- [PII redaction](https://uiarc.dev/components/pii-redaction/markdown): A guardrail card where personal data is redacted before the prompt reaches the model. Scan marks each name, email, phone number and card with its type and swaps it for a placeholder like [EMAIL_1]. The safe prompt travels to Claude, and the reply comes back with the original values put back for the person.
- [Response feedback](https://uiarc.dev/components/response-feedback/markdown): A feedback control for AI replies where thumbs down opens an inline panel with reason chips and an optional note, thumbs up fills and asks what was good, and a submit shows a short thank-you before folding back into the row.
- [LLM cost calculator](https://uiarc.dev/components/llm-cost-calculator/markdown): A pricing calculator for LLM workloads. Set tokens per request, requests per day and prompt caching, and eight current models re-rank by monthly cost. Bars glide and prices roll as you drag.
- [Provider keys](https://uiarc.dev/components/provider-keys/markdown): A settings card for bring-your-own-key AI products. Each provider row shows its real mark, the masked key, a status and when the key was last used. You can reveal a key for five seconds, copy, rotate or remove it with undo. Adding or rotating a key opens an inline form that checks the format as you type, then tests the connection before saving.
- [Generation stats](https://uiarc.dev/components/generation-stats/markdown): A live stats strip for a streaming LLM response where time to first token, speed with a sparkline, output tokens and cost count up in tabular numerals beside the model's real mark, then settle and open into a latency and token cost breakdown.
- [AI translate](https://uiarc.dev/components/ai-translate/markdown): A message card where picking a language streams the AI translation in place, sentence by sentence over the dimmed original, with a detected-language chip, a Show original toggle and a status line credited to the model's mark.
- [TL;DR toggle](https://uiarc.dev/components/tldr-toggle/markdown): An article card with a Full, Summary and Key points switch and a length slider. Switching streams an AI summary in place of the article as the card's height springs to fit, and each key point links back to the paragraph it came from, which gets scrolled to and highlighted.
- [Connector setup](https://uiarc.dev/components/connector-setup/markdown): A "Connect your tools" card for an AI assistant. Each app connects inline: it redirects, authorizes and runs a first sync with a progress hairline, then lists the scopes it was granted and offers Disconnect with an inline confirm.
- [Smart form fill](https://uiarc.dev/components/smart-form-fill/markdown): A paste-to-fill form card where AI reads an email signature or messy notes and fills a contact field by field. Each value flashes in with a confidence dot, its source lights up in the pasted text, low-confidence guesses ask for review, and Undo puts the old values back.
- [Enrich column](https://uiarc.dev/components/enrich-column/markdown): An AI enrichment column for a data table, where one prompt runs down every row and each cell shimmers while it works, then settles into a value with its source or a failure you can retry.
- [Ticket router](https://uiarc.dev/components/ticket-router/markdown): A support ticket router where messages from Gmail, Intercom, Slack and Zendesk come in one at a time. An AI classifier labels each one with intent, sentiment and confidence, and the ticket moves into a team lane with an assignee. Low confidence tickets wait in a review lane, and one click there routes them to the suggested team.
- [Ask your data](https://uiarc.dev/components/ask-your-data/markdown): A natural language to chart card: you ask a question, PostgreSQL streams into a collapsible, syntax highlighted panel, the query runs with a rolling row count, and the answer builds as stacked bars, lines or a table, with a one line insight streamed in underneath.
- [Agent cursor](https://uiarc.dev/components/agent-cursor/markdown): A live document where Claude edits like a collaborator. Its labeled cursor comes out of its avatar, selects a paragraph and streams in a rewrite, adds a heading and fixes a typo, while a teammate's cursor reads along. Changes stay tinted until someone accepts or undoes them from a floating review bar.
- [Provider status](https://uiarc.dev/components/provider-status/markdown): A status card for the AI providers your product depends on. Each row shows the provider's real mark, its health as an icon and label, p50 latency and a 30-day uptime bar with a tooltip for each day. An incident row expands into its timeline of updates, and the card checks again on a visible countdown.
- [Training run](https://uiarc.dev/components/training-run/markdown): A fine-tuning job card where a live train and validation loss curve draws across a fixed step axis that doubles as the epoch progress bar. It shows the learning rate, elapsed time, ETA and the latest evals and checkpoints, has Pause and Cancel while it runs, and ends in results with a Deploy button.
- [AI command](https://uiarc.dev/components/ai-command/markdown): A Cmd+K command palette with an AI mode. Search pages and actions, or press Tab to ask a question: the answer streams inside the palette with numbered sources, and the next steps it suggests, like filing a Linear issue or opening a Notion doc, run straight from the list.
- [Starter prompts](https://uiarc.dev/components/starter-prompts/markdown): A greeting and a grid of starter cards for the empty state of an AI app. The cards are grouped into Write, Code, Analyze and Plan tabs, and a shuffle swaps them with a short staggered crossfade. Picking a card fills the composer, and cards that use a connected app show its mark (Gmail, GitHub, Notion, Linear, Google Calendar).
- [AI mascot](https://uiarc.dev/components/ai-mascot/markdown): A small assistant character, a soft pebble with pill eyes and a companion dot, that shows what the AI is doing. It breathes and glances when idle, leans in to listen, looks up while the dot orbits its head, reads along the line it writes, squints with a sparkle when done and shakes once with worried brows on an error.
- [Image reveal](https://uiarc.dev/components/image-reveal/markdown): An image generation canvas where a soft, blurred preview made from the image's own colors sharpens top to bottom behind a soft-edged band. It works the way ChatGPT, Midjourney and Gemini show images forming, with fine film grain, a translucent progress pill and calm queued and error states.
- [AI spark](https://uiarc.dev/components/ai-spark/markdown): A brand-quality animated spark mark. Four tapered rays and four lighter diagonals breathe at rest, ripple while thinking, pulse like a heartbeat while writing, then gather and settle when done. Every status change blends from the pose the mark is already in.
- [Pixel mascot](https://uiarc.dev/components/pixel-mascot/markdown): A pixel-art robot that shows what an AI assistant is doing. It idles, thinks, types, celebrates and errors in frame-stepped sprite animations, and stays crisp at every integer size from 24px to 192px.
- [Ghost mascot](https://uiarc.dev/components/ghost-mascot/markdown): A floating ghost mascot whose soft sheet ripples at the hem while it hovers. It blinks when idle, turns toward you to listen, fades a little translucent while thinking, draws a tiny pen line while writing, smiles with a sparkle when done and wobbles once on an error.
- [Cube mascot](https://uiarc.dev/components/cube-mascot/markdown): An isometric cube mascot where three shaded faces and a painted-on face show what the assistant is doing. It turns a quarter turn in eased steps while thinking, prints lines onto the floor while writing, settles with a sparkle when done, and shakes once on error.
- [Tone tuner](https://uiarc.dev/components/tone-tuner/markdown): A brand voice card where two sliders (formality and detail) and Friendly, Confident and Empathetic chips rewrite a customer reply. Each changed sentence crossfades in place, new words can be highlighted against the original, and Copy takes the current version.
- [Upgrade prompt](https://uiarc.dev/components/upgrade-prompt/markdown): An upgrade nudge for the moment someone hits a limit. It shows a usage meter at 50 of 50 AI credits, a rolling price with a monthly and yearly toggle, three concrete unlocks with real model marks, and Upgrade or Maybe later. Upgrading leads into a success state with the new limits, and the card never changes size between states.
- [Referral card](https://uiarc.dev/components/referral-card/markdown): A give-and-get referral card where people copy or share their invite link, invite friends by email as chips, and watch invites move from invited to signed up to earned, with the credit total counting up and a milestone reward unlocking.
- [Trial banner](https://uiarc.dev/components/trial-banner/markdown): A trial status banner where a ring counts down the days left, the copy names what the workspace loses, and the upgrade path is one click away. It comes as a slim banner, a sidebar card or a header pill. It shifts to a warning tone in the last days, has expired and upgraded states, and folds into the pill when dismissed or snoozed.
- [Team switcher](https://uiarc.dev/components/team-switcher/markdown): A workspace switcher like Linear, Vercel or Slack. The trigger shows the current workspace's logo and plan. The menu has search, your role in each workspace and a Cmd+1 to 9 shortcut for each, and lets you create or join a workspace inline. A highlight glides between rows, and switching crossfades the trigger through a short loading state.
- [Live visitors](https://uiarc.dev/components/live-visitors/markdown): A realtime visitors card where the live count rolls digit by digit, new arrivals ping in on a dotted world map, the top pages reorder with bars, and signups and upgrades tick in with country flags.
- [Social proof toast](https://uiarc.dev/components/social-proof-toast/markdown): A stack of social proof notifications for landing and pricing pages, where recent trials, upgrades and verified purchases from people and companies arrive every few seconds. The stack pauses and fans out on hover, and visitors can dismiss any toast.
- [Install snippet](https://uiarc.dev/components/install-snippet/markdown): A "get started in 30 seconds" card where framework tabs, three numbered steps and highlighted snippets take a developer from install to first event. Generate key wipes a fresh API key into the placeholder in place.

### Guidance for AI tools

Model card: A model details card where switching models rolls every price, limit and score in place, a token slider estimates monthly cost live, and benchmark bars show each model's rank on hover. Compare crossfades to a side-by-side table against any rival with the better values marked, and the card never changes size. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## AI workflow

> A Linear-style AI workflow card where a Gmail trigger, a Claude step, a branch and Slack and Linear actions sit on one hairline rail, and a test run glides down it, opening each step's output inline. Steps are added from a compact command menu with real app marks.

- Type: Component (special)
- Access: Arc Pro
- Page: https://uiarc.dev/components/ai-workflow
- Markdown: https://uiarc.dev/components/ai-workflow/markdown
- Source file: `registry/components/ai-workflow/ai-workflow.tsx`
- Dependencies: motion, lucide-react, @radix-ui/react-popover
- Keywords: special, ai, new, workflow builder, automation, zapier, n8n, make, ai workflow, flow builder, trigger action, test run, integration, branch, claude, gmail, slack, linear

### When to use

- An automation or integrations page where people assemble a short trigger, AI step and action flow and want to test it in place.
- Onboarding or marketing surfaces that show how an AI step slots between real apps, with a working test run.
- Reviewing what an existing workflow does and seeing a sample run's outputs step by step.

### When not to use

- Large free-form graphs with many branches, loops or merges: use a canvas editor instead.
- Showing a single tool call or a live agent's steps: use tool-call or agent-run.
- Scheduling recurring agent jobs: use agent-routines.

### Installation

AI workflow is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/ai-workflow
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { useState } from "react";
import { AiWorkflow, workflowSampleSteps } from "@/components/arc/ai-workflow/ai-workflow";
import type { WorkflowStep } from "@/components/arc/ai-workflow/ai-workflow";

export function SupportAutomation() {
  const [steps, setSteps] = useState<WorkflowStep[]>(workflowSampleSteps);
  return (
    <AiWorkflow
      title="Escalate urgent support email"
      steps={steps}
      onStepsChange={setSteps}
      autoPlay={false}
      onRunStep={async (step, { signal, previous }) => {
        const res = await fetch(`/api/workflows/test/${step.id}`, { method: "POST", body: JSON.stringify({ previous }), signal });
        if (!res.ok) throw new Error((await res.json()).message);
        return res.json();
      }}
    />
  );
}
```

### API reference

#### AiWorkflow

A compact, Linear-style automation builder card with an AI step. Steps are 32px rows on one 1px hairline rail: a trigger (New email in Gmail), an AI step (Classify with Claude Sonnet 5.5), a branch (Route by label) whose paths switch with small tabs, and actions (Post to #support in Slack, Create Linear issue). Test run glides a small accent dot down each connector while the line behind it fills; each step crossfades to Running with a shimmering activity line, then shows its duration and an inline output preview in small muted text (the email, the label with a streamed reason, the posted message, the created issue). The untaken path is marked Skipped. A failing step shows its error and Retry, which resumes the run from that step. Steps are added from a command menu (search field, compact rows with real app marks and number shortcuts) and removed with a small button. With no props it plays the sample flow, simulated, and says so.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` | `string` | `"Escalate urgent support email"` | Workflow name in the header. |
| `description` | `string` | `"Runs on every new email to support@northwind.dev"` | One line of context under the name. |
| `steps` | `WorkflowStep[]` | – | Controlled steps. Pair with onStepsChange so adding and removing keep working. Each step has id, kind ("trigger" \| "ai" \| "action" \| "branch"), app (a built-in id or { name, mark }), title, and optional detail, activity, output, durationMs and error. A branch carries paths: { id, label, steps }[] and must be the last top-level step. |
| `defaultSteps` | `WorkflowStep[]` | `workflowSampleSteps` | Initial steps when uncontrolled. Pass [] for the empty state, which lists the catalog's triggers as compact rows. |
| `onStepsChange` | `(steps: WorkflowStep[]) => void` | – | Called after a step is added or removed. New steps land at the end of the flow, or at the end of the visible path when the flow ends in a branch. |
| `catalog` | `WorkflowCatalogItem[]` | `workflowSampleCatalog` | Entries for the add step command menu: the same shape as a step without id. Triggers are offered in the empty state; everything else goes in the menu. Pass [] to hide the menu. |
| `onRunStep` | `(step: WorkflowStep, context: { signal: AbortSignal; previous: Record<string, WorkflowOutput>; attempt: number }) => Promise<WorkflowOutput \| void>` | – | Runs one step for real and returns its output. Throw to fail the step with the error message. A branch returns { type: "route", pathId } to pick its path. The signal aborts on Stop, a new run or unmount. Without it, runs are simulated from each step's sample output and durationMs. |
| `onRunComplete` | `(result: { status: "passed" \| "failed"; durationMs: number; outputs: Record<string, WorkflowOutput>; failedStepId?: string }) => void` | – | Called when a test run passes or stops on a failed step. |
| `loading` | `boolean` | `false` | Shows three skeleton steps while your flow loads. Test run and the add menu are unavailable. |
| `autoPlay` | `boolean` | `true` | Plays a test run once the card is in view and repeats it after a short pause until someone presses or types inside the card. Nothing is scheduled while the card is off screen. |
| `editable` | `boolean` | `true` | Shows the add step menu and the remove buttons. Triggers cannot be removed. |
| `className` | `string` | – | Class on the root section. |

#### WorkflowOutput

The output preview union a step can return, rendered inline in small muted text under the step, aligned with its title.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `email` | `{ type: "email"; from: string; address?: string; subject: string; preview: string }` | – | Sender, subject on one line and a two line preview. |
| `label` | `{ type: "label"; label: string; confidence?: number; reason?: string }` | – | A hairline label with a status dot, confidence (0 to 1) in monospace, and a reason that streams in fast chunks. |
| `route` | `{ type: "route"; pathId: string; note?: string }` | – | Which branch path ran. |
| `message` | `{ type: "message"; channel: string; author: string; text: string }` | – | A posted chat message. |
| `record` | `{ type: "record"; id: string; title: string; meta?: string }` | – | A created or updated record: an issue key, a row, a ticket or a page. |
| `text` | `{ type: "text"; text: string }` | – | Free text such as a drafted reply, streamed in fast chunks. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Tab | Moves through Test run (or Stop), each step's remove button, the branch path tabs, Retry on a failed step, and the Add step button. |
| Enter / Space | Starts or stops a test run, removes a step, retries a failed step, or opens the add step menu. |
| Arrow keys | Move between paths in the branch tabs (Home and End jump to the ends). In the open menu, Up and Down move the highlighted row. |
| Type | Filters the add step menu by step title, app or detail. |
| Enter (menu) | Adds the highlighted step and closes the menu. |
| 1 to 9 (menu) | With an empty search, adds the step with that shortcut. |
| Escape | Closes the add step menu and returns focus to its trigger. |

### Accessibility

- The card is a labelled section with aria-busy while a run is in progress or steps are loading; steps are an ordered list, and each branch path is its own labelled list.
- Every step title carries its app and status for screen readers ("Create Linear issue, Linear, Done in 700ms"). Status is shown as an icon plus a short label, never color alone.
- A polite live region announces run start, each step's result, failures with their message, and the outcome, including "Simulated, nothing was sent" when no onRunStep is wired.
- The add step menu is a combobox: the search field owns focus and points at the highlighted option with aria-activedescendant; options are a listbox. Branch paths are a radio group with roving focus.
- Remove buttons are named per step ("Remove Create Linear issue") and are hidden only visually on hover devices until the row is hovered or the button is focused.
- Brand marks are decorative next to the visible step title; marks whose brand color is near black draw in currentColor so they keep contrast in dark mode.

### Motion

- A test run moves one thing at a time: a 5px accent dot glides down the next connector in 240ms while the line behind it fills, then the step crossfades to Running (icon and label) and its detail line crossfades to a shimmering activity line.
- Everything is bounce-free and 100 to 240ms. Output previews and added or removed steps open and close on measured height with a critically damped spring (visualDuration 0.22, bounce 0); switching paths crossfades the lists (100ms out, 160ms in) while the container height follows, and the tab highlight slides on the same spring.
- Status labels crossfade in a fixed 72px slot, so titles never shift. Reasons and drafts stream five words every 34ms, each chunk only fading in, with the final layout reserved from the first frame.
- The add step menu fades and settles in 150 to 180ms with no spring overshoot; filtering animates the list to its new measured height.
- Autoplay pauses while the card is off screen and stops for good after the first press or key inside the card.
- Reduced motion drops the traveling dot, line growth and height animation; states, outputs and the live region stay the same.

### Responsive behavior

- Fills its container up to 640px. Above 480px each step is one 32px row with the detail inline after the title; below that rows grow to 44px and stack the detail under the title, the status slot narrows to 64px and the header wraps to two lines.
- The empty state's trigger rows drop their detail text below 480px of card width.
- Remove buttons are always visible on touch screens and appear on hover or focus with a fine pointer.

### Performance

- One state update per step change; the rail and dot animate transform and opacity in CSS, and previews animate measured height only.
- Streaming renders the whole text once and toggles chunk opacity, so it never reflows. Autoplay timers stop off screen via IntersectionObserver.
- Marks are inline SVG with no network requests.

### Notes for AI

- Pick this to show or edit an automation that mixes app triggers, an LLM step and app actions, such as triage, routing or enrichment flows, inside a product settings page or onboarding.
- Wire onRunStep to a test endpoint and return the WorkflowOutput union so previews render; throw to show the failure state with Retry. Keep autoPlay off in real products.
- Use only current model names in AI step titles (Claude Sonnet 5.5, GPT-6.1 Sol, Gemini 4 Argon). Built-in app ids: gmail, slack, linear, claude, notion, sheets, hubspot, zendesk, github, stripe, branch; pass { name, mark } for anything else.
- One branch per flow, as the last top-level step. For multi-agent graphs or a run log, choose agent-orchestrator or agent-run instead.

### Related

- [Agent run](https://uiarc.dev/components/blocks/agent-run/markdown): A single card that follows one AI coding agent through a task: steps stream in with the live one shimmering, tool calls open in place, and the agent stops on a two-file diff for you to approve or send back before it writes. When the run ends, the steps fold into one line and a result shows the files changed, the checks that passed and a pull request button.
- [Agent plan](https://uiarc.dev/components/agent-plan/markdown): The plan an agent writes before it acts: edit, reorder or add steps while it is a draft, then watch it work through them as a live checklist.
- [Tool call](https://uiarc.dev/components/tool-call/markdown): A tool call row for agent transcripts: the tool's mark and the call in plain words, a live state while it runs, and the input and output a click away, with approval and retry when needed.
- [Agent routines](https://uiarc.dev/components/blocks/agent-routines/markdown): Scheduled agents in one card: each routine reads as a sentence with its schedule, next run countdown, connectors and destination, and opens smoothly to edit or run it now.
- [Connector setup](https://uiarc.dev/components/connector-setup/markdown): A "Connect your tools" card for an AI assistant. Each app connects inline: it redirects, authorizes and runs a first sync with a progress hairline, then lists the scopes it was granted and offers Disconnect with an inline confirm.
- [Agent orchestrator](https://uiarc.dev/components/blocks/agent-orchestrator/markdown): A lead agent splits a goal into a plan, fans the subtasks out to parallel worker lanes and merges what comes back, with each lane's model, progress and result in view.

### Also in ai

- [Agent status](https://uiarc.dev/components/agent-status/markdown): A compact live status pill for a running AI agent: the agent's mark in a live ring, the current activity and an elapsed timer, opening into the steps so far.
- [Agent timeline](https://uiarc.dev/components/agent-timeline/markdown): A compact timeline of one orchestrated agent run: the orchestrator and its subagents share a time axis, handoffs draw in between rows, and a playhead replays thinking, tool calls and waiting while the header counts time, tokens and cost. Hover a span for what it did, or click it to trace its handoff path.
- [Context window](https://uiarc.dev/components/context-window/markdown): An AI context window as a grid of 200 cells: the system prompt, tools, files, summary and messages fill it in order, a threshold row marks where compaction starts, and sending a message, attaching a file or compacting shows exactly how much still fits.
- [Reasoning block](https://uiarc.dev/components/reasoning-block/markdown): The collapsible thinking block of an AI reply. While the model thinks, a shimmering label counts the seconds and the latest reasoning streams underneath. When it finishes, it folds to "Thought for 7s" and opens to show the full reasoning as calm steps with headings.
- [Source cards](https://uiarc.dev/components/source-cards/markdown): A row of cited sources under an AI answer where cards stream in with real site marks while the model searches, the overflow collapses into a stack of favicons, hovering lifts a preview with the passage, and an inline [n] citation highlights its card.
- [Model card](https://uiarc.dev/components/model-card/markdown): A model details card where switching models rolls every price, limit and score in place, a token slider estimates monthly cost live, and benchmark bars show each model's rank on hover. Compare crossfades to a side-by-side table against any rival with the better values marked, and the card never changes size.
- [Code suggestion](https://uiarc.dev/components/code-suggestion/markdown): An AI code edit suggestion where the model's proposed changes stream into a small editor panel as inline diff hunks, and you accept or reject each one, or all at once with Cmd+Enter. Accepted hunks fold into the file with a smooth height change.
- [Ghost text](https://uiarc.dev/components/ghost-text/markdown): An inline AI autocomplete where muted ghost text continues your sentence exactly at the caret and Tab turns it solid in place. Cmd+Right takes it one word at a time, Escape fades it away, and a calm chip shows the model behind it.
- [Image generation](https://uiarc.dev/components/image-generation/markdown): An image studio where each image forms on a dot matrix: a soft halftone wave breathes across the grid, the dots take the colours of the coming photo and grow into a coloured halftone, then blur away into the sharp photo. One large canvas with a mono size label, a filmstrip of four variations, a prompt bar with model and ratio, and upscale with a sweeping dot band, vary or download, with real provider marks and a built-in simulation.
- [Dictation button](https://uiarc.dev/components/dictation-button/markdown): A chat composer with voice input, where the mic springs into a recording pill with a smooth live waveform, a timer, and cancel and insert buttons. Words stream into the field as you speak, muted until the recognizer settles them.
- [Speech player](https://uiarc.dev/components/speech-player/markdown): A read-aloud player for AI replies. The Read aloud button in the message's action row turns into a compact player with play, a scrubbable progress bar, speed and a voice picker, and a highlight follows the spoken word through the reply, karaoke style.
- [Meeting summary](https://uiarc.dev/components/meeting-summary/markdown): An AI meeting notes card: the header shows the Google Meet or Zoom mark, the attendees and the duration. Summary, Decisions and Action items stream in after a short summarizing pass. Hover any line to see the transcript quote it came from, then check off action items or send them to Linear or Notion.
- [Reply draft](https://uiarc.dev/components/reply-draft/markdown): An AI email reply drafter where Claude streams a reply under a received Gmail message. Quick replies steer a fresh draft, tone and length rewrite it with a single crossfade, and you can edit the finished draft before you insert it.
- [Agent handoff](https://uiarc.dev/components/agent-handoff/markdown): A support conversation where an AI assistant hands off to a person. When it transfers, a card shows the summary it passes to the team and the typical wait. The person then joins and takes over, and a thin timeline on the left marks each step.
- [PII redaction](https://uiarc.dev/components/pii-redaction/markdown): A guardrail card where personal data is redacted before the prompt reaches the model. Scan marks each name, email, phone number and card with its type and swaps it for a placeholder like [EMAIL_1]. The safe prompt travels to Claude, and the reply comes back with the original values put back for the person.
- [Response feedback](https://uiarc.dev/components/response-feedback/markdown): A feedback control for AI replies where thumbs down opens an inline panel with reason chips and an optional note, thumbs up fills and asks what was good, and a submit shows a short thank-you before folding back into the row.
- [LLM cost calculator](https://uiarc.dev/components/llm-cost-calculator/markdown): A pricing calculator for LLM workloads. Set tokens per request, requests per day and prompt caching, and eight current models re-rank by monthly cost. Bars glide and prices roll as you drag.
- [Provider keys](https://uiarc.dev/components/provider-keys/markdown): A settings card for bring-your-own-key AI products. Each provider row shows its real mark, the masked key, a status and when the key was last used. You can reveal a key for five seconds, copy, rotate or remove it with undo. Adding or rotating a key opens an inline form that checks the format as you type, then tests the connection before saving.
- [Generation stats](https://uiarc.dev/components/generation-stats/markdown): A live stats strip for a streaming LLM response where time to first token, speed with a sparkline, output tokens and cost count up in tabular numerals beside the model's real mark, then settle and open into a latency and token cost breakdown.
- [AI translate](https://uiarc.dev/components/ai-translate/markdown): A message card where picking a language streams the AI translation in place, sentence by sentence over the dimmed original, with a detected-language chip, a Show original toggle and a status line credited to the model's mark.
- [TL;DR toggle](https://uiarc.dev/components/tldr-toggle/markdown): An article card with a Full, Summary and Key points switch and a length slider. Switching streams an AI summary in place of the article as the card's height springs to fit, and each key point links back to the paragraph it came from, which gets scrolled to and highlighted.
- [Smart form fill](https://uiarc.dev/components/smart-form-fill/markdown): A paste-to-fill form card where AI reads an email signature or messy notes and fills a contact field by field. Each value flashes in with a confidence dot, its source lights up in the pasted text, low-confidence guesses ask for review, and Undo puts the old values back.
- [Enrich column](https://uiarc.dev/components/enrich-column/markdown): An AI enrichment column for a data table, where one prompt runs down every row and each cell shimmers while it works, then settles into a value with its source or a failure you can retry.
- [Ticket router](https://uiarc.dev/components/ticket-router/markdown): A support ticket router where messages from Gmail, Intercom, Slack and Zendesk come in one at a time. An AI classifier labels each one with intent, sentiment and confidence, and the ticket moves into a team lane with an assignee. Low confidence tickets wait in a review lane, and one click there routes them to the suggested team.
- [Ask your data](https://uiarc.dev/components/ask-your-data/markdown): A natural language to chart card: you ask a question, PostgreSQL streams into a collapsible, syntax highlighted panel, the query runs with a rolling row count, and the answer builds as stacked bars, lines or a table, with a one line insight streamed in underneath.
- [Agent cursor](https://uiarc.dev/components/agent-cursor/markdown): A live document where Claude edits like a collaborator. Its labeled cursor comes out of its avatar, selects a paragraph and streams in a rewrite, adds a heading and fixes a typo, while a teammate's cursor reads along. Changes stay tinted until someone accepts or undoes them from a floating review bar.
- [Provider status](https://uiarc.dev/components/provider-status/markdown): A status card for the AI providers your product depends on. Each row shows the provider's real mark, its health as an icon and label, p50 latency and a 30-day uptime bar with a tooltip for each day. An incident row expands into its timeline of updates, and the card checks again on a visible countdown.
- [Training run](https://uiarc.dev/components/training-run/markdown): A fine-tuning job card where a live train and validation loss curve draws across a fixed step axis that doubles as the epoch progress bar. It shows the learning rate, elapsed time, ETA and the latest evals and checkpoints, has Pause and Cancel while it runs, and ends in results with a Deploy button.
- [AI command](https://uiarc.dev/components/ai-command/markdown): A Cmd+K command palette with an AI mode. Search pages and actions, or press Tab to ask a question: the answer streams inside the palette with numbered sources, and the next steps it suggests, like filing a Linear issue or opening a Notion doc, run straight from the list.
- [Starter prompts](https://uiarc.dev/components/starter-prompts/markdown): A greeting and a grid of starter cards for the empty state of an AI app. The cards are grouped into Write, Code, Analyze and Plan tabs, and a shuffle swaps them with a short staggered crossfade. Picking a card fills the composer, and cards that use a connected app show its mark (Gmail, GitHub, Notion, Linear, Google Calendar).
- [AI mascot](https://uiarc.dev/components/ai-mascot/markdown): A small assistant character, a soft pebble with pill eyes and a companion dot, that shows what the AI is doing. It breathes and glances when idle, leans in to listen, looks up while the dot orbits its head, reads along the line it writes, squints with a sparkle when done and shakes once with worried brows on an error.
- [Image reveal](https://uiarc.dev/components/image-reveal/markdown): An image generation canvas where a soft, blurred preview made from the image's own colors sharpens top to bottom behind a soft-edged band. It works the way ChatGPT, Midjourney and Gemini show images forming, with fine film grain, a translucent progress pill and calm queued and error states.
- [AI spark](https://uiarc.dev/components/ai-spark/markdown): A brand-quality animated spark mark. Four tapered rays and four lighter diagonals breathe at rest, ripple while thinking, pulse like a heartbeat while writing, then gather and settle when done. Every status change blends from the pose the mark is already in.
- [Pixel mascot](https://uiarc.dev/components/pixel-mascot/markdown): A pixel-art robot that shows what an AI assistant is doing. It idles, thinks, types, celebrates and errors in frame-stepped sprite animations, and stays crisp at every integer size from 24px to 192px.
- [Ghost mascot](https://uiarc.dev/components/ghost-mascot/markdown): A floating ghost mascot whose soft sheet ripples at the hem while it hovers. It blinks when idle, turns toward you to listen, fades a little translucent while thinking, draws a tiny pen line while writing, smiles with a sparkle when done and wobbles once on an error.
- [Cube mascot](https://uiarc.dev/components/cube-mascot/markdown): An isometric cube mascot where three shaded faces and a painted-on face show what the assistant is doing. It turns a quarter turn in eased steps while thinking, prints lines onto the floor while writing, settles with a sparkle when done, and shakes once on error.
- [Tone tuner](https://uiarc.dev/components/tone-tuner/markdown): A brand voice card where two sliders (formality and detail) and Friendly, Confident and Empathetic chips rewrite a customer reply. Each changed sentence crossfades in place, new words can be highlighted against the original, and Copy takes the current version.
- [Upgrade prompt](https://uiarc.dev/components/upgrade-prompt/markdown): An upgrade nudge for the moment someone hits a limit. It shows a usage meter at 50 of 50 AI credits, a rolling price with a monthly and yearly toggle, three concrete unlocks with real model marks, and Upgrade or Maybe later. Upgrading leads into a success state with the new limits, and the card never changes size between states.
- [Referral card](https://uiarc.dev/components/referral-card/markdown): A give-and-get referral card where people copy or share their invite link, invite friends by email as chips, and watch invites move from invited to signed up to earned, with the credit total counting up and a milestone reward unlocking.
- [Trial banner](https://uiarc.dev/components/trial-banner/markdown): A trial status banner where a ring counts down the days left, the copy names what the workspace loses, and the upgrade path is one click away. It comes as a slim banner, a sidebar card or a header pill. It shifts to a warning tone in the last days, has expired and upgraded states, and folds into the pill when dismissed or snoozed.
- [Team switcher](https://uiarc.dev/components/team-switcher/markdown): A workspace switcher like Linear, Vercel or Slack. The trigger shows the current workspace's logo and plan. The menu has search, your role in each workspace and a Cmd+1 to 9 shortcut for each, and lets you create or join a workspace inline. A highlight glides between rows, and switching crossfades the trigger through a short loading state.
- [Live visitors](https://uiarc.dev/components/live-visitors/markdown): A realtime visitors card where the live count rolls digit by digit, new arrivals ping in on a dotted world map, the top pages reorder with bars, and signups and upgrades tick in with country flags.
- [Social proof toast](https://uiarc.dev/components/social-proof-toast/markdown): A stack of social proof notifications for landing and pricing pages, where recent trials, upgrades and verified purchases from people and companies arrive every few seconds. The stack pauses and fans out on hover, and visitors can dismiss any toast.
- [Install snippet](https://uiarc.dev/components/install-snippet/markdown): A "get started in 30 seconds" card where framework tabs, three numbered steps and highlighted snippets take a developer from install to first event. Generate key wipes a fresh API key into the placeholder in place.

### Guidance for AI tools

AI workflow: A Linear-style AI workflow card where a Gmail trigger, a Claude step, a branch and Slack and Linear actions sit on one hairline rail, and a test run glides down it, opening each step's output inline. Steps are added from a compact command menu with real app marks. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Code suggestion

> An AI code edit suggestion where the model's proposed changes stream into a small editor panel as inline diff hunks, and you accept or reject each one, or all at once with Cmd+Enter. Accepted hunks fold into the file with a smooth height change.

- Type: Component (special)
- Access: Arc Pro
- Page: https://uiarc.dev/components/code-suggestion
- Markdown: https://uiarc.dev/components/code-suggestion/markdown
- Source file: `registry/components/code-suggestion/code-suggestion.tsx`
- Dependencies: motion, lucide-react
- Keywords: special, ai, new, code suggestion, ai code edit, inline diff, accept reject, cursor, copilot, code review, diff hunk, inline edit, ai coding, apply changes, claude, code diff, suggested changes, accept all

### When to use

- Showing an AI's proposed edit to a file as an inline diff the person accepts or rejects hunk by hunk.
- Approving an agent's file change before it is written, with a clear record of what was kept.
- Landing pages and docs that demonstrate an AI coding feature with a realistic, self playing edit.

### When not to use

- Use a dedicated diff tool for large multi file diffs or side by side comparisons; this card is for one file and a handful of hunks.
- Use code-magic-move to animate code from one version to another without a review step.
- Use code-block to show code without changes.
- Use tool-call for an agent step that is not a file edit.
- Use agent-approvals when the person approves actions in general (emails, payments, deploys) rather than code.

### Installation

Code suggestion is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/code-suggestion
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { CodeSuggestion, type CodeSuggestionHunk } from "@/components/arc/code-suggestion/code-suggestion";
import { ClaudeMark } from "@/components/arc/code-suggestion/code-suggestion-marks";

const hunks: CodeSuggestionHunk[] = [
  { id: "timeout", start: 2, remove: 1, summary: "Add a 10s timeout", insert: [
    "  const res = await fetch(url, { signal: AbortSignal.timeout(10_000) });",
  ] },
];

export function InlineEdit({ file, onSave }: { file: { name: string; text: string }; onSave: (text: string) => void }) {
  return (
    <CodeSuggestion
      code={file.text}
      hunks={hunks}
      fileName={file.name}
      instruction="Time out slow requests"
      model={{ name: "Claude Opus 5.5", mark: <ClaudeMark aria-hidden style={{ color: "#D97757" }} /> }}
      onResolve={({ code }) => onSave(code)}
    />
  );
}
```

### API reference

#### CodeSuggestion

An AI code edit suggestion in a small editor panel, like an inline edit in Cursor or GitHub Copilot. The header shows the model mark, the instruction and the model; the panel shows a file tab with its language mark, a running +/− count and the code with each proposed change as an inline diff hunk: removed lines tinted red with a minus, new lines tinted green with a plus. New lines stream in, then every hunk gets Reject and Accept under it, and the footer offers Reject all and Accept all (Cmd or Ctrl + Enter). Accepting a hunk folds its removed lines away and settles the new lines into the file; rejecting folds the new lines away and restores the original. With no props it plays a simulated suggestion on a sample billing helper (Add retry with backoff, Claude Sonnet 5.5) that reviews itself and replays until someone touches it; pass code and hunks to show a real one.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `code` | `string` | `sample fetch-invoice.ts` | The original file contents, lines split on \n. |
| `hunks` | `CodeSuggestionHunk[]` | – | The proposed changes. Each is { id, start, remove?, insert?, summary? }: it replaces `remove` lines starting at the zero based line `start` with the `insert` lines (remove 0 inserts before start, an empty insert deletes). Overlapping hunks after the first are ignored. Leave it unset to play the built-in simulated suggestion. |
| `status` | `"thinking" \| "streaming" \| "ready" \| "error"` | `"ready"` | Controlled status when you pass hunks. thinking shows a shimmer label over the plain file; streaming shows hunks as they grow (append lines to insert and they fade in); ready shows Accept and Reject; error shows the error message and Retry. Going back to thinking clears earlier decisions. |
| `instruction` | `string` | `"Add retry with backoff"` | What the person asked for, shown as the header title. |
| `model` | `{ name: string; mark?: ReactNode } \| null` | `Claude Sonnet 5.5 with the Claude mark` | The model that wrote the suggestion. Mono marks take the text color; pass style={{ color }} for the brand color. null hides the model line. |
| `fileName` | `string` | `"fetch-invoice.ts"` | File name in the tab. |
| `filePath` | `string` | `"src/billing" for the sample` | Folder shown after the file name from a 520px card. |
| `fileMark` | `ReactNode \| null` | `TypeScript mark` | Language mark in the tab. null hides it. |
| `error` | `string` | `"The model stopped responding. Nothing was changed."` | Message for the error status. |
| `onDecision` | `(hunk: CodeSuggestionHunk, decision: "accepted" \| "rejected", code: string) => void` | – | Called for every hunk accepted or rejected (Accept all calls it once per hunk), with the file as it now stands: accepted hunks applied, the rest original. |
| `onResolve` | `(result: { code: string; accepted: string[]; rejected: string[] }) => void` | – | Called once every hunk has a decision, with the final code and the hunk ids. Write the file here. |
| `onStop` | `() => void` | – | Shows Stop while thinking or streaming. Abort your request here. The simulated suggestion stops on its own and keeps only the hunks it finished. |
| `onRegenerate` | `() => void` | – | Shows Regenerate once the review is done (or there were no changes) and Retry on error. The simulated suggestion replays on its own. |
| `autoPlay` | `boolean` | `true` | Simulated suggestion only: after streaming it accepts and rejects hunks on its own (alternating one by one and Accept all) and replays about 2.6s after it finishes. Any pointer, key or focus inside the card hands control to the person for that run. Off under reduced motion. |
| `shortcuts` | `boolean` | `true` | Cmd or Ctrl + Enter accepts all and Cmd or Ctrl + Backspace rejects all while focus is inside the card. Accept all shows the hint. |
| `maxCodeHeight` | `number` | – | Caps the code area height in pixels; longer files scroll inside it. |
| `className` | `string` | – | Class on the root element. |
| `style` | `CSSProperties` | – | Inline style on the root. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Tab | Moves to the code area (scrollable, and where the shortcuts work), then each hunk's Reject and Accept, then the footer actions. |
| Enter / Space | Presses the focused Accept, Reject, Accept all, Reject all, Stop or Regenerate. After a hunk is decided, focus moves to the next pending hunk's Accept, or to the code area when none are left. |
| Cmd / Ctrl + Enter | Accepts every pending hunk while focus is inside the card. |
| Cmd / Ctrl + Backspace | Rejects every pending hunk while focus is inside the card. |
| Arrow left / Arrow right | Scrolls long lines when the code area has focus. |

### Accessibility

- The card is a labelled group ("Code suggestion: Add retry with backoff") and the code is a focusable region named after the file.
- Each pending removed or added line starts with a visually hidden "Removed:" or "Added:", so the diff never relies on the red and green tints; the visible minus and plus signs carry it for sighted readers too.
- Accept and Reject name their hunk ("Accept Retry 429 and 5xx with backoff"). Accept all and Reject all expose their shortcuts with aria-keyshortcuts.
- A polite status region speaks the state ("3 changes to review"), each decision ("Accepted: Add retry limits. 2 changes to review") and the result. The simulated suggestion adds "Simulated, nothing was written to disk" when it finishes. Streaming is announced once, not per line.
- Status always pairs an icon with a label: a spinner for reading and writing, a dot for review, a check for applied, a cross for rejected and an alert for errors.
- Focus never falls back to the page when the pressed control leaves with its hunk or state. Pointer focus draws no ring; keyboard focus uses Arc's shared focus outline.

### Motion

- Thinking lasts about 0.8s with a calm shimmer on "Reading fetch-invoice.ts". Then each hunk opens: its removed lines tint red in 240ms and its new lines stream in one every 38ms, each opening to its 20px row in 120ms while it fades in. The whole sample streams in about 1.6s.
- Review bars open under every hunk at once on a critically damped spring (0.24s, no bounce).
- Accept folds the removed lines and the bar to zero height on the same spring (0.26s), so the code below glides up, while the green tint and the plus signs fade out. Reject does the same for the new lines and lets the red fade. Rows have fixed heights, so nothing is measured mid animation and nothing jitters.
- The footer status icon, label and actions each swap with one short crossfade in place (old out in 100ms, new in 160ms, the label with a 2px rise). The icon only swaps when its kind changes, so the spinner keeps turning from Reading to Writing and a count change swaps only the text. Zero counts in the tab turn muted.
- Reduced motion opens on the finished suggestion with no streaming, no autoplay and instant folds; decisions still apply and the status still updates. Autoplay waits until the card is in view and its replay waits until the card is back in view.

### Responsive behavior

- The card fills its container up to 720px. Long lines scroll sideways inside the code area while the line numbers stay pinned on the left and each review bar stays pinned to the visible width, so Accept is always in reach.
- The folder after the file name hides below a 520px card.
- Below a 440px card the gutter narrows, code drops to 12px, hunk summaries hide (the buttons keep their names for screen readers) and the footer stacks the status above full width actions. It holds down to 320px without page scroll.

### Performance

- Rows are fixed 20px lines animated between known heights; nothing is measured during animation.
- Each line is highlighted once and memoized by its text, so streaming a new line never re-highlights the others.
- The simulation runs on single timeouts per step, starts only when the card is in view and stops its loop when it scrolls away. Pass maxCodeHeight for long files.

### Notes for AI

- Use it wherever an AI proposes edits to one file and a person approves them: inline edit in an editor, a code review assistant, a config or SQL change preview, an agent's file edit approval.
- Map a unified diff to hunks: start is the zero based line of the first removed line (or the insert position), remove is the removed line count and insert the added lines. Keep hunks sorted and non overlapping, and give each a summary of two to six words.
- To stream, set status="streaming" and grow the hunks array and each hunk's insert as tokens arrive, then set status="ready". Wire onStop to abort the request with an AbortController.
- Write the file in onResolve (or progressively in onDecision); the component never writes anything itself. Say in surrounding copy when content is a sample.
- Copy marks from code-suggestion-marks.tsx (Claude, OpenAI, TypeScript) or pass any ReactNode with aria-hidden. Brand marks are sample content, never an implied endorsement.
- The highlighter is a small TypeScript and JavaScript tokenizer. For other languages, the code still renders cleanly in the plain text color.

### Related

- [Tool call](https://uiarc.dev/components/tool-call/markdown): A tool call row for agent transcripts: the tool's mark and the call in plain words, a live state while it runs, and the input and output a click away, with approval and retry when needed.
- [Agent approvals](https://uiarc.dev/components/blocks/agent-approvals/markdown): One approval card for agents: the waiting tool call reads like a permission prompt with the tool's mark, the agent's reason and its arguments, and you approve, deny or allow it from now on.
- [Code block](https://uiarc.dev/components/code-block/markdown): Present code with legible hierarchy and copy access.
- [Text shimmer](https://uiarc.dev/components/text-shimmer/markdown): Show ongoing work with a calm light across the words.
- [Button](https://uiarc.dev/components/button/markdown): A clear, responsive action with quiet secondary states.

### Also in ai

- [Agent status](https://uiarc.dev/components/agent-status/markdown): A compact live status pill for a running AI agent: the agent's mark in a live ring, the current activity and an elapsed timer, opening into the steps so far.
- [Agent plan](https://uiarc.dev/components/agent-plan/markdown): The plan an agent writes before it acts: edit, reorder or add steps while it is a draft, then watch it work through them as a live checklist.
- [Agent timeline](https://uiarc.dev/components/agent-timeline/markdown): A compact timeline of one orchestrated agent run: the orchestrator and its subagents share a time axis, handoffs draw in between rows, and a playhead replays thinking, tool calls and waiting while the header counts time, tokens and cost. Hover a span for what it did, or click it to trace its handoff path.
- [Context window](https://uiarc.dev/components/context-window/markdown): An AI context window as a grid of 200 cells: the system prompt, tools, files, summary and messages fill it in order, a threshold row marks where compaction starts, and sending a message, attaching a file or compacting shows exactly how much still fits.
- [Reasoning block](https://uiarc.dev/components/reasoning-block/markdown): The collapsible thinking block of an AI reply. While the model thinks, a shimmering label counts the seconds and the latest reasoning streams underneath. When it finishes, it folds to "Thought for 7s" and opens to show the full reasoning as calm steps with headings.
- [Source cards](https://uiarc.dev/components/source-cards/markdown): A row of cited sources under an AI answer where cards stream in with real site marks while the model searches, the overflow collapses into a stack of favicons, hovering lifts a preview with the passage, and an inline [n] citation highlights its card.
- [Model card](https://uiarc.dev/components/model-card/markdown): A model details card where switching models rolls every price, limit and score in place, a token slider estimates monthly cost live, and benchmark bars show each model's rank on hover. Compare crossfades to a side-by-side table against any rival with the better values marked, and the card never changes size.
- [AI workflow](https://uiarc.dev/components/ai-workflow/markdown): A Linear-style AI workflow card where a Gmail trigger, a Claude step, a branch and Slack and Linear actions sit on one hairline rail, and a test run glides down it, opening each step's output inline. Steps are added from a compact command menu with real app marks.
- [Ghost text](https://uiarc.dev/components/ghost-text/markdown): An inline AI autocomplete where muted ghost text continues your sentence exactly at the caret and Tab turns it solid in place. Cmd+Right takes it one word at a time, Escape fades it away, and a calm chip shows the model behind it.
- [Image generation](https://uiarc.dev/components/image-generation/markdown): An image studio where each image forms on a dot matrix: a soft halftone wave breathes across the grid, the dots take the colours of the coming photo and grow into a coloured halftone, then blur away into the sharp photo. One large canvas with a mono size label, a filmstrip of four variations, a prompt bar with model and ratio, and upscale with a sweeping dot band, vary or download, with real provider marks and a built-in simulation.
- [Dictation button](https://uiarc.dev/components/dictation-button/markdown): A chat composer with voice input, where the mic springs into a recording pill with a smooth live waveform, a timer, and cancel and insert buttons. Words stream into the field as you speak, muted until the recognizer settles them.
- [Speech player](https://uiarc.dev/components/speech-player/markdown): A read-aloud player for AI replies. The Read aloud button in the message's action row turns into a compact player with play, a scrubbable progress bar, speed and a voice picker, and a highlight follows the spoken word through the reply, karaoke style.
- [Meeting summary](https://uiarc.dev/components/meeting-summary/markdown): An AI meeting notes card: the header shows the Google Meet or Zoom mark, the attendees and the duration. Summary, Decisions and Action items stream in after a short summarizing pass. Hover any line to see the transcript quote it came from, then check off action items or send them to Linear or Notion.
- [Reply draft](https://uiarc.dev/components/reply-draft/markdown): An AI email reply drafter where Claude streams a reply under a received Gmail message. Quick replies steer a fresh draft, tone and length rewrite it with a single crossfade, and you can edit the finished draft before you insert it.
- [Agent handoff](https://uiarc.dev/components/agent-handoff/markdown): A support conversation where an AI assistant hands off to a person. When it transfers, a card shows the summary it passes to the team and the typical wait. The person then joins and takes over, and a thin timeline on the left marks each step.
- [PII redaction](https://uiarc.dev/components/pii-redaction/markdown): A guardrail card where personal data is redacted before the prompt reaches the model. Scan marks each name, email, phone number and card with its type and swaps it for a placeholder like [EMAIL_1]. The safe prompt travels to Claude, and the reply comes back with the original values put back for the person.
- [Response feedback](https://uiarc.dev/components/response-feedback/markdown): A feedback control for AI replies where thumbs down opens an inline panel with reason chips and an optional note, thumbs up fills and asks what was good, and a submit shows a short thank-you before folding back into the row.
- [LLM cost calculator](https://uiarc.dev/components/llm-cost-calculator/markdown): A pricing calculator for LLM workloads. Set tokens per request, requests per day and prompt caching, and eight current models re-rank by monthly cost. Bars glide and prices roll as you drag.
- [Provider keys](https://uiarc.dev/components/provider-keys/markdown): A settings card for bring-your-own-key AI products. Each provider row shows its real mark, the masked key, a status and when the key was last used. You can reveal a key for five seconds, copy, rotate or remove it with undo. Adding or rotating a key opens an inline form that checks the format as you type, then tests the connection before saving.
- [Generation stats](https://uiarc.dev/components/generation-stats/markdown): A live stats strip for a streaming LLM response where time to first token, speed with a sparkline, output tokens and cost count up in tabular numerals beside the model's real mark, then settle and open into a latency and token cost breakdown.
- [AI translate](https://uiarc.dev/components/ai-translate/markdown): A message card where picking a language streams the AI translation in place, sentence by sentence over the dimmed original, with a detected-language chip, a Show original toggle and a status line credited to the model's mark.
- [TL;DR toggle](https://uiarc.dev/components/tldr-toggle/markdown): An article card with a Full, Summary and Key points switch and a length slider. Switching streams an AI summary in place of the article as the card's height springs to fit, and each key point links back to the paragraph it came from, which gets scrolled to and highlighted.
- [Connector setup](https://uiarc.dev/components/connector-setup/markdown): A "Connect your tools" card for an AI assistant. Each app connects inline: it redirects, authorizes and runs a first sync with a progress hairline, then lists the scopes it was granted and offers Disconnect with an inline confirm.
- [Smart form fill](https://uiarc.dev/components/smart-form-fill/markdown): A paste-to-fill form card where AI reads an email signature or messy notes and fills a contact field by field. Each value flashes in with a confidence dot, its source lights up in the pasted text, low-confidence guesses ask for review, and Undo puts the old values back.
- [Enrich column](https://uiarc.dev/components/enrich-column/markdown): An AI enrichment column for a data table, where one prompt runs down every row and each cell shimmers while it works, then settles into a value with its source or a failure you can retry.
- [Ticket router](https://uiarc.dev/components/ticket-router/markdown): A support ticket router where messages from Gmail, Intercom, Slack and Zendesk come in one at a time. An AI classifier labels each one with intent, sentiment and confidence, and the ticket moves into a team lane with an assignee. Low confidence tickets wait in a review lane, and one click there routes them to the suggested team.
- [Ask your data](https://uiarc.dev/components/ask-your-data/markdown): A natural language to chart card: you ask a question, PostgreSQL streams into a collapsible, syntax highlighted panel, the query runs with a rolling row count, and the answer builds as stacked bars, lines or a table, with a one line insight streamed in underneath.
- [Agent cursor](https://uiarc.dev/components/agent-cursor/markdown): A live document where Claude edits like a collaborator. Its labeled cursor comes out of its avatar, selects a paragraph and streams in a rewrite, adds a heading and fixes a typo, while a teammate's cursor reads along. Changes stay tinted until someone accepts or undoes them from a floating review bar.
- [Provider status](https://uiarc.dev/components/provider-status/markdown): A status card for the AI providers your product depends on. Each row shows the provider's real mark, its health as an icon and label, p50 latency and a 30-day uptime bar with a tooltip for each day. An incident row expands into its timeline of updates, and the card checks again on a visible countdown.
- [Training run](https://uiarc.dev/components/training-run/markdown): A fine-tuning job card where a live train and validation loss curve draws across a fixed step axis that doubles as the epoch progress bar. It shows the learning rate, elapsed time, ETA and the latest evals and checkpoints, has Pause and Cancel while it runs, and ends in results with a Deploy button.
- [AI command](https://uiarc.dev/components/ai-command/markdown): A Cmd+K command palette with an AI mode. Search pages and actions, or press Tab to ask a question: the answer streams inside the palette with numbered sources, and the next steps it suggests, like filing a Linear issue or opening a Notion doc, run straight from the list.
- [Starter prompts](https://uiarc.dev/components/starter-prompts/markdown): A greeting and a grid of starter cards for the empty state of an AI app. The cards are grouped into Write, Code, Analyze and Plan tabs, and a shuffle swaps them with a short staggered crossfade. Picking a card fills the composer, and cards that use a connected app show its mark (Gmail, GitHub, Notion, Linear, Google Calendar).
- [AI mascot](https://uiarc.dev/components/ai-mascot/markdown): A small assistant character, a soft pebble with pill eyes and a companion dot, that shows what the AI is doing. It breathes and glances when idle, leans in to listen, looks up while the dot orbits its head, reads along the line it writes, squints with a sparkle when done and shakes once with worried brows on an error.
- [Image reveal](https://uiarc.dev/components/image-reveal/markdown): An image generation canvas where a soft, blurred preview made from the image's own colors sharpens top to bottom behind a soft-edged band. It works the way ChatGPT, Midjourney and Gemini show images forming, with fine film grain, a translucent progress pill and calm queued and error states.
- [AI spark](https://uiarc.dev/components/ai-spark/markdown): A brand-quality animated spark mark. Four tapered rays and four lighter diagonals breathe at rest, ripple while thinking, pulse like a heartbeat while writing, then gather and settle when done. Every status change blends from the pose the mark is already in.
- [Pixel mascot](https://uiarc.dev/components/pixel-mascot/markdown): A pixel-art robot that shows what an AI assistant is doing. It idles, thinks, types, celebrates and errors in frame-stepped sprite animations, and stays crisp at every integer size from 24px to 192px.
- [Ghost mascot](https://uiarc.dev/components/ghost-mascot/markdown): A floating ghost mascot whose soft sheet ripples at the hem while it hovers. It blinks when idle, turns toward you to listen, fades a little translucent while thinking, draws a tiny pen line while writing, smiles with a sparkle when done and wobbles once on an error.
- [Cube mascot](https://uiarc.dev/components/cube-mascot/markdown): An isometric cube mascot where three shaded faces and a painted-on face show what the assistant is doing. It turns a quarter turn in eased steps while thinking, prints lines onto the floor while writing, settles with a sparkle when done, and shakes once on error.
- [Tone tuner](https://uiarc.dev/components/tone-tuner/markdown): A brand voice card where two sliders (formality and detail) and Friendly, Confident and Empathetic chips rewrite a customer reply. Each changed sentence crossfades in place, new words can be highlighted against the original, and Copy takes the current version.
- [Upgrade prompt](https://uiarc.dev/components/upgrade-prompt/markdown): An upgrade nudge for the moment someone hits a limit. It shows a usage meter at 50 of 50 AI credits, a rolling price with a monthly and yearly toggle, three concrete unlocks with real model marks, and Upgrade or Maybe later. Upgrading leads into a success state with the new limits, and the card never changes size between states.
- [Referral card](https://uiarc.dev/components/referral-card/markdown): A give-and-get referral card where people copy or share their invite link, invite friends by email as chips, and watch invites move from invited to signed up to earned, with the credit total counting up and a milestone reward unlocking.
- [Trial banner](https://uiarc.dev/components/trial-banner/markdown): A trial status banner where a ring counts down the days left, the copy names what the workspace loses, and the upgrade path is one click away. It comes as a slim banner, a sidebar card or a header pill. It shifts to a warning tone in the last days, has expired and upgraded states, and folds into the pill when dismissed or snoozed.
- [Team switcher](https://uiarc.dev/components/team-switcher/markdown): A workspace switcher like Linear, Vercel or Slack. The trigger shows the current workspace's logo and plan. The menu has search, your role in each workspace and a Cmd+1 to 9 shortcut for each, and lets you create or join a workspace inline. A highlight glides between rows, and switching crossfades the trigger through a short loading state.
- [Live visitors](https://uiarc.dev/components/live-visitors/markdown): A realtime visitors card where the live count rolls digit by digit, new arrivals ping in on a dotted world map, the top pages reorder with bars, and signups and upgrades tick in with country flags.
- [Social proof toast](https://uiarc.dev/components/social-proof-toast/markdown): A stack of social proof notifications for landing and pricing pages, where recent trials, upgrades and verified purchases from people and companies arrive every few seconds. The stack pauses and fans out on hover, and visitors can dismiss any toast.
- [Install snippet](https://uiarc.dev/components/install-snippet/markdown): A "get started in 30 seconds" card where framework tabs, three numbered steps and highlighted snippets take a developer from install to first event. Generate key wipes a fresh API key into the placeholder in place.

### Guidance for AI tools

Code suggestion: An AI code edit suggestion where the model's proposed changes stream into a small editor panel as inline diff hunks, and you accept or reject each one, or all at once with Cmd+Enter. Accepted hunks fold into the file with a smooth height change. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Ghost text

> An inline AI autocomplete where muted ghost text continues your sentence exactly at the caret and Tab turns it solid in place. Cmd+Right takes it one word at a time, Escape fades it away, and a calm chip shows the model behind it.

- Type: Component (special)
- Access: Arc Pro
- Page: https://uiarc.dev/components/ghost-text
- Markdown: https://uiarc.dev/components/ghost-text/markdown
- Source file: `registry/components/ghost-text/ghost-text.tsx`
- Dependencies: motion, lucide-react
- Keywords: special, ai, new, ghost text, ai autocomplete, inline suggestion, copilot, tab to accept, text completion, autocomplete textarea, predictive text, smart compose, llm, claude, streaming, pull request, email, writing assistant

### When to use

- Long-form fields people write in product: pull request descriptions, emails, support replies, issue bodies, release notes, CRM notes.
- Short single-line fields where a likely completion saves typing, such as an email subject or a commit message.
- Anywhere you want AI help that stays out of the way until the person pauses, and never changes their text without an explicit key press.

### When not to use

- Use ai-composer for a chat-style prompt box that sends a message to an assistant.
- Use code-suggestion for code diffs with accept and reject per hunk.
- Use a combobox or command menu when the person picks from a list of known options rather than free text.
- Avoid it in fields with sensitive content (passwords, card numbers, health data) unless your model provider and data policy allow it.

### Installation

Ghost text is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/ghost-text
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { GhostText, ClaudeMark } from "@/components/arc/ghost-text/ghost-text";

// Stream a continuation from your API route (any model works).
async function* suggest(text: string, signal: AbortSignal) {
  const response = await fetch("/api/autocomplete", { method: "POST", body: JSON.stringify({ text }), signal });
  if (!response.ok || !response.body) throw new Error("Autocomplete is unavailable");
  const reader = response.body.pipeThrough(new TextDecoderStream()).getReader();
  for (;;) {
    const { value, done } = await reader.read();
    if (done) return;
    yield value;
  }
}

export function PullRequestDescription() {
  const [body, setBody] = useState("");
  return (
    <GhostText
      value={body}
      onValueChange={setBody}
      suggest={suggest}
      rows={6}
      placeholder="Describe what changed and why"
      label="Description"
      model={{ name: "Claude Haiku 5.5", mark: <ClaudeMark style={{ color: "#D97757" }} /> }}
      onAccept={(text, mode) => track("autocomplete_accept", { mode, chars: text.length })}
    />
  );
}

// Single-line, uncontrolled, whole suggestions from a promise.
<GhostText multiline={false} defaultValue="" aria-label="Subject" suggest={(text, signal) => api.complete(text, { signal })} />

// Flush inside your own card: the card owns the border and focus style.
<div className="compose-card">
  <ComposeHeader />
  <GhostText variant="plain" value={body} onValueChange={setBody} suggest={suggest} aria-label="Message" />
</div>

// With no props it plays the simulated pull request card.
<GhostText />
```

### API reference

#### GhostText

Inline AI autocomplete for a textarea or a single-line input. When the person pauses, muted ghost text continues their sentence right at the caret, streamed from your suggest(text, signal) function. Tab accepts the whole suggestion, Cmd+Right (Ctrl+Right on Windows, Option or Alt+Right too) accepts one word at a time, Escape dismisses it, and typing the same characters as the ghost keeps it in place instead of asking again. A small chip in the corner shows the model's mark and name, a shimmering Thinking while it waits, a Tab key cap and "to accept" when a suggestion is ready (a tap target on touch screens), Accepted with a check after Tab, and No suggestion with Retry when your function throws. Accepted text settles from ghost ink to text ink in place, with no flicker or movement. Works controlled or uncontrolled, as a bordered field or flush inside your own card (variant="plain"). With no props it plays a simulated pull request card that types, pauses, accepts and loops, and you can take it over by clicking it.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `suggest` | `(text: string, signal: AbortSignal) => string \| null \| Promise<string \| null> \| AsyncIterable<string>` | – | Returns a continuation for the text before the caret. Return a string or a promise of one for a whole suggestion, or an async iterable (an async generator over your model's stream) to stream it in chunk by chunk. Return null synchronously to skip without showing Thinking. Abort your request when signal fires: the person kept typing, moved the caret or left the field. A thrown error shows No suggestion with Retry. |
| `value` | `string` | – | The text, for a controlled field. Pair with onValueChange. Programmatic changes run through the same logic as typing, so a parent can drive the field. |
| `defaultValue` | `string` | `""` | The starting text for an uncontrolled field. |
| `onValueChange` | `(value: string) => void` | – | Called with the new text on every edit and every accepted suggestion or word. |
| `delay` | `number` | `450` | Milliseconds of pause before suggest is called. Every keystroke resets it. |
| `minLength` | `number` | `3` | Trimmed characters needed before suggestions start. |
| `multiline` | `boolean` | `true` | A growing textarea with a footer row, or a single-line input with the chip inline at its end. Line breaks pasted into a single-line field become spaces. |
| `variant` | `"field" \| "plain"` | `"field"` | field draws its own 1px border, hover and keyboard focus ring. plain drops the border, background and ring so the text sits flush inside a card you already have (a compose panel, a PR form); give the card its own focus style. |
| `rows` | `number` | `3` | Minimum visible lines of a multi-line field. |
| `maxRows` | `number` | `10` | Lines before a multi-line field stops growing and scrolls, keeping the caret in view. |
| `placeholder` | `string` | – | Placeholder text for the empty field. |
| `label` | `ReactNode` | – | A quiet row above the text, such as a field name with an icon. It labels the field unless aria-label is set. Multi-line only. |
| `footer` | `ReactNode` | – | Content at the start of the footer row, such as a character count, a note or a send button. Multi-line only. |
| `model` | `{ name: string; mark?: ReactNode }` | `{ name: "Autocomplete" }` | The model behind the suggestions. The name shows in the idle chip and the mark at 12px in every chip state. Give a mono mark its brand color, for example the Claude mark in #D97757. |
| `hint` | `boolean` | `true` | Shows the chip, the Cmd+Right and Escape key hints next to it on wide fields, and a screen reader description of the keys. |
| `onAccept` | `(accepted: string, mode: "all" \| "word") => void` | – | Called with the text that was accepted: the whole suggestion (all) or the next word (word). Useful for acceptance-rate analytics. |
| `onDismiss` | `(suggestion: string) => void` | – | Called with the suggestion the person dismissed with Escape. |
| `onStatusChange` | `(status: "idle" \| "loading" \| "ready" \| "error") => void` | – | Called when the suggestion status changes. |
| `disabled` | `boolean` | `false` | Disables the field and stops suggestions. |
| `name, id, autoFocus, aria-label` | `string \| boolean` | – | Passed to the textarea or input. |
| `notice` | `string` | – | A one-off message for screen readers, joined to the field's own announcements. |
| `ref` | `Ref<GhostTextHandle>` | – | Imperative handle: focus(), acceptAll(), acceptWord(), dismiss(), request() to ask now without waiting for a pause, and getState() returning { status, suggestion, streaming }. Use it for an Accept button of your own or for tests. |
| `className` | `string` | – | Class on the root element. |

#### createDemoSuggest

The rule based stand in for a model used by the preview, exported for prototypes and tests. It streams PR writing continuations in 3 to 6 word chunks after a short think, completes partial words from a small vocabulary, and fails with a timeout when the text contains the word timeout so the error state can be seen. Nothing is sent anywhere.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `scriptedOnly` | `boolean` | `false` | Only answer the autoplay script's contexts and return null for everything else. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Tab | Accepts the whole suggestion and keeps the caret at the end. With no suggestion showing, Tab moves focus as usual. |
| Cmd+Right / Ctrl+Right | Accepts the next word of the suggestion; the rest stays. Option+Right and Alt+Right work too. With no suggestion showing, the keys move the caret as usual. |
| Escape | Dismisses the suggestion. With no suggestion showing, Escape is left alone, so a surrounding dialog can still close. |
| Typing | Characters that match the start of the ghost consume it in place; anything else clears it and a new suggestion is asked for after the next pause. |
| Arrow keys, click | Moving the caret away from the end of the text clears the suggestion; suggestions only continue from the end. |

### Accessibility

- The field is a native textarea (or input), labelled by aria-label or the label row, and described by a hidden sentence that explains Tab, Cmd or Ctrl+Right and Escape.
- The ghost text lives in an aria-hidden mirror behind the field, so it is never read as content. A polite status region reads the finished suggestion ("Suggestion: date the plan changed. Press Tab to accept."), then Suggestion accepted, Suggestion dismissed or Couldn't get a suggestion.
- The chip is a button with a clear name in each state (Accept suggestion, Retry suggestion). It is reachable with Tab only in the error state, where Retry is the action; in the ready state Tab itself accepts. Pressing the chip never steals focus from the field.
- State is never shown by color alone: Thinking, the Tab key cap with "to accept", Accepted with a check and No suggestion with an alert icon all carry words.
- Keyboard focus draws Arc's focus ring around the whole field; pointer focus does not.
- On touch screens, where there is no Tab key, the chip reads Tap to accept.

### Motion

- Ghost text only fades in, chunk by chunk as it streams (140ms each, opacity only, no blur or slide), so a suggestion settles without any movement. Escape and leaving the field fade it out in 110ms; typing a different character clears it at once so nothing lingers over new text.
- Accepting turns the ghost solid in place: for 200ms an aria-hidden mirror with the field's exact metrics draws the text while the native glyphs go transparent (the caret stays), and the accepted range eases from muted to text color. Cmd+Right does the same per word, and the rest of the ghost never re-fades.
- The field's height follows the text, ghost included, on a 180ms tween and never bounces. The box is clipped while it grows, so the browser cannot scroll it under the caret mid-tween.
- Chip states crossfade in place (old out in 100ms, new in 160ms) while the chip's width follows on a 200ms tween, anchored to its right edge. Key caps press for 160ms when their key or the matching handle method fires. Thinking carries a calm shimmer.
- Reduced motion removes the fades, the ink merge, the shimmer and the height tween and keeps every state, text and announcement. The preview plays once and stops instead of looping, and it pauses while off screen.

### Responsive behavior

- The field fills its container's width; the text and ghost wrap identically at any width, so the suggestion always starts at the caret.
- Below 520px of field width the Cmd+Right and Escape hints step aside and only the chip remains; the footer note truncates with an ellipsis.
- On touch screens the chip reads Tap to accept and accepts on tap.
- The single-line variant scrolls sideways with the caret and keeps the chip inline at its end.

### Performance

- One debounced request at a time: each keystroke clears the timer and aborts the in-flight request, so a fast typist triggers nothing until they pause.
- Typing through a matching suggestion trims it locally without a new request.
- The ghost renders as a few spans in a mirror behind a native textarea, so typing stays native-fast and works with spellcheck, IME, undo and autofill.
- The height and the chip width animate motion values directly; ResizeObserver measures, never a layout read mid-animation.

### Notes for AI

- Use a fast, cheap model for suggest (Claude Haiku 5.5, Gemini 3.8 Flash or DeepSeek V4.1 Flash): people expect ghost text within about half a second of pausing. Cap max tokens to a sentence or a short line.
- Prompt for a continuation only: no preamble, no repetition of the input, and include a leading space when the text ends mid-sentence without one. The component strips a leading space if the text already ends with whitespace.
- Always pass signal to fetch. The component aborts on every keystroke, caret move, blur and accept, and ignores late chunks.
- Return null synchronously for contexts you never want to complete (inside a code block, after a URL), so no Thinking state flashes.
- Log onAccept and onDismiss to measure acceptance rate per model and prompt.

### Related

- [Textarea](https://uiarc.dev/components/textarea/markdown): A multiline field for notes, descriptions, and longer text.
- [Input](https://uiarc.dev/components/input/markdown): A single line field with clear labels and useful states.
- [AI composer](https://uiarc.dev/components/blocks/ai-composer/markdown): The prompt box at the bottom of an AI app: files upload in place, / opens commands, @ inserts mentions, a model and effort menu sits in the toolbar, and the send button turns into a stop control ringed by the reply's progress.
- [Code suggestion](https://uiarc.dev/components/code-suggestion/markdown): An AI code edit suggestion where the model's proposed changes stream into a small editor panel as inline diff hunks, and you accept or reject each one, or all at once with Cmd+Enter. Accepted hunks fold into the file with a smooth height change.
- [Text shimmer](https://uiarc.dev/components/text-shimmer/markdown): Show ongoing work with a calm light across the words.
- [AI chat](https://uiarc.dev/components/blocks/ai-chat/markdown): A full-screen AI chat where answers stream in as markdown with folding reasoning, tool chips and cited sources. People can switch chats and models, edit or retry a message into versions, rate replies and stop a reply mid-stream.

### Also in ai

- [Agent status](https://uiarc.dev/components/agent-status/markdown): A compact live status pill for a running AI agent: the agent's mark in a live ring, the current activity and an elapsed timer, opening into the steps so far.
- [Tool call](https://uiarc.dev/components/tool-call/markdown): A tool call row for agent transcripts: the tool's mark and the call in plain words, a live state while it runs, and the input and output a click away, with approval and retry when needed.
- [Agent plan](https://uiarc.dev/components/agent-plan/markdown): The plan an agent writes before it acts: edit, reorder or add steps while it is a draft, then watch it work through them as a live checklist.
- [Agent timeline](https://uiarc.dev/components/agent-timeline/markdown): A compact timeline of one orchestrated agent run: the orchestrator and its subagents share a time axis, handoffs draw in between rows, and a playhead replays thinking, tool calls and waiting while the header counts time, tokens and cost. Hover a span for what it did, or click it to trace its handoff path.
- [Context window](https://uiarc.dev/components/context-window/markdown): An AI context window as a grid of 200 cells: the system prompt, tools, files, summary and messages fill it in order, a threshold row marks where compaction starts, and sending a message, attaching a file or compacting shows exactly how much still fits.
- [Reasoning block](https://uiarc.dev/components/reasoning-block/markdown): The collapsible thinking block of an AI reply. While the model thinks, a shimmering label counts the seconds and the latest reasoning streams underneath. When it finishes, it folds to "Thought for 7s" and opens to show the full reasoning as calm steps with headings.
- [Source cards](https://uiarc.dev/components/source-cards/markdown): A row of cited sources under an AI answer where cards stream in with real site marks while the model searches, the overflow collapses into a stack of favicons, hovering lifts a preview with the passage, and an inline [n] citation highlights its card.
- [Model card](https://uiarc.dev/components/model-card/markdown): A model details card where switching models rolls every price, limit and score in place, a token slider estimates monthly cost live, and benchmark bars show each model's rank on hover. Compare crossfades to a side-by-side table against any rival with the better values marked, and the card never changes size.
- [AI workflow](https://uiarc.dev/components/ai-workflow/markdown): A Linear-style AI workflow card where a Gmail trigger, a Claude step, a branch and Slack and Linear actions sit on one hairline rail, and a test run glides down it, opening each step's output inline. Steps are added from a compact command menu with real app marks.
- [Image generation](https://uiarc.dev/components/image-generation/markdown): An image studio where each image forms on a dot matrix: a soft halftone wave breathes across the grid, the dots take the colours of the coming photo and grow into a coloured halftone, then blur away into the sharp photo. One large canvas with a mono size label, a filmstrip of four variations, a prompt bar with model and ratio, and upscale with a sweeping dot band, vary or download, with real provider marks and a built-in simulation.
- [Dictation button](https://uiarc.dev/components/dictation-button/markdown): A chat composer with voice input, where the mic springs into a recording pill with a smooth live waveform, a timer, and cancel and insert buttons. Words stream into the field as you speak, muted until the recognizer settles them.
- [Speech player](https://uiarc.dev/components/speech-player/markdown): A read-aloud player for AI replies. The Read aloud button in the message's action row turns into a compact player with play, a scrubbable progress bar, speed and a voice picker, and a highlight follows the spoken word through the reply, karaoke style.
- [Meeting summary](https://uiarc.dev/components/meeting-summary/markdown): An AI meeting notes card: the header shows the Google Meet or Zoom mark, the attendees and the duration. Summary, Decisions and Action items stream in after a short summarizing pass. Hover any line to see the transcript quote it came from, then check off action items or send them to Linear or Notion.
- [Reply draft](https://uiarc.dev/components/reply-draft/markdown): An AI email reply drafter where Claude streams a reply under a received Gmail message. Quick replies steer a fresh draft, tone and length rewrite it with a single crossfade, and you can edit the finished draft before you insert it.
- [Agent handoff](https://uiarc.dev/components/agent-handoff/markdown): A support conversation where an AI assistant hands off to a person. When it transfers, a card shows the summary it passes to the team and the typical wait. The person then joins and takes over, and a thin timeline on the left marks each step.
- [PII redaction](https://uiarc.dev/components/pii-redaction/markdown): A guardrail card where personal data is redacted before the prompt reaches the model. Scan marks each name, email, phone number and card with its type and swaps it for a placeholder like [EMAIL_1]. The safe prompt travels to Claude, and the reply comes back with the original values put back for the person.
- [Response feedback](https://uiarc.dev/components/response-feedback/markdown): A feedback control for AI replies where thumbs down opens an inline panel with reason chips and an optional note, thumbs up fills and asks what was good, and a submit shows a short thank-you before folding back into the row.
- [LLM cost calculator](https://uiarc.dev/components/llm-cost-calculator/markdown): A pricing calculator for LLM workloads. Set tokens per request, requests per day and prompt caching, and eight current models re-rank by monthly cost. Bars glide and prices roll as you drag.
- [Provider keys](https://uiarc.dev/components/provider-keys/markdown): A settings card for bring-your-own-key AI products. Each provider row shows its real mark, the masked key, a status and when the key was last used. You can reveal a key for five seconds, copy, rotate or remove it with undo. Adding or rotating a key opens an inline form that checks the format as you type, then tests the connection before saving.
- [Generation stats](https://uiarc.dev/components/generation-stats/markdown): A live stats strip for a streaming LLM response where time to first token, speed with a sparkline, output tokens and cost count up in tabular numerals beside the model's real mark, then settle and open into a latency and token cost breakdown.
- [AI translate](https://uiarc.dev/components/ai-translate/markdown): A message card where picking a language streams the AI translation in place, sentence by sentence over the dimmed original, with a detected-language chip, a Show original toggle and a status line credited to the model's mark.
- [TL;DR toggle](https://uiarc.dev/components/tldr-toggle/markdown): An article card with a Full, Summary and Key points switch and a length slider. Switching streams an AI summary in place of the article as the card's height springs to fit, and each key point links back to the paragraph it came from, which gets scrolled to and highlighted.
- [Connector setup](https://uiarc.dev/components/connector-setup/markdown): A "Connect your tools" card for an AI assistant. Each app connects inline: it redirects, authorizes and runs a first sync with a progress hairline, then lists the scopes it was granted and offers Disconnect with an inline confirm.
- [Smart form fill](https://uiarc.dev/components/smart-form-fill/markdown): A paste-to-fill form card where AI reads an email signature or messy notes and fills a contact field by field. Each value flashes in with a confidence dot, its source lights up in the pasted text, low-confidence guesses ask for review, and Undo puts the old values back.
- [Enrich column](https://uiarc.dev/components/enrich-column/markdown): An AI enrichment column for a data table, where one prompt runs down every row and each cell shimmers while it works, then settles into a value with its source or a failure you can retry.
- [Ticket router](https://uiarc.dev/components/ticket-router/markdown): A support ticket router where messages from Gmail, Intercom, Slack and Zendesk come in one at a time. An AI classifier labels each one with intent, sentiment and confidence, and the ticket moves into a team lane with an assignee. Low confidence tickets wait in a review lane, and one click there routes them to the suggested team.
- [Ask your data](https://uiarc.dev/components/ask-your-data/markdown): A natural language to chart card: you ask a question, PostgreSQL streams into a collapsible, syntax highlighted panel, the query runs with a rolling row count, and the answer builds as stacked bars, lines or a table, with a one line insight streamed in underneath.
- [Agent cursor](https://uiarc.dev/components/agent-cursor/markdown): A live document where Claude edits like a collaborator. Its labeled cursor comes out of its avatar, selects a paragraph and streams in a rewrite, adds a heading and fixes a typo, while a teammate's cursor reads along. Changes stay tinted until someone accepts or undoes them from a floating review bar.
- [Provider status](https://uiarc.dev/components/provider-status/markdown): A status card for the AI providers your product depends on. Each row shows the provider's real mark, its health as an icon and label, p50 latency and a 30-day uptime bar with a tooltip for each day. An incident row expands into its timeline of updates, and the card checks again on a visible countdown.
- [Training run](https://uiarc.dev/components/training-run/markdown): A fine-tuning job card where a live train and validation loss curve draws across a fixed step axis that doubles as the epoch progress bar. It shows the learning rate, elapsed time, ETA and the latest evals and checkpoints, has Pause and Cancel while it runs, and ends in results with a Deploy button.
- [AI command](https://uiarc.dev/components/ai-command/markdown): A Cmd+K command palette with an AI mode. Search pages and actions, or press Tab to ask a question: the answer streams inside the palette with numbered sources, and the next steps it suggests, like filing a Linear issue or opening a Notion doc, run straight from the list.
- [Starter prompts](https://uiarc.dev/components/starter-prompts/markdown): A greeting and a grid of starter cards for the empty state of an AI app. The cards are grouped into Write, Code, Analyze and Plan tabs, and a shuffle swaps them with a short staggered crossfade. Picking a card fills the composer, and cards that use a connected app show its mark (Gmail, GitHub, Notion, Linear, Google Calendar).
- [AI mascot](https://uiarc.dev/components/ai-mascot/markdown): A small assistant character, a soft pebble with pill eyes and a companion dot, that shows what the AI is doing. It breathes and glances when idle, leans in to listen, looks up while the dot orbits its head, reads along the line it writes, squints with a sparkle when done and shakes once with worried brows on an error.
- [Image reveal](https://uiarc.dev/components/image-reveal/markdown): An image generation canvas where a soft, blurred preview made from the image's own colors sharpens top to bottom behind a soft-edged band. It works the way ChatGPT, Midjourney and Gemini show images forming, with fine film grain, a translucent progress pill and calm queued and error states.
- [AI spark](https://uiarc.dev/components/ai-spark/markdown): A brand-quality animated spark mark. Four tapered rays and four lighter diagonals breathe at rest, ripple while thinking, pulse like a heartbeat while writing, then gather and settle when done. Every status change blends from the pose the mark is already in.
- [Pixel mascot](https://uiarc.dev/components/pixel-mascot/markdown): A pixel-art robot that shows what an AI assistant is doing. It idles, thinks, types, celebrates and errors in frame-stepped sprite animations, and stays crisp at every integer size from 24px to 192px.
- [Ghost mascot](https://uiarc.dev/components/ghost-mascot/markdown): A floating ghost mascot whose soft sheet ripples at the hem while it hovers. It blinks when idle, turns toward you to listen, fades a little translucent while thinking, draws a tiny pen line while writing, smiles with a sparkle when done and wobbles once on an error.
- [Cube mascot](https://uiarc.dev/components/cube-mascot/markdown): An isometric cube mascot where three shaded faces and a painted-on face show what the assistant is doing. It turns a quarter turn in eased steps while thinking, prints lines onto the floor while writing, settles with a sparkle when done, and shakes once on error.
- [Tone tuner](https://uiarc.dev/components/tone-tuner/markdown): A brand voice card where two sliders (formality and detail) and Friendly, Confident and Empathetic chips rewrite a customer reply. Each changed sentence crossfades in place, new words can be highlighted against the original, and Copy takes the current version.
- [Upgrade prompt](https://uiarc.dev/components/upgrade-prompt/markdown): An upgrade nudge for the moment someone hits a limit. It shows a usage meter at 50 of 50 AI credits, a rolling price with a monthly and yearly toggle, three concrete unlocks with real model marks, and Upgrade or Maybe later. Upgrading leads into a success state with the new limits, and the card never changes size between states.
- [Referral card](https://uiarc.dev/components/referral-card/markdown): A give-and-get referral card where people copy or share their invite link, invite friends by email as chips, and watch invites move from invited to signed up to earned, with the credit total counting up and a milestone reward unlocking.
- [Trial banner](https://uiarc.dev/components/trial-banner/markdown): A trial status banner where a ring counts down the days left, the copy names what the workspace loses, and the upgrade path is one click away. It comes as a slim banner, a sidebar card or a header pill. It shifts to a warning tone in the last days, has expired and upgraded states, and folds into the pill when dismissed or snoozed.
- [Team switcher](https://uiarc.dev/components/team-switcher/markdown): A workspace switcher like Linear, Vercel or Slack. The trigger shows the current workspace's logo and plan. The menu has search, your role in each workspace and a Cmd+1 to 9 shortcut for each, and lets you create or join a workspace inline. A highlight glides between rows, and switching crossfades the trigger through a short loading state.
- [Live visitors](https://uiarc.dev/components/live-visitors/markdown): A realtime visitors card where the live count rolls digit by digit, new arrivals ping in on a dotted world map, the top pages reorder with bars, and signups and upgrades tick in with country flags.
- [Social proof toast](https://uiarc.dev/components/social-proof-toast/markdown): A stack of social proof notifications for landing and pricing pages, where recent trials, upgrades and verified purchases from people and companies arrive every few seconds. The stack pauses and fans out on hover, and visitors can dismiss any toast.
- [Install snippet](https://uiarc.dev/components/install-snippet/markdown): A "get started in 30 seconds" card where framework tabs, three numbered steps and highlighted snippets take a developer from install to first event. Generate key wipes a fresh API key into the placeholder in place.

### Guidance for AI tools

Ghost text: An inline AI autocomplete where muted ghost text continues your sentence exactly at the caret and Tab turns it solid in place. Cmd+Right takes it one word at a time, Escape fades it away, and a calm chip shows the model behind it. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Image generation

> An image studio where each image forms on a dot matrix: a soft halftone wave breathes across the grid, the dots take the colours of the coming photo and grow into a coloured halftone, then blur away into the sharp photo. One large canvas with a mono size label, a filmstrip of four variations, a prompt bar with model and ratio, and upscale with a sweeping dot band, vary or download, with real provider marks and a built-in simulation.

- Type: Component (special)
- Access: Arc Pro
- Page: https://uiarc.dev/components/image-generation
- Markdown: https://uiarc.dev/components/image-generation/markdown
- Source file: `registry/components/image-generation/image-generation.tsx`
- Dependencies: motion, lucide-react, @radix-ui/react-tooltip
- Keywords: special, ai, new, image generation, text to image, ai image, diffusion, prompt, upscale, variations, filmstrip, generate images, aspect ratio, dot matrix, halftone, loading state, dot spinner, blur to sharp

### When to use

- A text to image feature inside a product: marketing asset tools, listing photo helpers, slide or doc illustration.
- Any flow where people compare a few candidates and continue with one (upscale, vary, download).
- Prototyping an image model integration before the backend exists, using the built in simulation.

### When not to use

- A full canvas editor with layers, masks and inpainting; build on a canvas library instead.
- Drawing a sketch to turn into an image; use sketch-to-image.
- Showing a single image with a loading state and no generation controls; use blur-image.

### Installation

Image generation is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/image-generation
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { ImageGeneration } from "@/components/arc/image-generation/image-generation";

export function Studio() {
  return <ImageGeneration
    onGenerate={async (request, { signal, onProgress }) => {
      const job = await fetch("/api/images", {
        method: "POST",
        signal,
        body: JSON.stringify({ prompt: request.prompt, model: request.model.id, size: `${request.aspect.width}x${request.aspect.height}`, seedFrom: request.variationOf?.id }),
      }).then(response => response.json());
      onProgress(1);
      return { id: job.id, src: job.url, alt: request.prompt, width: request.aspect.width, height: request.aspect.height };
    }}
    onDownload={image => window.open(image.src)}
  />;
}
```

### API reference

#### ImageGeneration

An image studio card: one large canvas shows the chosen image, a filmstrip of four variations sits under it beside Upscale, Vary and Download, and a prompt bar with model and aspect chips closes the card. Each image forms on a dot matrix: a soft halftone wave breathes across the grid, the dots take the colours of the coming photo and grow into a coloured halftone, then blur away into the sharp photo. A mono size label sits top right and a status pill with a 3×3 dot spinner bottom left. With no props it runs a local simulation on sample photos.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `prompt` | `string` | – | Controlled prompt. Pair with onPromptChange. |
| `defaultPrompt` | `string` | `sample golden hour landscape prompt` | Starting prompt when uncontrolled. |
| `onPromptChange` | `(prompt: string) => void` | – | Fires as the person types or picks a suggestion. |
| `models` | `ImageGenerationModel[]` | `imageGenerationModels` | Models offered as chips: { id, name, mark? }. The chosen chip shows its name, the others collapse to their 16px mark with a tooltip. |
| `model` | `string` | – | Controlled model id. Pair with onModelChange. |
| `defaultModel` | `string` | `first model` | Starting model id when uncontrolled. |
| `onModelChange` | `(id: string) => void` | – | Fires when a model chip is chosen. |
| `aspectRatios` | `ImageGenerationAspect[]` | `1:1, 4:5, 16:9` | Output shapes: { id, label, width, height }. Width and height are the pixels a generation returns, drive the canvas shape and show in the size label. |
| `aspectRatio` | `string` | – | Controlled aspect id. Pair with onAspectRatioChange. |
| `defaultAspectRatio` | `string` | `first ratio` | Starting aspect id when uncontrolled. |
| `onAspectRatioChange` | `(id: string) => void` | – | Fires when an aspect chip is chosen. Before the first generation the canvas springs to the new shape; after that the shape applies to the next generation and the current batch keeps its own. |
| `onGenerate` | `(request: ImageGenerationRequest, context: { signal: AbortSignal; onProgress(progress: number, preview?: string): void }) => Promise<ImageGenerationImage>` | `simulateImageGeneration` | Produces one image. Called once per variation, in parallel, for Generate, Vary (request.variationOf is set) and Retry. Report progress from 0 to 1, optionally with a preview URL: the dots sample their colours from it and dissolve into it over the last fifth of the run (without one, the dots stay neutral and the image resolves from soft to sharp when it arrives); without reports progress estimates. Reject to mark that variation failed; the signal aborts on Stop or Escape. |
| `onUpscale` | `(image: ImageGenerationImage, context: ImageGenerationContext) => Promise<ImageGenerationImage>` | `simulateImageUpscale` | Upscales the image on the canvas. Return the new image with its width and height; the size label updates to it. |
| `onDownload` | `(image: ImageGenerationImage) => void` | – | Replaces the built in download, which saves image.src with a file name built from the prompt, index and size. |
| `onSelect` | `(image: ImageGenerationImage \| null) => void` | – | Fires with the image on the canvas: when the person picks a finished variation, when the shown variation finishes, with the upscaled image once an upscale finishes, and with null when a new batch starts. |
| `suggestions` | `string[]` | `three sample prompts` | Prompts offered on the empty canvas before the first generation. |
| `autoGenerate` | `boolean` | `true with the simulation, false with onGenerate` | Generates once when the card first scrolls into view, unless someone has already touched it. |
| `placeholder` | `string` | `"Describe the image you want"` | Prompt placeholder. |
| `className` | `string` | – | Class on the card. |

#### simulateImageGeneration

The built in generator, exported so you can wrap it in tests or demos. Picks sample photos that match the prompt, reports the photo as the preview and frame by frame progress over about four and a half to six seconds. Nothing is sent anywhere.

No props.

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Cmd/Ctrl + Enter | Generate from the prompt field. |
| Arrow keys | Move between model chips or aspect chips, and between variations in the filmstrip (each one shows on the canvas as focus lands). |
| Escape | Stop a running generation; finished images are kept. |
| Tab | The chosen variation, Upscale, Vary, Download, then the prompt, model, aspect and Generate. |

### Accessibility

- Model and aspect chips and the filmstrip are radio groups with a roving tab stop; collapsed model chips keep their name as the accessible label and in a tooltip.
- The canvas is labelled with the image description once done, or with the variation's state while it generates, fails or stops; each thumbnail names its number and state.
- A polite live region reports starts, finishes, failures, picks, upscales and downloads, and says when results are simulated.
- Status is never color alone: failures pair a danger icon with "Failed" and the error, stops a square icon with "Stopped", the chosen thumbnail an accent ring with aria-checked, progress a spinner with a percentage.
- Icon only actions at narrow widths keep Upscale, Vary and Download as their accessible names.

### Motion

- Each image loads on a canvas of small neutral dots, drawn at device pixel ratio. A soft radial halftone wave breathes and wanders across the grid: dots under it grow and darken, and a blurred twin of them glows like a lens.
- From 20% the dots take the colour of the coming photo at their cell (the preview downscaled to the grid, cover fitted), showing first under the wave, and grow by the photo's darkness, so by 78% the image reads as a coloured halftone.
- Over the last fifth the dots blur and fade while the photo sharpens out of them from 12px blur and 4% zoom. The final frame is the photo, and the real <img> lands on it without a cut; an image that differs from the preview resolves from soft to sharp in 480ms.
- The filmstrip thumbnails run their own small dot fields, so all four variations show their progress at once. Picking another variation crossfades the canvas in 200ms.
- Upscale sweeps a vertical band of halftone dots in the photo's colours left to right: soft ahead of it, sharp behind it, the dots and their blurred twin in it, all from one motion value. The size label crossfades to the new size.
- The status pill carries a 3×3 dot spinner whose dots light in turn around the ring, with a mono percentage; pills crossfade by key so a label never resizes in a frame.
- The canvas springs to a new aspect ratio; a container resize cuts straight to the new size. Labels that change inside buttons (Generate and Stop, Upscale, Upscaling, Upscaled, Download and Saved) are stacked in one cell and crossfade, so no button changes width.
- Reduced motion draws a still dot grid with the halftone glow at rest, crossfades the photo in by progress, keeps the spinner still and drops the upscale sweep.

### Responsive behavior

- The card fills its container up to 600px. The canvas keeps the batch's ratio and caps its height at 440px, so portrait shapes stay compact.
- Below 500px of card width the actions drop their labels to icons, so the four thumbnails always fit beside them; thumbnails shrink and stay square.
- Below 440px the model chips and Generate share the first row of the prompt bar and the ratio chips move to a second.

### Performance

- Progress is written straight to motion values, the canvas and styles; React re-renders only on state changes (preview arrives, image finishes).
- The large canvas draws about four thousand dots per frame with one 2D context plus a blurred twin for the wave; thumbnails draw under two hundred.
- The preview is sampled once per grid size and cached; a cross origin image without CORS keeps the neutral dots.
- A loop runs only while its image generates and is on screen; finished, failed and stopped fields draw once and stop, and redraw on theme change.

### Notes for AI

- Wire onGenerate to your image API; it runs once per variation, so a provider that returns four images per call can be wrapped by caching one request and resolving each index from it.
- Use request.variationOf to pass a seed or reference image for Vary. Return width and height so the footer and file names show the real size.
- Keep model names to what your backend actually serves; the defaults are generic product names with provider marks.
- Pair with a gallery or asset picker by listening to onSelect; the component holds only the current batch.

### Related

- [Model picker](https://uiarc.dev/components/blocks/model-picker/markdown): A model picker in one quiet pill: open it to choose from featured models with a one line note each, set the reasoning effort, or browse every other model by provider, and the pill swaps to your choice in place.
- [AI composer](https://uiarc.dev/components/blocks/ai-composer/markdown): The prompt box at the bottom of an AI app: files upload in place, / opens commands, @ inserts mentions, a model and effort menu sits in the toolbar, and the send button turns into a stop control ringed by the reply's progress.
- [Text shimmer](https://uiarc.dev/components/text-shimmer/markdown): Show ongoing work with a calm light across the words.

### Also in ai

- [Agent status](https://uiarc.dev/components/agent-status/markdown): A compact live status pill for a running AI agent: the agent's mark in a live ring, the current activity and an elapsed timer, opening into the steps so far.
- [Tool call](https://uiarc.dev/components/tool-call/markdown): A tool call row for agent transcripts: the tool's mark and the call in plain words, a live state while it runs, and the input and output a click away, with approval and retry when needed.
- [Agent plan](https://uiarc.dev/components/agent-plan/markdown): The plan an agent writes before it acts: edit, reorder or add steps while it is a draft, then watch it work through them as a live checklist.
- [Agent timeline](https://uiarc.dev/components/agent-timeline/markdown): A compact timeline of one orchestrated agent run: the orchestrator and its subagents share a time axis, handoffs draw in between rows, and a playhead replays thinking, tool calls and waiting while the header counts time, tokens and cost. Hover a span for what it did, or click it to trace its handoff path.
- [Context window](https://uiarc.dev/components/context-window/markdown): An AI context window as a grid of 200 cells: the system prompt, tools, files, summary and messages fill it in order, a threshold row marks where compaction starts, and sending a message, attaching a file or compacting shows exactly how much still fits.
- [Reasoning block](https://uiarc.dev/components/reasoning-block/markdown): The collapsible thinking block of an AI reply. While the model thinks, a shimmering label counts the seconds and the latest reasoning streams underneath. When it finishes, it folds to "Thought for 7s" and opens to show the full reasoning as calm steps with headings.
- [Source cards](https://uiarc.dev/components/source-cards/markdown): A row of cited sources under an AI answer where cards stream in with real site marks while the model searches, the overflow collapses into a stack of favicons, hovering lifts a preview with the passage, and an inline [n] citation highlights its card.
- [Model card](https://uiarc.dev/components/model-card/markdown): A model details card where switching models rolls every price, limit and score in place, a token slider estimates monthly cost live, and benchmark bars show each model's rank on hover. Compare crossfades to a side-by-side table against any rival with the better values marked, and the card never changes size.
- [AI workflow](https://uiarc.dev/components/ai-workflow/markdown): A Linear-style AI workflow card where a Gmail trigger, a Claude step, a branch and Slack and Linear actions sit on one hairline rail, and a test run glides down it, opening each step's output inline. Steps are added from a compact command menu with real app marks.
- [Code suggestion](https://uiarc.dev/components/code-suggestion/markdown): An AI code edit suggestion where the model's proposed changes stream into a small editor panel as inline diff hunks, and you accept or reject each one, or all at once with Cmd+Enter. Accepted hunks fold into the file with a smooth height change.
- [Ghost text](https://uiarc.dev/components/ghost-text/markdown): An inline AI autocomplete where muted ghost text continues your sentence exactly at the caret and Tab turns it solid in place. Cmd+Right takes it one word at a time, Escape fades it away, and a calm chip shows the model behind it.
- [Dictation button](https://uiarc.dev/components/dictation-button/markdown): A chat composer with voice input, where the mic springs into a recording pill with a smooth live waveform, a timer, and cancel and insert buttons. Words stream into the field as you speak, muted until the recognizer settles them.
- [Speech player](https://uiarc.dev/components/speech-player/markdown): A read-aloud player for AI replies. The Read aloud button in the message's action row turns into a compact player with play, a scrubbable progress bar, speed and a voice picker, and a highlight follows the spoken word through the reply, karaoke style.
- [Meeting summary](https://uiarc.dev/components/meeting-summary/markdown): An AI meeting notes card: the header shows the Google Meet or Zoom mark, the attendees and the duration. Summary, Decisions and Action items stream in after a short summarizing pass. Hover any line to see the transcript quote it came from, then check off action items or send them to Linear or Notion.
- [Reply draft](https://uiarc.dev/components/reply-draft/markdown): An AI email reply drafter where Claude streams a reply under a received Gmail message. Quick replies steer a fresh draft, tone and length rewrite it with a single crossfade, and you can edit the finished draft before you insert it.
- [Agent handoff](https://uiarc.dev/components/agent-handoff/markdown): A support conversation where an AI assistant hands off to a person. When it transfers, a card shows the summary it passes to the team and the typical wait. The person then joins and takes over, and a thin timeline on the left marks each step.
- [PII redaction](https://uiarc.dev/components/pii-redaction/markdown): A guardrail card where personal data is redacted before the prompt reaches the model. Scan marks each name, email, phone number and card with its type and swaps it for a placeholder like [EMAIL_1]. The safe prompt travels to Claude, and the reply comes back with the original values put back for the person.
- [Response feedback](https://uiarc.dev/components/response-feedback/markdown): A feedback control for AI replies where thumbs down opens an inline panel with reason chips and an optional note, thumbs up fills and asks what was good, and a submit shows a short thank-you before folding back into the row.
- [LLM cost calculator](https://uiarc.dev/components/llm-cost-calculator/markdown): A pricing calculator for LLM workloads. Set tokens per request, requests per day and prompt caching, and eight current models re-rank by monthly cost. Bars glide and prices roll as you drag.
- [Provider keys](https://uiarc.dev/components/provider-keys/markdown): A settings card for bring-your-own-key AI products. Each provider row shows its real mark, the masked key, a status and when the key was last used. You can reveal a key for five seconds, copy, rotate or remove it with undo. Adding or rotating a key opens an inline form that checks the format as you type, then tests the connection before saving.
- [Generation stats](https://uiarc.dev/components/generation-stats/markdown): A live stats strip for a streaming LLM response where time to first token, speed with a sparkline, output tokens and cost count up in tabular numerals beside the model's real mark, then settle and open into a latency and token cost breakdown.
- [AI translate](https://uiarc.dev/components/ai-translate/markdown): A message card where picking a language streams the AI translation in place, sentence by sentence over the dimmed original, with a detected-language chip, a Show original toggle and a status line credited to the model's mark.
- [TL;DR toggle](https://uiarc.dev/components/tldr-toggle/markdown): An article card with a Full, Summary and Key points switch and a length slider. Switching streams an AI summary in place of the article as the card's height springs to fit, and each key point links back to the paragraph it came from, which gets scrolled to and highlighted.
- [Connector setup](https://uiarc.dev/components/connector-setup/markdown): A "Connect your tools" card for an AI assistant. Each app connects inline: it redirects, authorizes and runs a first sync with a progress hairline, then lists the scopes it was granted and offers Disconnect with an inline confirm.
- [Smart form fill](https://uiarc.dev/components/smart-form-fill/markdown): A paste-to-fill form card where AI reads an email signature or messy notes and fills a contact field by field. Each value flashes in with a confidence dot, its source lights up in the pasted text, low-confidence guesses ask for review, and Undo puts the old values back.
- [Enrich column](https://uiarc.dev/components/enrich-column/markdown): An AI enrichment column for a data table, where one prompt runs down every row and each cell shimmers while it works, then settles into a value with its source or a failure you can retry.
- [Ticket router](https://uiarc.dev/components/ticket-router/markdown): A support ticket router where messages from Gmail, Intercom, Slack and Zendesk come in one at a time. An AI classifier labels each one with intent, sentiment and confidence, and the ticket moves into a team lane with an assignee. Low confidence tickets wait in a review lane, and one click there routes them to the suggested team.
- [Ask your data](https://uiarc.dev/components/ask-your-data/markdown): A natural language to chart card: you ask a question, PostgreSQL streams into a collapsible, syntax highlighted panel, the query runs with a rolling row count, and the answer builds as stacked bars, lines or a table, with a one line insight streamed in underneath.
- [Agent cursor](https://uiarc.dev/components/agent-cursor/markdown): A live document where Claude edits like a collaborator. Its labeled cursor comes out of its avatar, selects a paragraph and streams in a rewrite, adds a heading and fixes a typo, while a teammate's cursor reads along. Changes stay tinted until someone accepts or undoes them from a floating review bar.
- [Provider status](https://uiarc.dev/components/provider-status/markdown): A status card for the AI providers your product depends on. Each row shows the provider's real mark, its health as an icon and label, p50 latency and a 30-day uptime bar with a tooltip for each day. An incident row expands into its timeline of updates, and the card checks again on a visible countdown.
- [Training run](https://uiarc.dev/components/training-run/markdown): A fine-tuning job card where a live train and validation loss curve draws across a fixed step axis that doubles as the epoch progress bar. It shows the learning rate, elapsed time, ETA and the latest evals and checkpoints, has Pause and Cancel while it runs, and ends in results with a Deploy button.
- [AI command](https://uiarc.dev/components/ai-command/markdown): A Cmd+K command palette with an AI mode. Search pages and actions, or press Tab to ask a question: the answer streams inside the palette with numbered sources, and the next steps it suggests, like filing a Linear issue or opening a Notion doc, run straight from the list.
- [Starter prompts](https://uiarc.dev/components/starter-prompts/markdown): A greeting and a grid of starter cards for the empty state of an AI app. The cards are grouped into Write, Code, Analyze and Plan tabs, and a shuffle swaps them with a short staggered crossfade. Picking a card fills the composer, and cards that use a connected app show its mark (Gmail, GitHub, Notion, Linear, Google Calendar).
- [AI mascot](https://uiarc.dev/components/ai-mascot/markdown): A small assistant character, a soft pebble with pill eyes and a companion dot, that shows what the AI is doing. It breathes and glances when idle, leans in to listen, looks up while the dot orbits its head, reads along the line it writes, squints with a sparkle when done and shakes once with worried brows on an error.
- [Image reveal](https://uiarc.dev/components/image-reveal/markdown): An image generation canvas where a soft, blurred preview made from the image's own colors sharpens top to bottom behind a soft-edged band. It works the way ChatGPT, Midjourney and Gemini show images forming, with fine film grain, a translucent progress pill and calm queued and error states.
- [AI spark](https://uiarc.dev/components/ai-spark/markdown): A brand-quality animated spark mark. Four tapered rays and four lighter diagonals breathe at rest, ripple while thinking, pulse like a heartbeat while writing, then gather and settle when done. Every status change blends from the pose the mark is already in.
- [Pixel mascot](https://uiarc.dev/components/pixel-mascot/markdown): A pixel-art robot that shows what an AI assistant is doing. It idles, thinks, types, celebrates and errors in frame-stepped sprite animations, and stays crisp at every integer size from 24px to 192px.
- [Ghost mascot](https://uiarc.dev/components/ghost-mascot/markdown): A floating ghost mascot whose soft sheet ripples at the hem while it hovers. It blinks when idle, turns toward you to listen, fades a little translucent while thinking, draws a tiny pen line while writing, smiles with a sparkle when done and wobbles once on an error.
- [Cube mascot](https://uiarc.dev/components/cube-mascot/markdown): An isometric cube mascot where three shaded faces and a painted-on face show what the assistant is doing. It turns a quarter turn in eased steps while thinking, prints lines onto the floor while writing, settles with a sparkle when done, and shakes once on error.
- [Tone tuner](https://uiarc.dev/components/tone-tuner/markdown): A brand voice card where two sliders (formality and detail) and Friendly, Confident and Empathetic chips rewrite a customer reply. Each changed sentence crossfades in place, new words can be highlighted against the original, and Copy takes the current version.
- [Upgrade prompt](https://uiarc.dev/components/upgrade-prompt/markdown): An upgrade nudge for the moment someone hits a limit. It shows a usage meter at 50 of 50 AI credits, a rolling price with a monthly and yearly toggle, three concrete unlocks with real model marks, and Upgrade or Maybe later. Upgrading leads into a success state with the new limits, and the card never changes size between states.
- [Referral card](https://uiarc.dev/components/referral-card/markdown): A give-and-get referral card where people copy or share their invite link, invite friends by email as chips, and watch invites move from invited to signed up to earned, with the credit total counting up and a milestone reward unlocking.
- [Trial banner](https://uiarc.dev/components/trial-banner/markdown): A trial status banner where a ring counts down the days left, the copy names what the workspace loses, and the upgrade path is one click away. It comes as a slim banner, a sidebar card or a header pill. It shifts to a warning tone in the last days, has expired and upgraded states, and folds into the pill when dismissed or snoozed.
- [Team switcher](https://uiarc.dev/components/team-switcher/markdown): A workspace switcher like Linear, Vercel or Slack. The trigger shows the current workspace's logo and plan. The menu has search, your role in each workspace and a Cmd+1 to 9 shortcut for each, and lets you create or join a workspace inline. A highlight glides between rows, and switching crossfades the trigger through a short loading state.
- [Live visitors](https://uiarc.dev/components/live-visitors/markdown): A realtime visitors card where the live count rolls digit by digit, new arrivals ping in on a dotted world map, the top pages reorder with bars, and signups and upgrades tick in with country flags.
- [Social proof toast](https://uiarc.dev/components/social-proof-toast/markdown): A stack of social proof notifications for landing and pricing pages, where recent trials, upgrades and verified purchases from people and companies arrive every few seconds. The stack pauses and fans out on hover, and visitors can dismiss any toast.
- [Install snippet](https://uiarc.dev/components/install-snippet/markdown): A "get started in 30 seconds" card where framework tabs, three numbered steps and highlighted snippets take a developer from install to first event. Generate key wipes a fresh API key into the placeholder in place.

### Guidance for AI tools

Image generation: An image studio where each image forms on a dot matrix: a soft halftone wave breathes across the grid, the dots take the colours of the coming photo and grow into a coloured halftone, then blur away into the sharp photo. One large canvas with a mono size label, a filmstrip of four variations, a prompt bar with model and ratio, and upscale with a sweeping dot band, vary or download, with real provider marks and a built-in simulation. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Dictation button

> A chat composer with voice input, where the mic springs into a recording pill with a smooth live waveform, a timer, and cancel and insert buttons. Words stream into the field as you speak, muted until the recognizer settles them.

- Type: Component (special)
- Access: Arc Pro
- Page: https://uiarc.dev/components/dictation-button
- Markdown: https://uiarc.dev/components/dictation-button/markdown
- Source file: `registry/components/dictation-button/dictation-button.tsx`
- Dependencies: motion, lucide-react, @radix-ui/react-tooltip
- Keywords: special, ai, new, dictation, voice input, speech to text, mic button, microphone, voice typing, transcription, web speech api, speechrecognition, waveform, recording pill, composer, chat input, interim results, ai composer

### When to use

- Chat and agent composers where people would rather talk than type: mobile, long prompts, accessibility.
- Notes, comments and support replies where dictation saves time and the person still edits before sending.
- Any field that already has a send action and needs a voice entry point with clear listening state.

### When not to use

- Full duplex voice conversations with spoken replies; use a voice agent pattern with call controls instead.
- Recording audio files to keep (voice memos); this inserts text and discards audio.
- Command palettes where a single spoken command should run immediately; confirm hands-free from onSpeechEnd only if you are sure.

### Installation

Dictation button is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/dictation-button
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { DictationButton, createWebSpeechRecognizer } from "@/components/arc/dictation-button/dictation-button";

const recognizer = createWebSpeechRecognizer({ lang: "en-US" });

export function Composer({ onSubmit }: { onSubmit: (text: string) => Promise<void> }) {
  return <DictationButton
    recognizer={recognizer}
    placeholder="Message Claude"
    onSend={onSubmit}
    onStatusChange={(status, error) => { if (status === "denied") console.info("Microphone blocked", error); }}
  />;
}
```

### Examples

#### Only the control, in your own composer

```tsx
import { useState } from "react";
import { DictationControl } from "@/components/arc/dictation-button/dictation-button";

export function Field() {
  const [text, setText] = useState("");
  const [live, setLive] = useState({ final: "", interim: "" });
  return <div className="composer">
    <p>{text} {live.final} <span className="muted">{live.interim}</span></p>
    <DictationControl
      onTranscript={setLive}
      onCommit={final => { setText(t => (t ? t + " " : "") + final); setLive({ final: "", interim: "" }); }}
      onCancel={() => setLive({ final: "", interim: "" })}
    />
  </div>;
}
```

#### Your own speech service

```tsx
import { DictationError, type DictationRecognizer } from "@/components/arc/dictation-button/dictation-button";

export const deepgram: DictationRecognizer = async (handlers, signal) => {
  const stream = await navigator.mediaDevices.getUserMedia({ audio: true }).catch(() => { throw new DictationError("not-allowed"); });
  const socket = new WebSocket("wss://your-proxy.example.com/listen");
  socket.onmessage = event => {
    const { final, interim, level } = JSON.parse(event.data);
    handlers.onTranscript({ final, interim });
    handlers.onLevel(level);
  };
  signal.addEventListener("abort", () => { socket.close(); stream.getTracks().forEach(t => t.stop()); });
  // ...pipe stream audio into the socket...
  return { stop: () => new Promise(resolve => { socket.onclose = () => resolve(lastFinal); socket.send("finalize"); }) };
};
```

### API reference

#### DictationButton

A composer with voice input: the field, a model label, the dictation pill and send. Words stream into the field while the person speaks, interim guesses muted until they settle.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `string` | – | Field text, controlled. |
| `defaultValue` | `string` | `""` | Initial field text when uncontrolled. |
| `onValueChange` | `(value: string) => void` | – | Called on typing, after a dictation is inserted, and when the field clears on send. |
| `placeholder` | `string` | `"Message Claude"` | Field placeholder. |
| `recognizer` | `DictationRecognizer` | `simulated` | Speech source. Defaults to a simulated recognizer that never touches the microphone. Pass createWebSpeechRecognizer() or your own adapter. |
| `onTranscript` | `(transcript: { final: string; interim: string }) => void` | – | Live, cumulative transcript of the current session. |
| `onCommit` | `(text: string) => void` | – | Final text of a session, after it has been appended to the field. |
| `onSend` | `(text: string) => void \| Promise<void>` | – | Send the message. The send button shows a spinner while the promise is pending and the field clears when it resolves. Without it, sending is simulated. |
| `onStatusChange` | `(status: "idle" \| "starting" \| "listening" \| "processing" \| "denied" \| "error", error?: DictationErrorCode) => void` | – | Every state change, with the error code for denied and error. |
| `autoPlay` | `boolean` | `true with the simulated recognizer` | Loop a scripted dictation (listen, insert, send) until the first pointer, key or focus inside the card. Pauses off screen. |
| `maxDuration` | `number` | `120` | Seconds before listening stops and inserts on its own. 0 turns the limit off. |
| `model` | `{ name: string; mark?: ReactNode } \| null` | `Claude Sonnet 5.5` | Model label at the start of the toolbar. null hides it. |
| `disabled` | `boolean` | `false` | Disables the field, mic and send. |
| `aria-label` | `string` | `"Message"` | Accessible name of the field. |
| `className` | `string` | – | Class on the root. |

#### DictationControl

Just the mic and recording pill, for a composer you already have. Same state machine, no field.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `recognizer` | `DictationRecognizer` | `simulated` | Speech source. |
| `onTranscript` | `(transcript: DictationTranscript) => void` | – | Live text to render in your own field (style interim as muted). |
| `onCommit` | `(text: string) => void` | – | Final text to append to your field. |
| `onCancel` | `() => void` | – | The person cancelled; drop any live text you rendered. |
| `onSpeechEnd` | `() => void` | – | The recognizer detected the end of an utterance. Call nothing, or confirm hands-free. |
| `onStatusChange` | `(status, error?) => void` | – | Every state change. |
| `maxDuration` | `number` | `120` | Seconds before listening inserts on its own. |
| `label` | `string` | `"Dictate"` | Accessible name and tooltip of the mic. |
| `disabled` | `boolean` | `false` | Disables the mic. |
| `className` | `string` | – | Class on the wrapper. |

#### useDictation

The headless state machine behind both parts: idle, starting, listening, processing, then idle, or denied and error. Returns status, transcript, error, startedAt, levelRef (0 to 1, read per frame), start, confirm, cancel and dismiss.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `options` | `UseDictationOptions` | – | recognizer, maxDuration, onTranscript, onCommit, onCancel, onSpeechEnd, onStatusChange. |

#### DictationRecognizer

The adapter contract: (handlers, signal) => Promise<{ stop(): Promise<string> }>. Resolve once audio flows, reject with new DictationError("not-allowed") on a blocked microphone, call handlers.onTranscript({ final, interim }), handlers.onLevel(0..1), handlers.onSpeechEnd() and handlers.onError(code). Abort the signal to cancel.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `createSimulatedRecognizer` | `(options?: { scripts?: DictationPhrase[][]; deny?: boolean; startDelay?: number; finalizeDelay?: number; wordInterval?: number }) => DictationRecognizer` | – | Scripted speech with interim corrections and speech-like levels. deny: true rejects every start, like a blocked microphone. |
| `createWebSpeechRecognizer` | `(options?: { lang?: string; levels?: boolean }) => DictationRecognizer` | – | Browser SpeechRecognition (Chrome, Edge, Safari) with levels from getUserMedia and an AnalyserNode. Rejects with "unsupported" where it is missing. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Enter / Space | On the mic: start dictating. Focus moves to Insert. |
| Enter | While listening: stop and insert the transcript (also from anywhere inside the card). |
| Escape | While listening: cancel and discard. On Try again: dismiss the error. |
| Enter | In the field: send. Shift+Enter adds a line. |
| Tab | Moves through cancel, insert, then send. Hidden faces of the pill are inert. |

### Accessibility

- A polite live region announces listening (and that the default recognizer is simulated, nothing is recorded), transcribing, the inserted word count, cancel, send and every error with how to fix it. Streaming words are not announced, to keep screen readers quiet.
- Status is never color alone: denied shows a mic-off icon and "Microphone blocked in site settings"; errors show an alert icon and a short reason; Try again keeps the same icon.
- Only the visible face of the pill is focusable (the other faces are inert), and focus follows the action: mic to Insert, Insert back to the field at the end of the text, cancel back to the mic, a failed start to Try again.
- The elapsed time is a role="timer" with tabular numerals in a reserved width; the waveform is decorative and hidden from assistive tech.
- Mic, cancel and Insert are icon buttons with accessible names and tooltips (Dictate, Cancel, Insert, Transcribing).
- Interim words use a muted tone between --text-muted and --text-secondary and settle to --foreground, so the difference reads in both themes without relying on hue.

### Motion

- The mic springs leftward into the recording pill (up to 216px, measured from the toolbar) with a critically damped spring (0.24s visual duration, no bounce); Try again springs to its measured label width. The mic's spot becomes Insert, so the next action sits where the pointer already is.
- Faces crossfade (out 100ms, in 160ms). The toolbar label swaps with a single 2px crossfade. Insert crossfades its check into a spinner while transcribing.
- Words only fade in (140ms). A corrected interim guess refades just the words that changed. The field springs to each new line.
- The waveform fits as many 3px rounded bars as the track holds with an even 2px gap, so no bar is ever clipped. A level sample enters on the right every 60ms and each bar eases toward it every frame, so heights glide without steps or jitter, written straight to the DOM with no React renders. When listening stops, the bars settle in place to a row of dots.
- Reduced motion: no size springs, no word fades, the waveform stops travelling and pulses in place with the voice. Loops pause off screen and in background tabs.

### Responsive behavior

- Fluid to 640px. The pill keeps a fixed 216px so nothing reflows while recording; at 360px the toolbar label gives way while recording.
- Container queries, not viewport: keyboard hints hide under 460px of card width and error copy shortens under 400px.
- All targets are 36px in the toolbar; the pill's cancel and insert are 28px inside a 36px pill with 4px padding.
- The field grows to six lines, then scrolls, and keeps the newest words in view while dictating.

### Performance

- Levels live in a ref and the waveform and timer write to the DOM directly, so a session renders React only when the transcript changes.
- The waveform frame loop stops once the bars have settled and pauses while off screen or in a background tab.
- The Web Speech adapter releases the microphone tracks and closes the AudioContext on stop, cancel, error and unmount.
- No audio is buffered in memory; text arrives as strings from the recognizer.

### Notes for AI

- Use DictationButton when you need the whole composer; use DictationControl inside an existing composer and render onTranscript yourself with interim text muted.
- The default recognizer is simulated. For production pass createWebSpeechRecognizer() (free, browser built-in, Chrome sends audio to Google) or write a DictationRecognizer for Deepgram, AssemblyAI, OpenAI or Whisper over a websocket; the contract is five callbacks and an AbortSignal.
- Handle status "denied" in product copy: the component already says where to fix it, but you may want to link to your help article.
- Do not pass autoPlay in production; it is for docs and marketing demos and defaults to off with a real recognizer.
- Keep the model label honest: pass the model the composer actually sends to, or null.

### Related

- [Chat thread](https://uiarc.dev/components/chat-thread/markdown): A chat thread with grouped messages, reactions, read receipts, typing, and a composer with attachments.
- [Text shimmer](https://uiarc.dev/components/text-shimmer/markdown): Show ongoing work with a calm light across the words.
- [Tooltip](https://uiarc.dev/components/tooltip/markdown): Short supporting text for unfamiliar controls.
- [Tool call](https://uiarc.dev/components/tool-call/markdown): A tool call row for agent transcripts: the tool's mark and the call in plain words, a live state while it runs, and the input and output a click away, with approval and retry when needed.
- [Agent status](https://uiarc.dev/components/agent-status/markdown): A compact live status pill for a running AI agent: the agent's mark in a live ring, the current activity and an elapsed timer, opening into the steps so far.

### Also in ai

- [Agent plan](https://uiarc.dev/components/agent-plan/markdown): The plan an agent writes before it acts: edit, reorder or add steps while it is a draft, then watch it work through them as a live checklist.
- [Agent timeline](https://uiarc.dev/components/agent-timeline/markdown): A compact timeline of one orchestrated agent run: the orchestrator and its subagents share a time axis, handoffs draw in between rows, and a playhead replays thinking, tool calls and waiting while the header counts time, tokens and cost. Hover a span for what it did, or click it to trace its handoff path.
- [Context window](https://uiarc.dev/components/context-window/markdown): An AI context window as a grid of 200 cells: the system prompt, tools, files, summary and messages fill it in order, a threshold row marks where compaction starts, and sending a message, attaching a file or compacting shows exactly how much still fits.
- [Reasoning block](https://uiarc.dev/components/reasoning-block/markdown): The collapsible thinking block of an AI reply. While the model thinks, a shimmering label counts the seconds and the latest reasoning streams underneath. When it finishes, it folds to "Thought for 7s" and opens to show the full reasoning as calm steps with headings.
- [Source cards](https://uiarc.dev/components/source-cards/markdown): A row of cited sources under an AI answer where cards stream in with real site marks while the model searches, the overflow collapses into a stack of favicons, hovering lifts a preview with the passage, and an inline [n] citation highlights its card.
- [Model card](https://uiarc.dev/components/model-card/markdown): A model details card where switching models rolls every price, limit and score in place, a token slider estimates monthly cost live, and benchmark bars show each model's rank on hover. Compare crossfades to a side-by-side table against any rival with the better values marked, and the card never changes size.
- [AI workflow](https://uiarc.dev/components/ai-workflow/markdown): A Linear-style AI workflow card where a Gmail trigger, a Claude step, a branch and Slack and Linear actions sit on one hairline rail, and a test run glides down it, opening each step's output inline. Steps are added from a compact command menu with real app marks.
- [Code suggestion](https://uiarc.dev/components/code-suggestion/markdown): An AI code edit suggestion where the model's proposed changes stream into a small editor panel as inline diff hunks, and you accept or reject each one, or all at once with Cmd+Enter. Accepted hunks fold into the file with a smooth height change.
- [Ghost text](https://uiarc.dev/components/ghost-text/markdown): An inline AI autocomplete where muted ghost text continues your sentence exactly at the caret and Tab turns it solid in place. Cmd+Right takes it one word at a time, Escape fades it away, and a calm chip shows the model behind it.
- [Image generation](https://uiarc.dev/components/image-generation/markdown): An image studio where each image forms on a dot matrix: a soft halftone wave breathes across the grid, the dots take the colours of the coming photo and grow into a coloured halftone, then blur away into the sharp photo. One large canvas with a mono size label, a filmstrip of four variations, a prompt bar with model and ratio, and upscale with a sweeping dot band, vary or download, with real provider marks and a built-in simulation.
- [Speech player](https://uiarc.dev/components/speech-player/markdown): A read-aloud player for AI replies. The Read aloud button in the message's action row turns into a compact player with play, a scrubbable progress bar, speed and a voice picker, and a highlight follows the spoken word through the reply, karaoke style.
- [Meeting summary](https://uiarc.dev/components/meeting-summary/markdown): An AI meeting notes card: the header shows the Google Meet or Zoom mark, the attendees and the duration. Summary, Decisions and Action items stream in after a short summarizing pass. Hover any line to see the transcript quote it came from, then check off action items or send them to Linear or Notion.
- [Reply draft](https://uiarc.dev/components/reply-draft/markdown): An AI email reply drafter where Claude streams a reply under a received Gmail message. Quick replies steer a fresh draft, tone and length rewrite it with a single crossfade, and you can edit the finished draft before you insert it.
- [Agent handoff](https://uiarc.dev/components/agent-handoff/markdown): A support conversation where an AI assistant hands off to a person. When it transfers, a card shows the summary it passes to the team and the typical wait. The person then joins and takes over, and a thin timeline on the left marks each step.
- [PII redaction](https://uiarc.dev/components/pii-redaction/markdown): A guardrail card where personal data is redacted before the prompt reaches the model. Scan marks each name, email, phone number and card with its type and swaps it for a placeholder like [EMAIL_1]. The safe prompt travels to Claude, and the reply comes back with the original values put back for the person.
- [Response feedback](https://uiarc.dev/components/response-feedback/markdown): A feedback control for AI replies where thumbs down opens an inline panel with reason chips and an optional note, thumbs up fills and asks what was good, and a submit shows a short thank-you before folding back into the row.
- [LLM cost calculator](https://uiarc.dev/components/llm-cost-calculator/markdown): A pricing calculator for LLM workloads. Set tokens per request, requests per day and prompt caching, and eight current models re-rank by monthly cost. Bars glide and prices roll as you drag.
- [Provider keys](https://uiarc.dev/components/provider-keys/markdown): A settings card for bring-your-own-key AI products. Each provider row shows its real mark, the masked key, a status and when the key was last used. You can reveal a key for five seconds, copy, rotate or remove it with undo. Adding or rotating a key opens an inline form that checks the format as you type, then tests the connection before saving.
- [Generation stats](https://uiarc.dev/components/generation-stats/markdown): A live stats strip for a streaming LLM response where time to first token, speed with a sparkline, output tokens and cost count up in tabular numerals beside the model's real mark, then settle and open into a latency and token cost breakdown.
- [AI translate](https://uiarc.dev/components/ai-translate/markdown): A message card where picking a language streams the AI translation in place, sentence by sentence over the dimmed original, with a detected-language chip, a Show original toggle and a status line credited to the model's mark.
- [TL;DR toggle](https://uiarc.dev/components/tldr-toggle/markdown): An article card with a Full, Summary and Key points switch and a length slider. Switching streams an AI summary in place of the article as the card's height springs to fit, and each key point links back to the paragraph it came from, which gets scrolled to and highlighted.
- [Connector setup](https://uiarc.dev/components/connector-setup/markdown): A "Connect your tools" card for an AI assistant. Each app connects inline: it redirects, authorizes and runs a first sync with a progress hairline, then lists the scopes it was granted and offers Disconnect with an inline confirm.
- [Smart form fill](https://uiarc.dev/components/smart-form-fill/markdown): A paste-to-fill form card where AI reads an email signature or messy notes and fills a contact field by field. Each value flashes in with a confidence dot, its source lights up in the pasted text, low-confidence guesses ask for review, and Undo puts the old values back.
- [Enrich column](https://uiarc.dev/components/enrich-column/markdown): An AI enrichment column for a data table, where one prompt runs down every row and each cell shimmers while it works, then settles into a value with its source or a failure you can retry.
- [Ticket router](https://uiarc.dev/components/ticket-router/markdown): A support ticket router where messages from Gmail, Intercom, Slack and Zendesk come in one at a time. An AI classifier labels each one with intent, sentiment and confidence, and the ticket moves into a team lane with an assignee. Low confidence tickets wait in a review lane, and one click there routes them to the suggested team.
- [Ask your data](https://uiarc.dev/components/ask-your-data/markdown): A natural language to chart card: you ask a question, PostgreSQL streams into a collapsible, syntax highlighted panel, the query runs with a rolling row count, and the answer builds as stacked bars, lines or a table, with a one line insight streamed in underneath.
- [Agent cursor](https://uiarc.dev/components/agent-cursor/markdown): A live document where Claude edits like a collaborator. Its labeled cursor comes out of its avatar, selects a paragraph and streams in a rewrite, adds a heading and fixes a typo, while a teammate's cursor reads along. Changes stay tinted until someone accepts or undoes them from a floating review bar.
- [Provider status](https://uiarc.dev/components/provider-status/markdown): A status card for the AI providers your product depends on. Each row shows the provider's real mark, its health as an icon and label, p50 latency and a 30-day uptime bar with a tooltip for each day. An incident row expands into its timeline of updates, and the card checks again on a visible countdown.
- [Training run](https://uiarc.dev/components/training-run/markdown): A fine-tuning job card where a live train and validation loss curve draws across a fixed step axis that doubles as the epoch progress bar. It shows the learning rate, elapsed time, ETA and the latest evals and checkpoints, has Pause and Cancel while it runs, and ends in results with a Deploy button.
- [AI command](https://uiarc.dev/components/ai-command/markdown): A Cmd+K command palette with an AI mode. Search pages and actions, or press Tab to ask a question: the answer streams inside the palette with numbered sources, and the next steps it suggests, like filing a Linear issue or opening a Notion doc, run straight from the list.
- [Starter prompts](https://uiarc.dev/components/starter-prompts/markdown): A greeting and a grid of starter cards for the empty state of an AI app. The cards are grouped into Write, Code, Analyze and Plan tabs, and a shuffle swaps them with a short staggered crossfade. Picking a card fills the composer, and cards that use a connected app show its mark (Gmail, GitHub, Notion, Linear, Google Calendar).
- [AI mascot](https://uiarc.dev/components/ai-mascot/markdown): A small assistant character, a soft pebble with pill eyes and a companion dot, that shows what the AI is doing. It breathes and glances when idle, leans in to listen, looks up while the dot orbits its head, reads along the line it writes, squints with a sparkle when done and shakes once with worried brows on an error.
- [Image reveal](https://uiarc.dev/components/image-reveal/markdown): An image generation canvas where a soft, blurred preview made from the image's own colors sharpens top to bottom behind a soft-edged band. It works the way ChatGPT, Midjourney and Gemini show images forming, with fine film grain, a translucent progress pill and calm queued and error states.
- [AI spark](https://uiarc.dev/components/ai-spark/markdown): A brand-quality animated spark mark. Four tapered rays and four lighter diagonals breathe at rest, ripple while thinking, pulse like a heartbeat while writing, then gather and settle when done. Every status change blends from the pose the mark is already in.
- [Pixel mascot](https://uiarc.dev/components/pixel-mascot/markdown): A pixel-art robot that shows what an AI assistant is doing. It idles, thinks, types, celebrates and errors in frame-stepped sprite animations, and stays crisp at every integer size from 24px to 192px.
- [Ghost mascot](https://uiarc.dev/components/ghost-mascot/markdown): A floating ghost mascot whose soft sheet ripples at the hem while it hovers. It blinks when idle, turns toward you to listen, fades a little translucent while thinking, draws a tiny pen line while writing, smiles with a sparkle when done and wobbles once on an error.
- [Cube mascot](https://uiarc.dev/components/cube-mascot/markdown): An isometric cube mascot where three shaded faces and a painted-on face show what the assistant is doing. It turns a quarter turn in eased steps while thinking, prints lines onto the floor while writing, settles with a sparkle when done, and shakes once on error.
- [Tone tuner](https://uiarc.dev/components/tone-tuner/markdown): A brand voice card where two sliders (formality and detail) and Friendly, Confident and Empathetic chips rewrite a customer reply. Each changed sentence crossfades in place, new words can be highlighted against the original, and Copy takes the current version.
- [Upgrade prompt](https://uiarc.dev/components/upgrade-prompt/markdown): An upgrade nudge for the moment someone hits a limit. It shows a usage meter at 50 of 50 AI credits, a rolling price with a monthly and yearly toggle, three concrete unlocks with real model marks, and Upgrade or Maybe later. Upgrading leads into a success state with the new limits, and the card never changes size between states.
- [Referral card](https://uiarc.dev/components/referral-card/markdown): A give-and-get referral card where people copy or share their invite link, invite friends by email as chips, and watch invites move from invited to signed up to earned, with the credit total counting up and a milestone reward unlocking.
- [Trial banner](https://uiarc.dev/components/trial-banner/markdown): A trial status banner where a ring counts down the days left, the copy names what the workspace loses, and the upgrade path is one click away. It comes as a slim banner, a sidebar card or a header pill. It shifts to a warning tone in the last days, has expired and upgraded states, and folds into the pill when dismissed or snoozed.
- [Team switcher](https://uiarc.dev/components/team-switcher/markdown): A workspace switcher like Linear, Vercel or Slack. The trigger shows the current workspace's logo and plan. The menu has search, your role in each workspace and a Cmd+1 to 9 shortcut for each, and lets you create or join a workspace inline. A highlight glides between rows, and switching crossfades the trigger through a short loading state.
- [Live visitors](https://uiarc.dev/components/live-visitors/markdown): A realtime visitors card where the live count rolls digit by digit, new arrivals ping in on a dotted world map, the top pages reorder with bars, and signups and upgrades tick in with country flags.
- [Social proof toast](https://uiarc.dev/components/social-proof-toast/markdown): A stack of social proof notifications for landing and pricing pages, where recent trials, upgrades and verified purchases from people and companies arrive every few seconds. The stack pauses and fans out on hover, and visitors can dismiss any toast.
- [Install snippet](https://uiarc.dev/components/install-snippet/markdown): A "get started in 30 seconds" card where framework tabs, three numbered steps and highlighted snippets take a developer from install to first event. Generate key wipes a fresh API key into the placeholder in place.

### Guidance for AI tools

Dictation button: A chat composer with voice input, where the mic springs into a recording pill with a smooth live waveform, a timer, and cancel and insert buttons. Words stream into the field as you speak, muted until the recognizer settles them. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Speech player

> A read-aloud player for AI replies. The Read aloud button in the message's action row turns into a compact player with play, a scrubbable progress bar, speed and a voice picker, and a highlight follows the spoken word through the reply, karaoke style.

- Type: Component (special)
- Access: Arc Pro
- Page: https://uiarc.dev/components/speech-player
- Markdown: https://uiarc.dev/components/speech-player/markdown
- Source file: `registry/components/speech-player/speech-player.tsx`
- Dependencies: motion, lucide-react, @radix-ui/react-popover, @radix-ui/react-tooltip
- Keywords: special, ai, new, text to speech, tts, read aloud, speech player, karaoke, word highlight, audio player, voice picker, playback speed, ai reply, accessibility, elevenlabs, openai tts, claude, message actions

### When to use

- A chat or answer surface where people want a reply read out, with the spoken word followed in the text.
- Accessibility and hands free reading for long AI answers, summaries or briefings.
- Previewing TTS voices and speeds against real product copy.

### When not to use

- Use dictation-button to turn speech into text in a composer.
- Use a plain audio player for podcasts or long recordings without a transcript to highlight.

### Installation

Speech player is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/speech-player
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { SpeechPlayer } from "@/components/arc/speech-player/speech-player";

export function AssistantMessage({ message }) {
  return (
    <SpeechPlayer
      variant="plain"
      text={message.text}
      author={{ name: "Claude Sonnet 5.5", mark: <ClaudeMark style={{ color: "#D97757" }} /> }}
      voices={[
        { id: "ava", name: "Ava", description: "Warm and conversational" },
        { id: "leo", name: "Leo", description: "Calm, lower register" },
      ]}
      synthesize={async ({ text, voice, signal }) => {
        const res = await fetch("/api/tts", { method: "POST", body: JSON.stringify({ text, voice: voice.id }), signal });
        if (!res.ok) throw new Error("The voice service is busy. Try again in a moment.");
        const { audioUrl, words } = await res.json(); // words: [{ start, end }] in ms
        return { src: audioUrl, timings: words };
      }}
      onPlay={e => track("tts_play", { voice: e.voice.id, speed: e.speed })}
      actions={<><CopyButton value={message.text} iconOnly variant="plain" /><RegenerateButton /></>}
    />
  );
}

// With no props it reads the sample reply, simulated, with no audio.
<SpeechPlayer />
```

### API reference

#### SpeechPlayer

Read aloud for an AI reply. The reply sits above an action row with Read aloud, Copy, Good response and Bad response. Read aloud crossfades the row into a compact player of the same height: a play and pause button, the elapsed time, a thin scrubbable progress bar, the total time, a speed button (1×, 1.5×, 2×), a voice picker and Stop reading. As it plays, the spoken word is highlighted in the paragraph by one rounded rect that glides from word to word along a line and cuts cleanly to the next line, while words still to come stay dimmed. Clicking a word jumps there. It covers idle, preparing (a shimmering "Preparing Ava's voice"), playing, paused, switching voice mid-sentence (it resumes from the same word), finished (Play again) and failed (Retry). With no props it reads a sample travel reply from Claude Sonnet 5.5 once in view and loops through two voices until someone interacts.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `text` | `string` | – | The reply to read. Blank lines start new paragraphs; each whitespace separated word is one highlight step. Leave it out for the self playing sample. |
| `synthesize` | `(request: { text: string; voice: SpeechVoice; signal: AbortSignal }) => Promise<SpeechAudio>` | – | Fetches speech from your TTS provider. Resolve with { src, timings?, duration? }: src is an audio URL or object URL, and timings are word start and end times in milliseconds from the provider's alignment data. Without timings, they are estimated from the text and scaled to the audio length. Abort the request when the signal fires (a new voice or Stop reading). Leave synthesize out for simulated timing with no audio. |
| `voices` | `SpeechVoice[]` | `Ava, Leo, Maya, Noah` | Voices in the picker: { id, name, description? }. The description is one short line, such as "Warm and conversational". |
| `voice` | `string` | – | Selected voice id (controlled). Pair with onVoiceChange. |
| `defaultVoice` | `string` | `first voice` | Initial voice id when uncontrolled. |
| `onVoiceChange` | `(voice: SpeechVoice) => void` | – | Called when a voice is picked. While reading, the player fetches the new voice and resumes from the word being spoken. |
| `speed` | `1 \| 1.5 \| 2` | – | Playback speed (controlled). Pair with onSpeedChange. |
| `defaultSpeed` | `1 \| 1.5 \| 2` | `1` | Initial speed when uncontrolled. The speed button cycles 1×, 1.5×, 2×. |
| `onSpeedChange` | `(speed: SpeechSpeed) => void` | – | Called when the speed button is pressed. |
| `onPlay` | `(event: SpeechPlaybackEvent) => void` | – | Playback started or resumed. The event carries time and duration in milliseconds on the 1× timeline, wordIndex, voice and speed. |
| `onPause` | `(event: SpeechPlaybackEvent) => void` | – | Playback paused. |
| `onEnd` | `(event: SpeechPlaybackEvent) => void` | – | The last word finished. |
| `onSeek` | `(event: SpeechPlaybackEvent) => void` | – | A scrub, an arrow key or a click on a word moved playback. Fires once when a drag ends, not on every move. |
| `onWordChange` | `(event: SpeechWordEvent) => void` | – | The spoken word changed. Adds word to the playback event; use it to sync a caption or analytics. |
| `onClose` | `() => void` | – | Stop reading was pressed and the action row returned. Fetched audio is kept, so Read aloud starts again instantly. |
| `author` | `{ name: string; mark?: ReactNode } \| null` | – | Who wrote the reply, shown above it with a 16px mark. Defaults to Claude Sonnet 5.5 for the sample and to nothing when text is passed. |
| `actions` | `ReactNode` | – | Buttons after Read aloud in the action row. Defaults to Copy, Good response and Bad response (feedback is local and announced as simulated); null shows Read aloud alone. |
| `autoPlay` | `boolean` | `true for the sample` | Starts reading once the player is in view. Browsers may block audio autoplay; the player then waits paused at 0:00. |
| `simulated` | `boolean` | `true without synthesize` | Notes in the voice menu and in announcements that no audio plays. |
| `variant` | `"card" \| "plain"` | `"card"` | card draws a bordered surface; plain drops border and padding to sit inside a chat column. |
| `className` | `string` | – | Class on the root element. |

#### simulateSpeech

The stand in TTS request behind the preview: waits like a network round trip, then resolves with estimated word timings and no audio. Nothing is sent. Pass { fail: true } as the second argument to see the error state, or { delay } to tune the wait. estimateSpeechTimings(text, pace) and fitTimings(timings, durationMs) are exported too.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `request` | `{ text: string; voice: SpeechVoice; signal: AbortSignal }` | – | The same request synthesize receives. |
| `options` | `{ delay?: number; fail?: boolean }` | `{ delay: 640 }` | Milliseconds before it resolves, and whether it rejects instead. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Tab | Moves through Read aloud and the actions, or, while reading, through play, the progress bar, speed, voice and Stop reading. |
| Enter, Space | On Read aloud, opens the player and starts reading with focus on the play button. On play, plays or pauses; on Stop reading, closes the player and returns focus to Read aloud. |
| Arrow Left, Arrow Right | On the progress bar, moves 2 seconds back or forward. Page Up and Page Down move 10 seconds; Home and End jump to the start or end. |
| Space, K | On the progress bar, plays or pauses. |
| Arrow Up, Arrow Down | In the voice menu, moves between voices; Enter picks one and Escape closes the menu. |

### Accessibility

- The player is a labelled group. The play button's name follows its state: Play, Pause, Play again, Retry, or Preparing audio (aria-disabled while a request is in flight).
- The progress bar is a slider with a value text such as "0:04 of 0:22", updated once a second rather than every frame.
- A polite status region announces what changed: reading with Ava at 1× (simulated, no audio plays), paused at 0:12, switching to Leo, finished, the failure message, speed changes and feedback.
- Status never relies on color: the error pairs an alert icon with "Couldn't generate audio" and the reason; dimmed upcoming words keep body contrast and are only a progress cue.
- Read aloud is described by the reply text. The voice menu uses menuitemradio items with aria-checked and opens with focus on the selected voice.
- The hidden layer of the dock is inert, so Tab never lands on a control that is not visible. Pointer focus draws no ring; keyboard focus uses Arc's shared focus ring.

### Motion

- Read aloud and Stop reading crossfade the action row and the player in the same 32px slot (out in 100ms, in 160ms with a 2px rise), so the card never changes size.
- The word highlight is one rect that glides between words on a line in 150ms at 1× (about 100ms at 1.5× and 75ms at 2×, so it always lands before the next word) and cuts to the next line instead of sweeping across it. Spoken words fade from dimmed to full color.
- The progress bar fill and thumb are written straight to transforms on each animation frame; the track thickens and the thumb scales in on hover, focus and drag.
- Play, pause, replay, retry and the spinner swap in place with a bounce free scale and fade. Speed and voice labels crossfade over hidden copies of every option, so their buttons never resize.
- The preparing label carries a calm shimmer. Reduced motion keeps every state and announcement, drops the glide, the shimmer and the sample loop, and moves the highlight instantly.

### Responsive behavior

- The card fills its container up to 640px; the reply wraps and the highlight re-measures on resize without animating.
- Below 440px of width the total time steps aside so the progress bar keeps room; elapsed time, speed, voice and Stop reading stay.
- On touch screens the row grows to 36px so every control meets the touch target size.

### Performance

- One requestAnimationFrame loop runs only while playing. It writes the bar to the DOM and commits React state only when the spoken word or the whole second changes.
- Highlight positions come from offsetLeft and offsetTop of the current word, read once per word, never per frame.
- Fetched audio is kept per voice, so replaying after Stop reading starts instantly; switching voices aborts the previous request.

### Notes for AI

- Pass synthesize for real audio. Most TTS providers can return word or character alignment; convert it to one { start, end } per whitespace separated word of text, in milliseconds. If yours cannot, return src alone and the timings are estimated and fitted to the audio length.
- Keep text exactly what was spoken: the word count of text must match timings. Strip markdown before passing it.
- Throw an Error with a short, human message from synthesize to show it next to "Couldn't generate audio"; the play button becomes Retry.
- Use variant="plain" inside a chat transcript and pass your own actions so the row matches the rest of the message actions.
- Without synthesize the player is a timed simulation that plays no sound; keep the simulated note so nobody thinks audio is broken.

### Related

- [AI chat](https://uiarc.dev/components/blocks/ai-chat/markdown): A full-screen AI chat where answers stream in as markdown with folding reasoning, tool chips and cited sources. People can switch chats and models, edit or retry a message into versions, rate replies and stop a reply mid-stream.
- [AI answer](https://uiarc.dev/components/blocks/ai-answer/markdown): One AI answer set like a clean article: it thinks, shows its sources as small cards with colored marks, and streams a formatted answer where every citation lights the sentence it supports. Copy, regenerate with options, rate, share, page through versions and ask a related question in place.
- [Dictation button](https://uiarc.dev/components/dictation-button/markdown): A chat composer with voice input, where the mic springs into a recording pill with a smooth live waveform, a timer, and cancel and insert buttons. Words stream into the field as you speak, muted until the recognizer settles them.
- [Copy button](https://uiarc.dev/components/copy-button/markdown): Copy a value with immediate confirmation.
- [Text shimmer](https://uiarc.dev/components/text-shimmer/markdown): Show ongoing work with a calm light across the words.
- [Meeting summary](https://uiarc.dev/components/meeting-summary/markdown): An AI meeting notes card: the header shows the Google Meet or Zoom mark, the attendees and the duration. Summary, Decisions and Action items stream in after a short summarizing pass. Hover any line to see the transcript quote it came from, then check off action items or send them to Linear or Notion.

### Also in ai

- [Agent status](https://uiarc.dev/components/agent-status/markdown): A compact live status pill for a running AI agent: the agent's mark in a live ring, the current activity and an elapsed timer, opening into the steps so far.
- [Tool call](https://uiarc.dev/components/tool-call/markdown): A tool call row for agent transcripts: the tool's mark and the call in plain words, a live state while it runs, and the input and output a click away, with approval and retry when needed.
- [Agent plan](https://uiarc.dev/components/agent-plan/markdown): The plan an agent writes before it acts: edit, reorder or add steps while it is a draft, then watch it work through them as a live checklist.
- [Agent timeline](https://uiarc.dev/components/agent-timeline/markdown): A compact timeline of one orchestrated agent run: the orchestrator and its subagents share a time axis, handoffs draw in between rows, and a playhead replays thinking, tool calls and waiting while the header counts time, tokens and cost. Hover a span for what it did, or click it to trace its handoff path.
- [Context window](https://uiarc.dev/components/context-window/markdown): An AI context window as a grid of 200 cells: the system prompt, tools, files, summary and messages fill it in order, a threshold row marks where compaction starts, and sending a message, attaching a file or compacting shows exactly how much still fits.
- [Reasoning block](https://uiarc.dev/components/reasoning-block/markdown): The collapsible thinking block of an AI reply. While the model thinks, a shimmering label counts the seconds and the latest reasoning streams underneath. When it finishes, it folds to "Thought for 7s" and opens to show the full reasoning as calm steps with headings.
- [Source cards](https://uiarc.dev/components/source-cards/markdown): A row of cited sources under an AI answer where cards stream in with real site marks while the model searches, the overflow collapses into a stack of favicons, hovering lifts a preview with the passage, and an inline [n] citation highlights its card.
- [Model card](https://uiarc.dev/components/model-card/markdown): A model details card where switching models rolls every price, limit and score in place, a token slider estimates monthly cost live, and benchmark bars show each model's rank on hover. Compare crossfades to a side-by-side table against any rival with the better values marked, and the card never changes size.
- [AI workflow](https://uiarc.dev/components/ai-workflow/markdown): A Linear-style AI workflow card where a Gmail trigger, a Claude step, a branch and Slack and Linear actions sit on one hairline rail, and a test run glides down it, opening each step's output inline. Steps are added from a compact command menu with real app marks.
- [Code suggestion](https://uiarc.dev/components/code-suggestion/markdown): An AI code edit suggestion where the model's proposed changes stream into a small editor panel as inline diff hunks, and you accept or reject each one, or all at once with Cmd+Enter. Accepted hunks fold into the file with a smooth height change.
- [Ghost text](https://uiarc.dev/components/ghost-text/markdown): An inline AI autocomplete where muted ghost text continues your sentence exactly at the caret and Tab turns it solid in place. Cmd+Right takes it one word at a time, Escape fades it away, and a calm chip shows the model behind it.
- [Image generation](https://uiarc.dev/components/image-generation/markdown): An image studio where each image forms on a dot matrix: a soft halftone wave breathes across the grid, the dots take the colours of the coming photo and grow into a coloured halftone, then blur away into the sharp photo. One large canvas with a mono size label, a filmstrip of four variations, a prompt bar with model and ratio, and upscale with a sweeping dot band, vary or download, with real provider marks and a built-in simulation.
- [Reply draft](https://uiarc.dev/components/reply-draft/markdown): An AI email reply drafter where Claude streams a reply under a received Gmail message. Quick replies steer a fresh draft, tone and length rewrite it with a single crossfade, and you can edit the finished draft before you insert it.
- [Agent handoff](https://uiarc.dev/components/agent-handoff/markdown): A support conversation where an AI assistant hands off to a person. When it transfers, a card shows the summary it passes to the team and the typical wait. The person then joins and takes over, and a thin timeline on the left marks each step.
- [PII redaction](https://uiarc.dev/components/pii-redaction/markdown): A guardrail card where personal data is redacted before the prompt reaches the model. Scan marks each name, email, phone number and card with its type and swaps it for a placeholder like [EMAIL_1]. The safe prompt travels to Claude, and the reply comes back with the original values put back for the person.
- [Response feedback](https://uiarc.dev/components/response-feedback/markdown): A feedback control for AI replies where thumbs down opens an inline panel with reason chips and an optional note, thumbs up fills and asks what was good, and a submit shows a short thank-you before folding back into the row.
- [LLM cost calculator](https://uiarc.dev/components/llm-cost-calculator/markdown): A pricing calculator for LLM workloads. Set tokens per request, requests per day and prompt caching, and eight current models re-rank by monthly cost. Bars glide and prices roll as you drag.
- [Provider keys](https://uiarc.dev/components/provider-keys/markdown): A settings card for bring-your-own-key AI products. Each provider row shows its real mark, the masked key, a status and when the key was last used. You can reveal a key for five seconds, copy, rotate or remove it with undo. Adding or rotating a key opens an inline form that checks the format as you type, then tests the connection before saving.
- [Generation stats](https://uiarc.dev/components/generation-stats/markdown): A live stats strip for a streaming LLM response where time to first token, speed with a sparkline, output tokens and cost count up in tabular numerals beside the model's real mark, then settle and open into a latency and token cost breakdown.
- [AI translate](https://uiarc.dev/components/ai-translate/markdown): A message card where picking a language streams the AI translation in place, sentence by sentence over the dimmed original, with a detected-language chip, a Show original toggle and a status line credited to the model's mark.
- [TL;DR toggle](https://uiarc.dev/components/tldr-toggle/markdown): An article card with a Full, Summary and Key points switch and a length slider. Switching streams an AI summary in place of the article as the card's height springs to fit, and each key point links back to the paragraph it came from, which gets scrolled to and highlighted.
- [Connector setup](https://uiarc.dev/components/connector-setup/markdown): A "Connect your tools" card for an AI assistant. Each app connects inline: it redirects, authorizes and runs a first sync with a progress hairline, then lists the scopes it was granted and offers Disconnect with an inline confirm.
- [Smart form fill](https://uiarc.dev/components/smart-form-fill/markdown): A paste-to-fill form card where AI reads an email signature or messy notes and fills a contact field by field. Each value flashes in with a confidence dot, its source lights up in the pasted text, low-confidence guesses ask for review, and Undo puts the old values back.
- [Enrich column](https://uiarc.dev/components/enrich-column/markdown): An AI enrichment column for a data table, where one prompt runs down every row and each cell shimmers while it works, then settles into a value with its source or a failure you can retry.
- [Ticket router](https://uiarc.dev/components/ticket-router/markdown): A support ticket router where messages from Gmail, Intercom, Slack and Zendesk come in one at a time. An AI classifier labels each one with intent, sentiment and confidence, and the ticket moves into a team lane with an assignee. Low confidence tickets wait in a review lane, and one click there routes them to the suggested team.
- [Ask your data](https://uiarc.dev/components/ask-your-data/markdown): A natural language to chart card: you ask a question, PostgreSQL streams into a collapsible, syntax highlighted panel, the query runs with a rolling row count, and the answer builds as stacked bars, lines or a table, with a one line insight streamed in underneath.
- [Agent cursor](https://uiarc.dev/components/agent-cursor/markdown): A live document where Claude edits like a collaborator. Its labeled cursor comes out of its avatar, selects a paragraph and streams in a rewrite, adds a heading and fixes a typo, while a teammate's cursor reads along. Changes stay tinted until someone accepts or undoes them from a floating review bar.
- [Provider status](https://uiarc.dev/components/provider-status/markdown): A status card for the AI providers your product depends on. Each row shows the provider's real mark, its health as an icon and label, p50 latency and a 30-day uptime bar with a tooltip for each day. An incident row expands into its timeline of updates, and the card checks again on a visible countdown.
- [Training run](https://uiarc.dev/components/training-run/markdown): A fine-tuning job card where a live train and validation loss curve draws across a fixed step axis that doubles as the epoch progress bar. It shows the learning rate, elapsed time, ETA and the latest evals and checkpoints, has Pause and Cancel while it runs, and ends in results with a Deploy button.
- [AI command](https://uiarc.dev/components/ai-command/markdown): A Cmd+K command palette with an AI mode. Search pages and actions, or press Tab to ask a question: the answer streams inside the palette with numbered sources, and the next steps it suggests, like filing a Linear issue or opening a Notion doc, run straight from the list.
- [Starter prompts](https://uiarc.dev/components/starter-prompts/markdown): A greeting and a grid of starter cards for the empty state of an AI app. The cards are grouped into Write, Code, Analyze and Plan tabs, and a shuffle swaps them with a short staggered crossfade. Picking a card fills the composer, and cards that use a connected app show its mark (Gmail, GitHub, Notion, Linear, Google Calendar).
- [AI mascot](https://uiarc.dev/components/ai-mascot/markdown): A small assistant character, a soft pebble with pill eyes and a companion dot, that shows what the AI is doing. It breathes and glances when idle, leans in to listen, looks up while the dot orbits its head, reads along the line it writes, squints with a sparkle when done and shakes once with worried brows on an error.
- [Image reveal](https://uiarc.dev/components/image-reveal/markdown): An image generation canvas where a soft, blurred preview made from the image's own colors sharpens top to bottom behind a soft-edged band. It works the way ChatGPT, Midjourney and Gemini show images forming, with fine film grain, a translucent progress pill and calm queued and error states.
- [AI spark](https://uiarc.dev/components/ai-spark/markdown): A brand-quality animated spark mark. Four tapered rays and four lighter diagonals breathe at rest, ripple while thinking, pulse like a heartbeat while writing, then gather and settle when done. Every status change blends from the pose the mark is already in.
- [Pixel mascot](https://uiarc.dev/components/pixel-mascot/markdown): A pixel-art robot that shows what an AI assistant is doing. It idles, thinks, types, celebrates and errors in frame-stepped sprite animations, and stays crisp at every integer size from 24px to 192px.
- [Ghost mascot](https://uiarc.dev/components/ghost-mascot/markdown): A floating ghost mascot whose soft sheet ripples at the hem while it hovers. It blinks when idle, turns toward you to listen, fades a little translucent while thinking, draws a tiny pen line while writing, smiles with a sparkle when done and wobbles once on an error.
- [Cube mascot](https://uiarc.dev/components/cube-mascot/markdown): An isometric cube mascot where three shaded faces and a painted-on face show what the assistant is doing. It turns a quarter turn in eased steps while thinking, prints lines onto the floor while writing, settles with a sparkle when done, and shakes once on error.
- [Tone tuner](https://uiarc.dev/components/tone-tuner/markdown): A brand voice card where two sliders (formality and detail) and Friendly, Confident and Empathetic chips rewrite a customer reply. Each changed sentence crossfades in place, new words can be highlighted against the original, and Copy takes the current version.
- [Upgrade prompt](https://uiarc.dev/components/upgrade-prompt/markdown): An upgrade nudge for the moment someone hits a limit. It shows a usage meter at 50 of 50 AI credits, a rolling price with a monthly and yearly toggle, three concrete unlocks with real model marks, and Upgrade or Maybe later. Upgrading leads into a success state with the new limits, and the card never changes size between states.
- [Referral card](https://uiarc.dev/components/referral-card/markdown): A give-and-get referral card where people copy or share their invite link, invite friends by email as chips, and watch invites move from invited to signed up to earned, with the credit total counting up and a milestone reward unlocking.
- [Trial banner](https://uiarc.dev/components/trial-banner/markdown): A trial status banner where a ring counts down the days left, the copy names what the workspace loses, and the upgrade path is one click away. It comes as a slim banner, a sidebar card or a header pill. It shifts to a warning tone in the last days, has expired and upgraded states, and folds into the pill when dismissed or snoozed.
- [Team switcher](https://uiarc.dev/components/team-switcher/markdown): A workspace switcher like Linear, Vercel or Slack. The trigger shows the current workspace's logo and plan. The menu has search, your role in each workspace and a Cmd+1 to 9 shortcut for each, and lets you create or join a workspace inline. A highlight glides between rows, and switching crossfades the trigger through a short loading state.
- [Live visitors](https://uiarc.dev/components/live-visitors/markdown): A realtime visitors card where the live count rolls digit by digit, new arrivals ping in on a dotted world map, the top pages reorder with bars, and signups and upgrades tick in with country flags.
- [Social proof toast](https://uiarc.dev/components/social-proof-toast/markdown): A stack of social proof notifications for landing and pricing pages, where recent trials, upgrades and verified purchases from people and companies arrive every few seconds. The stack pauses and fans out on hover, and visitors can dismiss any toast.
- [Install snippet](https://uiarc.dev/components/install-snippet/markdown): A "get started in 30 seconds" card where framework tabs, three numbered steps and highlighted snippets take a developer from install to first event. Generate key wipes a fresh API key into the placeholder in place.

### Guidance for AI tools

Speech player: A read-aloud player for AI replies. The Read aloud button in the message's action row turns into a compact player with play, a scrubbable progress bar, speed and a voice picker, and a highlight follows the spoken word through the reply, karaoke style. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Meeting summary

> An AI meeting notes card: the header shows the Google Meet or Zoom mark, the attendees and the duration. Summary, Decisions and Action items stream in after a short summarizing pass. Hover any line to see the transcript quote it came from, then check off action items or send them to Linear or Notion.

- Type: Component (special)
- Access: Arc Pro
- Page: https://uiarc.dev/components/meeting-summary
- Markdown: https://uiarc.dev/components/meeting-summary/markdown
- Source file: `registry/components/meeting-summary/meeting-summary.tsx`
- Dependencies: motion, lucide-react, @radix-ui/react-tooltip
- Keywords: special, ai, new, meeting summary, meeting notes, ai notes, action items, call recap, transcript summary, google meet, zoom, linear, notion, decisions, ai meeting assistant

### When to use

- Showing AI notes after a call in a CRM, a recruiting tool, a meeting recorder or a team workspace.
- Turning a transcript into decisions and owned tasks that people can push to their tracker.
- Any summary where readers should be able to check a point against what was actually said.

### When not to use

- Live captions or a running transcript during the call; use text-stream or a transcript view.
- A general task list with no meeting behind it; use checkbox rows in your own list.
- Long documents with many sections; render them as a document page instead of a card.

### Installation

Meeting summary is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/meeting-summary
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { MeetingSummary } from "@/components/arc/meeting-summary/meeting-summary";

export function CallNotes({ meeting, status, createIssue }) {
  return (
    <MeetingSummary
      meeting={meeting}
      status={status}
      onSend={(item, target, signal) => createIssue({ title: item.text, target, signal })}
      onActionItemChange={(item, done) => console.log(item.id, done)}
    />
  );
}
```

### API reference

#### MeetingSummary

AI notes for one call: a meeting header, then Summary, Decisions and Action items that stream in after a short summarizing pass. Each point links to its transcript quote, and each action item can be checked off or sent to Linear or Notion. With no props it plays a sample and simulates every send.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `meeting` | `MeetingSummaryData` | `meetingSummarySample` | Title, platform (google-meet, zoom or other), startsAt, durationMinutes, transcriptWords, attendees, and the summary, decisions and actionItems lists. Points carry an optional quote { speakerId, at (seconds), text }; action items add ownerId, due (ISO date) and done. |
| `status` | `"summarizing" \| "ready" \| "error"` | – | Controlled status. Leave it out and the card plays its own summarizing pass when it scrolls into view. Ready with empty lists shows the no transcript state. |
| `error` | `string` | – | Message shown under the error title when status is error. |
| `autoPlay` | `boolean` | `true` | Uncontrolled only: start summarizing and play the pass. False starts on the finished notes. |
| `streamIn` | `boolean` | `true` | Stream the notes in, a few words at a time, when status moves from summarizing to ready. |
| `model` | `{ name: string; icon?: ReactNode } \| null` | `Claude Sonnet 5.5` | The model credited in the footer. Pass null to hide it. |
| `sendTargets` | `("linear" \| "notion")[]` | `["linear", "notion"]` | Where action items can be sent. Pass [] to hide the send buttons. |
| `onSend` | `(item, target, signal: AbortSignal) => Promise<{ reference?: string; url?: string } \| void>` | – | Creates the issue or page. Resolve with a reference ("PRC-142") and optional url to show a sent chip; reject to show a retry. The signal aborts on unmount and on regenerate. Without it, sending is simulated. |
| `onActionItemChange` | `(item: MeetingActionItem, done: boolean) => void` | – | An action item was checked or unchecked. The card keeps the checked state itself. |
| `onRegenerate` | `() => void` | – | Regenerate in the footer and Try again in the error state. Uncontrolled cards also replay their own pass. |
| `className` | `string` | – | Class on the root article. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Tab | Moves through the attendees, each timestamp, checkbox and send button, then copy and regenerate. |
| Focus on a timestamp | Shows the transcript quote for that line. |
| Enter / Space | On a timestamp, pins or closes its quote. On a checkbox, toggles it. On Linear or Notion, sends the item. |
| Escape | Closes an open quote. |

### Accessibility

- The card is an article named after the meeting, with h2 for the title and h3 for each section.
- Timestamps are buttons with aria-expanded; the open quote is a role="tooltip" referenced by aria-describedby.
- Each checkbox is a native button with role="checkbox" and aria-checked, and each checkbox and send button is labeled with the action item text, so a list of them still reads clearly.
- The 16px checkbox has a 32px hit area, and the keyboard focus ring hugs the square itself.
- A polite live region announces summarizing, the finished summary, checked items and sends, and says "Simulated, nothing was sent" when no onSend is wired.
- Status never relies on color: a failed send shows an alert icon with a retry label, a sent item shows the target mark, its reference and a check.
- The platform name is read before the date, and owners shown by first name on narrow cards keep their full name for screen readers.

### Motion

- Summarizing lasts about one second with a shimmer on the label, then notes stream 3 to 8 words every 34ms; each chunk only fades in.
- The body springs to its new height between loading, notes, error and empty (0.24s, no bounce). Owner, date and send controls reserve their space while text streams, so nothing shifts when they fade in.
- Checking an item grows the accent fill in (160ms) and draws the check on (200ms ease-out), while a 1px strikethrough sweeps left to right across every wrapped line and the text eases to muted. Unchecking reverses it faster. A press scales the square to 0.9, never the row.
- Send buttons crossfade mark to spinner to a sent chip while their slot springs to the new width.
- Quotes fade in over 160ms with a 3px offset after a short hover intent, then switch instantly between lines.
- Reduced motion skips the stream, size springs, check drawing and strikethrough sweep and keeps every end state and announcement. The pass waits until the card is on screen. The sample sends one item to Linear and ticks off another once, unless someone has already used the card.

### Responsive behavior

- Holds from 360px to its 640px max width. Below 460px the attendee stack moves under the date; below 520px owners show their first name so meta stays on one line.
- Quotes open below their line and flip above when the viewport runs out of room.
- Hover quotes need a fine pointer; on touch, tapping a timestamp pins the quote and tapping elsewhere closes it.

### Performance

- Streaming re-renders only the card for about 1.5 seconds, using one interval. Chunk animations are CSS keyframes.
- One ResizeObserver for the body height and one per send slot; all are released on unmount and in-flight sends abort.
- Marks are inline SVG, no network requests besides attendee portraits.

### Notes for AI

- Use for post-meeting notes from a recorder or transcript pipeline. Map your model output to MeetingSummaryData; keep quote.at in seconds from the start of the recording.
- Drive status yourself when the summary comes from a server: summarizing while the request runs, ready when it resolves, error with a message on failure.
- Wire onSend to the Linear issueCreate mutation or a Notion pages.create call and resolve with the issue key or page title; pass the AbortSignal through to fetch.
- Dates are naive local strings printed the same on server and client. Format time zones before passing them in.

### Related

- [Tool call](https://uiarc.dev/components/tool-call/markdown): A tool call row for agent transcripts: the tool's mark and the call in plain words, a live state while it runs, and the input and output a click away, with approval and retry when needed.
- [Agent status](https://uiarc.dev/components/agent-status/markdown): A compact live status pill for a running AI agent: the agent's mark in a live ring, the current activity and an elapsed timer, opening into the steps so far.
- [Checkbox](https://uiarc.dev/components/checkbox/markdown): A binary choice with a precise, legible state.
- [Avatar](https://uiarc.dev/components/avatar/markdown): A compact identity marker for people and accounts.
- [Copy button](https://uiarc.dev/components/copy-button/markdown): Copy a value with immediate confirmation.

### Also in ai

- [Agent plan](https://uiarc.dev/components/agent-plan/markdown): The plan an agent writes before it acts: edit, reorder or add steps while it is a draft, then watch it work through them as a live checklist.
- [Agent timeline](https://uiarc.dev/components/agent-timeline/markdown): A compact timeline of one orchestrated agent run: the orchestrator and its subagents share a time axis, handoffs draw in between rows, and a playhead replays thinking, tool calls and waiting while the header counts time, tokens and cost. Hover a span for what it did, or click it to trace its handoff path.
- [Context window](https://uiarc.dev/components/context-window/markdown): An AI context window as a grid of 200 cells: the system prompt, tools, files, summary and messages fill it in order, a threshold row marks where compaction starts, and sending a message, attaching a file or compacting shows exactly how much still fits.
- [Reasoning block](https://uiarc.dev/components/reasoning-block/markdown): The collapsible thinking block of an AI reply. While the model thinks, a shimmering label counts the seconds and the latest reasoning streams underneath. When it finishes, it folds to "Thought for 7s" and opens to show the full reasoning as calm steps with headings.
- [Source cards](https://uiarc.dev/components/source-cards/markdown): A row of cited sources under an AI answer where cards stream in with real site marks while the model searches, the overflow collapses into a stack of favicons, hovering lifts a preview with the passage, and an inline [n] citation highlights its card.
- [Model card](https://uiarc.dev/components/model-card/markdown): A model details card where switching models rolls every price, limit and score in place, a token slider estimates monthly cost live, and benchmark bars show each model's rank on hover. Compare crossfades to a side-by-side table against any rival with the better values marked, and the card never changes size.
- [AI workflow](https://uiarc.dev/components/ai-workflow/markdown): A Linear-style AI workflow card where a Gmail trigger, a Claude step, a branch and Slack and Linear actions sit on one hairline rail, and a test run glides down it, opening each step's output inline. Steps are added from a compact command menu with real app marks.
- [Code suggestion](https://uiarc.dev/components/code-suggestion/markdown): An AI code edit suggestion where the model's proposed changes stream into a small editor panel as inline diff hunks, and you accept or reject each one, or all at once with Cmd+Enter. Accepted hunks fold into the file with a smooth height change.
- [Ghost text](https://uiarc.dev/components/ghost-text/markdown): An inline AI autocomplete where muted ghost text continues your sentence exactly at the caret and Tab turns it solid in place. Cmd+Right takes it one word at a time, Escape fades it away, and a calm chip shows the model behind it.
- [Image generation](https://uiarc.dev/components/image-generation/markdown): An image studio where each image forms on a dot matrix: a soft halftone wave breathes across the grid, the dots take the colours of the coming photo and grow into a coloured halftone, then blur away into the sharp photo. One large canvas with a mono size label, a filmstrip of four variations, a prompt bar with model and ratio, and upscale with a sweeping dot band, vary or download, with real provider marks and a built-in simulation.
- [Dictation button](https://uiarc.dev/components/dictation-button/markdown): A chat composer with voice input, where the mic springs into a recording pill with a smooth live waveform, a timer, and cancel and insert buttons. Words stream into the field as you speak, muted until the recognizer settles them.
- [Speech player](https://uiarc.dev/components/speech-player/markdown): A read-aloud player for AI replies. The Read aloud button in the message's action row turns into a compact player with play, a scrubbable progress bar, speed and a voice picker, and a highlight follows the spoken word through the reply, karaoke style.
- [Reply draft](https://uiarc.dev/components/reply-draft/markdown): An AI email reply drafter where Claude streams a reply under a received Gmail message. Quick replies steer a fresh draft, tone and length rewrite it with a single crossfade, and you can edit the finished draft before you insert it.
- [Agent handoff](https://uiarc.dev/components/agent-handoff/markdown): A support conversation where an AI assistant hands off to a person. When it transfers, a card shows the summary it passes to the team and the typical wait. The person then joins and takes over, and a thin timeline on the left marks each step.
- [PII redaction](https://uiarc.dev/components/pii-redaction/markdown): A guardrail card where personal data is redacted before the prompt reaches the model. Scan marks each name, email, phone number and card with its type and swaps it for a placeholder like [EMAIL_1]. The safe prompt travels to Claude, and the reply comes back with the original values put back for the person.
- [Response feedback](https://uiarc.dev/components/response-feedback/markdown): A feedback control for AI replies where thumbs down opens an inline panel with reason chips and an optional note, thumbs up fills and asks what was good, and a submit shows a short thank-you before folding back into the row.
- [LLM cost calculator](https://uiarc.dev/components/llm-cost-calculator/markdown): A pricing calculator for LLM workloads. Set tokens per request, requests per day and prompt caching, and eight current models re-rank by monthly cost. Bars glide and prices roll as you drag.
- [Provider keys](https://uiarc.dev/components/provider-keys/markdown): A settings card for bring-your-own-key AI products. Each provider row shows its real mark, the masked key, a status and when the key was last used. You can reveal a key for five seconds, copy, rotate or remove it with undo. Adding or rotating a key opens an inline form that checks the format as you type, then tests the connection before saving.
- [Generation stats](https://uiarc.dev/components/generation-stats/markdown): A live stats strip for a streaming LLM response where time to first token, speed with a sparkline, output tokens and cost count up in tabular numerals beside the model's real mark, then settle and open into a latency and token cost breakdown.
- [AI translate](https://uiarc.dev/components/ai-translate/markdown): A message card where picking a language streams the AI translation in place, sentence by sentence over the dimmed original, with a detected-language chip, a Show original toggle and a status line credited to the model's mark.
- [TL;DR toggle](https://uiarc.dev/components/tldr-toggle/markdown): An article card with a Full, Summary and Key points switch and a length slider. Switching streams an AI summary in place of the article as the card's height springs to fit, and each key point links back to the paragraph it came from, which gets scrolled to and highlighted.
- [Connector setup](https://uiarc.dev/components/connector-setup/markdown): A "Connect your tools" card for an AI assistant. Each app connects inline: it redirects, authorizes and runs a first sync with a progress hairline, then lists the scopes it was granted and offers Disconnect with an inline confirm.
- [Smart form fill](https://uiarc.dev/components/smart-form-fill/markdown): A paste-to-fill form card where AI reads an email signature or messy notes and fills a contact field by field. Each value flashes in with a confidence dot, its source lights up in the pasted text, low-confidence guesses ask for review, and Undo puts the old values back.
- [Enrich column](https://uiarc.dev/components/enrich-column/markdown): An AI enrichment column for a data table, where one prompt runs down every row and each cell shimmers while it works, then settles into a value with its source or a failure you can retry.
- [Ticket router](https://uiarc.dev/components/ticket-router/markdown): A support ticket router where messages from Gmail, Intercom, Slack and Zendesk come in one at a time. An AI classifier labels each one with intent, sentiment and confidence, and the ticket moves into a team lane with an assignee. Low confidence tickets wait in a review lane, and one click there routes them to the suggested team.
- [Ask your data](https://uiarc.dev/components/ask-your-data/markdown): A natural language to chart card: you ask a question, PostgreSQL streams into a collapsible, syntax highlighted panel, the query runs with a rolling row count, and the answer builds as stacked bars, lines or a table, with a one line insight streamed in underneath.
- [Agent cursor](https://uiarc.dev/components/agent-cursor/markdown): A live document where Claude edits like a collaborator. Its labeled cursor comes out of its avatar, selects a paragraph and streams in a rewrite, adds a heading and fixes a typo, while a teammate's cursor reads along. Changes stay tinted until someone accepts or undoes them from a floating review bar.
- [Provider status](https://uiarc.dev/components/provider-status/markdown): A status card for the AI providers your product depends on. Each row shows the provider's real mark, its health as an icon and label, p50 latency and a 30-day uptime bar with a tooltip for each day. An incident row expands into its timeline of updates, and the card checks again on a visible countdown.
- [Training run](https://uiarc.dev/components/training-run/markdown): A fine-tuning job card where a live train and validation loss curve draws across a fixed step axis that doubles as the epoch progress bar. It shows the learning rate, elapsed time, ETA and the latest evals and checkpoints, has Pause and Cancel while it runs, and ends in results with a Deploy button.
- [AI command](https://uiarc.dev/components/ai-command/markdown): A Cmd+K command palette with an AI mode. Search pages and actions, or press Tab to ask a question: the answer streams inside the palette with numbered sources, and the next steps it suggests, like filing a Linear issue or opening a Notion doc, run straight from the list.
- [Starter prompts](https://uiarc.dev/components/starter-prompts/markdown): A greeting and a grid of starter cards for the empty state of an AI app. The cards are grouped into Write, Code, Analyze and Plan tabs, and a shuffle swaps them with a short staggered crossfade. Picking a card fills the composer, and cards that use a connected app show its mark (Gmail, GitHub, Notion, Linear, Google Calendar).
- [AI mascot](https://uiarc.dev/components/ai-mascot/markdown): A small assistant character, a soft pebble with pill eyes and a companion dot, that shows what the AI is doing. It breathes and glances when idle, leans in to listen, looks up while the dot orbits its head, reads along the line it writes, squints with a sparkle when done and shakes once with worried brows on an error.
- [Image reveal](https://uiarc.dev/components/image-reveal/markdown): An image generation canvas where a soft, blurred preview made from the image's own colors sharpens top to bottom behind a soft-edged band. It works the way ChatGPT, Midjourney and Gemini show images forming, with fine film grain, a translucent progress pill and calm queued and error states.
- [AI spark](https://uiarc.dev/components/ai-spark/markdown): A brand-quality animated spark mark. Four tapered rays and four lighter diagonals breathe at rest, ripple while thinking, pulse like a heartbeat while writing, then gather and settle when done. Every status change blends from the pose the mark is already in.
- [Pixel mascot](https://uiarc.dev/components/pixel-mascot/markdown): A pixel-art robot that shows what an AI assistant is doing. It idles, thinks, types, celebrates and errors in frame-stepped sprite animations, and stays crisp at every integer size from 24px to 192px.
- [Ghost mascot](https://uiarc.dev/components/ghost-mascot/markdown): A floating ghost mascot whose soft sheet ripples at the hem while it hovers. It blinks when idle, turns toward you to listen, fades a little translucent while thinking, draws a tiny pen line while writing, smiles with a sparkle when done and wobbles once on an error.
- [Cube mascot](https://uiarc.dev/components/cube-mascot/markdown): An isometric cube mascot where three shaded faces and a painted-on face show what the assistant is doing. It turns a quarter turn in eased steps while thinking, prints lines onto the floor while writing, settles with a sparkle when done, and shakes once on error.
- [Tone tuner](https://uiarc.dev/components/tone-tuner/markdown): A brand voice card where two sliders (formality and detail) and Friendly, Confident and Empathetic chips rewrite a customer reply. Each changed sentence crossfades in place, new words can be highlighted against the original, and Copy takes the current version.
- [Upgrade prompt](https://uiarc.dev/components/upgrade-prompt/markdown): An upgrade nudge for the moment someone hits a limit. It shows a usage meter at 50 of 50 AI credits, a rolling price with a monthly and yearly toggle, three concrete unlocks with real model marks, and Upgrade or Maybe later. Upgrading leads into a success state with the new limits, and the card never changes size between states.
- [Referral card](https://uiarc.dev/components/referral-card/markdown): A give-and-get referral card where people copy or share their invite link, invite friends by email as chips, and watch invites move from invited to signed up to earned, with the credit total counting up and a milestone reward unlocking.
- [Trial banner](https://uiarc.dev/components/trial-banner/markdown): A trial status banner where a ring counts down the days left, the copy names what the workspace loses, and the upgrade path is one click away. It comes as a slim banner, a sidebar card or a header pill. It shifts to a warning tone in the last days, has expired and upgraded states, and folds into the pill when dismissed or snoozed.
- [Team switcher](https://uiarc.dev/components/team-switcher/markdown): A workspace switcher like Linear, Vercel or Slack. The trigger shows the current workspace's logo and plan. The menu has search, your role in each workspace and a Cmd+1 to 9 shortcut for each, and lets you create or join a workspace inline. A highlight glides between rows, and switching crossfades the trigger through a short loading state.
- [Live visitors](https://uiarc.dev/components/live-visitors/markdown): A realtime visitors card where the live count rolls digit by digit, new arrivals ping in on a dotted world map, the top pages reorder with bars, and signups and upgrades tick in with country flags.
- [Social proof toast](https://uiarc.dev/components/social-proof-toast/markdown): A stack of social proof notifications for landing and pricing pages, where recent trials, upgrades and verified purchases from people and companies arrive every few seconds. The stack pauses and fans out on hover, and visitors can dismiss any toast.
- [Install snippet](https://uiarc.dev/components/install-snippet/markdown): A "get started in 30 seconds" card where framework tabs, three numbered steps and highlighted snippets take a developer from install to first event. Generate key wipes a fresh API key into the placeholder in place.

### Guidance for AI tools

Meeting summary: An AI meeting notes card: the header shows the Google Meet or Zoom mark, the attendees and the duration. Summary, Decisions and Action items stream in after a short summarizing pass. Hover any line to see the transcript quote it came from, then check off action items or send them to Linear or Notion. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Reply draft

> An AI email reply drafter where Claude streams a reply under a received Gmail message. Quick replies steer a fresh draft, tone and length rewrite it with a single crossfade, and you can edit the finished draft before you insert it.

- Type: Component (special)
- Access: Arc Pro
- Page: https://uiarc.dev/components/reply-draft
- Markdown: https://uiarc.dev/components/reply-draft/markdown
- Source file: `registry/components/reply-draft/reply-draft.tsx`
- Dependencies: motion, lucide-react
- Keywords: special, ai, new, ai reply, email reply, smart reply, draft reply, help me write, gmail ai, tone, rewrite, quick replies, streaming text, claude, inbox ai, support reply

### When to use

- Drafting a reply to an email, ticket or message with an AI model, where the reader reviews and edits before sending.
- Offering quick reply intents plus tone and length controls for generated text.
- Showing an AI writing feature on a landing page with a realistic, self-playing example.

### When not to use

- Free-form chat with a model: use a chat or composer component instead.
- Inline autocomplete while typing: use ghost-text.
- Sending the email itself: this component inserts a draft; your composer owns sending.

### Installation

Reply draft is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/reply-draft
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { ReplyDraft } from "@/components/arc/reply-draft/reply-draft";

export function Inbox({ email }) {
  return (
    <ReplyDraft
      message={email}
      suggestions={[{ id: "yes", label: "Sounds good" }, { id: "later", label: "Next week" }]}
      model={{ name: "Claude Sonnet 5.5" }}
      generate={async function* ({ message, tone, length, suggestion, signal }) {
        const res = await fetch("/api/reply", { method: "POST", body: JSON.stringify({ id: email.id, tone, length, hint: suggestion?.label }), signal });
        const reader = res.body!.pipeThrough(new TextDecoderStream()).getReader();
        for (;;) { const { value, done } = await reader.read(); if (done) return; yield value; }
      }}
      onInsert={draft => composer.insert(draft)}
    />
  );
}
```

### API reference

#### ReplyDraft

A received email with an AI reply under it: quick reply chips, a fast streaming draft, tone and length rewrites, Regenerate and Insert. With no props it plays a simulated tour.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `message` | `ReplyDraftMessage` | `replyDraftSampleMessage` | The received email: from { name, email, avatar? }, to?, subject, body (blank lines split paragraphs) and receivedAt. |
| `suggestions` | `ReplyDraftSuggestion[]` | `3 sample quick replies` | Quick replies ({ id, label }) shown as chips above the draft. Selecting one streams a fresh draft steered by it. Pass [] to hide the row. |
| `defaultSuggestion` | `string` | – | Id of the quick reply that steers the first draft. Defaults to the first suggestion. |
| `onSuggestionSelect` | `(suggestion: ReplyDraftSuggestion) => void` | – | Called when a quick reply chip is chosen. |
| `model` | `ReplyDraftModel` | `{ name: "Claude Sonnet 5.5" }` | Model name and an optional 16px mark shown on the draft. The Claude mark is the default. |
| `tone` | `"friendly" \| "concise" \| "formal"` | – | Controlled tone. Changing it rewrites a finished draft with a crossfade, or restarts one that is still streaming. |
| `defaultTone` | `"friendly" \| "concise" \| "formal"` | `"friendly"` | Initial tone when uncontrolled. |
| `onToneChange` | `(tone: ReplyDraftTone) => void` | – | Called when the reader picks a tone. |
| `length` | `"short" \| "medium" \| "long"` | – | Controlled length. Works like tone. |
| `defaultLength` | `"short" \| "medium" \| "long"` | `"medium"` | Initial length when uncontrolled. |
| `onLengthChange` | `(length: ReplyDraftLength) => void` | – | Called when the reader picks a length. |
| `generate` | `(request: ReplyDraftRequest) => Promise<string> \| AsyncIterable<string>` | `simulateReplyDraft` | Writes the draft. The request carries message, tone, length, suggestion, mode ("draft" or "rewrite"), previous (the current text with edits) and an AbortSignal. Return the whole text, which is streamed locally in chunks, or yield chunks from your model stream. Throw to show the error state. |
| `onInsert` | `(draft: string, meta: { tone, length, suggestion? }) => void \| Promise<void>` | – | Receives the final draft, including the reader's edits. While a returned promise is pending, Insert shows a spinner. Without it, Insert is simulated and announces that nothing was sent. |
| `onDraft` | `(draft: string, meta: { tone, length, suggestion? }) => void` | – | Called each time a draft or rewrite finishes. |
| `autoStart` | `boolean` | `true` | Start the first draft when the card scrolls into view. When false, the draft box shows an empty state with a Draft reply button. |
| `autoPlay` | `boolean` | `true without generate` | Tours tones, length, a second quick reply and Insert on a loop. Stops for good on the first pointer or key press inside the card and pauses off screen. |
| `className` | `string` | – | Class on the outer wrapper (max width 600px, fills narrower containers). |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Tab | Moves through quick replies, the draft text, tone, length, Regenerate and Insert. |
| Arrow keys | Inside Tone or Length, move the selection and rewrite the draft. Home and End jump to the first and last option. |
| Enter / Space | Activates a quick reply or button. |
| Cmd / Ctrl + Enter | Inserts the finished draft from anywhere inside the card. |

### Accessibility

- The card is an article labelled with the sender; the reply area is a labelled section.
- Quick replies are toggle buttons with aria-pressed; tone and length are radio groups with roving tabindex.
- The finished draft is a plain-text editable textbox (contenteditable plaintext-only), so readers can fix a word before Insert. Edits are what onInsert receives.
- A polite live region announces drafting, rewriting, ready, inserted and errors. Simulated actions say nothing was sent.
- The body is aria-busy while drafting. Status uses an icon plus a short label, never color alone.

### Motion

- Drafts stream in chunks of 3 to 8 words every 34ms; each chunk only fades in over 140ms.
- Tone and length rewrites crossfade once: the old draft dims during the short rewrite, fades out in 100ms and the new one fades in over 160ms with a 2px rise.
- The draft box springs to its measured height with no bounce; during a regenerate its height is held until the new draft finishes, so the card never jumps.
- The selected tone and length pills glide with a bounce-free spring. Status labels crossfade; working labels use a calm shimmer.
- Reduced motion: drafts appear whole, crossfades and the height spring are instant, chunk fades and the press scale are dropped.

### Responsive behavior

- Fills its container up to 600px. Below 480px the card padding drops to 16px and the email body loses its avatar indent.
- Quick replies and the tone and length groups wrap; under 460px the divider between the groups hides and Length moves to its own row.
- Touch targets grow to 32px for options and 36px for quick replies on coarse pointers. Long emails and names truncate or wrap without horizontal scroll.

### Performance

- One state update per streamed chunk; chunks are plain spans with a CSS fade, swapped for a single text node when the draft finishes.
- The autoplay loop and auto start use an IntersectionObserver and stay idle off screen.
- No network calls by default; the simulation lives in reply-draft-data.ts.

### Notes for AI

- Use for AI-assisted replies in inboxes, support desks, CRMs and chat tools. Pass the real message and wire generate to your model with the AbortSignal; every new action aborts the previous request.
- generate can return a Promise<string> (it is chunk-streamed locally) or an async iterable of text deltas from a real stream. mode "rewrite" means restyle the previous text for the new tone or length.
- Map suggestions to intents your prompt understands (ids are stable, labels are what readers see). Keep labels to two or three words.
- Leave autoPlay off in products; it is for marketing and docs demos.

### Related

- [AI composer](https://uiarc.dev/components/blocks/ai-composer/markdown): The prompt box at the bottom of an AI app: files upload in place, / opens commands, @ inserts mentions, a model and effort menu sits in the toolbar, and the send button turns into a stop control ringed by the reply's progress.
- [Ghost text](https://uiarc.dev/components/ghost-text/markdown): An inline AI autocomplete where muted ghost text continues your sentence exactly at the caret and Tab turns it solid in place. Cmd+Right takes it one word at a time, Escape fades it away, and a calm chip shows the model behind it.
- [Tool call](https://uiarc.dev/components/tool-call/markdown): A tool call row for agent transcripts: the tool's mark and the call in plain words, a live state while it runs, and the input and output a click away, with approval and retry when needed.
- [Agent status](https://uiarc.dev/components/agent-status/markdown): A compact live status pill for a running AI agent: the agent's mark in a live ring, the current activity and an elapsed timer, opening into the steps so far.
- [Text shimmer](https://uiarc.dev/components/text-shimmer/markdown): Show ongoing work with a calm light across the words.
- [Segmented control](https://uiarc.dev/components/segmented-control/markdown): Switch between a small set of related views.

### Also in ai

- [Agent plan](https://uiarc.dev/components/agent-plan/markdown): The plan an agent writes before it acts: edit, reorder or add steps while it is a draft, then watch it work through them as a live checklist.
- [Agent timeline](https://uiarc.dev/components/agent-timeline/markdown): A compact timeline of one orchestrated agent run: the orchestrator and its subagents share a time axis, handoffs draw in between rows, and a playhead replays thinking, tool calls and waiting while the header counts time, tokens and cost. Hover a span for what it did, or click it to trace its handoff path.
- [Context window](https://uiarc.dev/components/context-window/markdown): An AI context window as a grid of 200 cells: the system prompt, tools, files, summary and messages fill it in order, a threshold row marks where compaction starts, and sending a message, attaching a file or compacting shows exactly how much still fits.
- [Reasoning block](https://uiarc.dev/components/reasoning-block/markdown): The collapsible thinking block of an AI reply. While the model thinks, a shimmering label counts the seconds and the latest reasoning streams underneath. When it finishes, it folds to "Thought for 7s" and opens to show the full reasoning as calm steps with headings.
- [Source cards](https://uiarc.dev/components/source-cards/markdown): A row of cited sources under an AI answer where cards stream in with real site marks while the model searches, the overflow collapses into a stack of favicons, hovering lifts a preview with the passage, and an inline [n] citation highlights its card.
- [Model card](https://uiarc.dev/components/model-card/markdown): A model details card where switching models rolls every price, limit and score in place, a token slider estimates monthly cost live, and benchmark bars show each model's rank on hover. Compare crossfades to a side-by-side table against any rival with the better values marked, and the card never changes size.
- [AI workflow](https://uiarc.dev/components/ai-workflow/markdown): A Linear-style AI workflow card where a Gmail trigger, a Claude step, a branch and Slack and Linear actions sit on one hairline rail, and a test run glides down it, opening each step's output inline. Steps are added from a compact command menu with real app marks.
- [Code suggestion](https://uiarc.dev/components/code-suggestion/markdown): An AI code edit suggestion where the model's proposed changes stream into a small editor panel as inline diff hunks, and you accept or reject each one, or all at once with Cmd+Enter. Accepted hunks fold into the file with a smooth height change.
- [Image generation](https://uiarc.dev/components/image-generation/markdown): An image studio where each image forms on a dot matrix: a soft halftone wave breathes across the grid, the dots take the colours of the coming photo and grow into a coloured halftone, then blur away into the sharp photo. One large canvas with a mono size label, a filmstrip of four variations, a prompt bar with model and ratio, and upscale with a sweeping dot band, vary or download, with real provider marks and a built-in simulation.
- [Dictation button](https://uiarc.dev/components/dictation-button/markdown): A chat composer with voice input, where the mic springs into a recording pill with a smooth live waveform, a timer, and cancel and insert buttons. Words stream into the field as you speak, muted until the recognizer settles them.
- [Speech player](https://uiarc.dev/components/speech-player/markdown): A read-aloud player for AI replies. The Read aloud button in the message's action row turns into a compact player with play, a scrubbable progress bar, speed and a voice picker, and a highlight follows the spoken word through the reply, karaoke style.
- [Meeting summary](https://uiarc.dev/components/meeting-summary/markdown): An AI meeting notes card: the header shows the Google Meet or Zoom mark, the attendees and the duration. Summary, Decisions and Action items stream in after a short summarizing pass. Hover any line to see the transcript quote it came from, then check off action items or send them to Linear or Notion.
- [Agent handoff](https://uiarc.dev/components/agent-handoff/markdown): A support conversation where an AI assistant hands off to a person. When it transfers, a card shows the summary it passes to the team and the typical wait. The person then joins and takes over, and a thin timeline on the left marks each step.
- [PII redaction](https://uiarc.dev/components/pii-redaction/markdown): A guardrail card where personal data is redacted before the prompt reaches the model. Scan marks each name, email, phone number and card with its type and swaps it for a placeholder like [EMAIL_1]. The safe prompt travels to Claude, and the reply comes back with the original values put back for the person.
- [Response feedback](https://uiarc.dev/components/response-feedback/markdown): A feedback control for AI replies where thumbs down opens an inline panel with reason chips and an optional note, thumbs up fills and asks what was good, and a submit shows a short thank-you before folding back into the row.
- [LLM cost calculator](https://uiarc.dev/components/llm-cost-calculator/markdown): A pricing calculator for LLM workloads. Set tokens per request, requests per day and prompt caching, and eight current models re-rank by monthly cost. Bars glide and prices roll as you drag.
- [Provider keys](https://uiarc.dev/components/provider-keys/markdown): A settings card for bring-your-own-key AI products. Each provider row shows its real mark, the masked key, a status and when the key was last used. You can reveal a key for five seconds, copy, rotate or remove it with undo. Adding or rotating a key opens an inline form that checks the format as you type, then tests the connection before saving.
- [Generation stats](https://uiarc.dev/components/generation-stats/markdown): A live stats strip for a streaming LLM response where time to first token, speed with a sparkline, output tokens and cost count up in tabular numerals beside the model's real mark, then settle and open into a latency and token cost breakdown.
- [AI translate](https://uiarc.dev/components/ai-translate/markdown): A message card where picking a language streams the AI translation in place, sentence by sentence over the dimmed original, with a detected-language chip, a Show original toggle and a status line credited to the model's mark.
- [TL;DR toggle](https://uiarc.dev/components/tldr-toggle/markdown): An article card with a Full, Summary and Key points switch and a length slider. Switching streams an AI summary in place of the article as the card's height springs to fit, and each key point links back to the paragraph it came from, which gets scrolled to and highlighted.
- [Connector setup](https://uiarc.dev/components/connector-setup/markdown): A "Connect your tools" card for an AI assistant. Each app connects inline: it redirects, authorizes and runs a first sync with a progress hairline, then lists the scopes it was granted and offers Disconnect with an inline confirm.
- [Smart form fill](https://uiarc.dev/components/smart-form-fill/markdown): A paste-to-fill form card where AI reads an email signature or messy notes and fills a contact field by field. Each value flashes in with a confidence dot, its source lights up in the pasted text, low-confidence guesses ask for review, and Undo puts the old values back.
- [Enrich column](https://uiarc.dev/components/enrich-column/markdown): An AI enrichment column for a data table, where one prompt runs down every row and each cell shimmers while it works, then settles into a value with its source or a failure you can retry.
- [Ticket router](https://uiarc.dev/components/ticket-router/markdown): A support ticket router where messages from Gmail, Intercom, Slack and Zendesk come in one at a time. An AI classifier labels each one with intent, sentiment and confidence, and the ticket moves into a team lane with an assignee. Low confidence tickets wait in a review lane, and one click there routes them to the suggested team.
- [Ask your data](https://uiarc.dev/components/ask-your-data/markdown): A natural language to chart card: you ask a question, PostgreSQL streams into a collapsible, syntax highlighted panel, the query runs with a rolling row count, and the answer builds as stacked bars, lines or a table, with a one line insight streamed in underneath.
- [Agent cursor](https://uiarc.dev/components/agent-cursor/markdown): A live document where Claude edits like a collaborator. Its labeled cursor comes out of its avatar, selects a paragraph and streams in a rewrite, adds a heading and fixes a typo, while a teammate's cursor reads along. Changes stay tinted until someone accepts or undoes them from a floating review bar.
- [Provider status](https://uiarc.dev/components/provider-status/markdown): A status card for the AI providers your product depends on. Each row shows the provider's real mark, its health as an icon and label, p50 latency and a 30-day uptime bar with a tooltip for each day. An incident row expands into its timeline of updates, and the card checks again on a visible countdown.
- [Training run](https://uiarc.dev/components/training-run/markdown): A fine-tuning job card where a live train and validation loss curve draws across a fixed step axis that doubles as the epoch progress bar. It shows the learning rate, elapsed time, ETA and the latest evals and checkpoints, has Pause and Cancel while it runs, and ends in results with a Deploy button.
- [AI command](https://uiarc.dev/components/ai-command/markdown): A Cmd+K command palette with an AI mode. Search pages and actions, or press Tab to ask a question: the answer streams inside the palette with numbered sources, and the next steps it suggests, like filing a Linear issue or opening a Notion doc, run straight from the list.
- [Starter prompts](https://uiarc.dev/components/starter-prompts/markdown): A greeting and a grid of starter cards for the empty state of an AI app. The cards are grouped into Write, Code, Analyze and Plan tabs, and a shuffle swaps them with a short staggered crossfade. Picking a card fills the composer, and cards that use a connected app show its mark (Gmail, GitHub, Notion, Linear, Google Calendar).
- [AI mascot](https://uiarc.dev/components/ai-mascot/markdown): A small assistant character, a soft pebble with pill eyes and a companion dot, that shows what the AI is doing. It breathes and glances when idle, leans in to listen, looks up while the dot orbits its head, reads along the line it writes, squints with a sparkle when done and shakes once with worried brows on an error.
- [Image reveal](https://uiarc.dev/components/image-reveal/markdown): An image generation canvas where a soft, blurred preview made from the image's own colors sharpens top to bottom behind a soft-edged band. It works the way ChatGPT, Midjourney and Gemini show images forming, with fine film grain, a translucent progress pill and calm queued and error states.
- [AI spark](https://uiarc.dev/components/ai-spark/markdown): A brand-quality animated spark mark. Four tapered rays and four lighter diagonals breathe at rest, ripple while thinking, pulse like a heartbeat while writing, then gather and settle when done. Every status change blends from the pose the mark is already in.
- [Pixel mascot](https://uiarc.dev/components/pixel-mascot/markdown): A pixel-art robot that shows what an AI assistant is doing. It idles, thinks, types, celebrates and errors in frame-stepped sprite animations, and stays crisp at every integer size from 24px to 192px.
- [Ghost mascot](https://uiarc.dev/components/ghost-mascot/markdown): A floating ghost mascot whose soft sheet ripples at the hem while it hovers. It blinks when idle, turns toward you to listen, fades a little translucent while thinking, draws a tiny pen line while writing, smiles with a sparkle when done and wobbles once on an error.
- [Cube mascot](https://uiarc.dev/components/cube-mascot/markdown): An isometric cube mascot where three shaded faces and a painted-on face show what the assistant is doing. It turns a quarter turn in eased steps while thinking, prints lines onto the floor while writing, settles with a sparkle when done, and shakes once on error.
- [Tone tuner](https://uiarc.dev/components/tone-tuner/markdown): A brand voice card where two sliders (formality and detail) and Friendly, Confident and Empathetic chips rewrite a customer reply. Each changed sentence crossfades in place, new words can be highlighted against the original, and Copy takes the current version.
- [Upgrade prompt](https://uiarc.dev/components/upgrade-prompt/markdown): An upgrade nudge for the moment someone hits a limit. It shows a usage meter at 50 of 50 AI credits, a rolling price with a monthly and yearly toggle, three concrete unlocks with real model marks, and Upgrade or Maybe later. Upgrading leads into a success state with the new limits, and the card never changes size between states.
- [Referral card](https://uiarc.dev/components/referral-card/markdown): A give-and-get referral card where people copy or share their invite link, invite friends by email as chips, and watch invites move from invited to signed up to earned, with the credit total counting up and a milestone reward unlocking.
- [Trial banner](https://uiarc.dev/components/trial-banner/markdown): A trial status banner where a ring counts down the days left, the copy names what the workspace loses, and the upgrade path is one click away. It comes as a slim banner, a sidebar card or a header pill. It shifts to a warning tone in the last days, has expired and upgraded states, and folds into the pill when dismissed or snoozed.
- [Team switcher](https://uiarc.dev/components/team-switcher/markdown): A workspace switcher like Linear, Vercel or Slack. The trigger shows the current workspace's logo and plan. The menu has search, your role in each workspace and a Cmd+1 to 9 shortcut for each, and lets you create or join a workspace inline. A highlight glides between rows, and switching crossfades the trigger through a short loading state.
- [Live visitors](https://uiarc.dev/components/live-visitors/markdown): A realtime visitors card where the live count rolls digit by digit, new arrivals ping in on a dotted world map, the top pages reorder with bars, and signups and upgrades tick in with country flags.
- [Social proof toast](https://uiarc.dev/components/social-proof-toast/markdown): A stack of social proof notifications for landing and pricing pages, where recent trials, upgrades and verified purchases from people and companies arrive every few seconds. The stack pauses and fans out on hover, and visitors can dismiss any toast.
- [Install snippet](https://uiarc.dev/components/install-snippet/markdown): A "get started in 30 seconds" card where framework tabs, three numbered steps and highlighted snippets take a developer from install to first event. Generate key wipes a fresh API key into the placeholder in place.

### Guidance for AI tools

Reply draft: An AI email reply drafter where Claude streams a reply under a received Gmail message. Quick replies steer a fresh draft, tone and length rewrite it with a single crossfade, and you can edit the finished draft before you insert it. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Agent handoff

> A support conversation where an AI assistant hands off to a person. When it transfers, a card shows the summary it passes to the team and the typical wait. The person then joins and takes over, and a thin timeline on the left marks each step.

- Type: Component (special)
- Access: Arc Pro
- Page: https://uiarc.dev/components/agent-handoff
- Markdown: https://uiarc.dev/components/agent-handoff/markdown
- Source file: `registry/components/agent-handoff/agent-handoff.tsx`
- Dependencies: motion, lucide-react
- Keywords: special, ai, new, agent handoff, human handoff, ai escalation, transfer to human, support chat, live chat, intercom, zendesk, ai support agent, customer support widget, escalation summary

### When to use

- A support widget where the AI answers first and escalates to a human agent.
- Showing customers what the assistant shared with the team, so they do not repeat themselves.
- Marketing or docs pages that explain an AI to human handoff flow.

### When not to use

- A general chat with one assistant and no handoff: use chat-thread.
- Showing an agent's internal steps or tool calls: use agent-timeline or tool-call.
- A full help desk inbox for agents: build it from list and detail layouts instead.

### Installation

Agent handoff is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/agent-handoff
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { AgentHandoff } from "@/components/arc/agent-handoff/agent-handoff";

// Demo: plays a simulated support chat
<AgentHandoff />

// Wired to your support backend
<AgentHandoff
  stage={conversation.stage}
  title="Order NW-48213"
  subtitle="Northwind Home support"
  messages={conversation.aiMessages}
  agentMessages={conversation.agentMessages}
  typing={conversation.typing}
  summary={{
    issue: "Desk arrived with a cracked leg. Customer wants a full refund.",
    fields: [{ label: "Order", value: "NW-48213" }, { label: "Asks for", value: "Full refund" }],
  }}
  agent={{ name: "Jordan Reyes", role: "Support specialist", avatar: "/jordan.jpg", joinedAt: "14:05" }}
  provider="intercom"
  onSend={text => sendMessage(text)}
  onRequestHuman={() => escalate()}
  onCancelTransfer={() => cancelEscalation()}
  onRetry={() => escalate()}
/>
```

### API reference

#### AgentHandoff

A support conversation where an AI assistant hands off to a person, with a summary card and a step timeline. Leave out `stage` to play the built in simulated chat.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `stage` | `"assistant" \| "transferring" \| "connected" \| "resolved" \| "unavailable"` | – | Where the conversation is. Leave it out to play the simulated demo. |
| `messages` | `HandoffMessage[]` | `[]` | The conversation with the assistant, before the handoff. Each message is { id, from: "customer" \| "assistant" \| "agent", text, time?, streaming? }. |
| `agentMessages` | `HandoffMessage[]` | `[]` | Everything after the handoff card: notes the customer adds while waiting and the conversation with the person. The join step sits before the person's first message. |
| `typing` | `"assistant" \| "agent" \| null` | `null` | Who is typing. The assistant shows a short shimmering Thinking line, a person shows typing dots. |
| `summary` | `{ issue: string; fields?: { label: string; value: string }[] }` | – | What the assistant passes to the person. Shown in the handoff card from transferring on, collapsible. |
| `assistant` | `{ name?: string; model?: string; mark?: ReactNode }` | `{ name: "Assistant", model: "Claude Sonnet 5.5" }` | The AI assistant on the first step. The mark defaults to the Claude mark; pass a 14px mark for another model. |
| `agent` | `{ name: string; role?: string; avatar?: string; joinedAt?: string }` | – | The person who takes over. Shown on the join step, in the card and in the header from connected on. |
| `provider` | `"intercom" \| "zendesk" \| { name: string; mark: ReactNode }` | `"intercom"` | The help desk the conversation moves to. Its mark sits on the timeline next to the handoff card. |
| `replyEstimate` | `string` | `"2 min"` | Typical wait shown while transferring. |
| `title` | `string` | `"Support chat"` | Header title, such as the order or ticket number. |
| `subtitle` | `string` | – | Muted line under the title. |
| `onSend` | `(text: string) => void` | – | Shows the composer. Called with the trimmed text; append the message to messages or agentMessages yourself. |
| `onRequestHuman` | `() => void` | – | Shows a Talk to a person reply under the assistant's last answer while the stage is assistant. |
| `onCancelTransfer` | `() => void` | – | Shows Cancel on the handoff card while transferring. |
| `onRetry` | `() => void` | – | Shows Try again on the handoff card when the stage is unavailable. |
| `placeholder` | `string` | – | Composer placeholder. Defaults to one that follows the stage, such as Message Jordan. |
| `height` | `number \| string` | `600` | Card height. The thread scrolls inside and stays pinned to the newest message. |
| `notice` | `string` | – | A one-off message for screen readers, such as Refund issued. |
| `scenario` | `"handoff" \| "unavailable"` | `"handoff"` | Simulation only: unavailable stops when nobody picks the transfer up, so Try again shows. |
| `className` | `string` | – | Class on the root card. |

#### useHandoffSimulation

The hook behind the demo: returns stage, messages, agentMessages, typing, summary, notice and the handlers, so you can drive the view yourself or prototype a flow.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `scenario` (required) | `"handoff" \| "unavailable"` | – | Which story to play. |
| `reduced` (required) | `boolean` | – | Reduced motion: replies appear whole and the loop plays once. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Tab | Moves through the thread, Talk to a person, the card actions, the summary toggle and the composer. |
| Enter | Sends the composer message, or activates the focused button. |
| Space | Toggles the summary when the summary button has focus. |

### Accessibility

- The thread is a focusable log so keyboard users can scroll it; it does not announce every streamed chunk.
- Stage changes and action results are announced once through a polite status region, including that the demo is simulated.
- Every status pairs an icon with a label: Transferring, With Jordan, Resolved, No one available. Color is never the only signal.
- The summary toggle uses aria-expanded and aria-controls. Typing dots carry a label such as Jordan is typing.
- Marks and avatars on the timeline are decorative next to their visible labels.

### Motion

- Assistant replies stream in chunks of 3 to 8 words every ~34ms; each chunk only fades in over 140ms.
- The thread animates to its measured height with a bounce-free spring (0.24s), so new rows and streamed lines push it up without a snap.
- While transferring, a small accent dot travels down the timeline beside the handoff card.
- Status labels crossfade (100ms out, 160ms in, 2px rise). Loops pause off screen.
- Reduced motion: replies appear whole, no travel dot, typing dots and spinner hold still, no height animation, the demo plays once.

### Responsive behavior

- Fills its container up to 560px wide; holds up at 360px with tighter padding and wider bubbles.
- Fixed height with an internal scroll pinned to the newest message, so the page never shifts as the thread grows.
- Long names and meta lines truncate with an ellipsis; message text wraps.

### Performance

- One ResizeObserver and one IntersectionObserver per card. Streaming updates re-render only the message being streamed and its chunks.
- CSS keyframes for the dots, spinner and travel dot; all pause off screen.
- For very long threads, pass only the recent messages; the card is meant for a live conversation, not an archive.

### Notes for AI

- Use for support or sales chat where an AI assistant escalates to a person. Keep the assistant's messages in `messages` and everything after the handoff in `agentMessages`.
- Drive `stage` from your backend: transferring when you create the ticket, connected when a person accepts, unavailable when the queue times out.
- Stream assistant text by updating the message's `text` with `streaming: true`; the component fades each appended chunk.
- Pass `summary` with the same facts you send to the help desk so the customer sees what was shared.
- Do not use `scenario` outside demos; it only affects the built in simulation.

### Related

- [Chat thread](https://uiarc.dev/components/chat-thread/markdown): A chat thread with grouped messages, reactions, read receipts, typing, and a composer with attachments.
- [Agent status](https://uiarc.dev/components/agent-status/markdown): A compact live status pill for a running AI agent: the agent's mark in a live ring, the current activity and an elapsed timer, opening into the steps so far.
- [Agent timeline](https://uiarc.dev/components/agent-timeline/markdown): A compact timeline of one orchestrated agent run: the orchestrator and its subagents share a time axis, handoffs draw in between rows, and a playhead replays thinking, tool calls and waiting while the header counts time, tokens and cost. Hover a span for what it did, or click it to trace its handoff path.
- [Tool call](https://uiarc.dev/components/tool-call/markdown): A tool call row for agent transcripts: the tool's mark and the call in plain words, a live state while it runs, and the input and output a click away, with approval and retry when needed.
- [Avatar](https://uiarc.dev/components/avatar/markdown): A compact identity marker for people and accounts.

### Also in ai

- [Agent plan](https://uiarc.dev/components/agent-plan/markdown): The plan an agent writes before it acts: edit, reorder or add steps while it is a draft, then watch it work through them as a live checklist.
- [Context window](https://uiarc.dev/components/context-window/markdown): An AI context window as a grid of 200 cells: the system prompt, tools, files, summary and messages fill it in order, a threshold row marks where compaction starts, and sending a message, attaching a file or compacting shows exactly how much still fits.
- [Reasoning block](https://uiarc.dev/components/reasoning-block/markdown): The collapsible thinking block of an AI reply. While the model thinks, a shimmering label counts the seconds and the latest reasoning streams underneath. When it finishes, it folds to "Thought for 7s" and opens to show the full reasoning as calm steps with headings.
- [Source cards](https://uiarc.dev/components/source-cards/markdown): A row of cited sources under an AI answer where cards stream in with real site marks while the model searches, the overflow collapses into a stack of favicons, hovering lifts a preview with the passage, and an inline [n] citation highlights its card.
- [Model card](https://uiarc.dev/components/model-card/markdown): A model details card where switching models rolls every price, limit and score in place, a token slider estimates monthly cost live, and benchmark bars show each model's rank on hover. Compare crossfades to a side-by-side table against any rival with the better values marked, and the card never changes size.
- [AI workflow](https://uiarc.dev/components/ai-workflow/markdown): A Linear-style AI workflow card where a Gmail trigger, a Claude step, a branch and Slack and Linear actions sit on one hairline rail, and a test run glides down it, opening each step's output inline. Steps are added from a compact command menu with real app marks.
- [Code suggestion](https://uiarc.dev/components/code-suggestion/markdown): An AI code edit suggestion where the model's proposed changes stream into a small editor panel as inline diff hunks, and you accept or reject each one, or all at once with Cmd+Enter. Accepted hunks fold into the file with a smooth height change.
- [Ghost text](https://uiarc.dev/components/ghost-text/markdown): An inline AI autocomplete where muted ghost text continues your sentence exactly at the caret and Tab turns it solid in place. Cmd+Right takes it one word at a time, Escape fades it away, and a calm chip shows the model behind it.
- [Image generation](https://uiarc.dev/components/image-generation/markdown): An image studio where each image forms on a dot matrix: a soft halftone wave breathes across the grid, the dots take the colours of the coming photo and grow into a coloured halftone, then blur away into the sharp photo. One large canvas with a mono size label, a filmstrip of four variations, a prompt bar with model and ratio, and upscale with a sweeping dot band, vary or download, with real provider marks and a built-in simulation.
- [Dictation button](https://uiarc.dev/components/dictation-button/markdown): A chat composer with voice input, where the mic springs into a recording pill with a smooth live waveform, a timer, and cancel and insert buttons. Words stream into the field as you speak, muted until the recognizer settles them.
- [Speech player](https://uiarc.dev/components/speech-player/markdown): A read-aloud player for AI replies. The Read aloud button in the message's action row turns into a compact player with play, a scrubbable progress bar, speed and a voice picker, and a highlight follows the spoken word through the reply, karaoke style.
- [Meeting summary](https://uiarc.dev/components/meeting-summary/markdown): An AI meeting notes card: the header shows the Google Meet or Zoom mark, the attendees and the duration. Summary, Decisions and Action items stream in after a short summarizing pass. Hover any line to see the transcript quote it came from, then check off action items or send them to Linear or Notion.
- [Reply draft](https://uiarc.dev/components/reply-draft/markdown): An AI email reply drafter where Claude streams a reply under a received Gmail message. Quick replies steer a fresh draft, tone and length rewrite it with a single crossfade, and you can edit the finished draft before you insert it.
- [PII redaction](https://uiarc.dev/components/pii-redaction/markdown): A guardrail card where personal data is redacted before the prompt reaches the model. Scan marks each name, email, phone number and card with its type and swaps it for a placeholder like [EMAIL_1]. The safe prompt travels to Claude, and the reply comes back with the original values put back for the person.
- [Response feedback](https://uiarc.dev/components/response-feedback/markdown): A feedback control for AI replies where thumbs down opens an inline panel with reason chips and an optional note, thumbs up fills and asks what was good, and a submit shows a short thank-you before folding back into the row.
- [LLM cost calculator](https://uiarc.dev/components/llm-cost-calculator/markdown): A pricing calculator for LLM workloads. Set tokens per request, requests per day and prompt caching, and eight current models re-rank by monthly cost. Bars glide and prices roll as you drag.
- [Provider keys](https://uiarc.dev/components/provider-keys/markdown): A settings card for bring-your-own-key AI products. Each provider row shows its real mark, the masked key, a status and when the key was last used. You can reveal a key for five seconds, copy, rotate or remove it with undo. Adding or rotating a key opens an inline form that checks the format as you type, then tests the connection before saving.
- [Generation stats](https://uiarc.dev/components/generation-stats/markdown): A live stats strip for a streaming LLM response where time to first token, speed with a sparkline, output tokens and cost count up in tabular numerals beside the model's real mark, then settle and open into a latency and token cost breakdown.
- [AI translate](https://uiarc.dev/components/ai-translate/markdown): A message card where picking a language streams the AI translation in place, sentence by sentence over the dimmed original, with a detected-language chip, a Show original toggle and a status line credited to the model's mark.
- [TL;DR toggle](https://uiarc.dev/components/tldr-toggle/markdown): An article card with a Full, Summary and Key points switch and a length slider. Switching streams an AI summary in place of the article as the card's height springs to fit, and each key point links back to the paragraph it came from, which gets scrolled to and highlighted.
- [Connector setup](https://uiarc.dev/components/connector-setup/markdown): A "Connect your tools" card for an AI assistant. Each app connects inline: it redirects, authorizes and runs a first sync with a progress hairline, then lists the scopes it was granted and offers Disconnect with an inline confirm.
- [Smart form fill](https://uiarc.dev/components/smart-form-fill/markdown): A paste-to-fill form card where AI reads an email signature or messy notes and fills a contact field by field. Each value flashes in with a confidence dot, its source lights up in the pasted text, low-confidence guesses ask for review, and Undo puts the old values back.
- [Enrich column](https://uiarc.dev/components/enrich-column/markdown): An AI enrichment column for a data table, where one prompt runs down every row and each cell shimmers while it works, then settles into a value with its source or a failure you can retry.
- [Ticket router](https://uiarc.dev/components/ticket-router/markdown): A support ticket router where messages from Gmail, Intercom, Slack and Zendesk come in one at a time. An AI classifier labels each one with intent, sentiment and confidence, and the ticket moves into a team lane with an assignee. Low confidence tickets wait in a review lane, and one click there routes them to the suggested team.
- [Ask your data](https://uiarc.dev/components/ask-your-data/markdown): A natural language to chart card: you ask a question, PostgreSQL streams into a collapsible, syntax highlighted panel, the query runs with a rolling row count, and the answer builds as stacked bars, lines or a table, with a one line insight streamed in underneath.
- [Agent cursor](https://uiarc.dev/components/agent-cursor/markdown): A live document where Claude edits like a collaborator. Its labeled cursor comes out of its avatar, selects a paragraph and streams in a rewrite, adds a heading and fixes a typo, while a teammate's cursor reads along. Changes stay tinted until someone accepts or undoes them from a floating review bar.
- [Provider status](https://uiarc.dev/components/provider-status/markdown): A status card for the AI providers your product depends on. Each row shows the provider's real mark, its health as an icon and label, p50 latency and a 30-day uptime bar with a tooltip for each day. An incident row expands into its timeline of updates, and the card checks again on a visible countdown.
- [Training run](https://uiarc.dev/components/training-run/markdown): A fine-tuning job card where a live train and validation loss curve draws across a fixed step axis that doubles as the epoch progress bar. It shows the learning rate, elapsed time, ETA and the latest evals and checkpoints, has Pause and Cancel while it runs, and ends in results with a Deploy button.
- [AI command](https://uiarc.dev/components/ai-command/markdown): A Cmd+K command palette with an AI mode. Search pages and actions, or press Tab to ask a question: the answer streams inside the palette with numbered sources, and the next steps it suggests, like filing a Linear issue or opening a Notion doc, run straight from the list.
- [Starter prompts](https://uiarc.dev/components/starter-prompts/markdown): A greeting and a grid of starter cards for the empty state of an AI app. The cards are grouped into Write, Code, Analyze and Plan tabs, and a shuffle swaps them with a short staggered crossfade. Picking a card fills the composer, and cards that use a connected app show its mark (Gmail, GitHub, Notion, Linear, Google Calendar).
- [AI mascot](https://uiarc.dev/components/ai-mascot/markdown): A small assistant character, a soft pebble with pill eyes and a companion dot, that shows what the AI is doing. It breathes and glances when idle, leans in to listen, looks up while the dot orbits its head, reads along the line it writes, squints with a sparkle when done and shakes once with worried brows on an error.
- [Image reveal](https://uiarc.dev/components/image-reveal/markdown): An image generation canvas where a soft, blurred preview made from the image's own colors sharpens top to bottom behind a soft-edged band. It works the way ChatGPT, Midjourney and Gemini show images forming, with fine film grain, a translucent progress pill and calm queued and error states.
- [AI spark](https://uiarc.dev/components/ai-spark/markdown): A brand-quality animated spark mark. Four tapered rays and four lighter diagonals breathe at rest, ripple while thinking, pulse like a heartbeat while writing, then gather and settle when done. Every status change blends from the pose the mark is already in.
- [Pixel mascot](https://uiarc.dev/components/pixel-mascot/markdown): A pixel-art robot that shows what an AI assistant is doing. It idles, thinks, types, celebrates and errors in frame-stepped sprite animations, and stays crisp at every integer size from 24px to 192px.
- [Ghost mascot](https://uiarc.dev/components/ghost-mascot/markdown): A floating ghost mascot whose soft sheet ripples at the hem while it hovers. It blinks when idle, turns toward you to listen, fades a little translucent while thinking, draws a tiny pen line while writing, smiles with a sparkle when done and wobbles once on an error.
- [Cube mascot](https://uiarc.dev/components/cube-mascot/markdown): An isometric cube mascot where three shaded faces and a painted-on face show what the assistant is doing. It turns a quarter turn in eased steps while thinking, prints lines onto the floor while writing, settles with a sparkle when done, and shakes once on error.
- [Tone tuner](https://uiarc.dev/components/tone-tuner/markdown): A brand voice card where two sliders (formality and detail) and Friendly, Confident and Empathetic chips rewrite a customer reply. Each changed sentence crossfades in place, new words can be highlighted against the original, and Copy takes the current version.
- [Upgrade prompt](https://uiarc.dev/components/upgrade-prompt/markdown): An upgrade nudge for the moment someone hits a limit. It shows a usage meter at 50 of 50 AI credits, a rolling price with a monthly and yearly toggle, three concrete unlocks with real model marks, and Upgrade or Maybe later. Upgrading leads into a success state with the new limits, and the card never changes size between states.
- [Referral card](https://uiarc.dev/components/referral-card/markdown): A give-and-get referral card where people copy or share their invite link, invite friends by email as chips, and watch invites move from invited to signed up to earned, with the credit total counting up and a milestone reward unlocking.
- [Trial banner](https://uiarc.dev/components/trial-banner/markdown): A trial status banner where a ring counts down the days left, the copy names what the workspace loses, and the upgrade path is one click away. It comes as a slim banner, a sidebar card or a header pill. It shifts to a warning tone in the last days, has expired and upgraded states, and folds into the pill when dismissed or snoozed.
- [Team switcher](https://uiarc.dev/components/team-switcher/markdown): A workspace switcher like Linear, Vercel or Slack. The trigger shows the current workspace's logo and plan. The menu has search, your role in each workspace and a Cmd+1 to 9 shortcut for each, and lets you create or join a workspace inline. A highlight glides between rows, and switching crossfades the trigger through a short loading state.
- [Live visitors](https://uiarc.dev/components/live-visitors/markdown): A realtime visitors card where the live count rolls digit by digit, new arrivals ping in on a dotted world map, the top pages reorder with bars, and signups and upgrades tick in with country flags.
- [Social proof toast](https://uiarc.dev/components/social-proof-toast/markdown): A stack of social proof notifications for landing and pricing pages, where recent trials, upgrades and verified purchases from people and companies arrive every few seconds. The stack pauses and fans out on hover, and visitors can dismiss any toast.
- [Install snippet](https://uiarc.dev/components/install-snippet/markdown): A "get started in 30 seconds" card where framework tabs, three numbered steps and highlighted snippets take a developer from install to first event. Generate key wipes a fresh API key into the placeholder in place.

### Guidance for AI tools

Agent handoff: A support conversation where an AI assistant hands off to a person. When it transfers, a card shows the summary it passes to the team and the typical wait. The person then joins and takes over, and a thin timeline on the left marks each step. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## PII redaction

> A guardrail card where personal data is redacted before the prompt reaches the model. Scan marks each name, email, phone number and card with its type and swaps it for a placeholder like [EMAIL_1]. The safe prompt travels to Claude, and the reply comes back with the original values put back for the person.

- Type: Component (special)
- Access: Arc Pro
- Page: https://uiarc.dev/components/pii-redaction
- Markdown: https://uiarc.dev/components/pii-redaction/markdown
- Source file: `registry/components/pii-redaction/pii-redaction.tsx`
- Dependencies: motion, lucide-react
- Keywords: special, ai, new, pii, redaction, guardrail, privacy, data loss prevention, dlp, anonymize, mask, placeholder, llm safety, prompt, claude, personal data, gdpr, support assistant

### When to use

- Explaining or proving a privacy guardrail in an AI product: support assistants, health or finance copilots, enterprise chat.
- A settings or onboarding screen where admins see what the PII filter does before they turn it on.
- A playground where people paste text and see exactly what would reach the model.

### When not to use

- Use ai-chat or ai-composer for the conversation itself; redact behind the scenes and show this card only where the guardrail needs explaining.
- Do not rely on the built-in detector for compliance; pass a real DLP service through detect.
- Use tool-call to show an arbitrary tool step in a transcript.

### Installation

PII redaction is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/pii-redaction
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { PiiRedaction, detectPii, redactPii, restorePii } from "@/components/arc/pii-redaction/pii-redaction";

export function SupportGuard({ user }) {
  return (
    <PiiRedaction
      autoPlay={false}
      defaultMessage=""
      names={[user.name]}
      model={{ name: "Claude Sonnet 5.5" }}
      detect={async (text, signal) => {
        const res = await fetch("/api/dlp/scan", { method: "POST", body: text, signal });
        return res.json(); // [{ type: "email", start: 74, end: 100 }, ...]
      }}
      send={async (prompt, signal) => {
        const res = await fetch("/api/chat", { method: "POST", body: JSON.stringify({ prompt }), signal });
        const { text } = await res.json();
        return text; // may contain [NAME_1], [EMAIL_1], restored by the component
      }}
      onRedact={({ entities }) => audit.log("pii.redacted", entities.map(e => e.type))}
    />
  );
}

// Server side, without the card:
const { prompt, entities } = redactPii(message, detectPii(message, { names: [user.name] }));
const reply = restorePii(await model.complete(prompt), entities);

// With no props it plays the simulated support conversation.
<PiiRedaction />
```

### API reference

#### PiiRedaction

A guardrail card that shows personal data being redacted before a prompt reaches the model. Scan marks each name, email, phone number and card in the message with its type, then swaps each one for a numbered placeholder such as [EMAIL_1] in a single crossfade. Send carries the safe prompt along a small flow (you, the PII guard, the model), the reply streams back in quick chunks with its placeholders, and the guard restores the original values for the person. Show original flips the message between the safe prompt and what was typed. The message is editable before a scan, so people can paste their own text. With no props it plays a simulated support conversation with Claude Sonnet 5.5 on a loop while on screen.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `defaultMessage` | `string` | `piiSampleMessage` | The message to check. The sample is a double charge support request from Sofia Ramirez with a name, a Luhn-valid test card, an email and a phone number. |
| `editable` | `boolean` | `true` | Lets people edit the message before a scan. Cmd or Ctrl plus Enter scans from the field. |
| `names` | `string[]` | `["Sofia Ramirez"]` | Names the built-in detector always flags, on top of introductions like "I'm", "this is" and "my name is". Pass the signed-in person's name and their contacts. |
| `detect` | `(text: string, signal: AbortSignal) => PiiMatch[] \| Promise<PiiMatch[]>` | – | Replaces the built-in detector, for example with your DLP or NER service. Return spans as { type: "name" \| "email" \| "phone" \| "card", start, end } with an exclusive end. The signal aborts when the person presses Stop or Reset. |
| `send` | `(prompt: string, signal: AbortSignal) => Promise<string>` | – | Sends the redacted prompt to your model and resolves with its reply, placeholders included. The component restores them. Without it the reply is simulated and the status says so. A rejection shows the error message with Retry. |
| `model` | `{ name: string; mark?: ReactNode }` | `{ name: "Claude Sonnet 5.5" }` | The model the safe prompt goes to, on the flow and above the reply. The mark draws at 16px; without one the Claude mark shows in its brand color. |
| `autoPlay` | `boolean` | `true` | Plays scan, send and restore on a loop while at least a quarter of the card is on screen. Stops for good as soon as someone edits, toggles or presses a button. Off with reduced motion. |
| `showOriginal` | `boolean` | – | Shows the original message instead of the safe prompt once it is redacted. Pair with onShowOriginalChange. |
| `defaultShowOriginal` | `boolean` | `false` | Initial Show original state when uncontrolled. |
| `onShowOriginalChange` | `(show: boolean) => void` | – | Called when the Show original switch changes. |
| `onRedact` | `(result: { prompt: string; entities: PiiEntity[] }) => void` | – | Called once the message is redacted, with the safe prompt and every entity (type, start, end, value, token). Log the entities server side, never the prompt alongside them. |
| `onReply` | `(reply: { raw: string; restored: string }) => void` | – | Called when the reply is restored, with the model's raw reply and the text the person sees. |
| `onPhaseChange` | `(phase: PiiRedactionPhase) => void` | – | Called on every phase change: idle, scanning, redacted, sending, thinking, streaming, restoring, done or error. |
| `className` | `string` | – | Class on the root card. |

#### detectPii, redactPii, restorePii

The pure helpers behind the card, safe on the server. detectPii(text, { names }) finds emails, card numbers (13 to 19 digits that pass Luhn), phone numbers (7 to 15 digits) and names. redactPii(text, matches) returns { prompt, entities } and gives a repeated value the same token. restorePii(reply, entities) puts the values back and leaves unknown tokens as they are.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `text` | `string` | – | The message to scan or redact. |
| `matches` | `PiiMatch[]` | – | Spans from detectPii or your own detector. Overlapping spans after the first are skipped. |
| `entities` | `PiiEntity[]` | – | The entities from redactPii, used to restore a reply. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Tab | Moves through the message field (before a scan), the Show original switch once there is a safe prompt, Reset when it shows, and the primary action. |
| Cmd + Enter, Ctrl + Enter | Scans the message from the field. Focus moves to the primary action, which now reads Stop. |
| Space, Enter | Toggles Show original, or activates Scan, Stop, Send, Run again, Retry or Reset. |

### Accessibility

- A polite status region announces each phase ("Scanning for personal data", "4 items redacted", "Reply restored") and, when the reply is simulated, adds "Simulated, nothing was sent".
- Status never relies on color: every phase pairs an icon with a short label, each type cell says Name, Email, Phone or Card with its token or None found, and marks in the original message carry labels such as "Email, redacted as EMAIL_1".
- Scan, Stop, Send, Run again and Retry are one button whose label changes, so keyboard focus stays put through the whole flow. Reset returns focus to the message field.
- Only the visible text layer is exposed to assistive tech; the hidden layers that keep the height steady are aria-hidden.
- The flow strip is decorative and hidden from screen readers, since the status region already narrates each hop.
- The Show original label is a real label for the switch, and the switch is disabled with a muted label until there is a safe prompt to compare.

### Motion

- Scan highlights each entity in turn, 120ms apart, with a 160ms tint in its type color while the matching type cell crossfades from Checking to its token.
- The swap to placeholders is a single crossfade between two stacked text layers (old out in 100ms, new in over 160ms), so no words slide or rewrap mid animation and the height never changes.
- Each hop of the flow is one dot traveling the connector in 460ms on an ease in out curve; the active node's label shimmers while it works.
- The reply streams three to six words every 34ms, each chunk only fading in, then crossfades once to the restored text.
- Labels, statuses and the Reset button crossfade in place; nothing bounces and nothing changes size between states.
- Reduced motion drops the travel, the stagger, the streaming and the autoplay loop, and keeps every state, label and announcement.

### Responsive behavior

- The card fills its container up to 640px. Below 520px the four type cells fall into two rows of two.
- Below 400px the card tightens its gaps and hides the Simulated tag (the status region still announces it); the model name truncates with an ellipsis in the flow.
- Text layers stack in one grid cell and the reply reserves the sample reply's height, so nothing jumps at 360px, 390px or desktop widths.

### Performance

- Detection is a handful of regular expressions and a Luhn check, linear in the message length.
- The loop runs only while the card is at least a quarter on screen (IntersectionObserver) and stops for good on the first interaction.
- Highlights and layer swaps are CSS transitions on opacity and background color; the dot animates a transform; every pending step aborts through one AbortController.

### Notes for AI

- Redact on the server in production: run detectPii and redactPii (or your DLP) before the prompt leaves your backend, keep entities in the request scope, and call restorePii on the reply. Use this card to show people what happens, or as the UI over that pipeline through detect and send.
- The built-in detector is a baseline. Names beyond the names list and simple introductions need an NER model or a DLP service passed through detect.
- Keep the same token for a repeated value within one conversation so the model can refer back to it; redactPii does this per call, so persist the entity map across turns if you need it.
- Instruct the model to keep placeholders verbatim (for example "Refer to [EMAIL_1] exactly as written") so restorePii can put the values back.
- Set autoPlay={false} in product UI and pass defaultMessage="" for a blank field.

### Related

- [AI chat](https://uiarc.dev/components/blocks/ai-chat/markdown): A full-screen AI chat where answers stream in as markdown with folding reasoning, tool chips and cited sources. People can switch chats and models, edit or retry a message into versions, rate replies and stop a reply mid-stream.
- [AI composer](https://uiarc.dev/components/blocks/ai-composer/markdown): The prompt box at the bottom of an AI app: files upload in place, / opens commands, @ inserts mentions, a model and effort menu sits in the toolbar, and the send button turns into a stop control ringed by the reply's progress.
- [Tool call](https://uiarc.dev/components/tool-call/markdown): A tool call row for agent transcripts: the tool's mark and the call in plain words, a live state while it runs, and the input and output a click away, with approval and retry when needed.
- [Agent approvals](https://uiarc.dev/components/blocks/agent-approvals/markdown): One approval card for agents: the waiting tool call reads like a permission prompt with the tool's mark, the agent's reason and its arguments, and you approve, deny or allow it from now on.
- [Prompt studio](https://uiarc.dev/components/blocks/prompt-studio/markdown): One card for editing, testing and shipping a prompt template: variables as chips with sample values, a test run against the chosen model, and versions you can compare and promote to production.
- [Text shimmer](https://uiarc.dev/components/text-shimmer/markdown): Show ongoing work with a calm light across the words.
- [Switch](https://uiarc.dev/components/switch/markdown): A tactile toggle for settings that take effect immediately.

### Also in ai

- [Agent status](https://uiarc.dev/components/agent-status/markdown): A compact live status pill for a running AI agent: the agent's mark in a live ring, the current activity and an elapsed timer, opening into the steps so far.
- [Agent plan](https://uiarc.dev/components/agent-plan/markdown): The plan an agent writes before it acts: edit, reorder or add steps while it is a draft, then watch it work through them as a live checklist.
- [Agent timeline](https://uiarc.dev/components/agent-timeline/markdown): A compact timeline of one orchestrated agent run: the orchestrator and its subagents share a time axis, handoffs draw in between rows, and a playhead replays thinking, tool calls and waiting while the header counts time, tokens and cost. Hover a span for what it did, or click it to trace its handoff path.
- [Context window](https://uiarc.dev/components/context-window/markdown): An AI context window as a grid of 200 cells: the system prompt, tools, files, summary and messages fill it in order, a threshold row marks where compaction starts, and sending a message, attaching a file or compacting shows exactly how much still fits.
- [Reasoning block](https://uiarc.dev/components/reasoning-block/markdown): The collapsible thinking block of an AI reply. While the model thinks, a shimmering label counts the seconds and the latest reasoning streams underneath. When it finishes, it folds to "Thought for 7s" and opens to show the full reasoning as calm steps with headings.
- [Source cards](https://uiarc.dev/components/source-cards/markdown): A row of cited sources under an AI answer where cards stream in with real site marks while the model searches, the overflow collapses into a stack of favicons, hovering lifts a preview with the passage, and an inline [n] citation highlights its card.
- [Model card](https://uiarc.dev/components/model-card/markdown): A model details card where switching models rolls every price, limit and score in place, a token slider estimates monthly cost live, and benchmark bars show each model's rank on hover. Compare crossfades to a side-by-side table against any rival with the better values marked, and the card never changes size.
- [AI workflow](https://uiarc.dev/components/ai-workflow/markdown): A Linear-style AI workflow card where a Gmail trigger, a Claude step, a branch and Slack and Linear actions sit on one hairline rail, and a test run glides down it, opening each step's output inline. Steps are added from a compact command menu with real app marks.
- [Code suggestion](https://uiarc.dev/components/code-suggestion/markdown): An AI code edit suggestion where the model's proposed changes stream into a small editor panel as inline diff hunks, and you accept or reject each one, or all at once with Cmd+Enter. Accepted hunks fold into the file with a smooth height change.
- [Ghost text](https://uiarc.dev/components/ghost-text/markdown): An inline AI autocomplete where muted ghost text continues your sentence exactly at the caret and Tab turns it solid in place. Cmd+Right takes it one word at a time, Escape fades it away, and a calm chip shows the model behind it.
- [Image generation](https://uiarc.dev/components/image-generation/markdown): An image studio where each image forms on a dot matrix: a soft halftone wave breathes across the grid, the dots take the colours of the coming photo and grow into a coloured halftone, then blur away into the sharp photo. One large canvas with a mono size label, a filmstrip of four variations, a prompt bar with model and ratio, and upscale with a sweeping dot band, vary or download, with real provider marks and a built-in simulation.
- [Dictation button](https://uiarc.dev/components/dictation-button/markdown): A chat composer with voice input, where the mic springs into a recording pill with a smooth live waveform, a timer, and cancel and insert buttons. Words stream into the field as you speak, muted until the recognizer settles them.
- [Speech player](https://uiarc.dev/components/speech-player/markdown): A read-aloud player for AI replies. The Read aloud button in the message's action row turns into a compact player with play, a scrubbable progress bar, speed and a voice picker, and a highlight follows the spoken word through the reply, karaoke style.
- [Meeting summary](https://uiarc.dev/components/meeting-summary/markdown): An AI meeting notes card: the header shows the Google Meet or Zoom mark, the attendees and the duration. Summary, Decisions and Action items stream in after a short summarizing pass. Hover any line to see the transcript quote it came from, then check off action items or send them to Linear or Notion.
- [Reply draft](https://uiarc.dev/components/reply-draft/markdown): An AI email reply drafter where Claude streams a reply under a received Gmail message. Quick replies steer a fresh draft, tone and length rewrite it with a single crossfade, and you can edit the finished draft before you insert it.
- [Agent handoff](https://uiarc.dev/components/agent-handoff/markdown): A support conversation where an AI assistant hands off to a person. When it transfers, a card shows the summary it passes to the team and the typical wait. The person then joins and takes over, and a thin timeline on the left marks each step.
- [Response feedback](https://uiarc.dev/components/response-feedback/markdown): A feedback control for AI replies where thumbs down opens an inline panel with reason chips and an optional note, thumbs up fills and asks what was good, and a submit shows a short thank-you before folding back into the row.
- [LLM cost calculator](https://uiarc.dev/components/llm-cost-calculator/markdown): A pricing calculator for LLM workloads. Set tokens per request, requests per day and prompt caching, and eight current models re-rank by monthly cost. Bars glide and prices roll as you drag.
- [Provider keys](https://uiarc.dev/components/provider-keys/markdown): A settings card for bring-your-own-key AI products. Each provider row shows its real mark, the masked key, a status and when the key was last used. You can reveal a key for five seconds, copy, rotate or remove it with undo. Adding or rotating a key opens an inline form that checks the format as you type, then tests the connection before saving.
- [Generation stats](https://uiarc.dev/components/generation-stats/markdown): A live stats strip for a streaming LLM response where time to first token, speed with a sparkline, output tokens and cost count up in tabular numerals beside the model's real mark, then settle and open into a latency and token cost breakdown.
- [AI translate](https://uiarc.dev/components/ai-translate/markdown): A message card where picking a language streams the AI translation in place, sentence by sentence over the dimmed original, with a detected-language chip, a Show original toggle and a status line credited to the model's mark.
- [TL;DR toggle](https://uiarc.dev/components/tldr-toggle/markdown): An article card with a Full, Summary and Key points switch and a length slider. Switching streams an AI summary in place of the article as the card's height springs to fit, and each key point links back to the paragraph it came from, which gets scrolled to and highlighted.
- [Connector setup](https://uiarc.dev/components/connector-setup/markdown): A "Connect your tools" card for an AI assistant. Each app connects inline: it redirects, authorizes and runs a first sync with a progress hairline, then lists the scopes it was granted and offers Disconnect with an inline confirm.
- [Smart form fill](https://uiarc.dev/components/smart-form-fill/markdown): A paste-to-fill form card where AI reads an email signature or messy notes and fills a contact field by field. Each value flashes in with a confidence dot, its source lights up in the pasted text, low-confidence guesses ask for review, and Undo puts the old values back.
- [Enrich column](https://uiarc.dev/components/enrich-column/markdown): An AI enrichment column for a data table, where one prompt runs down every row and each cell shimmers while it works, then settles into a value with its source or a failure you can retry.
- [Ticket router](https://uiarc.dev/components/ticket-router/markdown): A support ticket router where messages from Gmail, Intercom, Slack and Zendesk come in one at a time. An AI classifier labels each one with intent, sentiment and confidence, and the ticket moves into a team lane with an assignee. Low confidence tickets wait in a review lane, and one click there routes them to the suggested team.
- [Ask your data](https://uiarc.dev/components/ask-your-data/markdown): A natural language to chart card: you ask a question, PostgreSQL streams into a collapsible, syntax highlighted panel, the query runs with a rolling row count, and the answer builds as stacked bars, lines or a table, with a one line insight streamed in underneath.
- [Agent cursor](https://uiarc.dev/components/agent-cursor/markdown): A live document where Claude edits like a collaborator. Its labeled cursor comes out of its avatar, selects a paragraph and streams in a rewrite, adds a heading and fixes a typo, while a teammate's cursor reads along. Changes stay tinted until someone accepts or undoes them from a floating review bar.
- [Provider status](https://uiarc.dev/components/provider-status/markdown): A status card for the AI providers your product depends on. Each row shows the provider's real mark, its health as an icon and label, p50 latency and a 30-day uptime bar with a tooltip for each day. An incident row expands into its timeline of updates, and the card checks again on a visible countdown.
- [Training run](https://uiarc.dev/components/training-run/markdown): A fine-tuning job card where a live train and validation loss curve draws across a fixed step axis that doubles as the epoch progress bar. It shows the learning rate, elapsed time, ETA and the latest evals and checkpoints, has Pause and Cancel while it runs, and ends in results with a Deploy button.
- [AI command](https://uiarc.dev/components/ai-command/markdown): A Cmd+K command palette with an AI mode. Search pages and actions, or press Tab to ask a question: the answer streams inside the palette with numbered sources, and the next steps it suggests, like filing a Linear issue or opening a Notion doc, run straight from the list.
- [Starter prompts](https://uiarc.dev/components/starter-prompts/markdown): A greeting and a grid of starter cards for the empty state of an AI app. The cards are grouped into Write, Code, Analyze and Plan tabs, and a shuffle swaps them with a short staggered crossfade. Picking a card fills the composer, and cards that use a connected app show its mark (Gmail, GitHub, Notion, Linear, Google Calendar).
- [AI mascot](https://uiarc.dev/components/ai-mascot/markdown): A small assistant character, a soft pebble with pill eyes and a companion dot, that shows what the AI is doing. It breathes and glances when idle, leans in to listen, looks up while the dot orbits its head, reads along the line it writes, squints with a sparkle when done and shakes once with worried brows on an error.
- [Image reveal](https://uiarc.dev/components/image-reveal/markdown): An image generation canvas where a soft, blurred preview made from the image's own colors sharpens top to bottom behind a soft-edged band. It works the way ChatGPT, Midjourney and Gemini show images forming, with fine film grain, a translucent progress pill and calm queued and error states.
- [AI spark](https://uiarc.dev/components/ai-spark/markdown): A brand-quality animated spark mark. Four tapered rays and four lighter diagonals breathe at rest, ripple while thinking, pulse like a heartbeat while writing, then gather and settle when done. Every status change blends from the pose the mark is already in.
- [Pixel mascot](https://uiarc.dev/components/pixel-mascot/markdown): A pixel-art robot that shows what an AI assistant is doing. It idles, thinks, types, celebrates and errors in frame-stepped sprite animations, and stays crisp at every integer size from 24px to 192px.
- [Ghost mascot](https://uiarc.dev/components/ghost-mascot/markdown): A floating ghost mascot whose soft sheet ripples at the hem while it hovers. It blinks when idle, turns toward you to listen, fades a little translucent while thinking, draws a tiny pen line while writing, smiles with a sparkle when done and wobbles once on an error.
- [Cube mascot](https://uiarc.dev/components/cube-mascot/markdown): An isometric cube mascot where three shaded faces and a painted-on face show what the assistant is doing. It turns a quarter turn in eased steps while thinking, prints lines onto the floor while writing, settles with a sparkle when done, and shakes once on error.
- [Tone tuner](https://uiarc.dev/components/tone-tuner/markdown): A brand voice card where two sliders (formality and detail) and Friendly, Confident and Empathetic chips rewrite a customer reply. Each changed sentence crossfades in place, new words can be highlighted against the original, and Copy takes the current version.
- [Upgrade prompt](https://uiarc.dev/components/upgrade-prompt/markdown): An upgrade nudge for the moment someone hits a limit. It shows a usage meter at 50 of 50 AI credits, a rolling price with a monthly and yearly toggle, three concrete unlocks with real model marks, and Upgrade or Maybe later. Upgrading leads into a success state with the new limits, and the card never changes size between states.
- [Referral card](https://uiarc.dev/components/referral-card/markdown): A give-and-get referral card where people copy or share their invite link, invite friends by email as chips, and watch invites move from invited to signed up to earned, with the credit total counting up and a milestone reward unlocking.
- [Trial banner](https://uiarc.dev/components/trial-banner/markdown): A trial status banner where a ring counts down the days left, the copy names what the workspace loses, and the upgrade path is one click away. It comes as a slim banner, a sidebar card or a header pill. It shifts to a warning tone in the last days, has expired and upgraded states, and folds into the pill when dismissed or snoozed.
- [Team switcher](https://uiarc.dev/components/team-switcher/markdown): A workspace switcher like Linear, Vercel or Slack. The trigger shows the current workspace's logo and plan. The menu has search, your role in each workspace and a Cmd+1 to 9 shortcut for each, and lets you create or join a workspace inline. A highlight glides between rows, and switching crossfades the trigger through a short loading state.
- [Live visitors](https://uiarc.dev/components/live-visitors/markdown): A realtime visitors card where the live count rolls digit by digit, new arrivals ping in on a dotted world map, the top pages reorder with bars, and signups and upgrades tick in with country flags.
- [Social proof toast](https://uiarc.dev/components/social-proof-toast/markdown): A stack of social proof notifications for landing and pricing pages, where recent trials, upgrades and verified purchases from people and companies arrive every few seconds. The stack pauses and fans out on hover, and visitors can dismiss any toast.
- [Install snippet](https://uiarc.dev/components/install-snippet/markdown): A "get started in 30 seconds" card where framework tabs, three numbered steps and highlighted snippets take a developer from install to first event. Generate key wipes a fresh API key into the placeholder in place.

### Guidance for AI tools

PII redaction: A guardrail card where personal data is redacted before the prompt reaches the model. Scan marks each name, email, phone number and card with its type and swaps it for a placeholder like [EMAIL_1]. The safe prompt travels to Claude, and the reply comes back with the original values put back for the person. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Response feedback

> A feedback control for AI replies where thumbs down opens an inline panel with reason chips and an optional note, thumbs up fills and asks what was good, and a submit shows a short thank-you before folding back into the row.

- Type: Component (special)
- Access: Arc Pro
- Page: https://uiarc.dev/components/response-feedback
- Markdown: https://uiarc.dev/components/response-feedback/markdown
- Source file: `registry/components/response-feedback/response-feedback.tsx`
- Dependencies: motion, lucide-react, @radix-ui/react-tooltip
- Keywords: special, ai, new, thumbs up, thumbs down, feedback, ai feedback, response rating, message actions, rlhf, helpful, chat feedback, reasons, llm evaluation

### When to use

- Collecting thumbs up and down on AI replies in a chat, copilot or search answer.
- Gathering structured reasons (inaccurate, unsafe) for model evaluation or support triage.
- Adding a message action row with copy and regenerate next to feedback.

### When not to use

- Star or numeric ratings of a product or session: use rating.
- General product feedback not tied to one reply: use feedback-morph.
- Long surveys with many questions: use a form or dialog.

### Installation

Response feedback is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/response-feedback
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { FeedbackActions, ResponseFeedback } from "@/components/arc/response-feedback/response-feedback";

// The full reply card
<ResponseFeedback
  model={{ name: "Claude Opus 5.5" }}
  prompt={question}
  copyText={answerText}
  messageId={message.id}
  onFeedback={async (event, { signal }) => {
    await fetch("/api/feedback", { method: "POST", body: JSON.stringify(event), signal });
  }}
>
  <Markdown>{answerText}</Markdown>
</ResponseFeedback>

// Just the control, inside your own message row
<FeedbackActions
  messageId={message.id}
  defaultRating={message.rating}
  leading={<CopyButton value={answerText} iconOnly variant="plain" label="Copy reply" />}
  onFeedback={saveFeedback}
/>
```

### API reference

#### ResponseFeedback

An AI reply card: optional prompt bubble, model mark and name, the reply body and an action row with copy, optional regenerate and the thumbs feedback control. With no props it renders a sample Claude Sonnet 5.5 answer with simulated feedback. Accepts every FeedbackActions prop except leading.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `model` | `{ name: string; mark?: ReactNode }` | `{ name: "Claude Sonnet 5.5" }` | The model that wrote the reply. The mark is drawn at 16px and defaults to the Claude mark. |
| `prompt` | `ReactNode \| null` | – | The person's message shown above the reply. Defaults to a sample question; pass null to hide it. |
| `children` | `ReactNode` | – | The reply body. Paragraphs, lists and inline code are styled. Defaults to a sample Postgres answer. |
| `copyText` | `string \| null` | – | Plain text for the copy action. Defaults to the sample reply when no children are given; pass null to hide copy. |
| `onRegenerate` | `() => void` | – | Shows a regenerate action in the row. |
| `onFeedback` | `(event: FeedbackEvent, context: { signal: AbortSignal }) => void \| Promise<void>` | – | Persists feedback. Fires with stage "rating" on every thumb press and stage "details" when reasons or a note are submitted. Reject to show the inline error and Try again; the signal aborts when the panel closes or the rating changes. Without it, sends are simulated. |
| `messageId` | `string` | – | Passed back on every event so feedback can be stored against a message. |
| `rating` | `"up" \| "down" \| null` | – | Controlled rating. Leave undefined to let the control own it. |
| `defaultRating` | `"up" \| "down" \| null` | `null` | Initial rating when uncontrolled, for example a rating loaded from your database. |
| `onRatingChange` | `(rating: "up" \| "down" \| null) => void` | – | Called on every rating change, including clearing it by pressing the active thumb again. |
| `negativeReasons` | `string[]` | `["Inaccurate", "Not helpful", "Too long", "Unsafe", "Other"]` | Reason chips offered after a thumbs down. A chip labelled Other moves focus to the note and changes its placeholder. |
| `positiveReasons` | `string[]` | `["Accurate", "Easy to follow", "Good examples", "Saved me time"]` | Chips offered after a thumbs up. Pass [] to skip the follow-up row. |
| `allowComment` | `boolean` | `true` | Shows the optional note field after a thumbs down. |
| `commentPlaceholder` | `string` | `"Add details (optional)"` | Placeholder for the note field. |
| `commentMaxLength` | `number` | `1000` | Maximum note length. |
| `privacyNote` | `ReactNode` | `"Shares this reply for review"` | Quiet line next to Submit about what gets shared. Hidden below 400px of container width. |
| `thanksMessage` | `ReactNode` | – | Second line of the thank-you state. Defaults to a simulated note without onFeedback, otherwise "It helps improve future replies." |
| `thanksDuration` | `number` | `1600` | How long the thank-you state holds before the panel folds away, in ms. |
| `trailing` | `ReactNode` | – | Content pinned to the end of the row, such as a timestamp or token count. |
| `disabled` | `boolean` | `false` | Disables the thumbs, for example while the reply is still streaming. |
| `className` | `string` | – | Class on the root element. |

#### FeedbackActions

The feedback control on its own, for your own message rows: thumbs up and down, the reasons panel, the What was good row and the thank-you state.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `leading` | `ReactNode` | – | Actions rendered before the thumbs, such as copy or regenerate. Use 16px icons in control-height-sm buttons to match. |
| `onFeedback` | `(event: FeedbackEvent, context: { signal: AbortSignal }) => void \| Promise<void>` | – | Persists feedback. Fires with stage "rating" on every thumb press and stage "details" when reasons or a note are submitted. Reject to show the inline error and Try again; the signal aborts when the panel closes or the rating changes. Without it, sends are simulated. |
| `messageId` | `string` | – | Passed back on every event so feedback can be stored against a message. |
| `rating` | `"up" \| "down" \| null` | – | Controlled rating. Leave undefined to let the control own it. |
| `defaultRating` | `"up" \| "down" \| null` | `null` | Initial rating when uncontrolled, for example a rating loaded from your database. |
| `onRatingChange` | `(rating: "up" \| "down" \| null) => void` | – | Called on every rating change, including clearing it by pressing the active thumb again. |
| `negativeReasons` | `string[]` | `["Inaccurate", "Not helpful", "Too long", "Unsafe", "Other"]` | Reason chips offered after a thumbs down. A chip labelled Other moves focus to the note and changes its placeholder. |
| `positiveReasons` | `string[]` | `["Accurate", "Easy to follow", "Good examples", "Saved me time"]` | Chips offered after a thumbs up. Pass [] to skip the follow-up row. |
| `allowComment` | `boolean` | `true` | Shows the optional note field after a thumbs down. |
| `commentPlaceholder` | `string` | `"Add details (optional)"` | Placeholder for the note field. |
| `commentMaxLength` | `number` | `1000` | Maximum note length. |
| `privacyNote` | `ReactNode` | `"Shares this reply for review"` | Quiet line next to Submit about what gets shared. Hidden below 400px of container width. |
| `thanksMessage` | `ReactNode` | – | Second line of the thank-you state. Defaults to a simulated note without onFeedback, otherwise "It helps improve future replies." |
| `thanksDuration` | `number` | `1600` | How long the thank-you state holds before the panel folds away, in ms. |
| `trailing` | `ReactNode` | – | Content pinned to the end of the row, such as a timestamp or token count. |
| `disabled` | `boolean` | `false` | Disables the thumbs, for example while the reply is still streaming. |
| `className` | `string` | – | Class on the root element. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Tab | Moves through copy, thumbs up and thumbs down, then into the open panel. |
| Enter / Space | Presses a thumb, toggles a reason chip, or activates Submit, Send, Skip and Cancel. Pressing the active thumb clears the rating. |
| Escape | Closes the open panel and returns focus to the thumb that opened it. The rating stays. |
| Cmd / Ctrl + Enter | Submits from the note field. |

### Accessibility

- Thumbs are toggle buttons with aria-pressed and labels Good response and Bad response; aria-expanded and aria-controls point at the panel while it is open.
- Reason chips are toggle buttons with aria-pressed inside a labelled group. Selected chips invert to a solid fill, so the state never relies on hue.
- A keyboard press on thumbs down moves focus to the first reason; a pointer press leaves focus where it is. After a keyboard submit, focus lands on the thank-you line and returns to the thumb when the panel folds.
- A polite live region announces rating changes, sending, the thank-you state, errors, and says when nothing was sent because the send is simulated.
- Errors show an icon and text next to the actions, and Submit becomes Try again.

### Motion

- The panel opens and closes on a bounce-free spring (0.24s visual duration) that animates measured height, with a 160ms opacity fade.
- Switching between the form and the thank-you line is a single crossfade (out 100ms, in 160ms, 2px rise) while the panel height springs to the new content.
- The filled thumb fades in over 160ms on top of the outline, so nothing moves or resizes. Presses scale to .94 instantly and release on a spring.
- The success tick draws once in 280ms.
- Reduced motion: height changes cut instantly, the panel only fades, and press scales are dropped. All end states and announcements stay.

### Responsive behavior

- The card pads 16px below 480px of container width and 24px above; the panel and chips wrap, so it holds at 360px without horizontal scroll.
- Below 400px of container width the privacy note and Cancel give way (Close covers Cancel), so the error line and Try again always fit on one row.
- Chips grow to 32px tall on coarse pointers.

### Performance

- Two small motion trees (panel height and content crossfade) mount only while the panel is open.
- One ResizeObserver per open panel animates content height changes; it disconnects when the panel closes.
- No timers run while idle; the thank-you timer and in-flight sends are cleared on unmount.

### Notes for AI

- Use ResponseFeedback for a single assistant reply with its actions; use FeedbackActions when you already render your own messages.
- Persist both stages: store the rating on stage "rating" (null means cleared) and attach reasons and the note on stage "details". Always pass messageId.
- Throw or reject from onFeedback to show the error state; the component handles Try again and aborts stale calls through the signal.
- Set disabled while the reply is still streaming, so people rate the finished answer.
- Keep reason labels short (one or two words) so the chips stay on one or two lines at 360px.

### Related

- [Chat thread](https://uiarc.dev/components/chat-thread/markdown): A chat thread with grouped messages, reactions, read receipts, typing, and a composer with attachments.
- [Copy button](https://uiarc.dev/components/copy-button/markdown): Copy a value with immediate confirmation.
- [Tool call](https://uiarc.dev/components/tool-call/markdown): A tool call row for agent transcripts: the tool's mark and the call in plain words, a live state while it runs, and the input and output a click away, with approval and retry when needed.
- [Agent status](https://uiarc.dev/components/agent-status/markdown): A compact live status pill for a running AI agent: the agent's mark in a live ring, the current activity and an elapsed timer, opening into the steps so far.
- [Rating](https://uiarc.dev/components/rating/markdown): A simple, accessible way to capture a numeric opinion.

### Also in ai

- [Agent plan](https://uiarc.dev/components/agent-plan/markdown): The plan an agent writes before it acts: edit, reorder or add steps while it is a draft, then watch it work through them as a live checklist.
- [Agent timeline](https://uiarc.dev/components/agent-timeline/markdown): A compact timeline of one orchestrated agent run: the orchestrator and its subagents share a time axis, handoffs draw in between rows, and a playhead replays thinking, tool calls and waiting while the header counts time, tokens and cost. Hover a span for what it did, or click it to trace its handoff path.
- [Context window](https://uiarc.dev/components/context-window/markdown): An AI context window as a grid of 200 cells: the system prompt, tools, files, summary and messages fill it in order, a threshold row marks where compaction starts, and sending a message, attaching a file or compacting shows exactly how much still fits.
- [Reasoning block](https://uiarc.dev/components/reasoning-block/markdown): The collapsible thinking block of an AI reply. While the model thinks, a shimmering label counts the seconds and the latest reasoning streams underneath. When it finishes, it folds to "Thought for 7s" and opens to show the full reasoning as calm steps with headings.
- [Source cards](https://uiarc.dev/components/source-cards/markdown): A row of cited sources under an AI answer where cards stream in with real site marks while the model searches, the overflow collapses into a stack of favicons, hovering lifts a preview with the passage, and an inline [n] citation highlights its card.
- [Model card](https://uiarc.dev/components/model-card/markdown): A model details card where switching models rolls every price, limit and score in place, a token slider estimates monthly cost live, and benchmark bars show each model's rank on hover. Compare crossfades to a side-by-side table against any rival with the better values marked, and the card never changes size.
- [AI workflow](https://uiarc.dev/components/ai-workflow/markdown): A Linear-style AI workflow card where a Gmail trigger, a Claude step, a branch and Slack and Linear actions sit on one hairline rail, and a test run glides down it, opening each step's output inline. Steps are added from a compact command menu with real app marks.
- [Code suggestion](https://uiarc.dev/components/code-suggestion/markdown): An AI code edit suggestion where the model's proposed changes stream into a small editor panel as inline diff hunks, and you accept or reject each one, or all at once with Cmd+Enter. Accepted hunks fold into the file with a smooth height change.
- [Ghost text](https://uiarc.dev/components/ghost-text/markdown): An inline AI autocomplete where muted ghost text continues your sentence exactly at the caret and Tab turns it solid in place. Cmd+Right takes it one word at a time, Escape fades it away, and a calm chip shows the model behind it.
- [Image generation](https://uiarc.dev/components/image-generation/markdown): An image studio where each image forms on a dot matrix: a soft halftone wave breathes across the grid, the dots take the colours of the coming photo and grow into a coloured halftone, then blur away into the sharp photo. One large canvas with a mono size label, a filmstrip of four variations, a prompt bar with model and ratio, and upscale with a sweeping dot band, vary or download, with real provider marks and a built-in simulation.
- [Dictation button](https://uiarc.dev/components/dictation-button/markdown): A chat composer with voice input, where the mic springs into a recording pill with a smooth live waveform, a timer, and cancel and insert buttons. Words stream into the field as you speak, muted until the recognizer settles them.
- [Speech player](https://uiarc.dev/components/speech-player/markdown): A read-aloud player for AI replies. The Read aloud button in the message's action row turns into a compact player with play, a scrubbable progress bar, speed and a voice picker, and a highlight follows the spoken word through the reply, karaoke style.
- [Meeting summary](https://uiarc.dev/components/meeting-summary/markdown): An AI meeting notes card: the header shows the Google Meet or Zoom mark, the attendees and the duration. Summary, Decisions and Action items stream in after a short summarizing pass. Hover any line to see the transcript quote it came from, then check off action items or send them to Linear or Notion.
- [Reply draft](https://uiarc.dev/components/reply-draft/markdown): An AI email reply drafter where Claude streams a reply under a received Gmail message. Quick replies steer a fresh draft, tone and length rewrite it with a single crossfade, and you can edit the finished draft before you insert it.
- [Agent handoff](https://uiarc.dev/components/agent-handoff/markdown): A support conversation where an AI assistant hands off to a person. When it transfers, a card shows the summary it passes to the team and the typical wait. The person then joins and takes over, and a thin timeline on the left marks each step.
- [PII redaction](https://uiarc.dev/components/pii-redaction/markdown): A guardrail card where personal data is redacted before the prompt reaches the model. Scan marks each name, email, phone number and card with its type and swaps it for a placeholder like [EMAIL_1]. The safe prompt travels to Claude, and the reply comes back with the original values put back for the person.
- [LLM cost calculator](https://uiarc.dev/components/llm-cost-calculator/markdown): A pricing calculator for LLM workloads. Set tokens per request, requests per day and prompt caching, and eight current models re-rank by monthly cost. Bars glide and prices roll as you drag.
- [Provider keys](https://uiarc.dev/components/provider-keys/markdown): A settings card for bring-your-own-key AI products. Each provider row shows its real mark, the masked key, a status and when the key was last used. You can reveal a key for five seconds, copy, rotate or remove it with undo. Adding or rotating a key opens an inline form that checks the format as you type, then tests the connection before saving.
- [Generation stats](https://uiarc.dev/components/generation-stats/markdown): A live stats strip for a streaming LLM response where time to first token, speed with a sparkline, output tokens and cost count up in tabular numerals beside the model's real mark, then settle and open into a latency and token cost breakdown.
- [AI translate](https://uiarc.dev/components/ai-translate/markdown): A message card where picking a language streams the AI translation in place, sentence by sentence over the dimmed original, with a detected-language chip, a Show original toggle and a status line credited to the model's mark.
- [TL;DR toggle](https://uiarc.dev/components/tldr-toggle/markdown): An article card with a Full, Summary and Key points switch and a length slider. Switching streams an AI summary in place of the article as the card's height springs to fit, and each key point links back to the paragraph it came from, which gets scrolled to and highlighted.
- [Connector setup](https://uiarc.dev/components/connector-setup/markdown): A "Connect your tools" card for an AI assistant. Each app connects inline: it redirects, authorizes and runs a first sync with a progress hairline, then lists the scopes it was granted and offers Disconnect with an inline confirm.
- [Smart form fill](https://uiarc.dev/components/smart-form-fill/markdown): A paste-to-fill form card where AI reads an email signature or messy notes and fills a contact field by field. Each value flashes in with a confidence dot, its source lights up in the pasted text, low-confidence guesses ask for review, and Undo puts the old values back.
- [Enrich column](https://uiarc.dev/components/enrich-column/markdown): An AI enrichment column for a data table, where one prompt runs down every row and each cell shimmers while it works, then settles into a value with its source or a failure you can retry.
- [Ticket router](https://uiarc.dev/components/ticket-router/markdown): A support ticket router where messages from Gmail, Intercom, Slack and Zendesk come in one at a time. An AI classifier labels each one with intent, sentiment and confidence, and the ticket moves into a team lane with an assignee. Low confidence tickets wait in a review lane, and one click there routes them to the suggested team.
- [Ask your data](https://uiarc.dev/components/ask-your-data/markdown): A natural language to chart card: you ask a question, PostgreSQL streams into a collapsible, syntax highlighted panel, the query runs with a rolling row count, and the answer builds as stacked bars, lines or a table, with a one line insight streamed in underneath.
- [Agent cursor](https://uiarc.dev/components/agent-cursor/markdown): A live document where Claude edits like a collaborator. Its labeled cursor comes out of its avatar, selects a paragraph and streams in a rewrite, adds a heading and fixes a typo, while a teammate's cursor reads along. Changes stay tinted until someone accepts or undoes them from a floating review bar.
- [Provider status](https://uiarc.dev/components/provider-status/markdown): A status card for the AI providers your product depends on. Each row shows the provider's real mark, its health as an icon and label, p50 latency and a 30-day uptime bar with a tooltip for each day. An incident row expands into its timeline of updates, and the card checks again on a visible countdown.
- [Training run](https://uiarc.dev/components/training-run/markdown): A fine-tuning job card where a live train and validation loss curve draws across a fixed step axis that doubles as the epoch progress bar. It shows the learning rate, elapsed time, ETA and the latest evals and checkpoints, has Pause and Cancel while it runs, and ends in results with a Deploy button.
- [AI command](https://uiarc.dev/components/ai-command/markdown): A Cmd+K command palette with an AI mode. Search pages and actions, or press Tab to ask a question: the answer streams inside the palette with numbered sources, and the next steps it suggests, like filing a Linear issue or opening a Notion doc, run straight from the list.
- [Starter prompts](https://uiarc.dev/components/starter-prompts/markdown): A greeting and a grid of starter cards for the empty state of an AI app. The cards are grouped into Write, Code, Analyze and Plan tabs, and a shuffle swaps them with a short staggered crossfade. Picking a card fills the composer, and cards that use a connected app show its mark (Gmail, GitHub, Notion, Linear, Google Calendar).
- [AI mascot](https://uiarc.dev/components/ai-mascot/markdown): A small assistant character, a soft pebble with pill eyes and a companion dot, that shows what the AI is doing. It breathes and glances when idle, leans in to listen, looks up while the dot orbits its head, reads along the line it writes, squints with a sparkle when done and shakes once with worried brows on an error.
- [Image reveal](https://uiarc.dev/components/image-reveal/markdown): An image generation canvas where a soft, blurred preview made from the image's own colors sharpens top to bottom behind a soft-edged band. It works the way ChatGPT, Midjourney and Gemini show images forming, with fine film grain, a translucent progress pill and calm queued and error states.
- [AI spark](https://uiarc.dev/components/ai-spark/markdown): A brand-quality animated spark mark. Four tapered rays and four lighter diagonals breathe at rest, ripple while thinking, pulse like a heartbeat while writing, then gather and settle when done. Every status change blends from the pose the mark is already in.
- [Pixel mascot](https://uiarc.dev/components/pixel-mascot/markdown): A pixel-art robot that shows what an AI assistant is doing. It idles, thinks, types, celebrates and errors in frame-stepped sprite animations, and stays crisp at every integer size from 24px to 192px.
- [Ghost mascot](https://uiarc.dev/components/ghost-mascot/markdown): A floating ghost mascot whose soft sheet ripples at the hem while it hovers. It blinks when idle, turns toward you to listen, fades a little translucent while thinking, draws a tiny pen line while writing, smiles with a sparkle when done and wobbles once on an error.
- [Cube mascot](https://uiarc.dev/components/cube-mascot/markdown): An isometric cube mascot where three shaded faces and a painted-on face show what the assistant is doing. It turns a quarter turn in eased steps while thinking, prints lines onto the floor while writing, settles with a sparkle when done, and shakes once on error.
- [Tone tuner](https://uiarc.dev/components/tone-tuner/markdown): A brand voice card where two sliders (formality and detail) and Friendly, Confident and Empathetic chips rewrite a customer reply. Each changed sentence crossfades in place, new words can be highlighted against the original, and Copy takes the current version.
- [Upgrade prompt](https://uiarc.dev/components/upgrade-prompt/markdown): An upgrade nudge for the moment someone hits a limit. It shows a usage meter at 50 of 50 AI credits, a rolling price with a monthly and yearly toggle, three concrete unlocks with real model marks, and Upgrade or Maybe later. Upgrading leads into a success state with the new limits, and the card never changes size between states.
- [Referral card](https://uiarc.dev/components/referral-card/markdown): A give-and-get referral card where people copy or share their invite link, invite friends by email as chips, and watch invites move from invited to signed up to earned, with the credit total counting up and a milestone reward unlocking.
- [Trial banner](https://uiarc.dev/components/trial-banner/markdown): A trial status banner where a ring counts down the days left, the copy names what the workspace loses, and the upgrade path is one click away. It comes as a slim banner, a sidebar card or a header pill. It shifts to a warning tone in the last days, has expired and upgraded states, and folds into the pill when dismissed or snoozed.
- [Team switcher](https://uiarc.dev/components/team-switcher/markdown): A workspace switcher like Linear, Vercel or Slack. The trigger shows the current workspace's logo and plan. The menu has search, your role in each workspace and a Cmd+1 to 9 shortcut for each, and lets you create or join a workspace inline. A highlight glides between rows, and switching crossfades the trigger through a short loading state.
- [Live visitors](https://uiarc.dev/components/live-visitors/markdown): A realtime visitors card where the live count rolls digit by digit, new arrivals ping in on a dotted world map, the top pages reorder with bars, and signups and upgrades tick in with country flags.
- [Social proof toast](https://uiarc.dev/components/social-proof-toast/markdown): A stack of social proof notifications for landing and pricing pages, where recent trials, upgrades and verified purchases from people and companies arrive every few seconds. The stack pauses and fans out on hover, and visitors can dismiss any toast.
- [Install snippet](https://uiarc.dev/components/install-snippet/markdown): A "get started in 30 seconds" card where framework tabs, three numbered steps and highlighted snippets take a developer from install to first event. Generate key wipes a fresh API key into the placeholder in place.

### Guidance for AI tools

Response feedback: A feedback control for AI replies where thumbs down opens an inline panel with reason chips and an optional note, thumbs up fills and asks what was good, and a submit shows a short thank-you before folding back into the row. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## LLM cost calculator

> A pricing calculator for LLM workloads. Set tokens per request, requests per day and prompt caching, and eight current models re-rank by monthly cost. Bars glide and prices roll as you drag.

- Type: Component (special)
- Access: Arc Pro
- Page: https://uiarc.dev/components/llm-cost-calculator
- Markdown: https://uiarc.dev/components/llm-cost-calculator/markdown
- Source file: `registry/components/llm-cost-calculator/llm-cost-calculator.tsx`
- Dependencies: motion, lucide-react
- Keywords: special, ai, new, llm cost calculator, token pricing, ai pricing, model cost, api cost estimate, prompt caching, cached input, price comparison, claude, gpt, gemini, deepseek, monthly cost, budget, slider

### When to use

- A pricing or settings page needs an honest monthly estimate for an LLM workload across several models.
- People pick a model for a feature and should see how cost moves with prompt size, output length, traffic and caching.
- An internal tool compares provider prices before a migration or a budget review.

### When not to use

- Use model-picker to choose a model in a chat or composer without a cost comparison.
- Use context-window to show the live token usage of one conversation against a model's context window.
- Use usage-meter or usage-pricing for actual metered spend against a plan; this estimates, it does not report.

### Installation

LLM cost calculator is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/llm-cost-calculator
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { LlmCostCalculator, computeLlmCost, type LlmModelPrice } from "@/components/arc/llm-cost-calculator/llm-cost-calculator";

// With no props: eight current models at sample prices, RAG workload.
export function PricingSection() {
  return <LlmCostCalculator />;
}

// Your own price list, wired to your plan picker.
const models: LlmModelPrice[] = [
  { id: "claude-sonnet-5-5", name: "Claude Sonnet 5.5", provider: "Anthropic", mark: <ClaudeMark />, input: 3, cachedInput: 0.3, output: 15 },
  { id: "gpt-6-luna", name: "GPT-6 Luna", provider: "OpenAI", mark: <OpenaiMark />, input: 0.25, cachedInput: 0.025, output: 3 },
];

export function ModelBudget({ prices, onPick }) {
  const [usage, setUsage] = useState({ inputTokens: 8000, outputTokens: 500, requestsPerDay: 20000, cached: true });
  return (
    <LlmCostCalculator
      models={prices.data ?? models}
      loading={prices.isLoading}
      error={prices.error?.message}
      onRetry={prices.refetch}
      usage={usage}
      onUsageChange={setUsage}
      cacheHitRate={0.7}
      description="List prices per 1M tokens, checked October 24, 2026"
      onSelectedChange={(id, model) => onPick(model, computeLlmCost(model, usage, { cacheHitRate: 0.7 }))}
    />
  );
}
```

### API reference

#### LlmCostCalculator

A pricing calculator for LLM workloads in one panel. The header shows the selected model's monthly total in a large rolling figure. Below it, workload presets (Chat, RAG, Agent, Batch), three sliders for input tokens per request, output tokens per request and requests per day, and a Cached input switch that bills part of the input at the cache read rate. Every model sits in a ranked list, lowest cost first, with its real mark, a bar relative to the most expensive model and a rolling monthly cost; rows glide to their new rank as values change. Picking a row selects that model for the total and the footer breakdown (input, cached, output, per request) and its price line. With no props it compares eight current models at sample prices.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `models` | `LlmModelPrice[]` | `llmCostSampleModels` | Models to compare. Each has an id, name, provider, an optional 16px mark, and prices in US dollars per 1M tokens: input, output and optional cachedInput (cache reads; without it cached tokens bill at the input price). An empty array shows the empty state. |
| `usage` | `LlmUsage` | – | Controlled workload: { inputTokens, outputTokens, requestsPerDay, cached }. Pair with onUsageChange. Values between slider stops still compute exactly; the slider shows the nearest stop. |
| `defaultUsage` | `LlmUsage` | `the RAG preset (16,000 in, 500 out, 5,000 a day, cached)` | Starting workload when uncontrolled. |
| `onUsageChange` | `(usage: LlmUsage) => void` | – | Called on every slider step, preset and cache toggle with the whole workload. |
| `selected` | `string` | – | Controlled id of the selected model. Pair with onSelectedChange. An id that is not in models falls back to the cheapest model. |
| `defaultSelected` | `string` | `the second model` | Starting selection when uncontrolled. |
| `onSelectedChange` | `(id: string, model: LlmModelPrice) => void` | – | Called when someone picks a row by pointer or with the arrow keys. |
| `presets` | `LlmUsagePreset[] \| false` | `llmCostPresets` | Workload shortcuts shown as a segmented control, each { id, label, usage }. A Custom segment lights up when the sliders match no preset. Pass false to hide the row. |
| `cacheHitRate` | `number` | `0.6` | Share of input tokens billed at the cached rate while Cached input is on, from 0 to 1. Shown beside the switch as a percentage. |
| `daysPerMonth` | `number` | `30` | Days in a billing month. |
| `loading` | `boolean` | `false` | Shows placeholder rows with the list's exact geometry and disables the controls while prices load. |
| `error` | `string` | – | Shows "Prices did not load" with this reason in place of the list. Pair with onRetry. |
| `onRetry` | `() => void` | – | Adds a Try again button to the error state. |
| `title` | `string` | `"Estimated monthly cost"` | Heading of the panel. |
| `description` | `string` | `"Sample list prices per 1M tokens, October 2026"` | Line under the heading. Say where your prices come from and when they were checked. |
| `note` | `string` | `"Sample prices for illustration, not a quote. Calculated in your browser, nothing was sent."` | Fine print at the bottom of the panel. |
| `className` | `string` | – | Class on the root section. |

#### computeLlmCost

The function the calculator uses, exported for server code, tests and invoices: computeLlmCost(model, usage, { cacheHitRate, daysPerMonth }) returns { input, cachedInput, output, total, perRequest } in dollars per month (perRequest per call).

No props.

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Tab | Moves through the workload presets, the three sliders, the Cached input switch, the selected model row, then Try again in the error state. |
| Arrow left / Arrow right | On the presets, moves between workloads. On a slider, moves one stop. |
| Page up / Page down, Shift + Arrow | On a slider, moves two stops. |
| Home / End | On a slider, jumps to the smallest or largest stop. In the model list, selects the cheapest or most expensive model. |
| Arrow up / Arrow down | In the model list, selects the next or previous model by rank and moves focus with it. |
| Space | Toggles Cached input. |

### Accessibility

- The panel is a section named by its heading. The model list is a radio group named "Models ranked by monthly cost, lowest first" with a single tab stop on the selected model.
- Rows are in DOM order by rank, so a screen reader reads them in the order shown. Each row's name says the model, the provider, its rank and its monthly cost.
- Sliders are Arc sliders with real values spoken as token and request counts, not stop indexes.
- One polite status region announces the selected model's monthly cost and rank once the numbers settle (not on every drag frame) and says the prices are samples calculated in the browser.
- Selection is shown by a tinted row, an accent bar and aria-checked, never by color alone in the accessible tree. The error state pairs an icon with the words Prices did not load.
- The large total and the rolling numbers are hidden from assistive tech where the status region and row labels already carry the value.
- Pointer focus draws no ring; keyboard focus uses Arc's shared focus ring.

### Motion

- Rows are placed by transform only and move to their new rank on a critically damped spring (about 240ms, no bounce), so a re-rank is one clean glide with no reflow.
- Bars follow the same spring to their new share of the most expensive model.
- Every price counts to its new value over 240ms on an ease-out with tabular numerals, written straight to the node so eight rows roll during a drag without re-rendering.
- The model name under the total and the price line crossfade (100ms out, 160ms in) when the selection changes. State changes between loading, list, error and empty crossfade the list area at a fixed height.
- Reduced motion jumps rows, bars and numbers to their end values and keeps every state and announcement. The loading pulse stops.

### Responsive behavior

- A container query stacks the sliders below 600px and, below 520px, moves the total under the heading, puts each bar on its own line under the model name (rows grow from 44 to 58px), and wraps the breakdown into two columns.
- Monthly costs switch to compact figures ($420K, $4.2M) above $100,000, so the cost column never overflows; the total keeps every digit.
- The presets scroll inside their own track if they ever outgrow the panel. Reads well from 320px to 720px; the panel caps at 720px.

### Performance

- Costs are pure arithmetic memoized per workload; a slider drag re-renders one small list.
- Rolling numbers update text nodes from a motion value, not React state, and only transform, width and opacity animate.
- The status announcement is debounced to 450ms so screen readers are not flooded during a drag. Nothing runs while the panel is idle.

### Notes for AI

- Use it on a pricing page, a model settings screen or a budgeting step where people need to see what a workload costs across models. Prices are inputs: pass your own models with current list prices and say where they came from in description.
- The default prices are plausible samples for illustration, labeled as samples in the header and fine print. Do not present them as real quotes.
- Prices are US dollars per 1M tokens. cachedInput is the cache read price; cacheHitRate decides what share of input bills at it while Cached input is on.
- Keep marks 16px. Mono marks should use currentColor; the sample Claude mark is tinted with its brand color #D97757 and works in both themes.
- Use computeLlmCost on the server for the same numbers the panel shows, for example to store an estimate with a plan.
- Slider stops are fixed (250 to 200,000 input tokens, 100 to 16,000 output tokens, 100 to 1,000,000 requests a day). Controlled usage outside a stop still computes exactly.

### Related

- [Model picker](https://uiarc.dev/components/blocks/model-picker/markdown): A model picker in one quiet pill: open it to choose from featured models with a one line note each, set the reasoning effort, or browse every other model by provider, and the pill swaps to your choice in place.
- [Model card](https://uiarc.dev/components/model-card/markdown): A model details card where switching models rolls every price, limit and score in place, a token slider estimates monthly cost live, and benchmark bars show each model's rank on hover. Compare crossfades to a side-by-side table against any rival with the better values marked, and the card never changes size.
- [Context window](https://uiarc.dev/components/context-window/markdown): An AI context window as a grid of 200 cells: the system prompt, tools, files, summary and messages fill it in order, a threshold row marks where compaction starts, and sending a message, attaching a file or compacting shows exactly how much still fits.
- [Usage meter](https://uiarc.dev/components/usage-meter/markdown): Show what fills an allowance and how close it is to the limit.
- [Usage pricing](https://uiarc.dev/components/blocks/usage-pricing/markdown): A pricing calculator that finds your plan as you drag seats and traffic.
- [Slider](https://uiarc.dev/components/slider/markdown): Pick a value or a range on a track that follows your finger.

### Also in ai

- [Agent status](https://uiarc.dev/components/agent-status/markdown): A compact live status pill for a running AI agent: the agent's mark in a live ring, the current activity and an elapsed timer, opening into the steps so far.
- [Tool call](https://uiarc.dev/components/tool-call/markdown): A tool call row for agent transcripts: the tool's mark and the call in plain words, a live state while it runs, and the input and output a click away, with approval and retry when needed.
- [Agent plan](https://uiarc.dev/components/agent-plan/markdown): The plan an agent writes before it acts: edit, reorder or add steps while it is a draft, then watch it work through them as a live checklist.
- [Agent timeline](https://uiarc.dev/components/agent-timeline/markdown): A compact timeline of one orchestrated agent run: the orchestrator and its subagents share a time axis, handoffs draw in between rows, and a playhead replays thinking, tool calls and waiting while the header counts time, tokens and cost. Hover a span for what it did, or click it to trace its handoff path.
- [Reasoning block](https://uiarc.dev/components/reasoning-block/markdown): The collapsible thinking block of an AI reply. While the model thinks, a shimmering label counts the seconds and the latest reasoning streams underneath. When it finishes, it folds to "Thought for 7s" and opens to show the full reasoning as calm steps with headings.
- [Source cards](https://uiarc.dev/components/source-cards/markdown): A row of cited sources under an AI answer where cards stream in with real site marks while the model searches, the overflow collapses into a stack of favicons, hovering lifts a preview with the passage, and an inline [n] citation highlights its card.
- [AI workflow](https://uiarc.dev/components/ai-workflow/markdown): A Linear-style AI workflow card where a Gmail trigger, a Claude step, a branch and Slack and Linear actions sit on one hairline rail, and a test run glides down it, opening each step's output inline. Steps are added from a compact command menu with real app marks.
- [Code suggestion](https://uiarc.dev/components/code-suggestion/markdown): An AI code edit suggestion where the model's proposed changes stream into a small editor panel as inline diff hunks, and you accept or reject each one, or all at once with Cmd+Enter. Accepted hunks fold into the file with a smooth height change.
- [Ghost text](https://uiarc.dev/components/ghost-text/markdown): An inline AI autocomplete where muted ghost text continues your sentence exactly at the caret and Tab turns it solid in place. Cmd+Right takes it one word at a time, Escape fades it away, and a calm chip shows the model behind it.
- [Image generation](https://uiarc.dev/components/image-generation/markdown): An image studio where each image forms on a dot matrix: a soft halftone wave breathes across the grid, the dots take the colours of the coming photo and grow into a coloured halftone, then blur away into the sharp photo. One large canvas with a mono size label, a filmstrip of four variations, a prompt bar with model and ratio, and upscale with a sweeping dot band, vary or download, with real provider marks and a built-in simulation.
- [Dictation button](https://uiarc.dev/components/dictation-button/markdown): A chat composer with voice input, where the mic springs into a recording pill with a smooth live waveform, a timer, and cancel and insert buttons. Words stream into the field as you speak, muted until the recognizer settles them.
- [Speech player](https://uiarc.dev/components/speech-player/markdown): A read-aloud player for AI replies. The Read aloud button in the message's action row turns into a compact player with play, a scrubbable progress bar, speed and a voice picker, and a highlight follows the spoken word through the reply, karaoke style.
- [Meeting summary](https://uiarc.dev/components/meeting-summary/markdown): An AI meeting notes card: the header shows the Google Meet or Zoom mark, the attendees and the duration. Summary, Decisions and Action items stream in after a short summarizing pass. Hover any line to see the transcript quote it came from, then check off action items or send them to Linear or Notion.
- [Reply draft](https://uiarc.dev/components/reply-draft/markdown): An AI email reply drafter where Claude streams a reply under a received Gmail message. Quick replies steer a fresh draft, tone and length rewrite it with a single crossfade, and you can edit the finished draft before you insert it.
- [Agent handoff](https://uiarc.dev/components/agent-handoff/markdown): A support conversation where an AI assistant hands off to a person. When it transfers, a card shows the summary it passes to the team and the typical wait. The person then joins and takes over, and a thin timeline on the left marks each step.
- [PII redaction](https://uiarc.dev/components/pii-redaction/markdown): A guardrail card where personal data is redacted before the prompt reaches the model. Scan marks each name, email, phone number and card with its type and swaps it for a placeholder like [EMAIL_1]. The safe prompt travels to Claude, and the reply comes back with the original values put back for the person.
- [Response feedback](https://uiarc.dev/components/response-feedback/markdown): A feedback control for AI replies where thumbs down opens an inline panel with reason chips and an optional note, thumbs up fills and asks what was good, and a submit shows a short thank-you before folding back into the row.
- [Provider keys](https://uiarc.dev/components/provider-keys/markdown): A settings card for bring-your-own-key AI products. Each provider row shows its real mark, the masked key, a status and when the key was last used. You can reveal a key for five seconds, copy, rotate or remove it with undo. Adding or rotating a key opens an inline form that checks the format as you type, then tests the connection before saving.
- [Generation stats](https://uiarc.dev/components/generation-stats/markdown): A live stats strip for a streaming LLM response where time to first token, speed with a sparkline, output tokens and cost count up in tabular numerals beside the model's real mark, then settle and open into a latency and token cost breakdown.
- [AI translate](https://uiarc.dev/components/ai-translate/markdown): A message card where picking a language streams the AI translation in place, sentence by sentence over the dimmed original, with a detected-language chip, a Show original toggle and a status line credited to the model's mark.
- [TL;DR toggle](https://uiarc.dev/components/tldr-toggle/markdown): An article card with a Full, Summary and Key points switch and a length slider. Switching streams an AI summary in place of the article as the card's height springs to fit, and each key point links back to the paragraph it came from, which gets scrolled to and highlighted.
- [Connector setup](https://uiarc.dev/components/connector-setup/markdown): A "Connect your tools" card for an AI assistant. Each app connects inline: it redirects, authorizes and runs a first sync with a progress hairline, then lists the scopes it was granted and offers Disconnect with an inline confirm.
- [Smart form fill](https://uiarc.dev/components/smart-form-fill/markdown): A paste-to-fill form card where AI reads an email signature or messy notes and fills a contact field by field. Each value flashes in with a confidence dot, its source lights up in the pasted text, low-confidence guesses ask for review, and Undo puts the old values back.
- [Enrich column](https://uiarc.dev/components/enrich-column/markdown): An AI enrichment column for a data table, where one prompt runs down every row and each cell shimmers while it works, then settles into a value with its source or a failure you can retry.
- [Ticket router](https://uiarc.dev/components/ticket-router/markdown): A support ticket router where messages from Gmail, Intercom, Slack and Zendesk come in one at a time. An AI classifier labels each one with intent, sentiment and confidence, and the ticket moves into a team lane with an assignee. Low confidence tickets wait in a review lane, and one click there routes them to the suggested team.
- [Ask your data](https://uiarc.dev/components/ask-your-data/markdown): A natural language to chart card: you ask a question, PostgreSQL streams into a collapsible, syntax highlighted panel, the query runs with a rolling row count, and the answer builds as stacked bars, lines or a table, with a one line insight streamed in underneath.
- [Agent cursor](https://uiarc.dev/components/agent-cursor/markdown): A live document where Claude edits like a collaborator. Its labeled cursor comes out of its avatar, selects a paragraph and streams in a rewrite, adds a heading and fixes a typo, while a teammate's cursor reads along. Changes stay tinted until someone accepts or undoes them from a floating review bar.
- [Provider status](https://uiarc.dev/components/provider-status/markdown): A status card for the AI providers your product depends on. Each row shows the provider's real mark, its health as an icon and label, p50 latency and a 30-day uptime bar with a tooltip for each day. An incident row expands into its timeline of updates, and the card checks again on a visible countdown.
- [Training run](https://uiarc.dev/components/training-run/markdown): A fine-tuning job card where a live train and validation loss curve draws across a fixed step axis that doubles as the epoch progress bar. It shows the learning rate, elapsed time, ETA and the latest evals and checkpoints, has Pause and Cancel while it runs, and ends in results with a Deploy button.
- [AI command](https://uiarc.dev/components/ai-command/markdown): A Cmd+K command palette with an AI mode. Search pages and actions, or press Tab to ask a question: the answer streams inside the palette with numbered sources, and the next steps it suggests, like filing a Linear issue or opening a Notion doc, run straight from the list.
- [Starter prompts](https://uiarc.dev/components/starter-prompts/markdown): A greeting and a grid of starter cards for the empty state of an AI app. The cards are grouped into Write, Code, Analyze and Plan tabs, and a shuffle swaps them with a short staggered crossfade. Picking a card fills the composer, and cards that use a connected app show its mark (Gmail, GitHub, Notion, Linear, Google Calendar).
- [AI mascot](https://uiarc.dev/components/ai-mascot/markdown): A small assistant character, a soft pebble with pill eyes and a companion dot, that shows what the AI is doing. It breathes and glances when idle, leans in to listen, looks up while the dot orbits its head, reads along the line it writes, squints with a sparkle when done and shakes once with worried brows on an error.
- [Image reveal](https://uiarc.dev/components/image-reveal/markdown): An image generation canvas where a soft, blurred preview made from the image's own colors sharpens top to bottom behind a soft-edged band. It works the way ChatGPT, Midjourney and Gemini show images forming, with fine film grain, a translucent progress pill and calm queued and error states.
- [AI spark](https://uiarc.dev/components/ai-spark/markdown): A brand-quality animated spark mark. Four tapered rays and four lighter diagonals breathe at rest, ripple while thinking, pulse like a heartbeat while writing, then gather and settle when done. Every status change blends from the pose the mark is already in.
- [Pixel mascot](https://uiarc.dev/components/pixel-mascot/markdown): A pixel-art robot that shows what an AI assistant is doing. It idles, thinks, types, celebrates and errors in frame-stepped sprite animations, and stays crisp at every integer size from 24px to 192px.
- [Ghost mascot](https://uiarc.dev/components/ghost-mascot/markdown): A floating ghost mascot whose soft sheet ripples at the hem while it hovers. It blinks when idle, turns toward you to listen, fades a little translucent while thinking, draws a tiny pen line while writing, smiles with a sparkle when done and wobbles once on an error.
- [Cube mascot](https://uiarc.dev/components/cube-mascot/markdown): An isometric cube mascot where three shaded faces and a painted-on face show what the assistant is doing. It turns a quarter turn in eased steps while thinking, prints lines onto the floor while writing, settles with a sparkle when done, and shakes once on error.
- [Tone tuner](https://uiarc.dev/components/tone-tuner/markdown): A brand voice card where two sliders (formality and detail) and Friendly, Confident and Empathetic chips rewrite a customer reply. Each changed sentence crossfades in place, new words can be highlighted against the original, and Copy takes the current version.
- [Upgrade prompt](https://uiarc.dev/components/upgrade-prompt/markdown): An upgrade nudge for the moment someone hits a limit. It shows a usage meter at 50 of 50 AI credits, a rolling price with a monthly and yearly toggle, three concrete unlocks with real model marks, and Upgrade or Maybe later. Upgrading leads into a success state with the new limits, and the card never changes size between states.
- [Referral card](https://uiarc.dev/components/referral-card/markdown): A give-and-get referral card where people copy or share their invite link, invite friends by email as chips, and watch invites move from invited to signed up to earned, with the credit total counting up and a milestone reward unlocking.
- [Trial banner](https://uiarc.dev/components/trial-banner/markdown): A trial status banner where a ring counts down the days left, the copy names what the workspace loses, and the upgrade path is one click away. It comes as a slim banner, a sidebar card or a header pill. It shifts to a warning tone in the last days, has expired and upgraded states, and folds into the pill when dismissed or snoozed.
- [Team switcher](https://uiarc.dev/components/team-switcher/markdown): A workspace switcher like Linear, Vercel or Slack. The trigger shows the current workspace's logo and plan. The menu has search, your role in each workspace and a Cmd+1 to 9 shortcut for each, and lets you create or join a workspace inline. A highlight glides between rows, and switching crossfades the trigger through a short loading state.
- [Live visitors](https://uiarc.dev/components/live-visitors/markdown): A realtime visitors card where the live count rolls digit by digit, new arrivals ping in on a dotted world map, the top pages reorder with bars, and signups and upgrades tick in with country flags.
- [Social proof toast](https://uiarc.dev/components/social-proof-toast/markdown): A stack of social proof notifications for landing and pricing pages, where recent trials, upgrades and verified purchases from people and companies arrive every few seconds. The stack pauses and fans out on hover, and visitors can dismiss any toast.
- [Install snippet](https://uiarc.dev/components/install-snippet/markdown): A "get started in 30 seconds" card where framework tabs, three numbered steps and highlighted snippets take a developer from install to first event. Generate key wipes a fresh API key into the placeholder in place.

### Guidance for AI tools

LLM cost calculator: A pricing calculator for LLM workloads. Set tokens per request, requests per day and prompt caching, and eight current models re-rank by monthly cost. Bars glide and prices roll as you drag. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Provider keys

> A settings card for bring-your-own-key AI products. Each provider row shows its real mark, the masked key, a status and when the key was last used. You can reveal a key for five seconds, copy, rotate or remove it with undo. Adding or rotating a key opens an inline form that checks the format as you type, then tests the connection before saving.

- Type: Component (special)
- Access: Arc Pro
- Page: https://uiarc.dev/components/provider-keys
- Markdown: https://uiarc.dev/components/provider-keys/markdown
- Source file: `registry/components/provider-keys/provider-keys.tsx`
- Dependencies: motion, lucide-react, @radix-ui/react-tooltip
- Keywords: special, ai, new, api keys, provider keys, byok, bring your own key, anthropic api key, openai api key, secret, settings, rotate key, masked key, connection test

### When to use

- A settings page where users add their own Anthropic, OpenAI, Google AI, Mistral or xAI keys.
- Showing which providers are connected, which keys were rejected, and when each key was last used.
- Letting users rotate a leaked key or remove one with a short undo window.

### When not to use

- Choosing a model for a request; use model-picker.
- Managing your own product's API keys for customers with scopes and expiry; use secret-rotation or a table.
- Showing spend or rate limits; use usage-meter.

### Installation

Provider keys is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/provider-keys
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { ProviderKeys } from "@/components/arc/provider-keys/provider-keys";

// Sample workspace, every test simulated
<ProviderKeys />

// Wired to your API
<ProviderKeys
  keys={keys}
  onKeysChange={setKeys}
  testKey={({ provider, key, signal }) =>
    fetch("/api/provider-keys/test", { method: "POST", body: JSON.stringify({ provider, key }), signal }).then(r => r.json())}
  onSave={(provider, key) => saveKey(provider, key)}
  onRemove={provider => deleteKey(provider)}
/>
```

### API reference

#### ProviderKeys

A settings card for bring your own key AI products. One row per provider (Anthropic, OpenAI, Google AI, Mistral, xAI) with its real mark, the masked key (sk-ant-••••4f2a), a status as icon plus label (Connected, Invalid, Not set), when the key was last used, and four actions: reveal for five seconds with a countdown ring, copy, rotate and remove with undo. Clicking a status retests the stored key. Add key and Rotate open an inline form under the row that checks the key's format as you type, then shows Testing connection and Connected before the row updates. With no props it renders a sample workspace and simulates every test.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `keys` | `ProviderKey[]` | – | Controlled keys: { provider, status: "connected" \| "invalid" \| "unset", value?, last4?, lastUsedAt?, checkedAt?, error? }. Pass value to enable reveal and copy, or only last4 when your server never returns full keys. Providers without an entry read Not set. |
| `defaultKeys` | `ProviderKey[]` | `sample workspace` | Starting keys when uncontrolled. Pass [] for the empty state, every row Not set with an Add key button. |
| `onKeysChange` | `(keys: ProviderKey[]) => void` | – | Every change: added, rotated, removed, restored with undo, or retested. |
| `providers` | `ProviderId[]` | `["anthropic", "openai", "google", "mistral", "xai"]` | Which providers get a row, in order. |
| `testKey` | `(request: { provider, key?, signal }) => Promise<KeyTestResult>` | – | Tests a key and resolves { ok: true, detail? } or { ok: false, error }. key is the pasted key when adding or rotating, and missing when retesting a stored key (test it on your server by provider). Aborted when the form closes. Leave it out to simulate: stored invalid keys fail again, everything else connects in under a second. |
| `onSave` | `(provider, key, mode: "add" \| "rotate") => void` | – | A new key passed its test. Persist it here; the row already shows it as connected. |
| `onRemove` | `(provider) => void` | – | Fires when the undo window closes, so a removal only reaches your server once it sticks. |
| `onCopy` | `(provider) => void` | – | A key was copied to the clipboard, for an audit log. |
| `revealDuration` | `number` | `5000` | Milliseconds a revealed key stays visible before it masks itself again. |
| `undoDuration` | `number` | `5000` | Milliseconds Undo stays after a removal. |
| `loading` | `boolean` | `false` | Placeholder rows with the real row geometry while keys load. |
| `title` | `ReactNode` | `"Provider keys"` | Card title. |
| `description` | `ReactNode` | – | Line under the title. Falsy hides it. |
| `footer` | `ReactNode \| null` | – | Quiet line under the list. Defaults to an encryption note; null hides it. |
| `className` | `string` | – | Extra class on the card. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Tab | Moves through each row's status (retest), reveal, copy, rotate and remove, or Add key on an empty row. |
| Enter | In the form, saves the key and runs the connection test. |
| Escape | In the form, cancels and returns focus to the button that opened it. |

### Accessibility

- A section labelled by its title, with the rows in a list. Every icon button has a provider-specific label, such as "Copy the Anthropic key".
- Status is never color alone: an icon plus Connected, Invalid, Not set or Testing. The status button's label includes the rejection reason.
- Reveal is a toggle with aria-pressed; rotate and Add key report aria-expanded for the inline form.
- A polite live region announces reveals, copies, test results, removals and undo. Without testKey it adds "Simulated, nothing was sent."
- The form's input has a label and points at the helper line with aria-describedby; format and rejection errors set aria-invalid.
- Focus is managed: the form focuses its input, Cancel returns focus to its trigger, Remove moves focus to Undo, and Undo returns it to Remove.

### Motion

- Status, key, meta and helper text swap with one crossfade (out 100ms, in 160ms with a 2px rise) in a shared grid cell, so nothing resizes.
- The inline form opens and closes on a measured height spring (visualDuration .24, no bounce) with a short fade.
- The reveal countdown is a hairline ring that empties linearly over revealDuration. Icon swaps (eye, copy check) scale and fade in 160ms.
- Reduced motion keeps every state and announcement, drops the countdown ring, the rise and the press scale, and slows the spinner.

### Responsive behavior

- At 560px and wider each row is one line of columns: mark, name over key, status over last used, actions.
- Below 560px the status moves beside the name, the key gets its own line, and last used shares a line with the actions.
- The form puts input, Cancel and Save on one line on wide cards and stacks them under 560px. Holds at 360px with no horizontal scroll.

### Performance

- Plain DOM and CSS; Motion only animates the form height and short crossfades. The clock re-renders the card every 30 seconds for relative times.
- Timers and in-flight tests are cleared and aborted on unmount and when a form closes.

### Notes for AI

- Use for bring your own key settings in AI products: a workspace or account settings page, an onboarding step, or a gateway admin.
- Never ship full keys to the browser in production: pass last4 only and leave value out, which disables reveal and copy for that row.
- testKey should call the provider from your server (for example a models list request) and return { ok: false, error: "401 Unauthorized" } on rejection.
- Rotate means paste a new key: the row keeps the old key until the new one passes its test, then swaps.
- For a single generic secret with expiry and rotation history use secret-rotation; for spend per provider pair it with usage-meter.

### Related

- [Usage meter](https://uiarc.dev/components/usage-meter/markdown): Show what fills an allowance and how close it is to the limit.
- [Copy button](https://uiarc.dev/components/copy-button/markdown): Copy a value with immediate confirmation.
- [Input](https://uiarc.dev/components/input/markdown): A single line field with clear labels and useful states.
- [Model picker](https://uiarc.dev/components/blocks/model-picker/markdown): A model picker in one quiet pill: open it to choose from featured models with a one line note each, set the reasoning effort, or browse every other model by provider, and the pill swaps to your choice in place.

### Also in ai

- [Agent status](https://uiarc.dev/components/agent-status/markdown): A compact live status pill for a running AI agent: the agent's mark in a live ring, the current activity and an elapsed timer, opening into the steps so far.
- [Tool call](https://uiarc.dev/components/tool-call/markdown): A tool call row for agent transcripts: the tool's mark and the call in plain words, a live state while it runs, and the input and output a click away, with approval and retry when needed.
- [Agent plan](https://uiarc.dev/components/agent-plan/markdown): The plan an agent writes before it acts: edit, reorder or add steps while it is a draft, then watch it work through them as a live checklist.
- [Agent timeline](https://uiarc.dev/components/agent-timeline/markdown): A compact timeline of one orchestrated agent run: the orchestrator and its subagents share a time axis, handoffs draw in between rows, and a playhead replays thinking, tool calls and waiting while the header counts time, tokens and cost. Hover a span for what it did, or click it to trace its handoff path.
- [Context window](https://uiarc.dev/components/context-window/markdown): An AI context window as a grid of 200 cells: the system prompt, tools, files, summary and messages fill it in order, a threshold row marks where compaction starts, and sending a message, attaching a file or compacting shows exactly how much still fits.
- [Reasoning block](https://uiarc.dev/components/reasoning-block/markdown): The collapsible thinking block of an AI reply. While the model thinks, a shimmering label counts the seconds and the latest reasoning streams underneath. When it finishes, it folds to "Thought for 7s" and opens to show the full reasoning as calm steps with headings.
- [Source cards](https://uiarc.dev/components/source-cards/markdown): A row of cited sources under an AI answer where cards stream in with real site marks while the model searches, the overflow collapses into a stack of favicons, hovering lifts a preview with the passage, and an inline [n] citation highlights its card.
- [Model card](https://uiarc.dev/components/model-card/markdown): A model details card where switching models rolls every price, limit and score in place, a token slider estimates monthly cost live, and benchmark bars show each model's rank on hover. Compare crossfades to a side-by-side table against any rival with the better values marked, and the card never changes size.
- [AI workflow](https://uiarc.dev/components/ai-workflow/markdown): A Linear-style AI workflow card where a Gmail trigger, a Claude step, a branch and Slack and Linear actions sit on one hairline rail, and a test run glides down it, opening each step's output inline. Steps are added from a compact command menu with real app marks.
- [Code suggestion](https://uiarc.dev/components/code-suggestion/markdown): An AI code edit suggestion where the model's proposed changes stream into a small editor panel as inline diff hunks, and you accept or reject each one, or all at once with Cmd+Enter. Accepted hunks fold into the file with a smooth height change.
- [Ghost text](https://uiarc.dev/components/ghost-text/markdown): An inline AI autocomplete where muted ghost text continues your sentence exactly at the caret and Tab turns it solid in place. Cmd+Right takes it one word at a time, Escape fades it away, and a calm chip shows the model behind it.
- [Image generation](https://uiarc.dev/components/image-generation/markdown): An image studio where each image forms on a dot matrix: a soft halftone wave breathes across the grid, the dots take the colours of the coming photo and grow into a coloured halftone, then blur away into the sharp photo. One large canvas with a mono size label, a filmstrip of four variations, a prompt bar with model and ratio, and upscale with a sweeping dot band, vary or download, with real provider marks and a built-in simulation.
- [Dictation button](https://uiarc.dev/components/dictation-button/markdown): A chat composer with voice input, where the mic springs into a recording pill with a smooth live waveform, a timer, and cancel and insert buttons. Words stream into the field as you speak, muted until the recognizer settles them.
- [Speech player](https://uiarc.dev/components/speech-player/markdown): A read-aloud player for AI replies. The Read aloud button in the message's action row turns into a compact player with play, a scrubbable progress bar, speed and a voice picker, and a highlight follows the spoken word through the reply, karaoke style.
- [Meeting summary](https://uiarc.dev/components/meeting-summary/markdown): An AI meeting notes card: the header shows the Google Meet or Zoom mark, the attendees and the duration. Summary, Decisions and Action items stream in after a short summarizing pass. Hover any line to see the transcript quote it came from, then check off action items or send them to Linear or Notion.
- [Reply draft](https://uiarc.dev/components/reply-draft/markdown): An AI email reply drafter where Claude streams a reply under a received Gmail message. Quick replies steer a fresh draft, tone and length rewrite it with a single crossfade, and you can edit the finished draft before you insert it.
- [Agent handoff](https://uiarc.dev/components/agent-handoff/markdown): A support conversation where an AI assistant hands off to a person. When it transfers, a card shows the summary it passes to the team and the typical wait. The person then joins and takes over, and a thin timeline on the left marks each step.
- [PII redaction](https://uiarc.dev/components/pii-redaction/markdown): A guardrail card where personal data is redacted before the prompt reaches the model. Scan marks each name, email, phone number and card with its type and swaps it for a placeholder like [EMAIL_1]. The safe prompt travels to Claude, and the reply comes back with the original values put back for the person.
- [Response feedback](https://uiarc.dev/components/response-feedback/markdown): A feedback control for AI replies where thumbs down opens an inline panel with reason chips and an optional note, thumbs up fills and asks what was good, and a submit shows a short thank-you before folding back into the row.
- [LLM cost calculator](https://uiarc.dev/components/llm-cost-calculator/markdown): A pricing calculator for LLM workloads. Set tokens per request, requests per day and prompt caching, and eight current models re-rank by monthly cost. Bars glide and prices roll as you drag.
- [Generation stats](https://uiarc.dev/components/generation-stats/markdown): A live stats strip for a streaming LLM response where time to first token, speed with a sparkline, output tokens and cost count up in tabular numerals beside the model's real mark, then settle and open into a latency and token cost breakdown.
- [AI translate](https://uiarc.dev/components/ai-translate/markdown): A message card where picking a language streams the AI translation in place, sentence by sentence over the dimmed original, with a detected-language chip, a Show original toggle and a status line credited to the model's mark.
- [TL;DR toggle](https://uiarc.dev/components/tldr-toggle/markdown): An article card with a Full, Summary and Key points switch and a length slider. Switching streams an AI summary in place of the article as the card's height springs to fit, and each key point links back to the paragraph it came from, which gets scrolled to and highlighted.
- [Connector setup](https://uiarc.dev/components/connector-setup/markdown): A "Connect your tools" card for an AI assistant. Each app connects inline: it redirects, authorizes and runs a first sync with a progress hairline, then lists the scopes it was granted and offers Disconnect with an inline confirm.
- [Smart form fill](https://uiarc.dev/components/smart-form-fill/markdown): A paste-to-fill form card where AI reads an email signature or messy notes and fills a contact field by field. Each value flashes in with a confidence dot, its source lights up in the pasted text, low-confidence guesses ask for review, and Undo puts the old values back.
- [Enrich column](https://uiarc.dev/components/enrich-column/markdown): An AI enrichment column for a data table, where one prompt runs down every row and each cell shimmers while it works, then settles into a value with its source or a failure you can retry.
- [Ticket router](https://uiarc.dev/components/ticket-router/markdown): A support ticket router where messages from Gmail, Intercom, Slack and Zendesk come in one at a time. An AI classifier labels each one with intent, sentiment and confidence, and the ticket moves into a team lane with an assignee. Low confidence tickets wait in a review lane, and one click there routes them to the suggested team.
- [Ask your data](https://uiarc.dev/components/ask-your-data/markdown): A natural language to chart card: you ask a question, PostgreSQL streams into a collapsible, syntax highlighted panel, the query runs with a rolling row count, and the answer builds as stacked bars, lines or a table, with a one line insight streamed in underneath.
- [Agent cursor](https://uiarc.dev/components/agent-cursor/markdown): A live document where Claude edits like a collaborator. Its labeled cursor comes out of its avatar, selects a paragraph and streams in a rewrite, adds a heading and fixes a typo, while a teammate's cursor reads along. Changes stay tinted until someone accepts or undoes them from a floating review bar.
- [Provider status](https://uiarc.dev/components/provider-status/markdown): A status card for the AI providers your product depends on. Each row shows the provider's real mark, its health as an icon and label, p50 latency and a 30-day uptime bar with a tooltip for each day. An incident row expands into its timeline of updates, and the card checks again on a visible countdown.
- [Training run](https://uiarc.dev/components/training-run/markdown): A fine-tuning job card where a live train and validation loss curve draws across a fixed step axis that doubles as the epoch progress bar. It shows the learning rate, elapsed time, ETA and the latest evals and checkpoints, has Pause and Cancel while it runs, and ends in results with a Deploy button.
- [AI command](https://uiarc.dev/components/ai-command/markdown): A Cmd+K command palette with an AI mode. Search pages and actions, or press Tab to ask a question: the answer streams inside the palette with numbered sources, and the next steps it suggests, like filing a Linear issue or opening a Notion doc, run straight from the list.
- [Starter prompts](https://uiarc.dev/components/starter-prompts/markdown): A greeting and a grid of starter cards for the empty state of an AI app. The cards are grouped into Write, Code, Analyze and Plan tabs, and a shuffle swaps them with a short staggered crossfade. Picking a card fills the composer, and cards that use a connected app show its mark (Gmail, GitHub, Notion, Linear, Google Calendar).
- [AI mascot](https://uiarc.dev/components/ai-mascot/markdown): A small assistant character, a soft pebble with pill eyes and a companion dot, that shows what the AI is doing. It breathes and glances when idle, leans in to listen, looks up while the dot orbits its head, reads along the line it writes, squints with a sparkle when done and shakes once with worried brows on an error.
- [Image reveal](https://uiarc.dev/components/image-reveal/markdown): An image generation canvas where a soft, blurred preview made from the image's own colors sharpens top to bottom behind a soft-edged band. It works the way ChatGPT, Midjourney and Gemini show images forming, with fine film grain, a translucent progress pill and calm queued and error states.
- [AI spark](https://uiarc.dev/components/ai-spark/markdown): A brand-quality animated spark mark. Four tapered rays and four lighter diagonals breathe at rest, ripple while thinking, pulse like a heartbeat while writing, then gather and settle when done. Every status change blends from the pose the mark is already in.
- [Pixel mascot](https://uiarc.dev/components/pixel-mascot/markdown): A pixel-art robot that shows what an AI assistant is doing. It idles, thinks, types, celebrates and errors in frame-stepped sprite animations, and stays crisp at every integer size from 24px to 192px.
- [Ghost mascot](https://uiarc.dev/components/ghost-mascot/markdown): A floating ghost mascot whose soft sheet ripples at the hem while it hovers. It blinks when idle, turns toward you to listen, fades a little translucent while thinking, draws a tiny pen line while writing, smiles with a sparkle when done and wobbles once on an error.
- [Cube mascot](https://uiarc.dev/components/cube-mascot/markdown): An isometric cube mascot where three shaded faces and a painted-on face show what the assistant is doing. It turns a quarter turn in eased steps while thinking, prints lines onto the floor while writing, settles with a sparkle when done, and shakes once on error.
- [Tone tuner](https://uiarc.dev/components/tone-tuner/markdown): A brand voice card where two sliders (formality and detail) and Friendly, Confident and Empathetic chips rewrite a customer reply. Each changed sentence crossfades in place, new words can be highlighted against the original, and Copy takes the current version.
- [Upgrade prompt](https://uiarc.dev/components/upgrade-prompt/markdown): An upgrade nudge for the moment someone hits a limit. It shows a usage meter at 50 of 50 AI credits, a rolling price with a monthly and yearly toggle, three concrete unlocks with real model marks, and Upgrade or Maybe later. Upgrading leads into a success state with the new limits, and the card never changes size between states.
- [Referral card](https://uiarc.dev/components/referral-card/markdown): A give-and-get referral card where people copy or share their invite link, invite friends by email as chips, and watch invites move from invited to signed up to earned, with the credit total counting up and a milestone reward unlocking.
- [Trial banner](https://uiarc.dev/components/trial-banner/markdown): A trial status banner where a ring counts down the days left, the copy names what the workspace loses, and the upgrade path is one click away. It comes as a slim banner, a sidebar card or a header pill. It shifts to a warning tone in the last days, has expired and upgraded states, and folds into the pill when dismissed or snoozed.
- [Team switcher](https://uiarc.dev/components/team-switcher/markdown): A workspace switcher like Linear, Vercel or Slack. The trigger shows the current workspace's logo and plan. The menu has search, your role in each workspace and a Cmd+1 to 9 shortcut for each, and lets you create or join a workspace inline. A highlight glides between rows, and switching crossfades the trigger through a short loading state.
- [Live visitors](https://uiarc.dev/components/live-visitors/markdown): A realtime visitors card where the live count rolls digit by digit, new arrivals ping in on a dotted world map, the top pages reorder with bars, and signups and upgrades tick in with country flags.
- [Social proof toast](https://uiarc.dev/components/social-proof-toast/markdown): A stack of social proof notifications for landing and pricing pages, where recent trials, upgrades and verified purchases from people and companies arrive every few seconds. The stack pauses and fans out on hover, and visitors can dismiss any toast.
- [Install snippet](https://uiarc.dev/components/install-snippet/markdown): A "get started in 30 seconds" card where framework tabs, three numbered steps and highlighted snippets take a developer from install to first event. Generate key wipes a fresh API key into the placeholder in place.

### Guidance for AI tools

Provider keys: A settings card for bring-your-own-key AI products. Each provider row shows its real mark, the masked key, a status and when the key was last used. You can reveal a key for five seconds, copy, rotate or remove it with undo. Adding or rotating a key opens an inline form that checks the format as you type, then tests the connection before saving. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Generation stats

> A live stats strip for a streaming LLM response where time to first token, speed with a sparkline, output tokens and cost count up in tabular numerals beside the model's real mark, then settle and open into a latency and token cost breakdown.

- Type: Component (special)
- Access: Arc Pro
- Page: https://uiarc.dev/components/generation-stats
- Markdown: https://uiarc.dev/components/generation-stats/markdown
- Source file: `registry/components/generation-stats/generation-stats.tsx`
- Dependencies: motion, lucide-react
- Keywords: special, ai, new, generation stats, llm stats, tokens per second, time to first token, ttft, latency, token usage, cost, streaming, sparkline, prompt cache, cached tokens, reasoning tokens, claude, gpt, gemini, dev panel, usage meter

### When to use

- Under assistant messages in a chat product that shows people what a response cost or how fast it was.
- Playgrounds, eval runners and internal dev panels comparing models on latency, throughput and cost.
- Admin or debugging views that inspect a single request's token usage and cache hit rate.

### When not to use

- Use context-window to show how much of a model's context a conversation has used.
- Use a chart or table for spend across many requests or days; this strip describes one response.
- Use agent-status for a long running agent with steps; this measures one model call.

### Installation

Generation stats is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/generation-stats
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { GenerationStats } from "@/components/arc/generation-stats/generation-stats";

// Under an assistant message, fed by your streaming handler.
export function MessageStats({ run }) {
  return (
    <GenerationStats
      variant="inline"
      model={{ name: "Claude Sonnet 5.5", provider: "anthropic", id: "claude-sonnet-5-5" }}
      status={run.status}                 // "waiting" | "streaming" | "done" | "stopped" | "error"
      startedAt={run.startedAt}           // Date.now() when the request went out
      usage={{
        inputTokens: run.usage.input_tokens + run.usage.cache_read_input_tokens,
        cachedTokens: run.usage.cache_read_input_tokens,
        outputTokens: run.outputTokens,   // update on every chunk
        ttftMs: run.ttftMs,               // set on the first token
        durationMs: run.durationMs,       // set on the last
      }}
      pricing={{ input: 3, cachedInput: 0.3, output: 15 }}
      error={run.error}
      onRetry={() => run.retry()}
    />
  );
}

// A dev panel card with the breakdown open.
<GenerationStats model={model} status="done" usage={usage} pricing={pricing} defaultExpanded />

// With no props it plays the sample runs.
<GenerationStats />
```

### API reference

#### GenerationStats

A live stats strip for a streaming LLM response. The head shows the model's real mark, its name and a status with icon and label (Waiting, Streaming, Done in 4.18s, Stopped at 1.90s, Failed). Below it four cells split by hairlines: time to first token, speed in tokens per second with a small sparkline, output tokens and cost. While the response streams every number counts up in tabular numerals and the sparkline draws; when it ends the numbers settle on exact values. Details opens a breakdown with a latency bar (first token, generation, total) and a token table (input, cached input, output, reasoning, total) with rates and cost. A failed response gets a reason row with Retry. With no props it plays four sample runs (Claude Sonnet 5.5, GPT-6.1 Sol, Gemini 3.8 Flash and Mistral Large 4, which fails once and retries).

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `status` | `"idle" \| "waiting" \| "streaming" \| "done" \| "stopped" \| "error"` | – | Where the response is: waiting until the first token, streaming until the last. Leave it out to play the built in sample runs. |
| `model` | `{ name: string; provider: GenerationProvider; id?: string }` | – | The model that answered. provider picks the mark: "anthropic", "openai", "google", "xai", "mistral", "deepseek", "meta" or "qwen". id goes into the copied JSON. |
| `startedAt` | `number` | – | Epoch ms when the request was sent. While waiting, time to first token counts live from here; while streaming, total latency does. |
| `usage` | `GenerationUsage` | `{}` | inputTokens (cached included), cachedTokens, outputTokens, reasoningTokens, ttftMs, durationMs, tokensPerSecond, costUsd. All optional. Update outputTokens as chunks arrive and set ttftMs on the first token and durationMs on the last; speed and cost are derived unless you pass tokensPerSecond or costUsd. |
| `pricing` | `{ input: number; cachedInput?: number; output: number }` | – | USD per million tokens. Enables the Rate and Cost columns and the live cost. Reasoning tokens bill at the output rate; cachedInput defaults to the input rate. |
| `speedSamples` | `number[]` | – | Speed readings in tokens per second, oldest first, for the sparkline. By default the component reads speed every 160ms while outputTokens grows, smoothed, and keeps the whole run's shape. |
| `error` | `string` | – | The reason shown in the error row when status is "error". |
| `onRetry` | `() => void` | – | Shows Retry in the error row. |
| `variant` | `"card" \| "inline"` | `"card"` | card is a bordered strip for dev panels and run views. inline is one quiet wrapping line ("412ms to first token · 88 tok/s · 284 tokens · $0.0077") for the space under a chat message; the breakdown opens as a panel below it. |
| `expanded` | `boolean` | – | Controls the breakdown. Pair with onExpandedChange. |
| `defaultExpanded` | `boolean` | `false` | Opens the breakdown on first render when uncontrolled. |
| `onExpandedChange` | `(expanded: boolean) => void` | – | Called when Details is pressed. |
| `note` | `ReactNode` | – | A footnote under the breakdown, for example "Rates from your Anthropic contract, updated Oct 1, 2026". The preview uses it to say the run is simulated. |
| `className` | `string` | – | Class on the root element. |

#### useGenerationSimulation

The simulated stream behind the preview, exported for prototypes and tests. Returns { frame, cueOpen, retry, next }, where frame holds model, pricing, status, startedAt, usage and error in exactly the shape GenerationStats takes. Output ramps up, wavers a few percent and arrives in chunks of four or more tokens, like a real stream. Nothing is sent anywhere.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `runs` | `GenerationSampleRun[]` | `generationSampleRuns` | The runs to play in order. A run with failAtTokens fails there once and succeeds when retried. |
| `active` | `boolean` | `true` | Ticks only while true; pass false when the card is off screen. |
| `hold` | `boolean` | `false` | Keeps a settled run on screen instead of moving on. |
| `loop` | `boolean` | `true` | Plays the runs in a loop. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Tab | Moves to Details, then Retry when a response failed, then the copy button inside an open breakdown. |
| Enter, Space | Opens or closes the breakdown, retries, or copies the stats as JSON. |

### Accessibility

- The strip is a group named after the model ("Claude Sonnet 5.5 stats"). The four stats are a description list, so each value is read with its label: "First token, 412ms".
- Details is a button with aria-expanded and aria-controls; at narrow widths it becomes an icon button that keeps the name Show details or Hide details.
- A polite status region announces settled outcomes ("Claude Sonnet 5.5 done in 4.18s, 284 output tokens at 88 tokens per second, $0.0077"), failures and stops, never the live counts. The self-playing preview says once that it is simulated and stays quiet until someone interacts with it.
- Status never relies on color: a spinner, drawn check, alert or square always sits next to a word. The latency bar is decorative; its values are listed beside it in text.
- The breakdown is a real table with column and row headers and a caption, so screen readers can navigate tokens, rates and cost by cell.
- Pointer focus draws no ring; keyboard focus shows Arc's shared focus ring.

### Motion

- Numbers glide toward each new value in about 100ms per step with tabular numerals in reserved cells, so chunks of tokens read as one smooth count and nothing beside them moves. A drop, like a new request, cuts straight to the new value instead of counting down.
- While streaming, speed is measured when each chunk lands, so it holds still between chunks instead of sagging and jumping. The sparkline adds a smoothed reading every 160ms and compresses to keep the whole run's shape.
- Status labels swap with a single crossfade (out in 100ms, in over 160ms with a 2px rise); the done check draws itself once.
- The breakdown and the error row open on a 260ms critically damped spring for height with a 160ms fade. Nothing bounces.
- The preview loop pauses off screen and holds on a settled run while someone has the breakdown open.
- Reduced motion shows final values at once, drops the spinner, the check drawing and the height springs, and stops the preview on a settled run.

### Responsive behavior

- The card's four cells sit in one row above 600px of width and in a two by two grid below it, so the speed cell keeps room for its sparkline.
- Below 440px Details becomes an icon button and the Rate column hides; the model name truncates with an ellipsis rather than wrapping.
- The inline variant wraps its stats onto a second line on phones instead of scrolling; the breakdown spans the full width under it.

### Performance

- The live clock runs on requestAnimationFrame only while waiting or streaming, and each counting number re-renders only itself.
- The speed series is sampled on a 160ms interval only while streaming and capped at 48 points.
- The preview's simulation ticks every 40ms in virtual time and only while the card is on screen.

### Notes for AI

- Wire it to the stream you already have: set startedAt when the request leaves, status "waiting" until the first chunk, then "streaming" while you add to outputTokens, then "done" with durationMs. Speed, latency and cost follow.
- Map provider usage fields: Anthropic input_tokens plus cache_read_input_tokens is inputTokens and cache_read_input_tokens is cachedTokens; OpenAI prompt_tokens and prompt_tokens_details.cached_tokens map the same way, and completion_tokens_details.reasoning_tokens is reasoningTokens.
- Pass pricing from your own config. If your provider already reports cost, pass usage.costUsd and leave pricing out; the Rate column then hides.
- Use variant="inline" under chat messages and the card in eval views, playgrounds and admin panels. Keep the model name as people know it ("Claude Sonnet 5.5"), and put the API id in model.id.
- When the person stops a response, set status "stopped" with durationMs; when the request fails, set status "error" with a short, specific reason and onRetry.

### Related

- [Context window](https://uiarc.dev/components/context-window/markdown): An AI context window as a grid of 200 cells: the system prompt, tools, files, summary and messages fill it in order, a threshold row marks where compaction starts, and sending a message, attaching a file or compacting shows exactly how much still fits.
- [Tool call](https://uiarc.dev/components/tool-call/markdown): A tool call row for agent transcripts: the tool's mark and the call in plain words, a live state while it runs, and the input and output a click away, with approval and retry when needed.
- [Agent status](https://uiarc.dev/components/agent-status/markdown): A compact live status pill for a running AI agent: the agent's mark in a live ring, the current activity and an elapsed timer, opening into the steps so far.
- [AI chat](https://uiarc.dev/components/blocks/ai-chat/markdown): A full-screen AI chat where answers stream in as markdown with folding reasoning, tool chips and cited sources. People can switch chats and models, edit or retry a message into versions, rate replies and stop a reply mid-stream.
- [Model picker](https://uiarc.dev/components/blocks/model-picker/markdown): A model picker in one quiet pill: open it to choose from featured models with a one line note each, set the reasoning effort, or browse every other model by provider, and the pill swaps to your choice in place.
- [Text shimmer](https://uiarc.dev/components/text-shimmer/markdown): Show ongoing work with a calm light across the words.
- [Copy button](https://uiarc.dev/components/copy-button/markdown): Copy a value with immediate confirmation.

### Also in ai

- [Agent plan](https://uiarc.dev/components/agent-plan/markdown): The plan an agent writes before it acts: edit, reorder or add steps while it is a draft, then watch it work through them as a live checklist.
- [Agent timeline](https://uiarc.dev/components/agent-timeline/markdown): A compact timeline of one orchestrated agent run: the orchestrator and its subagents share a time axis, handoffs draw in between rows, and a playhead replays thinking, tool calls and waiting while the header counts time, tokens and cost. Hover a span for what it did, or click it to trace its handoff path.
- [Reasoning block](https://uiarc.dev/components/reasoning-block/markdown): The collapsible thinking block of an AI reply. While the model thinks, a shimmering label counts the seconds and the latest reasoning streams underneath. When it finishes, it folds to "Thought for 7s" and opens to show the full reasoning as calm steps with headings.
- [Source cards](https://uiarc.dev/components/source-cards/markdown): A row of cited sources under an AI answer where cards stream in with real site marks while the model searches, the overflow collapses into a stack of favicons, hovering lifts a preview with the passage, and an inline [n] citation highlights its card.
- [Model card](https://uiarc.dev/components/model-card/markdown): A model details card where switching models rolls every price, limit and score in place, a token slider estimates monthly cost live, and benchmark bars show each model's rank on hover. Compare crossfades to a side-by-side table against any rival with the better values marked, and the card never changes size.
- [AI workflow](https://uiarc.dev/components/ai-workflow/markdown): A Linear-style AI workflow card where a Gmail trigger, a Claude step, a branch and Slack and Linear actions sit on one hairline rail, and a test run glides down it, opening each step's output inline. Steps are added from a compact command menu with real app marks.
- [Code suggestion](https://uiarc.dev/components/code-suggestion/markdown): An AI code edit suggestion where the model's proposed changes stream into a small editor panel as inline diff hunks, and you accept or reject each one, or all at once with Cmd+Enter. Accepted hunks fold into the file with a smooth height change.
- [Ghost text](https://uiarc.dev/components/ghost-text/markdown): An inline AI autocomplete where muted ghost text continues your sentence exactly at the caret and Tab turns it solid in place. Cmd+Right takes it one word at a time, Escape fades it away, and a calm chip shows the model behind it.
- [Image generation](https://uiarc.dev/components/image-generation/markdown): An image studio where each image forms on a dot matrix: a soft halftone wave breathes across the grid, the dots take the colours of the coming photo and grow into a coloured halftone, then blur away into the sharp photo. One large canvas with a mono size label, a filmstrip of four variations, a prompt bar with model and ratio, and upscale with a sweeping dot band, vary or download, with real provider marks and a built-in simulation.
- [Dictation button](https://uiarc.dev/components/dictation-button/markdown): A chat composer with voice input, where the mic springs into a recording pill with a smooth live waveform, a timer, and cancel and insert buttons. Words stream into the field as you speak, muted until the recognizer settles them.
- [Speech player](https://uiarc.dev/components/speech-player/markdown): A read-aloud player for AI replies. The Read aloud button in the message's action row turns into a compact player with play, a scrubbable progress bar, speed and a voice picker, and a highlight follows the spoken word through the reply, karaoke style.
- [Meeting summary](https://uiarc.dev/components/meeting-summary/markdown): An AI meeting notes card: the header shows the Google Meet or Zoom mark, the attendees and the duration. Summary, Decisions and Action items stream in after a short summarizing pass. Hover any line to see the transcript quote it came from, then check off action items or send them to Linear or Notion.
- [Reply draft](https://uiarc.dev/components/reply-draft/markdown): An AI email reply drafter where Claude streams a reply under a received Gmail message. Quick replies steer a fresh draft, tone and length rewrite it with a single crossfade, and you can edit the finished draft before you insert it.
- [Agent handoff](https://uiarc.dev/components/agent-handoff/markdown): A support conversation where an AI assistant hands off to a person. When it transfers, a card shows the summary it passes to the team and the typical wait. The person then joins and takes over, and a thin timeline on the left marks each step.
- [PII redaction](https://uiarc.dev/components/pii-redaction/markdown): A guardrail card where personal data is redacted before the prompt reaches the model. Scan marks each name, email, phone number and card with its type and swaps it for a placeholder like [EMAIL_1]. The safe prompt travels to Claude, and the reply comes back with the original values put back for the person.
- [Response feedback](https://uiarc.dev/components/response-feedback/markdown): A feedback control for AI replies where thumbs down opens an inline panel with reason chips and an optional note, thumbs up fills and asks what was good, and a submit shows a short thank-you before folding back into the row.
- [LLM cost calculator](https://uiarc.dev/components/llm-cost-calculator/markdown): A pricing calculator for LLM workloads. Set tokens per request, requests per day and prompt caching, and eight current models re-rank by monthly cost. Bars glide and prices roll as you drag.
- [Provider keys](https://uiarc.dev/components/provider-keys/markdown): A settings card for bring-your-own-key AI products. Each provider row shows its real mark, the masked key, a status and when the key was last used. You can reveal a key for five seconds, copy, rotate or remove it with undo. Adding or rotating a key opens an inline form that checks the format as you type, then tests the connection before saving.
- [AI translate](https://uiarc.dev/components/ai-translate/markdown): A message card where picking a language streams the AI translation in place, sentence by sentence over the dimmed original, with a detected-language chip, a Show original toggle and a status line credited to the model's mark.
- [TL;DR toggle](https://uiarc.dev/components/tldr-toggle/markdown): An article card with a Full, Summary and Key points switch and a length slider. Switching streams an AI summary in place of the article as the card's height springs to fit, and each key point links back to the paragraph it came from, which gets scrolled to and highlighted.
- [Connector setup](https://uiarc.dev/components/connector-setup/markdown): A "Connect your tools" card for an AI assistant. Each app connects inline: it redirects, authorizes and runs a first sync with a progress hairline, then lists the scopes it was granted and offers Disconnect with an inline confirm.
- [Smart form fill](https://uiarc.dev/components/smart-form-fill/markdown): A paste-to-fill form card where AI reads an email signature or messy notes and fills a contact field by field. Each value flashes in with a confidence dot, its source lights up in the pasted text, low-confidence guesses ask for review, and Undo puts the old values back.
- [Enrich column](https://uiarc.dev/components/enrich-column/markdown): An AI enrichment column for a data table, where one prompt runs down every row and each cell shimmers while it works, then settles into a value with its source or a failure you can retry.
- [Ticket router](https://uiarc.dev/components/ticket-router/markdown): A support ticket router where messages from Gmail, Intercom, Slack and Zendesk come in one at a time. An AI classifier labels each one with intent, sentiment and confidence, and the ticket moves into a team lane with an assignee. Low confidence tickets wait in a review lane, and one click there routes them to the suggested team.
- [Ask your data](https://uiarc.dev/components/ask-your-data/markdown): A natural language to chart card: you ask a question, PostgreSQL streams into a collapsible, syntax highlighted panel, the query runs with a rolling row count, and the answer builds as stacked bars, lines or a table, with a one line insight streamed in underneath.
- [Agent cursor](https://uiarc.dev/components/agent-cursor/markdown): A live document where Claude edits like a collaborator. Its labeled cursor comes out of its avatar, selects a paragraph and streams in a rewrite, adds a heading and fixes a typo, while a teammate's cursor reads along. Changes stay tinted until someone accepts or undoes them from a floating review bar.
- [Provider status](https://uiarc.dev/components/provider-status/markdown): A status card for the AI providers your product depends on. Each row shows the provider's real mark, its health as an icon and label, p50 latency and a 30-day uptime bar with a tooltip for each day. An incident row expands into its timeline of updates, and the card checks again on a visible countdown.
- [Training run](https://uiarc.dev/components/training-run/markdown): A fine-tuning job card where a live train and validation loss curve draws across a fixed step axis that doubles as the epoch progress bar. It shows the learning rate, elapsed time, ETA and the latest evals and checkpoints, has Pause and Cancel while it runs, and ends in results with a Deploy button.
- [AI command](https://uiarc.dev/components/ai-command/markdown): A Cmd+K command palette with an AI mode. Search pages and actions, or press Tab to ask a question: the answer streams inside the palette with numbered sources, and the next steps it suggests, like filing a Linear issue or opening a Notion doc, run straight from the list.
- [Starter prompts](https://uiarc.dev/components/starter-prompts/markdown): A greeting and a grid of starter cards for the empty state of an AI app. The cards are grouped into Write, Code, Analyze and Plan tabs, and a shuffle swaps them with a short staggered crossfade. Picking a card fills the composer, and cards that use a connected app show its mark (Gmail, GitHub, Notion, Linear, Google Calendar).
- [AI mascot](https://uiarc.dev/components/ai-mascot/markdown): A small assistant character, a soft pebble with pill eyes and a companion dot, that shows what the AI is doing. It breathes and glances when idle, leans in to listen, looks up while the dot orbits its head, reads along the line it writes, squints with a sparkle when done and shakes once with worried brows on an error.
- [Image reveal](https://uiarc.dev/components/image-reveal/markdown): An image generation canvas where a soft, blurred preview made from the image's own colors sharpens top to bottom behind a soft-edged band. It works the way ChatGPT, Midjourney and Gemini show images forming, with fine film grain, a translucent progress pill and calm queued and error states.
- [AI spark](https://uiarc.dev/components/ai-spark/markdown): A brand-quality animated spark mark. Four tapered rays and four lighter diagonals breathe at rest, ripple while thinking, pulse like a heartbeat while writing, then gather and settle when done. Every status change blends from the pose the mark is already in.
- [Pixel mascot](https://uiarc.dev/components/pixel-mascot/markdown): A pixel-art robot that shows what an AI assistant is doing. It idles, thinks, types, celebrates and errors in frame-stepped sprite animations, and stays crisp at every integer size from 24px to 192px.
- [Ghost mascot](https://uiarc.dev/components/ghost-mascot/markdown): A floating ghost mascot whose soft sheet ripples at the hem while it hovers. It blinks when idle, turns toward you to listen, fades a little translucent while thinking, draws a tiny pen line while writing, smiles with a sparkle when done and wobbles once on an error.
- [Cube mascot](https://uiarc.dev/components/cube-mascot/markdown): An isometric cube mascot where three shaded faces and a painted-on face show what the assistant is doing. It turns a quarter turn in eased steps while thinking, prints lines onto the floor while writing, settles with a sparkle when done, and shakes once on error.
- [Tone tuner](https://uiarc.dev/components/tone-tuner/markdown): A brand voice card where two sliders (formality and detail) and Friendly, Confident and Empathetic chips rewrite a customer reply. Each changed sentence crossfades in place, new words can be highlighted against the original, and Copy takes the current version.
- [Upgrade prompt](https://uiarc.dev/components/upgrade-prompt/markdown): An upgrade nudge for the moment someone hits a limit. It shows a usage meter at 50 of 50 AI credits, a rolling price with a monthly and yearly toggle, three concrete unlocks with real model marks, and Upgrade or Maybe later. Upgrading leads into a success state with the new limits, and the card never changes size between states.
- [Referral card](https://uiarc.dev/components/referral-card/markdown): A give-and-get referral card where people copy or share their invite link, invite friends by email as chips, and watch invites move from invited to signed up to earned, with the credit total counting up and a milestone reward unlocking.
- [Trial banner](https://uiarc.dev/components/trial-banner/markdown): A trial status banner where a ring counts down the days left, the copy names what the workspace loses, and the upgrade path is one click away. It comes as a slim banner, a sidebar card or a header pill. It shifts to a warning tone in the last days, has expired and upgraded states, and folds into the pill when dismissed or snoozed.
- [Team switcher](https://uiarc.dev/components/team-switcher/markdown): A workspace switcher like Linear, Vercel or Slack. The trigger shows the current workspace's logo and plan. The menu has search, your role in each workspace and a Cmd+1 to 9 shortcut for each, and lets you create or join a workspace inline. A highlight glides between rows, and switching crossfades the trigger through a short loading state.
- [Live visitors](https://uiarc.dev/components/live-visitors/markdown): A realtime visitors card where the live count rolls digit by digit, new arrivals ping in on a dotted world map, the top pages reorder with bars, and signups and upgrades tick in with country flags.
- [Social proof toast](https://uiarc.dev/components/social-proof-toast/markdown): A stack of social proof notifications for landing and pricing pages, where recent trials, upgrades and verified purchases from people and companies arrive every few seconds. The stack pauses and fans out on hover, and visitors can dismiss any toast.
- [Install snippet](https://uiarc.dev/components/install-snippet/markdown): A "get started in 30 seconds" card where framework tabs, three numbered steps and highlighted snippets take a developer from install to first event. Generate key wipes a fresh API key into the placeholder in place.

### Guidance for AI tools

Generation stats: A live stats strip for a streaming LLM response where time to first token, speed with a sparkline, output tokens and cost count up in tabular numerals beside the model's real mark, then settle and open into a latency and token cost breakdown. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## AI translate

> A message card where picking a language streams the AI translation in place, sentence by sentence over the dimmed original, with a detected-language chip, a Show original toggle and a status line credited to the model's mark.

- Type: Component (special)
- Access: Arc Pro
- Page: https://uiarc.dev/components/ai-translate
- Markdown: https://uiarc.dev/components/ai-translate/markdown
- Source file: `registry/components/ai-translate/ai-translate.tsx`
- Dependencies: motion, lucide-react, @radix-ui/react-dropdown-menu
- Keywords: special, ai, new, ai translate, translation, inline translation, show original, language picker, detected language, streaming text, multilingual, localization, message translation, claude, llm, i18n

### When to use

- Messages, comments, reviews or support tickets written in another language, translated on demand inside the product.
- Release notes or announcements that readers in several regions open in their own language.
- Any place you want an AI translation to feel inline and reversible, with the original one click away.

### When not to use

- Translating a whole page or app interface; use your i18n framework.
- Long documents with headings and lists; this renders one plain paragraph.
- Live captions or speech; use a realtime stream component.

### Installation

AI translate is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/ai-translate
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { AiTranslate } from "@/components/arc/ai-translate/ai-translate";

export function TranslatableMessage({ message }) {
  return (
    <AiTranslate
      text={message.body}
      sourceLanguage={message.language}
      author={{ name: message.author.name, role: message.author.title, avatar: message.author.avatarUrl }}
      timestamp={message.sentAtLabel}
      model={{ name: "Claude Haiku 5.5" }}
      translate={async function* ({ text, from, to, signal }) {
        const response = await fetch("/api/translate", { method: "POST", body: JSON.stringify({ text, from, to }), signal });
        if (!response.ok || !response.body) throw new Error("The translation service is unavailable.");
        const reader = response.body.pipeThrough(new TextDecoderStream()).getReader();
        while (true) {
          const { value, done } = await reader.read();
          if (done) return;
          yield value;
        }
      }}
      onValueChange={language => savePreferredLanguage(language)}
    />
  );
}

// Pre-translated content, no network
<AiTranslate text={post.fr} sourceLanguage="fr" translations={{ en: post.en, de: post.de }} author={null} />
```

### API reference

#### AiTranslate

An inline translator for one message or paragraph. A byline with a detected language chip sits above the text; below it, a Translate picker (English, Deutsch, Français, Español, 日本語, Português), a Show original toggle and a status line credited to the model's mark. Picking a language dims the text on screen and streams the translation in place in fast chunks, each new sentence retiring one sentence of the old text, while the card's height springs to fit. Finished translations are cached, so Show original and switching back crossfade instantly. Failures put the previous text back and show Couldn't translate with Retry.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `text` | `string` | `sample release note in French` | The text to translate, in its original language. Changing it clears cached translations and shows the new original. |
| `sourceLanguage` | `"en" \| "de" \| "fr" \| "es" \| "ja" \| "pt"` | – | Language of text. When omitted it is detected from the text with a light stopword check and the chip reads Detected; when passed the chip reads Written in. |
| `languages` | `AiTranslateLanguageCode[]` | `all six` | Languages offered in the picker, in order. The source language appears as Original. |
| `value` | `AiTranslateLanguageCode` | – | The language on screen; the source language means the original. Pair with onValueChange to control it, for example to remember a reader's preferred language. |
| `defaultValue` | `AiTranslateLanguageCode` | `sourceLanguage` | Starting language when uncontrolled. A language other than the source translates on mount. |
| `onValueChange` | `(language: AiTranslateLanguageCode) => void` | – | Called when the reader picks a language or toggles Show original. |
| `translate` | `(request: { text, from, to, signal: AbortSignal }) => Promise<string> \| AsyncIterable<string>` | – | Your translation call. Resolve the whole translation, or return an async iterable that yields text deltas as your model streams them. The signal aborts when the reader picks another language, shows the original or the card unmounts. A thrown Error's message is announced and kept as the error tooltip. Without it, translations are streamed as a simulation. |
| `translations` | `Partial<Record<AiTranslateLanguageCode, string>>` | – | Ready translations, streamed by the simulation. Useful for content you translated ahead of time; a missing language shows the error state. |
| `onTranslate` | `(result: { from, to, text }) => void` | – | Called once a translation has fully arrived, before it is cached. |
| `onError` | `(error: Error, request: { from, to }) => void` | – | Called when a translation fails. Aborted requests never call it. |
| `author` | `{ name: string; role?: string; avatar?: string } \| null` | `sample author` | Who wrote the text, shown with an avatar. Pass null to hide the byline; the language chip stays. |
| `timestamp` | `string` | – | Shown after the role in the byline, for example "Oct 27, 09:14". |
| `model` | `{ name: string; mark?: ReactNode }` | `{ name: "Claude Haiku 5.5", mark: Claude mark }` | The model credited in the status line. The mark leads every status; the name is the idle label. |
| `autoPlay` | `boolean` | `true for the bare sample` | Tours English, Deutsch, 日本語 and Português, then the original, and loops. Pauses off screen and stops for good on the first pointer or key press inside the card. With reduced motion it translates once and stops. |
| `simulated` | `boolean` | `true without translate` | Adds "Simulated, nothing was sent" to the live status. |
| `className` | `string` | – | Class on the root section. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Tab | Moves through the Translate picker, the Show original toggle and, after a failure, Retry. |
| Enter / Space / Arrow down | On the picker, opens the language menu with the current language checked. |
| Arrow keys, Home, End | Move through the languages; typing a letter jumps to a language. The list loops. |
| Enter / Space | Picks the highlighted language and closes the menu. Picking the language that just failed retries it. |
| Escape | Closes the menu with focus back on the picker. |

### Accessibility

- The card is a section named after the author. The paragraph carries the lang attribute of the language on screen, and dimmed old sentences keep their own lang, so screen readers pronounce both correctly.
- Start, completion, the original and failures are announced in a polite status region; the paragraph is aria-busy while it streams. The simulation says that nothing was sent.
- The language menu is a radio group with a checkmark on the current language. The Show original toggle is a pressed button whose label switches to Show translation.
- Status is never color alone: the model mark plus a label (Translating to German, Translated from French, Showing original), or a warning icon plus Couldn't translate.
- Every control is at least 32px tall, and labels reserve the width of their longest version, so nothing moves under the pointer.

### Motion

- Streaming: chunks of 3 to 6 words (about 10 characters in Japanese) land every 34ms and only fade in over 140ms. No blur, slide or per word spring.
- The text on screen dims to 45% over 200ms as translating starts, and each sentence that starts in the new language removes one dimmed sentence, so the translation replaces the paragraph sentence by sentence.
- Cached translations and the original swap with one crossfade: the old text leaves in 100ms, the new one fades in over 160ms with a 2px rise.
- The paragraph's height follows its text with a critically damped spring (visualDuration 0.24, no bounce); window resizes cut straight to the new height.
- Status labels crossfade in one shared cell; the picker and toggle labels crossfade inside their reserved width. The menu fades and scales from 98% in 150ms.
- Reduced motion keeps every end state and announcement but drops chunk fades, crossfades and the height spring, and autoplay runs once.

### Responsive behavior

- The card fills its container up to 620px and pads 16px on phones.
- Below a 470px card width the status line drops under the controls, left-aligned with the text; below 380px the chip shows just the language name.
- Names and meta truncate with an ellipsis; the paragraph wraps with text-wrap: pretty. No horizontal scroll at 360px.

### Performance

- Chunks append as spans with a CSS fade, so streaming re-renders one paragraph and never animates layout.
- One ResizeObserver drives the height spring; autoplay pauses through an IntersectionObserver while the card is off screen.
- Every request owns an AbortController; switching language or unmounting cancels the network call and timers.

### Notes for AI

- Wire translate to your model. Return an async generator of deltas to stream real tokens, or a Promise<string> and the component streams it in chunks itself. Always pass the signal to fetch.
- Cache lives per instance and per text; a new text prop clears it. Persist translations yourself (onTranslate) if you want them across sessions, then pass them back in translations.
- Use the source language as value to show the original. Show original remembers the last translated language for Show translation.
- Keep one paragraph or message per instance. For a whole thread, render one AiTranslate per message and control value from a shared preferred language.
- Model names in samples must be current: Claude Haiku 5.5 is the default credit; swap the mark and name for your provider.
- Sentence splitting keeps decimals like 4.2 whole and handles 。！？ for Japanese.

### Related

- [Chat thread](https://uiarc.dev/components/chat-thread/markdown): A chat thread with grouped messages, reactions, read receipts, typing, and a composer with attachments.
- [Text shimmer](https://uiarc.dev/components/text-shimmer/markdown): Show ongoing work with a calm light across the words.
- [Dropdown menu](https://uiarc.dev/components/dropdown-menu/markdown): A focused list of actions anchored to a trigger.
- [Response feedback](https://uiarc.dev/components/response-feedback/markdown): A feedback control for AI replies where thumbs down opens an inline panel with reason chips and an optional note, thumbs up fills and asks what was good, and a submit shows a short thank-you before folding back into the row.
- [Meeting summary](https://uiarc.dev/components/meeting-summary/markdown): An AI meeting notes card: the header shows the Google Meet or Zoom mark, the attendees and the duration. Summary, Decisions and Action items stream in after a short summarizing pass. Hover any line to see the transcript quote it came from, then check off action items or send them to Linear or Notion.

### Also in ai

- [Agent status](https://uiarc.dev/components/agent-status/markdown): A compact live status pill for a running AI agent: the agent's mark in a live ring, the current activity and an elapsed timer, opening into the steps so far.
- [Tool call](https://uiarc.dev/components/tool-call/markdown): A tool call row for agent transcripts: the tool's mark and the call in plain words, a live state while it runs, and the input and output a click away, with approval and retry when needed.
- [Agent plan](https://uiarc.dev/components/agent-plan/markdown): The plan an agent writes before it acts: edit, reorder or add steps while it is a draft, then watch it work through them as a live checklist.
- [Agent timeline](https://uiarc.dev/components/agent-timeline/markdown): A compact timeline of one orchestrated agent run: the orchestrator and its subagents share a time axis, handoffs draw in between rows, and a playhead replays thinking, tool calls and waiting while the header counts time, tokens and cost. Hover a span for what it did, or click it to trace its handoff path.
- [Context window](https://uiarc.dev/components/context-window/markdown): An AI context window as a grid of 200 cells: the system prompt, tools, files, summary and messages fill it in order, a threshold row marks where compaction starts, and sending a message, attaching a file or compacting shows exactly how much still fits.
- [Reasoning block](https://uiarc.dev/components/reasoning-block/markdown): The collapsible thinking block of an AI reply. While the model thinks, a shimmering label counts the seconds and the latest reasoning streams underneath. When it finishes, it folds to "Thought for 7s" and opens to show the full reasoning as calm steps with headings.
- [Source cards](https://uiarc.dev/components/source-cards/markdown): A row of cited sources under an AI answer where cards stream in with real site marks while the model searches, the overflow collapses into a stack of favicons, hovering lifts a preview with the passage, and an inline [n] citation highlights its card.
- [Model card](https://uiarc.dev/components/model-card/markdown): A model details card where switching models rolls every price, limit and score in place, a token slider estimates monthly cost live, and benchmark bars show each model's rank on hover. Compare crossfades to a side-by-side table against any rival with the better values marked, and the card never changes size.
- [AI workflow](https://uiarc.dev/components/ai-workflow/markdown): A Linear-style AI workflow card where a Gmail trigger, a Claude step, a branch and Slack and Linear actions sit on one hairline rail, and a test run glides down it, opening each step's output inline. Steps are added from a compact command menu with real app marks.
- [Code suggestion](https://uiarc.dev/components/code-suggestion/markdown): An AI code edit suggestion where the model's proposed changes stream into a small editor panel as inline diff hunks, and you accept or reject each one, or all at once with Cmd+Enter. Accepted hunks fold into the file with a smooth height change.
- [Ghost text](https://uiarc.dev/components/ghost-text/markdown): An inline AI autocomplete where muted ghost text continues your sentence exactly at the caret and Tab turns it solid in place. Cmd+Right takes it one word at a time, Escape fades it away, and a calm chip shows the model behind it.
- [Image generation](https://uiarc.dev/components/image-generation/markdown): An image studio where each image forms on a dot matrix: a soft halftone wave breathes across the grid, the dots take the colours of the coming photo and grow into a coloured halftone, then blur away into the sharp photo. One large canvas with a mono size label, a filmstrip of four variations, a prompt bar with model and ratio, and upscale with a sweeping dot band, vary or download, with real provider marks and a built-in simulation.
- [Dictation button](https://uiarc.dev/components/dictation-button/markdown): A chat composer with voice input, where the mic springs into a recording pill with a smooth live waveform, a timer, and cancel and insert buttons. Words stream into the field as you speak, muted until the recognizer settles them.
- [Speech player](https://uiarc.dev/components/speech-player/markdown): A read-aloud player for AI replies. The Read aloud button in the message's action row turns into a compact player with play, a scrubbable progress bar, speed and a voice picker, and a highlight follows the spoken word through the reply, karaoke style.
- [Reply draft](https://uiarc.dev/components/reply-draft/markdown): An AI email reply drafter where Claude streams a reply under a received Gmail message. Quick replies steer a fresh draft, tone and length rewrite it with a single crossfade, and you can edit the finished draft before you insert it.
- [Agent handoff](https://uiarc.dev/components/agent-handoff/markdown): A support conversation where an AI assistant hands off to a person. When it transfers, a card shows the summary it passes to the team and the typical wait. The person then joins and takes over, and a thin timeline on the left marks each step.
- [PII redaction](https://uiarc.dev/components/pii-redaction/markdown): A guardrail card where personal data is redacted before the prompt reaches the model. Scan marks each name, email, phone number and card with its type and swaps it for a placeholder like [EMAIL_1]. The safe prompt travels to Claude, and the reply comes back with the original values put back for the person.
- [LLM cost calculator](https://uiarc.dev/components/llm-cost-calculator/markdown): A pricing calculator for LLM workloads. Set tokens per request, requests per day and prompt caching, and eight current models re-rank by monthly cost. Bars glide and prices roll as you drag.
- [Provider keys](https://uiarc.dev/components/provider-keys/markdown): A settings card for bring-your-own-key AI products. Each provider row shows its real mark, the masked key, a status and when the key was last used. You can reveal a key for five seconds, copy, rotate or remove it with undo. Adding or rotating a key opens an inline form that checks the format as you type, then tests the connection before saving.
- [Generation stats](https://uiarc.dev/components/generation-stats/markdown): A live stats strip for a streaming LLM response where time to first token, speed with a sparkline, output tokens and cost count up in tabular numerals beside the model's real mark, then settle and open into a latency and token cost breakdown.
- [TL;DR toggle](https://uiarc.dev/components/tldr-toggle/markdown): An article card with a Full, Summary and Key points switch and a length slider. Switching streams an AI summary in place of the article as the card's height springs to fit, and each key point links back to the paragraph it came from, which gets scrolled to and highlighted.
- [Connector setup](https://uiarc.dev/components/connector-setup/markdown): A "Connect your tools" card for an AI assistant. Each app connects inline: it redirects, authorizes and runs a first sync with a progress hairline, then lists the scopes it was granted and offers Disconnect with an inline confirm.
- [Smart form fill](https://uiarc.dev/components/smart-form-fill/markdown): A paste-to-fill form card where AI reads an email signature or messy notes and fills a contact field by field. Each value flashes in with a confidence dot, its source lights up in the pasted text, low-confidence guesses ask for review, and Undo puts the old values back.
- [Enrich column](https://uiarc.dev/components/enrich-column/markdown): An AI enrichment column for a data table, where one prompt runs down every row and each cell shimmers while it works, then settles into a value with its source or a failure you can retry.
- [Ticket router](https://uiarc.dev/components/ticket-router/markdown): A support ticket router where messages from Gmail, Intercom, Slack and Zendesk come in one at a time. An AI classifier labels each one with intent, sentiment and confidence, and the ticket moves into a team lane with an assignee. Low confidence tickets wait in a review lane, and one click there routes them to the suggested team.
- [Ask your data](https://uiarc.dev/components/ask-your-data/markdown): A natural language to chart card: you ask a question, PostgreSQL streams into a collapsible, syntax highlighted panel, the query runs with a rolling row count, and the answer builds as stacked bars, lines or a table, with a one line insight streamed in underneath.
- [Agent cursor](https://uiarc.dev/components/agent-cursor/markdown): A live document where Claude edits like a collaborator. Its labeled cursor comes out of its avatar, selects a paragraph and streams in a rewrite, adds a heading and fixes a typo, while a teammate's cursor reads along. Changes stay tinted until someone accepts or undoes them from a floating review bar.
- [Provider status](https://uiarc.dev/components/provider-status/markdown): A status card for the AI providers your product depends on. Each row shows the provider's real mark, its health as an icon and label, p50 latency and a 30-day uptime bar with a tooltip for each day. An incident row expands into its timeline of updates, and the card checks again on a visible countdown.
- [Training run](https://uiarc.dev/components/training-run/markdown): A fine-tuning job card where a live train and validation loss curve draws across a fixed step axis that doubles as the epoch progress bar. It shows the learning rate, elapsed time, ETA and the latest evals and checkpoints, has Pause and Cancel while it runs, and ends in results with a Deploy button.
- [AI command](https://uiarc.dev/components/ai-command/markdown): A Cmd+K command palette with an AI mode. Search pages and actions, or press Tab to ask a question: the answer streams inside the palette with numbered sources, and the next steps it suggests, like filing a Linear issue or opening a Notion doc, run straight from the list.
- [Starter prompts](https://uiarc.dev/components/starter-prompts/markdown): A greeting and a grid of starter cards for the empty state of an AI app. The cards are grouped into Write, Code, Analyze and Plan tabs, and a shuffle swaps them with a short staggered crossfade. Picking a card fills the composer, and cards that use a connected app show its mark (Gmail, GitHub, Notion, Linear, Google Calendar).
- [AI mascot](https://uiarc.dev/components/ai-mascot/markdown): A small assistant character, a soft pebble with pill eyes and a companion dot, that shows what the AI is doing. It breathes and glances when idle, leans in to listen, looks up while the dot orbits its head, reads along the line it writes, squints with a sparkle when done and shakes once with worried brows on an error.
- [Image reveal](https://uiarc.dev/components/image-reveal/markdown): An image generation canvas where a soft, blurred preview made from the image's own colors sharpens top to bottom behind a soft-edged band. It works the way ChatGPT, Midjourney and Gemini show images forming, with fine film grain, a translucent progress pill and calm queued and error states.
- [AI spark](https://uiarc.dev/components/ai-spark/markdown): A brand-quality animated spark mark. Four tapered rays and four lighter diagonals breathe at rest, ripple while thinking, pulse like a heartbeat while writing, then gather and settle when done. Every status change blends from the pose the mark is already in.
- [Pixel mascot](https://uiarc.dev/components/pixel-mascot/markdown): A pixel-art robot that shows what an AI assistant is doing. It idles, thinks, types, celebrates and errors in frame-stepped sprite animations, and stays crisp at every integer size from 24px to 192px.
- [Ghost mascot](https://uiarc.dev/components/ghost-mascot/markdown): A floating ghost mascot whose soft sheet ripples at the hem while it hovers. It blinks when idle, turns toward you to listen, fades a little translucent while thinking, draws a tiny pen line while writing, smiles with a sparkle when done and wobbles once on an error.
- [Cube mascot](https://uiarc.dev/components/cube-mascot/markdown): An isometric cube mascot where three shaded faces and a painted-on face show what the assistant is doing. It turns a quarter turn in eased steps while thinking, prints lines onto the floor while writing, settles with a sparkle when done, and shakes once on error.
- [Tone tuner](https://uiarc.dev/components/tone-tuner/markdown): A brand voice card where two sliders (formality and detail) and Friendly, Confident and Empathetic chips rewrite a customer reply. Each changed sentence crossfades in place, new words can be highlighted against the original, and Copy takes the current version.
- [Upgrade prompt](https://uiarc.dev/components/upgrade-prompt/markdown): An upgrade nudge for the moment someone hits a limit. It shows a usage meter at 50 of 50 AI credits, a rolling price with a monthly and yearly toggle, three concrete unlocks with real model marks, and Upgrade or Maybe later. Upgrading leads into a success state with the new limits, and the card never changes size between states.
- [Referral card](https://uiarc.dev/components/referral-card/markdown): A give-and-get referral card where people copy or share their invite link, invite friends by email as chips, and watch invites move from invited to signed up to earned, with the credit total counting up and a milestone reward unlocking.
- [Trial banner](https://uiarc.dev/components/trial-banner/markdown): A trial status banner where a ring counts down the days left, the copy names what the workspace loses, and the upgrade path is one click away. It comes as a slim banner, a sidebar card or a header pill. It shifts to a warning tone in the last days, has expired and upgraded states, and folds into the pill when dismissed or snoozed.
- [Team switcher](https://uiarc.dev/components/team-switcher/markdown): A workspace switcher like Linear, Vercel or Slack. The trigger shows the current workspace's logo and plan. The menu has search, your role in each workspace and a Cmd+1 to 9 shortcut for each, and lets you create or join a workspace inline. A highlight glides between rows, and switching crossfades the trigger through a short loading state.
- [Live visitors](https://uiarc.dev/components/live-visitors/markdown): A realtime visitors card where the live count rolls digit by digit, new arrivals ping in on a dotted world map, the top pages reorder with bars, and signups and upgrades tick in with country flags.
- [Social proof toast](https://uiarc.dev/components/social-proof-toast/markdown): A stack of social proof notifications for landing and pricing pages, where recent trials, upgrades and verified purchases from people and companies arrive every few seconds. The stack pauses and fans out on hover, and visitors can dismiss any toast.
- [Install snippet](https://uiarc.dev/components/install-snippet/markdown): A "get started in 30 seconds" card where framework tabs, three numbered steps and highlighted snippets take a developer from install to first event. Generate key wipes a fresh API key into the placeholder in place.

### Guidance for AI tools

AI translate: A message card where picking a language streams the AI translation in place, sentence by sentence over the dimmed original, with a detected-language chip, a Show original toggle and a status line credited to the model's mark. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## TL;DR toggle

> An article card with a Full, Summary and Key points switch and a length slider. Switching streams an AI summary in place of the article as the card's height springs to fit, and each key point links back to the paragraph it came from, which gets scrolled to and highlighted.

- Type: Component (special)
- Access: Arc Pro
- Page: https://uiarc.dev/components/tldr-toggle
- Markdown: https://uiarc.dev/components/tldr-toggle/markdown
- Source file: `registry/components/tldr-toggle/tldr-toggle.tsx`
- Dependencies: motion, lucide-react, @radix-ui/react-tooltip
- Keywords: special, ai, new, tldr, summarize, summary toggle, ai summary, key points, article summary, read mode, length slider, streaming summary, source links, citations

### When to use

- Offering a quick summary or key points above or in place of a long article, doc or report.
- Letting readers verify AI claims against the source, through key points that link back to paragraphs.
- Reading surfaces where people choose how much detail they want with a length control.

### When not to use

- Open-ended questions about content: use an answer or chat component such as ai-answer.
- Short content under a couple of paragraphs, where a summary saves no time.
- Summaries of many documents at once: use a list or a digest layout instead of one card per item.

### Installation

TL;DR toggle is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/tldr-toggle
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { TldrToggle, type TldrSummarize } from "@/components/arc/tldr-toggle/tldr-toggle";

// Stream from your route: newline-delimited JSON events, { type: "text", text } or { type: "point", source }.
const summarize: TldrSummarize = async function* ({ mode, length, targetWords, pointCount, article, signal }) {
  const response = await fetch("/api/tldr", {
    method: "POST",
    body: JSON.stringify({ mode, length, targetWords, pointCount, paragraphs: article.paragraphs }),
    signal,
  });
  const reader = response.body!.pipeThrough(new TextDecoderStream()).getReader();
  let buffer = "";
  for (;;) {
    const { value, done } = await reader.read();
    if (done) break;
    buffer += value;
    const lines = buffer.split("\n");
    buffer = lines.pop() ?? "";
    for (const line of lines) if (line) yield JSON.parse(line);
  }
};

export function PostSummary({ post }) {
  return (
    <TldrToggle
      article={{
        title: post.title,
        source: { name: "Engineering blog" },
        author: { name: post.author.name, avatar: post.author.avatar },
        date: post.date,
        paragraphs: post.paragraphs, // [{ id: "intro", text: "..." }, ...]
      }}
      summarize={summarize}
      model={{ name: "Claude Haiku 5.5", mark: <ClaudeMark style={{ color: "#D97757" }} /> }}
      onJump={id => track("tldr_jump", { id })}
    />
  );
}
```

### API reference

#### TldrToggle

An article card with a Full, Summary and Key points switch and a length slider. Switching streams an AI summary in place of the article in fast 3 to 8 word chunks while the card's height follows on a spring with no bounce. Key points arrive as a checklist: each point ticks when it is written, and once the list is done its ¶ jump link switches back to the article, scrolls the source paragraph into view and highlights it. Results are kept per mode and length, so switching back is instant; Regenerate asks again, Stop or Escape ends a stream and keeps what arrived, and a failure shows the message with Try again. With no props it summarizes a sample Linear engineering post with a simulated Claude Haiku 5.5 and opens the summary by itself once in view.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `article` | `{ title: string; paragraphs: { id: string; text: string }[]; source?: { name: string; mark?: ReactNode }; author?: { name: string; avatar?: string }; date?: string; readingTime?: string }` | `tldrSampleArticle` | The article to show and summarize. Paragraph ids are what key points link back to. readingTime is worked out at 230 words a minute when left out. An article with no paragraphs shows a quiet empty state. |
| `summarize` | `(request: TldrRequest) => AsyncIterable<TldrStreamEvent> \| Promise<string \| TldrKeyPoint[]>` | – | Produces the result. The request carries mode ("summary" \| "points"), length (1 to 5), targetWords (35 to 130), pointCount (3 to 7), the article and an AbortSignal that fires on Stop, Escape, a mode or length change, or unmount. Stream { type: "text", text } events for prose; for key points send { type: "point", source: paragraphId } before each point's text. A promise of the finished string or points also works: the card streams it in chunks itself. Leave it out to run the built-in simulation, which sends nothing. |
| `model` | `{ name: string; mark?: ReactNode }` | `Claude Haiku 5.5` | The model credited in the footer, with a 14px mark. Give a mono mark its brand color, for example the Claude mark in #D97757. |
| `mode` | `"full" \| "summary" \| "points"` | – | Controlled mode. Pair with onModeChange. |
| `defaultMode` | `"full" \| "summary" \| "points"` | `"full"` | Starting mode when uncontrolled. |
| `onModeChange` | `(mode: TldrMode) => void` | – | Called when the switch, a jump link or autoplay changes the mode. |
| `length` | `1 \| 2 \| 3 \| 4 \| 5` | – | Controlled length. Summaries aim for about 35, 60, 85, 100 and 130 words; key points return 3 to 7 items. |
| `defaultLength` | `1 \| 2 \| 3 \| 4 \| 5` | `2` | Starting length when uncontrolled. |
| `onLengthChange` | `(length: TldrLength) => void` | – | Called when a slider drag is released or a key moves it, not on every step, so each change makes one request. |
| `onComplete` | `(result: { mode; length; text: string; points?: TldrKeyPoint[]; words: number }) => void` | – | Called when a result finishes, for analytics or a server-side cache. Stopped and failed runs do not call it. |
| `onJump` | `(paragraphId: string) => void` | – | Called when a key point's jump link is used, before the card scrolls to the paragraph. |
| `autoPlay` | `boolean` | `true without summarize` | Opens the summary by itself once the card is half in view for a second, unless the reader has already touched the card. |
| `simulated` | `boolean` | `true without summarize` | Adds "Simulated, nothing was sent" to announcements and error text. Set it when you wrap simulateTldr yourself. |
| `className` | `string` | – | Class on the root element. |

#### simulateTldr

The simulation behind the preview, exported for prototypes and tests. It waits briefly, then streams the authored summary or key points for the sample article (or lead sentences of any other article) in 3 to 8 word chunks every 30 to 40ms. Nothing is sent anywhere.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `request` (required) | `TldrRequest` | – | The request the card passes to summarize. |
| `options.fail` | `boolean` | `false` | Throws after the thinking pause, to show the error state. |
| `options.thinkMs` | `number` | `700` | Milliseconds of thinking before the first chunk. |

#### streamResult

Turns a finished string or key point list into paced stream events, honoring the AbortSignal. Useful when a provider returns whole results but you still want the card to stream.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `result` (required) | `string \| TldrKeyPoint[]` | – | The finished summary, or the key points with their source paragraph ids. |
| `signal` (required) | `AbortSignal` | – | Stops the stream. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Tab | Moves through the mode switch, the length slider, the key point jump links and the footer actions. |
| Arrow keys | On the mode switch, move between Full, Summary and Key points. On the slider, change the length by one step; each step makes one request. |
| Home / End | Jump to the first or last mode, or the shortest or longest length. |
| Enter / Space | On a jump link, switch to the article, scroll to its source paragraph, move focus there and highlight it. |
| Escape | Stops a running stream and keeps what arrived. |

### Accessibility

- The card is an article with the title as a heading. The mode switch is a labelled group of pressed buttons, the length is a slider whose spoken value is the target ("~60 words", "4 points"), disabled in Full mode.
- A polite live region announces each run once ("Summarizing with Claude Haiku 5.5", "Summary ready, 58 words", "4 key points ready", "Stopped"), never the streamed chunks. With the simulation it adds "Simulated, nothing was sent".
- The card is aria-busy while a result streams. Failures render as an alert with the message and a Try again button.
- Jump links are named after their point ("Jump to paragraph 3: Partial bootstrapping loads..."), and the jump moves focus to the highlighted paragraph so screen reader and keyboard users land where the eye does.
- Status is never color alone: done, stopped and failed each pair an icon with a word, and key points tick from a dashed circle to a check.

### Motion

- The body's height follows its content on one critically damped spring (visualDuration .26, no bounce), whether a view swaps or text streams in. A container resize cuts straight to the new height.
- Views swap with a single crossfade: old out in 100ms, new in over 160ms. The footer's state label and actions crossfade the same way.
- Streamed chunks of 3 to 8 words arrive every 30 to 40ms and only fade in over 140ms. A cached result appears whole, with no fade.
- Thinking lasts about 0.7s with a calm shimmer on its label; the footer's Writing label shimmers while text arrives, so only one shimmer runs at a time.
- A jump waits for the height to settle, scrolls smoothly to the paragraph and fades a highlight in over 160ms and out over 600ms.
- Reduced motion drops the height spring, the chunk fades, smooth scrolling and the icon transitions; every end state and the highlight remain.

### Responsive behavior

- The card fills its container up to 680px. Below 520px the length slider moves under the mode switch at full width; below 440px the padding steps from 24px to 16px.
- Footer labels stay on one line, the model name truncates first, and actions keep 32px targets.
- Works at 360px with no horizontal scroll; long titles wrap and balance.

### Performance

- Each chunk is a small span with a CSS fade; a long summary renders a few dozen nodes.
- One ResizeObserver drives the height spring, and results are cached per mode and length, so switching back makes no request.
- Changing the slider aborts the previous request through its AbortSignal before the next starts.

### Notes for AI

- Use it where people read long content inside a product: blog posts, docs pages, release notes, tickets, research reports or support articles.
- Give paragraphs stable ids and have the model return the id each key point came from, so jump links land on the right paragraph.
- Pass length to the model as targetWords or pointCount rather than a vague word like "short".
- Stream when the provider streams; return a promise when it does not, and the card paces it.
- Without summarize the card runs a simulation and says so in its announcements; never ship that to production.

### Related

- [AI answer](https://uiarc.dev/components/blocks/ai-answer/markdown): One AI answer set like a clean article: it thinks, shows its sources as small cards with colored marks, and streams a formatted answer where every citation lights the sentence it supports. Copy, regenerate with options, rate, share, page through versions and ask a related question in place.
- [Text shimmer](https://uiarc.dev/components/text-shimmer/markdown): Show ongoing work with a calm light across the words.
- [Segmented control](https://uiarc.dev/components/segmented-control/markdown): Switch between a small set of related views.
- [Slider](https://uiarc.dev/components/slider/markdown): Pick a value or a range on a track that follows your finger.
- [Copy button](https://uiarc.dev/components/copy-button/markdown): Copy a value with immediate confirmation.
- [Tool call](https://uiarc.dev/components/tool-call/markdown): A tool call row for agent transcripts: the tool's mark and the call in plain words, a live state while it runs, and the input and output a click away, with approval and retry when needed.

### Also in ai

- [Agent status](https://uiarc.dev/components/agent-status/markdown): A compact live status pill for a running AI agent: the agent's mark in a live ring, the current activity and an elapsed timer, opening into the steps so far.
- [Agent plan](https://uiarc.dev/components/agent-plan/markdown): The plan an agent writes before it acts: edit, reorder or add steps while it is a draft, then watch it work through them as a live checklist.
- [Agent timeline](https://uiarc.dev/components/agent-timeline/markdown): A compact timeline of one orchestrated agent run: the orchestrator and its subagents share a time axis, handoffs draw in between rows, and a playhead replays thinking, tool calls and waiting while the header counts time, tokens and cost. Hover a span for what it did, or click it to trace its handoff path.
- [Context window](https://uiarc.dev/components/context-window/markdown): An AI context window as a grid of 200 cells: the system prompt, tools, files, summary and messages fill it in order, a threshold row marks where compaction starts, and sending a message, attaching a file or compacting shows exactly how much still fits.
- [Reasoning block](https://uiarc.dev/components/reasoning-block/markdown): The collapsible thinking block of an AI reply. While the model thinks, a shimmering label counts the seconds and the latest reasoning streams underneath. When it finishes, it folds to "Thought for 7s" and opens to show the full reasoning as calm steps with headings.
- [Source cards](https://uiarc.dev/components/source-cards/markdown): A row of cited sources under an AI answer where cards stream in with real site marks while the model searches, the overflow collapses into a stack of favicons, hovering lifts a preview with the passage, and an inline [n] citation highlights its card.
- [Model card](https://uiarc.dev/components/model-card/markdown): A model details card where switching models rolls every price, limit and score in place, a token slider estimates monthly cost live, and benchmark bars show each model's rank on hover. Compare crossfades to a side-by-side table against any rival with the better values marked, and the card never changes size.
- [AI workflow](https://uiarc.dev/components/ai-workflow/markdown): A Linear-style AI workflow card where a Gmail trigger, a Claude step, a branch and Slack and Linear actions sit on one hairline rail, and a test run glides down it, opening each step's output inline. Steps are added from a compact command menu with real app marks.
- [Code suggestion](https://uiarc.dev/components/code-suggestion/markdown): An AI code edit suggestion where the model's proposed changes stream into a small editor panel as inline diff hunks, and you accept or reject each one, or all at once with Cmd+Enter. Accepted hunks fold into the file with a smooth height change.
- [Ghost text](https://uiarc.dev/components/ghost-text/markdown): An inline AI autocomplete where muted ghost text continues your sentence exactly at the caret and Tab turns it solid in place. Cmd+Right takes it one word at a time, Escape fades it away, and a calm chip shows the model behind it.
- [Image generation](https://uiarc.dev/components/image-generation/markdown): An image studio where each image forms on a dot matrix: a soft halftone wave breathes across the grid, the dots take the colours of the coming photo and grow into a coloured halftone, then blur away into the sharp photo. One large canvas with a mono size label, a filmstrip of four variations, a prompt bar with model and ratio, and upscale with a sweeping dot band, vary or download, with real provider marks and a built-in simulation.
- [Dictation button](https://uiarc.dev/components/dictation-button/markdown): A chat composer with voice input, where the mic springs into a recording pill with a smooth live waveform, a timer, and cancel and insert buttons. Words stream into the field as you speak, muted until the recognizer settles them.
- [Speech player](https://uiarc.dev/components/speech-player/markdown): A read-aloud player for AI replies. The Read aloud button in the message's action row turns into a compact player with play, a scrubbable progress bar, speed and a voice picker, and a highlight follows the spoken word through the reply, karaoke style.
- [Meeting summary](https://uiarc.dev/components/meeting-summary/markdown): An AI meeting notes card: the header shows the Google Meet or Zoom mark, the attendees and the duration. Summary, Decisions and Action items stream in after a short summarizing pass. Hover any line to see the transcript quote it came from, then check off action items or send them to Linear or Notion.
- [Reply draft](https://uiarc.dev/components/reply-draft/markdown): An AI email reply drafter where Claude streams a reply under a received Gmail message. Quick replies steer a fresh draft, tone and length rewrite it with a single crossfade, and you can edit the finished draft before you insert it.
- [Agent handoff](https://uiarc.dev/components/agent-handoff/markdown): A support conversation where an AI assistant hands off to a person. When it transfers, a card shows the summary it passes to the team and the typical wait. The person then joins and takes over, and a thin timeline on the left marks each step.
- [PII redaction](https://uiarc.dev/components/pii-redaction/markdown): A guardrail card where personal data is redacted before the prompt reaches the model. Scan marks each name, email, phone number and card with its type and swaps it for a placeholder like [EMAIL_1]. The safe prompt travels to Claude, and the reply comes back with the original values put back for the person.
- [Response feedback](https://uiarc.dev/components/response-feedback/markdown): A feedback control for AI replies where thumbs down opens an inline panel with reason chips and an optional note, thumbs up fills and asks what was good, and a submit shows a short thank-you before folding back into the row.
- [LLM cost calculator](https://uiarc.dev/components/llm-cost-calculator/markdown): A pricing calculator for LLM workloads. Set tokens per request, requests per day and prompt caching, and eight current models re-rank by monthly cost. Bars glide and prices roll as you drag.
- [Provider keys](https://uiarc.dev/components/provider-keys/markdown): A settings card for bring-your-own-key AI products. Each provider row shows its real mark, the masked key, a status and when the key was last used. You can reveal a key for five seconds, copy, rotate or remove it with undo. Adding or rotating a key opens an inline form that checks the format as you type, then tests the connection before saving.
- [Generation stats](https://uiarc.dev/components/generation-stats/markdown): A live stats strip for a streaming LLM response where time to first token, speed with a sparkline, output tokens and cost count up in tabular numerals beside the model's real mark, then settle and open into a latency and token cost breakdown.
- [AI translate](https://uiarc.dev/components/ai-translate/markdown): A message card where picking a language streams the AI translation in place, sentence by sentence over the dimmed original, with a detected-language chip, a Show original toggle and a status line credited to the model's mark.
- [Connector setup](https://uiarc.dev/components/connector-setup/markdown): A "Connect your tools" card for an AI assistant. Each app connects inline: it redirects, authorizes and runs a first sync with a progress hairline, then lists the scopes it was granted and offers Disconnect with an inline confirm.
- [Smart form fill](https://uiarc.dev/components/smart-form-fill/markdown): A paste-to-fill form card where AI reads an email signature or messy notes and fills a contact field by field. Each value flashes in with a confidence dot, its source lights up in the pasted text, low-confidence guesses ask for review, and Undo puts the old values back.
- [Enrich column](https://uiarc.dev/components/enrich-column/markdown): An AI enrichment column for a data table, where one prompt runs down every row and each cell shimmers while it works, then settles into a value with its source or a failure you can retry.
- [Ticket router](https://uiarc.dev/components/ticket-router/markdown): A support ticket router where messages from Gmail, Intercom, Slack and Zendesk come in one at a time. An AI classifier labels each one with intent, sentiment and confidence, and the ticket moves into a team lane with an assignee. Low confidence tickets wait in a review lane, and one click there routes them to the suggested team.
- [Ask your data](https://uiarc.dev/components/ask-your-data/markdown): A natural language to chart card: you ask a question, PostgreSQL streams into a collapsible, syntax highlighted panel, the query runs with a rolling row count, and the answer builds as stacked bars, lines or a table, with a one line insight streamed in underneath.
- [Agent cursor](https://uiarc.dev/components/agent-cursor/markdown): A live document where Claude edits like a collaborator. Its labeled cursor comes out of its avatar, selects a paragraph and streams in a rewrite, adds a heading and fixes a typo, while a teammate's cursor reads along. Changes stay tinted until someone accepts or undoes them from a floating review bar.
- [Provider status](https://uiarc.dev/components/provider-status/markdown): A status card for the AI providers your product depends on. Each row shows the provider's real mark, its health as an icon and label, p50 latency and a 30-day uptime bar with a tooltip for each day. An incident row expands into its timeline of updates, and the card checks again on a visible countdown.
- [Training run](https://uiarc.dev/components/training-run/markdown): A fine-tuning job card where a live train and validation loss curve draws across a fixed step axis that doubles as the epoch progress bar. It shows the learning rate, elapsed time, ETA and the latest evals and checkpoints, has Pause and Cancel while it runs, and ends in results with a Deploy button.
- [AI command](https://uiarc.dev/components/ai-command/markdown): A Cmd+K command palette with an AI mode. Search pages and actions, or press Tab to ask a question: the answer streams inside the palette with numbered sources, and the next steps it suggests, like filing a Linear issue or opening a Notion doc, run straight from the list.
- [Starter prompts](https://uiarc.dev/components/starter-prompts/markdown): A greeting and a grid of starter cards for the empty state of an AI app. The cards are grouped into Write, Code, Analyze and Plan tabs, and a shuffle swaps them with a short staggered crossfade. Picking a card fills the composer, and cards that use a connected app show its mark (Gmail, GitHub, Notion, Linear, Google Calendar).
- [AI mascot](https://uiarc.dev/components/ai-mascot/markdown): A small assistant character, a soft pebble with pill eyes and a companion dot, that shows what the AI is doing. It breathes and glances when idle, leans in to listen, looks up while the dot orbits its head, reads along the line it writes, squints with a sparkle when done and shakes once with worried brows on an error.
- [Image reveal](https://uiarc.dev/components/image-reveal/markdown): An image generation canvas where a soft, blurred preview made from the image's own colors sharpens top to bottom behind a soft-edged band. It works the way ChatGPT, Midjourney and Gemini show images forming, with fine film grain, a translucent progress pill and calm queued and error states.
- [AI spark](https://uiarc.dev/components/ai-spark/markdown): A brand-quality animated spark mark. Four tapered rays and four lighter diagonals breathe at rest, ripple while thinking, pulse like a heartbeat while writing, then gather and settle when done. Every status change blends from the pose the mark is already in.
- [Pixel mascot](https://uiarc.dev/components/pixel-mascot/markdown): A pixel-art robot that shows what an AI assistant is doing. It idles, thinks, types, celebrates and errors in frame-stepped sprite animations, and stays crisp at every integer size from 24px to 192px.
- [Ghost mascot](https://uiarc.dev/components/ghost-mascot/markdown): A floating ghost mascot whose soft sheet ripples at the hem while it hovers. It blinks when idle, turns toward you to listen, fades a little translucent while thinking, draws a tiny pen line while writing, smiles with a sparkle when done and wobbles once on an error.
- [Cube mascot](https://uiarc.dev/components/cube-mascot/markdown): An isometric cube mascot where three shaded faces and a painted-on face show what the assistant is doing. It turns a quarter turn in eased steps while thinking, prints lines onto the floor while writing, settles with a sparkle when done, and shakes once on error.
- [Tone tuner](https://uiarc.dev/components/tone-tuner/markdown): A brand voice card where two sliders (formality and detail) and Friendly, Confident and Empathetic chips rewrite a customer reply. Each changed sentence crossfades in place, new words can be highlighted against the original, and Copy takes the current version.
- [Upgrade prompt](https://uiarc.dev/components/upgrade-prompt/markdown): An upgrade nudge for the moment someone hits a limit. It shows a usage meter at 50 of 50 AI credits, a rolling price with a monthly and yearly toggle, three concrete unlocks with real model marks, and Upgrade or Maybe later. Upgrading leads into a success state with the new limits, and the card never changes size between states.
- [Referral card](https://uiarc.dev/components/referral-card/markdown): A give-and-get referral card where people copy or share their invite link, invite friends by email as chips, and watch invites move from invited to signed up to earned, with the credit total counting up and a milestone reward unlocking.
- [Trial banner](https://uiarc.dev/components/trial-banner/markdown): A trial status banner where a ring counts down the days left, the copy names what the workspace loses, and the upgrade path is one click away. It comes as a slim banner, a sidebar card or a header pill. It shifts to a warning tone in the last days, has expired and upgraded states, and folds into the pill when dismissed or snoozed.
- [Team switcher](https://uiarc.dev/components/team-switcher/markdown): A workspace switcher like Linear, Vercel or Slack. The trigger shows the current workspace's logo and plan. The menu has search, your role in each workspace and a Cmd+1 to 9 shortcut for each, and lets you create or join a workspace inline. A highlight glides between rows, and switching crossfades the trigger through a short loading state.
- [Live visitors](https://uiarc.dev/components/live-visitors/markdown): A realtime visitors card where the live count rolls digit by digit, new arrivals ping in on a dotted world map, the top pages reorder with bars, and signups and upgrades tick in with country flags.
- [Social proof toast](https://uiarc.dev/components/social-proof-toast/markdown): A stack of social proof notifications for landing and pricing pages, where recent trials, upgrades and verified purchases from people and companies arrive every few seconds. The stack pauses and fans out on hover, and visitors can dismiss any toast.
- [Install snippet](https://uiarc.dev/components/install-snippet/markdown): A "get started in 30 seconds" card where framework tabs, three numbered steps and highlighted snippets take a developer from install to first event. Generate key wipes a fresh API key into the placeholder in place.

### Guidance for AI tools

TL;DR toggle: An article card with a Full, Summary and Key points switch and a length slider. Switching streams an AI summary in place of the article as the card's height springs to fit, and each key point links back to the paragraph it came from, which gets scrolled to and highlighted. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Connector setup

> A "Connect your tools" card for an AI assistant. Each app connects inline: it redirects, authorizes and runs a first sync with a progress hairline, then lists the scopes it was granted and offers Disconnect with an inline confirm.

- Type: Component (special)
- Access: Arc Pro
- Page: https://uiarc.dev/components/connector-setup
- Markdown: https://uiarc.dev/components/connector-setup/markdown
- Source file: `registry/components/connector-setup/connector-setup.tsx`
- Dependencies: motion, lucide-react
- Keywords: special, ai, new, connectors, integrations, connect apps, oauth, connect your tools, ai assistant settings, mcp connectors, slack integration, github integration, scopes, permissions, disconnect

### When to use

- An assistant's settings or onboarding step where people connect workspace apps.
- A first-run checklist that needs to show the OAuth handshake and first sync inline, without leaving the page.
- Reviewing which scopes an assistant holds per app and revoking them.

### When not to use

- Browsing dozens of integrations by category: use the integrations-grid block.
- Approving a single action the agent wants to take: use agent-approvals.
- Showing a tool the agent is calling right now: use tool-call.

### Installation

Connector setup is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/connector-setup
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { ConnectorSetup } from "@/components/arc/connector-setup/connector-setup";

export function Integrations({ connectedIds }: { connectedIds: string[] }) {
  return (
    <ConnectorSetup
      defaultConnected={connectedIds}
      connect={async (app, { signal, report }) => {
        const popup = await openOAuthPopup(app.id, { signal });
        report({ phase: "authorizing" });
        const grant = await popup.result;
        report({ phase: "syncing", synced: 0 });
        const { total } = await startFirstSync(app.id, grant, { signal, onProgress: synced => report({ synced }) });
        return { account: grant.workspace, scopes: grant.scopes, synced: total };
      }}
      disconnect={(app, { signal }) => revokeGrant(app.id, { signal })}
      onConnectedChange={ids => saveConnectedApps(ids)}
    />
  );
}
```

### API reference

#### ConnectorSetup

A "Connect your tools" card for an AI assistant. Each app connects inline through redirect, authorize and first sync with a progress line, then lists the scopes it granted with a Disconnect option. With no props it renders eight sample apps and plays a short scripted run.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `connectors` | `Connector[]` | `connectorSamples` | Apps to list: { id, name, description, mark, host?, account?, scopes?, sync?: { count, noun }, keywords? }. `mark` is a built-in id (slack, github, notion, google-drive, linear, jira, salesforce, hubspot) or your own 20px node. |
| `connected` | `string[]` | – | Controlled list of connected ids. |
| `defaultConnected` | `string[]` | `["github", "google-drive"] for the samples, [] otherwise` | Ids connected on mount when uncontrolled. |
| `onConnectedChange` | `(ids: string[]) => void` | – | Called with the new list after a connect or disconnect finishes. |
| `connect` | `(connector, { signal, report }) => Promise<ConnectResult \| void>` | – | Runs your real OAuth flow. Call report({ phase: "authorizing" }) and report({ phase: "syncing", synced }) as it advances; throw an Error to show its message with Retry; return { account?, scopes?, synced? } to finish. `signal` aborts on Cancel or unmount. Simulated when omitted. |
| `disconnect` | `(connector, { signal }) => Promise<void>` | – | Revokes access after the inline confirmation. Simulated when omitted. |
| `onConnect` | `(connector: Connector, result: ConnectResult) => void` | – | Called once a connection completes, with the account, scopes and sync count. |
| `onDisconnect` | `(connector: Connector) => void` | – | Called once access is revoked. |
| `assistantName` | `string` | `"Claude"` | Used in the description, the scopes heading and the footer. |
| `title` | `ReactNode` | `"Connect your tools"` | Card heading. |
| `description` | `ReactNode` | `"Let Claude search and act in the apps your team uses."` | Line under the heading. |
| `searchable` | `boolean` | `true` | Shows the search field. It matches name, description, account and keywords. |
| `searchPlaceholder` | `string` | `"Search apps"` | Placeholder for the search field. |
| `autoPlay` | `boolean` | `true for the samples without connect` | Plays a scripted run once the card is on screen: connect Slack, then a Salesforce attempt that needs admin approval and its retry. Stops at the first pointer or key press. |
| `footer` | `ReactNode` | – | Footer line under the list. Defaults to a short privacy note; pass null to hide it. |
| `className` | `string` | – | Class on the root card. |

#### ConnectorMark

The built-in app marks at any size, for use elsewhere in your settings UI.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `mark` (required) | `ConnectorMarkId \| ReactNode` | – | A built-in id or your own node. |
| `size` | `number` | `20` | Rendered size in px. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Tab | Moves through search, each row's Connect, Cancel, Retry or Connected button, and the open details. |
| Enter / Space | Connects, cancels, retries, or opens and closes a connected app's access details. |
| Escape | Clears the search field, or backs out of the disconnect confirmation. |

### Accessibility

- The card is a labelled group with a real heading; the list is a ul with one li per app.
- A polite live region announces each step: connecting, connected with the sync count, failed with the reason, cancelled and disconnected. With the built-in simulation it adds "Simulated, nothing was sent."
- Status is never color alone: errors pair an alert icon with the message, connected apps show a check with the word Connected.
- The Connected button carries aria-expanded and aria-controls for the details region; Disconnect asks for confirmation and focuses the destructive button only after a deliberate press.
- Content that is fading out leaves the accessibility tree and stops taking clicks immediately.

### Motion

- Status lines and actions swap with one crossfade (out 100ms, in 160ms with a 2px rise) in a shared grid cell, so the row never reflows.
- Progress is a 2px hairline that eases between steps and tracks the sync count linearly; the count rolls in tabular numerals inside a width reserved for its final value.
- Details open with a bounce-free spring on measured height (visualDuration 0.24).
- The scripted run starts only once the card is on screen and stops at the first interaction. Reduced motion keeps every state and announcement but cuts the crossfades and height springs.

### Responsive behavior

- Fluid up to 520px and holds at 360px: names and status lines truncate with an ellipsis while marks and actions keep their size.
- Actions stay 32px tall with full-width rows of 60px, comfortable for touch.
- The details column aligns to the row's text at every width; the disconnect confirmation truncates its question before it wraps.

### Performance

- Pure React and CSS with a few Motion components; marks are inline SVG with no image requests.
- Only the row that is syncing re-renders per frame while its count rolls; other rows stay static.
- Search filters in memory; for hundreds of apps, filter on your side and pass the result as connectors.

### Notes for AI

- Use for onboarding or settings screens where a person grants an assistant access to third-party apps. Pass your own connectors; built-in marks cover Slack, GitHub, Notion, Google Drive, Linear, Jira, Salesforce and HubSpot.
- Wire connect to your OAuth popup or redirect handshake and call report() at each step so the row shows real progress; throw an Error with a short human message ("Needs admin approval") to show Retry.
- Write scopes as plain-language capabilities ("Post replies as Claude"), not raw OAuth scope strings.
- Keep it one card in a settings column. For a full marketplace grid of integrations use the integrations-grid block instead.

### Related

- [Tool call](https://uiarc.dev/components/tool-call/markdown): A tool call row for agent transcripts: the tool's mark and the call in plain words, a live state while it runs, and the input and output a click away, with approval and retry when needed.
- [Agent status](https://uiarc.dev/components/agent-status/markdown): A compact live status pill for a running AI agent: the agent's mark in a live ring, the current activity and an elapsed timer, opening into the steps so far.
- [Agent approvals](https://uiarc.dev/components/blocks/agent-approvals/markdown): One approval card for agents: the waiting tool call reads like a permission prompt with the tool's mark, the agent's reason and its arguments, and you approve, deny or allow it from now on.

### Also in ai

- [Agent plan](https://uiarc.dev/components/agent-plan/markdown): The plan an agent writes before it acts: edit, reorder or add steps while it is a draft, then watch it work through them as a live checklist.
- [Agent timeline](https://uiarc.dev/components/agent-timeline/markdown): A compact timeline of one orchestrated agent run: the orchestrator and its subagents share a time axis, handoffs draw in between rows, and a playhead replays thinking, tool calls and waiting while the header counts time, tokens and cost. Hover a span for what it did, or click it to trace its handoff path.
- [Context window](https://uiarc.dev/components/context-window/markdown): An AI context window as a grid of 200 cells: the system prompt, tools, files, summary and messages fill it in order, a threshold row marks where compaction starts, and sending a message, attaching a file or compacting shows exactly how much still fits.
- [Reasoning block](https://uiarc.dev/components/reasoning-block/markdown): The collapsible thinking block of an AI reply. While the model thinks, a shimmering label counts the seconds and the latest reasoning streams underneath. When it finishes, it folds to "Thought for 7s" and opens to show the full reasoning as calm steps with headings.
- [Source cards](https://uiarc.dev/components/source-cards/markdown): A row of cited sources under an AI answer where cards stream in with real site marks while the model searches, the overflow collapses into a stack of favicons, hovering lifts a preview with the passage, and an inline [n] citation highlights its card.
- [Model card](https://uiarc.dev/components/model-card/markdown): A model details card where switching models rolls every price, limit and score in place, a token slider estimates monthly cost live, and benchmark bars show each model's rank on hover. Compare crossfades to a side-by-side table against any rival with the better values marked, and the card never changes size.
- [AI workflow](https://uiarc.dev/components/ai-workflow/markdown): A Linear-style AI workflow card where a Gmail trigger, a Claude step, a branch and Slack and Linear actions sit on one hairline rail, and a test run glides down it, opening each step's output inline. Steps are added from a compact command menu with real app marks.
- [Code suggestion](https://uiarc.dev/components/code-suggestion/markdown): An AI code edit suggestion where the model's proposed changes stream into a small editor panel as inline diff hunks, and you accept or reject each one, or all at once with Cmd+Enter. Accepted hunks fold into the file with a smooth height change.
- [Ghost text](https://uiarc.dev/components/ghost-text/markdown): An inline AI autocomplete where muted ghost text continues your sentence exactly at the caret and Tab turns it solid in place. Cmd+Right takes it one word at a time, Escape fades it away, and a calm chip shows the model behind it.
- [Image generation](https://uiarc.dev/components/image-generation/markdown): An image studio where each image forms on a dot matrix: a soft halftone wave breathes across the grid, the dots take the colours of the coming photo and grow into a coloured halftone, then blur away into the sharp photo. One large canvas with a mono size label, a filmstrip of four variations, a prompt bar with model and ratio, and upscale with a sweeping dot band, vary or download, with real provider marks and a built-in simulation.
- [Dictation button](https://uiarc.dev/components/dictation-button/markdown): A chat composer with voice input, where the mic springs into a recording pill with a smooth live waveform, a timer, and cancel and insert buttons. Words stream into the field as you speak, muted until the recognizer settles them.
- [Speech player](https://uiarc.dev/components/speech-player/markdown): A read-aloud player for AI replies. The Read aloud button in the message's action row turns into a compact player with play, a scrubbable progress bar, speed and a voice picker, and a highlight follows the spoken word through the reply, karaoke style.
- [Meeting summary](https://uiarc.dev/components/meeting-summary/markdown): An AI meeting notes card: the header shows the Google Meet or Zoom mark, the attendees and the duration. Summary, Decisions and Action items stream in after a short summarizing pass. Hover any line to see the transcript quote it came from, then check off action items or send them to Linear or Notion.
- [Reply draft](https://uiarc.dev/components/reply-draft/markdown): An AI email reply drafter where Claude streams a reply under a received Gmail message. Quick replies steer a fresh draft, tone and length rewrite it with a single crossfade, and you can edit the finished draft before you insert it.
- [Agent handoff](https://uiarc.dev/components/agent-handoff/markdown): A support conversation where an AI assistant hands off to a person. When it transfers, a card shows the summary it passes to the team and the typical wait. The person then joins and takes over, and a thin timeline on the left marks each step.
- [PII redaction](https://uiarc.dev/components/pii-redaction/markdown): A guardrail card where personal data is redacted before the prompt reaches the model. Scan marks each name, email, phone number and card with its type and swaps it for a placeholder like [EMAIL_1]. The safe prompt travels to Claude, and the reply comes back with the original values put back for the person.
- [Response feedback](https://uiarc.dev/components/response-feedback/markdown): A feedback control for AI replies where thumbs down opens an inline panel with reason chips and an optional note, thumbs up fills and asks what was good, and a submit shows a short thank-you before folding back into the row.
- [LLM cost calculator](https://uiarc.dev/components/llm-cost-calculator/markdown): A pricing calculator for LLM workloads. Set tokens per request, requests per day and prompt caching, and eight current models re-rank by monthly cost. Bars glide and prices roll as you drag.
- [Provider keys](https://uiarc.dev/components/provider-keys/markdown): A settings card for bring-your-own-key AI products. Each provider row shows its real mark, the masked key, a status and when the key was last used. You can reveal a key for five seconds, copy, rotate or remove it with undo. Adding or rotating a key opens an inline form that checks the format as you type, then tests the connection before saving.
- [Generation stats](https://uiarc.dev/components/generation-stats/markdown): A live stats strip for a streaming LLM response where time to first token, speed with a sparkline, output tokens and cost count up in tabular numerals beside the model's real mark, then settle and open into a latency and token cost breakdown.
- [AI translate](https://uiarc.dev/components/ai-translate/markdown): A message card where picking a language streams the AI translation in place, sentence by sentence over the dimmed original, with a detected-language chip, a Show original toggle and a status line credited to the model's mark.
- [TL;DR toggle](https://uiarc.dev/components/tldr-toggle/markdown): An article card with a Full, Summary and Key points switch and a length slider. Switching streams an AI summary in place of the article as the card's height springs to fit, and each key point links back to the paragraph it came from, which gets scrolled to and highlighted.
- [Smart form fill](https://uiarc.dev/components/smart-form-fill/markdown): A paste-to-fill form card where AI reads an email signature or messy notes and fills a contact field by field. Each value flashes in with a confidence dot, its source lights up in the pasted text, low-confidence guesses ask for review, and Undo puts the old values back.
- [Enrich column](https://uiarc.dev/components/enrich-column/markdown): An AI enrichment column for a data table, where one prompt runs down every row and each cell shimmers while it works, then settles into a value with its source or a failure you can retry.
- [Ticket router](https://uiarc.dev/components/ticket-router/markdown): A support ticket router where messages from Gmail, Intercom, Slack and Zendesk come in one at a time. An AI classifier labels each one with intent, sentiment and confidence, and the ticket moves into a team lane with an assignee. Low confidence tickets wait in a review lane, and one click there routes them to the suggested team.
- [Ask your data](https://uiarc.dev/components/ask-your-data/markdown): A natural language to chart card: you ask a question, PostgreSQL streams into a collapsible, syntax highlighted panel, the query runs with a rolling row count, and the answer builds as stacked bars, lines or a table, with a one line insight streamed in underneath.
- [Agent cursor](https://uiarc.dev/components/agent-cursor/markdown): A live document where Claude edits like a collaborator. Its labeled cursor comes out of its avatar, selects a paragraph and streams in a rewrite, adds a heading and fixes a typo, while a teammate's cursor reads along. Changes stay tinted until someone accepts or undoes them from a floating review bar.
- [Provider status](https://uiarc.dev/components/provider-status/markdown): A status card for the AI providers your product depends on. Each row shows the provider's real mark, its health as an icon and label, p50 latency and a 30-day uptime bar with a tooltip for each day. An incident row expands into its timeline of updates, and the card checks again on a visible countdown.
- [Training run](https://uiarc.dev/components/training-run/markdown): A fine-tuning job card where a live train and validation loss curve draws across a fixed step axis that doubles as the epoch progress bar. It shows the learning rate, elapsed time, ETA and the latest evals and checkpoints, has Pause and Cancel while it runs, and ends in results with a Deploy button.
- [AI command](https://uiarc.dev/components/ai-command/markdown): A Cmd+K command palette with an AI mode. Search pages and actions, or press Tab to ask a question: the answer streams inside the palette with numbered sources, and the next steps it suggests, like filing a Linear issue or opening a Notion doc, run straight from the list.
- [Starter prompts](https://uiarc.dev/components/starter-prompts/markdown): A greeting and a grid of starter cards for the empty state of an AI app. The cards are grouped into Write, Code, Analyze and Plan tabs, and a shuffle swaps them with a short staggered crossfade. Picking a card fills the composer, and cards that use a connected app show its mark (Gmail, GitHub, Notion, Linear, Google Calendar).
- [AI mascot](https://uiarc.dev/components/ai-mascot/markdown): A small assistant character, a soft pebble with pill eyes and a companion dot, that shows what the AI is doing. It breathes and glances when idle, leans in to listen, looks up while the dot orbits its head, reads along the line it writes, squints with a sparkle when done and shakes once with worried brows on an error.
- [Image reveal](https://uiarc.dev/components/image-reveal/markdown): An image generation canvas where a soft, blurred preview made from the image's own colors sharpens top to bottom behind a soft-edged band. It works the way ChatGPT, Midjourney and Gemini show images forming, with fine film grain, a translucent progress pill and calm queued and error states.
- [AI spark](https://uiarc.dev/components/ai-spark/markdown): A brand-quality animated spark mark. Four tapered rays and four lighter diagonals breathe at rest, ripple while thinking, pulse like a heartbeat while writing, then gather and settle when done. Every status change blends from the pose the mark is already in.
- [Pixel mascot](https://uiarc.dev/components/pixel-mascot/markdown): A pixel-art robot that shows what an AI assistant is doing. It idles, thinks, types, celebrates and errors in frame-stepped sprite animations, and stays crisp at every integer size from 24px to 192px.
- [Ghost mascot](https://uiarc.dev/components/ghost-mascot/markdown): A floating ghost mascot whose soft sheet ripples at the hem while it hovers. It blinks when idle, turns toward you to listen, fades a little translucent while thinking, draws a tiny pen line while writing, smiles with a sparkle when done and wobbles once on an error.
- [Cube mascot](https://uiarc.dev/components/cube-mascot/markdown): An isometric cube mascot where three shaded faces and a painted-on face show what the assistant is doing. It turns a quarter turn in eased steps while thinking, prints lines onto the floor while writing, settles with a sparkle when done, and shakes once on error.
- [Tone tuner](https://uiarc.dev/components/tone-tuner/markdown): A brand voice card where two sliders (formality and detail) and Friendly, Confident and Empathetic chips rewrite a customer reply. Each changed sentence crossfades in place, new words can be highlighted against the original, and Copy takes the current version.
- [Upgrade prompt](https://uiarc.dev/components/upgrade-prompt/markdown): An upgrade nudge for the moment someone hits a limit. It shows a usage meter at 50 of 50 AI credits, a rolling price with a monthly and yearly toggle, three concrete unlocks with real model marks, and Upgrade or Maybe later. Upgrading leads into a success state with the new limits, and the card never changes size between states.
- [Referral card](https://uiarc.dev/components/referral-card/markdown): A give-and-get referral card where people copy or share their invite link, invite friends by email as chips, and watch invites move from invited to signed up to earned, with the credit total counting up and a milestone reward unlocking.
- [Trial banner](https://uiarc.dev/components/trial-banner/markdown): A trial status banner where a ring counts down the days left, the copy names what the workspace loses, and the upgrade path is one click away. It comes as a slim banner, a sidebar card or a header pill. It shifts to a warning tone in the last days, has expired and upgraded states, and folds into the pill when dismissed or snoozed.
- [Team switcher](https://uiarc.dev/components/team-switcher/markdown): A workspace switcher like Linear, Vercel or Slack. The trigger shows the current workspace's logo and plan. The menu has search, your role in each workspace and a Cmd+1 to 9 shortcut for each, and lets you create or join a workspace inline. A highlight glides between rows, and switching crossfades the trigger through a short loading state.
- [Live visitors](https://uiarc.dev/components/live-visitors/markdown): A realtime visitors card where the live count rolls digit by digit, new arrivals ping in on a dotted world map, the top pages reorder with bars, and signups and upgrades tick in with country flags.
- [Social proof toast](https://uiarc.dev/components/social-proof-toast/markdown): A stack of social proof notifications for landing and pricing pages, where recent trials, upgrades and verified purchases from people and companies arrive every few seconds. The stack pauses and fans out on hover, and visitors can dismiss any toast.
- [Install snippet](https://uiarc.dev/components/install-snippet/markdown): A "get started in 30 seconds" card where framework tabs, three numbered steps and highlighted snippets take a developer from install to first event. Generate key wipes a fresh API key into the placeholder in place.

### Guidance for AI tools

Connector setup: A "Connect your tools" card for an AI assistant. Each app connects inline: it redirects, authorizes and runs a first sync with a progress hairline, then lists the scopes it was granted and offers Disconnect with an inline confirm. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Smart form fill

> A paste-to-fill form card where AI reads an email signature or messy notes and fills a contact field by field. Each value flashes in with a confidence dot, its source lights up in the pasted text, low-confidence guesses ask for review, and Undo puts the old values back.

- Type: Component (special)
- Access: Arc Pro
- Page: https://uiarc.dev/components/smart-form-fill
- Markdown: https://uiarc.dev/components/smart-form-fill/markdown
- Source file: `registry/components/smart-form-fill/smart-form-fill.tsx`
- Dependencies: motion, lucide-react
- Keywords: special, ai, new, ai form fill, autofill, smart paste, extract contact, email signature parser, ai form, confidence, crm contact, structured extraction, paste to fill

### When to use

- People paste an email signature, a forwarded message or notes and expect the record to fill itself.
- You need visible confidence and an easy review path before AI-filled data is saved.
- Onboarding or CRM flows where typing six fields by hand is the main friction.

### When not to use

- Plain data entry with no unstructured source; use form-field and input.
- Long multi-page applications; use multi-step-form and add a paste step to one page.
- Bulk imports of many records; use a table import flow instead of one card.

### Installation

Smart form fill is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/smart-form-fill
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { SmartFormFill } from "@/components/arc/smart-form-fill/smart-form-fill";

export function NewContact() {
  return (
    <SmartFormFill
      extract={async (text, signal) => {
        const response = await fetch("/api/extract-contact", { method: "POST", body: text, signal });
        return response.json(); // { name: { value, confidence, source }, ... }
      }}
      onSubmit={(values) => saveContact(values)}
    />
  );
}
```

### API reference

#### SmartFormFill

A form card with a paste area. Pasted text is read by AI, each field fills in turn with a short highlight and a confidence dot, low-confidence fields ask for review, and Undo restores the values from before the fill.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `fields` | `SmartFormFillField[]` | `contact fields` | The form: { id, label, kind?, placeholder?, span?, autoComplete? }. kind picks the input type; "company" adds a logo slot. Defaults to name, title, company, email, phone and address. |
| `defaultValues` | `Record<string, string>` | – | Starting values keyed by field id. |
| `onValuesChange` | `(values: Record<string, string>) => void` | – | Called on every change, typed or filled. |
| `extract` | `(text: string, signal: AbortSignal) => Promise<SmartFormFillResult>` | `simulateExtract` | Reads the pasted text and resolves { [fieldId]: { value, confidence, source?, note? } }. Abort when the signal fires (Stop, Escape, a new paste). Defaults to a simulated read: hand-checked results for the samples and a local parser for anything else. |
| `reviewThreshold` | `number` | `0.8` | Fields with a confidence below this ask for review and block Save until checked or edited. |
| `samples` | `{ label: string; text: string }[]` | `signature and messy note` | Texts behind Try sample, cycled in order. Pass [] to hide the button and the autoplay. |
| `autoPlay` | `boolean` | `true without extract` | Loops paste, fill, review and undo while visible, and stops for good on the first pointer or key press inside the card. |
| `onFill` | `(result: SmartFormFillResult) => void` | – | Called once every field from a read has been filled. |
| `onUndo` | `(restored: Record<string, string>) => void` | – | Called after Undo restores the values from before the last fill. |
| `onSubmit` | `(values: Record<string, string>) => void \| Promise<void>` | – | Saves the form. The button shows a loading state while the promise is pending; a rejection shows an error status. Defaults to a simulated save. |
| `resolveLogo` | `(company: string) => ReactNode \| undefined` | – | Logo for the company field. Falls back to built-in marks for Stripe, Linear, Vercel, Figma and Notion, then a building icon. |
| `model` | `{ name: string; mark?: ReactNode }` | `Claude Haiku 5.5` | The model named beside the paste area. |
| `title` | `string` | `"New contact"` | Card title. |
| `description` | `string` | – | One line under the title. Pass an empty string to hide it. |
| `submitLabel` | `string` | `"Save contact"` | Label of the primary action. |
| `className` | `string` | – | Class on the root card. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Cmd/Ctrl + V | Paste into the text area; the read starts right away. |
| Cmd/Ctrl + Enter | Read typed text from the text area. |
| Escape | Stop a read in progress; nothing changes. |
| Tab | Moves through the text area, Try sample, Fill, every field, the check buttons, Undo and Save. |

### Accessibility

- A polite live region announces each step: reading, how many fields were filled, which need review, checks, undo and save. With the default extractor it adds that the run was simulated.
- Each filled input carries an aria-description with its confidence and, for low-confidence fields, the reason. Fields that need review are aria-invalid until checked or edited.
- Status is never color alone: confidence shows a dot plus a percentage or a word (Review, Checked, Edited); the footer pairs an icon with text.
- The check button inside a review field has a label naming the field. Save focuses the first field that still needs review.
- The pasted text view is a focusable, labelled region so keyboard users can scroll it.

### Motion

- Fields fill in form order 140ms apart. Each value fades in over 200ms and the input breathes an accent tint for 900ms; no movement, no size change.
- The source span for the field being filled, hovered or focused takes a stronger tint (160ms), so cause and effect read across the card.
- Labels, badges, the logo and status swap with one crossfade: out in 100ms, in over 160ms with a 2px rise. The reading label uses a calm shimmer.
- Reduced motion fills every field at once, drops the tint animation and the autoplay loop, and keeps all end states. Autoplay pauses while the card is off screen.

### Responsive behavior

- Side by side from a 720px container: paste well left, form right. Below that the well stacks on top at a fixed height.
- Under 440px every field takes the full row and the footer stacks its status above the actions.
- Container queries, so it adapts to the column it sits in, not the viewport. Holds at 360px without horizontal scroll.

### Performance

- Only CSS animations for the fill highlight; motion is used for small crossfades. No layout animation.
- Autoplay timers stop when the card leaves the viewport and are cleared on unmount; reads are aborted on unmount.
- The built-in marks are inline SVG, about 6KB together; resolveLogo can supply your own.

### Notes for AI

- Use for creating a record from unstructured text: CRM contacts, vendor or company profiles, shipping addresses, support tickets. Pass custom fields for anything beyond a contact.
- Wire extract to your model with structured output that returns value, confidence 0 to 1 and the exact source substring; source powers the highlight, note explains low confidence.
- Keep the human in the loop: leave reviewThreshold around 0.8 so guesses (inferred states, paraphrased titles, one of several phone numbers) are flagged rather than saved silently.
- Set autoPlay={false} in product screens; the default loop is for docs and marketing.

### Related

- [Input](https://uiarc.dev/components/input/markdown): A single line field with clear labels and useful states.
- [Textarea](https://uiarc.dev/components/textarea/markdown): A multiline field for notes, descriptions, and longer text.
- [Multi-step form](https://uiarc.dev/components/blocks/multi-step-form/markdown): A guided form that presents one decision at a time and preserves progress.
- [AI command](https://uiarc.dev/components/ai-command/markdown): A Cmd+K command palette with an AI mode. Search pages and actions, or press Tab to ask a question: the answer streams inside the palette with numbered sources, and the next steps it suggests, like filing a Linear issue or opening a Notion doc, run straight from the list.

### Also in ai

- [Agent status](https://uiarc.dev/components/agent-status/markdown): A compact live status pill for a running AI agent: the agent's mark in a live ring, the current activity and an elapsed timer, opening into the steps so far.
- [Tool call](https://uiarc.dev/components/tool-call/markdown): A tool call row for agent transcripts: the tool's mark and the call in plain words, a live state while it runs, and the input and output a click away, with approval and retry when needed.
- [Agent plan](https://uiarc.dev/components/agent-plan/markdown): The plan an agent writes before it acts: edit, reorder or add steps while it is a draft, then watch it work through them as a live checklist.
- [Agent timeline](https://uiarc.dev/components/agent-timeline/markdown): A compact timeline of one orchestrated agent run: the orchestrator and its subagents share a time axis, handoffs draw in between rows, and a playhead replays thinking, tool calls and waiting while the header counts time, tokens and cost. Hover a span for what it did, or click it to trace its handoff path.
- [Context window](https://uiarc.dev/components/context-window/markdown): An AI context window as a grid of 200 cells: the system prompt, tools, files, summary and messages fill it in order, a threshold row marks where compaction starts, and sending a message, attaching a file or compacting shows exactly how much still fits.
- [Reasoning block](https://uiarc.dev/components/reasoning-block/markdown): The collapsible thinking block of an AI reply. While the model thinks, a shimmering label counts the seconds and the latest reasoning streams underneath. When it finishes, it folds to "Thought for 7s" and opens to show the full reasoning as calm steps with headings.
- [Source cards](https://uiarc.dev/components/source-cards/markdown): A row of cited sources under an AI answer where cards stream in with real site marks while the model searches, the overflow collapses into a stack of favicons, hovering lifts a preview with the passage, and an inline [n] citation highlights its card.
- [Model card](https://uiarc.dev/components/model-card/markdown): A model details card where switching models rolls every price, limit and score in place, a token slider estimates monthly cost live, and benchmark bars show each model's rank on hover. Compare crossfades to a side-by-side table against any rival with the better values marked, and the card never changes size.
- [AI workflow](https://uiarc.dev/components/ai-workflow/markdown): A Linear-style AI workflow card where a Gmail trigger, a Claude step, a branch and Slack and Linear actions sit on one hairline rail, and a test run glides down it, opening each step's output inline. Steps are added from a compact command menu with real app marks.
- [Code suggestion](https://uiarc.dev/components/code-suggestion/markdown): An AI code edit suggestion where the model's proposed changes stream into a small editor panel as inline diff hunks, and you accept or reject each one, or all at once with Cmd+Enter. Accepted hunks fold into the file with a smooth height change.
- [Ghost text](https://uiarc.dev/components/ghost-text/markdown): An inline AI autocomplete where muted ghost text continues your sentence exactly at the caret and Tab turns it solid in place. Cmd+Right takes it one word at a time, Escape fades it away, and a calm chip shows the model behind it.
- [Image generation](https://uiarc.dev/components/image-generation/markdown): An image studio where each image forms on a dot matrix: a soft halftone wave breathes across the grid, the dots take the colours of the coming photo and grow into a coloured halftone, then blur away into the sharp photo. One large canvas with a mono size label, a filmstrip of four variations, a prompt bar with model and ratio, and upscale with a sweeping dot band, vary or download, with real provider marks and a built-in simulation.
- [Dictation button](https://uiarc.dev/components/dictation-button/markdown): A chat composer with voice input, where the mic springs into a recording pill with a smooth live waveform, a timer, and cancel and insert buttons. Words stream into the field as you speak, muted until the recognizer settles them.
- [Speech player](https://uiarc.dev/components/speech-player/markdown): A read-aloud player for AI replies. The Read aloud button in the message's action row turns into a compact player with play, a scrubbable progress bar, speed and a voice picker, and a highlight follows the spoken word through the reply, karaoke style.
- [Meeting summary](https://uiarc.dev/components/meeting-summary/markdown): An AI meeting notes card: the header shows the Google Meet or Zoom mark, the attendees and the duration. Summary, Decisions and Action items stream in after a short summarizing pass. Hover any line to see the transcript quote it came from, then check off action items or send them to Linear or Notion.
- [Reply draft](https://uiarc.dev/components/reply-draft/markdown): An AI email reply drafter where Claude streams a reply under a received Gmail message. Quick replies steer a fresh draft, tone and length rewrite it with a single crossfade, and you can edit the finished draft before you insert it.
- [Agent handoff](https://uiarc.dev/components/agent-handoff/markdown): A support conversation where an AI assistant hands off to a person. When it transfers, a card shows the summary it passes to the team and the typical wait. The person then joins and takes over, and a thin timeline on the left marks each step.
- [PII redaction](https://uiarc.dev/components/pii-redaction/markdown): A guardrail card where personal data is redacted before the prompt reaches the model. Scan marks each name, email, phone number and card with its type and swaps it for a placeholder like [EMAIL_1]. The safe prompt travels to Claude, and the reply comes back with the original values put back for the person.
- [Response feedback](https://uiarc.dev/components/response-feedback/markdown): A feedback control for AI replies where thumbs down opens an inline panel with reason chips and an optional note, thumbs up fills and asks what was good, and a submit shows a short thank-you before folding back into the row.
- [LLM cost calculator](https://uiarc.dev/components/llm-cost-calculator/markdown): A pricing calculator for LLM workloads. Set tokens per request, requests per day and prompt caching, and eight current models re-rank by monthly cost. Bars glide and prices roll as you drag.
- [Provider keys](https://uiarc.dev/components/provider-keys/markdown): A settings card for bring-your-own-key AI products. Each provider row shows its real mark, the masked key, a status and when the key was last used. You can reveal a key for five seconds, copy, rotate or remove it with undo. Adding or rotating a key opens an inline form that checks the format as you type, then tests the connection before saving.
- [Generation stats](https://uiarc.dev/components/generation-stats/markdown): A live stats strip for a streaming LLM response where time to first token, speed with a sparkline, output tokens and cost count up in tabular numerals beside the model's real mark, then settle and open into a latency and token cost breakdown.
- [AI translate](https://uiarc.dev/components/ai-translate/markdown): A message card where picking a language streams the AI translation in place, sentence by sentence over the dimmed original, with a detected-language chip, a Show original toggle and a status line credited to the model's mark.
- [TL;DR toggle](https://uiarc.dev/components/tldr-toggle/markdown): An article card with a Full, Summary and Key points switch and a length slider. Switching streams an AI summary in place of the article as the card's height springs to fit, and each key point links back to the paragraph it came from, which gets scrolled to and highlighted.
- [Connector setup](https://uiarc.dev/components/connector-setup/markdown): A "Connect your tools" card for an AI assistant. Each app connects inline: it redirects, authorizes and runs a first sync with a progress hairline, then lists the scopes it was granted and offers Disconnect with an inline confirm.
- [Enrich column](https://uiarc.dev/components/enrich-column/markdown): An AI enrichment column for a data table, where one prompt runs down every row and each cell shimmers while it works, then settles into a value with its source or a failure you can retry.
- [Ticket router](https://uiarc.dev/components/ticket-router/markdown): A support ticket router where messages from Gmail, Intercom, Slack and Zendesk come in one at a time. An AI classifier labels each one with intent, sentiment and confidence, and the ticket moves into a team lane with an assignee. Low confidence tickets wait in a review lane, and one click there routes them to the suggested team.
- [Ask your data](https://uiarc.dev/components/ask-your-data/markdown): A natural language to chart card: you ask a question, PostgreSQL streams into a collapsible, syntax highlighted panel, the query runs with a rolling row count, and the answer builds as stacked bars, lines or a table, with a one line insight streamed in underneath.
- [Agent cursor](https://uiarc.dev/components/agent-cursor/markdown): A live document where Claude edits like a collaborator. Its labeled cursor comes out of its avatar, selects a paragraph and streams in a rewrite, adds a heading and fixes a typo, while a teammate's cursor reads along. Changes stay tinted until someone accepts or undoes them from a floating review bar.
- [Provider status](https://uiarc.dev/components/provider-status/markdown): A status card for the AI providers your product depends on. Each row shows the provider's real mark, its health as an icon and label, p50 latency and a 30-day uptime bar with a tooltip for each day. An incident row expands into its timeline of updates, and the card checks again on a visible countdown.
- [Training run](https://uiarc.dev/components/training-run/markdown): A fine-tuning job card where a live train and validation loss curve draws across a fixed step axis that doubles as the epoch progress bar. It shows the learning rate, elapsed time, ETA and the latest evals and checkpoints, has Pause and Cancel while it runs, and ends in results with a Deploy button.
- [Starter prompts](https://uiarc.dev/components/starter-prompts/markdown): A greeting and a grid of starter cards for the empty state of an AI app. The cards are grouped into Write, Code, Analyze and Plan tabs, and a shuffle swaps them with a short staggered crossfade. Picking a card fills the composer, and cards that use a connected app show its mark (Gmail, GitHub, Notion, Linear, Google Calendar).
- [AI mascot](https://uiarc.dev/components/ai-mascot/markdown): A small assistant character, a soft pebble with pill eyes and a companion dot, that shows what the AI is doing. It breathes and glances when idle, leans in to listen, looks up while the dot orbits its head, reads along the line it writes, squints with a sparkle when done and shakes once with worried brows on an error.
- [Image reveal](https://uiarc.dev/components/image-reveal/markdown): An image generation canvas where a soft, blurred preview made from the image's own colors sharpens top to bottom behind a soft-edged band. It works the way ChatGPT, Midjourney and Gemini show images forming, with fine film grain, a translucent progress pill and calm queued and error states.
- [AI spark](https://uiarc.dev/components/ai-spark/markdown): A brand-quality animated spark mark. Four tapered rays and four lighter diagonals breathe at rest, ripple while thinking, pulse like a heartbeat while writing, then gather and settle when done. Every status change blends from the pose the mark is already in.
- [Pixel mascot](https://uiarc.dev/components/pixel-mascot/markdown): A pixel-art robot that shows what an AI assistant is doing. It idles, thinks, types, celebrates and errors in frame-stepped sprite animations, and stays crisp at every integer size from 24px to 192px.
- [Ghost mascot](https://uiarc.dev/components/ghost-mascot/markdown): A floating ghost mascot whose soft sheet ripples at the hem while it hovers. It blinks when idle, turns toward you to listen, fades a little translucent while thinking, draws a tiny pen line while writing, smiles with a sparkle when done and wobbles once on an error.
- [Cube mascot](https://uiarc.dev/components/cube-mascot/markdown): An isometric cube mascot where three shaded faces and a painted-on face show what the assistant is doing. It turns a quarter turn in eased steps while thinking, prints lines onto the floor while writing, settles with a sparkle when done, and shakes once on error.
- [Tone tuner](https://uiarc.dev/components/tone-tuner/markdown): A brand voice card where two sliders (formality and detail) and Friendly, Confident and Empathetic chips rewrite a customer reply. Each changed sentence crossfades in place, new words can be highlighted against the original, and Copy takes the current version.
- [Upgrade prompt](https://uiarc.dev/components/upgrade-prompt/markdown): An upgrade nudge for the moment someone hits a limit. It shows a usage meter at 50 of 50 AI credits, a rolling price with a monthly and yearly toggle, three concrete unlocks with real model marks, and Upgrade or Maybe later. Upgrading leads into a success state with the new limits, and the card never changes size between states.
- [Referral card](https://uiarc.dev/components/referral-card/markdown): A give-and-get referral card where people copy or share their invite link, invite friends by email as chips, and watch invites move from invited to signed up to earned, with the credit total counting up and a milestone reward unlocking.
- [Trial banner](https://uiarc.dev/components/trial-banner/markdown): A trial status banner where a ring counts down the days left, the copy names what the workspace loses, and the upgrade path is one click away. It comes as a slim banner, a sidebar card or a header pill. It shifts to a warning tone in the last days, has expired and upgraded states, and folds into the pill when dismissed or snoozed.
- [Team switcher](https://uiarc.dev/components/team-switcher/markdown): A workspace switcher like Linear, Vercel or Slack. The trigger shows the current workspace's logo and plan. The menu has search, your role in each workspace and a Cmd+1 to 9 shortcut for each, and lets you create or join a workspace inline. A highlight glides between rows, and switching crossfades the trigger through a short loading state.
- [Live visitors](https://uiarc.dev/components/live-visitors/markdown): A realtime visitors card where the live count rolls digit by digit, new arrivals ping in on a dotted world map, the top pages reorder with bars, and signups and upgrades tick in with country flags.
- [Social proof toast](https://uiarc.dev/components/social-proof-toast/markdown): A stack of social proof notifications for landing and pricing pages, where recent trials, upgrades and verified purchases from people and companies arrive every few seconds. The stack pauses and fans out on hover, and visitors can dismiss any toast.
- [Install snippet](https://uiarc.dev/components/install-snippet/markdown): A "get started in 30 seconds" card where framework tabs, three numbered steps and highlighted snippets take a developer from install to first event. Generate key wipes a fresh API key into the placeholder in place.

### Guidance for AI tools

Smart form fill: A paste-to-fill form card where AI reads an email signature or messy notes and fills a contact field by field. Each value flashes in with a confidence dot, its source lights up in the pasted text, low-confidence guesses ask for review, and Undo puts the old values back. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Enrich column

> An AI enrichment column for a data table, where one prompt runs down every row and each cell shimmers while it works, then settles into a value with its source or a failure you can retry.

- Type: Component (special)
- Access: Arc Pro
- Page: https://uiarc.dev/components/enrich-column
- Markdown: https://uiarc.dev/components/enrich-column/markdown
- Source file: `registry/components/enrich-column/enrich-column.tsx`
- Dependencies: motion, lucide-react
- Keywords: special, ai, new, enrich column, ai column, clay, data enrichment, lead enrichment, ai table, spreadsheet ai, company data, headcount, funding round, retry, shimmer, agent

### When to use

- Enriching a list of companies or leads with facts an agent can look up (headcount, funding, tech stack).
- Classifying or summarizing rows with one prompt, with a visible source per answer.
- Showing per-row AI progress with stop, re-run and retry in a CRM, sales tool or internal admin.

### When not to use

- Large spreadsheets with many columns and editing; use Data grid and add an AI column there.
- A single question over a dataset; use Ask your data.
- A log of one agent's tool calls; use Tool call.

### Installation

Enrich column is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/enrich-column
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { EnrichColumn } from "@/components/arc/enrich-column/enrich-column";

<EnrichColumn
  title="Pipeline"
  rows={accounts.map(account => ({ id: account.id, name: account.name, domain: account.domain }))}
  defaultColumn={{ name: "Headcount and funding", prompt: "Find the headcount and latest funding round" }}
  enrich={async (row, { prompt, signal, setActivity }) => {
    setActivity(`Searching for ${row.name}`);
    const response = await fetch("/api/enrich", { method: "POST", body: JSON.stringify({ domain: row.domain, prompt }), signal });
    if (!response.ok) throw new Error("No source found");
    return response.json(); // { value, source: { label, href } }
  }}
  onCellChange={(row, cell) => cell.status === "done" && save(row.id, cell)}
/>
```

### API reference

#### EnrichColumn

A table card with an AI column. One prompt runs down every row; each cell shimmers while it works, then settles into a value with its source, or a failure with a retry. With no props it runs a simulated sample of seven companies.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` | `string` | `"Target accounts"` | The table's name in the top bar. |
| `rows` | `EnrichColumnRow[]` | `seven sample companies` | The rows to enrich: { id, name, domain?, logo? }. Logos render at 16px. |
| `defaultColumn` | `{ name: string; prompt: string }` | `{ name: "Headcount and funding", prompt: "Find the headcount and latest funding round" }` | The AI column's name and prompt on first render. The person can edit both from the column header. |
| `onColumnChange` | `(column: EnrichColumnDefinition) => void` | – | Called when the person saves an edited column. Saving re-runs every row. |
| `enrich` | `(row, context) => Promise<{ value: string; source?: { label: string; href: string } }>` | `local simulation` | Fills one cell. The context carries prompt, column, an AbortSignal, the attempt number and setActivity(text) for the shimmering label. Reject to mark the cell failed with the error's message. |
| `initialCells` | `Record<string, EnrichColumnCell>` | – | Values you already have, keyed by row id, such as cells saved from an earlier run. |
| `concurrency` | `number` | `2` | How many cells run at once. Workers start 140ms apart so the column fills top to bottom. |
| `autoRun` | `boolean` | `true with the simulation, false with enrich` | Runs the column once when it first scrolls into view, if no cell has a value yet. |
| `model` | `{ name: string; detail?: string; mark?: ReactNode } \| null` | `Claude Haiku 5.5, web search` | The model shown in the footer. Pass null to hide it. |
| `editable` | `boolean` | `true` | Shows the edit control on the AI column header. |
| `note` | `string` | `"sample data" with the simulation` | A short note after the row count. |
| `onCellChange` | `(row: EnrichColumnRow, cell: EnrichColumnCell) => void` | – | Called whenever a cell changes state (queued, running, done, failed). Use it to persist values. |
| `onRunComplete` | `(cells: Record<string, EnrichColumnCell>) => void` | – | Called when a run settles, with every cell. |
| `className` | `string` | – | Class on the root. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Tab | Moves through Run column, the column's edit control, each row's run or retry control and source links. Row controls appear on focus. |
| Enter / Space | Runs, stops or re-runs the column, runs one row, or retries a failed cell. |
| Cmd/Ctrl + Enter | Saves the edited column and re-runs it. |
| Escape | Closes the column editor without saving and returns focus to the edit control. |

### Accessibility

- A real table: the company is a row header and the AI column's name and prompt are its column header.
- Every cell state pairs an icon with text (Queued, a shimmering activity, the value, Failed with a reason), never color alone.
- A polite live region announces runs, stops and the final count, and says when values are simulated and nothing was sent.
- Icon buttons carry labels that name the row (Run Linear, Retry Retool); source links say they open a new tab.

### Motion

- Cell swaps are one crossfade in a shared grid cell: old content out in 100ms, new in 160ms with a 2px rise. Nothing changes size.
- Status icons crossfade with a bounce-free scale; the done tick draws in 240ms; the running label uses a calm text shimmer.
- The editor opens with a critically damped height spring (240ms, no bounce).
- Reduced motion keeps every state and cuts travel and the tick draw; the spinner slows down.

### Responsive behavior

- Fluid up to 760px. Below 560px the domain, source text and model detail fold away; the source keeps its arrow link.
- Below 440px the gutters tighten to 16px, values wrap to two lines in 60px rows, and failure reasons hide behind the Failed label.
- On touch screens the row run controls stay visible since there is no hover.

### Performance

- Only changed cells re-render visibly; runs are capped by concurrency and every request is abortable.
- Workers read the latest rows and prompt through refs, so editing mid-run never acts on stale data.
- Built for tens of rows; for hundreds, virtualize the table body and keep concurrency low.

### Notes for AI

- Use for AI-filled columns in tables of accounts, leads, documents or tickets, where one prompt runs per row.
- Pass a real enrich function and honor the AbortSignal; throw an Error with a short message to show a failed cell with retry.
- Persist values with onCellChange and feed them back through initialCells on the next render.
- Keep values to one short line; the cell truncates with an ellipsis and shows the full value on hover.

### Related

- [Tool call](https://uiarc.dev/components/tool-call/markdown): A tool call row for agent transcripts: the tool's mark and the call in plain words, a live state while it runs, and the input and output a click away, with approval and retry when needed.
- [Agent status](https://uiarc.dev/components/agent-status/markdown): A compact live status pill for a running AI agent: the agent's mark in a live ring, the current activity and an elapsed timer, opening into the steps so far.
- [Text shimmer](https://uiarc.dev/components/text-shimmer/markdown): Show ongoing work with a calm light across the words.
- [Sortable data table](https://uiarc.dev/components/sortable-data-table/markdown): Compare structured records with sortable columns.
- [Data grid](https://uiarc.dev/components/data-grid/markdown): A spreadsheet grid with range selection, inline editing, a fill handle, and animated sorting.
- [Ask your data](https://uiarc.dev/components/ask-your-data/markdown): A natural language to chart card: you ask a question, PostgreSQL streams into a collapsible, syntax highlighted panel, the query runs with a rolling row count, and the answer builds as stacked bars, lines or a table, with a one line insight streamed in underneath.

### Also in ai

- [Agent plan](https://uiarc.dev/components/agent-plan/markdown): The plan an agent writes before it acts: edit, reorder or add steps while it is a draft, then watch it work through them as a live checklist.
- [Agent timeline](https://uiarc.dev/components/agent-timeline/markdown): A compact timeline of one orchestrated agent run: the orchestrator and its subagents share a time axis, handoffs draw in between rows, and a playhead replays thinking, tool calls and waiting while the header counts time, tokens and cost. Hover a span for what it did, or click it to trace its handoff path.
- [Context window](https://uiarc.dev/components/context-window/markdown): An AI context window as a grid of 200 cells: the system prompt, tools, files, summary and messages fill it in order, a threshold row marks where compaction starts, and sending a message, attaching a file or compacting shows exactly how much still fits.
- [Reasoning block](https://uiarc.dev/components/reasoning-block/markdown): The collapsible thinking block of an AI reply. While the model thinks, a shimmering label counts the seconds and the latest reasoning streams underneath. When it finishes, it folds to "Thought for 7s" and opens to show the full reasoning as calm steps with headings.
- [Source cards](https://uiarc.dev/components/source-cards/markdown): A row of cited sources under an AI answer where cards stream in with real site marks while the model searches, the overflow collapses into a stack of favicons, hovering lifts a preview with the passage, and an inline [n] citation highlights its card.
- [Model card](https://uiarc.dev/components/model-card/markdown): A model details card where switching models rolls every price, limit and score in place, a token slider estimates monthly cost live, and benchmark bars show each model's rank on hover. Compare crossfades to a side-by-side table against any rival with the better values marked, and the card never changes size.
- [AI workflow](https://uiarc.dev/components/ai-workflow/markdown): A Linear-style AI workflow card where a Gmail trigger, a Claude step, a branch and Slack and Linear actions sit on one hairline rail, and a test run glides down it, opening each step's output inline. Steps are added from a compact command menu with real app marks.
- [Code suggestion](https://uiarc.dev/components/code-suggestion/markdown): An AI code edit suggestion where the model's proposed changes stream into a small editor panel as inline diff hunks, and you accept or reject each one, or all at once with Cmd+Enter. Accepted hunks fold into the file with a smooth height change.
- [Ghost text](https://uiarc.dev/components/ghost-text/markdown): An inline AI autocomplete where muted ghost text continues your sentence exactly at the caret and Tab turns it solid in place. Cmd+Right takes it one word at a time, Escape fades it away, and a calm chip shows the model behind it.
- [Image generation](https://uiarc.dev/components/image-generation/markdown): An image studio where each image forms on a dot matrix: a soft halftone wave breathes across the grid, the dots take the colours of the coming photo and grow into a coloured halftone, then blur away into the sharp photo. One large canvas with a mono size label, a filmstrip of four variations, a prompt bar with model and ratio, and upscale with a sweeping dot band, vary or download, with real provider marks and a built-in simulation.
- [Dictation button](https://uiarc.dev/components/dictation-button/markdown): A chat composer with voice input, where the mic springs into a recording pill with a smooth live waveform, a timer, and cancel and insert buttons. Words stream into the field as you speak, muted until the recognizer settles them.
- [Speech player](https://uiarc.dev/components/speech-player/markdown): A read-aloud player for AI replies. The Read aloud button in the message's action row turns into a compact player with play, a scrubbable progress bar, speed and a voice picker, and a highlight follows the spoken word through the reply, karaoke style.
- [Meeting summary](https://uiarc.dev/components/meeting-summary/markdown): An AI meeting notes card: the header shows the Google Meet or Zoom mark, the attendees and the duration. Summary, Decisions and Action items stream in after a short summarizing pass. Hover any line to see the transcript quote it came from, then check off action items or send them to Linear or Notion.
- [Reply draft](https://uiarc.dev/components/reply-draft/markdown): An AI email reply drafter where Claude streams a reply under a received Gmail message. Quick replies steer a fresh draft, tone and length rewrite it with a single crossfade, and you can edit the finished draft before you insert it.
- [Agent handoff](https://uiarc.dev/components/agent-handoff/markdown): A support conversation where an AI assistant hands off to a person. When it transfers, a card shows the summary it passes to the team and the typical wait. The person then joins and takes over, and a thin timeline on the left marks each step.
- [PII redaction](https://uiarc.dev/components/pii-redaction/markdown): A guardrail card where personal data is redacted before the prompt reaches the model. Scan marks each name, email, phone number and card with its type and swaps it for a placeholder like [EMAIL_1]. The safe prompt travels to Claude, and the reply comes back with the original values put back for the person.
- [Response feedback](https://uiarc.dev/components/response-feedback/markdown): A feedback control for AI replies where thumbs down opens an inline panel with reason chips and an optional note, thumbs up fills and asks what was good, and a submit shows a short thank-you before folding back into the row.
- [LLM cost calculator](https://uiarc.dev/components/llm-cost-calculator/markdown): A pricing calculator for LLM workloads. Set tokens per request, requests per day and prompt caching, and eight current models re-rank by monthly cost. Bars glide and prices roll as you drag.
- [Provider keys](https://uiarc.dev/components/provider-keys/markdown): A settings card for bring-your-own-key AI products. Each provider row shows its real mark, the masked key, a status and when the key was last used. You can reveal a key for five seconds, copy, rotate or remove it with undo. Adding or rotating a key opens an inline form that checks the format as you type, then tests the connection before saving.
- [Generation stats](https://uiarc.dev/components/generation-stats/markdown): A live stats strip for a streaming LLM response where time to first token, speed with a sparkline, output tokens and cost count up in tabular numerals beside the model's real mark, then settle and open into a latency and token cost breakdown.
- [AI translate](https://uiarc.dev/components/ai-translate/markdown): A message card where picking a language streams the AI translation in place, sentence by sentence over the dimmed original, with a detected-language chip, a Show original toggle and a status line credited to the model's mark.
- [TL;DR toggle](https://uiarc.dev/components/tldr-toggle/markdown): An article card with a Full, Summary and Key points switch and a length slider. Switching streams an AI summary in place of the article as the card's height springs to fit, and each key point links back to the paragraph it came from, which gets scrolled to and highlighted.
- [Connector setup](https://uiarc.dev/components/connector-setup/markdown): A "Connect your tools" card for an AI assistant. Each app connects inline: it redirects, authorizes and runs a first sync with a progress hairline, then lists the scopes it was granted and offers Disconnect with an inline confirm.
- [Smart form fill](https://uiarc.dev/components/smart-form-fill/markdown): A paste-to-fill form card where AI reads an email signature or messy notes and fills a contact field by field. Each value flashes in with a confidence dot, its source lights up in the pasted text, low-confidence guesses ask for review, and Undo puts the old values back.
- [Ticket router](https://uiarc.dev/components/ticket-router/markdown): A support ticket router where messages from Gmail, Intercom, Slack and Zendesk come in one at a time. An AI classifier labels each one with intent, sentiment and confidence, and the ticket moves into a team lane with an assignee. Low confidence tickets wait in a review lane, and one click there routes them to the suggested team.
- [Agent cursor](https://uiarc.dev/components/agent-cursor/markdown): A live document where Claude edits like a collaborator. Its labeled cursor comes out of its avatar, selects a paragraph and streams in a rewrite, adds a heading and fixes a typo, while a teammate's cursor reads along. Changes stay tinted until someone accepts or undoes them from a floating review bar.
- [Provider status](https://uiarc.dev/components/provider-status/markdown): A status card for the AI providers your product depends on. Each row shows the provider's real mark, its health as an icon and label, p50 latency and a 30-day uptime bar with a tooltip for each day. An incident row expands into its timeline of updates, and the card checks again on a visible countdown.
- [Training run](https://uiarc.dev/components/training-run/markdown): A fine-tuning job card where a live train and validation loss curve draws across a fixed step axis that doubles as the epoch progress bar. It shows the learning rate, elapsed time, ETA and the latest evals and checkpoints, has Pause and Cancel while it runs, and ends in results with a Deploy button.
- [AI command](https://uiarc.dev/components/ai-command/markdown): A Cmd+K command palette with an AI mode. Search pages and actions, or press Tab to ask a question: the answer streams inside the palette with numbered sources, and the next steps it suggests, like filing a Linear issue or opening a Notion doc, run straight from the list.
- [Starter prompts](https://uiarc.dev/components/starter-prompts/markdown): A greeting and a grid of starter cards for the empty state of an AI app. The cards are grouped into Write, Code, Analyze and Plan tabs, and a shuffle swaps them with a short staggered crossfade. Picking a card fills the composer, and cards that use a connected app show its mark (Gmail, GitHub, Notion, Linear, Google Calendar).
- [AI mascot](https://uiarc.dev/components/ai-mascot/markdown): A small assistant character, a soft pebble with pill eyes and a companion dot, that shows what the AI is doing. It breathes and glances when idle, leans in to listen, looks up while the dot orbits its head, reads along the line it writes, squints with a sparkle when done and shakes once with worried brows on an error.
- [Image reveal](https://uiarc.dev/components/image-reveal/markdown): An image generation canvas where a soft, blurred preview made from the image's own colors sharpens top to bottom behind a soft-edged band. It works the way ChatGPT, Midjourney and Gemini show images forming, with fine film grain, a translucent progress pill and calm queued and error states.
- [AI spark](https://uiarc.dev/components/ai-spark/markdown): A brand-quality animated spark mark. Four tapered rays and four lighter diagonals breathe at rest, ripple while thinking, pulse like a heartbeat while writing, then gather and settle when done. Every status change blends from the pose the mark is already in.
- [Pixel mascot](https://uiarc.dev/components/pixel-mascot/markdown): A pixel-art robot that shows what an AI assistant is doing. It idles, thinks, types, celebrates and errors in frame-stepped sprite animations, and stays crisp at every integer size from 24px to 192px.
- [Ghost mascot](https://uiarc.dev/components/ghost-mascot/markdown): A floating ghost mascot whose soft sheet ripples at the hem while it hovers. It blinks when idle, turns toward you to listen, fades a little translucent while thinking, draws a tiny pen line while writing, smiles with a sparkle when done and wobbles once on an error.
- [Cube mascot](https://uiarc.dev/components/cube-mascot/markdown): An isometric cube mascot where three shaded faces and a painted-on face show what the assistant is doing. It turns a quarter turn in eased steps while thinking, prints lines onto the floor while writing, settles with a sparkle when done, and shakes once on error.
- [Tone tuner](https://uiarc.dev/components/tone-tuner/markdown): A brand voice card where two sliders (formality and detail) and Friendly, Confident and Empathetic chips rewrite a customer reply. Each changed sentence crossfades in place, new words can be highlighted against the original, and Copy takes the current version.
- [Upgrade prompt](https://uiarc.dev/components/upgrade-prompt/markdown): An upgrade nudge for the moment someone hits a limit. It shows a usage meter at 50 of 50 AI credits, a rolling price with a monthly and yearly toggle, three concrete unlocks with real model marks, and Upgrade or Maybe later. Upgrading leads into a success state with the new limits, and the card never changes size between states.
- [Referral card](https://uiarc.dev/components/referral-card/markdown): A give-and-get referral card where people copy or share their invite link, invite friends by email as chips, and watch invites move from invited to signed up to earned, with the credit total counting up and a milestone reward unlocking.
- [Trial banner](https://uiarc.dev/components/trial-banner/markdown): A trial status banner where a ring counts down the days left, the copy names what the workspace loses, and the upgrade path is one click away. It comes as a slim banner, a sidebar card or a header pill. It shifts to a warning tone in the last days, has expired and upgraded states, and folds into the pill when dismissed or snoozed.
- [Team switcher](https://uiarc.dev/components/team-switcher/markdown): A workspace switcher like Linear, Vercel or Slack. The trigger shows the current workspace's logo and plan. The menu has search, your role in each workspace and a Cmd+1 to 9 shortcut for each, and lets you create or join a workspace inline. A highlight glides between rows, and switching crossfades the trigger through a short loading state.
- [Live visitors](https://uiarc.dev/components/live-visitors/markdown): A realtime visitors card where the live count rolls digit by digit, new arrivals ping in on a dotted world map, the top pages reorder with bars, and signups and upgrades tick in with country flags.
- [Social proof toast](https://uiarc.dev/components/social-proof-toast/markdown): A stack of social proof notifications for landing and pricing pages, where recent trials, upgrades and verified purchases from people and companies arrive every few seconds. The stack pauses and fans out on hover, and visitors can dismiss any toast.
- [Install snippet](https://uiarc.dev/components/install-snippet/markdown): A "get started in 30 seconds" card where framework tabs, three numbered steps and highlighted snippets take a developer from install to first event. Generate key wipes a fresh API key into the placeholder in place.

### Guidance for AI tools

Enrich column: An AI enrichment column for a data table, where one prompt runs down every row and each cell shimmers while it works, then settles into a value with its source or a failure you can retry. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Ticket router

> A support ticket router where messages from Gmail, Intercom, Slack and Zendesk come in one at a time. An AI classifier labels each one with intent, sentiment and confidence, and the ticket moves into a team lane with an assignee. Low confidence tickets wait in a review lane, and one click there routes them to the suggested team.

- Type: Component (special)
- Access: Arc Pro
- Page: https://uiarc.dev/components/ticket-router
- Markdown: https://uiarc.dev/components/ticket-router/markdown
- Source file: `registry/components/ticket-router/ticket-router.tsx`
- Dependencies: motion, lucide-react
- Keywords: special, ai, new, ticket routing, support triage, ai classifier, helpdesk, intent detection, sentiment, confidence, queue, assignment, intercom, zendesk, gmail, slack, customer support

### When to use

- Showing how an AI classifier triages inbound support messages into team queues.
- A live triage widget in a helpdesk or ops dashboard, with a human review lane for low confidence.
- Landing page or onboarding demos of AI routing for support products.

### When not to use

- A full ticket inbox with search and bulk actions; use a table or list layout.
- A single tool step in a chat transcript; use tool-call.
- Generic multi step agent progress; use agent-status or agent-plan.

### Installation

Ticket router is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/ticket-router
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { TicketRouter } from "@/components/arc/ticket-router/ticket-router";

export function SupportInbox({ tickets }) {
  return (
    <TicketRouter
      tickets={tickets}
      reviewThreshold={0.75}
      classify={async (ticket, { signal }) => {
        const res = await fetch("/api/classify", { method: "POST", body: JSON.stringify(ticket), signal });
        return res.json(); // { intent, sentiment, confidence }
      }}
      onRoute={ticket => assignInHelpdesk(ticket.id, ticket.lane, ticket.assignee)}
    />
  );
}
```

### API reference

#### TicketRouter

A support ticket router card. Messages from Gmail, Intercom, Slack and Zendesk arrive one at a time, an AI classifier labels intent, sentiment and confidence, and the ticket lands in a team lane with a round robin assignee. Low confidence tickets go to the review lane, where a click confirms the suggested lane. With no props it plays a simulated inbox.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `tickets` | `TicketMessage[]` | `ticketRouterSamples` | Incoming messages, processed in order. Each has id, channel (email, intercom, slack, zendesk), customer, company, subject, preview and an optional receivedAt label. |
| `lanes` | `TicketLane[]` | `Billing, Engineering, Success, Needs review` | Team lanes left to right: id, label, assignees for round robin, count for tickets routed earlier, and review: true on the lane that collects low confidence tickets. |
| `initialRouted` | `RoutedTicket[]` | `samples when tickets is unset` | Tickets already in the lanes on first render, newest first. |
| `classify` | `(ticket, { signal }) => Promise<TicketClassification>` | – | Your classifier. Resolve { intent, sentiment, confidence }; throw to show the error state with Retry and Send to review. The signal aborts on pause, off screen and unmount. Without it a simulated classifier reads each ticket's sample. |
| `route` | `(ticket, classification) => string` | `billing and refund to billing, bug to engineering, feature to success` | Picks the lane id for a confident classification. |
| `reviewThreshold` | `number` | `0.7` | Confidence below this sends the ticket to the review lane with the picked lane as a suggestion. |
| `loop` | `boolean` | `true for samples, false for your tickets` | Starts over when the queue runs out. Without it the card shows All caught up, and resumes when you append tickets. |
| `paused` | `boolean` | – | Controls the flow. Pair with onPausedChange. |
| `defaultPaused` | `boolean` | `false` | Starts paused when uncontrolled. |
| `onPausedChange` | `(paused: boolean) => void` | – | Called by the Pause and Resume button. |
| `onRoute` | `(ticket: RoutedTicket) => void` | – | Called when a ticket lands in a lane, with its classification, lane, assignee and suggested lane. |
| `onReview` | `(ticket: RoutedTicket, lane: string) => void` | – | Called when someone confirms a review ticket's suggested lane. |
| `onError` | `(ticket: TicketMessage, error: unknown) => void` | – | Called when the classifier throws. |
| `maxVisible` | `number` | `3` | Rows shown per lane. Narrow containers show at most 2. |
| `speed` | `number` | `1` | Playback speed multiplier for the simulated flow. |
| `title` | `string` | `"Ticket routing"` | Card title. |
| `model` | `string` | `"Claude Haiku 5.5"` | Classifier model name in the header and the classifying label. |
| `modelMark` | `ReactNode` | `Claude mark` | Mark shown before the title. |
| `className` | `string` | – | Extra class on the root section. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Tab | Moves between Pause, the error actions and review tickets. |
| Enter / Space | Pauses or resumes, retries a failed classification, or confirms a review ticket's suggested lane. |

### Accessibility

- The card is a section labelled by its title. Each lane is a list labelled with its name and ticket count.
- A polite live region announces each routing ("routed to Billing, assigned to Andre Williams"), failures, pauses and review confirmations, and says when the run is simulated and nothing was sent.
- Intent, sentiment and review status always pair an icon with a text label; confidence reads as a percentage, never color alone.
- Review tickets are real buttons with a label naming the subject, confidence and target lane.

### Motion

- About two seconds per ticket: arrive 220ms, classify, labels fade in with a 50ms stagger, then a pulse draws along the connector to the target lane in 240ms and the row lands.
- Rows enter and leave by animating their measured height with a bounce free spring (visualDuration .24). Counters roll in reserved tabular width.
- Ticket swaps are a single crossfade: out in 100ms, in over 160ms with a small rise. No blur, no per letter motion.
- Reduced motion keeps every end state and the landing highlight, and drops travel, rises and the connector draw. The flow pauses off screen.

### Responsive behavior

- Fills its container up to 840px. Four lanes sit in a row with a connector above 600px of content width; below that they form a 2 by 2 grid with two rows each.
- Below 600px the classifier labels stack above the route target; below 400px the confidence meter and model name hide, keeping the percentage.
- Every text line truncates with an ellipsis, so long subjects and names never change the card height.

### Performance

- One timer or one classifier call runs at a time; both cancel on pause, off screen (IntersectionObserver) and unmount.
- Routed history is capped at 80 tickets and each lane renders only its visible rows.
- Marks are inline SVG with no network requests; avatars use the shared image component.

### Notes for AI

- Use for support triage, helpdesk automation and AI routing previews. Wire classify to your model call and onRoute to your helpdesk API.
- Lane ids returned by route must match lanes; an unknown id falls back to the first non review lane.
- Pass loop={false} with your own tickets to get the empty and All caught up states. Append to tickets to keep the flow going.
- Keep it inside a content column (360 to 880px). Below 600px the lanes fold into a 2 by 2 grid and the connector hides.

### Related

- [Agent status](https://uiarc.dev/components/agent-status/markdown): A compact live status pill for a running AI agent: the agent's mark in a live ring, the current activity and an elapsed timer, opening into the steps so far.
- [Tool call](https://uiarc.dev/components/tool-call/markdown): A tool call row for agent transcripts: the tool's mark and the call in plain words, a live state while it runs, and the input and output a click away, with approval and retry when needed.
- [Agent approvals](https://uiarc.dev/components/blocks/agent-approvals/markdown): One approval card for agents: the waiting tool call reads like a permission prompt with the tool's mark, the agent's reason and its arguments, and you approve, deny or allow it from now on.
- [Agent handoff](https://uiarc.dev/components/agent-handoff/markdown): A support conversation where an AI assistant hands off to a person. When it transfers, a card shows the summary it passes to the team and the typical wait. The person then joins and takes over, and a thin timeline on the left marks each step.
- [AI workflow](https://uiarc.dev/components/ai-workflow/markdown): A Linear-style AI workflow card where a Gmail trigger, a Claude step, a branch and Slack and Linear actions sit on one hairline rail, and a test run glides down it, opening each step's output inline. Steps are added from a compact command menu with real app marks.

### Also in ai

- [Agent plan](https://uiarc.dev/components/agent-plan/markdown): The plan an agent writes before it acts: edit, reorder or add steps while it is a draft, then watch it work through them as a live checklist.
- [Agent timeline](https://uiarc.dev/components/agent-timeline/markdown): A compact timeline of one orchestrated agent run: the orchestrator and its subagents share a time axis, handoffs draw in between rows, and a playhead replays thinking, tool calls and waiting while the header counts time, tokens and cost. Hover a span for what it did, or click it to trace its handoff path.
- [Context window](https://uiarc.dev/components/context-window/markdown): An AI context window as a grid of 200 cells: the system prompt, tools, files, summary and messages fill it in order, a threshold row marks where compaction starts, and sending a message, attaching a file or compacting shows exactly how much still fits.
- [Reasoning block](https://uiarc.dev/components/reasoning-block/markdown): The collapsible thinking block of an AI reply. While the model thinks, a shimmering label counts the seconds and the latest reasoning streams underneath. When it finishes, it folds to "Thought for 7s" and opens to show the full reasoning as calm steps with headings.
- [Source cards](https://uiarc.dev/components/source-cards/markdown): A row of cited sources under an AI answer where cards stream in with real site marks while the model searches, the overflow collapses into a stack of favicons, hovering lifts a preview with the passage, and an inline [n] citation highlights its card.
- [Model card](https://uiarc.dev/components/model-card/markdown): A model details card where switching models rolls every price, limit and score in place, a token slider estimates monthly cost live, and benchmark bars show each model's rank on hover. Compare crossfades to a side-by-side table against any rival with the better values marked, and the card never changes size.
- [Code suggestion](https://uiarc.dev/components/code-suggestion/markdown): An AI code edit suggestion where the model's proposed changes stream into a small editor panel as inline diff hunks, and you accept or reject each one, or all at once with Cmd+Enter. Accepted hunks fold into the file with a smooth height change.
- [Ghost text](https://uiarc.dev/components/ghost-text/markdown): An inline AI autocomplete where muted ghost text continues your sentence exactly at the caret and Tab turns it solid in place. Cmd+Right takes it one word at a time, Escape fades it away, and a calm chip shows the model behind it.
- [Image generation](https://uiarc.dev/components/image-generation/markdown): An image studio where each image forms on a dot matrix: a soft halftone wave breathes across the grid, the dots take the colours of the coming photo and grow into a coloured halftone, then blur away into the sharp photo. One large canvas with a mono size label, a filmstrip of four variations, a prompt bar with model and ratio, and upscale with a sweeping dot band, vary or download, with real provider marks and a built-in simulation.
- [Dictation button](https://uiarc.dev/components/dictation-button/markdown): A chat composer with voice input, where the mic springs into a recording pill with a smooth live waveform, a timer, and cancel and insert buttons. Words stream into the field as you speak, muted until the recognizer settles them.
- [Speech player](https://uiarc.dev/components/speech-player/markdown): A read-aloud player for AI replies. The Read aloud button in the message's action row turns into a compact player with play, a scrubbable progress bar, speed and a voice picker, and a highlight follows the spoken word through the reply, karaoke style.
- [Meeting summary](https://uiarc.dev/components/meeting-summary/markdown): An AI meeting notes card: the header shows the Google Meet or Zoom mark, the attendees and the duration. Summary, Decisions and Action items stream in after a short summarizing pass. Hover any line to see the transcript quote it came from, then check off action items or send them to Linear or Notion.
- [Reply draft](https://uiarc.dev/components/reply-draft/markdown): An AI email reply drafter where Claude streams a reply under a received Gmail message. Quick replies steer a fresh draft, tone and length rewrite it with a single crossfade, and you can edit the finished draft before you insert it.
- [PII redaction](https://uiarc.dev/components/pii-redaction/markdown): A guardrail card where personal data is redacted before the prompt reaches the model. Scan marks each name, email, phone number and card with its type and swaps it for a placeholder like [EMAIL_1]. The safe prompt travels to Claude, and the reply comes back with the original values put back for the person.
- [Response feedback](https://uiarc.dev/components/response-feedback/markdown): A feedback control for AI replies where thumbs down opens an inline panel with reason chips and an optional note, thumbs up fills and asks what was good, and a submit shows a short thank-you before folding back into the row.
- [LLM cost calculator](https://uiarc.dev/components/llm-cost-calculator/markdown): A pricing calculator for LLM workloads. Set tokens per request, requests per day and prompt caching, and eight current models re-rank by monthly cost. Bars glide and prices roll as you drag.
- [Provider keys](https://uiarc.dev/components/provider-keys/markdown): A settings card for bring-your-own-key AI products. Each provider row shows its real mark, the masked key, a status and when the key was last used. You can reveal a key for five seconds, copy, rotate or remove it with undo. Adding or rotating a key opens an inline form that checks the format as you type, then tests the connection before saving.
- [Generation stats](https://uiarc.dev/components/generation-stats/markdown): A live stats strip for a streaming LLM response where time to first token, speed with a sparkline, output tokens and cost count up in tabular numerals beside the model's real mark, then settle and open into a latency and token cost breakdown.
- [AI translate](https://uiarc.dev/components/ai-translate/markdown): A message card where picking a language streams the AI translation in place, sentence by sentence over the dimmed original, with a detected-language chip, a Show original toggle and a status line credited to the model's mark.
- [TL;DR toggle](https://uiarc.dev/components/tldr-toggle/markdown): An article card with a Full, Summary and Key points switch and a length slider. Switching streams an AI summary in place of the article as the card's height springs to fit, and each key point links back to the paragraph it came from, which gets scrolled to and highlighted.
- [Connector setup](https://uiarc.dev/components/connector-setup/markdown): A "Connect your tools" card for an AI assistant. Each app connects inline: it redirects, authorizes and runs a first sync with a progress hairline, then lists the scopes it was granted and offers Disconnect with an inline confirm.
- [Smart form fill](https://uiarc.dev/components/smart-form-fill/markdown): A paste-to-fill form card where AI reads an email signature or messy notes and fills a contact field by field. Each value flashes in with a confidence dot, its source lights up in the pasted text, low-confidence guesses ask for review, and Undo puts the old values back.
- [Enrich column](https://uiarc.dev/components/enrich-column/markdown): An AI enrichment column for a data table, where one prompt runs down every row and each cell shimmers while it works, then settles into a value with its source or a failure you can retry.
- [Ask your data](https://uiarc.dev/components/ask-your-data/markdown): A natural language to chart card: you ask a question, PostgreSQL streams into a collapsible, syntax highlighted panel, the query runs with a rolling row count, and the answer builds as stacked bars, lines or a table, with a one line insight streamed in underneath.
- [Agent cursor](https://uiarc.dev/components/agent-cursor/markdown): A live document where Claude edits like a collaborator. Its labeled cursor comes out of its avatar, selects a paragraph and streams in a rewrite, adds a heading and fixes a typo, while a teammate's cursor reads along. Changes stay tinted until someone accepts or undoes them from a floating review bar.
- [Provider status](https://uiarc.dev/components/provider-status/markdown): A status card for the AI providers your product depends on. Each row shows the provider's real mark, its health as an icon and label, p50 latency and a 30-day uptime bar with a tooltip for each day. An incident row expands into its timeline of updates, and the card checks again on a visible countdown.
- [Training run](https://uiarc.dev/components/training-run/markdown): A fine-tuning job card where a live train and validation loss curve draws across a fixed step axis that doubles as the epoch progress bar. It shows the learning rate, elapsed time, ETA and the latest evals and checkpoints, has Pause and Cancel while it runs, and ends in results with a Deploy button.
- [AI command](https://uiarc.dev/components/ai-command/markdown): A Cmd+K command palette with an AI mode. Search pages and actions, or press Tab to ask a question: the answer streams inside the palette with numbered sources, and the next steps it suggests, like filing a Linear issue or opening a Notion doc, run straight from the list.
- [Starter prompts](https://uiarc.dev/components/starter-prompts/markdown): A greeting and a grid of starter cards for the empty state of an AI app. The cards are grouped into Write, Code, Analyze and Plan tabs, and a shuffle swaps them with a short staggered crossfade. Picking a card fills the composer, and cards that use a connected app show its mark (Gmail, GitHub, Notion, Linear, Google Calendar).
- [AI mascot](https://uiarc.dev/components/ai-mascot/markdown): A small assistant character, a soft pebble with pill eyes and a companion dot, that shows what the AI is doing. It breathes and glances when idle, leans in to listen, looks up while the dot orbits its head, reads along the line it writes, squints with a sparkle when done and shakes once with worried brows on an error.
- [Image reveal](https://uiarc.dev/components/image-reveal/markdown): An image generation canvas where a soft, blurred preview made from the image's own colors sharpens top to bottom behind a soft-edged band. It works the way ChatGPT, Midjourney and Gemini show images forming, with fine film grain, a translucent progress pill and calm queued and error states.
- [AI spark](https://uiarc.dev/components/ai-spark/markdown): A brand-quality animated spark mark. Four tapered rays and four lighter diagonals breathe at rest, ripple while thinking, pulse like a heartbeat while writing, then gather and settle when done. Every status change blends from the pose the mark is already in.
- [Pixel mascot](https://uiarc.dev/components/pixel-mascot/markdown): A pixel-art robot that shows what an AI assistant is doing. It idles, thinks, types, celebrates and errors in frame-stepped sprite animations, and stays crisp at every integer size from 24px to 192px.
- [Ghost mascot](https://uiarc.dev/components/ghost-mascot/markdown): A floating ghost mascot whose soft sheet ripples at the hem while it hovers. It blinks when idle, turns toward you to listen, fades a little translucent while thinking, draws a tiny pen line while writing, smiles with a sparkle when done and wobbles once on an error.
- [Cube mascot](https://uiarc.dev/components/cube-mascot/markdown): An isometric cube mascot where three shaded faces and a painted-on face show what the assistant is doing. It turns a quarter turn in eased steps while thinking, prints lines onto the floor while writing, settles with a sparkle when done, and shakes once on error.
- [Tone tuner](https://uiarc.dev/components/tone-tuner/markdown): A brand voice card where two sliders (formality and detail) and Friendly, Confident and Empathetic chips rewrite a customer reply. Each changed sentence crossfades in place, new words can be highlighted against the original, and Copy takes the current version.
- [Upgrade prompt](https://uiarc.dev/components/upgrade-prompt/markdown): An upgrade nudge for the moment someone hits a limit. It shows a usage meter at 50 of 50 AI credits, a rolling price with a monthly and yearly toggle, three concrete unlocks with real model marks, and Upgrade or Maybe later. Upgrading leads into a success state with the new limits, and the card never changes size between states.
- [Referral card](https://uiarc.dev/components/referral-card/markdown): A give-and-get referral card where people copy or share their invite link, invite friends by email as chips, and watch invites move from invited to signed up to earned, with the credit total counting up and a milestone reward unlocking.
- [Trial banner](https://uiarc.dev/components/trial-banner/markdown): A trial status banner where a ring counts down the days left, the copy names what the workspace loses, and the upgrade path is one click away. It comes as a slim banner, a sidebar card or a header pill. It shifts to a warning tone in the last days, has expired and upgraded states, and folds into the pill when dismissed or snoozed.
- [Team switcher](https://uiarc.dev/components/team-switcher/markdown): A workspace switcher like Linear, Vercel or Slack. The trigger shows the current workspace's logo and plan. The menu has search, your role in each workspace and a Cmd+1 to 9 shortcut for each, and lets you create or join a workspace inline. A highlight glides between rows, and switching crossfades the trigger through a short loading state.
- [Live visitors](https://uiarc.dev/components/live-visitors/markdown): A realtime visitors card where the live count rolls digit by digit, new arrivals ping in on a dotted world map, the top pages reorder with bars, and signups and upgrades tick in with country flags.
- [Social proof toast](https://uiarc.dev/components/social-proof-toast/markdown): A stack of social proof notifications for landing and pricing pages, where recent trials, upgrades and verified purchases from people and companies arrive every few seconds. The stack pauses and fans out on hover, and visitors can dismiss any toast.
- [Install snippet](https://uiarc.dev/components/install-snippet/markdown): A "get started in 30 seconds" card where framework tabs, three numbered steps and highlighted snippets take a developer from install to first event. Generate key wipes a fresh API key into the placeholder in place.

### Guidance for AI tools

Ticket router: A support ticket router where messages from Gmail, Intercom, Slack and Zendesk come in one at a time. An AI classifier labels each one with intent, sentiment and confidence, and the ticket moves into a team lane with an assignee. Low confidence tickets wait in a review lane, and one click there routes them to the suggested team. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Ask your data

> A natural language to chart card: you ask a question, PostgreSQL streams into a collapsible, syntax highlighted panel, the query runs with a rolling row count, and the answer builds as stacked bars, lines or a table, with a one line insight streamed in underneath.

- Type: Component (special)
- Access: Arc Pro
- Page: https://uiarc.dev/components/ask-your-data
- Markdown: https://uiarc.dev/components/ask-your-data/markdown
- Source file: `registry/components/ask-your-data/ask-your-data.tsx`
- Dependencies: motion, lucide-react
- Keywords: special, ai, new, ask your data, text to sql, natural language query, nl2sql, ai analytics, chart, postgresql, sql generation, stacked bar chart, line chart, data table, insight, bi, self serve analytics

### When to use

- Letting people ask product or business questions in plain words and see a chart, with the SQL one click away to verify or copy.
- Embedding an analytics answer in a dashboard card, an admin page or an AI assistant's result view.
- Teaching or auditing text to SQL, where showing the generated query builds trust.

### When not to use

- Use bar-chart or line-chart when the query is fixed and there is no question to ask.
- Use tool-call to show a database query as one step inside a longer agent transcript.
- Use sql-editor when people write and tune queries by hand.

### Installation

Ask your data is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/ask-your-data
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { AskYourData } from "@/components/arc/ask-your-data/ask-your-data";

// Self playing preview with sample data
<AskYourData />

// Wired to your model and a read only database role
export function Explore() {
  return (
    <AskYourData
      source={{ name: "analytics", dialect: "PostgreSQL" }}
      generateSql={(question, { signal }) => streamSql(question, { signal })} // AsyncIterable<string>
      runQuery={async (sql, { signal, onProgress }) => {
        const res = await fetch("/api/query", { method: "POST", body: JSON.stringify({ sql }), signal });
        if (!res.ok) throw new Error(await res.text()); // shows the database error
        const { rows, ms } = await res.json();
        onProgress(rows.length, rows.length);
        return {
          title: "Weekly signups by plan",
          categories: weeksOf(rows),
          series: seriesByPlan(rows),
          rowCount: rows.length,
          durationMs: ms,
        };
      }}
      onResult={(result, { sql }) => saveToHistory(result.title, sql)}
    />
  );
}
```

### API reference

#### AskYourData

Natural language to chart in one card. A question field with the data source, a collapsible Generated SQL panel where PostgreSQL streams in with syntax tints, a running state with a rolling row count, then a result that builds as stacked bars, lines or a table, with a legend, a hover and keyboard readout, and a streamed one line insight. With no props it asks "Weekly signups by plan since August" against sample data once it scrolls into view.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `question` | `string` | – | Controlled question text. Pair with onQuestionChange. |
| `defaultQuestion` | `string` | `"Weekly signups by plan since August"` | Starting question when uncontrolled; autoRun asks it. |
| `onQuestionChange` | `(question: string) => void` | – | Called as the person types or picks a suggestion. |
| `placeholder` | `string` | `"Ask a question about your data"` | Placeholder for the empty field. |
| `source` | `{ name: string; dialect?: string; mark?: ReactNode }` | `{ name: "analytics", dialect: "PostgreSQL" }` | The database the question runs against. The name shows in the field and the empty state; the dialect leads the SQL meta. |
| `suggestions` | `string[]` | `three sample questions` | Questions offered in the empty state and after a question that matches no data. Pass [] to hide them. |
| `generateSql` | `(question, { signal, source }) => Promise<string \| AsyncIterable<string>> \| string \| AsyncIterable<string>` | – | Writes SQL for the question. Return the whole string and the card streams it in four words a tick at a fixed final size, or return an async iterable of chunks from your model and the panel grows with them. Respect signal: Stop aborts it. Without it a sample model answers. |
| `runQuery` | `(sql, { signal, onProgress, question }) => Promise<AskYourDataResult>` | – | Runs the SQL (read only) and returns a chart ready result. Call onProgress(rowsScanned, totalRows?) to roll the count in the running state; passing the total reserves its width. Throw to show the database error. Without it sample data answers. |
| `onResult` | `(result: AskYourDataResult, details: { question: string; sql: string }) => void` | – | Called once a result is charted, for saving the question to a dashboard or logging. |
| `onError` | `(error: unknown, details: { question: string; stage: "sql" \| "query" }) => void` | – | Called when writing or running fails. Not called when the person stops a run. |
| `chart` | `"bar" \| "line" \| "table"` | – | Controlled view. Pair with onChartChange. |
| `defaultChart` | `"bar" \| "line" \| "table"` | `"bar"` | View for results that do not set result.chart. |
| `onChartChange` | `(chart: "bar" \| "line" \| "table") => void` | – | Called when the person switches the view. |
| `autoRun` | `boolean` | `true without generateSql` | Asks the starting question once the card is 35% on screen. Off by default when you wire a real model. |
| `keepSqlOpen` | `boolean` | `false` | Keeps the SQL panel open after the query starts instead of folding it away. Once the person opens or closes the panel, their choice wins. |
| `className` | `string` | – | Class on the card. |

#### AskYourDataResult

What runQuery returns, shaped for the chart.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` (required) | `string` | – | Chart title, such as "Weekly signups by plan". |
| `subtitle` | `string` | – | Quiet line under the title, such as "Aug 3 to Oct 25 · 1,284 signups". |
| `categories` (required) | `string[]` | – | X axis labels in order, such as week starts. Labels thin out on narrow cards. |
| `series` (required) | `{ id: string; label: string; values: number[]; color?: string }[]` | – | One entry per plan, region or metric, with one value per category. Colors default to --series-1 through --series-4. |
| `stacked` | `boolean` | `true` | Series add up: bars stack, and the legend, tooltip and table show totals. Set false for rates and averages; bars then group side by side. |
| `legendValue` | `"sum" \| "last" \| "none"` | `"sum" when stacked, else "none"` | What follows each legend label: the series total for flows like signups, the latest value for levels like MRR, or nothing. |
| `chart` | `"bar" \| "line" \| "table"` | – | View to open on for this result. |
| `categoryLabel` | `string` | `"Category"` | Header of the table's first column, such as "Week". |
| `formatValue` | `(value: number) => string` | `en-US grouping` | Formats axis ticks, legend totals, tooltip and table cells, such as $258k or 3.9%. |
| `insight` | `string` | – | One or two sentences that read the chart. Streams in under it with its final height reserved. |
| `rowCount` | `number` | – | Rows the query returned, shown in the SQL meta as "48 rows". |
| `durationMs` | `number` | – | Query time, shown as 214ms or 1.2s. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Enter | In the question field, asks the question. While writing or running, the same button stops the run. |
| Escape | In the question field, stops a run in progress. |
| Tab | Moves through the field, Ask, the Generated SQL row, Copy SQL, the code block (scrollable), the chart switch, the chart, and suggestions or Try again. |
| Enter, Space | On the Generated SQL row, opens or closes the SQL. |
| Left, Right, Home, End | On the chart, moves the readout between categories; on the chart switch, changes the view. |
| Escape (chart) | Clears the chart readout. |

### Accessibility

- A polite live region narrates the run: writing SQL, running the query, then the chart title, row count and insight. Without generateSql and runQuery it adds "Simulated with sample data, nothing was queried."
- Status is never color alone: a spinner, a drawn check, an alert or a stop glyph sits beside a text label in the SQL row and the stage header.
- The SQL row is a real button with aria-expanded and aria-controls, labelled with its title and meta, such as "Generated SQL, PostgreSQL · 48 rows · 214ms". Text not yet streamed is hidden from assistive technology.
- The chart is a focusable group: arrow keys move a readout that is announced, such as "Aug 10: Free 61, Pro 26, Team 10, Enterprise 2, total 99". The table view keeps real table semantics with column and row headers.
- The stage sets aria-busy while working. Text fields get no focus ring by design; the field border shifts to the accent on focus, and every other control uses Arc's shared keyboard ring.

### Motion

- SQL streams four tokens every 34ms, each chunk only fading in over 140ms. The full query is laid out invisibly first, so the panel holds its final size and nothing below moves.
- The SQL panel opens and folds on a 300ms bounce free spring; it folds once the query starts, before the chart builds, so only one region moves at a time.
- Bars rise from the baseline in 320ms with at most 180ms of stagger; lines draw in 460ms. Switching views crossfades (100ms out, 160ms in) in a fixed area.
- Header text and the SQL meta crossfade as single lines with a 2px settle. The row count rolls in tabular numerals in reserved width.
- The insight streams four words a tick with its two lines reserved. Reduced motion shows SQL and insight whole, drops the bar rise, line draw, spinner and breathing skeleton, and keeps every state and announcement. Loops pause off screen.

### Responsive behavior

- Container aware: below 520px the source keeps only its icon, the chart switch moves into the result above the legend at full width, and the stage grows to fit wrapped legend and insight lines.
- X axis labels thin out to keep 46px apart, wide SQL lines and tables scroll inside their own wells, and the tooltip flips to whichever side of the column has room.
- Touch: tap or drag across the chart to read values; vertical scrolling still passes through.

### Performance

- Charts are plain SVG measured with one ResizeObserver, no chart library. Text and hairlines are drawn at device pixels, so they stay crisp at any width.
- The SQL tokenizer is a single regular expression pass, memoized per query. The SQL panel and every view mount only while shown.
- Rows scanned updates come through onProgress; batch them to a few per second for very fast queries.

### Notes for AI

- Use it for self serve analytics inside a product: a question box on a dashboard, a metrics page, or an admin console. Wire generateSql to your model with the schema in the prompt and runQuery to a read only role with a statement timeout.
- Return the SQL as an async iterable of model chunks for true streaming, or a whole string for the paced reveal. Always honour signal so Stop really cancels both steps.
- Shape rows into categories and series in runQuery. Keep series to four or fewer for the default palette; set stacked false for rates or averages so totals are not shown.
- Let the model write the insight from the returned rows, one or two sentences with concrete numbers. Do not invent numbers that are not in the result.
- Throw from runQuery with the database message to show it verbatim in the error state with Try again.

### Related

- [Tool call](https://uiarc.dev/components/tool-call/markdown): A tool call row for agent transcripts: the tool's mark and the call in plain words, a live state while it runs, and the input and output a click away, with approval and retry when needed.
- [AI chat](https://uiarc.dev/components/blocks/ai-chat/markdown): A full-screen AI chat where answers stream in as markdown with folding reasoning, tool chips and cited sources. People can switch chats and models, edit or retry a message into versions, rate replies and stop a reply mid-stream.
- [Agent run](https://uiarc.dev/components/blocks/agent-run/markdown): A single card that follows one AI coding agent through a task: steps stream in with the live one shimmering, tool calls open in place, and the agent stops on a two-file diff for you to approve or send back before it writes. When the run ends, the steps fold into one line and a result shows the files changed, the checks that passed and a pull request button.
- [Bar chart](https://uiarc.dev/components/bar-chart/markdown): Compare one measure across days and scrub any bar for its value.
- [Line chart](https://uiarc.dev/components/line-chart/markdown): A multi-series line chart with a gliding crosshair, legend toggles, and paths that morph between ranges.
- [Text shimmer](https://uiarc.dev/components/text-shimmer/markdown): Show ongoing work with a calm light across the words.

### Also in ai

- [Agent status](https://uiarc.dev/components/agent-status/markdown): A compact live status pill for a running AI agent: the agent's mark in a live ring, the current activity and an elapsed timer, opening into the steps so far.
- [Agent plan](https://uiarc.dev/components/agent-plan/markdown): The plan an agent writes before it acts: edit, reorder or add steps while it is a draft, then watch it work through them as a live checklist.
- [Agent timeline](https://uiarc.dev/components/agent-timeline/markdown): A compact timeline of one orchestrated agent run: the orchestrator and its subagents share a time axis, handoffs draw in between rows, and a playhead replays thinking, tool calls and waiting while the header counts time, tokens and cost. Hover a span for what it did, or click it to trace its handoff path.
- [Context window](https://uiarc.dev/components/context-window/markdown): An AI context window as a grid of 200 cells: the system prompt, tools, files, summary and messages fill it in order, a threshold row marks where compaction starts, and sending a message, attaching a file or compacting shows exactly how much still fits.
- [Reasoning block](https://uiarc.dev/components/reasoning-block/markdown): The collapsible thinking block of an AI reply. While the model thinks, a shimmering label counts the seconds and the latest reasoning streams underneath. When it finishes, it folds to "Thought for 7s" and opens to show the full reasoning as calm steps with headings.
- [Source cards](https://uiarc.dev/components/source-cards/markdown): A row of cited sources under an AI answer where cards stream in with real site marks while the model searches, the overflow collapses into a stack of favicons, hovering lifts a preview with the passage, and an inline [n] citation highlights its card.
- [Model card](https://uiarc.dev/components/model-card/markdown): A model details card where switching models rolls every price, limit and score in place, a token slider estimates monthly cost live, and benchmark bars show each model's rank on hover. Compare crossfades to a side-by-side table against any rival with the better values marked, and the card never changes size.
- [AI workflow](https://uiarc.dev/components/ai-workflow/markdown): A Linear-style AI workflow card where a Gmail trigger, a Claude step, a branch and Slack and Linear actions sit on one hairline rail, and a test run glides down it, opening each step's output inline. Steps are added from a compact command menu with real app marks.
- [Code suggestion](https://uiarc.dev/components/code-suggestion/markdown): An AI code edit suggestion where the model's proposed changes stream into a small editor panel as inline diff hunks, and you accept or reject each one, or all at once with Cmd+Enter. Accepted hunks fold into the file with a smooth height change.
- [Ghost text](https://uiarc.dev/components/ghost-text/markdown): An inline AI autocomplete where muted ghost text continues your sentence exactly at the caret and Tab turns it solid in place. Cmd+Right takes it one word at a time, Escape fades it away, and a calm chip shows the model behind it.
- [Image generation](https://uiarc.dev/components/image-generation/markdown): An image studio where each image forms on a dot matrix: a soft halftone wave breathes across the grid, the dots take the colours of the coming photo and grow into a coloured halftone, then blur away into the sharp photo. One large canvas with a mono size label, a filmstrip of four variations, a prompt bar with model and ratio, and upscale with a sweeping dot band, vary or download, with real provider marks and a built-in simulation.
- [Dictation button](https://uiarc.dev/components/dictation-button/markdown): A chat composer with voice input, where the mic springs into a recording pill with a smooth live waveform, a timer, and cancel and insert buttons. Words stream into the field as you speak, muted until the recognizer settles them.
- [Speech player](https://uiarc.dev/components/speech-player/markdown): A read-aloud player for AI replies. The Read aloud button in the message's action row turns into a compact player with play, a scrubbable progress bar, speed and a voice picker, and a highlight follows the spoken word through the reply, karaoke style.
- [Meeting summary](https://uiarc.dev/components/meeting-summary/markdown): An AI meeting notes card: the header shows the Google Meet or Zoom mark, the attendees and the duration. Summary, Decisions and Action items stream in after a short summarizing pass. Hover any line to see the transcript quote it came from, then check off action items or send them to Linear or Notion.
- [Reply draft](https://uiarc.dev/components/reply-draft/markdown): An AI email reply drafter where Claude streams a reply under a received Gmail message. Quick replies steer a fresh draft, tone and length rewrite it with a single crossfade, and you can edit the finished draft before you insert it.
- [Agent handoff](https://uiarc.dev/components/agent-handoff/markdown): A support conversation where an AI assistant hands off to a person. When it transfers, a card shows the summary it passes to the team and the typical wait. The person then joins and takes over, and a thin timeline on the left marks each step.
- [PII redaction](https://uiarc.dev/components/pii-redaction/markdown): A guardrail card where personal data is redacted before the prompt reaches the model. Scan marks each name, email, phone number and card with its type and swaps it for a placeholder like [EMAIL_1]. The safe prompt travels to Claude, and the reply comes back with the original values put back for the person.
- [Response feedback](https://uiarc.dev/components/response-feedback/markdown): A feedback control for AI replies where thumbs down opens an inline panel with reason chips and an optional note, thumbs up fills and asks what was good, and a submit shows a short thank-you before folding back into the row.
- [LLM cost calculator](https://uiarc.dev/components/llm-cost-calculator/markdown): A pricing calculator for LLM workloads. Set tokens per request, requests per day and prompt caching, and eight current models re-rank by monthly cost. Bars glide and prices roll as you drag.
- [Provider keys](https://uiarc.dev/components/provider-keys/markdown): A settings card for bring-your-own-key AI products. Each provider row shows its real mark, the masked key, a status and when the key was last used. You can reveal a key for five seconds, copy, rotate or remove it with undo. Adding or rotating a key opens an inline form that checks the format as you type, then tests the connection before saving.
- [Generation stats](https://uiarc.dev/components/generation-stats/markdown): A live stats strip for a streaming LLM response where time to first token, speed with a sparkline, output tokens and cost count up in tabular numerals beside the model's real mark, then settle and open into a latency and token cost breakdown.
- [AI translate](https://uiarc.dev/components/ai-translate/markdown): A message card where picking a language streams the AI translation in place, sentence by sentence over the dimmed original, with a detected-language chip, a Show original toggle and a status line credited to the model's mark.
- [TL;DR toggle](https://uiarc.dev/components/tldr-toggle/markdown): An article card with a Full, Summary and Key points switch and a length slider. Switching streams an AI summary in place of the article as the card's height springs to fit, and each key point links back to the paragraph it came from, which gets scrolled to and highlighted.
- [Connector setup](https://uiarc.dev/components/connector-setup/markdown): A "Connect your tools" card for an AI assistant. Each app connects inline: it redirects, authorizes and runs a first sync with a progress hairline, then lists the scopes it was granted and offers Disconnect with an inline confirm.
- [Smart form fill](https://uiarc.dev/components/smart-form-fill/markdown): A paste-to-fill form card where AI reads an email signature or messy notes and fills a contact field by field. Each value flashes in with a confidence dot, its source lights up in the pasted text, low-confidence guesses ask for review, and Undo puts the old values back.
- [Enrich column](https://uiarc.dev/components/enrich-column/markdown): An AI enrichment column for a data table, where one prompt runs down every row and each cell shimmers while it works, then settles into a value with its source or a failure you can retry.
- [Ticket router](https://uiarc.dev/components/ticket-router/markdown): A support ticket router where messages from Gmail, Intercom, Slack and Zendesk come in one at a time. An AI classifier labels each one with intent, sentiment and confidence, and the ticket moves into a team lane with an assignee. Low confidence tickets wait in a review lane, and one click there routes them to the suggested team.
- [Agent cursor](https://uiarc.dev/components/agent-cursor/markdown): A live document where Claude edits like a collaborator. Its labeled cursor comes out of its avatar, selects a paragraph and streams in a rewrite, adds a heading and fixes a typo, while a teammate's cursor reads along. Changes stay tinted until someone accepts or undoes them from a floating review bar.
- [Provider status](https://uiarc.dev/components/provider-status/markdown): A status card for the AI providers your product depends on. Each row shows the provider's real mark, its health as an icon and label, p50 latency and a 30-day uptime bar with a tooltip for each day. An incident row expands into its timeline of updates, and the card checks again on a visible countdown.
- [Training run](https://uiarc.dev/components/training-run/markdown): A fine-tuning job card where a live train and validation loss curve draws across a fixed step axis that doubles as the epoch progress bar. It shows the learning rate, elapsed time, ETA and the latest evals and checkpoints, has Pause and Cancel while it runs, and ends in results with a Deploy button.
- [AI command](https://uiarc.dev/components/ai-command/markdown): A Cmd+K command palette with an AI mode. Search pages and actions, or press Tab to ask a question: the answer streams inside the palette with numbered sources, and the next steps it suggests, like filing a Linear issue or opening a Notion doc, run straight from the list.
- [Starter prompts](https://uiarc.dev/components/starter-prompts/markdown): A greeting and a grid of starter cards for the empty state of an AI app. The cards are grouped into Write, Code, Analyze and Plan tabs, and a shuffle swaps them with a short staggered crossfade. Picking a card fills the composer, and cards that use a connected app show its mark (Gmail, GitHub, Notion, Linear, Google Calendar).
- [AI mascot](https://uiarc.dev/components/ai-mascot/markdown): A small assistant character, a soft pebble with pill eyes and a companion dot, that shows what the AI is doing. It breathes and glances when idle, leans in to listen, looks up while the dot orbits its head, reads along the line it writes, squints with a sparkle when done and shakes once with worried brows on an error.
- [Image reveal](https://uiarc.dev/components/image-reveal/markdown): An image generation canvas where a soft, blurred preview made from the image's own colors sharpens top to bottom behind a soft-edged band. It works the way ChatGPT, Midjourney and Gemini show images forming, with fine film grain, a translucent progress pill and calm queued and error states.
- [AI spark](https://uiarc.dev/components/ai-spark/markdown): A brand-quality animated spark mark. Four tapered rays and four lighter diagonals breathe at rest, ripple while thinking, pulse like a heartbeat while writing, then gather and settle when done. Every status change blends from the pose the mark is already in.
- [Pixel mascot](https://uiarc.dev/components/pixel-mascot/markdown): A pixel-art robot that shows what an AI assistant is doing. It idles, thinks, types, celebrates and errors in frame-stepped sprite animations, and stays crisp at every integer size from 24px to 192px.
- [Ghost mascot](https://uiarc.dev/components/ghost-mascot/markdown): A floating ghost mascot whose soft sheet ripples at the hem while it hovers. It blinks when idle, turns toward you to listen, fades a little translucent while thinking, draws a tiny pen line while writing, smiles with a sparkle when done and wobbles once on an error.
- [Cube mascot](https://uiarc.dev/components/cube-mascot/markdown): An isometric cube mascot where three shaded faces and a painted-on face show what the assistant is doing. It turns a quarter turn in eased steps while thinking, prints lines onto the floor while writing, settles with a sparkle when done, and shakes once on error.
- [Tone tuner](https://uiarc.dev/components/tone-tuner/markdown): A brand voice card where two sliders (formality and detail) and Friendly, Confident and Empathetic chips rewrite a customer reply. Each changed sentence crossfades in place, new words can be highlighted against the original, and Copy takes the current version.
- [Upgrade prompt](https://uiarc.dev/components/upgrade-prompt/markdown): An upgrade nudge for the moment someone hits a limit. It shows a usage meter at 50 of 50 AI credits, a rolling price with a monthly and yearly toggle, three concrete unlocks with real model marks, and Upgrade or Maybe later. Upgrading leads into a success state with the new limits, and the card never changes size between states.
- [Referral card](https://uiarc.dev/components/referral-card/markdown): A give-and-get referral card where people copy or share their invite link, invite friends by email as chips, and watch invites move from invited to signed up to earned, with the credit total counting up and a milestone reward unlocking.
- [Trial banner](https://uiarc.dev/components/trial-banner/markdown): A trial status banner where a ring counts down the days left, the copy names what the workspace loses, and the upgrade path is one click away. It comes as a slim banner, a sidebar card or a header pill. It shifts to a warning tone in the last days, has expired and upgraded states, and folds into the pill when dismissed or snoozed.
- [Team switcher](https://uiarc.dev/components/team-switcher/markdown): A workspace switcher like Linear, Vercel or Slack. The trigger shows the current workspace's logo and plan. The menu has search, your role in each workspace and a Cmd+1 to 9 shortcut for each, and lets you create or join a workspace inline. A highlight glides between rows, and switching crossfades the trigger through a short loading state.
- [Live visitors](https://uiarc.dev/components/live-visitors/markdown): A realtime visitors card where the live count rolls digit by digit, new arrivals ping in on a dotted world map, the top pages reorder with bars, and signups and upgrades tick in with country flags.
- [Social proof toast](https://uiarc.dev/components/social-proof-toast/markdown): A stack of social proof notifications for landing and pricing pages, where recent trials, upgrades and verified purchases from people and companies arrive every few seconds. The stack pauses and fans out on hover, and visitors can dismiss any toast.
- [Install snippet](https://uiarc.dev/components/install-snippet/markdown): A "get started in 30 seconds" card where framework tabs, three numbered steps and highlighted snippets take a developer from install to first event. Generate key wipes a fresh API key into the placeholder in place.

### Guidance for AI tools

Ask your data: A natural language to chart card: you ask a question, PostgreSQL streams into a collapsible, syntax highlighted panel, the query runs with a rolling row count, and the answer builds as stacked bars, lines or a table, with a one line insight streamed in underneath. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Agent cursor

> A live document where Claude edits like a collaborator. Its labeled cursor comes out of its avatar, selects a paragraph and streams in a rewrite, adds a heading and fixes a typo, while a teammate's cursor reads along. Changes stay tinted until someone accepts or undoes them from a floating review bar.

- Type: Component (special)
- Access: Arc Pro
- Page: https://uiarc.dev/components/agent-cursor
- Markdown: https://uiarc.dev/components/agent-cursor/markdown
- Source file: `registry/components/agent-cursor/agent-cursor.tsx`
- Dependencies: motion, lucide-react
- Keywords: special, ai, new, ai cursor, agent cursor, multiplayer cursor, collaborative editing, ai writing assistant, live document edit, accept changes, suggested edits, claude, notion ai, presence

### When to use

- Showing an AI writing assistant that edits a doc alongside people, with accept and undo.
- Landing or onboarding sections that demo a collaborative AI editor in motion.
- A product surface that streams structured edits from an agent and needs a human review step.

### When not to use

- Free form chat or Q&A: use a chat transcript component.
- A real rich text editor: wire your editor's own collaboration cursors; this card renders read-only blocks.
- Long documents with many sections: the card is built for a short excerpt of five to ten blocks.

### Installation

Agent cursor is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/agent-cursor
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { AgentCursor, type AgentEdit, type DocBlock } from "@/components/arc/agent-cursor/agent-cursor";

const [doc, setDoc] = useState<DocBlock[]>(initialDoc);

<AgentCursor
  blocks={doc}
  run={async signal => {
    const res = await fetch("/api/agent/edits", { method: "POST", body: JSON.stringify(doc), signal });
    return (await res.json()) as AgentEdit[];
  }}
  collaborator={{ name: "Emma Collins", avatar: "/media/people/emma-collins.svg" }}
  onAccept={setDoc}
/>
```

### API reference

#### AgentCursor

A document card where an AI agent edits live with a labeled cursor beside a human collaborator, then hands the changes over for review. With no props it plays a simulated run on a sample launch brief.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `blocks` | `DocBlock[]` | `sample launch brief` | The document as title, heading and paragraph blocks with stable ids. Compared by content, so an inline array is fine. |
| `meta` | `string` | – | A muted line under the title, such as the owner and a target date. |
| `edits` | `AgentEdit[]` | `sample edits` | Edits to play in order: rewrite (select a block and stream new text), insert (add a block after another) and fix (replace a word, flagged with a wavy underline first). Ignored when run is set. |
| `run` | `(signal: AbortSignal) => Promise<AgentEdit[]>` | – | Fetches edits from your agent. The signal aborts when someone presses Stop. A rejected promise shows the error with a Retry button. |
| `agent` | `{ name: string; mark?: ReactNode; color?: string }` | `Claude, #D97757` | The agent's name, 24 × 24 currentColor mark, and the color used for its cursor, selection and change tint. |
| `collaborator` | `{ name: string; avatar?: string; color?: string } \| null` | `Emma Collins` | A human in the doc, drawn as a second cursor with their portrait and first name. Null hides it. |
| `autoPlay` | `boolean` | `true` | Starts a run as soon as the card is on screen. Off, the header shows an Ask button instead. |
| `loop` | `boolean` | `true for the sample` | Replays the run: the collaborator accepts after a short pause (never while you hover or focus the card), then the doc resets. |
| `speed` | `number` | `1` | Playback speed multiplier for cursor travel, streaming and pauses. |
| `onAccept` | `(blocks: DocBlock[]) => void` | – | Called with the edited document when someone accepts. Store it and pass it back as blocks. |
| `onUndo` | `(blocks: DocBlock[]) => void` | – | Called with the restored document when someone undoes the edits. |
| `onPhaseChange` | `(phase: AgentCursorPhase) => void` | – | Fires on idle, thinking, editing, review, accepted, reverted, stopped, empty and error. |
| `simulated` | `boolean` | `true for the sample` | Adds "Simulated, nothing was saved" to the screen reader status. |
| `className` | `string` | – | Extra class on the card. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Tab | Moves between Stop or Run again in the header, then Undo and Accept changes in the review bar. |
| Enter / Space | Activates the focused button. |

### Accessibility

- A polite live region announces each step (reading, the current edit, edits ready, accepted, undone, errors), and adds "Simulated, nothing was saved" for simulated runs.
- Cursors, selections and the visual status line are decorative and hidden from assistive tech; the document stays real headings and paragraphs, marked aria-busy while the agent edits.
- Status never relies on color: every terminal state pairs an icon with a label, and pending changes are tinted and listed in the review bar with a count.
- Focus inside the card or a hovering pointer holds the looping demo in review, so nobody loses the bar mid reach.

### Motion

- Cursors glide on a gentle quadratic arc with an ease-in-out curve, 280 to 600ms by distance, driven by motion values so nothing re-renders per frame.
- Selections fill line by line in step with the drag. Rewrites fade the old text out in 110ms, then stream 3 to 6 words every 34ms, each chunk fading in over 140ms with no blur or slide.
- Block heights follow measured content with a bounce-free spring (0.24s); inserted blocks grow from zero, then their text fades in.
- Status labels crossfade (100ms out, 160ms in). The review bar rises 8px and fades in 200ms.
- Reduced motion: cursors jump to each target, text appears whole, the loop and idle drift stop, and every end state stays.
- Playback pauses while the card is off screen.

### Responsive behavior

- Fluid up to 680px wide; under 480px the doc padding tightens and the review bar drops "by Claude" to stay on one line.
- Cursor tags flip to the left of the arrow near the right edge, and resting cursors re-anchor when the card resizes.
- Works at 360px with no horizontal scroll; text wraps and the selection and cursor targets are measured from live line boxes.

### Performance

- Cursor positions are motion values, so travel never re-renders React. Streaming re-renders one block per tick.
- Selection and target geometry come from Range.getClientRects on demand, not on every frame.
- Loops, idle drift and timers stop when the card is off screen or unmounted; Stop aborts the run's signal.

### Notes for AI

- Pick this to show an AI agent editing a shared document in place, Notion or Google Docs style, with a review step. For a chat transcript use ai-chat; for a single text diff use a diff view.
- Feed real edits through run (async, abortable) or edits (static). Edits address blocks by id; fix edits need the exact word to replace inside the block text.
- Persist accepted text from onAccept and pass it back as blocks; the doc only resets to blocks when no run is using it.
- Set agent to another provider with its own mark and brand color; the cursor, selection and tint all follow agent.color.

### Related

- [Agent status](https://uiarc.dev/components/agent-status/markdown): A compact live status pill for a running AI agent: the agent's mark in a live ring, the current activity and an elapsed timer, opening into the steps so far.
- [Tool call](https://uiarc.dev/components/tool-call/markdown): A tool call row for agent transcripts: the tool's mark and the call in plain words, a live state while it runs, and the input and output a click away, with approval and retry when needed.
- [Text shimmer](https://uiarc.dev/components/text-shimmer/markdown): Show ongoing work with a calm light across the words.
- [Avatar](https://uiarc.dev/components/avatar/markdown): A compact identity marker for people and accounts.
- [Button](https://uiarc.dev/components/button/markdown): A clear, responsive action with quiet secondary states.

### Also in ai

- [Agent plan](https://uiarc.dev/components/agent-plan/markdown): The plan an agent writes before it acts: edit, reorder or add steps while it is a draft, then watch it work through them as a live checklist.
- [Agent timeline](https://uiarc.dev/components/agent-timeline/markdown): A compact timeline of one orchestrated agent run: the orchestrator and its subagents share a time axis, handoffs draw in between rows, and a playhead replays thinking, tool calls and waiting while the header counts time, tokens and cost. Hover a span for what it did, or click it to trace its handoff path.
- [Context window](https://uiarc.dev/components/context-window/markdown): An AI context window as a grid of 200 cells: the system prompt, tools, files, summary and messages fill it in order, a threshold row marks where compaction starts, and sending a message, attaching a file or compacting shows exactly how much still fits.
- [Reasoning block](https://uiarc.dev/components/reasoning-block/markdown): The collapsible thinking block of an AI reply. While the model thinks, a shimmering label counts the seconds and the latest reasoning streams underneath. When it finishes, it folds to "Thought for 7s" and opens to show the full reasoning as calm steps with headings.
- [Source cards](https://uiarc.dev/components/source-cards/markdown): A row of cited sources under an AI answer where cards stream in with real site marks while the model searches, the overflow collapses into a stack of favicons, hovering lifts a preview with the passage, and an inline [n] citation highlights its card.
- [Model card](https://uiarc.dev/components/model-card/markdown): A model details card where switching models rolls every price, limit and score in place, a token slider estimates monthly cost live, and benchmark bars show each model's rank on hover. Compare crossfades to a side-by-side table against any rival with the better values marked, and the card never changes size.
- [AI workflow](https://uiarc.dev/components/ai-workflow/markdown): A Linear-style AI workflow card where a Gmail trigger, a Claude step, a branch and Slack and Linear actions sit on one hairline rail, and a test run glides down it, opening each step's output inline. Steps are added from a compact command menu with real app marks.
- [Code suggestion](https://uiarc.dev/components/code-suggestion/markdown): An AI code edit suggestion where the model's proposed changes stream into a small editor panel as inline diff hunks, and you accept or reject each one, or all at once with Cmd+Enter. Accepted hunks fold into the file with a smooth height change.
- [Ghost text](https://uiarc.dev/components/ghost-text/markdown): An inline AI autocomplete where muted ghost text continues your sentence exactly at the caret and Tab turns it solid in place. Cmd+Right takes it one word at a time, Escape fades it away, and a calm chip shows the model behind it.
- [Image generation](https://uiarc.dev/components/image-generation/markdown): An image studio where each image forms on a dot matrix: a soft halftone wave breathes across the grid, the dots take the colours of the coming photo and grow into a coloured halftone, then blur away into the sharp photo. One large canvas with a mono size label, a filmstrip of four variations, a prompt bar with model and ratio, and upscale with a sweeping dot band, vary or download, with real provider marks and a built-in simulation.
- [Dictation button](https://uiarc.dev/components/dictation-button/markdown): A chat composer with voice input, where the mic springs into a recording pill with a smooth live waveform, a timer, and cancel and insert buttons. Words stream into the field as you speak, muted until the recognizer settles them.
- [Speech player](https://uiarc.dev/components/speech-player/markdown): A read-aloud player for AI replies. The Read aloud button in the message's action row turns into a compact player with play, a scrubbable progress bar, speed and a voice picker, and a highlight follows the spoken word through the reply, karaoke style.
- [Meeting summary](https://uiarc.dev/components/meeting-summary/markdown): An AI meeting notes card: the header shows the Google Meet or Zoom mark, the attendees and the duration. Summary, Decisions and Action items stream in after a short summarizing pass. Hover any line to see the transcript quote it came from, then check off action items or send them to Linear or Notion.
- [Reply draft](https://uiarc.dev/components/reply-draft/markdown): An AI email reply drafter where Claude streams a reply under a received Gmail message. Quick replies steer a fresh draft, tone and length rewrite it with a single crossfade, and you can edit the finished draft before you insert it.
- [Agent handoff](https://uiarc.dev/components/agent-handoff/markdown): A support conversation where an AI assistant hands off to a person. When it transfers, a card shows the summary it passes to the team and the typical wait. The person then joins and takes over, and a thin timeline on the left marks each step.
- [PII redaction](https://uiarc.dev/components/pii-redaction/markdown): A guardrail card where personal data is redacted before the prompt reaches the model. Scan marks each name, email, phone number and card with its type and swaps it for a placeholder like [EMAIL_1]. The safe prompt travels to Claude, and the reply comes back with the original values put back for the person.
- [Response feedback](https://uiarc.dev/components/response-feedback/markdown): A feedback control for AI replies where thumbs down opens an inline panel with reason chips and an optional note, thumbs up fills and asks what was good, and a submit shows a short thank-you before folding back into the row.
- [LLM cost calculator](https://uiarc.dev/components/llm-cost-calculator/markdown): A pricing calculator for LLM workloads. Set tokens per request, requests per day and prompt caching, and eight current models re-rank by monthly cost. Bars glide and prices roll as you drag.
- [Provider keys](https://uiarc.dev/components/provider-keys/markdown): A settings card for bring-your-own-key AI products. Each provider row shows its real mark, the masked key, a status and when the key was last used. You can reveal a key for five seconds, copy, rotate or remove it with undo. Adding or rotating a key opens an inline form that checks the format as you type, then tests the connection before saving.
- [Generation stats](https://uiarc.dev/components/generation-stats/markdown): A live stats strip for a streaming LLM response where time to first token, speed with a sparkline, output tokens and cost count up in tabular numerals beside the model's real mark, then settle and open into a latency and token cost breakdown.
- [AI translate](https://uiarc.dev/components/ai-translate/markdown): A message card where picking a language streams the AI translation in place, sentence by sentence over the dimmed original, with a detected-language chip, a Show original toggle and a status line credited to the model's mark.
- [TL;DR toggle](https://uiarc.dev/components/tldr-toggle/markdown): An article card with a Full, Summary and Key points switch and a length slider. Switching streams an AI summary in place of the article as the card's height springs to fit, and each key point links back to the paragraph it came from, which gets scrolled to and highlighted.
- [Connector setup](https://uiarc.dev/components/connector-setup/markdown): A "Connect your tools" card for an AI assistant. Each app connects inline: it redirects, authorizes and runs a first sync with a progress hairline, then lists the scopes it was granted and offers Disconnect with an inline confirm.
- [Smart form fill](https://uiarc.dev/components/smart-form-fill/markdown): A paste-to-fill form card where AI reads an email signature or messy notes and fills a contact field by field. Each value flashes in with a confidence dot, its source lights up in the pasted text, low-confidence guesses ask for review, and Undo puts the old values back.
- [Enrich column](https://uiarc.dev/components/enrich-column/markdown): An AI enrichment column for a data table, where one prompt runs down every row and each cell shimmers while it works, then settles into a value with its source or a failure you can retry.
- [Ticket router](https://uiarc.dev/components/ticket-router/markdown): A support ticket router where messages from Gmail, Intercom, Slack and Zendesk come in one at a time. An AI classifier labels each one with intent, sentiment and confidence, and the ticket moves into a team lane with an assignee. Low confidence tickets wait in a review lane, and one click there routes them to the suggested team.
- [Ask your data](https://uiarc.dev/components/ask-your-data/markdown): A natural language to chart card: you ask a question, PostgreSQL streams into a collapsible, syntax highlighted panel, the query runs with a rolling row count, and the answer builds as stacked bars, lines or a table, with a one line insight streamed in underneath.
- [Provider status](https://uiarc.dev/components/provider-status/markdown): A status card for the AI providers your product depends on. Each row shows the provider's real mark, its health as an icon and label, p50 latency and a 30-day uptime bar with a tooltip for each day. An incident row expands into its timeline of updates, and the card checks again on a visible countdown.
- [Training run](https://uiarc.dev/components/training-run/markdown): A fine-tuning job card where a live train and validation loss curve draws across a fixed step axis that doubles as the epoch progress bar. It shows the learning rate, elapsed time, ETA and the latest evals and checkpoints, has Pause and Cancel while it runs, and ends in results with a Deploy button.
- [AI command](https://uiarc.dev/components/ai-command/markdown): A Cmd+K command palette with an AI mode. Search pages and actions, or press Tab to ask a question: the answer streams inside the palette with numbered sources, and the next steps it suggests, like filing a Linear issue or opening a Notion doc, run straight from the list.
- [Starter prompts](https://uiarc.dev/components/starter-prompts/markdown): A greeting and a grid of starter cards for the empty state of an AI app. The cards are grouped into Write, Code, Analyze and Plan tabs, and a shuffle swaps them with a short staggered crossfade. Picking a card fills the composer, and cards that use a connected app show its mark (Gmail, GitHub, Notion, Linear, Google Calendar).
- [AI mascot](https://uiarc.dev/components/ai-mascot/markdown): A small assistant character, a soft pebble with pill eyes and a companion dot, that shows what the AI is doing. It breathes and glances when idle, leans in to listen, looks up while the dot orbits its head, reads along the line it writes, squints with a sparkle when done and shakes once with worried brows on an error.
- [Image reveal](https://uiarc.dev/components/image-reveal/markdown): An image generation canvas where a soft, blurred preview made from the image's own colors sharpens top to bottom behind a soft-edged band. It works the way ChatGPT, Midjourney and Gemini show images forming, with fine film grain, a translucent progress pill and calm queued and error states.
- [AI spark](https://uiarc.dev/components/ai-spark/markdown): A brand-quality animated spark mark. Four tapered rays and four lighter diagonals breathe at rest, ripple while thinking, pulse like a heartbeat while writing, then gather and settle when done. Every status change blends from the pose the mark is already in.
- [Pixel mascot](https://uiarc.dev/components/pixel-mascot/markdown): A pixel-art robot that shows what an AI assistant is doing. It idles, thinks, types, celebrates and errors in frame-stepped sprite animations, and stays crisp at every integer size from 24px to 192px.
- [Ghost mascot](https://uiarc.dev/components/ghost-mascot/markdown): A floating ghost mascot whose soft sheet ripples at the hem while it hovers. It blinks when idle, turns toward you to listen, fades a little translucent while thinking, draws a tiny pen line while writing, smiles with a sparkle when done and wobbles once on an error.
- [Cube mascot](https://uiarc.dev/components/cube-mascot/markdown): An isometric cube mascot where three shaded faces and a painted-on face show what the assistant is doing. It turns a quarter turn in eased steps while thinking, prints lines onto the floor while writing, settles with a sparkle when done, and shakes once on error.
- [Tone tuner](https://uiarc.dev/components/tone-tuner/markdown): A brand voice card where two sliders (formality and detail) and Friendly, Confident and Empathetic chips rewrite a customer reply. Each changed sentence crossfades in place, new words can be highlighted against the original, and Copy takes the current version.
- [Upgrade prompt](https://uiarc.dev/components/upgrade-prompt/markdown): An upgrade nudge for the moment someone hits a limit. It shows a usage meter at 50 of 50 AI credits, a rolling price with a monthly and yearly toggle, three concrete unlocks with real model marks, and Upgrade or Maybe later. Upgrading leads into a success state with the new limits, and the card never changes size between states.
- [Referral card](https://uiarc.dev/components/referral-card/markdown): A give-and-get referral card where people copy or share their invite link, invite friends by email as chips, and watch invites move from invited to signed up to earned, with the credit total counting up and a milestone reward unlocking.
- [Trial banner](https://uiarc.dev/components/trial-banner/markdown): A trial status banner where a ring counts down the days left, the copy names what the workspace loses, and the upgrade path is one click away. It comes as a slim banner, a sidebar card or a header pill. It shifts to a warning tone in the last days, has expired and upgraded states, and folds into the pill when dismissed or snoozed.
- [Team switcher](https://uiarc.dev/components/team-switcher/markdown): A workspace switcher like Linear, Vercel or Slack. The trigger shows the current workspace's logo and plan. The menu has search, your role in each workspace and a Cmd+1 to 9 shortcut for each, and lets you create or join a workspace inline. A highlight glides between rows, and switching crossfades the trigger through a short loading state.
- [Live visitors](https://uiarc.dev/components/live-visitors/markdown): A realtime visitors card where the live count rolls digit by digit, new arrivals ping in on a dotted world map, the top pages reorder with bars, and signups and upgrades tick in with country flags.
- [Social proof toast](https://uiarc.dev/components/social-proof-toast/markdown): A stack of social proof notifications for landing and pricing pages, where recent trials, upgrades and verified purchases from people and companies arrive every few seconds. The stack pauses and fans out on hover, and visitors can dismiss any toast.
- [Install snippet](https://uiarc.dev/components/install-snippet/markdown): A "get started in 30 seconds" card where framework tabs, three numbered steps and highlighted snippets take a developer from install to first event. Generate key wipes a fresh API key into the placeholder in place.

### Guidance for AI tools

Agent cursor: A live document where Claude edits like a collaborator. Its labeled cursor comes out of its avatar, selects a paragraph and streams in a rewrite, adds a heading and fixes a typo, while a teammate's cursor reads along. Changes stay tinted until someone accepts or undoes them from a floating review bar. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Provider status

> A status card for the AI providers your product depends on. Each row shows the provider's real mark, its health as an icon and label, p50 latency and a 30-day uptime bar with a tooltip for each day. An incident row expands into its timeline of updates, and the card checks again on a visible countdown.

- Type: Component (special)
- Access: Arc Pro
- Page: https://uiarc.dev/components/provider-status
- Markdown: https://uiarc.dev/components/provider-status/markdown
- Source file: `registry/components/provider-status/provider-status.tsx`
- Dependencies: motion, lucide-react
- Keywords: special, ai, new, provider status, ai status, llm uptime, status page, incident, uptime bar, latency, health check, openai status, anthropic status, model provider, monitoring

### When to use

- Showing the live health, latency and recent uptime of the model providers your product routes to.
- Explaining degraded AI features to users or admins with the provider's incident updates in place.
- A routing or fallback settings page where people need to see which providers are healthy right now.

### When not to use

- A full public status page with components, subscriptions and history: build a page, not a card.
- A single provider's state inside a chat header: use agent-status or a small badge.
- Detailed latency charts over time: use a chart component.

### Installation

Provider status is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/provider-status
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { ProviderStatus } from "@/components/arc/provider-status/provider-status";
import { AnthropicMark, OpenaiMark } from "@/components/arc/provider-status/provider-status";

export function Health() {
  const [providers, setProviders] = useState<ProviderStatusItem[]>(initial);
  return (
    <ProviderStatus
      providers={providers}
      refreshInterval={60_000}
      onRefresh={async signal => {
        const res = await fetch("/api/provider-status", { signal });
        if (!res.ok) throw new Error("Couldn’t reach the status feeds. Showing the last results.");
        return (await res.json()) as ProviderStatusItem[];
      }}
      onOpenIncident={(provider, incident) => window.open(incident.url, "_blank")}
      footnote="Latency is the median over the last 5 minutes."
    />
  );
}
```

### API reference

#### ProviderStatus

A status card for the AI providers a product depends on. Each row shows the provider's real mark, its health as an icon and label (Operational, Degraded, Outage), median latency in tabular numerals and a 30 day uptime bar of small ticks with a tooltip per day. A row with an incident expands into its updates (Investigating, Identified, Monitoring, Resolved), newest first, and new updates grow the panel smoothly. The header sums up health across providers and checks again on a visible countdown ring, with a refresh button, a Checking state and an error state that keeps the last results. Narrow cards switch to two lines per row. With no props it plays a sample story on simulated checks: an OpenAI outage and a Gemini slowdown resolve, Mistral has a short incident, and one check fails to show the error state.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `providers` | `ProviderStatusItem[]` | – | The providers to show. Each has id, name, mark (a 16px ReactNode), detail (a short line such as the models you call), status ("operational" \| "degraded" \| "outage"), latencyMs, days and incident. Leave it out to play the built in sample. |
| `providers[].days` | `ProviderDay[]` | – | Daily history, oldest first; the bar shows the last 30 and pads missing days as No data. Each day has date ("YYYY-MM-DD"), uptime (0 to 100, or null), an optional status (derived from uptime when left out: below 99.9 degraded, below 99 outage) and an optional note for the tooltip. The last day is labeled Today. |
| `providers[].incident` | `{ id: string; title: string; updates: IncidentUpdate[]; url?: string }` | – | An open or just resolved incident. Its row becomes a button that expands the updates. Each update has stage ("investigating" \| "identified" \| "monitoring" \| "resolved"), at (a Date, a timestamp shown as HH:MM UTC, or a preformatted string) and message. |
| `onRefresh` | `(signal: AbortSignal) => Promise<ProviderStatusItem[] \| void>` | – | Fetches fresh status on the countdown and on the refresh button. Return the new providers, or update the providers prop yourself and return nothing. Throw to show the error state; the last results stay on screen and the countdown turns into a retry. A newer check aborts the older one through the signal. Without it the refresh controls are hidden. |
| `refreshInterval` | `number \| null` | `30000` | Milliseconds between automatic checks. The countdown pauses while the card is off screen or the tab is hidden. Retries after an error wait at most 10 seconds. Null turns auto refresh off and keeps the refresh button. The sample uses 8000. |
| `loading` | `boolean` | `false` | Shows skeleton rows with the same row height, for the first load. |
| `error` | `string \| null` | – | An error to show in the header, such as a failed first load. Errors thrown by onRefresh show on their own. |
| `title` | `string` | `"AI providers"` | Card title. |
| `expandedId` | `string \| null` | – | Which provider's incident is open. Pair with onExpandedChange. |
| `defaultExpandedId` | `string \| null` | `null` | The incident open on first render when uncontrolled. |
| `onExpandedChange` | `(id: string \| null) => void` | – | Called when an incident row is opened or closed. |
| `onOpenIncident` | `(provider: ProviderStatusItem, incident: ProviderIncident) => void` | – | Called by the Status page link in an open incident. Without it, the link opens incident.url in a new tab; with neither, the link is hidden. |
| `footnote` | `ReactNode` | – | A quiet line under the list, such as how latency and uptime are measured. The sample shows a sample data note. |
| `notice` | `string` | – | A one-off message for screen readers, such as the result of an action. |
| `className` | `string` | – | Class on the root element. |

#### sampleProviders

The sample data behind the preview, exported for prototypes and tests: sampleProviders(check) returns six providers (Anthropic, OpenAI, Google Gemini, Mistral AI, xAI, Amazon Bedrock) after a number of simulated checks. Every number is a plausible sample, not a measurement.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `check` | `number` | – | How many simulated checks have run. The story loops every 11 checks. |

#### AnthropicMark, OpenaiMark, GeminiColorMark, MistralColorMark, XaiMark, AwsMark

The provider marks used by the sample, from Simple Icons (CC0) and Lobe Icons (MIT). Mono marks draw with currentColor; Gemini and Mistral keep their brand fills.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` | `string` | – | Accessible name of the mark. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Tab | Moves to the refresh button, each incident row and each uptime bar. |
| Enter / Space | On an incident row, opens or closes its updates. |
| Arrow Left / Arrow Right | On an uptime bar, moves the day tooltip one day back or forward. |
| Home / End | On an uptime bar, jumps to the oldest day or today. |
| Escape | On an uptime bar, hides the day tooltip. |

### Accessibility

- The card is a labelled section. Rows are a list; an incident row has a full-row button with aria-expanded and aria-controls, named with the provider, its health and the incident title.
- Health is never color alone: every status shows an icon and a label, and day ticks carry their health in the tooltip and in the bar's label.
- Each uptime bar is one tab stop with a label that sums up the 30 days. Arrow keys move through the days and a polite live region reads each one, so 180 ticks never flood the tab order.
- A polite live region announces checks, refresh errors and simulated actions ("Simulated, no requests were sent").
- Focus rings come from the shared :focus-visible styles; the row button's ring sits just inside the row.

### Motion

- Health labels, latency, uptime and the summary change with a single crossfade (out in 100ms, in over 160ms with a 2px rise) inside a reserved grid cell, so nothing reflows.
- The incident panel springs to its measured height with no bounce (visual duration 240ms); new updates fade in while the panel grows.
- Ticks change color over 240ms. The countdown ring is a linear CSS drain that pauses with the countdown off screen; Checking swaps it for a short spinner and a shimmer label.
- Reduced motion keeps every end state and drops the rise, the height spring, the spinner and the skeleton pulse.

### Responsive behavior

- From 560px wide each row is one line with columns for status, p50 latency, the uptime bar and the 30 day percentage.
- Below 560px (a container query, so it follows the card, not the window) rows take two lines: name and status above, a full width uptime bar and percentage below, with latency under the name.
- Holds up at 360px with no horizontal scroll; long names and details truncate with an ellipsis.
- Touch: tapping a tick shows its day, dragging sideways scrubs, and vertical scrolling still works.

### Performance

- One shared tooltip for the whole card, positioned on demand, instead of one per tick.
- The countdown re-renders once per second at most; the ring animates in CSS. Both pause off screen and in background tabs.
- Refreshes are abortable and never overlap.

### Notes for AI

- Use it for a provider health view in an AI product: a settings page, an admin dashboard tile or a status popover. Wire onRefresh to your own aggregation endpoint; do not poll provider status pages from the browser.
- Pass real marks at 16px. Mono marks should use currentColor so they follow the theme.
- Keep latency and uptime as plain numbers; the component formats them (412 ms, 1.92 s, 99.61%).
- Label sample or synthetic numbers with the footnote prop.

### Related

- [Agent status](https://uiarc.dev/components/agent-status/markdown): A compact live status pill for a running AI agent: the agent's mark in a live ring, the current activity and an elapsed timer, opening into the steps so far.
- [Tool call](https://uiarc.dev/components/tool-call/markdown): A tool call row for agent transcripts: the tool's mark and the call in plain words, a live state while it runs, and the input and output a click away, with approval and retry when needed.
- [Tooltip](https://uiarc.dev/components/tooltip/markdown): Short supporting text for unfamiliar controls.
- [Text shimmer](https://uiarc.dev/components/text-shimmer/markdown): Show ongoing work with a calm light across the words.
- [Button](https://uiarc.dev/components/button/markdown): A clear, responsive action with quiet secondary states.

### Also in ai

- [Agent plan](https://uiarc.dev/components/agent-plan/markdown): The plan an agent writes before it acts: edit, reorder or add steps while it is a draft, then watch it work through them as a live checklist.
- [Agent timeline](https://uiarc.dev/components/agent-timeline/markdown): A compact timeline of one orchestrated agent run: the orchestrator and its subagents share a time axis, handoffs draw in between rows, and a playhead replays thinking, tool calls and waiting while the header counts time, tokens and cost. Hover a span for what it did, or click it to trace its handoff path.
- [Context window](https://uiarc.dev/components/context-window/markdown): An AI context window as a grid of 200 cells: the system prompt, tools, files, summary and messages fill it in order, a threshold row marks where compaction starts, and sending a message, attaching a file or compacting shows exactly how much still fits.
- [Reasoning block](https://uiarc.dev/components/reasoning-block/markdown): The collapsible thinking block of an AI reply. While the model thinks, a shimmering label counts the seconds and the latest reasoning streams underneath. When it finishes, it folds to "Thought for 7s" and opens to show the full reasoning as calm steps with headings.
- [Source cards](https://uiarc.dev/components/source-cards/markdown): A row of cited sources under an AI answer where cards stream in with real site marks while the model searches, the overflow collapses into a stack of favicons, hovering lifts a preview with the passage, and an inline [n] citation highlights its card.
- [Model card](https://uiarc.dev/components/model-card/markdown): A model details card where switching models rolls every price, limit and score in place, a token slider estimates monthly cost live, and benchmark bars show each model's rank on hover. Compare crossfades to a side-by-side table against any rival with the better values marked, and the card never changes size.
- [AI workflow](https://uiarc.dev/components/ai-workflow/markdown): A Linear-style AI workflow card where a Gmail trigger, a Claude step, a branch and Slack and Linear actions sit on one hairline rail, and a test run glides down it, opening each step's output inline. Steps are added from a compact command menu with real app marks.
- [Code suggestion](https://uiarc.dev/components/code-suggestion/markdown): An AI code edit suggestion where the model's proposed changes stream into a small editor panel as inline diff hunks, and you accept or reject each one, or all at once with Cmd+Enter. Accepted hunks fold into the file with a smooth height change.
- [Ghost text](https://uiarc.dev/components/ghost-text/markdown): An inline AI autocomplete where muted ghost text continues your sentence exactly at the caret and Tab turns it solid in place. Cmd+Right takes it one word at a time, Escape fades it away, and a calm chip shows the model behind it.
- [Image generation](https://uiarc.dev/components/image-generation/markdown): An image studio where each image forms on a dot matrix: a soft halftone wave breathes across the grid, the dots take the colours of the coming photo and grow into a coloured halftone, then blur away into the sharp photo. One large canvas with a mono size label, a filmstrip of four variations, a prompt bar with model and ratio, and upscale with a sweeping dot band, vary or download, with real provider marks and a built-in simulation.
- [Dictation button](https://uiarc.dev/components/dictation-button/markdown): A chat composer with voice input, where the mic springs into a recording pill with a smooth live waveform, a timer, and cancel and insert buttons. Words stream into the field as you speak, muted until the recognizer settles them.
- [Speech player](https://uiarc.dev/components/speech-player/markdown): A read-aloud player for AI replies. The Read aloud button in the message's action row turns into a compact player with play, a scrubbable progress bar, speed and a voice picker, and a highlight follows the spoken word through the reply, karaoke style.
- [Meeting summary](https://uiarc.dev/components/meeting-summary/markdown): An AI meeting notes card: the header shows the Google Meet or Zoom mark, the attendees and the duration. Summary, Decisions and Action items stream in after a short summarizing pass. Hover any line to see the transcript quote it came from, then check off action items or send them to Linear or Notion.
- [Reply draft](https://uiarc.dev/components/reply-draft/markdown): An AI email reply drafter where Claude streams a reply under a received Gmail message. Quick replies steer a fresh draft, tone and length rewrite it with a single crossfade, and you can edit the finished draft before you insert it.
- [Agent handoff](https://uiarc.dev/components/agent-handoff/markdown): A support conversation where an AI assistant hands off to a person. When it transfers, a card shows the summary it passes to the team and the typical wait. The person then joins and takes over, and a thin timeline on the left marks each step.
- [PII redaction](https://uiarc.dev/components/pii-redaction/markdown): A guardrail card where personal data is redacted before the prompt reaches the model. Scan marks each name, email, phone number and card with its type and swaps it for a placeholder like [EMAIL_1]. The safe prompt travels to Claude, and the reply comes back with the original values put back for the person.
- [Response feedback](https://uiarc.dev/components/response-feedback/markdown): A feedback control for AI replies where thumbs down opens an inline panel with reason chips and an optional note, thumbs up fills and asks what was good, and a submit shows a short thank-you before folding back into the row.
- [LLM cost calculator](https://uiarc.dev/components/llm-cost-calculator/markdown): A pricing calculator for LLM workloads. Set tokens per request, requests per day and prompt caching, and eight current models re-rank by monthly cost. Bars glide and prices roll as you drag.
- [Provider keys](https://uiarc.dev/components/provider-keys/markdown): A settings card for bring-your-own-key AI products. Each provider row shows its real mark, the masked key, a status and when the key was last used. You can reveal a key for five seconds, copy, rotate or remove it with undo. Adding or rotating a key opens an inline form that checks the format as you type, then tests the connection before saving.
- [Generation stats](https://uiarc.dev/components/generation-stats/markdown): A live stats strip for a streaming LLM response where time to first token, speed with a sparkline, output tokens and cost count up in tabular numerals beside the model's real mark, then settle and open into a latency and token cost breakdown.
- [AI translate](https://uiarc.dev/components/ai-translate/markdown): A message card where picking a language streams the AI translation in place, sentence by sentence over the dimmed original, with a detected-language chip, a Show original toggle and a status line credited to the model's mark.
- [TL;DR toggle](https://uiarc.dev/components/tldr-toggle/markdown): An article card with a Full, Summary and Key points switch and a length slider. Switching streams an AI summary in place of the article as the card's height springs to fit, and each key point links back to the paragraph it came from, which gets scrolled to and highlighted.
- [Connector setup](https://uiarc.dev/components/connector-setup/markdown): A "Connect your tools" card for an AI assistant. Each app connects inline: it redirects, authorizes and runs a first sync with a progress hairline, then lists the scopes it was granted and offers Disconnect with an inline confirm.
- [Smart form fill](https://uiarc.dev/components/smart-form-fill/markdown): A paste-to-fill form card where AI reads an email signature or messy notes and fills a contact field by field. Each value flashes in with a confidence dot, its source lights up in the pasted text, low-confidence guesses ask for review, and Undo puts the old values back.
- [Enrich column](https://uiarc.dev/components/enrich-column/markdown): An AI enrichment column for a data table, where one prompt runs down every row and each cell shimmers while it works, then settles into a value with its source or a failure you can retry.
- [Ticket router](https://uiarc.dev/components/ticket-router/markdown): A support ticket router where messages from Gmail, Intercom, Slack and Zendesk come in one at a time. An AI classifier labels each one with intent, sentiment and confidence, and the ticket moves into a team lane with an assignee. Low confidence tickets wait in a review lane, and one click there routes them to the suggested team.
- [Ask your data](https://uiarc.dev/components/ask-your-data/markdown): A natural language to chart card: you ask a question, PostgreSQL streams into a collapsible, syntax highlighted panel, the query runs with a rolling row count, and the answer builds as stacked bars, lines or a table, with a one line insight streamed in underneath.
- [Agent cursor](https://uiarc.dev/components/agent-cursor/markdown): A live document where Claude edits like a collaborator. Its labeled cursor comes out of its avatar, selects a paragraph and streams in a rewrite, adds a heading and fixes a typo, while a teammate's cursor reads along. Changes stay tinted until someone accepts or undoes them from a floating review bar.
- [Training run](https://uiarc.dev/components/training-run/markdown): A fine-tuning job card where a live train and validation loss curve draws across a fixed step axis that doubles as the epoch progress bar. It shows the learning rate, elapsed time, ETA and the latest evals and checkpoints, has Pause and Cancel while it runs, and ends in results with a Deploy button.
- [AI command](https://uiarc.dev/components/ai-command/markdown): A Cmd+K command palette with an AI mode. Search pages and actions, or press Tab to ask a question: the answer streams inside the palette with numbered sources, and the next steps it suggests, like filing a Linear issue or opening a Notion doc, run straight from the list.
- [Starter prompts](https://uiarc.dev/components/starter-prompts/markdown): A greeting and a grid of starter cards for the empty state of an AI app. The cards are grouped into Write, Code, Analyze and Plan tabs, and a shuffle swaps them with a short staggered crossfade. Picking a card fills the composer, and cards that use a connected app show its mark (Gmail, GitHub, Notion, Linear, Google Calendar).
- [AI mascot](https://uiarc.dev/components/ai-mascot/markdown): A small assistant character, a soft pebble with pill eyes and a companion dot, that shows what the AI is doing. It breathes and glances when idle, leans in to listen, looks up while the dot orbits its head, reads along the line it writes, squints with a sparkle when done and shakes once with worried brows on an error.
- [Image reveal](https://uiarc.dev/components/image-reveal/markdown): An image generation canvas where a soft, blurred preview made from the image's own colors sharpens top to bottom behind a soft-edged band. It works the way ChatGPT, Midjourney and Gemini show images forming, with fine film grain, a translucent progress pill and calm queued and error states.
- [AI spark](https://uiarc.dev/components/ai-spark/markdown): A brand-quality animated spark mark. Four tapered rays and four lighter diagonals breathe at rest, ripple while thinking, pulse like a heartbeat while writing, then gather and settle when done. Every status change blends from the pose the mark is already in.
- [Pixel mascot](https://uiarc.dev/components/pixel-mascot/markdown): A pixel-art robot that shows what an AI assistant is doing. It idles, thinks, types, celebrates and errors in frame-stepped sprite animations, and stays crisp at every integer size from 24px to 192px.
- [Ghost mascot](https://uiarc.dev/components/ghost-mascot/markdown): A floating ghost mascot whose soft sheet ripples at the hem while it hovers. It blinks when idle, turns toward you to listen, fades a little translucent while thinking, draws a tiny pen line while writing, smiles with a sparkle when done and wobbles once on an error.
- [Cube mascot](https://uiarc.dev/components/cube-mascot/markdown): An isometric cube mascot where three shaded faces and a painted-on face show what the assistant is doing. It turns a quarter turn in eased steps while thinking, prints lines onto the floor while writing, settles with a sparkle when done, and shakes once on error.
- [Tone tuner](https://uiarc.dev/components/tone-tuner/markdown): A brand voice card where two sliders (formality and detail) and Friendly, Confident and Empathetic chips rewrite a customer reply. Each changed sentence crossfades in place, new words can be highlighted against the original, and Copy takes the current version.
- [Upgrade prompt](https://uiarc.dev/components/upgrade-prompt/markdown): An upgrade nudge for the moment someone hits a limit. It shows a usage meter at 50 of 50 AI credits, a rolling price with a monthly and yearly toggle, three concrete unlocks with real model marks, and Upgrade or Maybe later. Upgrading leads into a success state with the new limits, and the card never changes size between states.
- [Referral card](https://uiarc.dev/components/referral-card/markdown): A give-and-get referral card where people copy or share their invite link, invite friends by email as chips, and watch invites move from invited to signed up to earned, with the credit total counting up and a milestone reward unlocking.
- [Trial banner](https://uiarc.dev/components/trial-banner/markdown): A trial status banner where a ring counts down the days left, the copy names what the workspace loses, and the upgrade path is one click away. It comes as a slim banner, a sidebar card or a header pill. It shifts to a warning tone in the last days, has expired and upgraded states, and folds into the pill when dismissed or snoozed.
- [Team switcher](https://uiarc.dev/components/team-switcher/markdown): A workspace switcher like Linear, Vercel or Slack. The trigger shows the current workspace's logo and plan. The menu has search, your role in each workspace and a Cmd+1 to 9 shortcut for each, and lets you create or join a workspace inline. A highlight glides between rows, and switching crossfades the trigger through a short loading state.
- [Live visitors](https://uiarc.dev/components/live-visitors/markdown): A realtime visitors card where the live count rolls digit by digit, new arrivals ping in on a dotted world map, the top pages reorder with bars, and signups and upgrades tick in with country flags.
- [Social proof toast](https://uiarc.dev/components/social-proof-toast/markdown): A stack of social proof notifications for landing and pricing pages, where recent trials, upgrades and verified purchases from people and companies arrive every few seconds. The stack pauses and fans out on hover, and visitors can dismiss any toast.
- [Install snippet](https://uiarc.dev/components/install-snippet/markdown): A "get started in 30 seconds" card where framework tabs, three numbered steps and highlighted snippets take a developer from install to first event. Generate key wipes a fresh API key into the placeholder in place.

### Guidance for AI tools

Provider status: A status card for the AI providers your product depends on. Each row shows the provider's real mark, its health as an icon and label, p50 latency and a 30-day uptime bar with a tooltip for each day. An incident row expands into its timeline of updates, and the card checks again on a visible countdown. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Training run

> A fine-tuning job card where a live train and validation loss curve draws across a fixed step axis that doubles as the epoch progress bar. It shows the learning rate, elapsed time, ETA and the latest evals and checkpoints, has Pause and Cancel while it runs, and ends in results with a Deploy button.

- Type: Component (special)
- Access: Arc Pro
- Page: https://uiarc.dev/components/training-run
- Markdown: https://uiarc.dev/components/training-run/markdown
- Source file: `registry/components/training-run/training-run.tsx`
- Dependencies: motion, lucide-react
- Keywords: special, ai, new, fine-tuning, training run, loss curve, lora, epochs, checkpoint, eval, learning rate, eta, deploy model, ml job, qwen, hugging face

### When to use

- A fine-tuning or training job page in an AI platform, where people watch loss, pause, cancel and deploy.
- An eval or distillation run that reports a loss curve, checkpoints and a final score.
- A product onboarding step that trains a custom model on the customer's data and ends in a deploy.

### When not to use

- A generic multi-series chart with no job lifecycle: use line-chart.
- A short agent task with steps rather than a loss curve: use agent-status.
- Explaining how training works conceptually: use model-training.

### Installation

Training run is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/training-run
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { TrainingRun, QwenColorMark, HuggingFaceMark } from "@/components/arc/training-run/training-run";

export function FineTuneJob({ job }: { job: Job }) {
  return (
    <TrainingRun
      status={job.status}
      name={job.outputName}
      model={{ name: "Qwen3.8 Max", mark: <QwenColorMark /> }}
      details={["LoRA r16", "8× H200"]}
      dataset={{ name: "arcwork/support-tickets-oct", examples: 48210, mark: <HuggingFaceMark /> }}
      step={job.step}
      totalSteps={job.totalSteps}
      epochs={job.epochs}
      loss={job.loss}
      learningRate={job.learningRate}
      elapsed={job.elapsedSeconds}
      eta={job.etaSeconds}
      events={job.events}
      error={job.error}
      onPause={() => api.pause(job.id)}
      onResume={() => api.resume(job.id)}
      onCancel={() => api.cancel(job.id)}
      onRetry={() => api.retry(job.id)}
      onDeploy={signal => api.deploy(job.id, { signal })}
    />
  );
}
```

### API reference

#### TrainingRun

A fine-tuning job card with a live train and validation loss curve, epoch progress, learning rate, elapsed time and ETA, recent events, pause and cancel, and results with a Deploy button once the run completes. With no props it plays a simulated LoRA run of Qwen3.8 Max.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `status` | `"queued" \| "running" \| "paused" \| "completed" \| "failed" \| "cancelled"` | – | Where the job is. Running with no loss samples reads as starting up. Leave it out to play the built in simulation. |
| `name` | `string` | `"Fine-tuning job"` | The job or output model name. |
| `model` | `{ name: string; mark?: ReactNode }` | `Qwen3.8 Max with its mark` | The base model. The mark renders at 24px; color marks keep brand fills, mono marks use currentColor. |
| `details` | `string[]` | `[]` | Short facts after the model name, such as ["LoRA r16", "8× H200"]. |
| `dataset` | `{ name: string; examples?: number; mark?: ReactNode }` | – | The training data, shown in the footer with an optional 14px mark (Hugging Face in the demo). |
| `step` | `number` | `0` | Optimizer steps done. |
| `totalSteps` | `number` | `1` | Steps in the whole run. Fixes the x axis so the curve never rescales mid-run. |
| `epochs` | `number` | `1` | Number of epochs. The axis splits into one band and one progress segment per epoch. |
| `loss` | `{ step: number; train?: number; val?: number }[]` | `[]` | Loss samples, oldest first. Train is drawn raw (faint) and smoothed; validation joins its own samples. The line eases toward each new point. |
| `learningRate` | `number` | – | The current learning rate, shown as 1.84e-4. |
| `elapsed` | `number` | – | Seconds of training so far, excluding pauses. |
| `eta` | `number` | – | Estimated seconds left. While queued it reads as About 18m 40s. |
| `events` | `{ id: string; kind: TrainingEventKind; label: string; step?: number }[]` | `[]` | The event log, oldest first. The newest three show; kinds are start, checkpoint, eval, epoch, info, warning, error and done. |
| `metrics` | `{ label: string; value: string; hint?: string }[]` | – | Up to four results that replace the live stats on completion. Defaults to final train loss, validation loss, steps and duration. |
| `activity` | `string` | – | A line over the empty chart while queued or starting, such as Waiting for 8× H200 · 2nd in queue. |
| `error` | `string` | – | Why the run failed, shown in the footer in place of the dataset. |
| `onPause` | `() => void` | – | Shows Pause while running. |
| `onResume` | `() => void` | – | Shows Resume while paused. |
| `onCancel` | `() => void` | – | Shows Cancel while queued, running or paused. Called after a second press on Confirm cancel within 3 seconds. |
| `onRetry` | `() => void` | – | Shows Retry from checkpoint when the run failed. |
| `onRestart` | `() => void` | – | Shows Run again after a run completes, fails or is cancelled. |
| `onDeploy` | `(signal: AbortSignal) => Promise<{ endpoint?: string } \| void>` | – | Shows Deploy on completion. The button loads while the promise runs, then the footer shows the endpoint with a copy button; a rejection shows its message and Retry deploy. Aborted if the card unmounts or the run leaves completed. |
| `notice` | `string` | – | A one-off message for screen readers, such as the result of an action. |
| `scenario` | `"healthy" \| "oom"` | `"healthy"` | Demo only, when status is left out: oom fails once at step 940 so the retry path can be seen. |
| `className` | `string` | – | Extra class on the card. |

#### useTrainingRunSimulation

The hook behind the demo. Returns every TrainingRun prop for a simulated run, so you can prototype against it before wiring a real job API.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `scenario` | `"healthy" \| "oom"` | `"healthy"` | Which simulated run to play. |
| `active` | `boolean` | `true` | Freezes the simulation while false, for example when the card is off screen. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Tab | Moves through the loss chart and the footer actions. |
| Left / Right | On the focused chart, steps through samples; the legend shows that step's train and validation loss. |
| Shift + Left / Right | Jumps ten samples. |
| Home / End | Jumps to the first or latest sample. |
| Escape | Clears the inspected step. |
| Enter / Space | Activates the focused action. Cancel needs a second press on Confirm cancel. |

### Accessibility

- A polite live region announces status changes (Queued, Training, Paused, Completed, Failed, Deployed) and any notice, never every step.
- Status is an icon plus a label, never color alone; the failure reason is text in the footer and in the event log.
- The chart is a labelled group whose name carries the current step and both losses; the arrow keys inspect samples and the legend reads them out visually.
- Cancel is a two step action so a stray press never stops a long run. Deploy keeps focus while loading.
- Stats are a description list; event steps and numbers use tabular numerals.

### Motion

- The curve and epoch segments ease toward each new sample every frame (exponential, 120ms), so data arriving in bursts still draws at an even pace with no jumps. A rollback or reset jumps instantly.
- The y axis is fixed from the first samples and the x axis spans the whole run, so nothing rescales mid-run.
- New events slide the list down with one bounce-free spring (0.24s); status, stats and footer text crossfade (100ms out, 160ms in, 2px rise).
- Reduced motion: the curve jumps to each sample, the spinner and shimmer stop, and crossfades become instant.
- The demo simulation freezes while the card is off screen.

### Responsive behavior

- Fills its container up to 640px. Under 440px the card padding drops to 16px, stats go to two columns, the legend shortens Validation to Val and the footer stacks context over actions.
- The chart measures its width and redraws at true pixel size, so strokes stay 2px crisp at any width. Touch drag scrubs the chart horizontally while vertical swipes still scroll.

### Performance

- Curve paths are written straight to the SVG on animation frames, without React renders; the smoother stops when it reaches the latest sample.
- Comfortable up to a few thousand samples. For longer runs, downsample to about 500 points before passing loss.

### Notes for AI

- Use for one fine-tuning or training job: model, dataset, live loss, controls and deploy. For a list of jobs, render one compact row per job and open this card for the selected one.
- Pass totalSteps and epochs from the job config so the axis is right from the first sample. Send loss as it streams; there is no need to throttle, the card smooths it.
- Each control only appears when its callback is passed, so a read-only monitor needs only data props.
- Real marks: import QwenColorMark, MetaColorMark or HuggingFaceMark from the component, or pass your own SVG as model.mark.
- Primary actions (Resume, Retry, Deploy) use the accent; only Confirm cancel uses danger.

### Related

- [Agent status](https://uiarc.dev/components/agent-status/markdown): A compact live status pill for a running AI agent: the agent's mark in a live ring, the current activity and an elapsed timer, opening into the steps so far.
- [Tool call](https://uiarc.dev/components/tool-call/markdown): A tool call row for agent transcripts: the tool's mark and the call in plain words, a live state while it runs, and the input and output a click away, with approval and retry when needed.
- [Model training](https://uiarc.dev/components/model-training/markdown): Training data batches feed a small neural net diagram whose connections strengthen, a loss curve descends beside it, and an evaluation check turns green at the end.
- [Line chart](https://uiarc.dev/components/line-chart/markdown): A multi-series line chart with a gliding crosshair, legend toggles, and paths that morph between ranges.
- [Progress](https://uiarc.dev/components/progress/markdown): Show how much of a known task is complete.
- [Copy button](https://uiarc.dev/components/copy-button/markdown): Copy a value with immediate confirmation.

### Also in ai

- [Agent plan](https://uiarc.dev/components/agent-plan/markdown): The plan an agent writes before it acts: edit, reorder or add steps while it is a draft, then watch it work through them as a live checklist.
- [Agent timeline](https://uiarc.dev/components/agent-timeline/markdown): A compact timeline of one orchestrated agent run: the orchestrator and its subagents share a time axis, handoffs draw in between rows, and a playhead replays thinking, tool calls and waiting while the header counts time, tokens and cost. Hover a span for what it did, or click it to trace its handoff path.
- [Context window](https://uiarc.dev/components/context-window/markdown): An AI context window as a grid of 200 cells: the system prompt, tools, files, summary and messages fill it in order, a threshold row marks where compaction starts, and sending a message, attaching a file or compacting shows exactly how much still fits.
- [Reasoning block](https://uiarc.dev/components/reasoning-block/markdown): The collapsible thinking block of an AI reply. While the model thinks, a shimmering label counts the seconds and the latest reasoning streams underneath. When it finishes, it folds to "Thought for 7s" and opens to show the full reasoning as calm steps with headings.
- [Source cards](https://uiarc.dev/components/source-cards/markdown): A row of cited sources under an AI answer where cards stream in with real site marks while the model searches, the overflow collapses into a stack of favicons, hovering lifts a preview with the passage, and an inline [n] citation highlights its card.
- [Model card](https://uiarc.dev/components/model-card/markdown): A model details card where switching models rolls every price, limit and score in place, a token slider estimates monthly cost live, and benchmark bars show each model's rank on hover. Compare crossfades to a side-by-side table against any rival with the better values marked, and the card never changes size.
- [AI workflow](https://uiarc.dev/components/ai-workflow/markdown): A Linear-style AI workflow card where a Gmail trigger, a Claude step, a branch and Slack and Linear actions sit on one hairline rail, and a test run glides down it, opening each step's output inline. Steps are added from a compact command menu with real app marks.
- [Code suggestion](https://uiarc.dev/components/code-suggestion/markdown): An AI code edit suggestion where the model's proposed changes stream into a small editor panel as inline diff hunks, and you accept or reject each one, or all at once with Cmd+Enter. Accepted hunks fold into the file with a smooth height change.
- [Ghost text](https://uiarc.dev/components/ghost-text/markdown): An inline AI autocomplete where muted ghost text continues your sentence exactly at the caret and Tab turns it solid in place. Cmd+Right takes it one word at a time, Escape fades it away, and a calm chip shows the model behind it.
- [Image generation](https://uiarc.dev/components/image-generation/markdown): An image studio where each image forms on a dot matrix: a soft halftone wave breathes across the grid, the dots take the colours of the coming photo and grow into a coloured halftone, then blur away into the sharp photo. One large canvas with a mono size label, a filmstrip of four variations, a prompt bar with model and ratio, and upscale with a sweeping dot band, vary or download, with real provider marks and a built-in simulation.
- [Dictation button](https://uiarc.dev/components/dictation-button/markdown): A chat composer with voice input, where the mic springs into a recording pill with a smooth live waveform, a timer, and cancel and insert buttons. Words stream into the field as you speak, muted until the recognizer settles them.
- [Speech player](https://uiarc.dev/components/speech-player/markdown): A read-aloud player for AI replies. The Read aloud button in the message's action row turns into a compact player with play, a scrubbable progress bar, speed and a voice picker, and a highlight follows the spoken word through the reply, karaoke style.
- [Meeting summary](https://uiarc.dev/components/meeting-summary/markdown): An AI meeting notes card: the header shows the Google Meet or Zoom mark, the attendees and the duration. Summary, Decisions and Action items stream in after a short summarizing pass. Hover any line to see the transcript quote it came from, then check off action items or send them to Linear or Notion.
- [Reply draft](https://uiarc.dev/components/reply-draft/markdown): An AI email reply drafter where Claude streams a reply under a received Gmail message. Quick replies steer a fresh draft, tone and length rewrite it with a single crossfade, and you can edit the finished draft before you insert it.
- [Agent handoff](https://uiarc.dev/components/agent-handoff/markdown): A support conversation where an AI assistant hands off to a person. When it transfers, a card shows the summary it passes to the team and the typical wait. The person then joins and takes over, and a thin timeline on the left marks each step.
- [PII redaction](https://uiarc.dev/components/pii-redaction/markdown): A guardrail card where personal data is redacted before the prompt reaches the model. Scan marks each name, email, phone number and card with its type and swaps it for a placeholder like [EMAIL_1]. The safe prompt travels to Claude, and the reply comes back with the original values put back for the person.
- [Response feedback](https://uiarc.dev/components/response-feedback/markdown): A feedback control for AI replies where thumbs down opens an inline panel with reason chips and an optional note, thumbs up fills and asks what was good, and a submit shows a short thank-you before folding back into the row.
- [LLM cost calculator](https://uiarc.dev/components/llm-cost-calculator/markdown): A pricing calculator for LLM workloads. Set tokens per request, requests per day and prompt caching, and eight current models re-rank by monthly cost. Bars glide and prices roll as you drag.
- [Provider keys](https://uiarc.dev/components/provider-keys/markdown): A settings card for bring-your-own-key AI products. Each provider row shows its real mark, the masked key, a status and when the key was last used. You can reveal a key for five seconds, copy, rotate or remove it with undo. Adding or rotating a key opens an inline form that checks the format as you type, then tests the connection before saving.
- [Generation stats](https://uiarc.dev/components/generation-stats/markdown): A live stats strip for a streaming LLM response where time to first token, speed with a sparkline, output tokens and cost count up in tabular numerals beside the model's real mark, then settle and open into a latency and token cost breakdown.
- [AI translate](https://uiarc.dev/components/ai-translate/markdown): A message card where picking a language streams the AI translation in place, sentence by sentence over the dimmed original, with a detected-language chip, a Show original toggle and a status line credited to the model's mark.
- [TL;DR toggle](https://uiarc.dev/components/tldr-toggle/markdown): An article card with a Full, Summary and Key points switch and a length slider. Switching streams an AI summary in place of the article as the card's height springs to fit, and each key point links back to the paragraph it came from, which gets scrolled to and highlighted.
- [Connector setup](https://uiarc.dev/components/connector-setup/markdown): A "Connect your tools" card for an AI assistant. Each app connects inline: it redirects, authorizes and runs a first sync with a progress hairline, then lists the scopes it was granted and offers Disconnect with an inline confirm.
- [Smart form fill](https://uiarc.dev/components/smart-form-fill/markdown): A paste-to-fill form card where AI reads an email signature or messy notes and fills a contact field by field. Each value flashes in with a confidence dot, its source lights up in the pasted text, low-confidence guesses ask for review, and Undo puts the old values back.
- [Enrich column](https://uiarc.dev/components/enrich-column/markdown): An AI enrichment column for a data table, where one prompt runs down every row and each cell shimmers while it works, then settles into a value with its source or a failure you can retry.
- [Ticket router](https://uiarc.dev/components/ticket-router/markdown): A support ticket router where messages from Gmail, Intercom, Slack and Zendesk come in one at a time. An AI classifier labels each one with intent, sentiment and confidence, and the ticket moves into a team lane with an assignee. Low confidence tickets wait in a review lane, and one click there routes them to the suggested team.
- [Ask your data](https://uiarc.dev/components/ask-your-data/markdown): A natural language to chart card: you ask a question, PostgreSQL streams into a collapsible, syntax highlighted panel, the query runs with a rolling row count, and the answer builds as stacked bars, lines or a table, with a one line insight streamed in underneath.
- [Agent cursor](https://uiarc.dev/components/agent-cursor/markdown): A live document where Claude edits like a collaborator. Its labeled cursor comes out of its avatar, selects a paragraph and streams in a rewrite, adds a heading and fixes a typo, while a teammate's cursor reads along. Changes stay tinted until someone accepts or undoes them from a floating review bar.
- [Provider status](https://uiarc.dev/components/provider-status/markdown): A status card for the AI providers your product depends on. Each row shows the provider's real mark, its health as an icon and label, p50 latency and a 30-day uptime bar with a tooltip for each day. An incident row expands into its timeline of updates, and the card checks again on a visible countdown.
- [AI command](https://uiarc.dev/components/ai-command/markdown): A Cmd+K command palette with an AI mode. Search pages and actions, or press Tab to ask a question: the answer streams inside the palette with numbered sources, and the next steps it suggests, like filing a Linear issue or opening a Notion doc, run straight from the list.
- [Starter prompts](https://uiarc.dev/components/starter-prompts/markdown): A greeting and a grid of starter cards for the empty state of an AI app. The cards are grouped into Write, Code, Analyze and Plan tabs, and a shuffle swaps them with a short staggered crossfade. Picking a card fills the composer, and cards that use a connected app show its mark (Gmail, GitHub, Notion, Linear, Google Calendar).
- [AI mascot](https://uiarc.dev/components/ai-mascot/markdown): A small assistant character, a soft pebble with pill eyes and a companion dot, that shows what the AI is doing. It breathes and glances when idle, leans in to listen, looks up while the dot orbits its head, reads along the line it writes, squints with a sparkle when done and shakes once with worried brows on an error.
- [Image reveal](https://uiarc.dev/components/image-reveal/markdown): An image generation canvas where a soft, blurred preview made from the image's own colors sharpens top to bottom behind a soft-edged band. It works the way ChatGPT, Midjourney and Gemini show images forming, with fine film grain, a translucent progress pill and calm queued and error states.
- [AI spark](https://uiarc.dev/components/ai-spark/markdown): A brand-quality animated spark mark. Four tapered rays and four lighter diagonals breathe at rest, ripple while thinking, pulse like a heartbeat while writing, then gather and settle when done. Every status change blends from the pose the mark is already in.
- [Pixel mascot](https://uiarc.dev/components/pixel-mascot/markdown): A pixel-art robot that shows what an AI assistant is doing. It idles, thinks, types, celebrates and errors in frame-stepped sprite animations, and stays crisp at every integer size from 24px to 192px.
- [Ghost mascot](https://uiarc.dev/components/ghost-mascot/markdown): A floating ghost mascot whose soft sheet ripples at the hem while it hovers. It blinks when idle, turns toward you to listen, fades a little translucent while thinking, draws a tiny pen line while writing, smiles with a sparkle when done and wobbles once on an error.
- [Cube mascot](https://uiarc.dev/components/cube-mascot/markdown): An isometric cube mascot where three shaded faces and a painted-on face show what the assistant is doing. It turns a quarter turn in eased steps while thinking, prints lines onto the floor while writing, settles with a sparkle when done, and shakes once on error.
- [Tone tuner](https://uiarc.dev/components/tone-tuner/markdown): A brand voice card where two sliders (formality and detail) and Friendly, Confident and Empathetic chips rewrite a customer reply. Each changed sentence crossfades in place, new words can be highlighted against the original, and Copy takes the current version.
- [Upgrade prompt](https://uiarc.dev/components/upgrade-prompt/markdown): An upgrade nudge for the moment someone hits a limit. It shows a usage meter at 50 of 50 AI credits, a rolling price with a monthly and yearly toggle, three concrete unlocks with real model marks, and Upgrade or Maybe later. Upgrading leads into a success state with the new limits, and the card never changes size between states.
- [Referral card](https://uiarc.dev/components/referral-card/markdown): A give-and-get referral card where people copy or share their invite link, invite friends by email as chips, and watch invites move from invited to signed up to earned, with the credit total counting up and a milestone reward unlocking.
- [Trial banner](https://uiarc.dev/components/trial-banner/markdown): A trial status banner where a ring counts down the days left, the copy names what the workspace loses, and the upgrade path is one click away. It comes as a slim banner, a sidebar card or a header pill. It shifts to a warning tone in the last days, has expired and upgraded states, and folds into the pill when dismissed or snoozed.
- [Team switcher](https://uiarc.dev/components/team-switcher/markdown): A workspace switcher like Linear, Vercel or Slack. The trigger shows the current workspace's logo and plan. The menu has search, your role in each workspace and a Cmd+1 to 9 shortcut for each, and lets you create or join a workspace inline. A highlight glides between rows, and switching crossfades the trigger through a short loading state.
- [Live visitors](https://uiarc.dev/components/live-visitors/markdown): A realtime visitors card where the live count rolls digit by digit, new arrivals ping in on a dotted world map, the top pages reorder with bars, and signups and upgrades tick in with country flags.
- [Social proof toast](https://uiarc.dev/components/social-proof-toast/markdown): A stack of social proof notifications for landing and pricing pages, where recent trials, upgrades and verified purchases from people and companies arrive every few seconds. The stack pauses and fans out on hover, and visitors can dismiss any toast.
- [Install snippet](https://uiarc.dev/components/install-snippet/markdown): A "get started in 30 seconds" card where framework tabs, three numbered steps and highlighted snippets take a developer from install to first event. Generate key wipes a fresh API key into the placeholder in place.

### Guidance for AI tools

Training run: A fine-tuning job card where a live train and validation loss curve draws across a fixed step axis that doubles as the epoch progress bar. It shows the learning rate, elapsed time, ETA and the latest evals and checkpoints, has Pause and Cancel while it runs, and ends in results with a Deploy button. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## AI command

> A Cmd+K command palette with an AI mode. Search pages and actions, or press Tab to ask a question: the answer streams inside the palette with numbered sources, and the next steps it suggests, like filing a Linear issue or opening a Notion doc, run straight from the list.

- Type: Component (special)
- Access: Arc Pro
- Page: https://uiarc.dev/components/ai-command
- Markdown: https://uiarc.dev/components/ai-command/markdown
- Source file: `registry/components/ai-command/ai-command.tsx`
- Dependencies: motion, lucide-react
- Keywords: special, ai, new, command palette, cmd k, command menu, ask ai, ai search, spotlight, raycast, quick actions, streaming answer, citations, sources, keyboard

### When to use

- A global Cmd+K in a SaaS app where people both jump to pages and ask questions about their workspace.
- Search that should fall back to an AI answer when nothing matches.
- Answers that lead straight to an action in another tool, like filing a Linear issue or posting to Slack.

### When not to use

- A long, multi-turn conversation: use a chat thread.
- Plain navigation with no AI: use command-palette.
- Inline field suggestions while typing in a form: use an autocomplete input.

### Installation

AI command is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/ai-command
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { AiCommand } from "@/components/arc/ai-command/ai-command";

// Sample walkthrough
<AiCommand />

// Wired to your app and model
<AiCommand
  items={commands}
  onSelect={item => { router.push(item.id); setOpen(false); }}
  onAsk={async (question, { signal, append, setSources }) => {
    const res = await fetch("/api/ask", { method: "POST", body: JSON.stringify({ question }), signal });
    const { sources, stream } = await readAnswer(res);
    setSources(sources);
    for await (const delta of stream) append(delta);
    return { actions: [{ id: "issue", label: "Create issue in Linear", run: s => createIssue(question, s) }] };
  }}
  onClose={() => setOpen(false)}
  elevated
/>
```

### API reference

#### AiCommand

A fixed-size command palette with an AI mode. Search pages and actions, or press Tab to ask: the answer streams in place with numbered sources and runnable next steps. With no props it plays a sample walkthrough until someone interacts.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `items` | `AiCommandItem[]` | `sample workspace` | Pages and actions to search: { id, label, group?, icon?, meta?, shortcut?, keywords?, suggested?, onSelect? }. Rows marked suggested show while the query is empty. |
| `onSelect` | `(item: AiCommandItem) => void` | – | Runs when a page or action is chosen with Enter or a click. Close your dialog or navigate here. |
| `onAsk` | `(question, { signal, append, setSources }) => Promise<AiCommandAnswer \| void>` | `simulated engine` | Answers a question. Stream text with append, show sources early with setSources, and resolve with { text?, sources?, actions? }. Throw to show the error state with Retry. The signal aborts when the person asks again or goes back. |
| `onAction` | `(action: AiCommandAction, result: string) => void` | – | Runs after a suggested action finishes, with the label it ended on (for example "Created ENG-2481"). |
| `onSourceSelect` | `(source: AiCommandSource) => void` | – | Runs when a source chip or citation is chosen. Sources with an href open in a new tab instead. |
| `suggestedQuestions` | `string[]` | `3 sample questions` | Questions offered while Ask AI is open and empty. |
| `model` | `{ name: string; mark?: ReactNode }` | `{ name: "Claude Sonnet 5.5" }` | The model that answers, shown in the footer, the input and beside each answer. |
| `defaultMode` | `"search" \| "ask"` | `"search"` | Mode on first render. |
| `defaultQuery` | `string` | `""` | Query on first render. |
| `onModeChange` | `(mode: "search" \| "ask") => void` | – | Runs when the palette switches between Search and Ask AI. |
| `onClose` | `() => void` | – | Escape on an empty search. Use it to close the surrounding dialog. |
| `placeholder` | `{ search?: string; ask?: string }` | – | Input placeholders per mode. |
| `thinkingLabel` | `string` | `"Searching your workspace"` | Status while the model works, before any text arrives. |
| `autoPlay` | `boolean` | `true without items and onAsk` | Plays a looping walkthrough while on screen. Stops for good on the first real pointer or key press inside, and never runs with reduced motion. |
| `hotkey` | `boolean` | `false` | Listens for Cmd+K or Ctrl+K on the page and focuses the input. |
| `height` | `number` | `392` | Height of the results area in px. The palette keeps this size while typing, switching modes and streaming. |
| `elevated` | `boolean` | `false` | Adds the floating shadow, for use inside a dialog or popover. |
| `className` | `string` | – | Class on the root. |
| `style` | `CSSProperties` | – | Inline styles on the root. |
| `aria-label` | `string` | `"Command palette"` | Accessible name of the palette. |

#### AiCommandAction

A suggested next step returned with an answer and run in place.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `id` (required) | `string` | – | Stable id. |
| `label` (required) | `string` | – | Row label, such as "Create issue in Linear". |
| `meta` | `string` | – | Quiet detail after the label. |
| `mark` | `ReactNode` | – | 16px brand mark or icon. |
| `run` | `(signal: AbortSignal) => Promise<string \| void>` | – | Does the work. Resolve with a done label or nothing; throw to show the error state (Enter retries). |
| `runningLabel / doneLabel / errorLabel / doneMeta` | `string` | – | Labels for each state. doneMeta is where a simulated action says nothing was sent. |

#### AiCommandSource

A document the answer cites as [1], [2] in its text.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `id` (required) | `string` | – | Stable id. |
| `title` (required) | `string` | – | Short chip title, such as "billing-api #1893". |
| `description` | `string` | – | Longer text for the tooltip and screen readers. |
| `mark` | `ReactNode` | – | 14px brand mark or icon. |
| `href` | `string` | – | Opens in a new tab when chosen. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Up / Down | Move through results, questions or suggested actions. |
| Enter | Open the page, run the action, ask the question, or retry a failed answer or action. |
| Tab | Ask AI about the current query. With an empty query it opens Ask AI with suggested questions; in that state Tab goes back to search. |
| Escape | From Ask AI, back to search (cancels a streaming answer). In search, clears the query, then calls onClose. |
| Cmd / Ctrl + K | Focuses the input when hotkey is on. |

### Accessibility

- The input is a combobox that owns a listbox; the active row is announced through aria-activedescendant, so focus never leaves the input.
- A polite live region announces questions, finished answers, action results and simulated runs ("Simulated, nothing was sent").
- Status is never color alone: running, done and failed actions change both the icon and the label.
- Citations and source chips are buttons with full descriptions as their accessible names; hovering or focusing one highlights its partner.
- The mode toggle uses aria-pressed buttons and keeps input focus.

### Motion

- The palette never changes size: the results area has a fixed height and views crossfade in place (100ms out, 160ms in, 2px rise).
- One highlight glides between rows in 130ms and jumps without travel when the list itself changes, so typing never animates.
- Answers stream 3 to 7 words every 34ms, each chunk fading in over 140ms; the view follows the text down unless you scroll up.
- Labels, status icons and footer hints swap with a single crossfade. The done check draws once.
- Reduced motion: no walkthrough, no chunk fades or travel; the answer reveals in large steps and every state stays.
- The walkthrough pauses off screen through IntersectionObserver and restarts from a clean state.

### Responsive behavior

- Fills its container up to 680px and holds up at 360px; long labels and meta truncate with an ellipsis, meta first.
- Below 540px the navigate hint hides from the footer; source chips wrap.
- Rows are 40px tall and work with touch; hover only moves the highlight on fine pointers that actually move.

### Performance

- Search is a synchronous word match over the items array, fine for a few hundred rows; filter on the server beyond that.
- Streaming appends one span per chunk; the highlight is positioned directly in the DOM without extra renders.
- The walkthrough and its timers stop off screen and on unmount; in-flight answers and actions abort through their signals.

### Notes for AI

- Use for a product-wide Cmd+K that can also answer questions; put it inside a dialog with elevated and onClose.
- Return sources before text with setSources so the chips land first, and cite them in the text as [1], [2].
- Give each suggested action a run that takes the AbortSignal; return the created object's name ("Created ENG-2481") as the done label.
- Keep item labels short and put context in meta; use group to section results.
- For a plain command menu without AI, use command-palette instead.

### Related

- [Command palette](https://uiarc.dev/components/blocks/command-palette/markdown): A complete keyboard driven action surface with search, grouped results, and shortcuts.
- [Source cards](https://uiarc.dev/components/source-cards/markdown): A row of cited sources under an AI answer where cards stream in with real site marks while the model searches, the overflow collapses into a stack of favicons, hovering lifts a preview with the passage, and an inline [n] citation highlights its card.
- [Tool call](https://uiarc.dev/components/tool-call/markdown): A tool call row for agent transcripts: the tool's mark and the call in plain words, a live state while it runs, and the input and output a click away, with approval and retry when needed.
- [Starter prompts](https://uiarc.dev/components/starter-prompts/markdown): A greeting and a grid of starter cards for the empty state of an AI app. The cards are grouped into Write, Code, Analyze and Plan tabs, and a shuffle swaps them with a short staggered crossfade. Picking a card fills the composer, and cards that use a connected app show its mark (Gmail, GitHub, Notion, Linear, Google Calendar).

### Also in ai

- [Agent status](https://uiarc.dev/components/agent-status/markdown): A compact live status pill for a running AI agent: the agent's mark in a live ring, the current activity and an elapsed timer, opening into the steps so far.
- [Agent plan](https://uiarc.dev/components/agent-plan/markdown): The plan an agent writes before it acts: edit, reorder or add steps while it is a draft, then watch it work through them as a live checklist.
- [Agent timeline](https://uiarc.dev/components/agent-timeline/markdown): A compact timeline of one orchestrated agent run: the orchestrator and its subagents share a time axis, handoffs draw in between rows, and a playhead replays thinking, tool calls and waiting while the header counts time, tokens and cost. Hover a span for what it did, or click it to trace its handoff path.
- [Context window](https://uiarc.dev/components/context-window/markdown): An AI context window as a grid of 200 cells: the system prompt, tools, files, summary and messages fill it in order, a threshold row marks where compaction starts, and sending a message, attaching a file or compacting shows exactly how much still fits.
- [Reasoning block](https://uiarc.dev/components/reasoning-block/markdown): The collapsible thinking block of an AI reply. While the model thinks, a shimmering label counts the seconds and the latest reasoning streams underneath. When it finishes, it folds to "Thought for 7s" and opens to show the full reasoning as calm steps with headings.
- [Model card](https://uiarc.dev/components/model-card/markdown): A model details card where switching models rolls every price, limit and score in place, a token slider estimates monthly cost live, and benchmark bars show each model's rank on hover. Compare crossfades to a side-by-side table against any rival with the better values marked, and the card never changes size.
- [AI workflow](https://uiarc.dev/components/ai-workflow/markdown): A Linear-style AI workflow card where a Gmail trigger, a Claude step, a branch and Slack and Linear actions sit on one hairline rail, and a test run glides down it, opening each step's output inline. Steps are added from a compact command menu with real app marks.
- [Code suggestion](https://uiarc.dev/components/code-suggestion/markdown): An AI code edit suggestion where the model's proposed changes stream into a small editor panel as inline diff hunks, and you accept or reject each one, or all at once with Cmd+Enter. Accepted hunks fold into the file with a smooth height change.
- [Ghost text](https://uiarc.dev/components/ghost-text/markdown): An inline AI autocomplete where muted ghost text continues your sentence exactly at the caret and Tab turns it solid in place. Cmd+Right takes it one word at a time, Escape fades it away, and a calm chip shows the model behind it.
- [Image generation](https://uiarc.dev/components/image-generation/markdown): An image studio where each image forms on a dot matrix: a soft halftone wave breathes across the grid, the dots take the colours of the coming photo and grow into a coloured halftone, then blur away into the sharp photo. One large canvas with a mono size label, a filmstrip of four variations, a prompt bar with model and ratio, and upscale with a sweeping dot band, vary or download, with real provider marks and a built-in simulation.
- [Dictation button](https://uiarc.dev/components/dictation-button/markdown): A chat composer with voice input, where the mic springs into a recording pill with a smooth live waveform, a timer, and cancel and insert buttons. Words stream into the field as you speak, muted until the recognizer settles them.
- [Speech player](https://uiarc.dev/components/speech-player/markdown): A read-aloud player for AI replies. The Read aloud button in the message's action row turns into a compact player with play, a scrubbable progress bar, speed and a voice picker, and a highlight follows the spoken word through the reply, karaoke style.
- [Meeting summary](https://uiarc.dev/components/meeting-summary/markdown): An AI meeting notes card: the header shows the Google Meet or Zoom mark, the attendees and the duration. Summary, Decisions and Action items stream in after a short summarizing pass. Hover any line to see the transcript quote it came from, then check off action items or send them to Linear or Notion.
- [Reply draft](https://uiarc.dev/components/reply-draft/markdown): An AI email reply drafter where Claude streams a reply under a received Gmail message. Quick replies steer a fresh draft, tone and length rewrite it with a single crossfade, and you can edit the finished draft before you insert it.
- [Agent handoff](https://uiarc.dev/components/agent-handoff/markdown): A support conversation where an AI assistant hands off to a person. When it transfers, a card shows the summary it passes to the team and the typical wait. The person then joins and takes over, and a thin timeline on the left marks each step.
- [PII redaction](https://uiarc.dev/components/pii-redaction/markdown): A guardrail card where personal data is redacted before the prompt reaches the model. Scan marks each name, email, phone number and card with its type and swaps it for a placeholder like [EMAIL_1]. The safe prompt travels to Claude, and the reply comes back with the original values put back for the person.
- [Response feedback](https://uiarc.dev/components/response-feedback/markdown): A feedback control for AI replies where thumbs down opens an inline panel with reason chips and an optional note, thumbs up fills and asks what was good, and a submit shows a short thank-you before folding back into the row.
- [LLM cost calculator](https://uiarc.dev/components/llm-cost-calculator/markdown): A pricing calculator for LLM workloads. Set tokens per request, requests per day and prompt caching, and eight current models re-rank by monthly cost. Bars glide and prices roll as you drag.
- [Provider keys](https://uiarc.dev/components/provider-keys/markdown): A settings card for bring-your-own-key AI products. Each provider row shows its real mark, the masked key, a status and when the key was last used. You can reveal a key for five seconds, copy, rotate or remove it with undo. Adding or rotating a key opens an inline form that checks the format as you type, then tests the connection before saving.
- [Generation stats](https://uiarc.dev/components/generation-stats/markdown): A live stats strip for a streaming LLM response where time to first token, speed with a sparkline, output tokens and cost count up in tabular numerals beside the model's real mark, then settle and open into a latency and token cost breakdown.
- [AI translate](https://uiarc.dev/components/ai-translate/markdown): A message card where picking a language streams the AI translation in place, sentence by sentence over the dimmed original, with a detected-language chip, a Show original toggle and a status line credited to the model's mark.
- [TL;DR toggle](https://uiarc.dev/components/tldr-toggle/markdown): An article card with a Full, Summary and Key points switch and a length slider. Switching streams an AI summary in place of the article as the card's height springs to fit, and each key point links back to the paragraph it came from, which gets scrolled to and highlighted.
- [Connector setup](https://uiarc.dev/components/connector-setup/markdown): A "Connect your tools" card for an AI assistant. Each app connects inline: it redirects, authorizes and runs a first sync with a progress hairline, then lists the scopes it was granted and offers Disconnect with an inline confirm.
- [Smart form fill](https://uiarc.dev/components/smart-form-fill/markdown): A paste-to-fill form card where AI reads an email signature or messy notes and fills a contact field by field. Each value flashes in with a confidence dot, its source lights up in the pasted text, low-confidence guesses ask for review, and Undo puts the old values back.
- [Enrich column](https://uiarc.dev/components/enrich-column/markdown): An AI enrichment column for a data table, where one prompt runs down every row and each cell shimmers while it works, then settles into a value with its source or a failure you can retry.
- [Ticket router](https://uiarc.dev/components/ticket-router/markdown): A support ticket router where messages from Gmail, Intercom, Slack and Zendesk come in one at a time. An AI classifier labels each one with intent, sentiment and confidence, and the ticket moves into a team lane with an assignee. Low confidence tickets wait in a review lane, and one click there routes them to the suggested team.
- [Ask your data](https://uiarc.dev/components/ask-your-data/markdown): A natural language to chart card: you ask a question, PostgreSQL streams into a collapsible, syntax highlighted panel, the query runs with a rolling row count, and the answer builds as stacked bars, lines or a table, with a one line insight streamed in underneath.
- [Agent cursor](https://uiarc.dev/components/agent-cursor/markdown): A live document where Claude edits like a collaborator. Its labeled cursor comes out of its avatar, selects a paragraph and streams in a rewrite, adds a heading and fixes a typo, while a teammate's cursor reads along. Changes stay tinted until someone accepts or undoes them from a floating review bar.
- [Provider status](https://uiarc.dev/components/provider-status/markdown): A status card for the AI providers your product depends on. Each row shows the provider's real mark, its health as an icon and label, p50 latency and a 30-day uptime bar with a tooltip for each day. An incident row expands into its timeline of updates, and the card checks again on a visible countdown.
- [Training run](https://uiarc.dev/components/training-run/markdown): A fine-tuning job card where a live train and validation loss curve draws across a fixed step axis that doubles as the epoch progress bar. It shows the learning rate, elapsed time, ETA and the latest evals and checkpoints, has Pause and Cancel while it runs, and ends in results with a Deploy button.
- [AI mascot](https://uiarc.dev/components/ai-mascot/markdown): A small assistant character, a soft pebble with pill eyes and a companion dot, that shows what the AI is doing. It breathes and glances when idle, leans in to listen, looks up while the dot orbits its head, reads along the line it writes, squints with a sparkle when done and shakes once with worried brows on an error.
- [Image reveal](https://uiarc.dev/components/image-reveal/markdown): An image generation canvas where a soft, blurred preview made from the image's own colors sharpens top to bottom behind a soft-edged band. It works the way ChatGPT, Midjourney and Gemini show images forming, with fine film grain, a translucent progress pill and calm queued and error states.
- [AI spark](https://uiarc.dev/components/ai-spark/markdown): A brand-quality animated spark mark. Four tapered rays and four lighter diagonals breathe at rest, ripple while thinking, pulse like a heartbeat while writing, then gather and settle when done. Every status change blends from the pose the mark is already in.
- [Pixel mascot](https://uiarc.dev/components/pixel-mascot/markdown): A pixel-art robot that shows what an AI assistant is doing. It idles, thinks, types, celebrates and errors in frame-stepped sprite animations, and stays crisp at every integer size from 24px to 192px.
- [Ghost mascot](https://uiarc.dev/components/ghost-mascot/markdown): A floating ghost mascot whose soft sheet ripples at the hem while it hovers. It blinks when idle, turns toward you to listen, fades a little translucent while thinking, draws a tiny pen line while writing, smiles with a sparkle when done and wobbles once on an error.
- [Cube mascot](https://uiarc.dev/components/cube-mascot/markdown): An isometric cube mascot where three shaded faces and a painted-on face show what the assistant is doing. It turns a quarter turn in eased steps while thinking, prints lines onto the floor while writing, settles with a sparkle when done, and shakes once on error.
- [Tone tuner](https://uiarc.dev/components/tone-tuner/markdown): A brand voice card where two sliders (formality and detail) and Friendly, Confident and Empathetic chips rewrite a customer reply. Each changed sentence crossfades in place, new words can be highlighted against the original, and Copy takes the current version.
- [Upgrade prompt](https://uiarc.dev/components/upgrade-prompt/markdown): An upgrade nudge for the moment someone hits a limit. It shows a usage meter at 50 of 50 AI credits, a rolling price with a monthly and yearly toggle, three concrete unlocks with real model marks, and Upgrade or Maybe later. Upgrading leads into a success state with the new limits, and the card never changes size between states.
- [Referral card](https://uiarc.dev/components/referral-card/markdown): A give-and-get referral card where people copy or share their invite link, invite friends by email as chips, and watch invites move from invited to signed up to earned, with the credit total counting up and a milestone reward unlocking.
- [Trial banner](https://uiarc.dev/components/trial-banner/markdown): A trial status banner where a ring counts down the days left, the copy names what the workspace loses, and the upgrade path is one click away. It comes as a slim banner, a sidebar card or a header pill. It shifts to a warning tone in the last days, has expired and upgraded states, and folds into the pill when dismissed or snoozed.
- [Team switcher](https://uiarc.dev/components/team-switcher/markdown): A workspace switcher like Linear, Vercel or Slack. The trigger shows the current workspace's logo and plan. The menu has search, your role in each workspace and a Cmd+1 to 9 shortcut for each, and lets you create or join a workspace inline. A highlight glides between rows, and switching crossfades the trigger through a short loading state.
- [Live visitors](https://uiarc.dev/components/live-visitors/markdown): A realtime visitors card where the live count rolls digit by digit, new arrivals ping in on a dotted world map, the top pages reorder with bars, and signups and upgrades tick in with country flags.
- [Social proof toast](https://uiarc.dev/components/social-proof-toast/markdown): A stack of social proof notifications for landing and pricing pages, where recent trials, upgrades and verified purchases from people and companies arrive every few seconds. The stack pauses and fans out on hover, and visitors can dismiss any toast.
- [Install snippet](https://uiarc.dev/components/install-snippet/markdown): A "get started in 30 seconds" card where framework tabs, three numbered steps and highlighted snippets take a developer from install to first event. Generate key wipes a fresh API key into the placeholder in place.

### Guidance for AI tools

AI command: A Cmd+K command palette with an AI mode. Search pages and actions, or press Tab to ask a question: the answer streams inside the palette with numbered sources, and the next steps it suggests, like filing a Linear issue or opening a Notion doc, run straight from the list. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Starter prompts

> A greeting and a grid of starter cards for the empty state of an AI app. The cards are grouped into Write, Code, Analyze and Plan tabs, and a shuffle swaps them with a short staggered crossfade. Picking a card fills the composer, and cards that use a connected app show its mark (Gmail, GitHub, Notion, Linear, Google Calendar).

- Type: Component (special)
- Access: Arc Pro
- Page: https://uiarc.dev/components/starter-prompts
- Markdown: https://uiarc.dev/components/starter-prompts/markdown
- Source file: `registry/components/starter-prompts/starter-prompts.tsx`
- Dependencies: motion, lucide-react
- Keywords: special, ai, new, starter prompts, prompt suggestions, empty state, ai chat, new chat, conversation starters, prompt cards, composer, shuffle, integrations

### When to use

- The empty state of a chat, copilot or agent, before the first message.
- Teaching what an assistant can do with connected tools, such as Gmail, GitHub or Notion.
- Onboarding a new workspace with a few tailored, ready to send prompts.

### When not to use

- Inside a running conversation; use follow-up suggestion chips in the chat thread instead.
- A command launcher with search; use command-palette or ai-command.
- A single inline suggestion in a text field; use ghost-text.

### Installation

Starter prompts is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/starter-prompts
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { StarterPrompts } from "@/components/arc/starter-prompts/starter-prompts";

export function NewChat() {
  return (
    <StarterPrompts
      greeting="Good morning, Maya"
      onSelect={prompt => track("starter_picked", { id: prompt.id })}
      onSubmit={async (message, { signal }) => {
        const res = await fetch("/api/chat", { method: "POST", body: JSON.stringify({ message }), signal });
        if (!res.ok) throw new Error("Couldn't send. Try again.");
      }}
    />
  );
}
```

### Examples

#### Your own starters and tabs

```tsx
<StarterPrompts
  categories={[{ id: "support", label: "Support" }, { id: "sales", label: "Sales" }]}
  prompts={[
    { id: "refund", category: "support", app: "gmail", title: "Answer refund requests", description: "Draft replies for the 6 open threads", prompt: "Draft replies to the 6 open refund threads in Gmail..." },
    { id: "pipeline", category: "sales", title: "Review the pipeline", description: "Deals that slipped this month", prompt: "List the deals that slipped in October and why..." },
  ]}
  model={{ name: "GPT-6.1 Sol", mark: <OpenAIMark width={14} height={14} /> }}
/>
```

### API reference

#### StarterPrompts

The empty state of an AI app: a greeting, starter cards filtered by category tabs, a shuffle that swaps cards with a short staggered crossfade, and a composer the cards fill. With no props it shows 24 sample starters and simulates the send.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `greeting` | `ReactNode` | `"What are we working on, Maya?"` | The heading. |
| `description` | `ReactNode` | `sample line` | One quiet line under the heading. Pass null to hide it. |
| `prompts` | `StarterPrompt[]` | `starterPromptSamples` | The starters: { id, category, title, description?, prompt, app? }. prompt is the full text placed in the composer; app is "gmail" \| "github" \| "notion" \| "linear" \| "calendar" and shows that app's mark. |
| `categories` | `StarterPromptCategory[]` | `Write, Code, Analyze, Plan` | The filter tabs in order, each { id, label, icon? }. All is added in front, and tabs with no starters are hidden. |
| `defaultCategory` | `string` | `"all"` | The tab selected first. |
| `count` | `number` | `4` | Cards on screen at once. The grid reserves this many slots so nothing jumps. |
| `loading` | `boolean` | `false` | Shows placeholder cards with the same size and rhythm while starters load. |
| `value` | `string` | – | The composer text, controlled. Pair with onValueChange. |
| `defaultValue` | `string` | `""` | The composer text on first render when uncontrolled. |
| `onValueChange` | `(value: string) => void` | – | Called when the composer text changes, from typing or a picked card. |
| `onSelect` | `(prompt: StarterPrompt) => void` | – | Called when a card is picked, after its prompt fills the composer. |
| `onSubmit` | `(message: string, context: { prompt: StarterPrompt \| null; signal: AbortSignal }) => Promise<void> \| void` | – | Sends the message. Throw to show the error state with Retry. The signal aborts when the person presses Stop or the component unmounts. Without it the send is simulated. |
| `model` | `{ name: string; mark?: ReactNode }` | `{ name: "Claude Sonnet 5.5" }` | The model named in the composer footer. The mark defaults to the Claude mark. |
| `placeholder` | `string` | `"Ask anything, or pick a starter above"` | Composer placeholder. |
| `className` | `string` | – | Extra class on the root section. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Tab | Moves through the tabs, Shuffle, each card and the composer. |
| Arrow keys | Move between category tabs. |
| Enter or Space | On a card, fills the composer with its prompt and focuses it. |
| Enter | In the composer, sends the message. |
| Shift Enter | In the composer, adds a new line. |
| Escape | While sending, stops the send and keeps the text. |

### Accessibility

- The component is a labelled section; the greeting is its heading.
- Each card is a button whose name includes the title, the connected app and the category.
- A polite live region announces picks, shuffles, sending, done and errors, and says when a send is simulated.
- Status is never color alone: done shows a check and label, errors an alert icon and the message.
- The send button is labelled Send message, and Stop sending while a message is in flight.

### Motion

- Shuffle and tab changes crossfade each card's content inside a fixed frame: out in 100ms, in over 160ms with a 2px rise, staggered 35ms per card (about 100ms in total).
- Picking a card focuses the composer and fades the new text in over 160ms.
- The footer status and the send or stop icon crossfade; nothing moves or resizes.
- Reduced motion keeps every end state and cuts the fades and the skeleton breathing.

### Responsive behavior

- Two columns of cards above about 560px of container width, one column below.
- Tabs scroll inside themselves with edge fades; Shuffle becomes an icon button under about 440px.
- Padding and the outer radius step down under 480px of viewport width. Holds at 360px with no horizontal scroll.

### Performance

- Renders only the cards on screen; the pool can hold hundreds of starters.
- No timers or loops while idle; the skeleton uses one CSS animation.
- Marks are inline SVG, no images to load.

### Notes for AI

- Use it as the first screen of a new chat or agent thread, then swap it for the conversation once a message is sent.
- Keep titles short and verb first, and put the full, specific instruction in prompt; the composer shows prompt, not title.
- Set app only when the prompt really uses that integration, so the mark means something.
- Wire onSubmit to your chat endpoint and honor the AbortSignal for Stop.

### Related

- [Chat thread](https://uiarc.dev/components/chat-thread/markdown): A chat thread with grouped messages, reactions, read receipts, typing, and a composer with attachments.
- [Tool call](https://uiarc.dev/components/tool-call/markdown): A tool call row for agent transcripts: the tool's mark and the call in plain words, a live state while it runs, and the input and output a click away, with approval and retry when needed.
- [Ghost text](https://uiarc.dev/components/ghost-text/markdown): An inline AI autocomplete where muted ghost text continues your sentence exactly at the caret and Tab turns it solid in place. Cmd+Right takes it one word at a time, Escape fades it away, and a calm chip shows the model behind it.
- [Empty state](https://uiarc.dev/components/empty-state/markdown): A useful next step when there is nothing to show yet.
- [AI command](https://uiarc.dev/components/ai-command/markdown): A Cmd+K command palette with an AI mode. Search pages and actions, or press Tab to ask a question: the answer streams inside the palette with numbered sources, and the next steps it suggests, like filing a Linear issue or opening a Notion doc, run straight from the list.
- [Segmented control](https://uiarc.dev/components/segmented-control/markdown): Switch between a small set of related views.

### Also in ai

- [Agent status](https://uiarc.dev/components/agent-status/markdown): A compact live status pill for a running AI agent: the agent's mark in a live ring, the current activity and an elapsed timer, opening into the steps so far.
- [Agent plan](https://uiarc.dev/components/agent-plan/markdown): The plan an agent writes before it acts: edit, reorder or add steps while it is a draft, then watch it work through them as a live checklist.
- [Agent timeline](https://uiarc.dev/components/agent-timeline/markdown): A compact timeline of one orchestrated agent run: the orchestrator and its subagents share a time axis, handoffs draw in between rows, and a playhead replays thinking, tool calls and waiting while the header counts time, tokens and cost. Hover a span for what it did, or click it to trace its handoff path.
- [Context window](https://uiarc.dev/components/context-window/markdown): An AI context window as a grid of 200 cells: the system prompt, tools, files, summary and messages fill it in order, a threshold row marks where compaction starts, and sending a message, attaching a file or compacting shows exactly how much still fits.
- [Reasoning block](https://uiarc.dev/components/reasoning-block/markdown): The collapsible thinking block of an AI reply. While the model thinks, a shimmering label counts the seconds and the latest reasoning streams underneath. When it finishes, it folds to "Thought for 7s" and opens to show the full reasoning as calm steps with headings.
- [Source cards](https://uiarc.dev/components/source-cards/markdown): A row of cited sources under an AI answer where cards stream in with real site marks while the model searches, the overflow collapses into a stack of favicons, hovering lifts a preview with the passage, and an inline [n] citation highlights its card.
- [Model card](https://uiarc.dev/components/model-card/markdown): A model details card where switching models rolls every price, limit and score in place, a token slider estimates monthly cost live, and benchmark bars show each model's rank on hover. Compare crossfades to a side-by-side table against any rival with the better values marked, and the card never changes size.
- [AI workflow](https://uiarc.dev/components/ai-workflow/markdown): A Linear-style AI workflow card where a Gmail trigger, a Claude step, a branch and Slack and Linear actions sit on one hairline rail, and a test run glides down it, opening each step's output inline. Steps are added from a compact command menu with real app marks.
- [Code suggestion](https://uiarc.dev/components/code-suggestion/markdown): An AI code edit suggestion where the model's proposed changes stream into a small editor panel as inline diff hunks, and you accept or reject each one, or all at once with Cmd+Enter. Accepted hunks fold into the file with a smooth height change.
- [Image generation](https://uiarc.dev/components/image-generation/markdown): An image studio where each image forms on a dot matrix: a soft halftone wave breathes across the grid, the dots take the colours of the coming photo and grow into a coloured halftone, then blur away into the sharp photo. One large canvas with a mono size label, a filmstrip of four variations, a prompt bar with model and ratio, and upscale with a sweeping dot band, vary or download, with real provider marks and a built-in simulation.
- [Dictation button](https://uiarc.dev/components/dictation-button/markdown): A chat composer with voice input, where the mic springs into a recording pill with a smooth live waveform, a timer, and cancel and insert buttons. Words stream into the field as you speak, muted until the recognizer settles them.
- [Speech player](https://uiarc.dev/components/speech-player/markdown): A read-aloud player for AI replies. The Read aloud button in the message's action row turns into a compact player with play, a scrubbable progress bar, speed and a voice picker, and a highlight follows the spoken word through the reply, karaoke style.
- [Meeting summary](https://uiarc.dev/components/meeting-summary/markdown): An AI meeting notes card: the header shows the Google Meet or Zoom mark, the attendees and the duration. Summary, Decisions and Action items stream in after a short summarizing pass. Hover any line to see the transcript quote it came from, then check off action items or send them to Linear or Notion.
- [Reply draft](https://uiarc.dev/components/reply-draft/markdown): An AI email reply drafter where Claude streams a reply under a received Gmail message. Quick replies steer a fresh draft, tone and length rewrite it with a single crossfade, and you can edit the finished draft before you insert it.
- [Agent handoff](https://uiarc.dev/components/agent-handoff/markdown): A support conversation where an AI assistant hands off to a person. When it transfers, a card shows the summary it passes to the team and the typical wait. The person then joins and takes over, and a thin timeline on the left marks each step.
- [PII redaction](https://uiarc.dev/components/pii-redaction/markdown): A guardrail card where personal data is redacted before the prompt reaches the model. Scan marks each name, email, phone number and card with its type and swaps it for a placeholder like [EMAIL_1]. The safe prompt travels to Claude, and the reply comes back with the original values put back for the person.
- [Response feedback](https://uiarc.dev/components/response-feedback/markdown): A feedback control for AI replies where thumbs down opens an inline panel with reason chips and an optional note, thumbs up fills and asks what was good, and a submit shows a short thank-you before folding back into the row.
- [LLM cost calculator](https://uiarc.dev/components/llm-cost-calculator/markdown): A pricing calculator for LLM workloads. Set tokens per request, requests per day and prompt caching, and eight current models re-rank by monthly cost. Bars glide and prices roll as you drag.
- [Provider keys](https://uiarc.dev/components/provider-keys/markdown): A settings card for bring-your-own-key AI products. Each provider row shows its real mark, the masked key, a status and when the key was last used. You can reveal a key for five seconds, copy, rotate or remove it with undo. Adding or rotating a key opens an inline form that checks the format as you type, then tests the connection before saving.
- [Generation stats](https://uiarc.dev/components/generation-stats/markdown): A live stats strip for a streaming LLM response where time to first token, speed with a sparkline, output tokens and cost count up in tabular numerals beside the model's real mark, then settle and open into a latency and token cost breakdown.
- [AI translate](https://uiarc.dev/components/ai-translate/markdown): A message card where picking a language streams the AI translation in place, sentence by sentence over the dimmed original, with a detected-language chip, a Show original toggle and a status line credited to the model's mark.
- [TL;DR toggle](https://uiarc.dev/components/tldr-toggle/markdown): An article card with a Full, Summary and Key points switch and a length slider. Switching streams an AI summary in place of the article as the card's height springs to fit, and each key point links back to the paragraph it came from, which gets scrolled to and highlighted.
- [Connector setup](https://uiarc.dev/components/connector-setup/markdown): A "Connect your tools" card for an AI assistant. Each app connects inline: it redirects, authorizes and runs a first sync with a progress hairline, then lists the scopes it was granted and offers Disconnect with an inline confirm.
- [Smart form fill](https://uiarc.dev/components/smart-form-fill/markdown): A paste-to-fill form card where AI reads an email signature or messy notes and fills a contact field by field. Each value flashes in with a confidence dot, its source lights up in the pasted text, low-confidence guesses ask for review, and Undo puts the old values back.
- [Enrich column](https://uiarc.dev/components/enrich-column/markdown): An AI enrichment column for a data table, where one prompt runs down every row and each cell shimmers while it works, then settles into a value with its source or a failure you can retry.
- [Ticket router](https://uiarc.dev/components/ticket-router/markdown): A support ticket router where messages from Gmail, Intercom, Slack and Zendesk come in one at a time. An AI classifier labels each one with intent, sentiment and confidence, and the ticket moves into a team lane with an assignee. Low confidence tickets wait in a review lane, and one click there routes them to the suggested team.
- [Ask your data](https://uiarc.dev/components/ask-your-data/markdown): A natural language to chart card: you ask a question, PostgreSQL streams into a collapsible, syntax highlighted panel, the query runs with a rolling row count, and the answer builds as stacked bars, lines or a table, with a one line insight streamed in underneath.
- [Agent cursor](https://uiarc.dev/components/agent-cursor/markdown): A live document where Claude edits like a collaborator. Its labeled cursor comes out of its avatar, selects a paragraph and streams in a rewrite, adds a heading and fixes a typo, while a teammate's cursor reads along. Changes stay tinted until someone accepts or undoes them from a floating review bar.
- [Provider status](https://uiarc.dev/components/provider-status/markdown): A status card for the AI providers your product depends on. Each row shows the provider's real mark, its health as an icon and label, p50 latency and a 30-day uptime bar with a tooltip for each day. An incident row expands into its timeline of updates, and the card checks again on a visible countdown.
- [Training run](https://uiarc.dev/components/training-run/markdown): A fine-tuning job card where a live train and validation loss curve draws across a fixed step axis that doubles as the epoch progress bar. It shows the learning rate, elapsed time, ETA and the latest evals and checkpoints, has Pause and Cancel while it runs, and ends in results with a Deploy button.
- [AI mascot](https://uiarc.dev/components/ai-mascot/markdown): A small assistant character, a soft pebble with pill eyes and a companion dot, that shows what the AI is doing. It breathes and glances when idle, leans in to listen, looks up while the dot orbits its head, reads along the line it writes, squints with a sparkle when done and shakes once with worried brows on an error.
- [Image reveal](https://uiarc.dev/components/image-reveal/markdown): An image generation canvas where a soft, blurred preview made from the image's own colors sharpens top to bottom behind a soft-edged band. It works the way ChatGPT, Midjourney and Gemini show images forming, with fine film grain, a translucent progress pill and calm queued and error states.
- [AI spark](https://uiarc.dev/components/ai-spark/markdown): A brand-quality animated spark mark. Four tapered rays and four lighter diagonals breathe at rest, ripple while thinking, pulse like a heartbeat while writing, then gather and settle when done. Every status change blends from the pose the mark is already in.
- [Pixel mascot](https://uiarc.dev/components/pixel-mascot/markdown): A pixel-art robot that shows what an AI assistant is doing. It idles, thinks, types, celebrates and errors in frame-stepped sprite animations, and stays crisp at every integer size from 24px to 192px.
- [Ghost mascot](https://uiarc.dev/components/ghost-mascot/markdown): A floating ghost mascot whose soft sheet ripples at the hem while it hovers. It blinks when idle, turns toward you to listen, fades a little translucent while thinking, draws a tiny pen line while writing, smiles with a sparkle when done and wobbles once on an error.
- [Cube mascot](https://uiarc.dev/components/cube-mascot/markdown): An isometric cube mascot where three shaded faces and a painted-on face show what the assistant is doing. It turns a quarter turn in eased steps while thinking, prints lines onto the floor while writing, settles with a sparkle when done, and shakes once on error.
- [Tone tuner](https://uiarc.dev/components/tone-tuner/markdown): A brand voice card where two sliders (formality and detail) and Friendly, Confident and Empathetic chips rewrite a customer reply. Each changed sentence crossfades in place, new words can be highlighted against the original, and Copy takes the current version.
- [Upgrade prompt](https://uiarc.dev/components/upgrade-prompt/markdown): An upgrade nudge for the moment someone hits a limit. It shows a usage meter at 50 of 50 AI credits, a rolling price with a monthly and yearly toggle, three concrete unlocks with real model marks, and Upgrade or Maybe later. Upgrading leads into a success state with the new limits, and the card never changes size between states.
- [Referral card](https://uiarc.dev/components/referral-card/markdown): A give-and-get referral card where people copy or share their invite link, invite friends by email as chips, and watch invites move from invited to signed up to earned, with the credit total counting up and a milestone reward unlocking.
- [Trial banner](https://uiarc.dev/components/trial-banner/markdown): A trial status banner where a ring counts down the days left, the copy names what the workspace loses, and the upgrade path is one click away. It comes as a slim banner, a sidebar card or a header pill. It shifts to a warning tone in the last days, has expired and upgraded states, and folds into the pill when dismissed or snoozed.
- [Team switcher](https://uiarc.dev/components/team-switcher/markdown): A workspace switcher like Linear, Vercel or Slack. The trigger shows the current workspace's logo and plan. The menu has search, your role in each workspace and a Cmd+1 to 9 shortcut for each, and lets you create or join a workspace inline. A highlight glides between rows, and switching crossfades the trigger through a short loading state.
- [Live visitors](https://uiarc.dev/components/live-visitors/markdown): A realtime visitors card where the live count rolls digit by digit, new arrivals ping in on a dotted world map, the top pages reorder with bars, and signups and upgrades tick in with country flags.
- [Social proof toast](https://uiarc.dev/components/social-proof-toast/markdown): A stack of social proof notifications for landing and pricing pages, where recent trials, upgrades and verified purchases from people and companies arrive every few seconds. The stack pauses and fans out on hover, and visitors can dismiss any toast.
- [Install snippet](https://uiarc.dev/components/install-snippet/markdown): A "get started in 30 seconds" card where framework tabs, three numbered steps and highlighted snippets take a developer from install to first event. Generate key wipes a fresh API key into the placeholder in place.

### Guidance for AI tools

Starter prompts: A greeting and a grid of starter cards for the empty state of an AI app. The cards are grouped into Write, Code, Analyze and Plan tabs, and a shuffle swaps them with a short staggered crossfade. Picking a card fills the composer, and cards that use a connected app show its mark (Gmail, GitHub, Notion, Linear, Google Calendar). Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## AI mascot

> A small assistant character, a soft pebble with pill eyes and a companion dot, that shows what the AI is doing. It breathes and glances when idle, leans in to listen, looks up while the dot orbits its head, reads along the line it writes, squints with a sparkle when done and shakes once with worried brows on an error.

- Type: Component (special)
- Access: Arc Pro
- Page: https://uiarc.dev/components/ai-mascot
- Markdown: https://uiarc.dev/components/ai-mascot/markdown
- Source file: `registry/components/ai-mascot/ai-mascot.tsx`
- Keywords: special, ai, motion, new, ai mascot, assistant character, ai avatar, thinking animation, generating, loading character, agent face, blob, listening, writing, done sparkle, error shake, empty state, eyes follow cursor, svg animation

### When to use

- Give an assistant a face that shows what it is doing: in a reply header, beside a composer, on an image canvas while it generates, or in an empty state.
- Products that want generation to feel alive and friendly without a spinner, with states that read at 24px.

### When not to use

- Use agent-status when people need the steps, tools and elapsed time of a run, not just a mood.
- Use text-shimmer alone for a plain "Thinking" line in dense interfaces where a character would distract.
- Do not use it as a progress indicator with a known percentage; use a progress bar.

### Installation

AI mascot is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/ai-mascot
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { AiMascot, type MascotStatus } from "@/components/arc/ai-mascot/ai-mascot";

// Inline next to a streaming reply
export function ReplyHeader({ phase }: { phase: "thinking" | "streaming" | "complete" | "failed" }) {
  const status: MascotStatus = phase === "streaming" ? "writing" : phase === "complete" ? "done" : phase === "failed" ? "error" : "thinking";
  return (
    <div style={{ display: "flex", alignItems: "center", gap: 8 }}>
      <AiMascot status={status} size={24} name="Atlas" followPointer={false} />
      <span>Atlas</span>
    </div>
  );
}

// Empty state: large, watching the pointer anywhere on the page
<AiMascot status="idle" size={160} followPointer="page" name="Atlas" />

// In a voice composer while the microphone is open
<AiMascot status={recording ? "listening" : "idle"} size={40} tone="ink" announce />

// Brand color body with light eyes
<AiMascot status="thinking" size={96} color="#7747ff" eyeColor="white" />
```

### API reference

#### AiMascot

A small assistant character drawn in SVG: a soft pebble with pill eyes, a quiet form shade and a companion dot. Six states, each a continuous motion with no loop seam. Idle breathes, floats, blinks and glances around. Listening leans in with wider eyes while the dot pulses like a voice level. Thinking tilts the head and looks up as the dot orbits it, passing behind and in front. Writing looks down and reads along a line the dot writes, then the pen lifts and returns. Done squints happily as the dot turns into a sparkle. Error shakes once and shows worried brows. Status changes blend the two poses over 420ms, never a hard cut, and the eyes follow the pointer on hover.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `status` | `"idle" \| "listening" \| "thinking" \| "writing" \| "done" \| "error"` | – | What the assistant is doing. Leave unset to play through every state on a loop (the docs demo). |
| `size` | `number` | `96` | Width and height in px, from 24 (inline next to a message) to 160 (empty state). Below 56 a compact drawing takes over: tighter framing, bolder eyes and dot, no ground line. |
| `tone` | `"accent" \| "ink" \| "soft"` | `"accent"` | Body color from the theme: the accent with accent-foreground eyes, the foreground ink with background eyes, or a muted surface with a 1px border and foreground eyes. |
| `color` | `string` | – | Any CSS color for the body. Overrides tone; the eyes become a dark mix of it unless eyeColor is set. |
| `eyeColor` | `string` | – | Any CSS color for the eyes and brows. |
| `followPointer` | `boolean \| "page"` | `true` | Eyes follow the pointer while it is over the mascot (true), anywhere on the page ("page", good for empty states) or never. Touch is ignored. Thinking and writing keep their own gaze. |
| `companion` | `boolean` | `true` | Show the companion dot that floats, pulses, orbits, writes and becomes the done sparkle. |
| `ground` | `boolean` | `true` | The soft contact shadow and the writing line under the mascot. Drawn only at 56px and up. |
| `paused` | `boolean` | `false` | Freeze on the current frame. The mascot also pauses by itself off screen and in background tabs, and resumes without a jump. |
| `name` | `string` | `"Assistant"` | Used in the accessible label, for example "Atlas, thinking". |
| `label` | `string` | – | Overrides the whole accessible label. |
| `announce` | `boolean` | `false` | Announce status changes in a polite live region. Turn it on for the one mascot that carries status, not for decorative copies. |
| `onStatusChange` | `(status: MascotStatus) => void` | – | Called when the self-playing loop (status unset) moves to the next state. Use it to sync a caption or a control. |
| `className` | `string` | – | Class on the root span. Set --mascot-body, --mascot-eye, --mascot-dot, --mascot-shade or --mascot-ground here to restyle. |
| `style` | `CSSProperties` | – | Inline style on the root span. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| None | The mascot is a status image and takes no focus. Pair it with a real control when people act on what it shows. |

### Accessibility

- The SVG has role img and a label built from name and status, for example "Atlas, thinking", which updates with every state.
- With announce, status changes are read in a polite live region outside the image. Use it on one mascot per view so screen readers do not hear duplicates.
- Status is never carried by motion alone: each state changes the face (wide eyes, eyes up, eyes down, happy squint, worried brows) and the label. Show a text status next to it where the state matters.
- Pointer following ignores touch and is off under reduced motion.

### Motion

- Every state is a continuous function of time (sums of slow sines, an orbit angle, a writing cycle whose start and end meet at zero length), so loops never restart and have no seam.
- A status change blends the old pose into the new one over 420ms with an ease in and out; a change during a blend starts from the frame on screen. The first paint (and the server render) is the still pose, and the loop eases out of it over the same 420ms, so nothing jumps on mount. Eyes ride a critically damped spring: quick saccades when idle, a soft follow while thinking, tight tracking while writing. Nothing bounces.
- Done passes the eyes through a closed line into the happy squint while the dot shrinks and the sparkle grows in its place. Error shakes once, decaying to rest in about .7s.
- The dot is drawn twice, behind and in front of the body, and switches layers only at the ends of its orbit where it is clear of the body. While it crosses the crown in front it fades into the eye color, so it stays visible on the body.
- Blinks come every 2.4 to 5.2s, sometimes twice, and take 160ms.
- Reduced motion shows a still, representative pose for each state (eyes up with the dot over the head, half a written line, the squint and sparkle, the brows), switches in place and drops every loop, glance, blink and shake.

### Responsive behavior

- A fixed square of size px that never reflows its parent. The drawing scales crisply as vector art at any device pixel ratio.
- Below 56px the compact drawing frames the body tighter and enlarges the eyes, dot and sparkle so they stay legible at 24px.

### Performance

- One requestAnimationFrame loop per mascot writes SVG attributes directly through refs, so React does not re-render per frame; only the self-playing loop sets state, once per state.
- The loop stops off screen (IntersectionObserver) and in hidden tabs, and its clock only runs while visible, so it resumes on the same frame instead of jumping.
- Under reduced motion the loop repaints only when the status changes.
- About fifteen small SVG nodes, with no filters, masks or gradients.

### Notes for AI

- Map your assistant's real phases to status: microphone open is listening, waiting for the first token is thinking, streaming is writing, finished is done, failed is error, otherwise idle.
- Keep thinking short in real use; switch to writing on the first token so the mascot reads what it writes.
- Use size 24 to 32 inline in a message header or composer, 40 to 64 in a side panel header, 96 to 160 in an empty state. Below 56 the drawing simplifies on its own.
- Set name to the assistant's name so the label reads well. Turn announce on for one mascot only.
- Leave status unset only for showcases; in a product always pass it.

### Related

- [Agent status](https://uiarc.dev/components/agent-status/markdown): A compact live status pill for a running AI agent: the agent's mark in a live ring, the current activity and an elapsed timer, opening into the steps so far.
- [Text shimmer](https://uiarc.dev/components/text-shimmer/markdown): Show ongoing work with a calm light across the words.
- [AI spark](https://uiarc.dev/components/ai-spark/markdown): A brand-quality animated spark mark. Four tapered rays and four lighter diagonals breathe at rest, ripple while thinking, pulse like a heartbeat while writing, then gather and settle when done. Every status change blends from the pose the mark is already in.
- [Image reveal](https://uiarc.dev/components/image-reveal/markdown): An image generation canvas where a soft, blurred preview made from the image's own colors sharpens top to bottom behind a soft-edged band. It works the way ChatGPT, Midjourney and Gemini show images forming, with fine film grain, a translucent progress pill and calm queued and error states.
- [Starter prompts](https://uiarc.dev/components/starter-prompts/markdown): A greeting and a grid of starter cards for the empty state of an AI app. The cards are grouped into Write, Code, Analyze and Plan tabs, and a shuffle swaps them with a short staggered crossfade. Picking a card fills the composer, and cards that use a connected app show its mark (Gmail, GitHub, Notion, Linear, Google Calendar).
- [Dictation button](https://uiarc.dev/components/dictation-button/markdown): A chat composer with voice input, where the mic springs into a recording pill with a smooth live waveform, a timer, and cancel and insert buttons. Words stream into the field as you speak, muted until the recognizer settles them.
- [AI chat](https://uiarc.dev/components/blocks/ai-chat/markdown): A full-screen AI chat where answers stream in as markdown with folding reasoning, tool chips and cited sources. People can switch chats and models, edit or retry a message into versions, rate replies and stop a reply mid-stream.
- [Reasoning block](https://uiarc.dev/components/reasoning-block/markdown): The collapsible thinking block of an AI reply. While the model thinks, a shimmering label counts the seconds and the latest reasoning streams underneath. When it finishes, it folds to "Thought for 7s" and opens to show the full reasoning as calm steps with headings.

### Also in ai

- [Tool call](https://uiarc.dev/components/tool-call/markdown): A tool call row for agent transcripts: the tool's mark and the call in plain words, a live state while it runs, and the input and output a click away, with approval and retry when needed.
- [Agent plan](https://uiarc.dev/components/agent-plan/markdown): The plan an agent writes before it acts: edit, reorder or add steps while it is a draft, then watch it work through them as a live checklist.
- [Agent timeline](https://uiarc.dev/components/agent-timeline/markdown): A compact timeline of one orchestrated agent run: the orchestrator and its subagents share a time axis, handoffs draw in between rows, and a playhead replays thinking, tool calls and waiting while the header counts time, tokens and cost. Hover a span for what it did, or click it to trace its handoff path.
- [Context window](https://uiarc.dev/components/context-window/markdown): An AI context window as a grid of 200 cells: the system prompt, tools, files, summary and messages fill it in order, a threshold row marks where compaction starts, and sending a message, attaching a file or compacting shows exactly how much still fits.
- [Source cards](https://uiarc.dev/components/source-cards/markdown): A row of cited sources under an AI answer where cards stream in with real site marks while the model searches, the overflow collapses into a stack of favicons, hovering lifts a preview with the passage, and an inline [n] citation highlights its card.
- [Model card](https://uiarc.dev/components/model-card/markdown): A model details card where switching models rolls every price, limit and score in place, a token slider estimates monthly cost live, and benchmark bars show each model's rank on hover. Compare crossfades to a side-by-side table against any rival with the better values marked, and the card never changes size.
- [AI workflow](https://uiarc.dev/components/ai-workflow/markdown): A Linear-style AI workflow card where a Gmail trigger, a Claude step, a branch and Slack and Linear actions sit on one hairline rail, and a test run glides down it, opening each step's output inline. Steps are added from a compact command menu with real app marks.
- [Code suggestion](https://uiarc.dev/components/code-suggestion/markdown): An AI code edit suggestion where the model's proposed changes stream into a small editor panel as inline diff hunks, and you accept or reject each one, or all at once with Cmd+Enter. Accepted hunks fold into the file with a smooth height change.
- [Ghost text](https://uiarc.dev/components/ghost-text/markdown): An inline AI autocomplete where muted ghost text continues your sentence exactly at the caret and Tab turns it solid in place. Cmd+Right takes it one word at a time, Escape fades it away, and a calm chip shows the model behind it.
- [Image generation](https://uiarc.dev/components/image-generation/markdown): An image studio where each image forms on a dot matrix: a soft halftone wave breathes across the grid, the dots take the colours of the coming photo and grow into a coloured halftone, then blur away into the sharp photo. One large canvas with a mono size label, a filmstrip of four variations, a prompt bar with model and ratio, and upscale with a sweeping dot band, vary or download, with real provider marks and a built-in simulation.
- [Speech player](https://uiarc.dev/components/speech-player/markdown): A read-aloud player for AI replies. The Read aloud button in the message's action row turns into a compact player with play, a scrubbable progress bar, speed and a voice picker, and a highlight follows the spoken word through the reply, karaoke style.
- [Meeting summary](https://uiarc.dev/components/meeting-summary/markdown): An AI meeting notes card: the header shows the Google Meet or Zoom mark, the attendees and the duration. Summary, Decisions and Action items stream in after a short summarizing pass. Hover any line to see the transcript quote it came from, then check off action items or send them to Linear or Notion.
- [Reply draft](https://uiarc.dev/components/reply-draft/markdown): An AI email reply drafter where Claude streams a reply under a received Gmail message. Quick replies steer a fresh draft, tone and length rewrite it with a single crossfade, and you can edit the finished draft before you insert it.
- [Agent handoff](https://uiarc.dev/components/agent-handoff/markdown): A support conversation where an AI assistant hands off to a person. When it transfers, a card shows the summary it passes to the team and the typical wait. The person then joins and takes over, and a thin timeline on the left marks each step.
- [PII redaction](https://uiarc.dev/components/pii-redaction/markdown): A guardrail card where personal data is redacted before the prompt reaches the model. Scan marks each name, email, phone number and card with its type and swaps it for a placeholder like [EMAIL_1]. The safe prompt travels to Claude, and the reply comes back with the original values put back for the person.
- [Response feedback](https://uiarc.dev/components/response-feedback/markdown): A feedback control for AI replies where thumbs down opens an inline panel with reason chips and an optional note, thumbs up fills and asks what was good, and a submit shows a short thank-you before folding back into the row.
- [LLM cost calculator](https://uiarc.dev/components/llm-cost-calculator/markdown): A pricing calculator for LLM workloads. Set tokens per request, requests per day and prompt caching, and eight current models re-rank by monthly cost. Bars glide and prices roll as you drag.
- [Provider keys](https://uiarc.dev/components/provider-keys/markdown): A settings card for bring-your-own-key AI products. Each provider row shows its real mark, the masked key, a status and when the key was last used. You can reveal a key for five seconds, copy, rotate or remove it with undo. Adding or rotating a key opens an inline form that checks the format as you type, then tests the connection before saving.
- [Generation stats](https://uiarc.dev/components/generation-stats/markdown): A live stats strip for a streaming LLM response where time to first token, speed with a sparkline, output tokens and cost count up in tabular numerals beside the model's real mark, then settle and open into a latency and token cost breakdown.
- [AI translate](https://uiarc.dev/components/ai-translate/markdown): A message card where picking a language streams the AI translation in place, sentence by sentence over the dimmed original, with a detected-language chip, a Show original toggle and a status line credited to the model's mark.
- [TL;DR toggle](https://uiarc.dev/components/tldr-toggle/markdown): An article card with a Full, Summary and Key points switch and a length slider. Switching streams an AI summary in place of the article as the card's height springs to fit, and each key point links back to the paragraph it came from, which gets scrolled to and highlighted.
- [Connector setup](https://uiarc.dev/components/connector-setup/markdown): A "Connect your tools" card for an AI assistant. Each app connects inline: it redirects, authorizes and runs a first sync with a progress hairline, then lists the scopes it was granted and offers Disconnect with an inline confirm.
- [Smart form fill](https://uiarc.dev/components/smart-form-fill/markdown): A paste-to-fill form card where AI reads an email signature or messy notes and fills a contact field by field. Each value flashes in with a confidence dot, its source lights up in the pasted text, low-confidence guesses ask for review, and Undo puts the old values back.
- [Enrich column](https://uiarc.dev/components/enrich-column/markdown): An AI enrichment column for a data table, where one prompt runs down every row and each cell shimmers while it works, then settles into a value with its source or a failure you can retry.
- [Ticket router](https://uiarc.dev/components/ticket-router/markdown): A support ticket router where messages from Gmail, Intercom, Slack and Zendesk come in one at a time. An AI classifier labels each one with intent, sentiment and confidence, and the ticket moves into a team lane with an assignee. Low confidence tickets wait in a review lane, and one click there routes them to the suggested team.
- [Ask your data](https://uiarc.dev/components/ask-your-data/markdown): A natural language to chart card: you ask a question, PostgreSQL streams into a collapsible, syntax highlighted panel, the query runs with a rolling row count, and the answer builds as stacked bars, lines or a table, with a one line insight streamed in underneath.
- [Agent cursor](https://uiarc.dev/components/agent-cursor/markdown): A live document where Claude edits like a collaborator. Its labeled cursor comes out of its avatar, selects a paragraph and streams in a rewrite, adds a heading and fixes a typo, while a teammate's cursor reads along. Changes stay tinted until someone accepts or undoes them from a floating review bar.
- [Provider status](https://uiarc.dev/components/provider-status/markdown): A status card for the AI providers your product depends on. Each row shows the provider's real mark, its health as an icon and label, p50 latency and a 30-day uptime bar with a tooltip for each day. An incident row expands into its timeline of updates, and the card checks again on a visible countdown.
- [Training run](https://uiarc.dev/components/training-run/markdown): A fine-tuning job card where a live train and validation loss curve draws across a fixed step axis that doubles as the epoch progress bar. It shows the learning rate, elapsed time, ETA and the latest evals and checkpoints, has Pause and Cancel while it runs, and ends in results with a Deploy button.
- [AI command](https://uiarc.dev/components/ai-command/markdown): A Cmd+K command palette with an AI mode. Search pages and actions, or press Tab to ask a question: the answer streams inside the palette with numbered sources, and the next steps it suggests, like filing a Linear issue or opening a Notion doc, run straight from the list.
- [Pixel mascot](https://uiarc.dev/components/pixel-mascot/markdown): A pixel-art robot that shows what an AI assistant is doing. It idles, thinks, types, celebrates and errors in frame-stepped sprite animations, and stays crisp at every integer size from 24px to 192px.
- [Ghost mascot](https://uiarc.dev/components/ghost-mascot/markdown): A floating ghost mascot whose soft sheet ripples at the hem while it hovers. It blinks when idle, turns toward you to listen, fades a little translucent while thinking, draws a tiny pen line while writing, smiles with a sparkle when done and wobbles once on an error.
- [Cube mascot](https://uiarc.dev/components/cube-mascot/markdown): An isometric cube mascot where three shaded faces and a painted-on face show what the assistant is doing. It turns a quarter turn in eased steps while thinking, prints lines onto the floor while writing, settles with a sparkle when done, and shakes once on error.
- [Tone tuner](https://uiarc.dev/components/tone-tuner/markdown): A brand voice card where two sliders (formality and detail) and Friendly, Confident and Empathetic chips rewrite a customer reply. Each changed sentence crossfades in place, new words can be highlighted against the original, and Copy takes the current version.
- [Upgrade prompt](https://uiarc.dev/components/upgrade-prompt/markdown): An upgrade nudge for the moment someone hits a limit. It shows a usage meter at 50 of 50 AI credits, a rolling price with a monthly and yearly toggle, three concrete unlocks with real model marks, and Upgrade or Maybe later. Upgrading leads into a success state with the new limits, and the card never changes size between states.
- [Referral card](https://uiarc.dev/components/referral-card/markdown): A give-and-get referral card where people copy or share their invite link, invite friends by email as chips, and watch invites move from invited to signed up to earned, with the credit total counting up and a milestone reward unlocking.
- [Trial banner](https://uiarc.dev/components/trial-banner/markdown): A trial status banner where a ring counts down the days left, the copy names what the workspace loses, and the upgrade path is one click away. It comes as a slim banner, a sidebar card or a header pill. It shifts to a warning tone in the last days, has expired and upgraded states, and folds into the pill when dismissed or snoozed.
- [Team switcher](https://uiarc.dev/components/team-switcher/markdown): A workspace switcher like Linear, Vercel or Slack. The trigger shows the current workspace's logo and plan. The menu has search, your role in each workspace and a Cmd+1 to 9 shortcut for each, and lets you create or join a workspace inline. A highlight glides between rows, and switching crossfades the trigger through a short loading state.
- [Live visitors](https://uiarc.dev/components/live-visitors/markdown): A realtime visitors card where the live count rolls digit by digit, new arrivals ping in on a dotted world map, the top pages reorder with bars, and signups and upgrades tick in with country flags.
- [Social proof toast](https://uiarc.dev/components/social-proof-toast/markdown): A stack of social proof notifications for landing and pricing pages, where recent trials, upgrades and verified purchases from people and companies arrive every few seconds. The stack pauses and fans out on hover, and visitors can dismiss any toast.
- [Install snippet](https://uiarc.dev/components/install-snippet/markdown): A "get started in 30 seconds" card where framework tabs, three numbered steps and highlighted snippets take a developer from install to first event. Generate key wipes a fresh API key into the placeholder in place.

### Guidance for AI tools

AI mascot: A small assistant character, a soft pebble with pill eyes and a companion dot, that shows what the AI is doing. It breathes and glances when idle, leans in to listen, looks up while the dot orbits its head, reads along the line it writes, squints with a sparkle when done and shakes once with worried brows on an error. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Image reveal

> An image generation canvas where a soft, blurred preview made from the image's own colors sharpens top to bottom behind a soft-edged band. It works the way ChatGPT, Midjourney and Gemini show images forming, with fine film grain, a translucent progress pill and calm queued and error states.

- Type: Component (special)
- Access: Arc Pro
- Page: https://uiarc.dev/components/image-reveal
- Markdown: https://uiarc.dev/components/image-reveal/markdown
- Source file: `registry/components/image-reveal/image-reveal.tsx`
- Dependencies: motion, lucide-react
- Keywords: special, ai, motion, new, image generation, ai image, generating, progressive reveal, diffusion, denoising, latent noise, sampler steps, vae decode, progress, canvas, image placeholder, midjourney style, chatgpt image

### When to use

- Showing an image model's progress on a canvas or in a chat reply.
- A batch of image variations sampling side by side.
- A queued image job that should feel alive before it starts.

### When not to use

- Plain image loading from a CDN; use a blur-up placeholder or a skeleton.
- Text generation or tool calls; use text-shimmer or tool-call.
- Determinate file uploads; use progress.

### Installation

Image reveal is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/image-reveal
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { ImageReveal } from "@/components/arc/image-reveal/image-reveal";

export function GeneratedImage({ job }: { job: { status: "queued" | "generating" | "done" | "error"; step: number; url?: string } }) {
  return (
    <ImageReveal
      src={job.url}
      alt="A calm alpine lake at golden hour"
      status={job.status}
      progress={job.step / 30}
      steps={30}
      aspectRatio="4 / 5"
      onRetry={() => retry(job)}
    />
  );
}
```

### Examples

#### Estimated duration, no progress events

```tsx
<ImageReveal src={url} status={url ? "done" : "generating"} duration={8000} />
```

#### Batch of four with a Generate again button

```tsx
const [run, setRun] = useState(0);

<div style={{ display: "grid", gridTemplateColumns: "1fr 1fr", gap: 8 }}>
  {urls.map((url, index) => (
    <ImageReveal key={index} src={url} size="sm" seed={index + 1}
      runKey={run} loop={false} duration={4200} style={{ maxInlineSize: "none" }} />
  ))}
</div>
<Button onClick={() => setRun(run + 1)}>Generate again</Button>
```

### API reference

#### ImageReveal

Image generation the way a diffusion model samples: pure latent noise, then one denoising step at a time the prediction resolves from color blobs to composition to shapes while the noise falls away, then a tiled decode lands the sharp image and the pill shows how long it took. With no props it plays a looping, simulated generation over sample photos.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `src` | `string` | – | Final image URL. Cross-origin images work (pixels are never read back). Omit to cycle through sample photos. |
| `alt` | `string` | `"Generated image"` | Alt text for the final image, used as the canvas label once done. |
| `status` | `"queued" \| "generating" \| "decoding" \| "done" \| "error"` | – | Controlled state. Omit for auto mode, which runs queued, sampling over `duration`, decoding over `decodeDuration`, then done. Going straight from generating to done still plays the decode. Every change transitions smoothly. |
| `progress` | `number` | – | Controlled progress from 0 to 1 while generating, usually step / total. The canvas moves one denoising step at a time, like the real sampler. Omit to step at a constant rate over `duration`. |
| `duration` | `number` | `4600` | Milliseconds the sampling steps take when `progress` is not controlled. |
| `decodeDuration` | `number` | `560` | Milliseconds the tiled decode takes after the last step. |
| `steps` | `number` | `30` | Sampling steps. Each is one visible denoising step, and the pill shows it as 18 / 30 (tabular numerals, reserved width). |
| `aspectRatio` | `number \| string` | `1` | Width over height, as a number (1.5) or a CSS ratio ("4 / 5"). The image is cover-cropped to it. |
| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Overlay scale and corner radius. "sm" (grids, thumbnails) shows only the ring and 18 / 30; "md" and "lg" add the Denoising label. The canvas always renders at device pixel ratio. |
| `color` | `string` | – | Any CSS color for the progress ring. Defaults to the accent. |
| `showProgress` | `boolean` | `true` | Shows the translucent progress pill. It fades out shortly after the image resolves. |
| `sheen` | `boolean` | `true` | Plays one soft light sheen across the image when it resolves. Skipped with reduced motion. |
| `queueLabel` | `string` | `"Queued"` | Chip label while queued, such as "Queued, 2 ahead". |
| `errorMessage` | `string` | `"Generation failed"` | Message in the error state. |
| `onRetry` | `() => void` | – | Shows a Retry button in the error state. |
| `onStatusChange` | `(status: ImageRevealStatus) => void` | – | Called when the displayed status changes, including auto mode transitions. |
| `onComplete` | `() => void` | – | Called once per run when the final image is fully resolved and crisp. |
| `autoPlay` | `boolean` | `true` | Auto mode only: starts generating on mount. |
| `loop` | `boolean` | `true` | Auto mode only: after `holdDuration` the image blurs back out and generates again. |
| `startDelay` | `number` | `0` | Auto mode only: extra queue time in milliseconds before a run, for staggered grids. |
| `queueDuration` | `number` | `900` | Auto mode only: milliseconds in the queue before each run. |
| `holdDuration` | `number` | `2600` | Auto mode only: milliseconds the finished image holds before a loop restarts. |
| `runKey` | `string \| number` | – | Auto mode only: change it to blur back out and run again (a Generate again button). |
| `seed` | `number` | `1` | Seeds the latent noise, so tiles in a batch differ and a replay of the same seed shows the same noise. Pass the model's real seed. |
| `className` | `string` | – | Class on the root. The root is 100% wide with a 560px max width; override max-inline-size in grids. |
| `style` | `CSSProperties` | – | Inline styles on the root. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Tab | Moves to the Retry button in the error state. The canvas itself is not focusable. |
| Enter / Space | Activates Retry. |

### Accessibility

- The canvas has role img; its label names the state while generating and becomes the alt text once done.
- A polite live region announces Queued, Generating image, Image ready and the error message, not every step. Auto mode appends simulated.
- While generating, the pill is a progressbar with aria-valuenow and an aria-valuetext of Step n of total.
- Status is never color alone: the pill pairs a ring or check with a short label, and the error state pairs an alert icon with its message.

### Motion

- Queued is the calm surface tone with one broad, soft shimmer that starts and ends fully off canvas, so its 2.6s loop has no seam.
- Generating starts from pure latent noise: per-cell gaussian color at about 1/8 of the output resolution, drawn as crisp blocks, with a new seeded frame every step crossfaded in 35ms.
- Under the noise is the model's current prediction, built from the image itself (6 to 96 px wide copies, smoothly upscaled). It moves along that chain per step, so color blobs come first, then composition, then shapes.
- Noise strength follows a schedule that drops fast early, so the composition reads by about a third of the steps and the last steps only refine. Steps run at a constant rate, like a real sampler.
- After the last step a tiled decode lands the sharp image tile by tile in raster order, each tile crossfading in, and the pill switches to Decoding.
- One soft-light sheen sweeps across once at completion (1.1s), the pill shows the elapsed time, then fades out.
- Starting over or swapping the photo fades the decoded image straight back to the surface before anything resets underneath, and a photo swap crossfades from a snapshot, so there is never a hard cut.
- Pill labels crossfade (100ms out, 160ms in after a 60ms gap) and the pill width springs with no bounce.
- Reduced motion keeps one static noise frame, decodes as a single crossfade and drops the shimmer travel, spinner and sheen.
- The frame loop stops off screen (IntersectionObserver) and in background tabs, and draws nothing once the image is resolved.

### Responsive behavior

- Fills its container width (up to 560px by default) and keeps the given aspect ratio.
- The canvas renders at device pixel ratio (capped at 2), so it stays crisp from a 120px thumbnail to a large canvas.
- Latent noise is sized in CSS pixels (about 6 px cells), so it reads as the same latent grid at every size.

### Performance

- Canvas 2D only, no WebGL and no per-pixel work per frame: a few drawImage calls. Noise is generated once per step at latent resolution (a few thousand cells).
- The prediction chain is built once per image and size; decode tiles are direct copies from the sharp image.
- Frames stop drawing when the image is resolved and nothing changes, and the loop stops entirely off screen.
- Images are decoded off the main thread before use.

### Notes for AI

- Use for image generation surfaces: an image canvas, an inline image in a chat reply, a variations grid, or an empty state while a first image renders.
- Wire a real job by passing status and progress (step / total), plus the job's seed. Pass decoding while the VAE decodes if the backend reports it. With no progress events, pass status only and an estimated duration.
- Use size="sm" in grids. A batch samples in lockstep, so give every tile the same duration and its own seed, and override max-inline-size through className or style.
- The preview is sampled from the final image, so pass src as soon as a preview or final URL exists; until it loads the tile stays in the calm queued look.
- For text or agent work in progress, pick a text shimmer or an agent status component instead.

### Related

- [Text shimmer](https://uiarc.dev/components/text-shimmer/markdown): Show ongoing work with a calm light across the words.
- [Agent status](https://uiarc.dev/components/agent-status/markdown): A compact live status pill for a running AI agent: the agent's mark in a live ring, the current activity and an elapsed timer, opening into the steps so far.
- [Tool call](https://uiarc.dev/components/tool-call/markdown): A tool call row for agent transcripts: the tool's mark and the call in plain words, a live state while it runs, and the input and output a click away, with approval and retry when needed.
- [Progress](https://uiarc.dev/components/progress/markdown): Show how much of a known task is complete.

### Also in ai

- [Agent plan](https://uiarc.dev/components/agent-plan/markdown): The plan an agent writes before it acts: edit, reorder or add steps while it is a draft, then watch it work through them as a live checklist.
- [Agent timeline](https://uiarc.dev/components/agent-timeline/markdown): A compact timeline of one orchestrated agent run: the orchestrator and its subagents share a time axis, handoffs draw in between rows, and a playhead replays thinking, tool calls and waiting while the header counts time, tokens and cost. Hover a span for what it did, or click it to trace its handoff path.
- [Context window](https://uiarc.dev/components/context-window/markdown): An AI context window as a grid of 200 cells: the system prompt, tools, files, summary and messages fill it in order, a threshold row marks where compaction starts, and sending a message, attaching a file or compacting shows exactly how much still fits.
- [Reasoning block](https://uiarc.dev/components/reasoning-block/markdown): The collapsible thinking block of an AI reply. While the model thinks, a shimmering label counts the seconds and the latest reasoning streams underneath. When it finishes, it folds to "Thought for 7s" and opens to show the full reasoning as calm steps with headings.
- [Source cards](https://uiarc.dev/components/source-cards/markdown): A row of cited sources under an AI answer where cards stream in with real site marks while the model searches, the overflow collapses into a stack of favicons, hovering lifts a preview with the passage, and an inline [n] citation highlights its card.
- [Model card](https://uiarc.dev/components/model-card/markdown): A model details card where switching models rolls every price, limit and score in place, a token slider estimates monthly cost live, and benchmark bars show each model's rank on hover. Compare crossfades to a side-by-side table against any rival with the better values marked, and the card never changes size.
- [AI workflow](https://uiarc.dev/components/ai-workflow/markdown): A Linear-style AI workflow card where a Gmail trigger, a Claude step, a branch and Slack and Linear actions sit on one hairline rail, and a test run glides down it, opening each step's output inline. Steps are added from a compact command menu with real app marks.
- [Code suggestion](https://uiarc.dev/components/code-suggestion/markdown): An AI code edit suggestion where the model's proposed changes stream into a small editor panel as inline diff hunks, and you accept or reject each one, or all at once with Cmd+Enter. Accepted hunks fold into the file with a smooth height change.
- [Ghost text](https://uiarc.dev/components/ghost-text/markdown): An inline AI autocomplete where muted ghost text continues your sentence exactly at the caret and Tab turns it solid in place. Cmd+Right takes it one word at a time, Escape fades it away, and a calm chip shows the model behind it.
- [Image generation](https://uiarc.dev/components/image-generation/markdown): An image studio where each image forms on a dot matrix: a soft halftone wave breathes across the grid, the dots take the colours of the coming photo and grow into a coloured halftone, then blur away into the sharp photo. One large canvas with a mono size label, a filmstrip of four variations, a prompt bar with model and ratio, and upscale with a sweeping dot band, vary or download, with real provider marks and a built-in simulation.
- [Dictation button](https://uiarc.dev/components/dictation-button/markdown): A chat composer with voice input, where the mic springs into a recording pill with a smooth live waveform, a timer, and cancel and insert buttons. Words stream into the field as you speak, muted until the recognizer settles them.
- [Speech player](https://uiarc.dev/components/speech-player/markdown): A read-aloud player for AI replies. The Read aloud button in the message's action row turns into a compact player with play, a scrubbable progress bar, speed and a voice picker, and a highlight follows the spoken word through the reply, karaoke style.
- [Meeting summary](https://uiarc.dev/components/meeting-summary/markdown): An AI meeting notes card: the header shows the Google Meet or Zoom mark, the attendees and the duration. Summary, Decisions and Action items stream in after a short summarizing pass. Hover any line to see the transcript quote it came from, then check off action items or send them to Linear or Notion.
- [Reply draft](https://uiarc.dev/components/reply-draft/markdown): An AI email reply drafter where Claude streams a reply under a received Gmail message. Quick replies steer a fresh draft, tone and length rewrite it with a single crossfade, and you can edit the finished draft before you insert it.
- [Agent handoff](https://uiarc.dev/components/agent-handoff/markdown): A support conversation where an AI assistant hands off to a person. When it transfers, a card shows the summary it passes to the team and the typical wait. The person then joins and takes over, and a thin timeline on the left marks each step.
- [PII redaction](https://uiarc.dev/components/pii-redaction/markdown): A guardrail card where personal data is redacted before the prompt reaches the model. Scan marks each name, email, phone number and card with its type and swaps it for a placeholder like [EMAIL_1]. The safe prompt travels to Claude, and the reply comes back with the original values put back for the person.
- [Response feedback](https://uiarc.dev/components/response-feedback/markdown): A feedback control for AI replies where thumbs down opens an inline panel with reason chips and an optional note, thumbs up fills and asks what was good, and a submit shows a short thank-you before folding back into the row.
- [LLM cost calculator](https://uiarc.dev/components/llm-cost-calculator/markdown): A pricing calculator for LLM workloads. Set tokens per request, requests per day and prompt caching, and eight current models re-rank by monthly cost. Bars glide and prices roll as you drag.
- [Provider keys](https://uiarc.dev/components/provider-keys/markdown): A settings card for bring-your-own-key AI products. Each provider row shows its real mark, the masked key, a status and when the key was last used. You can reveal a key for five seconds, copy, rotate or remove it with undo. Adding or rotating a key opens an inline form that checks the format as you type, then tests the connection before saving.
- [Generation stats](https://uiarc.dev/components/generation-stats/markdown): A live stats strip for a streaming LLM response where time to first token, speed with a sparkline, output tokens and cost count up in tabular numerals beside the model's real mark, then settle and open into a latency and token cost breakdown.
- [AI translate](https://uiarc.dev/components/ai-translate/markdown): A message card where picking a language streams the AI translation in place, sentence by sentence over the dimmed original, with a detected-language chip, a Show original toggle and a status line credited to the model's mark.
- [TL;DR toggle](https://uiarc.dev/components/tldr-toggle/markdown): An article card with a Full, Summary and Key points switch and a length slider. Switching streams an AI summary in place of the article as the card's height springs to fit, and each key point links back to the paragraph it came from, which gets scrolled to and highlighted.
- [Connector setup](https://uiarc.dev/components/connector-setup/markdown): A "Connect your tools" card for an AI assistant. Each app connects inline: it redirects, authorizes and runs a first sync with a progress hairline, then lists the scopes it was granted and offers Disconnect with an inline confirm.
- [Smart form fill](https://uiarc.dev/components/smart-form-fill/markdown): A paste-to-fill form card where AI reads an email signature or messy notes and fills a contact field by field. Each value flashes in with a confidence dot, its source lights up in the pasted text, low-confidence guesses ask for review, and Undo puts the old values back.
- [Enrich column](https://uiarc.dev/components/enrich-column/markdown): An AI enrichment column for a data table, where one prompt runs down every row and each cell shimmers while it works, then settles into a value with its source or a failure you can retry.
- [Ticket router](https://uiarc.dev/components/ticket-router/markdown): A support ticket router where messages from Gmail, Intercom, Slack and Zendesk come in one at a time. An AI classifier labels each one with intent, sentiment and confidence, and the ticket moves into a team lane with an assignee. Low confidence tickets wait in a review lane, and one click there routes them to the suggested team.
- [Ask your data](https://uiarc.dev/components/ask-your-data/markdown): A natural language to chart card: you ask a question, PostgreSQL streams into a collapsible, syntax highlighted panel, the query runs with a rolling row count, and the answer builds as stacked bars, lines or a table, with a one line insight streamed in underneath.
- [Agent cursor](https://uiarc.dev/components/agent-cursor/markdown): A live document where Claude edits like a collaborator. Its labeled cursor comes out of its avatar, selects a paragraph and streams in a rewrite, adds a heading and fixes a typo, while a teammate's cursor reads along. Changes stay tinted until someone accepts or undoes them from a floating review bar.
- [Provider status](https://uiarc.dev/components/provider-status/markdown): A status card for the AI providers your product depends on. Each row shows the provider's real mark, its health as an icon and label, p50 latency and a 30-day uptime bar with a tooltip for each day. An incident row expands into its timeline of updates, and the card checks again on a visible countdown.
- [Training run](https://uiarc.dev/components/training-run/markdown): A fine-tuning job card where a live train and validation loss curve draws across a fixed step axis that doubles as the epoch progress bar. It shows the learning rate, elapsed time, ETA and the latest evals and checkpoints, has Pause and Cancel while it runs, and ends in results with a Deploy button.
- [AI command](https://uiarc.dev/components/ai-command/markdown): A Cmd+K command palette with an AI mode. Search pages and actions, or press Tab to ask a question: the answer streams inside the palette with numbered sources, and the next steps it suggests, like filing a Linear issue or opening a Notion doc, run straight from the list.
- [Starter prompts](https://uiarc.dev/components/starter-prompts/markdown): A greeting and a grid of starter cards for the empty state of an AI app. The cards are grouped into Write, Code, Analyze and Plan tabs, and a shuffle swaps them with a short staggered crossfade. Picking a card fills the composer, and cards that use a connected app show its mark (Gmail, GitHub, Notion, Linear, Google Calendar).
- [AI mascot](https://uiarc.dev/components/ai-mascot/markdown): A small assistant character, a soft pebble with pill eyes and a companion dot, that shows what the AI is doing. It breathes and glances when idle, leans in to listen, looks up while the dot orbits its head, reads along the line it writes, squints with a sparkle when done and shakes once with worried brows on an error.
- [AI spark](https://uiarc.dev/components/ai-spark/markdown): A brand-quality animated spark mark. Four tapered rays and four lighter diagonals breathe at rest, ripple while thinking, pulse like a heartbeat while writing, then gather and settle when done. Every status change blends from the pose the mark is already in.
- [Pixel mascot](https://uiarc.dev/components/pixel-mascot/markdown): A pixel-art robot that shows what an AI assistant is doing. It idles, thinks, types, celebrates and errors in frame-stepped sprite animations, and stays crisp at every integer size from 24px to 192px.
- [Ghost mascot](https://uiarc.dev/components/ghost-mascot/markdown): A floating ghost mascot whose soft sheet ripples at the hem while it hovers. It blinks when idle, turns toward you to listen, fades a little translucent while thinking, draws a tiny pen line while writing, smiles with a sparkle when done and wobbles once on an error.
- [Cube mascot](https://uiarc.dev/components/cube-mascot/markdown): An isometric cube mascot where three shaded faces and a painted-on face show what the assistant is doing. It turns a quarter turn in eased steps while thinking, prints lines onto the floor while writing, settles with a sparkle when done, and shakes once on error.
- [Tone tuner](https://uiarc.dev/components/tone-tuner/markdown): A brand voice card where two sliders (formality and detail) and Friendly, Confident and Empathetic chips rewrite a customer reply. Each changed sentence crossfades in place, new words can be highlighted against the original, and Copy takes the current version.
- [Upgrade prompt](https://uiarc.dev/components/upgrade-prompt/markdown): An upgrade nudge for the moment someone hits a limit. It shows a usage meter at 50 of 50 AI credits, a rolling price with a monthly and yearly toggle, three concrete unlocks with real model marks, and Upgrade or Maybe later. Upgrading leads into a success state with the new limits, and the card never changes size between states.
- [Referral card](https://uiarc.dev/components/referral-card/markdown): A give-and-get referral card where people copy or share their invite link, invite friends by email as chips, and watch invites move from invited to signed up to earned, with the credit total counting up and a milestone reward unlocking.
- [Trial banner](https://uiarc.dev/components/trial-banner/markdown): A trial status banner where a ring counts down the days left, the copy names what the workspace loses, and the upgrade path is one click away. It comes as a slim banner, a sidebar card or a header pill. It shifts to a warning tone in the last days, has expired and upgraded states, and folds into the pill when dismissed or snoozed.
- [Team switcher](https://uiarc.dev/components/team-switcher/markdown): A workspace switcher like Linear, Vercel or Slack. The trigger shows the current workspace's logo and plan. The menu has search, your role in each workspace and a Cmd+1 to 9 shortcut for each, and lets you create or join a workspace inline. A highlight glides between rows, and switching crossfades the trigger through a short loading state.
- [Live visitors](https://uiarc.dev/components/live-visitors/markdown): A realtime visitors card where the live count rolls digit by digit, new arrivals ping in on a dotted world map, the top pages reorder with bars, and signups and upgrades tick in with country flags.
- [Social proof toast](https://uiarc.dev/components/social-proof-toast/markdown): A stack of social proof notifications for landing and pricing pages, where recent trials, upgrades and verified purchases from people and companies arrive every few seconds. The stack pauses and fans out on hover, and visitors can dismiss any toast.
- [Install snippet](https://uiarc.dev/components/install-snippet/markdown): A "get started in 30 seconds" card where framework tabs, three numbered steps and highlighted snippets take a developer from install to first event. Generate key wipes a fresh API key into the placeholder in place.

### Guidance for AI tools

Image reveal: An image generation canvas where a soft, blurred preview made from the image's own colors sharpens top to bottom behind a soft-edged band. It works the way ChatGPT, Midjourney and Gemini show images forming, with fine film grain, a translucent progress pill and calm queued and error states. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## AI spark

> A brand-quality animated spark mark. Four tapered rays and four lighter diagonals breathe at rest, ripple while thinking, pulse like a heartbeat while writing, then gather and settle when done. Every status change blends from the pose the mark is already in.

- Type: Component (special)
- Access: Arc Pro
- Page: https://uiarc.dev/components/ai-spark
- Markdown: https://uiarc.dev/components/ai-spark/markdown
- Source file: `registry/components/ai-spark/ai-spark.tsx`
- Dependencies: motion
- Keywords: special, ai, motion, new, ai spark, ai sparkle, asterisk, thinking indicator, generating indicator, ai loader, ai logo animation, working indicator, ai status mark, spinner alternative, ai avatar, sparkle animation

### When to use

- Showing that an assistant is thinking or writing, inline above a streaming reply.
- A send or generate button that turns into a working indicator inside a composer.
- An image or canvas tool that needs a calm, branded working mark over the canvas while a render runs.
- Empty states and onboarding where a 64 to 96px hero mark gives the AI feature an identity.

### When not to use

- Determinate progress with a known percentage; use a progress bar or the generation stats component instead.
- Multi step agent runs where each step needs its own state and detail; use agent-status or agent-run.
- Plain text loading lines with no mark; use text-shimmer.

### Installation

AI spark is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/ai-spark
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { AiSpark } from "@/components/arc/ai-spark/ai-spark";

export function ReplyStatus({ phase }: { phase: "thinking" | "generating" | "done" }) {
  return <AiSpark variant="pill" status={phase} />;
}
```

### Examples

#### Assistant avatar

```tsx
<AiSpark variant="avatar" size={32} status={phase} announce={false} />
```

#### Inline in a sentence

```tsx
<p>
  <AiSpark size="1em" tone="inherit" status="generating" announce={false} /> Drafting a reply to Maya Chen
</p>
```

#### Custom progress label

```tsx
<AiSpark variant="pill" status="thinking" label="Searching 4 sources" />
```

#### Hero mark in an empty state

```tsx
<AiSpark size={96} status="idle" />
```

### API reference

#### AiSpark

An animated spark mark that shows an AI at work: four tapered primary rays and four lighter diagonal rays around a soft core. Each status is its own motion, and every change blends from the current pose, so states never hard cut. Use variant="pill" for a status label or variant="avatar" for a round tile.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `status` | `"idle" \| "thinking" \| "generating" \| "done" \| "error"` | – | What the AI is doing. Leave it unset and the spark plays through idle, thinking, generating and done on its own. |
| `size` | `number \| string` | `24 (32 for the avatar, 16 in the pill)` | Size in px, or any CSS length such as "1em" to match surrounding text. The mark itself, the avatar tile, or the mark inside the pill. Proportions are hinted optically: small marks get heavier rays and under 18px the diagonals become dots. |
| `tone` | `"accent" \| "foreground" \| "muted" \| "inherit"` | `"accent"` | Semantic color of the mark; the diagonals and core use a lighter tone of the same color. Error always eases to a muted danger tone. |
| `color` | `string` | – | Any CSS color, overriding tone. |
| `variant` | `"mark" \| "pill" \| "avatar"` | `"mark"` | mark renders the spark alone. pill adds a crossfading status label (Ready, Thinking, Writing, Done, Couldn't finish) in a quiet bordered capsule. avatar sets the mark in a round, lightly tinted tile for message avatars and icon buttons. |
| `label` | `string` | – | Pill text, overriding the built-in label for the current status, for example "Reading 12 files". |
| `speed` | `number` | `1` | Multiplies every loop and spin speed. |
| `twinkle` | `boolean` | `true` | A very slow breathing twinkle while idle. Turn it off for a fully still idle mark. |
| `paused` | `boolean` | `false` | Freezes the animation in place; resuming continues from the same phase. |
| `announce` | `boolean` | `true` | Announce status changes through a polite live region. Turn it off for decorative copies so only one spark speaks. |
| `aria-label` | `string` | – | Accessible name. Defaults to a phrase for the status, such as "AI is thinking". |
| `className` | `string` | – | Class on the root span. |
| `style` | `CSSProperties` | – | Inline styles on the root span. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| None | The spark is a status indicator and takes no focus. Put controls such as Stop next to it. |

### Accessibility

- The root is a polite live region (role="status"): a status change is announced once, as "AI is thinking" for the mark or as the label text for the pill.
- aria-busy is set while thinking or generating.
- Status is never color alone: each state has its own shape and motion, error shortens the rays and dims the diagonals, and the pill adds a text label.
- Set announce={false} on decorative copies (lists, size ladders) so screen readers hear one voice. They then render as role="img" with an accessible name.
- The SVG is aria-hidden; the name comes from the label or a visually hidden phrase.

### Motion

- One requestAnimationFrame loop per spark writes eight small ray paths, a core radius and two group transforms. React never re-renders per frame and nothing triggers layout.
- Every status is a periodic function of time and of position around the ring, so idle, thinking and generating loop with no seam.
- Idle: a 6.4s breath of the whole mark while one diagonal at a time softly reaches out. Thinking: one crest ripples around the ring every 1.9s, with small per-ray phase offsets, while the mark turns at 26 degrees per second. Generating: a lub dub heartbeat every 1.04s, axes firing in sequence and diagonals answering, 46 degrees per second, with two particles orbiting just outside the rays (40px and up).
- Done: the rays gather toward the center in 170ms and ease back to rest over 510ms with no overshoot, while the spin glides into the home angle on an ease-out whose speed only falls.
- Error: one small decaying shake over 460ms, shorter rays, dimmer diagonals and a muted danger tone over 320ms.
- Status changes blend over 420 to 560ms from wherever the mark is; an interrupted blend becomes the new starting point, and the gather and shake gestures always finish smoothly even if the status changes again. Pill labels crossfade (100ms out, 160ms in, 2px rise) while the pill eases to its new width.
- Reduced motion: no spin, loops, gather, shake or particles. Each status shows a still pose with a 200ms blend between poses and the color change.
- The loop pauses when the spark is off screen or the tab is hidden, and stops entirely once a resting state has settled.

### Responsive behavior

- The mark has a fixed footprint at any status, so it never shifts surrounding layout.
- Crisp from 12px to 120px and beyond: geometry lives in a 100 unit viewBox, ray weight is hinted on a log scale by rendered size, and CSS lengths are measured so hinting still applies.
- The pill keeps a 28px height and only animates its label width.

### Performance

- Eight SVG paths, three circles and one rAF loop per spark; resting states stop the loop entirely, and off screen sparks do not tick.
- No canvas, no filters, no blur, no gradients; depth comes from two tones of one color.
- The pill label shimmer runs only while thinking or generating.

### Notes for AI

- Map your stream lifecycle to status: request sent or tool running -> thinking, first token until the last -> generating, finished -> done, failed or aborted -> error. Return to idle when the composer is ready again.
- Use variant="pill" with label for specific progress ("Searching 4 sources", "Drawing"); keep labels to one or two words.
- Use size="1em" and tone="inherit" to drop the mark inline into a sentence or a button so it matches the text.
- Use one spark per active generation. For many rows, render a static mark (status="idle", twinkle={false}) and animate only the active row.
- Use variant="avatar" next to assistant messages or inside an icon button; size sets the tile and the mark is 56% of it.
- Leaving status unset makes it self-play, which is only meant for demos and marketing pages.

### Related

- [Text shimmer](https://uiarc.dev/components/text-shimmer/markdown): Show ongoing work with a calm light across the words.
- [Agent status](https://uiarc.dev/components/agent-status/markdown): A compact live status pill for a running AI agent: the agent's mark in a live ring, the current activity and an elapsed timer, opening into the steps so far.
- [Reasoning block](https://uiarc.dev/components/reasoning-block/markdown): The collapsible thinking block of an AI reply. While the model thinks, a shimmering label counts the seconds and the latest reasoning streams underneath. When it finishes, it folds to "Thought for 7s" and opens to show the full reasoning as calm steps with headings.
- [AI mascot](https://uiarc.dev/components/ai-mascot/markdown): A small assistant character, a soft pebble with pill eyes and a companion dot, that shows what the AI is doing. It breathes and glances when idle, leans in to listen, looks up while the dot orbits its head, reads along the line it writes, squints with a sparkle when done and shakes once with worried brows on an error.
- [AI chat](https://uiarc.dev/components/blocks/ai-chat/markdown): A full-screen AI chat where answers stream in as markdown with folding reasoning, tool chips and cited sources. People can switch chats and models, edit or retry a message into versions, rate replies and stop a reply mid-stream.
- [AI composer](https://uiarc.dev/components/blocks/ai-composer/markdown): The prompt box at the bottom of an AI app: files upload in place, / opens commands, @ inserts mentions, a model and effort menu sits in the toolbar, and the send button turns into a stop control ringed by the reply's progress.

### Also in ai

- [Tool call](https://uiarc.dev/components/tool-call/markdown): A tool call row for agent transcripts: the tool's mark and the call in plain words, a live state while it runs, and the input and output a click away, with approval and retry when needed.
- [Agent plan](https://uiarc.dev/components/agent-plan/markdown): The plan an agent writes before it acts: edit, reorder or add steps while it is a draft, then watch it work through them as a live checklist.
- [Agent timeline](https://uiarc.dev/components/agent-timeline/markdown): A compact timeline of one orchestrated agent run: the orchestrator and its subagents share a time axis, handoffs draw in between rows, and a playhead replays thinking, tool calls and waiting while the header counts time, tokens and cost. Hover a span for what it did, or click it to trace its handoff path.
- [Context window](https://uiarc.dev/components/context-window/markdown): An AI context window as a grid of 200 cells: the system prompt, tools, files, summary and messages fill it in order, a threshold row marks where compaction starts, and sending a message, attaching a file or compacting shows exactly how much still fits.
- [Source cards](https://uiarc.dev/components/source-cards/markdown): A row of cited sources under an AI answer where cards stream in with real site marks while the model searches, the overflow collapses into a stack of favicons, hovering lifts a preview with the passage, and an inline [n] citation highlights its card.
- [Model card](https://uiarc.dev/components/model-card/markdown): A model details card where switching models rolls every price, limit and score in place, a token slider estimates monthly cost live, and benchmark bars show each model's rank on hover. Compare crossfades to a side-by-side table against any rival with the better values marked, and the card never changes size.
- [AI workflow](https://uiarc.dev/components/ai-workflow/markdown): A Linear-style AI workflow card where a Gmail trigger, a Claude step, a branch and Slack and Linear actions sit on one hairline rail, and a test run glides down it, opening each step's output inline. Steps are added from a compact command menu with real app marks.
- [Code suggestion](https://uiarc.dev/components/code-suggestion/markdown): An AI code edit suggestion where the model's proposed changes stream into a small editor panel as inline diff hunks, and you accept or reject each one, or all at once with Cmd+Enter. Accepted hunks fold into the file with a smooth height change.
- [Ghost text](https://uiarc.dev/components/ghost-text/markdown): An inline AI autocomplete where muted ghost text continues your sentence exactly at the caret and Tab turns it solid in place. Cmd+Right takes it one word at a time, Escape fades it away, and a calm chip shows the model behind it.
- [Image generation](https://uiarc.dev/components/image-generation/markdown): An image studio where each image forms on a dot matrix: a soft halftone wave breathes across the grid, the dots take the colours of the coming photo and grow into a coloured halftone, then blur away into the sharp photo. One large canvas with a mono size label, a filmstrip of four variations, a prompt bar with model and ratio, and upscale with a sweeping dot band, vary or download, with real provider marks and a built-in simulation.
- [Dictation button](https://uiarc.dev/components/dictation-button/markdown): A chat composer with voice input, where the mic springs into a recording pill with a smooth live waveform, a timer, and cancel and insert buttons. Words stream into the field as you speak, muted until the recognizer settles them.
- [Speech player](https://uiarc.dev/components/speech-player/markdown): A read-aloud player for AI replies. The Read aloud button in the message's action row turns into a compact player with play, a scrubbable progress bar, speed and a voice picker, and a highlight follows the spoken word through the reply, karaoke style.
- [Meeting summary](https://uiarc.dev/components/meeting-summary/markdown): An AI meeting notes card: the header shows the Google Meet or Zoom mark, the attendees and the duration. Summary, Decisions and Action items stream in after a short summarizing pass. Hover any line to see the transcript quote it came from, then check off action items or send them to Linear or Notion.
- [Reply draft](https://uiarc.dev/components/reply-draft/markdown): An AI email reply drafter where Claude streams a reply under a received Gmail message. Quick replies steer a fresh draft, tone and length rewrite it with a single crossfade, and you can edit the finished draft before you insert it.
- [Agent handoff](https://uiarc.dev/components/agent-handoff/markdown): A support conversation where an AI assistant hands off to a person. When it transfers, a card shows the summary it passes to the team and the typical wait. The person then joins and takes over, and a thin timeline on the left marks each step.
- [PII redaction](https://uiarc.dev/components/pii-redaction/markdown): A guardrail card where personal data is redacted before the prompt reaches the model. Scan marks each name, email, phone number and card with its type and swaps it for a placeholder like [EMAIL_1]. The safe prompt travels to Claude, and the reply comes back with the original values put back for the person.
- [Response feedback](https://uiarc.dev/components/response-feedback/markdown): A feedback control for AI replies where thumbs down opens an inline panel with reason chips and an optional note, thumbs up fills and asks what was good, and a submit shows a short thank-you before folding back into the row.
- [LLM cost calculator](https://uiarc.dev/components/llm-cost-calculator/markdown): A pricing calculator for LLM workloads. Set tokens per request, requests per day and prompt caching, and eight current models re-rank by monthly cost. Bars glide and prices roll as you drag.
- [Provider keys](https://uiarc.dev/components/provider-keys/markdown): A settings card for bring-your-own-key AI products. Each provider row shows its real mark, the masked key, a status and when the key was last used. You can reveal a key for five seconds, copy, rotate or remove it with undo. Adding or rotating a key opens an inline form that checks the format as you type, then tests the connection before saving.
- [Generation stats](https://uiarc.dev/components/generation-stats/markdown): A live stats strip for a streaming LLM response where time to first token, speed with a sparkline, output tokens and cost count up in tabular numerals beside the model's real mark, then settle and open into a latency and token cost breakdown.
- [AI translate](https://uiarc.dev/components/ai-translate/markdown): A message card where picking a language streams the AI translation in place, sentence by sentence over the dimmed original, with a detected-language chip, a Show original toggle and a status line credited to the model's mark.
- [TL;DR toggle](https://uiarc.dev/components/tldr-toggle/markdown): An article card with a Full, Summary and Key points switch and a length slider. Switching streams an AI summary in place of the article as the card's height springs to fit, and each key point links back to the paragraph it came from, which gets scrolled to and highlighted.
- [Connector setup](https://uiarc.dev/components/connector-setup/markdown): A "Connect your tools" card for an AI assistant. Each app connects inline: it redirects, authorizes and runs a first sync with a progress hairline, then lists the scopes it was granted and offers Disconnect with an inline confirm.
- [Smart form fill](https://uiarc.dev/components/smart-form-fill/markdown): A paste-to-fill form card where AI reads an email signature or messy notes and fills a contact field by field. Each value flashes in with a confidence dot, its source lights up in the pasted text, low-confidence guesses ask for review, and Undo puts the old values back.
- [Enrich column](https://uiarc.dev/components/enrich-column/markdown): An AI enrichment column for a data table, where one prompt runs down every row and each cell shimmers while it works, then settles into a value with its source or a failure you can retry.
- [Ticket router](https://uiarc.dev/components/ticket-router/markdown): A support ticket router where messages from Gmail, Intercom, Slack and Zendesk come in one at a time. An AI classifier labels each one with intent, sentiment and confidence, and the ticket moves into a team lane with an assignee. Low confidence tickets wait in a review lane, and one click there routes them to the suggested team.
- [Ask your data](https://uiarc.dev/components/ask-your-data/markdown): A natural language to chart card: you ask a question, PostgreSQL streams into a collapsible, syntax highlighted panel, the query runs with a rolling row count, and the answer builds as stacked bars, lines or a table, with a one line insight streamed in underneath.
- [Agent cursor](https://uiarc.dev/components/agent-cursor/markdown): A live document where Claude edits like a collaborator. Its labeled cursor comes out of its avatar, selects a paragraph and streams in a rewrite, adds a heading and fixes a typo, while a teammate's cursor reads along. Changes stay tinted until someone accepts or undoes them from a floating review bar.
- [Provider status](https://uiarc.dev/components/provider-status/markdown): A status card for the AI providers your product depends on. Each row shows the provider's real mark, its health as an icon and label, p50 latency and a 30-day uptime bar with a tooltip for each day. An incident row expands into its timeline of updates, and the card checks again on a visible countdown.
- [Training run](https://uiarc.dev/components/training-run/markdown): A fine-tuning job card where a live train and validation loss curve draws across a fixed step axis that doubles as the epoch progress bar. It shows the learning rate, elapsed time, ETA and the latest evals and checkpoints, has Pause and Cancel while it runs, and ends in results with a Deploy button.
- [AI command](https://uiarc.dev/components/ai-command/markdown): A Cmd+K command palette with an AI mode. Search pages and actions, or press Tab to ask a question: the answer streams inside the palette with numbered sources, and the next steps it suggests, like filing a Linear issue or opening a Notion doc, run straight from the list.
- [Starter prompts](https://uiarc.dev/components/starter-prompts/markdown): A greeting and a grid of starter cards for the empty state of an AI app. The cards are grouped into Write, Code, Analyze and Plan tabs, and a shuffle swaps them with a short staggered crossfade. Picking a card fills the composer, and cards that use a connected app show its mark (Gmail, GitHub, Notion, Linear, Google Calendar).
- [Image reveal](https://uiarc.dev/components/image-reveal/markdown): An image generation canvas where a soft, blurred preview made from the image's own colors sharpens top to bottom behind a soft-edged band. It works the way ChatGPT, Midjourney and Gemini show images forming, with fine film grain, a translucent progress pill and calm queued and error states.
- [Pixel mascot](https://uiarc.dev/components/pixel-mascot/markdown): A pixel-art robot that shows what an AI assistant is doing. It idles, thinks, types, celebrates and errors in frame-stepped sprite animations, and stays crisp at every integer size from 24px to 192px.
- [Ghost mascot](https://uiarc.dev/components/ghost-mascot/markdown): A floating ghost mascot whose soft sheet ripples at the hem while it hovers. It blinks when idle, turns toward you to listen, fades a little translucent while thinking, draws a tiny pen line while writing, smiles with a sparkle when done and wobbles once on an error.
- [Cube mascot](https://uiarc.dev/components/cube-mascot/markdown): An isometric cube mascot where three shaded faces and a painted-on face show what the assistant is doing. It turns a quarter turn in eased steps while thinking, prints lines onto the floor while writing, settles with a sparkle when done, and shakes once on error.
- [Tone tuner](https://uiarc.dev/components/tone-tuner/markdown): A brand voice card where two sliders (formality and detail) and Friendly, Confident and Empathetic chips rewrite a customer reply. Each changed sentence crossfades in place, new words can be highlighted against the original, and Copy takes the current version.
- [Upgrade prompt](https://uiarc.dev/components/upgrade-prompt/markdown): An upgrade nudge for the moment someone hits a limit. It shows a usage meter at 50 of 50 AI credits, a rolling price with a monthly and yearly toggle, three concrete unlocks with real model marks, and Upgrade or Maybe later. Upgrading leads into a success state with the new limits, and the card never changes size between states.
- [Referral card](https://uiarc.dev/components/referral-card/markdown): A give-and-get referral card where people copy or share their invite link, invite friends by email as chips, and watch invites move from invited to signed up to earned, with the credit total counting up and a milestone reward unlocking.
- [Trial banner](https://uiarc.dev/components/trial-banner/markdown): A trial status banner where a ring counts down the days left, the copy names what the workspace loses, and the upgrade path is one click away. It comes as a slim banner, a sidebar card or a header pill. It shifts to a warning tone in the last days, has expired and upgraded states, and folds into the pill when dismissed or snoozed.
- [Team switcher](https://uiarc.dev/components/team-switcher/markdown): A workspace switcher like Linear, Vercel or Slack. The trigger shows the current workspace's logo and plan. The menu has search, your role in each workspace and a Cmd+1 to 9 shortcut for each, and lets you create or join a workspace inline. A highlight glides between rows, and switching crossfades the trigger through a short loading state.
- [Live visitors](https://uiarc.dev/components/live-visitors/markdown): A realtime visitors card where the live count rolls digit by digit, new arrivals ping in on a dotted world map, the top pages reorder with bars, and signups and upgrades tick in with country flags.
- [Social proof toast](https://uiarc.dev/components/social-proof-toast/markdown): A stack of social proof notifications for landing and pricing pages, where recent trials, upgrades and verified purchases from people and companies arrive every few seconds. The stack pauses and fans out on hover, and visitors can dismiss any toast.
- [Install snippet](https://uiarc.dev/components/install-snippet/markdown): A "get started in 30 seconds" card where framework tabs, three numbered steps and highlighted snippets take a developer from install to first event. Generate key wipes a fresh API key into the placeholder in place.

### Guidance for AI tools

AI spark: A brand-quality animated spark mark. Four tapered rays and four lighter diagonals breathe at rest, ripple while thinking, pulse like a heartbeat while writing, then gather and settle when done. Every status change blends from the pose the mark is already in. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Pixel mascot

> A pixel-art robot that shows what an AI assistant is doing. It idles, thinks, types, celebrates and errors in frame-stepped sprite animations, and stays crisp at every integer size from 24px to 192px.

- Type: Component (special)
- Access: Arc Pro
- Page: https://uiarc.dev/components/pixel-mascot
- Markdown: https://uiarc.dev/components/pixel-mascot/markdown
- Source file: `registry/components/pixel-mascot/pixel-mascot.tsx`
- Dependencies: motion
- Keywords: special, ai, motion, new, pixel art, 8-bit, 16-bit, sprite, mascot, robot, ai loading, thinking indicator, typing indicator, generating, assistant avatar, retro, loader, empty state

### When to use

- A friendly generating indicator next to an assistant reply or in a chat composer.
- An empty state or onboarding panel where a small character makes an AI feature feel approachable.
- Image or canvas generation, where a mascot in the corner shows thinking, drawing and done.
- Products with a playful or retro visual voice that still want precise, calm motion.

### When not to use

- Detailed agent progress with steps and timings; use agent-status or agent-timeline.
- Dense tables or toolbars where a 24px character is noise; use status-dot or a spinner.
- Serious or regulated contexts (finance, health, legal) where a character feels flippant; use text-shimmer.
- Showing model reasoning content; use reasoning-block.

### Installation

Pixel mascot is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/pixel-mascot
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { PixelMascot } from "@/components/arc/pixel-mascot/pixel-mascot";

// Inline next to a streaming reply
<PixelMascot status={isStreaming ? "writing" : "thinking"} size={2} name="Claude Sonnet 5.5" announce={false} />

// Empty state or composer, self playing
<PixelMascot size={6} />
```

### API reference

#### PixelMascot

A pixel art robot on a 24 by 24 grid that shows what an assistant is doing. Every state is a frame based sprite animation on a fixed 40ms clock, and status changes morph from the current pose one pixel at a time.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `status` | `"idle" \| "thinking" \| "writing" \| "done" \| "error"` | – | What the assistant is doing. Leave it out to play the built in loop through every state. |
| `size` | `number` | `4` | Integer pixel scale from 1 to 8. Each sprite pixel is this many CSS pixels: 1 renders 24px, 2 renders 48px, 4 renders 96px, 8 renders 192px. Other values round and clamp. |
| `name` | `string` | `"Assistant"` | Who the mascot stands for, used in the accessible label ("Arc is thinking"). |
| `label` | `string` | – | Replaces the generated accessible label. |
| `announce` | `boolean` | – | Announces status changes in a polite live region. Defaults to true when status is controlled and false for the built in loop. Turn it off when nearby text already announces progress. |
| `paused` | `boolean` | `false` | Freezes the animation on the current frame. The mascot also pauses by itself while off screen. |
| `className` | `string` | – | Class for the inline wrapper. |
| `style` | `CSSProperties` | – | Style for the inline wrapper, for example a custom --accent. |

#### usePixelMascotLoop

Hook that returns the built in status loop (idle, thinking, writing, done, idle, thinking, error). Use it to keep several mascots in step.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `enabled` | `boolean` | `true` | Pass false to hold the current status. |

### Accessibility

- The sprite is one SVG with role="img" and a label such as "Arc is thinking" that follows the status.
- A visually hidden polite live region announces status changes when the status is controlled; set announce to false when the surrounding UI already reports progress, to avoid double announcements.
- Status is never color alone: each state has its own shape (thought bubble, keyboard, happy eyes, crossed eyes) and the label carries the words.
- The error state uses the danger token for the crossed eyes on a tinted screen, so it reads in light and dark and with any accent.

### Motion

- Stepped on purpose: the sprite advances on a fixed 40ms clock and moves in whole pixels. Timings are authored as ease curves in steps, for example the done jump rises fast, holds at the top for 120ms and settles without a rebound.
- Status changes never cut: lids close and open, eyes slide one pixel per step, arms pass through neighbouring poses, the thought bubble and keyboard step in and out from wherever they are. A change mid animation reverses from the current frame.
- Loops are seamless by construction: idle bobs on a 2s cycle with blinks and a glance on an 8s cycle, thinking cycles three dots every 1.12s, writing types an eight stroke bar every 1.6s while the eyes scan and return.
- Only SVG attributes change (transform, x, y, visibility, opacity) from a requestAnimationFrame loop outside React, so there is no layout work or re-render per frame.
- Pauses off screen with an IntersectionObserver and when paused is set. With reduced motion the mascot holds a clear resting pose for each status: open eyes, bubble with three dots, keyboard, happy eyes or crossed eyes.

### Responsive behavior

- The sprite is a fixed square of 24 times size CSS pixels and never reflows; pick a smaller size on narrow layouts.
- Inline-flex with vertical-align middle, so it sits on a text line at sizes 1 and 2.
- Crisp at every integer size thanks to shape-rendering crispEdges and whole pixel transforms.

### Performance

- One SVG with about 40 nodes and no images. The loop writes only changed attributes, about 25 times a second at most, and skips writes on unchanged steps.
- No React re-render per frame; the loop stops off screen, when paused and under reduced motion.
- Many instances on one page are fine; each runs its own lightweight loop only while visible.

### Notes for AI

- Choose PixelMascot for a characterful "AI is working" indicator with retro charm: inline in a reply at size 2, in a composer at size 2 or 3, on an image canvas or empty state at size 4 to 8.
- Map your own lifecycle to the five statuses: request sent is thinking, first token is writing, finished is done, failures are error, and settle back to idle a couple of seconds after done.
- Keep size an integer; the art is drawn for whole pixel multiples and stays crisp at every one of them.
- The palette follows --accent and the theme neutrals. Set --accent on a parent to brand it; it looks right with Arc's near neutral grey default too.
- Pair it with text, such as a TextShimmer label, when users need to know exactly what is happening; the mascot carries the mood, the text carries the detail.

### Related

- [AI mascot](https://uiarc.dev/components/ai-mascot/markdown): A small assistant character, a soft pebble with pill eyes and a companion dot, that shows what the AI is doing. It breathes and glances when idle, leans in to listen, looks up while the dot orbits its head, reads along the line it writes, squints with a sparkle when done and shakes once with worried brows on an error.
- [Cube mascot](https://uiarc.dev/components/cube-mascot/markdown): An isometric cube mascot where three shaded faces and a painted-on face show what the assistant is doing. It turns a quarter turn in eased steps while thinking, prints lines onto the floor while writing, settles with a sparkle when done, and shakes once on error.
- [Ghost mascot](https://uiarc.dev/components/ghost-mascot/markdown): A floating ghost mascot whose soft sheet ripples at the hem while it hovers. It blinks when idle, turns toward you to listen, fades a little translucent while thinking, draws a tiny pen line while writing, smiles with a sparkle when done and wobbles once on an error.
- [Agent status](https://uiarc.dev/components/agent-status/markdown): A compact live status pill for a running AI agent: the agent's mark in a live ring, the current activity and an elapsed timer, opening into the steps so far.
- [Text shimmer](https://uiarc.dev/components/text-shimmer/markdown): Show ongoing work with a calm light across the words.
- [Reasoning block](https://uiarc.dev/components/reasoning-block/markdown): The collapsible thinking block of an AI reply. While the model thinks, a shimmering label counts the seconds and the latest reasoning streams underneath. When it finishes, it folds to "Thought for 7s" and opens to show the full reasoning as calm steps with headings.
- [Chat thread](https://uiarc.dev/components/chat-thread/markdown): A chat thread with grouped messages, reactions, read receipts, typing, and a composer with attachments.
- [Empty state](https://uiarc.dev/components/empty-state/markdown): A useful next step when there is nothing to show yet.

### Also in ai

- [Tool call](https://uiarc.dev/components/tool-call/markdown): A tool call row for agent transcripts: the tool's mark and the call in plain words, a live state while it runs, and the input and output a click away, with approval and retry when needed.
- [Agent plan](https://uiarc.dev/components/agent-plan/markdown): The plan an agent writes before it acts: edit, reorder or add steps while it is a draft, then watch it work through them as a live checklist.
- [Agent timeline](https://uiarc.dev/components/agent-timeline/markdown): A compact timeline of one orchestrated agent run: the orchestrator and its subagents share a time axis, handoffs draw in between rows, and a playhead replays thinking, tool calls and waiting while the header counts time, tokens and cost. Hover a span for what it did, or click it to trace its handoff path.
- [Context window](https://uiarc.dev/components/context-window/markdown): An AI context window as a grid of 200 cells: the system prompt, tools, files, summary and messages fill it in order, a threshold row marks where compaction starts, and sending a message, attaching a file or compacting shows exactly how much still fits.
- [Source cards](https://uiarc.dev/components/source-cards/markdown): A row of cited sources under an AI answer where cards stream in with real site marks while the model searches, the overflow collapses into a stack of favicons, hovering lifts a preview with the passage, and an inline [n] citation highlights its card.
- [Model card](https://uiarc.dev/components/model-card/markdown): A model details card where switching models rolls every price, limit and score in place, a token slider estimates monthly cost live, and benchmark bars show each model's rank on hover. Compare crossfades to a side-by-side table against any rival with the better values marked, and the card never changes size.
- [AI workflow](https://uiarc.dev/components/ai-workflow/markdown): A Linear-style AI workflow card where a Gmail trigger, a Claude step, a branch and Slack and Linear actions sit on one hairline rail, and a test run glides down it, opening each step's output inline. Steps are added from a compact command menu with real app marks.
- [Code suggestion](https://uiarc.dev/components/code-suggestion/markdown): An AI code edit suggestion where the model's proposed changes stream into a small editor panel as inline diff hunks, and you accept or reject each one, or all at once with Cmd+Enter. Accepted hunks fold into the file with a smooth height change.
- [Ghost text](https://uiarc.dev/components/ghost-text/markdown): An inline AI autocomplete where muted ghost text continues your sentence exactly at the caret and Tab turns it solid in place. Cmd+Right takes it one word at a time, Escape fades it away, and a calm chip shows the model behind it.
- [Image generation](https://uiarc.dev/components/image-generation/markdown): An image studio where each image forms on a dot matrix: a soft halftone wave breathes across the grid, the dots take the colours of the coming photo and grow into a coloured halftone, then blur away into the sharp photo. One large canvas with a mono size label, a filmstrip of four variations, a prompt bar with model and ratio, and upscale with a sweeping dot band, vary or download, with real provider marks and a built-in simulation.
- [Dictation button](https://uiarc.dev/components/dictation-button/markdown): A chat composer with voice input, where the mic springs into a recording pill with a smooth live waveform, a timer, and cancel and insert buttons. Words stream into the field as you speak, muted until the recognizer settles them.
- [Speech player](https://uiarc.dev/components/speech-player/markdown): A read-aloud player for AI replies. The Read aloud button in the message's action row turns into a compact player with play, a scrubbable progress bar, speed and a voice picker, and a highlight follows the spoken word through the reply, karaoke style.
- [Meeting summary](https://uiarc.dev/components/meeting-summary/markdown): An AI meeting notes card: the header shows the Google Meet or Zoom mark, the attendees and the duration. Summary, Decisions and Action items stream in after a short summarizing pass. Hover any line to see the transcript quote it came from, then check off action items or send them to Linear or Notion.
- [Reply draft](https://uiarc.dev/components/reply-draft/markdown): An AI email reply drafter where Claude streams a reply under a received Gmail message. Quick replies steer a fresh draft, tone and length rewrite it with a single crossfade, and you can edit the finished draft before you insert it.
- [Agent handoff](https://uiarc.dev/components/agent-handoff/markdown): A support conversation where an AI assistant hands off to a person. When it transfers, a card shows the summary it passes to the team and the typical wait. The person then joins and takes over, and a thin timeline on the left marks each step.
- [PII redaction](https://uiarc.dev/components/pii-redaction/markdown): A guardrail card where personal data is redacted before the prompt reaches the model. Scan marks each name, email, phone number and card with its type and swaps it for a placeholder like [EMAIL_1]. The safe prompt travels to Claude, and the reply comes back with the original values put back for the person.
- [Response feedback](https://uiarc.dev/components/response-feedback/markdown): A feedback control for AI replies where thumbs down opens an inline panel with reason chips and an optional note, thumbs up fills and asks what was good, and a submit shows a short thank-you before folding back into the row.
- [LLM cost calculator](https://uiarc.dev/components/llm-cost-calculator/markdown): A pricing calculator for LLM workloads. Set tokens per request, requests per day and prompt caching, and eight current models re-rank by monthly cost. Bars glide and prices roll as you drag.
- [Provider keys](https://uiarc.dev/components/provider-keys/markdown): A settings card for bring-your-own-key AI products. Each provider row shows its real mark, the masked key, a status and when the key was last used. You can reveal a key for five seconds, copy, rotate or remove it with undo. Adding or rotating a key opens an inline form that checks the format as you type, then tests the connection before saving.
- [Generation stats](https://uiarc.dev/components/generation-stats/markdown): A live stats strip for a streaming LLM response where time to first token, speed with a sparkline, output tokens and cost count up in tabular numerals beside the model's real mark, then settle and open into a latency and token cost breakdown.
- [AI translate](https://uiarc.dev/components/ai-translate/markdown): A message card where picking a language streams the AI translation in place, sentence by sentence over the dimmed original, with a detected-language chip, a Show original toggle and a status line credited to the model's mark.
- [TL;DR toggle](https://uiarc.dev/components/tldr-toggle/markdown): An article card with a Full, Summary and Key points switch and a length slider. Switching streams an AI summary in place of the article as the card's height springs to fit, and each key point links back to the paragraph it came from, which gets scrolled to and highlighted.
- [Connector setup](https://uiarc.dev/components/connector-setup/markdown): A "Connect your tools" card for an AI assistant. Each app connects inline: it redirects, authorizes and runs a first sync with a progress hairline, then lists the scopes it was granted and offers Disconnect with an inline confirm.
- [Smart form fill](https://uiarc.dev/components/smart-form-fill/markdown): A paste-to-fill form card where AI reads an email signature or messy notes and fills a contact field by field. Each value flashes in with a confidence dot, its source lights up in the pasted text, low-confidence guesses ask for review, and Undo puts the old values back.
- [Enrich column](https://uiarc.dev/components/enrich-column/markdown): An AI enrichment column for a data table, where one prompt runs down every row and each cell shimmers while it works, then settles into a value with its source or a failure you can retry.
- [Ticket router](https://uiarc.dev/components/ticket-router/markdown): A support ticket router where messages from Gmail, Intercom, Slack and Zendesk come in one at a time. An AI classifier labels each one with intent, sentiment and confidence, and the ticket moves into a team lane with an assignee. Low confidence tickets wait in a review lane, and one click there routes them to the suggested team.
- [Ask your data](https://uiarc.dev/components/ask-your-data/markdown): A natural language to chart card: you ask a question, PostgreSQL streams into a collapsible, syntax highlighted panel, the query runs with a rolling row count, and the answer builds as stacked bars, lines or a table, with a one line insight streamed in underneath.
- [Agent cursor](https://uiarc.dev/components/agent-cursor/markdown): A live document where Claude edits like a collaborator. Its labeled cursor comes out of its avatar, selects a paragraph and streams in a rewrite, adds a heading and fixes a typo, while a teammate's cursor reads along. Changes stay tinted until someone accepts or undoes them from a floating review bar.
- [Provider status](https://uiarc.dev/components/provider-status/markdown): A status card for the AI providers your product depends on. Each row shows the provider's real mark, its health as an icon and label, p50 latency and a 30-day uptime bar with a tooltip for each day. An incident row expands into its timeline of updates, and the card checks again on a visible countdown.
- [Training run](https://uiarc.dev/components/training-run/markdown): A fine-tuning job card where a live train and validation loss curve draws across a fixed step axis that doubles as the epoch progress bar. It shows the learning rate, elapsed time, ETA and the latest evals and checkpoints, has Pause and Cancel while it runs, and ends in results with a Deploy button.
- [AI command](https://uiarc.dev/components/ai-command/markdown): A Cmd+K command palette with an AI mode. Search pages and actions, or press Tab to ask a question: the answer streams inside the palette with numbered sources, and the next steps it suggests, like filing a Linear issue or opening a Notion doc, run straight from the list.
- [Starter prompts](https://uiarc.dev/components/starter-prompts/markdown): A greeting and a grid of starter cards for the empty state of an AI app. The cards are grouped into Write, Code, Analyze and Plan tabs, and a shuffle swaps them with a short staggered crossfade. Picking a card fills the composer, and cards that use a connected app show its mark (Gmail, GitHub, Notion, Linear, Google Calendar).
- [Image reveal](https://uiarc.dev/components/image-reveal/markdown): An image generation canvas where a soft, blurred preview made from the image's own colors sharpens top to bottom behind a soft-edged band. It works the way ChatGPT, Midjourney and Gemini show images forming, with fine film grain, a translucent progress pill and calm queued and error states.
- [AI spark](https://uiarc.dev/components/ai-spark/markdown): A brand-quality animated spark mark. Four tapered rays and four lighter diagonals breathe at rest, ripple while thinking, pulse like a heartbeat while writing, then gather and settle when done. Every status change blends from the pose the mark is already in.
- [Tone tuner](https://uiarc.dev/components/tone-tuner/markdown): A brand voice card where two sliders (formality and detail) and Friendly, Confident and Empathetic chips rewrite a customer reply. Each changed sentence crossfades in place, new words can be highlighted against the original, and Copy takes the current version.
- [Upgrade prompt](https://uiarc.dev/components/upgrade-prompt/markdown): An upgrade nudge for the moment someone hits a limit. It shows a usage meter at 50 of 50 AI credits, a rolling price with a monthly and yearly toggle, three concrete unlocks with real model marks, and Upgrade or Maybe later. Upgrading leads into a success state with the new limits, and the card never changes size between states.
- [Referral card](https://uiarc.dev/components/referral-card/markdown): A give-and-get referral card where people copy or share their invite link, invite friends by email as chips, and watch invites move from invited to signed up to earned, with the credit total counting up and a milestone reward unlocking.
- [Trial banner](https://uiarc.dev/components/trial-banner/markdown): A trial status banner where a ring counts down the days left, the copy names what the workspace loses, and the upgrade path is one click away. It comes as a slim banner, a sidebar card or a header pill. It shifts to a warning tone in the last days, has expired and upgraded states, and folds into the pill when dismissed or snoozed.
- [Team switcher](https://uiarc.dev/components/team-switcher/markdown): A workspace switcher like Linear, Vercel or Slack. The trigger shows the current workspace's logo and plan. The menu has search, your role in each workspace and a Cmd+1 to 9 shortcut for each, and lets you create or join a workspace inline. A highlight glides between rows, and switching crossfades the trigger through a short loading state.
- [Live visitors](https://uiarc.dev/components/live-visitors/markdown): A realtime visitors card where the live count rolls digit by digit, new arrivals ping in on a dotted world map, the top pages reorder with bars, and signups and upgrades tick in with country flags.
- [Social proof toast](https://uiarc.dev/components/social-proof-toast/markdown): A stack of social proof notifications for landing and pricing pages, where recent trials, upgrades and verified purchases from people and companies arrive every few seconds. The stack pauses and fans out on hover, and visitors can dismiss any toast.
- [Install snippet](https://uiarc.dev/components/install-snippet/markdown): A "get started in 30 seconds" card where framework tabs, three numbered steps and highlighted snippets take a developer from install to first event. Generate key wipes a fresh API key into the placeholder in place.

### Guidance for AI tools

Pixel mascot: A pixel-art robot that shows what an AI assistant is doing. It idles, thinks, types, celebrates and errors in frame-stepped sprite animations, and stays crisp at every integer size from 24px to 192px. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Ghost mascot

> A floating ghost mascot whose soft sheet ripples at the hem while it hovers. It blinks when idle, turns toward you to listen, fades a little translucent while thinking, draws a tiny pen line while writing, smiles with a sparkle when done and wobbles once on an error.

- Type: Component (special)
- Access: Arc Pro
- Page: https://uiarc.dev/components/ghost-mascot
- Markdown: https://uiarc.dev/components/ghost-mascot/markdown
- Source file: `registry/components/ghost-mascot/ghost-mascot.tsx`
- Keywords: special, ai, motion, new, ghost mascot, ai mascot, assistant character, ai avatar, generating animation, thinking animation, loading character, ghost, listening, writing, done sparkle, error wobble, empty state, svg path morph, wavy hem

### When to use

- Give an assistant a light, friendly face that shows what it is doing: in a reply header, in a composer, over an image canvas while it generates, or in an empty state.
- Products that want generation to feel alive without a spinner, with states that still read at 24px.

### When not to use

- Use agent-status when people need the steps, tools and elapsed time of a run, not just a mood.
- Use text-shimmer alone for a plain "Thinking" line in dense interfaces where a character would distract.
- Do not use it as a progress indicator with a known percentage; use a progress bar.

### Installation

Ghost mascot is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/ghost-mascot
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { GhostMascot, type GhostStatus } from "@/components/arc/ghost-mascot/ghost-mascot";

// Inline next to a streaming reply
export function ReplyHeader({ phase }: { phase: "waiting" | "streaming" | "complete" | "failed" }) {
  const status: GhostStatus = phase === "streaming" ? "writing" : phase === "complete" ? "done" : phase === "failed" ? "error" : "thinking";
  return (
    <div style={{ display: "flex", alignItems: "center", gap: 8 }}>
      <GhostMascot status={status} size={24} name="Atlas" />
      <span>Atlas</span>
    </div>
  );
}

// Empty state: the classic pale sheet
<GhostMascot status="idle" size={160} tone="sheet" name="Atlas" />

// On an image canvas while it generates
<GhostMascot status={generating ? "thinking" : "done"} size={64} announce />

// Brand color sheet with light eyes
<GhostMascot status="listening" size={96} color="#7747ff" eyeColor="white" />
```

### API reference

#### GhostMascot

A floating ghost drawn in SVG: a soft sheet with a rippling hem, a quiet form shade and two simple eyes. Six states. Idle floats, blinks and glances around. Listening comes forward with wide eyes and a small head tilt. Thinking drifts up, turns translucent and looks up at a small swirl that curls in and out. Writing leans toward a line it writes with a tiny pen, eyes on the tip. Done lifts with happy eyes and a sparkle. Error wobbles once, sinks and droops its eyes. Status changes blend from the pose on screen over 400ms, never a hard cut.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `status` | `"idle" \| "listening" \| "thinking" \| "writing" \| "done" \| "error"` | – | What the assistant is doing. Leave unset to play through every state on a loop (the docs demo). |
| `size` | `number` | `96` | Width and height in px, from 24 (inline next to a message) to 160 (empty state). Below 56 a compact drawing takes over: tighter framing, bigger eyes, heavier swirl, pen and line, no shadow. |
| `tone` | `"accent" \| "sheet" \| "ink"` | `"accent"` | Sheet color from the theme: the accent with accent-foreground eyes, a pale raised surface with a hairline and foreground eyes (marks keep the accent), or the foreground ink with background eyes. |
| `color` | `string` | – | Any CSS color for the sheet. Overrides tone; the eyes become a dark mix of it unless eyeColor is set. |
| `eyeColor` | `string` | – | Any CSS color for the eyes. |
| `ground` | `boolean` | `true` | The soft floating shadow, which shrinks and fades as the ghost rises. Drawn only at 56px and up. |
| `paused` | `boolean` | `false` | Freeze on the current frame. The ghost also pauses by itself off screen and in background tabs, and resumes on the same frame. |
| `name` | `string` | `"Assistant"` | Used in the accessible label, for example "Atlas, thinking". |
| `label` | `string` | – | Overrides the whole accessible label. |
| `announce` | `boolean` | `false` | Announce status changes in a polite live region. Turn it on for the one ghost that carries status, not for decorative copies. |
| `onStatusChange` | `(status: GhostStatus) => void` | – | Called when the self-playing loop (status unset) moves to the next state. Use it to sync a caption or a control. |
| `className` | `string` | – | Class on the root span. Set --ghost-body, --ghost-eye, --ghost-mark, --ghost-shade or --ghost-ground here to restyle. |
| `style` | `CSSProperties` | – | Inline style on the root span. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| None | The ghost is a status image and takes no focus. Pair it with a real control when people act on what it shows. |

### Accessibility

- The SVG has role img and a label built from name and status, for example "Atlas, thinking", which updates with every state.
- With announce, status changes are read in a polite live region outside the image. Use it on one ghost per view so screen readers do not hear duplicates.
- Status is never carried by color or motion alone: each state changes the face and marks (wide eyes, eyes up with a swirl, a pen and line, happy eyes with a sparkle, droopy eyes) and the label. Show a text status next to it where the state matters.

### Motion

- Every loop is a function of a phase that only grows: the float, the two hem waves, the swirl and the writing cycle. Rates blend by integrating into those phases, so speed changes never jump and nothing restarts.
- The hem is two traveling sine waves drawn as exact Hermite curves through rounded corners, rebuilt every frame. It trails the float: the sheet stretches on the way up, and the hem lifts and flares on the way down.
- A status change blends every pose value from the frame on screen to the new pose over 400ms with an ease in and out. Eyes ride a critically damped spring: quick saccades when idle, a slow drift up while thinking, tight tracking of the pen tip while writing. Nothing bounces.
- The swirl draws in from its outer end and erases behind itself; the writing line draws word by word, the pen lifting between words, then erases while the pen glides back. Both are empty at the moment their cycle wraps, so there is no seam.
- Done grows the sparkle in 320ms with an ease out and a quarter turn, then a slow twinkle. Error wobbles once, decaying to rest in about 1.2s, softened at the start so it never kicks.
- Reduced motion shows a still, representative pose for each state (a half drawn swirl, half a written line, the sparkle, the droop), switches in place and drops every loop, glance, blink and wobble.

### Responsive behavior

- A fixed square of size px that never reflows its parent. The drawing is vector art and stays crisp at any device pixel ratio.
- Below 56px the compact drawing frames the ghost tighter and enlarges the eyes and marks so they stay legible at 24px.

### Performance

- One requestAnimationFrame loop per ghost writes SVG attributes directly, so React does not re-render per frame; only the self-playing loop sets state, once per state.
- The loop stops off screen (IntersectionObserver) and in hidden tabs, and its clock only runs while visible, so it resumes on the same frame instead of jumping.
- Under reduced motion the loop repaints only when the status changes.
- About a dozen SVG nodes, one clip path, no filters, masks or gradients.

### Notes for AI

- Map the assistant's real phases to status: microphone open is listening, waiting for the first token is thinking, streaming is writing, finished is done, failed is error, otherwise idle.
- Keep thinking short in real use; switch to writing on the first token.
- Use size 24 to 32 inline in a reply header or composer, 40 to 64 in a panel or on an image canvas, 96 to 160 in an empty state.
- The default accent tone follows the theme accent, including Arc's near-neutral grey. Use tone="sheet" for the classic pale ghost.
- Set name to the assistant's name so the label reads well. Turn announce on for one ghost only. Leave status unset only for showcases.

### Related

- [AI mascot](https://uiarc.dev/components/ai-mascot/markdown): A small assistant character, a soft pebble with pill eyes and a companion dot, that shows what the AI is doing. It breathes and glances when idle, leans in to listen, looks up while the dot orbits its head, reads along the line it writes, squints with a sparkle when done and shakes once with worried brows on an error.
- [Agent status](https://uiarc.dev/components/agent-status/markdown): A compact live status pill for a running AI agent: the agent's mark in a live ring, the current activity and an elapsed timer, opening into the steps so far.
- [Text shimmer](https://uiarc.dev/components/text-shimmer/markdown): Show ongoing work with a calm light across the words.
- [AI spark](https://uiarc.dev/components/ai-spark/markdown): A brand-quality animated spark mark. Four tapered rays and four lighter diagonals breathe at rest, ripple while thinking, pulse like a heartbeat while writing, then gather and settle when done. Every status change blends from the pose the mark is already in.
- [Image generation](https://uiarc.dev/components/image-generation/markdown): An image studio where each image forms on a dot matrix: a soft halftone wave breathes across the grid, the dots take the colours of the coming photo and grow into a coloured halftone, then blur away into the sharp photo. One large canvas with a mono size label, a filmstrip of four variations, a prompt bar with model and ratio, and upscale with a sweeping dot band, vary or download, with real provider marks and a built-in simulation.
- [AI chat](https://uiarc.dev/components/blocks/ai-chat/markdown): A full-screen AI chat where answers stream in as markdown with folding reasoning, tool chips and cited sources. People can switch chats and models, edit or retry a message into versions, rate replies and stop a reply mid-stream.
- [AI composer](https://uiarc.dev/components/blocks/ai-composer/markdown): The prompt box at the bottom of an AI app: files upload in place, / opens commands, @ inserts mentions, a model and effort menu sits in the toolbar, and the send button turns into a stop control ringed by the reply's progress.
- [Dictation button](https://uiarc.dev/components/dictation-button/markdown): A chat composer with voice input, where the mic springs into a recording pill with a smooth live waveform, a timer, and cancel and insert buttons. Words stream into the field as you speak, muted until the recognizer settles them.

### Also in ai

- [Tool call](https://uiarc.dev/components/tool-call/markdown): A tool call row for agent transcripts: the tool's mark and the call in plain words, a live state while it runs, and the input and output a click away, with approval and retry when needed.
- [Agent plan](https://uiarc.dev/components/agent-plan/markdown): The plan an agent writes before it acts: edit, reorder or add steps while it is a draft, then watch it work through them as a live checklist.
- [Agent timeline](https://uiarc.dev/components/agent-timeline/markdown): A compact timeline of one orchestrated agent run: the orchestrator and its subagents share a time axis, handoffs draw in between rows, and a playhead replays thinking, tool calls and waiting while the header counts time, tokens and cost. Hover a span for what it did, or click it to trace its handoff path.
- [Context window](https://uiarc.dev/components/context-window/markdown): An AI context window as a grid of 200 cells: the system prompt, tools, files, summary and messages fill it in order, a threshold row marks where compaction starts, and sending a message, attaching a file or compacting shows exactly how much still fits.
- [Reasoning block](https://uiarc.dev/components/reasoning-block/markdown): The collapsible thinking block of an AI reply. While the model thinks, a shimmering label counts the seconds and the latest reasoning streams underneath. When it finishes, it folds to "Thought for 7s" and opens to show the full reasoning as calm steps with headings.
- [Source cards](https://uiarc.dev/components/source-cards/markdown): A row of cited sources under an AI answer where cards stream in with real site marks while the model searches, the overflow collapses into a stack of favicons, hovering lifts a preview with the passage, and an inline [n] citation highlights its card.
- [Model card](https://uiarc.dev/components/model-card/markdown): A model details card where switching models rolls every price, limit and score in place, a token slider estimates monthly cost live, and benchmark bars show each model's rank on hover. Compare crossfades to a side-by-side table against any rival with the better values marked, and the card never changes size.
- [AI workflow](https://uiarc.dev/components/ai-workflow/markdown): A Linear-style AI workflow card where a Gmail trigger, a Claude step, a branch and Slack and Linear actions sit on one hairline rail, and a test run glides down it, opening each step's output inline. Steps are added from a compact command menu with real app marks.
- [Code suggestion](https://uiarc.dev/components/code-suggestion/markdown): An AI code edit suggestion where the model's proposed changes stream into a small editor panel as inline diff hunks, and you accept or reject each one, or all at once with Cmd+Enter. Accepted hunks fold into the file with a smooth height change.
- [Ghost text](https://uiarc.dev/components/ghost-text/markdown): An inline AI autocomplete where muted ghost text continues your sentence exactly at the caret and Tab turns it solid in place. Cmd+Right takes it one word at a time, Escape fades it away, and a calm chip shows the model behind it.
- [Speech player](https://uiarc.dev/components/speech-player/markdown): A read-aloud player for AI replies. The Read aloud button in the message's action row turns into a compact player with play, a scrubbable progress bar, speed and a voice picker, and a highlight follows the spoken word through the reply, karaoke style.
- [Meeting summary](https://uiarc.dev/components/meeting-summary/markdown): An AI meeting notes card: the header shows the Google Meet or Zoom mark, the attendees and the duration. Summary, Decisions and Action items stream in after a short summarizing pass. Hover any line to see the transcript quote it came from, then check off action items or send them to Linear or Notion.
- [Reply draft](https://uiarc.dev/components/reply-draft/markdown): An AI email reply drafter where Claude streams a reply under a received Gmail message. Quick replies steer a fresh draft, tone and length rewrite it with a single crossfade, and you can edit the finished draft before you insert it.
- [Agent handoff](https://uiarc.dev/components/agent-handoff/markdown): A support conversation where an AI assistant hands off to a person. When it transfers, a card shows the summary it passes to the team and the typical wait. The person then joins and takes over, and a thin timeline on the left marks each step.
- [PII redaction](https://uiarc.dev/components/pii-redaction/markdown): A guardrail card where personal data is redacted before the prompt reaches the model. Scan marks each name, email, phone number and card with its type and swaps it for a placeholder like [EMAIL_1]. The safe prompt travels to Claude, and the reply comes back with the original values put back for the person.
- [Response feedback](https://uiarc.dev/components/response-feedback/markdown): A feedback control for AI replies where thumbs down opens an inline panel with reason chips and an optional note, thumbs up fills and asks what was good, and a submit shows a short thank-you before folding back into the row.
- [LLM cost calculator](https://uiarc.dev/components/llm-cost-calculator/markdown): A pricing calculator for LLM workloads. Set tokens per request, requests per day and prompt caching, and eight current models re-rank by monthly cost. Bars glide and prices roll as you drag.
- [Provider keys](https://uiarc.dev/components/provider-keys/markdown): A settings card for bring-your-own-key AI products. Each provider row shows its real mark, the masked key, a status and when the key was last used. You can reveal a key for five seconds, copy, rotate or remove it with undo. Adding or rotating a key opens an inline form that checks the format as you type, then tests the connection before saving.
- [Generation stats](https://uiarc.dev/components/generation-stats/markdown): A live stats strip for a streaming LLM response where time to first token, speed with a sparkline, output tokens and cost count up in tabular numerals beside the model's real mark, then settle and open into a latency and token cost breakdown.
- [AI translate](https://uiarc.dev/components/ai-translate/markdown): A message card where picking a language streams the AI translation in place, sentence by sentence over the dimmed original, with a detected-language chip, a Show original toggle and a status line credited to the model's mark.
- [TL;DR toggle](https://uiarc.dev/components/tldr-toggle/markdown): An article card with a Full, Summary and Key points switch and a length slider. Switching streams an AI summary in place of the article as the card's height springs to fit, and each key point links back to the paragraph it came from, which gets scrolled to and highlighted.
- [Connector setup](https://uiarc.dev/components/connector-setup/markdown): A "Connect your tools" card for an AI assistant. Each app connects inline: it redirects, authorizes and runs a first sync with a progress hairline, then lists the scopes it was granted and offers Disconnect with an inline confirm.
- [Smart form fill](https://uiarc.dev/components/smart-form-fill/markdown): A paste-to-fill form card where AI reads an email signature or messy notes and fills a contact field by field. Each value flashes in with a confidence dot, its source lights up in the pasted text, low-confidence guesses ask for review, and Undo puts the old values back.
- [Enrich column](https://uiarc.dev/components/enrich-column/markdown): An AI enrichment column for a data table, where one prompt runs down every row and each cell shimmers while it works, then settles into a value with its source or a failure you can retry.
- [Ticket router](https://uiarc.dev/components/ticket-router/markdown): A support ticket router where messages from Gmail, Intercom, Slack and Zendesk come in one at a time. An AI classifier labels each one with intent, sentiment and confidence, and the ticket moves into a team lane with an assignee. Low confidence tickets wait in a review lane, and one click there routes them to the suggested team.
- [Ask your data](https://uiarc.dev/components/ask-your-data/markdown): A natural language to chart card: you ask a question, PostgreSQL streams into a collapsible, syntax highlighted panel, the query runs with a rolling row count, and the answer builds as stacked bars, lines or a table, with a one line insight streamed in underneath.
- [Agent cursor](https://uiarc.dev/components/agent-cursor/markdown): A live document where Claude edits like a collaborator. Its labeled cursor comes out of its avatar, selects a paragraph and streams in a rewrite, adds a heading and fixes a typo, while a teammate's cursor reads along. Changes stay tinted until someone accepts or undoes them from a floating review bar.
- [Provider status](https://uiarc.dev/components/provider-status/markdown): A status card for the AI providers your product depends on. Each row shows the provider's real mark, its health as an icon and label, p50 latency and a 30-day uptime bar with a tooltip for each day. An incident row expands into its timeline of updates, and the card checks again on a visible countdown.
- [Training run](https://uiarc.dev/components/training-run/markdown): A fine-tuning job card where a live train and validation loss curve draws across a fixed step axis that doubles as the epoch progress bar. It shows the learning rate, elapsed time, ETA and the latest evals and checkpoints, has Pause and Cancel while it runs, and ends in results with a Deploy button.
- [AI command](https://uiarc.dev/components/ai-command/markdown): A Cmd+K command palette with an AI mode. Search pages and actions, or press Tab to ask a question: the answer streams inside the palette with numbered sources, and the next steps it suggests, like filing a Linear issue or opening a Notion doc, run straight from the list.
- [Starter prompts](https://uiarc.dev/components/starter-prompts/markdown): A greeting and a grid of starter cards for the empty state of an AI app. The cards are grouped into Write, Code, Analyze and Plan tabs, and a shuffle swaps them with a short staggered crossfade. Picking a card fills the composer, and cards that use a connected app show its mark (Gmail, GitHub, Notion, Linear, Google Calendar).
- [Image reveal](https://uiarc.dev/components/image-reveal/markdown): An image generation canvas where a soft, blurred preview made from the image's own colors sharpens top to bottom behind a soft-edged band. It works the way ChatGPT, Midjourney and Gemini show images forming, with fine film grain, a translucent progress pill and calm queued and error states.
- [Pixel mascot](https://uiarc.dev/components/pixel-mascot/markdown): A pixel-art robot that shows what an AI assistant is doing. It idles, thinks, types, celebrates and errors in frame-stepped sprite animations, and stays crisp at every integer size from 24px to 192px.
- [Cube mascot](https://uiarc.dev/components/cube-mascot/markdown): An isometric cube mascot where three shaded faces and a painted-on face show what the assistant is doing. It turns a quarter turn in eased steps while thinking, prints lines onto the floor while writing, settles with a sparkle when done, and shakes once on error.
- [Tone tuner](https://uiarc.dev/components/tone-tuner/markdown): A brand voice card where two sliders (formality and detail) and Friendly, Confident and Empathetic chips rewrite a customer reply. Each changed sentence crossfades in place, new words can be highlighted against the original, and Copy takes the current version.
- [Upgrade prompt](https://uiarc.dev/components/upgrade-prompt/markdown): An upgrade nudge for the moment someone hits a limit. It shows a usage meter at 50 of 50 AI credits, a rolling price with a monthly and yearly toggle, three concrete unlocks with real model marks, and Upgrade or Maybe later. Upgrading leads into a success state with the new limits, and the card never changes size between states.
- [Referral card](https://uiarc.dev/components/referral-card/markdown): A give-and-get referral card where people copy or share their invite link, invite friends by email as chips, and watch invites move from invited to signed up to earned, with the credit total counting up and a milestone reward unlocking.
- [Trial banner](https://uiarc.dev/components/trial-banner/markdown): A trial status banner where a ring counts down the days left, the copy names what the workspace loses, and the upgrade path is one click away. It comes as a slim banner, a sidebar card or a header pill. It shifts to a warning tone in the last days, has expired and upgraded states, and folds into the pill when dismissed or snoozed.
- [Team switcher](https://uiarc.dev/components/team-switcher/markdown): A workspace switcher like Linear, Vercel or Slack. The trigger shows the current workspace's logo and plan. The menu has search, your role in each workspace and a Cmd+1 to 9 shortcut for each, and lets you create or join a workspace inline. A highlight glides between rows, and switching crossfades the trigger through a short loading state.
- [Live visitors](https://uiarc.dev/components/live-visitors/markdown): A realtime visitors card where the live count rolls digit by digit, new arrivals ping in on a dotted world map, the top pages reorder with bars, and signups and upgrades tick in with country flags.
- [Social proof toast](https://uiarc.dev/components/social-proof-toast/markdown): A stack of social proof notifications for landing and pricing pages, where recent trials, upgrades and verified purchases from people and companies arrive every few seconds. The stack pauses and fans out on hover, and visitors can dismiss any toast.
- [Install snippet](https://uiarc.dev/components/install-snippet/markdown): A "get started in 30 seconds" card where framework tabs, three numbered steps and highlighted snippets take a developer from install to first event. Generate key wipes a fresh API key into the placeholder in place.

### Guidance for AI tools

Ghost mascot: A floating ghost mascot whose soft sheet ripples at the hem while it hovers. It blinks when idle, turns toward you to listen, fades a little translucent while thinking, draws a tiny pen line while writing, smiles with a sparkle when done and wobbles once on an error. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Cube mascot

> An isometric cube mascot where three shaded faces and a painted-on face show what the assistant is doing. It turns a quarter turn in eased steps while thinking, prints lines onto the floor while writing, settles with a sparkle when done, and shakes once on error.

- Type: Component (special)
- Access: Arc Pro
- Page: https://uiarc.dev/components/cube-mascot
- Markdown: https://uiarc.dev/components/cube-mascot/markdown
- Source file: `registry/components/cube-mascot/cube-mascot.tsx`
- Keywords: special, ai, motion, new, cube mascot, isometric cube, ai mascot, assistant character, 3d cube, thinking animation, generating, loading character, agent face, writing, done sparkle, error shake, empty state, svg animation

### When to use

- Give an assistant a recognisable, product-like character that shows it is generating: in a reply header, in a composer, on an image canvas or in an empty state.
- Brands with a geometric, technical feel where a soft blob would feel off.

### When not to use

- Use ai-mascot for a softer, rounder character, or when you need a listening state.
- Use agent-status when people need the steps, tools and elapsed time of a run.
- Do not use it as a progress indicator with a known percentage; use a progress bar.

### Installation

Cube mascot is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/cube-mascot
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { CubeMascot, type CubeStatus } from "@/components/arc/cube-mascot/cube-mascot";

// Inline next to a streaming reply
export function ReplyHeader({ phase }: { phase: "waiting" | "streaming" | "complete" | "failed" }) {
  const status: CubeStatus = phase === "streaming" ? "writing" : phase === "complete" ? "done" : phase === "failed" ? "error" : "thinking";
  return (
    <div style={{ display: "flex", alignItems: "center", gap: 8 }}>
      <CubeMascot status={status} size={24} name="Atlas" />
      <span>Atlas</span>
    </div>
  );
}

// Empty state on an image canvas while it generates
<CubeMascot status={generating ? "thinking" : "idle"} size={144} name="Atlas" announce />

// Brand colored body with light features
<CubeMascot status="writing" size={64} color="#4f6bff" faceColor="white" />
```

### API reference

#### CubeMascot

An isometric cube character drawn in SVG from real 3D math: a rounded silhouette, three faces shaded by how they face the light, and a face painted on the front side through its projected plane. Idle tilts, floats and blinks. Thinking turns the cube a quarter turn in eased steps, and the face fades in on the side that arrives at the front. Writing tips the face down while lines print onto the ground in front of it. Done settles with a happy squint and a sparkle. Error shakes once and shows worried brows. Status changes blend from the pose on screen over 420ms, never a hard cut.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `status` | `"idle" \| "thinking" \| "writing" \| "done" \| "error"` | – | What the assistant is doing. Leave unset to play through every state on a loop (the docs demo). |
| `size` | `number` | `96` | Width and height in px, from 24 (inline next to a message) to 160 (empty state). Below 56 a compact drawing takes over: a larger cube in the frame, bolder eyes, no mouth, shadow or printed lines. |
| `color` | `string` | – | Any CSS color for the cube body. Defaults to the accent. The top and shaded side are mixed from it. |
| `faceColor` | `string` | – | Any CSS color for the eyes, brows and mouth. Defaults to the accent foreground. |
| `ground` | `boolean` | `true` | The contact shadow and the lines printed while writing. Drawn at 56px and up. |
| `paused` | `boolean` | `false` | Freeze on the current frame. The cube also pauses by itself off screen and in background tabs, and resumes without a jump. |
| `name` | `string` | `"Assistant"` | Used in the accessible label, for example "Atlas, thinking". |
| `label` | `string` | – | Overrides the whole accessible label. |
| `announce` | `boolean` | `false` | Announce status changes in a polite live region. Turn it on for the one mascot that carries status, not for decorative copies. |
| `onStatusChange` | `(status: CubeStatus) => void` | – | Called when the self-playing loop (status unset) moves to the next state. Use it to sync a caption or a control. |
| `className` | `string` | – | Class on the root span. Set --cube-body, --cube-ink, --cube-top, --cube-front, --cube-side, --cube-line, --cube-shadow or --cube-sparkle here to restyle. |
| `style` | `CSSProperties` | – | Inline style on the root span. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| None | The mascot is a status image and takes no focus. Pair it with a real control when people act on what it shows. |

### Accessibility

- The SVG has role img and a label built from name and status, for example "Atlas, writing", which updates with every state.
- With announce, status changes are read in a polite live region outside the image. Use it on one mascot per view.
- Status is never motion alone: each state changes the face (eyes up, eyes down, happy squint, worried brows and frown) and the label. Show a text status next to it where the state matters.
- Under reduced motion every state is a still pose that switches in place.

### Motion

- The cube is real 3D: eight corners are rotated (yaw, roll, pitch, then a fixed 32 degree camera) and projected each frame. The silhouette is their convex hull with rounded corners, used as a clip, so the outline stays soft while edges between faces stay exact.
- Each face is shaded by its normal against a light from the upper left, interpolating between three anchors (top, front, side), so a face turning away darkens continuously.
- Thinking holds for .5s, then turns a quarter turn over .8s with a cubic ease in and out, rising slightly and leaning into the turn. A cube looks identical after 90 degrees, so the end of each step is the start of the next and the loop has no seam. The face on the leaving side fades as it turns edge on; the face on the arriving side fades in and its eyes open as it reaches the front.
- Writing prints a line every 360ms: each line slides out from under the face along the ground for 1.44s and only fades in and out, and its length changes while it is invisible. Eyes sweep slowly and the cube nods once per four lines.
- Idle is a sum of slow sines with incommensurate periods (tilt, sway, float, glance), so it never repeats or restarts. Blinks come every 2.6 to 4.9s, sometimes twice, and take 170ms.
- Done dips once and settles while the eyes pass through a closed line into the squint and the sparkle grows and turns in, then twinkles slowly. Error shakes 3.5 times in .56s under a squared envelope that reaches rest with zero velocity.
- A status change blends every pose value from the frame on screen to the new state over 420ms (240ms into error) with an ease in and out. A change caught mid turn keeps turning forward instead of unwinding. Nothing bounces.

### Responsive behavior

- A fixed square of size px that never reflows its parent. Vector art stays crisp at any device pixel ratio.
- Below 56px the compact drawing frames the cube tighter and enlarges the eyes so they read at 24px.

### Performance

- One requestAnimationFrame loop per cube writes SVG attributes directly, and only when they change, so React does not re-render per frame; the self-playing loop sets state once per state.
- The loop stops off screen (IntersectionObserver) and in hidden tabs, and its clock only runs while visible, so it resumes on the same frame.
- Under reduced motion nothing loops; the drawing repaints only on status changes.
- About thirty small SVG nodes and one clip path, no filters, masks or gradients.

### Notes for AI

- Map your assistant's real phases to status: waiting for the first token is thinking, streaming is writing, finished is done, failed is error, otherwise idle.
- Keep thinking short in real use and switch to writing on the first token.
- Use size 24 to 32 inline in a message header or composer, 40 to 64 in a panel header, 96 to 160 in an empty state or on a generating canvas.
- Set name to the assistant's name. Turn announce on for one mascot only. Leave status unset only for showcases.
- The default body is the accent, which is near neutral grey in Arc; the shading anchors come from it, so any accent or color prop works in light and dark.

### Related

- [AI mascot](https://uiarc.dev/components/ai-mascot/markdown): A small assistant character, a soft pebble with pill eyes and a companion dot, that shows what the AI is doing. It breathes and glances when idle, leans in to listen, looks up while the dot orbits its head, reads along the line it writes, squints with a sparkle when done and shakes once with worried brows on an error.
- [Agent status](https://uiarc.dev/components/agent-status/markdown): A compact live status pill for a running AI agent: the agent's mark in a live ring, the current activity and an elapsed timer, opening into the steps so far.
- [Text shimmer](https://uiarc.dev/components/text-shimmer/markdown): Show ongoing work with a calm light across the words.
- [AI spark](https://uiarc.dev/components/ai-spark/markdown): A brand-quality animated spark mark. Four tapered rays and four lighter diagonals breathe at rest, ripple while thinking, pulse like a heartbeat while writing, then gather and settle when done. Every status change blends from the pose the mark is already in.
- [Image reveal](https://uiarc.dev/components/image-reveal/markdown): An image generation canvas where a soft, blurred preview made from the image's own colors sharpens top to bottom behind a soft-edged band. It works the way ChatGPT, Midjourney and Gemini show images forming, with fine film grain, a translucent progress pill and calm queued and error states.
- [AI chat](https://uiarc.dev/components/blocks/ai-chat/markdown): A full-screen AI chat where answers stream in as markdown with folding reasoning, tool chips and cited sources. People can switch chats and models, edit or retry a message into versions, rate replies and stop a reply mid-stream.
- [Reasoning block](https://uiarc.dev/components/reasoning-block/markdown): The collapsible thinking block of an AI reply. While the model thinks, a shimmering label counts the seconds and the latest reasoning streams underneath. When it finishes, it folds to "Thought for 7s" and opens to show the full reasoning as calm steps with headings.

### Also in ai

- [Tool call](https://uiarc.dev/components/tool-call/markdown): A tool call row for agent transcripts: the tool's mark and the call in plain words, a live state while it runs, and the input and output a click away, with approval and retry when needed.
- [Agent plan](https://uiarc.dev/components/agent-plan/markdown): The plan an agent writes before it acts: edit, reorder or add steps while it is a draft, then watch it work through them as a live checklist.
- [Agent timeline](https://uiarc.dev/components/agent-timeline/markdown): A compact timeline of one orchestrated agent run: the orchestrator and its subagents share a time axis, handoffs draw in between rows, and a playhead replays thinking, tool calls and waiting while the header counts time, tokens and cost. Hover a span for what it did, or click it to trace its handoff path.
- [Context window](https://uiarc.dev/components/context-window/markdown): An AI context window as a grid of 200 cells: the system prompt, tools, files, summary and messages fill it in order, a threshold row marks where compaction starts, and sending a message, attaching a file or compacting shows exactly how much still fits.
- [Source cards](https://uiarc.dev/components/source-cards/markdown): A row of cited sources under an AI answer where cards stream in with real site marks while the model searches, the overflow collapses into a stack of favicons, hovering lifts a preview with the passage, and an inline [n] citation highlights its card.
- [Model card](https://uiarc.dev/components/model-card/markdown): A model details card where switching models rolls every price, limit and score in place, a token slider estimates monthly cost live, and benchmark bars show each model's rank on hover. Compare crossfades to a side-by-side table against any rival with the better values marked, and the card never changes size.
- [AI workflow](https://uiarc.dev/components/ai-workflow/markdown): A Linear-style AI workflow card where a Gmail trigger, a Claude step, a branch and Slack and Linear actions sit on one hairline rail, and a test run glides down it, opening each step's output inline. Steps are added from a compact command menu with real app marks.
- [Code suggestion](https://uiarc.dev/components/code-suggestion/markdown): An AI code edit suggestion where the model's proposed changes stream into a small editor panel as inline diff hunks, and you accept or reject each one, or all at once with Cmd+Enter. Accepted hunks fold into the file with a smooth height change.
- [Ghost text](https://uiarc.dev/components/ghost-text/markdown): An inline AI autocomplete where muted ghost text continues your sentence exactly at the caret and Tab turns it solid in place. Cmd+Right takes it one word at a time, Escape fades it away, and a calm chip shows the model behind it.
- [Image generation](https://uiarc.dev/components/image-generation/markdown): An image studio where each image forms on a dot matrix: a soft halftone wave breathes across the grid, the dots take the colours of the coming photo and grow into a coloured halftone, then blur away into the sharp photo. One large canvas with a mono size label, a filmstrip of four variations, a prompt bar with model and ratio, and upscale with a sweeping dot band, vary or download, with real provider marks and a built-in simulation.
- [Dictation button](https://uiarc.dev/components/dictation-button/markdown): A chat composer with voice input, where the mic springs into a recording pill with a smooth live waveform, a timer, and cancel and insert buttons. Words stream into the field as you speak, muted until the recognizer settles them.
- [Speech player](https://uiarc.dev/components/speech-player/markdown): A read-aloud player for AI replies. The Read aloud button in the message's action row turns into a compact player with play, a scrubbable progress bar, speed and a voice picker, and a highlight follows the spoken word through the reply, karaoke style.
- [Meeting summary](https://uiarc.dev/components/meeting-summary/markdown): An AI meeting notes card: the header shows the Google Meet or Zoom mark, the attendees and the duration. Summary, Decisions and Action items stream in after a short summarizing pass. Hover any line to see the transcript quote it came from, then check off action items or send them to Linear or Notion.
- [Reply draft](https://uiarc.dev/components/reply-draft/markdown): An AI email reply drafter where Claude streams a reply under a received Gmail message. Quick replies steer a fresh draft, tone and length rewrite it with a single crossfade, and you can edit the finished draft before you insert it.
- [Agent handoff](https://uiarc.dev/components/agent-handoff/markdown): A support conversation where an AI assistant hands off to a person. When it transfers, a card shows the summary it passes to the team and the typical wait. The person then joins and takes over, and a thin timeline on the left marks each step.
- [PII redaction](https://uiarc.dev/components/pii-redaction/markdown): A guardrail card where personal data is redacted before the prompt reaches the model. Scan marks each name, email, phone number and card with its type and swaps it for a placeholder like [EMAIL_1]. The safe prompt travels to Claude, and the reply comes back with the original values put back for the person.
- [Response feedback](https://uiarc.dev/components/response-feedback/markdown): A feedback control for AI replies where thumbs down opens an inline panel with reason chips and an optional note, thumbs up fills and asks what was good, and a submit shows a short thank-you before folding back into the row.
- [LLM cost calculator](https://uiarc.dev/components/llm-cost-calculator/markdown): A pricing calculator for LLM workloads. Set tokens per request, requests per day and prompt caching, and eight current models re-rank by monthly cost. Bars glide and prices roll as you drag.
- [Provider keys](https://uiarc.dev/components/provider-keys/markdown): A settings card for bring-your-own-key AI products. Each provider row shows its real mark, the masked key, a status and when the key was last used. You can reveal a key for five seconds, copy, rotate or remove it with undo. Adding or rotating a key opens an inline form that checks the format as you type, then tests the connection before saving.
- [Generation stats](https://uiarc.dev/components/generation-stats/markdown): A live stats strip for a streaming LLM response where time to first token, speed with a sparkline, output tokens and cost count up in tabular numerals beside the model's real mark, then settle and open into a latency and token cost breakdown.
- [AI translate](https://uiarc.dev/components/ai-translate/markdown): A message card where picking a language streams the AI translation in place, sentence by sentence over the dimmed original, with a detected-language chip, a Show original toggle and a status line credited to the model's mark.
- [TL;DR toggle](https://uiarc.dev/components/tldr-toggle/markdown): An article card with a Full, Summary and Key points switch and a length slider. Switching streams an AI summary in place of the article as the card's height springs to fit, and each key point links back to the paragraph it came from, which gets scrolled to and highlighted.
- [Connector setup](https://uiarc.dev/components/connector-setup/markdown): A "Connect your tools" card for an AI assistant. Each app connects inline: it redirects, authorizes and runs a first sync with a progress hairline, then lists the scopes it was granted and offers Disconnect with an inline confirm.
- [Smart form fill](https://uiarc.dev/components/smart-form-fill/markdown): A paste-to-fill form card where AI reads an email signature or messy notes and fills a contact field by field. Each value flashes in with a confidence dot, its source lights up in the pasted text, low-confidence guesses ask for review, and Undo puts the old values back.
- [Enrich column](https://uiarc.dev/components/enrich-column/markdown): An AI enrichment column for a data table, where one prompt runs down every row and each cell shimmers while it works, then settles into a value with its source or a failure you can retry.
- [Ticket router](https://uiarc.dev/components/ticket-router/markdown): A support ticket router where messages from Gmail, Intercom, Slack and Zendesk come in one at a time. An AI classifier labels each one with intent, sentiment and confidence, and the ticket moves into a team lane with an assignee. Low confidence tickets wait in a review lane, and one click there routes them to the suggested team.
- [Ask your data](https://uiarc.dev/components/ask-your-data/markdown): A natural language to chart card: you ask a question, PostgreSQL streams into a collapsible, syntax highlighted panel, the query runs with a rolling row count, and the answer builds as stacked bars, lines or a table, with a one line insight streamed in underneath.
- [Agent cursor](https://uiarc.dev/components/agent-cursor/markdown): A live document where Claude edits like a collaborator. Its labeled cursor comes out of its avatar, selects a paragraph and streams in a rewrite, adds a heading and fixes a typo, while a teammate's cursor reads along. Changes stay tinted until someone accepts or undoes them from a floating review bar.
- [Provider status](https://uiarc.dev/components/provider-status/markdown): A status card for the AI providers your product depends on. Each row shows the provider's real mark, its health as an icon and label, p50 latency and a 30-day uptime bar with a tooltip for each day. An incident row expands into its timeline of updates, and the card checks again on a visible countdown.
- [Training run](https://uiarc.dev/components/training-run/markdown): A fine-tuning job card where a live train and validation loss curve draws across a fixed step axis that doubles as the epoch progress bar. It shows the learning rate, elapsed time, ETA and the latest evals and checkpoints, has Pause and Cancel while it runs, and ends in results with a Deploy button.
- [AI command](https://uiarc.dev/components/ai-command/markdown): A Cmd+K command palette with an AI mode. Search pages and actions, or press Tab to ask a question: the answer streams inside the palette with numbered sources, and the next steps it suggests, like filing a Linear issue or opening a Notion doc, run straight from the list.
- [Starter prompts](https://uiarc.dev/components/starter-prompts/markdown): A greeting and a grid of starter cards for the empty state of an AI app. The cards are grouped into Write, Code, Analyze and Plan tabs, and a shuffle swaps them with a short staggered crossfade. Picking a card fills the composer, and cards that use a connected app show its mark (Gmail, GitHub, Notion, Linear, Google Calendar).
- [Pixel mascot](https://uiarc.dev/components/pixel-mascot/markdown): A pixel-art robot that shows what an AI assistant is doing. It idles, thinks, types, celebrates and errors in frame-stepped sprite animations, and stays crisp at every integer size from 24px to 192px.
- [Ghost mascot](https://uiarc.dev/components/ghost-mascot/markdown): A floating ghost mascot whose soft sheet ripples at the hem while it hovers. It blinks when idle, turns toward you to listen, fades a little translucent while thinking, draws a tiny pen line while writing, smiles with a sparkle when done and wobbles once on an error.
- [Tone tuner](https://uiarc.dev/components/tone-tuner/markdown): A brand voice card where two sliders (formality and detail) and Friendly, Confident and Empathetic chips rewrite a customer reply. Each changed sentence crossfades in place, new words can be highlighted against the original, and Copy takes the current version.
- [Upgrade prompt](https://uiarc.dev/components/upgrade-prompt/markdown): An upgrade nudge for the moment someone hits a limit. It shows a usage meter at 50 of 50 AI credits, a rolling price with a monthly and yearly toggle, three concrete unlocks with real model marks, and Upgrade or Maybe later. Upgrading leads into a success state with the new limits, and the card never changes size between states.
- [Referral card](https://uiarc.dev/components/referral-card/markdown): A give-and-get referral card where people copy or share their invite link, invite friends by email as chips, and watch invites move from invited to signed up to earned, with the credit total counting up and a milestone reward unlocking.
- [Trial banner](https://uiarc.dev/components/trial-banner/markdown): A trial status banner where a ring counts down the days left, the copy names what the workspace loses, and the upgrade path is one click away. It comes as a slim banner, a sidebar card or a header pill. It shifts to a warning tone in the last days, has expired and upgraded states, and folds into the pill when dismissed or snoozed.
- [Team switcher](https://uiarc.dev/components/team-switcher/markdown): A workspace switcher like Linear, Vercel or Slack. The trigger shows the current workspace's logo and plan. The menu has search, your role in each workspace and a Cmd+1 to 9 shortcut for each, and lets you create or join a workspace inline. A highlight glides between rows, and switching crossfades the trigger through a short loading state.
- [Live visitors](https://uiarc.dev/components/live-visitors/markdown): A realtime visitors card where the live count rolls digit by digit, new arrivals ping in on a dotted world map, the top pages reorder with bars, and signups and upgrades tick in with country flags.
- [Social proof toast](https://uiarc.dev/components/social-proof-toast/markdown): A stack of social proof notifications for landing and pricing pages, where recent trials, upgrades and verified purchases from people and companies arrive every few seconds. The stack pauses and fans out on hover, and visitors can dismiss any toast.
- [Install snippet](https://uiarc.dev/components/install-snippet/markdown): A "get started in 30 seconds" card where framework tabs, three numbered steps and highlighted snippets take a developer from install to first event. Generate key wipes a fresh API key into the placeholder in place.

### Guidance for AI tools

Cube mascot: An isometric cube mascot where three shaded faces and a painted-on face show what the assistant is doing. It turns a quarter turn in eased steps while thinking, prints lines onto the floor while writing, settles with a sparkle when done, and shakes once on error. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Tone tuner

> A brand voice card where two sliders (formality and detail) and Friendly, Confident and Empathetic chips rewrite a customer reply. Each changed sentence crossfades in place, new words can be highlighted against the original, and Copy takes the current version.

- Type: Component (special)
- Access: Arc Pro
- Page: https://uiarc.dev/components/tone-tuner
- Markdown: https://uiarc.dev/components/tone-tuner/markdown
- Source file: `registry/components/tone-tuner/tone-tuner.tsx`
- Dependencies: motion, lucide-react, @radix-ui/react-switch
- Keywords: special, saas, new, tone, brand voice, rewrite, ai writing, formality, tone slider, copy editing, email reply, diff highlight, support reply

### When to use

- A composer or help desk reply that offers AI tone controls before sending.
- Brand voice tooling where marketers compare versions of the same copy.
- Any rewrite where people want to steer with a few dials rather than write a prompt.

### When not to use

- Free form AI editing with a prompt box: use a chat or composer instead.
- Long documents: the card is sized for a message of a few paragraphs.
- Exact line by line code or contract diffs: use a dedicated diff view.

### Installation

Tone tuner is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/tone-tuner
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { ToneTuner } from "@/components/arc/tone-tuner/tone-tuner";

export function ReplyTone({ draft }: { draft: string }) {
  return (
    <ToneTuner
      text={draft}
      recipient={{ name: "Sofia Ramirez", subject: "Re: Duplicate charge on INV-20481" }}
      rewrite={async ({ text, instructions }, signal) => {
        const res = await fetch("/api/rewrite", { method: "POST", body: JSON.stringify({ text, instructions }), signal });
        if (!res.ok) throw new Error("The model did not respond.");
        return (await res.json()).text;
      }}
      onRewrite={text => console.log("New version", text)}
    />
  );
}
```

### API reference

#### ToneTuner

A message card with voice chips and two sliders (formality and detail). Each change triggers a debounced rewrite; changed sentences crossfade in place, added words can be highlighted against the original, and Copy takes the current version. With no props it tunes a sample billing reply with simulated rewrites.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `text` | `string` | – | The original draft, the source of every rewrite. Used with `rewrite`. Blank lines split paragraphs; single line breaks keep lines (a sign off). |
| `rewrite` | `(request: ToneRewriteRequest, signal: AbortSignal) => Promise<string>` | – | Calls your model and resolves to the rewritten plain text. The request has `text`, `formality`, `detail`, `voice` and a ready made `instructions` string. Superseded requests are aborted. Without it the rewrites are simulated. |
| `value` | `ToneSettings` | – | Controlled tone: `{ formality: 0 \| 1 \| 2, detail: 0 \| 1 \| 2, voice: "neutral" \| "friendly" \| "confident" \| "empathetic" }`. |
| `defaultValue` | `ToneSettings` | `{ formality: 1, detail: 1, voice: "neutral" }` | Starting tone when uncontrolled. |
| `onValueChange` | `(value: ToneSettings) => void` | – | Runs on every slider step or chip press, before the debounce. |
| `onRewrite` | `(text: string, value: ToneSettings) => void` | – | Runs when a rewrite lands, with the new plain text. |
| `onCopy` | `(text: string) => void` | – | Runs after Copy succeeds. |
| `recipient` | `{ name: string; avatar?: string; subject?: string }` | `Sofia Ramirez sample` | Who the message is for, shown in the header. |
| `model` | `string` | `"Claude Sonnet 5.5"` | The model named in the status while a rewrite runs. |
| `presets` | `TonePreset[]` | `Friendly, Confident, Empathetic` | Voice chips. A chip sets the voice and moves both sliders to its starting point; pressing it again returns to the neutral voice. |
| `debounceMs` | `number` | `220` | Quiet time after the last change before a rewrite starts. |
| `showChanges` | `boolean` | – | Controlled change highlighting. Pair with onShowChangesChange. |
| `defaultShowChanges` | `boolean` | `true` | Highlights words that differ from the original draft. |
| `onShowChangesChange` | `(show: boolean) => void` | – | Runs when the Changes switch flips. |
| `autoPlay` | `boolean` | `true for the uncontrolled sample` | Tours the presets while the card is on screen, until the first pointer press or focus inside it. |
| `className` | `string` | – | Class on the card. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Tab | Moves through the voice chips, both sliders, the Changes switch and Copy. |
| Enter / Space | Presses a voice chip, flips Changes, or copies. |
| Left / Right arrow | Steps a focused slider between its three levels. |
| Home / End | Jumps a focused slider to its first or last level. |

### Accessibility

- Voice chips are toggle buttons with aria-pressed inside a group named Voice.
- Each slider is named (Formality, Detail) and speaks its level name, not a number.
- A polite live region announces each landed rewrite with its settings, says when the sample is simulated (nothing was sent), and reports failures.
- Highlighted words use a mark element and the header counts the changed words, so changes are not shown by color alone.
- Status pairs an icon with a short label: Original draft, Rewriting, Rewritten or Couldn't rewrite with a Retry button.

### Motion

- Each changed sentence fades out in 100ms, swaps while invisible and fades in over 160ms; all changed sentences swap on the same frame, so the paragraph reflows once, out of sight. Unchanged sentences never animate.
- The text area reserves the height of the longest voice at the current formality and detail, so switching voice never resizes the card; a slider move eases it to the new height on a bounce free spring.
- The status flips to Rewriting on the same frame as the input, with a calm shimmer, then crossfades to Rewritten.
- The self playing tour pauses off screen and stops at the first interaction. Reduced motion swaps text instantly and skips the tour.

### Responsive behavior

- The card is fluid up to 640px. Under 520px the sliders stack, the chips share one row in equal columns and the status hides its settings.
- Under 400px the chip icons and changed count drop so labels never clip. Holds at 360px without horizontal scroll.
- Sliders take touch drags; vertical pans still scroll the page.

### Performance

- Rewrites are debounced and superseded requests are aborted, so dragging a slider sends at most one request after it settles.
- The word diff is an O(n×m) table over the message words, fine for a few hundred words.
- Only changed sentences animate opacity; no layout animation on text.

### Notes for AI

- Use for tone and length controls on AI rewrites: support replies, sales emails, release notes, in-app copy.
- Pass `text` and `rewrite` together. Send `instructions` to the model as the system or user instruction; it already asks to keep facts, numbers and names.
- Return plain text from `rewrite` with the same paragraph breaks so sentences line up and only changed sentences animate.
- The diff is word level against the original draft; keep the original stable while the person tunes.

### Related

- [Slider](https://uiarc.dev/components/slider/markdown): Pick a value or a range on a track that follows your finger.
- [Switch](https://uiarc.dev/components/switch/markdown): A tactile toggle for settings that take effect immediately.
- [Copy button](https://uiarc.dev/components/copy-button/markdown): Copy a value with immediate confirmation.
- [Text shimmer](https://uiarc.dev/components/text-shimmer/markdown): Show ongoing work with a calm light across the words.
- [Segmented control](https://uiarc.dev/components/segmented-control/markdown): Switch between a small set of related views.
- [Agent status](https://uiarc.dev/components/agent-status/markdown): A compact live status pill for a running AI agent: the agent's mark in a live ring, the current activity and an elapsed timer, opening into the steps so far.

### Also in ai

- [Tool call](https://uiarc.dev/components/tool-call/markdown): A tool call row for agent transcripts: the tool's mark and the call in plain words, a live state while it runs, and the input and output a click away, with approval and retry when needed.
- [Agent plan](https://uiarc.dev/components/agent-plan/markdown): The plan an agent writes before it acts: edit, reorder or add steps while it is a draft, then watch it work through them as a live checklist.
- [Agent timeline](https://uiarc.dev/components/agent-timeline/markdown): A compact timeline of one orchestrated agent run: the orchestrator and its subagents share a time axis, handoffs draw in between rows, and a playhead replays thinking, tool calls and waiting while the header counts time, tokens and cost. Hover a span for what it did, or click it to trace its handoff path.
- [Context window](https://uiarc.dev/components/context-window/markdown): An AI context window as a grid of 200 cells: the system prompt, tools, files, summary and messages fill it in order, a threshold row marks where compaction starts, and sending a message, attaching a file or compacting shows exactly how much still fits.
- [Reasoning block](https://uiarc.dev/components/reasoning-block/markdown): The collapsible thinking block of an AI reply. While the model thinks, a shimmering label counts the seconds and the latest reasoning streams underneath. When it finishes, it folds to "Thought for 7s" and opens to show the full reasoning as calm steps with headings.
- [Source cards](https://uiarc.dev/components/source-cards/markdown): A row of cited sources under an AI answer where cards stream in with real site marks while the model searches, the overflow collapses into a stack of favicons, hovering lifts a preview with the passage, and an inline [n] citation highlights its card.
- [Model card](https://uiarc.dev/components/model-card/markdown): A model details card where switching models rolls every price, limit and score in place, a token slider estimates monthly cost live, and benchmark bars show each model's rank on hover. Compare crossfades to a side-by-side table against any rival with the better values marked, and the card never changes size.
- [AI workflow](https://uiarc.dev/components/ai-workflow/markdown): A Linear-style AI workflow card where a Gmail trigger, a Claude step, a branch and Slack and Linear actions sit on one hairline rail, and a test run glides down it, opening each step's output inline. Steps are added from a compact command menu with real app marks.
- [Code suggestion](https://uiarc.dev/components/code-suggestion/markdown): An AI code edit suggestion where the model's proposed changes stream into a small editor panel as inline diff hunks, and you accept or reject each one, or all at once with Cmd+Enter. Accepted hunks fold into the file with a smooth height change.
- [Ghost text](https://uiarc.dev/components/ghost-text/markdown): An inline AI autocomplete where muted ghost text continues your sentence exactly at the caret and Tab turns it solid in place. Cmd+Right takes it one word at a time, Escape fades it away, and a calm chip shows the model behind it.
- [Image generation](https://uiarc.dev/components/image-generation/markdown): An image studio where each image forms on a dot matrix: a soft halftone wave breathes across the grid, the dots take the colours of the coming photo and grow into a coloured halftone, then blur away into the sharp photo. One large canvas with a mono size label, a filmstrip of four variations, a prompt bar with model and ratio, and upscale with a sweeping dot band, vary or download, with real provider marks and a built-in simulation.
- [Dictation button](https://uiarc.dev/components/dictation-button/markdown): A chat composer with voice input, where the mic springs into a recording pill with a smooth live waveform, a timer, and cancel and insert buttons. Words stream into the field as you speak, muted until the recognizer settles them.
- [Speech player](https://uiarc.dev/components/speech-player/markdown): A read-aloud player for AI replies. The Read aloud button in the message's action row turns into a compact player with play, a scrubbable progress bar, speed and a voice picker, and a highlight follows the spoken word through the reply, karaoke style.
- [Meeting summary](https://uiarc.dev/components/meeting-summary/markdown): An AI meeting notes card: the header shows the Google Meet or Zoom mark, the attendees and the duration. Summary, Decisions and Action items stream in after a short summarizing pass. Hover any line to see the transcript quote it came from, then check off action items or send them to Linear or Notion.
- [Reply draft](https://uiarc.dev/components/reply-draft/markdown): An AI email reply drafter where Claude streams a reply under a received Gmail message. Quick replies steer a fresh draft, tone and length rewrite it with a single crossfade, and you can edit the finished draft before you insert it.
- [Agent handoff](https://uiarc.dev/components/agent-handoff/markdown): A support conversation where an AI assistant hands off to a person. When it transfers, a card shows the summary it passes to the team and the typical wait. The person then joins and takes over, and a thin timeline on the left marks each step.
- [PII redaction](https://uiarc.dev/components/pii-redaction/markdown): A guardrail card where personal data is redacted before the prompt reaches the model. Scan marks each name, email, phone number and card with its type and swaps it for a placeholder like [EMAIL_1]. The safe prompt travels to Claude, and the reply comes back with the original values put back for the person.
- [Response feedback](https://uiarc.dev/components/response-feedback/markdown): A feedback control for AI replies where thumbs down opens an inline panel with reason chips and an optional note, thumbs up fills and asks what was good, and a submit shows a short thank-you before folding back into the row.
- [LLM cost calculator](https://uiarc.dev/components/llm-cost-calculator/markdown): A pricing calculator for LLM workloads. Set tokens per request, requests per day and prompt caching, and eight current models re-rank by monthly cost. Bars glide and prices roll as you drag.
- [Provider keys](https://uiarc.dev/components/provider-keys/markdown): A settings card for bring-your-own-key AI products. Each provider row shows its real mark, the masked key, a status and when the key was last used. You can reveal a key for five seconds, copy, rotate or remove it with undo. Adding or rotating a key opens an inline form that checks the format as you type, then tests the connection before saving.
- [Generation stats](https://uiarc.dev/components/generation-stats/markdown): A live stats strip for a streaming LLM response where time to first token, speed with a sparkline, output tokens and cost count up in tabular numerals beside the model's real mark, then settle and open into a latency and token cost breakdown.
- [AI translate](https://uiarc.dev/components/ai-translate/markdown): A message card where picking a language streams the AI translation in place, sentence by sentence over the dimmed original, with a detected-language chip, a Show original toggle and a status line credited to the model's mark.
- [TL;DR toggle](https://uiarc.dev/components/tldr-toggle/markdown): An article card with a Full, Summary and Key points switch and a length slider. Switching streams an AI summary in place of the article as the card's height springs to fit, and each key point links back to the paragraph it came from, which gets scrolled to and highlighted.
- [Connector setup](https://uiarc.dev/components/connector-setup/markdown): A "Connect your tools" card for an AI assistant. Each app connects inline: it redirects, authorizes and runs a first sync with a progress hairline, then lists the scopes it was granted and offers Disconnect with an inline confirm.
- [Smart form fill](https://uiarc.dev/components/smart-form-fill/markdown): A paste-to-fill form card where AI reads an email signature or messy notes and fills a contact field by field. Each value flashes in with a confidence dot, its source lights up in the pasted text, low-confidence guesses ask for review, and Undo puts the old values back.
- [Enrich column](https://uiarc.dev/components/enrich-column/markdown): An AI enrichment column for a data table, where one prompt runs down every row and each cell shimmers while it works, then settles into a value with its source or a failure you can retry.
- [Ticket router](https://uiarc.dev/components/ticket-router/markdown): A support ticket router where messages from Gmail, Intercom, Slack and Zendesk come in one at a time. An AI classifier labels each one with intent, sentiment and confidence, and the ticket moves into a team lane with an assignee. Low confidence tickets wait in a review lane, and one click there routes them to the suggested team.
- [Ask your data](https://uiarc.dev/components/ask-your-data/markdown): A natural language to chart card: you ask a question, PostgreSQL streams into a collapsible, syntax highlighted panel, the query runs with a rolling row count, and the answer builds as stacked bars, lines or a table, with a one line insight streamed in underneath.
- [Agent cursor](https://uiarc.dev/components/agent-cursor/markdown): A live document where Claude edits like a collaborator. Its labeled cursor comes out of its avatar, selects a paragraph and streams in a rewrite, adds a heading and fixes a typo, while a teammate's cursor reads along. Changes stay tinted until someone accepts or undoes them from a floating review bar.
- [Provider status](https://uiarc.dev/components/provider-status/markdown): A status card for the AI providers your product depends on. Each row shows the provider's real mark, its health as an icon and label, p50 latency and a 30-day uptime bar with a tooltip for each day. An incident row expands into its timeline of updates, and the card checks again on a visible countdown.
- [Training run](https://uiarc.dev/components/training-run/markdown): A fine-tuning job card where a live train and validation loss curve draws across a fixed step axis that doubles as the epoch progress bar. It shows the learning rate, elapsed time, ETA and the latest evals and checkpoints, has Pause and Cancel while it runs, and ends in results with a Deploy button.
- [AI command](https://uiarc.dev/components/ai-command/markdown): A Cmd+K command palette with an AI mode. Search pages and actions, or press Tab to ask a question: the answer streams inside the palette with numbered sources, and the next steps it suggests, like filing a Linear issue or opening a Notion doc, run straight from the list.
- [Starter prompts](https://uiarc.dev/components/starter-prompts/markdown): A greeting and a grid of starter cards for the empty state of an AI app. The cards are grouped into Write, Code, Analyze and Plan tabs, and a shuffle swaps them with a short staggered crossfade. Picking a card fills the composer, and cards that use a connected app show its mark (Gmail, GitHub, Notion, Linear, Google Calendar).
- [AI mascot](https://uiarc.dev/components/ai-mascot/markdown): A small assistant character, a soft pebble with pill eyes and a companion dot, that shows what the AI is doing. It breathes and glances when idle, leans in to listen, looks up while the dot orbits its head, reads along the line it writes, squints with a sparkle when done and shakes once with worried brows on an error.
- [Image reveal](https://uiarc.dev/components/image-reveal/markdown): An image generation canvas where a soft, blurred preview made from the image's own colors sharpens top to bottom behind a soft-edged band. It works the way ChatGPT, Midjourney and Gemini show images forming, with fine film grain, a translucent progress pill and calm queued and error states.
- [AI spark](https://uiarc.dev/components/ai-spark/markdown): A brand-quality animated spark mark. Four tapered rays and four lighter diagonals breathe at rest, ripple while thinking, pulse like a heartbeat while writing, then gather and settle when done. Every status change blends from the pose the mark is already in.
- [Pixel mascot](https://uiarc.dev/components/pixel-mascot/markdown): A pixel-art robot that shows what an AI assistant is doing. It idles, thinks, types, celebrates and errors in frame-stepped sprite animations, and stays crisp at every integer size from 24px to 192px.
- [Ghost mascot](https://uiarc.dev/components/ghost-mascot/markdown): A floating ghost mascot whose soft sheet ripples at the hem while it hovers. It blinks when idle, turns toward you to listen, fades a little translucent while thinking, draws a tiny pen line while writing, smiles with a sparkle when done and wobbles once on an error.
- [Cube mascot](https://uiarc.dev/components/cube-mascot/markdown): An isometric cube mascot where three shaded faces and a painted-on face show what the assistant is doing. It turns a quarter turn in eased steps while thinking, prints lines onto the floor while writing, settles with a sparkle when done, and shakes once on error.
- [Upgrade prompt](https://uiarc.dev/components/upgrade-prompt/markdown): An upgrade nudge for the moment someone hits a limit. It shows a usage meter at 50 of 50 AI credits, a rolling price with a monthly and yearly toggle, three concrete unlocks with real model marks, and Upgrade or Maybe later. Upgrading leads into a success state with the new limits, and the card never changes size between states.
- [Referral card](https://uiarc.dev/components/referral-card/markdown): A give-and-get referral card where people copy or share their invite link, invite friends by email as chips, and watch invites move from invited to signed up to earned, with the credit total counting up and a milestone reward unlocking.
- [Trial banner](https://uiarc.dev/components/trial-banner/markdown): A trial status banner where a ring counts down the days left, the copy names what the workspace loses, and the upgrade path is one click away. It comes as a slim banner, a sidebar card or a header pill. It shifts to a warning tone in the last days, has expired and upgraded states, and folds into the pill when dismissed or snoozed.
- [Team switcher](https://uiarc.dev/components/team-switcher/markdown): A workspace switcher like Linear, Vercel or Slack. The trigger shows the current workspace's logo and plan. The menu has search, your role in each workspace and a Cmd+1 to 9 shortcut for each, and lets you create or join a workspace inline. A highlight glides between rows, and switching crossfades the trigger through a short loading state.
- [Live visitors](https://uiarc.dev/components/live-visitors/markdown): A realtime visitors card where the live count rolls digit by digit, new arrivals ping in on a dotted world map, the top pages reorder with bars, and signups and upgrades tick in with country flags.
- [Social proof toast](https://uiarc.dev/components/social-proof-toast/markdown): A stack of social proof notifications for landing and pricing pages, where recent trials, upgrades and verified purchases from people and companies arrive every few seconds. The stack pauses and fans out on hover, and visitors can dismiss any toast.
- [Install snippet](https://uiarc.dev/components/install-snippet/markdown): A "get started in 30 seconds" card where framework tabs, three numbered steps and highlighted snippets take a developer from install to first event. Generate key wipes a fresh API key into the placeholder in place.

### Guidance for AI tools

Tone tuner: A brand voice card where two sliders (formality and detail) and Friendly, Confident and Empathetic chips rewrite a customer reply. Each changed sentence crossfades in place, new words can be highlighted against the original, and Copy takes the current version. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Upgrade prompt

> An upgrade nudge for the moment someone hits a limit. It shows a usage meter at 50 of 50 AI credits, a rolling price with a monthly and yearly toggle, three concrete unlocks with real model marks, and Upgrade or Maybe later. Upgrading leads into a success state with the new limits, and the card never changes size between states.

- Type: Component (special)
- Access: Arc Pro
- Page: https://uiarc.dev/components/upgrade-prompt
- Markdown: https://uiarc.dev/components/upgrade-prompt/markdown
- Source file: `registry/components/upgrade-prompt/upgrade-prompt.tsx`
- Dependencies: motion, lucide-react
- Keywords: special, saas, new, upgrade, paywall, upsell, limit reached, usage limit, credits, plan upgrade, pricing toggle, monthly yearly, conversion, nudge, out of credits, pro plan, billing

### When to use

- An AI product that hits a usage limit (credits, generations, seats) and needs a tasteful, conversion focused nudge.
- A paywall moment inside an app, in a dialog, popover or inline in place of the blocked result.
- Offering one next plan with a monthly and yearly price.

### When not to use

- Comparing several plans side by side: use a pricing table or plan picker.
- Buying prepaid credits without a plan change: use credit-topup.
- Passive usage reporting on a billing page: use a usage meter.

### Installation

Upgrade prompt is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/upgrade-prompt
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { UpgradePrompt } from "@/components/arc/upgrade-prompt/upgrade-prompt";

export function OutOfCredits({ workspace, onClose, retry }) {
  return (
    <UpgradePrompt
      used={workspace.credits.used}
      limit={workspace.credits.limit}
      resetsOn="Nov 1"
      onUpgrade={async (selection, signal) => {
        const res = await fetch("/api/billing/upgrade", { method: "POST", body: JSON.stringify(selection), signal });
        if (!res.ok) throw new Error((await res.json()).message ?? "Your card was declined. Try another card.");
      }}
      onUpgraded={() => workspace.refresh()}
      onContinue={() => { onClose(); retry(); }}
      onDismiss={() => { fetch("/api/nudges/upgrade/snooze", { method: "POST" }); onClose(); }}
    />
  );
}
```

### API reference

#### UpgradePrompt

The upgrade nudge shown the moment someone hits a limit: what they used, a usage meter, the price with a monthly and yearly toggle, what the next plan unlocks, Upgrade and Maybe later. Upgrading rolls into a success state with the new limits; Maybe later shows a calm reminder with a way back. With no props it shows a Free workspace at 50 of 50 AI credits and simulates the upgrade.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `used` | `number` | `50` | How much of the limit is used. |
| `limit` | `number` | `50` | The current plan's limit. At or over it the meter reads Limit reached; below it, how many are left. |
| `unit` | `string` | `"AI credits"` | What is counted, plural, such as "AI credits", "seats" or "generations". Used in the title, meter and announcements. |
| `resetsOn` | `string` | `"Nov 1"` | When the current limit resets. Shown in the description and the Maybe later reminder. |
| `plan` | `UpgradePlan` | `Pro, $20 a month or $16 a month yearly, 2,000 credits` | { name, price: { monthly, yearly }, currency?, limit, features: { id, label }[], limits: { label, value }[] }. price.yearly is the per month price when billed yearly; the saving badge and the yearly charge derive from it. Feature labels and limit values take ReactNode, so inline marks work. |
| `interval` | `"monthly" \| "yearly"` | – | Billing interval, controlled. |
| `defaultInterval` | `"monthly" \| "yearly"` | `"yearly"` | Billing interval on mount when `interval` is left out. |
| `onIntervalChange` | `(interval) => void` | – | Called when the billing toggle changes. |
| `onUpgrade` | `(selection: UpgradeSelection, signal: AbortSignal) => Promise<void>` | – | Starts the upgrade with { plan, interval, amount, currency }, where amount is charged today. Resolve when the plan is active; reject with an Error and its message shows under the price with Try again. Aborted on unmount. Leave it out to simulate a 1.1s upgrade. |
| `onUpgraded` | `(selection: UpgradeSelection) => void` | – | Called once the upgrade succeeded, after the success state shows. |
| `onDismiss` | `() => void` | – | Called by Maybe later. Record the snooze here; the card shows a reminder with See Pro again. |
| `onContinue` | `() => void` | – | Called by Continue on the success state, usually to close the dialog and retry the blocked action. Leave it out and Continue resets the demo. |
| `title` | `ReactNode` | – | Replaces the limit title, such as "You've used all 3 seats". |
| `description` | `ReactNode` | – | Replaces the line under the title. |
| `className` | `string` | – | Extra class on the card. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Tab | Moves through the billing toggle, Maybe later and Upgrade, or Continue and See Pro again in the other states. |
| ArrowLeft / ArrowRight | Switches between Monthly and Yearly on the billing toggle. |
| Enter / Space | Activates the focused button. |

### Accessibility

- The card is a labelled section ("Upgrade to Pro") with a heading, so it reads well inside a dialog or popover.
- The usage bar is role="meter" with a value text such as "50 of 50 AI credits used".
- Status is an icon plus a label (Limit reached, 1,950 AI credits left), never color alone.
- A polite live region announces upgrading, success and errors. Without onUpgrade it says the upgrade is simulated and nothing was charged.
- The rolling price is aria-hidden with a plain text copy for screen readers. Inactive states are inert and hidden, so focus never lands on a faded panel.
- Upgrade stays focusable while processing (aria-busy) so keyboard focus is not lost.

### Motion

- The usage bar fills once when it scrolls into view and settles to the new limit after the upgrade on a 0.5s bounce-free spring, moved with transform so its rounded end never stretches.
- The price rolls digit by digit between monthly and yearly on a 0.28s spring, in tabular numerals so nothing shifts.
- Title, description, meter label and counts crossfade: 100ms out, 160ms in with a 2px rise. Panels fade the same way with a 4px rise.
- Every variant and panel shares one grid cell, so the card never changes size between offer, processing, error, success and reminder, and the buttons stay in place.
- Reduced motion: the bar and price jump to their values; crossfades become plain fades.

### Responsive behavior

- Fluid up to 440px. Below 420px viewport width padding drops to 20px.
- At very narrow widths the billing toggle wraps under the price; feature lines stay single line.
- Buttons sit side by side at every width: Maybe later at its natural width, Upgrade filling the rest.

### Performance

- No timers or loops while idle; the only timeout is the simulated upgrade.
- The meter and price animate transforms only, through motion values, so there are no re-renders while they move.
- Two inline SVG marks, about 4 KB.

### Notes for AI

- Show it at the moment of value: when an action is blocked by the limit, not on page load. Put it in a dialog or popover anchored to the blocked control.
- Keep the three features concrete and specific to what the person was just doing (more credits, the better model, no waiting).
- The price is display only. Charge the plan and interval on the server; amount in the selection is for confirmation copy.
- Pass onContinue to close the prompt and retry the blocked action, so upgrading feels like it unblocked them.
- Snooze the nudge in onDismiss so it does not reappear on every blocked action.

### Related

- [Credit top-up](https://uiarc.dev/components/blocks/credit-topup/markdown): A card for buying AI credits. It shows the balance with a 14 day usage chart and how many days are left, three preset packs with bonus badges, a custom amount slider with a live price, auto top-up with a threshold and the saved Visa or Mastercard. When you buy, the new balance rolls in like an odometer.
- [Usage meter](https://uiarc.dev/components/usage-meter/markdown): Show what fills an allowance and how close it is to the limit.
- [Live checkout](https://uiarc.dev/components/blocks/checkout-live/markdown): A subscription checkout whose summary recomputes as you edit, then glides to the centre and unfolds into a receipt.
- [Segmented control](https://uiarc.dev/components/segmented-control/markdown): Switch between a small set of related views.
- [Button](https://uiarc.dev/components/button/markdown): A clear, responsive action with quiet secondary states.

### Also in ai

- [Agent status](https://uiarc.dev/components/agent-status/markdown): A compact live status pill for a running AI agent: the agent's mark in a live ring, the current activity and an elapsed timer, opening into the steps so far.
- [Tool call](https://uiarc.dev/components/tool-call/markdown): A tool call row for agent transcripts: the tool's mark and the call in plain words, a live state while it runs, and the input and output a click away, with approval and retry when needed.
- [Agent plan](https://uiarc.dev/components/agent-plan/markdown): The plan an agent writes before it acts: edit, reorder or add steps while it is a draft, then watch it work through them as a live checklist.
- [Agent timeline](https://uiarc.dev/components/agent-timeline/markdown): A compact timeline of one orchestrated agent run: the orchestrator and its subagents share a time axis, handoffs draw in between rows, and a playhead replays thinking, tool calls and waiting while the header counts time, tokens and cost. Hover a span for what it did, or click it to trace its handoff path.
- [Context window](https://uiarc.dev/components/context-window/markdown): An AI context window as a grid of 200 cells: the system prompt, tools, files, summary and messages fill it in order, a threshold row marks where compaction starts, and sending a message, attaching a file or compacting shows exactly how much still fits.
- [Reasoning block](https://uiarc.dev/components/reasoning-block/markdown): The collapsible thinking block of an AI reply. While the model thinks, a shimmering label counts the seconds and the latest reasoning streams underneath. When it finishes, it folds to "Thought for 7s" and opens to show the full reasoning as calm steps with headings.
- [Source cards](https://uiarc.dev/components/source-cards/markdown): A row of cited sources under an AI answer where cards stream in with real site marks while the model searches, the overflow collapses into a stack of favicons, hovering lifts a preview with the passage, and an inline [n] citation highlights its card.
- [Model card](https://uiarc.dev/components/model-card/markdown): A model details card where switching models rolls every price, limit and score in place, a token slider estimates monthly cost live, and benchmark bars show each model's rank on hover. Compare crossfades to a side-by-side table against any rival with the better values marked, and the card never changes size.
- [AI workflow](https://uiarc.dev/components/ai-workflow/markdown): A Linear-style AI workflow card where a Gmail trigger, a Claude step, a branch and Slack and Linear actions sit on one hairline rail, and a test run glides down it, opening each step's output inline. Steps are added from a compact command menu with real app marks.
- [Code suggestion](https://uiarc.dev/components/code-suggestion/markdown): An AI code edit suggestion where the model's proposed changes stream into a small editor panel as inline diff hunks, and you accept or reject each one, or all at once with Cmd+Enter. Accepted hunks fold into the file with a smooth height change.
- [Ghost text](https://uiarc.dev/components/ghost-text/markdown): An inline AI autocomplete where muted ghost text continues your sentence exactly at the caret and Tab turns it solid in place. Cmd+Right takes it one word at a time, Escape fades it away, and a calm chip shows the model behind it.
- [Image generation](https://uiarc.dev/components/image-generation/markdown): An image studio where each image forms on a dot matrix: a soft halftone wave breathes across the grid, the dots take the colours of the coming photo and grow into a coloured halftone, then blur away into the sharp photo. One large canvas with a mono size label, a filmstrip of four variations, a prompt bar with model and ratio, and upscale with a sweeping dot band, vary or download, with real provider marks and a built-in simulation.
- [Dictation button](https://uiarc.dev/components/dictation-button/markdown): A chat composer with voice input, where the mic springs into a recording pill with a smooth live waveform, a timer, and cancel and insert buttons. Words stream into the field as you speak, muted until the recognizer settles them.
- [Speech player](https://uiarc.dev/components/speech-player/markdown): A read-aloud player for AI replies. The Read aloud button in the message's action row turns into a compact player with play, a scrubbable progress bar, speed and a voice picker, and a highlight follows the spoken word through the reply, karaoke style.
- [Meeting summary](https://uiarc.dev/components/meeting-summary/markdown): An AI meeting notes card: the header shows the Google Meet or Zoom mark, the attendees and the duration. Summary, Decisions and Action items stream in after a short summarizing pass. Hover any line to see the transcript quote it came from, then check off action items or send them to Linear or Notion.
- [Reply draft](https://uiarc.dev/components/reply-draft/markdown): An AI email reply drafter where Claude streams a reply under a received Gmail message. Quick replies steer a fresh draft, tone and length rewrite it with a single crossfade, and you can edit the finished draft before you insert it.
- [Agent handoff](https://uiarc.dev/components/agent-handoff/markdown): A support conversation where an AI assistant hands off to a person. When it transfers, a card shows the summary it passes to the team and the typical wait. The person then joins and takes over, and a thin timeline on the left marks each step.
- [PII redaction](https://uiarc.dev/components/pii-redaction/markdown): A guardrail card where personal data is redacted before the prompt reaches the model. Scan marks each name, email, phone number and card with its type and swaps it for a placeholder like [EMAIL_1]. The safe prompt travels to Claude, and the reply comes back with the original values put back for the person.
- [Response feedback](https://uiarc.dev/components/response-feedback/markdown): A feedback control for AI replies where thumbs down opens an inline panel with reason chips and an optional note, thumbs up fills and asks what was good, and a submit shows a short thank-you before folding back into the row.
- [LLM cost calculator](https://uiarc.dev/components/llm-cost-calculator/markdown): A pricing calculator for LLM workloads. Set tokens per request, requests per day and prompt caching, and eight current models re-rank by monthly cost. Bars glide and prices roll as you drag.
- [Provider keys](https://uiarc.dev/components/provider-keys/markdown): A settings card for bring-your-own-key AI products. Each provider row shows its real mark, the masked key, a status and when the key was last used. You can reveal a key for five seconds, copy, rotate or remove it with undo. Adding or rotating a key opens an inline form that checks the format as you type, then tests the connection before saving.
- [Generation stats](https://uiarc.dev/components/generation-stats/markdown): A live stats strip for a streaming LLM response where time to first token, speed with a sparkline, output tokens and cost count up in tabular numerals beside the model's real mark, then settle and open into a latency and token cost breakdown.
- [AI translate](https://uiarc.dev/components/ai-translate/markdown): A message card where picking a language streams the AI translation in place, sentence by sentence over the dimmed original, with a detected-language chip, a Show original toggle and a status line credited to the model's mark.
- [TL;DR toggle](https://uiarc.dev/components/tldr-toggle/markdown): An article card with a Full, Summary and Key points switch and a length slider. Switching streams an AI summary in place of the article as the card's height springs to fit, and each key point links back to the paragraph it came from, which gets scrolled to and highlighted.
- [Connector setup](https://uiarc.dev/components/connector-setup/markdown): A "Connect your tools" card for an AI assistant. Each app connects inline: it redirects, authorizes and runs a first sync with a progress hairline, then lists the scopes it was granted and offers Disconnect with an inline confirm.
- [Smart form fill](https://uiarc.dev/components/smart-form-fill/markdown): A paste-to-fill form card where AI reads an email signature or messy notes and fills a contact field by field. Each value flashes in with a confidence dot, its source lights up in the pasted text, low-confidence guesses ask for review, and Undo puts the old values back.
- [Enrich column](https://uiarc.dev/components/enrich-column/markdown): An AI enrichment column for a data table, where one prompt runs down every row and each cell shimmers while it works, then settles into a value with its source or a failure you can retry.
- [Ticket router](https://uiarc.dev/components/ticket-router/markdown): A support ticket router where messages from Gmail, Intercom, Slack and Zendesk come in one at a time. An AI classifier labels each one with intent, sentiment and confidence, and the ticket moves into a team lane with an assignee. Low confidence tickets wait in a review lane, and one click there routes them to the suggested team.
- [Ask your data](https://uiarc.dev/components/ask-your-data/markdown): A natural language to chart card: you ask a question, PostgreSQL streams into a collapsible, syntax highlighted panel, the query runs with a rolling row count, and the answer builds as stacked bars, lines or a table, with a one line insight streamed in underneath.
- [Agent cursor](https://uiarc.dev/components/agent-cursor/markdown): A live document where Claude edits like a collaborator. Its labeled cursor comes out of its avatar, selects a paragraph and streams in a rewrite, adds a heading and fixes a typo, while a teammate's cursor reads along. Changes stay tinted until someone accepts or undoes them from a floating review bar.
- [Provider status](https://uiarc.dev/components/provider-status/markdown): A status card for the AI providers your product depends on. Each row shows the provider's real mark, its health as an icon and label, p50 latency and a 30-day uptime bar with a tooltip for each day. An incident row expands into its timeline of updates, and the card checks again on a visible countdown.
- [Training run](https://uiarc.dev/components/training-run/markdown): A fine-tuning job card where a live train and validation loss curve draws across a fixed step axis that doubles as the epoch progress bar. It shows the learning rate, elapsed time, ETA and the latest evals and checkpoints, has Pause and Cancel while it runs, and ends in results with a Deploy button.
- [AI command](https://uiarc.dev/components/ai-command/markdown): A Cmd+K command palette with an AI mode. Search pages and actions, or press Tab to ask a question: the answer streams inside the palette with numbered sources, and the next steps it suggests, like filing a Linear issue or opening a Notion doc, run straight from the list.
- [Starter prompts](https://uiarc.dev/components/starter-prompts/markdown): A greeting and a grid of starter cards for the empty state of an AI app. The cards are grouped into Write, Code, Analyze and Plan tabs, and a shuffle swaps them with a short staggered crossfade. Picking a card fills the composer, and cards that use a connected app show its mark (Gmail, GitHub, Notion, Linear, Google Calendar).
- [AI mascot](https://uiarc.dev/components/ai-mascot/markdown): A small assistant character, a soft pebble with pill eyes and a companion dot, that shows what the AI is doing. It breathes and glances when idle, leans in to listen, looks up while the dot orbits its head, reads along the line it writes, squints with a sparkle when done and shakes once with worried brows on an error.
- [Image reveal](https://uiarc.dev/components/image-reveal/markdown): An image generation canvas where a soft, blurred preview made from the image's own colors sharpens top to bottom behind a soft-edged band. It works the way ChatGPT, Midjourney and Gemini show images forming, with fine film grain, a translucent progress pill and calm queued and error states.
- [AI spark](https://uiarc.dev/components/ai-spark/markdown): A brand-quality animated spark mark. Four tapered rays and four lighter diagonals breathe at rest, ripple while thinking, pulse like a heartbeat while writing, then gather and settle when done. Every status change blends from the pose the mark is already in.
- [Pixel mascot](https://uiarc.dev/components/pixel-mascot/markdown): A pixel-art robot that shows what an AI assistant is doing. It idles, thinks, types, celebrates and errors in frame-stepped sprite animations, and stays crisp at every integer size from 24px to 192px.
- [Ghost mascot](https://uiarc.dev/components/ghost-mascot/markdown): A floating ghost mascot whose soft sheet ripples at the hem while it hovers. It blinks when idle, turns toward you to listen, fades a little translucent while thinking, draws a tiny pen line while writing, smiles with a sparkle when done and wobbles once on an error.
- [Cube mascot](https://uiarc.dev/components/cube-mascot/markdown): An isometric cube mascot where three shaded faces and a painted-on face show what the assistant is doing. It turns a quarter turn in eased steps while thinking, prints lines onto the floor while writing, settles with a sparkle when done, and shakes once on error.
- [Tone tuner](https://uiarc.dev/components/tone-tuner/markdown): A brand voice card where two sliders (formality and detail) and Friendly, Confident and Empathetic chips rewrite a customer reply. Each changed sentence crossfades in place, new words can be highlighted against the original, and Copy takes the current version.
- [Referral card](https://uiarc.dev/components/referral-card/markdown): A give-and-get referral card where people copy or share their invite link, invite friends by email as chips, and watch invites move from invited to signed up to earned, with the credit total counting up and a milestone reward unlocking.
- [Trial banner](https://uiarc.dev/components/trial-banner/markdown): A trial status banner where a ring counts down the days left, the copy names what the workspace loses, and the upgrade path is one click away. It comes as a slim banner, a sidebar card or a header pill. It shifts to a warning tone in the last days, has expired and upgraded states, and folds into the pill when dismissed or snoozed.
- [Team switcher](https://uiarc.dev/components/team-switcher/markdown): A workspace switcher like Linear, Vercel or Slack. The trigger shows the current workspace's logo and plan. The menu has search, your role in each workspace and a Cmd+1 to 9 shortcut for each, and lets you create or join a workspace inline. A highlight glides between rows, and switching crossfades the trigger through a short loading state.
- [Live visitors](https://uiarc.dev/components/live-visitors/markdown): A realtime visitors card where the live count rolls digit by digit, new arrivals ping in on a dotted world map, the top pages reorder with bars, and signups and upgrades tick in with country flags.
- [Social proof toast](https://uiarc.dev/components/social-proof-toast/markdown): A stack of social proof notifications for landing and pricing pages, where recent trials, upgrades and verified purchases from people and companies arrive every few seconds. The stack pauses and fans out on hover, and visitors can dismiss any toast.
- [Install snippet](https://uiarc.dev/components/install-snippet/markdown): A "get started in 30 seconds" card where framework tabs, three numbered steps and highlighted snippets take a developer from install to first event. Generate key wipes a fresh API key into the placeholder in place.

### Guidance for AI tools

Upgrade prompt: An upgrade nudge for the moment someone hits a limit. It shows a usage meter at 50 of 50 AI credits, a rolling price with a monthly and yearly toggle, three concrete unlocks with real model marks, and Upgrade or Maybe later. Upgrading leads into a success state with the new limits, and the card never changes size between states. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Referral card

> A give-and-get referral card where people copy or share their invite link, invite friends by email as chips, and watch invites move from invited to signed up to earned, with the credit total counting up and a milestone reward unlocking.

- Type: Component (special)
- Access: Arc Pro
- Page: https://uiarc.dev/components/referral-card
- Markdown: https://uiarc.dev/components/referral-card/markdown
- Source file: `registry/components/referral-card/referral-card.tsx`
- Dependencies: motion, lucide-react, avatar, button, copy-button, tooltip
- Keywords: special, saas, new, referral, refer a friend, invite, give get, affiliate, credits, share link, growth, milestone, reward

### When to use

- A referral or invite program in account settings, billing or an onboarding checklist.
- Showing a person what their invites have earned and how close they are to a bonus reward.

### When not to use

- Team member invites with roles and permissions; use a members table.
- Public leaderboards or affiliate payouts with many columns; use a table.

### Installation

Referral card is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/referral-card
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { ReferralCard } from "@/components/arc/referral-card/referral-card";

export function Referrals({ me, referrals }) {
  return (
    <ReferralCard
      link={`https://northwind.app/r/${me.code}`}
      reward={20}
      referrals={referrals}
      milestone={{ goal: 5, reward: "3 months free", detail: "Applied to your next invoice" }}
      onShare={(channel, url) => window.open(url, "_blank", "noopener,width=600,height=640")}
      onInvite={(emails, { signal }) =>
        fetch("/api/referrals/invite", { method: "POST", body: JSON.stringify({ emails }), signal }).then(response => {
          if (!response.ok) throw new Error("Could not send the invites. Nothing was sent.");
        })}
      onMilestone={() => track("referral_milestone_unlocked")}
    />
  );
}
```

### API reference

#### ReferralCard

One referral program card. The ask on top (Give $20, get $20), the invite link in a quiet field with a Copy button, X, LinkedIn and email share buttons, and an invite by email field that turns each address into a chip. Below, the funnel as three rolling numbers (invited, signed up, earned), a segmented milestone bar with the reward it unlocks, and the list of people invited with their avatar and stage (Invited, Signed up, Earned $20) as an icon plus a word. Stage changes crossfade in place, the earned total counts up, and reaching the goal turns the bar and its line into the unlocked state.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `link` | `string` | `"https://northwind.app/r/emma20"` | The person's invite link. The domain shows muted and the code in full color; Copy copies the full URL. |
| `reward` | `number` | `20` | Credit each side gets, in whole currency units. Drives the heading, the Earned total and the Earned label on rows. |
| `currency` | `string` | `"USD"` | ISO currency code used to format the reward and the total. |
| `title` | `string` | `"Give $20, get $20"` | Heading. Built from reward and currency when unset. |
| `description` | `string` | – | One or two lines under the heading. Defaults to what both sides get. |
| `referrals` | `Referral[]` | `sample program` | Everyone invited, newest first: { id, name?, email, avatar?, stage: "invited" \| "signed-up" \| "earned", invitedAt (ISO) }. Counts, the milestone and the list are derived from it. When the array changes the card follows it. Leave unset for the simulated demo. |
| `milestone` | `ReferralMilestone` | `{ goal: 5, reward: "3 months free", detail: "Applied to your next invoice" }` | Paid referrals needed (goal, up to 12 segments are drawn), the reward in a few words, and an optional line shown once unlocked. |
| `shareMessage` | `string` | – | Text that goes with the link in the X post, LinkedIn share and email body. |
| `maxInvites` | `number` | `10` | Most addresses one send can hold. Extra addresses are refused with a note. |
| `simulate` | `boolean` | `true without referrals` | Plays the sample program once on screen (a friend subscribes, another signs up and subscribes, the milestone unlocks) and moves the first address of each simulated send through the stages. |
| `onCopy` | `(link: string) => void` | – | Called after the link is copied. |
| `onShare` | `(channel: "x" \| "linkedin" \| "email", url: string) => void` | – | Called with the channel and a ready share URL (X post intent, LinkedIn share-offsite, or mailto). Open it with window.open. Without it, sharing is simulated and the live region says so. |
| `onInvite` | `(emails: string[], options: { signal: AbortSignal }) => void \| Promise<unknown>` | – | Sends the invites. Return a promise to keep Send loading; a rejection keeps the chips and shows the Error's message. On success the addresses join the top of the list as Invited. Without it, sending is simulated. |
| `onMilestone` | `(milestone: ReferralMilestone) => void` | – | Called once when paid referrals reach the goal. |
| `className` | `string` | – | Class on the root element. |

#### referralShareUrl

Helper export that builds the share URL for a channel, the same one onShare receives.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `channel` | `"x" \| "linkedin" \| "email"` | – | Share target. |
| `link` | `string` | – | Invite link. |
| `message` | `string` | – | Text for the post or email body. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Tab | Moves through Copy, the three share buttons, the email field and Send. |
| Enter, comma, space or Tab | In the email field, turns the typed address into a chip. |
| Enter | In an empty email field, sends the chips. |
| Backspace | In an empty email field, removes the last chip. Each chip also has its own remove button. |
| Cmd/Ctrl + V | Pasting addresses separated by commas, spaces or new lines adds them all. |

### Accessibility

- Share buttons are icon buttons with aria-labels (Post on X, Share on LinkedIn, Share by email) and tooltips; a polite live region reports what happened, including Simulated, nothing was posted.
- The hint under the email field is a polite status tied to the input with aria-describedby; errors set aria-invalid and show an alert icon plus text, never color alone.
- Stages are an icon plus a word. The milestone is a progressbar with aria-valuetext such as 4 of 5 paid referrals.
- The funnel is a definition list, the people a labelled list.
- While sending, the field turns read only instead of disabled, so keyboard focus stays put.

### Motion

- Numbers roll to their new value in 600ms with tabular numerals, so columns never shift.
- Stage labels, the milestone line, share icons and the hint crossfade once: old out in 100ms, new in over 160ms with a 2px rise, stacked in one grid cell.
- Milestone segments fill from the left in 240ms and turn to the success color when unlocked.
- New invites open at the top of the list with a bounce-free height spring (0.24s) inside a fixed-height list, so the card never grows.
- Reduced motion keeps every end state and drops the roll, rise and height travel; the sample program plays twice as fast.

### Responsive behavior

- The card is fluid up to 560px. Below a 470px card width the share buttons take their own full row and the milestone line keeps room for two lines.
- Long emails truncate with an ellipsis while the date stays visible; chips scroll sideways inside a fixed-height field.

### Performance

- Rolling numbers are written by motion values, not React state, so a roll causes no re-renders.
- The sample program starts when the card is 40% on screen and runs once.

### Notes for AI

- Derive everything from referrals: pass the list from your backend and update it when webhooks report sign-ups and paid conversions.
- Keep reward, currency and copy consistent with your actual program terms; the heading is built from reward.
- Use referralShareUrl when you need the same share links elsewhere.
- Only the first address of each simulated send moves through the stages, so the demo stays believable.

### Related

- [Copy button](https://uiarc.dev/components/copy-button/markdown): Copy a value with immediate confirmation.
- [Avatar](https://uiarc.dev/components/avatar/markdown): A compact identity marker for people and accounts.
- [Button](https://uiarc.dev/components/button/markdown): A clear, responsive action with quiet secondary states.
- [Tooltip](https://uiarc.dev/components/tooltip/markdown): Short supporting text for unfamiliar controls.
- [Agent status](https://uiarc.dev/components/agent-status/markdown): A compact live status pill for a running AI agent: the agent's mark in a live ring, the current activity and an elapsed timer, opening into the steps so far.

### Also in ai

- [Tool call](https://uiarc.dev/components/tool-call/markdown): A tool call row for agent transcripts: the tool's mark and the call in plain words, a live state while it runs, and the input and output a click away, with approval and retry when needed.
- [Agent plan](https://uiarc.dev/components/agent-plan/markdown): The plan an agent writes before it acts: edit, reorder or add steps while it is a draft, then watch it work through them as a live checklist.
- [Agent timeline](https://uiarc.dev/components/agent-timeline/markdown): A compact timeline of one orchestrated agent run: the orchestrator and its subagents share a time axis, handoffs draw in between rows, and a playhead replays thinking, tool calls and waiting while the header counts time, tokens and cost. Hover a span for what it did, or click it to trace its handoff path.
- [Context window](https://uiarc.dev/components/context-window/markdown): An AI context window as a grid of 200 cells: the system prompt, tools, files, summary and messages fill it in order, a threshold row marks where compaction starts, and sending a message, attaching a file or compacting shows exactly how much still fits.
- [Reasoning block](https://uiarc.dev/components/reasoning-block/markdown): The collapsible thinking block of an AI reply. While the model thinks, a shimmering label counts the seconds and the latest reasoning streams underneath. When it finishes, it folds to "Thought for 7s" and opens to show the full reasoning as calm steps with headings.
- [Source cards](https://uiarc.dev/components/source-cards/markdown): A row of cited sources under an AI answer where cards stream in with real site marks while the model searches, the overflow collapses into a stack of favicons, hovering lifts a preview with the passage, and an inline [n] citation highlights its card.
- [Model card](https://uiarc.dev/components/model-card/markdown): A model details card where switching models rolls every price, limit and score in place, a token slider estimates monthly cost live, and benchmark bars show each model's rank on hover. Compare crossfades to a side-by-side table against any rival with the better values marked, and the card never changes size.
- [AI workflow](https://uiarc.dev/components/ai-workflow/markdown): A Linear-style AI workflow card where a Gmail trigger, a Claude step, a branch and Slack and Linear actions sit on one hairline rail, and a test run glides down it, opening each step's output inline. Steps are added from a compact command menu with real app marks.
- [Code suggestion](https://uiarc.dev/components/code-suggestion/markdown): An AI code edit suggestion where the model's proposed changes stream into a small editor panel as inline diff hunks, and you accept or reject each one, or all at once with Cmd+Enter. Accepted hunks fold into the file with a smooth height change.
- [Ghost text](https://uiarc.dev/components/ghost-text/markdown): An inline AI autocomplete where muted ghost text continues your sentence exactly at the caret and Tab turns it solid in place. Cmd+Right takes it one word at a time, Escape fades it away, and a calm chip shows the model behind it.
- [Image generation](https://uiarc.dev/components/image-generation/markdown): An image studio where each image forms on a dot matrix: a soft halftone wave breathes across the grid, the dots take the colours of the coming photo and grow into a coloured halftone, then blur away into the sharp photo. One large canvas with a mono size label, a filmstrip of four variations, a prompt bar with model and ratio, and upscale with a sweeping dot band, vary or download, with real provider marks and a built-in simulation.
- [Dictation button](https://uiarc.dev/components/dictation-button/markdown): A chat composer with voice input, where the mic springs into a recording pill with a smooth live waveform, a timer, and cancel and insert buttons. Words stream into the field as you speak, muted until the recognizer settles them.
- [Speech player](https://uiarc.dev/components/speech-player/markdown): A read-aloud player for AI replies. The Read aloud button in the message's action row turns into a compact player with play, a scrubbable progress bar, speed and a voice picker, and a highlight follows the spoken word through the reply, karaoke style.
- [Meeting summary](https://uiarc.dev/components/meeting-summary/markdown): An AI meeting notes card: the header shows the Google Meet or Zoom mark, the attendees and the duration. Summary, Decisions and Action items stream in after a short summarizing pass. Hover any line to see the transcript quote it came from, then check off action items or send them to Linear or Notion.
- [Reply draft](https://uiarc.dev/components/reply-draft/markdown): An AI email reply drafter where Claude streams a reply under a received Gmail message. Quick replies steer a fresh draft, tone and length rewrite it with a single crossfade, and you can edit the finished draft before you insert it.
- [Agent handoff](https://uiarc.dev/components/agent-handoff/markdown): A support conversation where an AI assistant hands off to a person. When it transfers, a card shows the summary it passes to the team and the typical wait. The person then joins and takes over, and a thin timeline on the left marks each step.
- [PII redaction](https://uiarc.dev/components/pii-redaction/markdown): A guardrail card where personal data is redacted before the prompt reaches the model. Scan marks each name, email, phone number and card with its type and swaps it for a placeholder like [EMAIL_1]. The safe prompt travels to Claude, and the reply comes back with the original values put back for the person.
- [Response feedback](https://uiarc.dev/components/response-feedback/markdown): A feedback control for AI replies where thumbs down opens an inline panel with reason chips and an optional note, thumbs up fills and asks what was good, and a submit shows a short thank-you before folding back into the row.
- [LLM cost calculator](https://uiarc.dev/components/llm-cost-calculator/markdown): A pricing calculator for LLM workloads. Set tokens per request, requests per day and prompt caching, and eight current models re-rank by monthly cost. Bars glide and prices roll as you drag.
- [Provider keys](https://uiarc.dev/components/provider-keys/markdown): A settings card for bring-your-own-key AI products. Each provider row shows its real mark, the masked key, a status and when the key was last used. You can reveal a key for five seconds, copy, rotate or remove it with undo. Adding or rotating a key opens an inline form that checks the format as you type, then tests the connection before saving.
- [Generation stats](https://uiarc.dev/components/generation-stats/markdown): A live stats strip for a streaming LLM response where time to first token, speed with a sparkline, output tokens and cost count up in tabular numerals beside the model's real mark, then settle and open into a latency and token cost breakdown.
- [AI translate](https://uiarc.dev/components/ai-translate/markdown): A message card where picking a language streams the AI translation in place, sentence by sentence over the dimmed original, with a detected-language chip, a Show original toggle and a status line credited to the model's mark.
- [TL;DR toggle](https://uiarc.dev/components/tldr-toggle/markdown): An article card with a Full, Summary and Key points switch and a length slider. Switching streams an AI summary in place of the article as the card's height springs to fit, and each key point links back to the paragraph it came from, which gets scrolled to and highlighted.
- [Connector setup](https://uiarc.dev/components/connector-setup/markdown): A "Connect your tools" card for an AI assistant. Each app connects inline: it redirects, authorizes and runs a first sync with a progress hairline, then lists the scopes it was granted and offers Disconnect with an inline confirm.
- [Smart form fill](https://uiarc.dev/components/smart-form-fill/markdown): A paste-to-fill form card where AI reads an email signature or messy notes and fills a contact field by field. Each value flashes in with a confidence dot, its source lights up in the pasted text, low-confidence guesses ask for review, and Undo puts the old values back.
- [Enrich column](https://uiarc.dev/components/enrich-column/markdown): An AI enrichment column for a data table, where one prompt runs down every row and each cell shimmers while it works, then settles into a value with its source or a failure you can retry.
- [Ticket router](https://uiarc.dev/components/ticket-router/markdown): A support ticket router where messages from Gmail, Intercom, Slack and Zendesk come in one at a time. An AI classifier labels each one with intent, sentiment and confidence, and the ticket moves into a team lane with an assignee. Low confidence tickets wait in a review lane, and one click there routes them to the suggested team.
- [Ask your data](https://uiarc.dev/components/ask-your-data/markdown): A natural language to chart card: you ask a question, PostgreSQL streams into a collapsible, syntax highlighted panel, the query runs with a rolling row count, and the answer builds as stacked bars, lines or a table, with a one line insight streamed in underneath.
- [Agent cursor](https://uiarc.dev/components/agent-cursor/markdown): A live document where Claude edits like a collaborator. Its labeled cursor comes out of its avatar, selects a paragraph and streams in a rewrite, adds a heading and fixes a typo, while a teammate's cursor reads along. Changes stay tinted until someone accepts or undoes them from a floating review bar.
- [Provider status](https://uiarc.dev/components/provider-status/markdown): A status card for the AI providers your product depends on. Each row shows the provider's real mark, its health as an icon and label, p50 latency and a 30-day uptime bar with a tooltip for each day. An incident row expands into its timeline of updates, and the card checks again on a visible countdown.
- [Training run](https://uiarc.dev/components/training-run/markdown): A fine-tuning job card where a live train and validation loss curve draws across a fixed step axis that doubles as the epoch progress bar. It shows the learning rate, elapsed time, ETA and the latest evals and checkpoints, has Pause and Cancel while it runs, and ends in results with a Deploy button.
- [AI command](https://uiarc.dev/components/ai-command/markdown): A Cmd+K command palette with an AI mode. Search pages and actions, or press Tab to ask a question: the answer streams inside the palette with numbered sources, and the next steps it suggests, like filing a Linear issue or opening a Notion doc, run straight from the list.
- [Starter prompts](https://uiarc.dev/components/starter-prompts/markdown): A greeting and a grid of starter cards for the empty state of an AI app. The cards are grouped into Write, Code, Analyze and Plan tabs, and a shuffle swaps them with a short staggered crossfade. Picking a card fills the composer, and cards that use a connected app show its mark (Gmail, GitHub, Notion, Linear, Google Calendar).
- [AI mascot](https://uiarc.dev/components/ai-mascot/markdown): A small assistant character, a soft pebble with pill eyes and a companion dot, that shows what the AI is doing. It breathes and glances when idle, leans in to listen, looks up while the dot orbits its head, reads along the line it writes, squints with a sparkle when done and shakes once with worried brows on an error.
- [Image reveal](https://uiarc.dev/components/image-reveal/markdown): An image generation canvas where a soft, blurred preview made from the image's own colors sharpens top to bottom behind a soft-edged band. It works the way ChatGPT, Midjourney and Gemini show images forming, with fine film grain, a translucent progress pill and calm queued and error states.
- [AI spark](https://uiarc.dev/components/ai-spark/markdown): A brand-quality animated spark mark. Four tapered rays and four lighter diagonals breathe at rest, ripple while thinking, pulse like a heartbeat while writing, then gather and settle when done. Every status change blends from the pose the mark is already in.
- [Pixel mascot](https://uiarc.dev/components/pixel-mascot/markdown): A pixel-art robot that shows what an AI assistant is doing. It idles, thinks, types, celebrates and errors in frame-stepped sprite animations, and stays crisp at every integer size from 24px to 192px.
- [Ghost mascot](https://uiarc.dev/components/ghost-mascot/markdown): A floating ghost mascot whose soft sheet ripples at the hem while it hovers. It blinks when idle, turns toward you to listen, fades a little translucent while thinking, draws a tiny pen line while writing, smiles with a sparkle when done and wobbles once on an error.
- [Cube mascot](https://uiarc.dev/components/cube-mascot/markdown): An isometric cube mascot where three shaded faces and a painted-on face show what the assistant is doing. It turns a quarter turn in eased steps while thinking, prints lines onto the floor while writing, settles with a sparkle when done, and shakes once on error.
- [Tone tuner](https://uiarc.dev/components/tone-tuner/markdown): A brand voice card where two sliders (formality and detail) and Friendly, Confident and Empathetic chips rewrite a customer reply. Each changed sentence crossfades in place, new words can be highlighted against the original, and Copy takes the current version.
- [Upgrade prompt](https://uiarc.dev/components/upgrade-prompt/markdown): An upgrade nudge for the moment someone hits a limit. It shows a usage meter at 50 of 50 AI credits, a rolling price with a monthly and yearly toggle, three concrete unlocks with real model marks, and Upgrade or Maybe later. Upgrading leads into a success state with the new limits, and the card never changes size between states.
- [Trial banner](https://uiarc.dev/components/trial-banner/markdown): A trial status banner where a ring counts down the days left, the copy names what the workspace loses, and the upgrade path is one click away. It comes as a slim banner, a sidebar card or a header pill. It shifts to a warning tone in the last days, has expired and upgraded states, and folds into the pill when dismissed or snoozed.
- [Team switcher](https://uiarc.dev/components/team-switcher/markdown): A workspace switcher like Linear, Vercel or Slack. The trigger shows the current workspace's logo and plan. The menu has search, your role in each workspace and a Cmd+1 to 9 shortcut for each, and lets you create or join a workspace inline. A highlight glides between rows, and switching crossfades the trigger through a short loading state.
- [Live visitors](https://uiarc.dev/components/live-visitors/markdown): A realtime visitors card where the live count rolls digit by digit, new arrivals ping in on a dotted world map, the top pages reorder with bars, and signups and upgrades tick in with country flags.
- [Social proof toast](https://uiarc.dev/components/social-proof-toast/markdown): A stack of social proof notifications for landing and pricing pages, where recent trials, upgrades and verified purchases from people and companies arrive every few seconds. The stack pauses and fans out on hover, and visitors can dismiss any toast.
- [Install snippet](https://uiarc.dev/components/install-snippet/markdown): A "get started in 30 seconds" card where framework tabs, three numbered steps and highlighted snippets take a developer from install to first event. Generate key wipes a fresh API key into the placeholder in place.

### Guidance for AI tools

Referral card: A give-and-get referral card where people copy or share their invite link, invite friends by email as chips, and watch invites move from invited to signed up to earned, with the credit total counting up and a milestone reward unlocking. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Trial banner

> A trial status banner where a ring counts down the days left, the copy names what the workspace loses, and the upgrade path is one click away. It comes as a slim banner, a sidebar card or a header pill. It shifts to a warning tone in the last days, has expired and upgraded states, and folds into the pill when dismissed or snoozed.

- Type: Component (special)
- Access: Arc Pro
- Page: https://uiarc.dev/components/trial-banner
- Markdown: https://uiarc.dev/components/trial-banner/markdown
- Source file: `registry/components/trial-banner/trial-banner.tsx`
- Dependencies: motion, lucide-react, @radix-ui/react-dropdown-menu, @radix-ui/react-popover
- Keywords: special, saas, new, trial banner, free trial, trial countdown, upgrade banner, billing nudge, trial expired, saas trial, paywall, add payment method, snooze banner

### When to use

- A SaaS app with a free trial that needs a quiet, always visible upgrade path.
- Telling a workspace what it loses when the trial ends and nudging harder in the last days.
- Showing an expired trial without blocking the app.

### When not to use

- A hard paywall that blocks a feature; use a modal or an upgrade screen instead.
- Generic announcements or release notes; use a plain banner or toast.
- Usage limits (credits, seats); use a usage meter.

### Installation

Trial banner is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/trial-banner
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { TrialBanner } from "@/components/arc/trial-banner/trial-banner";

export function AppTrialBanner({ trial }: { trial: { daysLeft: number; endsAt: string } }) {
  return (
    <TrialBanner
      daysLeft={trial.daysLeft}
      endsAt={trial.endsAt}
      onAddPayment={async signal => {
        const res = await fetch("/api/billing/checkout", { method: "POST", signal });
        if (!res.ok) throw new Error("Checkout failed");
        window.location.assign((await res.json()).url);
      }}
      onComparePlans={() => router.push("/pricing")}
      onSnooze={({ until }) => saveSnooze(until)}
      onDismiss={() => saveDismissed()}
    />
  );
}
```

### API reference

#### TrialBanner

A trial status banner with a ring countdown, what the customer loses, and the upgrade path. Three variants share one state model: active, warning (the last days), expired and upgraded. Dismiss and snooze collapse it into the trial pill.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"banner" \| "card" \| "pill"` | `"banner"` | banner: a slim row for the top of an app. card: a sidebar card with the feature list. pill: a compact header pill that opens the card in a popover. |
| `plan` | `string` | `"Pro"` | The plan being trialed, used in every line of copy. |
| `daysLeft` | `number` | `9` | Whole days left. 0 or less shows the expired state. |
| `trialDays` | `number` | `14` | Trial length in days. The ring shows daysLeft / trialDays. |
| `endsAt` | `Date \| number \| string` | – | When the trial ends, for the date copy. Defaults to October 27, 2026 plus daysLeft, a sample date; pass your real end date. |
| `warnAt` | `number` | `3` | The last N days switch to the warning tone, with copy that names the end day. |
| `workspace` | `string` | `"Northwind"` | The workspace name, used in the expired card copy. |
| `features` | `TrialFeature[]` | `Okta SSO, Slack alerts, Linear sync, team seats` | What the customer loses without paying, listed in the card: { id, label, detail?, icon? }. Icons are 14px marks. |
| `lossSummary` | `string` | `"Okta SSO and 12 seats"` | One short phrase for the banner copy. Keep it short so the slim banner stays on one line. |
| `onAddPayment` | `(signal: AbortSignal) => Promise<void> \| void` | – | Opens checkout or the billing portal. Resolve once a payment method is on file to show the upgraded state; throw to show the error state with Try again. Simulated (900ms) when left out. |
| `onComparePlans` | `() => void` | – | Opens your plans page. Without it the banner shows a short simulated note. |
| `onManageBilling` | `() => void` | – | The secondary action in the upgraded state. |
| `onDismiss` | `() => void` | – | Called when the person dismisses the banner. Persist it. |
| `onSnooze` | `(snooze: TrialSnooze & { until: Date }) => void` | – | Called with the chosen snooze (tomorrow, in 3 days, or when the warning starts). Persist `until` and stop rendering until then. |
| `collapseTo` | `"pill" \| "none"` | `"pill"` | After dismiss or snooze: collapse to the trial pill, which reopens the banner, or render nothing. |
| `dismissible` | `boolean` | `true` | Shows the dismiss button. |
| `snoozable` | `boolean` | `true` | Shows the snooze menu. |
| `className` | `string` | – | Class on the root. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Tab | Moves through Compare plans, Add payment method, Snooze and Dismiss. |
| Enter / Space | Runs the focused action, opens the snooze menu or opens the pill's card. |
| Arrow up / down | Moves through snooze options; Escape closes the menu or the pill's popover. |

### Accessibility

- The banner and card are labelled regions ("Pro trial"); the ring is decorative and the days are always in the text.
- A polite live region announces billing, snooze and dismiss results, and says when an action was simulated.
- Status never relies on color: the warning tone also changes the copy to name the end day, expired shows a lock, upgraded a check.
- After dismiss or snooze, focus moves to the trial pill; reopening it moves focus to the primary action.

### Motion

- The ring arc springs to its new length with no bounce (0.24s); its color follows the tone in 160ms.
- Copy, days and icons swap with one crossfade (old out in 100ms, new in over 160ms with a 2px rise) in a shared grid cell, so nothing shifts.
- Button labels morph their width without bounce; the pill label width springs to the measured text.
- Reduced motion keeps every end state and drops the crossfades and springs.

### Responsive behavior

- The banner uses a container query: under 600px the buttons move under the copy, aligned with its left edge, and the sub line may take two lines (space reserved).
- The card fills its container up to 340px. The pill's popover keeps 12px from the viewport edge.
- Holds up at 360px, 390px and desktop widths without horizontal scroll.

### Performance

- No timers or loops while idle; only the simulated billing call and the short simulated note use a timeout.
- Marks are inline SVG; no images or fonts are loaded.

### Notes for AI

- Pass daysLeft and endsAt from your billing provider (for example Stripe's subscription trial_end); the component never reads the clock itself, so it renders the same on server and client.
- Use variant="banner" above the app content, "card" at the bottom of a sidebar, "pill" in a dense header.
- Keep lossSummary to a few words and features to three or four rows; these are the reasons to pay, not a feature table.
- Persist onDismiss and onSnooze yourself, then stop rendering the component until the snooze ends.

### Related

- [Agent status](https://uiarc.dev/components/agent-status/markdown): A compact live status pill for a running AI agent: the agent's mark in a live ring, the current activity and an elapsed timer, opening into the steps so far.
- [Button](https://uiarc.dev/components/button/markdown): A clear, responsive action with quiet secondary states.
- [Dropdown menu](https://uiarc.dev/components/dropdown-menu/markdown): A focused list of actions anchored to a trigger.
- [Popover](https://uiarc.dev/components/popover/markdown): A small anchored surface for contextual information.
- [Segmented control](https://uiarc.dev/components/segmented-control/markdown): Switch between a small set of related views.

### Also in ai

- [Tool call](https://uiarc.dev/components/tool-call/markdown): A tool call row for agent transcripts: the tool's mark and the call in plain words, a live state while it runs, and the input and output a click away, with approval and retry when needed.
- [Agent plan](https://uiarc.dev/components/agent-plan/markdown): The plan an agent writes before it acts: edit, reorder or add steps while it is a draft, then watch it work through them as a live checklist.
- [Agent timeline](https://uiarc.dev/components/agent-timeline/markdown): A compact timeline of one orchestrated agent run: the orchestrator and its subagents share a time axis, handoffs draw in between rows, and a playhead replays thinking, tool calls and waiting while the header counts time, tokens and cost. Hover a span for what it did, or click it to trace its handoff path.
- [Context window](https://uiarc.dev/components/context-window/markdown): An AI context window as a grid of 200 cells: the system prompt, tools, files, summary and messages fill it in order, a threshold row marks where compaction starts, and sending a message, attaching a file or compacting shows exactly how much still fits.
- [Reasoning block](https://uiarc.dev/components/reasoning-block/markdown): The collapsible thinking block of an AI reply. While the model thinks, a shimmering label counts the seconds and the latest reasoning streams underneath. When it finishes, it folds to "Thought for 7s" and opens to show the full reasoning as calm steps with headings.
- [Source cards](https://uiarc.dev/components/source-cards/markdown): A row of cited sources under an AI answer where cards stream in with real site marks while the model searches, the overflow collapses into a stack of favicons, hovering lifts a preview with the passage, and an inline [n] citation highlights its card.
- [Model card](https://uiarc.dev/components/model-card/markdown): A model details card where switching models rolls every price, limit and score in place, a token slider estimates monthly cost live, and benchmark bars show each model's rank on hover. Compare crossfades to a side-by-side table against any rival with the better values marked, and the card never changes size.
- [AI workflow](https://uiarc.dev/components/ai-workflow/markdown): A Linear-style AI workflow card where a Gmail trigger, a Claude step, a branch and Slack and Linear actions sit on one hairline rail, and a test run glides down it, opening each step's output inline. Steps are added from a compact command menu with real app marks.
- [Code suggestion](https://uiarc.dev/components/code-suggestion/markdown): An AI code edit suggestion where the model's proposed changes stream into a small editor panel as inline diff hunks, and you accept or reject each one, or all at once with Cmd+Enter. Accepted hunks fold into the file with a smooth height change.
- [Ghost text](https://uiarc.dev/components/ghost-text/markdown): An inline AI autocomplete where muted ghost text continues your sentence exactly at the caret and Tab turns it solid in place. Cmd+Right takes it one word at a time, Escape fades it away, and a calm chip shows the model behind it.
- [Image generation](https://uiarc.dev/components/image-generation/markdown): An image studio where each image forms on a dot matrix: a soft halftone wave breathes across the grid, the dots take the colours of the coming photo and grow into a coloured halftone, then blur away into the sharp photo. One large canvas with a mono size label, a filmstrip of four variations, a prompt bar with model and ratio, and upscale with a sweeping dot band, vary or download, with real provider marks and a built-in simulation.
- [Dictation button](https://uiarc.dev/components/dictation-button/markdown): A chat composer with voice input, where the mic springs into a recording pill with a smooth live waveform, a timer, and cancel and insert buttons. Words stream into the field as you speak, muted until the recognizer settles them.
- [Speech player](https://uiarc.dev/components/speech-player/markdown): A read-aloud player for AI replies. The Read aloud button in the message's action row turns into a compact player with play, a scrubbable progress bar, speed and a voice picker, and a highlight follows the spoken word through the reply, karaoke style.
- [Meeting summary](https://uiarc.dev/components/meeting-summary/markdown): An AI meeting notes card: the header shows the Google Meet or Zoom mark, the attendees and the duration. Summary, Decisions and Action items stream in after a short summarizing pass. Hover any line to see the transcript quote it came from, then check off action items or send them to Linear or Notion.
- [Reply draft](https://uiarc.dev/components/reply-draft/markdown): An AI email reply drafter where Claude streams a reply under a received Gmail message. Quick replies steer a fresh draft, tone and length rewrite it with a single crossfade, and you can edit the finished draft before you insert it.
- [Agent handoff](https://uiarc.dev/components/agent-handoff/markdown): A support conversation where an AI assistant hands off to a person. When it transfers, a card shows the summary it passes to the team and the typical wait. The person then joins and takes over, and a thin timeline on the left marks each step.
- [PII redaction](https://uiarc.dev/components/pii-redaction/markdown): A guardrail card where personal data is redacted before the prompt reaches the model. Scan marks each name, email, phone number and card with its type and swaps it for a placeholder like [EMAIL_1]. The safe prompt travels to Claude, and the reply comes back with the original values put back for the person.
- [Response feedback](https://uiarc.dev/components/response-feedback/markdown): A feedback control for AI replies where thumbs down opens an inline panel with reason chips and an optional note, thumbs up fills and asks what was good, and a submit shows a short thank-you before folding back into the row.
- [LLM cost calculator](https://uiarc.dev/components/llm-cost-calculator/markdown): A pricing calculator for LLM workloads. Set tokens per request, requests per day and prompt caching, and eight current models re-rank by monthly cost. Bars glide and prices roll as you drag.
- [Provider keys](https://uiarc.dev/components/provider-keys/markdown): A settings card for bring-your-own-key AI products. Each provider row shows its real mark, the masked key, a status and when the key was last used. You can reveal a key for five seconds, copy, rotate or remove it with undo. Adding or rotating a key opens an inline form that checks the format as you type, then tests the connection before saving.
- [Generation stats](https://uiarc.dev/components/generation-stats/markdown): A live stats strip for a streaming LLM response where time to first token, speed with a sparkline, output tokens and cost count up in tabular numerals beside the model's real mark, then settle and open into a latency and token cost breakdown.
- [AI translate](https://uiarc.dev/components/ai-translate/markdown): A message card where picking a language streams the AI translation in place, sentence by sentence over the dimmed original, with a detected-language chip, a Show original toggle and a status line credited to the model's mark.
- [TL;DR toggle](https://uiarc.dev/components/tldr-toggle/markdown): An article card with a Full, Summary and Key points switch and a length slider. Switching streams an AI summary in place of the article as the card's height springs to fit, and each key point links back to the paragraph it came from, which gets scrolled to and highlighted.
- [Connector setup](https://uiarc.dev/components/connector-setup/markdown): A "Connect your tools" card for an AI assistant. Each app connects inline: it redirects, authorizes and runs a first sync with a progress hairline, then lists the scopes it was granted and offers Disconnect with an inline confirm.
- [Smart form fill](https://uiarc.dev/components/smart-form-fill/markdown): A paste-to-fill form card where AI reads an email signature or messy notes and fills a contact field by field. Each value flashes in with a confidence dot, its source lights up in the pasted text, low-confidence guesses ask for review, and Undo puts the old values back.
- [Enrich column](https://uiarc.dev/components/enrich-column/markdown): An AI enrichment column for a data table, where one prompt runs down every row and each cell shimmers while it works, then settles into a value with its source or a failure you can retry.
- [Ticket router](https://uiarc.dev/components/ticket-router/markdown): A support ticket router where messages from Gmail, Intercom, Slack and Zendesk come in one at a time. An AI classifier labels each one with intent, sentiment and confidence, and the ticket moves into a team lane with an assignee. Low confidence tickets wait in a review lane, and one click there routes them to the suggested team.
- [Ask your data](https://uiarc.dev/components/ask-your-data/markdown): A natural language to chart card: you ask a question, PostgreSQL streams into a collapsible, syntax highlighted panel, the query runs with a rolling row count, and the answer builds as stacked bars, lines or a table, with a one line insight streamed in underneath.
- [Agent cursor](https://uiarc.dev/components/agent-cursor/markdown): A live document where Claude edits like a collaborator. Its labeled cursor comes out of its avatar, selects a paragraph and streams in a rewrite, adds a heading and fixes a typo, while a teammate's cursor reads along. Changes stay tinted until someone accepts or undoes them from a floating review bar.
- [Provider status](https://uiarc.dev/components/provider-status/markdown): A status card for the AI providers your product depends on. Each row shows the provider's real mark, its health as an icon and label, p50 latency and a 30-day uptime bar with a tooltip for each day. An incident row expands into its timeline of updates, and the card checks again on a visible countdown.
- [Training run](https://uiarc.dev/components/training-run/markdown): A fine-tuning job card where a live train and validation loss curve draws across a fixed step axis that doubles as the epoch progress bar. It shows the learning rate, elapsed time, ETA and the latest evals and checkpoints, has Pause and Cancel while it runs, and ends in results with a Deploy button.
- [AI command](https://uiarc.dev/components/ai-command/markdown): A Cmd+K command palette with an AI mode. Search pages and actions, or press Tab to ask a question: the answer streams inside the palette with numbered sources, and the next steps it suggests, like filing a Linear issue or opening a Notion doc, run straight from the list.
- [Starter prompts](https://uiarc.dev/components/starter-prompts/markdown): A greeting and a grid of starter cards for the empty state of an AI app. The cards are grouped into Write, Code, Analyze and Plan tabs, and a shuffle swaps them with a short staggered crossfade. Picking a card fills the composer, and cards that use a connected app show its mark (Gmail, GitHub, Notion, Linear, Google Calendar).
- [AI mascot](https://uiarc.dev/components/ai-mascot/markdown): A small assistant character, a soft pebble with pill eyes and a companion dot, that shows what the AI is doing. It breathes and glances when idle, leans in to listen, looks up while the dot orbits its head, reads along the line it writes, squints with a sparkle when done and shakes once with worried brows on an error.
- [Image reveal](https://uiarc.dev/components/image-reveal/markdown): An image generation canvas where a soft, blurred preview made from the image's own colors sharpens top to bottom behind a soft-edged band. It works the way ChatGPT, Midjourney and Gemini show images forming, with fine film grain, a translucent progress pill and calm queued and error states.
- [AI spark](https://uiarc.dev/components/ai-spark/markdown): A brand-quality animated spark mark. Four tapered rays and four lighter diagonals breathe at rest, ripple while thinking, pulse like a heartbeat while writing, then gather and settle when done. Every status change blends from the pose the mark is already in.
- [Pixel mascot](https://uiarc.dev/components/pixel-mascot/markdown): A pixel-art robot that shows what an AI assistant is doing. It idles, thinks, types, celebrates and errors in frame-stepped sprite animations, and stays crisp at every integer size from 24px to 192px.
- [Ghost mascot](https://uiarc.dev/components/ghost-mascot/markdown): A floating ghost mascot whose soft sheet ripples at the hem while it hovers. It blinks when idle, turns toward you to listen, fades a little translucent while thinking, draws a tiny pen line while writing, smiles with a sparkle when done and wobbles once on an error.
- [Cube mascot](https://uiarc.dev/components/cube-mascot/markdown): An isometric cube mascot where three shaded faces and a painted-on face show what the assistant is doing. It turns a quarter turn in eased steps while thinking, prints lines onto the floor while writing, settles with a sparkle when done, and shakes once on error.
- [Tone tuner](https://uiarc.dev/components/tone-tuner/markdown): A brand voice card where two sliders (formality and detail) and Friendly, Confident and Empathetic chips rewrite a customer reply. Each changed sentence crossfades in place, new words can be highlighted against the original, and Copy takes the current version.
- [Upgrade prompt](https://uiarc.dev/components/upgrade-prompt/markdown): An upgrade nudge for the moment someone hits a limit. It shows a usage meter at 50 of 50 AI credits, a rolling price with a monthly and yearly toggle, three concrete unlocks with real model marks, and Upgrade or Maybe later. Upgrading leads into a success state with the new limits, and the card never changes size between states.
- [Referral card](https://uiarc.dev/components/referral-card/markdown): A give-and-get referral card where people copy or share their invite link, invite friends by email as chips, and watch invites move from invited to signed up to earned, with the credit total counting up and a milestone reward unlocking.
- [Team switcher](https://uiarc.dev/components/team-switcher/markdown): A workspace switcher like Linear, Vercel or Slack. The trigger shows the current workspace's logo and plan. The menu has search, your role in each workspace and a Cmd+1 to 9 shortcut for each, and lets you create or join a workspace inline. A highlight glides between rows, and switching crossfades the trigger through a short loading state.
- [Live visitors](https://uiarc.dev/components/live-visitors/markdown): A realtime visitors card where the live count rolls digit by digit, new arrivals ping in on a dotted world map, the top pages reorder with bars, and signups and upgrades tick in with country flags.
- [Social proof toast](https://uiarc.dev/components/social-proof-toast/markdown): A stack of social proof notifications for landing and pricing pages, where recent trials, upgrades and verified purchases from people and companies arrive every few seconds. The stack pauses and fans out on hover, and visitors can dismiss any toast.
- [Install snippet](https://uiarc.dev/components/install-snippet/markdown): A "get started in 30 seconds" card where framework tabs, three numbered steps and highlighted snippets take a developer from install to first event. Generate key wipes a fresh API key into the placeholder in place.

### Guidance for AI tools

Trial banner: A trial status banner where a ring counts down the days left, the copy names what the workspace loses, and the upgrade path is one click away. It comes as a slim banner, a sidebar card or a header pill. It shifts to a warning tone in the last days, has expired and upgraded states, and folds into the pill when dismissed or snoozed. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Team switcher

> A workspace switcher like Linear, Vercel or Slack. The trigger shows the current workspace's logo and plan. The menu has search, your role in each workspace and a Cmd+1 to 9 shortcut for each, and lets you create or join a workspace inline. A highlight glides between rows, and switching crossfades the trigger through a short loading state.

- Type: Component (special)
- Access: Arc Pro
- Page: https://uiarc.dev/components/team-switcher
- Markdown: https://uiarc.dev/components/team-switcher/markdown
- Source file: `registry/components/team-switcher/team-switcher.tsx`
- Dependencies: motion, lucide-react
- Keywords: special, saas, new, team switcher, workspace switcher, organization switcher, org picker, account switcher, tenant switcher, project switcher, multi-tenant, linear, vercel, slack, dropdown

### When to use

- Switching between organizations, teams or workspaces in a multi-tenant SaaS app.
- An account or project picker that needs search, roles and keyboard shortcuts.
- Letting people create a new workspace or accept an invite without leaving the current page.

### When not to use

- Picking from a short static list of options in a form: use a select or segmented control.
- Global navigation across pages and commands: use the command palette block.
- Switching between two or three views of the same data: use tabs.

### Installation

Team switcher is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/team-switcher
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { useState } from "react";
import { TeamSwitcher } from "@/components/arc/team-switcher/team-switcher";

const workspaces = [
  { id: "acme", name: "Acme", plan: "Enterprise", members: 214, role: "Admin" },
  { id: "acme-labs", name: "Acme Labs", plan: "Pro", members: 12, role: "Owner" },
];

export function AppHeader() {
  const [workspaceId, setWorkspaceId] = useState("acme");
  return (
    <TeamSwitcher
      workspaces={workspaces}
      value={workspaceId}
      onValueChange={setWorkspaceId}
      onSwitch={(workspace, signal) => api.session.switch(workspace.id, { signal })}
      onCreateWorkspace={async (name, signal) => api.workspaces.create({ name }, { signal })}
      onJoinWorkspace={async (invite, signal) => api.invites.accept(invite, { signal })}
    />
  );
}
```

### API reference

#### TeamSwitcher

A workspace switcher: a trigger with the current workspace's logo and plan, and a menu with search, roles, Cmd/Ctrl+number shortcuts, and inline create and join views. With no props it switches between six sample workspaces and simulates every action.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `workspaces` | `Workspace[]` | `sampleWorkspaces` | The workspaces you belong to: { id, name, plan?, members?, role?, logo?, tile?: { background, color? } }. The first nine get Cmd/Ctrl+1 to 9. Size a custom logo in em; the tile sets font-size to its own size. |
| `value` | `string` | – | The active workspace id. Pair with onValueChange. |
| `defaultValue` | `string` | `first workspace` | The starting workspace when uncontrolled. |
| `onValueChange` | `(id: string, workspace: Workspace) => void` | – | Called once a switch has finished loading. |
| `onSwitch` | `(workspace: Workspace, signal: AbortSignal) => Promise<void>` | – | Loads the workspace. The trigger crossfades to the new workspace with a switching state until it resolves; a rejection reverts and shows the error's message. A newer switch aborts the older one. Simulated (650ms) when left out. |
| `onCreateWorkspace` | `(name: string, signal: AbortSignal) => Promise<Workspace \| void>` | – | Creates a workspace. Return it to add it and switch to it; throw an Error to show its message under the field. Simulated when left out. |
| `onJoinWorkspace` | `(invite: string, signal: AbortSignal) => Promise<Workspace \| void>` | – | Joins from an invite link or code. Return the workspace to switch to it; throw an Error to show its message. Simulated when left out, with sample invites for Resend and Notion. |
| `open` | `boolean` | – | Controls the menu. Pair with onOpenChange. |
| `defaultOpen` | `boolean` | `false` | Starts with the menu open, without moving focus. |
| `onOpenChange` | `(open: boolean) => void` | – | Called when the menu opens or closes. |
| `globalShortcuts` | `boolean` | `false` | Listens for Cmd/Ctrl+1 to 9 anywhere on the page. Off, the shortcuts work while focus is inside the switcher. |
| `simulatedDelay` | `number` | `650` | How long the simulated switch takes, in milliseconds. |
| `disabled` | `boolean` | `false` | Disables the trigger. |
| `className` | `string` | – | Class on the root. The root is up to 360px wide and fills narrower containers. |

#### WorkspaceTile

The workspace avatar on its own: the brand mark on its brand color, or the first letter of the name.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `workspace` (required) | `Workspace` | – | The workspace to draw. |
| `size` | `number` | `28` | Tile size in pixels. The corner radius and mark scale with it. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Enter / Space / ArrowDown | On the trigger, opens the menu and moves focus to the search field. |
| Type | Filters workspaces by name, plan or role. With no match, Enter opens Create workspace with the name filled in. |
| ArrowDown / ArrowUp | Moves the highlight through workspaces and actions, wrapping at the ends. |
| Home / End | Jumps to the first or last item when the search is empty. |
| Enter | Switches to the highlighted workspace, or opens Create workspace or Join with invite. |
| Cmd/Ctrl+1 to 9 | Switches to the workspace at that place in the list. Works while focus is in the switcher, or anywhere with globalShortcuts. |
| Escape | Goes back from create or join, then clears the search, then closes and returns focus to the trigger. |

### Accessibility

- The trigger is a button with aria-haspopup="dialog", aria-expanded and aria-busy while switching; its label reads the workspace and its plan.
- The search field is a combobox that owns a listbox and points at the highlighted row with aria-activedescendant, so focus never leaves the field while navigating.
- The current workspace is aria-selected and marked with a check icon, not color alone. Errors pair an icon with text.
- A polite live region announces switching, the result, and when an action was simulated ("Simulated, nothing was sent").
- Closing with Escape or by choosing returns focus to the trigger. Tabbing out or clicking outside closes the menu.

### Motion

- The menu fades and scales in from 98% over 180ms and leaves in 120ms.
- One highlight glides between rows with a bounce-free spring (visualDuration 0.24) and appears in place instead of sliding in from the top.
- Switching crossfades the trigger's logo, name and plan line (100ms out, 160ms in, 2px y) through a shimmer label and a spinner. Nothing resizes.
- The create and join views crossfade inside a fixed-height panel with a 6px horizontal shift that follows the navigation direction.
- Reduced motion keeps the crossfades and feedback as plain fades and drops the glide, shifts and scale.

### Responsive behavior

- The root is up to 360px wide and fills narrower containers, so it holds at 360px and 390px viewports.
- Names and plan lines truncate with an ellipsis; roles and shortcuts keep their width.
- The list shows six rows and scrolls beyond that without a visible scrollbar; the panel height never changes.
- Rows are 48px tall for touch, and pointer and keyboard drive the same highlight.

### Performance

- One motion value pair drives the highlight; rows do not animate individually.
- Filtering is a plain in-memory match on name, plan and role, fine for hundreds of workspaces.
- Marks are inline SVG; no images load.

### Notes for AI

- Use it at the top of an app sidebar or in a header for multi-tenant SaaS: organizations, teams, projects or stores.
- Pass real workspaces with logo and tile when the tenant has a brand mark; otherwise the tile falls back to a letter avatar.
- Wire onSwitch to whatever loads the tenant (route prefetch, session switch); keep the promise short, the trigger shows a loading state meanwhile.
- Return the created or joined workspace from onCreateWorkspace or onJoinWorkspace and also add it to the workspaces prop; the switcher dedupes by id.
- The menu is absolutely positioned below the trigger. Leave about 450px below it or place it where the panel can overflow.

### Related

- [Dropdown menu](https://uiarc.dev/components/dropdown-menu/markdown): A focused list of actions anchored to a trigger.
- [Popover](https://uiarc.dev/components/popover/markdown): A small anchored surface for contextual information.
- [Combobox](https://uiarc.dev/components/combobox/markdown): Search and select from a list without leaving the field.
- [Avatar](https://uiarc.dev/components/avatar/markdown): A compact identity marker for people and accounts.

### Also in ai

- [Agent status](https://uiarc.dev/components/agent-status/markdown): A compact live status pill for a running AI agent: the agent's mark in a live ring, the current activity and an elapsed timer, opening into the steps so far.
- [Tool call](https://uiarc.dev/components/tool-call/markdown): A tool call row for agent transcripts: the tool's mark and the call in plain words, a live state while it runs, and the input and output a click away, with approval and retry when needed.
- [Agent plan](https://uiarc.dev/components/agent-plan/markdown): The plan an agent writes before it acts: edit, reorder or add steps while it is a draft, then watch it work through them as a live checklist.
- [Agent timeline](https://uiarc.dev/components/agent-timeline/markdown): A compact timeline of one orchestrated agent run: the orchestrator and its subagents share a time axis, handoffs draw in between rows, and a playhead replays thinking, tool calls and waiting while the header counts time, tokens and cost. Hover a span for what it did, or click it to trace its handoff path.
- [Context window](https://uiarc.dev/components/context-window/markdown): An AI context window as a grid of 200 cells: the system prompt, tools, files, summary and messages fill it in order, a threshold row marks where compaction starts, and sending a message, attaching a file or compacting shows exactly how much still fits.
- [Reasoning block](https://uiarc.dev/components/reasoning-block/markdown): The collapsible thinking block of an AI reply. While the model thinks, a shimmering label counts the seconds and the latest reasoning streams underneath. When it finishes, it folds to "Thought for 7s" and opens to show the full reasoning as calm steps with headings.
- [Source cards](https://uiarc.dev/components/source-cards/markdown): A row of cited sources under an AI answer where cards stream in with real site marks while the model searches, the overflow collapses into a stack of favicons, hovering lifts a preview with the passage, and an inline [n] citation highlights its card.
- [Model card](https://uiarc.dev/components/model-card/markdown): A model details card where switching models rolls every price, limit and score in place, a token slider estimates monthly cost live, and benchmark bars show each model's rank on hover. Compare crossfades to a side-by-side table against any rival with the better values marked, and the card never changes size.
- [AI workflow](https://uiarc.dev/components/ai-workflow/markdown): A Linear-style AI workflow card where a Gmail trigger, a Claude step, a branch and Slack and Linear actions sit on one hairline rail, and a test run glides down it, opening each step's output inline. Steps are added from a compact command menu with real app marks.
- [Code suggestion](https://uiarc.dev/components/code-suggestion/markdown): An AI code edit suggestion where the model's proposed changes stream into a small editor panel as inline diff hunks, and you accept or reject each one, or all at once with Cmd+Enter. Accepted hunks fold into the file with a smooth height change.
- [Ghost text](https://uiarc.dev/components/ghost-text/markdown): An inline AI autocomplete where muted ghost text continues your sentence exactly at the caret and Tab turns it solid in place. Cmd+Right takes it one word at a time, Escape fades it away, and a calm chip shows the model behind it.
- [Image generation](https://uiarc.dev/components/image-generation/markdown): An image studio where each image forms on a dot matrix: a soft halftone wave breathes across the grid, the dots take the colours of the coming photo and grow into a coloured halftone, then blur away into the sharp photo. One large canvas with a mono size label, a filmstrip of four variations, a prompt bar with model and ratio, and upscale with a sweeping dot band, vary or download, with real provider marks and a built-in simulation.
- [Dictation button](https://uiarc.dev/components/dictation-button/markdown): A chat composer with voice input, where the mic springs into a recording pill with a smooth live waveform, a timer, and cancel and insert buttons. Words stream into the field as you speak, muted until the recognizer settles them.
- [Speech player](https://uiarc.dev/components/speech-player/markdown): A read-aloud player for AI replies. The Read aloud button in the message's action row turns into a compact player with play, a scrubbable progress bar, speed and a voice picker, and a highlight follows the spoken word through the reply, karaoke style.
- [Meeting summary](https://uiarc.dev/components/meeting-summary/markdown): An AI meeting notes card: the header shows the Google Meet or Zoom mark, the attendees and the duration. Summary, Decisions and Action items stream in after a short summarizing pass. Hover any line to see the transcript quote it came from, then check off action items or send them to Linear or Notion.
- [Reply draft](https://uiarc.dev/components/reply-draft/markdown): An AI email reply drafter where Claude streams a reply under a received Gmail message. Quick replies steer a fresh draft, tone and length rewrite it with a single crossfade, and you can edit the finished draft before you insert it.
- [Agent handoff](https://uiarc.dev/components/agent-handoff/markdown): A support conversation where an AI assistant hands off to a person. When it transfers, a card shows the summary it passes to the team and the typical wait. The person then joins and takes over, and a thin timeline on the left marks each step.
- [PII redaction](https://uiarc.dev/components/pii-redaction/markdown): A guardrail card where personal data is redacted before the prompt reaches the model. Scan marks each name, email, phone number and card with its type and swaps it for a placeholder like [EMAIL_1]. The safe prompt travels to Claude, and the reply comes back with the original values put back for the person.
- [Response feedback](https://uiarc.dev/components/response-feedback/markdown): A feedback control for AI replies where thumbs down opens an inline panel with reason chips and an optional note, thumbs up fills and asks what was good, and a submit shows a short thank-you before folding back into the row.
- [LLM cost calculator](https://uiarc.dev/components/llm-cost-calculator/markdown): A pricing calculator for LLM workloads. Set tokens per request, requests per day and prompt caching, and eight current models re-rank by monthly cost. Bars glide and prices roll as you drag.
- [Provider keys](https://uiarc.dev/components/provider-keys/markdown): A settings card for bring-your-own-key AI products. Each provider row shows its real mark, the masked key, a status and when the key was last used. You can reveal a key for five seconds, copy, rotate or remove it with undo. Adding or rotating a key opens an inline form that checks the format as you type, then tests the connection before saving.
- [Generation stats](https://uiarc.dev/components/generation-stats/markdown): A live stats strip for a streaming LLM response where time to first token, speed with a sparkline, output tokens and cost count up in tabular numerals beside the model's real mark, then settle and open into a latency and token cost breakdown.
- [AI translate](https://uiarc.dev/components/ai-translate/markdown): A message card where picking a language streams the AI translation in place, sentence by sentence over the dimmed original, with a detected-language chip, a Show original toggle and a status line credited to the model's mark.
- [TL;DR toggle](https://uiarc.dev/components/tldr-toggle/markdown): An article card with a Full, Summary and Key points switch and a length slider. Switching streams an AI summary in place of the article as the card's height springs to fit, and each key point links back to the paragraph it came from, which gets scrolled to and highlighted.
- [Connector setup](https://uiarc.dev/components/connector-setup/markdown): A "Connect your tools" card for an AI assistant. Each app connects inline: it redirects, authorizes and runs a first sync with a progress hairline, then lists the scopes it was granted and offers Disconnect with an inline confirm.
- [Smart form fill](https://uiarc.dev/components/smart-form-fill/markdown): A paste-to-fill form card where AI reads an email signature or messy notes and fills a contact field by field. Each value flashes in with a confidence dot, its source lights up in the pasted text, low-confidence guesses ask for review, and Undo puts the old values back.
- [Enrich column](https://uiarc.dev/components/enrich-column/markdown): An AI enrichment column for a data table, where one prompt runs down every row and each cell shimmers while it works, then settles into a value with its source or a failure you can retry.
- [Ticket router](https://uiarc.dev/components/ticket-router/markdown): A support ticket router where messages from Gmail, Intercom, Slack and Zendesk come in one at a time. An AI classifier labels each one with intent, sentiment and confidence, and the ticket moves into a team lane with an assignee. Low confidence tickets wait in a review lane, and one click there routes them to the suggested team.
- [Ask your data](https://uiarc.dev/components/ask-your-data/markdown): A natural language to chart card: you ask a question, PostgreSQL streams into a collapsible, syntax highlighted panel, the query runs with a rolling row count, and the answer builds as stacked bars, lines or a table, with a one line insight streamed in underneath.
- [Agent cursor](https://uiarc.dev/components/agent-cursor/markdown): A live document where Claude edits like a collaborator. Its labeled cursor comes out of its avatar, selects a paragraph and streams in a rewrite, adds a heading and fixes a typo, while a teammate's cursor reads along. Changes stay tinted until someone accepts or undoes them from a floating review bar.
- [Provider status](https://uiarc.dev/components/provider-status/markdown): A status card for the AI providers your product depends on. Each row shows the provider's real mark, its health as an icon and label, p50 latency and a 30-day uptime bar with a tooltip for each day. An incident row expands into its timeline of updates, and the card checks again on a visible countdown.
- [Training run](https://uiarc.dev/components/training-run/markdown): A fine-tuning job card where a live train and validation loss curve draws across a fixed step axis that doubles as the epoch progress bar. It shows the learning rate, elapsed time, ETA and the latest evals and checkpoints, has Pause and Cancel while it runs, and ends in results with a Deploy button.
- [AI command](https://uiarc.dev/components/ai-command/markdown): A Cmd+K command palette with an AI mode. Search pages and actions, or press Tab to ask a question: the answer streams inside the palette with numbered sources, and the next steps it suggests, like filing a Linear issue or opening a Notion doc, run straight from the list.
- [Starter prompts](https://uiarc.dev/components/starter-prompts/markdown): A greeting and a grid of starter cards for the empty state of an AI app. The cards are grouped into Write, Code, Analyze and Plan tabs, and a shuffle swaps them with a short staggered crossfade. Picking a card fills the composer, and cards that use a connected app show its mark (Gmail, GitHub, Notion, Linear, Google Calendar).
- [AI mascot](https://uiarc.dev/components/ai-mascot/markdown): A small assistant character, a soft pebble with pill eyes and a companion dot, that shows what the AI is doing. It breathes and glances when idle, leans in to listen, looks up while the dot orbits its head, reads along the line it writes, squints with a sparkle when done and shakes once with worried brows on an error.
- [Image reveal](https://uiarc.dev/components/image-reveal/markdown): An image generation canvas where a soft, blurred preview made from the image's own colors sharpens top to bottom behind a soft-edged band. It works the way ChatGPT, Midjourney and Gemini show images forming, with fine film grain, a translucent progress pill and calm queued and error states.
- [AI spark](https://uiarc.dev/components/ai-spark/markdown): A brand-quality animated spark mark. Four tapered rays and four lighter diagonals breathe at rest, ripple while thinking, pulse like a heartbeat while writing, then gather and settle when done. Every status change blends from the pose the mark is already in.
- [Pixel mascot](https://uiarc.dev/components/pixel-mascot/markdown): A pixel-art robot that shows what an AI assistant is doing. It idles, thinks, types, celebrates and errors in frame-stepped sprite animations, and stays crisp at every integer size from 24px to 192px.
- [Ghost mascot](https://uiarc.dev/components/ghost-mascot/markdown): A floating ghost mascot whose soft sheet ripples at the hem while it hovers. It blinks when idle, turns toward you to listen, fades a little translucent while thinking, draws a tiny pen line while writing, smiles with a sparkle when done and wobbles once on an error.
- [Cube mascot](https://uiarc.dev/components/cube-mascot/markdown): An isometric cube mascot where three shaded faces and a painted-on face show what the assistant is doing. It turns a quarter turn in eased steps while thinking, prints lines onto the floor while writing, settles with a sparkle when done, and shakes once on error.
- [Tone tuner](https://uiarc.dev/components/tone-tuner/markdown): A brand voice card where two sliders (formality and detail) and Friendly, Confident and Empathetic chips rewrite a customer reply. Each changed sentence crossfades in place, new words can be highlighted against the original, and Copy takes the current version.
- [Upgrade prompt](https://uiarc.dev/components/upgrade-prompt/markdown): An upgrade nudge for the moment someone hits a limit. It shows a usage meter at 50 of 50 AI credits, a rolling price with a monthly and yearly toggle, three concrete unlocks with real model marks, and Upgrade or Maybe later. Upgrading leads into a success state with the new limits, and the card never changes size between states.
- [Referral card](https://uiarc.dev/components/referral-card/markdown): A give-and-get referral card where people copy or share their invite link, invite friends by email as chips, and watch invites move from invited to signed up to earned, with the credit total counting up and a milestone reward unlocking.
- [Trial banner](https://uiarc.dev/components/trial-banner/markdown): A trial status banner where a ring counts down the days left, the copy names what the workspace loses, and the upgrade path is one click away. It comes as a slim banner, a sidebar card or a header pill. It shifts to a warning tone in the last days, has expired and upgraded states, and folds into the pill when dismissed or snoozed.
- [Live visitors](https://uiarc.dev/components/live-visitors/markdown): A realtime visitors card where the live count rolls digit by digit, new arrivals ping in on a dotted world map, the top pages reorder with bars, and signups and upgrades tick in with country flags.
- [Social proof toast](https://uiarc.dev/components/social-proof-toast/markdown): A stack of social proof notifications for landing and pricing pages, where recent trials, upgrades and verified purchases from people and companies arrive every few seconds. The stack pauses and fans out on hover, and visitors can dismiss any toast.
- [Install snippet](https://uiarc.dev/components/install-snippet/markdown): A "get started in 30 seconds" card where framework tabs, three numbered steps and highlighted snippets take a developer from install to first event. Generate key wipes a fresh API key into the placeholder in place.

### Guidance for AI tools

Team switcher: A workspace switcher like Linear, Vercel or Slack. The trigger shows the current workspace's logo and plan. The menu has search, your role in each workspace and a Cmd+1 to 9 shortcut for each, and lets you create or join a workspace inline. A highlight glides between rows, and switching crossfades the trigger through a short loading state. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Live visitors

> A realtime visitors card where the live count rolls digit by digit, new arrivals ping in on a dotted world map, the top pages reorder with bars, and signups and upgrades tick in with country flags.

- Type: Component (special)
- Access: Arc Pro
- Page: https://uiarc.dev/components/live-visitors
- Markdown: https://uiarc.dev/components/live-visitors/markdown
- Source file: `registry/components/live-visitors/live-visitors.tsx`
- Dependencies: motion, lucide-react
- Keywords: special, saas, new, live visitors, realtime analytics, active users, visitors now, world map, dotted map, top pages, signups, upgrades, conversion ticker, rolling number, odometer, country flags, live dashboard

### When to use

- Realtime visitors on a marketing site or app, next to signups and upgrades as they happen.
- Launch days and campaigns where a team watches traffic and conversions live.
- Admin and growth dashboards that need one glanceable tile for right now.

### When not to use

- Historical trends over days or weeks; use a chart with axes.
- Precise geography or per-country breakdowns; use a table or a proper map.
- A single number with no context; use a stat card.

### Installation

Live visitors is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/live-visitors
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { LiveVisitors } from "@/components/arc/live-visitors/live-visitors";

export function RealtimeCard({ count, pages, arrivals, conversions, status }) {
  // Feed it from your realtime source (a websocket, SSE or a 2s poll of your analytics API).
  return (
    <LiveVisitors
      count={count}
      pages={pages}
      visitors={arrivals}
      events={conversions}
      connection={status}
      onPausedChange={paused => (paused ? socket.pause() : socket.resume())}
    />
  );
}
```

### API reference

#### LiveVisitors

A realtime visitors card: a pulsing live status, a count that rolls digit by digit, a dotted world map where new arrivals ping in and fade, the top pages right now with bars, and a ticker of signups and upgrades with country flags. With no props it plays a simulated stream of a SaaS marketing site.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `count` | `number` | – | People on the site right now. Leave it out to play the built-in simulated stream; once set, the card shows only the data you pass. |
| `pages` | `LivePage[]` | `[]` | Pages with people on them: { path, visitors }. The card sorts them and lists the top few with bars scaled to the busiest page. Rows slide when the order changes. |
| `visitors` | `LiveVisitorPing[]` | `[]` | Recent arrivals as map dots: { id, lat, lon, kind? }. New ids ping in, removed ids fade out. kind "event" draws a stronger ring. Keep it to the last few seconds of arrivals. |
| `events` | `LiveVisitorEvent[]` | `[]` | Recent conversions, newest first: { id, label, city, country, at, lat?, lon?, flag? }. country is an ISO alpha-2 code; US, GB, DE, FR, NL, SE, CH, JP, IN and BR have built-in flags, others take flag or a neutral swatch. With lat and lon the newest event is labelled on the map for 2s. |
| `connection` | `"live" \| "connecting" \| "reconnecting"` | `"live"` | The stream's state. connecting shows placeholders in the same space; reconnecting keeps the last data and switches the status to a warning dot with the word Reconnecting. |
| `paused` | `boolean` | – | Controls the pause state. While paused the card holds the last snapshot, whatever you keep passing. |
| `defaultPaused` | `boolean` | `false` | Starts paused when uncontrolled. |
| `onPausedChange` | `(paused: boolean) => void` | – | Called from the pause button. Use it to close or pause your own subscription. |
| `hidePause` | `boolean` | `false` | Hides the pause button. |
| `label` | `(count: number) => string` | `"people on the site now"` | The words after the number, pluralized from the count. Use it for "in the app now" or "watching the stream". |
| `maxPages` | `number` | `4` | How many pages to list. |
| `maxEvents` | `number` | `4` | How many events to list. |
| `title` | `string` | `"Live visitors"` | Accessible name of the card. |
| `className` | `string` | – | Extra class on the card. It is at most 640px wide and fills narrower containers. |

#### useLiveVisitorsSimulation

The simulated stream behind the default demo, for prototypes and tests: about 128 people, a new arrival every 600ms, drifting page counts and a signup or upgrade every 2.4s. Nothing is fetched or tracked.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `active` | `boolean` | `true` | Holds the stream when false. Returns { count, pages, visitors, events }. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Tab | Reaches the pause button. The map and lists are read-only. |
| Enter / Space | Pauses or resumes live updates. |

### Accessibility

- The card is a labelled section; the count is read once as plain text ("128 people on the site now"), and the rolling digits are hidden from screen readers.
- The pause button is a toggle with aria-pressed and a label that names the action; its tooltip says the same.
- Status is never color alone: the dot always sits next to Live, Paused, Connecting or Reconnecting.
- Each event row reads as one sentence with the country spelled out and the time in words ("Signed up, Berlin, Germany, 12 seconds ago"). Flags are decorative.
- The map is decorative and hidden; the same information is in the lists.
- Count changes are not announced, so screen readers are not flooded. A polite live region reports pause and resume, and says when the stream is simulated.

### Motion

- Digits roll on their own strips (280ms ease-out) with tabular numerals, so the number never changes width; a new leading digit (99 to 100) grows in.
- New visitors fade in on the map with one ring that expands and fades (900ms); events get a stronger ring and a small city label for 2s. Expired dots fade out over 400ms.
- Page rows and event rows move as one step: rows slide by one row height (280ms), the new row fades in (160ms) and the last one fades out below the clip. Bars ease to their new width.
- The live dot pulses every 1.6s only while live and on screen. The state label crossfades (out 100ms, in 160ms) in a reserved width.
- Reduced motion keeps every update but drops the rolls, rings, slides and pulse.

### Responsive behavior

- Holds 640px at most and fills narrower containers through a container query.
- Below 520px card width the two lists stack and padding drops to 16px; the map scales with the card.
- Paths, cities and labels truncate with an ellipsis; counts and times keep fixed right-aligned columns.

### Performance

- The land is one SVG path of round caps computed once; pings are a handful of circles.
- Rows, bars and digits move with CSS transforms and widths on absolutely positioned elements, so nothing reflows the card.
- The pulse, clock and simulation stop while the card is off screen (IntersectionObserver) or paused.

### Notes for AI

- Pick this for a realtime analytics view, an admin home or a launch day dashboard tile that answers who is here right now.
- Without count it is a self-playing demo. As soon as you pass count, pass pages, visitors and events too.
- Send arrivals as a rolling window (ids that stay for 5 to 8 seconds); the component handles enter and exit animations from id changes.
- Keep event labels short and past tense (Signed up, Upgraded to Pro) and never show personal data such as emails in the ticker.
- Use connection to reflect the socket state instead of hiding the card.

### Related

- [Account health](https://uiarc.dev/components/blocks/account-health/markdown): A customer success card where a health score gauge, a renewal countdown and five sourced signals with sparklines lead into an AI risk summary and one recommended next step, like scheduling a QBR before usage slips further.
- [Generation stats](https://uiarc.dev/components/generation-stats/markdown): A live stats strip for a streaming LLM response where time to first token, speed with a sparkline, output tokens and cost count up in tabular numerals beside the model's real mark, then settle and open into a latency and token cost breakdown.
- [Goal tracker](https://uiarc.dev/components/blocks/goal-tracker/markdown): A team goals card where objectives open into key results with owners, confidence and progress bars. A weekly check-in updates a value, confidence and note in place, fills the bar and recalculates the objective, and a quarter selector steps from last quarter's final scores to next quarter's planning.
- [Agent status](https://uiarc.dev/components/agent-status/markdown): A compact live status pill for a running AI agent: the agent's mark in a live ring, the current activity and an elapsed timer, opening into the steps so far.
- [Credit top-up](https://uiarc.dev/components/blocks/credit-topup/markdown): A card for buying AI credits. It shows the balance with a 14 day usage chart and how many days are left, three preset packs with bonus badges, a custom amount slider with a live price, auto top-up with a threshold and the saved Visa or Mastercard. When you buy, the new balance rolls in like an odometer.

### Also in ai

- [Tool call](https://uiarc.dev/components/tool-call/markdown): A tool call row for agent transcripts: the tool's mark and the call in plain words, a live state while it runs, and the input and output a click away, with approval and retry when needed.
- [Agent plan](https://uiarc.dev/components/agent-plan/markdown): The plan an agent writes before it acts: edit, reorder or add steps while it is a draft, then watch it work through them as a live checklist.
- [Agent timeline](https://uiarc.dev/components/agent-timeline/markdown): A compact timeline of one orchestrated agent run: the orchestrator and its subagents share a time axis, handoffs draw in between rows, and a playhead replays thinking, tool calls and waiting while the header counts time, tokens and cost. Hover a span for what it did, or click it to trace its handoff path.
- [Context window](https://uiarc.dev/components/context-window/markdown): An AI context window as a grid of 200 cells: the system prompt, tools, files, summary and messages fill it in order, a threshold row marks where compaction starts, and sending a message, attaching a file or compacting shows exactly how much still fits.
- [Reasoning block](https://uiarc.dev/components/reasoning-block/markdown): The collapsible thinking block of an AI reply. While the model thinks, a shimmering label counts the seconds and the latest reasoning streams underneath. When it finishes, it folds to "Thought for 7s" and opens to show the full reasoning as calm steps with headings.
- [Source cards](https://uiarc.dev/components/source-cards/markdown): A row of cited sources under an AI answer where cards stream in with real site marks while the model searches, the overflow collapses into a stack of favicons, hovering lifts a preview with the passage, and an inline [n] citation highlights its card.
- [Model card](https://uiarc.dev/components/model-card/markdown): A model details card where switching models rolls every price, limit and score in place, a token slider estimates monthly cost live, and benchmark bars show each model's rank on hover. Compare crossfades to a side-by-side table against any rival with the better values marked, and the card never changes size.
- [AI workflow](https://uiarc.dev/components/ai-workflow/markdown): A Linear-style AI workflow card where a Gmail trigger, a Claude step, a branch and Slack and Linear actions sit on one hairline rail, and a test run glides down it, opening each step's output inline. Steps are added from a compact command menu with real app marks.
- [Code suggestion](https://uiarc.dev/components/code-suggestion/markdown): An AI code edit suggestion where the model's proposed changes stream into a small editor panel as inline diff hunks, and you accept or reject each one, or all at once with Cmd+Enter. Accepted hunks fold into the file with a smooth height change.
- [Ghost text](https://uiarc.dev/components/ghost-text/markdown): An inline AI autocomplete where muted ghost text continues your sentence exactly at the caret and Tab turns it solid in place. Cmd+Right takes it one word at a time, Escape fades it away, and a calm chip shows the model behind it.
- [Image generation](https://uiarc.dev/components/image-generation/markdown): An image studio where each image forms on a dot matrix: a soft halftone wave breathes across the grid, the dots take the colours of the coming photo and grow into a coloured halftone, then blur away into the sharp photo. One large canvas with a mono size label, a filmstrip of four variations, a prompt bar with model and ratio, and upscale with a sweeping dot band, vary or download, with real provider marks and a built-in simulation.
- [Dictation button](https://uiarc.dev/components/dictation-button/markdown): A chat composer with voice input, where the mic springs into a recording pill with a smooth live waveform, a timer, and cancel and insert buttons. Words stream into the field as you speak, muted until the recognizer settles them.
- [Speech player](https://uiarc.dev/components/speech-player/markdown): A read-aloud player for AI replies. The Read aloud button in the message's action row turns into a compact player with play, a scrubbable progress bar, speed and a voice picker, and a highlight follows the spoken word through the reply, karaoke style.
- [Meeting summary](https://uiarc.dev/components/meeting-summary/markdown): An AI meeting notes card: the header shows the Google Meet or Zoom mark, the attendees and the duration. Summary, Decisions and Action items stream in after a short summarizing pass. Hover any line to see the transcript quote it came from, then check off action items or send them to Linear or Notion.
- [Reply draft](https://uiarc.dev/components/reply-draft/markdown): An AI email reply drafter where Claude streams a reply under a received Gmail message. Quick replies steer a fresh draft, tone and length rewrite it with a single crossfade, and you can edit the finished draft before you insert it.
- [Agent handoff](https://uiarc.dev/components/agent-handoff/markdown): A support conversation where an AI assistant hands off to a person. When it transfers, a card shows the summary it passes to the team and the typical wait. The person then joins and takes over, and a thin timeline on the left marks each step.
- [PII redaction](https://uiarc.dev/components/pii-redaction/markdown): A guardrail card where personal data is redacted before the prompt reaches the model. Scan marks each name, email, phone number and card with its type and swaps it for a placeholder like [EMAIL_1]. The safe prompt travels to Claude, and the reply comes back with the original values put back for the person.
- [Response feedback](https://uiarc.dev/components/response-feedback/markdown): A feedback control for AI replies where thumbs down opens an inline panel with reason chips and an optional note, thumbs up fills and asks what was good, and a submit shows a short thank-you before folding back into the row.
- [LLM cost calculator](https://uiarc.dev/components/llm-cost-calculator/markdown): A pricing calculator for LLM workloads. Set tokens per request, requests per day and prompt caching, and eight current models re-rank by monthly cost. Bars glide and prices roll as you drag.
- [Provider keys](https://uiarc.dev/components/provider-keys/markdown): A settings card for bring-your-own-key AI products. Each provider row shows its real mark, the masked key, a status and when the key was last used. You can reveal a key for five seconds, copy, rotate or remove it with undo. Adding or rotating a key opens an inline form that checks the format as you type, then tests the connection before saving.
- [AI translate](https://uiarc.dev/components/ai-translate/markdown): A message card where picking a language streams the AI translation in place, sentence by sentence over the dimmed original, with a detected-language chip, a Show original toggle and a status line credited to the model's mark.
- [TL;DR toggle](https://uiarc.dev/components/tldr-toggle/markdown): An article card with a Full, Summary and Key points switch and a length slider. Switching streams an AI summary in place of the article as the card's height springs to fit, and each key point links back to the paragraph it came from, which gets scrolled to and highlighted.
- [Connector setup](https://uiarc.dev/components/connector-setup/markdown): A "Connect your tools" card for an AI assistant. Each app connects inline: it redirects, authorizes and runs a first sync with a progress hairline, then lists the scopes it was granted and offers Disconnect with an inline confirm.
- [Smart form fill](https://uiarc.dev/components/smart-form-fill/markdown): A paste-to-fill form card where AI reads an email signature or messy notes and fills a contact field by field. Each value flashes in with a confidence dot, its source lights up in the pasted text, low-confidence guesses ask for review, and Undo puts the old values back.
- [Enrich column](https://uiarc.dev/components/enrich-column/markdown): An AI enrichment column for a data table, where one prompt runs down every row and each cell shimmers while it works, then settles into a value with its source or a failure you can retry.
- [Ticket router](https://uiarc.dev/components/ticket-router/markdown): A support ticket router where messages from Gmail, Intercom, Slack and Zendesk come in one at a time. An AI classifier labels each one with intent, sentiment and confidence, and the ticket moves into a team lane with an assignee. Low confidence tickets wait in a review lane, and one click there routes them to the suggested team.
- [Ask your data](https://uiarc.dev/components/ask-your-data/markdown): A natural language to chart card: you ask a question, PostgreSQL streams into a collapsible, syntax highlighted panel, the query runs with a rolling row count, and the answer builds as stacked bars, lines or a table, with a one line insight streamed in underneath.
- [Agent cursor](https://uiarc.dev/components/agent-cursor/markdown): A live document where Claude edits like a collaborator. Its labeled cursor comes out of its avatar, selects a paragraph and streams in a rewrite, adds a heading and fixes a typo, while a teammate's cursor reads along. Changes stay tinted until someone accepts or undoes them from a floating review bar.
- [Provider status](https://uiarc.dev/components/provider-status/markdown): A status card for the AI providers your product depends on. Each row shows the provider's real mark, its health as an icon and label, p50 latency and a 30-day uptime bar with a tooltip for each day. An incident row expands into its timeline of updates, and the card checks again on a visible countdown.
- [Training run](https://uiarc.dev/components/training-run/markdown): A fine-tuning job card where a live train and validation loss curve draws across a fixed step axis that doubles as the epoch progress bar. It shows the learning rate, elapsed time, ETA and the latest evals and checkpoints, has Pause and Cancel while it runs, and ends in results with a Deploy button.
- [AI command](https://uiarc.dev/components/ai-command/markdown): A Cmd+K command palette with an AI mode. Search pages and actions, or press Tab to ask a question: the answer streams inside the palette with numbered sources, and the next steps it suggests, like filing a Linear issue or opening a Notion doc, run straight from the list.
- [Starter prompts](https://uiarc.dev/components/starter-prompts/markdown): A greeting and a grid of starter cards for the empty state of an AI app. The cards are grouped into Write, Code, Analyze and Plan tabs, and a shuffle swaps them with a short staggered crossfade. Picking a card fills the composer, and cards that use a connected app show its mark (Gmail, GitHub, Notion, Linear, Google Calendar).
- [AI mascot](https://uiarc.dev/components/ai-mascot/markdown): A small assistant character, a soft pebble with pill eyes and a companion dot, that shows what the AI is doing. It breathes and glances when idle, leans in to listen, looks up while the dot orbits its head, reads along the line it writes, squints with a sparkle when done and shakes once with worried brows on an error.
- [Image reveal](https://uiarc.dev/components/image-reveal/markdown): An image generation canvas where a soft, blurred preview made from the image's own colors sharpens top to bottom behind a soft-edged band. It works the way ChatGPT, Midjourney and Gemini show images forming, with fine film grain, a translucent progress pill and calm queued and error states.
- [AI spark](https://uiarc.dev/components/ai-spark/markdown): A brand-quality animated spark mark. Four tapered rays and four lighter diagonals breathe at rest, ripple while thinking, pulse like a heartbeat while writing, then gather and settle when done. Every status change blends from the pose the mark is already in.
- [Pixel mascot](https://uiarc.dev/components/pixel-mascot/markdown): A pixel-art robot that shows what an AI assistant is doing. It idles, thinks, types, celebrates and errors in frame-stepped sprite animations, and stays crisp at every integer size from 24px to 192px.
- [Ghost mascot](https://uiarc.dev/components/ghost-mascot/markdown): A floating ghost mascot whose soft sheet ripples at the hem while it hovers. It blinks when idle, turns toward you to listen, fades a little translucent while thinking, draws a tiny pen line while writing, smiles with a sparkle when done and wobbles once on an error.
- [Cube mascot](https://uiarc.dev/components/cube-mascot/markdown): An isometric cube mascot where three shaded faces and a painted-on face show what the assistant is doing. It turns a quarter turn in eased steps while thinking, prints lines onto the floor while writing, settles with a sparkle when done, and shakes once on error.
- [Tone tuner](https://uiarc.dev/components/tone-tuner/markdown): A brand voice card where two sliders (formality and detail) and Friendly, Confident and Empathetic chips rewrite a customer reply. Each changed sentence crossfades in place, new words can be highlighted against the original, and Copy takes the current version.
- [Upgrade prompt](https://uiarc.dev/components/upgrade-prompt/markdown): An upgrade nudge for the moment someone hits a limit. It shows a usage meter at 50 of 50 AI credits, a rolling price with a monthly and yearly toggle, three concrete unlocks with real model marks, and Upgrade or Maybe later. Upgrading leads into a success state with the new limits, and the card never changes size between states.
- [Referral card](https://uiarc.dev/components/referral-card/markdown): A give-and-get referral card where people copy or share their invite link, invite friends by email as chips, and watch invites move from invited to signed up to earned, with the credit total counting up and a milestone reward unlocking.
- [Trial banner](https://uiarc.dev/components/trial-banner/markdown): A trial status banner where a ring counts down the days left, the copy names what the workspace loses, and the upgrade path is one click away. It comes as a slim banner, a sidebar card or a header pill. It shifts to a warning tone in the last days, has expired and upgraded states, and folds into the pill when dismissed or snoozed.
- [Team switcher](https://uiarc.dev/components/team-switcher/markdown): A workspace switcher like Linear, Vercel or Slack. The trigger shows the current workspace's logo and plan. The menu has search, your role in each workspace and a Cmd+1 to 9 shortcut for each, and lets you create or join a workspace inline. A highlight glides between rows, and switching crossfades the trigger through a short loading state.
- [Social proof toast](https://uiarc.dev/components/social-proof-toast/markdown): A stack of social proof notifications for landing and pricing pages, where recent trials, upgrades and verified purchases from people and companies arrive every few seconds. The stack pauses and fans out on hover, and visitors can dismiss any toast.
- [Install snippet](https://uiarc.dev/components/install-snippet/markdown): A "get started in 30 seconds" card where framework tabs, three numbered steps and highlighted snippets take a developer from install to first event. Generate key wipes a fresh API key into the placeholder in place.

### Guidance for AI tools

Live visitors: A realtime visitors card where the live count rolls digit by digit, new arrivals ping in on a dotted world map, the top pages reorder with bars, and signups and upgrades tick in with country flags. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Social proof toast

> A stack of social proof notifications for landing and pricing pages, where recent trials, upgrades and verified purchases from people and companies arrive every few seconds. The stack pauses and fans out on hover, and visitors can dismiss any toast.

- Type: Component (special)
- Access: Arc Pro
- Page: https://uiarc.dev/components/social-proof-toast
- Markdown: https://uiarc.dev/components/social-proof-toast/markdown
- Source file: `registry/components/social-proof-toast/social-proof-toast.tsx`
- Dependencies: motion, lucide-react
- Keywords: special, saas, new, social proof, fomo notification, recent purchase popup, sales notification, live activity toast, trial signup toast, conversion, landing page, verified badge, toast stack

### When to use

- Showing recent trials, purchases or upgrades on a landing or pricing page.
- A live activity feed for a launch or waitlist page (people joining, teams upgrading).
- Highlighting verified purchases from known companies near a checkout CTA.

### When not to use

- System feedback after a user action (saved, copied, failed): use toast or undo-toast.
- Inside a signed in product where activity is not marketing: use an activity feed list.
- When you do not have real events to show; fabricated social proof erodes trust.

### Installation

Social proof toast is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/social-proof-toast
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { SocialProofToast } from "@/components/arc/social-proof-toast/social-proof-toast";
import type { SocialProofEvent } from "@/components/arc/social-proof-toast/social-proof-toast";
import { LinearMark } from "@/components/arc/social-proof-toast/social-proof-toast-marks";

const events: SocialProofEvent[] = [
  { id: "1", name: "Sofia", action: "started a Pro trial", meta: "Madrid", time: new Date(Date.now() - 2 * 60_000), avatar: "/people/sofia.jpg" },
  { id: "2", name: "Linear", action: "upgraded to Business", meta: "48 seats", time: Date.now() - 4 * 60_000, logo: <LinearMark />, verified: "Verified by Stripe" },
];

export function Landing() {
  return <SocialProofToast events={events} position="bottom-left" limit={6} onShow={event => console.log("shown", event.id)} />;
}
```

### API reference

#### SocialProofToast

Stacked social proof notifications for a landing or pricing page. Toasts cycle on an interval, pause and fan out on hover or focus, and can be dismissed. With no props it plays a sample SaaS feed.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `events` | `SocialProofEvent[]` | `sampleSocialProofEvents` | The feed, oldest first. Each event is { id, name, action, meta?, time?, avatar?, logo?, verified? }. A Date or timestamp time renders as relative time; a string renders as is. |
| `interval` | `number` | `4000` | Milliseconds between toasts. The countdown keeps its remaining time across hover and focus pauses. |
| `initialDelay` | `number` | `800` | Milliseconds before the first toast. |
| `maxVisible` | `number` | `3` | How many toasts stack at once. Older ones fade out from the back. |
| `prefill` | `number` | `0` | How many toasts already show on mount, without an entrance. Useful for previews and screenshots. |
| `position` | `"inline" \| "bottom-left" \| "bottom-right" \| "top-left" \| "top-right"` | `"inline"` | Inline sits in the layout. The corners pin the stack to the viewport, 24px from the edges (16px and full width on phones). Top positions stack downward. |
| `expandOnHover` | `boolean` | `true` | Fans the stack out while it is hovered or holds focus. |
| `loop` | `boolean` | `true` | Starts the feed over when it ends. False stops after the last event. |
| `limit` | `number` | – | Stops after this many toasts in a session, so the page stays calm. |
| `paused` | `boolean` | `false` | Pauses the cycle from outside, for example while a modal or cookie banner is open. |
| `onShow` | `(event: SocialProofEvent) => void` | – | Called each time a toast appears, for impression tracking. |
| `onDismiss` | `(event: SocialProofEvent) => void` | – | Called when a visitor dismisses a toast. |
| `onSelect` | `(event: SocialProofEvent) => void` | – | Makes each toast a button, for example to open pricing or a customer story. |
| `label` | `string` | `"Recent activity"` | Accessible name of the region. |
| `className` | `string` | – | Class on the root region. |

#### SocialProofEvent

One entry in the feed.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `id` (required) | `string` | – | Stable id, used for keys and callbacks. |
| `name` (required) | `string` | – | A first name or a company, shown in medium weight. |
| `action` (required) | `string` | – | What they did, read after the name: "started a Pro trial". |
| `meta` | `string` | – | Short context before the time, such as a city or a seat count. |
| `time` | `Date \| number \| string` | – | When it happened. Dates render as Just now, 4 min ago, 2 h ago. |
| `avatar` | `string` | – | Portrait URL for a person. |
| `logo` | `ReactNode` | – | A company mark drawn in currentColor, rendered at 18px in the round slot when there is no avatar. Initials show when neither is set. |
| `verified` | `boolean \| string` | – | Shows a check badge with a label. True reads Verified; pass a string such as Verified by Stripe. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Tab | Moves to the dismiss button of each visible toast. Focus inside the stack pauses it and fans it out. |
| Enter / Space | Dismisses the focused toast, or selects it when onSelect is set. |
| Escape | Dismisses the focused toast, or the front one. Focus moves to the next toast. |

### Accessibility

- The stack is a labelled region (Recent activity). New toasts are not announced, so screen reader users are not interrupted every few seconds; dismissals are confirmed in a polite status.
- Each dismiss button names the toast it closes, such as Dismiss: Sofia started a Pro trial.
- Toasts behind the stack limit are aria-hidden and inert. Hover and keyboard focus both pause the cycle, so nothing moves while someone reads or acts.
- The verified state is an icon plus a text label, never color alone. Portraits use empty alt text because the name is in the sentence.

### Motion

- A new toast rises 16px and fades in at the front while the others step back 10px and scale down 5% each. Every move uses a bounce free spring (visual duration 0.24s); content of covered toasts fades out in 160ms so text never overlaps.
- Hover or focus fans the stack out with the same spring; dismissing fades and slightly shrinks the toast in 160ms and the rest close the gap.
- Toasts have a fixed 64px height, so nothing resizes between states.
- Reduced motion keeps the stack and the cycle but drops travel: toasts only fade.
- The cycle pauses off screen (IntersectionObserver) and in background tabs.

### Responsive behavior

- 360px wide in a corner, 24px from the edges. Below 480px the stack spans the width with 16px gutters.
- Text truncates with an ellipsis on one line per row, so toast height never changes.
- On touch screens the dismiss button is always visible; on pointer devices it appears on hover or keyboard focus.

### Performance

- At most maxVisible + 1 toasts are mounted. Animations are transform and opacity only.
- One timer drives the cycle and stops while paused, off screen, or in a hidden tab.

### Notes for AI

- Use for social proof on marketing, pricing and checkout pages. Feed it real, recent events from your billing or analytics backend; do not invent activity.
- Keep it calm: interval 4000 to 8000ms, limit around 5 to 8 per session, and pause it while modals or cookie banners are open via paused.
- For one-off app notifications use toast or toast-stack instead. Marks should be mono and use currentColor so they follow the theme.
- position="inline" is for docs and previews; on a real page use a corner position.

### Related

- [Toast](https://uiarc.dev/components/toast/markdown): Brief confirmation for a completed background action.
- [Toast stack](https://uiarc.dev/components/toast-stack/markdown): Stack short results at the edge until you reach for them.
- [Undo toast](https://uiarc.dev/components/undo-toast/markdown): Archive or delete rows with a second chance: the gap closes, a countdown toast merges repeat actions, and Undo or ⌘Z puts every row back exactly where it was.
- [Avatar](https://uiarc.dev/components/avatar/markdown): A compact identity marker for people and accounts.
- [Avatar group](https://uiarc.dev/components/avatar-group/markdown): Show a team or set of contributors in a small space.

### Also in ai

- [Agent status](https://uiarc.dev/components/agent-status/markdown): A compact live status pill for a running AI agent: the agent's mark in a live ring, the current activity and an elapsed timer, opening into the steps so far.
- [Tool call](https://uiarc.dev/components/tool-call/markdown): A tool call row for agent transcripts: the tool's mark and the call in plain words, a live state while it runs, and the input and output a click away, with approval and retry when needed.
- [Agent plan](https://uiarc.dev/components/agent-plan/markdown): The plan an agent writes before it acts: edit, reorder or add steps while it is a draft, then watch it work through them as a live checklist.
- [Agent timeline](https://uiarc.dev/components/agent-timeline/markdown): A compact timeline of one orchestrated agent run: the orchestrator and its subagents share a time axis, handoffs draw in between rows, and a playhead replays thinking, tool calls and waiting while the header counts time, tokens and cost. Hover a span for what it did, or click it to trace its handoff path.
- [Context window](https://uiarc.dev/components/context-window/markdown): An AI context window as a grid of 200 cells: the system prompt, tools, files, summary and messages fill it in order, a threshold row marks where compaction starts, and sending a message, attaching a file or compacting shows exactly how much still fits.
- [Reasoning block](https://uiarc.dev/components/reasoning-block/markdown): The collapsible thinking block of an AI reply. While the model thinks, a shimmering label counts the seconds and the latest reasoning streams underneath. When it finishes, it folds to "Thought for 7s" and opens to show the full reasoning as calm steps with headings.
- [Source cards](https://uiarc.dev/components/source-cards/markdown): A row of cited sources under an AI answer where cards stream in with real site marks while the model searches, the overflow collapses into a stack of favicons, hovering lifts a preview with the passage, and an inline [n] citation highlights its card.
- [Model card](https://uiarc.dev/components/model-card/markdown): A model details card where switching models rolls every price, limit and score in place, a token slider estimates monthly cost live, and benchmark bars show each model's rank on hover. Compare crossfades to a side-by-side table against any rival with the better values marked, and the card never changes size.
- [AI workflow](https://uiarc.dev/components/ai-workflow/markdown): A Linear-style AI workflow card where a Gmail trigger, a Claude step, a branch and Slack and Linear actions sit on one hairline rail, and a test run glides down it, opening each step's output inline. Steps are added from a compact command menu with real app marks.
- [Code suggestion](https://uiarc.dev/components/code-suggestion/markdown): An AI code edit suggestion where the model's proposed changes stream into a small editor panel as inline diff hunks, and you accept or reject each one, or all at once with Cmd+Enter. Accepted hunks fold into the file with a smooth height change.
- [Ghost text](https://uiarc.dev/components/ghost-text/markdown): An inline AI autocomplete where muted ghost text continues your sentence exactly at the caret and Tab turns it solid in place. Cmd+Right takes it one word at a time, Escape fades it away, and a calm chip shows the model behind it.
- [Image generation](https://uiarc.dev/components/image-generation/markdown): An image studio where each image forms on a dot matrix: a soft halftone wave breathes across the grid, the dots take the colours of the coming photo and grow into a coloured halftone, then blur away into the sharp photo. One large canvas with a mono size label, a filmstrip of four variations, a prompt bar with model and ratio, and upscale with a sweeping dot band, vary or download, with real provider marks and a built-in simulation.
- [Dictation button](https://uiarc.dev/components/dictation-button/markdown): A chat composer with voice input, where the mic springs into a recording pill with a smooth live waveform, a timer, and cancel and insert buttons. Words stream into the field as you speak, muted until the recognizer settles them.
- [Speech player](https://uiarc.dev/components/speech-player/markdown): A read-aloud player for AI replies. The Read aloud button in the message's action row turns into a compact player with play, a scrubbable progress bar, speed and a voice picker, and a highlight follows the spoken word through the reply, karaoke style.
- [Meeting summary](https://uiarc.dev/components/meeting-summary/markdown): An AI meeting notes card: the header shows the Google Meet or Zoom mark, the attendees and the duration. Summary, Decisions and Action items stream in after a short summarizing pass. Hover any line to see the transcript quote it came from, then check off action items or send them to Linear or Notion.
- [Reply draft](https://uiarc.dev/components/reply-draft/markdown): An AI email reply drafter where Claude streams a reply under a received Gmail message. Quick replies steer a fresh draft, tone and length rewrite it with a single crossfade, and you can edit the finished draft before you insert it.
- [Agent handoff](https://uiarc.dev/components/agent-handoff/markdown): A support conversation where an AI assistant hands off to a person. When it transfers, a card shows the summary it passes to the team and the typical wait. The person then joins and takes over, and a thin timeline on the left marks each step.
- [PII redaction](https://uiarc.dev/components/pii-redaction/markdown): A guardrail card where personal data is redacted before the prompt reaches the model. Scan marks each name, email, phone number and card with its type and swaps it for a placeholder like [EMAIL_1]. The safe prompt travels to Claude, and the reply comes back with the original values put back for the person.
- [Response feedback](https://uiarc.dev/components/response-feedback/markdown): A feedback control for AI replies where thumbs down opens an inline panel with reason chips and an optional note, thumbs up fills and asks what was good, and a submit shows a short thank-you before folding back into the row.
- [LLM cost calculator](https://uiarc.dev/components/llm-cost-calculator/markdown): A pricing calculator for LLM workloads. Set tokens per request, requests per day and prompt caching, and eight current models re-rank by monthly cost. Bars glide and prices roll as you drag.
- [Provider keys](https://uiarc.dev/components/provider-keys/markdown): A settings card for bring-your-own-key AI products. Each provider row shows its real mark, the masked key, a status and when the key was last used. You can reveal a key for five seconds, copy, rotate or remove it with undo. Adding or rotating a key opens an inline form that checks the format as you type, then tests the connection before saving.
- [Generation stats](https://uiarc.dev/components/generation-stats/markdown): A live stats strip for a streaming LLM response where time to first token, speed with a sparkline, output tokens and cost count up in tabular numerals beside the model's real mark, then settle and open into a latency and token cost breakdown.
- [AI translate](https://uiarc.dev/components/ai-translate/markdown): A message card where picking a language streams the AI translation in place, sentence by sentence over the dimmed original, with a detected-language chip, a Show original toggle and a status line credited to the model's mark.
- [TL;DR toggle](https://uiarc.dev/components/tldr-toggle/markdown): An article card with a Full, Summary and Key points switch and a length slider. Switching streams an AI summary in place of the article as the card's height springs to fit, and each key point links back to the paragraph it came from, which gets scrolled to and highlighted.
- [Connector setup](https://uiarc.dev/components/connector-setup/markdown): A "Connect your tools" card for an AI assistant. Each app connects inline: it redirects, authorizes and runs a first sync with a progress hairline, then lists the scopes it was granted and offers Disconnect with an inline confirm.
- [Smart form fill](https://uiarc.dev/components/smart-form-fill/markdown): A paste-to-fill form card where AI reads an email signature or messy notes and fills a contact field by field. Each value flashes in with a confidence dot, its source lights up in the pasted text, low-confidence guesses ask for review, and Undo puts the old values back.
- [Enrich column](https://uiarc.dev/components/enrich-column/markdown): An AI enrichment column for a data table, where one prompt runs down every row and each cell shimmers while it works, then settles into a value with its source or a failure you can retry.
- [Ticket router](https://uiarc.dev/components/ticket-router/markdown): A support ticket router where messages from Gmail, Intercom, Slack and Zendesk come in one at a time. An AI classifier labels each one with intent, sentiment and confidence, and the ticket moves into a team lane with an assignee. Low confidence tickets wait in a review lane, and one click there routes them to the suggested team.
- [Ask your data](https://uiarc.dev/components/ask-your-data/markdown): A natural language to chart card: you ask a question, PostgreSQL streams into a collapsible, syntax highlighted panel, the query runs with a rolling row count, and the answer builds as stacked bars, lines or a table, with a one line insight streamed in underneath.
- [Agent cursor](https://uiarc.dev/components/agent-cursor/markdown): A live document where Claude edits like a collaborator. Its labeled cursor comes out of its avatar, selects a paragraph and streams in a rewrite, adds a heading and fixes a typo, while a teammate's cursor reads along. Changes stay tinted until someone accepts or undoes them from a floating review bar.
- [Provider status](https://uiarc.dev/components/provider-status/markdown): A status card for the AI providers your product depends on. Each row shows the provider's real mark, its health as an icon and label, p50 latency and a 30-day uptime bar with a tooltip for each day. An incident row expands into its timeline of updates, and the card checks again on a visible countdown.
- [Training run](https://uiarc.dev/components/training-run/markdown): A fine-tuning job card where a live train and validation loss curve draws across a fixed step axis that doubles as the epoch progress bar. It shows the learning rate, elapsed time, ETA and the latest evals and checkpoints, has Pause and Cancel while it runs, and ends in results with a Deploy button.
- [AI command](https://uiarc.dev/components/ai-command/markdown): A Cmd+K command palette with an AI mode. Search pages and actions, or press Tab to ask a question: the answer streams inside the palette with numbered sources, and the next steps it suggests, like filing a Linear issue or opening a Notion doc, run straight from the list.
- [Starter prompts](https://uiarc.dev/components/starter-prompts/markdown): A greeting and a grid of starter cards for the empty state of an AI app. The cards are grouped into Write, Code, Analyze and Plan tabs, and a shuffle swaps them with a short staggered crossfade. Picking a card fills the composer, and cards that use a connected app show its mark (Gmail, GitHub, Notion, Linear, Google Calendar).
- [AI mascot](https://uiarc.dev/components/ai-mascot/markdown): A small assistant character, a soft pebble with pill eyes and a companion dot, that shows what the AI is doing. It breathes and glances when idle, leans in to listen, looks up while the dot orbits its head, reads along the line it writes, squints with a sparkle when done and shakes once with worried brows on an error.
- [Image reveal](https://uiarc.dev/components/image-reveal/markdown): An image generation canvas where a soft, blurred preview made from the image's own colors sharpens top to bottom behind a soft-edged band. It works the way ChatGPT, Midjourney and Gemini show images forming, with fine film grain, a translucent progress pill and calm queued and error states.
- [AI spark](https://uiarc.dev/components/ai-spark/markdown): A brand-quality animated spark mark. Four tapered rays and four lighter diagonals breathe at rest, ripple while thinking, pulse like a heartbeat while writing, then gather and settle when done. Every status change blends from the pose the mark is already in.
- [Pixel mascot](https://uiarc.dev/components/pixel-mascot/markdown): A pixel-art robot that shows what an AI assistant is doing. It idles, thinks, types, celebrates and errors in frame-stepped sprite animations, and stays crisp at every integer size from 24px to 192px.
- [Ghost mascot](https://uiarc.dev/components/ghost-mascot/markdown): A floating ghost mascot whose soft sheet ripples at the hem while it hovers. It blinks when idle, turns toward you to listen, fades a little translucent while thinking, draws a tiny pen line while writing, smiles with a sparkle when done and wobbles once on an error.
- [Cube mascot](https://uiarc.dev/components/cube-mascot/markdown): An isometric cube mascot where three shaded faces and a painted-on face show what the assistant is doing. It turns a quarter turn in eased steps while thinking, prints lines onto the floor while writing, settles with a sparkle when done, and shakes once on error.
- [Tone tuner](https://uiarc.dev/components/tone-tuner/markdown): A brand voice card where two sliders (formality and detail) and Friendly, Confident and Empathetic chips rewrite a customer reply. Each changed sentence crossfades in place, new words can be highlighted against the original, and Copy takes the current version.
- [Upgrade prompt](https://uiarc.dev/components/upgrade-prompt/markdown): An upgrade nudge for the moment someone hits a limit. It shows a usage meter at 50 of 50 AI credits, a rolling price with a monthly and yearly toggle, three concrete unlocks with real model marks, and Upgrade or Maybe later. Upgrading leads into a success state with the new limits, and the card never changes size between states.
- [Referral card](https://uiarc.dev/components/referral-card/markdown): A give-and-get referral card where people copy or share their invite link, invite friends by email as chips, and watch invites move from invited to signed up to earned, with the credit total counting up and a milestone reward unlocking.
- [Trial banner](https://uiarc.dev/components/trial-banner/markdown): A trial status banner where a ring counts down the days left, the copy names what the workspace loses, and the upgrade path is one click away. It comes as a slim banner, a sidebar card or a header pill. It shifts to a warning tone in the last days, has expired and upgraded states, and folds into the pill when dismissed or snoozed.
- [Team switcher](https://uiarc.dev/components/team-switcher/markdown): A workspace switcher like Linear, Vercel or Slack. The trigger shows the current workspace's logo and plan. The menu has search, your role in each workspace and a Cmd+1 to 9 shortcut for each, and lets you create or join a workspace inline. A highlight glides between rows, and switching crossfades the trigger through a short loading state.
- [Live visitors](https://uiarc.dev/components/live-visitors/markdown): A realtime visitors card where the live count rolls digit by digit, new arrivals ping in on a dotted world map, the top pages reorder with bars, and signups and upgrades tick in with country flags.
- [Install snippet](https://uiarc.dev/components/install-snippet/markdown): A "get started in 30 seconds" card where framework tabs, three numbered steps and highlighted snippets take a developer from install to first event. Generate key wipes a fresh API key into the placeholder in place.

### Guidance for AI tools

Social proof toast: A stack of social proof notifications for landing and pricing pages, where recent trials, upgrades and verified purchases from people and companies arrive every few seconds. The stack pauses and fans out on hover, and visitors can dismiss any toast. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Install snippet

> A "get started in 30 seconds" card where framework tabs, three numbered steps and highlighted snippets take a developer from install to first event. Generate key wipes a fresh API key into the placeholder in place.

- Type: Component (special)
- Access: Arc Pro
- Page: https://uiarc.dev/components/install-snippet
- Markdown: https://uiarc.dev/components/install-snippet/markdown
- Source file: `registry/components/install-snippet/install-snippet.tsx`
- Dependencies: motion, lucide-react
- Keywords: special, saas, new, install snippet, quickstart, getting started, sdk install, npm install, api key, code tabs, framework tabs, developer onboarding, copy code

### When to use

- A quickstart that has to work for several frameworks without three pages of docs.
- Onboarding where creating an API key is part of getting started.
- Marketing pages for developer tools that want to show how little setup it takes.

### When not to use

- A single code sample with no steps: use code-block.
- Trying requests against a live API: use api-playground.
- Long setup guides with many branches: write docs pages and link to them.

### Installation

Install snippet is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/install-snippet
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { InstallSnippet } from "@/components/arc/install-snippet/install-snippet";

export function Onboarding() {
  return (
    <InstallSnippet
      generateKey={async signal => {
        const res = await fetch("/api/keys", { method: "POST", signal });
        if (!res.ok) throw new Error("Could not create a key");
        return (await res.json()).key;
      }}
      onCopy={(step) => track("onboarding_copy", { step })}
    />
  );
}
```

### API reference

#### InstallSnippet

A "get started in 30 seconds" card for SDK onboarding: framework tabs with real marks (Next.js, React, Vue, HTML), three numbered steps (Install, Add your key, Ship), highlighted code blocks that crossfade in reserved space, package manager tabs (npm, pnpm, yarn, bun), Arc copy buttons, and a Generate key button that wipes the new key into the placeholder. With no props it shows the sample Lumen analytics SDK with a simulated key generator.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` | `ReactNode` | `"Get started in 30 seconds"` | Card title. |
| `description` | `ReactNode` | `"Three steps to your first event."` | One line under the title. |
| `version` | `ReactNode` | `"v2.4.0"` | Muted label at the top right, such as the SDK version. Pass null to hide it. |
| `frameworks` | `InstallSnippetFramework[]` | `Next.js, React, Vue, HTML samples` | One entry per tab: id, label, install ({ packages } for package managers, or { file, code } for a CDN tag), key ({ file, code }) and code ({ file, code }). Write {{key}} where the API key goes. The ids next, react, vue and html get their marks automatically. |
| `framework` | `string` | – | Controls the selected framework id. Pair with onFrameworkChange. |
| `defaultFramework` | `string` | `first framework` | Framework selected on mount when uncontrolled. |
| `onFrameworkChange` | `(id: string) => void` | – | Called when someone picks another framework tab. |
| `packageManager` | `"npm" \| "pnpm" \| "yarn" \| "bun"` | – | Controls the package manager used in step 1. |
| `defaultPackageManager` | `"npm" \| "pnpm" \| "yarn" \| "bun"` | `"npm"` | Package manager selected on mount when uncontrolled. |
| `onPackageManagerChange` | `(id: InstallSnippetPackageManager) => void` | – | Called when the package manager changes. Persist it to remember the reader's choice across pages. |
| `apiKey` | `string` | – | Controlled key. When set, the snippets show it and the Generate key button is hidden, for signed-in readers who already have a key. |
| `keyPlaceholder` | `string` | `"YOUR_LUMEN_KEY"` | Shown, tinted, wherever {{key}} appears until a key exists. Copies as written. |
| `generateKey` | `(signal: AbortSignal) => Promise<string>` | – | Creates a real key. Resolve with the key and it wipes into step 2; reject to show the error state with Try again. Aborted on unmount or when a new key is requested. Leave it out to simulate one (nothing is sent, and the step says so). |
| `onKeyGenerated` | `(key: string) => void` | – | Called with each new key. |
| `onCopy` | `(step: "install" \| "key" \| "code", value: string) => void` | – | Called after a copy with the exact clipboard text. Useful for onboarding analytics. |
| `className` | `string` | – | Extra class on the card. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Tab | Moves between the framework tabs, package manager tabs, copy buttons and the Generate key button. |
| ArrowLeft / ArrowRight | Inside a tab list, moves to and selects the previous or next tab. |
| Home / End | Inside a tab list, selects the first or last tab. |
| Enter / Space | Copies a snippet or generates a key. |

### Accessibility

- Framework and package manager tabs are real tablists with roving tabindex; the steps list is the framework tab panel.
- Steps are an ordered list with h4 titles; a finished step announces ", done" and swaps its number for a check, so progress is never color alone.
- A polite live region announces framework changes, key generation, and that the default key is simulated. Copy buttons announce Copied on their own.
- Errors show an alert icon plus text, and the button changes to Try again.
- Marks are decorative (aria-hidden); every tab has a text label, and package manager tabs keep an aria-label when the narrow layout hides their names.

### Motion

- Tab highlights slide to the measured tab on a bounce-free spring (visualDuration .24).
- Snippets, file names and step descriptions crossfade: the old one fades out in 100ms, the new one fades in over 160ms with a 2px rise. Old and new share one grid cell and every code block reserves the height of its longest snippet, so nothing moves.
- A new key eases the slot from the placeholder width to the key width (exact, in ch) while the key wipes in from the left over 340ms, then its tint fades out.
- Reduced motion keeps every end state and drops the wipe, rise and slide.

### Responsive behavior

- Fills its container up to 640px. Below 460px the padding tightens and package manager tabs show marks only; below 380px framework tabs drop their marks and keep their names, and the version label hides.
- Code scrolls horizontally inside its block, never the page.

### Performance

- Highlighting is a small regex tokenizer, memoized per snippet. No highlighter dependency.
- Only transforms, opacity, clip-path and one measured width animate. No loops, nothing runs when idle.

### Notes for AI

- Use for SDK, API or CLI onboarding: the first screen after sign-up, a docs quickstart, or an empty dashboard waiting for its first event.
- Wire generateKey to your key endpoint and pass apiKey for readers who already have one. Keep snippets short (under ten lines) so the card stays scannable.
- Replace the sample frameworks with your own; any id other than next, react, vue or html shows a text-only tab.
- Do not use it to display existing secret keys in full; mask them in an API keys page instead.

### Related

- [Code block](https://uiarc.dev/components/code-block/markdown): Present code with legible hierarchy and copy access.
- [Copy button](https://uiarc.dev/components/copy-button/markdown): Copy a value with immediate confirmation.
- [Connector setup](https://uiarc.dev/components/connector-setup/markdown): A "Connect your tools" card for an AI assistant. Each app connects inline: it redirects, authorizes and runs a first sync with a progress hairline, then lists the scopes it was granted and offers Disconnect with an inline confirm.
- [Onboarding checklist](https://uiarc.dev/components/onboarding-checklist/markdown): Guide a new workspace through setup, one step at a time.
- [Tabs](https://uiarc.dev/components/tabs/markdown): Switch between related content in the same context.

### Also in ai

- [Agent status](https://uiarc.dev/components/agent-status/markdown): A compact live status pill for a running AI agent: the agent's mark in a live ring, the current activity and an elapsed timer, opening into the steps so far.
- [Tool call](https://uiarc.dev/components/tool-call/markdown): A tool call row for agent transcripts: the tool's mark and the call in plain words, a live state while it runs, and the input and output a click away, with approval and retry when needed.
- [Agent plan](https://uiarc.dev/components/agent-plan/markdown): The plan an agent writes before it acts: edit, reorder or add steps while it is a draft, then watch it work through them as a live checklist.
- [Agent timeline](https://uiarc.dev/components/agent-timeline/markdown): A compact timeline of one orchestrated agent run: the orchestrator and its subagents share a time axis, handoffs draw in between rows, and a playhead replays thinking, tool calls and waiting while the header counts time, tokens and cost. Hover a span for what it did, or click it to trace its handoff path.
- [Context window](https://uiarc.dev/components/context-window/markdown): An AI context window as a grid of 200 cells: the system prompt, tools, files, summary and messages fill it in order, a threshold row marks where compaction starts, and sending a message, attaching a file or compacting shows exactly how much still fits.
- [Reasoning block](https://uiarc.dev/components/reasoning-block/markdown): The collapsible thinking block of an AI reply. While the model thinks, a shimmering label counts the seconds and the latest reasoning streams underneath. When it finishes, it folds to "Thought for 7s" and opens to show the full reasoning as calm steps with headings.
- [Source cards](https://uiarc.dev/components/source-cards/markdown): A row of cited sources under an AI answer where cards stream in with real site marks while the model searches, the overflow collapses into a stack of favicons, hovering lifts a preview with the passage, and an inline [n] citation highlights its card.
- [Model card](https://uiarc.dev/components/model-card/markdown): A model details card where switching models rolls every price, limit and score in place, a token slider estimates monthly cost live, and benchmark bars show each model's rank on hover. Compare crossfades to a side-by-side table against any rival with the better values marked, and the card never changes size.
- [AI workflow](https://uiarc.dev/components/ai-workflow/markdown): A Linear-style AI workflow card where a Gmail trigger, a Claude step, a branch and Slack and Linear actions sit on one hairline rail, and a test run glides down it, opening each step's output inline. Steps are added from a compact command menu with real app marks.
- [Code suggestion](https://uiarc.dev/components/code-suggestion/markdown): An AI code edit suggestion where the model's proposed changes stream into a small editor panel as inline diff hunks, and you accept or reject each one, or all at once with Cmd+Enter. Accepted hunks fold into the file with a smooth height change.
- [Ghost text](https://uiarc.dev/components/ghost-text/markdown): An inline AI autocomplete where muted ghost text continues your sentence exactly at the caret and Tab turns it solid in place. Cmd+Right takes it one word at a time, Escape fades it away, and a calm chip shows the model behind it.
- [Image generation](https://uiarc.dev/components/image-generation/markdown): An image studio where each image forms on a dot matrix: a soft halftone wave breathes across the grid, the dots take the colours of the coming photo and grow into a coloured halftone, then blur away into the sharp photo. One large canvas with a mono size label, a filmstrip of four variations, a prompt bar with model and ratio, and upscale with a sweeping dot band, vary or download, with real provider marks and a built-in simulation.
- [Dictation button](https://uiarc.dev/components/dictation-button/markdown): A chat composer with voice input, where the mic springs into a recording pill with a smooth live waveform, a timer, and cancel and insert buttons. Words stream into the field as you speak, muted until the recognizer settles them.
- [Speech player](https://uiarc.dev/components/speech-player/markdown): A read-aloud player for AI replies. The Read aloud button in the message's action row turns into a compact player with play, a scrubbable progress bar, speed and a voice picker, and a highlight follows the spoken word through the reply, karaoke style.
- [Meeting summary](https://uiarc.dev/components/meeting-summary/markdown): An AI meeting notes card: the header shows the Google Meet or Zoom mark, the attendees and the duration. Summary, Decisions and Action items stream in after a short summarizing pass. Hover any line to see the transcript quote it came from, then check off action items or send them to Linear or Notion.
- [Reply draft](https://uiarc.dev/components/reply-draft/markdown): An AI email reply drafter where Claude streams a reply under a received Gmail message. Quick replies steer a fresh draft, tone and length rewrite it with a single crossfade, and you can edit the finished draft before you insert it.
- [Agent handoff](https://uiarc.dev/components/agent-handoff/markdown): A support conversation where an AI assistant hands off to a person. When it transfers, a card shows the summary it passes to the team and the typical wait. The person then joins and takes over, and a thin timeline on the left marks each step.
- [PII redaction](https://uiarc.dev/components/pii-redaction/markdown): A guardrail card where personal data is redacted before the prompt reaches the model. Scan marks each name, email, phone number and card with its type and swaps it for a placeholder like [EMAIL_1]. The safe prompt travels to Claude, and the reply comes back with the original values put back for the person.
- [Response feedback](https://uiarc.dev/components/response-feedback/markdown): A feedback control for AI replies where thumbs down opens an inline panel with reason chips and an optional note, thumbs up fills and asks what was good, and a submit shows a short thank-you before folding back into the row.
- [LLM cost calculator](https://uiarc.dev/components/llm-cost-calculator/markdown): A pricing calculator for LLM workloads. Set tokens per request, requests per day and prompt caching, and eight current models re-rank by monthly cost. Bars glide and prices roll as you drag.
- [Provider keys](https://uiarc.dev/components/provider-keys/markdown): A settings card for bring-your-own-key AI products. Each provider row shows its real mark, the masked key, a status and when the key was last used. You can reveal a key for five seconds, copy, rotate or remove it with undo. Adding or rotating a key opens an inline form that checks the format as you type, then tests the connection before saving.
- [Generation stats](https://uiarc.dev/components/generation-stats/markdown): A live stats strip for a streaming LLM response where time to first token, speed with a sparkline, output tokens and cost count up in tabular numerals beside the model's real mark, then settle and open into a latency and token cost breakdown.
- [AI translate](https://uiarc.dev/components/ai-translate/markdown): A message card where picking a language streams the AI translation in place, sentence by sentence over the dimmed original, with a detected-language chip, a Show original toggle and a status line credited to the model's mark.
- [TL;DR toggle](https://uiarc.dev/components/tldr-toggle/markdown): An article card with a Full, Summary and Key points switch and a length slider. Switching streams an AI summary in place of the article as the card's height springs to fit, and each key point links back to the paragraph it came from, which gets scrolled to and highlighted.
- [Smart form fill](https://uiarc.dev/components/smart-form-fill/markdown): A paste-to-fill form card where AI reads an email signature or messy notes and fills a contact field by field. Each value flashes in with a confidence dot, its source lights up in the pasted text, low-confidence guesses ask for review, and Undo puts the old values back.
- [Enrich column](https://uiarc.dev/components/enrich-column/markdown): An AI enrichment column for a data table, where one prompt runs down every row and each cell shimmers while it works, then settles into a value with its source or a failure you can retry.
- [Ticket router](https://uiarc.dev/components/ticket-router/markdown): A support ticket router where messages from Gmail, Intercom, Slack and Zendesk come in one at a time. An AI classifier labels each one with intent, sentiment and confidence, and the ticket moves into a team lane with an assignee. Low confidence tickets wait in a review lane, and one click there routes them to the suggested team.
- [Ask your data](https://uiarc.dev/components/ask-your-data/markdown): A natural language to chart card: you ask a question, PostgreSQL streams into a collapsible, syntax highlighted panel, the query runs with a rolling row count, and the answer builds as stacked bars, lines or a table, with a one line insight streamed in underneath.
- [Agent cursor](https://uiarc.dev/components/agent-cursor/markdown): A live document where Claude edits like a collaborator. Its labeled cursor comes out of its avatar, selects a paragraph and streams in a rewrite, adds a heading and fixes a typo, while a teammate's cursor reads along. Changes stay tinted until someone accepts or undoes them from a floating review bar.
- [Provider status](https://uiarc.dev/components/provider-status/markdown): A status card for the AI providers your product depends on. Each row shows the provider's real mark, its health as an icon and label, p50 latency and a 30-day uptime bar with a tooltip for each day. An incident row expands into its timeline of updates, and the card checks again on a visible countdown.
- [Training run](https://uiarc.dev/components/training-run/markdown): A fine-tuning job card where a live train and validation loss curve draws across a fixed step axis that doubles as the epoch progress bar. It shows the learning rate, elapsed time, ETA and the latest evals and checkpoints, has Pause and Cancel while it runs, and ends in results with a Deploy button.
- [AI command](https://uiarc.dev/components/ai-command/markdown): A Cmd+K command palette with an AI mode. Search pages and actions, or press Tab to ask a question: the answer streams inside the palette with numbered sources, and the next steps it suggests, like filing a Linear issue or opening a Notion doc, run straight from the list.
- [Starter prompts](https://uiarc.dev/components/starter-prompts/markdown): A greeting and a grid of starter cards for the empty state of an AI app. The cards are grouped into Write, Code, Analyze and Plan tabs, and a shuffle swaps them with a short staggered crossfade. Picking a card fills the composer, and cards that use a connected app show its mark (Gmail, GitHub, Notion, Linear, Google Calendar).
- [AI mascot](https://uiarc.dev/components/ai-mascot/markdown): A small assistant character, a soft pebble with pill eyes and a companion dot, that shows what the AI is doing. It breathes and glances when idle, leans in to listen, looks up while the dot orbits its head, reads along the line it writes, squints with a sparkle when done and shakes once with worried brows on an error.
- [Image reveal](https://uiarc.dev/components/image-reveal/markdown): An image generation canvas where a soft, blurred preview made from the image's own colors sharpens top to bottom behind a soft-edged band. It works the way ChatGPT, Midjourney and Gemini show images forming, with fine film grain, a translucent progress pill and calm queued and error states.
- [AI spark](https://uiarc.dev/components/ai-spark/markdown): A brand-quality animated spark mark. Four tapered rays and four lighter diagonals breathe at rest, ripple while thinking, pulse like a heartbeat while writing, then gather and settle when done. Every status change blends from the pose the mark is already in.
- [Pixel mascot](https://uiarc.dev/components/pixel-mascot/markdown): A pixel-art robot that shows what an AI assistant is doing. It idles, thinks, types, celebrates and errors in frame-stepped sprite animations, and stays crisp at every integer size from 24px to 192px.
- [Ghost mascot](https://uiarc.dev/components/ghost-mascot/markdown): A floating ghost mascot whose soft sheet ripples at the hem while it hovers. It blinks when idle, turns toward you to listen, fades a little translucent while thinking, draws a tiny pen line while writing, smiles with a sparkle when done and wobbles once on an error.
- [Cube mascot](https://uiarc.dev/components/cube-mascot/markdown): An isometric cube mascot where three shaded faces and a painted-on face show what the assistant is doing. It turns a quarter turn in eased steps while thinking, prints lines onto the floor while writing, settles with a sparkle when done, and shakes once on error.
- [Tone tuner](https://uiarc.dev/components/tone-tuner/markdown): A brand voice card where two sliders (formality and detail) and Friendly, Confident and Empathetic chips rewrite a customer reply. Each changed sentence crossfades in place, new words can be highlighted against the original, and Copy takes the current version.
- [Upgrade prompt](https://uiarc.dev/components/upgrade-prompt/markdown): An upgrade nudge for the moment someone hits a limit. It shows a usage meter at 50 of 50 AI credits, a rolling price with a monthly and yearly toggle, three concrete unlocks with real model marks, and Upgrade or Maybe later. Upgrading leads into a success state with the new limits, and the card never changes size between states.
- [Referral card](https://uiarc.dev/components/referral-card/markdown): A give-and-get referral card where people copy or share their invite link, invite friends by email as chips, and watch invites move from invited to signed up to earned, with the credit total counting up and a milestone reward unlocking.
- [Trial banner](https://uiarc.dev/components/trial-banner/markdown): A trial status banner where a ring counts down the days left, the copy names what the workspace loses, and the upgrade path is one click away. It comes as a slim banner, a sidebar card or a header pill. It shifts to a warning tone in the last days, has expired and upgraded states, and folds into the pill when dismissed or snoozed.
- [Team switcher](https://uiarc.dev/components/team-switcher/markdown): A workspace switcher like Linear, Vercel or Slack. The trigger shows the current workspace's logo and plan. The menu has search, your role in each workspace and a Cmd+1 to 9 shortcut for each, and lets you create or join a workspace inline. A highlight glides between rows, and switching crossfades the trigger through a short loading state.
- [Live visitors](https://uiarc.dev/components/live-visitors/markdown): A realtime visitors card where the live count rolls digit by digit, new arrivals ping in on a dotted world map, the top pages reorder with bars, and signups and upgrades tick in with country flags.
- [Social proof toast](https://uiarc.dev/components/social-proof-toast/markdown): A stack of social proof notifications for landing and pricing pages, where recent trials, upgrades and verified purchases from people and companies arrive every few seconds. The stack pauses and fans out on hover, and visitors can dismiss any toast.

### Guidance for AI tools

Install snippet: A "get started in 30 seconds" card where framework tabs, three numbered steps and highlighted snippets take a developer from install to first event. Generate key wipes a fresh API key into the placeholder in place. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Data flow

> Data flow illustration. Sources (app, database, events) are on the left, a processing core with a live count sits in the middle, and destinations (warehouse, dashboard, alerts) are on the right. Records leave as hollow dots and travel curved paths. In the core they turn into solid accent squares, then fan out to each destination; alerts receives about every third record.

- Type: Component (special)
- Access: Arc Pro
- Page: https://uiarc.dev/components/data-flow
- Markdown: https://uiarc.dev/components/data-flow/markdown
- Source file: `registry/components/data-flow/data-flow.tsx`
- Dependencies: motion, lucide-react
- Keywords: special, motion, illustration, new, data flow, pipeline illustration, etl, data pipeline, event routing, animated diagram, fan out, ingestion, transform

### When to use

- A hero or feature section explaining how data moves through a product.
- Docs pages introducing an ingestion, transform, or routing concept.
- Integration pages that show which sources feed which destinations.

### When not to use

- Use sankey-flow to show real volumes between stages.
- Use pipeline-status for the live state of a CI or data job.
- Use a table or list when people need to act on individual records.

### Installation

Data flow is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/data-flow
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { DataFlow } from "@/components/arc/data-flow/data-flow";
import { AppWindow, LayoutDashboard, Warehouse } from "lucide-react";

// Image URLs keep full brand color; lucide icons follow the muted text color.
const sources = [
  { label: "App", meta: "Web and iOS", icon: <AppWindow /> },
  { label: "Database", meta: "Supabase", icon: "/logos/supabase-color.svg" },
  { label: "Events", meta: "Stripe webhooks", icon: "/logos/stripe-color.svg" },
];
const destinations = [
  { label: "Warehouse", meta: "Every record", icon: <Warehouse /> },
  { label: "Dashboard", meta: "Live metrics", icon: <LayoutDashboard /> },
  { label: "Alerts", meta: "Slack", icon: "/logos/slack-color.svg", share: 0.34 },
];

export function PipelineHero() {
  return <DataFlow sources={sources} destinations={destinations} core={{ label: "Transform" }} />;
}
```

### API reference

#### DataFlow

An animated data flow illustration. Sources sit on one side, a processing core in the middle, and destinations on the other. Raw records leave the sources as hollow dots, travel curved paths into the core, turn into solid accent squares as they are processed, and fan out to every destination that takes them. A live count under the core ticks up as records are processed, and hovering a node highlights its path and records with a one line tag.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `sources` | `{ id?: string; label: string; meta?: string; detail?: string; icon?: string \| ReactNode; color?: string }[]` | `App, Database, Events` | Where records come from. Three read best. meta is the second line (hidden on narrow layouts), detail is the hover tag. icon is SVG path data on a 24 by 24 viewBox painted in color, an image URL for a full color logo, or any ReactNode. |
| `destinations` | `{ id?: string; label: string; meta?: string; detail?: string; icon?: string \| ReactNode; color?: string; share?: number }[]` | `Warehouse, Dashboard, Alerts` | Where processed records go. share (0 to 1) thins out a destination evenly, so 0.34 sends about every third record, as alerts do in the default. |
| `core` | `{ label?: string; detail?: string; countLabel?: string; countStart?: number }` | `{ label: "Transform", countLabel: "processed", countStart: 12480 }` | The processing step: its name, hover tag, the word after the live count, and the number the count starts from. |
| `speed` | `number` | `1` | Multiplies the flow speed. At 1 a record takes about four seconds end to end. 0 holds still. |
| `paused` | `boolean` | `false` | Holds the flow still where it is, easing to rest instead of stopping in one frame. |
| `accent` | `string` | – | Color of processed records, trails, and active paths. Defaults to the accent token. |
| `label` | `string` | – | Accessible description of the diagram. Built from the source, core, and destination labels when left out. |
| `caption` | `ReactNode` | – | Optional visible caption under the diagram, rendered as a figcaption. |
| `className` | `string` | – | Extra class on the root figure. |
| `style` | `CSSProperties` | – | Inline styles on the root figure. |

### Accessibility

- The diagram is one element with role="img" and an aria-label that describes the whole flow, built from the labels unless label is passed.
- Nodes are not controls, so nothing enters the tab order; hover tags repeat detail that is optional.
- Raw and processed records differ in shape (hollow dot, solid square), not only color.
- Pass caption for a visible explanation under the diagram.
- Pointer focus draws no ring; keyboard focus shows Arc's shared focus ring.

### Motion

- One rAF loop writes SVG transforms, opacity, and dash offsets straight to the DOM, and only when a value changed; React does not render per frame.
- Records travel along real cubic paths at an even pace from an arc length table, eased in and out on each leg, with a short trail that stops at the core outline.
- In the core each record swells slightly as it morphs from a hollow dot into an accent square, the core outline widens and fades, and the dashed ring quickens for a moment. On the way out one copy carries the record while the others fade in as they split off, so the fan out never clumps.
- Six records per 6.6 second cycle are a pure function of time, so the loop repeats seamlessly; ports and node borders light up as records leave and land.
- Speed changes, pausing, and hover (which slows the flow a little) ease on a critically damped spring.
- The loop stops off screen, in hidden tabs, and when paused. Reduced motion shows a still frame: a raw record on each in path and a processed record on each out path.

### Responsive behavior

- From 600px wide the flow runs left to right with two line nodes; below that it stacks top to bottom with sources in a row above the core and destinations below.
- The diagram is measured in real pixels and drawn in an SVG viewBox of that size, so text and hairlines stay crisp at any width.
- Hover tags only appear for a mouse; touch shows the same diagram without them.

### Performance

- About forty SVG elements move, from a single loop that caches every written value.
- Paths are sampled once per layout into a small length table; nothing is measured per frame.

### Notes for AI

- Use it to explain a pipeline on a landing page or in docs: ingestion, ETL, event routing, sync.
- Keep labels to one or two words and put the product in meta, such as Database with Supabase.
- Use real brand logos only where the product matters to the story; keep generic roles on lucide icons.
- Use share on destinations that receive a subset, such as alerts, so the fan out tells the truth.

### Related

- [Sankey flow](https://uiarc.dev/components/sankey-flow/markdown): Flows between stages as ribbons with drifting particles; hover any node or ribbon to pour its share through the whole journey.
- [Orbit logos](https://uiarc.dev/components/orbit-logos/markdown): An integrations showcase with brand logos orbiting your product mark on tilted rings. Hover or focus one to rest the orbit, draw a connection, and see what it does.
- [Realtime stream](https://uiarc.dev/components/realtime-stream/markdown): A live line that scrolls at 60fps as readings arrive, holds still on hover to read, and pops a marker on every anomaly.

### Also in illustrations

- [Payment flow](https://uiarc.dev/components/payment-flow/markdown): A card tap goes to a processor, then the network, then the bank and back with authorization, then settlement; each hop lights up with a status label and the amount travels as a chip.
- [DNS resolution](https://uiarc.dev/components/dns-resolution/markdown): A browser asks for a domain and the query hops from the resolver to a root server, the TLD server and the authoritative nameserver, each pointing to the next, until an IP address comes back and the page connects. The resolver keeps the answer with a TTL ring that drains, and a second lookup is answered straight from that cache in one short hop.
- [Model training](https://uiarc.dev/components/model-training/markdown): Training data batches feed a small neural net diagram whose connections strengthen, a loss curve descends beside it, and an evaluation check turns green at the end.
- [Multi-region failover](https://uiarc.dev/components/multi-region-failover/markdown): Animated multi-region failover on a 2.5D stage: users stream requests through a global load balancer to two regions; the primary degrades, fails three health checks, traffic shifts smoothly to the healthy region, then it recovers, passes three checks and traffic ramps back to an even split.
- [Vector search](https://uiarc.dev/components/vector-search/markdown): Documents drop onto a tilted embedding plane and fold into points that cluster by topic; the index links neighbours, a query is typed, embedded and lowered onto the plane, a signal hops along the graph toward it, and a widening ring lights the nearest documents with connecting lines, similarity scores and a ranked list.
- [Branch graph](https://uiarc.dev/components/branch-graph/markdown): A git commit graph where branches draw in as colored lanes, merge commits join lines, a rebase lifts commits and replays them onto main, a squash folds them into one, and hovering a commit shows its message, author and diff stats.
- [Agent loop](https://uiarc.dev/components/agent-loop/markdown): An illustration of the agent loop: gather context, take action, verify, repeat, with a bright head circling three stations around the model.
- [Mixture of experts](https://uiarc.dev/components/mixture-of-experts/markdown): An illustration of mixture of experts routing: each token is scored by a router, travels to its top experts, and their outputs merge into the token's result.
- [Speculative decoding](https://uiarc.dev/components/speculative-decoding/markdown): An illustration of speculative decoding: a fast draft model guesses a few tokens, the target model checks them in one pass, and accepted guesses join the answer.
- [Prompt cache](https://uiarc.dev/components/prompt-cache/markdown): An animated explainer for prompt caching: the shared prefix of each request is cached once, later requests read it back, and the cost and time saved add up.
- [Reasoning tree](https://uiarc.dev/components/reasoning-tree/markdown): An illustration of tree search over thoughts: candidates are scored, weak branches fade, the best expand, and the winning path from question to answer draws in.

### Guidance for AI tools

Data flow: Data flow illustration. Sources (app, database, events) are on the left, a processing core with a live count sits in the middle, and destinations (warehouse, dashboard, alerts) are on the right. Records leave as hollow dots and travel curved paths. In the core they turn into solid accent squares, then fan out to each destination; alerts receives about every third record. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Payment flow

> A card tap goes to a processor, then the network, then the bank and back with authorization, then settlement; each hop lights up with a status label and the amount travels as a chip.

- Type: Component (special)
- Access: Arc Pro
- Page: https://uiarc.dev/components/payment-flow
- Markdown: https://uiarc.dev/components/payment-flow/markdown
- Source file: `registry/components/payment-flow/payment-flow.tsx`
- Dependencies: motion, lucide-react
- Keywords: special, motion, illustration, new, payment, card payment, authorization, settlement, payout, processor, card network, issuer, fees, animated diagram

### When to use

- A payments or checkout landing section that explains authorization and settlement.
- Docs pages introducing processors, card networks, issuers, fees, and payout timing.

### When not to use

- Use checkout-flow or checkout-live for a real checkout form.
- Use webhook-fanout to explain what happens after a payment event is emitted.

### Installation

Payment flow is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/payment-flow
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { PaymentFlow } from "@/components/arc/payment-flow/payment-flow";

export function PaymentsSection() {
  return <PaymentFlow
    amount={42.5}
    fee={1.53}
    balance={1284.1}
    currency="USD"
    caption="Approved in about a second, paid out the next business day."
  />;
}
```

### API reference

#### PaymentFlow

An animated card payment illustration. A tap at checkout sends the amount as a small chip through the processor and the card network to the issuing bank, slipping under each node while it is processed as that node's status line changes. The bank approves, and an approval chip travels back and repaints the path in success. Then settlement runs on a second rail: the funds clear through the network, the processor takes its fee (the chip turns into the net amount), and the payout lands in the merchant balance, which counts up. A step row under the diagram counts the authorization time and fills as settlement runs.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `nodes` | `{ terminal?, processor?, network?, issuer?, merchant?: PaymentFlowNode }` | `Checkout, Stripe, Mastercard, Bank, Your balance` | The five stops. Each one you pass replaces the default for that stop. A node is { label, meta?, detail?, icon?, color? }: meta is the resting second line, detail is the hover tag, icon is SVG path data on a 24 by 24 viewBox painted in color, an image URL, or any ReactNode. The merchant's second line always shows the balance. |
| `amount` | `number` | `42.5` | The charge, shown on the chip that travels to the bank. |
| `fee` | `number` | `1.53` | What the processor keeps at settlement. The payout is amount minus fee. |
| `balance` | `number` | `1284.1` | Merchant balance before the first payout. It grows by the payout on every loop. |
| `currency` | `string` | `"USD"` | ISO currency code for every amount. |
| `locale` | `string` | `"en-US"` | Locale for money formatting. Keep it fixed so the server and the browser agree. |
| `authorizationMs` | `number` | `1340` | Authorization time the step row counts to, in milliseconds. |
| `labels` | `{ authorization?: string; settlement?: string; settlementTime?: string; approved?: string }` | `Authorization, Settlement, Next business day, Approved` | Phase names in the step row, when settlement happens, and the text on the approval chip. |
| `hideSteps` | `boolean` | `false` | Hides the step row and shows only the diagram. |
| `speed` | `number` | `1` | Multiplies the pace. At 1 one payment takes about 15 seconds. 0 holds still. |
| `paused` | `boolean` | `false` | Holds the diagram still where it is, easing to rest instead of stopping in one frame. |
| `accent` | `string` | – | Color of the moving amount, the active path, the settlement rail, and hovered wires. Defaults to the accent token. Approval and settled states stay semantic success. |
| `label` | `string` | – | Accessible description of the diagram. Built from the nodes and amounts when left out. |
| `caption` | `ReactNode` | – | Optional visible caption under the diagram, rendered as a figcaption. |
| `className` | `string` | – | Extra class on the root figure. |
| `style` | `CSSProperties` | – | Inline styles on the root figure. |

### Accessibility

- The diagram is one element with role="img" and an aria-label that tells the whole story: the amount, every hop, the approval, the fee, and the payout.
- Nodes are not controls, so nothing enters the tab order; hover tags only repeat optional detail.
- State never relies on color alone: every node's status line reads Checking risk, Routed to bank, Approved, Cleared, Fee $1.53, or Settled, and the approval chip carries a check and a word.
- Pass caption for a visible explanation under the diagram.
- Pointer focus draws no ring; keyboard focus shows Arc's shared focus ring.

### Motion

- One rAF loop writes transforms, opacity, dash values, a few attributes, and text nodes straight to the DOM, and only when a value changed; React does not render per frame.
- The payment is a pure function of time, so the loop repeats seamlessly: tap, authorize, approve, settle, pay out, rest. The balance keeps growing from loop to loop instead of jumping back.
- The amount eases from node to node and slips under each chip while it is processed, so every hop reads as enter, work, leave. The path lights in the accent behind it and turns to success as the approval travels back.
- At the processor waypoint the settlement chip crossfades from the gross to the net amount, which is the fee shown as cause and effect; the balance then counts up with tabular numerals.
- Speed changes, pausing, and hover (which slows the story a little) ease on a critically damped spring. The loop stops off screen, in hidden tabs, and when paused.
- Reduced motion shows a still frame just after the fee: approved at checkout, the network cleared, the bank settled, and the net amount on its way to the balance.

### Responsive behavior

- The diagram is measured in real pixels and drawn in an SVG viewBox of that size, so text and hairlines stay crisp at any width.
- Below 700px it turns vertical: the four hops stack on the left and the balance sits top right, with the settlement rail running up beside the chain.
- The step row stacks into one column below 420px. Hover tags only appear for a mouse.

### Performance

- About forty small elements driven by a single loop that caches every written value.
- Paths are sampled once per layout into small length tables; nothing is measured per frame.

### Notes for AI

- Use it to explain how a card payment works, why payouts arrive later than approvals, or where fees come from, on a landing page or in docs.
- Match the fee and amount to the product's real pricing so the diagram tells the truth, and swap the processor and network marks for the ones the product uses.
- Keep node labels to one or two words; the status lines carry the story.

### Related

- [Data flow](https://uiarc.dev/components/data-flow/markdown): Data flow illustration. Sources (app, database, events) are on the left, a processing core with a live count sits in the middle, and destinations (warehouse, dashboard, alerts) are on the right. Records leave as hollow dots and travel curved paths. In the core they turn into solid accent squares, then fan out to each destination; alerts receives about every third record.

### Also in illustrations

- [DNS resolution](https://uiarc.dev/components/dns-resolution/markdown): A browser asks for a domain and the query hops from the resolver to a root server, the TLD server and the authoritative nameserver, each pointing to the next, until an IP address comes back and the page connects. The resolver keeps the answer with a TTL ring that drains, and a second lookup is answered straight from that cache in one short hop.
- [Model training](https://uiarc.dev/components/model-training/markdown): Training data batches feed a small neural net diagram whose connections strengthen, a loss curve descends beside it, and an evaluation check turns green at the end.
- [Multi-region failover](https://uiarc.dev/components/multi-region-failover/markdown): Animated multi-region failover on a 2.5D stage: users stream requests through a global load balancer to two regions; the primary degrades, fails three health checks, traffic shifts smoothly to the healthy region, then it recovers, passes three checks and traffic ramps back to an even split.
- [Vector search](https://uiarc.dev/components/vector-search/markdown): Documents drop onto a tilted embedding plane and fold into points that cluster by topic; the index links neighbours, a query is typed, embedded and lowered onto the plane, a signal hops along the graph toward it, and a widening ring lights the nearest documents with connecting lines, similarity scores and a ranked list.
- [Branch graph](https://uiarc.dev/components/branch-graph/markdown): A git commit graph where branches draw in as colored lanes, merge commits join lines, a rebase lifts commits and replays them onto main, a squash folds them into one, and hovering a commit shows its message, author and diff stats.
- [Agent loop](https://uiarc.dev/components/agent-loop/markdown): An illustration of the agent loop: gather context, take action, verify, repeat, with a bright head circling three stations around the model.
- [Mixture of experts](https://uiarc.dev/components/mixture-of-experts/markdown): An illustration of mixture of experts routing: each token is scored by a router, travels to its top experts, and their outputs merge into the token's result.
- [Speculative decoding](https://uiarc.dev/components/speculative-decoding/markdown): An illustration of speculative decoding: a fast draft model guesses a few tokens, the target model checks them in one pass, and accepted guesses join the answer.
- [Prompt cache](https://uiarc.dev/components/prompt-cache/markdown): An animated explainer for prompt caching: the shared prefix of each request is cached once, later requests read it back, and the cost and time saved add up.
- [Reasoning tree](https://uiarc.dev/components/reasoning-tree/markdown): An illustration of tree search over thoughts: candidates are scored, weak branches fade, the best expand, and the winning path from question to answer draws in.

### Guidance for AI tools

Payment flow: A card tap goes to a processor, then the network, then the bank and back with authorization, then settlement; each hop lights up with a status label and the amount travels as a chip. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## DNS resolution

> A browser asks for a domain and the query hops from the resolver to a root server, the TLD server and the authoritative nameserver, each pointing to the next, until an IP address comes back and the page connects. The resolver keeps the answer with a TTL ring that drains, and a second lookup is answered straight from that cache in one short hop.

- Type: Component (special)
- Access: Arc Pro
- Page: https://uiarc.dev/components/dns-resolution
- Markdown: https://uiarc.dev/components/dns-resolution/markdown
- Source file: `registry/components/dns-resolution/dns-resolution.tsx`
- Dependencies: motion, lucide-react
- Keywords: special, motion, illustration, new, dns, dns resolution, dns lookup, resolver, root server, tld, nameserver, authoritative, ttl, cache, domain, ip address, isometric, animated diagram, landing page, docs

### When to use

- A docs or marketing section that explains how a domain name turns into an address and why the second visit is faster.
- Custom domain setup, DNS hosting, resolver or CDN pages that need the chain of servers and the role of TTL to click.
- Teaching material where viewers should be able to step back and forth through each hop.

### When not to use

- Use webhook-fanout to show one event delivered to many endpoints with retries.
- Use data-flow for a general pipeline between services.
- Use a real status or table component to report actual DNS records or propagation.

### Installation

DNS resolution is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/dns-resolution
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { DnsResolution } from "@/components/arc/dns-resolution/dns-resolution";

export function DnsSection() {
  return (
    <DnsResolution
      domain="app.acme.dev"
      address="203.0.113.24"
      ttl={300}
      nodes={{ resolver: { label: "Resolver", meta: "1.1.1.1" } }}
    />
  );
}
```

### API reference

#### DnsResolution

An animated DNS lookup on a layered 2.5D stage. The browser asks a resolver for a name, and the query arcs through the air to the root server, the TLD server and the authoritative nameserver, each pointing to the next, until the address comes back and the page draws in on the browser. The resolver stores the answer with a TTL ring that drains on its cache tier, and a second lookup is answered from that cache in one short hop. A step scrubber replays the story or jumps to any stage, and statuses, counters and the record each packet carries update in sync.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `domain` | `string` | `"app.acme.dev"` | The name being looked up. The TLD server (.dev) and the default nameserver (ns1.acme.dev) are derived from it. |
| `address` | `string` | `"203.0.113.24"` | The address the nameserver answers with, shown on the answer packets, the nameserver status and the cached record. |
| `ttl` | `number` | `300` | Time to live of the answer in seconds. The cached record counts it down while the ring drains, then shows Expired. |
| `lookupMs` | `number` | `84` | Milliseconds the full lookup takes, counted up in the browser status. |
| `cachedMs` | `number` | `1` | Milliseconds the cached lookup takes. |
| `nodes` | `Partial<Record<"browser" \| "resolver" \| "root" \| "tld" \| "authoritative", { label?: string; meta?: string; detail?: string; icon?: string \| ReactNode; color?: string }>>` | `Browser, Resolver, Root server, TLD server, Nameserver` | Overrides per node: the name, a meta line, the hover detail and an optional mark (Simple Icons path data, an image URL or a ReactNode). The nameserver meta is also the host the TLD refers to. |
| `speed` | `number` | `1` | Multiplies the pace. One lookup and cache cycle takes 16 seconds at 1. 0 holds still. |
| `paused` | `boolean` | `false` | Holds the animation, easing to rest. Paused from the start, it shows the cached state with every hop answered. |
| `accent` | `string` | – | Any CSS color for the moving query, lit routes, the TTL ring and the scrubber. Defaults to the theme accent. |
| `controls` | `boolean` | `true` | Shows the step scrubber with a pause button. Each step is a button that jumps to that stage; arrow keys move between them. |
| `caption` | `boolean` | `true` | Shows the current stage title and one line that narrates it under the scrubber. |
| `label` | `string` | – | Accessible description. Defaults to a sentence built from the domain, the servers, the address and the TTL. |
| `className` | `string` | – | Class on the root figure. |
| `style` | `CSSProperties` | – | Inline styles on the root figure. |

### Accessibility

- The drawing is role="img" with an aria-label that tells the whole story: the chain of servers, the address, the connection time and that the next lookup comes from the cache. Pass label to write your own.
- The labels, moving record chips and hover tags inside the drawing are part of that image, and the narrated caption is hidden from assistive technology, so screen readers hear one stable description instead of a changing loop.
- The scrubber is a group of real buttons named Step 1 of 6 and so on; the current step carries aria-current="step", arrow keys, Home and End move between steps, and the pause button reports its state with aria-pressed.
- Status is never color alone: every status chip pairs its dot with words such as Resolving, Try .dev, Cache hit or Connected in 84 ms.

### Motion

- One requestAnimationFrame loop writes SVG attributes, transforms, opacity and text directly, and only when a value changed; React never re-renders per frame.
- Packets travel along real quadratic arcs at an even pace (arc length lookup) with a sine ease, a short lit trail and a shadow that slides along the floor and shrinks as the packet rises, which gives the 2.5D depth.
- Every frame is a pure function of one clock, so the counters, statuses, TTL ring and scrubber stay in sync, jumps land exactly, and the loop joins seamlessly when the cached record expires and the scene fades back to its start.
- Pausing, speed changes and the gentle hover slowdown ease on a critically damped spring. The loop stops offscreen and in a hidden tab and resumes where it left off.
- With reduced motion there is no travel or loop: the stage shows a settled frame of the cached state, and the scrubber switches between settled frames of each stage.

### Responsive behavior

- The drawing is one SVG with a viewBox and non-scaling one pixel strokes. At 640px and wider it uses a landscape stage; below that a portrait stage with the servers in a column beside the browser and resolver.
- Labels, status chips, the cached record and the moving record chip are HTML placed by percentage, so text stays at its real size at every width.
- Container queries hide the step names on phones (the caption names the current step) and the meta lines in the narrowest landscape range. Scrubber buttons keep a tall touch target.

### Performance

- About a hundred small SVG nodes. Each frame writes only values that changed, and nothing runs offscreen or in a background tab.
- Geometry and arc length tables are built once per layout; resizing only rescales the moving record chip.
- No canvas, images, filters or blur.

### Notes for AI

- Use it as an explanatory figure on a landing page, a docs page or a blog post about DNS, custom domains, resolvers, TTLs or caching.
- Keep the domain and address realistic but fictional; 203.0.113.0/24 is reserved for documentation. The lookup is a simulation and takes no live data.
- Only add a brand mark where it is true to the story, such as a public resolver. Brands are sample content, never an endorsement.

### Related

- [Data flow](https://uiarc.dev/components/data-flow/markdown): Data flow illustration. Sources (app, database, events) are on the left, a processing core with a live count sits in the middle, and destinations (warehouse, dashboard, alerts) are on the right. Records leave as hollow dots and travel curved paths. In the core they turn into solid accent squares, then fan out to each destination; alerts receives about every third record.

### Also in illustrations

- [Payment flow](https://uiarc.dev/components/payment-flow/markdown): A card tap goes to a processor, then the network, then the bank and back with authorization, then settlement; each hop lights up with a status label and the amount travels as a chip.
- [Model training](https://uiarc.dev/components/model-training/markdown): Training data batches feed a small neural net diagram whose connections strengthen, a loss curve descends beside it, and an evaluation check turns green at the end.
- [Multi-region failover](https://uiarc.dev/components/multi-region-failover/markdown): Animated multi-region failover on a 2.5D stage: users stream requests through a global load balancer to two regions; the primary degrades, fails three health checks, traffic shifts smoothly to the healthy region, then it recovers, passes three checks and traffic ramps back to an even split.
- [Vector search](https://uiarc.dev/components/vector-search/markdown): Documents drop onto a tilted embedding plane and fold into points that cluster by topic; the index links neighbours, a query is typed, embedded and lowered onto the plane, a signal hops along the graph toward it, and a widening ring lights the nearest documents with connecting lines, similarity scores and a ranked list.
- [Branch graph](https://uiarc.dev/components/branch-graph/markdown): A git commit graph where branches draw in as colored lanes, merge commits join lines, a rebase lifts commits and replays them onto main, a squash folds them into one, and hovering a commit shows its message, author and diff stats.
- [Agent loop](https://uiarc.dev/components/agent-loop/markdown): An illustration of the agent loop: gather context, take action, verify, repeat, with a bright head circling three stations around the model.
- [Mixture of experts](https://uiarc.dev/components/mixture-of-experts/markdown): An illustration of mixture of experts routing: each token is scored by a router, travels to its top experts, and their outputs merge into the token's result.
- [Speculative decoding](https://uiarc.dev/components/speculative-decoding/markdown): An illustration of speculative decoding: a fast draft model guesses a few tokens, the target model checks them in one pass, and accepted guesses join the answer.
- [Prompt cache](https://uiarc.dev/components/prompt-cache/markdown): An animated explainer for prompt caching: the shared prefix of each request is cached once, later requests read it back, and the cost and time saved add up.
- [Reasoning tree](https://uiarc.dev/components/reasoning-tree/markdown): An illustration of tree search over thoughts: candidates are scored, weak branches fade, the best expand, and the winning path from question to answer draws in.

### Guidance for AI tools

DNS resolution: A browser asks for a domain and the query hops from the resolver to a root server, the TLD server and the authoritative nameserver, each pointing to the next, until an IP address comes back and the page connects. The resolver keeps the answer with a TTL ring that drains, and a second lookup is answered straight from that cache in one short hop. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Model training

> Training data batches feed a small neural net diagram whose connections strengthen, a loss curve descends beside it, and an evaluation check turns green at the end.

- Type: Component (special)
- Access: Arc Pro
- Page: https://uiarc.dev/components/model-training
- Markdown: https://uiarc.dev/components/model-training/markdown
- Source file: `registry/components/model-training/model-training.tsx`
- Dependencies: lucide-react
- Keywords: special, motion, illustration, new, model training, machine learning, neural network, deep learning, backpropagation, loss curve, epochs, evaluation, fine-tuning, ai, animated diagram

### When to use

- An AI or ML product section that explains training, fine-tuning or evaluation in one glance.
- Docs pages introducing batches, epochs, loss curves or held-out evaluation.

### When not to use

- Use line-chart or metric-card for real, live training metrics.
- Use data-flow to explain how records move through a pipeline, and pipeline-status for real job status.

### Installation

Model training is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/model-training
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { ModelTraining } from "@/components/arc/model-training/model-training";

export function TrainingSection() {
  return <ModelTraining
    classes={["Positive", "Negative"]}
    samples={12800}
    heldOutSamples={1600}
    epochs={12}
    lossFrom={0.69}
    lossTo={0.08}
    accuracy={94.2}
    target={90}
  />;
}
```

### API reference

#### ModelTraining

An animated model training illustration told in five stages. A batch peels off a layered stack of training data and drops into the input layer of a small neural network drawn on thin plates in 2.5D depth. Signals travel forward along every connection to a prediction, then the error travels back as a short dash and each connection it passes grows a little stronger. Over the epochs batches stream through, the useful connections thicken and take on the accent while the rest stay light, the loss curve descends beside the network and the loss, epoch and prediction readouts count in sync. At the end a held-out set runs through once, the evaluation score counts up, and the check turns green with a Passed tag. A step bar with play and pause replays the story or jumps to any stage, and a caption explains the current stage.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `classes` | `string[]` | `["Positive", "Negative"]` | The two labels the model learns to predict, shown beside the output layer with a probability and a bar. |
| `inputs` | `number` | `3` | Units in the input layer, from 2 to 5. Each data sheet shows one line per input feature. |
| `hidden` | `number[]` | `[4, 4]` | Units in the two hidden layers, each from 2 to 6. |
| `samples` | `number` | `12800` | Samples in the training set, shown under the stack and in its hover detail. |
| `heldOutSamples` | `number` | `1600` | Samples in the held-out set. |
| `batchSize` | `number` | `32` | Samples per batch, used in the caption and hover detail. |
| `epochs` | `number` | `12` | Epochs the story trains for. The epoch readout and the chart axis count to it. |
| `lossFrom` | `number` | `0.69` | Loss after the first batch. The curve starts here. |
| `lossTo` | `number` | `0.08` | Loss after the last epoch. The curve ends here and the validation point sits just above it. |
| `accuracy` | `number` | `94.2` | Accuracy on the held-out set in percent. The evaluation counts up to it. |
| `target` | `number` | `90` | Accuracy the evaluation must reach, shown under the evaluation name. |
| `labels` | `{ training?: string; heldOut?: string; unit?: string; input?: string; hidden?: string; output?: string; loss?: string; epoch?: string; evaluation?: string; waiting?: string; running?: string; passed?: string; noBatch?: string }` | `Training set, Held-out set, reviews, Input, Hidden, Output, Loss, Epoch, Evaluation, Waiting, Running, Passed, Waiting for a batch` | Names on the diagram and readouts. unit is what one sample is and follows every sample count. |
| `steps` | `string[]` | `["Batch", "Forward pass", "Backprop", "Epochs", "Evaluate"]` | Labels for the five stages in the step bar. |
| `defaultStep` | `number` | – | Stage to start on, from 0 to 4. When held or with reduced motion it picks the still frame; otherwise the finished, evaluated model is shown. |
| `caption` | `boolean` | `true` | Shows a sentence under the step bar that explains the current stage. On narrow layouts it also names the stage. |
| `controls` | `boolean` | `true` | Shows the step bar with play and pause. |
| `speed` | `number` | `1` | Multiplies the playback speed. One full run takes about 21 seconds at 1. 0 holds still. |
| `paused` | `boolean` | `false` | Holds the illustration still. Held from the start, it shows the finished, evaluated model. |
| `accent` | `string` | – | Any CSS color for signals, the error dash, learned connections, the loss curve and the active stage. Defaults to the accent token. The passed state keeps the success color. |
| `label` | `string` | – | Accessible description of the diagram. Built from the classes and numbers when left out. |
| `className` | `string` | – | Extra class on the root figure. |
| `style` | `CSSProperties` | – | Inline styles on the root figure. |

### Accessibility

- The diagram is one element with role="img" and an aria-label that walks through the whole run: batches, the forward pass, backprop strengthening the connections, the loss falling over the epochs, and the held-out evaluation passing its target.
- The step bar is an ordered list of real buttons named "Stage 3, Backprop" with aria-current on the playing stage, and a play and pause button with a specific name. The caption repeats the story in words.
- Nothing relies on color alone: every readout is a number, the evaluation shows Waiting, Running or Passed as a named tag next to the score, and the winning prediction is a probability.
- Pointer focus draws no ring; keyboard focus shows Arc's shared focus ring.

### Motion

- One rAF loop writes SVG transforms, opacity, dash offsets, widths, CSS variables and a few text nodes straight to the DOM, and only when a value changed; React does not render per frame.
- The whole run is a pure function of time, so the loop is seamless: at the start of each run the connections relax back to their random starting weights while the readouts crossfade from the finished run to an untrained model.
- Batches fly from the stack into the input layer on an eased curve while the stack advances one slot, signals ride each connection with a smooth ease and fade at both ends, and the error travels back as a short dash. Nodes fill as a signal lands and ring as the error passes.
- Each backward pass strengthens the connections it crossed, so weights, the loss curve, the epoch count and the output probabilities all step together, with the loss head gliding along the curve during each update.
- Hover slows the story on a critically damped spring. The loop stops off screen, in hidden tabs, and when paused. Reduced motion shows the finished run as a still frame: learned connections, the full loss curve with its validation point, and the passed evaluation. Picking a stage then shows that stage's still frame.

### Responsive behavior

- The network is measured in real pixels and drawn in an SVG viewBox of that size, so text and hairlines stay crisp at any width.
- Above 720px the loss readout sits beside the network; below it moves under. Below 480px the two data stacks move above the network and batches drop into it, the output probabilities stack under their labels, and the step bar shows numbers while the caption names the stage.
- Hover details only appear for a mouse; touch shows the same diagram without them.

### Performance

- About 150 small SVG elements for the default 3, 4, 4, 2 network, driven by a single loop that caches every written value.
- Geometry and weights are computed once per width; nothing is measured per frame.

### Notes for AI

- Use it to explain how a model learns on a landing page or in docs: training data, forward and backward passes, epochs, loss and evaluation.
- Match classes, unit and the numbers to the product's real task, such as spam and not spam for emails. Keep class names to one word so they fit beside the output layer on phones.
- The numbers are illustrative. Say so near the illustration if they could be read as a real benchmark.

### Related

- [Data flow](https://uiarc.dev/components/data-flow/markdown): Data flow illustration. Sources (app, database, events) are on the left, a processing core with a live count sits in the middle, and destinations (warehouse, dashboard, alerts) are on the right. Records leave as hollow dots and travel curved paths. In the core they turn into solid accent squares, then fan out to each destination; alerts receives about every third record.

### Also in illustrations

- [Payment flow](https://uiarc.dev/components/payment-flow/markdown): A card tap goes to a processor, then the network, then the bank and back with authorization, then settlement; each hop lights up with a status label and the amount travels as a chip.
- [DNS resolution](https://uiarc.dev/components/dns-resolution/markdown): A browser asks for a domain and the query hops from the resolver to a root server, the TLD server and the authoritative nameserver, each pointing to the next, until an IP address comes back and the page connects. The resolver keeps the answer with a TTL ring that drains, and a second lookup is answered straight from that cache in one short hop.
- [Multi-region failover](https://uiarc.dev/components/multi-region-failover/markdown): Animated multi-region failover on a 2.5D stage: users stream requests through a global load balancer to two regions; the primary degrades, fails three health checks, traffic shifts smoothly to the healthy region, then it recovers, passes three checks and traffic ramps back to an even split.
- [Vector search](https://uiarc.dev/components/vector-search/markdown): Documents drop onto a tilted embedding plane and fold into points that cluster by topic; the index links neighbours, a query is typed, embedded and lowered onto the plane, a signal hops along the graph toward it, and a widening ring lights the nearest documents with connecting lines, similarity scores and a ranked list.
- [Branch graph](https://uiarc.dev/components/branch-graph/markdown): A git commit graph where branches draw in as colored lanes, merge commits join lines, a rebase lifts commits and replays them onto main, a squash folds them into one, and hovering a commit shows its message, author and diff stats.
- [Agent loop](https://uiarc.dev/components/agent-loop/markdown): An illustration of the agent loop: gather context, take action, verify, repeat, with a bright head circling three stations around the model.
- [Mixture of experts](https://uiarc.dev/components/mixture-of-experts/markdown): An illustration of mixture of experts routing: each token is scored by a router, travels to its top experts, and their outputs merge into the token's result.
- [Speculative decoding](https://uiarc.dev/components/speculative-decoding/markdown): An illustration of speculative decoding: a fast draft model guesses a few tokens, the target model checks them in one pass, and accepted guesses join the answer.
- [Prompt cache](https://uiarc.dev/components/prompt-cache/markdown): An animated explainer for prompt caching: the shared prefix of each request is cached once, later requests read it back, and the cost and time saved add up.
- [Reasoning tree](https://uiarc.dev/components/reasoning-tree/markdown): An illustration of tree search over thoughts: candidates are scored, weak branches fade, the best expand, and the winning path from question to answer draws in.

### Guidance for AI tools

Model training: Training data batches feed a small neural net diagram whose connections strengthen, a loss curve descends beside it, and an evaluation check turns green at the end. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Multi-region failover

> Animated multi-region failover on a 2.5D stage: users stream requests through a global load balancer to two regions; the primary degrades, fails three health checks, traffic shifts smoothly to the healthy region, then it recovers, passes three checks and traffic ramps back to an even split.

- Type: Component (special)
- Access: Arc Pro
- Page: https://uiarc.dev/components/multi-region-failover
- Markdown: https://uiarc.dev/components/multi-region-failover/markdown
- Source file: `registry/components/multi-region-failover/multi-region-failover.tsx`
- Dependencies: motion, lucide-react
- Keywords: special, motion, illustration, new, failover, multi-region, region, high availability, disaster recovery, load balancer, global load balancing, dns failover, health check, traffic shift, weights, rebalance, outage, isometric, animated diagram, landing page, docs

### When to use

- A reliability, infrastructure or pricing page that needs to show why running in two regions keeps a service up during an outage.
- Docs for health checks, failover policies, traffic weights or slow start, where viewers should step through detection, failover, recovery and rebalance.
- Incident write-ups and postmortems that explain how traffic moved during a regional outage.

### When not to use

- Use database-replication to show a primary database failing over to a replica.
- Use circuit-breaker for one service failing fast against a failing dependency.
- Use autoscale for instances added and removed with load in one place.
- Use a real status or monitoring component to report actual region health.

### Installation

Multi-region failover is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/multi-region-failover
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { MultiRegionFailover } from "@/components/arc/multi-region-failover/multi-region-failover";

export function FailoverSection() {
  return (
    <MultiRegionFailover
      hostname="api.acme.dev"
      requestsPerSecond={12000}
      nodes={{
        primary: { label: "US East", meta: "us-east-1" },
        secondary: { label: "EU West", meta: "eu-west-1" },
      }}
    />
  );
}
```

### API reference

#### MultiRegionFailover

An animated multi-region failover on a layered 2.5D stage. Users send a steady stream of requests to a global load balancer that splits them between two regions, each a platform of six instances. The instances in the primary region fail one by one, requests there turn into errors and three health checks fail in a row, so the balancer marks the region unhealthy and shifts its weight smoothly to the healthy region. The primary recovers, has to pass three checks, and traffic ramps back until the split is even again. A step scrubber replays the story or jumps to any stage, and the weight bar, the dial on the balancer, error rate, requests per second, latency and status chips all update in sync.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `hostname` | `string` | `"api.acme.dev"` | The hostname the balancer answers for, shown under it and in the default description. |
| `requestsPerSecond` | `number` | `12000` | Total requests per second from users. Each region's counter shows its share of it. |
| `latencyMs` | `number` | `38` | Median latency of the primary region while the split is even. The secondary runs 4 ms slower and climbs as it takes the whole load. |
| `nodes` | `Partial<Record<"users" \| "balancer" \| "primary" \| "secondary", { label?: string; meta?: string; detail?: string; icon?: string \| ReactNode; color?: string }>>` | `Users, Load balancer, US East (us-east-1), EU West (eu-west-1)` | Overrides per node: the name, a meta line, the hover detail and an optional mark (Simple Icons path data, an image URL or a ReactNode). The region names also label the weight split and the captions. |
| `speed` | `number` | `1` | Multiplies the pace. One outage and recovery cycle takes 21 seconds at 1. 0 holds still. |
| `paused` | `boolean` | `false` | Holds the animation, easing to rest. Paused from the start, it shows the moment traffic shifts away from the unhealthy region. |
| `accent` | `string` | – | Any CSS color for the requests, lit routes, the weight dial, the split bar and the scrubber. Defaults to the theme accent. Errors and health always use the status colors. |
| `controls` | `boolean` | `true` | Shows the step scrubber with a pause button. Each step is a button that jumps to that stage; arrow keys move between them. |
| `caption` | `boolean` | `true` | Shows the current stage title and one line that narrates it under the scrubber. |
| `label` | `string` | – | Accessible description. Defaults to a sentence built from the hostname and the region names. |
| `className` | `string` | – | Class on the root figure. |
| `style` | `CSSProperties` | – | Inline styles on the root figure. |

### Accessibility

- The drawing is role="img" with an aria-label that tells the whole story: the split, the failing region, the failed checks, the shift to the healthy region and the gradual return. Pass label to write your own.
- Labels, counters, the moving health check chip and hover tags inside the drawing are part of that image, and the narrated caption is hidden from assistive technology, so screen readers hear one stable description instead of a changing loop.
- The scrubber is a group of real buttons named Step 1 of 6 and so on; the current step carries aria-current="step", arrow keys, Home and End move between steps, and the pause button reports its state with aria-pressed.
- Status is never color alone: every chip pairs its dot with words such as Failed checks 2/3, Out of rotation, Warming up 62% or Errors 27.3%, and failing instances also change their outline.

### Motion

- One requestAnimationFrame loop writes SVG attributes, transforms, opacity and text directly, and only when a value changed; React never re-renders per frame.
- Requests are a deterministic stream: each one is routed by the balancer weight at the moment it reaches the balancer and lands on a specific instance, which flashes. Requests to a down instance stall, turn to errors and fade.
- Requests travel along real arcs at an even pace with a glide ease, so they gather at the balancer and fan out, with a shadow that slides along the floor and shrinks as they rise, which gives the 2.5D depth.
- Every frame is a pure function of one clock, so the weights, counters, checks, statuses and scrubber stay in sync, jumps land exactly, and the loop is seamless because the last frame is the balanced first frame.
- Pausing, speed changes and the gentle hover slowdown ease on a critically damped spring. The loop stops offscreen and in a hidden tab and resumes where it left off.
- With reduced motion there is no travel or loop: the stage shows a settled frame of the failover, and the scrubber switches between settled frames of each stage.

### Responsive behavior

- The drawing is one SVG with a viewBox and non-scaling one pixel strokes. At 640px and wider it uses a landscape stage with the regions stacked on the right; below that a portrait stage with users on top, the balancer in the middle and the two regions side by side.
- Labels, status chips, counters, the weight split and the moving health check chip are HTML placed by percentage, so text stays at its real size at every width.
- Container queries hide the step names on phones (the caption names the current step) and the meta lines in the narrowest landscape range. Scrubber buttons keep a tall touch target.

### Performance

- About 130 small SVG nodes, with a fixed pool of 15 request dots reused across the stream. Each frame writes only values that changed, and nothing runs offscreen or in a background tab.
- Geometry and arc length tables are built once per layout; resizing only rescales the moving health check chip.
- No canvas, images, filters or blur.

### Notes for AI

- Use it as an explanatory figure on a landing page, a docs page or a blog post about high availability, disaster recovery, global load balancing, DNS failover or health checks.
- Keep region names and codes realistic. The outage, traffic and timings are a simulation and take no live data.
- Only add a brand mark where it is true to the story, such as the load balancer provider. Brands are sample content, never an endorsement.

### Related

- [DNS resolution](https://uiarc.dev/components/dns-resolution/markdown): A browser asks for a domain and the query hops from the resolver to a root server, the TLD server and the authoritative nameserver, each pointing to the next, until an IP address comes back and the page connects. The resolver keeps the answer with a TTL ring that drains, and a second lookup is answered straight from that cache in one short hop.

### Also in illustrations

- [Data flow](https://uiarc.dev/components/data-flow/markdown): Data flow illustration. Sources (app, database, events) are on the left, a processing core with a live count sits in the middle, and destinations (warehouse, dashboard, alerts) are on the right. Records leave as hollow dots and travel curved paths. In the core they turn into solid accent squares, then fan out to each destination; alerts receives about every third record.
- [Payment flow](https://uiarc.dev/components/payment-flow/markdown): A card tap goes to a processor, then the network, then the bank and back with authorization, then settlement; each hop lights up with a status label and the amount travels as a chip.
- [Model training](https://uiarc.dev/components/model-training/markdown): Training data batches feed a small neural net diagram whose connections strengthen, a loss curve descends beside it, and an evaluation check turns green at the end.
- [Vector search](https://uiarc.dev/components/vector-search/markdown): Documents drop onto a tilted embedding plane and fold into points that cluster by topic; the index links neighbours, a query is typed, embedded and lowered onto the plane, a signal hops along the graph toward it, and a widening ring lights the nearest documents with connecting lines, similarity scores and a ranked list.
- [Branch graph](https://uiarc.dev/components/branch-graph/markdown): A git commit graph where branches draw in as colored lanes, merge commits join lines, a rebase lifts commits and replays them onto main, a squash folds them into one, and hovering a commit shows its message, author and diff stats.
- [Agent loop](https://uiarc.dev/components/agent-loop/markdown): An illustration of the agent loop: gather context, take action, verify, repeat, with a bright head circling three stations around the model.
- [Mixture of experts](https://uiarc.dev/components/mixture-of-experts/markdown): An illustration of mixture of experts routing: each token is scored by a router, travels to its top experts, and their outputs merge into the token's result.
- [Speculative decoding](https://uiarc.dev/components/speculative-decoding/markdown): An illustration of speculative decoding: a fast draft model guesses a few tokens, the target model checks them in one pass, and accepted guesses join the answer.
- [Prompt cache](https://uiarc.dev/components/prompt-cache/markdown): An animated explainer for prompt caching: the shared prefix of each request is cached once, later requests read it back, and the cost and time saved add up.
- [Reasoning tree](https://uiarc.dev/components/reasoning-tree/markdown): An illustration of tree search over thoughts: candidates are scored, weak branches fade, the best expand, and the winning path from question to answer draws in.

### Guidance for AI tools

Multi-region failover: Animated multi-region failover on a 2.5D stage: users stream requests through a global load balancer to two regions; the primary degrades, fails three health checks, traffic shifts smoothly to the healthy region, then it recovers, passes three checks and traffic ramps back to an even split. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Vector search

> Documents drop onto a tilted embedding plane and fold into points that cluster by topic; the index links neighbours, a query is typed, embedded and lowered onto the plane, a signal hops along the graph toward it, and a widening ring lights the nearest documents with connecting lines, similarity scores and a ranked list.

- Type: Component (special)
- Access: Arc Pro
- Page: https://uiarc.dev/components/vector-search
- Markdown: https://uiarc.dev/components/vector-search/markdown
- Source file: `registry/components/vector-search/vector-search.tsx`
- Dependencies: motion, lucide-react
- Keywords: special, motion, illustration, new, vector search, embeddings, semantic search, nearest neighbours, similarity, rag, retrieval, vector database, hnsw, animated diagram

### When to use

- A feature section on semantic search, AI answers, or retrieval over a team's docs.
- Docs pages introducing embeddings, nearest neighbour search, or approximate indexes.

### When not to use

- Use search-index to explain keyword search with an inverted index.
- Use a real scatter or cluster chart to show an actual embedding projection.

### Installation

Vector search is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/vector-search
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { VectorSearch } from "@/components/arc/vector-search/vector-search";

export function RetrievalSection() {
  return <VectorSearch
    topics={[{ name: "Billing" }, { name: "Access" }, { name: "Deploys" }]}
    documents={[
      { title: "Refund a charge", topic: 0 },
      { title: "Update a card on file", topic: 0 },
      { title: "Download invoices", topic: 0 },
      { title: "Rotate an API key", topic: 1 },
      { title: "Scope API tokens", topic: 1 },
      { title: "Revoke a session", topic: 1 },
      { title: "Roll back a deploy", topic: 2 },
      { title: "Preview environments", topic: 2 },
      { title: "Add a custom domain", topic: 2 },
    ]}
    query="How do I rotate a leaked API key?"
    k={3}
  />;
}
```

### API reference

#### VectorSearch

An animated vector search illustration. Documents drop onto a tilted embedding plane as small pages and fold into points in their topic color, while a readout beside the plane shows each one's title and vector. Similar documents land close together, so dashed clusters fade up around each topic and the index links every point to its nearest neighbours. Then the query is typed, embedded (its vector replaces the document's in the readout), and lowered onto the plane on a thin stem. A search signal enters the graph at the farthest point and hops along real links toward the query, lighting its path, before a ring widens from the query: each match it reaches gets a halo, a line to the query, and a similarity score, and fills a ranked list with the source of each document. Counters for embedded documents, links, and hops update in sync, and a step bar with play and pause replays or jumps between stages.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `documents` | `{ title: string; topic: number; source?: { name: string; icon?: string \| ReactNode; color?: string }; x?: number; y?: number }[]` | `18 help articles across Billing, Access, and Deploys` | Documents in the index, 6 to 24. topic indexes into topics. source is shown beside a match in the results: icon is Simple Icons path data (painted in color, or the text color when color is left out), an image URL for a full color logo, or a ReactNode. x and y place the point on the plane from -1 to 1; left out, points spiral around their topic's center. |
| `topics` | `{ name: string; color?: string }[]` | `Billing, Access, Deploys` | Topics the documents cluster by, two to four. Each gets a region of the plane, a dashed cluster, and a name chip. color overrides the chart series color. |
| `query` | `string` | `"How do I rotate a leaked API key?"` | The search query, typed into the readout before it is embedded. |
| `queryAt` | `{ x: number; y: number }` | – | Where the query lands on the plane, from -1 to 1. Defaults to beside the first document of the second topic. |
| `k` | `number` | `3` | How many nearest documents are returned, from 1 to 5. |
| `dimensions` | `number` | `1536` | Embedding size shown in the readout heading. |
| `labels` | `{ embed?; index?; query?; rank?; embedded?; links?; hops?; embedding?; queryHeading?; results?; queryChip? }` | `Embed, Index, Query, Rank, Embedded, Links, Hops, Embedding, Query, Nearest documents, Query` | Stage names in the step bar, the three counter names, the readout headings, the results heading, and the chip on the falling query. |
| `speed` | `number` | `1` | Multiplies the pace. At 1 the whole story takes about 18 seconds. 0 holds still. |
| `paused` | `boolean` | `false` | Holds the diagram still where it is, easing to rest instead of stopping in one frame. |
| `controls` | `boolean` | `true` | Shows the step bar with play and pause above the diagram. |
| `accent` | `string` | – | Color of the query, the search path and signal, the ring, the match lines, and the score bars. Defaults to the accent token. |
| `label` | `string` | – | Accessible description of the diagram. Built from the topics, the query, the hop count, and the real matches with their scores when left out. |
| `caption` | `ReactNode` | – | Optional visible caption under the diagram, rendered as a figcaption. |
| `className` | `string` | – | Extra class on the root figure. |
| `style` | `CSSProperties` | – | Inline styles on the root figure. |

### Accessibility

- The plane and its legend form one element with role="img" and an aria-label that explains the idea with the real values: how many documents cluster into which topics, the query, how many hops the search takes, and each match with its similarity score.
- The step bar is a group of real buttons named for each stage, with aria-current on the playing stage, plus a named play and pause button.
- Nothing relies on color alone: clusters carry name chips, matches are written out as a ranked list with titles, sources, and scores, and the counters are plain numbers.
- Points are not controls, so nothing else enters the tab order; hover tags only repeat the title, topic, and source that the list and label already give.
- Pointer focus draws no ring; keyboard focus shows Arc's shared focus ring.

### Motion

- One rAF loop writes SVG transforms, opacity, dash lengths, and a few text nodes straight to the DOM, and only when a value changed; React does not render per frame.
- The whole story is a pure function of time, so the loop repeats seamlessly: pages fall and fold into points, clusters and links draw in, the query is typed and lowered, the signal hops, the ring finds the matches, and the plane clears.
- The signal hops along the real shortest route through the index graph, and each hop's duration scales with the link's length, so the pace stays even. Hops arc slightly above the plane.
- The ring widens on an eased curve, and each match lights at the exact moment the ring reaches it; the time is solved from the curve, so halo, line, score chip, and ranked row stay in sync.
- Speed changes, pausing, and hover (which slows the story a little) ease on a critically damped spring. Readout bars and result bars ease with the standard and considered durations.
- The loop stops off screen, in hidden tabs, and when paused. Reduced motion shows the answer as a still frame: every point placed, the path walked, the matches linked and scored; the step bar still jumps between still frames of each stage.

### Responsive behavior

- The plane is measured in real pixels and drawn in an SVG viewBox of that size, so hairlines and text stay crisp at any width.
- From 720px of container width the legend sits beside the plane; below it the legend drops under the plane. The story is the same.
- Cluster names sit above clusters at the back and below clusters at the sides, and score chips sit on the side of each match facing away from the query, so labels stay apart even at 390px.
- Hover tags only appear for a mouse; touch shows the same diagram without them.

### Performance

- About 150 small SVG and HTML elements, driven by a single loop that caches every written value.
- Positions, the index graph, the search route, and every timing are computed once per layout; nothing is measured per frame.

### Notes for AI

- Use it to explain semantic search, embeddings, RAG retrieval, or a vector database on a landing page or in docs.
- Keep titles short, like help center article names. Three topics with five or six documents each read best.
- Rankings and scores are computed from the positions on the plane, so they always match the picture. To make a specific document the top match, list it first in its topic or pass queryAt near it.
- Sources are sample content: use real brand marks only for the tools the documents actually come from.

### Related

- [Model training](https://uiarc.dev/components/model-training/markdown): Training data batches feed a small neural net diagram whose connections strengthen, a loss curve descends beside it, and an evaluation check turns green at the end.
- [Data flow](https://uiarc.dev/components/data-flow/markdown): Data flow illustration. Sources (app, database, events) are on the left, a processing core with a live count sits in the middle, and destinations (warehouse, dashboard, alerts) are on the right. Records leave as hollow dots and travel curved paths. In the core they turn into solid accent squares, then fan out to each destination; alerts receives about every third record.

### Also in illustrations

- [Payment flow](https://uiarc.dev/components/payment-flow/markdown): A card tap goes to a processor, then the network, then the bank and back with authorization, then settlement; each hop lights up with a status label and the amount travels as a chip.
- [DNS resolution](https://uiarc.dev/components/dns-resolution/markdown): A browser asks for a domain and the query hops from the resolver to a root server, the TLD server and the authoritative nameserver, each pointing to the next, until an IP address comes back and the page connects. The resolver keeps the answer with a TTL ring that drains, and a second lookup is answered straight from that cache in one short hop.
- [Multi-region failover](https://uiarc.dev/components/multi-region-failover/markdown): Animated multi-region failover on a 2.5D stage: users stream requests through a global load balancer to two regions; the primary degrades, fails three health checks, traffic shifts smoothly to the healthy region, then it recovers, passes three checks and traffic ramps back to an even split.
- [Branch graph](https://uiarc.dev/components/branch-graph/markdown): A git commit graph where branches draw in as colored lanes, merge commits join lines, a rebase lifts commits and replays them onto main, a squash folds them into one, and hovering a commit shows its message, author and diff stats.
- [Agent loop](https://uiarc.dev/components/agent-loop/markdown): An illustration of the agent loop: gather context, take action, verify, repeat, with a bright head circling three stations around the model.
- [Mixture of experts](https://uiarc.dev/components/mixture-of-experts/markdown): An illustration of mixture of experts routing: each token is scored by a router, travels to its top experts, and their outputs merge into the token's result.
- [Speculative decoding](https://uiarc.dev/components/speculative-decoding/markdown): An illustration of speculative decoding: a fast draft model guesses a few tokens, the target model checks them in one pass, and accepted guesses join the answer.
- [Prompt cache](https://uiarc.dev/components/prompt-cache/markdown): An animated explainer for prompt caching: the shared prefix of each request is cached once, later requests read it back, and the cost and time saved add up.
- [Reasoning tree](https://uiarc.dev/components/reasoning-tree/markdown): An illustration of tree search over thoughts: candidates are scored, weak branches fade, the best expand, and the winning path from question to answer draws in.

### Guidance for AI tools

Vector search: Documents drop onto a tilted embedding plane and fold into points that cluster by topic; the index links neighbours, a query is typed, embedded and lowered onto the plane, a signal hops along the graph toward it, and a widening ring lights the nearest documents with connecting lines, similarity scores and a ranked list. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Branch graph

> A git commit graph where branches draw in as colored lanes, merge commits join lines, a rebase lifts commits and replays them onto main, a squash folds them into one, and hovering a commit shows its message, author and diff stats.

- Type: Component (special)
- Access: Arc Pro
- Page: https://uiarc.dev/components/branch-graph
- Markdown: https://uiarc.dev/components/branch-graph/markdown
- Source file: `registry/components/branch-graph/branch-graph.tsx`
- Dependencies: lucide-react
- Keywords: special, git, graph, developer, motion, new, commit graph, branch, merge, rebase, squash, pull request, history, version control, developer tools, diff stats

### When to use

- A merge strategy picker in a code review or pull request screen, showing exactly what main will look like afterwards.
- A commit history panel in a developer tool, with hover details and keyboard browsing.
- Docs and landing pages for version control or CI products that explain merge, rebase, and squash.

### When not to use

- Use git-branches for a looping, non-interactive illustration of a branch, pull request, and release.
- Use a timeline or changelog for releases people need to read rather than a commit graph.
- Use a virtualized table for long real histories; this graph is built for a focused slice of about five to fifteen commits.

### Installation

Branch graph is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/branch-graph
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { BranchGraph } from "@/components/arc/branch-graph/branch-graph";

const ada = { name: "Ada Park", avatar: "/people/ada.jpg" };

const commits = [
  { id: "c3", hash: "b81f2e0", message: "Rank results by recency", branch: "feat/search", parents: ["c2"], author: ada, date: "1 hour ago", additions: 64, deletions: 9, files: 3 },
  { id: "m2", hash: "4a0c9d1", message: "Upgrade to Node 22", branch: "main", parents: ["m1"], author: ada, date: "3 hours ago", additions: 8, deletions: 8, files: 2 },
  { id: "c2", hash: "e27d4b3", message: "Index docs on publish", branch: "feat/search", parents: ["m1"], author: ada, date: "Yesterday", additions: 210, deletions: 12, files: 7 },
  { id: "m1", hash: "93c5a07", message: "Launch docs site", branch: "main", parents: [], author: ada, date: "2 days ago", additions: 540, deletions: 0, files: 31 },
];

export function MergePreview() {
  return (
    <BranchGraph
      commits={commits}
      branches={[{ name: "main" }, { name: "feat/search" }]}
      pullRequest={{ number: 1207, title: "Instant search", branch: "feat/search" }}
      autoplay={false}
    />
  );
}
```

### API reference

#### BranchGraph

An interactive commit graph with a merge preview. Branches draw in as colored lanes from the oldest commit up, and merge commits join their lines with clean curves. A strategy control replays the pull request as a merge commit that joins both lines, a rebase that lifts the branch's commits like cards and replays them on top of the base branch with new hashes, or a squash that folds them into one commit. Hovering or arrowing to a commit shows its message, author, and diff stats, and dims every other branch.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `commits` | `{ id: string; hash: string; message: string; body?: string; branch: string; parents?: string[]; author: { name: string; avatar?: string }; date: string; additions?: number; deletions?: number; files?: number }[]` | `a checkout pull request with a merged fix` | Commits, newest first. parents lists parent ids; a second parent makes a merge commit. date is display text such as "2 hours ago", so server and client agree. |
| `branches` | `{ name: string; color?: string }[]` | `main, feat/checkout, fix/rounding` | Branches in lane order. The first is the base branch the pull request merges into. Colors default to the chart series palette; the first lane follows the accent. |
| `pullRequest` | `{ number: number; title: string; branch: string }` | `{ number: 482, title: "Checkout redesign", branch: "feat/checkout" }` | The pull request being previewed. Its branch's commits are the ones that merge, rebase, or squash; the title names the squashed commit. |
| `strategy` | `"open" \| "merge" \| "rebase" \| "squash"` | – | Controlled strategy. open is the history before merging. Pair with onStrategyChange. |
| `defaultStrategy` | `"open" \| "merge" \| "rebase" \| "squash"` | `"open"` | Starting strategy when uncontrolled. |
| `onStrategyChange` | `(strategy) => void` | – | Called when a strategy is picked. |
| `strategies` | `("open" \| "merge" \| "rebase" \| "squash")[]` | `all four` | Strategies offered in the control, in order. Pass one to hide the control. |
| `title` | `string` | `the pull request title` | Visible title with the pull request number. Pass an empty string to hide it. |
| `autoplay` | `boolean` | `true` | Cycles before, rebase, merge, and squash while nobody interacts. Hover holds it; the first pick, tap, or key press stops it for good. Only when uncontrolled. |
| `speed` | `number` | `1` | Multiplies the pace of every animation. 0 jumps straight to each state. |
| `paused` | `boolean` | `false` | Holds the autoplay where it is. Picks by the user still animate. |
| `accent` | `string` | – | Any CSS color for the base lane and hash rewrites. Defaults to the first chart series, which follows the accent. |
| `label` | `string` | – | Accessible name of the component. Built from the title and branch names when left out. |
| `className` | `string` | – | Class on the root element. |
| `style` | `CSSProperties` | – | Inline styles on the root element. |

### Accessibility

- The root is a labelled section. The strategy control is a radiogroup of real radio buttons with a roving tab stop; arrow keys, Home, and End pick a strategy.
- Commits form a listbox in visual order, newest first. Up and Down, Home, and End move through commits with aria-activedescendant; Escape closes the commit card. Each option is named with its message, hash, author, date, diff stats, and the branches that point to it.
- A polite live region announces the result of every strategy picked by the user, such as how many commits were replayed and that they got new hashes. Autoplay changes are not announced.
- The graph and the commit card are aria-hidden because the listbox carries the same information. Branch color is always paired with a named tag, merge commits carry an icon and a hollow dot, and additions and deletions carry + and − signs, so nothing relies on color alone.
- Pointer focus draws no ring; keyboard focus shows Arc's shared focus ring. The keyboard commit takes the hover fill and shows its card.

### Motion

- One rAF loop writes SVG path data, transforms, and opacity straight to the DOM and skips every value that did not change. React renders only when the strategy or the inspected commit changes.
- Edges are computed each frame from the live positions of their two commits, so lines stretch and bend with them. A branch bends near its parent and a merge bends near its child, like a real git client.
- The entrance draws each line up from the oldest commit at a constant pace, and every commit lands as its line reaches it.
- A rebase lifts the branch's rows into floating cards, carries them one after another along an eased arc into the base lane, and sets them down with a soft ring while their hashes rewrite in place. The old branch point retracts first and the new link to the base tip draws in after the commits land.
- A merge makes room at the top, then the merge commit lands and both lines draw into it. A squash flies the commits into one point where the squashed commit appears; undoing it replays them back out. Every transition starts from wherever things are, so picking a new strategy mid-flight never jumps.
- The loop runs only while something moves or autoplay is waiting, and stops off screen and in hidden tabs. With reduced motion the graph shows each state immediately with no entrance, flights, or autoplay.

### Responsive behavior

- The graph is drawn in real pixels in an SVG beside the rows, so hairlines and dots stay crisp at any width.
- Container queries drop the date below 720px, the author below 560px, and the hash below 400px; the full details stay in the hover card and each option's accessible name. The strategy control takes a full row on phones.
- On touch, a tap on a commit pins its card and a tap elsewhere closes it.

### Performance

- About sixty SVG and HTML elements are updated from one loop with a write cache, so a quiet frame touches nothing.
- Every layout is computed once per data set. Nothing is measured inside the loop.

### Notes for AI

- Use it where people choose how a pull request lands: a merge button, a code review tool, or docs that teach merge, rebase, and squash.
- Pass commits newest first with real parent ids. Keep the pull request branch to two to five commits and use two or three lanes; more lanes read as noise.
- Keep branch names short, like feat/search. The hover card holds the longer story in body.
- The merge, rebase, and squash states are previews computed from the data. Say so if the page could be read as the live state of a repository.

### Related

- [Timeline](https://uiarc.dev/components/timeline/markdown): Follow what happened, newest first, grouped by day.

### Also in illustrations

- [Data flow](https://uiarc.dev/components/data-flow/markdown): Data flow illustration. Sources (app, database, events) are on the left, a processing core with a live count sits in the middle, and destinations (warehouse, dashboard, alerts) are on the right. Records leave as hollow dots and travel curved paths. In the core they turn into solid accent squares, then fan out to each destination; alerts receives about every third record.
- [Payment flow](https://uiarc.dev/components/payment-flow/markdown): A card tap goes to a processor, then the network, then the bank and back with authorization, then settlement; each hop lights up with a status label and the amount travels as a chip.
- [DNS resolution](https://uiarc.dev/components/dns-resolution/markdown): A browser asks for a domain and the query hops from the resolver to a root server, the TLD server and the authoritative nameserver, each pointing to the next, until an IP address comes back and the page connects. The resolver keeps the answer with a TTL ring that drains, and a second lookup is answered straight from that cache in one short hop.
- [Model training](https://uiarc.dev/components/model-training/markdown): Training data batches feed a small neural net diagram whose connections strengthen, a loss curve descends beside it, and an evaluation check turns green at the end.
- [Multi-region failover](https://uiarc.dev/components/multi-region-failover/markdown): Animated multi-region failover on a 2.5D stage: users stream requests through a global load balancer to two regions; the primary degrades, fails three health checks, traffic shifts smoothly to the healthy region, then it recovers, passes three checks and traffic ramps back to an even split.
- [Vector search](https://uiarc.dev/components/vector-search/markdown): Documents drop onto a tilted embedding plane and fold into points that cluster by topic; the index links neighbours, a query is typed, embedded and lowered onto the plane, a signal hops along the graph toward it, and a widening ring lights the nearest documents with connecting lines, similarity scores and a ranked list.
- [Agent loop](https://uiarc.dev/components/agent-loop/markdown): An illustration of the agent loop: gather context, take action, verify, repeat, with a bright head circling three stations around the model.
- [Mixture of experts](https://uiarc.dev/components/mixture-of-experts/markdown): An illustration of mixture of experts routing: each token is scored by a router, travels to its top experts, and their outputs merge into the token's result.
- [Speculative decoding](https://uiarc.dev/components/speculative-decoding/markdown): An illustration of speculative decoding: a fast draft model guesses a few tokens, the target model checks them in one pass, and accepted guesses join the answer.
- [Prompt cache](https://uiarc.dev/components/prompt-cache/markdown): An animated explainer for prompt caching: the shared prefix of each request is cached once, later requests read it back, and the cost and time saved add up.
- [Reasoning tree](https://uiarc.dev/components/reasoning-tree/markdown): An illustration of tree search over thoughts: candidates are scored, weak branches fade, the best expand, and the winning path from question to answer draws in.

### Guidance for AI tools

Branch graph: A git commit graph where branches draw in as colored lanes, merge commits join lines, a rebase lifts commits and replays them onto main, a squash folds them into one, and hovering a commit shows its message, author and diff stats. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Agent loop

> An illustration of the agent loop: gather context, take action, verify, repeat, with a bright head circling three stations around the model.

- Type: Component (special)
- Access: Arc Pro
- Page: https://uiarc.dev/components/agent-loop
- Markdown: https://uiarc.dev/components/agent-loop/markdown
- Source file: `registry/components/agent-loop/agent-loop.tsx`
- Dependencies: motion, lucide-react, @radix-ui/react-tooltip
- Keywords: special, motion, illustration, new, agent loop, ai agent, tool use, tool calling, gather context, take action, verify, agentic loop, react loop, observe act, context window, claude, explainer, ai diagram

### When to use

- Docs, explainers and landing pages that teach how an AI agent works: it gathers context, calls tools, checks the result and repeats until the task is done.
- Showing why agents take several passes, with a failed check or a failed tool call that sends the loop round again.
- A visual summary of a finished agent run with the tools it used and the context it built up.

### When not to use

- Use agent-run or research-run to show a real agent's live steps and streamed output.
- Use tool-call for a single tool call card inside a chat or a log.
- Use reasoning-tree to explain search over thoughts rather than tool use.
- Use mcp-flow to explain how a host talks to MCP servers over a transport.
- Use context-window to show what fills a model's context and how close it is to the limit.

### Installation

Agent loop is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/agent-loop
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { AgentLoop } from "@/components/arc/agent-loop/agent-loop";
import { GithubMark, SlackColorMark } from "@/components/arc/agent-loop/agent-loop-marks";

export function DeployLoop() {
  return (
    <AgentLoop
      task="Fix the failing deploy on main and tell #releases."
      summary="The build cache was stale. Cleared it, the deploy passed and #releases knows."
      onDone={() => console.log("loop finished")}
      iterations={[
        {
          gather: { label: "Build log", detail: "Step 4 of 9 failed", tokens: 3200 },
          calls: [{ tool: "GitHub", mark: <GithubMark aria-hidden />, action: "Read workflow run", result: "Cache key mismatch" }],
          verify: { passed: false, note: "Fix not applied yet" },
        },
        {
          gather: { label: "Workflow file", detail: "deploy.yml, 84 lines", tokens: 1900, mark: <GithubMark aria-hidden /> },
          calls: [
            { tool: "GitHub", mark: <GithubMark aria-hidden />, action: "Clear cache and rerun", result: "Deploy passed in 3m 12s" },
            { tool: "Slack", mark: <SlackColorMark aria-hidden />, action: "Post update", result: "Posted in #releases" },
          ],
          verify: { passed: true, note: "Deploy green, team told" },
        },
      ]}
    />
  );
}
```

### API reference

#### AgentLoop

An illustration of the agent loop: gather context, take action, verify, repeat. A bright head with a soft gradient trail runs clockwise round a ring past three stations, with the model at the center. At Gather context a block joins the context stack beside the ring and the token count rolls up; at Take action a tool call with its real mark drops out of the ring on a short pin and resolves with a result (or an error); at Verify a check passes or leaves a retry note that sends the loop round again. A counter rolls with each loop, and the last one ends in a done state with the ring drawn in, a check at the center and the summary as the caption, or a stopped state when the last check fails. Play, pause, step, restart and speed drive it. The run, the tool calls and their results are sample data; nothing calls a real service.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `iterations` | `AgentLoopIteration[]` | `sample triage run (3 loops)` | The loops, in order. Each is { gather, calls, verify }: gather is the context block { label, detail?, tokens, mark? }, calls are one to three tool calls { tool, mark?, action, result, status? } shown one after another, and verify is { passed, note }. A failed check reads as a retry note; when the last one fails the run ends as stopped. An empty array shows the ring at rest with the controls off. |
| `task` | `string` | `"Find out why EU cards are declined at checkout, then update the team."` | The caption while the loop is ready or running. |
| `summary` | `string` | – | The caption once the loop ends. Defaults to a count of loops and tool calls, or a stopped note when the last check fails (the sample run has its own summary). |
| `model` | `{ name: string; mark?: ReactNode } \| null` | `Claude Opus 5.5 with the Claude mark` | The model at the center. Pass null to show only the loop counter. |
| `title` | `string` | `"Agent loop"` | Card title. |
| `stationLabels` | `Partial<Record<"gather" \| "act" \| "verify", string>>` | `Gather context, Take action, Verify` | Station names. Keep them to about two words; a longer name truncates beside its station. |
| `autoPlay` | `boolean` | `true` | Starts the loop the first time the card is mostly in view. Under reduced motion the card opens on its done state instead. |
| `loop` | `boolean` | `false` | Plays again about four seconds after the done state. |
| `speed` | `number` | – | Playback speed, controlled. At 1 the sample run takes about 18 seconds; 0 holds still. Pair it with onSpeedChange. |
| `defaultSpeed` | `number` | `1` | Starting speed when uncontrolled. The control offers 0.5, 1 and 2. |
| `onSpeedChange` | `(speed: number) => void` | – | Called when the speed control changes. |
| `controls` | `boolean` | `true` | Shows play and pause, step, restart and the speed control. |
| `onStationChange` | `(station: "gather" \| "act" \| "verify", iteration: number) => void` | – | Called when the head reaches a station, with the zero based loop. Fires once per beat, never per frame. |
| `onDone` | `() => void` | – | Called each time playback reaches the done state. |
| `className` | `string` | – | Class on the root element. |
| `style` | `CSSProperties` | – | Inline style on the root. Set --al-accent to recolor the head, trail, pins and active stations (defaults to --series-1). |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Tab | Moves through play or pause, next step, restart and the speed control. |
| Enter / Space | On play, pauses or resumes; on next step, plays to the next beat (a new context block, a tool result, a check or the end) and stops there; on restart, starts over from the ready state. |
| Arrow left / Arrow right | On the speed control, moves between 0.5×, 1× and 2×. |

### Accessibility

- The card is a labelled group. Station names, tool calls, results, checks and context blocks are real text, and the ring drawing itself (track, pins, head) is hidden from assistive technology.
- A polite status region speaks each beat when you step or pause (for example "GitHub returned: EU cards, since Oct 18"), and the summary at the end, but stays quiet while the loop plays on its own.
- Status never relies on color: ready, running, paused, done and stopped each pair an icon with a label; a tool result shows a check or a cross, a failed call says failed to screen readers, and a check shows a check icon with "Check passed" or a rotate icon with "Retry".
- The context list is an ordered list, read in the order blocks were gathered.
- When stepping reaches the end, Next step turns off and focus moves to Restart instead of falling back to the page.
- Pointer focus draws no ring; keyboard focus uses Arc's shared focus outline on every control.

### Motion

- The head eases from station to station round the ring and drags a soft gradient trail that stretches with its speed and shrinks to nothing when it lands, so it never sits still with a tail. Small chevrons on the track show the direction.
- The active station's node fills, a thin ring settles around it and its label carries a calm shimmer that stops with a clear solid state.
- A tool call drops out of the ring: the pin under Take action draws down in about 180ms, then the chip lands at its end with a 6px drop and a slight scale on a critically damped spring (no bounce), growing from the pin. Its spinner crossfades to a check or a cross as the result fades in. A second call crossfades into the same lane after the old one fades out in 80ms, so nothing reflows. Checks drop from Verify the same way.
- A new context block fades in at the end of the stack with a short drop while the token count rolls up in tabular numerals; the space for every block is reserved, so the card never grows.
- The loop counter rolls its digit up inside a fixed width. Labels such as the status and the caption swap with one short crossfade.
- At the end the ring draws in clockwise in about 760ms and the head fades out. A stopped run leaves the ring neutral.
- Reduced motion opens on the done state. Playing and stepping still work, with no travel and no trail: the head jumps between stations and each change applies in place.

### Responsive behavior

- From a 640px container the context stack sits in a column beside the ring, with the check and the tool call side by side in two lanes, each at the end of its station's pin.
- Narrower, the context stack moves under the ring (two columns between 460 and 640px) and one lane shows the latest tool call or check.
- The ring is laid out in real pixels from the measured width, so strokes and labels stay crisp at every size. Below a 360px ring column the labels drop their icons and shrink, and on the narrowest cards the two lower stations move further down the ring so their labels fit beside them, which holds down to 320px.
- The speed label hides below a 400px container and the controls wrap onto two lines on the narrowest phones.

### Performance

- The whole run is a pure timeline built once from the iterations, so pausing, stepping and replaying are exact.
- The head and the trail are written straight to the SVG from one requestAnimationFrame loop that runs only while playing or stepping; React renders once per beat, not per frame.
- The trail is one arc path with a gradient whose ends follow the tail and the head; everything else animates transform, opacity or a stroke dash.
- Autoplay waits until the card is in view.

### Notes for AI

- Use it to explain how a tool using agent works (gather context, act, verify, repeat), not to stream a real agent's output. Say in the surrounding copy that the run is illustrative.
- Write two to four iterations. Give each a short context label (one to three words), a detail under about 30 characters, a tool call action of two to four words and a result under about 30 characters, so nothing truncates in the context column or the chips. The context stack reserves a slot per iteration.
- Let the last iteration pass its check; earlier ones can fail with a retry note to show why the loop goes round again. Set status: "error" on a call to show a failed tool call followed by a retry in the same step.
- Copy brand marks from agent-loop-marks.tsx or pass any ReactNode with aria-hidden. Mono marks follow the text color; set style={{ color }} for a brand color. Brand marks are sample content, never an implied endorsement.
- The card is a single focused component about 760px wide at most; it puts the context stack beside the ring from a 640px container and under it below that.

### Related

- [Reasoning tree](https://uiarc.dev/components/reasoning-tree/markdown): An illustration of tree search over thoughts: candidates are scored, weak branches fade, the best expand, and the winning path from question to answer draws in.
- [Agent run](https://uiarc.dev/components/blocks/agent-run/markdown): A single card that follows one AI coding agent through a task: steps stream in with the live one shimmering, tool calls open in place, and the agent stops on a two-file diff for you to approve or send back before it writes. When the run ends, the steps fold into one line and a result shows the files changed, the checks that passed and a pull request button.
- [Tool call](https://uiarc.dev/components/tool-call/markdown): A tool call row for agent transcripts: the tool's mark and the call in plain words, a live state while it runs, and the input and output a click away, with approval and retry when needed.
- [Agent plan](https://uiarc.dev/components/agent-plan/markdown): The plan an agent writes before it acts: edit, reorder or add steps while it is a draft, then watch it work through them as a live checklist.
- [Context window](https://uiarc.dev/components/context-window/markdown): An AI context window as a grid of 200 cells: the system prompt, tools, files, summary and messages fill it in order, a threshold row marks where compaction starts, and sending a message, attaching a file or compacting shows exactly how much still fits.
- [Text shimmer](https://uiarc.dev/components/text-shimmer/markdown): Show ongoing work with a calm light across the words.

### Also in illustrations

- [Data flow](https://uiarc.dev/components/data-flow/markdown): Data flow illustration. Sources (app, database, events) are on the left, a processing core with a live count sits in the middle, and destinations (warehouse, dashboard, alerts) are on the right. Records leave as hollow dots and travel curved paths. In the core they turn into solid accent squares, then fan out to each destination; alerts receives about every third record.
- [Payment flow](https://uiarc.dev/components/payment-flow/markdown): A card tap goes to a processor, then the network, then the bank and back with authorization, then settlement; each hop lights up with a status label and the amount travels as a chip.
- [DNS resolution](https://uiarc.dev/components/dns-resolution/markdown): A browser asks for a domain and the query hops from the resolver to a root server, the TLD server and the authoritative nameserver, each pointing to the next, until an IP address comes back and the page connects. The resolver keeps the answer with a TTL ring that drains, and a second lookup is answered straight from that cache in one short hop.
- [Model training](https://uiarc.dev/components/model-training/markdown): Training data batches feed a small neural net diagram whose connections strengthen, a loss curve descends beside it, and an evaluation check turns green at the end.
- [Multi-region failover](https://uiarc.dev/components/multi-region-failover/markdown): Animated multi-region failover on a 2.5D stage: users stream requests through a global load balancer to two regions; the primary degrades, fails three health checks, traffic shifts smoothly to the healthy region, then it recovers, passes three checks and traffic ramps back to an even split.
- [Vector search](https://uiarc.dev/components/vector-search/markdown): Documents drop onto a tilted embedding plane and fold into points that cluster by topic; the index links neighbours, a query is typed, embedded and lowered onto the plane, a signal hops along the graph toward it, and a widening ring lights the nearest documents with connecting lines, similarity scores and a ranked list.
- [Branch graph](https://uiarc.dev/components/branch-graph/markdown): A git commit graph where branches draw in as colored lanes, merge commits join lines, a rebase lifts commits and replays them onto main, a squash folds them into one, and hovering a commit shows its message, author and diff stats.
- [Mixture of experts](https://uiarc.dev/components/mixture-of-experts/markdown): An illustration of mixture of experts routing: each token is scored by a router, travels to its top experts, and their outputs merge into the token's result.
- [Speculative decoding](https://uiarc.dev/components/speculative-decoding/markdown): An illustration of speculative decoding: a fast draft model guesses a few tokens, the target model checks them in one pass, and accepted guesses join the answer.
- [Prompt cache](https://uiarc.dev/components/prompt-cache/markdown): An animated explainer for prompt caching: the shared prefix of each request is cached once, later requests read it back, and the cost and time saved add up.

### Guidance for AI tools

Agent loop: An illustration of the agent loop: gather context, take action, verify, repeat, with a bright head circling three stations around the model. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Mixture of experts

> An illustration of mixture of experts routing: each token is scored by a router, travels to its top experts, and their outputs merge into the token's result.

- Type: Component (special)
- Access: Arc Pro
- Page: https://uiarc.dev/components/mixture-of-experts
- Markdown: https://uiarc.dev/components/mixture-of-experts/markdown
- Source file: `registry/components/mixture-of-experts/mixture-of-experts.tsx`
- Dependencies: motion, lucide-react, @radix-ui/react-tooltip
- Keywords: special, motion, illustration, new, mixture of experts, moe, sparse moe, expert routing, gating network, router, top k, top 2 routing, active parameters, load balancing, expert capacity, token dropping, llm architecture, transformer

### When to use

- Explaining why a mixture of experts model is cheap per token: only the chosen experts run, which the active parameter readout makes concrete.
- Showing how a gate scores experts, picks the top k and blends their outputs, with real or sample scores.
- Teaching load balancing and expert capacity, where an uneven router overloads some experts and drops tokens.

### When not to use

- Use model-router to pick which model handles a request in a product; this card explains routing inside one model.
- Use attention-map to show which tokens a token attends to, rather than which experts process it.
- Use token-inspector to show tokenization, token ids and probabilities of generated text.
- Use speculative-decoding to explain draft and verify generation speedups.

### Installation

Mixture of experts is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/mixture-of-experts
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { MixtureOfExperts } from "@/components/arc/mixture-of-experts/mixture-of-experts";

export function RoutingExplainer() {
  return <MixtureOfExperts />;
}

// Your own sequence and experts. Scores are gate weights in expert order.
const experts = [
  { name: "Code", handles: "Identifiers and keywords" },
  { name: "Math", handles: "Numbers and operators" },
  { name: "Prose", handles: "Everyday words" },
  { name: "Names", handles: "People and places" },
];

export function CustomRouting() {
  return (
    <MixtureOfExperts
      experts={experts}
      tokens={[
        { text: "const", scores: [0.7, 0.05, 0.15, 0.1] },
        { text: " total", scores: [0.4, 0.3, 0.25, 0.05] },
        { text: " =", scores: [0.35, 0.55, 0.05, 0.05] },
      ]}
      defaultTopK={1}
      capacityFactor={Infinity}
      parameters={{ total: 141, shared: 5, perExpert: 22 }}
      onRoute={route => console.log(route.token, route.experts)}
    />
  );
}
```

### API reference

#### MixtureOfExperts

An illustration of sparse mixture of experts routing in one card. Tokens slide in one at a time, a router scores every expert with a small bar each, and the token travels to its top k experts. The chosen experts light up in a first and second choice color, their load counters roll, and their outputs merge into the token's output chip. A capacity limit can make a full expert skip a token, which the card shows as a warning. Hover or focus a token to freeze on its gate scores and choices, hover an expert to see what it tends to handle and which tokens it took, switch between top 1 and top 2 to roll the active parameter readout, and read the load balance bar underneath. The expert specialties, scores and parameter counts are illustrative, not measurements of a real model.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `tokens` | `MixtureOfExpertsToken[]` | `DEFAULT_TOKENS` | The sequence to route, as { text, scores? }. Scores are gate weights, one per expert in expert order; any non-negative numbers work and are normalized to sum to 1. Tokens without scores get stable sample scores derived from their text. Defaults to a 15 token sample sentence with hand tuned scores. |
| `experts` | `MixtureOfExpertsExpert[]` | `DEFAULT_EXPERTS` | The routed experts, from 2 to 12, as { name, handles?, icon? }. `handles` is the short description shown on hover; `icon` is a 14px glyph that narrow cards show instead of the name (it falls back to the first letter). The defaults are eight illustrative specialties: code, numbers, punctuation, names, grammar, verbs, dates and symbols. |
| `topK` | `1 \| 2` | – | Experts per token, controlled. Pair with onTopKChange. |
| `defaultTopK` | `1 \| 2` | `2` | Experts per token on first render when uncontrolled. |
| `onTopKChange` | `(topK: 1 \| 2) => void` | – | Called when the top 1 or top 2 control changes. |
| `parameters` | `{ total: number; shared: number; perExpert: number }` | `{ total: 671, shared: 5, perExpert: 16 }` | Sizes in billions for the readout. Active parameters are shared plus top k times perExpert, so the defaults read 21B at top 1 and 37B at top 2, of 671B. These numbers are illustrative: they echo the scale of large open weights models, not the exact layout of the eight expert diagram. |
| `capacityFactor` | `number` | `1` | Room per expert as a multiple of an even share of the routes: capacity is ceil(factor × tokens × k / experts). A token whose chosen expert is already full skips that expert, and passes through unchanged when every choice is full. Pass Infinity to never drop. With the defaults, two tokens overflow at top 2 and one at top 1. |
| `speed` | `number` | `1` | Multiplies the pace. At 1 a token takes about 2.2 seconds; 0 holds still. |
| `paused` | `boolean` | – | Holds the animation, controlled. Pair with onPausedChange. |
| `defaultPaused` | `boolean` | `false` | Starts paused when uncontrolled. |
| `onPausedChange` | `(paused: boolean) => void` | – | Called by the play and pause button. |
| `loop` | `boolean` | `true` | Starts over after a short summary once the last token is through. With reduced motion the card never loops; the button turns into a replay. |
| `onRoute` | `(route: MixtureOfExpertsRoute) => void` | – | Called as each token is sent to its experts with { index, token, scores, experts, weights, dropped }. Experts are best first and weights are renormalized over the top k. |
| `label` | `string` | `"Mixture of experts routing"` | Accessible name of the card. |
| `className` | `string` | – | Class on the root element. Set --moe-first and --moe-second on it to recolor the first and second choice. |
| `style` | `CSSProperties` | – | Inline style on the root element. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Tab | Moves through the top k control, the play and pause button, the expert tiles (one stop) and the token sequence (one stop). |
| Arrow keys, Home, End | Move between options in the top k control, between expert tiles, or between tokens. Focusing a tile or a token with the keyboard freezes the card and shows its details. |
| Enter, Space | On a token or an expert, pins it so the card stays frozen on it; press again to unpin. On the play button, pauses, resumes or replays. |
| Escape | Unpins the pinned token or expert and lets routing resume. |

### Accessibility

- The card is a labelled group. The stage lines, router bars and packets are decorative and hidden from assistive technology; every fact they show is also on a focusable element or in text.
- Each token is a button whose name lists its experts and weights, such as "paid: Verbs 68%, Symbols 32%", and says when an expert skipped it at capacity. Pinning sets aria-pressed.
- Each expert tile is a button named with its load, whether it is at capacity, and its role in the route on screen.
- The rolling numbers are hidden from assistive technology and paired with plain text, such as "37B of 671B parameters active per token" and the load balance in percent.
- First and second choices are told apart by order and label as well as color, and a skipped expert shows a warning icon, a dashed border and the word full, never color alone.
- Pausing, resuming, pinning, the top k change and replay are announced through a polite status region. Autoplay itself is not announced.
- Pointer focus draws no ring; keyboard focus shows Arc's shared focus ring.

### Motion

- One clock drives the story: the input chip slides in, a packet with a short soft trail travels to the router, the score bars grow, packets travel to the chosen experts, the tiles light up and their counters roll, and the packets curve into the merge point and out to the output chip.
- Packets are drawn straight to the DOM on requestAnimationFrame; React only re-renders when a phase changes. Travel uses an in-out curve and an arc length table so dots and trails move evenly on curves.
- Score bars, tile tints and connector colors are CSS transitions on transform and color. Load counters, the active parameter readout and the balance roll on tabular numerals with the smooth, critically damped spring.
- Hover, keyboard focus, a pin, scrolling out of view and the pause button all stop the clock exactly where it is, and it resumes from there.
- Footer text swaps with a short crossfade: the old line fades out in about 100ms while the new one fades in from 2px below.
- Reduced motion drops all travel and the loop: each token's scores, experts and output land in place on a slower cadence, and the card stops on its summary.

### Responsive behavior

- From about 568px wide the card flows left to right: input, router, a column of experts with names and counters, then output.
- Narrower cards flow top to bottom: the router becomes a band of vertical score bars, each above its expert, and the experts become a row of icon tiles with their counters.
- The header wraps so the readout takes its own row, the route readout drops the token chip, and the footer stacks the load balance under it. Everything holds at 320px without horizontal scroll.
- Touch has no hover, so tapping a token or an expert pins it and tapping again resumes.

### Performance

- Routes, loads and drops for the whole sequence are planned once per top k with plain arithmetic and memoized.
- Per frame work is a handful of attribute writes on six packet groups; nothing re-renders between phase changes.
- The clock stops while the card is offscreen, paused, inspected or finished, and the geometry is rebuilt only when the stage width changes.

### Notes for AI

- Choose it to explain how a sparse mixture of experts layer routes tokens: on a model page, in docs about a model's architecture, or in a lesson on LLM internals. It is an illustration, not a profiler.
- Keep expert names to one word. Narrow cards show only each expert's icon, so pass an icon for custom experts or accept the first letter.
- Scores do not need to sum to 1. The top k are taken by score with ties kept in expert order, and their weights are renormalized for the readout.
- capacityFactor is what produces the warning state. Leave it at 1 to show a couple of overflows in the sample, raise it to 1.25 or more for a clean run, or pass Infinity to turn dropping off.
- The default parameter counts are illustrative. If the page names a real model, pass that model's own total, shared and per expert sizes and say where they come from.
- Use onRoute to sync something else on the page, such as highlighting the token in a transcript.

### Related

- [Speculative decoding](https://uiarc.dev/components/speculative-decoding/markdown): An illustration of speculative decoding: a fast draft model guesses a few tokens, the target model checks them in one pass, and accepted guesses join the answer.
- [Agent loop](https://uiarc.dev/components/agent-loop/markdown): An illustration of the agent loop: gather context, take action, verify, repeat, with a bright head circling three stations around the model.
- [Vector search](https://uiarc.dev/components/vector-search/markdown): Documents drop onto a tilted embedding plane and fold into points that cluster by topic; the index links neighbours, a query is typed, embedded and lowered onto the plane, a signal hops along the graph toward it, and a widening ring lights the nearest documents with connecting lines, similarity scores and a ranked list.
- [Context window](https://uiarc.dev/components/context-window/markdown): An AI context window as a grid of 200 cells: the system prompt, tools, files, summary and messages fill it in order, a threshold row marks where compaction starts, and sending a message, attaching a file or compacting shows exactly how much still fits.

### Also in illustrations

- [Data flow](https://uiarc.dev/components/data-flow/markdown): Data flow illustration. Sources (app, database, events) are on the left, a processing core with a live count sits in the middle, and destinations (warehouse, dashboard, alerts) are on the right. Records leave as hollow dots and travel curved paths. In the core they turn into solid accent squares, then fan out to each destination; alerts receives about every third record.
- [Payment flow](https://uiarc.dev/components/payment-flow/markdown): A card tap goes to a processor, then the network, then the bank and back with authorization, then settlement; each hop lights up with a status label and the amount travels as a chip.
- [DNS resolution](https://uiarc.dev/components/dns-resolution/markdown): A browser asks for a domain and the query hops from the resolver to a root server, the TLD server and the authoritative nameserver, each pointing to the next, until an IP address comes back and the page connects. The resolver keeps the answer with a TTL ring that drains, and a second lookup is answered straight from that cache in one short hop.
- [Model training](https://uiarc.dev/components/model-training/markdown): Training data batches feed a small neural net diagram whose connections strengthen, a loss curve descends beside it, and an evaluation check turns green at the end.
- [Multi-region failover](https://uiarc.dev/components/multi-region-failover/markdown): Animated multi-region failover on a 2.5D stage: users stream requests through a global load balancer to two regions; the primary degrades, fails three health checks, traffic shifts smoothly to the healthy region, then it recovers, passes three checks and traffic ramps back to an even split.
- [Branch graph](https://uiarc.dev/components/branch-graph/markdown): A git commit graph where branches draw in as colored lanes, merge commits join lines, a rebase lifts commits and replays them onto main, a squash folds them into one, and hovering a commit shows its message, author and diff stats.
- [Prompt cache](https://uiarc.dev/components/prompt-cache/markdown): An animated explainer for prompt caching: the shared prefix of each request is cached once, later requests read it back, and the cost and time saved add up.
- [Reasoning tree](https://uiarc.dev/components/reasoning-tree/markdown): An illustration of tree search over thoughts: candidates are scored, weak branches fade, the best expand, and the winning path from question to answer draws in.

### Guidance for AI tools

Mixture of experts: An illustration of mixture of experts routing: each token is scored by a router, travels to its top experts, and their outputs merge into the token's result. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Speculative decoding

> An illustration of speculative decoding: a fast draft model guesses a few tokens, the target model checks them in one pass, and accepted guesses join the answer.

- Type: Component (special)
- Access: Arc Pro
- Page: https://uiarc.dev/components/speculative-decoding
- Markdown: https://uiarc.dev/components/speculative-decoding/markdown
- Source file: `registry/components/speculative-decoding/speculative-decoding.tsx`
- Dependencies: motion, lucide-react, @radix-ui/react-switch, @radix-ui/react-tooltip
- Keywords: special, motion, illustration, new, speculative decoding, draft model, target model, assisted generation, inference speed, llm latency, token acceptance, tokens per pass, verify, ai illustration, explainer, decoding

### When to use

- Explaining why a product answers faster: docs, model pages, inference dashboards and blog posts about latency.
- Showing a recorded speculative run from your own server, with acceptance and tokens per pass for a chosen draft length.
- Teaching the trade off between draft length, acceptance rate and speedup with a slider people can try.

### When not to use

- Use text-stream to show an answer streaming to a user; this card explains the mechanism behind the speed.
- Use token-inspector to look at token probabilities and alternatives for one answer.
- Use model-router to explain how requests are sent to different models; speculative decoding runs two models on every request.
- Use attention-map or mixture-of-experts for what happens inside a single forward pass.

### Installation

Speculative decoding is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/speculative-decoding
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { SpeculativeDecoding } from "@/components/arc/speculative-decoding/speculative-decoding";

// Simulated: pass the answer and let the seeded draft guess.
<SpeculativeDecoding
  tokens={[{ text: "The" }, { text: " build", ease: 0.6, miss: " deploy" }, { text: " passed" }, { text: "." }]}
  defaultDraftLength={5}
  defaultCompare
/>

// Replayed: pass rounds recorded from your own server.
<SpeculativeDecoding
  rounds={[
    { draft: ["The", " build", " failed"], accepted: 2, target: " passed" },
    { draft: [], accepted: 0, target: "." },
  ]}
  onComplete={stats => console.log(stats.speedup)}
/>
```

### API reference

#### SpeculativeDecoding

An illustration of speculative decoding in one card. A draft model lane proposes a few ghost tokens quickly; a target model lane checks them in one sweep. Accepted guesses get a check and travel into the answer, the first miss is struck through and replaced by the target's token, and the rest fade away. Rounds repeat until the sentence is done. A compare switch races a second line where the target writes one token per pass, while the speedup, the share of drafts accepted and the tokens per target pass roll up below. Every token in the answer is underlined in the color of the model that wrote it.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `tokens` | `DecodeToken[]` | `sampleTokens` | The target model's answer, one entry per token with its leading space ({ text: " deploy" }). Optional ease (0 to 1) is how likely the draft guesses the token, and miss is what it proposes instead. |
| `rounds` | `DecodeRound[]` | – | A recorded run to replay instead of the simulation: per round the draft tokens, how many were accepted from the start, and the target's own token. Hides the draft length slider. |
| `draftLength` | `number` | – | Tokens the draft guesses per round, 2 to 8 (controlled). Changing it replans and replays from the start. |
| `defaultDraftLength` | `number` | `4` | Draft length on first render. |
| `onDraftLengthChange` | `(length: number) => void` | – | Called when the slider moves. |
| `compare` | `boolean` | – | Shows the target only line and races it on the same clock (controlled). |
| `defaultCompare` | `boolean` | `false` | Compare state on first render. |
| `onCompareChange` | `(compare: boolean) => void` | – | Called when the compare switch changes. |
| `autoplay` | `boolean` | `true` | Starts the run once, when the card is mostly in view. Never starts on its own with reduced motion. |
| `seed` | `number` | `12` | Seed for the simulated guesses. The same seed, tokens and draft length always give the same run. |
| `draftCost` | `number` | `0.1` | Cost of one draft token as a share of a target pass. It sets how long drafting takes on screen and counts toward the speedup. |
| `passDuration` | `number` | `640` | Milliseconds one target pass takes on screen. |
| `title` | `string` | `"Speculative decoding"` | Card title and the group's accessible name. |
| `draftLabel / draftDetail` | `string` | `"Draft model" / "Small, fast"` | Name and detail of the draft lane. Keep them generic or clearly illustrative. |
| `targetLabel / targetDetail` | `string` | `"Target model" / "Large"` | Name and detail of the target lane. |
| `status` | `"ready" \| "loading" \| "error"` | `"ready"` | Loading dims the lanes and shimmers the status line; error shows the message with a retry. Controls are disabled in both. |
| `error` | `string` | – | Message shown when status is "error". |
| `onRetry` | `() => void` | – | Called by the retry button in the error state. The button is hidden without it. |
| `onComplete` | `(stats: DecodeStats) => void` | – | Called each time the speculative line finishes, with passes, drafted, accepted, tokens, acceptance, tokensPerPass and speedup. |
| `className` | `string` | – | Class on the root element. |
| `style` | `CSSProperties` | – | Inline style on the root element. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Tab | Moves through play or pause, restart, the draft length slider and the compare switch. |
| Enter, Space | On play or pause and restart, activates them. On the compare switch, toggles the race. |
| Arrow left / Arrow right, Home, End | On the draft length slider, changes the length by one or jumps to 2 or 8. The run replays with the new length. |

### Accessibility

- The card is a named group. The lanes are hidden from assistive technology and summarized in hidden text once each round has its verdicts: what the draft proposed, how many the target accepted and which token it wrote instead.
- Each output line carries the text written so far as its accessible name, so a screen reader reads words instead of tokens.
- Stats are a description list with spoken values ("2.6 times", "67 percent"); the rolling digits are decorative.
- Verdicts never rely on color: accepted columns show a check, the rejected guess is struck through with an x beside the target's token, and discarded guesses fade.
- A polite live region announces play, pause, restart, the comparison, a new draft length with its expected acceptance and speedup, and the finished result. It never announces every round.
- Pointer focus draws no ring; keyboard focus shows Arc's shared focus ring.

### Motion

- Draft chips appear one by one, fading in from 4px to the left, with a short shimmer on the text while they wait.
- The target's sweep fills each cell in order from a per frame CSS variable; verdict icons and the replacement token crossfade in as the sweep reaches them, and the strike draws from the left.
- Accepted tokens and the target's token travel from their chips into their slot in the answer on a critically damped spring, about 20ms apart. The answer is laid out in full from the start, so the line never reflows.
- Lane height follows wrapping chips on the smooth spring; the target only line opens and closes on the same spring. Stats roll per digit with tabular numerals.
- Status text swaps with a short crossfade; no character morphs, blur or typewriter effects.
- Reduced motion never autoplays; when played, tokens appear in place without travel, the sweep steps per column, and the shimmer, slide and rolls are off.

### Responsive behavior

- Lane and line labels sit in a 120px column on wide cards. Below 560px the lane labels become a legend above the columns and line labels sit above their text with the pass count on the right.
- Draft columns wrap onto a second line when they run out of room; the lane height follows on a spring.
- The status line reserves two lines on narrow cards so wrapping copy never moves the lanes. Stats stay three across; the slider takes a full row above the compare switch.

### Performance

- The clock runs on requestAnimationFrame in a ref. React state changes only when something on screen changes (a chip, a verdict, a landed token); the sweep is a CSS variable written each frame.
- Plans are memoized on a serialized copy of the inputs, so an inline tokens array does not restart the run each render.
- The loop stops when the run ends or is paused, and frame steps are capped so a background tab never jumps ahead.

### Notes for AI

- This is an explainer, not a live decoder. With tokens it simulates a draft model from ease values and a seed; with rounds it replays a real run. Say "illustrative" when the numbers are simulated.
- Token text keeps its leading space, as tokenizers do. Punctuation without a space stays on the same line as the word before it.
- The speedup counts draft time: tokens divided by the sum of one pass per round plus draftCost per drafted token. Longer drafts accept a smaller share because everything after the first miss is discarded, so the speedup peaks at a middle length.
- Keep model names generic (Draft model, Target model) unless the run really came from named models.
- The simulation always leaves the final token to the target, so every round ends with a token from the target.

### Related

- [Mixture of experts](https://uiarc.dev/components/mixture-of-experts/markdown): An illustration of mixture of experts routing: each token is scored by a router, travels to its top experts, and their outputs merge into the token's result.
- [Context window](https://uiarc.dev/components/context-window/markdown): An AI context window as a grid of 200 cells: the system prompt, tools, files, summary and messages fill it in order, a threshold row marks where compaction starts, and sending a message, attaching a file or compacting shows exactly how much still fits.

### Also in illustrations

- [Data flow](https://uiarc.dev/components/data-flow/markdown): Data flow illustration. Sources (app, database, events) are on the left, a processing core with a live count sits in the middle, and destinations (warehouse, dashboard, alerts) are on the right. Records leave as hollow dots and travel curved paths. In the core they turn into solid accent squares, then fan out to each destination; alerts receives about every third record.
- [Payment flow](https://uiarc.dev/components/payment-flow/markdown): A card tap goes to a processor, then the network, then the bank and back with authorization, then settlement; each hop lights up with a status label and the amount travels as a chip.
- [DNS resolution](https://uiarc.dev/components/dns-resolution/markdown): A browser asks for a domain and the query hops from the resolver to a root server, the TLD server and the authoritative nameserver, each pointing to the next, until an IP address comes back and the page connects. The resolver keeps the answer with a TTL ring that drains, and a second lookup is answered straight from that cache in one short hop.
- [Model training](https://uiarc.dev/components/model-training/markdown): Training data batches feed a small neural net diagram whose connections strengthen, a loss curve descends beside it, and an evaluation check turns green at the end.
- [Multi-region failover](https://uiarc.dev/components/multi-region-failover/markdown): Animated multi-region failover on a 2.5D stage: users stream requests through a global load balancer to two regions; the primary degrades, fails three health checks, traffic shifts smoothly to the healthy region, then it recovers, passes three checks and traffic ramps back to an even split.
- [Vector search](https://uiarc.dev/components/vector-search/markdown): Documents drop onto a tilted embedding plane and fold into points that cluster by topic; the index links neighbours, a query is typed, embedded and lowered onto the plane, a signal hops along the graph toward it, and a widening ring lights the nearest documents with connecting lines, similarity scores and a ranked list.
- [Branch graph](https://uiarc.dev/components/branch-graph/markdown): A git commit graph where branches draw in as colored lanes, merge commits join lines, a rebase lifts commits and replays them onto main, a squash folds them into one, and hovering a commit shows its message, author and diff stats.
- [Agent loop](https://uiarc.dev/components/agent-loop/markdown): An illustration of the agent loop: gather context, take action, verify, repeat, with a bright head circling three stations around the model.
- [Prompt cache](https://uiarc.dev/components/prompt-cache/markdown): An animated explainer for prompt caching: the shared prefix of each request is cached once, later requests read it back, and the cost and time saved add up.
- [Reasoning tree](https://uiarc.dev/components/reasoning-tree/markdown): An illustration of tree search over thoughts: candidates are scored, weak branches fade, the best expand, and the winning path from question to answer draws in.

### Guidance for AI tools

Speculative decoding: An illustration of speculative decoding: a fast draft model guesses a few tokens, the target model checks them in one pass, and accepted guesses join the answer. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Prompt cache

> An animated explainer for prompt caching: the shared prefix of each request is cached once, later requests read it back, and the cost and time saved add up.

- Type: Component (special)
- Access: Arc Pro
- Page: https://uiarc.dev/components/prompt-cache
- Markdown: https://uiarc.dev/components/prompt-cache/markdown
- Source file: `registry/components/prompt-cache/prompt-cache.tsx`
- Dependencies: motion, lucide-react, @radix-ui/react-tooltip
- Keywords: special, motion, illustration, new, prompt caching, prompt cache, cache hit, cache write, cache read, prefix matching, time to live, ttl, time to first token, token cost, llm cost, claude, api pricing, animated diagram

### When to use

- A docs page or blog post that explains why a stable prefix makes repeat requests cheaper and faster.
- A pricing or usage page that shows how cache reads, writes and the time to live affect cost.
- Developer onboarding for an AI product where prompt order and cache breakpoints matter.

### When not to use

- Use context-window to show how much of a model's window a conversation fills and when it compacts.
- Use token-inspector to show how text splits into tokens and what each costs.
- Use model-picker or model-router when the subject is choosing a model rather than reusing a prompt.
- Use a real chart of cache hit rate over time for production analytics; this is a teaching illustration with a simulated clock.

### Installation

Prompt cache is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/prompt-cache
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { PromptCache } from "@/components/arc/prompt-cache/prompt-cache";

export function CachingSection() {
  return <PromptCache
    segments={[
      { id: "tools", label: "Tools", tokens: 3_800 },
      { id: "system", label: "System prompt", tokens: 2_400 },
      { id: "documents", label: "Documents", tokens: 36_200 },
      { id: "conversation", label: "Conversation", tokens: 6_000 },
    ]}
    requests={[
      { message: "Which refunds are still pending this week?", tokens: 180 },
      { message: "Draft a reply to Northwind about their late refund", tokens: 240, gap: 42 },
      { message: "Summarize ticket 48213 and the attached invoice", tokens: 410, gap: 35 },
      { message: "Which customers asked about SSO in October?", tokens: 150, gap: 51 },
    ]}
    onRequest={result => console.log(result.kind, result.cost)}
  />;
}
```

### API reference

#### PromptCache

An animated explainer for prompt caching. Four requests stack over time, each a bar of the same prefix segments (tools, system prompt, documents, conversation) plus its own new message, with token counts in the legend. The first request processes every segment in one steady sweep, then the prefix lifts out of the bar and travels into a cache panel, where a time to live ring fills. Later requests light their matching prefix as a cache hit with one quick sweep, only the new message is processed, and their processed tokens, input cost and time to first token roll down from the row above. A toggle edits one segment: the next request matches the cache only up to it, shows a break marker there, and rewrites the rest. When no requests arrive, the ring drains on an accelerated clock and the cache expires. Totals roll into a summary of input cost saved and first token speedup.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `segments` | `{ id: string; label: string; tokens: number; color?: string }[]` | `Tools 3.8K, System prompt 2.4K, Documents 36.2K, Conversation 6K` | The stable prefix in prompt order. Prefix matching runs left to right, so put what changes least first. Colors default to the chart series tokens. Bar widths use a square root scale so a short message stays visible beside a long document; the legend shows the real counts. |
| `requests` | `{ message?: string; tokens: number; gap?: number }[]` | `Four support questions of 150 to 410 tokens, 35 to 51 seconds apart` | One to four requests per round. tokens is the size of the new message (the uncached suffix); gap is the simulated seconds since the previous request. message is used in the accessible description and the onRequest payload. |
| `model` | `{ name: string; mark?: ReactNode; inputPrice: number; cacheWritePrice: number; cacheReadPrice: number }` | `Claude Sonnet 5.5: $2.00 input, $2.50 cache write, $0.20 cache read per million tokens` | The model line in the header and the prices behind every cost. Prices are dollars per million input tokens. Pass your provider's current prices; the default uses Claude's pattern of reads at 0.1x and five minute writes at 1.25x the input price. |
| `ttl` | `number` | `300` | Seconds the cache lives after its last use. Every hit refreshes it. Shown as the ring and the countdown, and in the copy as a duration. |
| `changeSegment` | `string \| null` | `"system"` | Id of the segment the change toggle edits. The toggle arms one edit for the next request and releases once that request is sent. Pass null to hide it. |
| `autoPlay` | `boolean` | `true` | Plays on its own while in view. With reduced motion it opens on a finished round instead and waits for play or step. |
| `loop` | `boolean` | `true` | After a round the cache idles, expires and the story starts over. When false it stops after the cache expires. |
| `speed` | `number` | `1` | Multiplies the pace of the clock and every animation. 0 holds still. |
| `firstToken` | `(tokens: { processed: number; cached: number }) => number` | `0.42 + processed / 40000 + cached / 500000` | Seconds to the first output token for a prompt. The default is an illustrative model: a fixed overhead, prefill of new tokens, and a much faster load of cached ones. |
| `onRequest` | `(result: PromptCacheResult) => void` | – | Called when a request finishes, with index, simulated time, kind (write, hit or partial), breakAt, cachedTokens, writtenTokens, processedTokens, cost, uncachedCost, firstToken, uncachedFirstToken, changed, cold and message. |
| `onExpire` | `() => void` | – | Called when the cache expires. |
| `messageLabel` | `string` | `"New message"` | Legend label for the suffix at the end of each prompt. |
| `title` | `string` | `"Prompt cache"` | Heading of the card, also used in its accessible name. |
| `className` | `string` | – | Extra class on the root section. |
| `style` | `CSSProperties` | – | Inline styles on the root section. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Tab | Moves through play or pause, send the next request, reset, and the change toggle. |
| Enter, Space | Plays or pauses, sends the next request, resets, or arms and disarms the edit. |

### Accessibility

- The card is a section named for the title and marked as a simulation with sample prices.
- Each request is a list item with a sentence that gives its time, message, outcome, tokens read from the cache, tokens processed, input cost and time to first token; the bars and rolling numbers are hidden from assistive technology.
- Requests sent with the step button, the edit toggle, pausing and reset are announced in a polite live region. Autoplay stays silent so it never talks over the page.
- Outcomes are never color alone: every status pairs an icon with a label (Cache write, Cache hit, Partial hit), cached and processed fills differ in fill and outline, and the cache status is written out as Empty, Writing, Reading, Expires in 4:52 or Expired.
- The change toggle is a button with aria-pressed. Icon buttons have names and tooltips.
- Pointer focus draws no ring; keyboard focus shows Arc's shared focus ring.

### Motion

- One requestAnimationFrame clock drives the story and runs only while playing or stepping, on screen and in a visible tab. The ring and countdown are written straight to the DOM; React renders only on events.
- Processing is one linear sweep at a steady speed across the segments that need it. A cache hit fades the prefix to its cached fill while a single band of each segment's color passes once across the prefix, and the cache panel sweeps in step.
- A write carries the new part of the prompt from the row into the cache on a 460ms ease out, changing from processed to cached on the way; the panel's segments land in place and its token count rolls up. The ring refills on a critically damped follow and drains as simulated time passes.
- A changed segment raises a short warning line in the gap where matching stops; the cache drops everything after it before the rewrite lands.
- Numbers roll from the row above, so cost and first token visibly come down, with tabular numerals in columns sized to their content. Status labels swap with one crossfade. Pausing freezes every CSS animation and the clock together.
- Reduced motion opens on a finished round, drops the sweeps, the flight and the break animation, and changes values at once; play and step still work.

### Responsive behavior

- From 660px of container width the cache panel sits beside the requests; below it the panel moves above them as a strip, so the flight still travels from the row into the cache.
- Below 480px each request takes three lines (label and status, the bar, then its three numbers under shared column headings), the stats stack, and the controls wrap under the title when needed.
- Metric columns share one subgrid, so values align across rows at every width. The card holds at 320px with no horizontal scroll.

### Performance

- About 120 small elements. Fills, sweeps, the break line and the flight are CSS animations on transform and opacity; the flight also animates the size of one absolutely positioned element.
- Outcomes are computed once per request with plain arithmetic. The loop stops off screen, in hidden tabs and while paused.

### Notes for AI

- Use it to explain prompt caching on a pricing page, in API docs, or inside a usage dashboard next to real cache hit numbers.
- Keep segment order realistic: content that rarely changes first (tools, system prompt), then documents, then the conversation. Prefix matching stops at the first difference, which the toggle demonstrates.
- Pass the real prices of the model you show. The defaults are Claude Sonnet 5.5 sample prices; for other providers set inputPrice, cacheWritePrice (equal to inputPrice when writes cost nothing extra) and cacheReadPrice.
- Costs, savings and speedups are computed from the props, never typed in. The first request costs more than an uncached one because of the write, and the summary says so until the hits pay it back.
- Latency numbers are illustrative unless you pass firstToken with your own measurements.

### Related

- [Context window](https://uiarc.dev/components/context-window/markdown): An AI context window as a grid of 200 cells: the system prompt, tools, files, summary and messages fill it in order, a threshold row marks where compaction starts, and sending a message, attaching a file or compacting shows exactly how much still fits.
- [Model picker](https://uiarc.dev/components/blocks/model-picker/markdown): A model picker in one quiet pill: open it to choose from featured models with a one line note each, set the reasoning effort, or browse every other model by provider, and the pill swaps to your choice in place.
- [Speculative decoding](https://uiarc.dev/components/speculative-decoding/markdown): An illustration of speculative decoding: a fast draft model guesses a few tokens, the target model checks them in one pass, and accepted guesses join the answer.
- [Agent loop](https://uiarc.dev/components/agent-loop/markdown): An illustration of the agent loop: gather context, take action, verify, repeat, with a bright head circling three stations around the model.
- [Text shimmer](https://uiarc.dev/components/text-shimmer/markdown): Show ongoing work with a calm light across the words.

### Also in illustrations

- [Data flow](https://uiarc.dev/components/data-flow/markdown): Data flow illustration. Sources (app, database, events) are on the left, a processing core with a live count sits in the middle, and destinations (warehouse, dashboard, alerts) are on the right. Records leave as hollow dots and travel curved paths. In the core they turn into solid accent squares, then fan out to each destination; alerts receives about every third record.
- [Payment flow](https://uiarc.dev/components/payment-flow/markdown): A card tap goes to a processor, then the network, then the bank and back with authorization, then settlement; each hop lights up with a status label and the amount travels as a chip.
- [DNS resolution](https://uiarc.dev/components/dns-resolution/markdown): A browser asks for a domain and the query hops from the resolver to a root server, the TLD server and the authoritative nameserver, each pointing to the next, until an IP address comes back and the page connects. The resolver keeps the answer with a TTL ring that drains, and a second lookup is answered straight from that cache in one short hop.
- [Model training](https://uiarc.dev/components/model-training/markdown): Training data batches feed a small neural net diagram whose connections strengthen, a loss curve descends beside it, and an evaluation check turns green at the end.
- [Multi-region failover](https://uiarc.dev/components/multi-region-failover/markdown): Animated multi-region failover on a 2.5D stage: users stream requests through a global load balancer to two regions; the primary degrades, fails three health checks, traffic shifts smoothly to the healthy region, then it recovers, passes three checks and traffic ramps back to an even split.
- [Vector search](https://uiarc.dev/components/vector-search/markdown): Documents drop onto a tilted embedding plane and fold into points that cluster by topic; the index links neighbours, a query is typed, embedded and lowered onto the plane, a signal hops along the graph toward it, and a widening ring lights the nearest documents with connecting lines, similarity scores and a ranked list.
- [Branch graph](https://uiarc.dev/components/branch-graph/markdown): A git commit graph where branches draw in as colored lanes, merge commits join lines, a rebase lifts commits and replays them onto main, a squash folds them into one, and hovering a commit shows its message, author and diff stats.
- [Mixture of experts](https://uiarc.dev/components/mixture-of-experts/markdown): An illustration of mixture of experts routing: each token is scored by a router, travels to its top experts, and their outputs merge into the token's result.
- [Reasoning tree](https://uiarc.dev/components/reasoning-tree/markdown): An illustration of tree search over thoughts: candidates are scored, weak branches fade, the best expand, and the winning path from question to answer draws in.

### Guidance for AI tools

Prompt cache: An animated explainer for prompt caching: the shared prefix of each request is cached once, later requests read it back, and the cost and time saved add up. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Reasoning tree

> An illustration of tree search over thoughts: candidates are scored, weak branches fade, the best expand, and the winning path from question to answer draws in.

- Type: Component (special)
- Access: Arc Pro
- Page: https://uiarc.dev/components/reasoning-tree
- Markdown: https://uiarc.dev/components/reasoning-tree/markdown
- Source file: `registry/components/reasoning-tree/reasoning-tree.tsx`
- Dependencies: motion, lucide-react, @radix-ui/react-tooltip
- Keywords: special, motion, illustration, new, tree of thoughts, beam search, reasoning, search tree, pruning, chain of thought, test time compute, thought tree, best path, llm reasoning, explainer, ai diagram

### When to use

- Explainers, docs and landing pages that teach tree of thoughts, beam search or test time search over reasoning steps.
- Showing why a wider search can beat a greedy one, with a control the reader can change and replay.
- A visual summary of how an agent weighed options before it chose a plan.

### When not to use

- Use agent-run or research-run to show a real agent's steps and output as they stream.
- Use agent-loop to explain the plan, act and observe cycle of a tool using agent.
- Use speculative-decoding or attention-map for token level mechanics rather than whole thoughts.
- Use model-router when the decision is which model handles a request.

### Installation

Reasoning tree is part of Arc Pro. The live preview is public; the source and install command need Pro.

#### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/reasoning-tree
```

#### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

### Usage

```tsx
import { ReasoningTree } from "@/components/arc/reasoning-tree/reasoning-tree";

export function SearchExplainer() {
  return (
    <ReasoningTree
      question="Which caching plan cuts p95 latency?"
      defaultBeamWidth={2}
      onAnswer={({ answer }) => console.log(answer.label, answer.score)}
      thoughts={[
        { label: "Cache at the edge", score: 0.81, text: "Serve product pages from the CDN with a 60 second TTL.", children: [
          { label: "Purge on publish", score: 0.77, children: [
            { label: "Tag based purge", score: 0.9 },
            { label: "Purge everything", score: 0.42 },
          ] },
          { label: "Stale while revalidate", score: 0.84 },
        ] },
        { label: "Add a Redis layer", score: 0.66 },
        { label: "Bigger database", score: 0.35 },
      ]}
    />
  );
}
```

### API reference

#### ReasoningTree

An illustration of tree search over thoughts. A question proposes candidate thoughts; each gets a score bar that fills, the weakest fade while their edges retract into the parent, and the best few expand another depth, up to three. At the end the best path from the question to the answer draws in the accent with a shimmer travelling along it, and the answer settles in with a check. Play, pause, step and restart drive the search, and a beam width control from 1 to 3 changes how many thoughts survive each depth. The scores are illustrative sample values, not the output of a real model.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `question` | `string` | `"Which release plan ships by Friday?"` | Short question on the root node. Keep it to about three short lines. |
| `questionDetail` | `string` | – | The full question, shown on hover and focus and read to screen readers. Defaults to the question. |
| `thoughts` | `ReasoningThought[]` | `sample release plan` | Thoughts at the first depth, each { id?, label, text?, score?, children? }. label is the short node text (about 2 to 4 words), text the full thought, score an illustrative value from 0 to 0.99. The tree is read to a depth of 3. |
| `beamWidth` | `number` | – | How many thoughts survive each depth, from 1 to 3. Controlled; pair it with onBeamWidthChange. |
| `defaultBeamWidth` | `number` | `2` | Starting beam width when uncontrolled. |
| `onBeamWidthChange` | `(beamWidth: number) => void` | – | Called when the beam width control changes. A new width starts the search over. |
| `seed` | `number` | `7` | Seeds the scores of thoughts that have none, so the same tree and seed always search the same way. |
| `autoPlay` | `boolean` | `true` | Starts the search the first time the tree scrolls into view. Ignored under reduced motion, which shows the answer. |
| `loop` | `boolean` | `false` | Starts over about four seconds after the answer is found. |
| `speed` | `number` | `1` | Multiplies the pace. At 1 a three depth search takes about 7 seconds; 0 holds still. |
| `controls` | `boolean` | `true` | Shows play and pause, step, restart and the beam width control. |
| `model` | `{ name: string; mark?: ReactNode } \| null` | `Claude Opus 5.5 with the Claude mark` | The model named in the header. Pass null to show only the title. |
| `title` | `string` | `"Tree of thoughts"` | Header title, shown after the model name. |
| `accent` | `string` | `"var(--series-1)"` | Color of kept thoughts and the best path. The answer always uses the success color with a check. |
| `onAnswer` | `(result: { answer, path, beamWidth }) => void` | – | Called once each time the search reaches its answer, with the answer thought and the path from the first depth to it. |
| `className` | `string` | – | Class on the root element. |
| `style` | `CSSProperties` | – | Inline style on the root element. Set --rt-accent here to recolor the path. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| Tab | Moves to the tree (one stop on the current thought), then play or pause, step, restart and the beam width control. |
| Arrow up / Arrow down | In the tree, moves to the previous or next thought at the same depth on wide layouts, or the previous or next line of the outline on phones. |
| Arrow right / Arrow left | Moves to a thought's best shown child, or back to its parent. |
| Home / End | Moves to the question, or to the answer once it is found. |
| Arrow left / Arrow right on the beam width | Changes the beam width, which starts the search over. |

### Accessibility

- The thoughts form a tree with treeitems that carry their level and position, and a roving tab stop, so the whole tree is a single Tab stop.
- Every thought's accessible name is its full text with its score and its fate: not scored yet, scored, kept, pruned, on the best path, or answer. A pruned thought fades and loses its edge, and the answer has a check icon, so state never relies on color alone.
- Focus and hover show the full thought in a tag next to the node; the same text is in the accessible name.
- A polite status region speaks each step when you step or pause, and the answer when the search ends, but stays quiet while the search plays on its own.
- The header status pairs a pause or check icon with a short label, and the working label carries a calm shimmer.
- Pointer focus draws no ring; keyboard focus shows Arc's shared focus ring around the node.

### Motion

- A proposed thought fades in as its edge draws out of the parent, 20ms apart per sibling.
- Scores fill as a bar with digits that roll on the same 640ms curve, using tabular numerals in a fixed width.
- Pruning fades the thought to 40% and retracts its edge back into the parent. Kept thoughts turn their bar to the accent.
- At the end the best path draws from the question to the answer in about 760ms with a lighter sheen at its head, each node on it lights up as the line reaches it, and the answer settles with one short press and a check.
- On phones a new child glides the lines below it down on a critically damped spring before it fades in, so nothing jumps and nothing bounces.
- Header labels swap with a single 160ms crossfade; the play and pause icons crossfade in place.
- Reduced motion shows the finished search with the path highlighted. Stepping and playing still work, with every change applied at once and no shimmer.

### Responsive behavior

- From about 670px wide the tree reads left to right in four columns: the question, then depths 1 to 3, each with a header that counts how many thoughts were kept.
- Narrower, it becomes a vertical outline with one line per thought, indented by depth and joined by elbow edges, which holds down to 320px.
- The stage reserves the full tree before the search starts, so the card never changes size while it plays; a new beam width animates the height on phones.
- The controls wrap under each other on the narrowest widths.

### Performance

- The search and the layout are pure functions memoized on the data and beam width.
- Positions and edges are written straight to the DOM from one requestAnimationFrame loop that runs only while something glides, so React renders once per step, not per frame.
- Fades, edge draws, bars and the rolling score are CSS transitions on transform, opacity, stroke-dashoffset and a registered integer property.
- Autoplay waits until the tree is in view.

### Notes for AI

- Use it to explain how a reasoning search works, not to show a live model's real scores. Say in the surrounding copy that the scores are illustrative.
- Keep labels to about 2 to 4 words (under about 20 characters) and put the full sentence in text. Give the first depth about 3 thoughts and each later thought about 2 children; deeper levels are ignored.
- The search is plain beam search: every depth proposes the children of the survivors, keeps the best beamWidth, and the last depth keeps only the best one as the answer. Write scores so that a wider beam can find a better answer than the greedy path, which is what makes the control worth trying.
- Thoughts without a score get a seeded one, so a given tree and seed always produce the same outcome.
- Pass model={null} when no specific model is involved. Brand marks are sample content, never an implied endorsement.

### Related

- [Agent loop](https://uiarc.dev/components/agent-loop/markdown): An illustration of the agent loop: gather context, take action, verify, repeat, with a bright head circling three stations around the model.
- [Mixture of experts](https://uiarc.dev/components/mixture-of-experts/markdown): An illustration of mixture of experts routing: each token is scored by a router, travels to its top experts, and their outputs merge into the token's result.
- [Speculative decoding](https://uiarc.dev/components/speculative-decoding/markdown): An illustration of speculative decoding: a fast draft model guesses a few tokens, the target model checks them in one pass, and accepted guesses join the answer.
- [Vector search](https://uiarc.dev/components/vector-search/markdown): Documents drop onto a tilted embedding plane and fold into points that cluster by topic; the index links neighbours, a query is typed, embedded and lowered onto the plane, a signal hops along the graph toward it, and a widening ring lights the nearest documents with connecting lines, similarity scores and a ranked list.
- [Research run](https://uiarc.dev/components/blocks/research-run/markdown): Deep research that plans searches, reads sources with their marks, and streams a cited answer where every chip lights up the sentence it supports.

### Also in illustrations

- [Data flow](https://uiarc.dev/components/data-flow/markdown): Data flow illustration. Sources (app, database, events) are on the left, a processing core with a live count sits in the middle, and destinations (warehouse, dashboard, alerts) are on the right. Records leave as hollow dots and travel curved paths. In the core they turn into solid accent squares, then fan out to each destination; alerts receives about every third record.
- [Payment flow](https://uiarc.dev/components/payment-flow/markdown): A card tap goes to a processor, then the network, then the bank and back with authorization, then settlement; each hop lights up with a status label and the amount travels as a chip.
- [DNS resolution](https://uiarc.dev/components/dns-resolution/markdown): A browser asks for a domain and the query hops from the resolver to a root server, the TLD server and the authoritative nameserver, each pointing to the next, until an IP address comes back and the page connects. The resolver keeps the answer with a TTL ring that drains, and a second lookup is answered straight from that cache in one short hop.
- [Model training](https://uiarc.dev/components/model-training/markdown): Training data batches feed a small neural net diagram whose connections strengthen, a loss curve descends beside it, and an evaluation check turns green at the end.
- [Multi-region failover](https://uiarc.dev/components/multi-region-failover/markdown): Animated multi-region failover on a 2.5D stage: users stream requests through a global load balancer to two regions; the primary degrades, fails three health checks, traffic shifts smoothly to the healthy region, then it recovers, passes three checks and traffic ramps back to an even split.
- [Branch graph](https://uiarc.dev/components/branch-graph/markdown): A git commit graph where branches draw in as colored lanes, merge commits join lines, a rebase lifts commits and replays them onto main, a squash folds them into one, and hovering a commit shows its message, author and diff stats.
- [Prompt cache](https://uiarc.dev/components/prompt-cache/markdown): An animated explainer for prompt caching: the shared prefix of each request is cached once, later requests read it back, and the cost and time saved add up.

### Guidance for AI tools

Reasoning tree: An illustration of tree search over thoughts: candidates are scored, weak branches fade, the best expand, and the winning path from question to answer draws in. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

---

## Release readiness

A launch checklist that keeps prerequisites, progress, and the final action together.

- Type: Block (composition)
- Access: Pro
- Built from: Checkbox, Progress, Switch, Button, Avatar
- Documentation: https://uiarc.dev/components/blocks/release-readiness

### Overview

Use this before a release or handoff. Replace the sample checklist and completion callback with your product data.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/release-readiness. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/release-readiness while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- A pre-launch or handoff gate where several checks must be done before one action unlocks.
- Release or launch checklists with a readiness bar and owners.
- Handoffs that should optionally notify people when the action runs.

### When not to use

- Use onboarding-checklist for a user's own getting-started tasks.

### Usage

```tsx
import { ReleaseReadiness } from "@/components/arc/blocks/release-readiness/release-readiness";

export function ReleasePanel() {
  return <ReleaseReadiness onRelease={() => startRelease("2.4")} />;
}
```

### API

#### ReleaseReadiness

A release checklist with a readiness bar, a notify switch, and a release action that unlocks once every check is done. The four checks are sample data defined in the file.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `onRelease` | `() => void \| Promise<void>` |  | Called when the release button is pressed. Awaited; a thrown error shows an inline alert. |

### Dependencies

- `motion`
- `lucide-react`

### Accessibility

- The completed count lives in an aria-live="polite" region.
- Success is announced with role="status" and failures with role="alert".
- Checks use the library Checkbox, so each has a real label.

### Motion

- The completed count swaps with a 5px rise and fade.
- Reduced motion sets the transition duration to zero.

### Responsive behavior

- Below 700px the summary narrows to a tighter two-column header.
- Below 520px the summary and the two-column task grid collapse to one column, and actions stack.

### Performance

- Four checkboxes and one progress bar; state updates are local and cheap.
- The task list is a plain array with no virtualization, which is fine for a checklist of this size.

### Notes for AI agents

- Use for a pre-launch or handoff gate where several conditions must be true before one action.
- Replace the tasks array, initialChecks, and the hard-coded release name and avatars.
- Wire onRelease to your deploy or handoff call.
- Composes Arc Avatar, Button, Checkbox, Progress, and Switch.

### Keywords

react release checklist, launch readiness, pre release checklist, deploy gate, checklist with progress bar, handoff checklist

### Related

- onboarding-checklist
- progress

---

## Sign up form

An account creation flow with field validation, password strength, and a clear completion state.

- Type: Block (composition)
- Access: Free
- Built from: Input, Password field, Checkbox, Button
- Documentation: https://uiarc.dev/components/blocks/signup-form

### Overview

Use this as the client side of an account flow. Supply an onSubmit handler that creates the account and handles server errors.

### Install

```bash
npx shadcn@latest add https://uiarc.dev/r/signup-form.json
```

With `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`: `npx shadcn@latest add @uiarc/signup-form`

### When to use

- The client side of an email and password sign-up.
- Sign-up pages that should show password strength and a product updates opt-in.
- Flows that want an in-place success panel after the account is created.

### When not to use

- Use sign-in or login-split for returning users.
- Use password-field alone when the form is already built.
- Use otp-input for passwordless or code-based sign-up.

### Usage

```tsx
import { SignupForm, type SignupDetails } from "@/components/arc/blocks/signup-form/signup-form";

export function SignUpPage() {
  const [error, setError] = useState<string | null>(null);
  async function create(details: SignupDetails) {
    const res = await fetch("/api/sign-up", { method: "POST", body: JSON.stringify(details) });
    if (!res.ok) setError("That email is already registered.");
  }
  return <SignupForm onSubmit={create} serverError={error} onProvider={provider => signIn(provider.toLowerCase())} />;
}
```

### API

#### SignupForm

An account creation card: Google, Apple, and GitHub buttons, then name, email, password with strength, a product updates opt-in, and a completion state whose check draws itself in.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `onSubmit` | `(details: SignupDetails) => void \| Promise<void>` |  | Called with valid details. Awaited; a thrown error shows a submit error. |
| `serverError` | `string \| null` |  | External error message shown under the form, for example from your auth API. |
| `onProvider` | `(provider: "Google" \| "Apple" \| "GitHub") => void` |  | Called when a provider button is pressed. Start your OAuth redirect here. Without a redirect, the block simulates the provider and shows the completion state after 900ms. |

#### SignupDetails

Type passed to onSubmit.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `name` (required) | `string` |  | Full name, at least 2 characters. |
| `email` (required) | `string` |  | Email that passed a basic format check. |
| `password` (required) | `string` |  | Password of 8 or more characters. |
| `productUpdates` (required) | `boolean` |  | Opt-in checkbox state. |

### Dependencies

- `motion`
- `lucide-react`

### Accessibility

- Invalid fields set aria-invalid and point aria-describedby at their message.
- Field and submit errors use role="alert"; the success panel uses role="status".
- Provider buttons have labels like "Sign up with Google"; while one is busy the others are aria-disabled.
- Password strength is shown as text, not only color.

### Motion

- The card height springs between the form and the completion panel, which slides in while the form exits.
- The completion ring and check draw themselves in with pathLength.
- Reduced motion drops the offsets and blur and uses zero durations.

### Responsive behavior

- Container query: below 380px of card width the padding, heading, and provider button text shrink so fields keep their width.
- Below 480px viewport width the card uses the smaller panel radius.

### Performance

- Validation is local and synchronous; the card height is a motion value measured with a layout effect, so swapping steps does not reflow the page.
- Strength bars animate with CSS transitions, turned off under reduced motion.

### Notes for AI agents

- Use as the client side of an email and password sign-up with optional social providers.
- Wire onProvider to your auth library's OAuth sign-in; the built-in provider flow is a simulation.
- Validation is local; keep server checks in onSubmit and pass their message through serverError.
- Composes Arc Button, Checkbox, Input, and PasswordField.

### Keywords

react signup form, sign up page, registration form, create account form, password strength form, email password signup

### Related

- sign-in
- login-split
- password-field
- password-strength
- otp-input

---

## Wallet card

A compact account view with balance, recent activity, and focused money actions.

- Type: Block (composition)
- Access: Pro
- Built from: Button, Input, Number field
- Documentation: https://uiarc.dev/components/blocks/wallet-card

### Overview

Use this for a balance summary. The preview uses sample values; connect its actions and amounts to your own verified data.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/wallet-card. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/wallet-card while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- A personal or business balance summary with quick send, deposit, swap, and buy actions.
- Dashboards that pair a balance with a small history chart and recent activity.
- Apps with a main and a reserve account shown in one card.

### When not to use

- Use billing-overview for subscription billing and invoices.
- Use wallet-stack for a stack of payment cards.
- Use checkout-flow for paying for an order.

### Usage

```tsx
import { WalletCard } from "@/components/arc/blocks/wallet-card/wallet-card";

export function AccountSummary() {
  return <WalletCard initialBalanceCents={482_150} />;
}
```

### API

#### WalletCard

A wallet view with two accounts, a scrubbable balance chart, activity search, and send, deposit, swap, and buy panels. All balances, history, and actions are local sample state.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `initialBalanceCents` | `number` | `1_248_032` | Starting balance of the main wallet in cents. The reserve wallet starts at 285,000 cents. |

### Dependencies

- `motion`
- `lucide-react`

### Keyboard

| Keys | Action |
| --- | --- |
| Arrow keys | Move along the balance history via the range input scrubber. |

### Accessibility

- The balance is an aria-live region; hidden balances read as "Balance hidden".
- Action buttons use aria-pressed and aria-controls; focus returns to the action after a submit.
- Amount errors use role="alert" and aria-describedby on the input.

### Motion

- Balances count to the new value over about 0.75s, and the card resizes on a gentle spring.
- Panels swap with a short rise and blur; new activity rows expand in place.
- Reduced motion sets values instantly and disables layout animation.

### Responsive behavior

- The card is a container query root capped at 660px, so it adapts to its slot, not the viewport.
- At 420px container width padding tightens and action arrows hide; at 280px the wallet switcher drops its label and the footer text shrinks.
- Chart hover scrubbing is mouse only; touch and keyboard use the range input over the chart.

### Performance

- Balances tween through a motion value over about 0.75s instead of re-rendering per frame.
- Activity search filters in memory and shows three rows until expanded; the list is not virtualized.

### Notes for AI agents

- Use for a personal or business balance summary with quick money actions.
- Every action is simulated. Replace initialEntries, balances, and submit() with calls to your ledger, and never trust client amounts.
- Composes Arc Button, DropdownMenu, Popover, and SegmentedControl.

### Keywords

react wallet card, crypto wallet ui, balance card, fintech dashboard card, send money ui, account balance chart, banking app component

### Related

- billing-overview
- wallet-stack
- animated-counter

---

## Logo marquee

A quiet, continuously moving row of brand marks with a pause control.

- Type: Block (composition)
- Access: Free
- Built from: Motion, Button, Brand marks
- Documentation: https://uiarc.dev/components/blocks/logo-marquee

### Overview

Use this to show a collection of organizations or tools. Replace the sample marks with brands you have permission to represent.

### Install

```bash
npx shadcn@latest add https://uiarc.dev/r/logo-marquee.json
```

With `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`: `npx shadcn@latest add @uiarc/logo-marquee`

### When to use

- A customer or integration logo strip on a landing page.
- Social proof sections with a heading and a short supporting line.

### When not to use

- Use integrations when each logo needs a description or a connect action.
- Use testimonial-stage when quotes matter more than logos.
- Use carousel when people should browse items by hand.

### Usage

```tsx
import { LogoMarquee } from "@/components/arc/blocks/logo-marquee/logo-marquee";

export function Customers() {
  return (
    <LogoMarquee
      title="Trusted by product teams"
      description="Teams of every size ship with us."
      brands={[{ name: "Acme", icon: "/logos/acme.svg" }, { name: "Globex", icon: "/logos/globex.svg" }]}
    />
  );
}
```

### Examples

#### Integration logos

```tsx
<LogoMarquee
  title="Works with your stack"
  description="Connect the tools your team already uses."
  brands={[
    { name: "Linear", icon: "/logos/linear.svg" },
    { name: "Figma", icon: "/logos/figma.svg" },
    { name: "Notion", icon: "/logos/notion.svg" },
  ]}
/>
```

### API

#### LogoMarquee

A heading, a looping row of brand marks, and a pause control.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` | `string` | `"Good work moves between tools"` | Section heading. |
| `description` | `string` | `"From the first idea to the final handoff, a familiar set of tools stays close to the work."` | Supporting line under the heading. |
| `brands` | `LogoMarqueeBrand[]` | `exampleBrands` | Marks to show. Defaults to seven sample tool logos. |
| `tone` | `"color" \| "mono"` | `"color"` | Color shows each mark in its official brand colors; mono draws every mark in the text color for a quieter row. |

#### LogoMarqueeBrand

One brand entry.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `name` (required) | `string` |  | Visible brand name. |
| `icon` (required) | `string` |  | URL of a single-color SVG, applied as a CSS mask so it inherits the text color. |
| `color` | `string` |  | Official brand color for a single-color mark in color tone. Leave out for black or white marks such as GitHub, Notion, and Vercel so they follow the text. |
| `colorIcon` | `string` |  | URL of a full color SVG for multicolor marks such as Slack or Figma, used in color tone. |

### Dependencies

- `lucide-react`

### Accessibility

- The duplicated loop copy is aria-hidden, so each brand is read once.
- The pause button uses aria-pressed and a live region announces the motion state.

### Motion

- A CSS keyframe loop scrolls two copies of the list for a seamless track.
- Under prefers-reduced-motion the animation stops and the duplicate list is hidden.

### Responsive behavior

- Below 700px the heading and description stack and the marks shrink.
- The track fades at both edges with a mask, so logos never hard-cut at narrow widths.

### Performance

- The loop is a single CSS transform keyframe on one track, with no JavaScript animation.
- Two copies of the list are rendered for a seamless loop; under reduced motion the animation stops and the copy is hidden.
- Logos are CSS masks from SVG URLs, so use small single-color SVGs.

### Notes for AI agents

- Use for a customer or integration logo strip on a landing page.
- Only pass brands you have permission to show; the defaults are illustrative.
- Composes Arc Button for the pause control.

### Keywords

react logo marquee, logo cloud, infinite logo scroll, trusted by logos, customer logos strip, css marquee

### Related

- testimonial-stage
- integrations
- carousel

---

## Team directory

Searchable people, team filters, and a focused profile panel.

- Type: Block (composition)
- Access: Pro
- Built from: Input, Avatar, Button, Motion
- Documentation: https://uiarc.dev/components/blocks/team-directory

### Overview

Use this when people need to browse a team and find contact details. Replace the sample people and portraits with your own directory data.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/team-directory. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/team-directory while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- An internal directory where people search colleagues and copy contact details.
- Team pages with department filters and a profile pane.

### When not to use

- Use team-members to manage roles and invitations.
- Use team-showcase for a public, image-led team section.
- Use customers-table for large tabular people data.

### Usage

```tsx
import { TeamDirectory } from "@/components/arc/blocks/team-directory/team-directory";

export function PeoplePage() {
  const router = useRouter();
  return <TeamDirectory onPersonSelect={(person) => router.push("/people/" + person.id)} />;
}
```

### API

#### TeamDirectory

A searchable people list with Design, Engineering, and Operations filters (each with a count), availability, and a profile pane with focus, location, time zone, and a copyable email. People and portraits are sample data in the file.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `onPersonSelect` | `(person: { id: string; name: string; team: "Design" \| "Engineering" \| "Operations" }) => void` |  | Called when a person is chosen from the list. |

### Dependencies

- `motion`
- `lucide-react`

### Accessibility

- Filter buttons are a labelled group with aria-pressed; person rows are buttons with aria-pressed.
- Escape in the search field clears the query.
- The profile pane is polite live content, so selection changes are announced.
- Copy success and failure are announced through role="status".

### Motion

- The filter highlight and the row selection highlight glide with shared layoutIds on the morph spring.
- Filtered rows close their gaps with position layout animation and fade in or out.
- The profile pane fades up 4px when the person changes.
- Reduced motion removes layout animation and offsets and turns off CSS transitions.

### Responsive behavior

- Container queries on the block: below 640px the copy button becomes icon-only; below 500px the profile pane moves under the list; below 400px the header stacks, search fills the width, and filter counts hide.

### Performance

- Search and filters run in memory on every keystroke, and rows are not virtualized.
- For hundreds of people, filter on the server and paginate before passing data in.

### Notes for AI agents

- Use for an internal directory or team page where people need contact details.
- Replace the people array, the Team union, and portrait paths with your directory data.
- Composes Arc Avatar.

### Keywords

react team directory, employee directory, people search, staff directory ui, company directory, team list with profile

### Related

- team-members
- team-showcase
- search-field
- avatar

---

## Project board

A living workflow board for moving work between stages.

- Type: Block (composition)
- Access: Pro
- Built from: Button, Avatar, Motion
- Documentation: https://uiarc.dev/components/blocks/project-board

### Overview

Use this to track a focused set of work across stages. Connect its local card actions to your project data.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/project-board. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/project-board while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- A compact kanban with a handful of tasks across fixed stages.
- Boards where moving tasks should be accessible through explicit buttons, not drag only.

### When not to use

- Use reorderable-list when order within one list matters more than stages.
- Use timeline for a dated sequence of events.
- Add drag and drop and virtualization, or use a dedicated board library, for large boards.

### Usage

```tsx
import { ProjectBoard } from "@/components/arc/blocks/project-board/project-board";

export function Board() {
  return (
    <ProjectBoard
      onTaskMove={(task) => updateTask(task.id, { stage: task.stage })}
    />
  );
}
```

### API

#### ProjectBoard

A four-stage board (Planned, In progress, Review, Done) with a sprint progress bar, per-column counts, arrow buttons to move cards, an All work / My work filter, and an add task action. Tasks and owner portraits are sample data.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `onTaskMove` | `(task: { id: string; title: string; stage: "Planned" \| "In progress" \| "Review" \| "Done" }) => void` |  | Called after a task moves to its new stage. |

### Dependencies

- `motion`
- `lucide-react`

### Accessibility

- Each card has explicit buttons labeled "Move <task> to <stage>" instead of drag only.
- Moves are announced in a visually hidden role="status" region.
- Each column is a section labelled "<stage>, <n> tasks"; the filter buttons use aria-pressed.

### Motion

- Cards travel between columns with a per-card layoutId on the gentle spring; new cards scale in from 0.98.
- The filter highlight glides between All work and My work, and the progress bar grows with scaleX.
- Reduced motion drops the layoutId and springs, so cards and bars change in place.

### Responsive behavior

- The four columns need 820px; narrower boards scroll horizontally with proximity snap to each column.
- Below 700px each column is up to 78vw wide, team avatars hide, and padding tightens; below 400px the add button becomes icon only.
- Moves use buttons, so touch never needs a drag gesture.

### Performance

- Cards move between columns with a per-card layoutId, which measures layout on each move.
- No virtualization; keep boards to dozens of cards rather than hundreds.

### Notes for AI agents

- Use for a compact kanban of a few tasks. For large boards add virtualization and drag and drop.
- Replace initialTasks, the stages list, and the owner portraits; addTask cycles through sample draft titles.
- Owner portraits render with next/image from lib/media.
- Wire onTaskMove to persist the stage change.

### Keywords

react kanban board, project board, task board, kanban component, accessible kanban, trello style board

### Related

- reorderable-list
- workspace-sidebar
- avatar-group
- filter-toolbar

---

## Invoice studio

An editable invoice with live totals and a clear save flow.

- Type: Block (composition)
- Access: Pro
- Built from: Input, Button, Motion
- Documentation: https://uiarc.dev/components/blocks/invoice-studio

### Overview

Use this as a starting point for creating an invoice. Persist line items and totals through your own service.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/invoice-studio. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/invoice-studio while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- Creating or editing an invoice or quote with line items.
- Forms that need a live subtotal and total as quantities and rates change.

### When not to use

- Use billing-overview to show past invoices and plan status.
- Use checkout-flow when the customer is paying.
- Use sortable-data-table for read-only lists of invoices.

### Usage

```tsx
import { InvoiceStudio, type InvoiceLine } from "@/components/arc/blocks/invoice-studio/invoice-studio";

export function NewInvoice() {
  async function save(lines: InvoiceLine[]) {
    await fetch("/api/invoices/draft", { method: "POST", body: JSON.stringify({ lines }) });
  }
  return <InvoiceStudio onSave={save} />;
}
```

### API

#### InvoiceStudio

An editable invoice with line items, live subtotal and total, and a save draft action. Client details and starting lines are sample data.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `onSave` | `(lines: InvoiceLine[]) => void \| Promise<void>` |  | Called with parsed lines when every line has a description. Awaited; a thrown error shows a save error. |

#### InvoiceLine

Type passed to onSave.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `description` (required) | `string` |  | Line description. |
| `quantity` (required) | `number` |  | Quantity, clamped to zero or more. |
| `rate` (required) | `number` |  | Unit rate in USD. |

### Dependencies

- `motion`
- `lucide-react`

### Accessibility

- The total is an output element with aria-live and aria-atomic.
- Save progress and validation messages are announced via role="status".
- Row inputs and remove buttons carry per-line aria-labels.

### Motion

- Totals roll with a short vertical slide and blur when they change.
- Added and removed lines animate height via layout.
- Reduced motion uses opacity-only swaps with zero duration.

### Responsive behavior

- Below 760px line columns narrow; below 620px the column header hides and each line becomes a stacked card with its own labels.
- Below 380px the from and to parties stack into one column.

### Performance

- Totals recompute on each edit and roll with a short slide; line add and remove animate height with layout.
- Lines are not virtualized, which suits invoices with a few dozen lines.

### Notes for AI agents

- Use for creating or editing an invoice or quote.
- Replace startingLines and the client header; totals are USD only.
- Recompute totals on the server; treat onSave data as a draft.

### Keywords

react invoice editor, invoice generator ui, line items form, quote builder, invoice form with totals, billing invoice component

### Related

- billing-overview
- number-field
- sortable-data-table

---

## Plan comparison

Compare meaningful differences between plans and billing periods.

- Type: Block (composition)
- Access: Free
- Built from: Segmented control, Button, Motion
- Documentation: https://uiarc.dev/components/blocks/plan-comparison

### Overview

Use this when people need to weigh plans side by side. Replace the sample features and prices with your current offering.

### Install

```bash
npx shadcn@latest add https://uiarc.dev/r/plan-comparison.json
```

With `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`: `npx shadcn@latest add @uiarc/plan-comparison`

### When to use

- Comparing two tiers side by side with a feature matrix.
- Pricing pages that switch between monthly and yearly prices.
- Long feature lists where people want to see only the differences.

### When not to use

- Use usage-pricing when price depends on seats or volume.
- Use segmented-control alone for a simple billing toggle.
- Use cancel-flow for downgrade or cancellation decisions.

### Usage

```tsx
import { PlanComparison } from "@/components/arc/blocks/plan-comparison/plan-comparison";

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

### API

#### PlanComparison

A Team vs Studio comparison with a monthly or yearly toggle, animated prices, and a feature matrix. Takes no props; plans, prices, and features are sample data in the file.

No props.

### Dependencies

- `motion`
- `lucide-react`

### Accessibility

- The matrix uses table, row, columnheader, rowheader, and cell roles.
- Prices are aria-live with aria-atomic so the full value is read.
- The chosen plan is announced in a role="status" footer.

### Motion

- Prices count between billing periods and the selection highlight moves with layoutId.
- Extra feature rows expand in height with a light blur.
- Reduced motion jumps to the final values and disables height animation.

### Responsive behavior

- Below 640px the feature header column hides and each feature name spans the row above its two values.
- Below 365px plan and value padding tighten so both plans still fit side by side.

### Performance

- Prices tween with a single animate call per value; the selection highlight uses one layoutId.
- Showing extra rows animates height, so keep the matrix to a few dozen features.

### Notes for AI agents

- Use when people compare two tiers side by side.
- Edit the pricing and features constants; there is no selection callback, so wire the Button onClick yourself.
- Composes Arc Button, SegmentedControl, and Switch.

### Keywords

react pricing comparison, plan comparison table, pricing table, monthly yearly toggle, feature matrix, saas pricing page

### Related

- usage-pricing
- segmented-control
- animated-counter
- cancel-flow

---

## Availability picker

Find a meeting time across people and see the choice come together.

- Type: Block (composition)
- Access: Pro
- Built from: Avatar, Button, Calendar, Motion
- Documentation: https://uiarc.dev/components/blocks/availability-picker

### Overview

Use this to let people choose a time that fits a group. Connect confirmation to your scheduling service.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/availability-picker. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/availability-picker while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- Picking a meeting time that works for several attendees.
- Booking flows that show a few days and open slots with a confirmation step.

### When not to use

- Use calendar or date-picker to pick a single date.
- Use time-picker for a free time input.
- Use event-invite to show and respond to an invite.

### Usage

```tsx
import { AvailabilityPicker } from "@/components/arc/blocks/availability-picker/availability-picker";

export function Schedule() {
  return (
    <AvailabilityPicker
      onConfirm={({ date, time }) => bookMeeting({ date, time })}
    />
  );
}
```

### API

#### AvailabilityPicker

A day strip and time slot list for a group meeting, with attendee avatars and a confirmation step. Days, slots, and attendees are sample data.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `onConfirm` | `(selection: { date: string; time: string }) => void` |  | Called with the chosen day label and time when confirmed. |

### Dependencies

- `motion`
- `lucide-react`

### Accessibility

- Days and times are labeled groups of buttons with aria-pressed.
- The selected day and the final selection are aria-live regions.

### Motion

- Time slots slide in from the direction of the day change.
- The selected slot highlight moves with a shared layoutId on a responsive spring.
- Reduced motion removes the horizontal offset and uses zero durations.

### Responsive behavior

- The five days sit in a fixed five-column grid and time slots in two columns at every width.
- Below 700px attendee names hide; below 490px day cards shrink and the heading icon and date header hide.

### Performance

- Slot lists swap with AnimatePresence on day change; there are no timers or observers.
- Load availability before render, since the block does no fetching.

### Notes for AI agents

- Use for picking a meeting time across several people.
- Replace the days, slots, and attendees with availability from your calendar service; times are labeled Zürich time.
- onConfirm receives display strings, so map them back to real timestamps.

### Keywords

react availability picker, meeting time picker, group scheduling, calendly style picker, time slot picker, book a meeting ui

### Related

- calendar
- time-picker
- date-picker
- booking-pill

---

## Metrics dashboard

A dense analytics view with KPI tabs, one inspectable chart, and top pages and sources.

- Type: Block (composition)
- Access: Pro
- Built from: Button, Charts, Motion
- Documentation: https://uiarc.dev/components/blocks/metrics-dashboard

### Overview

Use this to make a small set of key measures explorable. Replace the sample figures with your analytics source.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/metrics-dashboard. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/metrics-dashboard while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- A small, explorable KPI overview with a range toggle and one chart.
- Product or marketing dashboards with four headline metrics, a 7, 30, or 90 day range, and top pages and sources.

### When not to use

- Use metric-explorer or revenue-explorer for larger or drill-down data.
- Use stat-card for a single number.
- Use sparkline for inline trends in a table.

### Usage

```tsx
import { MetricsDashboard } from "@/components/arc/blocks/metrics-dashboard/metrics-dashboard";

export function Overview() {
  return <MetricsDashboard />;
}
```

### API

#### MetricsDashboard

A dense analytics view: a range control, four KPI tabs that pick the charted metric, one line chart with an optional previous-period comparison and a hover or keyboard tooltip, and top pages and sources lists. Takes no props; all figures are sample data.

No props.

### Dependencies

- `motion`
- `lucide-react`

### Keyboard

| Keys | Action |
| --- | --- |
| Tab | Moves through the range control, Export, the KPI tabs, Compare, and the chart. |
| ArrowLeft / ArrowRight | With the chart focused, moves the inspected point. |
| Home / End | Jumps to the first or last point. |

### Accessibility

- Range buttons use aria-pressed; the KPI tiles are tabs with aria-selected.
- The chart is role="img" with a label; the inspected value is announced through a status tooltip.
- Deltas carry a text direction, not only color.

### Motion

- KPI values and list counts count to their new amounts with tabular numerals.
- The range thumb and KPI underline slide on a spring; the chart crossfades between metrics and ranges.
- Reduced motion swaps values and views immediately.

### Responsive behavior

- Layout follows the block's own width through a ResizeObserver: below 640px the KPI tabs form a two by two grid and the top pages and sources lists stack.
- Below 460px padding tightens, the range control and actions fill the width, KPI values shrink, and the chart is 168px tall.
- Chart hover is mouse based; touch and keyboard select points through focus and the arrow keys.

### Performance

- The chart is a hand-built SVG with a monotone cubic path: up to 30 daily points, or 13 weekly points for 90 days. No charting library.
- All aggregation runs over an in-memory daily series on each change; for larger data or drill-down use metric-explorer.

### Notes for AI agents

- Use for a compact product or marketing analytics overview.
- Replace the generated daily series with your analytics source; Export only shows a local confirmation.
- The layout follows the block's own width (measured), so it works in narrow panels as well as full pages.
- For larger sets, prefer metric-explorer or revenue-explorer.

### Keywords

react metrics dashboard, analytics dashboard, kpi dashboard, dashboard with chart, saas analytics ui, traffic dashboard

### Related

- metric-explorer
- revenue-explorer
- sparkline
- bar-chart

---

## Media player

An audio player with a living playlist and complete playback controls.

- Type: Block (composition)
- Access: Pro
- Built from: Button, Progress, Motion
- Documentation: https://uiarc.dev/components/blocks/media-player

### Overview

Use this for an audio collection where people need clear transport, progress, and volume controls. Replace the sample local loops with your media.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/media-player. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/media-player while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- A small audio collection such as a podcast, sample pack, or playlist.
- Pages that need a full player with seek, skip, volume, and a track list.

### When not to use

- Use now-playing for a compact now playing widget.
- Use transcript-studio when the audio needs a synced transcript.
- Use voice-recorder for recording audio.

### Usage

```tsx
import { MediaPlayerBlock } from "@/components/arc/blocks/media-player/media-player";

export function Listen() {
  return <MediaPlayerBlock />;
}
```

### API

#### MediaPlayerBlock

An audio player with cover art, a three-track playlist, seek bar, skip, and volume with mute. Takes no props; the tracks are short loops synthesized in the browser as WAV blobs, and covers come from lib/media photos.

No props.

### Dependencies

- `motion`
- `lucide-react`

### Keyboard

| Keys | Action |
| --- | --- |
| Arrow keys | Adjust seek position and volume on the focused range inputs. |

### Accessibility

- Uses a native audio element with range inputs for seek and volume.
- Transport and playlist buttons have labels such as "Play <title>" and "Next track"; the current track has aria-current.
- Seek and volume ranges carry aria-valuetext such as "0:12 of 0:24" and "70%". The mute button's label switches between Mute and Unmute audio.

### Motion

- The selection rail glides to the current track with a shared layoutId on the gentle spring; playing bars pulse beside it.
- The cover crossfades and the title rises in when the track changes; the play icon swaps with a short scale and blur.
- Reduced motion removes the glides, swaps, and bar animation.

### Responsive behavior

- Below 420px viewport width the padding tightens, the cover takes a 1.7 ratio, transport buttons shrink, and the volume slider narrows to 64px.
- Seek and volume are native range inputs, so touch and keyboard work without extra handling.

### Performance

- Uses a native audio element; position updates come from timeupdate, not a frame loop.
- The demo tracks are generated as WAV blobs in the browser; replace them with real audio URLs in production.

### Notes for AI agents

- Use for a small audio collection such as a podcast, a sample pack, or a playlist.
- Replace the tracks array and renderTrack() with real audio URLs set on the audio element, and the cover ids with your images.
- The default export is MediaPlayerBlock.

### Keywords

react audio player, music player component, podcast player, playlist player, custom audio controls, media player ui

### Related

- now-playing
- slider
- voice-recorder

---

## Support conversation

A responsive message thread with useful quick replies and live feedback.

- Type: Block (composition)
- Access: Pro
- Built from: Input, Button, Avatar, Motion
- Documentation: https://uiarc.dev/components/blocks/support-conversation

### Overview

Use this as a conversation shell. Replace the deterministic demo replies with messages from your own support service.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/support-conversation. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/support-conversation while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- A support chat or ticket thread with quick replies and attachments.
- Help flows that should show a typing indicator and a resolve toggle.

### When not to use

- Use support-widget for a floating help launcher.
- Use ai-composer for a prompt input without a thread.
- Use inbox-triage to handle many conversations at once.

### Usage

```tsx
import { SupportConversation } from "@/components/arc/blocks/support-conversation/support-conversation";

export function Ticket({ ticketId }: { ticketId: string }) {
  return (
    <SupportConversation
      onSend={(message) => postMessage(ticketId, message)}
      onResolve={(resolved) => setTicketResolved(ticketId, resolved)}
    />
  );
}
```

### API

#### SupportConversation

A support thread with quick replies, PDF attachment, a typing indicator, and a resolve toggle. Replies are deterministic canned answers.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `onSend` | `(message: string) => void` |  | Called with each message the user sends. |
| `onResolve` | `(resolved: boolean) => void` |  | Called when the conversation is marked resolved or reopened. |

### Dependencies

- `motion`
- `lucide-react`

### Accessibility

- New messages are announced through a polite live region.
- The send, attach, and typing indicator elements have aria-labels.
- The file input only accepts PDF.

### Motion

- Messages rise into the thread on a gentle spring and existing messages shift via layout.
- Reduced motion removes the offsets and uses instant transitions.

### Responsive behavior

- The thread scrolls within a 350 to 450px height and centers messages up to 590px wide.
- Below 650px and again below 390px the header and composer padding tighten and the portrait shrinks.

### Performance

- Every message stays mounted and the thread is not virtualized, so load long histories in pages.
- New messages smooth-scroll the thread to the bottom; replies are simulated with timers you should replace.

### Notes for AI agents

- Use as a chat or ticket thread shell.
- Replace replyFor and scheduleReply with messages from your support backend, and initialMessages with the real history.
- onSend fires before the simulated reply; the component still keeps its own message list.

### Keywords

react support chat, chat thread ui, customer support conversation, help desk chat, chat with typing indicator, ticket conversation

### Related

- support-widget
- ai-composer
- inbox-triage
- textarea

---

## Inbox triage

Process a focused inbox with archive, snooze, and restore actions.

- Type: Block (composition)
- Access: Pro
- Built from: Avatar, Button, Motion
- Documentation: https://uiarc.dev/components/blocks/inbox-triage

### Overview

Use this pattern when messages need clear next actions. Connect the demo folder state to your own message service.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/inbox-triage. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/inbox-triage while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- A queue of messages or requests that need archive, snooze, or restore decisions.
- Inboxes where rows expand in place to show details and actions.

### When not to use

- Use inbox-sidebar for mail navigation with folders and counts.
- Use notification-center for system notifications.
- Use swipe-actions for touch-first lists with gesture actions.

### Usage

```tsx
import { InboxTriage } from "@/components/arc/blocks/inbox-triage/inbox-triage";

export function Messages() {
  return <InboxTriage />;
}
```

### API

#### InboxTriage

Inbox, Snoozed, and Archive tabs with messages that expand in place, an Unread filter, archive, snooze, and restore actions with single-key shortcuts, and an undo for the last move. Takes no props; messages are sample data.

No props.

### Dependencies

- `motion`
- `lucide-react`

### Keyboard

| Keys | Action |
| --- | --- |
| ArrowLeft / ArrowRight | Switch folders in the tab list. |
| ArrowUp / ArrowDown | Move between message rows. |
| Enter / Space | Expands or collapses the focused message and marks it read. |
| E | Archives the focused message (outside Archive). |
| S | Snoozes the focused message (in Inbox). |
| U | Moves the focused message back to Inbox (in Snoozed or Archive). |

### Accessibility

- Folders are a tablist with arrow key navigation; the list is its tabpanel.
- Message rows toggle with aria-expanded and aria-controls and declare their shortcuts with aria-keyshortcuts.
- After a message leaves, focus moves to the next row, or to the heading when the list is empty; undo returns focus to the restored row.
- Moves are announced in a polite role="status" region; the Unread filter uses aria-pressed.

### Motion

- Rows and message details open and collapse with height and opacity on the smooth spring.
- The folder indicator glides between tabs with a shared layoutId; the status line swaps with a short rise.
- Reduced motion removes height and travel and keeps plain fades.

### Responsive behavior

- Container queries: below 560px rows switch to a two-line layout with a 32px avatar, subject and preview under the sender, and a short hint in the footer.
- Below 360px the unread count hides, tabs tighten, and detail text drops its avatar indent.

### Performance

- Rows collapse with height animation; the list is not virtualized.
- Focus moves to the next row after an action on the next frame, without extra timers.

### Notes for AI agents

- Use when a queue of messages or requests needs clear next actions.
- No callbacks are exposed; replace initialMessages and the move() and undo() functions with calls to your message service.
- Composes Arc Avatar and Button.

### Keywords

react inbox, email triage ui, inbox component, archive snooze inbox, message list, mail app ui

### Related

- inbox-sidebar
- notification-center
- swipe-actions
- support-conversation

---

## Command palette

A complete keyboard driven action surface with search, grouped results, and shortcuts.

- Type: Block (pattern)
- Access: Free
- Built from: Search, Keyboard navigation, Action list
- Documentation: https://uiarc.dev/components/blocks/command-palette

### Overview

Use it for product wide actions and navigation. Provide meaningful groups, icons, keyboard shortcuts, and handlers.

### Install

```bash
npx shadcn@latest add https://uiarc.dev/r/command-palette.json
```

With `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`: `npx shadcn@latest add @uiarc/command-palette`

### When to use

- App-wide command search opened with Cmd or Ctrl plus K.
- Jumping to pages, creating items, and running actions from one input.
- Inline search panels that group results with shortcuts.

### When not to use

- Use combobox to pick a value inside a form.
- Use dropdown-menu for a short list of actions.
- Use expanding-search or search-field to search page content.

### Usage

```tsx
import { CommandPalette, type CommandItem } from "@/components/arc/command-palette/command-palette";

const items: CommandItem[] = [
  { id: "new", label: "New project", group: "Create", shortcut: "N" },
  { id: "invite", label: "Invite teammate", group: "Team", keywords: ["member"] },
  { id: "theme", label: "Toggle theme", description: "Switch light and dark" },
];

export function Palette({ onClose }: { onClose: () => void }) {
  return <CommandPalette items={items} onSelect={item => run(item.id)} onClose={onClose} />;
}
```

### Examples

#### Inside a dialog

```tsx
<Dialog open={open} onOpenChange={setOpen}>
  <DialogContent title="Command palette">
    <CommandPalette
      items={items}
      onSelect={item => { run(item.id); setOpen(false); }}
      onClose={() => setOpen(false)}
    />
  </DialogContent>
</Dialog>
```

### API

#### CommandPalette

An inline search-and-run panel: a combobox input over grouped, filtered results with one highlight that follows the active row.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `items` (required) | `CommandItem[]` |  | Commands to search. Every word of the query must match: anywhere in the label, at a word start in the description or keywords, or as letters in order across the label ("shpr" finds Share project). Label prefixes rank first, groups follow their best match, and the matched letters render in medium weight. |
| `placeholder` | `string` | `"Search commands"` | Input placeholder. |
| `onSelect` | `(item: CommandItem) => void` |  | Called on click or Enter. The query then clears and focus returns to the input. |
| `onClose` | `() => void` |  | Called on Escape with an empty query. Also renders an Esc close button. |
| `label` | `string` | `"Command palette"` | Visually hidden label for the input. |
| `autoFocus` | `boolean` | `false` | Focuses the search input on mount, for a palette that opens on demand. |

#### CommandItem

Item type: { id: string; label: string; description?: string; group?: string; keywords?: string[]; icon?: ReactNode; shortcut?: string }. Items without a group land under Actions. A shortcut such as "⇧ N" or "Shift+N" renders one keycap per key.

No props.

### Dependencies

- `motion`
- `lucide-react`

### Keyboard

| Keys | Action |
| --- | --- |
| Cmd/Ctrl + K | Focuses the search input from anywhere on the page. |
| ArrowDown / ArrowUp | Moves the active result. |
| Home / End | Jumps to the first or last result. |
| Enter | Runs the active result. The first result is active as soon as results show. |
| Escape | Clears the query, or calls onClose when it is already empty. |

### Accessibility

- The input is a combobox with aria-controls and aria-activedescendant pointing at the listbox option, so focus never leaves the input.
- Results are role=option buttons with aria-selected, grouped in labelled role=group containers.
- A polite live region announces the result count, or No results, as the query changes.
- It renders inline, not in a modal. Put it in a dialog yourself if it should trap focus and close on outside click.

### Motion

- The panel rises in on a spring; the results frame springs to the list height as the query filters.
- Remaining rows glide into place when the shift is small and snap when it is a long jump; the highlight follows the active row on the snappy spring for pointer and arrow keys.
- Reduced motion removes the entrance, glides, and highlight travel.

### Responsive behavior

- It fills its container width; below 480px shortcut hints are hidden and padding tightens.
- Below 340px the footer drops its last hint.
- Results scroll inside a 342px maximum height, and long labels ellipsize.

### Performance

- Filtering is a simple substring match over label, description, group, and keywords on every keystroke.
- Rows are not virtualized and animate with layout; keep lists to a few hundred items or filter on the server.

### Notes for AI agents

- Use for app-wide command search. For picking a value inside a form use combobox; for a small list of actions use dropdown-menu.
- Wrap it in dialog and pass onClose to close the dialog; map onSelect to your router or action handlers by item.id.

### Keywords

react command palette, cmd k menu, command menu, spotlight search, cmdk alternative, keyboard command palette, quick actions

### Related

- dialog
- combobox
- dropdown-menu
- expanding-search
- search-field

---

## Notification center

A home for updates with read state, grouped information, and animated disclosure.

- Type: Block (pattern)
- Access: Free
- Built from: Popover, Badge, Action list
- Documentation: https://uiarc.dev/components/blocks/notification-center

### Overview

Use it when updates need a persistent home instead of a brief toast. Connect read state to your data store.

### Install

```bash
npx shadcn@latest add https://uiarc.dev/r/notification-center.json
```

With `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`: `npx shadcn@latest add @uiarc/notification-center`

### When to use

- A bell in the app header with an unread badge and an inbox of recent updates.
- Notifications people can mark read, expand, and dismiss in bulk.

### When not to use

- Use toast-stack for transient messages that should disappear.
- Use inbox-triage for a full-page inbox.
- Use badge for a count without a panel.

### Usage

```tsx
import { NotificationCenter } from "@/components/arc/notification-center/notification-center";

export function HeaderBell() {
  return (
    <NotificationCenter
      notifications={[
        { id: "1", title: "Deploy finished", time: "2m", tone: "success" },
        { id: "2", title: "Ana commented", time: "1h", actor: { name: "Ana", photo: "/ana.jpg" } },
      ]}
      onReadChange={(item, read) => markRead(item.id, read)}
      onDismiss={item => dismiss(item.id)}
    />
  );
}
```

### API

#### NotificationCenter

A bell trigger with an unread badge that opens a popover of notifications with All and Unread views, expandable rows, and bulk actions.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `notifications` (required) | `NotificationItem[]` |  | Initial notifications. The component keeps its own copy after mount. |
| `label` | `string` | `"Notifications"` | Panel heading and trigger label. |
| `onReadChange` | `(notification: NotificationItem, read: boolean) => void` |  | Called for each item marked read or unread, including Mark all read. |
| `onDismiss` | `(notification: NotificationItem) => void` |  | Called for each dismissed item, including Clear read. |
| `open` | `boolean` |  | Controlled open state. |
| `onOpenChange` | `(open: boolean) => void` |  | Called when the popover opens or closes. |
| `avoidCollisions` | `boolean` | `true` | Lets the popover flip or shift to stay in the viewport. |

#### NotificationItem

Item type: { id: string; title: string; description?: string; time: string; read?: boolean; tone?: "info" | "success" | "warning"; actor?: { name: string; photo: string } }. actor shows an avatar instead of a tone icon.

No props.

### Dependencies

- `motion`
- `lucide-react`
- `@radix-ui/react-popover`

### Keyboard

| Keys | Action |
| --- | --- |
| Enter / Space | Opens the panel from the trigger, toggles a row's details, and activates actions. |
| Escape | Closes the panel and returns focus to the trigger (Radix Popover). |
| Tab | Moves through view toggles, rows, and row actions. |

### Accessibility

- The trigger's aria-label includes the unread count; the visual badge is aria-hidden.
- The summary line is aria-live polite, and outgoing text copies are aria-hidden while they fade.
- Row toggles use aria-expanded and announce unread state; view toggles use aria-pressed.
- Focus moves to the next row, or a view toggle, after an item is read, dismissed, or cleared.

### Motion

- The bell tilts when open; counts roll like an odometer in the direction of change.
- Rows open and collapse their own height on a spring, and bulk actions cascade down the list in under a quarter second.
- Reduced motion replaces height, roll, and tilt with instant fades.

### Responsive behavior

- The panel is min(424px, 100vw minus 24px) wide and at most min(590px, 100vh minus 24px) tall, with the list scrolling inside.
- Below 380px padding tightens, the details indent shrinks, and the Mark all read label becomes icon only.
- Titles and previews ellipsize on one line.

### Performance

- The list is not virtualized and keeps its own copy of the notifications; cap what you pass in.
- The panel mounts in a portal only while open.

### Notes for AI agents

- Use in an app header for an inbox of updates. Use toast or toast-stack for transient messages and inbox-triage for a full-page inbox.
- notifications seeds internal state; sync changes back to your server through onReadChange and onDismiss rather than re-passing the array.

### Keywords

react notification center, notification bell, notification dropdown, inbox popover, unread notifications, activity feed popover

### Related

- popover
- toast-stack
- badge
- avatar
- inbox-triage

---

## Selection toolbar

A contextual batch action surface that appears when items are selected.

- Type: Block (pattern)
- Access: Pro
- Built from: Button, Selection state, Action list
- Documentation: https://uiarc.dev/components/blocks/selection-toolbar

### Overview

Use it next to selectable collections. Keep the count accurate and confirm destructive actions before applying them.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/selection-toolbar. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/selection-toolbar while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- Bulk actions for checkbox-selectable tables or grids.
- Floating bars that appear only while items are selected.

### When not to use

- Use dropdown-menu for per-row actions.

### Usage

```tsx
import { SelectionToolbar } from "@/components/arc/selection-toolbar/selection-toolbar";

export function ProjectsBar({ selected, clear }: { selected: string[]; clear: () => void }) {
  return (
    <SelectionToolbar
      count={selected.length}
      noun="project"
      onClear={clear}
      actions={[
        { label: "Archive", onClick: () => archive(selected) },
        { label: "Delete", onClick: () => remove(selected), destructive: true },
      ]}
    />
  );
}
```

### API

#### SelectionToolbar

A floating bar that appears while items are selected, showing a rolling count, bulk actions, and a clear button.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `count` (required) | `number` |  | Number of selected items. The bar mounts above 0 and leaves at 0. |
| `actions` (required) | `SelectionAction[]` |  | Bulk actions rendered as buttons after the count. |
| `onClear` (required) | `() => void` |  | Called by the clear button. Reset your selection here. |
| `noun` | `string` | `"item"` | Singular noun; an s is added when count is not 1. |

#### SelectionAction

Action type: { label: string; icon?: ReactNode; onClick: () => void; destructive?: boolean }. label is also the React key, so keep labels unique.

No props.

### Dependencies

- `motion`
- `lucide-react`

### Keyboard

| Keys | Action |
| --- | --- |
| Tab | Moves through the actions and the clear button. |
| Enter / Space | Activates the focused button. |

### Accessibility

- The bar is role=toolbar labelled Selection actions.
- A visually hidden aria-live polite line announces the count, such as 3 projects selected; the animated count is aria-hidden.
- The clear button has aria-label Clear selection.
- The bar unmounts at count 0, so move focus back to the list yourself if it was inside the bar.

### Motion

- The bar rises and scales in on a spring and sinks back faster when the selection clears.
- Digits roll in the direction of the change, the plural s fades in place, and the count's width springs so actions do not jump.
- Reduced motion uses plain fades and no width spring.

### Responsive behavior

- Below 520px the bar goes full width and actions wrap onto a second row under the count.
- You position it yourself, for example fixed at the bottom center.

### Performance

- The bar unmounts at count 0; a ResizeObserver springs the count width so actions do not jump.

### Notes for AI agents

- Use with checkbox-selectable tables and grids for bulk actions.
- Position it yourself (for example fixed at the bottom center); it has no default export, so import it by name.

### Keywords

react selection toolbar, bulk actions bar, floating action bar, selected items toolbar, table bulk actions, multi select actions

### Related

- sortable-data-table
- checkbox

---

## File upload

A complete file selection flow with constraints, progress, and error feedback.

- Type: Block (pattern)
- Access: Free
- Built from: File picker, Progress, Feedback
- Documentation: https://uiarc.dev/components/blocks/file-upload

### Overview

Use it for documents or media when people need to see upload progress and recover from invalid files.

### Install

```bash
npx shadcn@latest add https://uiarc.dev/r/file-upload.json
```

With `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`: `npx shadcn@latest add @uiarc/file-upload`

### When to use

- Uploading files with per-file progress, retry, and remove.
- Attachments that must be validated by type and size before upload.
- Uploads that should abort when a file is removed, via the AbortSignal.

### When not to use

- Use file-dropzone when you only need to pick files without upload state.
- Use import-mapper when uploaded data needs column mapping.

### Usage

```tsx
import { FileUpload } from "@/components/arc/file-upload/file-upload";

export function Attachments() {
  return (
    <FileUpload
      accept="image/*,.pdf"
      maxSize={10 * 1024 * 1024}
      onUpload={async (file, { onProgress, signal }) => {
        await uploadWithProgress(file, onProgress, signal);
      }}
    />
  );
}
```

### API

#### FileUpload

A dropzone with a file list that validates type and size, runs your upload per file with progress, and supports retry and remove.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `accept` | `string` |  | Comma-separated extensions or MIME types, including wildcards like image/*. Rejected files stay listed with an error. |
| `maxSize` | `number` |  | Maximum size in bytes. Larger files are listed with an error. |
| `multiple` | `boolean` | `true` | Allows several files. When false a new file replaces the old one. |
| `disabled` | `boolean` | `false` | Disables the dropzone and input. |
| `label` | `string` | `"Upload files"` | Dropzone heading. |
| `description` | `string` | `"Drop files here or browse from your device."` | Helper text, linked with aria-describedby. |
| `value` | `FileUploadItem[]` |  | Controlled file list. |
| `onChange` | `(files: FileUploadItem[]) => void` |  | Called when files are added or removed. |
| `onUpload` | `(file: File, options: { onProgress: (percent: number) => void; signal: AbortSignal }) => Promise<void>` |  | Uploads each valid file. Report 0-100 through onProgress, resolve when done, reject to mark it failed. Removing a file aborts its signal. |

#### FileUploadItem

Item type: { id: string; file: File; error?: string }.

No props.

### Dependencies

- `motion`
- `lucide-react`

### Keyboard

| Keys | Action |
| --- | --- |
| Enter / Space | Opens the file picker from the dropzone. |
| Tab | Moves through the dropzone and each row's retry and remove buttons. |

### Accessibility

- The dropzone is role=button with aria-disabled and aria-describedby for the helper text.
- An aria-live polite status line announces added, rejected, uploaded, failed, and removed files.
- Retry and remove buttons are labelled with the file name.
- After removing a file, focus moves to the neighbouring remove button or back to the dropzone.

### Motion

- The dropzone label swaps to Drop to add files while dragging; rows open and close their height on a spring.
- One spring drives the progress bar and the counted percentage, the bar folds away once the file lands, and a check draws in.
- Reduced motion jumps progress and replaces height and blur swaps with fades.

### Responsive behavior

- The dropzone and list fill their container; file names ellipsize on one line.
- On touch devices the dropzone opens the native file picker, since drag and drop is desktop only.

### Performance

- Uploads run through your onUpload, one call per valid file; there is no concurrency limit, so queue large batches yourself.
- The file list is not virtualized; keep it to a reasonable number of files.

### Notes for AI agents

- Use when files are uploaded with progress. Use file-dropzone when you only need to pick files without upload state.
- Wire onUpload to fetch or XHR and honour the AbortSignal; without onUpload files are only listed and validated.

### Keywords

react file upload, drag and drop upload, upload progress, file dropzone, multiple file upload, upload with retry

### Related

- file-dropzone
- progress

---

## OTP input

A six digit verification flow with paste support and keyboard navigation.

- Type: Block (pattern)
- Access: Free
- Built from: Input, Keyboard navigation, Validation
- Documentation: https://uiarc.dev/components/blocks/otp-input

### Overview

Use it as part of verification after you have sent a code. Validate the code on your server.

### Install

```bash
npx shadcn@latest add https://uiarc.dev/r/otp-input.json
```

With `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`: `npx shadcn@latest add @uiarc/otp-input`

### When to use

- Verification codes from email or SMS.
- Two-factor authentication code entry.

### When not to use

- Use password-field for secrets people type from memory.
- Use input for any other text.

### Usage

```tsx
import { useState } from "react";
import { OtpInput } from "@/components/arc/otp-input/otp-input";

export function VerifyCode() {
  const [code, setCode] = useState("");
  return (
    <OtpInput
      label="Verification code"
      description="We sent a 6-digit code to your email."
      value={code}
      onChange={next => { setCode(next); if (next.length === 6) verify(next); }}
      autoFocus
    />
  );
}
```

### API

#### OtpInput

A row of single-character inputs for one-time codes, with paste fill, a gliding focus ring, and animated helper and error copy.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` (required) | `string` |  | Visible label and group name; each slot is labelled with it plus its position. |
| `length` | `number` | `6` | Number of slots. |
| `value` | `string` | `""` | Current code. Controlled: update it from onChange. |
| `onChange` | `(value: string) => void` |  | Called with the full code after every edit or paste. |
| `description` | `string` |  | Helper text below the slots. |
| `error` | `string` |  | Error text. Sets aria-invalid and shakes the row once when it changes. |
| `inputMode` | `"numeric" \| "text"` | `"numeric"` | numeric strips non-digits. |
| `autoFocus` | `boolean` | `false` | Focuses the first slot on mount. |
| `disabled` | `boolean` | `false` | Disables every slot. |
| `className` | `string` |  | Merged onto the field wrapper. |

### Dependencies

- `motion`

### Keyboard

| Keys | Action |
| --- | --- |
| 0-9 / characters | Fills the slot and moves to the next one. |
| ArrowLeft / ArrowRight | Moves between slots. |
| Backspace | On an empty slot, clears the previous one and moves back. |
| Delete | Clears the current slot. |
| Cmd/Ctrl + V | Pastes a code across the slots from the focused one. |

### Accessibility

- Slots sit in a labelled role=group, each with an aria-label like Verification code, digit 1 of 6.
- Helper and error text are linked with aria-describedby; the error uses role=alert and sets aria-invalid.
- The first slot uses autocomplete one-time-code so browsers can offer SMS codes.

### Motion

- Typed characters rise into the slot and unblur; a paste lands as a short left-to-right wave.
- One focus ring glides between slots, and a new error nudges the row side to side once.
- Reduced motion removes the glide, shake, and blur and uses instant fades.

### Responsive behavior

- Slots are 42px wide and can shrink with max-width 100%; below 360px gaps tighten and slots drop to 44px tall.
- The first slot uses autocomplete one-time-code, so iOS and Android can offer SMS codes.
- numeric inputMode brings up the number pad on phones.

### Performance

- Only a handful of inputs plus one gliding ring; a ResizeObserver springs the message height.

### Notes for AI agents

- Use for verification and two-factor codes. Use input or password-field for anything else.
- It is controlled: keep value in state and submit when value.length equals length. There is no default export, so import it by name.

### Keywords

react otp input, verification code input, 2fa code input, pin input, one time code, sms code input

### Related

- input
- password-field
- sign-in
- signup-form
- security-settings

---

## Multi-step form

A guided form that presents one decision at a time and preserves progress.

- Type: Block (pattern)
- Access: Pro
- Built from: Input, Progress, Button
- Documentation: https://uiarc.dev/components/blocks/multi-step-form

### Overview

Use it when a form needs distinct steps. Keep the number of steps small and provide a clear completion action.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/multi-step-form. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/multi-step-form while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- Onboarding or intake flows split into a few short steps.
- Wizards that need Back and Continue, progress, and a success state out of the box.

### When not to use

- Use stepper when you only need the progress indicator.
- Use checkout-flow for full page flows.
- Use onboarding-checklist for tasks done outside a form.

### Usage

```tsx
import { MultiStepForm } from "@/components/arc/multi-step-form/multi-step-form";

export function Onboarding() {
  return (
    <MultiStepForm
      steps={[
        { id: "account", title: "Account", content: <AccountFields /> },
        { id: "team", title: "Team", description: "Who will you work with?", content: <TeamFields /> },
        { id: "plan", title: "Plan", content: <PlanFields /> },
      ]}
      onComplete={saveOnboarding}
    />
  );
}
```

### API

#### MultiStepForm

A wizard that shows one fieldset per step with a progress list, Back and Continue actions, and a success state after the last step.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `steps` (required) | `FormStep[]` |  | Steps in order. Renders nothing when empty. |
| `onComplete` | `() => void` |  | Called when the last step is submitted. |
| `nextLabel` | `string` | `"Continue"` | Submit label on every step except the last. |
| `completeLabel` | `string` | `"Finish"` | Submit label on the last step. |
| `initialStep` | `number` | `0` | Zero-based starting step, clamped to the range. |

#### FormStep

Step type: { id: string; title: string; description?: string; content: ReactNode }. title becomes the fieldset legend and the progress label.

No props.

### Dependencies

- `motion`
- `lucide-react`

### Keyboard

| Keys | Action |
| --- | --- |
| Enter | Submits the step (native form submit), advancing or finishing. |
| Tab | Moves through step fields and the Back and Continue buttons. |

### Accessibility

- Each step is a fieldset with a legend, and focus moves to the new legend (or the success heading) after navigation.
- Progress is a labelled nav with aria-current=step, plus a visually hidden aria-live line announcing Step 2 of 3.
- The success state is role=status. Native required and pattern constraints in step content block submit before the step advances.

### Motion

- Steps slide 20px in the direction of travel while the shell springs to the new step's height.
- Completed markers draw a check, the step count rolls, and the submit button's width springs when the label changes.
- Reduced motion swaps steps, heights, and labels instantly.

### Responsive behavior

- The progress list scrolls horizontally when steps overflow.
- Below 420px the progress header stacks with the step count on top and padding tightens.

### Performance

- Only the active step is rendered, so keep field values in parent state.
- The shell springs to each step's height; step content is otherwise untouched.

### Notes for AI agents

- Use for onboarding or intake flows split into a few short steps. Use stepper for a standalone progress indicator and checkout-flow for full page flows.
- Step content is rendered only while active, so keep field values in parent state; validation beyond native constraints is up to you.

### Keywords

react multi step form, form wizard, step form, onboarding form, wizard component, multi page form

### Related

- stepper
- signup-form

---

## Team showcase

An image led team introduction with profiles that open in place.

- Type: Block (composition)
- Access: Pro
- Built from: Avatar, Button, Motion
- Documentation: https://uiarc.dev/components/blocks/team-showcase

### Overview

Use this when people behind a product deserve a clear introduction. Supply accurate profiles, portraits, and destinations.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/team-showcase. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/team-showcase while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- About or company pages that introduce the team with portraits.
- Sections that need one of four layouts: gallery, filmstrip, directory, or spotlight.

### When not to use

- Use team-directory for an internal, searchable people list.
- Use team-members for managing members and roles.
- Use testimonial-stage for quotes from customers.

### Usage

```tsx
import { TeamShowcase } from "@/components/arc/blocks/team-showcase/team-showcase";

export function About() {
  return (
    <TeamShowcase
      variant="spotlight"
      onPersonSelect={(person) => router.push("/team/" + person.id)}
    />
  );
}
```

### Examples

#### Directory layout

```tsx
<TeamShowcase
  variant="directory"
  onPersonSelect={(person) => track("team_profile_open", { id: person.id })}
/>
```

### API

#### TeamShowcase

An image-led team section in four layouts, with profiles that open in place and copyable sample contact details. People and portraits are sample data.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"gallery" \| "filmstrip" \| "directory" \| "spotlight"` | `"gallery"` | Layout of the section. |
| `onPersonSelect` | `(person: { id: string; name: string; role: string }) => void` |  | Called when a person is chosen. Receives the full sample person object. |

#### TeamShowcaseReview

Demo wrapper with a SegmentedControl to switch variants. Use it for previews only.

No props.

### Dependencies

- `motion`
- `lucide-react`

### Accessibility

- Selection buttons use aria-pressed; the directory rows use aria-expanded with aria-controls.
- Profile changes are announced in aria-live regions.
- Copy buttons are labeled per person, such as "Copy Maya's email".

### Motion

- Profiles crossfade and expand in place when selection changes.
- Reduced motion removes offsets and height animation.

### Responsive behavior

- It is a container query root, so layouts adapt to the section width, not the viewport.
- At 760px container width the header stacks and details move under the photos.
- At 440px the gallery and filmstrip become horizontal snap scrollers and spotlight stacks the photo under the copy.

### Performance

- Portraits load through next/image with fill and per-layout sizes.
- The selected person is scrolled into view with a smooth scroll that becomes instant under reduced motion.

### Notes for AI agents

- Use on an about or company page to introduce the team.
- Replace the people array and portraits; remove the demo contact details if they should not be public.
- Render TeamShowcase with a fixed variant; TeamShowcaseReview exists for the docs preview.
- Composes Arc CopyButton and SegmentedControl.

### Keywords

react team section, meet the team, team page, about us team grid, team profiles, staff showcase

### Related

- team-directory
- testimonial-stage
- team-members
- avatar

---

## Studio perspectives

Portrait led editorial stories with a focused reading state.

- Type: Block (composition)
- Access: Pro
- Built from: Avatar, Button, Motion
- Documentation: https://uiarc.dev/components/blocks/testimonial-stage

### Overview

Use this to introduce the people behind a product or team. Use verified quotes and portrait permissions for a public site.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/testimonial-stage. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/testimonial-stage while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- Testimonials or editorial stories where the person's portrait matters.
- Landing sections that rotate through a few quotes on demand.

### When not to use

- Use logo-marquee when logos are enough social proof.
- Use carousel for many short testimonials.
- Use team-showcase to introduce your own team.

### Usage

```tsx
import { TestimonialStage } from "@/components/arc/blocks/testimonial-stage/testimonial-stage";

export function Stories() {
  return (
    <TestimonialStage
      className="my-24"
      onPerspectiveChange={(p) => track("testimonial_view", p)}
    />
  );
}
```

### API

#### TestimonialStage

Portrait-led stories with a tab list of people and a quote panel. Quotes and portraits are sample data.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` |  | Appended to the root section. |
| `onPerspectiveChange` | `(perspective: { id: string; name: string }) => void` |  | Called when the active person changes. |

### Dependencies

- `motion`
- `lucide-react`

### Keyboard

| Keys | Action |
| --- | --- |
| ArrowLeft / ArrowRight | Move to the previous or next person in the tab list, wrapping around, and focus it. |

### Accessibility

- People form a role="tablist" with role="tab" and aria-selected.
- The quote panel is a polite live region.

### Motion

- Portrait and quote crossfade with a small directional shift.
- Reduced motion removes the shift and uses instant transitions.

### Responsive behavior

- Below 800px the columns narrow; below 680px the portrait stacks above the quote.
- Below 350px padding and quote size shrink to keep the quote readable.

### Performance

- Only the active portrait is mounted, via next/image, and the first one gets priority loading.
- There is no autoplay timer; changes happen only on tab, arrow, or key input.

### Notes for AI agents

- Use for testimonials or editorial stories about people.
- Replace the perspectives array with verified quotes and portraits you have permission to use.

### Keywords

react testimonial section, testimonial slider, customer quotes, testimonials with photos, review showcase, quote carousel

### Related

- team-showcase
- logo-marquee
- carousel
- tabs

---

## Changelog feed

Release notes you can filter, open in place, and scroll through month by month.

- Type: Block (composition)
- Access: Free
- Built from: Copy button
- Documentation: https://uiarc.dev/components/blocks/changelog-feed

### Overview

Use this for a product changelog page. Load entries from your release notes source and connect the subscribe control to your mailing list.

### Install

```bash
npx shadcn@latest add https://uiarc.dev/r/changelog-feed.json
```

With `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`: `npx shadcn@latest add @uiarc/changelog-feed`

### When to use

- A product changelog or release notes page grouped by month.
- Release notes with type filters such as features, fixes, and improvements.
- Changelogs that should offer an email subscribe action in the header.

### When not to use

- Use timeline for a short vertical list of events without filters.
- Use accordion for plain expandable content that is not dated.

### Usage

```tsx
import { ChangelogFeed } from "@/components/arc/blocks/changelog-feed/changelog-feed";

export default function ChangelogPage() {
  return (
    <main>
      <ChangelogFeed />
    </main>
  );
}
```

### API

#### ChangelogFeed

Release notes grouped by month, with type filter chips, expandable entries with media, a month jump nav, and an inline subscribe form. Entries, images, and the webhook snippet are sample data.

No props.

### Dependencies

- `motion`
- `lucide-react`

### Keyboard

| Keys | Action |
| --- | --- |
| Escape | Cancels the subscribe form and returns to the Subscribe button. |

### Accessibility

- Each entry row is a button with aria-expanded and aria-controls pointing at its detail panel.
- Filter chips are toggle buttons with aria-pressed, and the visible count is announced in a polite status region.
- The month nav marks the current month with aria-current, and the scroll area is focusable with an aria-label.

### Motion

- Entries open in place on a spring while the chevron rotates; the month label slides in the scroll direction.
- The subscribe control morphs from button to form to a drawn check with a short blur crossfade.
- Reduced motion makes these changes instant.

### Responsive behavior

- Below 640px the header stacks, rows move date and type above the text, and the scroller drops from 560px to 520px.
- Below 480px month counts and the shown count are hidden so the month nav fits on one line.
- Hover styles apply only on hover-capable fine pointers.

### Performance

- The feed scrolls inside a fixed-height area; entries are not virtualized, so paginate or load older months on demand.
- Scroll tracking for the month bar is batched to one requestAnimationFrame, and a ResizeObserver resyncs it on resize.

### Notes for AI agents

- Use for a product changelog or release notes page.
- Replace the entries array and the imported sample images with data from your release notes source or CMS.
- The subscribe submit only changes local state; post the email to your mailing list provider.

### Keywords

react changelog, release notes page, changelog component, product updates feed, what's new page, changelog with filters

### Related

- timeline
- accordion
- copy-button
- chip-group

---

## Usage pricing

A pricing calculator that finds your plan as you drag seats and traffic.

- Type: Block (composition)
- Access: Pro
- Built from: Slider, Segmented control, Animated counter, Text morph, Button
- Documentation: https://uiarc.dev/components/blocks/usage-pricing

### Overview

Use this on a pricing page for seat and usage based plans. Replace the plan table with your own rates and limits and connect the trial button to signup.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/usage-pricing. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/usage-pricing while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- Pricing pages for plans priced by seats plus usage.
- Calculators that should recommend a plan as people move sliders.
- Monthly and yearly toggles where the saving should be visible in the breakdown.

### When not to use

- Use plan-comparison for a side by side table of fixed tiers.
- Use usage-forecast to project spend for an existing customer.
- Use billing-overview for the settings page of someone already subscribed.

### Usage

```tsx
import { UsagePricing } from "@/components/arc/blocks/usage-pricing/usage-pricing";

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

### API

#### UsagePricing

A pricing calculator with seat and traffic sliders and a monthly or yearly toggle that recommends a plan, shows its features, and breaks down the cost. Plan rates, limits, and features are sample data.

No props.

### Dependencies

- `motion`
- `lucide-react`

### Accessibility

- The plan card and breakdown are labelled sections tied to their headings with aria-labelledby.
- Plan changes are announced in a polite live region with the plan name and reason.
- The decorative meter is aria-hidden; the numbers are real text.

### Motion

- Prices roll with the animated counter and plan names morph with text-morph as sliders move.
- The feature list reflows as items are added or removed for the recommended plan.
- Reduced motion drops the layout and entrance animations.

### Responsive behavior

- At 780px container width and above the plan card sits in its own column beside the sliders; below that everything stacks.
- The block caps at 1060px and clips its own overflow, so it fits any page column.

### Performance

- Prices roll with the animated counter and the feature list reflows with layout animation on each slider change.
- A ResizeObserver drives the height morph of the plan card.

### Notes for AI agents

- Use on a pricing page for seat plus usage based plans.
- Replace the plan table, rates, and limits with your own; the trial button only sets local state, so route it to signup.
- Composes Arc slider, segmented-control, animated-counter, text-morph, and button.

### Keywords

react pricing calculator, usage based pricing, seat pricing slider, pricing page component, plan recommender, monthly yearly toggle, saas pricing

### Related

- plan-comparison
- slider
- animated-counter
- segmented-control
- usage-forecast

---

## Delivery tracker

A live order tracker whose marker glides between stops while the arrival time rolls.

- Type: Block (composition)
- Access: Pro
- Built from: Avatar, Button, Text morph
- Documentation: https://uiarc.dev/components/blocks/delivery-tracker

### Overview

Use this on an order status page. Feed it updates from your carrier or dispatch webhooks and connect the courier contact options to your messaging and masked calling service; the preview is simulated.

### Install

Arc Pro block: not in the public registry. It uses local image assets, so Pro members copy the source from the Manual tab at https://uiarc.dev/components/blocks/delivery-tracker while signed in (or read it with the MCP get_component tool and a Pro token). Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- Order status pages that follow a delivery from dispatch to door.
- Tracking screens with a live arrival time and an event history.
- Deliveries where people can message or call the courier.

### When not to use

- Use timeline for a static list of past events.
- Use progress when a single percentage is enough.
- Use support-conversation for a full chat with support.

### Usage

```tsx
import { DeliveryTracker } from "@/components/arc/blocks/delivery-tracker/delivery-tracker";

export default function OrderPage() {
  return (
    <main>
      <DeliveryTracker className="order-status" />
    </main>
  );
}
```

### API

#### DeliveryTracker

An order status card with a route progress bar, rolling arrival time, event history, and a courier contact panel for quick replies and calls. The order, courier, and updates are simulated.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` |  | Extra class on the root element. |

### Dependencies

- `motion`
- `lucide-react`

### Accessibility

- Stage changes and arrival updates are announced through a polite live region.
- Quick replies are a labelled group, and the courier typing indicator is a role="status" with a label.
- Call status text updates in its own polite live region.

### Motion

- The marker glides between stops while the arrival time rolls.
- The contact button morphs into the contact panel through a shared layoutId.
- Reduced motion makes the marker and panel morph instant.

### Responsive behavior

- Below 760px container width the courier, updates, and order stack in one column.
- Below 560px the hero stacks and only the current stop keeps its label on the route bar.

### Performance

- The call timer interval runs only during a call, and a ResizeObserver positions the route marker.
- Shared layoutIds morph the contact button into its panel; nothing animates while idle.

### Notes for AI agents

- Use on an order status page.
- Replace the simulated timeline with updates from your carrier or dispatch webhooks, and swap the sample product photos.
- Connect message and call actions to your messaging and masked calling service; composes Arc avatar, button, and text-morph.

### Keywords

react delivery tracker, order tracking page, shipment status, courier tracking ui, package tracker, eta tracker

### Related

- timeline
- avatar
- support-conversation

---

## AI composer

The prompt box at the bottom of an AI app: files upload in place, / opens commands, @ inserts mentions, a model and effort menu sits in the toolbar, and the send button turns into a stop control ringed by the reply's progress.

- Type: Block (composition)
- Access: Pro
- Built from: Tooltip, Text shimmer, Copy button, Dropdown menu
- Documentation: https://uiarc.dev/components/blocks/ai-composer

### Overview

Pass onSend(message, { signal }) and return an async iterable of text deltas; the block handles the fast streamed reveal, Stop (it aborts the signal), Retry and the progress ring. The message carries the text, mention and command tokens, attachments with their File, model, effort, webSearch and thinking. Without onSend it plays simulated replies; greeting, suggestions, models, placeholder and maxLength customize it.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/ai-composer. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/ai-composer while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- The prompt box of an assistant, a coding agent or an in-product AI feature where people attach files, mention docs and pick a model.
- A new chat screen that should open on a greeting and suggestions, then show the first exchange.
- Any place that needs a streaming send and stop control with honest progress and keyboard first commands.

### When not to use

- Use ai-chat for a full conversation with history, message actions and a sidebar of chats.
- Use ai-inline-edit to rewrite a selection inside a document instead of chatting about it.
- Use voice-agent when speech is the main input and the reply is spoken.
- Use model-picker when the job is comparing and choosing models rather than sending a prompt.

### Usage

```tsx
import { AiComposer, type ComposerMessage } from "@/components/arc/blocks/ai-composer/ai-composer";

async function* streamReply(message: ComposerMessage, signal: AbortSignal) {
  const response = await fetch("/api/chat", {
    method: "POST",
    body: JSON.stringify({ text: message.text, model: message.model, effort: message.effort, webSearch: message.webSearch, thinking: message.thinking }),
    signal,
  });
  const reader = response.body!.pipeThrough(new TextDecoderStream()).getReader();
  for (;;) {
    const { value, done } = await reader.read();
    if (done) return;
    yield value;
  }
}

export function Assistant() {
  return <AiComposer greeting="How can I help with checkout?" onSend={(message, { signal }) => streamReply(message, signal)} />;
}
```

### API

#### AiComposer

The prompt box at the bottom of an AI app, shown on a minimal chat stage. One rounded surface holds an autosizing textarea and a toolbar: a plus menu to upload files or add them from Google Drive, GitHub or a screenshot, Web search and Extended thinking toggles, a model chip with the model's mark that opens five current models and an effort row, a dictation mic, and the send button. The send button is muted until there is something to send, shows an arrow when ready, and morphs into a stop square ringed by the reply's progress while it streams. Attachments upload in place with a progress ring that resolves into a check, long pastes become a pasted text chip, / opens commands and @ inserts a mention token. The empty state shows a greeting and three suggestions; sending lifts the message into a bubble and streams the reply below it.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `onSend` | `(message: ComposerMessage, options: { signal: AbortSignal }) => void \| Promise<void> \| AsyncIterable<string>` |  | Called with every sent message: { text, tokens, attachments, files, model, effort, webSearch, thinking }. Return an async iterable of text deltas to stream a real reply into the thread; Stop aborts `signal`. Return nothing and the preview plays a simulated reply and says so in its status region. |
| `greeting` | `string` | `"What should we work on?"` | Display heading of the new chat state, set in Geist. |
| `suggestions` | `Suggestion[]` | `sampleSuggestions` | Up to three starters under the composer, each { id, label, prompt, icon? } with icon "summary", "draft" or "bug". Choosing one fills the composer with its prompt; known commands and mentions in the prompt become tokens. |
| `models` | `ComposerModel[]` | `sampleModels` | Models in the model menu, each { id, name, short, note, mark, defaultEffort } with mark "claude", "openai" or "gemini". The chip shows `short`; the menu shows `name` and `note`. |
| `defaultModel` | `string` |  | Id of the model selected at first. Defaults to the first model, Claude Opus 5.5 in the sample. |
| `placeholder` | `string` | `"Ask anything, / for commands, @ to add context"` | Placeholder of the empty textarea. |
| `maxLength` | `number` | `4000` | Character limit. A ring counter appears at 80 percent, turns to the warning color at 95 percent, and sending stops above the limit. |
| `className` | `string` |  | Class on the root element. |

### Dependencies

- `motion`
- `lucide-react`
- `@radix-ui/react-dropdown-menu`
- `@radix-ui/react-tooltip`

### Keyboard

| Keys | Action |
| --- | --- |
| Enter | Sends the message. With the command or mention list open, inserts the highlighted option instead. |
| Shift + Enter | Adds a new line. The field grows to about eight lines, then scrolls. |
| / | At the start of a line, opens the command list: /summarize, /translate, /explain and /fix. |
| @ | After a space or at the start, opens the files and docs list. The choice is inserted as one atomic token. |
| Arrow up / Arrow down | Moves through the command or mention list while it is open; the textarea keeps focus. |
| Tab | Inserts the highlighted command or mention while the list is open; otherwise moves through the toolbar controls. |
| Escape | Closes the command or mention list, cancels dictation, or stops a running reply, in that order. |
| Backspace / Delete | Next to a token, removes the whole token at once. Arrow keys hop over a token instead of entering it. |
| Arrow left / Arrow right | In the model menu, moves along the effort row. Up and down move through the models. |

### Accessibility

- The textarea is labeled Message and described by a hidden hint for Enter, Shift Enter, / and @. While a list is open it points at it with aria-controls and aria-activedescendant, and the list is a listbox of options grouped into Files and Docs.
- Tokens are drawn by a mirror under a transparent textarea, so the field stays a real textarea for screen readers, spellcheck, undo and IME input.
- The send button changes its accessible name with its state: Send message, Send after uploads finish, Send with the message over the limit, and Stop generating. It stays focusable while it cannot send and reports aria-disabled.
- Web search, Extended thinking and the mic are toggle buttons with aria-pressed; on state also shows in the accent fill and a tooltip, never color alone.
- Attachment chips name their remove control after the file, and a running upload's control reads Cancel upload. A failed file shows an icon and a short reason.
- A polite status region reports what happened: uploads finished, a long paste added as an attachment, the model and effort chosen, sent with a simulated reply, reply finished or stopped, and that dictation and the Drive, GitHub and screenshot actions are simulated.
- Menus come from Radix with focus moved in and returned on close; after picking an attach action focus returns to the textarea.
- Pointer focus draws no ring; keyboard focus shows Arc's shared focus ring.

### Motion

- The send arrow lifts out and a stop square scales in on the morph spring; a thin accent arc around the button fills with the reply, then fades as the button turns back into an arrow the moment the stream ends.
- Replies stream in chunks of whole words every 34ms on an animation frame clock, about 80 words a second, with catch-up when a live stream runs ahead. Each new chunk only fades in over 160ms; settled text is static, and the reply grows line by line on a short ease-out.
- A short Thinking shimmer covers the moment before the first token; with Extended thinking or Web search on, those steps shimmer instead and settle into Thought for 1s or Searched 6 sites.
- The sent message lifts into its bubble on the snappy spring while the composer glides from the center to the bottom on the smooth spring.
- Attachment chips scale in, their ring fills with the upload, and a check pops in before handing over to the remove control. The model chip springs to the width of its new label.
- Reduced motion keeps every state and announcement but drops travel: chunks appear without a fade, the waveform holds still, the ring does not spin, and panels change at once.

### Responsive behavior

- The block is a container: below 680px the tool chips fold into icon buttons with tooltips, below 560px the effort label leaves the model chip, and below 400px the model chip keeps only its mark and the counter keeps only its ring.
- At 320px every control stays in one toolbar row, attachment chips scroll sideways in their own row, and suggestions stack to full width.
- The command and mention list sits above the line being typed and stays inside the composer's width.

### Performance

- The reveal clock runs on requestAnimationFrame only while a reply is writing and skips renders when nothing changed; older chunks merge into one text node so the DOM stays small for long replies.
- The field height follows the mirror through a ResizeObserver instead of measuring scrollHeight on every keystroke.
- The dictation waveform writes bar transforms directly on animation frames without re-rendering React.
- Object URLs for image thumbnails are revoked when a chip is removed or the block unmounts.

### Notes for AI agents

- Wire `onSend` to your model endpoint and return an async iterable of text deltas; the block handles the reveal clock, Stop (through the AbortSignal), Retry and the progress ring. Throwing inside the iterable shows an error line under the reply.
- The message carries `tokens` (the commands and mentions in the text) and `attachments` (with the real File for picked, dropped or pasted files, and the pasted text for pasted chips), so the server can resolve context without parsing the text.
- Uploads, Google Drive, GitHub, screenshots and dictation are simulated in the preview. Replace the actions in composer.tsx with your own upload and picker calls; the chip model (status uploading, done, ready or error with progress) stays the same.
- Use only current models in `models`. The sample lists Claude Opus 5.5, Sonnet 5.5, Haiku 5.5, GPT-6.1 Sol and Gemini 4 Argon with their real marks.
- Keep the stage minimal. For a full thread with history, branching and message actions, use ai-chat and reuse this composer inside it.

### Keywords

ai composer, chat input, prompt box, chat composer, message input, send button, stop generating, attachments, file upload, slash commands, mentions, model picker, effort, dictation, streaming, claude, assistant

### Related

- ai-chat
- ai-answer
- ai-side-panel
- model-picker
- context-window
- text-shimmer

---

## Sign in

A sign in card that morphs from email to a six digit code to your account.

- Type: Block (composition)
- Access: Free
- Built from: Input, OTP input, Button, Avatar
- Documentation: https://uiarc.dev/components/blocks/sign-in

### Overview

Use this as the entry to your app. Send and check codes through your auth provider, connect the passkey button to WebAuthn and the single sign-on buttons to OAuth; everything in the preview is simulated.

### Install

```bash
npx shadcn@latest add https://uiarc.dev/r/sign-in.json
```

With `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`: `npx shadcn@latest add @uiarc/sign-in`

### When to use

- The entry screen of an app with email code sign in.
- Sign in cards that also offer passkeys and single sign-on.
- Passwordless flows that should confirm the account before continuing.

### When not to use

- Use login-centered, login-split, or login-immersive for password based layouts.
- Use signup-form to create an account.
- Use otp-input on its own when the code step lives in your own form.

### Usage

```tsx
import { SignIn } from "@/components/arc/blocks/sign-in/sign-in";
import { useRouter } from "next/navigation";

export function SignInPage() {
  const router = useRouter();

  return <SignIn onSignIn={() => router.push("/dashboard")} />;
}
```

### API

#### SignIn

A sign in card that moves from email to a six digit code to a signed in account, with passkey and single sign-on buttons. Sending and checking codes is simulated.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `demoCode` | `string` | `"123456"` | The code the simulated email contains. |
| `onSignIn` | `(account: SignInAccount, method: SignInMethod) => void` |  | Called once sign in succeeds. SignInAccount is { name, email, photo? }; SignInMethod is "Email code", "Passkey", "Google", "Apple", or "GitHub". |

### Dependencies

- `motion`
- `lucide-react`

### Accessibility

- Single sign-on providers are a labelled group of buttons with visible names.
- Step changes and errors are announced through a visually hidden role="status" region.
- Provider marks are aria-hidden SVGs next to text labels.

### Motion

- The card morphs its height between the email, code, and done steps, sliding content in the direction of travel.
- Reduced motion swaps the slide for a plain fade.

### Responsive behavior

- The card is a container; below 380px its padding and heading shrink, and the provider buttons tighten.
- Below a 480px viewport the card corners soften to the panel radius.

### Performance

- A ResizeObserver drives the height morph between steps.
- The signed in avatar reuses the same image through a layoutId, so the morph does not wait on a second image.

### Notes for AI agents

- Use as the entry screen of an app.
- Send and verify codes through your auth provider instead of demoCode, connect the passkey button to WebAuthn, and the provider buttons to OAuth.
- Composes Arc input, otp-input, button, and avatar; exports SignInAccount and SignInMethod types.

### Keywords

react sign in, passwordless login, email code login, magic code sign in, passkey login, sso buttons, otp login

### Related

- otp-input
- login-centered
- login-split
- signup-form
- password-field

---

## Workspace sidebar

A product sidebar with a workspace switcher, live search, draggable favorites, and inline projects.

- Type: Block (composition)
- Access: Pro
- Built from: Search field, Avatar, Animated counter, Text morph, Button
- Documentation: https://uiarc.dev/components/blocks/workspace-sidebar

### Overview

Use this as the main navigation of a multi-workspace app. Load workspaces, favorites, and projects from your API, route through onNavigate, and persist order and new projects; creation in the preview is simulated.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/workspace-sidebar. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/workspace-sidebar while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- The main navigation of a multi-workspace app.
- Sidebars with draggable favorites and inline project creation.
- Navigation that should collapse to an icon rail with the [ shortcut.

### When not to use

- Use sidebar-rail when you need the whole app shell with a mobile sheet.
- Use docs-sidebar for documentation trees.
- Use inbox-sidebar for mail folders and labels.

### Usage

```tsx
import { WorkspaceSidebar } from "@/components/arc/blocks/workspace-sidebar/workspace-sidebar";
import { useRouter } from "next/navigation";

export function AppNav() {
  const router = useRouter();

  return (
    <WorkspaceSidebar
      onNavigate={({ workspace, id }) => router.push(`/${workspace}/${id}`)}
      onCollapsedChange={(collapsed) => localStorage.setItem("rail", String(collapsed))}
    />
  );
}
```

### API

#### WorkspaceSidebar

A product sidebar with a workspace switcher, live search, draggable favorites, inline project creation, and a collapsible icon rail. Workspaces, favorites, and projects are sample data.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` |  | Extra class on the root element. |
| `onNavigate` | `(target: { workspace: string; id: string; name: string }) => void` |  | Called when a favorite or project is opened. Connect it to your router. |
| `defaultCollapsed` | `boolean` | `false` | Start as the narrow icon rail. |
| `onCollapsedChange` | `(collapsed: boolean) => void` |  | Called when the sidebar collapses or expands, from the toggle or the [ shortcut. |

### Dependencies

- `motion`
- `lucide-react`
- `@radix-ui/react-dropdown-menu`
- `@radix-ui/react-tooltip`

### Keyboard

| Keys | Action |
| --- | --- |
| [ | Toggles the icon rail when focus is not in a text field, menu, or dialog. |
| Alt+Arrow Up / Down | Moves the focused favorite up or down. |
| Escape | Clears the search, or cancels a new project name. |

### Accessibility

- The workspace switcher is a Radix dropdown menu with full menu keyboard support.
- Favorites can be reordered by keyboard as well as by drag.
- The rail shortcut ignores inputs, menus, and dialogs so typing is never hijacked.

### Motion

- The sidebar width springs between full and rail, and favorites reorder with layout animation.
- New projects slide in and counts roll with the animated counter.
- Reduced motion is applied after hydration and makes width and reorder changes instant.

### Responsive behavior

- The open width is the --full custom property, 272px by default, and the rail is 64px.
- It has no mobile sheet; below 380px it only shortens to 660px, so pair it with drawer on phones.
- Favorites drag on the y axis with Reorder, and Alt+Arrow keys reorder without a pointer.

### Performance

- Width springs through one motion value, so collapsing does not re-render the lists.
- Lists are not virtualized; keep favorites and projects to a sidebar's worth of rows.

### Notes for AI agents

- Use as the main navigation of a multi-workspace app.
- Load workspaces, favorites, and projects from your API, route through onNavigate, and persist favorite order and new projects yourself.
- Composes Arc search-field, avatar, animated-counter, text-morph, and button.

### Keywords

react sidebar, workspace switcher, collapsible sidebar, app sidebar navigation, icon rail sidebar, linear style sidebar, draggable favorites

### Related

- sidebar-rail
- inbox-sidebar
- docs-sidebar
- search-field
- reorderable-list

---

## Settings page

Account settings with a gliding section nav and a save bar that morphs in as you edit.

- Type: Block (composition)
- Access: Pro
- Built from: Input, Select, Switch, Segmented control, Avatar, Animated counter, Text morph, Button
- Documentation: https://uiarc.dev/components/blocks/settings-page

### Overview

Use this for account or workspace settings. Load values from your user API, send the changed fields on save, and upload the photo file to your storage; saving in the preview is simulated.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/settings-page. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/settings-page while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- Account or workspace settings with several sections.
- Forms that should show a save bar only when something changed.
- Settings where Cmd or Ctrl+S should save.

### When not to use

- Use security-settings for sessions, two factor, and passwords.
- Use billing-overview for plan and invoice management.
- Use team-members for inviting and managing people.

### Usage

```tsx
import { SettingsPage } from "@/components/arc/blocks/settings-page/settings-page";

export default function AccountSettings() {
  return (
    <main>
      <SettingsPage />
    </main>
  );
}
```

### API

#### SettingsPage

Account settings with profile, notifications, security, and billing sections, a gliding section nav, and a save bar that appears when fields change. Values and saving are simulated.

No props.

### Dependencies

- `motion`
- `lucide-react`

### Keyboard

| Keys | Action |
| --- | --- |
| Arrow keys | Move between sections in the section nav. |
| Home / End | Jump to the first or last section. |
| Cmd/Ctrl+S | Saves pending changes. |

### Accessibility

- The root is a labelled section, and the section nav supports roving arrow key focus.
- Form fields use Arc input, select, and switch with visible labels.
- The save bar counts changed fields and announces saves and reverts.

### Motion

- The active section indicator glides between nav items.
- The save bar morphs in as you edit and its changed count rolls.
- Reduced motion removes the glide and morph.

### Responsive behavior

- Below 720px container width the section nav becomes a horizontal scrolling row above the form and fields drop to one column.
- Below 460px and 360px the save bar hides secondary text and the profile header stacks.

### Performance

- The form scrolls inside a fixed-height pane; a ResizeObserver keeps the nav indicator aligned.
- Only the save bar count and indicator animate; fields are plain controlled inputs.

### Notes for AI agents

- Use for account or workspace settings.
- Replace the initial values with data from your user API, send only changed fields on save, and upload the photo file to your storage.
- Composes Arc input, select, switch, segmented-control, avatar, animated-counter, text-morph, and button.

### Keywords

react settings page, account settings, settings form, unsaved changes bar, profile settings ui, save bar

### Related

- security-settings
- billing-overview
- team-members
- api-keys
- switch

---

## Sidebar rail

An app shell whose sidebar folds into an icon rail and slides in as a sheet on phones.

- Type: Block (composition)
- Access: Pro
- Built from: Tooltip, Avatar, Avatar group, Badge, Animated counter
- Documentation: https://uiarc.dev/components/blocks/sidebar-rail

### Overview

Use this as the frame of a product app. Map the sections to your routes, send selection to your router, and persist the collapsed state per person; press [ to fold the rail.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/sidebar-rail. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/sidebar-rail while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- The frame of a product app with a sidebar, breadcrumbs, and content area.
- Apps with nested nav groups that should fold into an icon rail.
- Shells that need a navigation sheet on narrow widths.

### When not to use

- Use workspace-sidebar when workspace switching and favorites matter more than the shell.
- Use docs-sidebar for documentation.
- Use breadcrumb on its own when the page already has navigation.

### Usage

```tsx
import { SidebarRail } from "@/components/arc/blocks/sidebar-rail/sidebar-rail";

export default function AppShell() {
  return (
    <main>
      <SidebarRail />
    </main>
  );
}
```

### API

#### SidebarRail

An app shell with a sidebar that folds into an icon rail, nested nav groups, breadcrumbs, and a sheet on narrow widths. Sections and page content are sample data.

No props.

### Dependencies

- `motion`
- `lucide-react`
- `@radix-ui/react-dialog`
- `@radix-ui/react-tooltip`

### Keyboard

| Keys | Action |
| --- | --- |
| [ | Folds or unfolds the rail when focus is not in a text field, menu, or dialog. |
| Escape | Closes the navigation sheet on narrow widths. |

### Accessibility

- Nav rows set aria-current="page" on the active item and aria-expanded on groups.
- The narrow layout uses a Radix dialog sheet that moves focus to the current item when it opens.
- Rail icons show Radix tooltips with their labels, and section changes are announced in a status region.

### Motion

- The sidebar folds to a rail on a spring and nested groups expand by height.
- The breadcrumb rises into the new section name.
- Reduced motion makes folding and group changes instant.

### Responsive behavior

- Below 640px container width the sidebar is replaced by a menu button that opens a Radix dialog sheet, up to 288px wide.
- The sheet drags closed to the left, and a ResizeObserver closes it when the shell widens past 640px.
- Content rows drop the timestamp below 420px of content width.

### Performance

- The shell has a fixed 640px height and scrolls its content inside, so it does not reflow the page.
- Rail tooltips mount only while shown through Radix.

### Notes for AI agents

- Use as the frame of a product app.
- Map the sections to your routes, send selection to your router, and persist the collapsed state per person.
- Composes Arc tooltip, avatar, avatar-group, badge, and animated-counter.

### Keywords

react app shell, sidebar layout, collapsible sidebar, icon rail navigation, mobile nav sheet, dashboard layout, nested sidebar

### Related

- workspace-sidebar
- docs-sidebar
- inbox-sidebar
- breadcrumb
- tooltip

---

## Onboarding illustration

A compact onboarding card whose line illustration morphs from folder to files, team, and badge.

- Type: Block (composition)
- Access: Pro
- Built from: Arc foundation
- Documentation: https://uiarc.dev/components/blocks/onboarding-illustration

### Overview

Use this as a first-run dialog in a document product. Swap the copy for your own steps and send Get started to your workspace creation flow; the preview creates nothing.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/onboarding-illustration. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/onboarding-illustration while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- A short first-run dialog in a document or workspace product.
- Onboarding with three or four steps that each need a simple picture.

### When not to use

- Use onboarding-checklist for tasks people complete over time.
- Use feature-illustration for a feature section on a marketing page.

### Usage

```tsx
import { OnboardingIllustration } from "@/components/arc/blocks/onboarding-illustration/onboarding-illustration";

export function FirstRun() {
  return (
    <div role="dialog" aria-label="Welcome">
      <OnboardingIllustration />
    </div>
  );
}
```

### API

#### OnboardingIllustration

A compact onboarding card whose line illustration morphs through four steps, with back and next buttons, step dots, and a Get started action. The copy is sample content and Get started creates nothing.

No props.

### Dependencies

- `motion`
- `lucide-react`

### Keyboard

| Keys | Action |
| --- | --- |
| Arrow Left / Right | Go to the previous or next step. |

### Accessibility

- The illustration is role="img" with a label describing the current scene.
- Step copy sits in a polite live region, so step changes are read out.
- Step dots are labelled buttons with aria-current on the active step.

### Motion

- The same line shapes morph between folder, files, team, and badge scenes on springs.
- Reduced motion jumps to each scene without the morph.

### Responsive behavior

- Below 440px padding tightens, the Back label becomes an icon, and the copy keeps a fixed minimum height so buttons do not jump.
- The illustration's pointer parallax runs only for a mouse on hover-capable devices.

### Performance

- The scenes are one inline SVG whose shapes morph on springs, with no images to load.

### Notes for AI agents

- Use as a first-run dialog in a document or workspace product.
- Swap the step copy and scene labels for your own, and route Get started to your workspace creation flow.
- Has no Arc component dependencies.

### Keywords

react onboarding, onboarding modal, welcome dialog, first run experience, onboarding steps illustration, animated svg onboarding

### Related

- onboarding-checklist
- stepper
- empty-states

---

## Docs sidebar

A docs layout with a live filtering nav tree, version switcher, and a gliding on this page outline.

- Type: Block (composition)
- Access: Pro
- Built from: Search field, Dropdown menu, Code block, Copy button, Badge, Avatar, Button
- Documentation: https://uiarc.dev/components/blocks/docs-sidebar

### Overview

Use this for product or API documentation. Load the tree and pages from your content source, route page changes through your router, and point the version switcher at your versioned builds.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/docs-sidebar. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/docs-sidebar while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- Product or API documentation with a nav tree and page outline.
- Docs that need a version switcher and a filterable tree.
- Pages where the on this page outline should follow scroll.

### When not to use

- Use tree-view for a plain hierarchy outside a docs layout.
- Use sidebar-rail for app navigation.
- Use command-palette for global search across docs.

### Usage

```tsx
import { DocsSidebar } from "@/components/arc/blocks/docs-sidebar/docs-sidebar";

export default function DocsPage() {
  return (
    <DocsSidebar
      defaultCollapsed={false}
      onCollapsedChange={(collapsed) => localStorage.setItem("docs-rail", String(collapsed))}
    />
  );
}
```

### API

#### DocsSidebar

A docs layout with a filterable nav tree, version switcher, page content with code blocks, and an on this page outline that tracks scroll. The tree, pages, and versions are sample content.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `defaultCollapsed` | `boolean` | `false` | Start with the navigation collapsed to its icon rail. |
| `onCollapsedChange` | `(collapsed: boolean) => void` |  | Called when the navigation collapses or expands, from the toggle or the [ shortcut. |

### Dependencies

- `motion`
- `lucide-react`
- `@radix-ui/react-tooltip`

### Keyboard

| Keys | Action |
| --- | --- |
| [ | Toggles the icon rail when focus is not in a text field, menu, or dialog. |
| Arrow Up / Down, Home / End | Move through the nav tree. |
| Arrow Left / Right | Collapse or expand a nav group. |
| Enter | In the filter field, opens the first matching page. |
| Escape | Clears the filter. |

### Accessibility

- The rail toggle exposes aria-expanded and aria-keyshortcuts="[".
- Filter results are announced as a count in a polite status region.
- The nav tree supports arrow key movement from the search field into the list.

### Motion

- The outline indicator glides to the heading in view, and the sidebar folds to a rail on a spring.
- Nav groups expand by height as the filter opens matching branches.
- Reduced motion makes the glide and folds instant.

### Responsive behavior

- At 1000px container width and above the outline gets its own 200px column; below 740px it becomes a collapsible bar above the article.
- Below 620px the rail is dropped and the nav tree folds behind a menu button above the content.

### Performance

- Scroll spy is batched to one requestAnimationFrame per scroll, and ResizeObservers remeasure on width changes.
- The nav tree is not virtualized; very large trees rely on the filter.

### Notes for AI agents

- Use for product or API documentation.
- Load the tree and pages from your content source, route page changes through your router, and point the version switcher at your versioned builds.
- Composes Arc search-field, dropdown-menu, code-block, copy-button, badge, avatar, and button.

### Keywords

react docs layout, documentation sidebar, docs navigation, table of contents scroll spy, on this page outline, api docs template

### Related

- tree-view
- sidebar-rail
- code-block
- search-field
- command-palette

---

## Integrations

An integrations directory where Connect morphs to Connected and the filters recount as you go.

- Type: Block (composition)
- Access: Pro
- Built from: Search field, Drawer, Select, Hold to confirm, Avatar, Button
- Documentation: https://uiarc.dev/components/blocks/integrations

### Overview

Use this on a settings or marketplace page. Load integrations and connection state from your API, start each provider's OAuth flow from Connect, and save sync frequency and Disconnect through it; every connection in the preview is simulated.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/integrations. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/integrations while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- Settings or marketplace pages for third party connections.
- Directories with search, category filters, and Connect buttons.
- Connections that need sync settings and a safe disconnect.

### When not to use

- Use webhooks for outgoing event endpoints.
- Use api-keys for developer credentials.

### Usage

```tsx
import { Integrations } from "@/components/arc/blocks/integrations/integrations";

export default function IntegrationsPage() {
  return (
    <main>
      <Integrations />
    </main>
  );
}
```

### API

#### Integrations

An integrations directory with search, category filters, Connect buttons that morph to Connected, and a drawer for sync settings and hold to disconnect. Providers and connections are simulated.

No props.

### Dependencies

- `motion`
- `lucide-react`

### Keyboard

| Keys | Action |
| --- | --- |
| Arrow keys, Home / End | Move between filter options. |

### Accessibility

- Filters are a role="radiogroup" of role="radio" buttons with aria-checked and roving arrow keys.
- Filter results and connection changes are announced in a polite status region.
- Disconnect uses hold to confirm, so it cannot fire from a stray click.

### Motion

- Connect morphs into a Connected state and filter counts recount as you go.
- Cards reflow with layout animation when filtering.
- Reduced motion swaps morphs and reflow for instant changes.

### Responsive behavior

- Below 720px container width the search goes full width under the title.
- Below 480px the filters become one horizontally scrolling row instead of wrapping.
- Settings open in a drawer, which goes nearly full width on phones.

### Performance

- Cards reflow with layout animation when filtering; the grid is not virtualized.
- ResizeObservers drive the filter indicator and height morphs.

### Notes for AI agents

- Use on a settings or marketplace page for third party connections.
- Load integrations and connection state from your API, start each provider's OAuth flow from Connect, and save sync frequency and Disconnect through it.
- Composes Arc search-field, drawer, select, hold-to-confirm, avatar, and button.

### Keywords

react integrations page, app marketplace, connect apps ui, integrations directory, oauth connect button, third party integrations

### Related

- webhooks
- api-keys
- drawer
- hold-to-confirm
- search-field

---

## Billing overview

A billing page where the plan card morphs into a picker and usage, invoices, and card follow.

- Type: Block (composition)
- Access: Pro
- Built from: Button, Badge, Input, Segmented control, Text morph, Animated counter, Avatar
- Documentation: https://uiarc.dev/components/blocks/billing-overview

### Overview

Use this as the billing settings page of a SaaS app. Load plan, usage, card, and invoices from your billing provider and connect Upgrade, Update, Pay now, and Download to it; every charge in the preview is simulated.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/billing-overview. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/billing-overview while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- The billing settings page of a SaaS app.
- Pages that show plan, usage, payment method, and invoices together.
- Plan changes that should happen in place without leaving billing.

### When not to use

- Use plan-comparison or usage-pricing on a public pricing page.
- Use cancel-flow for the cancellation journey.
- Use usage-meter to show a single quota elsewhere.

### Usage

```tsx
import { BillingOverview } from "@/components/arc/blocks/billing-overview/billing-overview";

export default function BillingPage() {
  return (
    <main>
      <BillingOverview />
    </main>
  );
}
```

### API

#### BillingOverview

A billing settings page: a plan card that morphs into a plan picker with a monthly or yearly switch and a prorated quote, usage meters that fill when seen, a payment card that edits in place and turns its digits when replaced, and an invoice list with download and pay now. Plan, usage, card, and invoices are simulated.

No props.

### Dependencies

- `motion`
- `lucide-react`

### Keyboard

| Keys | Action |
| --- | --- |
| Arrow keys, Home / End | Move between plans in the picker. |
| Escape | Closes the plan picker or cancels card editing. |

### Accessibility

- The plan picker is a role="radiogroup" of role="radio" buttons; unavailable plans are disabled.
- The price quote updates in a polite live region, and actions are announced in a status region.

### Motion

- The plan card morphs into the picker and back inside a region whose height springs; the selected plan highlight glides with a shared layoutId.
- Changing copy rises into place while the old line lifts away; totals roll with AnimatedCounter and card digits turn one column at a time.
- Usage bars fill when they scroll into view.
- Reduced motion makes the morph and fills instant.

### Responsive behavior

- Below 780px container width the plan and payment cards stack; below 700px meters go single column and invoice rows wrap.
- Below 480px quote buttons stretch full width, and below 340px the card form fields stack.

### Performance

- Usage bars animate once when 30% in view.
- The invoice list is not virtualized; paginate long billing histories.

### Notes for AI agents

- Use as the billing settings page of a SaaS app.
- Load plan, usage, card, and invoices from your billing provider and connect confirmPlan, saveCard, pay, and download to it.
- Quotes prorate a mid-term change for the days left; switching billing period starts a new period today and credits unused time. Replace this with your provider's preview invoice.
- Composes Arc button, badge, input, segmented-control, text-morph, animated-counter, and avatar.

### Keywords

react billing page, subscription management, billing settings, invoice list, usage meters, change plan ui, saas billing

### Related

- usage-meter
- plan-comparison
- cancel-flow
- invoice-studio
- settings-page

---

## API keys

API key management where Create key unfolds into its form and each secret is shown once.

- Type: Block (composition)
- Access: Pro
- Built from: Hold to confirm, Copy button, Input, Segmented control, Checkbox, Badge, Avatar, Button
- Documentation: https://uiarc.dev/components/blocks/api-keys

### Overview

Use this on the developer settings page of an API product. Create keys on your server, pass the one-time secret to the reveal step, and connect Hold to revoke to your key revocation endpoint; every key in the preview is simulated.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/api-keys. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/api-keys while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- The developer settings page of an API product.
- Key management with scopes, environments, and a one-time secret reveal.
- Revoking keys where a stray click must not fire.

### When not to use

- Use webhooks for event endpoints and signing secrets.
- Use integrations for OAuth connections to other apps.
- Use roles-permissions for user access.

### Usage

```tsx
import { ApiKeys } from "@/components/arc/blocks/api-keys/api-keys";

export default function DeveloperSettings() {
  return (
    <main>
      <ApiKeys />
    </main>
  );
}
```

### API

#### ApiKeys

API key management where Create key unfolds into a form with scopes and environment, each new secret is shown once, and keys revoke with hold to confirm. Keys and secrets are simulated.

No props.

### Dependencies

- `motion`
- `lucide-react`

### Keyboard

| Keys | Action |
| --- | --- |
| Escape | Closes the create key form and returns focus to its button. |

### Accessibility

- Each key opens a labelled role="region" detail panel.
- Revoke uses hold to confirm, so it cannot fire from a stray click.
- Creation, copy, and revoke results are announced in a polite status region.

### Motion

- The Create key button unfolds into its form, and new keys slide into the list.
- Reduced motion replaces the unfold with an instant swap.

### Responsive behavior

- Below 700px container width key rows stack scopes and dates under the name; below 540px detail facts go single column.
- The create form drops to one column below 560px of its own width.

### Performance

- Key rows are not virtualized, which suits the handful of keys most accounts have.
- A ResizeObserver drives the create button's unfold into the form.

### Notes for AI agents

- Use on the developer settings page of an API product.
- Create keys on your server and pass the one-time secret to the reveal step; never store it client side.
- Connect hold to revoke to your revocation endpoint. Composes Arc hold-to-confirm, copy-button, input, segmented-control, checkbox, badge, avatar, and button.

### Keywords

react api keys, api key management, developer settings, create api key, revoke api key, secret reveal, token management

### Related

- webhooks
- integrations
- hold-to-confirm
- copy-button
- roles-permissions

---

## Inbox sidebar

A mail sidebar whose Compose button grows into a composer and whose folders take dropped mail.

- Type: Block (composition)
- Access: Pro
- Built from: Avatar, Animated counter, Tooltip, Button
- Documentation: https://uiarc.dev/components/blocks/inbox-sidebar

### Overview

Use this as the shell of a mail or messaging app. Load folders, labels, and messages from your mail API, persist moves and stars through it, and connect Send and drafts to your outbox; sending and saving in the preview are simulated.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/inbox-sidebar. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/inbox-sidebar while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- The shell of a mail or messaging app.
- Inboxes where messages are dragged onto folders.
- Mail clients with row quick actions and a compose window.

### When not to use

- Use inbox-triage for a focused one-at-a-time triage flow.
- Use notification-center for app notifications.
- Use workspace-sidebar for general app navigation.

### Usage

```tsx
import { InboxSidebar } from "@/components/arc/blocks/inbox-sidebar/inbox-sidebar";

export default function MailPage() {
  return (
    <InboxSidebar
      onCollapsedChange={(collapsed) => localStorage.setItem("mail-rail", String(collapsed))}
    />
  );
}
```

### API

#### InboxSidebar

A mail shell with folders, labels, a message list you can drag onto folders, row quick actions, and a Compose button that grows into a composer. Folders, messages, and sending are simulated.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `defaultCollapsed` | `boolean` | `false` | Start with the sidebar collapsed to its icon rail. |
| `onCollapsedChange` | `(collapsed: boolean) => void` |  | Called when the sidebar collapses or expands, from the toggle or the [ shortcut. |

### Dependencies

- `motion`
- `lucide-react`
- `@radix-ui/react-dropdown-menu`
- `@radix-ui/react-tooltip`

### Keyboard

| Keys | Action |
| --- | --- |
| [ | Toggles the icon rail when focus is not in a text field, menu, or dialog. |
| E | On a message row, archives or moves it with its quick action. |
| S | On a message row, toggles the star. |
| Cmd/Ctrl+Enter | Sends from the composer. |
| Escape | Closes the composer and saves a draft, or cancels a drag in progress. |

### Accessibility

- The composer is a role="dialog" labelled by its title.
- Moves, stars, and sends are announced through a polite status region, and rail icons have tooltips.
- Every drag action has a keyboard or menu alternative.

### Motion

- Compose grows into the composer through a shared layoutId, and unread counts roll.
- Dropped messages leave the list with layout animation while the target folder pulses.
- Reduced motion makes the morph and list changes instant.

### Responsive behavior

- Below 720px container width the sidebar is locked to its 64px icon rail; below 420px row labels are hidden.
- Dragging to folders works with a mouse only; touch uses the row menu and quick actions.

### Performance

- The shell is a fixed 660px tall and the message list is not virtualized; page long mailboxes.
- Sidebar width springs through one motion value, and a ResizeObserver detects the narrow layout.

### Notes for AI agents

- Use as the shell of a mail or messaging app.
- Load folders, labels, and messages from your mail API, persist moves and stars through it, and connect Send and drafts to your outbox.
- Composes Arc avatar, animated-counter, tooltip, and button.

### Keywords

react email client, inbox ui, mail sidebar, gmail clone, drag to folder, compose window, mail app layout

### Related

- inbox-triage
- workspace-sidebar
- sidebar-rail
- notification-center
- swipe-actions

---

## Team members

A members list where typed emails turn into chips and fly into pending invites as seats roll.

- Type: Block (composition)
- Access: Pro
- Built from: Avatar, Button, Search field, Text morph, Animated counter
- Documentation: https://uiarc.dev/components/blocks/team-members

### Overview

Use this on the team or workspace settings page of a SaaS app. Load members, invites, and seat limits from your API and connect role changes, Send invite, Resend, Revoke, and Remove to it; every invite and removal in the preview is simulated.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/team-members. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/team-members while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- The team or workspace settings page of a SaaS app.
- Inviting several people at once by typing or pasting emails.
- Member lists with roles, pending invites, and seat counts.

### When not to use

- Use team-directory for a browsable people directory.
- Use roles-permissions to define what each role can do.
- Use tag-input for a general chip input outside invites.

### Usage

```tsx
import { TeamMembers } from "@/components/arc/blocks/team-members/team-members";

export default function TeamSettings() {
  return (
    <main>
      <TeamMembers />
    </main>
  );
}
```

### API

#### TeamMembers

A members list with an invite field that turns typed emails into chips, pending invites, role selects, seat counts, and confirm to remove. Members, invites, and seats are simulated.

No props.

### Dependencies

- `motion`
- `lucide-react`
- `@radix-ui/react-select`

### Keyboard

| Keys | Action |
| --- | --- |
| Enter | Turns the typed email into a chip, or sends invites when the field is empty. |
| , / ; / Space | Commits the typed email as a chip. |
| Backspace | Removes the last chip when the field is empty. |
| Escape | Cancels a pending member removal. |

### Accessibility

- Role selects use Radix select with full keyboard support.
- Invite validation messages sit in a polite live region, and actions are announced in a status region.

### Motion

- Email chips fly into the pending invites list and the seat count rolls.
- Rows enter and leave with layout animation.
- Reduced motion makes the flight and reflow instant.

### Responsive behavior

- Below 600px container width the header and invite row stack and the search goes full width.
- Below 420px each member row splits into the identity on top and last active, role, and remove underneath.

### Performance

- Member rows are not virtualized; add paging for large organizations.
- Rows enter and leave with layout animation, and a ResizeObserver drives the height morph.

### Notes for AI agents

- Use on the team or workspace settings page of a SaaS app.
- Load members, invites, and seat limits from your API and connect role changes, Send invite, Resend, Revoke, and Remove to it.
- Composes Arc avatar, button, search-field, text-morph, and animated-counter.

### Keywords

react team members, invite team members, member management, user roles table, invite by email, seat management, workspace members

### Related

- team-directory
- roles-permissions
- tag-input
- settings-page
- avatar

---

## Page header

A project page header that folds into a compact bar as you scroll, with tabs whose counts roll.

- Type: Block (composition)
- Access: Free
- Built from: Button, Badge, Animated counter, Avatar group, Avatar, Progress
- Documentation: https://uiarc.dev/components/blocks/page-header

### Overview

Use this at the top of a project, repository, or record page. Connect breadcrumbs to your router, tab counts and status to your data, and Follow, Share update, New issue, and Archive to your API; every action in the preview is simulated.

### Install

```bash
npx shadcn@latest add https://uiarc.dev/r/page-header.json
```

With `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`: `npx shadcn@latest add @uiarc/page-header`

### When to use

- The top of a project, repository, or record page with breadcrumbs, status, people, and tabs.
- Detail pages with long content where the header should fold into a compact bar as people scroll.
- Headers that need a few primary actions plus an overflow menu for the rest.

### When not to use

- Use tabs and breadcrumb on their own when the page only needs navigation, not status and people.
- Use workspace-sidebar for app-level navigation between sections.
- Use settings-page for settings screens that need a section nav rather than a record header.

### Usage

```tsx
import { PageHeader } from "@/components/arc/blocks/page-header/page-header";

export default function ProjectPage() {
  return (
    <main>
      <PageHeader />
    </main>
  );
}
```

### API

#### PageHeader

A self-contained project header with breadcrumbs, status, members, progress, tabs and an actions menu that condenses into a compact bar on scroll. The project, people, tabs and counts are sample data declared at the top of page-header.tsx.

No props.

### Dependencies

- `motion`
- `lucide-react`
- `@radix-ui/react-tabs`
- `@radix-ui/react-dropdown-menu`

### Keyboard

| Keys | Action |
| --- | --- |
| Arrow keys | Move between tabs (Radix tabs) and through the actions menu, which loops. |
| Enter / Space | Activates the focused tab or menu item. |

### Accessibility

- Tabs use Radix roles (tab, tabpanel) and the current breadcrumb carries aria-current.
- The icon-only actions trigger has aria-label="More actions"; disabled items use aria-disabled.
- A polite role="status" region announces results of Follow, Share, Copy link and Archive.

### Motion

- Past a short scroll threshold the header folds into a compact bar; the tab indicator glides with a shared layoutId and counts roll with Animated counter.
- Reduced motion swaps springs for fades, uses instant scroll instead of smooth, and keeps widths static.

### Responsive behavior

- A ResizeObserver moves secondary actions into the menu when the action row runs out of room.
- Below a 560px container the root breadcrumb hides, the tab row scrolls sideways with a faded edge, and below 460px the create button drops to an icon.
- The header condenses from the scroll of its own inner scroller, not the window, so page content must live inside that scroller.

### Performance

- Scroll handling only compares scrollTop to a 16px threshold, so it re-renders when crossing it, not on every frame.
- Tab counts roll with Animated counter and the tab indicator uses a shared layoutId; both are cheap at a handful of tabs.

### Notes for AI agents

- Use at the top of a project, repository or record page that scrolls beneath it.
- The block takes no props: replace the in-file project, people and tab data with your own, or lift them into props.
- Follow, Share update, Copy link, New issue and Archive are simulated; wire them to your API and the breadcrumbs to your router.
- Composes Arc Button, Badge, Animated counter, Avatar, Avatar group and Progress.

### Keywords

react page header, project header, sticky header on scroll, condensing header, record header with tabs, breadcrumb header, page title with actions

### Related

- tabs
- breadcrumb
- avatar-group
- dropdown-menu
- workspace-sidebar

---

## Revenue explorer

A SaaS revenue chart you zoom with a brush while paths, axes and figures glide to the range.

- Type: Block (composition)
- Access: Pro
- Built from: Animated counter
- Documentation: https://uiarc.dev/components/blocks/revenue-explorer

### Overview

Use this for MRR or other monthly flow metrics on an analytics page. Replace the seeded months in revenue-data.ts with your billing data; the chart, brush and comparison compute everything from that series.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/revenue-explorer. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/revenue-explorer while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- Monthly MRR or revenue broken into new, expansion, and churn on an analytics page.
- Charts where people need to zoom a date range with an overview brush and compare against a prior period.

### When not to use

- Use mrr-waterfall to explain how MRR moved between two points in time.
- Use metric-explorer for a row of KPI cards that open into a chart.
- Use bar-chart or sparkline for a small chart inside a card.

### Usage

```tsx
import { RevenueExplorer } from "@/components/arc/blocks/revenue-explorer/revenue-explorer";

export default function AnalyticsPage() {
  return (
    <section>
      <RevenueExplorer />
    </section>
  );
}
```

### API

#### RevenueExplorer

A monthly revenue chart with series toggles, a comparison mode, a hover scrubber and an overview brush that zooms the range. All figures derive from the seeded months in revenue-data.ts.

No props.

### Dependencies

- `motion`
- `lucide-react`

### Keyboard

| Keys | Action |
| --- | --- |
| Arrow keys | On the plot, step the scrubbed month. On the brush or its handles, move the window or one edge by a month. |
| Shift + Arrow keys | Move the brush or a handle by three months. |
| Home / End | Jump to the range start or end (plot), or to the timeline edges (brush). |
| Escape | Clears the scrubbed month on the plot. |

### Accessibility

- The brush window and both handles are role="slider" with aria-valuenow and month-name aria-valuetext.
- Series toggles use aria-pressed and the comparison toggle is a role="switch" with aria-checked.
- The plot is a focusable role="img" with aria-describedby pointing at the live summary.

### Motion

- Paths, axes and ticks glide to the new range on springs while totals roll with Animated counter.
- Reduced motion jumps values instantly and replaces movement with opacity changes.

### Responsive behavior

- Chart width follows its container through a ResizeObserver, so axes and paths recompute at any width.
- Below a 560px container padding tightens and the comparison context wraps under the KPIs.
- The plot uses touch-action pan-y so vertical page scroll still works, while the brush uses touch-action none and pointer capture for dragging.

### Performance

- Geometry is computed from 24 months of data; paths and ticks animate on springs rather than a per-frame loop.
- It is SVG with no downsampling, so long daily series should be aggregated to months before passing them in.

### Notes for AI agents

- Use for MRR or other monthly flow metrics (new, expansion, churn) on an analytics page.
- Replace DATA and the month calendar in revenue-data.ts with your billing series; geometry, summaries and y domains are computed from it.
- No props or callbacks; lift the data into props if you load it at runtime.

### Keywords

react revenue chart, mrr chart, chart with brush zoom, range selector chart, saas analytics chart, comparison line chart, interactive area chart

### Related

- metric-explorer
- mrr-waterfall
- usage-forecast
- cohort-retention
- animated-counter

---

## Journey flow

A Sankey of user journeys whose flows morph by channel and trace a cohort on hover.

- Type: Block (composition)
- Access: Pro
- Built from: Arc foundation
- Documentation: https://uiarc.dev/components/blocks/journey-flow

### Overview

Use this to show where users go between funnel steps on an analytics page. Replace the link counts in journey-flow-geometry.ts with your own; layout, tracing and rates are computed from them.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/journey-flow. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/journey-flow while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- Showing where users go between funnel stages, such as visit to signup to activation.
- Comparing flows across acquisition channels with a segment switch.
- Tracing one step to see which paths lead into and out of it.

### When not to use

- Use cohort-retention to show how groups retain over time.
- Use bar-chart for a simple linear funnel without branching paths.
- Use metrics-dashboard for a general KPI overview.

### Usage

```tsx
import { JourneyFlow } from "@/components/arc/blocks/journey-flow/journey-flow";

export default function FunnelPage() {
  return <JourneyFlow className="funnel" />;
}
```

### API

#### JourneyFlow

A Sankey of trial journeys across funnel stages. A channel switch morphs every band, hovering a step or band traces that cohort through the whole journey with a tooltip, and selecting a step pins its breakdown in a side panel with rolling counts. A data table toggle shows the same numbers. Nodes, links, and per-segment counts are sample data in journey-flow-geometry.ts.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` |  | Appended to the root element. |

### Dependencies

- `motion`
- `lucide-react`

### Keyboard

| Keys | Action |
| --- | --- |
| Arrow keys | In the segment switch, move between channels. On steps, Up/Down moves within a stage and Left/Right to the nearest step in the next or previous stage. |
| Home / End | Jump to the first or last step. |
| Enter / Space | Selects a step to trace its flows. |
| Escape | Clears the traced step. |

### Accessibility

- Segments form a role="radiogroup"; steps sit in a role="toolbar" with roving tabIndex and aria-pressed.
- The diagram is role="img" with a text summary; each step button's label includes its users and share of visitors.
- A polite live region announces visits and paid plans when the channel changes.
- The breakdown panel is a labelled aside, and the data table toggle exposes aria-expanded for a non-visual reading of the chart.

### Motion

- Ribbons morph their widths on a spring slightly slower than a control when the segment changes; counts follow a beat later and never overshoot.
- Tracing dims everything outside the cohort; panel text settles with a short rise and digits roll in place.
- Reduced motion swaps the morph for an instant change with an opacity fade.

### Responsive behavior

- From an 860px container the detail panel sits beside the chart at 280px; below that it moves under the chart.
- Below 560px the segment switch fills the width and padding tightens, and below 480px step labels shrink to 10 to 11px.
- A ResizeObserver feeds the chart width, so ribbons re-lay out on resize rather than scaling.

### Performance

- Ribbons are SVG paths computed from 13 sample nodes; very large graphs with many stages will get crowded and slower to morph.
- Segment changes morph ribbon widths on springs, with no loop running at rest.

### Notes for AI agents

- Use to show where users go between funnel steps on an analytics page.
- Replace NODES, STAGES, LINKS and SEGMENTS in journey-flow-geometry.ts with your counts; layout, tracing and percentages are computed.
- No callbacks; selection is internal.

### Keywords

react sankey diagram, user journey flow, funnel flow chart, sankey chart, conversion paths, user flow visualization

### Related

- metrics-dashboard
- cohort-retention
- revenue-explorer
- segmented-control

---

## Empty states

Four empty states in one illustration whose shapes morph between scenes as you switch tabs.

- Type: Block (composition)
- Access: Free
- Built from: Arc foundation
- Documentation: https://uiarc.dev/components/blocks/empty-states

### Overview

Use this for no results, offline, inbox zero and missing page moments. Wire each action to your real filter reset, retry, refresh or search; the preview simulates them locally.

### Install

```bash
npx shadcn@latest add https://uiarc.dev/r/empty-states.json
```

With `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`: `npx shadcn@latest add @uiarc/empty-states`

### When to use

- A reference for no results, offline, inbox zero, and 404 moments with one shared illustration style.
- Extracting one scene as a richer empty state for a key screen.

### When not to use

- Use empty-state for a simple empty state with an icon, text, and action.
- Use onboarding-illustration for first-run screens that teach the product.
- Use skeleton while content is still loading.

### Usage

```tsx
import { EmptyStates } from "@/components/arc/blocks/empty-states/empty-states";

export default function EmptyGallery() {
  return (
    <main>
      <EmptyStates />
    </main>
  );
}
```

### API

#### EmptyStates

Four empty states (no results, offline, inbox zero, missing page) in one illustration that morphs between scenes via tabs, each with a simulated action. Scene copy is in empty-states.tsx and shapes in empty-states-art.ts.

No props.

### Dependencies

- `motion`

### Keyboard

| Keys | Action |
| --- | --- |
| Left / Right | Move between scene tabs (wraps around). |
| Home / End | Jump to the first or last scene. |

### Accessibility

- Scenes use role="tablist", "tab" and "tabpanel" with aria-selected and aria-controls.
- The illustration is a role="img" labelled by the scene; a polite live region reports action results.

### Motion

- Each shape morphs its path to the next scene with slight per-shape delays, and the tab indicator glides with a layoutId.
- Reduced motion swaps scenes with a short fade and no morph.

### Responsive behavior

- The block is a container query root; from a 560px container the title steps up a size.
- Pointer parallax only turns on for hover-capable fine pointers, so touch devices get a still illustration.

### Performance

- Shape morphs run on a small requestAnimationFrame loop that stops as soon as every shape settles.
- A ResizeObserver springs the copy height when scenes change.

### Notes for AI agents

- Use as a reference for no results, offline, inbox zero or 404 moments; usually you extract one scene rather than ship the tabbed gallery.
- Actions (clear filters, retry, refresh, search) are simulated; wire them to your real handlers.
- For a single simple empty state, prefer the empty-state component.

### Keywords

react empty state, empty state illustration, no results state, offline state, 404 page illustration, inbox zero, morphing svg illustration

### Related

- empty-state
- onboarding-illustration
- tabs

---

## Centered login

A passkey-first login card on a quiet ring backdrop that morphs through email and code.

- Type: Block (composition)
- Access: Free
- Built from: Button, Input, OTP input
- Documentation: https://uiarc.dev/components/blocks/login-centered

### Overview

Use this as a full screen sign in page (pass fullScreen). Connect the passkey button to WebAuthn, the email step to your magic code sender, the code step to verification, and the SSO buttons to your OAuth routes; onSignIn receives the email, method and mode.

### Install

```bash
npx shadcn@latest add https://uiarc.dev/r/login-centered.json
```

With `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`: `npx shadcn@latest add @uiarc/login-centered`

### When to use

- A full screen sign in or sign up page where passkeys are the main method.
- Auth flows that fall back to a six digit email code.
- Products that want one card for both sign in and sign up.

### When not to use

- Use login-split for password sign in beside a brand photo.
- Use login-immersive for magic link auth over a full-bleed photo.
- Use sign-in for a simpler embedded sign in form.

### Usage

```tsx
import { LoginCentered } from "@/components/arc/blocks/login-centered/login-centered";
import { useRouter } from "next/navigation";

export default function SignInPage() {
  const router = useRouter();
  return (
    <LoginCentered
      fullScreen
      termsHref="/terms"
      privacyHref="/privacy"
      onSignIn={() => router.push("/app")}
    />
  );
}
```

### Examples

#### Route sign ups to onboarding

```tsx
<LoginCentered
  fullScreen
  onSignIn={(email, method, mode) =>
    router.push(mode === "sign-up" ? "/welcome" : "/app")
  }
/>
```

### API

#### LoginCentered

A passkey-first sign in and sign up card on a ring backdrop that morphs through email and a six digit code. Passkey, email delivery and SSO are simulated.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `fullScreen` | `boolean` | `false` | Fill the viewport (100dvh, no frame) when the block is the whole page. |
| `onSignIn` | `(email: string, method: LoginMethod, mode: "sign-in" \| "sign-up") => void` |  | Called once the simulated sign in or sign up succeeds. LoginMethod is "Passkey" \| "Email code" \| "Google" \| "Apple" \| "GitHub". |
| `demoCode` | `string` | `"482913"` | The code the simulated email contains. |
| `demoEmail` | `string` | `"maya@northwind.studio"` | The account a simulated passkey or single sign-on resolves to. |
| `termsHref` | `string` | `"#terms"` | Terms link in the footer. |
| `privacyHref` | `string` | `"#privacy"` | Privacy link in the footer. |
| `className` | `string` |  | Appended to the root element. |

### Dependencies

- `motion`
- `lucide-react`

### Accessibility

- The email field uses autoComplete="email" and the code step uses the OTP input group.
- Busy buttons use aria-busy and aria-disabled so focus stays put during simulated requests.
- A polite role="status" region announces step changes and errors.

### Motion

- Steps slide and blur between passkey, email, code and done while the card height follows; the resend label rolls.
- Reduced motion swaps slides for fades and shows the passkey check without drawing its stroke.

### Responsive behavior

- Below a 520px container the stage and card padding shrink, and below 400px the SSO buttons tighten to small text.
- Pass fullScreen to fill 100dvh; without it the block sits in a framed card.
- The ring backdrop drifts with the pointer only while it moves over the screen, and stays still on touch and under reduced motion.

### Performance

- The backdrop is a light SVG ring set moved by CSS variables from motion values, with no re-render per pointer move.
- Only the active step is mounted; the card height animates as steps change.

### Notes for AI agents

- Use as a full screen sign in page (pass fullScreen) when passkeys are the primary method.
- Connect the passkey button to WebAuthn, the email step to your code sender, the code step to verification and SSO buttons to OAuth routes; demoCode and demoEmail exist only for the simulation.
- onSignIn receives the email, method and mode; redirect from there.
- Composes Arc Button, Input and OTP input.

### Keywords

react login page, passkey login, sign in page, otp email login, webauthn sign in ui, sign up page, auth card

### Related

- sign-in
- login-split
- login-immersive
- signup-form
- otp-input

---

## Immersive login

A glass magic link card over dusk photography that folds its envelope shut once sent.

- Type: Block (composition)
- Access: Pro
- Built from: Button, Input
- Documentation: https://uiarc.dev/components/blocks/login-immersive

### Overview

Use this as a full screen sign in or sign up page (pass fullScreen). Connect the email form to your magic link sender, Open mail app to a mailto or deep link, and the SSO buttons to your OAuth routes; onSignIn receives the email and method.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/login-immersive. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/login-immersive while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- A magic link sign in page with a strong brand photo behind a glass card.
- Consumer or creative products where the sign in screen carries the brand mood.

### When not to use

- Use login-centered for passkey-first auth with an email code.
- Use login-split for password sign in with a quieter layout.
- Use sign-in when the form sits inside an existing page.

### Usage

```tsx
import { LoginImmersive } from "@/components/arc/blocks/login-immersive/login-immersive";

export default function SignInPage() {
  return (
    <LoginImmersive
      fullScreen
      termsHref="/terms"
      privacyHref="/privacy"
      onSignIn={(email, method) => console.log(email, method)}
    />
  );
}
```

### API

#### LoginImmersive

A glass magic link card over a full-bleed photo whose envelope folds shut once the link is sent. The photo is imported from public/media/photos/mountain-ridges.jpg; sending and SSO are simulated.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `fullScreen` | `boolean` | `false` | Fill the viewport (100dvh, square corners) when the block is the whole page. |
| `onSignIn` | `(email: string, method: LoginImmersiveMethod) => void` |  | Called once the simulated sign in succeeds. LoginImmersiveMethod is "Magic link" \| "Google" \| "Apple" \| "GitHub". |
| `resendSeconds` | `number` | `30` | Seconds before another link can be sent. |
| `termsHref` | `string` |  | Terms link. Without it the preview explains where the link would go. |
| `privacyHref` | `string` |  | Privacy link. Without it the preview explains where the link would go. |

### Dependencies

- `motion`
- `lucide-react`

### Accessibility

- The email field uses autoComplete="email" and SSO buttons sit in a labelled role="group".
- Busy actions use aria-disabled rather than disabled so focus is kept.
- A polite role="status" region announces when the link is sent and resend availability.

### Motion

- After sending, the form gives way to an envelope that folds shut and the resend countdown rolls.
- Reduced motion replaces the fold and slides with fades.

### Responsive behavior

- The card is min(100%, 420px) wide; below a 380px card width its padding and heading shrink and the SSO buttons tighten.
- Below a 520px container the top bar and footer padding shrink.
- The photo uses next/image with fill and sizes 100vw, so it covers any viewport.

### Performance

- The photo loads eagerly with a blur placeholder; use a well compressed image since it is the largest asset.
- The card uses backdrop blur, which falls back to a solid surface where backdrop-filter is not supported.

### Notes for AI agents

- Use as a full screen sign in or sign up page for magic link auth with a strong brand photo.
- Replace the imported photo with your own, connect the email form to your magic link sender, Open mail app to a mailto or deep link, and SSO to OAuth routes.
- Uses next/image; composes Arc Button and Input.

### Keywords

react magic link login, passwordless sign in, login page with background image, glass login card, email link sign in, full screen login

### Related

- login-centered
- login-split
- sign-in
- signup-form

---

## Security settings

An account security page with guided two-factor setup, password change and active sessions.

- Type: Block (composition)
- Access: Pro
- Built from: Button, Badge, Checkbox, Copy button, Hold to confirm, OTP input, Password field, Password strength
- Documentation: https://uiarc.dev/components/blocks/security-settings

### Overview

Use this as the security tab of account settings. Connect Verify to your TOTP check, the backup codes to your generator, Update password to your password endpoint, and Revoke and Sign out to your session API.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/security-settings. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/security-settings while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- The security tab of account settings with two-factor setup, password change, and sessions.
- Guided TOTP setup that walks through scan, verify, and backup codes.

### When not to use

- Use settings-page for general account and workspace settings.
- Use api-keys for managing developer tokens.
- Use audit-log for the history of security events.

### Usage

```tsx
import { SecuritySettings } from "@/components/arc/blocks/security-settings/security-settings";

export default function SecurityTab() {
  return (
    <section>
      <SecuritySettings />
    </section>
  );
}
```

### API

#### SecuritySettings

An account security page with guided two-factor setup (scan, verify, backup codes), password change with strength meter, and active sessions you can revoke. Account, setup key, demo code (246810), backup codes and initialSessions are sample data in security-settings.tsx.

No props.

### Dependencies

- `motion`
- `lucide-react`

### Accessibility

- Password errors render in a role="alert" linked with aria-describedby and aria-invalid; the field uses autoComplete="current-password".
- After revoking a session, focus moves to the neighbouring Revoke button or the sessions heading.
- A polite live region announces saves, verification and session changes.

### Motion

- Two-factor steps advance along a rail with a gliding marker, and sections expand with a height spring.
- Reduced motion uses instant transitions and skips height animation.

### Responsive behavior

- Below a 640px container backup codes drop to two columns.
- Below 560px the QR code stacks above the setup key and section padding tightens.

### Performance

- Sections are plain DOM with height springs when expanding; there is no loop or observer cost.
- The session list is not virtualized, which is fine for the handful of sessions an account normally has.

### Notes for AI agents

- Use as the security tab of account settings.
- Verification, backup code download, password update and session revoke are simulated with timers; replace them with your TOTP check, code generator, password endpoint and session API.
- Replace the in-file ACCOUNT, SETUP_KEY, QR pattern and initialSessions with real data from props or a fetch.
- Composes Arc Button, Badge, Checkbox, Copy button, Hold to confirm, OTP input, Password field and Password strength.

### Keywords

react security settings, two factor setup, 2fa setup flow, totp qr code setup, active sessions list, change password form, backup codes

### Related

- settings-page
- api-keys
- password-strength
- otp-input

---

## Cancel flow

A cancellation flow that answers each reason with a tailored offer and a calm hold-to-cancel.

- Type: Block (composition)
- Access: Pro
- Built from: Button, Badge, Avatar, Textarea, Animated counter, Hold to confirm
- Documentation: https://uiarc.dev/components/blocks/cancel-flow

### Overview

Use this in billing settings when someone cancels a subscription. Connect each offer's accept to your discount, pause or plan change API, the hold to your cancel endpoint, and the note to your feedback store; the preview simulates them.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/cancel-flow. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/cancel-flow while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- Subscription cancellation in billing settings with a reason step and a retention offer.
- Flows that offer a discount, pause, or downgrade before confirming the cancel.

### When not to use

- Use dialog with hold-to-confirm for a one step destructive action without offers.
- Use plan-comparison when people are choosing a plan rather than leaving.
- Use billing-overview for the billing page itself.

### Usage

```tsx
import { CancelFlow } from "@/components/arc/blocks/cancel-flow/cancel-flow";

export default function CancelPage() {
  return (
    <main>
      <CancelFlow />
    </main>
  );
}
```

### API

#### CancelFlow

A three step subscription cancellation (reason, tailored offer, confirm) that ends in a hold-to-cancel. Reasons, offers, price, resume dates and impacts are sample data in cancel-flow.tsx.

No props.

### Dependencies

- `motion`
- `lucide-react`

### Keyboard

| Keys | Action |
| --- | --- |
| Arrow keys | Move between reason cards and select them (wraps around). |
| Home / End | Select the first or last reason; on the pause offer, set the shortest or longest pause. |
| Up / Down, Left / Right | On the pause offer, change the pause length between one and three months. |

### Accessibility

- Reasons form a role="radiogroup" with aria-checked cards.
- The pause length is a role="spinbutton" whose aria-valuetext includes the resume date.
- A polite role="status" region announces offer changes and the outcome.

### Motion

- Steps slide between reason, offer and confirm, the selection highlight glides with a layoutId, and prices roll with Animated counter.
- Reduced motion swaps slides for fades and figures change without rolling.

### Responsive behavior

- Below a 520px container the reason cards drop to one column and the action buttons fill the width.
- The final hold works with mouse, touch, and keyboard through hold-to-confirm.

### Performance

- Only the current step is mounted; prices roll with Animated counter.
- No observers or loops; the cost is a few spring transitions per step change.

### Notes for AI agents

- Use in billing settings when someone cancels a subscription.
- Connect each offer's accept to your discount, pause or plan change API, the hold to your cancel endpoint and the note to your feedback store; all are simulated.
- Edit REASONS, PRICE, RESUME and IMPACTS in cancel-flow.tsx to match your plans.
- Composes Arc Button, Badge, Avatar, Textarea, Animated counter and Hold to confirm.

### Keywords

react cancel subscription flow, churn prevention flow, cancellation survey, retention offer, pause subscription, cancel flow saas

### Related

- billing-overview
- plan-comparison
- hold-to-confirm
- stepper

---

## Login split

A full screen split login: an email-first form that morphs into a password step beside a photo.

- Type: Block (composition)
- Access: Pro
- Built from: Button, Input, Password field, Avatar
- Documentation: https://uiarc.dev/components/blocks/login-split

### Overview

Use this as your sign in page with fullScreen. Connect Continue to your account lookup, Sign in and the SSO buttons to your auth provider, Forgot password to your reset email, and pass links for sign up, terms and privacy.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/login-split. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/login-split while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- Password-based sign in with an email-first step beside a brand photo.
- Sign in pages that should show the recognised account before asking for a password.

### When not to use

- Use login-centered for passkey-first auth.
- Use login-immersive for magic link auth.
- Use signup-form for account creation.

### Usage

```tsx
import { LoginSplit } from "@/components/arc/blocks/login-split/login-split";

export default function SignInPage() {
  return (
    <LoginSplit
      fullScreen
      links={{ signUp: "/sign-up", terms: "/terms", privacy: "/privacy" }}
      onSignIn={(account, method) => console.log(account.email, method)}
    />
  );
}
```

### Examples

#### Real links

```tsx
<LoginSplit
  fullScreen
  links={{ signUp: "/sign-up", terms: "/terms", privacy: "/privacy" }}
  onSignIn={account => router.push("/app")}
/>
```

### API

#### LoginSplit

A split sign in screen: an email-first form that morphs into a password step beside a photo. Accounts are the sample people list in login-split.tsx with portraits from public/media/people, and the photo is imported from public/media/photos/concert-hall.jpg.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `fullScreen` | `boolean` | `false` | Fill the viewport (100dvh, no frame) when the screen is used as a page. |
| `onSignIn` | `(account: LoginSplitAccount, method: LoginSplitMethod) => void` |  | Called once the simulated sign in finishes. LoginSplitAccount is { name, email, photo? }; LoginSplitMethod is "Password" \| "Google" \| "Apple" \| "GitHub". |
| `demoPassword` | `string` | `"arc-demo"` | The password the simulated account accepts. |
| `links` | `Partial<Record<"signUp" \| "terms" \| "privacy", string>>` |  | Real destinations for the small links. Without them each link announces a simulated action. |

### Dependencies

- `motion`
- `lucide-react`

### Accessibility

- Fields use autoComplete="username" and "current-password"; errors render in a role="alert" tied with aria-describedby and aria-invalid.
- SSO buttons sit in a labelled role="group".
- A polite role="status" region announces step changes and simulated link actions.

### Motion

- Continue morphs the email form into the password step with the account avatar, and labels roll between states.
- Reduced motion uses fades and shortens the simulated delays.

### Responsive behavior

- Below a 760px container the photo stacks under the form at a 460px minimum height; from 760px they sit side by side.
- From 1100px the columns split 5 to 6 and the quote moves to the photo's lower left.
- The photo uses sizes that request 100vw below 760px and 50vw above.

### Performance

- The photo drifts on a 36 second CSS animation that people can pause, and it is off under reduced motion.
- The photo loads through next/image with a blur placeholder; there are no scripts running while idle.

### Notes for AI agents

- Use as a password-based sign in page with fullScreen.
- Connect Continue to your account lookup, Sign in and SSO to your auth provider, and Forgot password to your reset email; replace the sample people list and the imported photo.
- Pass links for sign up, terms and privacy; onSignIn receives the account and method.
- Uses next/image; composes Arc Button, Input, Password field and Avatar.

### Keywords

react split login page, login with image, email first login, password sign in page, two column login, sign in screen

### Related

- login-centered
- login-immersive
- sign-in
- signup-form
- password-field

---

## Cohort retention

A cohort retention triangle that morphs into retention curves and rewashes by segment.

- Type: Block (composition)
- Access: Pro
- Built from: Segmented control, Animated counter
- Documentation: https://uiarc.dev/components/blocks/cohort-retention

### Overview

Use this on a growth or customer success dashboard to compare how signup cohorts retain. Replace simulate() in cohort-data.ts with your cohort sizes and retained counts per month; rates, averages, headline figures and deltas are derived from them.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/cohort-retention. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/cohort-retention while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- Growth or customer success dashboards comparing how signup cohorts retain month over month.
- Views that need both the cohort triangle and retention curves from the same data.

### When not to use

- Use journey-flow for paths between funnel steps.
- Use activity-heatmap for activity by day rather than by cohort.
- Use revenue-explorer for revenue over time.

### Usage

```tsx
import { CohortRetention } from "@/components/arc/blocks/cohort-retention/cohort-retention";

export default function GrowthPage() {
  return (
    <section>
      <CohortRetention />
    </section>
  );
}
```

### API

#### CohortRetention

A cohort retention triangle that morphs into retention curves, with segment filters and a keyboard-navigable cell cursor. Cohort sizes and retained counts come from simulate() in cohort-data.ts.

No props.

### Dependencies

- `motion`
- `lucide-react`

### Keyboard

| Keys | Action |
| --- | --- |
| Arrow keys | Move the cell cursor between cohorts (rows) and months (columns). |
| Home / End | Jump to the first or last month of the current cohort. |
| Escape | Clears the cursor. |

### Accessibility

- The chart is a focusable role="group" with aria-describedby, and a polite live region reads the focused cohort, month and rate.
- Decorative cells and curves are aria-hidden; the legend is a labelled role="img".

### Motion

- Cells morph into curves on the view switch and rewash their colour when the segment changes; headline figures roll with Animated counter.
- Reduced motion jumps values instantly and follows the pointer without springs.

### Responsive behavior

- Chart geometry follows container width through a ResizeObserver.
- Below a 560px container padding tightens and the KPI context wraps.
- The chart uses touch-action pan-y, so touch scrubbing does not block vertical page scroll.

### Performance

- The triangle is 12 cohorts by 12 months of SVG cells; much larger grids mean many more animated cells.
- Cell colour changes use CSS transitions with a stagger instead of JavaScript per cell.

### Notes for AI agents

- Use on a growth or customer success dashboard to compare how signup cohorts retain.
- Replace simulate() in cohort-data.ts with your cohort sizes and monthly retained counts; rates, averages and deltas are derived.
- Edit SEGMENTS in cohort-data.ts to match your segments. No props or callbacks.
- Composes Arc Segmented control and Animated counter.

### Keywords

react cohort retention chart, retention triangle, cohort analysis table, retention curves, churn cohort heatmap, saas retention chart

### Related

- revenue-explorer
- journey-flow
- metrics-dashboard
- activity-heatmap
- segmented-control

---

## Support widget

An in-app help launcher that grows into live article search, reading, and a chat with your team.

- Type: Block (composition)
- Access: Pro
- Built from: Search field, Avatar, Button, Text morph, Animated counter
- Documentation: https://uiarc.dev/components/blocks/support-widget

### Overview

Use this as the help entry point inside a SaaS app. Load articles from your help center into support-widget-data.ts and connect onSend to your inbox or chat provider; replies in the preview are simulated.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/support-widget. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/support-widget while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- An in-app help launcher with article search, an article reader, and chat.
- SaaS products that want one help entry point mounted near the app root.

### When not to use

- Use support-conversation for a full page support chat.
- Use ai-composer for an AI prompt input without help articles.
- Use popover for a small anchored tip.

### Usage

```tsx
import { SupportWidget } from "@/components/arc/blocks/support-widget/support-widget";

export function AppShell() {
  return (
    <SupportWidget
      onSend={message => sendToInbox(message)}
      onOpenChange={open => track(open ? "help_opened" : "help_closed")}
    />
  );
}
```

### API

#### SupportWidget

A help launcher that grows into article search, an article reader and a chat thread. Articles, team and suggested replies are sample data in support-widget-data.ts; agent replies are simulated.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `onSend` | `(message: string) => void` |  | Called with each message the person sends, so you can forward it to your inbox or chat provider. |
| `onOpenChange` | `(open: boolean) => void` |  | Called when the launcher opens or closes the panel. |

### Dependencies

- `motion`
- `lucide-react`

### Keyboard

| Keys | Action |
| --- | --- |
| Escape | Closes the panel and returns focus to the launcher. |
| Arrow down | From the search field, moves focus into the article list. |
| Arrow up / Arrow down | Moves between articles; up from the first article returns to search. |
| Enter | In search, opens the top result. |

### Accessibility

- The open panel is a role="dialog" whose label switches between Help and the conversation.
- The chat thread is a role="log" with a screen reader only typing indicator, and a polite live region announces view changes.
- The launcher uses aria-haspopup="dialog" and includes the unread reply count in its label.

### Motion

- The launcher springs open into the panel, and views slide in the direction of travel.
- Unread badges and the launcher icon pop in on a snappy spring; changing text crossfades with a short rise.
- Reduced motion replaces scale, slide and rotate with plain fades.

### Responsive behavior

- The dock is positioned absolute inside the block's 680px demo stage; move it to position fixed when you mount it in a real app.
- Below a 519px container the stage is 640px tall, the dock sits closer to the corner, and the sample app nav hides.
- On coarse pointers opening chat focuses the panel instead of the text field, so the keyboard does not pop up on its own.

### Performance

- Views mount one at a time and ResizeObservers animate the panel size between them.
- Article search filters an in-memory list; move it to your search API for a large help center.

### Notes for AI agents

- Use as the in-app help entry point of a SaaS product, mounted once near the app root.
- Replace ARTICLES, TEAM, SUGGESTIONS and replyTo in support-widget-data.ts with your help center and real replies.
- Wire onSend to your inbox or chat provider; the sample app page behind the launcher is decoration to remove.

### Keywords

react support widget, help center widget, intercom style chat, in-app help launcher, customer support chat, help article search

### Related

- search-field
- avatar
- text-morph
- dialog
- ai-composer

---

## Uptime status

A status page with 90 day uptime bars, a morphing latency chart and an incident timeline.

- Type: Block (composition)
- Access: Pro
- Built from: Badge, Button, Avatar, Animated counter
- Documentation: https://uiarc.dev/components/blocks/uptime-status

### Overview

Use this as a public or internal status page. Feed your incident history and monitor latency into uptime-data.ts; day bars, uptime percentages and chart scales are derived from them, and the incident button is a simulation.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/uptime-status. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/uptime-status while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- A public or internal status page with per-service uptime history.
- Pages that combine 90 day uptime strips, response time, and an incident timeline.

### When not to use

- Use activity-heatmap for activity counts rather than availability.
- Use timeline for an incident history on its own.
- Use sparkline for a small latency trend inside a card.

### Usage

```tsx
import { UptimeStatus } from "@/components/arc/blocks/uptime-status/uptime-status";

export default function StatusPage() {
  return (
    <main>
      <UptimeStatus />
    </main>
  );
}
```

### API

#### UptimeStatus

A status page with 90 day uptime strips per service, a response time chart and an incident timeline. Takes no props; services, days, latency and incidents are sample data in uptime-data.ts, and the incident button is a simulation.

No props.

### Dependencies

- `motion`
- `lucide-react`

### Keyboard

| Keys | Action |
| --- | --- |
| Arrow left / Arrow right | Inspects the previous or next day on a service strip, or the previous or next half hour on the latency chart. |
| Page up / Page down | Jumps a week on a service strip. |
| Home / End | Jumps to the first or latest point. |
| Enter / Space | Selects the focused service so the latency chart follows it. |
| Escape | Clears the inspected day or point. |

### Accessibility

- Each strip is a focusable role="group" labelled with the service and described by its uptime summary.
- The latency chart has a text summary as its label, and polite live regions read out the inspected day or point.
- Incident headers are disclosure buttons with aria-expanded and aria-controls, and service rows use aria-pressed.

### Motion

- The selected service highlight moves between rows with a shared layout spring, and the tooltip follows the pointer on a spring.
- The latency line morphs between services, and status text swaps with a short rise.
- Reduced motion removes the springs and moves the tooltip directly.

### Responsive behavior

- Below an 860px container the response time chart and incidents stack into one column.
- Below 560px row details and uptime labels hide and the status button moves under the summary.
- Strips and the latency chart use touch-action pan-y, so touch scrubbing keeps vertical scroll.

### Performance

- Each service draws 90 SVG bars; many services on one page means hundreds of rects, which is fine but not free.
- Chart widths follow ResizeObservers; there is no animation loop.

### Notes for AI agents

- Use for a public or internal status page.
- Replace services, daily history, latency samples and incidents in uptime-data.ts; bars, percentages and scales derive from them.
- Remove or rewire the simulated incident trigger to your monitoring feed.

### Keywords

react status page, uptime monitor, service status page, uptime bars, incident timeline, 90 day uptime

### Related

- activity-heatmap
- badge
- timeline
- sparkline

---

## Usage forecast

A billing period usage chart with a forecast cone and a draggable budget that dates the crossing.

- Type: Block (composition)
- Access: Pro
- Built from: Segmented control, Animated counter, Text morph
- Documentation: https://uiarc.dev/components/blocks/usage-forecast

### Overview

Use this on a billing or usage page to warn before a customer hits a budget. Replace the readings in usage-data.ts with your metering data and connect the budget and alert rules to your billing settings; alert emails in the preview are simulated.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/usage-forecast. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/usage-forecast while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- Billing or usage pages that warn customers before they hit a budget.
- Metered products that show month to date usage with a forecast range.

### When not to use

- Use usage-meter for a simple progress bar against a limit.
- Use usage-pricing to estimate price from usage before buying.
- Use metric-explorer for general KPIs without a budget.

### Usage

```tsx
import { UsageForecast } from "@/components/arc/blocks/usage-forecast/usage-forecast";

export default function BillingUsagePage() {
  return (
    <section>
      <UsageForecast />
    </section>
  );
}
```

### API

#### UsageForecast

A billing period usage chart with a forecast cone, a draggable budget line and alert rules. Takes no props; readings and metrics are sample data in usage-data.ts, and alert emails are simulated.

No props.

### Dependencies

- `motion`
- `lucide-react`

### Keyboard

| Keys | Action |
| --- | --- |
| Arrow keys | On the plot, steps one day; on the budget handle, moves the budget one step. |
| Page up / Page down | Jumps a week on the plot, or five steps on the budget handle. |
| Home / End | Jumps to the first or last day, or to the minimum or maximum budget. |
| Escape | Clears the inspected day on the plot. |

### Accessibility

- The plot and the budget handle are role="slider" elements with aria-valuetext in plain words.
- The chart SVG has a full sentence label and is described by a data table; a polite live region reads the forecast summary.
- Alert rules are toggle buttons with aria-pressed and labels that include their current status.

### Motion

- The budget line follows drags directly and settles on a snappy spring when released or moved by keyboard.
- The crossing marker and inspection panel follow the scrubbed day on springs; numbers roll with the animated counter.
- Reduced motion drops the springs and applies changes immediately.

### Responsive behavior

- Chart width follows its container through a ResizeObserver, and below 560px KPIs and the legend tighten.
- The plot uses touch-action pan-y for scrubbing, while the budget handle uses touch-action none so it can be dragged on touch.

### Performance

- SVG over daily readings for one billing period; the forecast cone is computed once per change, not per frame.
- Dragging the budget updates one line and label; there is no loop at rest.

### Notes for AI agents

- Use on a billing or usage page to warn customers before they hit a budget.
- Replace METRICS and daily readings in usage-data.ts with your metering data.
- Persist budget and alert rule changes to your billing settings; they are local state in the preview.

### Keywords

react usage chart, usage forecast, budget alert chart, billing usage graph, metered billing dashboard, spend forecast

### Related

- usage-meter
- usage-pricing
- billing-overview
- segmented-control
- metric-explorer

---

## MRR waterfall

An MRR bridge whose floating bars morph by period and open the accounts behind each move.

- Type: Block (composition)
- Access: Pro
- Built from: Segmented control, Animated counter
- Documentation: https://uiarc.dev/components/blocks/mrr-waterfall

### Overview

Use this on a revenue or board reporting page to explain how MRR moved. Replace the seeded months and accounts in mrr-data.ts with your billing movements; levels, axis, ratios and lists are computed from them.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/mrr-waterfall. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/mrr-waterfall while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- Revenue or board reporting that explains how MRR moved from start to end of a period.
- Finance views where each movement should list the accounts behind it.

### When not to use

- Use revenue-explorer for MRR over many months.
- Use bar-chart for plain comparisons that do not build from a start value.
- Use cohort-retention for retention by cohort.

### Usage

```tsx
import { MrrWaterfall } from "@/components/arc/blocks/mrr-waterfall/mrr-waterfall";

export default function RevenuePage() {
  return (
    <section>
      <MrrWaterfall />
    </section>
  );
}
```

### API

#### MrrWaterfall

An MRR bridge with floating bars per movement, a period switch and a panel listing the accounts behind the selected bar. Takes no props; periods, movements and accounts are sample data in mrr-data.ts.

No props.

### Dependencies

- `motion`
- `lucide-react`

### Keyboard

| Keys | Action |
| --- | --- |
| Arrow keys | Moves the selection to the previous or next bar, wrapping at the ends. |
| Home / End | Selects the first or last bar. |

### Accessibility

- Bars are a role="radiogroup" of radio buttons with roving tabindex; each label reads the movement, amount and account count.
- The chart SVG carries a text summary, and the accounts panel is labelled by the selected movement.
- A polite live region announces each newly selected bar.

### Motion

- Bars morph to new levels when the period changes, and the account list reorders with layout animation.
- Headings and figures swap with a short rise, and totals roll with the animated counter.
- Reduced motion swaps values without movement.

### Responsive behavior

- Below an 800px container the accounts panel moves under the chart.
- Below 560px the summary stats become a three column row with smaller figures.
- Hover previews apply only to mouse pointers; touch taps select a bar.

### Performance

- A handful of SVG bars per period, sized by ResizeObserver; cheap at any size.
- Account lists are not virtualized, so cap or paginate large movements.

### Notes for AI agents

- Use on a revenue or board reporting page to explain how MRR moved between periods.
- Replace PERIODS in mrr-data.ts with your billing movements; levels, axis and lists are computed from them.

### Keywords

react waterfall chart, mrr bridge, revenue waterfall, mrr movements chart, saas revenue bridge, floating bar chart

### Related

- revenue-explorer
- cohort-retention
- bar-chart
- segmented-control
- metric-explorer

---

## Webhooks

A webhooks console with delivery history, a payload inspector and retries that roll the rate.

- Type: Block (composition)
- Access: Pro
- Built from: Badge, Button, Checkbox, Copy button, Input, Avatar
- Documentation: https://uiarc.dev/components/blocks/webhooks

### Overview

Use this on a developer settings page. Load endpoints, event volume and delivery attempts from your webhook service into webhooks-data.ts and connect retry, test event and endpoint creation to your API; the preview is simulated.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/webhooks. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/webhooks while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- A developer settings page for webhook endpoints, delivery history, and retries.
- Consoles that need a payload and headers inspector next to the delivery list.

### When not to use

- Use api-keys for managing tokens.
- Use audit-log for account activity rather than outgoing events.
- Use integrations for a catalogue of third-party connections.

### Usage

```tsx
import { Webhooks } from "@/components/arc/blocks/webhooks/webhooks";

export default function DeveloperSettings() {
  return (
    <main>
      <Webhooks />
    </main>
  );
}
```

### API

#### Webhooks

A webhooks console with an endpoint list, delivery volume chart, delivery history, a payload and headers inspector, retries and an add endpoint form. Takes no props; endpoints, deliveries and payloads are sample data in webhooks-data.ts, and retries, test events and creation are simulated.

No props.

### Dependencies

- `motion`
- `lucide-react`

### Keyboard

| Keys | Action |
| --- | --- |
| Arrow up / Arrow down | Moves focus and selection through endpoints or deliveries. |
| Home / End | Jumps to the first or last endpoint or delivery, or the first or last inspector tab. |
| Arrow left / Arrow right | Switches between the Payload and Headers tabs. |
| Escape | Closes the add endpoint panel. |

### Accessibility

- Payload and headers use a tablist with roving tabindex, and the code panel is a focusable tabpanel.
- Endpoint and delivery rows mark the current item with aria-current and point at the detail region with aria-controls.
- Form errors render with role="alert", and the add toggle exposes aria-expanded.

### Motion

- Selection highlights and the active tab slide with shared layout springs; new rows grow in and flash once.
- A successful retry swaps to Resolved and the delivery rate rolls to its new value.
- Reduced motion replaces growth and rolls with instant or opacity-only changes.

### Responsive behavior

- Below an 880px container the delivery list and inspector stack, and below 760px endpoint rows wrap onto two lines.
- Below 540px padding tightens and the footer stacks; inner container queries also reflow the add form, delivery rows, and headers on their own widths.

### Performance

- Delivery rows are not virtualized; paginate from your webhook service for busy endpoints.
- ResizeObservers size the volume chart; there is no animation loop.

### Notes for AI agents

- Use on a developer settings page for managing webhook endpoints.
- Load endpoints, event volume and delivery attempts from your webhook service into webhooks-data.ts.
- Connect retry, send test event and endpoint creation to your API, and return the real signing secret once.

### Keywords

react webhooks dashboard, webhook endpoints ui, webhook delivery logs, retry webhook, payload inspector, developer settings webhooks

### Related

- api-keys
- code-block
- copy-button
- integrations

---

## Roles and permissions

A permissions matrix with group toggles that ripple, role duplication and a review bar.

- Type: Block (composition)
- Access: Pro
- Built from: Button, Animated counter, Text morph, Avatar group
- Documentation: https://uiarc.dev/components/blocks/roles-permissions

### Overview

Use this on a workspace settings page to edit what each role can do. Load roles, permission groups and grants from your authorization API and connect Save to it; saving in the preview is simulated.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/roles-permissions. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/roles-permissions while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- Workspace settings where admins edit what each role can do.
- Permission matrices with grouped permissions and a review step before saving.

### When not to use

- Use team-members to assign roles to people.
- Use switch rows in settings-page for a few on and off settings.
- Use security-settings for personal account security.

### Usage

```tsx
import { RolesPermissions } from "@/components/arc/blocks/roles-permissions/roles-permissions";

export default function WorkspaceRoles() {
  return (
    <section>
      <RolesPermissions />
    </section>
  );
}
```

### API

#### RolesPermissions

A permissions matrix with role columns, collapsible permission groups, group toggles, role duplication and a review bar for unsaved changes. Takes no props; roles, groups, grants and members are inline constants (ROLES, GROUPS, GRANTED, MEMBERS) in roles-permissions.tsx, and saving is simulated.

No props.

### Dependencies

- `motion`
- `lucide-react`
- `@radix-ui/react-dropdown-menu`

### Keyboard

| Keys | Action |
| --- | --- |
| Arrow keys | Moves focus across the matrix, snapping to the nearest cell in the next row. |
| Home / End | Jumps to the first or last cell in the row. |
| Ctrl + Home / Ctrl + End | Jumps to the first or last cell in the grid. |

### Accessibility

- The matrix uses grid, row, rowheader and columnheader roles with a single tab stop.
- Cells are role="switch" or role="checkbox" buttons, group toggles report aria-checked="mixed", and locked owner cells use aria-disabled.
- A polite status region announces toggles and save progress.

### Motion

- Group toggles ripple across their permissions with a short stagger, and a column band follows the hovered role.
- Unsaved dots pop in and the review bar slides up while changes exist.
- Reduced motion removes the ripple and springs.

### Responsive behavior

- The matrix scrolls sideways with sticky permission labels, so role columns stay aligned on narrow screens.
- Below a 760px container the label column is 208px and role columns 88px; below 540px they shrink to 160px and 84px and group counts hide.
- The review bar stays sticky to the viewport while there are unsaved changes.

### Performance

- Every cell is a real control and rows are not virtualized; very large permission sets should stay collapsed by group.

### Notes for AI agents

- Use on a workspace settings page for editing what each role can do.
- Replace ROLES, GROUPS, GRANTED and MEMBERS in roles-permissions.tsx with data from your authorization API.
- Connect Save changes to your API; it only shows a simulated saved state.

### Keywords

react permissions matrix, roles and permissions ui, rbac settings, access control table, role editor, permission toggles

### Related

- team-members
- security-settings
- settings-page
- switch
- avatar-group

---

## Metric explorer

KPI cards that open into a scrubbable chart and morph between metrics and ranges.

- Type: Block (composition)
- Access: Pro
- Built from: Segmented control, Animated counter
- Documentation: https://uiarc.dev/components/blocks/metric-explorer

### Overview

Use this at the top of a SaaS analytics or finance page. Replace the seeded series in metric-data.ts with daily values from your warehouse or metrics API; the range and comparison math stay the same.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/metric-explorer. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/metric-explorer while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- The top of a SaaS analytics or finance page with KPI cards that open into a chart.
- Dashboards where people move between a few metrics and date ranges.

### When not to use

- Use stat-card or metric-card for static KPI tiles.
- Use revenue-explorer for a revenue breakdown with a range brush.
- Use metrics-dashboard for a full dashboard layout.

### Usage

```tsx
import { MetricExplorer } from "@/components/arc/blocks/metric-explorer/metric-explorer";

export default function AnalyticsPage() {
  return (
    <main>
      <MetricExplorer />
    </main>
  );
}
```

### API

#### MetricExplorer

A row of KPI cards that morph open into a scrubbable chart with metric tabs and a range switch. Takes no props; series and ranges are sample data in metric-data.ts.

No props.

### Dependencies

- `motion`
- `lucide-react`

### Keyboard

| Keys | Action |
| --- | --- |
| Arrow left / Arrow right | On the metric tabs, switches metric; on the chart, steps back or forward one interval. |
| Home / End | Jumps to the first or last metric tab, or the first or last point in range. |
| Escape | Clears the scrubbed point, then closes the chart back to its card. |

### Accessibility

- Each card is a button whose label reads the value, change and range.
- The open chart uses a tablist and tabpanel, and the scrubber is a role="slider" with a dated aria-valuetext.
- The close button advertises Escape with aria-keyshortcuts, and a polite live region announces changes.

### Motion

- A card's surface morphs into the chart panel with a shared layout transition and back on close.
- The line morphs between metrics and ranges, and the tab highlight slides with the selection.
- Reduced motion replaces the morph and slides with instant changes.

### Responsive behavior

- Four cards per row drop to two below a 760px container.
- Below 640px tab values hide and the readout stacks; below 440px card padding and values shrink.
- The chart uses touch-action pan-y, so touch scrubbing does not block page scroll.

### Performance

- Opening a card morphs one shared surface with a layoutId, and ResizeObservers fit the chart and tab indicator.
- SVG charts over daily series; aggregate long histories before passing them in.

### Notes for AI agents

- Use at the top of a SaaS analytics or finance page.
- Replace the seeded series in metric-data.ts with daily values from your warehouse; range and comparison math stay the same.

### Keywords

react kpi cards, metric explorer, analytics dashboard chart, expandable stat card, kpi to chart, saas metrics

### Related

- metric-card
- sparkline
- revenue-explorer
- segmented-control

---

## Activity terrain

A 3D terrain of hourly activity you can orbit, zoom, fly into and flatten into a heatmap.

- Type: Block (composition)
- Access: Pro
- Built from: Arc foundation
- Documentation: https://uiarc.dev/components/blocks/activity-terrain

### Overview

Use this on an analytics or operations page to show when a product is busiest. Replace the seeded week in terrain-data.ts with hourly counts from your events warehouse; the camera, springs and summaries follow the data.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/activity-terrain. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/activity-terrain while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- Analytics or operations pages showing when a product is busiest across a week.
- Showcase dashboards where a 3D view of a 7 by 24 grid adds impact, with a flat heatmap fallback.

### When not to use

- Use activity-heatmap for a plain 2D grid that is easier to read.
- Use bar-chart for totals by day or hour.

### Usage

```tsx
import { ActivityTerrain } from "@/components/arc/blocks/activity-terrain/activity-terrain";

export default function UsagePatterns() {
  return (
    <section>
      <ActivityTerrain />
    </section>
  );
}
```

### API

#### ActivityTerrain

A canvas 3D terrain of hourly activity across a week that can orbit, zoom, fly to a cell and flatten into a heatmap. Takes no props; metrics and the hourly grid are sample data in terrain-data.ts.

No props.

### Dependencies

- `motion`
- `lucide-react`

### Keyboard

| Keys | Action |
| --- | --- |
| Arrow keys | Moves the highlighted day and hour. |
| Shift + Arrow keys | Orbits the camera. |
| Home / End | Jumps to the first or last hour of the day. |
| + / - | Zooms in or out. |
| Enter / Space | Flies to the highlighted hour. |
| Escape | Returns to the whole week, then clears the highlight. |

### Accessibility

- The stage is a focusable group with a keyboard hint, and the canvas has a text summary as its label.
- Peak hours are aria-pressed buttons that fly to or leave the hour.
- A polite live region reads the highlighted hour's value.

### Motion

- Columns rise in a wave on load and when the metric changes; camera moves use spring physics with momentum on drag.
- Flattening to a heatmap springs the camera to a top view.
- The engine watches prefers-reduced-motion and snaps the camera and heights with no wave.

### Responsive behavior

- Below an 880px container the stats move under the plot; below 560px the plot is 280px tall and the camera starts from a steeper angle.
- Touch devices swipe sideways to orbit while vertical swipes scroll the page, and the hint text switches for coarse pointers.
- Two-finger pinch zooms on touch.

### Performance

- Draws on a 2D canvas with devicePixelRatio capped at 2.
- The requestAnimationFrame loop pauses offscreen via IntersectionObserver and in hidden tabs, and idles when nothing moves.

### Notes for AI agents

- Use on an analytics or operations page to show when a product is busiest across a week.
- Replace METRICS in terrain-data.ts with hourly counts from your events warehouse; keep the 7 by 24 shape.

### Keywords

react 3d heatmap, activity terrain, 3d bar chart canvas, hourly activity chart, week by hour heatmap, canvas data visualization

### Related

- activity-heatmap
- revenue-globe
- customer-galaxy
- segmented-control

---

## Revenue globe

A dotted globe where live payments arc home to headquarters, with a replayable day.

- Type: Block (composition)
- Access: Pro
- Built from: Animated counter
- Documentation: https://uiarc.dev/components/blocks/revenue-globe

### Overview

Use this on a revenue or operations overview to show where money comes from right now. Swap minuteTx in globe-data.ts for a query on your payments table; totals, arcs and replay all derive from it.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/revenue-globe. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/revenue-globe while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- Revenue or operations overviews showing where payments come from right now.
- Showcase pages where a live globe with arcs and a day timeline adds impact.

### When not to use

- Use a table or bar-chart when exact regional numbers matter more than the view.
- Use customer-galaxy to explore accounts rather than transactions.
- Use revenue-explorer for revenue over time.

### Usage

```tsx
import { RevenueGlobe } from "@/components/arc/blocks/revenue-globe/revenue-globe";

export default function RevenueOverview() {
  return (
    <section>
      <RevenueGlobe />
    </section>
  );
}
```

### API

#### RevenueGlobe

A dotted canvas globe where payments arc into headquarters, with a scrubbable day timeline, replay and region and city breakdowns. Takes no props; cities, regions and the transaction stream are sample data in globe-data.ts.

No props.

### Dependencies

- `motion`
- `lucide-react`

### Keyboard

| Keys | Action |
| --- | --- |
| Arrow keys | Spins the globe when it has focus. |
| Escape | Clears the selected city or region. |
| Arrow keys (timeline) | Moves the time by five minutes, or an hour with Shift. |
| Page up / Page down | Moves the time by an hour. |
| Home / End | Jumps to midnight or back to live. |

### Accessibility

- The globe is a focusable region with a roledescription, instructions in its label and a text summary of revenue.
- The timeline is a role="slider" whose value text reads the UTC time.
- Region and city rows are aria-pressed buttons, and a polite live region announces changes.

### Motion

- Payments draw as arcs to headquarters while the globe drifts; drags rubber-band past the latitude limit.
- The tooltip follows the pointer on a spring, and totals roll with the animated counter.
- Reduced motion stops the auto rotation, hides replay and play controls, and shows the current state as Now.

### Responsive behavior

- Below an 880px container the panel moves under the globe and the globe height follows width with clamp.
- Below 600px the panel drops to one column; below 400px the clock takes its own row.
- The timeline slider uses touch-action none and pointer capture, so scrubbing works on touch.

### Performance

- Draws on a 2D canvas with devicePixelRatio capped at 2.
- The animation loop pauses offscreen via IntersectionObserver and in hidden tabs.

### Notes for AI agents

- Use on a revenue or operations overview to show where money comes from right now.
- Swap minuteTx in globe-data.ts for a query on your payments table, and set HQ, CITIES and REGIONS to your own.

### Keywords

react globe, revenue globe, payments map animation, 3d globe canvas, live transactions map, dotted globe

### Related

- customer-galaxy
- activity-terrain
- animated-counter
- revenue-explorer

---

## Customer galaxy

2,400 accounts as a drifting galaxy that spirals into clusters by plan, region or health.

- Type: Block (composition)
- Access: Pro
- Built from: Arc foundation
- Documentation: https://uiarc.dev/components/blocks/customer-galaxy

### Overview

Use this on a customer success or revenue page to explore where MRR and risk concentrate. Replace the seeded book in galaxy-data.ts with your accounts; clusters, totals and the side panel derive from it.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/customer-galaxy. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/customer-galaxy while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- Customer success or revenue pages to explore where MRR and risk concentrate.
- Showcase views that cluster thousands of accounts by plan, region, or health.

### When not to use

- Use customers-table when people need to find and act on specific accounts.
- Use semantic-zoom for hierarchical data like teams and projects.
- Use bar-chart for simple totals by segment.

### Usage

```tsx
import { CustomerGalaxy } from "@/components/arc/blocks/customer-galaxy/customer-galaxy";

export default function CustomerSuccessPage() {
  return (
    <section>
      <CustomerGalaxy />
    </section>
  );
}
```

### API

#### CustomerGalaxy

A canvas galaxy of about 2,400 accounts sized by MRR that spirals into clusters by plan, region or health, with pan, zoom and a totals panel. Takes no props; accounts are sample data in galaxy-data.ts.

No props.

### Dependencies

- `motion`
- `lucide-react`

### Keyboard

| Keys | Action |
| --- | --- |
| Arrow left / Arrow right | On the grouping tabs, switches grouping; on the stage, flies between clusters by MRR. |
| Arrow keys | Steps through accounts when a single cluster is in view. |
| + / - | Zooms in or out. |
| Escape | Clears the selected account, then resets the view. |
| 0 / Home | Fits all accounts. |

### Accessibility

- The stage is role="application" with a roledescription, a text summary label and a keyboard hint.
- Grouping uses a tablist and tabpanel; cluster rows are aria-pressed buttons with MRR and risk in their labels.
- Zoom buttons have labels, and a polite live region announces selections.

### Motion

- Accounts drift, then spiral into clusters with spring physics when grouping changes; flying to a cluster eases the camera.
- The tab pill slides with a shared layout spring, and panel rows reorder with layout animation.
- Reduced motion is passed to the engine, which snaps to layouts, and UI transitions become instant.

### Responsive behavior

- From an 880px container the totals panel sits beside the stage at 296px; below that it moves under it, and below 620px the stage is 440px tall.
- Touch uses pinch to zoom and double tap; the stage allows vertical page scroll until zoomed in.
- Mouse wheel zoom only takes over for ctrl or pinch gestures and mouse-like wheels, so trackpad scrolling still moves the page.

### Performance

- Renders about 2,400 accounts on a 2D canvas with devicePixelRatio capped at 2.
- The loop pauses offscreen via IntersectionObserver and in hidden tabs.

### Notes for AI agents

- Use on a customer success or revenue page to explore where MRR and risk concentrate.
- Replace the seeded accounts in galaxy-data.ts with your book, keeping plan, region, health and MRR fields.

### Keywords

react data galaxy, customer visualization, canvas particle clusters, zoomable scatter, account explorer, mrr visualization

### Related

- revenue-globe
- semantic-zoom
- cohort-retention

---

## Semantic zoom

An infinite-zoom map of a company that reveals teams, projects, tasks and people as you fly in.

- Type: Block (composition)
- Access: Pro
- Built from: Arc foundation
- Documentation: https://uiarc.dev/components/blocks/semantic-zoom

### Overview

Use this on a workspace or portfolio overview so people can move from the whole company to a single task without losing their place. Replace the seeded teams in zoom-data.ts with your own; layout, rollups and labels derive from it.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/semantic-zoom. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/semantic-zoom while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- Workspace or portfolio overviews where people zoom from the whole company to one task.
- Hierarchical data where each zoom level should show different detail.

### When not to use

- Use tree-view for a plain hierarchy people scan and expand.
- Use project-board for working on tasks.
- Use customer-galaxy for flat data clustered by attributes.

### Usage

```tsx
import { SemanticZoom } from "@/components/arc/blocks/semantic-zoom/semantic-zoom";

export default function WorkspaceMap() {
  return (
    <section>
      <SemanticZoom />
    </section>
  );
}
```

### API

#### SemanticZoom

An infinite zoom canvas map of a company that reveals teams, projects, tasks and people as you fly in, with breadcrumbs, a minimap and a guided tour. Takes no props; teams, projects, tasks and people are sample data in zoom-data.ts.

No props.

### Dependencies

- `motion`
- `lucide-react`

### Keyboard

| Keys | Action |
| --- | --- |
| Arrow keys | Moves the cursor between nearby items. |
| Enter / Space | Flies into the item under the cursor. |
| Escape / Backspace | Flies out one level. |
| + / - | Zooms in or out. |
| 0 / Home | Fits the whole company. |

### Accessibility

- The stage is role="application" with a zoomable map roledescription, a text summary label and a keyboard hint.
- Breadcrumbs are a nav with aria-current="location" on the current level.
- The tour toggle uses aria-pressed, the side panel is labelled, and a polite live region announces moves.

### Motion

- The camera flies between levels on eased zooms, and detail fades in as each level gets large enough.
- Breadcrumbs, panel stats and people avatars enter with a blur rise or spring.
- Reduced motion is passed to the engine for instant camera moves, and UI transitions become instant.

### Responsive behavior

- From a 900px container the side panel sits beside the stage at 268px; below that it moves underneath, and below 600px the stage is 480px tall.
- Touch uses pinch to zoom and tap to fly in; the stage allows vertical page scroll until zoomed in.
- The mouse wheel always zooms over the stage, so leave page space around it for scrolling.

### Performance

- Draws on 2D canvases sized by ResizeObserver with devicePixelRatio capped at 2.
- The loop pauses offscreen via IntersectionObserver and in hidden tabs.

### Notes for AI agents

- Use on a workspace or portfolio overview so people can move from the whole company to a single task.
- Replace TEAMS, PROJECTS, TASKS and PEOPLE in zoom-data.ts; layout, rollups and labels derive from them.

### Keywords

react semantic zoom, infinite zoom canvas, zoomable org chart, zoom ui, portfolio map, canvas zoom and pan

### Related

- customer-galaxy
- tree-view
- breadcrumb
- layout-morph

---

## Layout morph

A 24 card gallery that flies between grid, masonry, list, fan, carousel and a 3D helix.

- Type: Block (composition)
- Access: Pro
- Built from: Arc foundation
- Documentation: https://uiarc.dev/components/blocks/layout-morph

### Overview

Use this for a catalogue, portfolio or team page where people browse the same set in different ways. Replace ITEMS in morph-data.ts with your own; layouts, captions, the open view and the numbers derive from it.

### Install

Arc Pro block: not in the public registry. It uses local image assets, so Pro members copy the source from the Manual tab at https://uiarc.dev/components/blocks/layout-morph while signed in (or read it with the MCP get_component tool and a Pro token). Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- Catalogue, portfolio, or team pages where people browse the same set in different layouts.
- Showcase galleries that fly between grid, masonry, list, fan, carousel, and a 3D helix.

### When not to use

- Use photo-grid for a simple gallery.
- Use carousel or cover-flow for one horizontal browsing style.
- Use lightbox-gallery when opening a full size image is the main job.

### Usage

```tsx
import { LayoutMorph } from "@/components/arc/blocks/layout-morph/layout-morph";

export default function CataloguePage() {
  return (
    <main>
      <LayoutMorph />
    </main>
  );
}
```

### API

#### LayoutMorph

A 24 card gallery that flies between grid, masonry, list, fan, carousel and a 3D helix, with an open view for each card. Takes no props; cards are sample data in ITEMS in morph-data.ts, using images from other blocks and public portraits.

No props.

### Dependencies

- `motion`
- `lucide-react`

### Keyboard

| Keys | Action |
| --- | --- |
| Arrow keys / Home / End | On the view switch, picks the next, previous, first or last layout. |
| Arrow left / Arrow right | On a card, switches to the previous or next layout and keeps that card in focus. |
| Arrow up / Arrow down / Home / End | Moves focus between cards. |
| Enter | Opens the focused card. |
| Escape | Closes the open card. |

### Accessibility

- The view switch is a role="radiogroup" with roving tabindex and labelled icon options.
- The stage is a group with a gallery roledescription whose label explains the keys.
- The open card is a role="dialog"; the gallery behind it is hidden and the closed dialog is inert.

### Motion

- Cards fly between layouts on springs, staggered outward from the chosen origin.
- Opening a card morphs it into the detail view.
- Reduced motion is passed to the engine and MotionConfig uses the user setting.

### Responsive behavior

- Below a 720px container the layout tabs become icon-only and the stage is 540px tall, shrinking to 500px and 460px below 480px and 360px.
- In scrolling layouts the stage takes touch-action none; wheel only rotates the ring for horizontal or shift scrolls.

### Performance

- Cards are DOM elements moved with transforms, and the ring layouts spin one camera transform per frame instead of every card.
- The loop pauses offscreen via IntersectionObserver and in hidden tabs; keep the set near the 24 sample cards.

### Notes for AI agents

- Use for a catalogue, portfolio or team page where people browse the same set in different ways.
- Replace ITEMS in morph-data.ts with your own photos and profiles; layouts, captions and totals derive from it.
- The save action in the open view is local state; connect it to your favourites API if needed.

### Keywords

react layout animation, gallery layout switcher, masonry to grid animation, 3d helix gallery, view mode toggle, morphing gallery

### Related

- photo-grid
- carousel
- cover-flow
- card-stack
- segmented-control

---

## Agent run

A single card that follows one AI coding agent through a task: steps stream in with the live one shimmering, tool calls open in place, and the agent stops on a two-file diff for you to approve or send back before it writes. When the run ends, the steps fold into one line and a result shows the files changed, the checks that passed and a pull request button.

- Type: Block (composition)
- Access: Pro
- Built from: Button, Input, Text shimmer, Tooltip
- Documentation: https://uiarc.dev/components/blocks/agent-run

### Overview

With no props it plays a simulated run. To show a real agent, pass run={{ status, elapsedMs, steps, result }} built from your runtime's events, plus onApprove(change), onReject(change, reason), onOpenPullRequest() and onRestart. To replay your own scenario, pass script instead; autoPlay={false} shows a Start run button.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/agent-run. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/agent-run while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- Coding agents and background jobs that read, search, edit and test, where people watch progress and approve the change before it is written.
- Product surfaces that hand an agent a ticket and return a pull request, such as an issue tracker, a review tool or an IDE side panel.
- Demos and onboarding that explain how an agent works step by step, with a real approval gate.

### When not to use

- Use research-run for a research agent that reads sources and writes a cited report.
- Use agent-approvals for an inbox of pending approvals across many agents and tools.
- Use agent-orchestrator when several agents work in parallel on parts of one job.
- Use code-review for reviewing a finished pull request line by line with comments.

### Usage

```tsx
import { AgentRun } from "@/components/arc/blocks/agent-run/agent-run";

// Simulated demo
<AgentRun />

// Live: build the state from your agent runtime's events
export function AgentPanel({ run, task }) {
  return (
    <AgentRun
      task={task}
      run={run} // { status: "working" | "waiting" | "done", elapsedMs, steps, result }
      onApprove={change => agent.approve(change.id)}
      onReject={(change, reason) => agent.reject(change.id, reason)}
      onOpenPullRequest={() => agent.openPullRequest()} // resolves to { number, url }
      onRestart={() => agent.restart()}
    />
  );
}

// A step while it runs, and an approval step waiting for a decision
const steps = [
  { id: "tests", mark: "npm", verb: "Running tests", doneVerb: "Ran tests", doneTarget: "12 passed", status: "running", progress: { value: 8, total: 12 } },
  { id: "review", mark: "review", verb: "Preparing", doneVerb: "Approved", doneTarget: "changes to 2 files", status: "waiting", change },
];
```

### API

#### AgentRun

One card that follows an AI coding agent through a task. The header holds the task, the model with its mark, a live status word (Working with a shimmer, Waiting for you, Done) and an elapsed timer. Steps stream into a list named Steps, the live verb shimmering; tool steps open in place to show their input and output in mono, and finished steps settle to secondary text with a drawn check. Before it writes, the agent stops on a compact unified diff with one tab per file and Approve and Reject; Reject asks for a short note and the agent revises once. When the run ends the steps fold into one line and a result appears: the closing message, files changed with a diffstat, checks, and Open pull request.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `task` | `string` | `"Add rate limiting to the public API"` | What the agent was asked to do, shown as the card title. |
| `model` | `{ name: string; mark?: ReactNode }` | `Claude Sonnet 5.5 with the Claude mark` | The model doing the work. The mark is decorative; the name is read out. |
| `script` | `RunScript` | `sampleScript` | The simulated run: steps with durations, approval steps carrying a ProposedChange and an optional revise branch, and the tests and checks to report. Ignored when run is set. |
| `run` | `AgentRunState` |  | A live run from your agent runtime: { status, elapsedMs, steps, result }. Map your runtime's events onto it; the card renders exactly what you pass. Leave it out to simulate script. |
| `autoPlay` | `boolean` | `true` | Start the simulation once the card is on screen. When false, the card shows a Start run button. |
| `onApprove` | `(change: ProposedChange) => void` |  | Called when someone approves a change. A simulation then writes it and carries on. |
| `onReject` | `(change: ProposedChange, reason: string) => void` |  | Called with the note when someone rejects a change. A simulation revises once, then stops on a second rejection. |
| `onOpenPullRequest` | `() => Promise<PullRequest \| void> \| PullRequest \| void` |  | Opens a pull request from the result and returns { number, url }. Throw to report a failure. Without it the preview simulates PR #482 and says so in a live region. |
| `onRestart` | `() => void` |  | Called by Restart run. A simulation restarts on its own. |
| `className` | `string` |  | Class on the root section. |

#### useSimulatedRun

The hook behind the simulation, exported for tests and custom shells. Plays a RunScript on one animation frame clock and returns { state, start, restart, approve, reject }. The clock stops while a change waits, while the card is off screen and while the tab is hidden.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `script` | `RunScript` |  | The script to play. |
| `options.running` | `boolean` |  | Whether the clock may tick, for example only while the card is in view. |

### Dependencies

- `motion`
- `lucide-react`
- `@radix-ui/react-tooltip`

### Keyboard

| Keys | Action |
| --- | --- |
| Tab | Moves through Restart run, each finished step, the file tabs and code of a waiting diff, Reject and Approve, the folded steps line and Open pull request. |
| Enter, Space | On a step, opens or closes its input and output. On the folded line, shows or hides the steps. |
| Arrow left / Arrow right, Home, End | On the diff's file tabs, switches file. |
| Enter | In the rejection note, sends the change back to the agent. |
| Escape | In the rejection note, cancels and returns focus to Reject. |

### Accessibility

- The card is a section named by the task. Steps are an ordered list named Steps; each expandable step is a button with aria-expanded and aria-controls.
- A polite live region announces each step as it starts, the wait for approval, the end of the run with the test count, and stopping. A second region reports the pull request, including that the preview only simulates it.
- Status is never color alone: the status word sits beside an icon, finished steps change to past tense with a check, and a sent back step reads Sent back with the note.
- Diff lines carry hidden Added and Removed prefixes; the + and − markers and the tints are decorative. The file tabs are a tablist with tabpanels, and the hidden panel is inert.
- Approving or rejecting moves focus to that step's row, opening the note moves focus into it, and cancelling returns it to Reject.
- Pointer focus draws no ring; keyboard focus shows Arc's shared focus ring.

### Motion

- New steps open their height on a critically damped spring and fade in; nothing bounces.
- The live verb shimmers with Text shimmer. When a step finishes, the verb crossfades to past tense (100ms out, 160ms in from 2px) while its slot follows the measured width, and the check draws its stroke once.
- The header status word swaps with the same crossfade; the timer uses tabular numerals in a reserved width.
- Every diff file shares one grid cell, so switching tabs only crossfades and the card never resizes. The reject note swaps in place while the footer height follows on the smooth spring.
- At the end the steps fold to one line and the result opens below; the closing message streams in chunks of a few words every 34ms, laid out in advance so nothing reflows.
- The pull request button keeps every label in one cell, so Open pull request, Opening and PR #482 opened crossfade without changing width.
- Reduced motion drops travel, fades and the shimmer and keeps every state, label and announcement.

### Responsive behavior

- The card is up to 720px wide and works from 320px. Below 520px the step durations hide, the step details lose their indent, the diffstat blocks hide and the approval buttons take a full row.
- Long step labels and file paths truncate on one line; the full path stays in the tab title and the panel label.
- Diff and tool output scroll sideways inside their own frame, so the card never scrolls horizontally.

### Performance

- The simulation commits about 25 times a second from one requestAnimationFrame loop and pauses off screen, in a hidden tab and while waiting.
- Finished steps keep the same object and the rows are memoized, so only the live row re-renders on each beat.
- Streaming text renders its chunks once and only flips their opacity; there is no per-word animation.

### Notes for AI agents

- Use it for one agent on one task with a human approval before writes. For a fleet of agents use agent-orchestrator; for a queue of approvals use agent-approvals.
- Pass run for a live agent. Each step needs id, mark, verb, doneVerb and status; add target, doneTarget, progress, io, text or change as they apply. The card derives labels: running shows verb + target, waiting shows Review + doneTarget, done shows doneVerb + doneTarget.
- An approval step carries change: { id, summary, files: [{ path, status, lines }], outcome }. Diff lines are { type: "add" | "del" | "ctx", old?, new?, text }.
- Marks: think, read, search, edit, terminal and review are lucide icons; npm, typescript and github are real brand marks. Pass icon on a step for your own.
- Set result when status is done: summary, files with additions and deletions, tests and checks. elapsedMs should count only time the agent worked.
- Do not show it as executing real code in a demo; the default script is simulated and the pull request is simulated unless onOpenPullRequest is wired.

### Keywords

ai agent, coding agent, agent run, tool calls, approval, human in the loop, diff, unified diff, pull request, steps, timeline, claude, streaming, autonomous agent, agent trace

### Related

- research-run
- agent-approvals
- agent-orchestrator
- agent-tasks
- text-shimmer

---

## Week calendar

A week calendar where you drag to create, move, and resize events, with color coded calendars, day and agenda views, and swipes on phones.

- Type: Block (composition)
- Access: Pro
- Built from: Motion
- Documentation: https://uiarc.dev/components/blocks/week-calendar

### Overview

Use this for scheduling and planning views. Pass your events and calendars, and persist changes in onCreate, onUpdate, and onDelete.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/week-calendar. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/week-calendar while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- Scheduling and planning screens where people create, move and resize time blocks across a week.
- Team or personal calendars that need several color coded calendars, all day events and an agenda on phones.

### When not to use

- Use month-calendar for a month overview with events per day.
- Use calendar or date-picker to pick a date, and time-picker for a single time.
- Use availability-picker to collect open slots from someone.

### Usage

```tsx
import { useState } from "react";
import { WeekCalendar, type CalendarEvent } from "@/components/arc/blocks/week-calendar/week-calendar";

const calendars = [
  { id: "work", name: "Work", color: "blue" },
  { id: "personal", name: "Personal", color: "green" },
];

export default function SchedulePage({ initial }: { initial: CalendarEvent[] }) {
  const [events, setEvents] = useState(initial);
  return (
    <WeekCalendar
      events={events}
      onEventsChange={setEvents}
      calendars={calendars}
      onCreate={event => api.create(event)}
      onUpdate={event => api.update(event)}
      onDelete={event => api.remove(event.id)}
      startHour={6}
      timeZone="America/Los_Angeles"
    />
  );
}
```

### API

#### WeekCalendar

A week calendar at the level of a native app: week, work week and day views on wide screens, three days and an agenda list on phones, a mini month and calendar toggles in a sidebar when there is room, and an all day row that collapses when it fills up. Drag on empty time to draw an event and name it in a quick create popover, drag events between days and times, stretch the bottom edge to resize, and click an event to edit its title, day, time and calendar; everything snaps to 15 minutes. Events can be controlled or uncontrolled; without events it shows a realistic sample week.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `events` | `CalendarEvent[]` |  | Controlled events: { id, title, start: Date, end: Date, calendarId, allDay?, location?, attendees? }. Pair with onEventsChange. |
| `defaultEvents` | `CalendarEvent[]` |  | Starting events when uncontrolled. Without events or defaultEvents the calendar shows the sample week from week-calendar-data.ts. |
| `onEventsChange` | `(events: CalendarEvent[]) => void` |  | Called with the full list after every change: create, move, resize, edit, delete and undo. |
| `onCreate` | `(event: CalendarEvent) => void` |  | Called when someone saves a new event, and when an undo restores a deleted one. |
| `onUpdate` | `(event: CalendarEvent, previous: CalendarEvent) => void` |  | Called after a move, resize or edit in the details popover, with the event before the change. |
| `onDelete` | `(event: CalendarEvent) => void` |  | Called when an event is deleted. The undo toast calls onCreate if the person restores it. |
| `calendars` | `CalendarSource[]` | `SAMPLE_CALENDARS` | Calendars as { id, name, color, hidden? }. color is blue, green, violet, amber, rose, teal or any CSS color; built in names are tuned for light and dark. |
| `defaultDate` | `Date` |  | The day to open on. Defaults to today, or to the sample week when showing sample events. |
| `defaultView` | `"week" \| "workweek" \| "day" \| "3day" \| "agenda"` | `"week"` | Starting view. Below a 640px container week views show three days, and agenda is offered instead of work week. |
| `onViewChange` | `(view: CalendarView) => void` |  | Called when the view changes. |
| `weekStartsOn` | `0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6` | `1` | First day of the week; 0 is Sunday. |
| `startHour` | `number` | `0` | First hour shown in the day grid. |
| `endHour` | `number` | `24` | Hour the day grid ends at. |
| `timeZone` | `string` |  | IANA zone the grid runs in, such as "America/New_York". Times are converted and formatted with Intl. Defaults to the browser's zone. |
| `locale` | `string` | `"en-US"` | Locale for dates and times. |
| `className` | `string` |  | Class for the root element. Set --calendar-height on it to change the height of the scrolling grid. |

### Dependencies

- `motion`
- `lucide-react`

### Keyboard

| Keys | Action |
| --- | --- |
| Arrow left / Arrow right | Moves between days; past the edge of the range, the next week or days slide in. |
| T | Goes to today. |
| N | Drafts a new event at the next free hour of the focused day and opens the quick create form. |
| Enter | Saves the quick create form, opens a focused event, or drafts an event on a focused day. |
| Delete / Backspace | Deletes the focused or selected event, with an undo toast. |
| Escape | Closes a popover, cancels a drag, or clears the selection. |
| D / W | Switches to the day or week view. |
| Arrow up / Arrow down | On an event, moves focus to the previous or next event. |
| Alt + Arrow keys | Moves the focused event by a day or 15 minutes; add Shift with up and down to change its length. |
| Cmd / Ctrl + Z | Undoes the last move, resize, time change or delete. |

### Accessibility

- Each range is a role="grid" labelled with its dates and described by screen reader instructions; every day is a labelled grid cell with its date and event count, and keyboard focus moves between them with the arrow keys.
- Events are buttons whose labels read the title, full date, start and end time, calendar and location; all day events and agenda rows follow the same pattern.
- The quick create form and event details are labelled dialogs that take focus, close on Escape or a press outside, and return focus to the event.
- A polite live region announces range changes, creates, moves, resizes, deletes and undos. Pointer focus draws no ring; keyboard focus shows Arc's shared focus ring. Focus shows the same fill as hover.

### Motion

- Ranges slide in the direction of travel on a spring without overshoot, the header and all day row move with the grid, and a swipe on touch drags the neighbors along so letting go continues without a seam.
- Events animate to new positions with transforms only: a dragged event hops between 15 minute slots, and neighbors settle into their new columns after a drop or an edit.
- Popovers scale in from the edge that faces their event; the undo toast rises from the bottom.
- Reduced motion replaces slides and position springs with instant moves and short fades.

### Responsive behavior

- From a 1100px container a sidebar adds a mini month and calendar toggles; narrower, the toggles move into a Calendars popover.
- Between 640px and 900px the gutter and dates tighten and event blocks drop details that no longer fit, using container queries on each event.
- Below 640px the week becomes three days with Day and Agenda views, horizontal swipes change days, and a long press starts creating or moving so vertical swipes still scroll.
- The grid scrolls inside a height of clamp(480px, 72vh, 760px); set --calendar-height on the root to change it.

### Performance

- Event blocks are memoized on primitive props, so a drag re-renders only the event that moves; position changes animate with transforms, never layout.
- Time zone conversion runs once per events change; the now line updates on each minute boundary.
- All events are plain DOM; for thousands of events per week, pass only the visible range.

### Notes for AI agents

- Use for scheduling and planning screens where people create and rearrange time blocks; pass events and persist in onCreate, onUpdate and onDelete.
- Event times are Date instants. The grid shows them in timeZone (or the browser's zone), so store UTC and let the calendar format them.
- Map your calendars to calendars with a color each; hidden calendars start toggled off in the calendar list.
- sampleEvents() and SAMPLE_CALENDARS in week-calendar-data.ts are demo content to remove.

### Keywords

react week calendar, drag and drop calendar, google calendar clone, scheduler component, time blocking calendar, event scheduler, react calendar with time zones

### Related

- calendar
- date-picker
- time-picker
- popover
- availability-picker

---

## Scroll story

A feature section where scrolling the copy drives a pinned product view through each step.

- Type: Block (composition)
- Access: Pro
- Built from: Motion
- Documentation: https://uiarc.dev/components/blocks/scroll-story

### Overview

Use this on a marketing page to walk through a product in a few steps. Replace the step copy and the product states with your own.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/scroll-story. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/scroll-story while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- Marketing pages that walk through a product in a few steps as people scroll.
- Feature sections where a pinned product view should change with the copy.

### When not to use

- Use scroll-highlight for a single paragraph that reveals with scroll.
- Use chaos-to-order for one before and after switch.
- Use feature-illustration for a static feature visual.

### Usage

```tsx
import { ScrollStory } from "@/components/arc/blocks/scroll-story/scroll-story";

export default function FeaturesSection() {
  return (
    <section>
      <ScrollStory />
    </section>
  );
}
```

### API

#### ScrollStory

A feature section where scrolling the copy drives a pinned product view through four steps: messages arrive, sort by theme, fold into a trend and end in a share sheet. Takes no props; STEPS, MESSAGES, THEMES, TREND, TEAM and LINK are inline sample data in scroll-story.tsx, and sending to a channel is simulated.

No props.

### Dependencies

- `motion`
- `lucide-react`

### Keyboard

| Keys | Action |
| --- | --- |
| Arrow left / Arrow right | On the step tabs, scrolls to the previous or next step. |

### Accessibility

- The scrolling viewport is a focusable, labelled region, so it scrolls with the keyboard.
- Step tabs use a tablist with roving tabindex, and the active step in the copy carries aria-current="step".
- The product status and copy link and send results are announced through polite live regions.

### Motion

- Scroll position drives a progress value that fills the step tabs, sorts messages on springs and draws the trend line.
- Springs are restated as stiffness and damping, so retargeting mid-scroll keeps velocity.
- Reduced motion jumps to steps instead of smooth scrolling and replaces the springs with short fades.

### Responsive behavior

- The story scrolls inside its own viewport of clamp(480px, 74vh, 600px), not the page.
- Below a 700px container the product view stacks above the copy and stays pinned while the steps scroll under it.

### Performance

- Scroll is read in a passive listener and measured once per animation frame.
- Product states are memoized per step, so they do not re-render on every scroll frame.

### Notes for AI agents

- Use on a marketing page to walk through a product in a few steps.
- Replace STEPS copy and the product states (MESSAGES, THEMES, TREND, TEAM, LINK) in scroll-story.tsx with your own.
- Below 700px the product view stacks above the copy and stays pinned; no extra layout work is needed.

### Keywords

react scroll story, scrollytelling, sticky scroll section, scroll driven animation, product walkthrough on scroll, apple style scroll section

### Related

- text-reveal
- in-view-title

---

## Spotlight grid

A feature grid where light follows the pointer, cards play live demos, and a click morphs a card into its detail.

- Type: Block (composition)
- Access: Pro
- Built from: Motion
- Documentation: https://uiarc.dev/components/blocks/spotlight-grid

### Overview

Use this as a starting point and replace the sample data with your own.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/spotlight-grid. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/spotlight-grid while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- A product landing page section that shows four features with live, hands-on previews.
- Developer tool marketing where a small working demo explains a feature better than copy.
- Pages that want a bento grid with one wide card per row and a detail view that opens in place.

### When not to use

- Use use-case-gallery for a browsable set of customer or use case stories.
- Use expandable-card when you need a single card that expands, not a whole feature grid.
- Use feature-illustration for one static feature explained with an illustration.

### Usage

```tsx
import { SpotlightGrid } from "@/components/arc/blocks/spotlight-grid/spotlight-grid";

export function FeaturesSection() {
  return (
    <section style={{ padding: "96px 24px" }}>
      <SpotlightGrid />
    </section>
  );
}
```

### API

#### SpotlightGrid

A marketing feature grid of four cards (latency, deploys, flags, review). A soft light follows the mouse along the card borders, hovering a card plays a small live preview, and opening a card morphs it into a working detail view in place. Copy, charts, and people are sample data inside the file. Also the default export.

No props.

### Dependencies

- `motion`
- `lucide-react`

### Keyboard

| Keys | Action |
| --- | --- |
| Tab | Moves between the card buttons. Each card title is a button that stretches over the whole card. |
| Enter / Space | Opens the focused card into its detail view; focus moves to the close button. |
| Escape | Closes the open detail view and returns focus to the card that opened it. |
| Arrow keys | Inside a detail view, move and select within the time range and rollout segmented controls. |

### Accessibility

- The section is labelled by its heading. Card buttons carry aria-expanded and aria-controls pointing at the open detail region.
- The open detail is a role="region" labelled by its title, and the grid behind it is made inert.
- Segmented controls are radiogroups with roving tabindex; the flag toggle is a role="switch"; Approve uses aria-pressed.
- The latency chart is a role="img" SVG whose label states the range and p95. Deploy and approval results are announced through a polite live region.
- Mini previews are aria-hidden; the card title and blurb carry the meaning.

### Motion

- The card surface and title share layoutIds with the detail view, so opening grows the card on a spring with a little bounce and closing settles without overshoot.
- The border light tracks the pointer through springs and fades in and out; it only runs for mouse pointers.
- Hover previews: the latency sparkline redraws every 1.1s, the deploy counter ticks every 0.9s, the flag switch and comment pin spring in.
- Charts morph their path between time ranges; changed labels crossfade with a short blur.
- Reduced motion drops the layout morph, the pointer light, and the preview timers. Content fades or switches instantly and previews show their end state.

### Responsive behavior

- The root is a size container named spotlight. Below 520px the grid is one column, from 520px two columns with wide cards spanning both, from 820px three columns.
- Below 520px the detail view opens at the card's own position instead of the top of the grid, and cards, padding, and the chart get smaller.
- The pointer light and hover previews only run for a mouse; on touch, cards simply open on tap.

### Performance

- The pointer light is driven by motion values and CSS variables, so pointer moves do not re-render React.
- Each card reads its offset with a ResizeObserver. Preview intervals only run while a card is hovered or focused.
- useInView starts the first sparkline and tick animations once, when the grid is 30% visible.

### Notes for AI agents

- Use for a landing page feature section where each feature can be tried, not just described.
- All content lives in constants at the top of the file (CARDS, RANGES, SHIPS, COMMENTS). Edit those and the matching Mini and Detail components to present your own features.
- There are no props or callbacks; the deploy, flag, and approval interactions are simulated locally.
- Uses next/image with shared demo portraits from @/components/arc/lib/media, and Arc AnimatedCounter for numbers.

### Keywords

react spotlight grid, feature grid, bento grid, interactive feature section, landing page features, card spotlight hover, expanding feature cards, shared layout card morph

### Related

- expandable-card
- scroll-story

---

## Invite people

Invite teammates with roles, bulk paste validation, a seat meter, and avatars that fly into a pending list.

- Type: Block (composition)
- Access: Pro
- Built from: Motion
- Documentation: https://uiarc.dev/components/blocks/invite-people

### Overview

Use this as a starting point and replace the sample data with your own.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/invite-people. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/invite-people while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- Inviting several people at once by name or email, with a role for each.
- Plans with a seat limit where people should see the effect of an invite before sending.
- Flows where users paste a messy list from a spreadsheet and need clear per-entry errors.

### When not to use

- Use team-members to manage people who already joined.
- Use roles-permissions to edit what each role can do.
- Use tag-input for a plain chip field without a directory, roles, or seats.

### Usage

```tsx
import { InvitePeople } from "@/components/arc/blocks/invite-people/invite-people";

export function InviteDialogBody() {
  return <InvitePeople />;
}
```

### API

#### InvitePeople

A workspace invite form. People are picked from a directory or typed and pasted as emails, each gets a role, and a seat meter tracks members, pending invites, and the new selection against the plan limit. Sending, joining, resending, revoking, and upgrading are simulated. Also the default export.

No props.

### Dependencies

- `motion`
- `lucide-react`

### Keyboard

| Keys | Action |
| --- | --- |
| Arrow Down / Arrow Up | Moves through the suggestion list, skipping people already on the team or invited. |
| Enter | Adds the highlighted suggestion, or turns the typed text into a chip. |
| , / ; | Commits the typed text as a chip. |
| Backspace | In an empty field, the first press marks the last chip and the second removes it. |
| Escape | Closes the suggestion list, then clears the typed text. |
| Arrow Down (role button) | Opens the role menu for that chip. |
| Arrow Up / Down, Home / End, Escape | Move through and close the role menu; Escape returns focus to the role button. |

### Accessibility

- The field is a combobox with aria-expanded, aria-controls, and aria-activedescendant pointing into a role="listbox" of options; blocked options are aria-disabled.
- Role menus are role="menu" with menuitemradio items and aria-checked.
- The seat bar is a role="meter" with aria-valuetext such as "12 of 10 seats, 2 over the limit".
- Send stays focusable with aria-disabled while blocked and points aria-describedby at the error list or the seat summary.
- Every add, remove, send, join, and revoke is announced in a polite live region.

### Motion

- Avatars share layoutIds, so a person flies from the suggestion into a chip, from the chip into the pending list, and from the row into the team stack when they join.
- Invalid chips shake when you try to send; the over-limit notice shakes on the same attempt.
- Labels that change length resize on a spring and crossfade their text; the field height springs as chips wrap.
- Reduced motion (MotionConfig reducedMotion="user" plus a hydrated flag) removes shakes, offsets, and layout travel and sets durations to zero.

### Responsive behavior

- The card is at most 600px wide and is a size container. Below 440px pending rows move the status under the name and suggestions hide their title column.
- Below 480px viewport width the padding drops to 16px and the corner radius shrinks.
- The role menu is positioned inside the block and clamped 8px from its edges.

### Performance

- AutoWidth and AutoHeight use one ResizeObserver each to spring sizes; there is no per-frame loop.
- Suggestions filter the in-memory directory on every keystroke and show at most five. For a large directory, search on the server and debounce.
- All simulated timers are tracked and cleared on unmount and on reset.

### Notes for AI agents

- Use for inviting teammates to a workspace with per-person roles and a seat limit.
- Replace DIRECTORY, TEAM, INVITED, PLANS, and ROLES in invite-people-data.ts with your own data. parseToken and splitList handle names, bare emails, and "Name <email>" from pasted lists.
- There are no props or callbacks. Wire the send, resend, revoke, and upgrade functions in the component to your API; the timers there only simulate delivery and one accepted invite.
- Error chips explain each bad entry in plain words; clicking one moves its text back into the field for editing.

### Keywords

react invite people, invite teammates form, email chip input, workspace invite, seat limit meter, invite by email, team invite with roles, paste email list

### Related

- team-members
- roles-permissions
- tag-input
- multi-select
- avatar-group

---

## Cart drawer

Products fly into the cart, counts roll, and a drawer handles quantities, shipping progress, and checkout.

- Type: Block (composition)
- Access: Pro
- Built from: Motion
- Documentation: https://uiarc.dev/components/blocks/cart-drawer

### Overview

Use this as a starting point and replace the sample data with your own.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/cart-drawer. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/cart-drawer while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- Product listings where people add several items and review them in a side cart.
- Stores that show a free shipping threshold and promo codes before checkout.
- Demos of an add to cart interaction with clear feedback on where the item went.

### When not to use

- Use checkout-flow for a full multi-step checkout with address and payment.
- Use checkout-summary when you only need the order summary and totals.
- Use drawer for a generic side panel that is not a cart.

### Usage

```tsx
import { CartDrawer } from "@/components/arc/blocks/cart-drawer/cart-drawer";

export function ShopPage() {
  return <CartDrawer />;
}
```

### API

#### CartDrawer

A product grid with a slide-in cart. Adding an item arcs its photo into the cart button, lines can be swiped away, a free shipping bar fills, promo codes validate, and the checkout button folds into a confirmation disc. Products, prices, and the order are sample data; checkout is simulated. Also the default export.

No props.

### Dependencies

- `motion`
- `lucide-react`

### Keyboard

| Keys | Action |
| --- | --- |
| Enter / Space | Adds a product, opens the cart, and runs the quantity, remove, and checkout buttons. |
| Escape | Closes the drawer, except while an order is being placed. Focus returns to the cart button. |
| Enter (promo field) | Applies the promo code. |

### Accessibility

- The cart button has aria-haspopup="dialog", aria-expanded, and a label with the item count. The drawer is role="dialog" with aria-modal and moves focus to its close button.
- The shop behind an open drawer is inert, and the drawer body is inert while an order is placing.
- Quantity steppers are labelled groups; the minus button becomes "Remove" at quantity one. Swipe to remove has button equivalents.
- The shipping bar is a role="progressbar"; an invalid promo sets aria-invalid and swaps the note under the field.
- Adds, removals, promo changes, and the placed order are announced in a polite live region.

### Motion

- The product photo flies along a quadratic arc into the cart over 780ms, shrinking and tilting; the badge count only changes when it lands, then the cart bumps and rings.
- The drawer slides in on a critically damped spring. Rows collapse in height when removed and the totals roll with AnimatedCounter.
- Swipe a row left past 110px, or flick it, to remove; short drags snap back with the release velocity.
- The checkout button shares a layoutId with the confirmation disc, then a checkmark draws in.
- Reduced motion skips the flight and the bump, disables row dragging, fades the drawer instead of sliding it, and zeroes the remaining springs.

### Responsive behavior

- The root is a size container. Above 640px the grid has three columns; at 640px and below it has two, with tighter padding.
- At 380px and below the cart label hides, prices stack under names, and the drawer fills the block with a 4px inset.
- Rows accept horizontal drag with direction lock, so vertical scrolling in the drawer still works on touch.

### Performance

- Each flight is driven by one motion value and transforms, not React state per frame; several flights can overlap.
- The drawer and scrim only mount while open; timers are cleared on unmount.
- Product images use next/image with sizes for 50vw on small screens and 260px otherwise.

### Notes for AI agents

- Use for an ecommerce page where adding to cart and reviewing the cart happen without leaving the grid.
- Replace PRODUCTS (with PhotoId images from @/components/arc/lib/media) and the FREE_SHIPPING, SHIPPING, and PROMO constants; swap the image source for your own URLs if needed.
- There are no props. Connect the add, setQty, remove, applyPromo, and checkout functions to your cart store and payment flow; checkout currently waits 1.3s and shows a sample receipt.
- Composes Arc Button and AnimatedCounter.

### Keywords

react cart drawer, shopping cart drawer, add to cart animation, slide out cart, ecommerce cart, free shipping progress bar, swipe to remove cart item, promo code field

### Related

- checkout-summary
- drawer
- swipe-actions
- number-field

---

## Pricing calculator

A seat slider and billing toggle drive plan cards with rolling prices and a moving recommended badge.

- Type: Block (composition)
- Access: Pro
- Built from: Motion
- Documentation: https://uiarc.dev/components/blocks/pricing-calculator

### Overview

Use this as a starting point and replace the sample data with your own.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/pricing-calculator. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/pricing-calculator while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- Per-seat pricing where showing the exact total for a team size helps people choose.
- Pricing pages with a monthly and yearly toggle and a visible yearly saving.
- Plans with seat caps or volume discounts that are hard to explain in a static table.

### When not to use

- Use usage-pricing when price depends on metered usage rather than seats.
- Use plan-comparison for a feature by feature table across plans.
- Use billing-toggle when you only need the monthly and yearly switch.

### Usage

```tsx
import { PricingCalculator } from "@/components/arc/blocks/pricing-calculator/pricing-calculator";

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

### API

#### PricingCalculator

A seat based pricing section. A slider picks team size from fixed seat stops, a billing toggle switches monthly and yearly, and three plan cards update prices, totals, volume discounts, and features live. The recommended plan follows the seat count. Plans and prices are constants in the file; the trial is simulated. Also the default export.

No props.

### Dependencies

- `motion`
- `lucide-react`

### Keyboard

| Keys | Action |
| --- | --- |
| Arrow keys / Home / End / Page Up / Page Down | Native range input: moves between seat stops. |
| Arrow keys | In the billing toggle, switch between monthly and yearly and move focus with the selection. |
| Enter / Space | Chooses a plan, steps seats with the plus and minus buttons, and starts the trial. |

### Accessibility

- The slider is a native range input labelled "Team size" with aria-valuetext such as "20 seats".
- Billing is a radiogroup with roving tabindex; plan buttons use aria-pressed for the selected plan.
- Each plan card is labelled by its heading, and each feature list is labelled with the plan name.
- Billing changes, plan picks, and the started trial are announced in a polite live region.

### Motion

- The selection frame and the Recommended badge are shared layout elements that travel between cards on a spring.
- Prices and totals roll with AnimatedCounter; changed copy crossfades with a short blur.
- Features that appear or disappear with the seat count open and close in height.
- Reduced motion removes the offsets and blur and sets layout and height transitions to zero.

### Responsive behavior

- The root is a size container. At 860px and below the three plan cards stack in one column.
- At 560px and below padding and the title shrink, and the controls tighten.
- At 360px and below the savings line and switch button wrap onto several lines.

### Performance

- State is a seat index, billing period, and picked plan; everything else is derived on render.
- Twenty three seat stops and three cards, so no memoization or virtualization is needed.

### Notes for AI agents

- Use for per-seat SaaS pricing where the right plan depends on team size and billing period.
- Edit STOPS, PLANS, recommend, and seatPrice to match your pricing. Starter has maxSeats 10; picking more shows a limit note and a button to drop back to 10 seats.
- Volume pricing takes $2 off each seat from 25 seats and $4 from 100 on Team and Business.
- There are no props. Wire startTrial to your signup or checkout; it currently waits 1.1s. Composes Arc Button and AnimatedCounter.

### Keywords

react pricing calculator, seat pricing slider, per seat pricing, pricing page, monthly yearly toggle, saas pricing plans, team size pricing, volume discount pricing

### Related

- usage-pricing
- plan-comparison
- billing-toggle
- slider

---

## Gantt timeline

A project timeline with draggable, resizable bars, dependency arrows that follow them, and animated zoom.

- Type: Block (composition)
- Access: Pro
- Built from: Motion
- Documentation: https://uiarc.dev/components/blocks/gantt-timeline

### Overview

Use this as a starting point and replace the sample data with your own.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/gantt-timeline. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/gantt-timeline while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- Planning work across weeks or months where tasks depend on each other.
- Roadmaps that people reschedule by dragging, with undo and conflict warnings.
- Phase based plans where finished phases can be folded into a summary bar.

### When not to use

- Use project-board for status columns without dates.
- Use week-calendar for time slots within days.
- Use timeline for a read-only list of dated events.

### Usage

```tsx
"use client";

import { useState } from "react";
import { GanttTimeline } from "@/components/arc/blocks/gantt-timeline/gantt-timeline";
import type { GanttGroup, GanttTask } from "@/components/arc/blocks/gantt-timeline/gantt-timeline";

const groups: GanttGroup[] = [
  { id: "design", name: "Design" },
  { id: "build", name: "Build" },
];

const initial: GanttTask[] = [
  { id: "wires", name: "Wireframes", group: "design", start: "2026-10-05", end: "2026-10-09", progress: 1 },
  { id: "ui", name: "Visual design", group: "design", start: "2026-10-12", end: "2026-10-23", progress: 0.4, dependsOn: ["wires"] },
  { id: "api", name: "API", group: "build", start: "2026-10-12", end: "2026-10-30", progress: 0.2 },
  { id: "beta", name: "Beta", group: "build", start: "2026-11-02", end: "2026-11-02", milestone: true, dependsOn: ["ui", "api"] },
];

export function Roadmap() {
  const [tasks, setTasks] = useState(initial);
  return (
    <GanttTimeline
      title="Q4 roadmap"
      groups={groups}
      defaultTasks={initial}
      tasks={tasks}
      onTasksChange={(next, change) => {
        setTasks(next);
        if (change.kind === "move" || change.kind === "resize") {
          void fetch("/api/tasks/" + change.id, { method: "PATCH", body: JSON.stringify({ start: change.start, end: change.end }) });
        }
      }}
      today="2026-10-14"
      defaultCollapsed={[]}
    />
  );
}
```

### API

#### GanttTimeline

A project timeline with tasks grouped by phase. Drag a bar to move it or its edges to change dates, snapped to whole days. Dependency arrows re-route as bars move and turn red when a task starts before one it depends on ends. Zoom glides between day, week, and month. Also the default export.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` | `string` | `"App relaunch"` | Heading in the toolbar and the section's accessible name. |
| `groups` | `GanttGroup[]` | `GROUPS` | Phases in display order. Each task's group field refers to a group id. |
| `tasks` | `GanttTask[]` |  | Controlled tasks. Pair with onTasksChange. |
| `defaultTasks` | `GanttTask[]` | `TASKS` | Starting tasks when uncontrolled. Also sets the calendar range once on mount and is what Reset restores. |
| `onTasksChange` | `(tasks: GanttTask[], change: GanttChange) => void` |  | Called after a move, resize, undo, or reset with the full list and what changed. |
| `today` | `string` | `"2026-09-23"` | ISO date that places the today line and the initial scroll. |
| `zoom` | `GanttZoom` |  | Controlled zoom: "day", "week", or "month". |
| `defaultZoom` | `GanttZoom` | `"week"` | Starting zoom when uncontrolled. |
| `onZoomChange` | `(zoom: GanttZoom) => void` |  | Called when the zoom control changes. |
| `collapsed` | `string[]` |  | Controlled ids of folded groups. |
| `defaultCollapsed` | `string[]` | `["discovery"]` | Groups folded on first render when uncontrolled. |
| `onCollapsedChange` | `(ids: string[]) => void` |  | Called when a group is folded or unfolded. |
| `className` | `string` |  | Extra class on the root section. |

#### GanttTask

Exported type. { id: string; name: string; group: string; start: string; end: string; progress?: number; assignee?: PersonId; dependsOn?: string[]; milestone?: boolean }. Dates are ISO days and end is inclusive; a milestone uses start only. progress runs from 0 to 1.

No props.

#### GanttGroup

Exported type. { id: string; name: string }.

No props.

#### GanttChange

Exported type passed to onTasksChange. { id: string; start: string; end: string; kind: "move" | "resize" | "undo" | "reset" }.

No props.

### Dependencies

- `motion`
- `lucide-react`

### Keyboard

| Keys | Action |
| --- | --- |
| Tab | Moves into the chart; one bar is tabbable at a time. |
| Arrow Down / Arrow Up | Moves focus to the next or previous visible bar and scrolls it into view. |
| Alt + Arrow Left / Right | Moves the focused task by one day. |
| Alt + Shift + Arrow Left / Right | Changes the focused task's end date by one day. |
| Enter / Space | Selects or deselects the focused bar, highlighting its dependency arrows. |
| Escape | Clears the selection. |

### Accessibility

- Bars are role="button" with aria-roledescription "Task bar" or "Milestone", aria-pressed for selection, and a label with name, dates, percent done, and a warning when a dependency is violated.
- Every bar is described by hidden text that explains the Alt and Alt Shift shortcuts.
- Folded rows are aria-hidden and inert; group toggles carry aria-expanded.
- The zoom control is a group of aria-pressed buttons. The footer status is role="status" and reports each change and conflict.
- The calendar header, grid lines, arrows, and summary bars are aria-hidden.

### Motion

- Bars, arrows, group summaries, and task rows read the same motion values, so they move together without drifting.
- After a drag, the bar springs to the snapped day from its release velocity; a dashed snap target and a date label show while dragging.
- Shortening past one day resists with a soft rubber band instead of stopping.
- Zoom animates the day scale on a spring while keeping the middle of the view fixed; the header tiers crossfade.
- Folding a group slides its rows up into the group row and fades them.
- Reduced motion jumps bars, rows, scale, and scroll to their targets and removes the crossfades.

### Responsive behavior

- When the scroller is under 560px wide, the sticky task column narrows from 248px to 132px.
- Bars under 96px wide hide their name and bars under 36px hide their percentage, through container queries on each bar.
- The chart scrolls horizontally, and dragging near either edge scrolls the view along with the bar.
- Below 480px viewport width the root padding and task row indent shrink.

### Performance

- Drag, zoom, and row folding update motion values; React re-renders only on commit and when the snapped day changes.
- Each dependency arrow recomputes its path from motion values every frame while something moves; keep plans in the tens of tasks.
- The header and grid lines render one element per day at day zoom, so very long ranges add DOM weight.

### Notes for AI agents

- Use for project plans with phases, dependencies, and drag to reschedule.
- The calendar range is computed once on mount from defaultTasks and today, starting on a Monday with a week before and three weeks after. In controlled mode pass defaultTasks as well, or the calendar spans the sample data.
- onTasksChange reports each move or resize as ISO start and end dates; persist change.id with those dates. Undo keeps the last 20 changes.
- Assignee avatars come from @/components/arc/lib/media PersonId portraits; tasks without one show a plain marker.
- Dependency conflicts are shown, not prevented. Validate on the server if a violation must be blocked.

### Keywords

react gantt chart, gantt timeline, project timeline, drag to reschedule, task dependencies, roadmap timeline, project planning chart, resizable task bars

### Related

- project-board
- week-calendar
- timeline
- workflow-canvas
- tree-table

---

## AI chat

A full-screen AI chat where answers stream in as markdown with folding reasoning, tool chips and cited sources. People can switch chats and models, edit or retry a message into versions, rate replies and stop a reply mid-stream.

- Type: Block (composition)
- Access: Pro
- Built from: Button, Copy button, Hover card, Tooltip, Text shimmer
- Documentation: https://uiarc.dev/components/blocks/ai-chat

### Overview

Use it as the main assistant screen of an app. Pass respond(messages, { signal, model }) as an async iterable of events (reasoning, tool, sources, text deltas, error) to stream a real model; Stop aborts the signal. initialMessages, history, models, suggestions, onFeedback, onModelChange and onNewChat wire it to your data. It fills its container; set --chat-height to embed it smaller and --chat-column for the conversation width.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/ai-chat. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/ai-chat while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- A multi turn assistant inside a product page, drawer or dashboard card, with streaming answers, reasoning, tools and citations.
- Any place users need to retry, edit, rate or copy answers and switch models mid conversation.
- Prototyping an LLM feature: with no props it plays a realistic scripted conversation and answers new messages with simulated replies.

### When not to use

- Use ai-composer when you only need the prompt box with attachments, mentions and commands.
- Use ai-answer for a single question and a long, article like answer with sources.
- Use agent-run or research-run when the work is a multi step agent run with a plan and progress rather than a conversation.
- Use model-picker for a standalone model selector with pricing and context details.

### Usage

```tsx
import { AiChat } from "@/components/arc/blocks/ai-chat/ai-chat";
import type { ChatRespond } from "@/components/arc/blocks/ai-chat/ai-chat";

// Map your API's stream onto chat events. Text can arrive in any chunk size; the chat paces it.
const respond: ChatRespond = async function* (messages, { signal, model }) {
  const response = await fetch("/api/chat", {
    method: "POST",
    body: JSON.stringify({ model: model.id, messages: messages.map(({ role, content }) => ({ role, content })) }),
    signal,
  });
  const reader = response.body!.pipeThrough(new TextDecoderStream()).getReader();
  while (true) {
    const { value, done } = await reader.read();
    if (done) break;
    yield { type: "text", delta: value };
  }
};

export function SupportChat() {
  return <AiChat respond={respond} onFeedback={(message, value) => track("reply_feedback", { id: message.id, value })} />;
}
```

### API

#### AiChat

A focused AI chat card. A slim header holds the conversation title (a menu of recent chats), a model chip with a compact model menu and a New chat button. The thread scrolls inside the card and follows new text while it streams. User turns are quiet right aligned bubbles that can be copied or edited; assistant turns are unboxed, with a small model mark, a "Thought for 4s" line that folds open, tool chips that open their searches, sources or query, and markdown answers with lists, inline code, code blocks with copy and numbered citations that preview their source on hover. Copy, retry and feedback appear on hover, and an edit or retry adds a version shown as a "2 / 2" switcher. The composer autosizes, takes attachments and turns its send button into Stop while a reply streams. Empty, thinking, streaming, stopped and error states are all built in.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `respond` | `(messages: AiChatMessage[], options: { signal: AbortSignal; model: ChatModel }) => AsyncIterable<ChatStreamEvent>` |  | Streams one reply for the messages on screen. Yield { type: "reasoning", delta }, { type: "reasoning-end", seconds? }, { type: "tool", tool } (upserted by id), { type: "sources", sources } and { type: "text", delta }; the reply ends when the iterable finishes. Throw or yield { type: "error", message } to fail it with a Retry. Stop aborts the signal. Without it the chat answers with scripted, simulated replies. |
| `models` | `ChatModel[]` | `sampleModels` | Models in the header menu: { id, name, note?, mark, color? }. The mark is any SVG component; color tints a mono mark. Samples are Claude Opus 5.5, Claude Sonnet 5.5, GPT-6.1 Sol, Gemini 4 Argon and Mistral Large 4. |
| `defaultModel` | `string` |  | Id of the model selected first. Defaults to the first model. |
| `initialMessages` | `AiChatMessage[]` |  | The open conversation, alternating user and assistant messages. Assistant messages can carry model, reasoning, thoughtFor, tools, sources and status. A trailing user message is answered when the card first scrolls into view. |
| `title` | `string` |  | Title of the open conversation. Defaults to one taken from its first message. |
| `history` | `AiChatHistoryItem[]` |  | Earlier conversations in the title menu: { id, title, group?, messages }. Each opens settled at its latest message and keeps its own scroll position. Defaults to sample chats only in the simulated preview. |
| `suggestions` | `ChatSuggestion[]` | `sampleSuggestions` | Up to three prompts in the empty state: { label, prompt?, icon? } where icon is "database", "timer", "activity" or "search". |
| `greeting` | `string` | `"What are we working on?"` | Heading of the empty state. |
| `placeholder` | `string` | `"Ask anything"` | Composer placeholder. |
| `autoPlay` | `boolean` |  | Plays a two turn scripted conversation once the card is in view. Defaults to true only without respond and initialMessages. Typing, sending or switching chats stops it. |
| `onFeedback` | `(message: AiChatMessage, value: "up" \| "down" \| null) => void` |  | Called when a reply is rated or the rating is cleared. Without it the preview records the rating locally and announces it as simulated. |
| `onModelChange` | `(model: ChatModel) => void` |  | Called when a model is picked. New replies use it; earlier replies keep the mark of the model that wrote them. |
| `onNewChat` | `() => void` |  | Called by the New chat button and menu item. |
| `className` | `string` |  | Class on the root. It fills its container's width and the screen's height; set --chat-height to fit a smaller area and --chat-column (default 760px) for the width of the conversation column. |

### Dependencies

- `motion`
- `lucide-react`
- `@radix-ui/react-dropdown-menu`
- `@radix-ui/react-tooltip`
- `@radix-ui/react-popover`

### Keyboard

| Keys | Action |
| --- | --- |
| Enter | In the composer, sends the message. In the edit field, sends the edited message as a new version. |
| Shift + Enter | Adds a new line in the composer or the edit field. |
| Escape | In the composer, stops a streaming reply. In the edit field, cancels the edit. In a menu, closes it and returns focus to its chip. |
| Tab | Moves through the chat menu, model chip, New chat, each message's actions, reasoning and tool toggles, citations and the composer controls. |
| Arrow up / Arrow down | Moves through the chat and model menus; Enter or Space picks the highlighted row. |

### Accessibility

- The card is a labelled section. Each turn is an article; a reply that is still thinking or streaming sets aria-busy.
- A polite status region announces when a reply starts, finishes, stops or fails, model and chat changes, copy results and feedback. In the preview every scripted reply and rating is announced as simulated.
- The reasoning line and tool chips are buttons with aria-expanded and aria-controls. Citations are links named "Source 2: title, domain" and open a read only preview on hover or keyboard focus.
- Icon buttons carry specific names (Copy, Retry, Good response, Bad response, Edit, Attach files, Send message or Stop reply), and the thumbs expose aria-pressed.
- Status is never color alone: errors pair an icon with "Reply failed" and the message, a stopped reply says Stopped, and a failed tool shows an alert icon with its summary.
- The version switcher is a labelled group ("Version 2 of 2") with Previous and Next buttons.
- Pointer focus draws no ring; keyboard focus shows Arc's shared focus ring.

### Motion

- Answers stream in chunks of three or four whole words every 34ms on a requestAnimationFrame clock (about 90 to 120 words per second). Each chunk is its own span that fades in once over 150ms; nothing already on screen re-renders, moves or blurs, and list markers and code fences never appear before their first word.
- Thinking and running tools use a calm text shimmer that stops when they finish. Labels such as Thinking to "Thought for 4s", tool states, the model chip and the title swap with one crossfade (100ms out, 160ms in from 2px) while the box follows the measured width on a critically damped spring.
- Reasoning, tool details and attachments fold open by height on a spring with no bounce. Switching versions or opening the editor glides the turn to its new height and fades the new content in.
- While stuck to the bottom the thread follows new lines on a soft lerp, so text glides up instead of jumping a line at a time. Scrolling up releases it and shows a jump to latest button.
- Switching chats crossfades the thread (out in 100ms, in over 160ms from 4px), restores that chat's scroll position and never replays finished replies. Menus fade and scale from their trigger.
- Reduced motion drops the chunk fade, travel and smooth scrolling and keeps every state, label and announcement.

### Responsive behavior

- It fills the screen: the header spans the full width while the conversation and composer stay in one centered column (760px by default, set --chat-column). Set --chat-height to embed it in a smaller area. It works from 320px wide.
- Padding, bubble width and the source list adapt to the card's own width through container queries, so it fits a sidebar as well as a page.
- The header title truncates before the model chip and New chat button move; code blocks scroll sideways inside themselves.
- On touch screens message actions are always visible instead of appearing on hover.

### Performance

- Turns are memoized; while a reply streams only that turn re-renders, once per 34ms tick.
- Streaming text is parsed from the revealed slice each tick with a small linear parser, and settles into plain strings 240ms after the last chunk.
- The stream is aborted on Stop, on a new message and on unmount, and the reveal clock only runs while a reply is streaming.

### Notes for AI agents

- Use it when the conversation itself is the product surface: support, internal assistants, docs Q&A or a copilot card. Wire `respond` to your API and map its stream to events; yield text deltas in whatever size they arrive, because the reveal clock paces them.
- Markdown support is deliberately small: paragraphs, ordered and bulleted lists, short headings, **bold**, `inline code`, fenced code blocks and [n] citations that index into the sources event (1 based). Keep answers in that subset.
- Send sources before the text that cites them. A citation with no matching source renders as a plain number.
- Tools are upserted by id: yield the same id with status "running", then "done" or "error", plus a short summary such as "4 sources" or "40,213,880 rows". Give a tool `sources` for a search or `input` and `output` for a query.
- Messages passed to `respond` follow the visible branch only. An edit or retry adds a version, and later turns belong to the version they followed.
- Real model names and marks are sample content. Use only models you actually offer.

### Keywords

ai chat, chatbot, llm chat, assistant, streaming, markdown, reasoning, thinking, tool calls, citations, model switcher, regenerate, message versions, chat history, stop generating, claude, gpt, gemini

### Related

- ai-composer
- ai-answer
- model-picker
- research-run
- agent-run
- text-shimmer
- context-window

---

## Checkout summary

An order summary with a promo code that becomes a chip, discount and tax lines, and pay button states.

- Type: Block (composition)
- Access: Pro
- Built from: Motion
- Documentation: https://uiarc.dev/components/blocks/checkout-summary

### Overview

Use this as a starting point and replace the sample data with your own.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/checkout-summary. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/checkout-summary while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- The last step before a hosted checkout such as a Stripe session redirect.
- A single product purchase with launch discounts or promo codes.
- A pricing page side panel that confirms the final total.

### When not to use

- Use checkout-flow when you collect shipping and card details in the page.
- Use cart-drawer for a cart with several items and quantities.
- Use billing-overview for an existing subscription's invoices and plan.

### Usage

```tsx
import { CheckoutSummary } from "@/components/arc/blocks/checkout-summary/checkout-summary";

export function Checkout() {
  return (
    <CheckoutSummary
      item={{ name: "Arc Pro", description: "All components and blocks", price: 199, period: "one payment" }}
      adjustments={[{ id: "launch", label: "Launch price", amount: -50, note: "38 of 50 left" }]}
      coupon={{
        onApply: async code => {
          const res = await fetch("/api/coupon", { method: "POST", body: JSON.stringify({ code }) });
          return res.json();
        },
      }}
      tax={{ label: "Tax", note: "Calculated at checkout" }}
      form={{ action: "/api/checkout", fields: { plan: "pro" } }}
      payLabel={total => `Continue to payment, ${total}`}
    />
  );
}
```

### API

#### CheckoutSummary

An order summary for the last step before payment, with discount lines, a promo code field, a counting total, and a pay button that moves from idle to processing to paid. Without item it renders a sample order with simulated code and payment.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `item` | `CheckoutSummaryItem` |  | The product: name, price, and optional description, period, and media. Omit it to render the built-in sample order. |
| `adjustments` | `CheckoutSummaryLine[]` | `[]` | Automatic lines, each with id, label, amount (negative for a discount), and optional note. |
| `coupon` | `{ onApply: (code: string) => Promise<CheckoutCouponResult>; placeholder?: string }` |  | Enables the promo code field. onApply resolves { ok: true, code, label?, amount } or { ok: false, message }. Validate on your server. |
| `tax` | `{ label: string; rate?: number; note?: string }` |  | Tax line. With rate the amount is computed from the discounted subtotal; without it note, or Calculated at checkout, is shown. |
| `currency` | `string` | `"$"` | Symbol before amounts. |
| `title` | `string` | `"Order summary"` | Heading, also the section's accessible name. |
| `payLabel` | `(total: string) => string` | `total => `Pay ${total}`` | Pay button label. Receives the formatted total. |
| `onPay` | `() => Promise<void>` |  | Client-side payment. Resolve to show success, reject to show an error and Try again. |
| `form` | `{ action: string; fields?: Record<string, string> }` |  | Posts a native form instead, such as to a route that creates a hosted checkout session. fields become hidden inputs. |
| `secureNote` | `ReactNode` | `"Encrypted payment"` | Line beside the lock under the button. |
| `successLabel` | `string` | `"Paid"` | Button label once onPay resolves. |
| `disabled` | `boolean` | `false` | Shows the button but blocks payment, such as before checkout opens. |
| `footnote` | `ReactNode` |  | Small print under the button. |
| `className` | `string` |  | Extra class on the root section. |

#### CheckoutSummaryItem

The product being bought.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `name` (required) | `string` |  | Product name, truncated on one line. |
| `description` | `string` |  | Short line under the name. |
| `price` (required) | `number` |  | Price before adjustments. Shown as the subtotal. |
| `period` | `string` |  | Note under the price, such as one payment or per year. |
| `media` | `ReactNode` |  | Thumbnail or mark in a 44px tile. |

#### CheckoutSummaryLine

An adjustment line.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `id` (required) | `string` |  | Stable key. "coupon" is used by the applied code line. |
| `label` (required) | `string` |  | Line label. |
| `amount` (required) | `number` |  | Amount added to the subtotal. Negative for a discount, which is tinted. |
| `note` | `string` |  | Short note under the label, such as 38 of 50 left. |

### Dependencies

- `motion`
- `lucide-react`

### Keyboard

| Keys | Action |
| --- | --- |
| Enter | In the promo code field, applies the code. An empty field keeps focus. |
| Enter / Space | On the remove button of an applied code, removes it and returns focus to the field. |

### Accessibility

- The block is a section labelled by title with an h3 heading.
- The promo field has a visually hidden label. Errors set aria-invalid, aria-describedby, and a role="alert" message.
- The applied code chip has a remove button labelled Remove code followed by the code.
- The pay button is aria-live="polite", so Processing, Paid, and Try again are announced. A payment error adds a role="alert" line.
- The total has visually hidden formatted text, while the rolling digits are aria-hidden.

### Motion

- Adjustment and coupon lines open with a height spring and fade.
- The promo form swaps to the applied chip with a small scale and blur. An invalid code shakes the field horizontally for 360ms.
- The total rolls through AnimatedCounter. The pay button's label and icon swap with a rise and blur on each state change, and a spinner turns while processing.
- Reduced motion skips the shake, makes lines appear instantly, reduces swaps to fades, and slows the spinner to 1.6s per turn.

### Responsive behavior

- The card is up to 440px wide and fills narrower containers. Padding scales between 20px and 28px with the viewport.
- The product name truncates on one line; the price column stays unwrapped.
- Hover styles apply only on fine pointers. Buttons scale down slightly on press.

### Performance

- One pageshow listener per instance. No timers except those in the sample handlers.
- Only the total uses AnimatedCounter. Line and button animations run on state changes only.

### Notes for AI agents

- Choose it for a one-product order summary before payment. Use checkout-flow for a multi-step checkout with address and payment fields, and cart-drawer for many items.
- Pass either onPay for a client-side payment or form for a server route that redirects to a hosted checkout. With form, the button shows Processing on submit and resets on back-forward cache restore.
- Always pass item in production. Without it the block uses a sample order, a WELCOME10 test code, and a simulated payment.
- Coupon amounts are positive in CheckoutCouponResult and are subtracted. The subtotal never goes below zero; decimals switch to two when any amount is fractional.

### Keywords

react checkout summary, order summary, promo code field, coupon input, pay button states, checkout total, stripe checkout summary

### Related

- cart-drawer
- billing-toggle
- action-button
- money-input

---

## Site header

A sticky website header that turns solid on scroll, with a gliding active link, mega menu panels, and a mobile sheet.

- Type: Block (composition)
- Access: Free
- Built from: Motion
- Documentation: https://uiarc.dev/components/blocks/site-header

### Overview

Use this as a starting point and replace the sample data with your own.

### Install

```bash
npx shadcn@latest add https://uiarc.dev/r/site-header.json
```

With `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`: `npx shadcn@latest add @uiarc/site-header`

### When to use

- The top bar of a marketing site, landing page, or docs site.
- Product sites with grouped destinations that deserve a mega menu with a feature card.
- Pages that need one clear sign-up action in the header.

### When not to use

- Use workspace-sidebar or sidebar-rail inside a signed-in app.
- Use morph-nav for a single-surface animated navigation with built-in search.
- Use menubar for application commands.

### Usage

```tsx
import { SiteHeader } from "@/components/arc/blocks/site-header/site-header";

export function MarketingHeader() {
  return (
    <SiteHeader
      variant="simple"
      brand={{ name: "Acme", href: "/", mark: <Logo /> }}
      items={[
        { value: "product", label: "Product", href: "/product" },
        { value: "pricing", label: "Pricing", href: "/pricing" },
        { value: "docs", label: "Docs", href: "/docs" },
      ]}
      current="pricing"
      secondaryAction={{ label: "Sign in", href: "/sign-in" }}
      primaryAction={{ label: "Start free", href: "/sign-up" }}
    />
  );
}
```

### API

#### SiteHeader

A marketing site header in three variants. It turns solid once the page scrolls, and on narrow containers the links move into a sheet.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"simple" \| "centered" \| "mega"` | `"mega"` | `simple` puts links beside the brand, `centered` centers them in a quiet capsule, `mega` opens panels for items with links. |
| `brand` | `{ name: string; href?: string; mark?: ReactNode }` | `{ name: "Arc" }` | Brand at the start of the bar. |
| `items` | `SiteHeaderItem[]` | `siteHeaderExampleItems` | Top level destinations: { value, label, href?, links?, feature? }. Items with links open a panel in the mega variant. |
| `current` | `string` |  | Value of the item that holds the current page (controlled). |
| `defaultCurrent` | `string` |  | Initial current item when uncontrolled. |
| `onCurrentChange` | `(value: string) => void` |  | Called when a destination inside an item is chosen, with that item's value. |
| `onNavigate` | `(destination: { label: string; href?: string; section?: string }) => void` |  | Called for every destination: items, panel links, the brand, and actions with an href. |
| `secondaryAction` | `{ label: string; href?: string; onClick?: () => void } \| null` | `{ label: "Sign in" }` | A quiet action before the primary one. Pass null to hide it. |
| `primaryAction` | `{ label: string; href?: string; onClick?: () => void } \| null` | `{ label: "Get Arc" }` | The one primary action. Pass null to hide it. |
| `sticky` | `boolean` | `true` | Sticks to the top of its scroll container. |
| `scrollContainer` | `RefObject<HTMLElement \| null>` |  | The element that scrolls, when it is not the window. |
| `scrollThreshold` | `number` | `8` | Pixels of scroll before the background turns solid. |
| `label` | `string` |  | Accessible name of the navigation landmark. |
| `className` | `string` |  | Extra class on the header. |

#### SiteHeaderBlock

Default export: a preview with a variant switcher over a small scrolling page.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `SiteHeaderVariant` | `"mega"` | Initial variant. |

### Dependencies

- `motion`
- `lucide-react`

### Keyboard

| Keys | Action |
| --- | --- |
| ArrowLeft / ArrowRight | Move between top level items in the mega variant. |
| ArrowDown | On an item with links, opens its panel and focuses the first link. |
| ArrowUp / ArrowDown / Home / End | Move between links inside an open panel. |
| Escape | Closes the open panel or the mobile sheet and returns focus to its trigger. |

### Accessibility

- A labelled nav landmark; the current item is marked with aria-current.
- Panel triggers expose aria-expanded; outside presses and Escape close whichever layer is open.
- The mobile sheet locks page scroll while open and returns focus to the menu button when closed.

### Motion

- Mega panels open on hover after a short intent delay and close after a leave grace; switching items morphs the panel to the new content.
- The header background turns solid past scrollThreshold.
- Reduced motion removes panel travel and uses fades.

### Responsive behavior

- It is a container-query component: below 760px of its own width the links, panels, and wide actions hide and a menu button opens a sheet.
- From 760px the sheet and scrim are removed; widening the container closes an open sheet.
- Hover-to-open panels only apply to fine pointers.

### Performance

- Panels mount only while open; the scroll listener updates a single solid-state attribute.
- Feature images use next/image with sizes set, so they load only when a panel opens.

### Notes for AI agents

- Choose it for marketing and docs sites. For in-app navigation use workspace-sidebar or sidebar-rail.
- The defaults are Arc sample content; always pass brand, items, and actions for real sites.
- Links render as anchors when an href is set; wire onNavigate for client-side routing or analytics.
- The mega variant uses next/image for feature images; allow their host in your image config.

### Keywords

react site header, marketing navbar, mega menu, responsive navbar, sticky header, mobile menu sheet, landing page header

### Related

- morph-nav
- site-footer
- hero-section
- breadcrumb

---

## Site footer

A website footer with link columns and newsletter, a minimal layout, and a large fading Arc mark.

- Type: Block (composition)
- Access: Free
- Built from: Motion
- Documentation: https://uiarc.dev/components/blocks/site-footer

### Overview

Use this as a starting point and replace the sample data with your own.

### Install

```bash
npx shadcn@latest add https://uiarc.dev/r/site-footer.json
```

With `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`: `npx shadcn@latest add @uiarc/site-footer`

### When to use

- The closing section of a marketing, docs, or product site.
- Footers that need a newsletter signup and a status link.
- Minimal one-row footers for app shells and docs.

### When not to use

- Use a plain row with breadcrumb or links inside signed-in app screens.
- Use contact-section when the main goal is to start a conversation.

### Usage

```tsx
import { SiteFooter } from "@/components/arc/blocks/site-footer/site-footer";

export function Footer() {
  return (
    <SiteFooter
      brand={{ name: "Acme", href: "/" }}
      tagline="Scheduling for small clinics."
      columns={[
        { title: "Product", links: [{ label: "Pricing", href: "/pricing" }, { label: "Changelog", href: "/changelog" }] },
        { title: "Company", links: [{ label: "About", href: "/about" }, { label: "Careers", href: "/careers" }] },
      ]}
      legal={[{ label: "Privacy", href: "/privacy" }, { label: "Terms", href: "/terms" }]}
      newsletter={{ onSubscribe: email => subscribe(email) }}
      status={{ label: "All systems normal", tone: "success", href: "https://status.example.com" }}
    />
  );
}
```

### API

#### SiteFooter

A site footer in three variants: link columns with a newsletter, one minimal row, or a closing large brand mark.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"columns" \| "minimal" \| "logo"` | `"columns"` | `columns` pairs a newsletter with link columns, `minimal` is one quiet row, `logo` ends in a large fading mark. |
| `brand` | `{ name: string; href?: string; mark?: ReactNode }` | `{ name: "Arc" }` | Brand shown with the tagline. |
| `tagline` | `string` |  | One short line under the brand. |
| `columns` | `{ title: string; links: SiteFooterLink[] }[]` | `siteFooterExampleColumns` | Link columns. |
| `links` | `SiteFooterLink[]` |  | Links for the minimal variant. Defaults to the first link of each column. |
| `legal` | `SiteFooterLink[]` |  | Small links beside the copyright, such as Privacy and Terms. |
| `socials` | `SiteFooterLink[]` |  | Social links. |
| `newsletter` | `{ title?; description?; placeholder?; onSubscribe?: (email: string) => void \| Promise<void> } \| null` |  | Newsletter signup. Throw or reject in onSubscribe to show an error. Pass null to hide it. |
| `status` | `{ label: string; tone?: "success" \| "warning" \| "danger"; href?: string } \| null` |  | A system status link. Pass null to hide it. |
| `year` | `number` |  | Year in the copyright line. |
| `onNavigate` | `(link: SiteFooterLink) => void` |  | Called for every pressed link. Links without an href render as buttons and only call this. |
| `className` | `string` |  | Extra class on the footer. |

#### SiteFooterLink

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` (required) | `string` |  | Link text. |
| `href` | `string` |  | Destination. |
| `external` | `boolean` |  | Opens in a new tab and shows an outward arrow. |

#### SiteFooterBlock

Default export: a preview with a layout switcher.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `SiteFooterVariant` | `"columns"` | Initial variant. |

### Dependencies

- `motion`
- `lucide-react`

### Accessibility

- Renders a footer landmark with labelled link groups.
- The newsletter validates in place with a message tied to the field, and confirms without a toast.
- External links show an outward arrow and open in a new tab.
- Status tone is paired with its label, not shown by color alone.

### Motion

- The subscribe button morphs to its confirmed state while the form keeps its width.
- The logo variant's large mark fades toward the bottom edge.
- Reduced motion swaps states without travel.

### Responsive behavior

- Container queries: below 760px the newsletter stacks above the columns; below 520px columns become two per row and the bottom row stacks.
- Link rows wrap rather than truncate.

### Performance

- Static markup apart from the newsletter form; no observers or timers.

### Notes for AI agents

- Defaults are Arc sample content; pass brand, columns, legal, socials, and newsletter for real sites.
- Pass newsletter={null} and status={null} when you have no backend for them.
- Composes Arc Button and SegmentedControl.

### Keywords

react footer, site footer, footer with newsletter, footer link columns, minimal footer, marketing footer

### Related

- site-header
- hero-section
- faq-section
- contact-section

---

## Hero section

Three full screen SaaS heroes: a live dashboard rising from the bottom edge over a drifting mesh, a workflow graph that routes sample events node by node, and editorial type over a mesh gradient.

- Type: Block (composition)
- Access: Free
- Built from: Button, Line chart, Sparkline, Segmented control, Avatar, Gradient mesh
- Documentation: https://uiarc.dev/components/blocks/hero-section

### Overview

Use this as the first section of a landing page and replace the sample copy and data with your own. Events in the workflow preview are simulated.

### Install

```bash
npx shadcn@latest add https://uiarc.dev/r/hero-section.json
```

With `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`: `npx shadcn@latest add @uiarc/hero-section`

### When to use

- The first section of a SaaS landing page, when the product screen is the pitch (Screenshot).
- Developer tools, automation, and infrastructure products, where showing the product working is the pitch (Workflow).
- A launch or download page that wants one confident line and a sense of atmosphere (Mesh).

### When not to use

- Use page-header for titles inside app screens.
- Use hero-signup when the goal is collecting an email in the first section.

### Usage

```tsx
import { HeroSection } from "@/components/arc/blocks/hero-section/hero-section";

export function Hero() {
  return (
    <HeroSection
      variant="centered"
      primaryAction={{ label: "Start free trial", href: "/sign-up" }}
      secondaryAction={{ label: "Book a demo", href: "/demo" }}
    />
  );
}
```

### API

#### HeroSection

A SaaS landing hero in three designs, each exactly one full screen (100svh) and edge to edge. `centered` (Screenshot) sets a headline over a drifting mesh gradient that fills the screen, with a live revenue dashboard rising from the bottom edge: the window settles from a tilt as it enters and runs off the screen into a fade. `split` (Workflow) puts the copy beside a live workflow graph on a dotted canvas: sample Stripe events run node by node, data draws along each edge, the branch decides which actions run, and every step reports its time. `minimal` (Mesh) is large editorial type over a full mesh gradient with grain, with customer marks along the bottom edge. Pass `title` to render your own content in any layout instead.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"centered" \| "split" \| "minimal"` | `"centered"` | Which design to render. |
| `animateIn` | `boolean` | `true` | Plays the entrance once on mount. |
| `primaryAction` | `HeroAction \| null` |  | The main call to action: { label, href?, onClick?, external?, doneLabel? }. With href it renders a link; without, a button that shows `doneLabel` for a moment after a press. |
| `secondaryAction` | `HeroAction \| null` |  | The second call to action, same shape. |
| `title` | `string` |  | Your own headline. When set, the hero renders your content (HeroContent) in the chosen layout. |
| `description` | `string` |  | Your own content: one or two sentences under the title. |
| `announcement` | `HeroAction \| null` |  | Your own content: a short link above the title for real news. |
| `install` | `{ label: string; command: string }[] \| null` |  | Your own content: the first command is shown with a copy button. |
| `media` | `ReactNode` |  | Your own content: a visual beside the copy in the split layout. |
| `meta` | `string[]` |  | Your own content: small facts under the actions. |
| `className` | `string` |  | Extra class on the section. |

#### HeroLumen

The Screenshot design on its own. The dashboard is real markup built from Arc LineChart, Sparkline, SegmentedControl, and Avatar; its range control changes every figure on screen, and the chart can be scrubbed.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `primaryAction` | `HeroAction` | `{ label: "Start free trial", doneLabel: "Trial started" }` | The main call to action. |
| `secondaryAction` | `HeroAction` | `{ label: "Book a demo" }` | The second call to action. |

#### HeroRelay

The Workflow design on its own: a Relay workflow (Stripe invoice paid, HubSpot lookup, an amount branch, then Slack, Linear, and warehouse actions) that runs sample events on its own while on screen. Send test event runs the next sample at once; a small invoice skips the Slack and Linear steps.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `primaryAction` | `HeroAction` | `{ label: "Start building", doneLabel: "Workspace created" }` | The main call to action. |
| `secondaryAction` | `HeroAction` | `{ label: "Read the docs" }` | The second call to action. |

#### HeroCadence

The Mesh design on its own: type over a mesh gradient, and customer marks drawn in the text color.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `primaryAction` | `HeroAction` | `{ label: "Download for Mac" }` | The main call to action. |

#### HeroMesh

The background renderer: a lean, non-editing version of the Gradient mesh. Points use the editor's model (x, y, spread); colors come from the CSS variables `--mesh-base` and `--mesh-1` onward, so each theme authors its own palette.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `points` | `{ x: number; y: number; spread: number }[]` |  | Up to eight points, bottom to top. |
| `grain` | `number` | `0.35` | Film grain, 0 to 1. |
| `speed` | `number` | `1` | Drift speed; 1 loops every 20 seconds, 0 holds still. |

#### HeroSectionBlock

Default export: the hero full screen with a small glass design switch floating over its top edge; switching replays the entrance.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `HeroSectionVariant` | `"centered"` | Initial design. |

### Dependencies

- `motion`
- `lucide-react`

### Accessibility

- Each design has one h1, and the calls to action are real links or buttons with visible text.
- The dashboard is a labelled group of sample data; its range control is a segmented control and the chart keeps its screen reader table.
- The workflow graph is a labelled group; each step's state has a text label (waiting, running, done, skipped) and its result is written out, never shown by color alone.
- The mesh and glow are decorative and hidden from assistive technology. Pointer focus draws no ring; keyboard focus shows Arc's shared focus ring.

### Motion

- Screenshot: the copy rises in reading order, then the window rises in behind it and settles flat from a tilt.
- Workflow: each step turns to the accent while it runs, the data draws along the edge to the next one, and the result and time swap in with a small spring. The run pauses while the hero is off screen or the tab is hidden.
- Mesh: the gradient drifts on the Gradient mesh editor's seamless 20 second loop.
- Reduced motion removes every transform: no rise or tilt, the mesh draws one still frame, content fades in briefly, and the workflow shows each event as its finished run without playing; Send test event moves to the next one at once.

### Responsive behavior

- Every design is one full screen (100svh, full width) on desktop and phones. Container queries: the split layout stacks below 900px; below 560px padding tightens and actions fill the width.
- The dashboard and the workflow graph are drawn at a fixed design size and scaled like a screenshot. The dashboard switches to a compact layout without the sidebar under 720px and runs off the bottom edge into a fade; the graph switches to compact action nodes on phones.
- On phones the logo row of the Mesh design becomes a grid.

### Performance

- One WebGL canvas at most per hero, drawn at one pixel per CSS pixel and thirty frames a second, only while on screen and the tab is visible. A static CSS render of the same mesh shows first.
- The workflow advances one React state step every few hundred milliseconds only while the hero is on screen and the tab is visible; nothing else loops at rest.

### Notes for AI agents

- The three designs carry sample products (Lumen, Relay, Cadence). Replace the copy in hero-lumen.tsx, hero-relay.tsx, and hero-cadence.tsx, the dashboard data in hero-lumen-data.ts, and the sample events at the top of hero-relay.tsx, or pass title and friends for a plain content hero.
- Mesh colors live in CSS per theme (hero-lumen.module.css and hero-cadence.module.css), in the variables --mesh-base and --mesh-1 onward.
- Brand marks are sample customers from public/block-logos, not endorsements.
- Composes Arc Button, LineChart, Sparkline, SegmentedControl, and Avatar.

### Keywords

react hero section, saas hero, landing page hero, hero with dashboard screenshot, mesh gradient hero, workflow hero, perspective screenshot hero

### Related

- site-header
- logo-marquee
- hero-signup

---

## FAQ section

FAQs as an accordion, a topic rail, or a searchable list that highlights matches.

- Type: Block (composition)
- Access: Free
- Built from: Motion
- Documentation: https://uiarc.dev/components/blocks/faq-section

### Overview

Use this as a starting point and replace the sample data with your own.

### Install

```bash
npx shadcn@latest add https://uiarc.dev/r/faq-section.json
```

With `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`: `npx shadcn@latest add @uiarc/faq-section`

### When to use

- FAQ sections on pricing, product, and support pages.
- Long FAQs that benefit from categories or live search.

### When not to use

- Use accordion for generic collapsible content that is not a question list.
- Use a docs page when answers need code, images, or long structure.

### Usage

```tsx
import { FaqSection } from "@/components/arc/blocks/faq-section/faq-section";

export function PricingFaq() {
  return (
    <FaqSection
      variant="search"
      title="Questions about billing"
      items={[
        { question: "Can I cancel anytime?", answer: "Yes. Your plan stays active until the end of the billing period." },
        { question: "Do you offer refunds?", answer: "We refund annual plans within 14 days of purchase." },
      ]}
      contact={{ label: "Talk to billing", href: "mailto:billing@example.com" }}
    />
  );
}
```

### API

#### FaqSection

An FAQ in three layouts: one centered accordion, questions grouped beside a category rail, or a list that filters as you type.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"accordion" \| "columns" \| "search"` | `"accordion"` | Layout. |
| `title` | `string` | `"Frequently asked questions"` | Section heading. |
| `description` | `string` |  | One line under the heading. |
| `items` | `{ id?: string; question: string; answer: string; category?: string }[]` | `faqExampleItems` | Questions. answer is plain text and is what search matches. category groups the columns variant. |
| `multiple` | `boolean` | `false` | Allow several answers open at once. |
| `value` | `string[]` |  | Open item ids (controlled). Ids default to the question. |
| `defaultValue` | `string[]` |  | Initially open ids when uncontrolled. |
| `onValueChange` | `(value: string[]) => void` |  | Called when answers open or close. |
| `category` | `string` |  | Active category in the columns variant (controlled). |
| `onCategoryChange` | `(category: string) => void` |  | Called when the category changes. |
| `query` | `string` |  | Search text in the search variant (controlled). |
| `onQueryChange` | `(query: string) => void` |  | Called as the search text changes. |
| `contact` | `{ label: string; description?: string; href?: string; onClick?: () => void } \| null` |  | A way to reach a person when the answer isn't here. Pass null to hide it. |
| `className` | `string` |  | Extra class on the section. |

#### FaqSectionBlock

Default export: a preview with a layout switcher.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `FaqSectionVariant` | `"accordion"` | Initial variant. |

### Dependencies

- `motion`
- `lucide-react`

### Keyboard

| Keys | Action |
| --- | --- |
| ArrowUp / ArrowDown | Move between questions in one list. |
| Home / End | First or last question. |
| Enter / Space | Opens or closes the focused answer. |

### Accessibility

- Questions are buttons with aria-expanded controlling their answer region.
- Search matches are wrapped in mark elements; closed items that match only in the answer show a short excerpt.
- The search variant uses Arc SearchField with a real label.

### Motion

- Answers open with height and opacity together and the plus icon turns.
- Filtering and category changes move remaining items with layout animation.
- Reduced motion opens and filters instantly.

### Responsive behavior

- Container queries: below 760px the category rail becomes a horizontal scrolling row above the questions; below 480px padding tightens.

### Performance

- Search filters in memory on each keystroke; fine for dozens of items, not thousands.

### Notes for AI agents

- Keep answers plain text; the search variant matches and highlights inside them.
- Pass stable ids when questions may be reworded, so controlled open state survives edits.
- Composes Arc SearchField and SegmentedControl.

### Keywords

react faq section, faq accordion, searchable faq, faq with categories, frequently asked questions component

### Related

- accordion
- search-field
- contact-section
- hero-section

---

## Contact section

A validated contact form that morphs into a confirmation, support channels, and office cards with local times.

- Type: Block (composition)
- Access: Free
- Built from: Motion
- Documentation: https://uiarc.dev/components/blocks/contact-section

### Overview

Use this as a starting point and replace the sample data with your own.

### Install

```bash
npx shadcn@latest add https://uiarc.dev/r/contact-section.json
```

With `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`: `npx shadcn@latest add @uiarc/contact-section`

### When to use

- Contact pages and sections on marketing sites.
- Sales or support pages that list several channels with response times.
- Companies with offices in several time zones.

### When not to use

- Use support-widget for an in-app help launcher.
- Use signup-form or login blocks for account flows.

### Usage

```tsx
import { ContactSection } from "@/components/arc/blocks/contact-section/contact-section";

export function Contact() {
  return (
    <ContactSection
      title="Talk to us"
      topics={["Sales", "Support"]}
      onSubmit={async message => {
        const response = await fetch("/api/contact", { method: "POST", body: JSON.stringify(message) });
        if (!response.ok) throw new Error("Could not send");
      }}
    />
  );
}
```

### API

#### ContactSection

A contact section in three layouts: a validated form that springs into a confirmation, a list of channels with detail, or offices with live local times and open status.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"form" \| "channels" \| "offices"` | `"form"` | Layout. |
| `title` | `string` |  | Section heading. |
| `description` | `string` |  | One line under the heading. |
| `topics` | `string[]` | `["Sales", "Support", "Partnerships", "Press"]` | Topics offered in the form as a radio group of chips. |
| `onSubmit` | `(message: { name; email; topic; message }) => void \| Promise<void>` |  | Called with a valid message. Reject to keep the form and show an error; resolve to show the confirmation. |
| `channels` | `{ value; label; meta; icon?; detail: ReactNode }[]` | `contactExampleChannels` | Ways to reach you for the channels variant. |
| `channel` | `string` |  | Selected channel (controlled). |
| `defaultChannel` | `string` |  | Initial channel when uncontrolled. |
| `onChannelChange` | `(value: string) => void` |  | Called when the channel changes. |
| `offices` | `{ city; timeZone; address: string[]; email?; hours?: [number, number] }[]` | `contactExampleOffices` | Offices. timeZone is an IANA zone; hours default to 9 to 18 local time. |
| `className` | `string` |  | Extra class on the section. |

#### ContactSectionBlock

Default export: a preview with a layout switcher. Messages are simulated and never sent.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `ContactSectionVariant` | `"form"` | Initial variant. |

### Dependencies

- `motion`
- `lucide-react`

### Keyboard

| Keys | Action |
| --- | --- |
| Arrow keys | Move between topic chips, which form a radio group. |

### Accessibility

- Fields use labelled Arc Input and Textarea; errors appear after the first submit and update as you type.
- A failed send shows a role="alert" message and keeps the form.
- Office open status is written out, not shown by color alone.

### Motion

- The form card springs into the confirmation; faces slide along one axis in the direction of travel out of a soft blur.
- The topic highlight glides between chips.
- Reduced motion swaps faces without travel.

### Responsive behavior

- Container queries: below 820px the form layout stacks and the channel list becomes a horizontal scrolling row; below 520px field rows stack and the submit button fills the width.

### Performance

- The offices variant re-renders every 15 seconds to keep local times live; other variants have no timers.

### Notes for AI agents

- Without onSubmit the form only simulates sending; always wire it in production.
- Offices compute local time and open status with Intl.DateTimeFormat in each timeZone.
- Composes Arc Input, Textarea, Button, CopyButton, SegmentedControl, and Avatar.

### Keywords

react contact form, contact section, contact page, office hours time zones, support channels, validated contact form

### Related

- signup-form
- support-widget
- faq-section
- site-footer

---

## Settings command

Workspace settings where a search field grows into a palette that flies you to any setting.

- Type: Block (composition)
- Access: Pro
- Built from: Switch, Segmented control, Animated counter, Text morph, Button
- Documentation: https://uiarc.dev/components/blocks/settings-command

### Overview

Use this for app or workspace settings with many options. Describe your settings in the data file, load saved values from your API, and persist the changed ids through onSave; saving in the preview is simulated.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/settings-command. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/settings-command while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- Workspace or account settings with several sections and many options.
- Admin consoles where support links people to a specific setting.
- Any settings page where people ask where something lives.

### When not to use

- Use settings-page for a short, paged profile form with a few fields per section.
- Use command-palette for app wide navigation and actions, not just settings.
- Avoid it for a single form; a plain form with a submit button is clearer.

### Usage

```tsx
import { SettingsCommand } from "@/components/arc/blocks/settings-command/settings-command";
import { settingDefinitions, settingsSections } from "@/components/arc/blocks/settings-command/settings-command-data";

export function WorkspaceSettings({ saved }: { saved: Record<string, string | boolean> }) {
  return (
    <SettingsCommand
      sections={settingsSections}
      settings={settingDefinitions}
      defaultValues={saved}
      onSave={async (values, changed) => {
        await fetch("/api/workspace/settings", { method: "PATCH", body: JSON.stringify(Object.fromEntries(changed.map(id => [id, values[id]]))) });
      }}
    />
  );
}
```

### API

#### SettingsCommand

Workspace settings on one scrolling page with a sticky section nav, a search field that grows into a command palette, and an unsaved changes bar. Picking a result flies the palette into the matching row, scrolls it into view, and the row breathes twice.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `sections` | `SettingsSection[]` | `settingsSections` | Sections in page order: id, label, and a one line description. |
| `settings` | `SettingDefinition[]` | `settingDefinitions` | Every setting: id, section, label, description, kind (switch, segmented, select, text), options, keywords for search, placeholder, and prefix. |
| `defaultValues` | `Record<string, string \| boolean>` | `savedSettings` | Saved values keyed by setting id. Edits are compared against these to count unsaved changes. |
| `suggested` | `string[]` | `suggestedSettingIds` | Setting ids listed in the palette before anything is typed. |
| `onSave` | `(values, changedIds) => Promise<void> \| void` |  | Persists the draft. Resolve to confirm; reject to keep the bar open with Retry. Without it the save is simulated. |
| `onValuesChange` | `(values) => void` |  | Called on every edit with the full draft. |
| `title` | `string` | `"Settings"` | Heading beside the search field. |
| `className` | `string` |  | Class on the root. |

### Dependencies

- `motion`
- `lucide-react`

### Keyboard

| Keys | Action |
| --- | --- |
| Command K / Control K / slash | Opens the settings search while focus is inside the block. |
| Arrow up / Arrow down | Moves through results. The input keeps focus; the active result is announced through aria-activedescendant. |
| Enter | Jumps to the active result and moves focus to its control. |
| Escape | Closes the palette back into the search field and returns focus to it. |
| Tab | Moves through section nav, controls, and the Save and Discard buttons. |

### Accessibility

- The palette is a modal dialog with a combobox input and a listbox of options; the scrim closes it on press.
- Each row labels its control with the setting label and describes it with the hint and any validation error.
- Edited rows and sections carry a dot plus visually hidden Edited text, so the state never relies on color.
- A polite status region announces jumps, saves, discards, and validation problems.
- Invalid fields block saving; Save jumps to the first invalid row the same way search does.

### Motion

- The search field grows into the palette: position, size, and corner radius ride one spring, and results are revealed by the growing edge instead of reflowing.
- Picking a result flies the palette into the target row while the page scrolls, then the row's wash swells and settles twice.
- The section nav highlight glides to whichever section is in view as you scroll.
- The unsaved changes bar grows out of a small puck, rolls its count, and shrinks into Settings saved.
- Reduced motion swaps flights for fades, scrolls instantly, and keeps a single soft pulse.

### Responsive behavior

- Below 720px the section nav becomes a scrolling row above the content.
- Below 480px select and segmented rows stack their control under the label; switches stay inline.
- The palette always fits the frame with a 12px margin and drops its hint row on phones.

### Performance

- Search is a synchronous filter over the settings array; it stays instant for a few hundred settings.
- Scroll spy is throttled to one read per animation frame.
- The palette and save bar animate transform, size, and opacity of a single element each.

### Notes for AI agents

- Choose it when a product has more than about 15 settings and people search for them by name.
- Add keywords for the words people actually type, such as 2fa, sso, dark mode, or invoice.
- Keep the data file as the single schema: the palette, nav, and rows all read from it.
- Send only the changed ids to your API through onSave and reject on failure so the bar offers Retry.

### Keywords

settings, preferences, search settings, command palette, jump to setting, unsaved changes, save bar, sticky nav, scroll spy, admin settings

### Related

- settings-page
- command-palette
- security-settings
- switch
- segmented-control

---

## Live checkout

A subscription checkout whose summary recomputes as you edit, then glides to the centre and unfolds into a receipt.

- Type: Block (composition)
- Access: Pro
- Built from: Segmented control, Checkbox, Input, Button, Animated counter
- Documentation: https://uiarc.dev/components/blocks/checkout-live

### Overview

Use this as the paid signup or upgrade step of a SaaS app. Load plans, add-ons and tax rates from your billing provider, check coupons on your server through validateCoupon, and charge through onPay with your payment SDK; the preview simulates payment.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/checkout-live. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/checkout-live while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- Upgrade from a free plan to a paid team plan.
- Paid signup where seats and add-ons change the price.
- A self serve checkout that needs coupons and tax by country.

### When not to use

- A physical goods cart with shipping; use checkout-flow.
- Only showing totals without payment; use checkout-summary.
- Comparing plans before choosing; use plan-comparison.

### Usage

```tsx
import { CheckoutLive } from "@/components/arc/blocks/checkout-live/checkout-live";

export function UpgradePage() {
  return (
    <CheckoutLive
      defaultPlan="team"
      defaultSeats={12}
      validateCoupon={code => fetch(`/api/coupons/${code}`).then(r => r.json())}
      onPay={async order => {
        const res = await fetch("/api/subscribe", { method: "POST", body: JSON.stringify(order) });
        if (!res.ok) throw new Error("Your card was declined. Try another card.");
      }}
    />
  );
}
```

### API

#### CheckoutLive

A subscription checkout with a live order summary. Plan, seats, billing period, add-ons, coupon and country recompute every line and the tax as you edit, and every amount rolls to its new value. On success the form steps aside and the summary glides to the centre and unfolds into a receipt.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `plans` | `Plan[]` | `sample plans` | Plans with an id, name, monthly seat price in cents, and a short blurb. |
| `addons` | `Addon[]` | `sample add-ons` | Optional add-ons with a flat monthly price in cents. |
| `countries` | `Country[]` | `sample countries` | Billing countries with a tax rate, tax label, postal code pattern, and a hint shown when the postal code does not match. |
| `defaultPlan` | `PlanId` | `"team"` | Plan selected on mount. |
| `defaultSeats` | `number` | `8` | Seats on mount, from 1 to 500. |
| `defaultBilling` | `"monthly" \| "yearly"` | `"yearly"` | Billing period on mount. |
| `defaultAddons` | `string[]` | `["support"]` | Add-on ids selected on mount. |
| `yearlyDiscount` | `number` | `0.2` | Discount for yearly billing, from 0 to 1. Shown on the billing toggle. |
| `currency` | `string` | `"USD"` | ISO currency code used to format every amount. |
| `validateCoupon` | `(code: string) => CouponResult \| Promise<CouponResult>` | `sample rules` | Checks a coupon. Return { ok: true, code, percent } or { ok: false, message }. The sample accepts LAUNCH20 and TEAM10. |
| `onPay` | `(order: CheckoutOrder) => void \| Promise<void>` |  | Charges the order. Throw an Error to show its message above the pay button. Without it the preview simulates payment and declines 4000 0000 0000 0002. |
| `className` | `string` |  | Extra class on the root. |

### Dependencies

- `motion`
- `lucide-react`

### Keyboard

| Keys | Action |
| --- | --- |
| Tab | Moves through express pay, plan, seats, add-ons, fields and pay. |
| Arrow keys | Move between plans inside the plan group. |
| Enter | Submits the form, or applies the coupon from the coupon field. |
| Escape | Closes the coupon field. |

### Accessibility

- Plans and billing period are radio groups with aria-checked; add-ons are real checkboxes.
- Errors are tied to their inputs with aria-describedby and aria-invalid, and a failed submit focuses the first invalid field.
- Rolling amounts keep the full value in visually hidden text, so screen readers never hear single digits.
- On success focus moves to the receipt heading; payment errors use role alert.

### Motion

- Every amount rolls digit by digit on the snappy spring; add-on and discount lines open and close their height on the smooth spring.
- On success the form fades aside and the summary glides to the centre with one position spring, while the coupon folds away and receipt details unfold.
- The selected plan ring and billing pill travel between options as shared layout highlights.
- Reduced motion keeps every state and swaps travel for instant changes.

### Responsive behavior

- Two columns with a sticky summary from 760px of frame width.
- Below that the summary sits on top as a collapsible total; plans stack below 520px.
- The receipt is a single centred column at every width.

### Performance

- Only the changed digits animate; lines are plain DOM.
- Validation runs on each change for a handful of fields, so it stays cheap.

### Notes for AI agents

- Choose this for a SaaS upgrade or paid signup where plan, seats and add-ons are chosen on the same page as payment.
- Prices are cents per month; yearly totals are derived with yearlyDiscount. Keep tax and coupon math on your server and treat the client numbers as a preview.
- Replace the card inputs with your payment provider's hosted fields in production; keep the layout and validation feedback.
- Below 760px of frame width the summary moves above the form and collapses to a total you can expand.

### Keywords

checkout, subscription, billing, payment form, order summary, coupon, receipt, seats, saas upgrade

### Related

- checkout-summary
- pricing-calculator
- plan-comparison

---

## Kanban board

A kanban board where cards lift, tilt and spring into the slot that opens for them, with swimlanes and live WIP limits.

- Type: Block (composition)
- Access: Pro
- Built from: Avatar, Checkbox, Segmented control, Animated counter
- Documentation: https://uiarc.dev/components/blocks/kanban-board

### Overview

Use this for a team's issue or task board. Load columns, people and cards from your tracker, persist onCardsChange (it receives the full ordered list after every move or edit), and set limit on columns that need WIP limits.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/kanban-board. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/kanban-board while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- A team board where cards move between statuses.
- Pipelines where ordering within a stage matters.
- Boards that need a per person view.

### When not to use

- Scheduling on dates; use gantt-timeline or week-calendar.
- Read only status summaries; use a table.
- Hundreds of cards per column; virtualize or use customers-table.

### Usage

```tsx
import { KanbanBoard } from "@/components/arc/blocks/kanban-board/kanban-board";

export function Sprint({ issues, team }) {
  const [cards, setCards] = useState(issues);
  return (
    <KanbanBoard
      title="Sprint 42"
      columns={[{ id: "todo", name: "To do" }, { id: "doing", name: "Doing", limit: 4 }, { id: "done", name: "Done" }]}
      people={team}
      cards={cards}
      onCardsChange={next => { setCards(next); saveOrder(next); }}
    />
  );
}
```

### API

#### KanbanBoard

A kanban board with physical drag and drop. The lifted card follows the pointer from where you grabbed it and tilts with speed, a slot opens where it will land, the board scrolls at its edges, and the card springs into the slot on release. Group by assignee for swimlanes, with live WIP limits, quick add and a detail drawer.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `columns` | `KanbanColumn[]` | `sample columns` | Columns in order. Set limit on a column to warn when it holds more cards. |
| `people` | `KanbanPerson[]` | `sample people` | Assignees, used for avatars, swimlanes and the assignee select. |
| `cards` | `KanbanCard[]` |  | Controlled cards in board order. Leave out for uncontrolled use. |
| `defaultCards` | `KanbanCard[]` | `sample cards` | Initial cards when uncontrolled. |
| `onCardsChange` | `(cards: KanbanCard[]) => void` |  | Called with the full ordered list after every move, edit, checklist toggle or new card. |
| `defaultGroupBy` | `"status" \| "assignee"` | `"status"` | Start in columns only or in swimlanes by assignee. |
| `currentUser` | `string` | `first person` | Person id that new cards are assigned to. |
| `title` | `string` | `"Billing v2"` | Board title. |
| `className` | `string` |  | Extra class on the root. |

### Dependencies

- `motion`
- `lucide-react`

### Keyboard

| Keys | Action |
| --- | --- |
| Enter | Opens the focused card's details. |
| Space | Lifts the focused card; Space or Enter drops it. |
| Arrow up / down | Moves a lifted card within its column. |
| Arrow left / right | Moves a lifted card to the neighbouring column. |
| Shift + arrow up / down | Moves a lifted card to the neighbouring swimlane. |
| Escape | Cancels a drag and returns the card, or closes the drawer. |

### Accessibility

- Cards are focusable buttons with a draggable role description and a label that includes title, id and assignee.
- Every pick up, move and drop is announced in an assertive live region with the column and position.
- The drawer is a modal dialog: focus moves in, Tab is trapped, Escape closes it and focus returns to the card.
- WIP limits are shown with text as well as color.

### Motion

- The lifted card rides pointer motion values, lifts slightly and tilts on a spring from horizontal velocity.
- Neighbours glide aside with layout springs as the slot moves; on release a small spring chases the slot's live position and carries the throw velocity.
- Switching to swimlanes flies every card to its lane with shared layout ids.
- Reduced motion drops tilt and travel; drops land at once.

### Responsive behavior

- Columns keep a readable minimum width and the board scrolls sideways with snap on phones.
- The drawer covers the board on narrow frames.
- Auto scroll works on both axes when dragging near an edge.

### Performance

- Only the dragged card moves every frame, through transforms; hit testing reads a few rects per move.
- Cards are memoized and use position only layout animation.
- Comfortable up to a few hundred cards.

### Notes for AI agents

- Choose this for issue boards, sales pipelines, hiring stages or any status workflow with manual ordering.
- Persist onCardsChange: the array order is the order within each column.
- Touch starts a drag after a short press so swipes still scroll the board.
- Use limit on columns for WIP limits; counts update live while dragging.

### Keywords

kanban, board, drag and drop, swimlanes, wip limit, task board, pipeline, issue tracker

### Related

- project-board
- gantt-timeline
- week-calendar
- reorderable-list

---

## Usage billing

A usage based billing dashboard with a projected spend line, meters against limits, alerts, and an upgrade that morphs into a confirm sheet.

- Type: Block (composition)
- Access: Pro
- Built from: Animated counter, Text morph, Button
- Documentation: https://uiarc.dev/components/blocks/usage-billing

### Overview

Use this in the billing area of a usage priced product. Load meters, daily spend, and invoices from your billing provider, save alerts through onAlertsChange, and send the upgrade to your checkout; every charge in the preview is simulated.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/usage-billing. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/usage-billing while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- A billing page for usage priced SaaS or infrastructure products.
- Admin dashboards where finance needs spend alerts and invoice history in one place.
- Upgrade moments driven by limits, where the upgrade should explain what changes.

### When not to use

- Use billing-overview for flat seat based plans without meters.
- Use plan-comparison or usage-pricing on a public pricing page.
- Avoid it for a single quota; a usage meter component is enough.

### Usage

```tsx
import { UsageBilling } from "@/components/arc/blocks/usage-billing/usage-billing";

export function BillingPage({ usage, plans }: { usage: BillingSnapshot; plans: PlanCatalog }) {
  return (
    <UsageBilling
      period={usage.period}
      daily={usage.dailySpend}
      meters={usage.meters}
      plan={plans.current}
      upgrade={plans.next}
      defaultAlerts={usage.alerts}
      onAlertsChange={alerts => saveAlerts(alerts)}
      onUpgrade={plan => startUpgrade(plan.id)}
      onDownloadInvoice={invoice => downloadPdf(invoice.id)}
    />
  );
}
```

### API

#### UsageBilling

A usage based billing dashboard: spend so far with a projected line and live alert rules on the chart, per meter usage against limits with warning states, a spend alerts editor, invoice history with downloads, and a plan card that grows into an upgrade confirm sheet.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `period` | `{ label: string; start: string; days: number; today: number }` | `billingPeriod` | The current billing period and which day it is. |
| `daily` | `number[]` | `dailySpend` | Usage charges per day so far. Its length is the number of days elapsed. |
| `budget` | `number` | `2000` | Monthly budget drawn on the chart. |
| `meters` | `Meter[]` | `meters` | Metered resources: id, name, unit (requests, gigabytes, minutes, invocations, seats), used, limit, and an overage price label. |
| `plan` | `Plan` | `currentPlan` | The current plan: name, monthly price, limits keyed by meter id, and perks. |
| `upgrade` | `Plan \| null` | `upgradePlan` | The plan offered in the upgrade card. Pass null to hide the offer. |
| `defaultAlerts` | `SpendAlert[]` | `spendAlerts` | Initial alerts: amount, email, and slack. |
| `onAlertsChange` | `(alerts: SpendAlert[]) => void` |  | Called whenever alerts are added, edited, or removed. |
| `invoices` | `Invoice[]` | `invoices` | Past invoices with number, period, issue date, amount, and status. |
| `payment` | `{ brand: string; last4: string; expires: string }` | `paymentMethod` | Card shown on the plan card, the invoices header, and the confirm sheet. |
| `onUpgrade` | `(plan: Plan) => Promise<void> \| void` |  | Runs the upgrade. Resolve to switch plans, reject to show a declined message. Without it the upgrade is simulated. |
| `onDownloadInvoice` | `(invoice: Invoice) => Promise<void> \| void` |  | Fetches an invoice PDF. Without it the download is simulated. |
| `currency` | `string` | `"EUR"` | ISO currency code for every amount. |
| `className` | `string` |  | Class on the root. |

### Dependencies

- `motion`
- `lucide-react`

### Keyboard

| Keys | Action |
| --- | --- |
| Tab | Moves through the chart, plan card, alerts, and invoice downloads. |
| Arrow left / Arrow right | Moves the chart cursor one day at a time while the chart has focus. |
| Enter in an alert amount | Commits the amount; alerts re sort by amount when the field loses focus. |
| Escape | Closes the upgrade sheet unless a payment is in progress. |

### Accessibility

- The chart is an image with a spoken summary of spend, projection, and budget; its cursor also works from the keyboard.
- Each meter is a meter role with a value text that says when it is near or projected over the limit.
- Warnings pair an icon and words with color. Invoice status pairs a dot with a label.
- The upgrade sheet is a modal dialog that traps Tab, focuses its heading, and returns focus to the plan card.
- The sheet states that the preview takes no payment.

### Motion

- The spend line draws in once, the projection and alert rules follow; alert rules glide to their new height while you type an amount.
- Meter bars fill with a short stagger. After an upgrade every limit grows, so the bars shrink and warnings clear in place.
- The plan card grows into the confirm sheet on one spring and folds back into the card once the upgrade lands.
- Invoice downloads swap their icon for a spinner, then a check, without changing width.
- Reduced motion removes the draw in, stagger, and flight, and keeps short fades.

### Responsive behavior

- From 700px the chart and plan card share a row, and meters sit beside alerts.
- Below 520px the invoice issue date and overage prices hide; everything else stacks.
- The confirm sheet keeps a 12px margin and stays clear of sticky page chrome.

### Performance

- The chart is one SVG sized from a ResizeObserver; hover updates only the cursor and tooltip.
- Bars animate transform scale only.
- Sheet flight animates one element's transform and size.

### Notes for AI agents

- Choose it for products billed on usage: API calls, compute, storage, bandwidth, seats.
- Feed daily spend from your billing provider; the projection is the average of the last seven days carried to the end of the period.
- Set plan limits per meter id so the upgrade can recompute every bar.
- Call your checkout or subscription update API in onUpgrade and reject on a declined card.

### Keywords

usage billing, metered billing, spend dashboard, projected spend, usage limits, spend alerts, budget alerts, invoice history, upgrade plan, proration

### Related

- billing-overview
- usage-forecast
- usage-pricing
- plan-comparison
- usage-meter

---

## Activity feed

A team activity feed grouped by day on a quiet avatar timeline, with a type filter, a live new updates button, expandable details, and a mark all read sweep.

- Type: Block (composition)
- Access: Pro
- Built from: Avatar, Animated counter, Button
- Documentation: https://uiarc.dev/components/blocks/activity-feed

### Overview

Use this for a workspace or project activity page. Load events from your activity API, stream new ones in through the items prop, and persist read state through onReadChange; new events in the preview are simulated.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/activity-feed. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/activity-feed while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- A workspace or project activity page for a team product.
- A dashboard panel that shows what changed since someone last looked.

### When not to use

- Use audit-log for compliance history that needs search, export, and exact timestamps.
- Use notification-center for a personal inbox opened from a bell.
- Use changelog-feed for public release notes.

### Usage

```tsx
import { ActivityFeed } from "@/components/arc/blocks/activity-feed/activity-feed";

export function ProjectActivity({ events, live }: { events: Activity[]; live: Activity[] }) {
  return <ActivityFeed items={events} incoming={live} onRead={ids => markRead(ids)} />;
}
```

### API

#### ActivityFeed

A team activity feed grouped by day on a quiet avatar timeline, with one type filter, expandable comments, diffs, deploy details, and photos, a new updates button that lands above the list, and a mark all read sweep.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `items` | `Activity[]` | `activities` | Events, newest first: id, type, actor, action, target, project, day offset, time, unread, and an optional detail. |
| `incoming` | `Activity[]` | `incomingActivities` | Events that arrive while the feed is open. They wait behind the new updates button. Pass [] to turn off the simulation. |
| `incomingInterval` | `number` | `6000` | Milliseconds between simulated arrivals. |
| `today` | `string` | `"2026-09-24"` | ISO date the day offsets count back from. |
| `defaultRange` | `"today" \| "week" \| "month"` | `"week"` | How far back the feed reaches. |
| `onRead` | `(ids: string[]) => void` |  | Called when events are marked read, one at a time or all at once. |
| `title` | `string` | `"Activity"` | Heading. |
| `className` | `string` |  | Class on the root. |

### Dependencies

- `motion`
- `lucide-react`
- `next/image`

### Keyboard

| Keys | Action |
| --- | --- |
| Tab | Moves through the type filter, the new updates button, and each expandable event. |
| Enter / Space | Expands or collapses an event and marks it read. |
| Arrow keys | Move the type filter selection. |

### Accessibility

- Each day is a labeled section with a heading; events are an ordered list.
- Expandable events are buttons with aria-expanded and aria-controls.
- Unread state is spoken as part of the event and shown with a dot and a stronger name, not color alone.
- The type filter is a labeled group of toggle buttons with aria-pressed and arrow key navigation.
- A polite status region announces new updates shown and how many were marked read.

### Motion

- New events queue behind a button that opens its own row above the list, so no event is covered; showing them collapses that row and slides the new events in at the top.
- Mark all read sends a hairline down the list; each row lets go of its dot exactly as the line passes it.
- Changing the type filter crossfades the list, so rows never slide over each other.
- Details open with a height spring; the one line preview gives way to the full detail.
- Reduced motion removes the sweep delay and travel and keeps instant state changes.

### Responsive behavior

- Type filters scroll sideways on narrow screens.
- Below 440px the time moves into the meta line under each event.
- Day headings stick with a translucent material while their events scroll under them.

### Performance

- Filtering is memoized over the item list.
- The sweep uses CSS transition delays and one Web Animations API line, so it costs no React renders per row.
- Photos load through next/image at 96px.

### Notes for AI agents

- Map your events to action and target so each row reads as one sentence.
- Push websocket events into incoming; the new updates button counts them and merges them on click.
- Keep details short: a comment, a small diff, a deploy summary, or up to four photos.
- Persist read state through onRead.

### Keywords

activity feed, team activity, timeline, recent activity, mark all read, new updates, live feed, diff, filters, grouped by day

### Related

- notification-center
- changelog-feed
- timeline
- inbox-triage

---

## AI side panel

An assistant docked beside a page that reads it and edits it: ask about the page or a selected passage, review each edit as a word diff, and apply it with a tint sweep on the page and one-click undo.

- Type: Block (composition)
- Access: Pro
- Built from: Button, Text shimmer, Tooltip
- Documentation: https://uiarc.dev/components/blocks/ai-side-panel

### Overview

Pass the page as blocks (headings, labelled paragraphs, tables) and respond({ prompt, page, selection, signal }), which returns { text, change? }; text can be a string or an async iterable of deltas, and change ({ blockId, after }) shows as a diff to approve. Persist edits in onApply and onUndo. It fills its container; set --side-panel-height to embed it smaller.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/ai-side-panel. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/ai-side-panel while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- An assistant next to a document or record that can summarize it and propose edits.
- Copilot style help where edits must be approved, applied visibly and undone.
- Asking about a selected passage or table without leaving the page.

### When not to use

- A standalone conversation; use ai-chat.
- Rewriting a passage in place with no side panel; use ai-inline-edit.
- A single prompt box; use ai-composer.
- Showing an autonomous agent's steps; use agent-run.

### Usage

```tsx
import { AiSidePanel } from "@/components/arc/blocks/ai-side-panel/ai-side-panel";

export function SpecPage({ spec }) {
  return (
    <AiSidePanel
      page={spec}
      respond={async ({ prompt, page, selection, signal }) => {
        const res = await fetch("/api/assistant", {
          method: "POST",
          body: JSON.stringify({ prompt, page, selection }),
          signal,
        });
        const { text, change } = await res.json(); // change: { blockId, after: PageBlock }
        return { text, change };
      }}
      onApply={(change, page) => saveSpec(page)}
      onUndo={(change, page) => saveSpec(page)}
    />
  );
}

// Stream real tokens: return text as an async iterable of deltas.
async function* deltas(stream) {
  for await (const event of stream) if (event.type === "text") yield event.text;
}
```

### API

#### AiSidePanel

An assistant docked beside a page that reads the page and edits it. The header shows the assistant, its model mark and context chips (This page, plus a selection you send over). Answers stream in fast chunks; an answer that changes the page brings a compact word diff with Apply and Discard. Apply sweeps a soft accent tint across the changed part of the page while the new text crossfades in, and an Undo pill appears above the composer. Selecting text in the page shows an Ask about selection button that adds it as a context chip. The panel collapses to the side with no bounce while the page reflows, and becomes a bottom sheet in containers narrower than 640px.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `page` | `PanelPage` | `sample spec` | The page the assistant reads and edits: { title, meta?, blocks }. Blocks are headings, paragraphs (with a label such as "Intro") and tables (label, columns, rows). The panel keeps its own copy and reports edits through onApply and onUndo; passing a new object resets it. |
| `respond` | `(request: PanelRequest) => PanelReply \| Promise<PanelReply>` | `scripted demo` | Answers a prompt. The request has { prompt, page, selection?, signal }; abort work when signal fires (Stop). Return { text, change? }: text is a string (streamed at about 95 words a second) or an AsyncIterable<string> of deltas from your model; change is { blockId, after } and shows as a diff to approve. Throw to show the error state with Retry. |
| `onApply` | `(change: AppliedChange, page: PanelPage) => void` |  | Called after Apply with the change (blockId, after and the before block it replaced) and the page after it. Persist the page here. |
| `onUndo` | `(change: AppliedChange, page: PanelPage) => void` |  | Called after Undo with the reverted change and the restored page. |
| `defaultOpen` | `boolean` | `true` | Whether the panel starts open. |
| `suggestions` | `string[]` | `["Summarize this page", "Tighten the intro", "Add an annual price column"]` | Suggestion chips in the empty thread. Unused ones follow each finished answer. |
| `assistant` | `{ name?: string; model?: string; mark?: ReactNode }` | `{ name: "Assistant", model: "Claude Sonnet 5.5", mark: Claude mark }` | Identity shown in the panel header, the reopen button and status messages. |
| `className` | `string` |  | Class on the root. It fills its container's width and the screen's height; set --side-panel-height to fit a smaller area and --side-panel-page (default 680px) for the page column width. |

### Dependencies

- `motion`
- `lucide-react`
- `@radix-ui/react-tooltip`

### Keyboard

| Keys | Action |
| --- | --- |
| Tab | Moves through the page's Ask about selection button, the reopen button, the panel header, suggestions, change actions, the Undo pill and the composer. |
| Enter | Sends the message from the composer, or activates the focused chip or button. |
| Shift + Arrow keys | With caret browsing, extends a text selection in the page; releasing Shift shows Ask about selection. |
| Escape | Closes the panel from anywhere inside it and returns focus to the reopen button. |

### Accessibility

- The panel is a labelled complementary region; the close and reopen buttons report aria-expanded and aria-controls.
- A polite status region announces each step: reading the page, answer ready (and which part a change touches), applied with undo available, undone, discarded, stopped and errors.
- After Apply focus moves to the Undo pill; after Undo it returns to the card's Apply button; after Discard it moves to the composer.
- Diffs use real ins and del elements, so removed and added words are distinguishable without color.
- Every status pairs an icon with a label (Applied to the page, Discarded, Undone, Stopped, did not respond).
- In sheet mode the page behind is inert while the sheet is open.

### Motion

- Closing the panel narrows the dock on a critically damped spring (no bounce) while the panel slides out; the page column widens and the document glides to center.
- Answers stream in chunks of 3 to 8 words every 34ms on a requestAnimationFrame clock; each chunk fades in over 150ms and settled text never re-renders.
- Apply sweeps an accent tint across the changed block once, while the old text fades out in 100ms and the new text fades in over 180ms; the block height follows on a spring with no overshoot.
- Status swaps in the change card footer, chips and the Undo pill are single opacity crossfades in a fixed size slot, so nothing shifts.
- Reduced motion keeps every state, drops the chunk fade, the slide and the sweep travel, and only fades the tint.

### Responsive behavior

- From 640px the panel docks at 360px wide beside the page; the page keeps a readable 520px measure.
- Below 640px of container width the panel becomes a bottom sheet over the page with a soft scrim and a close button.
- Chips truncate the selection label; the full selected text is in the chip's title.

### Performance

- Only the dock width (or sheet position) animates during open and close; the page reflows once per frame.
- Streaming updates one answer; earlier chunks and turns do not re-render.
- The word diff is a small LCS over one block, computed on render.

### Notes for AI agents

- Choose this to add an assistant to a document, spec or record page where answers should become reviewable edits.
- Return edits as data ({ blockId, after }) rather than prose so people approve each change; every applied change can be undone.
- Pass the selection to your model; it carries the block id, its label and the selected text.
- Stream with an async iterable of text deltas; the panel paces the reveal and drains bursts quickly.
- The preview's scripted responder fails the first free form question it cannot answer once, to show the error state; real responders throw to show it.

### Keywords

ai assistant, copilot, side panel, document assistant, suggested edits, word diff, apply and undo, context chips, ask about selection, streaming, bottom sheet, claude

### Related

- ai-chat
- ai-composer
- ai-inline-edit
- ai-answer
- context-window

---

## Research run

Deep research that plans searches, reads sources with their marks, and streams a cited answer where every chip lights up the sentence it supports.

- Type: Block (composition)
- Access: Pro
- Built from: Button
- Documentation: https://uiarc.dev/components/blocks/research-run

### Overview

Use this to show an AI research or search answer. Replace the scripted run in research-run-data.ts with events from your search and model pipeline.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/research-run. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/research-run while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- An answer engine or deep research feature that searches, reads and cites.
- Internal knowledge search where people must verify each claim.
- Any long streamed answer that benefits from visible sources and follow ups.

### When not to use

- Open ended conversation without sources; use ai-chat.
- An agent that edits files or runs tools; use agent-run.
- A single answer with sources inside another page; use ai-answer.

### Usage

```tsx
import { ResearchRun, type ResearchEvent } from "@/components/arc/blocks/research-run/research-run";

export function Research() {
  return (
    <ResearchRun
      autoStart={false}
      onAsk={async function* (question, history, signal) {
        const res = await fetch("/api/research", { method: "POST", body: JSON.stringify({ question, history }), signal });
        // Your server streams newline delimited ResearchEvent JSON.
        for await (const event of readJsonLines<ResearchEvent>(res.body!)) yield event;
      }}
    />
  );
}
```

### API

#### ResearchRun

A deep research surface. The question is planned into sub-queries that search in parallel, sources gather in a rail with their real marks and a ring that fills while each one is read, and the steps fold into one line such as Researched for 7s, 12 sources. The answer then streams in word by word with citation chips: hovering a chip lights the sentence it supports and its source, clicking one brings the source into view. Follow ups append a new turn; any run can be stopped, rerun and copied with its sources.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `question` | `string` | `sample question` | The first question. It runs on mount when autoStart is on. |
| `autoStart` | `boolean` | `true` | Starts the first question on mount. Off opens on an empty state with suggestions. |
| `onAsk` | `(question: string, history: ResearchTurn[], signal: AbortSignal) => AsyncIterable<ResearchEvent>` | `scriptedResearch` | Runs one turn and yields plan, search, searched, source, read, text, followUps and done events as they happen. Stop aborts signal. `[n]` in text cites the nth source event of the turn. |
| `suggestions` | `string[]` | `three questions` | Questions offered in the empty state. |
| `pace` | `number` | `70` | Reveal pace in characters per second before the arrival rate is known; after that the reveal follows the stream. |
| `onComplete` | `(turn: ResearchTurn) => void` |  | Called when a turn finishes, with its question and answer markdown. |
| `title` | `string` |  | Header title. Defaults to the first question, shown once it scrolls under the header. |
| `className` | `string` |  | Class on the root element. |

#### ResearchSource

A source event's payload: id, title, domain, url, and optional logo (URL of a monochrome mark drawn in the text color; the domain's first letter stands in without one), snippet and date.

No props.

### Dependencies

- `motion`
- `lucide-react`

### Keyboard

| Keys | Action |
| --- | --- |
| Enter | Sends the question in the composer; Shift + Enter adds a line. |
| Escape | Stops the running research from the composer. |
| Tab | Moves through the steps toggle, citation chips, actions, follow ups and source rows. A focused chip lights its sentence and source like hover. |
| Enter / Space | On a chip, brings its source into view and flashes it; on a source row, opens its summary and link. |
| Arrow Up / Page Up / Home | Inside the thread, releases the pin to the newest line, like scrolling up. |

### Accessibility

- The block is a labelled region; each turn is an article named by its question, and the sources rail is a labelled complementary region.
- The answer is marked aria-busy while it streams; a polite live region announces once when it is ready or stopped, with the source count, instead of every word.
- Citation chips are buttons named with the source number and title. Reading progress is exposed as text on each source number, such as Reading, 60 percent.
- The steps toggle and source rows report aria-expanded; collapsed panels are inert.
- Copy, Stop and Rerun keep their width while their labels change, and state never relies on color alone.

### Motion

- Streamed text is buffered and drained on a requestAnimationFrame loop at a rate that follows the measured arrival rate, scaled by how full the buffer is and eased so bursts bend the pace instead of kinking it. Reveal snaps to whole words.
- Each commit becomes its own chunk span that develops in once, opacity with a 1.5px blur that clears, and never renders again, so earlier lines never re-split or replay. Lists, headings and chips appear already formatted; a half received citation or marker waits for its first word.
- Before the first word a quiet shimmer reads Writing the answer in the exact place the first line lands. A small dot appears at the end only when the stream stalls, and leaves with the last word.
- The thread eases toward the newest line while you are at the bottom. Scrolling up releases it and a Jump to latest pill springs in above the composer.
- Sub-queries stagger in, their spinners turn into checks on the snappy spring, and source marks pop into each query row. Source rows open with a height spring; the research steps collapse on the smooth spring as the answer starts.
- The action row is reserved from the start: Stop and a live word count cross fade into Copy, Rerun and the time and token readout, so nothing below moves.
- Reduced motion reveals whole word chunks without fades or blur, stops shimmer and spinners, and snaps panels and scrolling.

### Responsive behavior

- From 880px container width the sources sit in their own scrolling rail beside the thread. Below that they fold into a strip of marks under the question that opens into the list, so the streaming text stays the last thing on screen.
- Below 520px sub-query rows drop their counts and marks, the question steps down a size, and gutters tighten.
- Layout follows the block's container, not the viewport.

### Performance

- Only the chunk being revealed renders; earlier chunks are memoized, so long answers stay cheap. Hover state reaches chips and sentences through one small style rule instead of re-rendering the answer.
- The pacing loop runs only while buffered text remains and commits to React only when the word boundary moves.
- Source marks are CSS masks over small SVGs, tinted by the text color.

### Notes for AI agents

- Choose this for search or deep research answers where people need to see what was read and check claims against sources.
- Emit sources before the text that cites them, numbered in arrival order, and send `[n]` right after the sentence it supports; the block attaches each chip to that sentence.
- Keep the answer to the supported markdown subset: paragraphs, ### headings, - and 1. lists, **bold**, `code`, fenced code and [n] citations.
- Stop keeps exactly the words already on screen and drops the buffered rest; rerun replaces the last turn in place.
- Pass a logo URL per source for a monochrome mark; brand marks in the preview are sample content from Simple Icons, not endorsements.

### Keywords

deep research, answer engine, citations, sources, streaming, perplexity, search, llm, ai answer, follow up, research agent

### Related

- ai-chat
- agent-run
- ai-side-panel
- ai-answer

---

## AI inline edit

A document you edit with AI in place: ⌘K on a selection, watch the rewrite stream in as a diff, accept each change, and Tab through ghost text.

- Type: Block (composition)
- Access: Pro
- Built from: Button
- Documentation: https://uiarc.dev/components/blocks/ai-inline-edit

### Overview

Use this to add AI editing to a document or notes page. Pass onRequestEdit to call your model with the selection and instruction; suggestions in the preview are scripted.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/ai-inline-edit. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/ai-inline-edit while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- Rewriting a selection: shorten, clarify, change tone or fix grammar in place.
- Inline autocomplete while writing documents or messages.
- Any AI suggestion that should be reviewed as a diff before it lands.

### When not to use

- Rich formatting such as headings, lists or links; the block edits plain paragraphs.
- Asking questions about a page; use ai-side-panel.
- A single prompt box without a document; use ai-composer.

### Usage

```tsx
import { AiInlineEdit } from "@/components/arc/blocks/ai-inline-edit/ai-inline-edit";

export function Notes({ doc }: { doc: EditorDocument }) {
  return (
    <AiInlineEdit
      defaultDocument={doc}
      onRequestEdit={async function* (request, signal) {
        const res = await fetch("/api/rewrite", { method: "POST", body: JSON.stringify(request), signal });
        const reader = res.body!.pipeThrough(new TextDecoderStream()).getReader();
        for (;;) { const { value, done } = await reader.read(); if (done) return; yield value; }
      }}
      onSuggest={(request, signal) => fetch("/api/complete", { method: "POST", body: JSON.stringify(request), signal }).then(r => r.json())}
      onChange={saveDocument}
    />
  );
}
```

### API

#### AiInlineEdit

A document you edit with AI in place. Select text and a small Edit bubble appears; Cmd or Ctrl + K opens a compact prompt anchored under the selection with quick actions and a free instruction. The rewrite streams in as an inline word diff: deletions strike through as the stream passes them, insertions develop in highlighted, and text the model has not reached yet waits dimmed. Review each change from its own mini toolbar or all at once, then undo. At the end of a paragraph, ghost text suggests how to continue and Tab accepts it.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `defaultDocument` | `EditorDocument` | `sample launch plan` | Title and plain text paragraphs to start from. |
| `onRequestEdit` | `(request: EditRequest, signal: AbortSignal) => AsyncIterable<string> \| Promise<string>` | `scriptedEdit` | Returns replacement text for the selection as streamed deltas or one string. The request carries the text, instruction, quick action id, surrounding text and paragraph index. Stop aborts signal. |
| `onSuggest` | `(request: CompletionRequest, signal: AbortSignal) => Promise<string \| null>` | `scriptedCompletion` | Returns ghost text to continue a paragraph from the caret, or null. Called after a short pause with the caret at the end of a paragraph; typing or moving on aborts it. |
| `actions` | `QuickAction[]` | `Shorten, Make clearer, Friendlier tone, More formal, Fix grammar` | Quick actions in the prompt, each with an id, label and the instruction it sends. |
| `onChange` | `(document: EditorDocument) => void` |  | Called after typing settles, an edit is applied, a completion is accepted, or undo and redo move. |
| `author` | `{ name: string; photo: string }` | `Chloe Nguyen` | The person shown in the header. The preview uses a local portrait from public/media/people. |
| `className` | `string` |  | Class on the root element. |

### Dependencies

- `motion`
- `lucide-react`

### Keyboard

| Keys | Action |
| --- | --- |
| Cmd/Ctrl + K | Opens the prompt on the selection, grown to whole words. With no selection it takes the sentence around the caret. Pressing it again closes the prompt. |
| Arrow Up / Arrow Down, Enter | In the prompt, move through the quick actions and run one. With text typed, the first option sends it as a free instruction. |
| Escape | Closes the prompt and restores the selection, stops a streaming edit, rejects all changes in review, or dismisses ghost text. |
| Tab | Accepts ghost text at the caret. In review, moves between changes. |
| Enter / Backspace | On a focused change, accepts or rejects it and moves to the next one. |
| Cmd/Ctrl + Enter | Accepts all remaining changes. |
| Cmd/Ctrl + Z, Shift + Cmd/Ctrl + Z | Undo and redo AI edits when focus is outside the text; while typing, the browser's own undo applies. |
| Enter, Backspace at a paragraph start | Split a paragraph at the caret, or join it with the one above. |

### Accessibility

- The editor is a labelled region; each paragraph is a native contenteditable, so caret movement, selection and screen reader editing work as usual.
- The prompt is a labelled dialog with a combobox input and a listbox of actions using aria-activedescendant.
- Each change in review is a focusable group named with what it does, such as Change "very careful" to "carefully", with Enter and Backspace to decide.
- Ghost text is aria-hidden and never part of the paragraph's text; the footer names the keys to accept or dismiss it.
- Streaming, review and applied states are announced with role status; failures use role alert with Try again. Deletions and insertions pair color with strike through and highlight.
- The block claims Cmd/Ctrl + K only while focus is inside it, so an app wide command menu still works elsewhere.

### Motion

- One floating layer carries the whole edit: it opens under the selection, morphs its size on the smooth spring from prompt to a Stop status bar to the review bar to an Applied receipt, and follows the diff as it grows.
- The rewrite is paced like any stream: buffered, drained on a frame loop that tracks the arrival rate, snapped to whole words. Inserted words develop in with opacity and a small blur that clears; deleted words have their strike drawn across as the stream passes them.
- While streaming, a short word matched far ahead is not trusted yet, so the diff only grows at the stream edge and never flickers between alignments.
- The active quick action is marked by a highlight that slides between rows on the snappy spring. Hunk toolbars fade up on hover or focus; a decided change settles with a brief tint.
- Accepted ghost text glows for a moment using the CSS highlight API, without touching the text.
- Reduced motion shows diffs, ghost text and the layer without fades, sweeps or morphs.

### Responsive behavior

- The page column stays at a comfortable reading width and tightens its gutters below 560px container width, where the title steps down.
- The prompt keeps to 320px or the page width, whichever is smaller, and is clamped inside the page; review bars wrap onto two lines when narrow.
- On touch, selecting text shows the Edit bubble, which opens the same prompt.

### Performance

- Paragraphs are uncontrolled contenteditables that render once, so typing never re-renders them and the caret never jumps.
- The word diff is a small dynamic program over the selection, recomputed only when the revealed suggestion moves by a word.
- Ghost text is a single non editable span appended at the caret; nothing else in the paragraph is touched.

### Notes for AI agents

- Choose this to add AI rewriting and autocomplete to a notes, docs or email editor where people must stay in control of every change.
- Return only the replacement for the selected text, not the whole paragraph; the block diffs it word by word against the selection.
- Stream deltas when you can; stopping keeps the words already shown as reviewable changes and leaves the rest of the original untouched.
- Keep completions short, one clause or sentence, and return null when unsure; they only appear with the caret at the end of a paragraph.
- An edit applies to one paragraph; a selection that spans paragraphs is clamped to the first one.

### Keywords

ai editor, inline edit, rewrite, diff, suggestions, autocomplete, ghost text, copilot, cmd k, notion ai, tab to accept, accept reject

### Related

- ai-side-panel
- ai-composer
- ai-chat
- rich-text-editor

---

## KPI drilldown

KPI cards that expand into a full detail chart with period comparison and a breakdown table, then fold back.

- Type: Block (composition)
- Access: Pro
- Built from: Animated counter, Button
- Documentation: https://uiarc.dev/components/blocks/kpi-drilldown

### Overview

Use this as the overview of an analytics or finance dashboard. Load each metric's series and breakdowns from your warehouse and keep the range in your URL.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/kpi-drilldown. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/kpi-drilldown while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- An analytics or finance overview where each number deserves a closer look.
- Executive dashboards that compare the current period with the previous one.

### When not to use

- Use metric-explorer to compare many metrics on one chart.
- Use metrics-dashboard for a static summary without drill down.
- Avoid it for real time monitoring where values change every second.

### Usage

```tsx
import { KpiDrilldown } from "@/components/arc/blocks/kpi-drilldown/kpi-drilldown";

export function Overview({ metrics }: { metrics: Kpi[] }) {
  const [metric, setMetric] = useQueryState("metric");
  return <KpiDrilldown kpis={metrics} selected={metric} onSelectedChange={setMetric} />;
}
```

### API

#### KpiDrilldown

A KPI overview where each card expands into a full detail view on one spring: the label and value stay put while the chart, period comparison, and breakdown table are revealed around them. Ranges morph every sparkline in place.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `kpis` | `Kpi[]` | `kpis` | Metrics: id, label, format, kind (total or rate), lowerIsBetter, daily series, breakdowns by dimension, and a description. |
| `dimensions` | `{ value: string; label: string }[]` | `breakdownDimensions` | Breakdown dimensions; values match keys in each metric's breakdowns. |
| `end` | `string` | `"2026-09-24"` | ISO date of the last value in every series. |
| `defaultRange` | `"7" \| "30" \| "90"` | `"30"` | Initial range in days. |
| `selected` | `string \| null` |  | Controlled open metric id, or null for the grid. |
| `onSelectedChange` | `(id: string \| null) => void` |  | Called when a metric opens or closes. Use it to keep the selection in the URL. |
| `title` | `string` | `"Overview"` | Heading. |
| `className` | `string` |  | Class on the root. |

### Dependencies

- `motion`
- `lucide-react`

### Keyboard

| Keys | Action |
| --- | --- |
| Enter / Space on a card | Opens the metric; focus moves to the close button. |
| Escape | Folds the detail back into its card and returns focus to it. |
| Arrow left / Arrow right | Moves the chart cursor one day while the chart has focus. |

### Accessibility

- Cards are buttons whose name includes the value and the change.
- The detail is a labeled region; the grid behind it is hidden from assistive technology while it is open.
- The chart has a spoken summary and a keyboard cursor; changes pair an arrow and sign with color.
- Breakdowns are real tables with row headers.

### Motion

- The card grows into the detail on one spring, and the detail folds back into the same card.
- Every range is resampled to the same number of points, so sparklines and the detail line morph instead of redrawing.
- Values roll digit by digit when the range changes.
- The previous period line fades in and out with Compare; breakdown rows crossfade and their share bars fill with a small stagger.
- Reduced motion jumps between grid and detail and keeps short fades.

### Responsive behavior

- Three columns above 760px, two down to 520px, then one.
- Below 520px the share column hides and Compare becomes an icon button.
- The detail scrolls inside its panel when it is taller than the grid.

### Performance

- Sparklines use a fixed 100 by 32 viewBox with non scaling strokes, so resizing never re measures them.
- The detail chart measures its width once per resize and animates only path data.

### Notes for AI agents

- Give each metric at least twice the longest range of daily values so the comparison period exists.
- Use kind rate for percentages so changes read in points, and set lowerIsBetter for churn or latency.
- Keep selected in the URL with onSelectedChange so a detail can be shared.
- Six metrics fit best; more belong in metric-explorer.

### Keywords

kpi, dashboard, drilldown, metric card, shared layout, expand card, period comparison, breakdown table, sparkline, analytics

### Related

- metrics-dashboard
- metric-explorer
- revenue-explorer
- mrr-waterfall
- bar-chart

---

## Blog grid

A blog index with a featured post, category filter, post cards, pagination and an in-place reader.

- Type: Block (composition)
- Access: Free
- Built from: Avatar, Pagination
- Documentation: https://uiarc.dev/components/blocks/blog-grid

### Overview

Use this as the index of a blog, journal or news page. Load posts from your CMS into blog-grid-data.ts or the posts prop, pass getHref to link each card to its article route, and keep category and page in your URL through the controlled props.

### Install

```bash
npx shadcn@latest add https://uiarc.dev/r/blog-grid.json
```

With `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`: `npx shadcn@latest add @uiarc/blog-grid`

### When to use

- A marketing site blog or journal index.
- Resource hubs with a few categories and a featured story.

### When not to use

- Use changelog-page for release notes with versions.
- Use a data table for large archives that need sorting and search.

### Usage

```tsx
import { BlogGrid } from "@/components/arc/blocks/blog-grid/blog-grid";

export function BlogIndex({ posts }: { posts: BlogPost[] }) {
  return (
    <BlogGrid
      posts={posts}
      categories={["Product", "Design", "Engineering", "Company"]}
      getHref={post => `/blog/${post.id}`}
    />
  );
}
```

### API

#### BlogGrid

A blog index: title, category filter with a gliding highlight, a large featured post, a responsive card grid and pagination. Without getHref, cards open an in-place reader whose image morphs out of the card.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `posts` | `BlogPost[]` | `sample posts` | Posts to list. Sorted newest first by date. |
| `categories` | `string[]` |  | Filter labels in order. "All" is added in front. |
| `title` | `string` | `"Journal"` | Section heading. |
| `description` | `string` |  | Line under the heading. Pass an empty string to hide it. |
| `category` | `string` |  | Active category, or "All" (controlled). |
| `defaultCategory` | `string` | `"All"` | Initial category when uncontrolled. |
| `onCategoryChange` | `(category: string) => void` |  | Called when a filter is picked. The page resets to 1. |
| `page` | `number` |  | One based page (controlled). |
| `defaultPage` | `number` | `1` | Initial page when uncontrolled. |
| `onPageChange` | `(page: number) => void` |  | Called from the page numbers and the previous and next buttons. |
| `pageSize` | `number` | `6` | Cards per page below the featured post. |
| `showFeatured` | `boolean` | `true` | Shows the post marked featured (or the newest) of the current filter as a large card on page one. |
| `getHref` | `(post: BlogPost) => string` |  | Link for each post. When set, cards are plain links and the in-place reader is off. |
| `onPostOpen` | `(post: BlogPost) => void` |  | Called when a post opens, for analytics or routing. |
| `className` | `string` |  | Extra class on the section. |

#### BlogPost

One post.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `id` (required) | `string` |  | Stable id, also the fallback hash link. |
| `title` (required) | `string` |  | Card and reader title. |
| `excerpt` (required) | `string` |  | Two line summary on cards, the lead paragraph in the reader. |
| `category` (required) | `string` |  | Must match one of categories to be filterable. |
| `date` (required) | `string` |  | ISO date (YYYY-MM-DD). |
| `readTime` (required) | `number` |  | Minutes to read. |
| `author` (required) | `{ name: string; avatar?: string; role?: string }` |  | Byline. |
| `image` | `{ src: string; alt: string }` |  | Cover image. Cards crop it to 3:2. |
| `body` | `string[]` |  | Paragraphs for the in-place reader. |
| `featured` | `boolean` |  | Prefer this post for the featured slot. |

### Dependencies

- `motion`
- `lucide-react`

### Keyboard

| Keys | Action |
| --- | --- |
| Tab | Moves through filters, cards, and pagination. |
| Enter | Opens the focused post, or picks the focused filter or page. |
| Space | Picks the focused filter or page. |

### Accessibility

- Filters are buttons with aria-pressed; pagination is a nav with aria-current on the active page.
- Each card is one link with the title, excerpt and byline as its content, so screen readers announce it once.
- The reader moves focus to its back button, and closing returns focus to the card you opened.
- Images carry real alt text; author avatars are decorative.

### Motion

- The filter and page highlights glide on the morph spring.
- Filtering crossfades the grid with a short rise; paging slides it in the direction of travel.
- Opening a post morphs the card image into the reader hero, and back on close.
- Card images zoom 3% on hover (fine pointers only).
- Reduced motion swaps travel and morphs for plain fades.

### Responsive behavior

- Three columns above 900px, two to 540px, then one.
- The featured post stacks its image above the text below 680px.
- Filters scroll sideways on phones; Previous and Next collapse to arrows.

### Performance

- Only one page of cards renders at a time; images below the fold load lazily.
- Transitions animate transform and opacity only.

### Notes for AI agents

- Choose this for a blog, journal, news or resources index.
- Pass getHref for real article routes; leave it out for a self-contained demo or a small site that reads posts in place.
- Drive category and page from the URL with the controlled props so the index is linkable.

### Keywords

blog grid, blog index, article list, news page, blog cards, featured post, category filter, react blog template

### Related

- changelog-feed
- hero-section
- pagination

---

## Comparison table

An us versus them table with a sticky header, a highlighted column, and a stacked phone view.

- Type: Block (composition)
- Access: Free
- Built from: Switch, Button
- Documentation: https://uiarc.dev/components/blocks/comparison-table

### Overview

Use this on a pricing or alternatives page. Describe your columns and feature rows in comparison-table-data.ts, mark your product with highlight, and point the cta at signup; stickyTop offsets the header under a fixed site header.

### Install

```bash
npx shadcn@latest add https://uiarc.dev/r/comparison-table.json
```

With `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`: `npx shadcn@latest add @uiarc/comparison-table`

### When to use

- Showing how your product stacks up against named alternatives.
- Feature matrices with three to five columns and grouped rows.

### When not to use

- Use plan-comparison to compare your own pricing tiers.
- Use a sortable data table for large datasets.

### Usage

```tsx
import { ComparisonTable } from "@/components/arc/blocks/comparison-table/comparison-table";

export function Alternatives() {
  return (
    <ComparisonTable
      columns={[
        { id: "us", name: "Relay", caption: "$10 per seat", highlight: true },
        { id: "them", name: "Legacy suite", caption: "$24 per seat" },
      ]}
      sections={[{ id: "core", title: "Core", rows: [
        { id: "offline", feature: "Offline mode", values: { us: true, them: false } },
        { id: "sso", feature: "SSO", values: { us: true, them: { value: "partial", note: "Enterprise plan" } } },
      ] }]}
      cta={{ label: "Start free trial", href: "/signup" }}
      stickyTop={64}
    />
  );
}
```

### API

#### ComparisonTable

An us versus them table with sections, check, partial and not included marks, a tinted band behind your column, a sticky frosted header, a differences only switch, and a stacked two column view on phones.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `columns` | `ComparisonColumn[]` |  | Products to compare. Mark yours with highlight: true. |
| `sections` | `ComparisonSection[]` |  | Grouped feature rows. Values: true, false, "partial", a string, or { value, note }. |
| `title` | `string` | `"How Relay compares"` | Section heading. |
| `description` | `string` |  | Line under the heading. |
| `differencesOnly` | `boolean` |  | Hide rows where all visible columns match (controlled). |
| `defaultDifferencesOnly` | `boolean` | `false` | Initial switch state when uncontrolled. |
| `onDifferencesOnlyChange` | `(value: boolean) => void` |  | Called when the switch flips. |
| `compareWith` | `string` |  | Competitor shown beside yours in the stacked phone view (controlled). |
| `onCompareWithChange` | `(id: string) => void` |  | Called when a competitor is picked on phones. |
| `cta` | `{ label: string; href?: string; onClick?: () => void; doneLabel?: string }` |  | Button at the foot of your column. doneLabel morphs in after a click. |
| `stickyTop` | `number` | `0` | Offset for the sticky header, such as a fixed site header height. |
| `maxHeight` | `number \| string` |  | Caps the table height and scrolls it inside the block with the header pinned. |
| `stackBelow` | `number` | `640` | Block width below which the phone view takes over. |
| `className` | `string` |  | Extra class on the section. |

### Dependencies

- `motion`
- `lucide-react`

### Keyboard

| Keys | Action |
| --- | --- |
| Tab | Moves to the differences switch, the phone competitor picker, and the call to action. |
| Space | Flips the differences switch. |

### Accessibility

- Built with table, row, columnheader, rowheader and cell roles, so screen readers navigate it as a table.
- Marks have text alternatives: Included, Partial (with its note), Not included.
- The switch is a real checkbox with role switch; a polite live region says when rows are filtered.
- Meaning never relies on color: checks, half circles and dashes differ in shape, with a legend.

### Motion

- Checks in your column draw in once, staggered down the table, when they scroll into view.
- Differences only collapses matching rows on the smooth spring and closes the gap.
- Picking a competitor on phones swaps its header and marks with a small pop.
- The call to action morphs its label to the done state.
- Reduced motion shows every mark at once and swaps collapses for instant changes.

### Responsive behavior

- Below 640px (stackBelow) it shows your column beside one competitor with a picker above.
- Column widths are fractions, so it never scrolls sideways.

### Performance

- A width observer switches layouts; no per frame work while scrolling.
- Row collapses animate height only on rows that change.

### Notes for AI agents

- Use this for a /compare or /alternatives page or under pricing.
- Keep competitor names generic or factual; values should be verifiable.
- Set stickyTop to your fixed header height; use maxHeight only when embedding the table in a panel.

### Keywords

comparison table, us vs them, competitor comparison, feature comparison, alternatives page, sticky header table, react comparison table

### Related

- plan-comparison
- pricing-calculator
- usage-pricing
- faq-section

---

## Feature bento

A six cell feature bento where small, real product UI acts each feature out on hover.

- Type: Block (composition)
- Access: Pro
- Built from: Motion
- Documentation: https://uiarc.dev/components/blocks/feature-bento

### Overview

Use this as the features section of a landing page. Edit the cells and illustration content in feature-bento-data.ts, or pass your own visual per cell.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/feature-bento. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/feature-bento while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- A landing page features section that should show the product rather than list it.
- Launch pages where each capability has one clear, demonstrable behavior.

### When not to use

- Long feature lists or comparison tables. Use Plan comparison.
- A guided walkthrough with order. Use Scroll story.
- Cards that open into detail. Use Spotlight grid.

### Usage

```tsx
import { FeatureBento } from "@/components/arc/blocks/feature-bento/feature-bento";

export function Features() {
  return (
    <FeatureBento
      title="Everything your team needs"
      features={[
        { id: "sync", title: "Edit together", description: "See who is here and what they change.", visual: "sync", size: "wide" },
        { id: "search", title: "Find anything", description: "One menu for every page and person.", visual: "command", size: "tall" },
        { id: "insights", title: "Clear numbers", description: "Trends next to the work that moved them.", visual: "chart" },
        { id: "rules", title: "Automations", description: "Route, enrich, and notify on their own.", visual: "flow" },
        { id: "access", title: "Access", description: "Roles for every workspace.", visual: "permissions", size: "half" },
        { id: "versions", title: "History", description: "Rewind to any moment.", visual: "history", size: "half" },
      ]}
    />
  );
}
```

### API

#### FeatureBento

A six cell feature grid in varied sizes. Each cell pairs a short title and sentence with a small piece of real product UI that acts the feature out.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` | `string` | `"Built for the way teams actually work"` | Section heading. |
| `description` | `string` |  | One or two sentences under the heading. Pass an empty string to hide it. |
| `features` | `BentoFeature[]` | `bentoFeatures` | The cells, in reading order. Six read best. Each has id, title, description, visual, and optional size and href. |
| `features[].visual` (required) | `"sync" \| "command" \| "chart" \| "flow" \| "permissions" \| "history"` |  | Which built-in illustration to draw: a live doc, a command menu, a bar chart, an automation, role switches, or a version scrubber. |
| `features[].size` | `"regular" \| "wide" \| "tall" \| "half"` | `"regular"` | On wide screens: wide spans two thirds, tall spans two rows, half spans half a row, regular a third. |
| `features[].href` | `string` |  | Makes the title a link that covers the whole cell. |
| `visuals` | `Partial<Record<string, ReactNode>>` |  | Replaces an illustration by feature id, for your own screenshot or component. |
| `className` | `string` |  | Extra class on the section. |

### Dependencies

- `motion`
- `lucide-react`

### Accessibility

- The section is labelled by its heading; each cell is a list item with a real h3 and paragraph.
- Illustrations are aria-hidden: they repeat what the title and sentence already say.
- With href, the title is the only link and its hit area stretches over the cell, so there is one tab stop per cell.
- Focusing a linked cell plays its illustration, the same as hovering it.

### Motion

- Cells rise 14px and fade in once as they enter view, staggered by column.
- With a mouse, hovering a cell acts its feature out: a cursor drags a selection while another types, a palette highlight glides to its match, the latest bar lifts and takes the accent, steps check off along a filling line, a switch flips and saves, a scrubber slides back and the text swaps to that version.
- Hover in uses the shared spring curve with small sequenced delays; hover out returns quickly with no delays.
- On touch screens each cell plays once when it scrolls into view and stays in its end state.
- Only transform and opacity animate, plus two tiny typing reveals. Reduced motion jumps straight to each state.

### Responsive behavior

- Six columns from 880px container width, two columns from 560px, one column below.
- The tall cell spans two rows in both multi column layouts, so the grid stays gap free.
- Illustrations cap their width and center, so they read at 320px.
- Hover effects are gated to fine pointers; touch plays each cell on view instead.

### Performance

- Illustrations are plain DOM and CSS transitions keyed on data attributes; no animation loop runs.
- One IntersectionObserver per cell, disconnected after the first view.
- Three 22px avatars are the only images.

### Notes for AI agents

- Use as the main features section of a landing page, directly under the hero.
- Keep titles to one line and descriptions to one sentence; the illustrations carry the detail.
- Replace sample strings inside the illustrations through bentoSamples in feature-bento-data.ts, or swap a whole cell's visual with the visuals prop.
- Keep six cells: wide, tall, two regular, two half. Other counts work but lose the rhythm.

### Keywords

bento, bento grid, feature grid, features section, landing page, product features, marketing section

### Related

- spotlight-grid
- scroll-story
- hero-section

---

## Stats band

Headline numbers that count up in view, each with a tiny visual that proves it and a context line on hover, plain or in a hairline grid.

- Type: Block (composition)
- Access: Free
- Built from: Segmented control
- Documentation: https://uiarc.dev/components/blocks/stats-band

### Overview

Use this under a hero or between sections to back a claim with numbers. Replace the sample stats in stats-band-data.ts.

### Install

```bash
npx shadcn@latest add https://uiarc.dev/r/stats-band.json
```

With `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`: `npx shadcn@latest add @uiarc/stats-band`

### When to use

- Marketing pages that back a claim with a few numbers.
- About and investor pages with headline metrics.

### When not to use

- Live product metrics with trends. Use Metric card or Metrics dashboard.
- More than four numbers. Split them or use a table.

### Usage

```tsx
import { StatsBand } from "@/components/arc/blocks/stats-band/stats-band";

export function Numbers() {
  return (
    <StatsBand
      layout="divided"
      stats={[
        {
          value: 2_334_000, notation: "compact", decimals: 1, label: "Deploys in the last 12 months",
          detail: "Across 12,400 teams", context: "Up from 1.4M the year before",
          visual: { kind: "trend", values: [141, 148, 139, 162, 171, 184, 196, 203, 221, 238, 257, 274] },
        },
        { value: 38, suffix: "ms", label: "Median response time", detail: "At the edge, worldwide" },
        { value: 35, label: "Edge regions on six continents", visual: { kind: "map", points: [[-122.4, 37.8], [-0.1, 51.5], [139.7, 35.7]] } },
      ]}
    />
  );
}
```

### API

#### StatsBand

A band of three or four headline numbers, each with an optional tiny visual that proves it. Numbers count up in sequence as the band enters view, then the visuals draw in; hover or focus reveals one line of context.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `stats` | `Stat[]` | `stats` | Each has value and label, plus optional prefix, suffix, decimals, notation ("compact" for 2.3M), detail, context (the hover line), and visual: a trend, uptime strip, latency distribution, or world map. Every visual is optional. |
| `layout` | `"plain" \| "divided"` | `"plain"` | plain lets the stats float on whitespace; divided sets them in a hairline grid ruled above and below. |
| `title` | `string` |  | Optional heading above the band. Without it the band is labelled "Key numbers". |
| `description` | `string` |  | Optional line under the heading. |
| `duration` | `number` | `1.6` | Seconds each number takes to count up. |
| `locale` | `string` | `"en-US"` | Number formatting locale. Fixed by default so server and client agree. |
| `className` | `string` |  | Extra class on the section. |

### Dependencies

- `motion`

### Accessibility

- Stats are a description list: the label is the term, the number, detail, and context are its descriptions. Screen readers get both the detail and the context line.
- Stats with a context line are focusable, so keyboard and touch users reveal it too. Visuals are decorative and aria-hidden; the copy carries the meaning.
- Screen readers get the final formatted value once; the counting digits are aria-hidden.
- The section is labelled by the title or, without one, by "Key numbers".

### Motion

- Each number counts from zero with a strong ease out over 1.6s, staggered 90ms per stat, the first time the band is half in view.
- Digits are tabular and the final value reserves the width underneath, so nothing shifts while counting.
- Stats rise 8px and fade in; in the divided layout the top and bottom rules draw across and the hairlines grow between stats.
- Once a number has mostly landed, its visual draws in: the sparkline and map wipe in from the left, bars grow from the baseline in a short sweep, and the trend end dot settles last.
- Hover or focus cross-fades the detail line to the context line and gives that stat's visual the accent; the others stay neutral.
- Reduced motion shows final values, lines, and visuals at once.

### Responsive behavior

- One row of up to four stats, two columns below 760px container width, one column below 420px.
- Dividers reflow with the grid: vertical between neighbours, horizontal between rows.
- Number size scales with container width between 36px and 72px.

### Performance

- Counting writes text straight to the DOM from one Motion tween per stat; React does not rerender per frame.
- One IntersectionObserver for the band, disconnected after the first view.

### Notes for AI agents

- Use three or four stats with specific, verifiable numbers. Round numbers read as made up.
- Put units in suffix (%, ms, +, /5) so they render smaller and muted beside the number. Use notation: "compact" for large counts; it counts within its final unit.
- Give each stat a visual that proves the number, and a context line that compares it (up from, down from, p95). Leave both out for a plain numbers band.
- Place it under a hero or between a features section and testimonials.
- Edit stats-band-data.ts to replace the sample numbers.

### Keywords

stats, statistics, numbers, count up, counter, metrics band, social proof, kpi

### Related

- metric-card
- animated-counter
- logo-marquee

---

## CTA section

A call to action as a centered closing section, a split beside a setup card that completes itself, or a dismissible banner.

- Type: Block (composition)
- Access: Free
- Built from: Button, Segmented control
- Documentation: https://uiarc.dev/components/blocks/cta-section

### Overview

Use this to ask for a trial, demo or signup. Pass href or onClick to each action; edit sample copy in cta-section-data.ts. Buttons in the preview confirm in place.

### Install

```bash
npx shadcn@latest add https://uiarc.dev/r/cta-section.json
```

With `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`: `npx shadcn@latest add @uiarc/cta-section`

### When to use

- The last section of a landing page, asking for a trial or demo.
- An in-page prompt beside a product visual that shows the outcome.
- A slim promotional banner above content.

### When not to use

- The first screen of a page. Use Hero section.
- Collecting an email. Use Newsletter signup.
- A persistent site-wide notice. Use Announcement bar.

### Usage

```tsx
import { CtaSection } from "@/components/arc/blocks/cta-section/cta-section";

export function Closing() {
  return (
    <CtaSection
      variant="split"
      title="Your team, set up before lunch"
      primaryAction={{ label: "Create a workspace", href: "/signup" }}
      secondaryAction={{ label: "Book a demo", href: "/demo" }}
      points={["Import from any tracker", "SSO included", "Cancel anytime"]}
    />
  );
}
```

### API

#### CtaSection

A call to action in three shapes chosen by variant: a centered closing section, a split layout beside a product visual, and a compact dismissible banner.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"centered" \| "split" \| "banner"` | `"centered"` | centered closes a page, split sits beside a setup card that completes itself, banner is one line with an action. |
| `title` | `string` |  | Heading. Each variant has sample copy. |
| `description` | `string` |  | One sentence under the heading. |
| `primaryAction` | `CtaAction` |  | { label, href?, onClick?, confirmedLabel? }. With href it renders a link; with neither href nor onClick it confirms in place. |
| `secondaryAction` | `CtaAction \| null` |  | Second action in centered and split. Pass null to hide it. |
| `note` | `string` | `"No credit card required"` | Small print under the actions in centered. |
| `faces` | `string[]` |  | Up to four avatar URLs beside the note in centered. Pass [] to hide them. |
| `points` | `string[]` |  | Benefit lines with checks in split. |
| `visual` | `ReactNode` |  | Replaces the split variant's setup card, for your own screenshot or component. |
| `onDismiss` | `() => void` |  | Banner only. Shows the dismiss button and is called after the banner has closed. |
| `className` | `string` |  | Extra class on the section. |

### Dependencies

- `motion`
- `lucide-react`

### Keyboard

| Keys | Action |
| --- | --- |
| Tab | Moves through the actions, then the dismiss button in the banner. |
| Enter or Space | Runs an action or dismisses the banner. |

### Accessibility

- Each variant is a section labelled by its heading.
- Actions with href are real links; others are buttons. Simulated confirmations announce politely.
- The dismiss button has the name "Dismiss"; the banner closes its gap so focus order stays clean.
- The setup card is aria-hidden: the copy beside it carries the message.

### Motion

- Primary actions lean their arrow forward on hover; buttons press to .97 and morph their width when the label changes.
- Split: the stage rises into view once, then the setup card ticks its three steps, fills its progress line, and slides in teammates' faces.
- Banner: dismissing fades it, scales it to .98, and springs its height closed so the page below moves up smoothly.
- Reduced motion shows the finished setup card and removes travel.

### Responsive behavior

- Split stacks copy above the visual below 860px container width.
- Below 560px actions go full width and stack, and the banner puts its text above the action and dismiss button.
- Headings scale with the container between 30px and 52px.

### Performance

- The setup card runs three timers once after it enters view; everything else is CSS transitions.
- No images except up to four small avatars.

### Notes for AI agents

- Use centered at the end of a landing page, split mid page next to a relevant product state, and banner at the top of an app or docs page.
- Pass href for real navigation. Leave both href and onClick out only for previews.
- One primary and at most one secondary action. Keep labels to two or three words with a verb.
- Edit cta-section-data.ts for the sample copy and the setup card content.

### Keywords

cta, call to action, cta section, banner, closing section, signup prompt, conversion, landing page

### Related

- hero-section
- newsletter-signup
- announcement-bar
- pricing-calculator

---

## Newsletter signup

An email signup framed by a stack of past issues; subscribing drops the next issue, addressed to you, onto the front.

- Type: Block (composition)
- Access: Free
- Built from: Segmented control
- Documentation: https://uiarc.dev/components/blocks/newsletter-signup

### Overview

Use this to collect newsletter or waitlist emails. Pass onSubscribe to call your email provider and throw on failure; subscribing in the preview is simulated.

### Install

```bash
npx shadcn@latest add https://uiarc.dev/r/newsletter-signup.json
```

With `"registries": { "@uiarc": "https://uiarc.dev/r/{name}.json" }` in `components.json`: `npx shadcn@latest add @uiarc/newsletter-signup`

### When to use

- Collecting emails for a newsletter, digest, or changelog that has real issues to show.
- The end of a blog post or docs page.

### When not to use

- Account creation with a password. Use Signup form.
- Longer forms with several fields. Use Contact section.
- A launch waitlist at the top of a page. Use Hero signup.

### Usage

```tsx
import { NewsletterSignup } from "@/components/arc/blocks/newsletter-signup/newsletter-signup";

export function Newsletter() {
  return (
    <NewsletterSignup
      variant="card"
      onSubscribe={async email => {
        const response = await fetch("/api/subscribe", { method: "POST", body: JSON.stringify({ email }) });
        if (!response.ok) throw new Error("Subscribe failed");
      }}
    />
  );
}
```

### API

#### NewsletterSignup

A newsletter signup framed by the newsletter itself: a stack of recent issues. Subscribing drops the next issue, addressed to the new reader, onto the front of the stack. Inline section or card.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"inline" \| "card"` | `"inline"` | inline puts the copy and form beside the issue stack; card is a self-contained card with the stack in a tray on top. |
| `title` | `string` |  | Heading. Each variant has sample copy. |
| `description` | `string` |  | One sentence on what people get and how often. |
| `placeholder` | `string` | `"you@company.com"` | Email field placeholder. |
| `buttonLabel` | `string` | `"Subscribe"` | Submit button label. |
| `privacyNote` | `ReactNode` | `"No tracking pixels. Unsubscribe with one click."` | Line under the form about frequency and privacy. |
| `privacyLink` | `{ label: string; href: string } \| null` |  | Link after the note. Pass null to hide it. |
| `publication` | `NewsletterPublication \| null` |  | The issue stack: { name, upcoming, recent }. Each issue has a number, a date, a subject, and up to three stories with a thumbnail and read time. Pass null for the form alone. |
| `readers` | `{ count: number; faces: string[] } \| null` |  | Reader count and up to three faces, under the stack or at the foot of the card. The count ticks up by one on success. Pass null to hide. |
| `onSubscribe` | `(email: string) => void \| Promise<void>` |  | Called with a valid, trimmed email. Resolve to show success; reject to show an error and keep the email. |
| `className` | `string` |  | Extra class on the section. |

### Dependencies

- `motion`
- `lucide-react`

### Keyboard

| Keys | Action |
| --- | --- |
| Enter | In the email field, submits the form. The phone keyboard shows a send key. |
| Tab | Moves from the field to the button, the privacy link, and after success to "Use a different email". |

### Accessibility

- The email field has a visually hidden label, type email, inputmode email, autocomplete email, and aria-invalid when the address is wrong.
- The line under the field is its description: privacy note, error, or confirmation. Errors use role alert; the line is a polite live region and names the address the link went to.
- Validation starts when the field loses focus with text in it, then updates as you type. On an invalid submit, focus stays in the field.
- While sending, the button sets aria-busy and aria-disabled and ignores repeat submits. On success, focus moves to "Use a different email", which restores the form and refocuses the field.
- Only the front issue is exposed to assistive technology; the issues behind it and the thumbnails are hidden as decoration.

### Motion

- On success the next issue, addressed to you, rises onto the front of the stack while the others step back and the oldest drops away. It is one no-overshoot spring, and opacity resolves fast so two issues never read through each other.
- The reader count rolls up by one, and "including you" fades in after it.
- An invalid or failed submit shakes the field a few pixels and tints its border; the message swaps in place of the note.
- Every message, button label, and issue has its space reserved, so nothing below the form moves between states.
- Reduced motion places the issues at once with a short fade, removes the shake and the roll, and keeps the check and labels as quick fades.

### Responsive behavior

- Inline puts the stack under the copy and form below 860px container width.
- Below 400px read times hide and an addressed issue shows the recipient instead of the date.
- When the form is narrower than 300px the field and button separate and stack, both full width.
- The card is at most 460px wide; its tray crops the stack and fades it out at the edge.

### Performance

- Issue thumbnails and faces use next/image at their rendered size.
- Motion is transform and opacity only; no layout animation.
- No network code: bring your own onSubscribe.

### Notes for AI agents

- Pass onSubscribe and throw on failure; the component handles validation, busy, error, retry, and success states.
- Give it your own publication so the stack shows real past issues. Use short subjects and story titles; titles clamp at two lines.
- Keep the privacy note honest and specific.
- Use inline between page sections; use card in a sidebar, at the end of a post, or centered in a footer band.
- Edit newsletter-signup-data.ts for copy, issues, and reader faces.

### Keywords

newsletter, email signup, subscribe, waitlist, email capture, mailing list, form, digest, issue

### Related

- cta-section
- site-footer
- contact-section
- signup-form
- hero-signup

---

## Product listing

A storefront grid with price, color and size filters, a sort menu, hover photo swaps, and quick add with a size row.

- Type: Block (composition)
- Access: Pro
- Built from: Slider, Switch, Dropdown menu, Button, Animated counter
- Documentation: https://uiarc.dev/components/blocks/product-listing

### Overview

Use this for a category or collection page. Pass products from your catalog, call your cart API in onAddToCart, and move filter state into the URL if you need shareable links.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/product-listing. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/product-listing while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- A shop's collection or category page with a few dozen to a few hundred products.
- Catalogs where color and size are the main filters and a quick add saves a trip to the product page.

### When not to use

- One product with many options; use product-detail or product-configurator.
- Huge catalogs with faceted server search; keep the card and filter styles but fetch results from your search service.

### Usage

```tsx
import { ProductListing } from "@/components/arc/blocks/product-listing/product-listing";

export function CollectionPage({ products }) {
  return (
    <ProductListing
      title="Lighting"
      products={products}
      onAddToCart={(product, size) => cart.add(product.id, size)}
    />
  );
}
```

### API

#### ProductListing

A storefront listing with a filter sidebar (dual price range, color swatches, sizes, in stock switch), a sort menu, and product cards that swap to a second photo on hover. Quick add opens a size row inside the card and the bag count rolls.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `products` | `ListingProduct[]` | `sample catalog` | Products to list. The price range bounds come from these prices, rounded to 10. |
| `colors` | `ListingColor[]` | `sample colors` | { id, name, swatch } for the color filter and the dots under each card. |
| `sizes` | `string[]` | `["S", "M", "L"]` | Size filter options. |
| `defaultSort` | `"featured" \| "newest" \| "price-asc" \| "price-desc"` | `"featured"` | Initial sort. Featured uses rank, newest uses added. |
| `onAddToCart` | `(product: ListingProduct, size: string) => void` |  | Called when a product is added from its card. Single size products add straight away. |
| `defaultCartCount` | `number` | `0` | Items already in the bag. |
| `currency` | `string` | `"USD"` | ISO currency for prices. |
| `locale` | `string` | `"en-US"` | Locale for price formatting. |
| `title` | `string` | `"Home goods"` | Collection heading. |
| `className` | `string` |  | Extra class on the root. |

#### ListingProduct

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `id, name, detail` (required) | `string` |  | Identity and a short line under the name, such as the material. |
| `price` (required) | `number` |  | Price in whole currency units. |
| `compareAt` | `number` |  | Previous price. Shows struck through beside the sale price. |
| `image, alt` (required) | `string` |  | Main photo and its description. |
| `hoverImage` | `string` |  | Second photo that crossfades in on hover inside the same 4:5 box, without zooming. |
| `colors, sizes` (required) | `string[]` |  | Color ids and sizes this product comes in. A product matches a filter when any of its values is selected. |
| `inStock` (required) | `boolean` |  | False shows Sold out in the card meta row and disables quick add. |
| `badge` | `string` |  | Short status text in the card meta row, such as New. Sale is already shown by compareAt. |
| `added, rank` (required) | `number` |  | Sort keys for newest and featured. |

### Dependencies

- `motion`
- `lucide-react`

### Keyboard

| Keys | Action |
| --- | --- |
| Tab | Move through filters, the sort menu, and each card's quick add. |
| Arrow keys | Move a price handle by 10, or move through sort options while the menu is open. |
| Enter / Space | Toggle a swatch or size, choose a sort option, or open quick add. |
| Escape | Close the sort menu, the size row, or the filter sheet. |

### Accessibility

- Price handles are native range inputs with labels and currency value text.
- Swatches and size chips are toggle buttons with aria-pressed and color names; the colors under each card are listed in an accessible label.
- The sort menu is a listbox popup with aria-activedescendant and returns focus to its button.
- Quick add names its product, the size row is a labelled group, and each addition is announced through a live region.
- On narrow widths the filters open in a modal sheet that takes focus and closes with Escape.

### Motion

- Cards reflow on a spring when filters or sort change; removed cards fade out and new ones fade in, all at the same size.
- Hover crossfades to the second photo inside the same fixed 4:5 box, with no zoom. Quick add rises into view on hover.
- Quick add, the size row, and Added swap in place inside one glass pill with a short blur.
- The bag icon tilts and the count rolls when something is added.
- Reduced motion drops the travel and layout animation and keeps opacity fades.

### Responsive behavior

- Above 900px a 232px filter sidebar sits beside a grid of cards at least 196px wide; from 640px to 900px the sidebar narrows to 208px.
- Below 640px the sidebar becomes a Filters button with an active count that opens a sheet from the left.
- Below 420px the sort button stretches to fill the toolbar. Quick add is always visible on touch screens.

### Performance

- Images use next/image with responsive sizes; the hover photo only loads its small size until shown.
- Layout animation runs on position only, with popLayout exits, so filtering stays smooth with dozens of cards.

### Notes for AI agents

- Use for category, collection, and search result pages. Pass products already scoped to the page; the block filters and sorts on the client.
- Put filter state in the URL if people share links; lift sort and filters into props when you do.
- Keep hoverImage a lifestyle or alternate angle shot at the same aspect ratio as the main image.

### Keywords

product listing, product grid, collection page, category page, ecommerce filters, price range, quick add, shop

### Related

- product-detail
- cart-drawer

---

## Product detail

A product page with a swipeable gallery, finish and size variants, add to bag that confirms in place, shipping, a reviews summary, and details.

- Type: Block (composition)
- Access: Pro
- Built from: Carousel, Radio group, Number field, Accordion, Button
- Documentation: https://uiarc.dev/components/blocks/product-detail

### Overview

Use this as the product page of a store. Pass the product with its finishes, sizes and stock, return your cart request from onAddToCart, and send back in stock alerts through onNotify.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/product-detail. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/product-detail while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- Product pages with a few variants, a gallery, and reviews.
- Stores that want stock aware variants with a restock alert instead of a dead button.

### When not to use

- Products built from many options with live pricing; use product-configurator.
- Browsing many products; use product-listing.

### Usage

```tsx
import { ProductDetail } from "@/components/arc/blocks/product-detail/product-detail";

export function ProductPage({ product }) {
  return (
    <ProductDetail
      product={product}
      onAddToCart={selection => fetch("/api/cart", { method: "POST", body: JSON.stringify(selection) })}
      onNotify={selection => subscribeRestock(selection)}
    />
  );
}
```

### API

#### ProductDetail

A product page with a swipeable gallery and thumbnails, finish and size variants, a quantity stepper, add to bag that confirms in place, shipping promises, a reviews summary, and a details accordion.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `product` | `DetailProduct` | `sample lamp` | The product with finishes, sizes, reviews, shipping lines, and detail sections. |
| `defaultFinish` | `string` | `first finish` | Initial finish id. |
| `defaultSize` | `string` | `first size` | Initial size id. |
| `onAddToCart` | `(selection: DetailSelection) => void \| Promise<void>` |  | Adds the selection. Return a promise to show Adding until it settles; a rejection shows Try again. Without it the preview simulates a short request. |
| `onNotify` | `(selection) => void` |  | Called when someone asks to be told when a sold out finish and size is back. |
| `onWishlistChange` | `(saved: boolean) => void` |  | Called when the heart is toggled. |
| `defaultCartCount` | `number` | `0` | Items already in the bag. |
| `maxQuantity` | `number` | `9` | Upper bound of the stepper. |
| `currency, locale` | `string` | `"USD", "en-US"` | Price formatting. |
| `className` | `string` |  | Extra class on the root. |

#### DetailProduct

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `id, name, collection, summary` (required) | `string` |  | Identity, breadcrumb collection, and a one or two sentence summary. |
| `finishes` (required) | `{ id, name, swatch, images }[]` |  | Each finish has its own photos; switching finish crossfades the gallery in place. |
| `sizes` (required) | `{ id, name, price, note?, soldOutIn? }[]` |  | Price per size. soldOutIn lists finish ids in which the size is out of stock. |
| `rating, reviewCount, distribution` (required) | `number, number, [5 numbers]` |  | Average, total, and counts for 5 to 1 stars. |
| `shipping` (required) | `{ title, text }[]` |  | Delivery, returns, and warranty lines. |
| `sections` (required) | `{ id, title, body }[]` |  | Accordion sections. The first opens by default. |

### Dependencies

- `motion`
- `lucide-react`

### Keyboard

| Keys | Action |
| --- | --- |
| Arrow left / Arrow right | On the gallery, show the previous or next photo. In the finish and size groups, move the selection. |
| Tab | Move from the gallery to thumbnails, variants, the stepper, add to bag, and the accordion. |
| Enter / Space | Choose a thumbnail, toggle an accordion section, or add to bag. |

### Accessibility

- The gallery is a labelled carousel region with slide groups; hidden slides are aria-hidden and the counter is live.
- Finish and size are radiogroups with roving tab stops, like native radios. Sold out sizes stay selectable and say Sold out in text.
- Add to bag reports aria-busy while adding and announces the result; failures show Try again on the button itself.
- Accordion buttons sit in headings with aria-expanded and aria-controls.
- Review bars are hidden from assistive technology and each row carries a text label with its count.

### Motion

- The gallery follows the pointer 1:1, rubber-bands at the ends, projects the flick with momentum, and hands the release velocity to the spring.
- Changing finish crossfades each photo in place; the thumbnail ring slides between thumbnails.
- The price rolls when size changes. Add to bag morphs through Adding and Added to bag without changing width while the bag icon tilts and its count rolls.
- Review bars fill once when they scroll into view; accordion sections open on a critically damped height spring.
- Reduced motion jumps the gallery, removes travel and blur, and shows final bar widths.

### Responsive behavior

- Above 980px the gallery sticks beside the info column; from 680px to 980px both columns share the width equally.
- Below 680px everything stacks: a square gallery with a four up thumbnail row, then the info.
- Under 420px the reviews summary stacks above the bars. Gallery arrows appear on hover only; touch uses swipe.

### Performance

- The gallery drags one track with a motion value; only transform changes during a swipe.
- The first photo uses priority loading; the rest load lazily at the gallery's size.

### Notes for AI agents

- Use as the main product page. Put finish specific photos on each finish so the gallery always matches the chosen swatch.
- Return your cart request from onAddToCart so the button shows real pending and error states.
- Keep sections to three or four; long policies belong on their own page.

### Keywords

product detail, product page, pdp, ecommerce, gallery, variants, add to cart, reviews summary, shop

### Related

- product-listing
- cart-drawer

---

## Feedback board

A feature request board with a submit form that finds similar requests, upvotes, top and new sorting, status filters, and comments.

- Type: Block (composition)
- Access: Pro
- Built from: Input, Textarea, Segmented control, Avatar, Animated counter
- Documentation: https://uiarc.dev/components/blocks/feedback-board

### Overview

Use this to collect and rank feature requests. Save new requests with onSubmit, votes with onVote and comments with onComment, and set each status from your own admin tools.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/feedback-board. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/feedback-board while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- A public or in app board where customers suggest and vote on features.
- Beta programs that need a lightweight place for requests and team replies.

### When not to use

- One to one support conversations; use support-conversation or support-widget.

### Usage

```tsx
import { FeedbackBoard } from "@/components/arc/blocks/feedback-board/feedback-board";

export function FeedbackPage({ requests, user }) {
  return (
    <FeedbackBoard
      defaultRequests={requests}
      currentUser={{ name: user.name, avatar: user.avatar }}
      onSubmit={draft => createRequest(draft)}
      onVote={(id, voted) => vote(id, voted)}
      onComment={(id, text) => comment(id, text)}
    />
  );
}
```

### API

#### FeedbackBoard

A feature request board: post an idea, upvote with a rolling count, sort by top or new, filter by status, and expand a request in place to read and add comments. While a title is typed, similar requests appear so people vote instead of posting duplicates.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `requests` | `FeedbackRequest[]` |  | Controlled requests. Pair with onRequestsChange. |
| `defaultRequests` | `FeedbackRequest[]` | `sample requests` | Initial requests when uncontrolled. |
| `onRequestsChange` | `(requests: FeedbackRequest[]) => void` |  | Called with the full list after a vote, a new request, or a comment. |
| `onVote` | `(id: string, voted: boolean) => void` |  | Called after a vote is added or removed. |
| `onSubmit` | `(draft: { title, details, category }) => void` |  | Called with a new request once the title passes validation. The author's vote is added automatically. |
| `onComment` | `(id: string, text: string) => void` |  | Called when a comment is posted. |
| `statuses` | `{ id: FeedbackStatus; name: string }[]` | `Under review, Planned, In progress, Complete` | Status names for filters and tags. |
| `categories` | `string[]` | `["Feature", "Integration", "Improvement"]` | Category choices in the form. |
| `currentUser` | `{ name: string; avatar?: string }` | `{ name: "You" }` | Author of new requests and comments. |
| `defaultSort` | `"top" \| "new"` | `"top"` | Initial sort. |
| `title` | `string` | `"Feedback"` | Page heading. |
| `className` | `string` |  | Extra class on the root. |

#### FeedbackRequest

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `id, title, details, category` (required) | `string` |  | Request content. |
| `status` (required) | `"review" \| "planned" \| "progress" \| "done"` |  | Shown as a dot and label; filterable. |
| `votes` (required) | `number` |  | Vote count. |
| `voted` | `boolean` |  | Whether the current visitor voted. |
| `author` (required) | `{ name, avatar? }` |  | Who posted it. |
| `at, created` (required) | `string, number` |  | Display time and a sort key for New (higher is newer). |
| `comments` (required) | `{ id, author, text, at, team? }[]` |  | Comments. team marks replies from your team with a Team tag. |

### Dependencies

- `motion`
- `lucide-react`

### Keyboard

| Keys | Action |
| --- | --- |
| Tab | Move through New request, status filters, sort, and each request's vote and title. |
| Enter / Space | Toggle a vote, expand a request, or pick a filter. |
| Arrow left / Arrow right | Switch between Top and New. |
| Escape | Close the new request form. |

### Accessibility

- The form validates on submit with an inline error tied to the title through aria-describedby and aria-invalid.
- Votes are toggle buttons with aria-pressed and a label that names the request and count; changes and posts are announced.
- Request titles are buttons with aria-expanded that reveal details and comments in place.
- Status always pairs a dot with its name; filters and sort are radiogroups.

### Motion

- Voting hops the arrow and rolls the count. Rows keep their place while you vote and only re-rank when you change sort or filter, so nothing moves under the pointer.
- Sort and filter changes glide rows to their new order. A posted request lands at the top with a brief tint.
- The form, similar requests, errors, and expanded details open on a critically damped height spring.
- Reduced motion removes travel and height springs and keeps short fades.

### Responsive behavior

- Content sits in a centered 820px column under a frosted sticky header.
- Below 640px the toolbar stacks: status filters scroll sideways above the sort switch, and the form's category chips sit above a full width Post button.
- Vote boxes shrink slightly and the relative time hides on phones.

### Performance

- Sorting and filtering are memoized per change; only rows that move animate.
- The header blur is one backdrop filter; it falls back to a solid surface when transparency is reduced.

### Notes for AI agents

- Use to collect and rank feature requests from customers. Keep the admin side (status changes, merging) in your own tools and pass the result in.
- The similar requests check is a simple word match on the client. Swap it for server search when the board grows.
- Record votes per signed in user; the board tracks only the current visitor's vote.

### Keywords

feedback board, feature requests, upvote, voting, ideas, product feedback, canny, suggestions

### Related

- changelog-feed
- support-widget
- activity-feed

---

## Profile page

A user profile with cover, bio, stats, activity and project tabs, and an edit sheet that writes back into the page.

- Type: Block (composition)
- Access: Pro
- Built from: Tabs, Avatar, Drawer, Input, Textarea, Button
- Documentation: https://uiarc.dev/components/blocks/profile-page

### Overview

Use this for member or creator profiles. Load the profile, stats, activity, and projects from your API, save edits through onSave, and persist stars through onStarChange; saving in the preview is simulated.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/profile-page. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/profile-page while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- A person's own profile with an edit flow
- Public creator or member pages inside an app
- Team member pages that show recent work

### When not to use

- Account security or billing settings, use settings-page
- A directory of many people, use team-directory
- A marketing team section, use team-showcase

### Usage

```tsx
import { ProfilePage } from "@/components/arc/blocks/profile-page/profile-page";

export function Profile({ user, activity, projects }) {
  return (
    <ProfilePage
      profile={user}
      activity={activity}
      projects={projects}
      onSave={async next => {
        const res = await fetch("/api/me", { method: "PATCH", body: JSON.stringify(next) });
        if (!res.ok) throw new Error("Could not save your profile.");
      }}
    />
  );
}
```

### API

#### ProfilePage

A full profile screen: cover photo, overlapping avatar, name and headline, an about column with bio, links, and stats, and Activity and Projects tabs. Edit profile slides a sheet in from the right edge; saving writes the changes back into the page and briefly highlights every field that changed.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `profile` | `ProfileDetails` | `sample profile` | Name, handle, headline, location, website, bio, avatar and cover image paths, and the joined label. |
| `stats` | `ProfileStat[]` | `sample stats` | Up to three counts shown under the bio, each with an id, label, and value. |
| `activity` | `ProfileActivity[]` | `sample activity` | Activity items with a kind (shipped, commented, created, reviewed, starred), action text, target, optional detail, time, and a group heading such as This week. |
| `projects` | `ProfileProject[]` | `sample projects` | Project cards with a cover image, description, visibility, collaborators, updated label, and star count. |
| `tab` | `"activity" \| "projects"` |  | Controlled tab. Pair with onTabChange. |
| `defaultTab` | `"activity" \| "projects"` | `"activity"` | Tab shown on mount when uncontrolled. |
| `onTabChange` | `(tab: ProfileTab) => void` |  | Called when the tab changes. |
| `onSave` | `(profile: ProfileDetails) => void \| Promise<void>` |  | Persists edited details. Throw an Error to keep the sheet open and show its message. Without it the preview simulates a save. |
| `onStarChange` | `(projectId: string, starred: boolean) => void` |  | Called when a project star is toggled. |
| `profileUrl` | `string` | `"https://northwind.app/@<handle>"` | Public link copied by Share. |
| `editable` | `boolean` | `true` | Shows Edit profile. Set false when someone views another person's profile. |
| `className` | `string` |  | Extra class on the root. |

### Dependencies

- `motion`
- `lucide-react`

### Keyboard

| Keys | Action |
| --- | --- |
| Tab | Moves through Share, Edit profile, links, tabs, and project stars. |
| Arrow left / Arrow right | Switch between the Activity and Projects tabs. |
| Escape | Closes the edit sheet without saving and returns focus to Edit profile. |
| Enter | Saves the edit sheet from any single line field. |

### Accessibility

- Tabs use tablist, tab, and tabpanel roles with roving tab index and aria-controls.
- The edit sheet is a modal dialog with a labelled title; focus moves to the first field, stays inside while open, and returns to Edit profile on close.
- Validation errors are tied to their inputs with aria-describedby and aria-invalid; save errors use role alert.
- Star buttons expose aria-pressed and name the project and count. Share keeps its width while its label changes to Copied or Failed.

### Motion

- The tab underline travels between tabs on the morph spring; tab content fades up 6px.
- The edit sheet slides from the right edge on the smooth spring over a fading scrim, and leaves the same way faster.
- Saved fields glow once with the accent tint, and a new star pops with a small spring.
- Reduced motion swaps the slide for a fade, keeps the highlight, and removes travel.

### Responsive behavior

- Below 760px the about column stacks above the tabs; below 560px project cards go to one column.
- The cover shortens and the avatar shrinks on narrow screens; the edit sheet becomes full width.
- The screen height is min(760px, 100dvh) and the page scrolls inside it.

### Performance

- Only transform and opacity animate; images are lazy except the cover.
- The edit sheet mounts only while open.
- Activity and projects render as plain lists; paginate beyond a few hundred items.

### Notes for AI agents

- Choose this for a member, creator, or teammate profile inside a product. It is a full screen: the page scrolls inside the block so the sheet always covers the visible area.
- Load all data from your API and pass it in; the block owns only the edit draft and local star state.
- Set editable={false} for other people's profiles and replace the actions with Follow or Message in your own fork.
- Covers and avatars render with next/image; pass paths your image config allows.

### Keywords

profile, user profile, account page, edit profile, cover photo, avatar, bio, activity tab, projects

### Related

- settings-page
- team-directory
- activity-feed
- team-members

---

## Help center

A help center with instant search, topic cards, and popular articles that open into a readable article with an outline and feedback.

- Type: Block (composition)
- Access: Pro
- Built from: Search field, Command palette, Card, Button
- Documentation: https://uiarc.dev/components/blocks/help-center

### Overview

Use this as a self serve support site or in-app help. Load categories and articles from your CMS, pass a server search through search if you have one, and record votes through onFeedback; contact in the preview is simulated.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/help-center. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/help-center while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- A public help center or knowledge base
- In-app help with searchable articles
- Support portals that deflect tickets with good answers

### When not to use

- Developer API reference with a nav tree, use docs-sidebar
- A short FAQ on a marketing page, use faq-section
- Live chat with support, use support-conversation

### Usage

```tsx
import { HelpCenter } from "@/components/arc/blocks/help-center/help-center";

export function Help({ articles, categories }) {
  return (
    <HelpCenter
      brand="Acme"
      articles={articles}
      categories={categories}
      onArticleOpen={article => router.replace(`/help/${article.id}`)}
      onFeedback={(id, helpful, comment) => fetch("/api/help/feedback", { method: "POST", body: JSON.stringify({ id, helpful, comment }) })}
    />
  );
}
```

### API

#### HelpCenter

A help center app. The home screen leads with a large instant search, then topic cards, popular articles, and a contact card. Results appear under the field as you type with the matching words highlighted. Articles open in a reading view with breadcrumbs, a sticky on this page outline that follows your scroll, a feedback question, and related articles.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `articles` | `HelpArticle[]` | `sample articles` | Articles with id, title, categoryId, summary, updated label, reading minutes, popular flag, and sections of paragraphs and optional steps. |
| `categories` | `HelpCategory[]` | `sample categories` | Topics with id, name, description, and an icon key: start, billing, team, integrations, security, or troubleshooting. |
| `brand` | `string` | `"Northwind"` | Name in the top bar. |
| `heading` | `string` | `"How can we help?"` | Heading above the big search. |
| `suggestions` | `string[]` | `["invoice", "single sign-on", "slack"]` | Quick searches under the big search field. |
| `defaultArticleId` | `string` |  | Opens this article on mount, for deep links. |
| `search` | `(query: string, articles: HelpArticle[]) => HelpArticle[]` | `searchArticles` | Ranks results. The default requires every word and ranks title matches above summary and body matches. |
| `onFeedback` | `(articleId: string, helpful: boolean, comment?: string) => void \| Promise<void>` |  | Records a vote and the optional comment. |
| `onContact` | `() => void \| Promise<void>` |  | Opens your support channel. Without it the preview simulates a sent request. |
| `onArticleOpen` | `(article: HelpArticle) => void` |  | Called when an article opens, for routing or analytics. |
| `className` | `string` |  | Extra class on the root. |

### Dependencies

- `motion`
- `lucide-react`

### Keyboard

| Keys | Action |
| --- | --- |
| Arrow down / Arrow up | Move through search results. |
| Enter | Opens the highlighted result. |
| Escape | Clears the search, then leaves the field. |
| Tab | Moves through topics, articles, the outline, and feedback. |

### Accessibility

- Search is a combobox with a listbox of options and aria-activedescendant; the result count is announced politely.
- Articles use real headings; outline links move focus to their section heading and mark the current one with aria-current.
- Breadcrumbs are a labelled navigation; the feedback area announces its thank you politely.
- Topic icons are decorative; every card is a button named by its text.

### Motion

- Results drop in from the field with a short fade and scale; they are never animated while you arrow through them.
- Views slide 16px in the direction of travel, deeper to the right and back to the left.
- The outline bar follows the section you are reading on the snappy spring; clicking a section scrolls smoothly.
- Feedback states crossfade and the card resizes on the smooth spring. Reduced motion uses fades and instant scrolling.

### Responsive behavior

- Topic cards go from one to two to three columns.
- The compact search moves into the top bar once you leave the home screen.
- The screen height is min(760px, 100dvh) and the page scrolls inside it.

### Performance

- Search runs in memory on every keystroke; switch to a server search past a few thousand articles.
- Scroll tracking uses one passive listener and reads section positions only while scrolling.

### Notes for AI agents

- Choose this for a self serve support site, a docs style help area, or an in-app help screen.
- Wire a server search through search when you have many articles; keep the combobox and highlight behavior.
- Article sections are plain text paragraphs and steps; render your CMS rich text inside the prose container if you need links or images.
- The outline appears from 860px of width; below that the article reads as one column.

### Keywords

help center, knowledge base, support, faq, search, instant search, articles, table of contents, was this helpful, docs

### Related

- docs-sidebar
- faq-section
- support-widget
- support-conversation

---

## Hero signup

A full screen waitlist hero on a soft, drifting mesh gradient: the email field validates as you type and its button grows into the confirmation with your place in line.

- Type: Block (composition)
- Access: Pro
- Built from: Gradient mesh, Input, Button
- Documentation: https://uiarc.dev/components/blocks/hero-signup

### Overview

Use this as the first section of a waitlist or early access page. Add the email in onSubscribe and return the place in line; reject with an Error to show its message with a retry. Signups in the preview are simulated.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/hero-signup. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/hero-signup while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- Waitlists, early access, and launch pages where the email is the only ask.
- Pages that want a calm but alive first impression without product screenshots.

### When not to use

- Signup that needs a password, SSO choice, or consent up front; use Sign up form.
- A newsletter box further down the page; use Newsletter signup.

### Usage

```tsx
import { HeroSignup } from "@/components/arc/blocks/hero-signup/hero-signup";

export function Hero() {
  return (
    <HeroSignup
      count={2140}
      onSubscribe={async email => {
        const res = await fetch("/api/waitlist", { method: "POST", body: JSON.stringify({ email }) });
        if (!res.ok) throw new Error("We couldn't save your spot");
        const { position } = await res.json();
        return position;
      }}
    />
  );
}
```

### API

#### HeroSignup

A full screen landing hero built around one email field, on a soft mesh gradient tinted from the page accent. The field validates as you type, the button holds a spinner while the request runs, and on success the button grows across the field into the confirmation, where your place in line rolls in.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` | `ReactNode` | `"Close the month in an afternoon"` | Headline. A string rises in word by word on load. |
| `description` | `ReactNode` |  | One supporting line under the headline. |
| `placeholder` | `string` | `"you@company.com"` | Email field placeholder. |
| `buttonLabel` | `string` | `"Join waitlist"` | Submit label. |
| `shortButtonLabel` | `string` | `"Join"` | Submit label on very narrow layouts. |
| `footnote` | `ReactNode` | `"One email when your invite is ready. Nothing else."` | Quiet line under the field. Validation, a typo fix, a failure with retry, and the confirmation replace it in place. |
| `count` | `number` | `1283` | People already on the list. The social proof rolls up by one when the visitor joins. |
| `people` | `{ name: string; src: string }[]` |  | Portraits in the social proof stack. Up to five are shown. |
| `proof` | `(count: ReactNode) => ReactNode` |  | Social proof line. Receives the rolling count. |
| `hue` | `number` |  | Mesh hue in degrees. Defaults to the hue of the page accent, or a calm blue violet for the neutral accent. The palette stays pale and low in chroma in light mode and deep and calm in dark mode. |
| `onSubscribe` | `(email: string) => void \| number \| Promise<void \| number>` |  | Adds the email to the list. Resolve with the visitor's place in line, or nothing to use count + 1. Reject with an Error to show its message with Try again. Without it the preview simulates the request. |
| `onStateChange` | `(state: "idle" \| "submitting" \| "error" \| "success") => void` |  | Called on every state change, for analytics. |
| `className` | `string` |  | Extra class on the section. |

### Dependencies

- `motion`
- `lucide-react`

### Keyboard

| Keys | Action |
| --- | --- |
| Enter | Submits the email. The field shows send on mobile keyboards. |
| Tab | Moves from the field to the button, then to the inline actions under it: the typo fix, Try again, or Change email. |

### Accessibility

- A real form with a labeled type=email field, autocomplete=email, inputmode=email and enterkeyhint=send.
- Validation messages are specific (a missing @, an unfinished domain) and tied to the field with aria-describedby and aria-invalid; they appear after blur or submit, never while the first address is still being typed.
- Joining, success, and failure are announced through a polite status region; focus moves to the confirmation on success and back to the field on Change email.
- The button stays focusable while busy and ignores repeat submits, so a double press never joins twice.
- The field font is 16px on phones so iOS never zooms, and every target is at least 44px tall.

### Motion

- The headline rises in word by word once on load, followed by the supporting line, the field, and the social proof.
- Submitting crossfades the label into a spinner inside the same button, so nothing changes size.
- Success is one spatial transition: the button's shape grows across the whole field on a critically damped spring and becomes the confirmation, while the place in line rolls in digit by digit.
- The mesh drifts on a slow, seamless loop and blends into the new colors when the theme or accent changes. Reduced motion draws one still frame, removes the rise, the shake and the rolls, and swaps states instantly.

### Responsive behavior

- Fills exactly one screen: min-height is 100svh (100vh where unsupported), so mobile browser bars never hide the bottom, and the content is centered vertically.
- Works from 320px: the headline scales with the container, the button label shortens on very narrow widths, and the social proof stacks.
- The line under the field reserves its height, so a validation message or the confirmation never moves the content below.

### Performance

- The background is the Gradient mesh component in background mode: one WebGL triangle with a light shader grain, no editor chrome and no pointer handling.
- The loop stops while the hero is off screen or the tab is hidden. Without WebGL the same palette renders as CSS radial gradients.

### Notes for AI agents

- Choose this when the first section of a page exists to collect an email: a waitlist, early access, or a launch list.
- Wire onSubscribe to your API and return the real position; throw Errors with short human messages and the block handles busy, retry, and focus.
- In the preview, an address that contains fail shows the failure path once, so Try again can be tested.

### Keywords

hero, waitlist, email signup, mesh gradient, early access, landing page, email capture, launch

### Related

- hero-section
- newsletter-signup
- cta-section

---

## Pivot builder

A pivot table builder where you drag dimensions and measures into Rows, Columns, Values and Filters wells, with a live preview while you hover, per value aggregation, subtotals, a grand total, heat shading, collapsible row groups, swap and CSV export.

- Type: Block (composition)
- Access: Pro
- Built from: Button, Empty state
- Documentation: https://uiarc.dev/components/blocks/pivot-builder

### Overview

Render <PivotBuilder /> for the Ridgeline Coffee demo, or pass records, fields (dimensions and measures) and a defaultLayout of { filters, columns, rows, values } chips. Use onLayoutChange to save views and fileName to name the export.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/pivot-builder. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/pivot-builder while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- Self-serve analysis where the viewer picks the rows, columns and measures.
- Internal reporting screens that replace a spreadsheet pivot table.
- Exploring a flat export before deciding which fixed chart or report to build.

### When not to use

- Use data-grid or sortable-data-table to browse, edit or select individual records; the pivot only shows aggregates.
- Use tree-table for a hierarchy that already exists in the data, such as folders or an org chart.
- Use cohort-retention or metric-explorer when the question is fixed and a chart answers it faster.

### Usage

```tsx
import { PivotBuilder, type PivotField } from "@/components/arc/blocks/pivot-builder/pivot-builder";

const fields: PivotField[] = [
  { id: "team", label: "Team", kind: "dimension" },
  { id: "month", label: "Month", kind: "dimension", values: ["Jan", "Feb", "Mar"] },
  { id: "hours", label: "Hours", kind: "measure", format: "number", aggs: ["sum", "average", "percent"] },
];

export function TimeReport({ rows }: { rows: { team: string; month: string; hours: number }[] }) {
  return (
    <PivotBuilder
      title="Logged hours"
      description="Q1 2026, all teams"
      records={rows}
      fields={fields}
      defaultLayout={{
        filters: [],
        columns: [{ id: "c-month", field: "month" }],
        rows: [{ id: "r-team", field: "team" }],
        values: [{ id: "v-hours", field: "hours", agg: "sum", heat: true }],
      }}
      fileName="logged-hours.csv"
      onLayoutChange={layout => saveView(layout)}
    />
  );
}
```

### API

#### PivotBuilder

A pivot table builder. Drag dimensions and measures from the field list into Rows, Columns, Values and Filters, and the pivot recomputes as you hover, with subtotals, a grand total, per value aggregation, heat shading, row groups that expand and collapse, a swap for rows and columns, and CSV export.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `records` | `PivotRecord[]` | `pivotOrders` | Flat records to aggregate, one object per row keyed by field id. Defaults to 1,184 Ridgeline Coffee orders from 2025, generated from a fixed seed. |
| `fields` | `PivotField[]` | `pivotFields` | Fields in the list: { id, label, kind: "dimension" \| "measure", values?, format?, aggs? }. values sets the display order of a dimension; format is currency, number, percent or text; aggs lists the aggregations a measure offers, first is the default. |
| `defaultLayout` | `PivotLayout` | `starterLayout` | Lanes the pivot opens with: { filters, columns, rows, values }, each a list of { id, field, agg?, heat? }. Pass empty lists to open on the empty state. |
| `defaultExclusions` | `PivotExclusions` | `{}` | Values hidden by the filters lane, keyed by field id, such as { channel: ["Retail"] }. Only fields placed in Filters apply. |
| `title` | `string` | `"Sales pivot"` | Heading of the screen. |
| `description` | `string` | `"Ridgeline Coffee orders, January to December 2025"` | Line under the heading. Pass an empty string to hide it. |
| `fileName` | `string` | `"ridgeline-sales-pivot.csv"` | Name of the file Export CSV downloads. |
| `onLayoutChange` | `(layout: PivotLayout) => void` |  | Called after every committed change to the lanes, an aggregation or heat shading. Hover previews during a drag do not call it. |
| `className` | `string` |  | Class on the root element. |

#### Aggregations

Set per value chip from its menu. The same measure can sit in Values twice with different aggregations.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `sum` | `Agg` |  | Adds the measure across the records in a cell. |
| `average` | `Agg` |  | Mean of the measure across the records in a cell. |
| `count` | `Agg` |  | Number of records in a cell. |
| `distinct` | `Agg` |  | Number of different values, such as unique customers. Offered for text measures. |
| `percent` | `Agg` |  | Share of the filtered grand total, shown as % of total. Text measures use the share of records. |

### Dependencies

- `motion`
- `lucide-react`
- `@radix-ui/react-dropdown-menu`

### Keyboard

| Keys | Action |
| --- | --- |
| Enter / Space on a field | Opens the field menu: add a dimension to rows, columns or filters, or add a measure to values with a chosen aggregation. |
| Enter / Space on a chip | Opens the chip menu: aggregation and heat shading for values, shown values for filters, move, reorder and remove. |
| Alt + Arrow left / Arrow right | Moves the focused chip one place within its well. |
| Delete / Backspace | Removes the focused chip from the pivot. |
| Arrow keys in a menu, Escape | Move through menu items and close the menu, returning focus to the chip. |
| Enter / Space on a row group | Expands or collapses that group. The corner button expands or collapses all groups. |

### Accessibility

- The result is a table with role="table", row, rowheader, columnheader and cell roles, and aria-colspan on grouped column headers, so screen readers read each value with its row and column.
- Every drag has a menu path: fields and chips are real buttons with menus, so the whole pivot can be built without a pointer.
- Row groups are buttons with aria-expanded. The scroll area is focusable and named, so keyboard users can scroll wide pivots.
- Changes are announced in a polite live region, such as "Country moved to columns" or "Exported ridgeline-sales-pivot.csv".
- Heat shading is never the only signal: every shaded cell prints its value, and the footer names the shaded measure with a low to high key.
- Pointer focus draws no ring; keyboard focus shows Arc's shared focus ring. Keyboard position shows as a filled chip, field or row header.

### Motion

- The dragged chip follows the pointer on motion values, with no React render per frame. React only hears when the target well or insert position changes.
- Chips in the wells glide aside to open a dashed slot where the chip will land, on the smooth spring with no overshoot. On release the chip flies into that slot, or home if nothing changed, or fades out when dropped outside to remove.
- The table previews the drop while you hover: a new structure crossfades in, rows that appear or leave slide the rest into place, and a changed number rises into its cell.
- Group chevrons rotate on the spring token, heat shading fades by opacity, and the swap icon turns half a turn per swap.
- Reduced motion removes the fly, lift and slide; chips and rows land at once and numbers change in place.

### Responsive behavior

- From 880px the field list sits beside the wells as a column; below it becomes wrapped field pills above the wells.
- Wells sit in a two by two grid from 640px and stack below it, with the well name above its chips on phones.
- The table scrolls inside its card with the header row and first column pinned, and the grand total pinned to the bottom.
- On touch screens chips, fields, row groups and menu items grow to 44px. A tap opens the menu; a drag moves the chip.

### Performance

- The pivot recomputes in one pass per layout change and memoizes on layout and filters; 1,200 records with nested rows and columns compute in well under a frame.
- Drag hit testing reads layout offsets, not animated rects, so the insert position never oscillates while neighbours move.
- Row and cell animations use transform and opacity only. Very large pivots (hundreds of rows) stay correct but should collapse groups by default.

### Notes for AI agents

- Choose it when people need to slice one flat dataset their own way: sales by region and quarter, hours by team and month, tickets by queue and priority.
- Feed records as flat objects keyed by field id. Give dimensions an explicit values order when the natural order is not alphabetical (quarters, months, sizes).
- Start with a meaningful defaultLayout so the first view already answers a question. Use the empty layout only where building from scratch is the point.
- Persist views with onLayoutChange and pass the saved layout back as defaultLayout with a key to restore it.
- The engine is synchronous and client side. Aggregate on the server first for datasets beyond tens of thousands of records.

### Keywords

pivot table, pivot, crosstab, olap, aggregation, group by, subtotal, grand total, heatmap, drag and drop, report builder, analytics, csv export, spreadsheet

### Related

- data-grid
- tree-table
- cohort-retention
- metric-explorer
- sortable-data-table

---

## Search results

A faceted workspace search page with suggestions, facet counts that follow the query, filter chips, mixed doc, person and file results with highlighted matches, a gliding keyboard cursor and a preview pane.

- Type: Block (composition)
- Access: Pro
- Built from: Checkbox, Slider, Bottom sheet, Filter toolbar, Segmented control, Empty state, Button, Avatar
- Documentation: https://uiarc.dev/components/blocks/search-results

### Overview

Render <SearchResults /> for the demo, or pass results (docs, people, files), teams, recentSearches and suggestedSearches, with onSearch and onOpen to wire it to a real index. Set latency={0} and swap results yourself when your fetch resolves.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/search-results. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/search-results while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- A full search page for a workspace or knowledge base that returns several kinds of things at once.
- Search where people narrow by type, team, and date, and want to read a match before opening it.

### When not to use

- Use command-palette for quick jump to navigation from any screen.
- Use product-listing for a storefront grid filtered by price, color, and size.
- Use customers-table or sortable-data-table when results are records to compare in columns.

### Usage

```tsx
import { SearchResults } from "@/components/arc/blocks/search-results/search-results";

export function WorkspaceSearch({ items }: { items: SearchResult[] }) {
  return (
    <SearchResults
      results={items}
      workspace="Acme"
      defaultQuery=""
      latency={0}
      onSearch={query => track("search", { query })}
      onOpen={result => router.push(`/${result.kind}/${result.id}`)}
    />
  );
}
```

### API

#### SearchResults

A faceted search results page for a workspace. A query bar with recent and suggested searches, a facet sidebar whose counts follow the query, a last edited range, active filter chips, and one list of mixed docs, people, and files with every match highlighted. A keyboard cursor glides through the results and a preview pane follows it.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `results` | `SearchResult[]` | `sample workspace` | Everything that can be found. Each item is a doc ({ title, path, snippet, body, author, updated, readMinutes }), a person ({ person, title, role, snippet, email, location, owns }), or a file ({ title, ext, size, snippet, owner, updated, photo?, pages? }), all with an id and a team. |
| `teams` | `SearchTeam[]` | `teams` | Team facet options ({ id, label }) in display order. |
| `recentSearches` | `string[]` |  | Recent queries shown first in the suggestions. Runs are added to the front, up to five. |
| `suggestedSearches` | `string[]` |  | Suggested queries shown under recent ones and offered again when nothing matches. |
| `defaultQuery` | `string` | `"onboarding"` | Query shown and run on first render. |
| `defaultSort` | `"relevance" \| "newest" \| "title"` | `"relevance"` | Initial sort: best match, newest first, or A to Z. |
| `today` | `string` | `"2026-09-24"` | ISO day that relative dates and the edited range are measured from, so the server and client render the same labels. |
| `workspace` | `string` | `"Northwind"` | Workspace name used in the placeholder and the region label. |
| `latency` | `number` | `650` | Simulated query time in milliseconds while skeletons show. 0 shows results at once. |
| `onSearch` | `(query: string) => void` |  | Called each time a query runs, from Enter, a suggestion, a spelling fix, or an empty state suggestion. |
| `onOpen` | `(result: SearchResult) => void` |  | Called when the preview's primary action (Open doc, View profile, Download) completes. |
| `className` | `string` |  | Class on the root section. |

### Dependencies

- `motion`
- `lucide-react`

### Keyboard

| Keys | Action |
| --- | --- |
| / | Focuses the query from anywhere on the page, unless another field has focus. |
| Arrow down / Arrow up in the query | Moves through recent and suggested searches; with the list closed, Arrow down moves into the results. |
| Enter in the query | Runs the highlighted suggestion or the typed query. |
| Escape in the query | Closes the suggestions, then clears the text. |
| Arrow down / Arrow up, J / K | Moves the result cursor; Arrow up on the first result returns to the query. |
| Home / End | Jumps to the first or last result. |
| Enter / Space on a result | Opens it: the preview pane follows on wide layouts, and a sheet opens on narrow ones. |
| Escape in the results | Returns focus to the query. |

### Accessibility

- The query is a combobox with aria-activedescendant into a grouped listbox of recent and suggested searches.
- Results are one listbox with aria-activedescendant, so a screen reader hears each result's title, meta, and snippet as the cursor moves.
- Result counts and loading are announced in a polite status region; the results region sets aria-busy while skeletons show.
- Facets are fieldsets with legends; each option is a labeled checkbox, and options with no matches are disabled rather than hidden.
- The last edited range is a two thumb slider with named thumbs and month value text.
- Keyboard position shows through the gliding fill, never a focus ring. Highlights use mark elements, and matches are never shown by color alone.

### Motion

- One neutral fill glides between results on a no overshoot spring as the cursor moves, by keyboard or pointer.
- The result count rolls up when results grow and down when a filter narrows them, in tabular numerals.
- New result sets crossfade with a short rise; the preview pane crossfades per result. Skeletons share the result grid, so nothing shifts when results land.
- The suggestions menu scales in from the query bar; the chip row opens and closes its height on a smooth spring.
- Reduced motion removes travel and the skeleton pulse and keeps plain fades.

### Responsive behavior

- From 1120px wide the layout is facets, results, and a preview pane; below that the preview opens in a bottom sheet.
- Below 680px the facets move into a filters sheet with a sticky Clear all and Show results footer, and the query bar gains a Filters button with a count.
- Rows and sheet controls keep 44px touch targets; titles wrap to two lines and snippets clamp to two.
- Layout decisions use a container query, so the block adapts to its column, not the window.

### Performance

- Matching, sorting, and facet counts are memoized and run on the client for a few hundred items; move them to the server for larger indexes.
- Only transform and opacity animate; the preview pane width is measured once with a ResizeObserver.

### Notes for AI agents

- Map your index to the three result shapes; keep snippets to the sentence that contains the match, since highlighting reads the query terms.
- Facet counts are disjunctive within a group: each option counts what you would see if you added it. Keep that behavior when counts come from a server.
- Pass latency={0} and drive loading from your own fetch by swapping results when a query resolves.
- Photos in file results come from lib/media; replace them with real thumbnails.

### Keywords

search, search results, faceted search, filters, facets, highlight, keyboard navigation, skeleton, no results, workspace search, app shell

### Related

- command-palette
- filter-toolbar
- help-center
- product-listing

---

## Environment variables

An environment variables and secrets manager with masked values, per-environment scope toggles, .env paste import with duplicate and invalid key warnings, write-only sensitive values, an environment diff by fingerprint, and a redeploy banner.

- Type: Block (composition)
- Access: Pro
- Built from: Button, Checkbox, Copy button, Input, Search field, Segmented control, Select, Switch, Textarea
- Documentation: https://uiarc.dev/components/blocks/env-variables

### Overview

Render <EnvVariables /> for the demo, or pass variables, project and sampleDotenv with onChange to persist rows and onRedeploy (which can return a promise) to run a real deploy.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/env-variables. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/env-variables while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- A settings screen where developers manage configuration and secrets across development, preview, and production.
- Onboarding a project by pasting an existing .env file and scoping it to environments in one step.
- Auditing drift between environments before a release, such as a key set in Preview but missing in Production.

### When not to use

- Use api-keys for creating, scoping, and revoking access tokens that your product issues to its users.
- Use a plain form for a handful of fixed settings that are not per environment.

### Usage

```tsx
import { EnvVariables } from "@/components/arc/blocks/env-variables/env-variables";

export function ProjectEnvironment({ project, variables }) {
  return (
    <EnvVariables
      project={project.slug}
      variables={variables}
      sampleDotenv=""
      onChange={rows => saveVariables(project.id, rows)}
      onRedeploy={environments => triggerRedeploy(project.id, environments)}
    />
  );
}
```

### API

#### EnvVariables

An environment variables and secrets manager. Each row is one value and the environments it applies to, drawn as a matrix of Development, Preview, and Production toggles, so a key can hold a different value per environment. Values stay masked and are not in the DOM until revealed; sensitive values are write-only. Add one variable or paste a whole .env file, compare two environments by fingerprint, and redeploy from a banner that appears after changes.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variables` | `EnvVariable[]` | `VARIABLES` | Rows in any order: { id, key, value, environments, sensitive, updated, updatedBy }. A key can appear on several rows as long as each environment is covered at most once. The block sorts rows by key. |
| `project` | `string` | `"northwind-storefront"` | Project name shown under the heading. |
| `sampleDotenv` | `string` | `SAMPLE_DOTENV` | Text the paste area starts with when Import .env opens. Pass an empty string for a blank paste area. |
| `title` | `string` | `"Environment variables"` | Heading text. |
| `onChange` | `(variables: EnvVariable[]) => void` |  | Called with every row after each add, import, edit, removal, scope toggle, or copy between environments. |
| `onRedeploy` | `(environments: EnvName[]) => void \| Promise<void>` |  | Called when Redeploy is pressed with the environments that changed. Return a promise to keep the banner pending until it settles; a rejection shows the failure state and keeps the changes queued. Without it, the deploy is simulated. |
| `className` | `string` |  | Class on the root section. |

### Dependencies

- `motion`
- `lucide-react`
- `@radix-ui/react-select`
- `@radix-ui/react-switch`
- `@radix-ui/react-checkbox`

### Keyboard

| Keys | Action |
| --- | --- |
| Tab | Moves through the header actions, search, view switch, and each row's reveal, copy, environment toggles, and edit button. |
| Enter / Space | Reveals or hides a value, turns an environment on or off for a row, opens the inline editor, or presses a button. |
| Escape | Closes the inline editor or the add panel and returns focus to the button that opened it. |
| Arrow keys | Move between options in the view switch, the add mode switch, and the compare environment selects. |
| Enter in a form | Saves the edited value, saves a new variable, or imports the parsed .env lines. |

### Accessibility

- Masked values render as bullets hidden from assistive technology plus a visually hidden "Hidden value" or "Sensitive value, write-only" label; the real value is only rendered after Reveal.
- Reveal and environment toggles are buttons with aria-pressed and names that include the key, such as "Production for DATABASE_URL".
- Each row's toggles sit in a labelled group; the wide matrix column heads are decorative and every toggle carries its own name.
- Inline errors (invalid key, key already set in an environment, empty value) are tied to their fields; scope conflicts appear as an alert under the row.
- A polite live region announces every change, import, removal, and redeploy result, and the .env parse summary updates live as you type.
- Pointer focus draws no ring; keyboard focus shows Arc's shared focus ring. Keyboard position shows as a fill on toggles and icon buttons, matching hover.

### Motion

- The redeploy banner, add panel, inline editor, and conflict notes open with height and opacity on the smooth spring and close with a quicker exit ease.
- Environment toggles fill with a snappy scale and draw their check with pathLength, both without overshoot.
- Revealing a value crossfades the mask and the value with a short rise in a fixed height slot, so the row never jumps.
- Added and removed rows grow and collapse their height so the list closes its gap; saved or imported rows glow once in the accent and fade.
- The Variables and Compare views crossfade with a small rise. Reduced motion removes all travel and lands every change at once.

### Responsive behavior

- From a 760px container, rows become a matrix: key, value, one toggle column per environment with a count of values set, and an edit action.
- Below that, each row stacks the key and edit action, then the value, then three labelled environment pills in an even grid.
- Below 560px header actions, search, form actions, and the redeploy button go full width; the .env preview drops the masked value column.
- Toggles, icon buttons, and the swap control grow to 44px targets on touch screens. The block is a container query, so it adapts to the space it is placed in.

### Performance

- The .env text is parsed in a memo keyed on the text, rows, and chosen environments; there is no per-frame work.
- Only revealed rows render their value and copy button, and only the open row renders an editor.
- Timers for notes, the saved glow, and the redeploy confirmation are cleared on change and unmount.

### Notes for AI agents

- Choose it for a project settings page in a hosting, deployment, or backend platform. Wire onChange to your store and onRedeploy to your deploy API.
- Search matches key names only, never values. Compare shows a six character fingerprint of each value, so two environments can be checked without exposing either.
- Sensitive rows are write-only: the editor starts empty and saving replaces the value; the flag cannot be turned off without removing and re-adding the variable.
- The .env parser handles comments, blank lines, export prefixes, quotes, and inline comments. Later duplicates win the key and earlier ones are skipped; keys that start with a number or contain other characters are rejected.

### Keywords

environment variables, env, dotenv, .env, secrets, config, configuration, vercel, netlify, deploy, redeploy, preview, production, development, sensitive, masked, diff, compare environments, developer settings

### Related

- api-keys
- security-settings

---

## Market terminal

A trading terminal with a canvas candlestick chart, volume, moving averages, crosshair OHLC readout, wheel, drag and pinch zoom, a live watchlist with sparklines and flashing prices, and a market and limit order ticket.

- Type: Block (composition)
- Access: Pro
- Built from: Animated counter, Button, Number field, Segmented control
- Documentation: https://uiarc.dev/components/blocks/market-terminal

### Overview

Render <MarketTerminal /> for the demo, or pass symbols, holdings, buyingPower, orders, defaultTicker and defaultRange with your own data. Pass onPlaceOrder and onCancelOrder (they can return promises) to connect it to a real order API.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/market-terminal. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/market-terminal while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- A trading or investing product that needs a full chart, a watchlist and an order ticket on one screen.
- A paper trading or education app where people practice placing market and limit orders against moving prices.
- A markets dashboard where candles, volume and moving averages must be inspected bar by bar.

### When not to use

- Use order-book-depth to show bids and asks at each price level.
- Use metric-explorer or a line chart for product or business metrics without open, high, low and close.
- Use options-payoff to model an options position's profit at expiry.
- Use wallet-card for a simple balance and recent transactions without a chart.

### Usage

```tsx
import { MarketTerminal } from "@/components/arc/blocks/market-terminal/market-terminal";

export function Trade() {
  return (
    <MarketTerminal
      defaultTicker="AAPL"
      defaultRange="1D"
      onPlaceOrder={order => api.orders.create(order)}
      onCancelOrder={order => api.orders.cancel(order.id)}
    />
  );
}
```

### API

#### MarketTerminal

A trading terminal screen. A candlestick chart with volume, two moving averages, a crosshair with an OHLC readout, and wheel, drag and pinch zoom sits beside a watchlist with intraday sparklines and flashing live prices, and an order ticket for market and limit orders with an order list.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `symbols` | `MarketSymbol[]` | `SYMBOLS` | Watchlist symbols in order: ticker, name, exchange, price, previous close, daily volatility (a fraction such as .02) and average daily volume. Candles are generated from these, deterministically per ticker and range. |
| `holdings` | `Holding[]` | `HOLDINGS` | Shares held per ticker. The ticket shows the position and blocks selling more than is held. |
| `buyingPower` | `number` | `24860.35` | Cash available for buys. The ticket blocks a buy that costs more, and fills update it. |
| `orders` | `OrderRecord[]` | `ORDERS` | Orders in the ticket's list, newest first: side, type, ticker, shares, price, status (filled, working or canceled) and time. |
| `defaultTicker` | `string` |  | Ticker charted on first render. Defaults to the first symbol. |
| `defaultRange` | `"1D" \| "5D" \| "1M" \| "6M" \| "1Y"` | `"6M"` | Time range on first render. 1D and 5D use 5 and 30 minute candles; the rest are daily. |
| `defaultAverages` | `AverageId[]` | `["ma20", "ma50"]` | Moving averages drawn on first render. Viewers toggle them in the toolbar. |
| `live` | `boolean` | `true` | Streams simulated ticks. Viewers can still pause and resume them with the Live button. |
| `tickInterval` | `number` | `1200` | Milliseconds between simulated ticks. |
| `onPlaceOrder` | `(order: OrderRequest) => void \| Promise<void>` |  | Called when an order is submitted with its side, type, ticker, shares and price. Return a promise to keep the button pending; a rejection leaves the order unplaced and says so under the button. |
| `onCancelOrder` | `(order: OrderRecord) => void \| Promise<void>` |  | Called when a working order is canceled from the list. |
| `className` | `string` |  | Class on the root element. |

### Dependencies

- `motion`
- `lucide-react`

### Keyboard

| Keys | Action |
| --- | --- |
| Tab | Moves through the Live button, the range control, the average toggles, the zoom buttons, the chart, the watchlist rows and the order ticket. |
| Arrow left / Arrow right | On the chart, moves the crosshair one candle and reads it out. The view follows the crosshair past either edge. |
| Shift + Arrow left / right | On the chart, moves the crosshair ten candles. |
| Home / End | On the chart, jumps to the first or the live candle. |
| + / - | On the chart, zooms in or out around the crosshair. |
| 0 | On the chart, resets the view to the range's default window. |
| Escape | On the chart, clears the crosshair. |
| Arrow up / Arrow down, Home / End | In the watchlist, moves between symbols. Enter or Space charts the focused symbol. |

### Accessibility

- The chart is a focusable image with a role description, a label naming the symbol, range and candle interval, and a description of its keys.
- Moving the crosshair with the keyboard announces the candle's time, open, high, low, close, change and volume through a polite live region.
- Watchlist rows are buttons with a full label (ticker, name, price and change today); the charted symbol carries aria-current.
- Direction is never color alone: changes carry a sign and an arrow, and order status is written as text.
- Order problems (too few shares, not enough buying power, not enough shares to sell) and failures are written in a status line under the button.
- Pointer focus draws no ring; keyboard focus shows Arc's shared focus ring. Keyboard position shows as a fill on rows, toggles and icon buttons, and as the crosshair on the chart.

### Motion

- The chart is one canvas drawn in a requestAnimationFrame loop that runs only while something moves; React never re-renders per frame.
- Zoom, pan and range changes ease the view and the price scale with an exponential approach timed from the smooth spring, so nothing overshoots and every gesture can be reversed mid-way.
- A drag flick carries momentum that decays like a thrown card. Pinch zooms around the midpoint of two fingers.
- Live ticks glide the last candle, its price tag, the price line and the moving averages to the new price; the header price rolls with the animated counter.
- Each watchlist price flashes a green or red tint in the direction it moved, as a single opacity fade. The selected row's fill glides between rows.
- The limit field opens with height and opacity together; new orders grow into the list. The live dot's pulse is the only loop, because it reports live status.
- Reduced motion makes the view, prices and panels change at once, drops momentum and the pulse, and holds the flash as a brief static tint.

### Responsive behavior

- From 1080px the watchlist and ticket stack in a 340px column beside the chart; from 720px they sit side by side under it; below that everything stacks.
- On narrow charts the OHLC readout moves above the canvas, the chart shortens to 340px, and the default window thins so candles stay at least five pixels apart.
- Below 640px the stats row spans four equal columns, the range control takes its own row, and every button in the toolbar grows to 44px.
- Touch drags pan the chart horizontally while vertical swipes still scroll the page; a tap pins the crosshair and a second tap clears it.

### Performance

- Candles, volume, averages and the crosshair draw on one canvas at up to 2x device pixel ratio, only for the visible candles.
- The readout, axis tags and crosshair labels are written straight into their text nodes by the engine, and only when their text changes.
- Series are generated once per symbol and range and then updated in place by ticks; moving averages are one running sum.
- Ticks pause while the tab is hidden, and theme or accent changes recolor the canvas without rebuilding it.

### Notes for AI agents

- Choose it for the main screen of a brokerage, a paper trading app or an internal markets dashboard where one symbol is charted and traded at a time.
- Everything is simulated: candles are generated from each symbol's price, previous close and volatility, ticks are a random walk, and orders fill against the live price locally. Pass the callbacks and your own data for real use.
- Today's session is identical on every range: coarser candles are folded from the five minute bars, and ticks update the live candle of every range together.
- Working limit orders fill on their own when the live price crosses them, and a marketable limit fills at the better of the limit and the market.
- Keep sample prices believable: the header, watchlist and ticket all read the same live price, so a mismatch shows immediately.

### Keywords

trading, stocks, market, candlestick, ohlc, volume, moving average, watchlist, order ticket, brokerage, paper trading, limit order, crosshair, zoom, pan, live prices, finance, terminal

### Related

- metric-explorer
- wallet-card

---

## Budget variance

Budget against actual operating spend by department as aligned bullet charts, with favorable and unfavorable variance, a month, quarter and year to date switch that springs every bar, in-place drill-down into budget lines, and a total row.

- Type: Block (composition)
- Access: Pro
- Built from: Segmented control, Avatar
- Documentation: https://uiarc.dev/components/blocks/budget-variance

### Overview

Render <BudgetVariance /> for the demo, or pass departments (lines with budget and actual keyed by period id), periods, defaultPeriod, defaultExpanded and ranges. Department figures and the total are summed from the lines, and onPeriodChange and onDepartmentToggle report changes.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/budget-variance. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/budget-variance while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- Monthly close and budget review screens that compare planned and actual operating spend by department or cost center.
- Finance dashboards where a controller needs to see at a glance which teams are over, which are under, and by how much.
- Any plan against actual comparison with a meaningful tolerance band, such as headcount cost or cloud spend by team.

### When not to use

- Use mrr-waterfall to explain how a single total moved from one value to another.
- Use usage-forecast to project spend against a cap over time.
- Use a line or bar chart to show a trend across many periods; this block compares one window at a time.
- Use a sortable data table when there are dozens of cost centers and sorting matters more than the visual comparison.

### Usage

```tsx
import { BudgetVariance } from "@/components/arc/blocks/budget-variance/budget-variance";

export function FinanceOverview({ departments }) {
  return (
    <BudgetVariance
      departments={departments}
      defaultPeriod="quarter"
      ranges={[0.9, 1.05]}
      onDepartmentToggle={(id, open) => open && prefetchLines(id)}
    />
  );
}
```

### API

#### BudgetVariance

Budget against actual spend by department as bullet charts on one shared scale, so every budget tick lines up down the table. Each row shows qualitative bands, the actual bar with the overspend drawn in the danger color past the tick, and variance as a signed amount and share colored by whether it is favorable. A month, quarter and year to date switch springs every bar and counts every number to the new window, a total row sums the table, and any department opens in place to show its budget lines.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `departments` | `BudgetDepartment[]` | `budgetDepartments` | Departments with an id, a name, an owner ({ name, avatar? }) and budget lines. Each line has an id, a name, and budget and actual amounts keyed by period id. Department figures and the total are summed from the lines. |
| `periods` | `BudgetPeriod[]` | `budgetPeriods` | Reporting windows for the switch, each with an id, a short label, a description shown under the title and a phrase for screen reader sentences ("in the third quarter"). |
| `defaultPeriod` | `string` |  | Id of the window shown first. Defaults to the first period. |
| `defaultExpanded` | `string \| null` | `"engineering"` | Id of the department open on first render. Pass null to start with every department closed. |
| `ranges` | `[number, number]` | `[0.9, 1.1]` | Qualitative band edges as shares of budget. Spend between them is within tolerance; the bands step darker past the upper edge. |
| `onPlanThreshold` | `number` | `0.005` | Variance smaller than this share of budget reads as on plan and stays neutral. |
| `currency` | `string` | `"$"` | Symbol placed before every amount. Amounts shorten to k and M. |
| `title` | `string` | `"Budget vs actual"` | Heading of the block. |
| `description` | `string` |  | Replaces the period description under the title. |
| `onPeriodChange` | `(periodId: string) => void` |  | Called when the reporting window changes. |
| `onDepartmentToggle` | `(departmentId: string, open: boolean) => void` |  | Called when a department opens or closes. Opening one closes the one that was open, which is reported first. |
| `className` | `string` |  | Class on the root element. |

### Dependencies

- `motion`
- `lucide-react`

### Keyboard

| Keys | Action |
| --- | --- |
| Tab | Moves to the period switch, then into the department list, then out of the block. |
| Arrow left / Arrow right | On the period switch, changes the reporting window. |
| Arrow up / Arrow down | In the department list, moves to the previous or next department. |
| Home / End | In the department list, jumps to the first or last department. |
| Enter / Space | Opens or closes the budget lines of the department in focus. |

### Accessibility

- Each department is a heading with a disclosure button (aria-expanded, aria-controls) whose name is a full sentence: spent, budget, variance and whether it is favorable.
- The total and every budget line carry the same sentence in visually hidden text; the charts and the counting numbers are hidden from assistive technology so nothing is read twice or mid-count.
- Changing the window announces the new window and the total through a polite live region.
- Variance never relies on color: amounts carry a sign and every share ends in over, under or on plan.
- Pointer focus draws no ring; keyboard focus shows Arc's shared focus ring. The focused department shows a filled row.

### Motion

- Switching the window springs every bar to its new length on one critically damped spring and counts every amount and share to the new value, all written to the DOM from motion values.
- The overspend is the same bar clipped to the space past budget, so the danger color appears exactly as the bar crosses the tick, with no second animation to keep in sync.
- Opening a department grows its lines in height and opacity together without overshoot; closing is faster. The chevron turns on the shared spring curve.
- Every animation is interruptible: a new window or toggle starts from wherever the bars and numbers are.
- Reduced motion jumps bars and numbers to their final values and opens lines at full height.

### Responsive behavior

- From a 760px container the block is a table: name and owner, the bullet chart, actual, budget, variance and the disclosure chevron in aligned columns.
- Below that each row puts the name, its actual of budget and the variance on top and the bullet chart across the full width below, so the chart never gets squeezed.
- Long names wrap instead of truncating. The period switch fills the width on phones.
- Rows are at least 60px tall and the switch grows to 44px on touch screens.

### Performance

- Bars animate transform only (scaleX from the left edge); bands and ticks are static percentage positions, so a window change never measures layout.
- Numbers count on motion values that write text content directly, so a window change renders React once, not once per frame.
- Department and total figures are memoized per window; the shared scale is computed once per data set.

### Notes for AI agents

- Choose it for cost centers where spending under budget is favorable. Every department and line is read as an expense.
- Pass one amount per period id for both budget and actual on every line; departments and the total are summed, so they always reconcile.
- The scale is shared by every row and every period (at least 120 percent of budget, rounded up to fit the largest line), so the budget tick never moves when the window changes.
- Bands mix the text color and the overspend uses the danger token, so the block stays neutral in any accent. The accent marks only the open department's chevron and the selected window.
- The first render formats every number from props, so server and client match.

### Keywords

budget, budget vs actual, variance, bullet chart, finance, fp&a, operating expenses, opex, cost center, department spend, favorable, unfavorable, plan vs actual, month close

### Related

- mrr-waterfall
- usage-forecast
- revenue-explorer
- metrics-dashboard

---

## Choropleth explorer

A filled-region map that shades every state or region by revenue, growth or penetration on a stepped scale, with a country switch (United States, Canada, Brazil, United Kingdom, France, Germany, Italy, Australia), a hoverable legend, a synced ranked list and a camera zoom into local detail.

- Type: Block (composition)
- Access: Pro
- Built from: Segmented control
- Documentation: https://uiarc.dev/components/blocks/choropleth-explorer

### Overview

Render <ChoroplethExplorer /> for the demo, or pass your own regions (SVG paths, values per metric, optional subregions) and metrics. Listen to onRegionOpen and onMetricChange to sync the zoomed region or metric with the URL.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/choropleth-explorer. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/choropleth-explorer while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- Sales, revenue or usage dashboards that break a metric down by state, country or territory.
- Market coverage and penetration reviews where a region's own subareas explain its number.
- Any analytics view where readers compare neighbouring areas and need the ranked numbers beside the map.

### When not to use

- Use offices-map to place pins at specific locations such as offices or stores.
- Use revenue-globe for flows and totals on a spinning globe when geography is ambience rather than the comparison.
- Use a bar chart or sortable table when the regions are few, or when area size would mislead (a large, sparse region draws more attention than a small, dense one).

### Usage

```tsx
import { ChoroplethExplorer } from "@/components/arc/blocks/choropleth-explorer/choropleth-explorer";

export function SalesByRegion() {
  return (
    <ChoroplethExplorer
      defaultMetric="growth"
      onRegionOpen={id => router.replace(id ? `?state=${id}` : "?")}
    />
  );
}
```

### API

#### ChoroplethExplorer

A filled-region map that shades every state by a metric on a stepped sequential or diverging scale. A metric switch sweeps the new fills across the map from west to east, the legend steps light every region in their bin, a ranked list stays in sync with the map both ways, and selecting a state zooms the camera into it and shades its counties.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `maps` | `ChoroplethMap[]` | `choroplethMaps` | Areas to switch between, such as countries: an id, a name, its regions, a plural region noun, an optional title, metrics (for a local currency) and view box. A country switch appears when there is more than one. Ignored when regions is set. |
| `defaultMap` | `string` |  | Id of the area shown first. Defaults to the first one. |
| `onMapChange` | `(id: string) => void` |  | Called after the area changes. |
| `regions` | `ChoroplethRegion[]` |  | Top level regions of a single area: an id, a name, SVG path data in view box units, an optional bounding box, one value per metric id (null for no data) and optional subregions with their own paths and values. |
| `metrics` | `ChoroplethMetric[]` | `choroplethMetrics` | Metrics in the switch. Each has a label, a headline label, a format ("currency", "change" or "percent"), a scale ("sequential" or "diverging") and how the headline aggregates ("sum", or "weighted" by the first metric). |
| `defaultMetric` | `string` |  | Id of the metric shown first. Defaults to the first metric. |
| `viewBox` | `[number, number]` | `[975, 610]` | Width and height of the view box the region paths are drawn in. |
| `areaName` | `string` | `"United States"` | Name of the whole area, shown above the map before zooming in. |
| `regionNoun` | `string` | `"states"` | Plural noun for top level regions, used in the list heading, legend and announcements. |
| `title` | `string` | `"Revenue by state"` | Heading of the block. |
| `description` | `string` | `choroplethCaption` | Line under the title. Pass an empty string to hide it. |
| `onRegionOpen` | `(id: string \| null) => void` |  | Called after the map zooms into a region, with its id, or with null when it zooms back out. |
| `onMetricChange` | `(id: string) => void` |  | Called after the metric changes. |
| `className` | `string` |  | Class on the root element. |

### Dependencies

- `motion`
- `lucide-react`

### Keyboard

| Keys | Action |
| --- | --- |
| Tab | Moves to the metric switch, the back button when zoomed in, the legend steps and the ranked list. |
| Arrow up / Arrow down | In the ranked list, moves between regions and outlines the focused one on the map. |
| Home / End | In the ranked list, jumps to the first or last region. |
| Enter / Space | On a state, zooms into it and lists its counties. On a county, pins it on the map. On a legend step, keeps its regions lit until pressed again. |
| Escape | Releases a pinned legend step, then zooms back out to every state. |

### Accessibility

- The map is an image with a label naming the area and the metric; the ranked list next to it is the accessible path to every value and every zoom.
- The list is one tab stop with roving focus. Each row names its rank, region, value and whether it opens counties.
- Zooming, zooming out, switching the metric and pinning a county are announced through one polite live region, including the highest region for the new metric.
- Legend steps are toggle buttons with aria-pressed and a label that counts their regions and states their range. Values carry a sign and a true minus, so direction never depends on color alone.
- Pointer focus draws no ring; keyboard focus shows Arc's shared focus ring. Keyboard position shows as a filled row and an outline on the map.

### Motion

- Switching the metric fades each region to its new fill with a delay set by its position, so the change sweeps across the map from west to east in under 800ms.
- Selecting a state moves one camera on a critically damped spring: translate and scale travel together, so the state glides to the center in a straight line and can be reversed mid-flight. Counties fade in while the camera is still arriving; other states recede to context.
- The headline total counts to each new value on a motion value, list rows glide to their new rank with a layout spring, and rank bars resize on a transform.
- The tooltip follows the pointer on motion values without React renders; the hovered row scrolls into view inside the list, never the page.
- Reduced motion makes every fill, zoom, count and reorder instant.

### Responsive behavior

- From an 820px container the map and the ranked list sit side by side and the list matches the map column's height; below that the list stacks under the map and scrolls inside a fixed height.
- The metric switch takes the full width on phones; the legend wraps its no data step below the ramp.
- Rows are 44px tall, and switches, legend steps and the back button grow to 44px on touch. Tapping a state zooms in directly; tooltips are limited to fine pointers.
- Nothing scrolls sideways: the map scales with its container through the view box.

### Performance

- About 51 state paths plus the counties of one state at a time, with one delegated pointer listener for the whole map.
- The camera writes a single transform attribute from three motion values, and strokes use non-scaling-stroke so the zoom never re-rasterises line widths in JavaScript.
- Fills change through CSS transitions of fill and fill-opacity; ranking and binning are memoized per metric and level.
- The sample data file is about 85KB of simplified path data; supply your own paths at the precision your map needs.

### Notes for AI agents

- Choose it when the question is how a metric is distributed across areas that people recognise by shape, and when a region's subareas are worth a closer look.
- Bins are recomputed for whatever is in view: quantile breaks rounded to two significant digits, split at zero with a second hue on diverging metrics. Pass raw values and let the block choose the steps.
- Paths are straight segment SVG data. Top level regions share one view box; subregions use a local grid placed with origin [x, y, unit], which keeps small states sharp when zoomed. The sample data is simplified US Census cartographic boundaries in Albers USA.
- Only ten states carry county data in the sample; the others zoom in and explain there is no county detail, which is also how the block handles a region without subregions.
- The positive side uses the first chart series color and the negative side the third, both theme tokens. No data renders as a flat neutral with its own legend step.

### Keywords

choropleth, map, filled map, heat map, geography, states, counties, regions, drilldown, zoom, sales territories, penetration, legend, analytics

### Related

- revenue-globe
- revenue-explorer
- kpi-drilldown
- metric-explorer

---

## Small multiples

A trellis of small line charts that reads as one chart, with a synced crosshair, a shared or independent y scale that springs the axes, sorting with a FLIP reorder, a ghost of the overall total behind every panel and dimming for flat trends.

- Type: Block (composition)
- Access: Pro
- Built from: Segmented control, Switch
- Documentation: https://uiarc.dev/components/blocks/small-multiples

### Overview

Render <SmallMultiples /> for the regional revenue demo, or pass series (id, name, values) and periods (short, long) with formatValue and formatTick for your own unit. Use defaultSort, defaultScale, defaultDimFlat, flatThreshold and growthLag to set the opening view, and onIndexChange to follow the crosshair.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/small-multiples. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/small-multiples while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- Comparing revenue, signups or usage across regions, products, plans or channels over the same months.
- Showing which segments grow, shrink or stall at a glance, with one shared crosshair to read every value for the same period.
- Dashboards where one multi-line chart would be a tangle of overlapping series.

### When not to use

- Use line-chart when two or three series need to be read against each other on one plot.
- Use metric-explorer or kpi-drilldown when a person picks one metric and drills into its detail.
- Use sparkline inside a table row when each series is a small supporting detail beside other columns.
- Use a plain table when the exact values matter more than the shape of each trend.

### Usage

```tsx
import { SmallMultiples } from "@/components/arc/blocks/small-multiples/small-multiples";

export function SignupsByPlan() {
  return (
    <SmallMultiples
      title="Signups by plan"
      description="Weekly signups, last 26 weeks"
      series={plans.map(plan => ({ id: plan.id, name: plan.name, values: plan.weekly }))}
      periods={weeks.map(week => ({ short: week.short, long: week.long }))}
      growthLag={4}
      formatValue={value => value.toLocaleString("en-US")}
      formatTick={value => value.toLocaleString("en-US")}
      defaultScale="shared"
    />
  );
}
```

### API

#### SmallMultiples

A trellis of small line charts, one per region or product, that reads as one chart. A synced crosshair shows every panel's value at the same period, a shared or independent y scale springs the axes and lines between comparing size and comparing shape, panels sort by latest value, growth or name with a FLIP reorder, a dashed ghost of the overall total sits behind every panel for context, and flat trends can be dimmed.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `series` | `SmallMultiplesSeries[]` | `smallMultiplesSeries` | One panel per series: a stable id, a name for the panel heading and one value per period. |
| `periods` | `SmallMultiplesPeriod[]` | `smallMultiplesPeriods` | Periods on the shared x axis, oldest first, each with a short label ("Sep 2025") and a long label ("September 2025") for the readout and screen readers. |
| `title` | `string` | `"Revenue by region"` | Heading of the block. |
| `description` | `string` | `smallMultiplesDescription` | Line under the title. Pass an empty string to hide it. |
| `defaultSort` | `"latest" \| "growth" \| "name"` | `"latest"` | Opening panel order. |
| `defaultScale` | `"independent" \| "shared"` | `"independent"` | Opening y scale. Independent fits each series to its own range so panels compare shape; shared starts every panel at zero on one range so panels compare size. |
| `defaultDimFlat` | `boolean` | `true` | Whether panels with a flat trend start dimmed. |
| `flatThreshold` | `number` | `0.05` | Growth below this absolute share counts as flat (0.05 is 5 percent). |
| `growthLag` | `number` | `12` | Periods between the latest value and the value growth is measured against. 12 compares monthly data with the same month last year. |
| `formatValue` | `(value: number) => string` |  | Formats values for panel headings, the readout and screen readers. The default reads values as thousands of US dollars ($412k, $1.71M). |
| `formatTick` | `(value: number) => string` |  | Formats compact axis ticks in the right gutter of each panel. |
| `onSortChange` | `(sort: SmallMultiplesSort) => void` |  | Called after the panel order changes. |
| `onScaleChange` | `(scale: SmallMultiplesScale) => void` |  | Called after the y scale switches between independent and shared. |
| `onIndexChange` | `(index: number \| null) => void` |  | Called when the synced crosshair moves to a period, or with null when it leaves the panels. |
| `className` | `string` |  | Class on the root element. |

### Dependencies

- `motion`
- `lucide-react`

### Keyboard

| Keys | Action |
| --- | --- |
| Tab | Moves to the sort control, the scale control, the dim switch and then the panels. |
| Left / Right arrow | On the panels, moves the synced crosshair one period in every panel at once. Focusing the panels with the keyboard places it on the latest period. |
| Page up / Page down | On the panels, moves the crosshair twelve periods. |
| Home / End | On the panels, jumps to the first or latest period. |
| Escape | On the panels, clears the crosshair and shows the latest values again. |
| Arrow keys | In the sort and scale controls, choose the next or previous option. |

### Accessibility

- The panels are one focusable group with a keyboard hint, so the whole trellis is a single tab stop instead of eight.
- Moving the crosshair by keyboard announces the period, the total and the highest series through one polite live region; sorting, scaling and dimming announce what changed.
- A visually hidden table lists every series with its value at the current period, its growth and its trend in words, in the current sort order.
- Trend direction is carried by an arrow icon and a signed percentage with a true minus sign, and flat trends are labelled Flat, so dimming never relies on opacity alone.
- Pointer focus draws no ring; keyboard focus shows Arc's shared focus ring. Keyboard position shows as the crosshair and the filled selection in the controls.

### Motion

- Switching the y scale springs each panel's domain on one critically damped spring. The line, the area, the end dot and the axis ticks all derive from the same two motion values, so the axes slide and the line reshapes as one movement; ticks for the other scale fade in as they arrive.
- Sorting moves every panel to its new slot with a FLIP layout animation on a no-overshoot spring, and the hairline dividers travel with the panels.
- The crosshair appears in place, then glides between periods on a short spring written straight to motion values; the dot in each panel rides its line between points.
- Dimming flat trends fades the panel content only, so the grid dividers stay crisp.
- Reduced motion makes the rescale, the reorder and the crosshair instant.

### Responsive behavior

- Four columns from a 640px container, two below it, with plot heights of 104px, 92px and 76px as the container narrows.
- On phones the controls wrap to full rows, the panel value moves under the name, and the tick gutter narrows.
- Hovering a panel drives the crosshair on fine pointers; on touch, a tap or horizontal drag on a chart places it while vertical swipes still scroll the page.
- Controls grow to 44px on coarse pointers.

### Performance

- Paths are SVG in a fixed viewBox stretched to the panel, with non-scaling strokes, so resizing never recomputes geometry.
- During a rescale, paths and ticks are rebuilt from motion values each frame without React renders; the crosshair moves by transforms of full-size layers.
- React renders only when the crosshair crosses into a new period, and the FLIP layout measurement runs only when the order changes.

### Notes for AI agents

- Choose it when the question is how several series of the same measure compare over one period, and every panel should be read at once rather than opened.
- Pass series with the same number of values as periods. Four to twelve panels work best; the grid is two columns on phones and four from a 640px container.
- The default formatters read values as thousands of US dollars; pass formatValue and formatTick for any other unit.
- The ghost line is the sum of all series drawn in its own scale, so it shows the overall shape, not a size to compare against.
- The line uses the first chart series color, which follows the accent; keep one color so the panels read as one chart.

### Keywords

small multiples, trellis, facet, sparklines, line chart grid, synced crosshair, shared scale, independent scale, compare regions, compare products, trend, analytics, dashboard

### Related

- metric-explorer
- kpi-drilldown
- revenue-explorer
- line-chart
- sparkline

---

## Connected scatter

A connected scatterplot of monthly CAC against LTV where the path draws itself in, a scrubber moves a head along the curve, and a channel switch morphs the path against a shaded 3x target line.

- Type: Block (composition)
- Access: Pro
- Built from: Segmented control, Button
- Documentation: https://uiarc.dev/components/blocks/connected-scatter

### Overview

Render <ConnectedScatter /> for the demo, or pass series (same number of points in each, in time order), xAxis, yAxis, targetRatio and formatValue for your own two metrics. Listen to onMonthChange to sync the month the head settles on.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/connected-scatter. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/connected-scatter while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- A growth or finance screen that shows whether unit economics are moving toward or away from a target ratio.
- Comparing how a few segments or channels travelled through the same two metrics over the same months.
- A report where specific months (a pricing change, a campaign) explain a turn and deserve a label on the path.

### When not to use

- Use line-chart or metric-explorer when time itself is the axis and one metric is enough.
- Use efficient-frontier for risk against return of a portfolio you can change.
- Use a plain scatter or beeswarm when points have no time order to connect.

### Usage

```tsx
import { ConnectedScatter } from "@/components/arc/blocks/connected-scatter/connected-scatter";

export function UnitEconomics() {
  return (
    <ConnectedScatter
      defaultSeries="partners"
      onMonthChange={index => setSelectedMonth(index)}
    />
  );
}
```

### API

#### ConnectedScatter

A connected scatterplot of two metrics over time. Each month is a point, joined in time order by a smooth path with small direction arrows. The path draws itself in once, a head marks the selected month and a time scrubber moves it along the path, a channel switch morphs the path point by point to another series, and a dashed target line (LTV = 3x CAC) splits the plot with the healthy side lightly shaded. Hovering a point shows its date and both values.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `series` | `ScatterSeries[]` | `SERIES` | Series to switch between: id, name, points in time order ({ label, x, y }) and optional notes ({ index, text, side }) that label key months. Every series needs the same number of points so the path can morph. |
| `defaultSeries` | `string` |  | Id of the series shown first. Defaults to the first series. |
| `xAxis` | `ScatterAxis` | `X_AXIS` | Horizontal axis: short name for the readout, title printed on the axis, min, max and gridline step. The sample is CAC from $200 to $1,800. |
| `yAxis` | `ScatterAxis` | `Y_AXIS` | Vertical axis, same shape. The sample is 12 month LTV from $2,000 to $6,000. |
| `targetRatio` | `number` | `3` | Slope of the reference line y = targetRatio times x. The region above it is shaded as healthy and the readout says whether the selected month is above or below it. |
| `formatValue` | `(value: number) => string` | `whole US dollars` | Formats values in the readout, the tooltip, the axis ticks and the screen reader table. |
| `title` | `string` | `"CAC and LTV by channel"` | Block heading. |
| `description` | `string` |  | One line under the heading. Defaults to a sentence naming the metrics and the date range. |
| `onMonthChange` | `(index: number) => void` |  | Called with the month index whenever the head settles on a month: a released scrub, a key press, a tap on a point, or the end of playback. Not called on every frame. |
| `className` | `string` |  | Class on the root element. |

### Dependencies

- `motion`
- `lucide-react`

### Keyboard

| Keys | Action |
| --- | --- |
| Tab | Moves through the channel switch, the play button and the month scrubber. |
| Arrow left / Arrow right | On the scrubber, moves the head one month back or forward along the path. |
| Page up / Page down | On the scrubber, moves three months at a time. |
| Home / End | On the scrubber, jumps to the first or last month. |
| Arrow keys in the channel switch | Switch channel; the path morphs to the new series. |
| Enter / Space on the play button | Plays through the months from the head, pauses, or replays from the first month at the end. |

### Accessibility

- The scrubber is role="slider" over the months, with a value text that reads the date, both values, the ratio and whether it is above or below the target.
- A polite live region announces the month when the head settles and the new values when the channel changes. Playback announces only where it stops.
- The readout is a description list, so the selected month, both values and the ratio are always available as text.
- The chart drawing is hidden from assistive technology; a visually hidden table lists every month with both values and the ratio for the current channel.
- Above or below target is written out beside a status dot, never shown by color alone.
- Pointer focus draws no ring; keyboard focus shows Arc's shared focus ring. The focused scrubber fills and enlarges its thumb.

### Motion

- The first time the block scrolls into view, the head travels every month and the path draws in behind it; the dotted future path, arrows and labels fade in once it lands.
- Scrubbing moves the head along the real curve, not a straight line between months. A press glides the head to the pointer once, then it follows one to one, and a release settles on the nearest month with the smooth spring, which never overshoots.
- Switching channel morphs every point, arrow and the path itself on the smooth spring; the readout numbers count through the in between values and month labels crossfade.
- Every moving part (path, trail length, head, guides, dots, arrows, scrubber thumb and readout values) is a motion value written once per frame, so none of it re-renders React.
- Reduced motion shows the finished path at once, jumps the head to each month, steps playback month by month and swaps channels without a morph.

### Responsive behavior

- The block reflows against its own width with container queries: four readout cells in a row from 720px, two by two below it.
- The chart draws in real pixels at every size, so text and strokes never stretch; the plot is 380px tall on wide layouts, 330px at tablet widths and 300px on phones.
- Below 480px of plot width the notes, the target line label and the zone label hide (the key names both), x ticks thin to every other gridline, and edge labels flip inward.
- The scrubber is 44px tall for touch and the play button is a full size control. On phones the play button sits above the scrubber, and quarter labels under the scrubber hide below 560px.
- Tapping a point on a touch screen shows its values and moves the head there.

### Performance

- The path is traced as Catmull-Rom Béziers and sampled once per resize or per morph frame (24 samples per month), so moving the head is a lookup, not a curve solve.
- Only month changes, hover changes and the play state re-render React; every frame writes motion values directly.
- Comfortable up to a few dozen points per series; beyond that, thin the direction arrows or aggregate to quarters.

### Notes for AI agents

- Choose it when the story is how two metrics moved together over time, such as CAC against LTV, price against volume, or spend against conversions.
- The sample data is monthly CAC and 12 month LTV for three acquisition channels, January 2025 to June 2026. Replace SERIES, X_AXIS and Y_AXIS with your own; keep the same number of points in every series.
- Use notes sparingly (one or two per series) for events that explain a turn in the path; the first and last month are labelled automatically and narrow plots hide the notes.
- The target line always passes through the origin, so it suits ratio targets. Set min on both axes to zoom into where the data lives; the shaded region is clipped to the plot.
- The first render is server safe: it draws at a default size with the head on the first month, then measures and animates on the client.

### Keywords

connected scatter, connected scatterplot, scatter plot, cac, ltv, ltv to cac, unit economics, time series, trajectory, path chart, scrubber, morph, growth, acquisition channels, price volume

### Related

- metric-explorer
- segmented-control
- line-chart

---

## Horizon chart

A horizon chart that stacks fourteen daily series as compact folded rows, with a synced crosshair, a sort by name, peak or latest, a band count setting that folds every row on one spring, and a legend that explains how to read the bands.

- Type: Block (composition)
- Access: Pro
- Built from: Segmented control
- Documentation: https://uiarc.dev/components/blocks/horizon-chart

### Overview

Render <HorizonChart /> for the demo, or pass series (signed values against a baseline, one per day), days and ticks, plus baselineLabel for the legend. defaultSort, defaultBands and extent set the opening view; onSortChange, onBandsChange and onDayChange report changes.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/horizon-chart. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/horizon-chart while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- Operations or growth dashboards comparing many markets, services or products against their own baseline over weeks or months.
- Monitoring views where the reader scans for which rows broke from normal and when, then reads exact values on one day.
- Any time series comparison where small multiples of line charts would need too much height.

### When not to use

- Use small-multiples when there are only a few series and the reader needs axes and exact levels in each panel.
- Use ridgeline to compare distributions rather than values over time.
- Use streamgraph to show how parts add up to a total over time.
- Use line-chart for one to four series that should be read precisely against a y axis.

### Usage

```tsx
import { HorizonChart } from "@/components/arc/blocks/horizon-chart/horizon-chart";

export function MarketHealth({ markets, days }) {
  return (
    <HorizonChart
      title="Sessions against baseline"
      series={markets}
      days={days}
      baselineLabel="spring average"
      defaultBands={3}
      onDayChange={index => setInspectedDay(index)}
    />
  );
}
```

### API

#### HorizonChart

A horizon chart that stacks many daily series as compact rows. Each row folds its curve into bands of rising intensity, one hue above the baseline and one below, so a dozen series fit in the height of two line charts. A synced crosshair reads every row on the same day, rows sort by name, peak swing or latest value on one spring, a band count setting folds and unfolds every row together, and a legend explains how to read the bands.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `series` | `HorizonSeries[]` | `horizonSeries` | One row per series: an id, a name and one value per day as a signed distance from its baseline (12 means 12% above, -8 means 8% below). |
| `days` | `HorizonDay[]` | `horizonDays` | Days on the shared x axis, oldest first, each with a short label and a long label for the readout and screen readers. |
| `ticks` | `{ index: number; label: string }[]` | `horizonMonthTicks` | Labels on the x axis, each placed at a day index. |
| `title` | `string` | `"Sessions against baseline"` | Heading of the block. |
| `description` | `string` | `horizonDescription` | Line under the title. Pass an empty string to hide it. |
| `baselineLabel` | `string` | `"spring average"` | What the values are measured against, used in the legend caption and for screen readers. |
| `defaultSort` | `"name" \| "peak" \| "latest"` | `"peak"` | Opening row order. Peak sorts by the largest swing from baseline in either direction, latest by the value on the last day. |
| `defaultBands` | `1 \| 2 \| 3 \| 4` | `3` | Opening number of bands each row folds into. One band draws a plain area chart. |
| `extent` | `number` |  | Distance from the baseline that fills every band; larger values stay in the strongest band. Defaults to the largest value rounded up to a multiple of 12, so every band count has a round step. |
| `formatValue` | `(value: number) => string` | `signed whole percent` | Formats a value for the rows, the legend and screen readers. The default uses a true minus sign. |
| `onSortChange` | `(sort: HorizonSort) => void` |  | Called after the row order changes. |
| `onBandsChange` | `(bands: 1 \| 2 \| 3 \| 4) => void` |  | Called after the band count changes. |
| `onDayChange` | `(index: number \| null) => void` |  | Called when the synced crosshair moves to a day, or with null when it clears. |
| `className` | `string` |  | Class on the root element. |

### Dependencies

- `motion`

### Keyboard

| Keys | Action |
| --- | --- |
| Tab | Moves to the sort switch, the band count switch and the chart. |
| Arrow keys | On a switch, moves the selection. On the chart, moves the crosshair one day left or right. |
| Shift + Arrow left / right | On the chart, moves the crosshair one week. |
| Home / End | On the chart, jumps to the first or last day. |
| Escape | On the chart, clears the crosshair and shows the latest day again. |

### Accessibility

- The chart is a focusable group with a keyboard hint; focusing it places the crosshair on the latest day.
- A visually hidden table lists every row with its latest value, its highest and its lowest value with their dates, in the current order.
- Moving the crosshair by keyboard announces the day with the highest and lowest row through one polite live region; sort and band changes are announced there too.
- Values carry a sign and the legend names both sides (below and above), so direction never depends on color alone. The color scale is an image with a full text label.
- Pointer focus draws no ring; keyboard focus shows Arc's shared focus ring. Keyboard position shows as the crosshair, the readout and the selected fills of the switches.

### Motion

- Changing the band count animates one motion value that drives two custom properties on the root, so every layer in every row folds or unfolds together on a no-overshoot spring, on transform and opacity alone.
- Sorting moves each row to its new place with a layout spring that never overshoots.
- The crosshair is a full-width track translated by a share of its own width, following the pointer on a short critically damped spring; it appears in place instead of sliding in from its last day.
- Row values and the date are written straight to the DOM while scrubbing, so the pointer never renders React.
- Reduced motion makes the fold, the reorder and the crosshair instant.

### Responsive behavior

- Rows share one plot column, so the crosshair spans every row at any width.
- Below a 560px container the name and value columns narrow, text steps down to the small size and the switches wrap under the title at full width.
- Switches grow to 44px on touch. Tapping or dragging across the chart sets the crosshair and keeps it after the finger lifts; vertical scrolling is never captured.
- The legend moves under the readout on narrow screens and keeps its fixed scale so band changes never shift the layout.

### Performance

- Each row draws its above and below areas once as paths in a unit box; the bands are CSS transforms of those paths, so changing the band count never rebuilds geometry.
- Scrubbing writes the date and one text node per row without React renders; hit testing uses one rectangle over the plot column.
- Comfortable up to about 40 rows of a few hundred days; beyond that, aggregate days into weeks.

### Notes for AI agents

- Choose it for 8 to 30 series on one time axis where each value is a deviation from a baseline: sessions against a seasonal average, latency against a target, demand against a forecast, returns against a benchmark.
- Pass signed values against the baseline, not raw levels. Convert levels first (value / baseline - 1) so rows of different sizes compare on one scale.
- The above side uses the first chart series color and the below side the third, both theme tokens that follow the accent; keep them if you restyle.
- Every row always renders four layers per side; a layer above the band count covers values past the extent and stays empty, which is what lets the band count animate continuously.

### Keywords

horizon chart, horizon graph, time series, many series, deviation, baseline, anomaly, monitoring, compact chart, bands, crosshair, analytics

### Related

- small-multiples
- ridgeline
- streamgraph
- activity-heatmap

---

## Line replay

A time replay line chart that draws a day of traffic with a moving playhead, a value label on the tip, a scrubber, speed control and key moments annotated as the playhead passes them.

- Type: Block (composition)
- Access: Pro
- Built from: Button, Segmented control
- Documentation: https://uiarc.dev/components/blocks/line-replay

### Overview

Render <LineReplay /> for the launch day demo, or pass data (points with time in minutes, value and optional baseline) and moments on the same clock. Use onMomentReached to react as playback passes each moment, and defaultPosition, duration and defaultSpeed to tune how it opens and plays.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/line-replay. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/line-replay while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- Post-launch or campaign reviews where the team wants to watch traffic respond to each announcement.
- Incident retrospectives that step through a metric with the alert, the deploy and the recovery marked.
- Storytelling pages and reports where a single series over one session or day is best understood in sequence.

### When not to use

- Use annotated-trend when people need to add and edit their own notes on a static trend.
- Use connected-scatter to replay how two measures moved together over time.
- Use metric-explorer or a line chart to compare several series or ranges at a glance without playback.

### Usage

```tsx
import { LineReplay, type ReplayMoment, type ReplayPoint } from "@/components/arc/blocks/line-replay/line-replay";

export function IncidentReplay({ points, moments }: { points: ReplayPoint[]; moments: ReplayMoment[] }) {
  return (
    <LineReplay
      title="Checkout errors, 14 May"
      description="Failed payments per minute across the incident window, UTC."
      data={points}
      moments={moments}
      seriesLabel="14 May"
      baselineLabel="Previous Tuesday"
      valueLabel="Errors"
      duration={20}
      onMomentReached={moment => analytics.track("replay_moment", { id: moment.id })}
    />
  );
}
```

### API

#### LineReplay

A time replay line chart. Press play and the line draws through the day with a playhead, a value label riding the tip and a clock on the time axis. Key moments are annotated as the playhead passes them: a marker settles onto the line, a callout rises in a lane above the plot, and the matching row in the moments list lights up and reveals its effect once that window has played. A scrubber with moment ticks, a speed control and a live readout (time, value, ratio to a comparison line and the peak so far) sit around the chart.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `data` | `ReplayPoint[]` | `POINTS` | Points in time order: `time` in minutes from the start, the replayed `value`, and an optional `baseline` drawn in full as a quiet dashed comparison. Leave `baseline` out of every point to hide the comparison, its legend entry and the ratio readout. |
| `moments` | `ReplayMoment[]` | `MOMENTS` | Key moments on the same clock: `id`, `time`, `title`, an optional one-line `detail` and a `kind` (launch, press, email, incident or milestone) that picks the icon. Incidents are drawn in the warning color and their effect is the dip over 20 minutes; every other moment reports the rise over the next hour. |
| `title` | `string` | `"Launch day"` | Heading of the block. |
| `description` | `string` | `"People on site every five minutes on Tuesday 8 September 2026, Pacific time."` | One line under the heading that names what is measured and when. |
| `seriesLabel` | `string` | `"Launch day"` | Legend name of the replayed line. |
| `baselineLabel` | `string` | `"Typical Tuesday"` | Legend name of the comparison line, also used in the ratio readout ("Versus typical Tuesday"). |
| `valueLabel` | `string` | `"On site"` | Label of the value under the playhead, in the readout and the scrubber's value text. |
| `formatTime` | `(minutes: number) => string` | `formatClock` | Formats a time on the replay clock for the readout, the playhead clock, callouts and the moments list. The default prints 9:40 am. |
| `formatTick` | `(minutes: number) => string` | `formatHour` | Formats the time axis labels. The default prints 6 am. |
| `formatValue` | `(value: number) => string` | `formatCount` | Formats values in the readout, the tip label and moment effects. |
| `duration` | `number` | `16` | Seconds a full replay takes at 1×. |
| `defaultSpeed` | `0.5 \| 1 \| 2 \| 4` | `1` | Starting playback speed. |
| `defaultPosition` | `"start" \| "end"` | `"end"` | Where the playhead rests before the first play. "end" shows the whole line with every moment; pressing Replay rewinds and plays from the start. |
| `autoPlay` | `boolean` | `false` | Plays from the start the first time the block is 40% in view. Ignored with reduced motion. |
| `onMomentReached` | `(moment: ReplayMoment) => void` |  | Called when playback passes a moment (not when scrubbing or jumping). |
| `className` | `string` |  | Class on the root element. |

### Dependencies

- `motion`
- `lucide-react`

### Keyboard

| Keys | Action |
| --- | --- |
| Tab | Moves through the play button, the scrubber, the speed control and each key moment. |
| Space / Enter / K | On the scrubber, plays or pauses the replay. At the end it replays from the start. |
| Arrow left / Arrow right | On the scrubber, steps one point (five minutes in the sample). Hold Shift to step an hour. |
| Page up / Page down | On the scrubber, steps an hour. |
| Home / End | On the scrubber, jumps to the start or the end. |
| Arrow keys | On the speed control, moves between 0.5×, 1×, 2× and 4×. |
| Enter / Space | On a key moment, moves the playhead to it; playback continues from there if it was playing. |

### Accessibility

- The scrubber is a role="slider" measured in minutes; its value text reads the time and the value ("9:40 am, 2,316 on site") and is updated whenever playback is paused, so a screen reader is not flooded while it plays.
- The readout above the chart repeats the time, the value, the ratio to the comparison and the peak so far as text, so nothing is available only as a line position. The drawing itself is hidden from assistive technology.
- Passing a moment during playback, pausing, jumping and finishing are announced through a polite live region ("9:40 am. Hacker News front page.", "Replay finished. Peak 6,041 at 10:25 am.").
- Key moments are an ordered list of buttons; the latest reached one has aria-current. A moment's effect line stays hidden from screen readers until the replay has played through it.
- The play button has a specific name for each state: Play replay, Pause replay, Replay from the start.
- Incidents carry a warning icon and their own title, never color alone. Pointer focus draws no ring; keyboard focus shows Arc's shared focus ring. The scrubber and the moment rows show keyboard position with a fill.

### Motion

- Playback advances a single motion value from requestAnimationFrame; each frame writes the line and area paths, the playhead, the tip label, the axis clock, the scrubber and the readout straight to the DOM. React renders only when a moment is passed, playback starts or stops, or the size changes.
- Replay and jumping to a moment glide the playhead with the smooth spring, which never overshoots, so the line retracts or extends to the target and a new jump mid-way picks up from where it is.
- Passing a moment settles its marker onto the line (opacity and scale), fades in its stem, and rises its callout into the lane above the plot on the smooth spring; the previous callout fades out faster than the new one enters.
- Time axis labels fade out of the way of the playhead clock instead of overlapping it.
- Reduced motion keeps playback (it is started by the viewer and can be paused at any time) but makes rewinds, jumps, markers and callouts instant and turns off autoplay.

### Responsive behavior

- From a block width of 1000px the key moments sit in a divided column beside the chart; below that they move under it in two columns, and in one column below 560px.
- Below 560px the readout becomes a three-column grid with the peak on its own row, the time axis labels every six hours, the chart is 300px tall, and the scrubber takes a full row above the play button and the speed control.
- The play button and every moment row are at least 44px tall, and the scrubber's hit area is 44px tall. The chart keeps vertical page scrolling; a horizontal drag or a tap scrubs.

### Performance

- One path string is built per frame from precomputed point positions (288 points in the sample), and text nodes are written only when their text changes.
- Running peaks, moment positions and effects are computed once per data set; positions are recomputed only on resize through a ResizeObserver.
- No React render happens per frame; state changes only a handful of times per replay.

### Notes for AI agents

- Choose it when the order in which something happened is the story: a launch day, an incident, an election night, a match, a trading session. The replay makes cause and effect visible by revealing the line and the moments together.
- Pass points on one clock in minutes from the start, and moments on the same clock. Points do not need to be evenly spaced; moments between points are placed by interpolation.
- The value axis is fixed to the whole series, so the line never rescales while it plays.
- The sample is an illustrative launch day for a fictional product with typical traffic for comparison; it is not real traffic.

### Keywords

replay, time replay, playback chart, animated line chart, playhead, scrubber, timeline, annotations, key moments, launch day, incident timeline, story chart, speed control

### Related

- connected-scatter
- metric-explorer

---

## Exploded view

A scroll driven exploded view where a live phone screen built from five CSS 3D layers lies back, separates in depth with labels that follow each layer, takes each layer into focus, and then reassembles.

- Type: Block (composition)
- Access: Pro
- Built from: Arc foundation
- Documentation: https://uiarc.dev/components/blocks/exploded-view

### Overview

Render <ExplodedView /> for the Tally demo in its own scrolling frame, or pass scroll="page" on a landing page so it pins to the viewport. Copy changes through title, description, layers (five entries, bottom to top) and ends, and onStopChange reports the current stop (0 assembled, 1 to 5 layers, 6 reassembled).

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/exploded-view. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/exploded-view while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- A showpiece section that shows a product is built with care, by literally taking its screen apart.
- Explaining the layers of a design system or UI kit: tokens, grid, content, controls and overlays.
- A launch page moment between the hero and the feature list, where one strong scroll interaction earns its place.

### When not to use

- Use zoom-into-ui to fly into parts of a flat product screen and explain features in place.
- Use scroll-story when the story is a sequence of product states rather than the structure of one screen.
- Use a static screenshot or feature-illustration where scroll driven motion would compete with nearby sections.

### Usage

```tsx
import { ExplodedView } from "@/components/arc/blocks/exploded-view/exploded-view";

export function HowItIsBuilt() {
  return (
    <ExplodedView
      scroll="page"
      title="Built in layers"
      description="Take the home screen apart. Each layer has one job, and together they read as one calm surface."
      onStopChange={stop => analytics.track("exploded_view_stop", { stop })}
    />
  );
}
```

### API

#### ExplodedView

A scroll driven exploded view of a product screen. A live, themed phone screen is built from five layers stacked in CSS 3D: surface, layout grid, content, controls and a floating notification. As you scroll the screen lies back, the layers separate in depth, a label with a leader line follows each layer, the layers take focus one at a time with a caption beside them, and then the stack closes and stands back up as one screen.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` | `string` | `"Built in layers"` | Heading of the section. |
| `description` | `string` | `sampleIntro.body` | One or two sentences under the heading. |
| `layers` | `ExplodedLayer[]` | `sampleLayers` | Name, short note and caption for each of the five layers, bottom to top ({ id, name, note, body }). The layer art is the built in screen, so pass exactly five entries in the order surface, grid, content, controls, floating. |
| `ends` | `{ start: { title: string; body: string }; end: { title: string; body: string } }` | `sampleEnds` | Captions shown before the stack separates and after it comes back together. |
| `scroll` | `"container" \| "page"` | `"container"` | "container" scrolls inside its own rounded frame, for previews and embeds. "page" lets the track run in the page and pins the stage to the viewport. |
| `length` | `number` | `4` | Scroll distance as a multiple of the frame height. Longer gives each layer more time in focus. |
| `onStopChange` | `(stop: number) => void` |  | Called when the stop under the reading position changes: 0 is assembled, 1 to 5 are the layers bottom to top, 6 is reassembled. |
| `className` | `string` |  | Class on the root section. |

### Dependencies

- `motion`
- `lucide-react`

### Keyboard

| Keys | Action |
| --- | --- |
| Tab | Moves to the scrolling frame (container mode) and then through the seven stop buttons under the caption. |
| Arrow up / Arrow down, Page up / Page down, Space | On the focused frame, scrolls the story, which separates and reassembles the layers. |
| Home / End | On the focused frame, jumps to the assembled screen or to the end. |
| Enter / Space | On a stop button, scrolls to that stop: assembled, one of the five layers, or reassembled. |

### Accessibility

- The section is labelled by its heading, and in container mode the scrolling frame is a focusable region named after it.
- The 3D stage and its floating labels are decorative and hidden from assistive tech; an ordered list outside the stage names every layer with its caption, bottom to top.
- The caption for the current stop sits in a polite live region, so each layer's name and description is announced as it takes focus.
- Each stop is a real button with the stop's name as its label and aria-current="step" on the current one.
- Pointer focus draws no ring; keyboard focus shows Arc's shared focus ring. A focused or hovered stop button fills with the muted surface, and the current stop's tick turns the accent and thickens, so position never depends on color alone.

### Motion

- One scroll timeline drives everything: the screen tilts back and turns, the layers spread apart in depth, the labels draw their leader lines and fade in bottom to top, then the stack closes and stands up again.
- Scroll progress is smoothed by a critically damped spring with no overshoot, so the stack follows the wheel softly, never passes its true position, and reverses mid way without a jump.
- The layer in focus keeps full strength while the others step back in opacity, and its outline and label take the accent; the caption crossfades with a short rise on the enter curve and leaves faster than it arrives.
- Labels live in flat stage space and are positioned each frame by projecting the layer's anchor point through the same rotation and perspective as the CSS, so text never tilts and the leader line always meets its layer.
- Per frame work writes transforms and opacity straight to the DOM from the motion value; React renders only when the stop changes.
- Reduced motion removes all travel: the screen shows flat at the start and end and fully separated for the five layer stops, switching instantly, and caption changes are instant.

### Responsive behavior

- From 880px wide the heading, caption and stops share a column on the left and the 3D stage fills the right.
- Below that the heading sits above the stage and the caption with its stops below it; below 560px the stops span the full width above the caption and the floating labels keep their names only.
- On a tall, narrow stage the stack turns less and spreads further, so it uses the height instead of shrinking; the scale is fitted from the stage size so the separated stack and its labels never overflow.
- Every stop button is 44px tall, and at phone widths the seven buttons share the full row.

### Performance

- Only transform and opacity change per frame, on a small number of elements: one group rotation, five layer depths and five label positions.
- Fit is measured once and again only when the stage resizes, through a ResizeObserver; the projection per frame is a few lines of trigonometry per layer.
- The first render is the flat screen on the server and the client alike, so there is no hydration mismatch; reduced motion is read after hydration.

### Notes for AI agents

- Choose it for a marketing or launch page that explains how a product is put together: design systems, UI kits, hardware with a screen, or an app whose craft is the selling point.
- The layer art is the built in Tally budgeting screen. Change the copy through layers, title and description; to show your own product, replace LayerArt in the source with your screen split into five layers at 280 by 620 design px.
- Use scroll="page" on a real landing page so the section pins to the viewport; container mode is for previews, docs and embeds where page scroll is not available.
- Tally, the people and the wine bar are sample content. Portraits and photos are local assets from public/media.

### Keywords

exploded view, layers, 3d, css 3d, perspective, isometric, scroll driven, scrollytelling, product screen, phone mockup, design system, showpiece, sticky section, depth

### Related

- scroll-story

---

## Seat map

An event seat picker with a curved concert hall map, price tiers, zoom and pan, sold, held and wheelchair seats, and a live summary with fees and a hold countdown.

- Type: Block (composition)
- Access: Pro
- Built from: Button, Animated counter
- Documentation: https://uiarc.dev/components/blocks/seat-map

### Overview

Render <SeatMap /> for the demo, or pass event, venue (seats with x, y, rotate, tier, status), tiers, maxSeats and an onHold promise that reserves the chosen seats. onSelectionChange reports the picked seats in order.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/seat-map. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/seat-map while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- Reserved seating for concerts, theatre, sports and conferences where the buyer picks exact seats.
- Any spatial picker with priced places: tables in a restaurant plan, desks in an office, cabins on a deck.
- Checkout flows that need a live total and a short hold before payment.

### When not to use

- Use a quantity stepper with best available when seats are general admission or assigned by the box office.
- Use availability-picker for choosing times rather than places.
- Use choropleth-explorer to compare values across regions without selecting them.

### Usage

```tsx
import { SeatMap } from "@/components/arc/blocks/seat-map/seat-map";

export function ChooseSeats({ performance, hall, prices }) {
  return (
    <SeatMap
      event={performance}
      venue={hall}
      tiers={prices}
      maxSeats={8}
      onHold={seats => fetch("/api/holds", { method: "POST", body: JSON.stringify(seats.map(seat => seat.id)) }).then(response => {
        if (!response.ok) throw new Error("Hold failed");
      })}
    />
  );
}
```

### API

#### SeatMap

An event seat picker. The hall is drawn as curved rows that face the stage, colored by price tier, with sold, held and wheelchair seats marked. Buyers zoom and pan the map, pick up to a set number of seats, and see a running summary with fees and a hold countdown.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `event` | `SeatEvent` | `seatEvent` | The performance: name, venue, a preformatted date string and an optional thumbnail image. |
| `venue` | `SeatVenue` | `seatVenue` | The hall in its own map units: width, height, the stage path and label position, sections with label positions, seats (id, section, row, number, x, y, rotate, tier, status, access, note) and row labels. |
| `tiers` | `SeatTier[]` | `seatTiers` | Price tiers in filter order. Each has an id, name, price and a CSS color; the demo uses --series-1 to --series-4 so tiers follow the accent and theme. |
| `maxSeats` | `number` | `6` | Most seats one buyer can pick. Picking past it shows an inline notice on the map instead of adding the seat. |
| `serviceFee` | `number` | `4.5` | Fee added per ticket, shown as its own line in the summary. |
| `currency` | `string` | `"USD"` | ISO currency code. Prices are formatted with the en-US locale so server and client render the same text. |
| `holdMinutes` | `number` | `10` | Length of the hold that starts after the hold button succeeds. The countdown releases the seats when it reaches zero. |
| `defaultSelected` | `string[]` | `seatDefaultSelection` | Seat ids selected on first render. Ids that are not available, or past maxSeats, are ignored. |
| `title` | `string` | `"Your seats"` | Heading of the summary panel. |
| `onSelectionChange` | `(seats: Seat[]) => void` |  | Called after every change to the selection, with the seats in the order they were picked. |
| `onHold` | `(seats: Seat[]) => void \| Promise<void>` |  | Called by the hold button. Return a promise to show the pending state; a rejection keeps the selection and shows an inline error with a retry. Without it the demo simulates a short request. |
| `className` | `string` |  | Class on the root section. |

### Dependencies

- `motion`
- `lucide-react`

### Keyboard

| Keys | Action |
| --- | --- |
| Tab | Moves into the map on one seat at a time (a roving tab stop), then on to the zoom controls and the summary. |
| Arrow keys | Left and right move along the row and cross the aisle to the next section; up and down move toward or away from the stage. The map pans to keep the seat in view. |
| Home / End | Jumps to the first or last seat in the row. |
| Enter / Space | Chooses or removes the seat. Sold and held seats explain why they cannot be chosen. |
| + / - | Zooms in or out around the middle of the map. |
| 0 | Shows the whole hall again. |

### Accessibility

- Every seat is a checkbox with a full name, such as "Row G, seat 7, Stalls centre. Stalls, $112. Aisle seat", and sold or held seats are marked disabled.
- Seats are grouped by section, and the map carries instructions for its keys through aria-describedby.
- Keyboard position shows as a soft fill behind the seat and a tooltip with the seat details, never a focus ring.
- Selections, removals, the seat limit, holds and expiry are announced in a polite live region.
- Tier, status and access never rely on color alone: sold seats shrink, held seats are outlined with a dot, selected seats carry a check, and wheelchair spaces are square with a glyph. The key under the map names each mark.
- Zoom buttons, the tier filter and each summary row are real buttons with specific names; remove buttons name the seat they remove.

### Motion

- The camera moves on one critically damped spring, so zooming, choosing a tier and following the keyboard glide without overshoot and can be interrupted by a drag at any point.
- Choosing a price tier dims the other tiers and flies the camera to where those seats sit; choosing it again returns to the whole hall.
- A picked seat fills and its check scales in; summary rows open and close their height on the smooth spring, and totals roll to their new values with tabular digits.
- Pan, pinch and ctrl or cmd scroll write straight to motion values and a single transform per frame, with no React state per frame.
- Reduced motion jumps the camera and swaps every transition for an instant change while keeping focus and announcements.

### Responsive behavior

- From 860px the map and the summary sit side by side with a 320px summary; below that the summary stacks under the map.
- Below 560px the map is 340px tall, the price filter scrolls sideways, and section labels hide until there is room for them.
- On touch, a tap on the whole hall zooms to that spot first, so seats are 44px apart before one can be chosen; one finger pans and two fingers pinch once zoomed, while the page still scrolls at the full view.
- Zoom buttons, price chips and remove buttons grow to 44px on coarse pointers.

### Performance

- Seats are plain SVG groups in a memoized component, so a selection repaints the changed seats rather than the hall. The demo draws about 500 seats.
- Camera motion is one transform on a single group, batched to one write per frame with Motion's frame loop.
- Tooltip position is written directly to its style when the camera or seat changes, without re-rendering.
- For halls of many thousands of seats, split sections into separate layers or render seats to canvas and keep the same props.

### Notes for AI agents

- Generate seat positions from your venue plan in any unit system; the camera fits whatever bounds the seats cover. Rotation turns each seat toward the stage.
- Map your inventory to status: available, held (in another buyer's cart) or sold. Only available seats can be chosen.
- Tier colors are plain CSS values. Keep them to the chart series or other semantic tokens so both themes stay legible.
- Wire onHold to your reservation API and return its promise. The countdown only reflects the local hold length; take the real expiry from your server if it differs.
- The first render uses the venue view box and no camera transform, then measures the viewport after mount, so the markup matches on server and client.

### Keywords

seat map, seat picker, seat selection, venue map, event tickets, ticketing, theatre seating, concert tickets, price tiers, zoom and pan, pinch zoom, wheelchair seats, accessible seating, hold timer, checkout

### Related

- availability-picker
- choropleth-explorer

---

## AI answer

One AI answer set like a clean article: it thinks, shows its sources as small cards with colored marks, and streams a formatted answer where every citation lights the sentence it supports. Copy, regenerate with options, rate, share, page through versions and ask a related question in place.

- Type: Block (composition)
- Access: Pro
- Built from: Text shimmer, Hover card, Copy button, Tooltip, Popover
- Documentation: https://uiarc.dev/components/blocks/ai-answer

### Overview

Pass question and respond, an async generator that yields reasoning deltas, the sources, text deltas in markdown with [n] citations, and a done event. Throw to show the error state; the AbortSignal fires on Stop, a new question and unmount. Pass answer, sources and usage to render a stored answer at once, and wire onFeedback, onFollowUp and onShare. With no props it runs a scripted demo.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/ai-answer. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/ai-answer while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- An answer page where one question gets one well formatted, cited answer that people read, copy and share.
- Docs and help center assistants that must show where each claim comes from.
- Internal knowledge search where the answer mixes prose, steps, a comparison table and code.

### When not to use

- Use ai-chat for a back and forth conversation with many turns kept on screen.
- Use research-run for long multi step research that plans searches and reads many sources before writing.
- Use ai-side-panel when the assistant sits next to a document or app the person is working in.
- Use ai-inline-edit to rewrite a selection in place rather than answer a question.

### Usage

```tsx
import { AiAnswer, type AnswerEvent } from "@/components/arc/blocks/ai-answer/ai-answer";

// Wire a real model: forward your server's stream as AnswerEvents.
async function* respond({ question, mode, model, signal }) {
  const response = await fetch("/api/answer", { method: "POST", body: JSON.stringify({ question, mode, model: model.id }), signal });
  if (!response.ok) throw new Error("The model is busy. Try again in a moment.");
  for await (const event of readNdjson<AnswerEvent>(response.body!)) yield event;
}

export function AnswerPage() {
  return (
    <AiAnswer
      question="How do we roll out passkeys without locking anyone out?"
      respond={respond}
      onFeedback={feedback => track("answer_feedback", feedback)}
      onFollowUp={question => router.push(`/ask?q=${encodeURIComponent(question)}`)}
      onShare={({ version }) => `https://acme.dev/answers/42${version ? `?v=${version + 1}` : ""}`}
    />
  );
}

// Or show a stored answer without streaming.
<AiAnswer
  question="What should we measure before each rollout stage?"
  answer={[
    { type: "paragraph", text: "Measure whether people get in, not just whether they enroll. [1]" },
    { type: "list", ordered: true, items: ["Enrollment", "Passkey success", "Fallbacks"] },
  ]}
  sources={[{ id: "webdev", title: "Passkey form autofill", site: "web.dev", domain: "web.dev", url: "https://web.dev/articles/passkey-form-autofill" }]}
  usage={{ tokens: 1240, thoughtSeconds: 7, seconds: 18.4 }}
/>
```

### API

#### AiAnswer

One AI answer in a calm app view. A slim top bar carries the thread title, New thread and Share. The question sits above a reasoning row that shimmers "Thinking" and settles to "Thought for 9s", which opens a short reasoning summary, and a sources row with a stack of small site marks that opens into source cards. The answer streams in chunks with headings, numbered lists, a comparison table, a code block with copy and inline citations; hovering or focusing a citation shows its source and softly lights the exact sentence it supports and the matching card. Under the answer: copy, regenerate (Try again, More concise, More detailed, Switch model), thumbs up, thumbs down with a reason, a share link, a version switcher after regenerating, the model line with tokens and time, and three related questions. A docked composer asks follow-ups and turns into Stop while an answer streams.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `question` | `string` | `"How do we roll out passkeys without locking anyone out?"` | The question. Leave it out for the demo. An empty string, with no `answer`, shows the empty state with suggestions. |
| `answer` | `AnswerBlock[]` |  | A finished answer to show at once, without streaming. Blocks are { type: "paragraph" \| "heading", text }, { type: "list", ordered?, items }, { type: "table", columns, rows } and { type: "code", code, language?, filename? }. Inline text supports **bold**, `code` and [n] citations. |
| `sources` | `AnswerSource[]` |  | Sources for a finished answer, numbered in order: [1] in the text is the first. Each is { id, title, site, domain, url, date?, snippet?, icon? }; `icon` is the site's mark (about 16px, brand colors kept), and the domain's first letter stands in without one. |
| `reasoning` | `string` |  | Reasoning summary for a finished answer, shown under "Thought for". Paragraphs split on blank lines. |
| `usage` | `{ tokens?: number; thoughtSeconds?: number; seconds?: number }` |  | Usage for a finished answer, shown on the model line and the reasoning row. |
| `followUps` | `string[]` |  | Related questions under the answer. The demo offers three from its script. |
| `suggestions` | `string[]` |  | Questions offered in the empty state. The demo offers its four sample questions; with `respond` the default is none. |
| `title` | `string` |  | Title in the top bar. Defaults to the question. |
| `model` | `AnswerModel` | `Claude Opus 5.5` | The model that writes the answer: { id, name, mark? }. The mark shows at 14px on the model line. |
| `models` | `AnswerModel[]` | `Claude Opus 5.5, Sonnet 5.5, Haiku 5.5, Fable 5.1` | Models offered under Regenerate, Switch model. The first is the default when `model` is not set. |
| `respond` | `(request: AnswerRequest) => AsyncIterable<AnswerEvent>` |  | Streams an answer from your model. The request has { question, mode, model, previous?, signal }; mode is "answer", "retry", "concise", "detailed" or "model". Yield { type: "reasoning", text }, { type: "sources", sources }, { type: "thought", seconds }, { type: "text", text } (markdown) and { type: "done", tokens?, seconds?, followUps? }. Throw to show the error state; stop when `signal` aborts. Without it, a scripted demo answers four sample questions. |
| `onFeedback` | `(feedback: AnswerFeedback) => void` |  | Called with { value: "up" \| "down" \| null, reason?, question, answer, model, version } on thumbs up, on thumbs down after a reason is picked, and with null when feedback is taken back. |
| `onFollowUp` | `(question: string) => void` |  | Called when a question is asked from the composer, a related question or a suggestion, just before its answer streams. |
| `onShare` | `(info: { question: string; answer: string; version?: number }) => string \| Promise<string>` |  | Returns the link that Share copies. `version` is set for the action bar link and undefined for the thread link in the top bar. Without it, a sample example.com link is copied and the status says so. |
| `className` | `string` |  | Class on the root element. The root fills the viewport height by default; set a height here to embed it. |

### Dependencies

- `motion`
- `lucide-react`
- `@radix-ui/react-dropdown-menu`
- `@radix-ui/react-popover`
- `@radix-ui/react-tooltip`

### Keyboard

| Keys | Action |
| --- | --- |
| Tab | Moves through New thread, Share, the reasoning and sources rows, the source cards, each citation, the table and code regions, code Copy, the action bar, the related questions and the composer. |
| Enter, Space | On the reasoning or sources row, opens or closes it. On a citation, opens the source in a new tab; focusing it already shows the source card and lights its sentence and card. |
| Enter | In the composer, sends the question. Shift+Enter adds a line. |
| Arrow up / Arrow down | In the Regenerate menu, moves between options; Arrow right opens Switch model and Arrow left closes it. |
| Escape | Closes the Regenerate menu, the reason picker or a citation card and returns focus to its trigger. |

### Accessibility

- The block is a labelled region named by the question, with aria-busy while an answer streams. A polite status region announces Thinking, Writing the answer, Answer ready, Answer stopped or the error.
- Action results (copied, link copied, feedback sent, version shown) go to a second polite live region; the share links say when the preview copies a sample link.
- The reasoning and sources rows are buttons with aria-expanded and aria-controls; closed panels are inert, so their content leaves the tab order.
- Citations are links named "Source n: title, site"; the source card opens on keyboard focus as well as hover, and a lit sentence is a visual aid only, never the only cue.
- The comparison table keeps header cells with scope, and the table and code scroll inside focusable, labelled regions on narrow screens.
- Status is never color alone: copied shows a drawn check, errors an icon and text, feedback a filled glyph with aria-pressed, and stopped or failed answers a note with a Try again button.
- Asking a related question moves focus to the new question heading; New thread moves focus to the composer.
- Pointer focus draws no ring; keyboard focus shows Arc's shared focus ring.

### Motion

- "Thinking" uses the Arc text shimmer for about a second and settles to solid text as "Thought for 9s" when the first words arrive.
- The answer streams in chunks on a requestAnimationFrame clock: about every 34ms, three to eight words commit at once and fade in over 160ms on a plain ease-out, with no blur, travel or stagger. A steady pace of about a hundred words a second plus catch-up drains bursts, so a full answer lands in two to four seconds. Settled text never re-renders or reflows.
- Headings, list items, table rows and code lines appear as their text arrives; a line or row waits for its newline, so containers never pop in half built.
- The reasoning and sources panels open on the smooth spring; source cards fade in 20ms apart, at most six steps. Hovering the sources row fans the mark chips apart on the CSS spring.
- Regenerating or switching versions crossfades the answer while its height springs to the new length, and the version number rolls up or down.
- Copy and Share morph their icon (a drawn check) and label in place without changing width; Send turns into Stop in the same spot.
- Reduced motion keeps the chunked arrival but drops every fade, roll, fan and spring, and keeps all states and announcements.

### Responsive behavior

- The reading column caps at about 704px with even gutters that shrink to 16px on phones; the question scales between 22px and 28px with the container.
- Source cards form a two column grid in a wide column and a snap scrolling row on phones, faded at the trailing edge with a mask; a citation that lights an off screen card scrolls it into view.
- The table and code scroll horizontally inside their frames; the action bar wraps its model line under the actions.
- The top bar truncates the title and keeps Share; the composer stays docked at the bottom and grows to six lines.

### Performance

- Streamed markdown is parsed into numbered units that stay stable as text arrives, so each commit only appends new spans and earlier text never re-renders.
- One requestAnimationFrame loop per answer paces the reveal and commits at most every 34ms; it stops as soon as the answer is on screen.
- Finished versions render whole without the reveal, and the answer body is memoized against hover changes outside its sentences.

### Notes for AI agents

- Choose it for a single answer page with sources: help centers, internal search, docs assistants, answer engines. It shows one question at a time; asking another replaces it.
- Stream markdown in `text` events: paragraphs, ### headings, 1. and - lists, pipe tables and fenced code (```js filename.js). Inline **bold**, `code` and [n] citations work everywhere; [n] points at sources[n - 1].
- Send `sources` early, during reasoning, so the stack fills while the model thinks. Send `thought` with the thinking duration when the first text is ready; without it the time to first text is used.
- Brand marks are sample content. Pass your own `icon` per source; keep color brands in their colors and mono brands on currentColor.
- Regenerate keeps every version in memory for the session and calls `respond` with mode and the previous answer as markdown, so your prompt can ask for a shorter, longer or different answer.
- The demo compresses time: thinking plays in about a second and the reported thinking time and duration are what the simulated model would have taken.

### Keywords

ai answer, answer engine, cited answer, citations, sources, streaming, reasoning, thinking, regenerate, feedback, follow-up questions, perplexity style, llm, markdown, answer page

### Related

- ai-chat
- research-run
- ai-composer
- ai-side-panel
- model-picker
- text-shimmer

---

## Model picker

A model picker in one quiet pill: open it to choose from featured models with a one line note each, set the reasoning effort, or browse every other model by provider, and the pill swaps to your choice in place.

- Type: Block (composition)
- Access: Pro
- Built from: Arc foundation
- Documentation: https://uiarc.dev/components/blocks/model-picker

### Overview

Drop it into a composer or settings row. Pass models, value and onChange to control the selection, and effort with onEffortChange for reasoning models; with no props it shows a sample lineup of current models.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/model-picker. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/model-picker while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- Choosing the model and effort for a chat, an agent or a playground.
- A default model setting with a short review of what the chosen model costs and how much context it takes.

### When not to use

- Comparing two models' answers side by side; use model-arena.
- A full prompt box with attachments and tools; use ai-composer, which has its own model chip.
- Choosing from a plain list of options with no descriptions; use the select or dropdown-menu component.

### Usage

```tsx
import { ModelPicker } from "@/components/arc/blocks/model-picker/model-picker";

export function ComposerModel({ model, setModel, effort, setEffort }) {
  return (
    <ModelPicker
      value={model}
      onValueChange={id => setModel(id)}
      effort={effort}
      onEffortChange={setEffort}
      featured={["claude-opus-5-5", "claude-sonnet-5-5", "claude-haiku-5-5"]}
      showSummary={false}
    />
  );
}
```

### API

#### ModelPicker

A model picker for an AI product. One quiet pill names the current model and its effort and opens a short menu: the featured models with a one line description each, an Effort submenu for reasoning models and every other model under More models, grouped by provider. Choosing a model closes the menu, the pill morphs to the new model, and the review underneath updates its description, context window, prices and effort. On phones the submenus open as pages inside the menu with a Back row.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `models` | `PickerModel[]` | `sampleModels` | The catalog. Each model has id (the API id the picker reports), name, provider, blurb (the short menu line), description, context, maxOutput, price { input, output } in USD per 1M tokens, released, and optional tag, effort { levels, default }, mark and color. Anthropic prices in the sample are real; every other price and limit is a sample value. |
| `providers` | `PickerProvider[]` | `sampleProviders` | Providers in the order More models groups them, each { id, name, mark, color? }. A model without its own mark uses its provider's. |
| `featured` | `string[]` | `["claude-opus-5-5", "claude-sonnet-5-5", "gpt-6.1-sol", "gemini-4-argon"]` | Model ids listed at the top of the menu, in order. Every other model sits under More models. With your own models and no featured list, the first four are featured. |
| `value` | `string` |  | The chosen model id (controlled). |
| `defaultValue` | `string` |  | The first chosen model when uncontrolled. Defaults to the first featured model. |
| `onValueChange` | `(id: string, model: PickerModel) => void` |  | Called when someone picks a model. |
| `effort` | `"low" \| "medium" \| "high" \| "xhigh" \| "max"` |  | Effort for the chosen model (controlled). A level the model does not accept snaps to the nearest level it does. |
| `defaultEffort` | `Effort` |  | The first effort when uncontrolled. Defaults to the chosen model's own default. |
| `onEffortChange` | `(effort: Effort) => void` |  | Called when the effort changes, including when a new model snaps it to a level it accepts. |
| `open` | `boolean` |  | Whether the menu is open (controlled). |
| `defaultOpen` | `boolean` | `false` | Opens the menu on first render. |
| `onOpenChange` | `(open: boolean) => void` |  | Called when the menu opens or closes. |
| `showSummary` | `boolean` | `true` | Shows the review under the pill: description, context, input and output price, effort, and a short confirmation after each change. Turn it off to use the pill alone, for example inside a composer toolbar. |
| `className` | `string` |  | Class on the root element. |

### Dependencies

- `motion`
- `lucide-react`
- `@radix-ui/react-dropdown-menu`

### Keyboard

| Keys | Action |
| --- | --- |
| Enter, Space, Arrow down | On the pill, opens the menu and focuses the current model. |
| Arrow up / Arrow down | Moves through the models and rows. The highlight follows. |
| Type a letter | Jumps to the next model whose name starts with it. |
| Enter, Space | Chooses the highlighted model or effort and closes the menu. |
| Arrow right / Arrow left | Opens and closes the Effort and More models submenus, or their pages on phones. |
| Escape | Closes the menu and returns focus to the pill. |

### Accessibility

- Built on the Radix dropdown menu: the featured models, the effort levels and the other models are radio groups, so a screen reader announces each as checked or not.
- The pill's name includes the current model and effort, for example "Model: Claude Opus 5.5, medium effort. Change model".
- Each change is announced through a polite status region, and the review under the pill is a labelled section.
- Brand marks are decorative next to the model name and hidden from assistive technology.
- Focus returns to the pill when the menu closes. A pointer choice does not draw the keyboard focus ring; keyboard use keeps Arc's shared ring.

### Motion

- The menu opens from the pill edge with a short offset, a slight scale and a quick fade, and reverses from where it is if closed mid-open.
- One highlight glides between rows on the snappy spring for the pointer and jumps for the keyboard, so moving through the list never flickers.
- On a change, the pill's mark and name crossfade and the pill width springs to the new name, so it never snaps.
- The review's values crossfade in place with no character morphing; every slot keeps its height.
- On phones, moving between menu pages slides the content a few pixels and the menu height springs to the new page.
- Reduced motion swaps everything in place and keeps every state and announcement.

### Responsive behavior

- The pill truncates long names inside narrow toolbars and keeps its chevron visible.
- Below 640px the Effort and More models submenus become pages inside the same menu with a Back row, so nothing opens off screen.
- Long lists scroll inside the menu, and the review's four values fold into a two by two grid under 400px.

### Performance

- The menu mounts only while open. The highlight is one element per menu surface, moved with transforms.
- The pill width is measured with a ResizeObserver and animated once per change.

### Notes for AI agents

- Use it wherever a person chooses which model answers: a composer toolbar, a settings row or an API playground. Keep the featured list short (three to five) and put the rest under More models.
- Pass blurb as a few words on what the model is for; it is the only line under the name in the menu. Put the longer sentence in description for the review.
- Only models with an effort field show the Effort row. Effort levels are per model, and a level the new model does not accept snaps to the nearest one it does.
- Show real prices only for models you have verified. The sample marks non-Anthropic prices as sample values.

### Keywords

model picker, model selector, llm model switcher, ai model dropdown, reasoning effort, claude, gpt, gemini, choose model, ai settings

### Related

- ai-composer
- model-arena
- ai-chat
- context-window
- dropdown-menu

---

## Model arena

A blind side by side model comparison in one card: send one prompt to two models, watch both answers stream at the same pace, vote for the better one, then reveal which model wrote each.

- Type: Block (composition)
- Access: Pro
- Built from: Animated counter, Button, Popover, Switch, Text shimmer
- Documentation: https://uiarc.dev/components/blocks/model-arena

### Overview

Use it for evals, demos or a feedback page. Pass models and respond to stream real answers per side, and onVote to record the choice; with no props it plays scripted answers.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/model-arena. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/model-arena while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- Blind human preference tests between two models on the same prompt, such as an internal bake-off before switching providers.
- Prompt or model evaluation tools where people should judge answers without knowing which model wrote them.
- Showing latency, speed and cost differences between two models live, side by side, on a real prompt.

### When not to use

- Use model-picker to let someone choose one model for their own chat; this block compares answers, it does not set a default.
- Use eval-suite to score many prompts automatically against expected outputs rather than collecting one human vote at a time.
- Use model-router to explain or configure automatic routing between models.
- Use ai-chat for a single ongoing conversation with one model.

### Usage

```tsx
import { ModelArena, ArenaRunError } from "@/components/arc/blocks/model-arena/model-arena";

// Stream each model through your own endpoint. Yield text as it arrives.
async function* run(model, prompt, signal) {
  const response = await fetch("/api/arena", { method: "POST", body: JSON.stringify({ model: model.id, prompt }), signal });
  if (!response.ok) throw new ArenaRunError(response.status === 429 ? "Rate limited. Try again in a moment." : "The model did not respond.");
  const reader = response.body.getReader();
  const decoder = new TextDecoder();
  for (;;) {
    const { done, value } = await reader.read();
    if (done) return;
    yield decoder.decode(value, { stream: true });
  }
}

export function Arena() {
  return <ModelArena run={run} onVote={vote => saveVote(vote)} />;
}
```

### API

#### ModelArena

A blind side by side comparison in one card. A single line prompt field with Run and three sample chips sends the same prompt to two models, and two slim panes stream their answers at the same pace inside a fixed height. Each pane header shows "Model A" or "Model B" with a small status (Thinking, Writing, Done), the first pane to finish earns a Finished first marker, and a quiet line under each pane rolls first token time, tokens per second and cost on tabular digits. When both answers land, the vote row offers A is better, Tie, B is better and Both bad. Voting reveals both models: the brand mark and name crossfade in where the letter stood while the label's width follows on a spring with no bounce, and the row becomes a one line result with Next round. A Leaderboard button opens a popover with the top five by win rate, which replays the latest vote as a smooth reorder. A Blind switch reveals names at any time, a pane that fails shows its error and a retry, and below 560px the panes become two tabs that keep both statuses in view.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `contestants` | `ArenaModel[]` | `arenaModels` | The pool each round draws its blind pair from. An ArenaModel has id, name, optional shortName for tabs, provider, an optional mark component with markColor for mono marks, price { input, output } in US dollars per million tokens, and an optional color for its leaderboard bar (a series token such as var(--series-2)). The default pool is Claude Opus 5.5, GPT-6.1 Sol, Gemini 4 Argon, Grok 4.7, Claude Sonnet 5.5, DeepSeek V4.1 Flash and Mistral Large 4; Anthropic prices are list prices and the others are sample values. |
| `prompts` | `ArenaPrompt[]` | `arenaPrompts` | Sample prompts shown as chips under the field, each { id, label, text }. The first one prefills the field, a chip fills and runs its prompt, and Next round moves to the next one. |
| `run` | `(model: ArenaModel, prompt: string, signal: AbortSignal) => AsyncIterable<ArenaStreamEvent>` |  | Streams one model's answer. Yield text deltas as strings, or objects { text?, inputTokens?, outputTokens? } to report the provider's usage; without usage, output tokens are estimated at four characters per token. Throw to fail the pane; throw an ArenaRunError with { retryable: false } to hide the retry. Stop when the signal aborts. Without run, the arena streams scripted sample answers at simulated speeds and says so in its live region. |
| `onVote` | `(vote: ArenaVote) => void` |  | Called once per vote with { round, prompt, models (model A, model B), choice ("a" \| "b" \| "tie" \| "bad"), winner, metrics }. Each metrics entry carries ttftMs, tokensPerSecond, totalMs, outputTokens and costUsd as measured from the stream. |
| `defaultBlind` | `boolean` | `true` | Hides model names and marks until a vote. The Blind switch flips it at any time. |
| `autoStart` | `boolean` | `true without run, false with run` | Runs the first round once the card scrolls into view. |
| `initialStandings` | `Record<string, { wins: number; ties: number; losses: number }>` |  | Starting records per model id, for a leaderboard loaded from your own store. Without it the leaderboard counts this session's votes from zero. |
| `className` | `string` |  | Class on the root element. |

### Dependencies

- `motion`
- `lucide-react`
- `@radix-ui/react-popover`
- `@radix-ui/react-switch`

### Keyboard

| Keys | Action |
| --- | --- |
| Tab | Moves through Leaderboard, the Blind switch, the prompt field, Run, the sample chips, each answer (a scrollable region), Retry where shown, and the vote buttons or Next round. |
| Enter | In the prompt field, runs the prompt. While the models are answering, Run becomes Stop. |
| Command Enter / Ctrl Enter | Runs the prompt from the field, Run or a chip. |
| Escape | Stops a run in progress from the prompt row, and closes the leaderboard popover, returning focus to its button. |
| Arrow left / Arrow right, Home, End | On the narrow layout's answer tabs, moves between model A and model B. |
| Arrow up, Page up, Home | Inside a focused answer, scrolls back and stops it following the stream; scrolling to the end follows again. |
| Enter, Space | On a vote button, records the vote and moves focus to Next round, which starts the next blind round and returns focus to Stop. |

### Accessibility

- Each pane is a labelled region ("Model A", or "Model A, Claude Opus 5.5" once revealed). Its answer is a focusable scroll region marked aria-busy while it streams.
- In blind mode no model name, mark or title reaches the page or the accessibility tree until the vote.
- Every status pairs an icon with a word: Thinking, Writing, Done, Finished first, Stopped, Failed. Color only reinforces it.
- A polite status region narrates the round: that a run started (and that the preview is simulated), which model finished first, that voting is open, the vote result with both real models, and a leaderboard reset.
- On narrow containers the panes use tab semantics: a tablist with aria-selected tabs, each controlling a tabpanel; the hidden panel leaves the tab order.
- The vote buttons form a labelled group. Leaderboard rows read their rank and win rate as text, the bars are hidden from assistive technology, and the Leaderboard button's name says when a vote has updated it.
- Run carries aria-keyshortcuts for its shortcut. Pointer focus draws no ring; keyboard focus shows Arc's shared focus ring, inset inside scroll regions.

### Motion

- Answers stream in chunks of whole words every 30 to 40ms, each fading in over 160ms with no blur or travel, at the same pace in both panes; settled text never re-renders, and each answer follows its stream until the reader scrolls up.
- The reveal is one minimal crossfade: "Model A" fades out in 100ms while the brand mark and name fade in over 160ms from 2px below, and the label's measured width follows on a spring with no bounce. Status words and tab labels swap the same way; no character morph, blur or per letter motion anywhere.
- Working statuses shimmer with Text shimmer, and each status word mounts with its own shimmer so a change is a crossfade, never a morph inside the label.
- First token time counts live while the model thinks; speed and cost are sampled twice a second while it writes and roll on Animated counter digits, so each roll settles before the next.
- The vote row crossfades between waiting, voting and result while its height follows on the smooth spring. Run and Stop share one cell, so the button never changes width.
- Opening the leaderboard after a vote replays it: rows start at their earlier ranks and glide to the new ones on a critically damped spring while win rates roll and bars scale in each model's series color; ranks stay put while rows move. After the first vote, the bars grow from empty.
- Narrow tabs slide their highlight on a 220ms tween with no bounce, and the chosen pane fades in.
- Reduced motion keeps every state, label and announcement but shows chunks without fading, swaps labels instantly, reorders rows in place and stops the spinner and shimmer.

### Responsive behavior

- The card is up to 800px wide. From 560px the panes sit side by side; below that they become two tabs, each showing the model's name and status, so both statuses stay visible while you read one answer.
- Each answer scrolls inside a fixed height, so the card never grows while text streams. Code blocks scroll sideways inside the pane.
- Below 480px the Leaderboard button collapses to its icon with an accessible name, the shortcut hint hides, sample chips scroll sideways in one line, and the vote buttons form a two by two grid.

### Performance

- Streamed chunks are memoized spans that never re-render once shown, so long answers stay cheap.
- The first token clock ticks on animation frames only while a model thinks, and speed and cost are sampled twice a second only while it writes.
- Every stream has its own AbortController: Stop, a new prompt, Next round and Retry abort the work they replace, and the arena aborts everything on unmount.
- The leaderboard rows mount only while the popover is open. The simulation runs on requestAnimationFrame and pauses with the tab.

### Notes for AI agents

- Pass run to stream real models; it receives the ArenaModel, the prompt text and an AbortSignal. Timing (first token, speed) is measured from your stream on the client, so yield as soon as text arrives rather than buffering.
- Report the provider's usage by yielding { inputTokens, outputTokens } (with or without text) for exact cost; otherwise tokens are estimated from characters and cost uses the model's price.
- Throw from run to fail one pane; the other keeps streaming. ArenaRunError(message, { retryable: false }) hides the retry button.
- Persist votes in onVote. To show standings from earlier sessions, pass initialStandings keyed by model id; a tie counts as half a win and Both bad counts as a loss for each model.
- Give each model a color from --series-1 to --series-4 so providers read as families on the leaderboard; the default pool colors by provider.
- In blind mode cost and speed can hint at a model's identity; leave them for honest measurement, or pass the same price for every contestant if identity must stay fully hidden.
- Model names, marks and non-Anthropic prices in the default pool are sample content, not endorsements or published benchmarks.

### Keywords

model arena, llm comparison, blind test, side by side, model battle, ab test, human preference, vote, leaderboard, win rate, time to first token, tokens per second, latency, cost, streaming, claude, gpt, gemini

### Related

- model-picker
- eval-suite
- prompt-studio
- ai-chat

---

## Prompt studio

One card for editing, testing and shipping a prompt template: variables as chips with sample values, a test run against the chosen model, and versions you can compare and promote to production.

- Type: Block (composition)
- Access: Pro
- Built from: Avatar, Button, Copy button, Kbd, Popover
- Documentation: https://uiarc.dev/components/blocks/prompt-studio

### Overview

Pass template, variables and versions to load your own prompt, run to call your model, and onPromote to ship a version; with no props it edits a sample support prompt.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/prompt-studio. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/prompt-studio while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- A settings or admin page where a support lead or engineer tunes the prompt behind one AI feature and tests it on real cases.
- Prompt management that needs a compact version history with authors, a diff against an earlier version and a visible production pointer.
- Any LLM feature with template variables filled from records, such as a support reply, a summary or a classifier prompt.

### When not to use

- Use ai-chat for an end user conversation; this card edits templates, not messages.
- Use model-arena to compare the replies of several models side by side on one prompt.
- Use eval-suite to score a prompt across many cases with graders and pass rates.
- Use model-picker when the only job is choosing a model and effort.

### Usage

```tsx
import { PromptStudio } from "@/components/arc/blocks/prompt-studio/prompt-studio";

export function SupportPrompt({ prompt, cases }) {
  return (
    <PromptStudio
      name={prompt.name}
      versions={prompt.versions}
      productionId={prompt.productionId}
      variables={["customer_name", "order_id", "policy"]}
      testCases={cases}
      onRun={async function* (request, signal) {
        const response = await fetch("/api/prompt-run", { method: "POST", body: JSON.stringify(request), signal });
        const reader = response.body!.pipeThrough(new TextDecoderStream()).getReader();
        for (;;) {
          const { value, done } = await reader.read();
          if (done) return;
          yield value;
        }
      }}
      onPromote={versionId => setProduction(prompt.id, versionId)}
    />
  );
}

// A version is plain text with {{variables}}.
const version = {
  id: "v4", label: "v4", createdAt: "2026-10-16T15:20:00Z", message: "Escalate when the policy falls short",
  author: { name: "Hannah Walsh", avatar: "/media/people/hannah-walsh.svg" },
  system: "You are a support agent for Fernwood. Follow this policy exactly: {{policy}}",
  user: "Reply to the latest message from {{customer_name}} about order {{order_id}}.",
};
```

### API

#### PromptStudio

One card for editing, testing and shipping a prompt template. The header holds the prompt's name, a version chip (a menu of versions with compare, promote to production and undo) and a model chip (model and effort). System and User tabs show the template with {{variable}} placeholders as atomic chips, each variable in its own series color. A row of colored fields fills the variables from saved test cases, and Run streams the reply into a quiet panel at the foot with latency, tokens and cost. Compare turns the editor into an inline word diff.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `name` | `string` | `"Support reply"` | Name of the prompt, shown in the header. |
| `versions` | `PromptVersion[]` | `sampleVersions` | Saved versions, newest first. Each has id, label ("v4"), message, author ({ name, avatar? }), createdAt (ISO date) and the system and user text. |
| `versionId` | `string` |  | The version open in the editor; the chip shows its label. Defaults to the newest version. |
| `productionId` | `string \| null` |  | The version production serves; it carries the Production marker. Defaults to the open version. |
| `template` | `{ system: string; user: string }` |  | The draft the editor opens with. Defaults to the open version's text. |
| `variables` | `string[]` |  | Variable order for colors and fields: the first four take --series-1 to --series-4, then the colors repeat. Variables found in the text but not listed are added after. Defaults to the order they appear in the open version. |
| `testCases` | `PromptTestCase[]` | `sampleCases` | Saved test cases as { id, label, values }, where values maps a variable name to its value. The first case is loaded on mount. Keep labels short: the cases share one segmented control. |
| `models` | `PromptModel[]` | `studioModels` | Models for the model menu: id, name, short (chip label), mark ("claude" \| "openai" \| "gemini"), input and output price per million tokens, sample (marks illustrative prices) and defaultEffort. |
| `defaultModel` | `string` | `"claude-sonnet-5-5"` | Id of the model selected on first render. |
| `defaultEffort` | `"low" \| "medium" \| "high" \| "xhigh" \| "max"` |  | Effort selected on first render. Defaults to the model's own default (high for Claude Sonnet 5.5). Choosing another model resets effort to that model's default. |
| `now` | `string \| number \| Date` |  | Reference moment for the relative dates in the version menu. Defaults to the current time, or to Oct 20, 2026 for the sample versions so the demo never ages. |
| `onRun` | `(request: PromptRunRequest, signal: AbortSignal) => Promise<string \| AsyncIterable<string>> \| AsyncIterable<string>` |  | Runs the prompt. The request carries the raw template, the rendered template, the values, model, effort, test case id and version id. Return the whole reply or an async iterable of text deltas; throw to show the error state with Retry. Stop aborts the signal. Without it, runs are simulated and labelled as such. |
| `onPromote` | `(versionId: string, previousId: string \| null) => void` |  | Called when a version is promoted to production, and again with the ids swapped when the promotion is undone. |
| `onTemplateChange` | `(template: { system: string; user: string }) => void` |  | Called with the draft after every edit, for autosave. |
| `className` | `string` |  | Class on the root element. |

#### PromptEditor

The chip editor on its own, exported from prompt-editor.tsx. A plain text contenteditable where the string is the model: every edit is applied to the string and the DOM is rebuilt from it, so chips cannot be split and copy and paste keep the braces.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` (required) | `string` |  | The template text, with placeholders written as {{name}}. |
| `onChange` (required) | `(value: string) => void` |  | Called with the new text after every edit. Placeholders are normalized to {{name}} without inner spaces. |
| `variables` (required) | `string[]` |  | Names offered after typing {{. |
| `toneOf` (required) | `(name: string) => number` |  | Color slot (1 to 4) for a variable, read as --series-1 to --series-4. |
| `label` (required) | `string` |  | Accessible name of the text box. |
| `missing` | `string[]` |  | Variables without a value; their chips draw a dashed outline. |
| `activeVariable` | `string \| null` |  | A variable to light up, for example while its value field has focus. |
| `flash` | `{ name: string; at: number } \| null` |  | Flashes every chip of a variable once. Pass a new `at` to flash again, for example on each keystroke in its field. |
| `onChipClick` | `(name: string) => void` |  | Called when a chip is clicked. |
| `onSubmit` | `() => void` |  | Called on Mod+Enter. |
| `placeholder` | `string` |  | Shown while the text is empty. |

### Dependencies

- `motion`
- `lucide-react`
- `@radix-ui/react-popover`

### Keyboard

| Keys | Action |
| --- | --- |
| Mod+Enter | Runs the prompt for the selected test case from anywhere in the card, including the editors and the variable fields. |
| {{ | In the editor, opens the list of known variables. Arrow up and down move, Enter or Tab inserts the variable as a chip, Escape closes the list. Typing a new name then }} creates a variable and a field for it. |
| Backspace, Delete | Remove a chip whole when the caret is beside it. Option or Ctrl with Backspace removes a word. |
| Mod+Z, Shift+Mod+Z | Undo and redo inside the editor. Typing within a short pause is one step. |
| Arrow left / Arrow right | On the System and User tabs, the test case control and the effort control, move the selection. |
| Arrow up / Arrow down | In the version menu and the model menu, move between rows and select them. |
| Escape | Closes an open menu. In compare mode, returns to editing. |
| Tab | Moves through the version chip, model chip, tabs, editor, each variable field, the test cases, Run, and Copy or Retry. |

### Accessibility

- The editor is a role="textbox" with aria-multiline and an accessible name per tab; while the {{ list is open it points at the list with aria-controls and at the highlighted option with aria-activedescendant.
- System and User are real tabs with tabpanels. The hidden panel is inert, so it leaves the tab order and the reading order.
- Every variable field has a visible label in its variable's color, paired with a colored dot. Clicking a chip focuses its field.
- Status is never color alone: the version chip says Production or Latest, the run status pairs an icon with Reply, Stopped or Run failed, and an empty variable's chips switch to a dashed outline.
- The diff uses ins and del elements with visually hidden Added and Removed prefixes, plus a visible + or minus sign before each change and a strikethrough on removals.
- Version rows and model rows are radios in a labelled group. The Production marker is text, and the menu's status line says which version production serves.
- Runs, results, errors, promotions, undos and compare mode are announced through one polite status region, including when a run is simulated.
- Pointer focus draws no ring; keyboard focus shows Arc's shared focus ring, inset on menu rows and segmented options.

### Motion

- Promoting a version glides the Production marker from its old row to the new one on the critically damped smooth spring, with no overshoot. Undo glides it back.
- The reply streams in chunks of three to six whole words every 40ms on a requestAnimationFrame clock, about 100 words a second, and a backlog widens the chunks. Each chunk only fades in over 150ms; settled text never moves. Thinking lasts 0.5 to 1.2 seconds by effort.
- The output panel follows its content's height on the smooth spring. A rerun holds the panel at its current height until the new reply is in, then settles, so nothing collapses and regrows.
- Labels that change (version state, model name, effort, run status, the footer) use one crossfade: the old label fades out in 100ms while the new one fades in from 2px over 160ms, and the chip width follows on a fast spring without bounce. No blur, no per-letter motion.
- Tab and test case highlights slide on a critically damped spring. Token counts roll their digits with tabular numerals in a fixed slot. Editing a value flashes its chips once.
- The working label uses a calm shimmer that stops on Reply, Stopped or Run failed.
- Reduced motion removes the glides, the chunk fade, the shimmer and every height animation while keeping each state, label and announcement.

### Responsive behavior

- The card is up to 760px wide and reads well from 320px. It uses container queries, so it adapts to its slot, not the viewport.
- Below 560px of container width the variable fields fall into two columns, and below 340px into one.
- Below 480px the test cases and Run each take a full row, and the model chip wraps under the title.
- System and User share one editor slot sized to the taller text, so switching tabs never changes the card's height.

### Performance

- The editor rebuilds a few dozen DOM nodes per keystroke from the string, well under a millisecond for prompt sized text.
- The word diff trims the shared start and end before its longest common subsequence pass, so typical edits compare a few dozen tokens.
- Streaming appends one chunk per tick and never re-renders earlier chunks; the clock stops when the reply is complete, stopped or failed.
- Only one run is active at a time; starting another cancels the first and aborts its signal.

### Notes for AI agents

- Choose it when a team edits a prompt template, tries it on saved cases and promotes a version to production, inside a product page or settings screen.
- Write placeholders as {{name}} in the system and user text. Pass `variables` to fix the color order; values in test cases are matched by name.
- Wire onRun to stream real replies. Return an async iterable of text deltas, or a promise of the full text, and respect the AbortSignal: Stop aborts it. The footer estimates tokens and cost from the model prices you pass.
- Keep onPromote as the source of truth: the card updates its own pointer optimistically and calls back, and Undo calls it again with the ids swapped.
- Model prices outside Anthropic in the sample list are illustrative. Pass your own models with real prices for cost estimates.
- Without props it renders the full demo: a Fernwood support reply prompt with four versions, v4 in production and three saved cases. Without onRun, the first run of the Past window case returns a simulated overload error so the retry path can be seen.

### Keywords

prompt studio, prompt editor, prompt template, prompt management, prompt versioning, llm playground, template variables, test cases, production prompt, promote to production, prompt diff, system prompt, model effort, streaming reply

### Related

- model-picker
- model-arena
- eval-suite
- ai-inline-edit
- ai-chat

---

## Document extraction

Turns a document into typed data with a model and shows where every value came from: fields fill in as the page is read, and hovering a value lights its source on the PDF.

- Type: Block (composition)
- Access: Pro
- Built from: Button, Copy button, Tabs, Text shimmer, Tooltip
- Documentation: https://uiarc.dev/components/blocks/document-extract

### Overview

Pass a document, a schema and extract, which streams field values with their source boxes; onConfirm receives the checked data. With no props it extracts a sample invoice.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/document-extract. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/document-extract while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- Accounts payable, logistics or back office tools that turn invoices, receipts, emails or forms into records a person accepts before saving.
- Any extraction flow where a reviewer needs to see exactly where each value came from and fix the few the model was unsure about.
- Demos and settings pages for a structured output feature, with the schema and live typed JSON one tab away.

### When not to use

- Use ai-answer for a written answer with citations rather than typed fields.
- Use knowledge-base to search and cite across many documents instead of reading one.
- Use ai-inline-edit to rewrite text in place rather than pull values out of it.
- Use agent-approvals when the decision is approving an agent's actions, not reviewing extracted values.

### Usage

```tsx
import { DocumentExtract, documentToText, invoiceSchema, toJsonSchema } from "@/components/arc/blocks/document-extract/document-extract";

export function InvoiceInbox({ document }) {
  return (
    <DocumentExtract
      document={document}
      schema={invoiceSchema}
      extract={async function* (doc, schema, { signal }) {
        // Your route sends documentToText(doc) and toJsonSchema(schema) to the model as structured output,
        // and streams back one line of JSON per value: { path, value, source, confidence, note }.
        const response = await fetch("/api/extract", {
          method: "POST",
          body: JSON.stringify({ text: documentToText(doc), schema: toJsonSchema(schema) }),
          signal,
        });
        const reader = response.body!.pipeThrough(new TextDecoderStream()).getReader();
        let buffer = "";
        for (;;) {
          const { value, done } = await reader.read();
          if (done) break;
          buffer += value;
          const lines = buffer.split("\n");
          buffer = lines.pop() ?? "";
          for (const line of lines) if (line.trim()) yield { type: "value", ...JSON.parse(line) };
        }
      }}
      onAccept={data => saveInvoice(data)}
    />
  );
}

// Mark the spans a value can cite, so the form can point back at them.
const document = {
  id: "inv-0418",
  name: "larkspur-invoice-0418.pdf",
  label: "Invoice",
  kind: "pdf",
  blocks: [
    { type: "masthead", logo: { name: "larkspur", detail: "studio", color: "#3d4fc4", symbol: "petals" }, title: "Invoice" },
    { type: "meta", items: [["Invoice no.", [{ span: "number", text: "INV-2026-0418" }]], ["Issue date", [{ span: "issue", text: "14 October 2026" }]]] },
  ],
};
```

### API

#### DocumentExtract

Turns a document into typed data with a model and shows where every value came from. The document sits in a quiet PDF viewer: a slim toolbar with the file name, page count and zoom, and the page as a white A4 sheet (white in dark mode too, like paper) on a slightly darker canvas. An email renders as a message view. The schema's fields sit beside it as an editable form in color groups. Extract streams values in while one soft scan bar passes down the page and each cited span takes a faint tint in its group's color. Hovering, focusing or clicking a field or a span lights both ends and draws one curved connector between them in that color, with a single sheen along it. Low confidence values carry the model's reason and a Looks right button; edits update the JSON tab live. Accept all confirms every value with a short check cascade and hands the typed output to onAccept.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `document` | `SourceDocument` |  | The document to read: { id, name, label, kind?, meta?, blocks }. kind is "pdf" (an A4 sheet with a page count) or "email" (a message view), inferred from the file name when left out. Blocks are masthead (a text wordmark and title), email (subject, sender, recipient, date), heading, paragraph, lines (an address under a label), pairs, meta (a strip of label and value cells), columns, table (with optional detail lines), totals (the strong row sits on a double rule), rule and footer. Text is a string or an array of segments, where { span, text } marks a source span a value can cite. Without it the preview offers its two samples, an invoice and a shipping email. |
| `schema` | `ExtractSchema` | `invoiceSchema` | The fields to fill: { name, title, description?, groups?, fields }. A field is { key, label, type, description?, group? } with type string, date, money, currency, iban, integer or number; a table is { key, label, type: "table", group?, columns }. Each group in groups takes the next series color (--series-1 to --series-4) for its dot, rows, spans and connector; without groups each field takes its own. The Schema tab shows toJsonSchema(schema). |
| `samples` | `{ document: SourceDocument; schema: ExtractSchema }[]` | `sampleDocuments` | Several documents to switch between from a menu on the file name, each with its own schema. Ignored when document is set. |
| `extract` | `(document, schema, { signal }) => AsyncIterable<ExtractEvent> \| Promise<ExtractEvent[]>` |  | Your model call. Yield { type: "value", path, value, source?, confidence, note? } as values arrive, { type: "usage", inputTokens, outputTokens } for the cost readout, and { type: "error", message } or throw to show the failure state. Paths are field keys, or table.row.column for a cell such as lineItems.0.amount; source is the span id. Respect signal; Stop and Escape abort it. Without it the preview simulates the run and fails the first run of the shipping email so Retry can be tried. |
| `onAccept` | `(data: ExtractOutput, detail: { document, schema, values }) => void \| Promise<void>` |  | Called by Accept all after every value turns accepted. data has one key per schema field, typed: dates as YYYY-MM-DD strings, money and numbers as numbers, IBANs without spaces, tables as arrays of row objects. Accept all first asks to fix any value that does not fit its type. Throw to undo the accept. Without it the preview simulates the hand-off and says so. |
| `model` | `ExtractModel` | `{ name: "Claude Haiku 5.5", id: "claude-haiku-5-5", inputPrice: 0.1, outputPrice: 0.5 }` | The model named in the footer. Prices are US dollars per million tokens and drive the cost readout; id is named in the Schema tab. |
| `modelMark` | `ReactNode` | `Claude mark` | The model's mark in the footer. |
| `reviewThreshold` | `number` | `0.8` | Values with a confidence below this are flagged with a warning, show their reason, and count toward the to check summary. |
| `className` | `string` |  | Class on the root element. |

### Dependencies

- `motion`
- `lucide-react`
- `@radix-ui/react-tabs`
- `@radix-ui/react-dropdown-menu`
- `@radix-ui/react-tooltip`

### Keyboard

| Keys | Action |
| --- | --- |
| Tab | Moves through the file menu, the zoom controls and Fit, the page canvas, the output tabs, Extract, each field and table cell, every Looks right button, Review and Accept all. |
| Focus a field | Selects it: the page scrolls to its source span, both ends light in the group's color and the connector draws between them. Tabbing through the form walks the document alongside. |
| Control or Command with = / - / 0 | With the page canvas focused, zooms in, zooms out, or fits the page to the width. |
| Arrow keys | Scroll the focused page canvas and the JSON blocks; on the output tabs and in the file menu they move the selection. |
| Escape | Stops a running extraction. Otherwise clears the selected field. |
| Enter, Space | Activates Extract, Stop, Retry, Review, Looks right, the zoom controls, Fit, the copy buttons and Accept all, and picks a document in the file menu. |

### Accessibility

- The run's state is announced through a polite status region: extracting, done with how many fields need a check, failed with the error, and stopped. Checking a value and accepting speak through a second polite region, including that the preview only simulates the hand-off.
- Confidence is a percent with an icon for every state that matters: a warning for low confidence, a check once checked or accepted, a pencil once edited. Spoken text reads the state and percent, and a flagged value's reason is tied to its input with aria-describedby.
- Every value is a real input with a label. Table cells are inputs inside a table role with column headers, and each cell's name includes its column, row and whether it needs a check.
- The viewer is a labeled region that announces its zoom; icon buttons have names and tooltips, and Fit reports its pressed state. The document switcher is a menu of radio items.
- The connector, the scan bar and the confidence bars are decorative and hidden from assistive technology; the linked field, its status text and the summary carry the same information.
- Values that do not fit their type, such as a date that is not YYYY-MM-DD or an IBAN whose check digits fail, show a message tied to the field, become null in the JSON, and block Accept all with a spoken reason.
- Pointer focus draws no ring; keyboard focus shows Arc's shared focus ring. Inputs show focus with their border.

### Motion

- The connector is one cubic Bezier that draws in over 220ms with round caps in the field's series color; a soft band of light travels along it once, then the line rests. Round anchors sit at both ends and the far one settles in as the line reaches it. It is measured on requestAnimationFrame while shown, so it follows scrolling, zoom and resizing without lag, and fades out in 120ms.
- While extracting, one thin bar of light with a soft trailing fade passes down the page once. Each cited span takes a brief stronger tint as its value lands, then rests at a faint tint; the field's text fades in.
- Zoom eases on the smooth spring around the middle of the canvas, so the point you are reading stays put.
- Accept all turns each field's status into a check with a short stagger and a crisp snappy pop, and the footer bars turn green in the same order.
- Table rows grow in on the smooth spring; reasons for flagged values open and close their height on the same spring. Status lines crossfade (out in 100ms, in over 160ms) inside a container that animates its height. Average confidence and cost roll on a short tween with tabular numerals.
- Reduced motion removes the scan bar, the draw, the sheen, the cascade, flashes and tweens. Selection, tints, the connector, labels and announcements stay, and zoom changes in one step.

### Responsive behavior

- The block caps at 1080px. From 760px of its own width the viewer and the form sit side by side, 600px tall, with the connector between them; the form keeps up to 436px.
- Below 760px the viewer stacks above the form with its own 330px canvas and the form scrolls in 430px below it. The connector hides there, since it would cross the form; the matching tints, the auto scroll to each source and a press on a span that brings its field into view carry the link.
- Fit keeps the A4 sheet at the canvas width, so on a phone the whole page shows and zoom brings the text up. Below 520px the page count and model name drop, field labels narrow, the line items table scrolls sideways inside its own box and Accept all takes the full width.
- The page, the form and the code tabs scroll inside their own panes, so the block never scrolls the page sideways.

### Performance

- Values arrive through one reducer; the form, links, output and JSON lines are derived with memoized maps keyed on the values object.
- Span hover is one delegated pointer listener on the page and one on each JSON block. Span flashes write a data attribute directly instead of re-rendering the document.
- Zoom writes the sheet's scale and size straight to the DOM on each animation frame, so the page never re-renders while it zooms.
- The connector runs one requestAnimationFrame loop only while a link shows, measures two rectangles per frame, and writes path attributes only when they change. The sheen moves three gradient stops; the scan bar is a single transform animation.
- Panes scroll themselves with scrollTo on their own element, never scrollIntoView, so the host page never jumps; the one exception is a press on a span in the stacked layout, which may bring its field into the window.

### Notes for AI agents

- Mark every value the model may cite as a span in the document data, and ask the model to return the span id as source. Without a source a value still fills its field but cannot be linked.
- Ask for a confidence between 0 and 1 and a short note for anything inferred rather than read, such as a due date worked out from payment terms. Notes appear under flagged values.
- Stream values in schema order so the form fills top to bottom. Emit usage events as the stream goes so cost rolls instead of jumping at the end.
- Keep display values as the document writes them (1,400.00, CH56 0483 ...); the block parses them into typed output with parseValue rules.
- Use toJsonSchema(schema) as the model's structured output format so the Schema tab shows exactly what was sent.
- Give the schema up to four groups so each gets its own series color; more groups repeat the colors.
- The preview is fully simulated: scripted values, usage and timing for the two samples, an overloaded_error on the first run of the shipping email, and a simulated hand-off on Accept all.

### Keywords

document extraction, structured output, invoice parsing, pdf viewer, data extraction, ocr, llm extraction, json schema, typed output, confidence, human review, source highlighting, citations, form filling, claude haiku

### Related

- knowledge-base
- ai-answer
- agent-approvals
- model-picker
- text-shimmer

---

## Agent memory

One card for what an assistant remembers about you: filter and search memories, edit or forget one in place, and turn saved memories and chat history on or off.

- Type: Block (composition)
- Access: Pro
- Built from: Avatar, Button, Switch, Text shimmer, Tooltip
- Documentation: https://uiarc.dev/components/blocks/agent-memory

### Overview

Pass memories and the onEdit, onForget and onToggle callbacks to wire your memory store; with no props it shows a sample set.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/agent-memory. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/agent-memory while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- Settings for an assistant that remembers people across chats, where people need to see, filter, search, correct and delete what it knows.
- Showing the moment an assistant saves something from a chat, with a way to see where it was filed.
- Any small personal knowledge store grouped by kind, where each entry is a sentence with a source and an undoable delete.

### When not to use

- Use knowledge-base for documents and files an agent retrieves from, rather than short facts about the user.
- Use context-window to show what fills a single conversation's token budget, rather than what persists across chats.
- Use ai-chat for the conversation itself; this card only receives what the chat noted.
- Use agent-routines for scheduled instructions the agent runs, not facts it recalls.

### Usage

```tsx
import { AgentMemory, type MemoryItem } from "@/components/arc/blocks/agent-memory/agent-memory";

export function MemorySettings({ memories, userId }: { memories: MemoryItem[]; userId: string }) {
  return (
    <AgentMemory
      memories={memories}
      captured={null}
      classify={text => fetch("/api/memory/classify", { method: "POST", body: text }).then(r => r.json()).then(r => r.group)}
      onChange={async (next, change) => {
        if (change.type === "forget") await deleteMemory(userId, change.memory.id);
        else await saveMemory(userId, change.memory); // throw to show the error in place
      }}
      onToggle={(setting, on) => updatePreference(userId, setting, on)}
    />
  );
}

// Offer what the assistant noted in the current chat as a "Memory updated" pill.
<AgentMemory captured={[{ note: "Noted: you prefer pnpm over npm", memory: { id: "m-pnpm", group: "preferences", text: "Prefers pnpm over npm in install commands" } }]} />
```

### API

#### AgentMemory

One card for what an assistant remembers about you. The header shows how full memory is and two switches for saved memories and chat history. A row of filter pills (All, About you, Preferences, Projects, People) and a search button that widens into a field sit over the list, where each memory is one plain sentence; hovering or focusing a row reveals its source and the Edit and Forget actions in reserved space. A Memory updated pill from the current chat files its memory into the right group with a glide and a soft highlight, Forget leaves an undo bar with a countdown, and the field at the bottom sorts a typed memory into its group.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `memories` | `MemoryItem[]` | `sampleMemories` | The saved memories: { id, text, group, source, person? }. text is one sentence without a closing period; group is "about", "preferences", "projects" or "people"; source is { kind: "chat" \| "manual", date (ISO), href? } and reads From a chat or Added by you; person is { name, src? } and shows a small portrait. Newest first within a group. Passing a new array replaces what the card shows, so it can be controlled through onChange. |
| `captured` | `CapturedMemory[] \| null` | `sampleCaptured` | Memories the assistant just noted in the current chat: { note, memory }. The first one not yet filed shows as a Memory updated pill with its note, such as "Noted: you prefer pnpm over npm". Pressing it files the memory into its group (switching the filter or clearing the search first if needed), then the pill reads Saved to Preferences and folds away. Pass null or [] to hide the pill. |
| `onChange` | `(memories: MemoryItem[], change: MemoryChange) => void \| Promise<void>` |  | Called after every change with the full new list and what changed: { type: "capture" \| "add", memory }, { type: "edit", memory, previous } or { type: "forget", memory }. Reject from an add or an edit to show the message in place and keep the old state. Forgets are reported only after their undo window closes. Without it, edits simulate a short save. |
| `onToggle` | `(setting: "savedMemories" \| "chatHistory", on: boolean) => void` |  | Called when either switch changes. |
| `settings` | `{ savedMemories?: boolean; chatHistory?: boolean }` | `both on` | Starting values for the switches. With saved memories off the list dims under a short note and the pill is hidden; each switch's line below its title says what the current setting does. |
| `classify` | `(text: string) => MemoryGroupId \| Promise<MemoryGroupId>` | `guessGroup` | Sorts a typed memory into a group, for example with a model call. The default is a keyword guess that checks people first, then preferences, projects and finally about you, and the status region says the preview guessed with keywords. |
| `groups` | `MemoryGroup[]` | `memoryGroups` | The groups in filter order, each { id, label, empty } where empty is the line a filter shows when its group holds nothing. |
| `capacity` | `number` | `sampleCapacity` | Characters of memory the assistant can hold. The meter shows the share in use, turns to the warning color with an icon at 90%, and the add field refuses new memories when full. The sample sets it so the demo starts 62% full. |
| `assistantName` | `string` | `"Claude"` | The assistant's name in the subtitle and the notes. |
| `undoSeconds` | `number` | `5` | How long a forgotten memory can be restored. |
| `className` | `string` |  | Class on the outer wrapper. |

### Dependencies

- `motion`
- `lucide-react`
- `@radix-ui/react-switch`
- `@radix-ui/react-tooltip`

### Keyboard

| Keys | Action |
| --- | --- |
| Tab | Moves through the two switches, the selected filter pill, the search button, the Memory updated pill, each memory's Edit and Forget buttons (a row's source and actions appear while it has focus), and the add field. |
| Arrow left, Arrow right, Home, End | Move between the filter pills; only the selected pill is a tab stop. |
| Enter, Space | Press the focused control: toggle a switch, file the captured memory, start editing, forget, or restore with Undo. |
| Enter | In the edit field, saves; in the add field, sorts and adds the memory. Shift+Enter adds a line break while editing. |
| Escape | Cancels an edit, or closes the search and clears it. |

### Accessibility

- The card has a level two heading; in the All view and in search results each group has a level three heading with its count, and every group is a labelled group of list items.
- Switches are labelled by their visible titles and described by the line beneath; the meter is a meter role with a text value such as "62% full". Filter pills are toggle buttons with aria-pressed.
- Status is never color alone: the pill reads Memory updated, then Saved to Preferences with a check; the meter's warning pairs color with an icon; the add field shows Added to People with a check or an error with an icon; a paused list carries a note with an icon.
- Icon buttons name the memory they act on, such as "Forget memory: Prefers metric units and 24 hour times", and show a tooltip. Row actions stay visible on touch screens.
- Focus follows each change: into the edit field, back to Edit after saving or cancelling, onto Undo after Forget, back to Forget after Undo, into the search field when it opens and back to the search button when it closes, and to the selected filter when an Undo button times out.
- A polite status region announces captures, adds (including that the preview sorts with a keyword guess), saves, forgets with their undo window, restores, switch changes and the number of search matches.
- Pointer focus draws no ring; keyboard focus shows Arc's shared focus ring, and text fields show focus with their border.

### Motion

- Capture and add: a copy of the new row lifts off the pill or the field and glides to the row's place in its group on the smooth spring (0.4s, no bounce), moving only by transform, while the row's slot opens beneath it. The row's own text takes over as it lands, under a soft tint that fades over about a second. If the memory's group is filtered out or a search is open, the filter switches or the search clears first, then the copy flies.
- Filtering opens and closes groups and rows by height on a critically damped spring (0.32s, no bounce) with a quick fade, so the list closes its gap instead of jumping. The active pill's background glides to the new pill on a 0.26s spring without bounce.
- The search button widens into a field over the pills with a 240ms ease-out width transition while the pills fade out.
- A row swaps between reading, editing and the undo bar with one crossfade (100ms out, 160ms in) while its height follows on the smooth spring. A saved edit crossfades the old sentence into the new one. When the undo countdown ends, the bar folds away.
- Labels that change (a switch's line, the pill, the add status) crossfade in place with at most 2px of rise; the pill keeps its width with an invisible sizer, so nothing shifts. No per-letter, blurred or morphing text.
- The meter's percentage counts in tabular numerals inside a reserved width and the bar scales on the smooth spring. Sorting a typed memory shows a short shimmer on its status. The undo ring drains linearly.
- Reduced motion skips the flight, places heights and rows immediately, stops the shimmer and the ring, and keeps every state, focus move and announcement.

### Responsive behavior

- The card is at most 640px wide and centered; the list scrolls inside a 380px area that fades at an edge only while there is more to see.
- Below 440px of container width the inset tightens, the subtitle wraps under the title next to the meter, and the filter pills scroll sideways with an edge fade, keeping the selected pill in view.
- Row actions and sources show on hover and focus with a mouse and stay visible on touch screens; their space is always reserved, so text never shifts.
- The Memory updated pill truncates its note with an ellipsis on narrow cards; the full text is in its accessible name.

### Performance

- Heights animate through motion values and one ResizeObserver per row; the list's edge fade and the filter fades are toggled as attributes, without React renders per frame.
- The flight moves one absolutely positioned copy by transform; scrolling the list to the landing row runs on the same spring.
- Undo windows share one 200ms interval that runs only while something can be restored.
- Search is a plain substring filter; matches are marked by splitting the text, without regular expressions built from input.

### Notes for AI agents

- Use it as the memory page of an assistant's settings or in a side panel next to a chat. Pass captured={null} when capture happens in your real chat, or pass what the model just noted to offer it as a pill.
- Write memories as one plain third person sentence without a closing period, such as "Prefers metric units and 24 hour times". Keep them under 200 characters; the editor enforces it.
- Set source.kind to "chat" (reads From a chat) or "manual" (Added by you) with an ISO date; add href to link the source to the chat.
- For memories about a person, set group "people" and person { name, src } to show their portrait. Typed memories that name someone in lib/media get that portrait automatically.
- onChange receives the whole list, so you can store it as is, or act on change.type. Reject from add or edit to surface server errors in place. Forget is final only after undoSeconds, which is when onChange reports it.
- The sample shows Claude as the assistant; set assistantName for your own. Do not invent capture claims for real products.

### Keywords

memory, assistant memory, agent memory, saved memories, chat history, personalization, memory updated, remember, forget, undo, filter, settings, preferences, llm, ai, privacy, user profile

### Related

- ai-chat
- ai-side-panel
- knowledge-base
- context-window
- agent-tasks
- agent-routines
- mcp-servers

---

## Agent tasks

A home for background coding agents: start a task on a repository and branch, watch each card move from queued to running to ready for review, and open a pull request from the result.

- Type: Block (composition)
- Access: Pro
- Built from: Button, Kbd, Segmented control, Tooltip
- Documentation: https://uiarc.dev/components/blocks/agent-tasks

### Overview

Pass tasks and onStart to connect your agent runner, and onCreatePullRequest for the review step; with no props it simulates a few runs.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/agent-tasks. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/agent-tasks while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- A product surface where people hand coding tasks to background agents and come back later to review, open a pull request, retry or archive.
- Dashboards for automated maintenance runs, such as dependency upgrades, flaky test fixes or codemods, where each run ends in a branch with a diff and checks.
- Any queue of long running agent jobs where the current step, the elapsed time and a clear finished state matter more than a transcript.

### When not to use

- Use agent-run to follow one live agent run in detail, with its plan, tool calls and output.
- Use code-review when people need to read the diff line by line and leave comments; this block only summarizes the change.
- Use agent-approvals when the agent pauses for a person to approve a risky action before it continues.
- Use agent-routines for scheduled, recurring agent jobs rather than one-off tasks.
- Use ai-composer for a chat style prompt box without a task list.

### Usage

```tsx
import { AgentTasks } from "@/components/arc/blocks/agent-tasks/agent-tasks";

export function BackgroundAgents({ tasks, repositories }) {
  return (
    <AgentTasks
      tasks={tasks}
      repositories={repositories}
      onStart={({ prompt, repo, branch, model }) => api.tasks.create({ prompt, repo, branch, model })}
      onCreatePullRequest={async task => {
        const pr = await api.tasks.openPullRequest(task.id);
        return { number: pr.number, url: pr.html_url };
      }}
      onCancel={task => api.tasks.cancel(task.id)}
      onRetry={task => api.tasks.retry(task.id)}
      onArchive={task => api.tasks.archive(task.id)}
    />
  );
}

// A running task streams its current step; a finished one carries files and checks.
const task = {
  id: "task_8f2",
  title: "Fix the flaky checkout test in CI",
  repo: "arc-ui/web",
  branch: "fix/flaky-checkout-test",
  baseBranch: "main",
  model: "claude-opus-5-5",
  status: "running",
  startedAt: Date.parse("2026-10-20T09:14:00Z"),
  step: "Running tests",
  steps: [{ text: "Installed dependencies with pnpm", state: "done", seconds: 38 }, { text: "Running tests", state: "active" }],
};
```

### API

#### AgentTasks

A home for background coding agents. A composer takes the task, a repository, a branch and a model; Start inserts a card at the top that moves through queued, setting up environment and running, with the live step shimmering, until it is ready for review with a diff stat, the changed file count and the checks. Create pull request turns the button into the PR number with the GitHub mark. Filter tabs with rolling counts split the list into all, running, ready for review and merged; each card expands in place to show its step log and changed files, and running tasks can be cancelled, failed or cancelled ones retried and finished ones archived with undo. Without `tasks` the block runs a simulated demo and says so to assistive technology.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `tasks` | `AgentTask[]` |  | The tasks to show, newest first. Passing it makes the list controlled: nothing is simulated, every action calls back and you update the tasks. Each task has id, title, repo, branch, model (an id from `models`), status, startedAt (epoch ms) and optionally baseBranch, finishedAt, step (the live line), steps, files, checks, pullRequest and error. Leave it out for the demo. |
| `repositories` | `Repository[]` | `sampleRepositories` | Repositories for the composer as { name, branches, defaultBranch }. Picking a repository resets the branch to its default. |
| `models` | `AgentModel[]` | `sampleModels` | Models for the composer chip as { id, name, short, provider }, where provider is "anthropic", "openai" or "google" and picks the mark. The first model is the default. The sample list is Claude Opus 5.5, Claude Sonnet 5.5, Claude Fable 5.1, GPT-6.1 Sol and Gemini 4 Argon. |
| `onStart` | `(request: StartRequest) => void \| Promise<void>` |  | Called with { prompt, repo, branch, model } when someone presses Start or Command Enter. Reject to keep the prompt and show an inline error. In the demo it is called before the simulated run begins. |
| `onCreatePullRequest` | `(task: AgentTask) => PullRequest \| Promise<PullRequest>` |  | Opens a pull request for a task that is ready for review and returns { number, url?, state? }. The button shows a spinner while it runs, then morphs into "PR #number open"; with a url the result is a link. Throw to show Try again. Without it the preview simulates PR #482 onwards. |
| `onCancel` | `(task: AgentTask) => void` |  | Called when someone cancels a queued, setting up or running task. In the demo the run stops and the card reads Cancelled. |
| `onRetry` | `(task: AgentTask) => void` |  | Called when someone retries a failed or cancelled task. In the demo the card restarts from queued in place. |
| `onArchive` | `(task: AgentTask) => void` |  | Called when someone archives a finished task. The card leaves the list right away and an Undo line stays for six seconds; undo only restores it locally, so treat archive as reversible on your side. |
| `defaultFilter` | `"all" \| "running" \| "review" \| "merged"` | `"all"` | The filter tab shown first. |
| `className` | `string` |  | Class on the root element, for width or a max height with your own scrolling. |

### Dependencies

- `motion`
- `lucide-react`
- `@radix-ui/react-dropdown-menu`
- `@radix-ui/react-tooltip`

### Keyboard

| Keys | Action |
| --- | --- |
| Tab | Moves through the task field, the repository, branch and model chips, Start, the filter tabs, then each card's toggle and its actions. |
| Command Enter / Control Enter | In the task field, starts the task. |
| Enter, Space | On a chip, opens its menu. On a card, expands or collapses the step log and changed files. On an action, runs it. |
| Arrow up / Arrow down | Inside an open chip menu, moves between options; Enter picks one and Escape closes the menu and returns focus to the chip. |
| Arrow left / Arrow right, Home, End | On the filter tabs, moves the selection. |

### Accessibility

- Each card's title row is a button with aria-expanded and aria-controls pointing at its details; closed details are inert so their content leaves the tab order.
- Status is never color alone: every state pairs an icon with a label, such as Ready for review, Failed or Checks passed, and the live step is read with its status.
- The diff stat has a spoken label (lines added, removed and files changed); each file and step carries a hidden change or state word before it.
- Elapsed time has a spoken label such as Running for 2 minutes 14 seconds, so the compact 2m 14s is never the only form.
- Starting, finishing, cancelling, retrying, archiving and opening a pull request are announced in a polite status region, including that the preview simulates the run and the PR.
- Focus follows the control that replaced the pressed one: Cancel to Retry, Retry to Cancel, a created PR back to its card, and an archived card to its neighbour.
- Chips are Radix dropdown menus with radio items, so the chosen repository, branch and model are announced as checked. Pointer focus draws no ring; keyboard focus uses Arc's shared ring.

### Motion

- A started task grows in at the top on the critically damped smooth spring and its background flashes the accent tint once, so the eye lands on it.
- The live step shimmers with a calm, linear sweep while the agent works. A new step crossfades in: the old line fades out in about 100ms and the new one fades in over 160ms from 3px below. The sweep stops the moment the run stops.
- Status changes crossfade the state line once. Actions crossfade as a group and their slot follows the new width on the morph spring, which is how Create pull request becomes PR #482 open.
- Filter counts roll up or down with tabular numerals on the snappy spring, and the tab highlight glides on the segmented control's morph spring.
- Expanding a card animates height and opacity together on the smooth spring; new log lines grow in the same way. Archiving collapses the card so the list closes the gap.
- Reduced motion keeps every state, label, announcement and focus move but drops the sweep, the spinner rotation, the travel and the springs; content crossfades quickly or appears at once.

### Responsive behavior

- The block is a single panel up to 760px wide and works from 320px. Layout follows the panel's own width through a container query, not the viewport.
- The composer chips wrap under the task field on narrow panels, the shortcut hint hides below 520px and Start stays at the end of the row.
- Card titles wrap to two lines; the branch truncates first in the meta line; the state line wraps its facts and the actions drop to their own line when there is no room.
- Filter tabs scroll inside their track with edge fades when all four do not fit. The expanded details show steps and changed files side by side from 600px and stack below.

### Performance

- One shared clock ticks once a second only while a task is queued, setting up or running, and stops when nothing runs.
- The demo runs each task on a single chained timer that is cleared on cancel, retry and unmount.
- Collapsed details stay mounted and inert, so reopening a card is instant; counts and filters are derived from the task list on each render without extra state.

### Notes for AI agents

- Use it for asynchronous agent work that ends in a branch: background coding agents, dependency bots, code migration runs. Pass `tasks` from your store and update them from your backend events (queued, setting-up, running with `step`, then ready with `files` and `checks`).
- Statuses: queued, setting-up and running count as Running; ready waits for review (open or not); merged is final; failed shows `error` as the reason and offers Retry; cancelled offers Retry.
- Keep `step` short and concrete, such as "Reading src/billing/invoice.ts" or "Running tests". Push a matching `steps` entry with state "active" so the expanded log matches the card.
- The diff stat and file count are summed from `files`; do not pass totals. Paths render in a monospace font with the directory muted and truncated first.
- A pull request on the task (`pullRequest`) wins over the local result of `onCreatePullRequest`, so once your data has the PR you can return anything.
- Model ids must exist in `models`; the mark comes from the provider. Use current models only, such as Claude Opus 5.5 or Claude Sonnet 5.5.
- This block lists runs and their outcome. Send people to code-review for the full diff and to agent-run for a single live run with its tool calls.

### Keywords

background agents, coding agent, agent tasks, task queue, cloud agent, pull request, diff stat, ci checks, step log, changed files, retry, cancel, archive, repository picker, branch picker, model picker, ai agent dashboard

### Related

- agent-run
- agent-approvals
- agent-routines
- agent-orchestrator
- model-picker
- ai-composer

---

## Agent approvals

One approval card for agents: the waiting tool call reads like a permission prompt with the tool's mark, the agent's reason and its arguments, and you approve, deny or allow it from now on.

- Type: Block (composition)
- Access: Pro
- Built from: Animated counter, Button, Dropdown menu, Kbd, Popover, Text shimmer
- Documentation: https://uiarc.dev/components/blocks/agent-approvals

### Overview

Pass requests and onDecide to connect your agent's permission flow; decisions can apply once or always. With no props it plays a sample queue.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/agent-approvals. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/agent-approvals while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- Human in the loop control for agents that call tools with side effects: deploys, emails, database writes, payments and ticket changes.
- An approvals card in an agent console or side panel where one person reviews, edits and decides tool calls quickly, from the keyboard if they like.
- Products that let people turn repeated approvals into standing rules for one agent or a whole workspace.

### When not to use

- Use agent-run to follow one agent's steps and tool calls live, with an inline confirm inside the run.
- Use mcp-servers to connect tools and set their permissions up front rather than per call.
- Use agent-tasks or agent-orchestrator to plan and watch work across agents, not to gate individual tool calls.
- Use code-review when the thing to approve is a diff with comments.

### Usage

```tsx
import { AgentApprovals } from "@/components/arc/blocks/agent-approvals/agent-approvals";

export function ApprovalPrompt({ pending, rules }) {
  return (
    <AgentApprovals
      requests={pending}
      rules={rules}
      reviewer="Emma Collins"
      workspace="Northwind"
      onDecision={decision => fetch(`/api/approvals/${decision.requestId}`, { method: "POST", body: JSON.stringify(decision) }).then(response => {
        if (!response.ok) throw new Error("The agent did not get your decision. Nothing ran.");
      })}
      onRuleChange={({ type, rule }) => type === "added" ? saveRule(rule) : deleteRule(rule.id)}
    />
  );
}

// One pending request
const request = {
  id: "req-deploy-web",
  agent: { id: "deploy", name: "Deploy agent", model: "Claude Opus 5.5", provider: "anthropic" },
  tool: { id: "vercel.deploy", name: "Vercel", action: "Deploy to production", brand: "vercel" },
  title: "Run `vercel deploy --prod`",
  summary: "Deploy northwind-web to production",
  reason: "The preview passed all 214 checks and the release window opened at 14:00.",
  args: [
    { key: "project", label: "Project", value: "northwind-web", mono: true },
    { key: "commit", label: "Commit", value: "8f3c2a1", mono: true, editable: false },
    { key: "target", label: "Target", value: "production", mono: true },
  ],
  risk: "high",
  requestedAt: "2026-10-20T14:30:00",
};
```

### API

#### AgentApprovals

One approval card for agents. The request on top of the queue reads like an inline permission prompt: the agent's name with its model's mark, how long ago it asked, the tool's real mark with the call in plain words (Run vercel deploy --prod, Send an email with Gmail), the agent's one line reason, the arguments as a key and value list whose values can be edited in place, and the risk as an icon plus Low, Medium or High. Deny, Approve (Enter) and an Always allow menu (this agent, or any agent in the workspace) decide it. The other pending requests wait below as one line rows; clicking a row brings it into focus, and a decision slides the next one up. Always allow sends a rule chip up into the Rules button, whose count rolls, and other waiting requests the new rule covers resolve themselves with a short note. A quiet Rules popover lists the rules with remove buttons, and Resolved expands in place into a log of who decided what and when.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `requests` | `ApprovalRequest[]` | `sample queue` | Pending tool calls in queue order: { id, agent: { id, name, model, provider?: "anthropic" \| "openai" \| "google" }, tool: { id, name, action, brand? }, title, summary, reason, args, risk: "low" \| "medium" \| "high", requestedAt (ISO) }. The first one is in focus. Ids added to a later array join the end of the queue. Leave unset for the simulated demo. |
| `rules` | `ApprovalRule[]` | `sample rules` | Always-allow rules that already skip the ask: { id, tool, scope: "agent" \| "workspace", agent?: { id, name }, createdBy?, createdAt? }. A rule covers a request with the same tool id, and the same agent when its scope is agent. |
| `resolved` | `ResolvedEntry[]` | `sample log` | Earlier decisions for the log, newest first: { id, agentName, tool, summary, outcome: "approved" \| "denied" \| "allowed", edited?, decidedBy, decidedAt }. |
| `reviewer` | `string` | `"Emma Collins"` | The person deciding. Recorded as decidedBy in each decision and in the log. |
| `workspace` | `string` | `"Northwind"` | Workspace name for the workspace-wide Always allow option and the rules list. |
| `title` | `string` | `"Approvals"` | Heading of the card. |
| `onDecision` | `(decision: ApprovalDecision) => void \| Promise<unknown>` |  | Called for every decision with { requestId, outcome, args (edits applied), edited, ruleId?, decidedBy, decidedAt }, including requests a new rule covered (outcome "allowed"). Return a promise to keep the request in its sending state; a rejection shows the error with Retry and Deny, using the Error's message when it has one. Without it, delivery is simulated and the card says so. |
| `onRuleChange` | `(change: { type: "added" \| "removed"; rule: ApprovalRule }) => void` |  | Called when Always allow adds a rule or one is removed from the Rules popover. Persist rules here. |
| `className` | `string` |  | Class on the root element. |

#### ApprovalRequest

One pending tool call.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` | `string` |  | The call in plain words, shown large. Wrap code in backticks to set it in the mono face, for example "Run `vercel deploy --prod`" or "`UPDATE` 1,284 rows in PostgreSQL". |
| `summary` | `string` |  | A short label for the queue row and the log, for example "Deploy northwind-web to production". |
| `reason` | `string` |  | The agent's one line reason for the call. |
| `tool` | `ApprovalTool` |  | { id, name, action, brand? }. id is the permission rules match on (vercel.deploy); action names the permission in the rules list (Deploy to production); brand picks a built-in mark: vercel, gmail, postgresql, linear, github, sentry or stripe. |
| `args` | `ApprovalArgument[]` |  | The arguments as rows: { key, label, value, editable? (default true), mono?, multiline? }. Editable values turn into a field on click; multiline ones edit in a growing textarea. |
| `risk` | `"low" \| "medium" \| "high"` |  | Shown as a shield icon in the success, warning or danger color plus the word. |

### Dependencies

- `motion`
- `lucide-react`
- `@radix-ui/react-dropdown-menu`
- `@radix-ui/react-popover`

### Keyboard

| Keys | Action |
| --- | --- |
| j / k | Bring the next or previous pending request into focus. |
| a or Enter | Approve the request in focus. Enter approves while focus is on the card, not on a button or field. |
| d | Deny the request in focus. |
| Enter / Escape | In an argument field, Enter saves and Escape restores the value (Command or Control with Enter in a multiline field). Focus returns to the value. |
| Tab | Moves through the Rules button, the editable values, Deny, Always allow and Approve, the queue rows and the Resolved toggle. |
| Arrow keys, Escape | Inside the Always allow menu and the Rules popover, move between items and close, with focus back on the trigger. |

### Accessibility

- The request in focus is a group named by its title, inside a region that takes focus after each decision, so the shortcuts keep working when the buttons that were pressed leave.
- Shortcuts answer anywhere in the card, and after a click in it left focus on the page, but stay quiet in fields, the menu and the popover, so typing an edited value never approves anything.
- Risk is a shield icon in its status color plus the word Low, Medium or High (with risk added for screen readers). Outcomes in the card and the log are an icon plus a word: Approved, Denied, Allowed by rule, Not sent.
- Every decision, edit, new rule, removed rule and failure is announced in a polite status region, and the demo says that nothing reached a real agent.
- Editable values are buttons named with their label, value and Edit; edited rows add a hidden "edited" to the label and a named Restore button.
- Queue rows are buttons with the agent, the summary and the risk in their name. The Resolved toggle carries aria-expanded and aria-controls.
- Pointer focus draws no ring; keyboard focus shows Arc's shared focus ring.

### Motion

- Bringing a queued request into focus is one crossfade of the request (the old one fades out in 100ms, the new one fades in over 200ms from 3px) while the card's height follows on a critically damped spring and the row closes its gap. Nothing bounces.
- After a decision the next request slides up: it rises 14px into place on the same spring as its row collapses below.
- Always allow sends a small rule chip from the menu up into the Rules button on an ease-in-out path, then the button's count rolls and a faint accent wash fades out of it. Covered rows swap their risk for Allowed by rule with one crossfade and collapse a moment later.
- Sending shows a calm text shimmer that stops when the agent answers. The pending, rules and resolved counts roll with tabular numerals.
- Reduced motion drops travel, the chip flight and the shimmer: requests, rows and labels change in place with every state, focus move and announcement kept.

### Responsive behavior

- One card up to 640px wide that fills narrower containers; it holds without horizontal scroll from 320px up.
- Below a 540px container the shortcut hints and the agent names in the queue hide, since touch is the likely input there.
- Below 440px the model name and the word risk drop out of the meta line, argument labels sit above their values, the Enter key cap leaves the Approve button and queue rows keep the marks, the summary and a short status.
- Long titles wrap, while row summaries and log entries truncate with the full text still in their accessible names or titles.

### Performance

- Only the request in focus renders its arguments and actions; queued requests are one row each.
- Timers for simulated delivery, settling and rule matches are tracked and cleared on unmount, and async callbacks read the latest state from a ref instead of re-subscribing.
- The relative times share one 15 second clock through useSyncExternalStore, so the card re-renders a few times a minute at most.
- Height changes are measured with one ResizeObserver per animated slot and animate only that slot.

### Notes for AI agents

- Write title as the call itself in a few words and summary as a short row label. Backticks in title render code in the mono face.
- Use real agent and model names and set provider so the right mark shows (anthropic, openai or google); any other value shows a neutral bot mark.
- Give each permission a stable tool id (vercel.deploy, gmail.send). Rules match on it, so several requests for the same permission are covered by one rule.
- Keep the reason to one line in the agent's voice and put anything a person might change into args. Mark values that must not change with editable: false.
- onDecision receives the edited argument values. Apply those, not the originals, and keep edited in your audit trail.
- Always allow both approves the request in focus and creates the rule; requests the rule then covers arrive through onDecision with outcome "allowed" and the rule id.
- Return a rejected promise from onDecision to show the error state; the Error's message is shown to the person.

### Keywords

agent approvals, human in the loop, tool call approval, permission prompt, approve deny, always allow, agent permissions, rules, audit log, keyboard shortcuts, ai agent, mcp, guardrails, risk level, editable arguments

### Related

- agent-run
- agent-tasks
- agent-orchestrator
- agent-routines
- mcp-servers

---

## Agent routines

Scheduled agents in one card: each routine reads as a sentence with its schedule, next run countdown, connectors and destination, and opens smoothly to edit or run it now.

- Type: Block (composition)
- Access: Pro
- Built from: Button, Input, Popover, Segmented control, Select, Switch, Text shimmer, Tooltip
- Documentation: https://uiarc.dev/components/blocks/agent-routines

### Overview

Pass routines with onToggle, onRun and onChange to wire your scheduler; with no props it shows sample routines with live countdowns.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/agent-routines. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/agent-routines while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- Settings or automation screens where people schedule agents to run on their own and post results to Slack.
- A card on a dashboard that shows at a glance which scheduled agents are healthy, which failed and when each runs next.
- Products that let people create automations from a sentence and confirm the parsed schedule, sources and destination.

### When not to use

- Use agent-run to watch a single agent work through a task in real time with its tool calls.
- Use agent-tasks for a queue of one-off jobs that run once rather than on a schedule.
- Use agent-approvals when the agent's output needs a person to approve it before anything is posted.
- Use agent-orchestrator to show several agents handing work to each other within one run.

### Usage

```tsx
import { AgentRoutines, type Routine } from "@/components/arc/blocks/agent-routines/agent-routines";

export function Routines({ routines }: { routines: Routine[] }) {
  return (
    <AgentRoutines
      routines={routines}
      onRun={async routine => {
        const result = await api.routines.run(routine.id); // { id, status, summary, durationMs, report }
        return {
          run: { id: result.id, status: result.status, at: Date.now(), summary: result.summary, durationMs: result.durationMs },
          report: result.report,
        };
      }}
      onToggle={(id, enabled) => api.routines.update(id, { enabled })}
      onSave={(routine, { created }) => created ? api.routines.create(routine) : api.routines.update(routine.id, routine)}
    />
  );
}

// A routine
const triage: Routine = {
  id: "morning-triage",
  name: "Morning triage",
  instruction: "Read new Linear issues, match them to Sentry errors and post a ranked list to #triage.",
  schedule: { frequency: "weekdays", time: "09:00" },
  sources: ["linear", "sentry"],
  destination: "#triage",
  model: "claude-sonnet-5-5",
  enabled: true,
  steps: ["Reading new Linear issues", "Matching Sentry errors", "Ranking by customer impact", "Posting to #triage"],
  history: [{ id: "r-1", status: "success", at: "2026-10-19T09:00:00", durationMs: 41000, summary: "Triaged 9 issues, 2 urgent" }],
  report: "Triage for Monday 19 October\n- ENG-2141 Checkout button stays disabled. Urgent, assigned to Priya.\n9 issues reviewed, 2 urgent.",
};
```

### API

#### AgentRoutines

Scheduled agents in one card. Each row reads as a sentence: the routine's name and an on and off switch, its schedule in plain words with a live countdown to the next run and the last run on the right, then the connectors it reads, the Slack destination and the model as small colored marks in a fixed slot that never wraps, beside its last 14 runs as small tinted ticks with a tooltip each. Run now sits in a reserved slot that shows on hover or focus; a run fills a thin line under the row in the routine's series color, shimmers a Running label with the current step, then slides a new tick into the history and updates the last run. Clicking a row opens it in place, one at a time, with the latest run's output as a short formatted report, the instruction prompt and a compact schedule editor. New routine opens an inline row where a sentence is read into editable chips for the schedule, sources and destination.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `routines` | `Routine[]` | `four sample routines` | The routines: id, name, instruction, schedule ({ frequency: "hourly" \| "daily" \| "weekdays" \| "weekly", time: "HH:MM", day?: 0-6 }), sources (connector ids: linear, github, sentry, google-calendar, notion), destination ("#channel" or "Direct message"), model (claude-opus-5-5, claude-sonnet-5-5, claude-haiku-5-5, gpt-6-luna, gemini-3-8-flash), enabled, history (oldest first), an optional report, optional step labels and an optional accent (1 to 4, the series color for its progress). Passing a new array replaces the list; changes made in the card are kept until then. |
| `onRun` | `(routine: Routine) => Promise<RoutineRunResult> \| RoutineRunResult \| void` |  | Called when a run starts, from Run now or when a schedule comes due while the card is open. Return a promise of { run, report? } to drive the row from your backend: the steps advance while it is pending, the result lands when it resolves, and a rejection shows its message as the error. Return nothing to keep the built-in simulation, which says so in the status region. |
| `onToggle` | `(id: string, enabled: boolean) => void` |  | Called when a routine's schedule switch changes. |
| `onSave` | `(routine: Routine, meta: { created: boolean }) => void` |  | Called with the full routine when its schedule changes in the open row, and with created: true when New routine adds one. |
| `now` | `number \| Date` |  | The current time for countdowns and run times. Without it the card uses a demo clock that starts on Tuesday 20 October 2026 at 6:45 when no routines are passed, and the real clock otherwise. |
| `defaultOpenId` | `string \| null` | `null` | The routine that starts open. Opening another closes it. |
| `title` | `string` | `"Routines"` | The card title, also the list's accessible name. |
| `className` | `string` |  | Class on the root element. |

### Dependencies

- `motion`
- `lucide-react`
- `@radix-ui/react-switch`
- `@radix-ui/react-tooltip`
- `@radix-ui/react-popover`
- `@radix-ui/react-select`

### Keyboard

| Keys | Action |
| --- | --- |
| Tab | Moves through New routine, then for each row the routine name, Run now, the schedule switch and the run ticks, then the open row's schedule editor. |
| Enter, Space | On a routine name, opens or closes the row. On Run now, starts a run; while it runs the same button stops it. |
| Arrow up / Arrow down, Home, End | On a routine name, moves focus to the previous, next, first or last routine. |
| Arrow left / Arrow right, Home, End | Inside the run ticks, moves between runs; each run shows its result, time, duration and summary in a tooltip. In the frequency control, changes the frequency. |
| Enter | In the New routine sentence field, adds the routine. A sentence typed a moment ago is read at once. |
| Escape | In the sentence field, cancels New routine and returns focus to its button. In a chip's popover, closes the popover. |

### Accessibility

- Each routine name is a real button with aria-expanded; the rest of the row also opens it on click, while Run now, the switch and the ticks stay separate controls.
- Status is never color alone: the last run pairs an icon with its time, each tick has a full text label and a tooltip with an icon and a label, and the strip is a group named with its counts (for example 12 succeeded, 1 failed, 1 skipped).
- Connector, destination and model marks are hidden from assistive technology and replaced by one sentence per row: what it reads, where it posts and which model runs it.
- The run ticks are one tab stop with a roving index, so a list of routines does not add 14 stops per row.
- Run starts, results, failures, stops, toggles, schedule changes and new routines are announced in a polite status region, including that the preview only simulates runs and Slack posts.
- While a run is in progress the open row lists its steps as an ordered list with the current step marked aria-current="step"; a failure is announced as an alert with the step and the error.
- The sentence parser's state and the simulation note sit in a polite live region. Chips are buttons named with their field and value, and their popovers use pressed buttons for sources and the destination.
- Pointer focus draws no ring; keyboard focus shows Arc's shared focus ring.

### Motion

- A row opens from height 0 to auto and back on a critically damped spring (about 340ms, no bounce). Opacity starts a beat after the height and ends a beat before it on close, the content rises 6px into place, and the chevron and the row's quiet tint change on the same timing. Opening one row closes the other at the same time, and the rows below glide with the height.
- While a row is open its height keeps following its content on the same spring, so a streamed report or the step list never resizes the card in one frame.
- Run now fills a 2px line under the row at the pace of the steps, in the routine's series color, then the line fades. A new tick slides in from one slot to the right while the others tween one slot left and the oldest fades out, on a 240ms ease-out tween. Ticks sit in fixed slots and never measure layout, so they do not drift while rows open or close.
- Labels change with one minimal crossfade: the old one fades out in 100ms and the new one fades in over 160ms from 2px below. A schedule change slides the text after it as its width follows on a critically damped spring. The countdown uses tabular numerals in a reserved width.
- The Running label and the active step carry a calm shimmer that stops when the run ends. Run now and Stop share one button and one width, so the swap never resizes it.
- The latest report streams in chunks of 15 to 40 characters every 32ms on a requestAnimationFrame clock; each new chunk only fades in and settled text never re-renders.
- Reduced motion opens, closes, shifts and swaps at once and keeps every state, label and announcement; the shimmer stops and streamed chunks appear without the fade.

### Responsive behavior

- The card is up to 680px wide and reads the same at 360px: every row keeps its three lines, and the marks slot and ticks never wrap.
- Below 540px of card width the last run moves out of line two (it stays in the ticks' tooltips and the open row), and the insets tighten.
- Below 420px Run now and Stop become icon buttons with the same accessible names, and the schedule's time field takes its own line.
- Long step labels and destinations truncate with an ellipsis; the full text is in the open row, the tooltips and the status region.

### Performance

- One shared one second clock drives every countdown; nothing else re-renders on a timer.
- Runs are cancelled with an AbortController when stopped or when the card unmounts, so no timers outlive it.
- Ticks animate only transform and opacity in fixed slots; nothing in the list uses layout animation.
- Closed rows unmount their details, so a long list only renders one report and one schedule editor.
- Brand marks are inline SVG components in the block's folder; the Gemini mark scopes its gradient ids per instance.

### Notes for AI agents

- Choose it for agents that run on a schedule and report back: daily triage, weekly digests, hourly watchers, meeting briefs. One row per routine; keep names short and specific so the first line never truncates.
- Schedules are four plain shapes (hourly at a minute, daily, weekdays, weekly on a day) with 24 hour times. The card derives the plain words, the cron expression and the next run in local time.
- History is oldest first and only the last 14 runs show. Use status skipped for runs that found nothing to post, so the strip separates quiet runs from failures.
- The report is short plain text: the first line is the title, lines starting with "- " become list items and other lines become paragraphs. Issue keys like ENG-2141, pull requests like #1842 and channels like #eng are set apart.
- Rows show up to three source marks; with four or more they show two and a +N count whose tooltip names the rest. Give each routine step labels that match what your agent really does, so the progress is honest.
- New routine parsing is a local, simulated pattern match and says so. In production, send the sentence to a model and keep the chips as the confirmation step before onSave.

### Keywords

scheduled agents, agent routines, cron, automations, recurring tasks, ai agent schedule, run history, slack digest, triage bot, agent runs, natural language schedule, workflow automation

### Related

- agent-run
- agent-tasks
- agent-approvals
- agent-orchestrator
- mcp-servers
- model-picker
- research-run
- text-shimmer

---

## Agent orchestrator

A lead agent splits a goal into a plan, fans the subtasks out to parallel worker lanes and merges what comes back, with each lane's model, progress and result in view.

- Type: Block (composition)
- Access: Pro
- Built from: Button, Copy button, Segmented control, Text shimmer
- Documentation: https://uiarc.dev/components/blocks/agent-orchestrator

### Overview

Pass a goal and run, which emits plan, dispatch, progress and result events, to show a real orchestration; with no props it plays a sample run.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/agent-orchestrator. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/agent-orchestrator while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- Showing a multi agent run where a lead model splits a task across subagents, such as research, audits, migrations or comparisons.
- Debug or observability panels that need per worker progress, tool calls, errors, retries, tokens and cost in one view.
- Explaining the cost and speed tradeoff of parallel agents, with a live concurrency control.

### When not to use

- Use agent-run for a single agent working through steps in one thread.
- Use agent-plan when the job is to review and edit a plan before anything runs.
- Use research-run for a single research answer with sources and citations.
- Use agent-tasks to track many independent background tasks that do not merge into one result.
- Use model-router when one request is routed to one model rather than split across several.

### Usage

```tsx
import { AgentOrchestrator, type OrchestratorRun } from "@/components/arc/blocks/agent-orchestrator/agent-orchestrator";

// Yield events from your orchestrator. The block handles timing, pulses, queues and totals.
const run: OrchestratorRun = async function* ({ goal, workers, concurrency, signal }) {
  const plan = await planWithLead(goal, workers);           // your lead model call
  for (const subtask of plan) yield { type: "plan", subtask };

  for await (const update of runWorkers(plan, { concurrency, signal })) {
    // update.kind: "dispatch" | "tool" | "toolDone" | "text" | "usage" | "error" | "retry" | "result"
    if (update.kind === "dispatch") yield { type: "dispatch", subtaskId: update.id };
    if (update.kind === "tool") yield { type: "tool", subtaskId: update.id, tool: update.tool, target: update.target };
    if (update.kind === "text") yield { type: "output", subtaskId: update.id, delta: update.text, newLine: update.first };
    if (update.kind === "usage") yield { type: "usage", subtaskId: update.id, tokens: update.tokens, cost: update.cost };
    if (update.kind === "error") yield { type: "error", subtaskId: update.id, message: update.message, retryInMs: 2000 };
    if (update.kind === "result") yield { type: "result", subtaskId: update.id, text: update.text };
  }

  for await (const delta of streamSummary(signal)) yield { type: "summary", delta };
  yield { type: "done" };
};

export function PricingReview() {
  return (
    <AgentOrchestrator
      goal="Compare our pricing page with four competitors and suggest changes"
      run={run}
      defaultConcurrency={3}
      onComplete={result => saveReport(result.summary, result.cost)}
    />
  );
}
```

### API

#### AgentOrchestrator

A lead agent splits a goal into a plan, fans the subtasks out to parallel worker lanes and merges what they return. The lead writes its plan one subtask at a time, then dispatches each subtask down a connector to its lane; a short pulse runs the connector on dispatch and again when the result comes back. Each lane shows its model, subtask, the current tool (web search, fetch page, read file, write findings), one line of streaming output, rolling tokens and cost, and elapsed time; a lane that fails counts down to a retry. When every lane has returned, the lead streams a summary and a totals row compares the wall time with running every subtask in sequence. A concurrency limit from 1 to 4 holds extra lanes in a visible queue, and clicking a lane opens its compact transcript. Lanes sit side by side on wide cards and stack under a trunk on narrow ones; the connectors are measured from the real layout and follow either arrangement.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `goal` | `string` | `"Compare our pricing page with four competitors and suggest changes"` | What the lead agent is asked to do. Shown as the card heading and passed to the run hook. |
| `plan` | `OrchestratorSubtask[]` | `samplePlan` | Subtasks passed to the run hook: { id, title, instruction?, workerId? }. The title heads the lane; the instruction is the line the lead writes in its plan. The built in simulation writes this plan; your own hook may yield a different one with plan events. |
| `workers` | `OrchestratorWorker[]` | `Claude Sonnet 5.5, Claude Haiku 5.5, Gemini 3.8 Flash, GPT-6 Luna` | The worker lanes in order: { id, name, mark? }. A subtask lands on the worker named by its workerId, or on the next free worker. Up to four lanes sit side by side; more always stack. |
| `lead` | `{ name: string; mark?: ReactNode }` | `Claude Opus 5.5` | The lead agent shown at the top of the flow and again on the summary. |
| `run` | `(context: OrchestratorRunContext) => AsyncIterable<OrchestratorEvent>` | `simulateOrchestration` | The run hook. It receives { goal, plan, workers, concurrency(), signal } and yields events: plan, dispatch, tool, toolResult, output, usage, error, retry, result, fail, summary and done. An async generator is the simplest way to write one. The signal aborts on Stop, on Run again and on unmount. Without it the block plays a local simulation and says so in its status region. |
| `concurrency` | `number` |  | Controlled concurrency limit from 1 to 4. Leave it out to let the built in control own the value. |
| `defaultConcurrency` | `number` | `number of workers, at most 4` | Starting limit when uncontrolled. |
| `onConcurrencyChange` | `(value: number) => void` |  | Called when someone picks a new limit. The run hook reads the live value through context.concurrency(), so raising it mid run releases queued lanes at once. |
| `autoStart` | `boolean` | `true` | Starts the first run when the block scrolls into view. Never starts on its own with reduced motion; the Run button is always there. |
| `onComplete` | `(result: OrchestratorResult) => void` |  | Called once per finished run, after the summary has landed, with { summary, tokens, cost, wallMs, sequentialMs, speedup, lanes }. Each lane reports its subtask, worker, status, text, tokens, cost and time. |
| `className` | `string` |  | Class on the root element. |

#### simulateOrchestration

The default run hook, exported so you can read the event order it produces or wrap it. It plans four subtasks, dispatches them up to the live concurrency limit, runs each lane through scripted tool calls with token usage, fails one fetch with a 503 and retries it after two seconds, then streams the lead's summary. Prices for Claude models are list prices; the others are illustrative sample values.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `context` | `OrchestratorRunContext` |  | { goal, plan, workers, concurrency, signal }, as passed by the component. |

### Dependencies

- `motion`
- `lucide-react`

### Keyboard

| Keys | Action |
| --- | --- |
| Tab | Moves through the concurrency control, the Run or Stop button, each lane, and the copy summary button once a run is done. An open transcript has no controls of its own. |
| Arrow left / Arrow right | On the concurrency control, picks a lower or higher limit. Home and End pick 1 and the maximum. |
| Enter, Space | On a lane, opens or closes its transcript. On Run, starts a run; while running the same button stops it; afterwards it runs again. |

### Accessibility

- The goal is the card heading, and the lead, the plan and the summary are labelled sections, so the flow reads top to bottom in the order the work happens.
- Each lane is a button with aria-expanded and aria-controls, named by its subtask, model and status. A closed transcript is inert, so it leaves the reading order.
- Status never rests on color: every lane state pairs a glyph with a word (waiting, planned, queued with its place in line, starting, the running tool, failed with a retry countdown, returned, gave up, stopped).
- A polite status region announces planning, dispatch, errors and retries, each returned lane, the start of the summary and the final totals, and says that the default run is a simulation.
- Connectors and pulses are decorative and hidden from assistive technology; the plan's colored dots repeat information that the lane titles already give.
- Pointer focus draws no ring; keyboard focus shows Arc's shared focus ring, inset on lanes so it follows their corners.

### Motion

- Plan items grow in one by one on a critically damped spring and their text streams in chunks of a few words that only fade in.
- A dispatch sends a short colored packet down the connector to the lane; a returning result sends one from the lane to the summary. The simulation waits for the packet to land before the lane starts, so cause always comes before effect.
- A lane's branch and port take its series color when work reaches it; queued branches stay dashed with a hollow port.
- Tool, status and output swaps are one minimal crossfade: the old label fades out in 100ms while the new one fades in over 160ms from 2px below. Running labels carry a calm shimmer that stops when the lane settles.
- One line of output streams on a steady requestAnimationFrame clock and glides left under a soft edge when it outgrows the lane, so the newest words stay in view; settled lines rest at the start with an ellipsis.
- Tokens and cost count to each new value with tabular digits; elapsed times tick in tenths.
- Transcripts and the totals row open with height and opacity on a spring without bounce.
- Reduced motion removes pulses, spinners, shimmer, chunk fades and height travel, keeps every state, label and announcement, and never starts a run on its own.

### Responsive behavior

- Above 720px of card width, up to four lanes sit side by side; the trunk drops from the lead into a bus above them and their results merge on a second bus into the summary.
- Below that, lanes stack under a single trunk in the lead's column with a short branch into each lane, and the same pulses run down and back along it.
- Connectors are measured from the rendered layout with a ResizeObserver, so they follow wrapping text, an opened transcript and container resizes without breakpoints of their own.
- Below 440px the side padding tightens, the concurrency label and the lead's elapsed time are hidden, and the totals fall into two columns. It holds at 320px without horizontal scroll.

### Performance

- The run hook's events go through one reducer; nothing renders per animation frame except the chunk clock of a line that is streaming.
- Token and cost counters write their text straight to the DOM through motion values, so a busy run does not re-render lanes for every tick.
- Pulses are single SVG paths animated with the Web Animations API on stroke-dashoffset and removed when they finish.
- Connector geometry is recomputed only when an observed size changes and is skipped when nothing moved.

### Notes for AI agents

- Choose it when one model plans and several models work in parallel, and the reader needs to see who is doing what, what failed, and what parallelism saved.
- Write the run hook as an async generator. Yield plan events first, then dispatch before a lane's first tool event, then result (or fail) for every dispatched subtask, then summary deltas and done.
- Respect context.concurrency() before each dispatch. The block shows a lane as queued only while every slot is taken, so a hook that ignores the limit will simply show no queue.
- usage events are increments, not totals. Leave out subtaskId for the lead's own tokens; they count toward the totals row but not toward any lane.
- output deltas append to the lane's line; set newLine on the first delta of a new step. The block smooths bursty deltas into a steady stream.
- The sequential estimate is the wall time minus the parallel stretch plus every lane's own time from dispatch to return, so concurrency 1 reads as about the same as running in sequence.
- Company names, prices and pages in the sample are fictional. Prices for non Anthropic models are illustrative sample values.

### Keywords

multi agent, orchestrator, subagents, parallel agents, fan out, fan in, lead agent, agent workflow, concurrency, tool calls, token usage, cost, retry, agent observability, claude, ai agents

### Related

- agent-run
- agent-plan
- agent-tasks
- research-run
- agent-loop
- mixture-of-experts
- agent-status

---

## MCP servers

Manage the MCP servers that give an agent its tools: see what the enabled tools cost in context, connect or pause a server, and switch single tools on or off.

- Type: Block (composition)
- Access: Pro
- Built from: Animated counter, Avatar, Button, Input, Search field, Segmented control, Switch, Text shimmer
- Documentation: https://uiarc.dev/components/blocks/mcp-servers

### Overview

Pass servers with onToggle and onConnect to wire your MCP client; with no props it shows sample servers with real marks.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/mcp-servers. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/mcp-servers while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- Settings for an agent or AI assistant that connects to MCP servers: which servers it has, which tools are on and what they cost in context.
- Onboarding a new integration with a directory, sign in and tool discovery in one place.
- Keeping tool definitions inside a context budget by switching off tools the agent does not need.

### When not to use

- Use agent-approvals to approve or deny individual tool calls while the agent runs.
- Use context-window to show everything in the context window, not only tool definitions.
- Use agent-run to follow an agent's steps and tool calls live.
- Use knowledge-base to manage documents an agent retrieves from, rather than tools it calls.

### Usage

```tsx
import { McpServers } from "@/components/arc/blocks/mcp-servers/mcp-servers";

export function AgentTools({ servers, directory }) {
  return (
    <McpServers
      servers={servers}
      directory={directory}
      budget={8000}
      clientName="Northwind agent"
      account={{ name: "Emma Collins", email: "emma@northwind.dev", avatar: "/media/people/emma-collins.svg" }}
      onToggleTool={(serverId, toolId, enabled) => saveTool(serverId, toolId, enabled)}
      onPermissionChange={(serverId, permission) => savePermission(serverId, permission)}
      onConnect={async ({ kind, serverId, endpoint }) => {
        if (kind !== "url" && kind !== "retry") await openOAuthWindow(serverId);
        const response = await fetch(`/api/mcp/${serverId}/tools`, { method: "POST", body: JSON.stringify({ endpoint }) });
        if (!response.ok) throw new Error("The server closed the connection during tools/list.");
        return response.json(); // [{ id, name, access, tokens }]
      }}
      onRemove={serverId => fetch(`/api/mcp/${serverId}`, { method: "DELETE" })}
    />
  );
}

// One server
const github = {
  id: "github",
  name: "GitHub",
  brand: "github",
  transport: "remote",
  endpoint: "https://api.githubcopilot.com/mcp/",
  status: "connected",
  permission: "allow-reads",
  tools: [
    { id: "search_code", name: "search_code", access: "read", tokens: 420, enabled: true },
    { id: "create_pull_request", name: "create_pull_request", access: "write", tokens: 640, enabled: true },
    { id: "merge_pull_request", name: "merge_pull_request", access: "write", tokens: 360, enabled: false },
  ],
};
```

### API

#### McpServers

Manages the MCP (Model Context Protocol) servers that give an agent its tools. The header shows what the enabled tool definitions cost in context ("18 tools · 6.4k tokens of context") over a bar with one segment per server and a budget that turns the overflow amber. Each server row has its real mark, a status with icon and label (Connected, Needs sign in, Error), the transport (Remote or Local), how many tools are on and their token cost. Expanding a row lists its tools with a switch, a read or write label and a per tool token cost, the default for tool calls (Ask every time or Always allow reads), the endpoint and Remove. Toggling a tool rolls the numbers and resizes its segment. Add server opens a sheet inside the card with a searchable directory and a custom URL field. Choosing a server runs the connect flow in the same sheet: a labelled, simulated authorize screen, then discovering tools as they arrive, then the new server slides into the top of the list. Servers that need sign in reconnect through the same sheet, servers in error retry in place, and Remove comes with Undo.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `servers` | `McpServer[]` | `sample servers` | The agent's servers: { id, name, brand?, transport: "remote" \| "local", endpoint?, status: "connected" \| "needs-auth" \| "error", error?, permission?: "ask" \| "allow-reads", scopes?, tools: McpTool[] }. Only enabled tools of connected servers count toward context. Leave unset for the simulated demo; passing a new array replaces the list. |
| `directory` | `McpDirectoryEntry[]` | `sample directory` | What Add server offers: { id, name, brand?, description (one line), transport, endpoint?, auth: "oauth" \| "none", scopes?, tools }. OAuth entries show the authorize step first. Entries whose id is already in the list read Added. |
| `budget` | `number` | `8000` | Tokens of context you are willing to spend on tool definitions. The bar spans the budget; past it the bar rescales, the overflow turns amber and the label says how far over it is. |
| `title` | `string` | `"MCP servers"` | Heading of the card. |
| `clientName` | `string` | `"Northwind agent"` | Your agent's name on the authorize screen. |
| `account` | `{ name: string; email: string; avatar?: string }` | `Emma Collins` | The signed in person shown on the authorize screen. |
| `onToggleTool` | `(serverId: string, toolId: string, enabled: boolean) => void` |  | Called when a tool is switched on or off in a server's list. |
| `onConnect` | `(request: McpConnectRequest) => void \| McpTool[] \| Promise<void \| McpTool[]>` |  | Called when a server connects, with { kind: "directory" \| "url" \| "reconnect" \| "retry", serverId, name, transport, endpoint? }. For OAuth servers it runs when Authorize is pressed, so open your consent window here. Resolve with the tools the server reported (enabled is optional; reads default on, writes off); resolve with nothing to use the directory's tools. A rejection shows the error with Try again, using the error's message. Without it, the whole flow is simulated. |
| `onRemove` | `(serverId: string) => void` |  | Called once a removal's undo window closes (about 6 seconds, paused while the pointer or focus rests on the bar), or when another remove starts. |
| `onPermissionChange` | `(serverId: string, permission: "ask" \| "allow-reads") => void` |  | Called when a server's default for tool calls changes. |
| `className` | `string` |  | Class on the root element. |

#### McpTool

One tool a server reports.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` |  | Stable id, usually the tool name. |
| `name` | `string` |  | The name the model sees, for example create_issue. Shown in the mono face. |
| `access` | `"read" \| "write"` |  | Read tools only fetch; write tools change something. Shown as an icon and a word, and used by Always allow reads. |
| `tokens` | `number` |  | Tokens the tool's name, description and input schema take in context. Count them with your provider's token counting endpoint. |
| `enabled` | `boolean` |  | Whether the tool is loaded into the agent's context. |

### Dependencies

- `motion`
- `lucide-react`
- `@radix-ui/react-switch`

### Keyboard

| Keys | Action |
| --- | --- |
| Enter, Space | On a server row, opens or closes its tools. On a tool switch, turns the tool on or off. |
| Arrow down / Arrow up | Moves between server rows. Home and End jump to the first and last row. |
| Arrow left / Arrow right | Changes the default for tool calls in an open row. |
| Command or Control + Z | Undoes the last remove while the Undo bar shows. |
| Arrow down / Arrow up in the sheet | Moves from the search field into the directory and between entries, and back up to the field. |
| Escape | Closes the sheet and returns focus to what opened it. Tab stays inside the sheet while it is open. |

### Accessibility

- Each server row is a button with aria-expanded and aria-controls, named with the server, its status, transport, tools on and token cost.
- Status is an icon in its semantic color plus a word (Connected, Needs sign in, Error, Connecting), never color alone. Read and write tools carry an eye or pen icon and the word; below 400px the word stays for screen readers only.
- The context bar is a meter with a value text such as "6,400 of 8,000 budgeted tokens", and over budget adds how far over it is beside a warning icon.
- Every tool switch is named with the tool, its access and its token cost, and the tool name is its label, so clicking the name toggles it.
- The sheet is a modal dialog: the card behind it is inert, Tab is trapped inside, Escape closes it, and focus moves to the search field, the Authorize button or the step heading as the flow advances.
- Toggles, permission changes, connects, failures, removes and undo are announced in a polite status region, and the simulated authorize screen says plainly that no account is contacted.
- When a row's action button disappears (Retry, Sign in) or a row is removed, focus moves to that row or its neighbour so keyboard users never land on the page body.
- Pointer focus draws no ring; keyboard focus shows Arc's shared focus ring.

### Motion

- Toggling a tool rolls the tool count and token numbers with tabular digits, and its server's segment resizes on a critically damped spring.
- Hovering or focusing a server highlights its segment in the first series color and dims the others.
- Rows open and close their tools on a smooth height spring with a short fade; the chevron turns.
- The sheet rises from the card's bottom edge over a scrim, without overshoot. Steps cross fade with an 18px shift in the direction of the flow.
- Discovered tools arrive one by one with a 4px fade in, under a calm shimmer on "Discovering tools" that settles into "Found 5 tools".
- A new server slides into the top of the list as its height opens, with a brief accent tint that fades out. Removed rows close their gap, and Undo opens them again in place.
- Status labels and actions cross fade (about 100ms out, 160ms in). No text morphs or per letter motion.
- Reduced motion drops travel, height animation and the shimmer: content appears in place with every state, focus move and announcement kept.

### Responsive behavior

- Fills its container up to 720px. Rows keep one line of name and one of status at every width.
- Below a 520px container the tool list drops its indent, "5 of 6 tools" shortens to "5 of 6" and the sheet rises higher.
- Below 400px the tool count leaves the row (the token cost stays), read and write show as icons, and the permission control wraps under its label.
- While the sheet is open the card grows to at least 600px so the directory has room, and scrolls its bottom edge into view if needed. Holds without horizontal scroll from 320px up.

### Performance

- Only the open row renders its tools; the others are one button each.
- The meter and counters derive from the server list on render; there is no separate state to keep in sync.
- Simulated delays and the undo window use tracked timers that clear on unmount, and an abandoned discovery is ignored through a run ticket.

### Notes for AI agents

- Use real server names and pick a brand so the real mark shows: github, linear, notion, slack, sentry, stripe, postgresql, figma, vercel, supabase, cloudflare, googledrive, atlassian, datadog, hubspot, asana, posthog, airtable, docker, zendesk, intercom, gmail, googlecalendar. Leave brand unset for the generic MCP mark.
- Measure tokens per tool from the tool's JSON definition with your provider's token counter. Typical definitions take 150 to 700 tokens.
- Mark every tool read or write honestly: Always allow reads lets read tools run without asking, so a tool that changes data must be write.
- Set status "needs-auth" when a token expired or was revoked, and "error" with a short error string when tools/list failed. Neither counts toward context until it connects again.
- Return the discovered tools from onConnect so the sheet shows what the server really reported. Throw an Error with a readable message to show the failure state.
- The endpoints, token counts and directory in the demo are sample values.

### Keywords

mcp, model context protocol, mcp servers, tools, integrations, connectors, agent tools, tool definitions, context budget, token cost, oauth, tool discovery, permissions, always allow reads, ai agent settings

### Related

- agent-approvals
- context-window
- agent-run
- ai-composer
- agent-routines
- agent-orchestrator
- knowledge-base

---

## Knowledge base

A retrieval knowledge base in one card: add sources and watch them parse, chunk, embed and index, then test a question and see which chunks come back and why.

- Type: Block (composition)
- Access: Pro
- Built from: Button, Copy button, Dropdown menu, Popover, Segmented control, Select, Slider, Switch, Text shimmer
- Documentation: https://uiarc.dev/components/blocks/knowledge-base

### Overview

Pass sources, onAdd and search to connect your ingestion and retrieval; with no props it ingests sample sources and answers test queries.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/knowledge-base. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/knowledge-base while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- Admin screens for a RAG or support assistant where people add documents, watch them index, and check what a question retrieves.
- Explaining or tuning chunking, hybrid search and reranking with a working test bench instead of a diagram.
- Debugging why an assistant answered from the wrong source by looking at scores, matches and neighbouring chunks.

### When not to use

- Use vector-search to illustrate how embeddings and nearest neighbours work; this block is the working product surface.
- Use document-extract to pull structured fields out of a single document.
- Use agent-memory to show what an agent remembers about a user or a project.
- Use ai-answer or research-run to show the cited answer a model writes from retrieved sources.

### Usage

```tsx
import { KnowledgeBase } from "@/components/arc/blocks/knowledge-base/knowledge-base";

export function SupportKnowledge({ sources, upload, retry }) {
  return (
    <KnowledgeBase
      title="Support knowledge base"
      sources={sources}
      onAddSource={({ kind, file }) => upload(kind, file)}
      onRetrySource={retry}
      onQuery={async (query, settings) => {
        const res = await fetch("/api/retrieve", { method: "POST", body: JSON.stringify({ query, ...settings, candidates: 20 }) });
        if (!res.ok) throw new Error("The retriever did not respond");
        return res.json(); // [{ id, sourceId, text, location, similarity, relevance, before, after }]
      }}
    />
  );
}

// With no props the card runs a full simulation with sample documents.
<KnowledgeBase />
```

### API

#### KnowledgeBase

A retrieval knowledge base in one card. The Sources view lists PDFs, Notion pages, Google Drive docs and website crawls, each with a four step ingestion pipeline (parse, chunk, embed, index) that fills as it runs while page, chunk and token counts climb. Add source and a drop zone bring in new sources that ingest live; a failed source names its reason and offers Retry. The Test retrieval view runs a query and lists the top k chunks with similarity bars and scores, highlighted matching words, the source and page. Turning on Rerank reorders the same results in place and shows how far each chunk moved, and opening a result shows the chunk between its neighbours. A settings popover holds chunk size, overlap, top k, hybrid search, reranking and the embedding model, and asks for a re-index when chunking changes.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` | `string` | `"Support knowledge base"` | Heading at the top of the card. |
| `sources` | `KnowledgeSource[]` |  | Live sources: { id, name, kind ("pdf" \| "notion" \| "drive" \| "web" \| "file"), pages, chunks, tokens, status, progress?, failedStep?, error?, note? }. status is "queued", "parse", "chunk", "embed", "index", "indexed" or "failed"; progress is 0 to 1 within the current step. Omit to run the built-in simulation with sample company documents. |
| `chunks` | `KnowledgeChunk[]` |  | Chunks the built-in retriever searches when onQuery is not set: { id, sourceId, index, location, text, overview? }. index orders chunks inside a source so neighbours can be shown. Defaults to the sample corpus in the simulation. |
| `settings` | `RetrievalSettings` |  | Controlled settings: { chunkSize, overlap, topK, hybrid, rerank, embeddingModel }. Pair with onSettingsChange. |
| `defaultSettings` | `Partial<RetrievalSettings>` | `{ chunkSize: 512, overlap: 64, topK: 4, hybrid: true, rerank: false, embeddingModel: "general-v2" }` | Starting settings when uncontrolled. |
| `onSettingsChange` | `(settings: RetrievalSettings) => void` |  | Called on every settings change, including the Rerank switch above the results. Overlap is clamped to half the chunk size. |
| `embeddingModels` | `{ value: string; label: string }[]` | `four generic sample models` | Options for the embedding model select. The text before the first comma also shows in the card summary. |
| `suggestions` | `string[]` |  | Questions offered before the first search. Defaults to sample questions for sources that are indexed, so a new suggestion appears when its source finishes. |
| `onQuery` | `(query: string, settings: RetrievalSettings) => Promise<RetrievedChunk[]> \| RetrievedChunk[]` |  | Runs a retrieval test. Return candidates ({ id, sourceId, text, location?, similarity, relevance?, before?, after? }), ideally more than top k so the reranker can pull one up. The card orders by similarity, or by relevance while Rerank is on, and slices to top k. Throw to show the error state. |
| `onAddSource` | `(request: { kind: SourceKind; file?: File }) => void` |  | Called by the Add source menu and for dropped or picked files. In the simulation the card also adds a sample source of that kind and ingests it. |
| `onRetrySource` | `(id: string) => void` |  | Called by Retry on a failed source. The simulation resumes from the failed step. |
| `onRemoveSource` | `(id: string) => void` |  | Called by Remove on a source that cannot be retried, such as an unsupported file type. |
| `onReindex` | `(settings: RetrievalSettings) => void` |  | Called by Re-index after chunk size, overlap or the embedding model changed. Search keeps using the current index until each source finishes. |
| `defaultView` | `"sources" \| "retrieval"` | `"sources"` | The view shown first. |
| `className` | `string` |  | Class on the root element. |

### Dependencies

- `motion`
- `lucide-react`
- `@radix-ui/react-popover`
- `@radix-ui/react-dropdown-menu`
- `@radix-ui/react-select`
- `@radix-ui/react-switch`

### Keyboard

| Keys | Action |
| --- | --- |
| Tab | Moves through settings, Add source, the view switch, each Retry or Remove button and browse in Sources; and through the query field, Search, the Rerank switch and each result in Test retrieval. |
| Arrow left / Arrow right | On the view switch, moves between Sources and Test retrieval. On a settings slider, changes the value by one step; Shift moves a larger step. |
| Enter | In the query field, runs the search. On a suggestion, runs that question. On a result, opens or closes the chunk in context. |
| Escape | In the query field, clears the query and returns to suggestions. In the settings popover or the Add source menu, closes it and returns focus to its trigger. |
| Space | Toggles the Rerank, Hybrid search and Reranking switches and activates buttons. |

### Accessibility

- The card is a labelled section. Each pipeline is a progressbar with the overall percent and a value text that names the step, such as Embed, step 3 of 4, or Failed at embed.
- Status never relies on color: indexed rows show a check with a label, failed rows an alert icon with the reason in text, and working rows a named step and a percent.
- Each result is a button with aria-expanded and aria-controls; its similarity or reranker score and any rank change (for example, Up 2 after reranking, was 3) are in its accessible name.
- Matching words are wrapped in mark elements, so assistive technology can report highlighted text.
- Ingestion milestones, failures, search results, reranking and simulated actions are announced through one polite status region; simulated uploads say that files stay in the browser.
- Icon-only controls (settings, clear query) have specific names. The settings toggles are full labels, so the text toggles the switch too.
- Pointer focus draws no ring; keyboard focus shows Arc's shared focus ring.

### Motion

- Turning on Rerank shows a short reranking state, then moves each result to its new rank with a critically damped layout animation (no bounce) while score bars and numbers roll to the reranker's values and a rank change fades in.
- Opening a result springs its height open: the previous chunk slides in above, the excerpt grows from two lines to the full chunk, and the next chunk slides in below, all on the smooth spring.
- Pipeline segments fill from a single animation-frame clock while counts climb; the meta line crossfades when a step changes. Active labels use a finite text shimmer that settles when the step ends.
- New sources open in at the top of the list on a height spring; removed ones close their gap. Views crossfade without moving.
- Reduced motion places results, heights and values immediately, stops the spinner and the skeleton pulse, and keeps every label and announcement.

### Responsive behavior

- The card is container aware: from about 720px down to 320px it keeps one column, with no horizontal scroll.
- Below 560px the pipeline moves under each source name at full width, step labels drop, the page or path beside a result shortens, and the chunk-in-context rail moves inline.
- Below 440px the gutters tighten, the header actions wrap under the title, meta lines wrap instead of truncating, and the indexing summary beside the view switch hides.
- Long source names truncate with the full name in a title; failure reasons always wrap so they stay readable.

### Performance

- The simulation advances all sources from one requestAnimationFrame loop that only runs while something is queued or working.
- Scores and counts roll through motion values without React re-renders; excerpt heights are measured once with a ResizeObserver and only re-measured when their width changes.
- The local retriever scores a few dozen chunks with plain string matching; real deployments pass onQuery and skip it.

### Notes for AI agents

- Pass sources from your ingestion job and update status and progress as events arrive; the card only renders them when sources is set. Leave sources unset for a self-running demo.
- Return more candidates than top k from onQuery (for example 20) with both similarity and relevance. That is what lets the reranker pull a chunk up from below the cut, which is the point of the comparison.
- Scores are expected between 0 and 1. Map cosine similarity or a reranker logit into that range before returning it.
- Give each result before and after neighbours (or index plus a chunks prop) so opening a result can show it in context.
- location is free text: a page such as "p. 3" for documents, a heading for Notion, or a path for a crawled site.
- The embedding model labels are generic placeholders. Replace them with the models your stack actually uses.

### Keywords

knowledge base, rag, retrieval, vector store, embeddings, chunking, ingestion, reranking, reranker, hybrid search, semantic search, document indexing, top k, similarity score, retrieval test, ai search

### Related

- vector-search
- document-extract
- agent-memory
- ai-answer
- research-run
- mcp-servers

---

## Eval suite

Run an evaluation suite on a new version of an LLM feature against its baseline: results stream in case by case, and regressions and fixes are called out with the cases behind them.

- Type: Block (composition)
- Access: Pro
- Built from: Button, Text shimmer
- Documentation: https://uiarc.dev/components/blocks/eval-suite

### Overview

Pass cases, candidate, baseline and run, which streams graded results, to show your own evals; with no props it runs a sample suite.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/eval-suite. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/eval-suite while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- Regression testing an LLM feature before shipping a new prompt, model or agent version.
- CI style eval dashboards where people need the overall score, the per category picture and the exact cases that broke in one place.
- Triage of failing cases with an LLM judge: read both outputs, check the rubric, then accept the change or file an issue.

### When not to use

- Use prompt-studio to edit a prompt and try it on one test case at a time.
- Use model-arena for a blind side by side vote between models on a single prompt.
- Use agent-run to follow one agent run step by step rather than scoring a suite.
- Use token-inspector to look at token level probabilities of a single reply.

### Usage

```tsx
import { EvalSuite } from "@/components/arc/blocks/eval-suite/eval-suite";

export function SupportAgentEvals({ suite, history }) {
  return (
    <EvalSuite
      suite={suite}
      runs={history}
      onRun={async function* (suite, { signal, started }) {
        const response = await fetch(`/api/evals/${suite.name}/runs`, { method: "POST", signal });
        for await (const event of readEvents(response)) {
          if (event.type === "started") started(event.caseId);
          if (event.type === "scored") yield event.result; // { caseId, outcome, output, scores, rationale, costUsd }
        }
      }}
      onTriage={async (caseId, action) => {
        if (action === "issue") return (await createIssue(caseId)).key; // "SUP-2481"
        await markExpected(caseId);
      }}
    />
  );
}

// A case with a drilldown. Cases without input still score and list, without the side by side view.
const refundCase = {
  id: "refunds-02",
  category: "Refunds",
  title: "Refund after partial shipment",
  baseline: "pass",
  input: "Only 2 of my 3 items arrived (order #48213). Can I get my money back for that part?",
  expected: "Refund only the missing item, not the whole order.",
  baselineOutput: "I've refunded $34.00 for the candle set to your original payment method.",
  baselineScores: [5, 5, 4, 5], // one per rubric criterion
};
```

### API

#### EvalSuite

One card for running an evaluation suite on a new version of an LLM feature against its baseline. The header names the feature, the candidate and baseline versions with their models, the case count and the judge model, with Run beside it. While the run streams, one row per category fills with a small cell per case (pass, fail or error, each with its own glyph), the score counts up next to the baseline with the delta in points, and each category bar fills with a ghost tick at the baseline value. Cost, time and a sparkline of the last runs sit in the summary. The case list filters to All, Failed, Regressions or Improved; opening a case shows the input, the expected behavior, the baseline and new outputs side by side with a word diff, and the judge's rubric scores and rationale, then lets you mark it as expected or open an issue.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `suite` | `EvalSuiteData` | `sampleSuite` | The suite: name, candidate { version, model }, baseline { version, model }, judge model, optional categories (row order), rubric (criteria the judge scores 1 to 5), cases and an estimate { costUsd, seconds } shown before the first run. A model is { name, brand?: "claude" \| "openai", mark?: ReactNode }. Each case has id, category, title and its baseline outcome; add input, expected, baselineOutput and baselineScores to give it a drilldown. |
| `runs` | `EvalRunRecord[]` | `sampleRuns` | Earlier runs, oldest first, each { id, label, score, date? } with the score in percent. The sparkline shows the last seven plus the current run, and rings the last one as the baseline. |
| `onRun` | `(suite: EvalSuiteData, context: { signal: AbortSignal; started: (caseId: string) => void }) => AsyncIterable<EvalCaseResult> \| Promise<EvalCaseResult[]>` |  | Runs the suite. Yield each EvalCaseResult { caseId, outcome, output?, scores?, rationale?, error?, costUsd? } as it is scored to fill the grid live, or resolve every result at once. Call started(caseId) to show a case as in flight. Stop aborts the signal. Throw to show the failed state with Try again. Without it, the run is simulated on eight workers and announced as simulated. |
| `onTriage` | `(caseId: string, action: "expected" \| "issue") => void \| string \| Promise<void \| string>` |  | Called by Mark as expected and Open issue. Return or resolve an issue key such as "SUP-2481" for an issue; reject to restore the buttons. Without it, triage is simulated and says so. |
| `defaultFilter` | `"all" \| "failed" \| "regressions" \| "improved"` | `"regressions"` | The filter the case list opens with. |
| `className` | `string` |  | Class on the root element. |

### Dependencies

- `motion`
- `lucide-react`

### Keyboard

| Keys | Action |
| --- | --- |
| Tab | Moves through Run, the run history, the case filter, each case row, Show more, and inside an open case the triage buttons. |
| Enter, Space | On Run, starts the run; while running the same button stops it. On a case row, opens or closes its drilldown. On Mark as expected or Open issue, triages the case and moves focus to Undo or the confirmation that replaces the buttons; Undo brings the buttons back with focus on the first. |
| Arrow left / Arrow right | On the case filter, moves between All, Failed, Regressions and Improved. On the run history, steps through the runs and reads out each version, score and date. |
| Home / End | On the case filter or the run history, jumps to the first or last item. |
| Escape | On the run history, returns the readout to the latest run. |

### Accessibility

- Each category row is one image with a full text summary (passed, failed, errors, not yet scored, percent and the change against the baseline), so the 120 cells never become 120 announcements.
- Outcomes never rely on color: pass, fail and error each have their own glyph, a regression is the only solid cell, and every list row spells out both outcomes in hidden text.
- Case rows with a drilldown are buttons with aria-expanded and aria-controls; the drilldown is a labelled region. Rows without one are plain text.
- The case filter is a radio group with roving focus. The run history is a slider whose value text names the run, its score and date.
- Run start, finish (score, delta, regressions, improvements), stop, failure and each triage are announced in a polite status region, including when a run or an issue is simulated.
- The score and every category percent count with tabular numerals; hidden text carries the final value so screen readers never read a number mid count.
- Pointer focus draws no ring; keyboard focus shows Arc's shared focus ring.

### Motion

- Cells fill as results arrive: the background tints over 240ms and the glyph scales in from 40 percent with an ease out. Cases in flight breathe once a second.
- The score, category percents and cost count to their values on a critically damped spring, so a burst of results reads as one smooth count; a new run resets them at once.
- Bars fill with a clip-path tween and tint green or red only when the run finishes; the deltas fade up 3px at the same moment.
- The current run lands on the sparkline as a short drawn segment and a dot that scales in after it.
- Rows that appear mid run, the drilldown and Show more open on the smooth spring with no overshoot. The filter highlight glides on a critically damped spring and the list height follows the new filter.
- Run, Stop and Run again crossfade in place while the pill width follows the measured label.
- Reduced motion fills cells, numbers, bars and panels immediately, stops the breathing, and keeps every state and announcement.

### Responsive behavior

- The card is 760px wide at most. From 680px a category is one line: label, 24 cells and its bar; below that the cells move under the label, and below 480px they wrap into two rows of 12.
- Below 480px the header's model chips become a small aligned table (v12, v11 and Judge on the left, the model on the right) and the subtitle takes the full width under the title and Run.
- The summary goes from three columns to two at 620px and to one at 420px, with cost and time side by side.
- The two outputs share one frame split down the middle and stack below 560px; the drilldown labels move above their text. Below 480px each rubric row puts its name, score and change on one line with the bar under them.
- Case categories hide below 480px, triage tags keep only their icon, and titles truncate with the full title in hidden text.
- The filter drops its counts below 480px and tightens to fit 320px without scrolling.

### Performance

- Scores, counts and per category numbers are derived from one results map in memoized passes; cells only change attributes, and their fills are CSS transitions.
- Counting numbers write their text through a motion value, so the spring never re-renders React per frame.
- The word diff runs once per opened case and is memoized on the two outputs.
- The simulation uses timers on eight workers and clears them on stop and unmount.

### Notes for AI agents

- Use it when a team compares a candidate version of a prompt, model or agent against a baseline on a fixed suite and needs to know which cases regressed, not only the average.
- Score is the pass rate over all cases in percent; the delta compares it with the baseline pass rate computed from each case's baseline outcome. A regression is a case that passed on the baseline and does not pass now; improved is the reverse.
- Stream results from onRun as an async iterable for the live grid. Results may arrive in any order; the regression and improved lists keep arrival order while the run streams.
- Rubric scores are 1 to 5, one per suite.rubric criterion, for both baselineScores and result scores. The rubric bars reuse the category bar: new score as the fill, baseline as the ghost tick.
- When the two replies share little wording, the drilldown shows both in full without highlights instead of striking through the whole baseline.
- Model marks: pass brand "claude" or "openai" for the built-in marks, or any inline SVG as mark. The sample uses Claude Sonnet 5.5 against GPT-6 Luna with Claude Opus 5.5 as judge; costs and timings are sample values.

### Keywords

eval, evals, evaluation suite, llm evaluation, regression testing, llm judge, rubric, test cases, pass rate, baseline, prompt regression, model comparison, diff, ai quality, ci for prompts

### Related

- prompt-studio
- model-arena
- agent-run

---

## Agent builder

A card for setting up an AI agent: an inline editable name, a model picker, instructions, tool toggles with real app marks, and knowledge files with upload progress. A Configure / Test switch opens a compact chat that answers with the tools you turned on, and Publish ships the setup with a saved or unsaved state.

- Type: Block (composition)
- Access: Pro
- Built from: Button, Segmented control, Switch, Text shimmer, Radix dropdown menu (radio items)
- Documentation: https://uiarc.dev/components/blocks/agent-builder

### Overview

Drop it into the settings screen of a support, sales or ops agent. Pass defaultConfig (or a controlled config with onConfigChange) and publishedConfig from your server, so unsaved changes are measured against what is live. Wire onPublish(config, signal) to save the setup, onUpload(file, report, signal) to upload knowledge files with progress, and onSend(message, config, signal) to answer test messages with the unsaved setup. onSend returns { text, calls }, and each call's tool id must match an AgentTool id (or "knowledge") so its chip gets the right mark. models and tools take your own lists with 16px SVG marks. Leave any callback out and that part is simulated.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/agent-builder. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/agent-builder while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- Letting customers configure their own AI agent inside your product, like Intercom Fin, Zapier agents or an OpenAI GPT builder.
- Internal admin screens where ops teams tune instructions, tools and knowledge for a support or billing agent.
- A product tour or landing section that shows how an agent is set up and tested in one place.

### When not to use

- Running or monitoring an agent in production: use agent-status or agent-routines.
- Approving actions an agent wants to take: use agent-approvals.
- A full chat product: use ai-chat. The Test view here is a compact preview, not a conversation app.
- Only choosing a model: use model-picker.

### Usage

```tsx
import { AgentBuilder, sampleAgentConfig } from "@/components/arc/blocks/agent-builder/agent-builder";

export function SupportAgentSettings() {
  return (
    <AgentBuilder
      defaultConfig={sampleAgentConfig}
      onPublish={async (config, signal) => {
        const response = await fetch("/api/agents/billing", { method: "PUT", body: JSON.stringify(config), signal });
        if (!response.ok) throw new Error("Server rejected the config");
      }}
      onSend={async (message, config, signal) => {
        const response = await fetch("/api/agents/billing/test", { method: "POST", body: JSON.stringify({ message, config }), signal });
        return response.json(); // { text, calls: [{ tool: "stripe", label: "Searched customers", result: "2 charges" }] }
      }}
    />
  );
}
```

### API

#### AgentBuilder

Configure an AI agent in one card: an inline editable name over its workspace and version, a model picker, instructions with a character count, tools as toggle rows, and knowledge files with upload progress. A Configure / Test switch swaps the body for a compact chat that answers with the configured model and tools, and Publish ships the config with an unsaved, publishing, failed and published state. With no props it plays the Lumen billing assistant sample with simulated uploads, replies and publishing.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `config` | `AgentConfig` |  | Controlled config: { name, tint, modelId, instructions, tools, files }. tint (1 to 4) colors the agent's mark beside its replies in Test. Pair with onConfigChange. |
| `defaultConfig` | `AgentConfig` | `sampleAgentConfig` | Starting config when uncontrolled. Passing it turns off the sample's auto upload. |
| `onConfigChange` | `(config: AgentConfig) => void` |  | Called with the next config on every edit, toggle, model change and file update. |
| `publishedConfig` | `AgentConfig` |  | The config that is live now. Unsaved changes are measured against it, so reverting an edit clears the unsaved state. Defaults to the starting config. |
| `models` | `AgentModel[]` | `defaultModels` | Models in the picker: { id, name, note?, mark? }. Defaults to Claude Sonnet 5.5, Claude Opus 5.5, Claude Haiku 5.5, GPT-6.1 Sol and Gemini 4 Argon with their marks. |
| `tools` | `AgentTool[]` | `defaultTools` | Tools the agent can be given: { id, name, description, mark? }. Defaults to Gmail, Slack, Linear, Notion, Google Calendar and Stripe. |
| `onPublish` | `(config: AgentConfig, signal: AbortSignal) => Promise<void>` |  | Saves and ships the config. Resolve to bump the version and show the published state; reject to show "Couldn't publish". Simulated when left out. |
| `onUpload` | `(file: File, report: (progress: number) => void, signal: AbortSignal) => Promise<void>` |  | Uploads one knowledge file. Call report with 0 to 1 as bytes go out; reject with an Error to mark the row failed with its message and a retry button. The signal aborts when the row is removed. Simulated when left out (files over 20 MB fail). |
| `onSend` | `(message: string, config: AgentConfig, signal: AbortSignal) => Promise<TestReply>` |  | Answers a Test message. Return { text, calls?: { tool, label, result? }[] }; calls render as tool chips with the tool's mark before the reply streams. Defaults to simulateReply, which follows the enabled tools. |
| `version` | `number` | `12` | Published version shown under the name. Counts up after each successful publish. |
| `workspace` | `string` | `"Lumen support"` | Short line under the name, such as the workspace or team. |
| `maxInstructions` | `number` | `2000` | Instruction length limit. The count turns to the warning color past 90%. |
| `accept` | `string` | `".pdf,.md,.txt,.csv,.docx,.html"` | Accepted file types for the knowledge file picker. |
| `mode` | `"configure" \| "test"` |  | Controlled view. Pair with onModeChange. |
| `defaultMode` | `"configure" \| "test"` | `"configure"` | Starting view when uncontrolled. |
| `onModeChange` | `(mode: AgentBuilderMode) => void` |  | Called when the Configure / Test switch changes. |
| `className` | `string` |  | Extra class on the card. |

#### simulateReply

The built in reply function used when onSend is left out. Matches billing, bug and booking requests and changes its answer and tool calls to the tools that are on, so it is useful for demos and tests.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `message` (required) | `string` |  | The test message. |
| `config` (required) | `AgentConfig` |  | The current config. Disabled tools are never called. |

### Dependencies

- `motion`
- `lucide-react`
- `@radix-ui/react-dropdown-menu`
- `@radix-ui/react-switch`

### Keyboard

| Keys | Action |
| --- | --- |
| Tab | Moves through the name, view switch, model picker, instructions, each tool switch, file actions and Publish. The hidden view is inert and skipped. |
| Arrow keys | Move between Configure and Test on the view switch, and between models in the open picker. |
| Enter / Space | Opens the model picker, chooses a model, toggles a tool, and presses buttons. |
| Escape | Closes the model picker and returns focus to it. In the name, restores the name from before editing. |
| Enter (in the name) | Finishes editing the name. |
| Enter (in Test) | Sends the message. While a reply runs, the send button becomes Stop. |

### Accessibility

- The card is a labelled section; the name field, instructions and every tool switch have labels, and the tool row text is part of the switch label so the whole row is clickable.
- The model picker is a Radix menu with radio items, so the selected model is announced as checked.
- Upload progress uses role="progressbar" with a value; failed uploads show an icon and the error message, never color alone.
- Status changes (published, upload done or failed, reply ready) go to a polite live region, and simulated actions say so: "Simulated, nothing was deployed".
- The inactive view is inert and aria-hidden, so screen readers and the Tab key only reach what is visible.

### Motion

- Configure and Test crossfade in the same box (100ms out, 160ms in); Test overlays Configure, so the card never changes size.
- Text swaps (model name, version, footer status, reply meta) are a single crossfade with a 2px rise. No blur or scramble.
- Test replies: a short Thinking shimmer, tool chips that shimmer while running and reveal their result in place, then fast chunked streaming of three to six words every 34ms, each chunk only fading in.
- Added and removed files animate their measured height with a bounce free spring; switches and the segmented control use the shared bounce free presets.
- Reduced motion drops the rises, height animation and streaming (replies appear whole) but keeps every state and status change.

### Responsive behavior

- Fills its container up to 640px. Below 480px the padding drops to 16px and the model picker narrows; the agent name, tool descriptions and file names truncate with an ellipsis. The Configure / Test switch stays beside the name down to 300px of card width, then takes its own row.
- Holds up at 360px without horizontal scroll; the Test view scrolls its own thread and keeps the composer pinned.
- Tool rows and buttons are at least 28px tall targets inside 52px rows for touch.

### Performance

- Plain DOM and CSS; motion only animates opacity, small transforms and the height of added or removed file rows.
- The sample upload starts only once the card is on screen. Text shimmers pause off screen.
- Streaming appends one chunk every 34ms; each chunk is its own span so earlier text never re-renders its animation.

### Notes for AI agents

- Use it for the settings screen of a support, sales or ops agent: one card that holds the whole config with a built in test loop.
- Wire onPublish to persist the config and onSend to call your agent runtime with the unsaved config, so people can test before they publish.
- Pass publishedConfig from the server so the unsaved state compares against what is live; files still uploading or failed do not count as changes.
- Tool ids in TestReply.calls must match AgentTool ids (or "knowledge" for a file lookup) so the chips get the right mark.
- Keep marks 16px square SVGs; mono marks should use currentColor so they follow the theme.

### Keywords

agent builder, configure AI agent, GPT builder, assistant settings, AI agent config, tools toggle, knowledge base upload, system prompt editor, test agent chat, publish agent, Intercom Fin, Zapier agents

### Related

- model-picker
- agent-routines
- agent-approvals
- ai-chat
- tool-call
- agent-status

---

## AI insight card

A KPI card that explains itself. Explain streams a short reason for the change and ranks three drivers with contribution bars. A numbered annotation lights up on the sparkline as each driver is read, and follow-up chips ask the next question in place.

- Type: Block (composition)
- Access: Pro
- Built from: Button, TextShimmer
- Documentation: https://uiarc.dev/components/blocks/ai-insight-card

### Overview

Pass your KPI as `metric`: totals, the current and previous series, and point labels. Pass `followUps` for the chips. Wire `explain({ metric, followUp, signal })` to your analysis endpoint. It should resolve with `{ segments, drivers }`, where each driver has a signed delta and the series index its annotation marks. Write one text segment per driver, with `driver` set and in rank order, so the chart lights up as the reader reaches it. The signal aborts on Stop, Hide or a new question. If the promise rejects, the card shows an error row with Retry. Use `lowerIsBetter` for churn or cost metrics so a rise reads red, and `format` for metrics that are not currency. With `explain` set, autoPlay is off by default, so the card never calls the model on its own.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/ai-insight-card. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/ai-insight-card while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- A dashboard KPI where readers ask why it moved, such as net revenue, MRR, signups or churn.
- Weekly business reviews and finance dashboards that want an explanation next to the number.
- Products adding AI analysis to existing analytics without a separate chat.

### When not to use

- Open ended questions across many tables: use ask-your-data.
- A plain number with no explanation: use metric-card or stat-card.
- Dense multi series charts: use a full chart component.

### Usage

```tsx
import { AiInsightCard } from "@/components/arc/blocks/ai-insight-card/ai-insight-card";

export function RevenueCard({ metric }) {
  return (
    <AiInsightCard
      metric={metric}
      followUps={[{ id: "plan", label: "Break down by plan" }]}
      explain={async ({ metric, followUp, signal }) => {
        const res = await fetch("/api/insights/explain", {
          method: "POST",
          body: JSON.stringify({ metric: metric.label, followUp: followUp?.id }),
          signal,
        });
        if (!res.ok) throw new Error("The analysis service did not respond.");
        return res.json(); // { segments: [{ text, driver? }], drivers: [{ id, label, delta, point }] }
      }}
    />
  );
}
```

### API

#### AiInsightCard

A KPI card with a sparkline that explains its own change: Explain streams a short reason, ranks three drivers with contribution bars and lights up a numbered chart annotation as each driver is read. Follow-up chips ask the next question in place.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `metric` | `InsightMetric` | `sampleMetric` | The KPI: label, period, value, previous, comparisonLabel, series, previousSeries, points (tooltip labels), legend labels, an optional format function and lowerIsBetter to flip delta colors. |
| `insight` | `Insight` | `sampleInsight` | The local answer for Explain: segments of text (a segment with `driver` lights up that driver) and up to three ranked drivers, each with a signed delta and the series index its annotation marks. |
| `followUps` | `InsightFollowUp[]` | `sampleFollowUps` | Follow-up chips under the answer. Each has an id, a label and an optional local insight. The chip showing its answer reads as pressed. |
| `explain` | `(request: { metric, followUp?, signal }) => Promise<Insight>` |  | Fetch a real answer. Resolve with the full insight; the card streams it in chunks and syncs the annotations. The signal aborts on Stop, Hide or a new question. A rejection shows the error row with Retry. |
| `onExplain` | `(followUp?: InsightFollowUp) => void` |  | Called when Explain is pressed (no argument) or a follow-up is picked. |
| `autoPlay` | `boolean` | `true without explain` | Plays Explain and each follow-up on a loop while the card is on screen, until the reader interacts. Off with reduced motion. |
| `thinkingLabel` | `string` | `"Reading invoices and renewals"` | Shimmering status line while the answer is prepared. |
| `source` | `{ label: string; icon?: ReactNode } \| null` | `Stripe billing` | Data source in the footer. Pass null to hide it. |
| `model` | `{ label: string; icon?: ReactNode } \| null` | `Claude Sonnet 5.5` | Model in the footer. Pass null to hide it. |
| `className` | `string` |  | Class on the card root. |

### Dependencies

- `motion`
- `lucide-react`

### Keyboard

| Keys | Action |
| --- | --- |
| Tab | Moves through Explain (Stop while streaming, Hide when open), the chart, Retry and the follow-up chips. |
| Enter / Space | Explains the change, stops a stream, hides the panel or asks a follow-up. |
| Left / Right | With the chart focused, steps through the points and announces each value. |
| Home / End | Jumps to the first or last point. |
| Escape | Clears the chart readout. |

### Accessibility

- The card is a labelled section; Explain carries aria-expanded and aria-controls for the answer panel.
- A polite live region announces when the answer starts, the full answer when it is ready, Stop and errors. Without `explain` it says the answer is simulated from sample data.
- Deltas carry a sign as well as color, and unread driver rows are hidden from assistive tech until the answer reaches them.
- The chart is a focusable group with arrow key reading; values are announced through its own live region.
- Follow-up chips use aria-pressed for the answer on screen and are disabled while a stream runs.

### Motion

- The panel opens and closes on a critically damped 260ms spring; answers of a different length spring to their height. No bounce.
- The answer streams 3 to 7 words every 34ms, each chunk only fading in over 140ms. Its full text is reserved underneath, so the card never grows while streaming.
- Annotations fade and scale in over 200ms as their driver is read; the driver being read takes the accent on its badge, dot, guide, rank and underline.
- Contribution bars grow to their share over 240ms ease-out; skeletons crossfade to labels in 160ms.
- Reduced motion: the answer appears whole after the short thinking state, transitions cut, and the demo loop stays off.

### Responsive behavior

- The card fills its container up to 640px. Under 460px the legend hides and the contribution bars shorten, so driver labels keep their room and truncate with an ellipsis.
- Follow-up chips wrap onto a second row on phones. The chart redraws at the container width with crisp strokes.
- Touch scrubs the chart only while the finger is down, so vertical page scrolling still works.

### Performance

- The chart is one inline SVG with two paths; annotations are absolutely positioned spans with CSS transitions.
- Streaming updates one counter per tick; tokenizing runs once per answer.
- The demo loop waits while the card is off screen and stops for good on the first interaction.

### Notes for AI agents

- Use for one KPI that needs a why: revenue, signups, churn, pipeline. Return drivers that add up to the change, ranked by absolute size, at most three.
- Point each driver at the series index where it shows, and write one text segment per driver with `driver` set, in rank order, so the chart lights up as the reader reaches it.
- Pass lowerIsBetter for costs and churn so a rise reads red. Pass `format` for non-currency metrics.
- With a real `explain`, autoPlay defaults to off so the card never spends model calls on its own.

### Keywords

ai insight, kpi card, explain metric, revenue explanation, drivers, sparkline, analytics ai, metric annotation, why did revenue drop, dashboard card

### Related

- ask-your-data
- metric-card
- sparkline
- account-health
- text-shimmer

---

## Catch up

A catch me up digest for when you return, where one button reads Slack, Linear, GitHub and Gmail for the range you pick and streams back a short ranked summary: Needs you, Decisions made, Shipped and FYI. Each item is one sentence with its source mark, people and a jump link, and marking items as read clears them with a smooth collapse.

- Type: Block (composition)
- Access: Pro
- Built from: Button, SegmentedControl, TextShimmer, Tooltip
- Documentation: https://uiarc.dev/components/blocks/catch-up

### Overview

Drop it on a home or inbox screen for the moment someone comes back. Pass `generate(range, signal)` returning `CatchUpItem[]` (id, section, source, one-sentence text, context, when, people, href) and abort when the signal fires. Pass `counts` keyed by range for the per-source totals shown before it runs, plus `onOpen` and `onMarkRead` to wire jump links and read state. `ranges`, `range`/`onRangeChange`, `model` and `title` are optional. With no props it plays a simulated three-day digest once it scrolls into view.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/catch-up. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/catch-up while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- A home or inbox screen that summarizes what happened across connected tools while the user was away.
- An AI assistant feature that turns hundreds of notifications into a short ranked list with jump links.
- A weekly or daily digest preview inside a product's notification settings.

### When not to use

- A live notification feed where every event matters; use a plain activity list instead.
- A long-form report or meeting summary with paragraphs; use a document view or ai-chat.
- Approving agent actions; use agent-approvals.

### Usage

```tsx
import { CatchUp } from "@/components/arc/blocks/catch-up/catch-up";

export function ReturnDigest() {
  return (
    <CatchUp
      generate={async (range, signal) => {
        const response = await fetch(`/api/digest?range=${range}`, { signal });
        if (!response.ok) throw new Error("Gmail did not respond. Try again in a minute.");
        return response.json();
      }}
      counts={{ "1d": { slack: 31, linear: 9 }, "3d": { slack: 86, linear: 31 }, "1w": { slack: 214, linear: 77 } }}
      onOpen={item => window.open(item.href, "_blank")}
      onMarkRead={ids => fetch("/api/digest/read", { method: "POST", body: JSON.stringify({ ids }) })}
    />
  );
}
```

### API

#### CatchUp

A catch me up digest card. One button reads Slack, Linear, GitHub and Gmail for a time range and streams back a prioritized summary in four sections: Needs you, Decisions made, Shipped and FYI. With no props it plays a simulated three day digest.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `generate` | `(range: string, signal: AbortSignal) => Promise<CatchUpItem[]>` |  | Builds the digest for a range. Abort the request when the signal fires (Stop, a new range, unmount). Leave it out to play the built in sample digest, which reads nothing. |
| `ranges` | `CatchUpRange[]` | `1 day, 3 days, 1 week` | Options in the time range selector: { value, label, since }. The label also fills the button ("Catch up on 3 days") and since fills the summary line. |
| `range` | `string` |  | Controlled range value. Pair with onRangeChange. |
| `defaultRange` | `string` | `second range` | Starting range when uncontrolled. |
| `onRangeChange` | `(range: string) => void` |  | Called when the range changes. A digest that is already showing rebuilds for the new range. |
| `counts` | `Record<string, Partial<Record<CatchUpSource, number>>>` | `sample counts` | Unread updates per source, keyed by range value. Shown before the digest runs and summed in the summary line. |
| `onOpen` | `(item: CatchUpItem) => void` |  | Jump to an item in its app. Without it, items with an href open in a new tab, and items without one show a simulated notice. |
| `onMarkRead` | `(ids: string[]) => void` |  | Called with the ids marked as read, one item at a time or all at once from Mark all as read. |
| `model` | `{ name: string; mark?: ReactNode }` | `Claude Haiku 5.5` | The model that writes the digest, shown in the footer. |
| `title` | `string` | `"Welcome back"` | Card title. |
| `autoStart` | `boolean` | `true without generate` | Runs the digest once when the card first scrolls into view. |
| `className` | `string` |  | Extra class on the root card. |

#### CatchUpItem

One digest line.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `id` (required) | `string` |  | Stable id, passed back to onMarkRead. |
| `section` (required) | `"needs-you" \| "decisions" \| "shipped" \| "fyi"` |  | Which section the item belongs to. Sections show in this order and hide when empty. |
| `source` (required) | `"slack" \| "linear" \| "github" \| "gmail"` |  | Source app, drawn with its real mark. |
| `text` (required) | `string` |  | One sentence. It streams in a few words at a time. |
| `context` | `string` |  | Where it happened: a channel, issue, pull request or thread. |
| `when` | `string` |  | Short time label, such as "Sun 13:10". |
| `people` | `{ name: string; avatar?: string }[]` |  | People involved. Up to three faces show, with the first name and a count. |
| `href` | `string` |  | Jump link to the item in its app. |

### Dependencies

- `motion`
- `lucide-react`
- `@radix-ui/react-tooltip`

### Keyboard

| Keys | Action |
| --- | --- |
| Tab | Moves through the range selector, each item's open and mark as read buttons, then the footer action. |
| Arrow keys | Move between time ranges in the selector. |
| Enter / Space | Runs the digest, stops it, opens an item, or marks it as read. |

### Accessibility

- A polite live region announces each phase: reading, digest ready with the item count, marked as read with the count left, and all caught up. The sample adds that it is simulated and nothing was read.
- Sections are labelled regions with a heading that includes the count, and each sentence starts with its source name for screen readers.
- Rows that have not streamed in yet are hidden from assistive tech and their buttons are out of the tab order.
- After marking an item as read, focus moves to the next item's mark as read button, or to the footer action when the list is clear.
- Status is never color alone: sections pair an icon with a label, and the reading state uses a spinner then a check per source.

### Motion

- The digest streams four words every 34ms; each chunk only fades in. Rows reserve their full height up front behind quiet skeleton bars, so nothing shifts while text streams.
- Switching between sources, digest and outcome is one crossfade (100ms out, 160ms in) while the card height springs to the new size with no bounce.
- Mark as read collapses the row's height and opacity in 200ms; an emptied section collapses the same way. The card follows the collapse frame by frame instead of chasing it with a second spring.
- Labels, counts and the summary line swap with a single crossfade and a 2px rise. The button keeps a fixed minimum width across labels.
- Reduced motion shows the finished digest at once, keeps crossfades as plain fades, and stops the spinner.

### Responsive behavior

- The card fills its container up to 600px. Below 440px container width the padding tightens, the range selector wraps under the title, and meta lines truncate with an ellipsis.
- Item actions are always visible, so touch users do not depend on hover.
- Holds at 360px and 390px viewports without horizontal scroll.

### Performance

- Streaming re-renders one small list on a 34ms timer only while text is streaming; it stops at ready.
- Word fades run on CSS opacity transitions, not per-word motion components.
- The sample starts once via IntersectionObserver; the spinner animates only during reading.

### Notes for AI agents

- Use for a return or Monday morning moment: a manager or engineer comes back after time away and needs what changed, ranked by whether it needs them.
- Keep items to one sentence written as an outcome ("API v2.14 is live with 38% faster search"), not a raw message. Put the person, channel and time in people, context and when.
- Order is fixed by section: Needs you first. Only put items in Needs you when the reader has to act.
- Pass generate for real data; it receives an AbortSignal that fires on Stop, a range change or unmount.
- Sources are Slack, Linear, GitHub and Gmail. To add another, extend CatchUpSource and the marks file.

### Keywords

catch up, catch me up, digest, ai summary, chief of staff, while you were away, inbox summary, slack summary, notifications digest, linear, github, gmail, prioritized summary, mark as read

### Related

- agent-status
- tool-call
- agent-approvals
- ai-chat

---

## Agent gallery

A marketplace card of AI agent templates where you filter by team, search by agent or app, preview a sample run and install an agent inline: choose a workspace, grant access app by app, and the card confirms with a check.

- Type: Block (composition)
- Access: Pro
- Built from: Button
- Documentation: https://uiarc.dev/components/blocks/agent-gallery

### Overview

Drop <AgentGallery /> onto an agents or integrations page. With no props it shows 20 sample agents and simulates installs. To wire it up, pass `agents` (name, job, category, apps with mark and scope, model, rating, installs, optional three-step preview), `workspaces`, and an async `onInstall(agent, workspace, signal)`. If it rejects, the card shows "Could not connect" with Try again. The signal aborts on Cancel, Escape or unmount. Category, query and installed each work controlled or uncontrolled (`category`/`onCategoryChange`, `query`/`onQueryChange`, `installed`/`onInstalledChange`). `onOpen` opens an installed agent and `onPreview` is there for analytics.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/agent-gallery. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/agent-gallery while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- An agents or integrations page where people browse and install ready made AI agents.
- Onboarding that suggests agent templates by team and installs one without leaving the page.
- A marketplace teaser on a dashboard or settings page.

### When not to use

- Configuring a single agent's prompt, tools or schedule: use a settings form or agent routines.
- Showing a running agent's progress: use agent status or tool call.
- Catalogs with hundreds of items that need pagination, sorting and facets: use a full page table or list.

### Usage

```tsx
import { AgentGallery } from "@/components/arc/blocks/agent-gallery/agent-gallery";

// Sample catalog with simulated installs
<AgentGallery />

// Real installs
<AgentGallery
  agents={templates}
  workspaces={[{ id: "acme", name: "Acme", detail: "Business · 48 seats" }]}
  installed={installedIds}
  onInstalledChange={setInstalledIds}
  onInstall={async (agent, workspace, signal) => {
    const res = await fetch("/api/agents/install", {
      method: "POST",
      body: JSON.stringify({ agent: agent.id, workspace: workspace.id }),
      signal,
    });
    if (!res.ok) throw new Error("The workspace admin must approve this app.");
  }}
  onOpen={agent => router.push(`/agents/${agent.id}`)}
/>
```

### API

#### AgentGallery

A card that lists AI agent templates by team, with search, a sample run preview and an inline install flow (choose workspace, grant access per app, installed). With no props it shows 20 sample agents and simulates installs.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `agents` | `AgentTemplate[]` | `defaultAgents` | The catalog. Each agent has an id, name, one line job, category, apps (name, mark, scope), model (name, mark), rating, installs and an optional three step preview. |
| `categories` | `string[]` | `["Sales", "Support", "Engineering", "Marketing", "Ops"]` | Filter chips, in order. Agents show under the chip that matches their category. |
| `category` | `string` |  | The selected category. Pair with onCategoryChange. |
| `defaultCategory` | `string` | `categories[0]` | The first selected category when uncontrolled. |
| `onCategoryChange` | `(category: string) => void` |  | Called when a chip is chosen, including from the empty state's "Show in" button. |
| `query` | `string` |  | The search text. Pair with onQueryChange. Matches name, job, app names and model within the selected category. |
| `defaultQuery` | `string` | `""` | The first search text when uncontrolled. |
| `onQueryChange` | `(query: string) => void` |  | Called on every search edit and when search is cleared. |
| `workspaces` | `AgentWorkspace[]` | `defaultWorkspaces` | Workspaces offered on the first install step ({ id, name, detail? }). With a single workspace that step is skipped. |
| `installed` | `string[]` |  | Ids of installed agents. Installed cards show a check and offer Open instead of Install. Pair with onInstalledChange. |
| `defaultInstalled` | `string[]` | `[]` | Installed ids when uncontrolled. |
| `onInstalledChange` | `(installed: string[]) => void` |  | Called with the new list after an install completes. |
| `onInstall` | `(agent, workspace, signal: AbortSignal) => Promise<void>` |  | Runs the real install after the person grants access. Reject to show the error state with Try again. The signal aborts on Cancel, Escape or when the card leaves the list. Leave it out to simulate a 1.2s install. |
| `onPreview` | `(agent: AgentTemplate) => void` |  | Called when a card opens its sample run, for analytics. |
| `onOpen` | `(agent: AgentTemplate) => void` |  | Opens an installed agent, for example its settings page. |
| `title` | `string` | `"Agent templates"` | Heading of the card. |
| `description` | `string` |  | One line under the heading. Pass an empty string to hide it. |
| `className` | `string` |  | Extra class on the root section. |

### Dependencies

- `motion`
- `lucide-react`

### Keyboard

| Keys | Action |
| --- | --- |
| Tab | Moves through search, the selected chip and each card's actions. Focus inside a card reveals Preview and Install. |
| Arrow keys | Move between team chips, and between workspaces on the first install step. |
| Home / End | Jump to the first or last team chip. |
| Escape | In search, clears the text. Inside an install or preview, returns the card to its summary; while connecting, cancels the install. |
| Enter / Space | Activates the focused chip, workspace or button. |

### Accessibility

- The root is a labelled section; chips are a radiogroup with a roving tab stop, and workspaces are a second radiogroup.
- Each card is an article named after the agent. App marks are hidden from assistive tech and replaced by a sentence ("Connects to HubSpot, Slack and Gmail"); rating and installs are read as full words.
- After every step change made by the person, focus moves to the new step's main control, so keyboard users never fall back to the page. A leaving step is inert.
- A polite live region announces result counts, connect progress, errors and the installed result; without onInstall it adds "Simulated, nothing was connected".
- Status is never color alone: connected apps show a check, errors show an icon with "Could not connect", installed cards show a check with "Installed".

### Motion

- Filtering: removed cards fade out in 90ms and pop out of flow; remaining cards glide to their new cells on a critically damped spring (0.3s, no bounce), and the grid's height springs to the new row count.
- The chip highlight slides between chips on a 0.24s spring with no bounce. Text never animates layout.
- Card steps crossfade in place inside a fixed 176px card (out 100ms, in 160ms with 2px rise), so nothing changes size between states.
- Granting access connects apps one by one (340ms apart): a spinner, then a check that scales in without overshoot. The install button keeps its width while loading.
- Hover reveal of Preview and Install is a 160ms opacity and 2px rise. Touch screens show them permanently.
- Reduced motion keeps every end state and feedback but drops travel, staggers and the layout glide.

### Responsive behavior

- Uses container queries: two columns from 600px of card width, one column below. The header stacks the search under the title below 560px.
- Team chips scroll sideways inside their row on narrow screens; the page never scrolls horizontally. Tested at 360px, 390px and desktop.
- On touch screens Preview and Install stay visible since there is no hover.

### Performance

- Filtering is a memoized pass over the catalog; only visible cards render.
- Height animation reads one ResizeObserver; resizes jump instead of animating.
- No timers run while idle; the connect sequence uses abortable timeouts cleared on cancel or unmount.

### Notes for AI agents

- Pass real marks as ReactNode (inline SVG at 16px). Mono marks should draw with currentColor so they follow the theme.
- Keep job lines to one sentence of about 60 characters; the card reserves two lines and clamps the rest.
- Each app's scope is the plain language permission shown on the grant step. Keep it short and honest ("Draft email for your review").
- The card is a fixed height so the grid never jitters: preview shows the first three steps, the grant step fits three apps, and more than two workspaces scroll inside the step.
- onInstall should throw an Error with a short message; it is announced to screen readers after "could not be installed".

### Keywords

agent marketplace, agent templates, ai agents, agent gallery, integrations, install flow, oauth scopes, grant access, app directory, filter chips, search, claude, gpt, gemini, slack, hubspot, github

### Related

- agent-status
- tool-call
- model-picker
- agent-routines
- agent-approvals

---

## AI feature launch

An in-product launch card for an AI feature. A looping mini demo plays above a three-step tour (inline rewrite, thread summary, ask your workspace), with benefit rows, an admin-gated "Enable for my workspace" switch, and Try it now and Learn more actions.

- Type: Block (composition)
- Access: Pro
- Built from: Button, Switch, Text shimmer
- Documentation: https://uiarc.dev/components/blocks/ai-feature-launch

### Overview

Show it once when a member first opens the product after an AI feature ships, inline or inside a Dialog. Wire `onEnabledChange(enabled, signal)` to your settings endpoint. The switch shows the new value while the save runs. Toggling again aborts the signal and reverts, and a rejection shows an error note. Set `canManage` from the viewer's role, and `onTry` / `onLearnMore` to open the feature and the docs. To replace the tour, pass `steps`. Each `demo` can be a function of the loop time in ms, so pausing, looping, freezing between steps and reduced motion all work without timers.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/ai-feature-launch. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/ai-feature-launch while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- Announcing a new AI feature inside the product, with a tour of what it does and a switch to turn it on for the workspace.
- Admin-gated rollouts where an admin enables AI for everyone and members can still try it.
- A what's new modal or popover that needs to look polished in a launch clip.

### When not to use

- Multi-step configuration with real inputs (models, data sources): use ai-setup-wizard.
- Ongoing activation tasks: use onboarding-checklist.
- A long changelog or release notes page: render the entries as a page instead.

### Usage

```tsx
import { AiFeatureLaunch } from "@/components/arc/blocks/ai-feature-launch/ai-feature-launch";

export function AiLaunch({ workspace, isAdmin }: { workspace: { name: string; members: number; aiEnabled: boolean }; isAdmin: boolean }) {
  return (
    <AiFeatureLaunch
      workspaceName={workspace.name}
      memberCount={workspace.members}
      canManage={isAdmin}
      defaultEnabled={workspace.aiEnabled}
      onEnabledChange={async (enabled, signal) => {
        const res = await fetch("/api/workspace/ai", { method: "PATCH", body: JSON.stringify({ enabled }), signal });
        if (!res.ok) throw new Error("Could not save");
      }}
      onTry={() => router.push("/editor?ai=1")}
      onLearnMore={() => window.open("/docs/ai", "_blank")}
    />
  );
}
```

### API

#### AiFeatureLaunch

An in-product launch card for an AI feature: a looping mini demo, a three-step tour with dots, three benefit rows per step, a workspace switch with an admin note, and Try it now and Learn more actions. With no props it plays a simulated tour of inline rewrite, thread summary and workspace search, and every action says that it was simulated.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `steps` | `LaunchStep[]` | `rewrite, summarize, ask` | Tour steps: { id, title, description, benefits, demo?, posterTime? }. The card is always as tall as its tallest step, so switching steps never resizes it. |
| `step` | `number` |  | Controlled step index. Pair with onStepChange. |
| `defaultStep` | `number` | `0` | Starting step when uncontrolled. |
| `onStepChange` | `(index: number) => void` |  | Called when the step changes from the dots, the arrow keys or autoplay. |
| `autoPlay` | `boolean` | `true` | Advances to the next step after each preview loop. Stops for good on any interaction, waits while the pointer is over the card, and is off with reduced motion. |
| `stepDuration` | `number` | `6400` | Length of one preview loop in milliseconds. The active dot fills over this time while autoplay runs. |
| `workspaceName` | `string` | `"Halcyon"` | Workspace named in the saved and simulated announcements. |
| `memberCount` | `number` | `48` | Members the setting applies to, used in the note and the pending label. |
| `canManage` | `boolean` | `true` | When false the switch is disabled and the note says only admins can change it, while Try it now still works. |
| `enabled` | `boolean` |  | Controlled workspace setting. |
| `defaultEnabled` | `boolean` | `false` | Starting setting when uncontrolled. |
| `onEnabledChange` | `(enabled: boolean, signal: AbortSignal) => Promise<void> \| void` |  | Saves the setting. The switch shows the new value while it runs and the note shimmers; toggling again aborts the signal and reverts; a rejection reverts and shows an error note. Leave it out to simulate a 0.9s save. |
| `onTry` | `(signal: AbortSignal) => Promise<void> \| void` |  | Primary action, for example opening the editor with the feature focused. The button shows a spinner while the promise runs. Simulated when omitted. |
| `onLearnMore` | `() => void` |  | Secondary action, for example opening the docs or a changelog entry. Simulated when omitted. |
| `modelName` | `string` | `"Claude Sonnet 5.5"` | Model credited in the footer ("Runs on ..."). |
| `modelMark` | `ReactNode` | `Claude mark` | 14px mark before the model name. |
| `enableLabel` | `string` | `"Enable for my workspace"` | Switch label. |
| `tryLabel` | `string` | `"Try it now"` | Primary action label. |
| `learnMoreLabel` | `string` | `"Learn more"` | Secondary action label. |
| `className` | `string` |  | Extra class on the root card. |

#### LaunchStep

One step of the tour.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `id` (required) | `string` |  | Stable key. |
| `title` (required) | `string` |  | Step title, sentence case, one line. |
| `description` (required) | `string` |  | One sentence under the title. |
| `benefits` (required) | `{ icon: LucideIcon; label: string }[]` |  | Up to three rows with a 16px icon. Keep labels under about 45 characters. |
| `demo` | `ReactNode \| ((time: number) => ReactNode)` |  | The preview in the stage. A function gets the loop time in milliseconds, so a mini demo is a pure function of time that pauses, loops and freezes for free. Return the start state at 0 and near the end of the loop so it repeats seamlessly. |
| `posterTime` | `number` | `60% of stepDuration` | Loop time shown as a still frame with reduced motion. Pick the most telling moment. |

### Dependencies

- `motion`
- `lucide-react`
- `@radix-ui/react-switch`

### Keyboard

| Keys | Action |
| --- | --- |
| Tab | Moves through the active tour dot, the workspace switch, Learn more and Try it now. |
| ArrowLeft / ArrowRight | On the dots, moves to the previous or next step and stops autoplay. |
| Home / End | On the dots, jumps to the first or last step. |
| Space | Toggles the workspace switch. Pressing it again while saving cancels the save. |
| Enter / Space | Activates a dot or an action button. |

### Accessibility

- The card is a labelled section whose name follows the current step title. Only the active step is exposed; hidden steps are aria-hidden and inert.
- The preview stage is decorative (aria-hidden): the title, description and benefits carry the same message as text.
- Dots are buttons named "Step 2 of 3: Catch up on any thread" with aria-current="step" and a roving tab stop.
- The switch is labelled by its visible label and described by the admin note. Saving, cancelled, saved, error and simulated results are announced in a polite live region.
- Status is never color alone: the saved note pairs a check with "On for all 48 members", the error note pairs an alert icon with text.
- Autoplay stops on the first interaction and waits while the pointer is over the card, so nobody loses a step they are reading.

### Motion

- One shared loop clock drives the mini demo, the dot fill and autoplay, so they never drift. It pauses off screen.
- Step changes are a single crossfade: the old step fades out in 100ms, the new one fades in over 160ms and rises 2px. All steps share one grid cell, so the card never changes height.
- Mini demos stream text in chunks of three words every 40ms, each chunk only fading in; thinking labels shimmer for under a second.
- The active dot widens on a bounce-free spring (0.24s) and fills linearly with the loop.
- Reduced motion: no autoplay or loops, each step shows a still frame at posterTime, and feedback (notes, spinner) stays.

### Responsive behavior

- Fills its container up to 520px. Below 440px (container query) the actions span the width and the model credit centers under them.
- The mini demo panel caps at 380px inside the stage and truncates long lines with an ellipsis, so it holds at 360px.
- Dots have 24px tall hit areas; the switch keeps the Arc switch's touch size.

### Performance

- The active demo re-renders on a 40ms grid (about 25 renders a second) while visible; leaving demos freeze and unmount.
- Inactive step copy stays mounted for the height reservation but is hidden and inert.
- Three inline SVG marks and three 20px avatars; no images in the copy.

### Notes for AI agents

- Use it once, the first time a member opens the product after an AI feature ships; persist dismissal yourself (put it in a Dialog or a popover and close it from onTry).
- Swap the default steps for your own: write each demo as a pure function of time using the loop time argument rather than timers, so pause, loop and reduced motion work automatically.
- Wire onEnabledChange to a real settings endpoint and respect the AbortSignal; set canManage from the viewer's role.
- Keep three steps with three benefits each; the card is designed for 360 to 520px.

### Keywords

ai feature launch, introducing ai, feature announcement, launch modal, whats new, product tour, onboarding tour, enable ai, workspace setting, admin toggle, rollout, announcement card, notion ai, linear launch, pagination dots

### Related

- ai-setup-wizard
- onboarding-checklist
- catch-up
- ghost-text
- ai-answer
- switch
- text-shimmer

---

## AI search bar

A search card for an app or docs, where typing lists grouped results right away (Docs, Customers, Issues) and pressing Tab streams a short AI answer on top. The answer's numbered citations point to the results below it.

- Type: Block (composition)
- Access: Pro
- Built from: Kbd, TextShimmer
- Documentation: https://uiarc.dev/components/blocks/ai-search-bar

### Overview

Pass `search(query, signal)` so it returns `AiSearchResult[]` (each with id, group, title, description, meta, icon or issue status), either directly or as a promise. Pass `answer({ query, results, signal })` as an async iterable: first yield `{ type: "sources", ids }`, then `{ type: "text", text }` pieces, where [n] cites ids[n - 1] and backticks render as inline code. To show the error state with Try again, throw. Wire `onSelect` to open a result and `onAsk` for analytics. Set `groups`, `recent`, `suggestions` and `model` to match your product. If you pass neither `search` nor `answer`, the card plays a scripted demo until someone touches it.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/ai-search-bar. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/ai-search-bar while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- A product or docs search where people mix finding a page or record with asking a question.
- Support and success tools that search docs, customers and tickets in one place.
- A command bar or search dialog that should offer an AI answer without leaving the results.

### When not to use

- Use ai-answer for a full answer page with long formatted answers, follow ups and feedback.
- Use ai-chat for a back and forth conversation.
- Use ai-command for an action palette that runs commands rather than searches content.

### Usage

```tsx
import { AiSearchBar, type AiSearchAnswerEvent } from "@/components/arc/blocks/ai-search-bar/ai-search-bar";

async function search(query: string, signal: AbortSignal) {
  const response = await fetch(`/api/search?q=${encodeURIComponent(query)}`, { signal });
  return response.json(); // [{ id, group: "docs", title, description, meta }]
}

async function* answer({ query, results, signal }) {
  const response = await fetch("/api/ask", { method: "POST", body: JSON.stringify({ query, ids: results.map(r => r.id) }), signal });
  if (!response.ok) throw new Error("The assistant is busy. Try again in a moment.");
  for await (const event of readNdjson<AiSearchAnswerEvent>(response.body!)) yield event;
}

export function AppSearch() {
  return (
    <AiSearchBar
      search={search}
      answer={answer}
      recent={recentSearches}
      suggestions={["How do I set up SAML SSO?", "How do I rotate an API key safely?"]}
      onSelect={result => router.push(result.href!)}
      onAsk={query => track("search_ask_ai", { query })}
    />
  );
}
```

### API

#### AiSearchBar

One search card for an app or docs. Typing lists grouped results at once (Docs, Customers, Issues from Linear) with the matched words highlighted, and the arrow keys move through them. The first row is "Ask AI about ...": press Tab or click it and a short answer streams in its place, with numbered citations that match small number badges on the results below; hovering or focusing a citation lights its result, and clicking it jumps there. With an empty field it shows recent searches and suggested questions. The field, a fixed height body and a footer with key hints and the model never change size between states. With no props it plays a short scripted search and answer until touched.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `search` | `(query: string, signal: AbortSignal) => AiSearchResult[] \| Promise<AiSearchResult[]>` |  | Returns results for a query. Sync results show in the same frame; a promise keeps the previous list and swaps the search icon for a spinner until it resolves. Stop when `signal` aborts. Each result is { id, group, title, description?, meta?, icon?, status?, href? }. Defaults to a sample search over a developer platform's docs, customers and issues. |
| `answer` | `(request: AiSearchAnswerRequest) => AsyncIterable<AiSearchAnswerEvent>` |  | Streams the AI answer. The request has { query, results, signal } with the results on screen. Yield { type: "sources", ids } first, then { type: "text", text } pieces; [n] in the text cites ids[n - 1] and `code` spans render as inline code. Throw to show the error state with Try again. Defaults to a scripted demo that sends nothing. |
| `groups` | `AiSearchGroup[]` | `Docs, Customers, Issues` | Sections in order: { id, label, icon?, source? }. `icon` is the default 16px icon for results without one; `source` ({ name, mark? }) shows where a group comes from on the right of its heading. Results with an unknown group go under Other. |
| `recent` | `string[]` | `["webhook retries", "Figma", "AUTH-912"]` | Recent searches shown when the field is empty. Picking one fills the field. New searches and opened results are added for the session, three at most. |
| `suggestions` | `string[]` |  | Suggested questions shown when the field is empty. Picking one asks AI right away. The demo offers three. |
| `model` | `{ name: string; mark?: ReactNode }` | `Claude Sonnet 5.5` | The model named in the footer and on the answer, with its mark. |
| `placeholder` | `string` | `"Search docs, customers and issues"` | Placeholder in the empty field. |
| `autoPlay` | `boolean` | `true without search or answer` | Plays a scripted search, Tab and answer, then a suggested question, while on screen. Any pointer, key or focus inside the card stops it for good. Plays once with reduced motion. |
| `onSelect` | `(result: AiSearchResult) => void` |  | Called when a result is opened with Enter or a click. Without it the footer confirms the open and the status says it was simulated. |
| `onAsk` | `(query: string) => void` |  | Called when AI is asked, just before the answer streams. |
| `className` | `string` |  | Class on the card. It is 100% wide up to 640px. |

### Dependencies

- `motion`
- `lucide-react`

### Keyboard

| Keys | Action |
| --- | --- |
| Arrow down / Arrow up | Moves through Ask AI and the results, or through recent searches and suggestions when the field is empty. Wraps at both ends and keeps the active row in view. |
| Enter | Opens the active result, fills the field with a recent search, asks a suggested question, or asks AI from the Ask AI row. |
| Tab | With text in the field and no answer yet, asks AI about it. Otherwise moves focus as usual: clear, copy and close on the answer, then each citation. |
| Escape | Closes the answer first, then clears the field. |
| Enter, Space | On a citation, jumps to its result and makes it active. |

### Accessibility

- The field is a combobox with aria-activedescendant, so focus stays in the field while the arrow keys move the active option. Results sit in a listbox with one labelled group per section; the Ask AI row is its own small listbox, and aria-controls names both.
- Each option has a full label: title, description, meta or issue status, and "cited as source n" once the answer cites it. The number badges are aria-hidden because the label carries them.
- The answer is a labelled region with aria-busy while it streams. A polite status region announces Asking AI, Answer ready with the source count, Answer closed, results opened and errors, and says Simulated when the demo stands in for a real model or link.
- Citations are buttons named "Source n: title"; focus lights the matching result just like hover. Highlights in titles are a visual aid only.
- Issue status is an icon plus a text label, never color alone. The error state shows an icon, the message and a Try again button.
- Pointer focus draws no ring; keyboard focus shows Arc's shared focus ring.

### Motion

- Results update in the same frame as each keystroke with no animation, like a native search; the active row's background changes in 80ms.
- Switching between the empty view and results crossfades (out 100ms, in 160ms). The body has a fixed height, so the card never resizes.
- Asking AI crossfades the Ask AI row into the answer panel while the slot's height follows its content on a 240ms spring with no bounce.
- The status shimmers "Thinking" for about half a second, then "Writing", then settles to "4 sources". The answer streams on a requestAnimationFrame clock: every 34ms three to eight words commit together and fade in over 140ms, with no blur, travel or stagger.
- Number badges fade in on results as their citations arrive. Copy swaps its icon for a check in place.
- Reduced motion keeps the chunked arrival and every state but drops the fades, shimmer, pulse and the auto play loop.

### Responsive behavior

- The card is 100% wide up to 640px. Below about 520px the footer keeps only the Ask AI hint and the model, and below about 400px result descriptions hide so titles keep their room.
- Titles truncate after descriptions, which truncate first; meta stays right aligned in tabular numerals.
- The field uses 16px text so phones do not zoom on focus.

### Performance

- Streamed text is split into stable units, so each tick only appends a new span and earlier text never re-renders.
- One requestAnimationFrame loop runs only while an answer streams, and an aborted ask or a new query stops it and the request at once.
- Auto play pauses while the card is off screen or the tab is hidden.

### Notes for AI agents

- Choose it for in-app or docs search that should answer questions as well as find things: a support console, an admin app, a docs site, an internal knowledge base.
- Send `sources` before the text so badges can appear as citations stream. Cite only results the request carried; a cited id that is not on screen still shows its number but has nothing to jump to.
- Keep answers to two to four sentences; this is a search, not a chat. Link out to a full answer page (ai-answer) for longer replies.
- Results are grouped by `group` in the order of `groups`; return at most three to five per group so the answer and every section fit in the body.
- Brand marks and ARR figures are sample content. Pass your own `icon` per result; keep color brands in their colors and mono marks on currentColor.

### Keywords

ai search, search bar, ask ai, command palette, docs search, instant search, grouped results, keyboard navigation, citations, streaming answer, algolia ask ai, mintlify search, linear search, combobox, rag

### Related

- ai-answer
- ai-command
- ai-chat
- ai-side-panel
- text-shimmer

---

## AI setup wizard

A three-step setup card for turning on an AI feature. You connect Notion, Google Drive, Confluence or Zendesk and watch each one sync. Then you pick the model, tone and guardrails, and ask a test question whose answer streams with numbered citations before you go live.

- Type: Block (composition)
- Access: Pro
- Built from: Button, SegmentedControl, Switch, TextShimmer
- Documentation: https://uiarc.dev/components/blocks/ai-setup-wizard

### Overview

Drop `<AiSetupWizard featureName="Ask Acme" />` into the first-run screen of your AI assistant or copilot. Connect your real sync job with `onConnect(source, report, signal)` and call `report(0..1)` as items arrive. Wire `onAsk(question, config, signal)` to your assistant so the test uses the unsaved config; it returns `{ text, citations }` with `[1]` markers in the text. `onGoLive(config, signal)` turns the feature on. `sources`, `models`, `tones`, `guardrails` and `suggestions` replace the sample content, and `onStepChange` and `onConfigChange` report progress. With no handlers it plays the simulated Ask Northwind flow in a loop, which stops on the first interaction. Set `autoPlay={false}` to turn the loop off.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/ai-setup-wizard. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/ai-setup-wizard while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- Turning on an AI answers feature for a support, sales or internal knowledge team, like Intercom Fin, Zendesk AI or Notion Q&A.
- Onboarding admins to a copilot that needs data sources, a model choice and guardrails before it is enabled.
- A landing page or product tour section that shows the full setup in one short, looping clip.

### When not to use

- Configuring an agent's instructions, tools and files in depth: use agent-builder.
- Only choosing a model: use model-picker.
- A full conversation after setup: use ai-chat. The test step answers one question at a time.
- Monitoring a running agent: use agent-status.

### Usage

```tsx
import { AiSetupWizard } from "@/components/arc/blocks/ai-setup-wizard/ai-setup-wizard";

export function TurnOnAnswers() {
  return (
    <AiSetupWizard
      featureName="Ask Acme"
      onConnect={async (source, report, signal) => {
        const job = await startSync(source.id, { signal });
        for await (const progress of job.progress()) report(progress);
      }}
      onAsk={(question, config, signal) => askAssistant(question, config, { signal })}
      onGoLive={config => saveAssistant({ ...config, enabled: true })}
    />
  );
}
```

### API

#### AiSetupWizard

A three step card for turning on an AI feature. Step 1 connects data sources (Notion, Google Drive, Confluence, Zendesk) with a live sync count and a progress line per row. Step 2 picks the model from three cards, a tone and three guardrail switches. Step 3 asks a test question; the answer streams in fast chunks with numbered citations that match the connected sources. Go live shows a drawn check and a summary of the setup, and the header flips from Draft to Live. With no props it plays the Ask Northwind support assistant sample end to end and loops until someone interacts.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `featureName` | `string` | `"Ask Northwind"` | The AI feature being turned on. Used in the title ("Set up Ask Northwind") and the confirmation. |
| `audience` | `string` | `"Answers for 48 agents in Northwind support"` | One muted line under the title, such as who gets the feature. |
| `logo` | `ReactNode` | `<NorthwindMark />` | The company or product mark left of the title, drawn at 24px. Defaults to the Northwind sample mark; pass null to hide it. |
| `sources` | `WizardSource[]` | `defaultSources` | Sources for step 1: { id, name, description, count, unit, mark? }. Four fit the card. Defaults to Notion, Google Drive, Confluence and Zendesk with their marks. |
| `models` | `WizardModel[]` | `defaultModels` | Three model cards: { id, name, shortName?, note?, mark? }. Defaults to Claude Sonnet 5.5, GPT-6.1 Sol and Gemini 4 Argon. |
| `tones` | `WizardOption[]` | `defaultTones` | Tone options for the segmented control: { value, label }. Defaults to Concise, Friendly and Formal. |
| `guardrails` | `WizardGuardrail[]` | `defaultGuardrails` | Up to three switches: { id, label, defaultOn? }. Defaults to citing sources, handing off when unsure and redacting personal data. |
| `suggestions` | `string[]` | `defaultSuggestions` | Up to three sample questions offered in step 3 before the first test. |
| `defaultModelId` | `string` |  | The model selected at the start. Defaults to the first model. |
| `defaultTone` | `string` |  | The tone selected at the start. Defaults to the first tone. |
| `onConnect` | `(source: WizardSource, report: (progress: number) => void, signal: AbortSignal) => Promise<void>` |  | Connects and syncs one source. The row shows Connecting until the first report call, then the synced count and a progress line. Resolve when the sync is done; reject with an Error to show its message on the row with a Retry button. Simulated when left out. |
| `onAsk` | `(question: string, config: WizardConfig, signal: AbortSignal) => Promise<WizardAnswer>` |  | Answers a test question with the current config. Return { text, citations: { sourceId, title }[] } and write [1], [2] into text in citation order. The signal aborts when the person presses Stop. Simulated when left out. |
| `onGoLive` | `(config: WizardConfig, signal: AbortSignal) => Promise<void>` |  | Turns the feature on. Resolve to show the confirmation; reject to show the error in the footer with Try again. Simulated when left out. |
| `onStepChange` | `(step: number) => void` |  | Called with 0, 1 or 2 for the steps and 3 for the live confirmation. |
| `onConfigChange` | `(config: WizardConfig) => void` |  | Called with { sources, modelId, tone, guardrails } whenever a source finishes syncing or a setting changes. |
| `autoPlay` | `boolean` |  | Plays the whole flow on its own and loops, pausing off screen. The first pointer or key press inside the card stops it. Defaults to true when none of onConnect, onAsk or onGoLive is passed; always off with reduced motion. |
| `className` | `string` |  | Extra class on the card. |

### Dependencies

- `motion`
- `lucide-react`
- `@radix-ui/react-switch`

### Keyboard

| Keys | Action |
| --- | --- |
| Tab | Moves through the stepper, row actions, settings, the composer and the footer buttons. |
| Arrow keys | Move between model cards and select the focused one (radio group). |
| Space | Toggles the focused guardrail switch. |
| Enter | Asks the typed question, or stops an answer that is streaming. |

### Accessibility

- The stepper is an ordered list of buttons; the current step has aria-current="step" and completed steps say so. Steps not reached yet are disabled.
- Model cards are a radiogroup with roving focus; each radio is labelled with the full model name and note.
- A polite status region announces step changes, finished syncs, answers and going live, and says when the sample is simulated.
- Status is never color alone: synced rows show a check and "Synced", errors an alert icon and text, the header a Draft or Live label with its icon.
- Focus stays on the footer button across steps because the same button changes its label; Back keeps its space when hidden so nothing shifts.

### Motion

- Steps slide 32px horizontally with a bounce free spring (visualDuration .24) and an opacity crossfade, inside a fixed height viewport, so the card never changes size.
- Stepper bars fill with scaleX and glyphs crossfade from number to check. Row meta, footer meta and status labels swap with one crossfade (100ms out, 160ms in, 2px rise).
- Answers stream three to six words every 34ms and each chunk only fades in; citations fade in after the stream with a 40ms stagger.
- The confirmation draws its circle and check with pathLength. Reduced motion drops travel, drawing and streaming (answers appear whole) and turns off the self playing demo.

### Responsive behavior

- Fills its container up to 600px. Below 480px the padding drops to 16px, stepper labels shorten to one word and model names may wrap to two lines.
- Below 400px the footer meta hides and only Back and the primary button remain; citation source names hide and titles truncate.
- Holds up at 360px with no horizontal scroll; the step viewport keeps one height at every width.

### Performance

- Plain DOM and CSS; motion animates opacity, small transforms and scaleX only.
- The self playing loop only counts time while the card is on screen (IntersectionObserver) and stops for good on the first interaction.
- Streaming appends one chunk span every 34ms with a CSS fade, so earlier text never re-renders its animation.

### Notes for AI agents

- Use it as the first run setup for an AI assistant, copilot or answer engine inside a SaaS product, where admins choose data, behavior and test before turning it on.
- Wire onConnect to your sync job and call report as it progresses; onAsk should call the real assistant with the config so the test reflects unsaved settings.
- Citation sourceIds must match WizardSource ids so the marks line up. Keep the answer under about 320 characters so it fits without scrolling.
- Marks are 20px square SVGs in rows and 14px in citations, and the header logo is 24px; mono marks should use currentColor so they follow the theme.
- Tabular figures are applied only to spans that hold nothing but a number (sync counts, percentages, citation numbers), so model names like GPT-6.1 keep normal spacing.
- Pass autoPlay={false} when embedding with real handlers if you also leave one of them out.

### Keywords

AI setup wizard, onboarding wizard, stepper, connect data sources, knowledge base sync, model picker, guardrails, test AI answer, citations, go live, AI feature onboarding, RAG setup

### Related

- agent-builder
- model-picker
- ai-chat
- agent-status
- tool-call

---

## Smart scheduler

A scheduling card where one sentence like "Find 30 min with Maya and Leo next week, mornings" is read into chips. The three best slots are then ranked across everyone's Google Calendar and Outlook calendars, with an availability strip per person and conflicts called out. Picking a slot opens a draft invite with a Google Meet link, ready to send.

- Type: Block (composition)
- Access: Pro
- Built from: Button, CopyButton, TextShimmer
- Documentation: https://uiarc.dev/components/blocks/smart-scheduler

### Overview

Drop it into a CRM, recruiting tool or team app as the "find a time" step. Pass `parse` for your LLM call (structured output: duration, people, range, window) and keep `findSlots` deterministic on your server (Google freeBusy or Microsoft Graph getSchedule). Each slot returns every attendee's busy blocks for that day so the strips can draw them. `onSend` creates the event (reject to show a retry), and `onPick` plus `meetLink` let you create a real Meet link before sending. With no props it plays a simulated run on a loop until someone clicks or types in the card. The sample parser and slot finder (`parseScheduleRequest`, `findScheduleSlots`) are exported as a reference.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/smart-scheduler. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/smart-scheduler while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- A scheduling assistant inside a CRM, recruiting tool, or team app that books internal meetings from one sentence.
- Showing why a time was suggested: who is free, what conflicts, and what is tentative.
- An AI feature demo where the result has to be checkable at a glance before anything is sent.

### When not to use

- Public booking pages where guests pick from your open times; use availability-picker or booking-pill.
- Browsing or editing a full calendar; use week-calendar or month-calendar.
- Picking a single date or time without other people involved; use date-picker or time-picker.

### Usage

```tsx
import { SmartScheduler } from "@/components/arc/blocks/smart-scheduler/smart-scheduler";

export function ScheduleCard({ me }) {
  return (
    <SmartScheduler
      organizer={me}
      defaultQuery=""
      timeZone="ET"
      parse={(query, signal) =>
        fetch("/api/schedule/parse", { method: "POST", body: JSON.stringify({ query }), signal }).then(async (res) => {
          if (!res.ok) throw new Error((await res.json()).message ?? "Couldn't read that request.");
          return res.json();
        })}
      findSlots={(request, signal) =>
        fetch("/api/schedule/slots", { method: "POST", body: JSON.stringify(request), signal }).then((res) => res.json())}
      onSend={(invite, signal) =>
        fetch("/api/schedule/invite", { method: "POST", body: JSON.stringify(invite), signal }).then((res) => {
          if (!res.ok) throw new Error("Not sent");
        })}
    />
  );
}
```

### API

#### SmartScheduler

Natural language scheduling in one card. A request such as "Find 30 min with Maya and Leo next week, mornings" is read into chips (duration, people with their avatars, range, time of day), then the three best slots are ranked across everyone's calendars. Above the list, one availability strip per person (with a Google Calendar or Outlook mark) draws that day's busy blocks, and an outlined column marks the slot under the pointer, sliding as you move between suggestions. Conflicts are called out with a warning icon and a short reason ("Leo's Arch office hours is tentative") and tint the block they overlap. Picking a slot opens a draft invite in the same space: an editable title, the time, a Google Meet link with a copy button, the guests, and Send invite, which turns into Sent. With no props it plays a simulated run on a loop until someone interacts.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `defaultQuery` | `string` | `"Find 30 min with Maya and Leo next week, mornings"` | The request in the field on first render. |
| `placeholder` | `string` | `"Find 30 min with Maya next week"` | Placeholder for the empty field. |
| `organizer` | `SchedulerPerson` | `Sofia Ramirez (sample)` | The person sending the invite: { id, name, avatar?, email?, calendar?: "google" \| "outlook" }. Shown as "You" in the strips. |
| `directory` | `SchedulerPerson[]` | `sample directory` | People the built in parser can match by first name. Ignored when you pass parse. |
| `parse` | `(query: string, signal: AbortSignal) => Promise<ScheduleRequest>` |  | Turns the request into { duration (min), people, range: { label, detail, days: { id, label }[] }, window: { id, label, start, end } } (minutes from midnight). Wire your LLM call with structured output here. Throw an Error with a short message to show it in the card. A new request aborts the signal. |
| `findSlots` | `(request: ScheduleRequest, signal: AbortSignal) => Promise<SlotSuggestion[]>` |  | Returns ranked slots, best first; the first three are shown. Each is { id, day, start, end, reason, conflicts: { personId, title, tentative? }[], busy: Record<personId, BusyBlock[]> }. busy feeds the strips. An empty array shows the no time works state. |
| `onSend` | `(invite: InviteDraft, signal: AbortSignal) => Promise<void>` |  | Sends { title, slot, organizer, people, meetLink, timeZone }. Reject to show Couldn't send with the button ready to retry. Without it the send is simulated and the card says nothing was sent. |
| `onPick` | `(slot: SlotSuggestion) => void` |  | Called when a slot is picked and the draft opens. |
| `meetLink` | `string` | `"meet.google.com/kfq-rvwp-zte"` | Video link on the draft. Create a real one in onPick (Google Calendar conferenceData) and pass it back. |
| `timeZone` | `string` | `"ET"` | Short time zone label shown beside the window and the invite time. |
| `autoPlay` | `boolean` | `true without parse, findSlots and onSend` | Plays read, preview, pick and send on a loop. Stops for good on the first click or key press in the card, pauses off screen, and is off under reduced motion. |
| `className` | `string` |  | Class on the root element. |

#### BusyBlock

One event on an attendee's day, as drawn in the strips.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `start` (required) | `number` |  | Minutes from midnight. |
| `end` (required) | `number` |  | Minutes from midnight. |
| `title` (required) | `string` |  | Event title, used in the block's tooltip, the strip's label and conflict reasons. |
| `tentative` | `boolean` |  | Drawn with a dashed outline and treated as a soft conflict. |

### Dependencies

- `motion`
- `lucide-react`

### Keyboard

| Keys | Action |
| --- | --- |
| Enter | In the field, reads the request and finds times. |
| Tab | Moves from the field to Find times, then to the suggested slots, or through the draft's title, copy link, Back and Send invite. |
| Arrow up / Arrow down | Moves between the suggested slots; focusing a slot previews it in the strips. |
| Enter / Space | On a slot, opens the draft invite. |
| Escape | In the draft, goes back to the suggestions. |

### Accessibility

- The field is a labeled search form, the chips are a list named What was understood, and the slots are a list of buttons whose text carries the day, the time and the reason.
- Each strip is an image with a label listing that person's events in the window, with tentative ones marked, or free.
- Conflicts are never color alone: a warning icon plus a reason in words, and a dashed outline for tentative events.
- Reading, the parsed request, the number of times found, the draft and the send result are announced in a polite status region; the demo says nothing was sent.
- Pointer focus draws no ring; keyboard focus shows Arc's shared focus ring.

### Motion

- Chips fade in from 2px, 40ms apart. Reading and checking calendars show a short shimmer on the label.
- The slot highlight and the strip column slide together on a critically damped spring (0.24s, no bounce) as the pointer or focus moves; busy blocks crossfade when the day changes.
- Suggestions, states and the draft share one fixed height and swap with a single crossfade (out 100ms, in 160ms), so the card never changes size. Send invite turns into Sent through the button's own label crossfade.
- The demo loop pauses off screen. Reduced motion drops the loop and the travel and opens on the ranked times.

### Responsive behavior

- Holds from 360px to 600px. Below about 460px the button keeps only its icon, chip details hide and the name column narrows; below 400px the people chip shows avatars only.
- Long names, reasons and links truncate with an ellipsis; nothing wraps, so rows keep their height.

### Performance

- Pure React and CSS with motion for the highlight, column and crossfades. No canvas, no timers beyond the demo script, and the loop stops off screen.
- Strips render only the blocks inside the time window.

### Notes for AI agents

- Use parse for the LLM step (structured output with duration, people ids, range, window) and keep findSlots deterministic: query free/busy (Google Calendar freeBusy, Microsoft Graph getSchedule) and score slots server side.
- Return busy blocks for every attendee on each slot's day so the strips can draw them; titles can be "Busy" when you only have free/busy access.
- The built in parseScheduleRequest and findScheduleSlots are exported and work on the sample calendars; they are a reference, not a production parser.

### Keywords

ai scheduling, natural language scheduling, find a time, meeting scheduler, availability, free busy, calendar assistant, google calendar, outlook, google meet, invite, booking

### Related

- availability-picker
- week-calendar
- booking-pill
- meeting-summary
- smart-form-fill
- date-range-picker

---

## Task breakdown

A goal input where AI breaks one sentence into a plan: tasks stream in with estimates, owners and dependencies, and a live timeline shows whether the deadline holds. Reorder, edit or regenerate any task, then send the plan to Linear or Jira with progress for each issue and links.

- Type: Block (composition)
- Access: Pro
- Built from: Button, TextShimmer
- Documentation: https://uiarc.dev/components/blocks/task-breakdown

### Overview

Drop `<TaskBreakdown />` into a planning surface. With no props it plays a simulated plan. Pass `generate(goal, signal)` returning `TaskDraft[]` (id, title, estimate in working days, ownerId, dependsOn) and the block streams the rows in, works out the critical path, the ship date and the slack against `deadline`, and keeps them current as people edit. Pass `createIssue(target, task, signal)` returning `{ key, url }` to create real Linear or Jira issues one by one in list order. `regenerate` rewrites a single task, `owners` supplies your team's portraits, and `onTasksChange` and `onSent` report edits and finished exports.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/task-breakdown. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/task-breakdown while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- Turning a goal or brief into a scoped project plan inside a PM, CRM or internal tool.
- Exporting AI drafted work to Linear or Jira with a review step before anything is created.
- Showing whether a plan fits a deadline and updating that as people edit estimates.

### When not to use

- Showing an agent working through steps live; use agent-plan.
- A full backlog or board with many projects; use a dedicated table or kanban.
- Single task creation from a prompt; a simple composer is lighter.

### Usage

```tsx
import { TaskBreakdown } from "@/components/arc/blocks/task-breakdown/task-breakdown";

export function PlanFromGoal() {
  return (
    <TaskBreakdown
      deadline="2026-12-01"
      generate={async (goal, signal) => {
        const res = await fetch("/api/plan", { method: "POST", body: JSON.stringify({ goal }), signal });
        return res.json();
      }}
      createIssue={async (target, task, signal) => {
        const res = await fetch(`/api/${target}/issues`, { method: "POST", body: JSON.stringify(task), signal });
        return res.json(); // { key: "BIL-241", url: "https://linear.app/..." }
      }}
    />
  );
}
```

### API

#### TaskBreakdown

A goal input that turns one sentence into a project plan. Press Break down and, after a short "Planning tasks" shimmer, tasks stream into reserved rows in fast chunks, each with an estimate in working days, an owner avatar and its dependencies ("After 2, 3"). A summary above the list counts tasks and total effort, and a timeline bar draws the critical path from the start date toward the deadline marker with "Ships Nov 17, 10d early" or a warning when the plan runs late; both update live as rows land and as tasks change. Rows can be edited in place (title and estimate), reordered by dragging the grip or with the arrow keys, and regenerated one at a time. A dependency placed below its task turns into a "Waits on 5" warning. Send to Linear or Send to Jira creates one issue per task with a spinner per row, then swaps each row's actions for its issue key link. With no props it plays a simulated plan for "Launch usage-based billing by Dec 1".

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `defaultGoal` | `string` | `"Launch usage-based billing by Dec 1"` | Goal shown in the input on first render. |
| `defaultTasks` | `TaskDraft[]` |  | Tasks to open with. The block then starts ready instead of empty and does not auto start. A TaskDraft has id, title, estimate (working days, steps of 0.5), ownerId and dependsOn (task ids). |
| `owners` | `TaskOwner[]` | `demoOwners` | People tasks can be assigned to: id, name and an optional avatar URL (initials otherwise). |
| `generate` | `(goal: string, signal: AbortSignal) => Promise<TaskDraft[]>` |  | Breaks a goal into tasks. Rows stream in visually as soon as it resolves. Stop aborts the signal. Simulated with the sample plan when omitted. |
| `regenerate` | `(task: TaskDraft, context: { goal: string; tasks: TaskDraft[] }, signal: AbortSignal) => Promise<Partial<Omit<TaskDraft, "id">>>` |  | Rewrites one task. Return the fields to replace; the id and, unless returned, dependencies are kept. Simulated when omitted. |
| `createIssue` | `(target: "linear" \| "jira", task: TaskDraft, signal: AbortSignal) => Promise<{ key: string; url: string }>` |  | Creates one issue, called once per task in list order. A rejection marks that row failed with a retry button. Simulated (BIL-241 and up, PAY-318 and up) when omitted. |
| `targets` | `("linear" \| "jira")[]` | `["linear", "jira"]` | Trackers offered in the footer. The first one is the primary button. |
| `startDate` | `Date \| string` | `"2026-10-27"` | First working day of the plan. Weekends are skipped. |
| `deadline` | `Date \| string` | `"2026-12-01"` | Ship-by date, drawn as the marker on the timeline and used for the early or late label. |
| `model` | `string` | `"Claude Sonnet 5.5"` | Model named in the footer next to the Claude mark. |
| `autoStart` | `boolean` | `true without defaultTasks` | Run the breakdown once when the block scrolls into view. |
| `onTasksChange` | `(tasks: TaskDraft[]) => void` |  | Called after every edit, reorder or regeneration. |
| `onSent` | `(target: "linear" \| "jira", issues: Record<string, { key: string; url: string }>) => void` |  | Called once every task has an issue, keyed by task id. |
| `className` | `string` |  | Class on the root card. |

### Dependencies

- `motion`
- `lucide-react`

### Keyboard

| Keys | Action |
| --- | --- |
| Enter | In the goal input, breaks the goal down. While drafting the same button stops. |
| ArrowUp / ArrowDown | On a row's grip, moves the task up or down; focus stays on the grip. |
| Enter | While editing a row, saves the title and estimate. |
| Escape | While editing a row, cancels the edit. |
| Tab | Moves through the goal, each row's grip, regenerate and edit buttons, issue links and the footer actions. |

### Accessibility

- The card is a labelled section; the goal input has a label and the task list is an ordered list named Tasks.
- A polite live region announces planning, drafted counts, saves, moves ("Moved to position 3 of 7"), rewrites and issue creation, and says when an action was simulated.
- Each grip is a button named with the task and its position, and explains the arrow keys; row actions are named with the task number.
- Status never relies on color: late plans and blocked dependencies pair a warning icon with text, created issues show their key.
- Rows that are streaming or regenerating set aria-busy; the timeline bar has a text label with the ship date and the deadline.

### Motion

- Rows stream three words per 36ms tick, each chunk fading in over 140ms; meta fades in when the title completes. The thinking shimmer lasts under a second.
- Reordering uses bounce-free springs (visualDuration .24, bounce 0) on position only, so text is never scaled.
- Titles, estimates, owners, dependency labels and footer status swap with one crossfade (100ms out, 160ms in, 2px rise).
- Timeline segments glide their left and width on the same bounce-free spring; the list area reserves seven rows so the card never changes height between empty, drafting and ready.
- Reduced motion skips streaming and travel and keeps every end state and status.

### Responsive behavior

- The card fills its container up to 640px and holds at 360px without horizontal scroll.
- Below 520px container width the dependency column hides; below 440px the footer buttons shorten to the tracker name with their marks.
- Titles truncate with an ellipsis; row actions are always visible on touch screens.

### Performance

- Streaming is one interval and one state update per tick; it stops as soon as the last row lands.
- The schedule is a memoized dependency walk, linear in the number of tasks.
- Auto start waits for an IntersectionObserver and runs once; nothing loops off screen.

### Notes for AI agents

- Choose this when a user states a goal and needs a plan with estimates, owners and dependencies they can push to a tracker; it is a planning surface, not an execution log.
- Wire generate to a model call that returns TaskDraft[] with stable ids and dependsOn ids; the block computes the critical path and ship date itself.
- createIssue is called sequentially per task, so issue keys come back in list order; return the tracker's real key and URL.
- Owners are matched by ownerId; pass your team as owners with portrait URLs.
- For an agent that executes steps after approval use agent-plan instead.

### Keywords

task breakdown, ai project plan, goal to tasks, linear export, jira export, estimates, critical path, timeline, drag reorder, ai planning, work breakdown

### Related

- agent-plan
- agent-tasks
- tool-call
- agent-status

---

## Call insights

A sales call insights card where talk time, flagged pricing, competitor and objection moments, an AI summary and owned next steps sit in one view. Selecting a moment plays its quote, and checking off next steps lowers the deal risk.

- Type: Block (composition)
- Access: Pro
- Built from: Avatar, Checkbox, CopyButton, TextShimmer
- Documentation: https://uiarc.dev/components/blocks/call-insights

### Overview

Pass `call`, `speakers` (with side and talk share), `moments` (type, seconds, speakerId, quote, clip length), `summary` and `nextSteps` (with ownerId and due) from your transcription or conversation intelligence pipeline. Wire `loadClip(moment, signal)` to seek your audio player to `moment.at`; it should resolve when playback can start and abort on the signal. Use `onNextStepChange` to save step state. Leave `risk` unset to tie it to the open next steps, or pass your own score. Set `autoPlay={false}` in a product so the demo tour does not run.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/call-insights. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/call-insights while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- A deal page that shows the latest sales call with talk ratio, flagged moments, summary and next steps.
- A call review queue for sales managers who coach on talk time and objection handling.
- A research or support tool that recaps a recorded customer call with jump-to-quote clips.

### When not to use

- Full transcript reading or editing: use transcript-studio.
- An internal meeting recap without a prospect or deal: use meeting-summary.
- A pipeline overview across many deals: use a table such as crm-contacts.

### Usage

```tsx
import { CallInsights } from "@/components/arc/blocks/call-insights/call-insights";

export function DealCall({ call, transcript }) {
  return (
    <CallInsights
      call={{ title: "Data platform evaluation", company: "Ramp", date: "Oct 22, 2026", duration: 2052 }}
      speakers={transcript.speakers}
      moments={transcript.moments}
      summary={transcript.summary}
      nextSteps={transcript.nextSteps}
      autoPlay={false}
      loadClip={(moment, signal) => audio.load(call.recordingUrl, moment.at, { signal })}
      onNextStepChange={(step, done) => fetch(`/api/steps/${step.id}`, { method: "PATCH", body: JSON.stringify({ done }) })}
    />
  );
}
```

### API

#### CallInsights

A sales call distilled into one card. The header carries the prospect's logo, the call title, the meeting platform mark, date and length, the attendees and a deal risk chip. Talk time is one bar split by speaker and grouped by side, with a legend in tabular percentages. Key moments sit on a rail for the whole call as 24px markers (pricing, competitor mention, objection, each with its own icon); selecting one fills the rail up to it and crossfades the quote, speaker and timestamp into a well with a play button and a seekable waveform. Below are the AI summary, which streams in once with a copy button, and next steps with owners and due dates. Checking off a step lowers the deal risk when the risk is derived. With no props it renders a 34 minute Ramp evaluation on Zoom that tours its moments until someone interacts.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `call` | `CallDetails` | `Ramp evaluation on Zoom` | { title, company, logo?: ReactNode (20px, currentColor), platform?, platformMark?: ReactNode (14px), date, duration (seconds) }. |
| `speakers` | `CallSpeaker[]` | `four sample speakers` | { id, name, title?, avatar?, side: "internal" \| "external", talk }. talk is any scale and is normalised to 100. Talk time groups your team first, then the prospect. |
| `moments` | `CallMoment[]` | `five sample moments` | { id, type: "pricing" \| "competitor" \| "objection", at (seconds), speakerId, quote, clip (seconds) }. Positioned on the rail by at / call.duration. |
| `summary` | `string` | `sample summary` | AI summary. Streams in once when the card first scrolls into view, over a reserved block so the card never grows. An empty string shows the empty state. |
| `summaryModel` | `string` | `"Claude Sonnet 5.5"` | Model credited next to the summary heading. |
| `nextSteps` | `CallNextStep[]` | `three sample steps` | { id, label, ownerId, due, done?, risk? }. ownerId is a speaker id. risk (default true) means the open step keeps the deal at risk. |
| `risk` | `"low" \| "medium" \| "high"` |  | Fixed deal risk. When omitted it follows the open risk steps: all open (two or more) is high, some open is medium, none open is low. |
| `autoPlay` | `boolean` | `true` | Tours the moments and plays each clip while the card is on screen, until the first pointer or key press inside it. Always off with reduced motion. |
| `defaultMomentId` | `string` |  | Moment selected first. Defaults to the first moment. |
| `loadClip` | `(moment: CallMoment, signal: AbortSignal) => Promise<void>` |  | Resolves when the clip is ready to play; the button shows a spinner meanwhile and a rejection shows Clip unavailable with Retry. The signal aborts when another moment is selected or loading is cancelled. Without it, loading is simulated and the status region says no audio plays. |
| `onMomentChange` | `(moment: CallMoment) => void` |  | Called when a moment is selected, by click, keyboard or the tour. |
| `onNextStepChange` | `(step: CallNextStep, done: boolean) => void` |  | Called when a next step is checked or unchecked. Persist it here. |
| `className` | `string` |  | Class on the root section. |

#### deriveRisk

The rule the card uses when risk is omitted, exported so a list view can show the same chip.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `steps` (required) | `CallNextStep[]` |  | Next steps. |
| `done` (required) | `Record<string, boolean>` |  | Done state by step id. |

### Dependencies

- `motion`
- `lucide-react`
- `@radix-ui/react-checkbox`

### Keyboard

| Keys | Action |
| --- | --- |
| Tab | Moves through the selected moment marker, the play button, the waveform, the copy button and each next step checkbox. |
| Arrow keys, Home, End | On the markers, select the previous, next, first or last moment. On the waveform, seek one second back or forward, or to the start or end. |
| Space / Enter | Play, pause, cancel loading or retry the clip; toggle a next step. |

### Accessibility

- The card is a section named after the company. Markers are a radio group named Key moments; each radio names the type, timestamp and speaker, so type never relies on the icon alone.
- The waveform is a slider with the clip position as value text (0:03 of 0:07).
- Deal risk is an icon plus the words High, Medium or Low risk. Talk time is an image whose name lists every speaker and share.
- Playback, pauses, load failures and next step changes (with any change in risk) are announced in a polite status region, which also says clips are simulated with no audio.
- The summary is aria-busy while it streams and only exposed once complete; the thinking label is hidden from assistive tech.
- Pointer focus draws no ring; keyboard focus shows Arc's shared focus ring.

### Motion

- Selecting a moment fills the rail up to it on one 240ms ease-out transform and crossfades the quote (old out in 100ms, new in over 160ms from 2px). All quotes share one grid cell, so the well never changes height.
- The waveform reshapes per clip with a 240ms height ease, and the played part is clipped in from a CSS variable each frame, so playback never re-renders React per frame.
- The summary waits 0.7s on a calm shimmer, then streams 3 to 8 words every 35ms with each chunk fading in over 140ms. Talk time reveals left to right once. The risk chip crossfades its icon and label inside the width of its longest label.
- The tour pauses while the card is off screen and stops at the first interaction. Nothing bounces.
- Reduced motion skips the tour, streaming and reveals and drops travel; selection, playback and every state and announcement stay.

### Responsive behavior

- Fluid from 360px to 680px. Container queries move the talk legend to two columns and hide the attendee stack below 560px; below 460px sections pad 16px and the company name, platform name, type legend, speaker title and owner names drop, leaving marks and avatars.
- Markers keep a 40px hit area and clamp inside the rail at both ends. Checkboxes keep their 44px target.

### Performance

- Playback writes one CSS variable per frame and re-renders only when the whole second changes. The tour and playback stop off screen through an IntersectionObserver.
- Waveforms are 52 bars per layer, computed once per moment.

### Notes for AI agents

- Use for a recorded call, demo or interview where the reader needs the gist and the moments that matter: sales call reviews, CRM deal pages, customer research recaps.
- Feed moments from your transcription or conversation intelligence pipeline; keep quotes under about 20 words so the well stays two lines.
- Wire loadClip to seek your audio player to moment.at and resolve when playback can start; abort on the signal.
- Pass risk when your own model scores deals; leave it unset to tie risk to the open next steps.

### Keywords

call insights, sales call, conversation intelligence, gong, talk time, talk ratio, call recording, deal risk, next steps, call summary, objection, competitor mention

### Related

- meeting-summary
- lead-scoring
- account-health

---

## Lead scoring

A lead scoring card where inbound B2B leads are ranked by an AI fit score, each with a score ring and a one-line reason. Open a lead to see its signals and score breakdown, then push it to HubSpot or Salesforce.

- Type: Block (composition)
- Access: Pro
- Built from: Button, SegmentedControl, TextShimmer, Tooltip
- Documentation: https://uiarc.dev/components/blocks/lead-scoring

### Overview

Pass your leads newest first, each with a weighted `breakdown`, so the ring and the bars always agree (or set `score` directly). Mark a lead `scoring` while your model works on it. Wire `onPush(lead, crm, signal)` to your backend: resolve for the done state, reject for the error and retry state. `crms` picks the destinations, and `sort`/`onSortChange` control the order. `onRescore` shows a rescore button. With no props it plays a short intro once it scrolls into view: scores land, the list re-sorts by score, the top lead opens and is pushed to HubSpot. Every push in the demo is simulated.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/lead-scoring. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/lead-scoring while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- A sales inbox or SDR queue that ranks new inbound leads by fit.
- Showing why a model scored a lead, with signals and a weighted breakdown.
- Handing a qualified lead to HubSpot or Salesforce from the same view.

### When not to use

- Large tables of hundreds of leads with filters and bulk edits; use a data table.
- Enriching columns of company data; use enrich-column.
- Tracking the health of existing customers; use account-health.

### Usage

```tsx
import { LeadScoring } from "@/components/arc/blocks/lead-scoring/lead-scoring";

export function InboundLeads({ leads }: { leads: Lead[] }) {
  return (
    <LeadScoring
      leads={leads}
      onPush={async (lead, crm, signal) => {
        const res = await fetch(`/api/crm/${crm}/leads`, { method: "POST", body: JSON.stringify({ id: lead.id }), signal });
        if (!res.ok) throw new Error("Push failed");
      }}
    />
  );
}
```

### API

#### LeadScoring

A card of inbound leads ranked by an AI fit score. Each row shows the company mark, the person, a score ring and the model's one-line reason; opening a row shows signal chips, the weighted score breakdown and a push to HubSpot or Salesforce. With no props it plays a short intro on first view with sample leads and simulated pushes.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `leads` | `Lead[]` | `leadScoringSamples` | Leads to show, newest first. Each lead has id, name, title, company, mark, received, reason, and optional signals, breakdown, score, scoring and pushedTo. |
| `title` | `string` | `"Inbound leads"` | Card title. |
| `description` | `ReactNode` |  | Line under the title. Defaults to the scoring model and the lead count. |
| `sort` | `"score" \| "newest"` |  | Controlled sort. Newest keeps the array order. |
| `defaultSort` | `"score" \| "newest"` | `"newest" while auto playing, else "score"` | Starting sort when uncontrolled. |
| `onSortChange` | `(sort: LeadSort) => void` |  | Called when the sort control changes. |
| `crms` | `LeadCrmId[]` | `["hubspot", "salesforce"]` | CRMs a lead can be pushed to. The first is the default destination; one entry hides the picker. |
| `onPush` | `(lead: Lead, crm: LeadCrmId, signal: AbortSignal) => Promise<void>` |  | Creates the contact and deal. Resolve for the done state, reject for the error state with a retry. The signal aborts on unmount. Without it pushes are simulated and announced as such. |
| `onRescore` | `() => void` |  | Shows a rescore button. Mark leads scoring while you rescore them. The sample demo rescores on its own. |
| `autoPlay` | `boolean` | `true for sample data` | Plays the intro once when the card scrolls into view: scores land, the list sorts by score, the top lead opens and is pushed to the first CRM. |
| `defaultExpandedId` | `string \| null` | `null` | Lead open on first render. |
| `className` | `string` |  | Class on the card. |

#### Lead

One inbound lead.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `id` (required) | `string` |  | Stable id, used as the React key and for push state. |
| `name` (required) | `string` |  | Person's name. |
| `title` (required) | `string` |  | Job title. Hidden in the row on narrow cards. |
| `company` (required) | `string` |  | Company name. |
| `mark` | `LeadCompanyMarkId \| ReactNode` |  | "vercel", "ramp", "linear", "notion", "retool", "figma", or your own 20px logo node. Falls back to a monogram. |
| `received` (required) | `string` |  | Arrival time, already formatted ("6m ago"). |
| `reason` (required) | `string` |  | The model's one-line reason for the score. |
| `signals` | `{ kind: LeadSignalKind; label: string }[]` |  | Chips in the open row. Kinds: pricing, team, hiring, email, demo, stack, docs, repo, security. |
| `breakdown` | `{ id: string; label: string; value: number; weight: number }[]` |  | Score factors, 0 to 100, with weights that add up to 1. The score is their weighted sum unless score is set. |
| `score` | `number` |  | 0 to 100. Overrides the breakdown sum. |
| `scoring` | `boolean` |  | Still being scored: the ring spins and the reason shimmers. |
| `pushedTo` | `LeadCrmId[]` |  | CRMs the lead already lives in. Shows Synced in the row. |

### Dependencies

- `motion`
- `lucide-react`
- `@radix-ui/react-tooltip`

### Keyboard

| Keys | Action |
| --- | --- |
| Tab | Moves through the sort control, rescore, each lead row and the open row's controls. |
| Enter / Space | Opens or closes the focused lead. |
| ArrowDown / ArrowUp | Moves focus between lead rows. |
| Home / End | Jumps to the first or last lead row. |
| ArrowLeft / ArrowRight | Switches the CRM destination inside the open row. |

### Accessibility

- Each row is a button with aria-expanded and aria-controls; its label reads name, title, company, score, fit band and the reason.
- The score ring is decorative; the number and the fit band are in the row label and the breakdown list label.
- Status is never color alone: done and error states pair an icon with a short label.
- The CRM picker is a radio group with roving focus and named options.
- A polite live region announces pushes, errors and rescoring, and says when a push was simulated.

### Motion

- Re-sorting glides each row to its new place with a bounce-free spring (position only, text is never scaled).
- The ring arc and number share one motion value, so they count up together in about 640ms with tabular numerals.
- Opening a row springs the measured height with no bounce; breakdown bars grow with a 30ms stagger.
- Time, synced, reason and status swaps are single crossfades in a fixed slot, so nothing changes size.
- The scoring spinner pauses off screen. Reduced motion keeps every end state and drops travel, counting and the spinner.

### Responsive behavior

- Fits 360px to 640px. Below 460px the job title leaves the row, details start at the card edge and the push button fills the row.
- Names, roles and reasons truncate with an ellipsis; scores and times keep fixed slots.

### Performance

- Designed for a short queue of 5 to 20 leads; every row is rendered.
- Ring counting runs on motion values without React renders.

### Notes for AI agents

- Use for ranking inbound leads, trial signups or accounts by an AI fit score with a reason and a CRM handoff.
- Pass leads newest first; let the score come from a weighted breakdown so the bars and the ring always agree.
- Keep the reason to one short line of evidence (funding stage, team size, intent), not a paragraph.
- Wire onPush to your backend; never call a CRM from the client with secret keys.

### Keywords

lead scoring, ai lead scoring, inbound leads, sales qualification, fit score, crm, hubspot, salesforce, sdr queue, b2b sales

### Related

- account-health
- enrich-column
- call-insights
- agent-approvals
- connector-setup

---

## Domain verify

A custom domain setup card where customers add a domain and copy the DNS records. A live checker then polls resolvers, marks each record valid, not found or misconfigured with a one-line fix, and finishes with the domain verified and the SSL certificate issued.

- Type: Block (composition)
- Access: Pro
- Built from: Button, CopyButton, TextShimmer
- Documentation: https://uiarc.dev/components/blocks/domain-verify

### Overview

Drop it into a project's domain settings and connect three async handlers to your backend. getRecords(domain, signal) returns the records the customer must create. verify(domain, records, { signal, attempt, run }) runs one check and returns per-record status plus how many regions have propagated. issueCertificate(domain, signal) returns { issuer, renews }. The card does the polling (pollInterval), aborts requests when the domain is removed or the component unmounts, and stops on "all valid" or on any "invalid" record. On an invalid record it shows `found` and `fix` under that row. Pass `provider` (name + mark) from your NS lookup, or null when you don't know it. Listen with onVerified, onRemove and onPhaseChange. With no props it plays a simulated flow until someone clicks or types inside it.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/domain-verify. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/domain-verify while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- Letting customers serve an app, docs site, status page or storefront from their own domain.
- Verifying a sending domain for email (SPF, DKIM, DMARC) before turning on delivery.
- Any setup step where a person must copy values into a third party and wait for propagation.

### When not to use

- Buying or searching domains: use a search field with results instead.
- Managing many domains at once: use a table with one row per domain and open this card per domain.
- One-off copy of a single value: a copy-button next to the value is enough.

### Usage

```tsx
import { DomainVerify } from "@/components/arc/blocks/domain-verify/domain-verify";

export function DomainSettings({ projectId }: { projectId: string }) {
  return <DomainVerify
    defaultDomain=""
    provider={null}
    getRecords={(domain, signal) => fetch(`/api/projects/${projectId}/domains`, { method: "POST", body: JSON.stringify({ domain }), signal }).then(r => r.json())}
    verify={(domain, _records, { signal }) => fetch(`/api/projects/${projectId}/domains/${domain}/verify`, { signal }).then(r => r.json())}
    issueCertificate={(domain, signal) => fetch(`/api/projects/${projectId}/domains/${domain}/certificate`, { method: "POST", signal }).then(r => r.json())}
    onVerified={domain => console.log(`${domain} is live`)}
  />;
}
```

### API

#### DomainVerify

Custom domain setup in one card. The customer enters a domain, copies the DNS records (type, name, value with copy buttons), and a live checker polls resolvers: each record shows not checked, checking, valid, not found or misconfigured with a one line fix, the footer reports propagation across regions, and the card finishes with the domain verified and the SSL certificate issued. With no props it plays a simulated flow, a Cloudflare proxied CNAME that gets fixed, and no DNS is queried.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `defaultDomain` | `string` | `"app.acme.com"` | Prefilled domain. Pasted protocols, paths, ports and trailing dots are stripped before validation. |
| `title` | `string` | `"Custom domain"` | Card title. |
| `description` | `string` | `"Serve your workspace from a domain you own."` | One muted line under the title. |
| `provider` | `{ name: string; mark?: ReactNode } \| null` | `Cloudflare` | Detected DNS host, shown as "DNS hosted at {name}" with a 14px mark. Pass null to hide it. |
| `getRecords` | `(domain: string, signal: AbortSignal) => Promise<DnsRecord[]>` |  | Returns the records to create. Each record is { id, type, name, value, purpose? }. Defaults to a CNAME (an A record on an apex), an ownership TXT and a CAA for Let's Encrypt. |
| `verify` | `(domain: string, records: DnsRecord[], context: { signal: AbortSignal; attempt: number; run: number }) => Promise<VerifyResult>` |  | One DNS check. Return { records: RecordCheck[], regions: { propagated, total } }. A RecordCheck is { id, status: "valid" \| "missing" \| "invalid", detail?, found?, fix? }. The card polls while any record is missing, and stops on all valid or any invalid, showing `found` and `fix` under that row. |
| `issueCertificate` | `(domain: string, signal: AbortSignal) => Promise<{ issuer: string; renews: string }>` |  | Called once every record is valid. The domain row shows "Issuing SSL certificate" until it resolves. |
| `pollInterval` | `number` | `800 simulated, 5000 with verify` | Milliseconds between checks. |
| `autoPlay` | `boolean` | `true when no handlers are passed` | Plays add, verify, fix and verified by itself, pausing off screen. Any pointer or key press inside the card hands control to the person. |
| `onPhaseChange` | `(phase: "enter" \| "adding" \| "records" \| "checking" \| "invalid" \| "verified") => void` |  | Called on every phase change. |
| `onVerified` | `(domain: string, certificate: Certificate) => void` |  | Called after the certificate is issued. |
| `onRemove` | `(domain: string) => void` |  | Called when the domain is removed with the close button or when Add another starts over. |
| `className` | `string` |  | Extra class on the card. |

### Dependencies

- `motion`
- `lucide-react`

### Keyboard

| Keys | Action |
| --- | --- |
| Enter | In the domain field, adds the domain (same as the Add domain button). |
| Tab | Moves through the remove button, each record's copy button and the footer action. |
| Space / Enter | Activates the focused copy, remove or footer button. |

### Accessibility

- The card is a labelled section; the records are a list labelled DNS records.
- A polite live region announces each step (added, checking, needs a fix, verified, certificate issued) and adds "Simulated, no DNS was queried" when no verify handler is passed.
- Status is never color alone: every record and the domain show an icon with a short label.
- The domain field is labelled, marks itself aria-invalid on a bad domain and is described by the footer status.
- Placeholder rows behind the empty state are inert, so their copy buttons are skipped by keyboard and screen readers.
- Each copy button has its own label, such as "Copy TXT value", and announces the copy.

### Motion

- Text and icon swaps are single crossfades: the old one fades out in 100ms, the new one fades in over 160ms with a 2px rise.
- Rows fade in over 160ms with a 40ms stagger when the records arrive. No row, column or slot changes size between states.
- When a fix hint wraps on a narrow card, the card eases to its measured height on a spring with no bounce.
- Checking rows show a steady spinner, and the footer label carries a calm shimmer while checks run.
- Reduced motion keeps every state and label, swaps instantly and stops the spinner. The demo loop pauses off screen.

### Responsive behavior

- Fills its container up to 680px and adapts with a container query, not the viewport.
- Below about 544px the header row hides and each record stacks: type, name and status on one line, the value with its copy button below, then the meta line.
- On narrow cards the domain meta shortens ("DNS at Cloudflare", "SSL by Let's Encrypt") so the status never collides.
- Long names and values truncate with an ellipsis and keep the full text in a title; copy always copies the full value.

### Performance

- Plain DOM and CSS; motion is limited to opacity and a measured height spring.
- Every poll is abortable: removing the domain, starting a new check or unmounting aborts the in-flight request and timer.
- The demo pauses its timers when the card is off screen.

### Notes for AI agents

- Use for custom domain, sending domain or verified domain setup in a SaaS settings page. Wire getRecords, verify and issueCertificate to your backend; keep verify a single check, the card handles polling and aborts.
- Return `missing` while a record is still propagating and `invalid` only when a conflicting value is found, with `found` and a one sentence `fix`.
- Pass `provider` from your DNS lookup (NS records) so the hint can name the provider; pass null when unknown.
- For email sending domains, return MX, SPF (TXT) and DKIM (CNAME or TXT) records from getRecords and set a title like "Sending domain".

### Keywords

custom domain, domain verification, dns records, cname, txt record, caa, ssl certificate, propagation, verify domain, sending domain, dkim, vercel domains, resend domains

### Related

- copy-button
- button
- text-shimmer
- agent-status
- tool-call

---

## Two-factor setup

A two-factor setup card where you scan a real, working authenticator QR code, type the 6-digit code into slots that move to the next box on their own, and save your backup codes before it turns on. Every step shares one fixed-size card, so it moves between steps with a short slide and never changes size.

- Type: Block (composition)
- Access: Pro
- Built from: Button, Checkbox, Copy button
- Documentation: https://uiarc.dev/components/blocks/two-factor-setup

### Overview

Use this as the authenticator app step in account or workspace security settings. Pass `secret` and `backupCodes` from your server, along with `issuer` and `account`. Wire `verifyCode(code, signal)` to your TOTP check: return true to continue or false to show the mismatch error. Turn two-factor on in `onEnable(signal)`; if it rejects, an inline error shows. Use `onDone` to go back to settings, `onCancel` to show a Cancel button, and `onStepChange` for analytics. Once you pass `verifyCode`, the simulated authenticator row and the local check go away.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/two-factor-setup. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/two-factor-setup while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- Turning on authenticator app two-factor from account or workspace security settings.
- Enforced two-factor onboarding for admins after sign-in.
- Re-enrolling a new phone, with fresh backup codes.

### When not to use

- SMS or email one-time codes only: use otp-input in a sign-in form.
- Passkeys or WebAuthn enrolment, which needs no QR or code step.
- A full security settings page with sessions and password: use security-settings.

### Usage

```tsx
import { TwoFactorSetup } from "@/components/arc/blocks/two-factor-setup/two-factor-setup";

export function SecurityTwoFactor({ setup }: { setup: { secret: string; codes: string[] } }) {
  return (
    <TwoFactorSetup
      issuer="Acme"
      account="dana@acme.com"
      secret={setup.secret}
      backupCodes={setup.codes}
      verifyCode={async (code, signal) => {
        const res = await fetch("/api/2fa/verify", { method: "POST", body: JSON.stringify({ code }), signal });
        return res.ok;
      }}
      onEnable={signal => fetch("/api/2fa/enable", { method: "POST", signal }).then(() => undefined)}
      onDone={() => router.push("/settings/security")}
    />
  );
}
```

### API

#### TwoFactorSetup

A three step authenticator app setup card: scan a real TOTP QR code (or copy the setup key), confirm a six digit code, save backup codes, then a final enabled state. With no props it is a working demo that checks real codes for its sample secret.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `issuer` | `string` | `"Northwind"` | Product name written into the otpauth URI and shown in the authenticator entry. |
| `account` | `string` | `"maya@northwind.io"` | Account label written into the otpauth URI, usually the email. |
| `secret` | `string` | `"QK7MR2XD5LVNA3WE"` | Base32 TOTP secret from your server. The QR code and grouped setup key are built from it. |
| `backupCodes` | `string[]` | `8 sample codes` | One-time recovery codes from your server, shown in a grid and used for Download and Copy. |
| `verifyCode` | `(code: string, signal: AbortSignal) => Promise<boolean>` |  | Checks the six digit code on your server. Resolve true to continue, false to show the mismatch error, reject to show a retry error. Without it the card verifies real TOTP codes for `secret` locally and shows a simulated authenticator entry you can click to fill the code. |
| `onEnable` | `(signal: AbortSignal) => Promise<void> \| void` |  | Called from Turn on after the person confirms they saved the codes. Persist two-factor here; reject to show an inline error. |
| `onCancel` | `() => void` |  | Shows a Cancel button on the first step. |
| `onDone` | `() => void` |  | Called from Done on the enabled state. Without it, Done restarts the demo. |
| `onStepChange` | `(step: "scan" \| "verify" \| "backup" \| "enabled") => void` |  | Fires whenever the step changes, for analytics or routing. |
| `addedLabel` | `string` | `"Added Oct 27, 2026"` | Date label for the authenticator row on the enabled state. |
| `className` | `string` |  | Class for the card root. |

### Dependencies

- `motion`
- `lucide-react`
- `@radix-ui/react-checkbox`

### Keyboard

| Keys | Action |
| --- | --- |
| 0-9 | Types a digit and moves to the next slot. The sixth digit submits. |
| Backspace | Clears the slot, or the previous slot when this one is empty, and moves back. |
| Left / Right, Home / End | Moves between code slots. |
| Cmd/Ctrl + V | Pastes a full code into all six slots from any slot and submits. |
| Enter | Submits a complete code. |
| Tab | Moves through the setup key copy button, slots, checkbox, Download, Copy, Back and the primary action. |

### Accessibility

- The card is a labelled section; each step has its own heading, and inactive steps are inert and hidden from assistive tech.
- The QR code is an SVG with role img and a label naming the issuer and account; the setup key is selectable text with a copy button for people who cannot scan.
- Code slots are a labelled group with per-digit labels, autocomplete one-time-code on the first slot, and aria-invalid plus a role alert message on a mismatch.
- Errors use an icon and text, never color alone. A polite live region announces verification, downloads and whether anything was simulated.
- Moving to the verify step places focus in the first empty slot; the primary button keeps focus across steps.

### Motion

- All steps share one grid cell, so the card never changes size. The outgoing step fades in 100ms; the incoming one fades and slides 12px on a no-bounce spring (0.24s) in the direction of travel.
- Digits fade in with a 2px rise; the error state changes slot borders and swaps the hint for the message in one crossfade, with no shake.
- The countdown ring drains in sync with the real 30 second TOTP window using a negative animation delay and only ticks while the verify step is visible on screen.
- Progress segments fill on a 240ms ease-out; the done check draws itself once.
- Reduced motion keeps the crossfades and end states, drops the slide, the caret blink and the ring animation.

### Responsive behavior

- Fluid up to 34rem. Below a 460px card width the QR shrinks to 112px beside the copy, apps and setup key go full width, and backup codes move to two columns.
- Code slots shrink evenly down to a 360px viewport; the 44px checkbox hit area is offset so its square aligns with the text above.
- Container queries, so it adapts inside dialogs and side panels as well as pages.

### Performance

- The QR is encoded once per otpauth value and drawn as a single merged path plus three eyes.
- TOTP uses Web Crypto HMAC-SHA1; the clock ticks once per second only on the verify step and pauses off screen.

### Notes for AI agents

- Use for enabling authenticator app (TOTP) two-factor in account security settings. Pass the server-generated secret and backup codes; never generate secrets in the browser for production.
- Always pass verifyCode in production so the demo's simulated authenticator entry and local check are removed.
- Place it in a settings page or a dialog around 480 to 560px wide; it stacks the QR beside a narrower column below 460px.
- For pairing a device by scanning instead of typing a code, use qr-pairing; for a whole security page with password and sessions, use security-settings.

### Keywords

two-factor authentication, 2fa setup, totp, authenticator app, qr code, google authenticator, 1password, backup codes, recovery codes, mfa enrolment, otp input, account security

### Related

- security-settings
- otp-input
- copy-button
- checkbox

---

## Onboarding survey

A post-signup onboarding survey where each question gets its own step of large option cards, picked with keys 1 to 4 and Enter. A short personalization checklist then ticks off and lands on an editable "You're all set" summary.

- Type: Block (composition)
- Access: Pro
- Built from: Button, Kbd, TextShimmer
- Documentation: https://uiarc.dev/components/blocks/onboarding-survey

### Overview

Drop it in right after sign-up and pass your own `questions` (two to four options each, with 16px icons or mono brand marks). Store picks from `onAnswer` as they happen. Put your real setup work in `personalize(answers, signal)`: the last checklist item waits for it, and if it rejects, the card shows the error with Try again. Route on with `onComplete(answers)`. `setupSteps` sets the checklist labels to match the answers. With no props it plays a sample run that stops on the first click or key press.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/onboarding-survey. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/onboarding-survey while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- Post-signup personalization: role, team size and first action before the first screen.
- Short in-product surveys where every answer changes what someone sees next.
- Re-onboarding when a workspace changes plan or adds a team.

### When not to use

- Long forms with free text or many fields; use a regular form or import-wizard.
- Guided tours over the real interface; use onboarding-tour.
- A single choice inside a settings page; use radio-cards.

### Usage

```tsx
import { OnboardingSurvey } from "@/components/arc/blocks/onboarding-survey/onboarding-survey";

export function Welcome() {
  return (
    <OnboardingSurvey
      questions={questions}
      onAnswer={(id, value) => analytics.track("onboarding_answer", { id, value })}
      personalize={async (answers, signal) => {
        await fetch("/api/workspace/personalize", { method: "POST", body: JSON.stringify(answers), signal });
      }}
      onComplete={() => router.push("/inbox")}
    />
  );
}
```

### API

#### OnboardingSurvey

A post-signup survey card: one question per step on large option cards, a slim progress bar, keys 1 to 9 and Enter, then a personalization checklist that lands on an editable summary. With no props it plays a sample run until someone interacts.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `questions` | `OnboardingSurveyQuestion[]` | `onboardingSurveySampleQuestions` | One question per step: { id, title, description?, label?, options: { value, label, description?, icon? }[] }. Two to four options read best; label names the summary row. |
| `defaultAnswers` | `Record<string, string>` |  | Answers to start from, keyed by question id. Start over resets to these. |
| `setupSteps` | `string[] \| (answers) => string[]` |  | Checklist labels for the personalization step. Defaults to steps derived from the sample answers, or three generic steps for custom questions. |
| `personalize` | `(answers, signal: AbortSignal) => Promise<void>` |  | Your real setup work, started when the last question is answered. The last checklist item waits for it; a rejection shows its message with Try again. The signal aborts when the person goes back or the card unmounts. |
| `onAnswer` | `(questionId, value: string \| undefined, answers) => void` |  | Fires on every pick. value is undefined when a question is skipped. |
| `onComplete` | `(answers) => void \| Promise<void>` |  | Runs when the finish button is pressed; the button shows a spinner while a returned promise is pending. Without it the finish is simulated. |
| `autoPlay` | `boolean` | `true for the sample questions` | Plays a sample run (number key, then Enter) and loops. Stops for good on the first pointer or key press, pauses off screen and never runs with reduced motion. |
| `doneTitle` | `string` | `"You're all set"` | Title of the final step. |
| `doneDescription` | `string` | `"Your workspace is ready. Change any answer below."` | Line under the final title. |
| `finishLabel` | `string` | `"Open workspace"` | Label of the finish button. |
| `aria-label` | `string` | `"Onboarding survey"` | Accessible name of the card. |
| `className` | `string` |  | Extra class on the card. |

### Dependencies

- `motion`
- `lucide-react`

### Keyboard

| Keys | Action |
| --- | --- |
| 1 to 9 | Pick the matching option on the current question. |
| Enter | Continue once an option is picked. |
| Arrow keys | Move between options in the radio group and pick as you go. |
| Tab | Move through the selected option, Skip, Back and the main action. |
| Space | Pick the focused option or press the focused button. |

### Accessibility

- Each question is a radiogroup labelled by its title; options are radios with aria-checked and aria-keyshortcuts, and one roving tab stop.
- The progress bar is a progressbar with a percentage value.
- A polite live region announces picks, the next question, setup progress and the result, including "Simulated, nothing was saved" in the demo.
- When a step changes, focus moves to the new step's selected or first option so keyboard flow never drops to the page.
- Checklist rows pair every state with an icon and text: a spinner, a check with a hidden Done label, or an alert with Failed.
- Hidden controls (Back on the first question, Skip after the last) keep their space but leave the tab order and accessibility tree.

### Motion

- Steps crossfade: the old step fades out in 100ms while the new one fades in over 160ms with a 2px rise.
- The stage springs to the incoming step's measured height with no bounce, so the footer glides instead of jumping.
- The progress fill scales from the left with a bounce-free spring; option checks and checklist icons swap with a short scale and fade.
- Number keys and Enter press their key caps and the main button for 150ms, so pointer and keyboard both get instant feedback.
- Reduced motion keeps the crossfades and end states, drops the rise, the height spring and the sample loop.

### Responsive behavior

- Up to 560px wide. Above 440px the options sit in a 2 by 2 grid of cards; below, each option becomes one compact row with icon, label, description and key.
- Labels and descriptions truncate with an ellipsis instead of wrapping, so every option keeps one height.
- Holds at 360px with 16px padding and no horizontal scroll; touch targets stay at least 40px tall.

### Performance

- One component with local state; only the current step is mounted, plus the outgoing one during its 100ms fade.
- The sample run uses a single timeout at a time and pauses when the card leaves the viewport.
- Brand marks are inline SVG; no images or network requests.

### Notes for AI agents

- Use right after sign-up to collect two to four answers that change the first screen. Keep each question to four options so keys 1 to 4 and the 2 by 2 grid hold.
- Pass personalize for the real work (create views, seed templates, invite flow) and keep setupSteps labels specific to the answers.
- Store answers from onAnswer as they come so a skipped or abandoned survey still informs the workspace.
- Option icons are 16px; lucide icons at strokeWidth 1.75 and mono brand marks in currentColor match the sample.

### Keywords

onboarding survey, welcome survey, post signup, personalization, onboarding questions, role picker, team size, option cards, multi step form, typeform style, workspace setup, keyboard shortcuts

### Related

- ai-setup-wizard
- invite-people
- signup-form
- radio-cards
- stepper

---

## Webhook tester

A developer webhook tester where you pick an event, edit its JSON payload and send a signed test event. You watch it go from signed to sent to 200 OK in 184 ms, then read the response body, headers and exact request, and retry failed deliveries from a recent list.

- Type: Block (composition)
- Access: Pro
- Built from: Button, CopyButton, Kbd, TextShimmer
- Documentation: https://uiarc.dev/components/blocks/webhook-tester

### Overview

Put it on the Test endpoint screen of any product that sends webhooks. Pass your own `events` (type plus default payload), the endpoint's `secret` and an `onSend(request, signal)` that hands the signed request to your backend. Your backend does the real POST and resolves with `{ status, durationMs, headers, body }`, or with status 0 and an `error` when nothing came back. `onRetry` re-sends a failed delivery and falls back to onSend. `source` and `signatureHeader` replace the Stripe defaults with your own product's name, mark and header. With no props it simulates the endpoint and sends one sample event when it scrolls into view.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/webhook-tester. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/webhook-tester while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- A developer settings page where customers test a webhook endpoint before going live.
- Integration onboarding that asks people to prove their handler returns 2xx and verifies signatures.
- Internal tools for replaying failed deliveries with a retry.

### When not to use

- Managing many endpoints, filters and event subscriptions: use the webhooks block and link here for testing one.
- A general HTTP client for arbitrary methods and headers: this always sends a signed POST with a JSON body.
- Live event logs with thousands of rows: the list is for a few recent attempts, not a paginated log.

### Usage

```tsx
import { WebhookTester } from "@/components/arc/blocks/webhook-tester/webhook-tester";

export function EndpointTest({ endpointId }: { endpointId: string }) {
  return (
    <WebhookTester
      defaultEndpoint="https://api.acme.com/webhooks/billing"
      secret={signingSecret}
      onSend={async (request, signal) => {
        const res = await fetch(`/api/endpoints/${endpointId}/test`, { method: "POST", body: JSON.stringify(request), signal });
        return res.json(); // { status, durationMs, headers, body }
      }}
    />
  );
}
```

### API

#### WebhookTester

A developer webhook tester in one card. The request side has the endpoint URL, an event type select, the signing secret with reveal and copy, and a JSON payload editor with syntax tint, line numbers, validation and Format. Send test event signs the body with real HMAC SHA-256, runs a request timeline (signed, sent, 200 OK in 184 ms) and shows the response body, response headers and the exact request in tabs. Recent deliveries list every attempt with a status chip; failed ones have Retry. With no props it simulates the endpoint and sends one sample event when it scrolls into view.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `defaultEndpoint` | `string` | `"https://api.northwind.dev/webhooks/stripe"` | Endpoint the test events go to. https is required, except http on localhost. |
| `onEndpointChange` | `(url: string) => void` |  | Called as the endpoint field is edited. |
| `events` | `{ type: string; payload: unknown }[]` | `five Stripe events (invoice.paid, customer.created, customer.subscription.updated, checkout.session.completed, payment_intent.payment_failed)` | Event types in the select. Choosing one loads its payload (an object, pretty printed, or a JSON string kept as is) into the editor. |
| `defaultEvent` | `string` | `the first event` | Event selected on first render. |
| `secret` | `string` | `a sample whsec_ secret` | The endpoint's signing secret. Shown masked with the prefix visible; the body is signed in the browser as HMAC SHA-256 of `${timestamp}.${body}`. |
| `defaultDeliveries` | `WebhookDelivery[]` | `five sample deliveries, two failed` | Deliveries shown on first render, newest first. Each has id, event, time, request ({ url, event, body, headers, timestamp, signature }) and response. The first one is selected. |
| `onSend` | `(request: WebhookTestRequest, signal: AbortSignal) => Promise<WebhookTestResponse>` |  | Sends the signed test event, usually through your backend. Resolve with { status, durationMs, headers?, body? }, or status 0 with error (and timedOut) when nothing came back; a rejection is shown as a failed delivery. Without it every delivery is simulated and the status line says so. |
| `onRetry` | `(delivery: WebhookDelivery, signal: AbortSignal) => Promise<WebhookTestResponse>` |  | Re-sends a failed delivery with a fresh timestamp and signature. Defaults to onSend with the same body. |
| `source` | `{ name: string; mark: ReactNode }` | `{ name: "Stripe", mark: <StripeMark /> }` | Who sends the events, shown in the header as a 16px mark and "Signed test events from Stripe". |
| `signatureHeader` | `string` | `"stripe-signature"` | Name of the header that carries t=…,v1=… in the request. |
| `autoPlay` | `boolean` | `true without onSend` | Sends one event about a second after the card first scrolls half into view, unless someone has already interacted with it. |
| `className` | `string` |  | Class on the card. |

### Dependencies

- `motion`
- `lucide-react`

### Keyboard

| Keys | Action |
| --- | --- |
| Mod+Enter | Sends the test event from the payload editor or anywhere in the endpoint field (Enter also works in the endpoint field). |
| Enter | In the payload editor, starts a new line that keeps the current indentation, and indents after { or [. |
| ArrowLeft / ArrowRight, Home / End | Move between the Body, Headers and Request tabs. |
| Tab | Moves through endpoint, event, reveal, copy, payload, Format, Send, tabs, copy, the response panel and each delivery with its Retry. |

### Accessibility

- Every field has a visible label; the payload textarea is labelled with the event type and reports aria-invalid when the JSON does not parse, with the line named in the footer.
- The signing secret is hidden from assistive technology until revealed; the reveal button is a toggle with aria-pressed and a label that says what it will do.
- Response tabs follow the tabs pattern with roving tabindex; the panel is focusable so long bodies can be scrolled from the keyboard.
- Delivery rows are buttons labelled with event, status and time, and mark the selected one with aria-current. Status chips pair an icon and a code or word, never color alone.
- A polite live region announces each send and its outcome, and adds "Simulated, nothing was sent" when no onSend is wired.

### Motion

- The timeline runs signed, sent, response: icons crossfade, the connector fills left to right and a small dot travels along it while the request is in flight, looping on the last leg until the response arrives.
- Text swaps (node labels, status chips, hints, the reveal icon) are a single crossfade: 100ms out, 160ms in with a 2px rise, in fixed slots so nothing shifts.
- A new delivery fades in at the top while the rows below glide down with a bounce free spring; the response panel crossfades between tabs and deliveries.
- Reduced motion keeps every end state and status change, drops the traveling dot, the fills and the glides, and slows the spinner.

### Responsive behavior

- Two columns from 680px of container width, stacked below; the payload editor stretches to match the response column when side by side.
- At 360px the delivery time hides and long event names truncate with an ellipsis; nothing scrolls horizontally except a long payload line inside the editor.
- Every target is at least 28px tall, and rows are 40px.

### Performance

- Highlighting is a single regex pass over the payload on each keystroke; fine for typical webhook bodies (under a few hundred lines).
- Signing uses WebCrypto (crypto.subtle) and falls back to a placeholder where it is unavailable, such as a non secure context.
- The traveling dot is a transform only animation and stops when no request is in flight; the autoplay observer disconnects after its single run.

### Notes for AI agents

- Use for the Test endpoint screen of a product that sends webhooks (billing, auth, email, CI): pass your own events and payloads, the endpoint's secret and an onSend that calls your backend, which performs the real POST and returns status, timing, headers and body.
- Never send the request from the browser to a customer endpoint; the request object is meant for your server, which can verify it re-signs identically.
- For a non Stripe product pass source (your product name and mark) and signatureHeader, such as "webhook-signature".
- Card is 760px max and splits into request and response columns from 680px; below that it stacks.

### Keywords

webhook tester, test webhook, send test event, webhook endpoint, signing secret, hmac signature, stripe webhook, json editor, request timeline, delivery log, retry webhook, developer settings, api, event payload

### Related

- webhooks
- api-keys
- tool-call
- copy-button
- text-shimmer

---

## Seat manager

A team seats and billing card where avatars and a seat meter show members, invites and open seats against what you pay for, a stepper rolls the prorated charge for today and the new monthly total live, and changes go through a confirm step before anyone is charged. Pending invites can be resent or revoked with undo, and when every seat is taken the card says so and offers to add one.

- Type: Block (composition)
- Access: Pro
- Built from: Button, Avatar, TextShimmer
- Documentation: https://uiarc.dev/components/blocks/seat-manager

### Overview

Put it in the seats or members section of a team billing page. Pass `purchased` (the subscription quantity), `members`, `invites`, `plan` ({ name, pricePerSeat, interval, currency, maxSeats }) and the real billing `period` so the proration matches your billing system. Then wire `updateSeats(quote, signal)`, `resendInvite` and `revokeInvite` to your backend. Revoke runs after the undo window closes. If `updateSeats` rejects with an Error, its message appears in the footer with a Try again button. `buildQuote` is exported so your server can check the same numbers, and `onQuoteChange` lets you swap in your billing system's own invoice preview if you need it.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/seat-manager. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/seat-manager while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- Letting a team admin add or remove paid seats with the price impact visible before paying.
- Showing seat usage against purchased seats, including invites that reserve a seat.
- Handling the seat limit at the moment an admin hits it, with a one tap way to add a seat.

### When not to use

- Managing roles and permissions for many members: use a member table and link to this card for seats.
- Usage based or credit billing: use credit-topup or a usage meter instead.
- Plan comparison or upgrades between tiers: use a pricing table.

### Usage

```tsx
import { SeatManager } from "@/components/arc/blocks/seat-manager/seat-manager";

export function TeamBilling({ team }: { team: Team }) {
  return <SeatManager
    workspace={team.name}
    plan={{ name: "Pro", pricePerSeat: 16, interval: "month", maxSeats: 25 }}
    purchased={team.seats}
    members={team.members.map(m => ({ id: m.id, name: m.name, avatar: m.imageUrl }))}
    invites={team.invites.map(i => ({ id: i.id, email: i.email, invitedBy: i.inviter, note: i.sentAgo }))}
    period={{ start: team.periodStart, end: team.periodEnd }}
    paymentMethod={{ brand: "Visa", last4: team.cardLast4 }}
    updateSeats={(quote, signal) => fetch("/api/billing/seats", { method: "POST", body: JSON.stringify({ seats: quote.target }), signal }).then(r => { if (!r.ok) throw new Error("Your card was declined. Nothing was charged."); })}
    resendInvite={(invite, signal) => fetch(`/api/invites/${invite.id}/resend`, { method: "POST", signal }).then(() => undefined)}
    revokeInvite={(invite, signal) => fetch(`/api/invites/${invite.id}`, { method: "DELETE", signal }).then(() => undefined)}
  />;
}
```

### API

#### SeatManager

Team seats and billing in one card. Avatars and a seat meter show members, pending invites and open seats against what is purchased; a stepper changes the seat count while the prorated charge for today and the new recurring total roll live; pending invites can be resent or revoked with undo; and Update seats asks for a confirm step before paying. When every seat is taken it says so and offers one tap to add a seat. With no props it plays a simulated loop on a Pro workspace, and nothing is charged or sent.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `workspace` | `string` | `"Halcyon"` | Workspace name shown under the title. |
| `plan` | `{ name: string; pricePerSeat: number; interval?: "month" \| "year"; currency?: string; maxSeats?: number }` | `Pro, $16 per seat per month, up to 25 seats` | Plan badge, seat price in major units, billing interval, ISO currency and the seat cap. The plus button stops at maxSeats and explains why. |
| `purchased` | `number` | `12` | Seats paid for right now. Becomes the new count after a successful update. |
| `members` | `{ id: string; name: string; avatar?: string }[]` | `10 sample members` | Members holding a seat. The first four show as avatars, the rest as a +N count. |
| `memberCount` | `number` | `members.length` | Total members when `members` is only a sample for the avatars. |
| `invites` | `{ id: string; email: string; invitedBy?: string; note?: string }[]` | `2 sample invites` | Pending invites. Each reserves a seat until accepted or revoked. `note` is a short muted suffix such as "2 days ago". |
| `period` | `{ start: Date \| string; end: Date \| string }` | `Oct 18 to Nov 18 2026` | Current billing period. Added seats are prorated by the days left; the new total starts at `end`. |
| `now` | `Date` | `new Date() (Oct 27 2026 in the demo)` | "Today" for proration. |
| `paymentMethod` | `{ brand: string; last4: string } \| null` | `Visa ending 4242` | Named in the footer and the confirm step. Pass null to hide it. |
| `receiptEmail` | `string` | `"billing@halcyon.so"` | Named in the done message. |
| `updateSeats` | `(quote: SeatQuote, signal: AbortSignal) => Promise<void>` |  | Applies the change. SeatQuote is { current, target, delta, dueToday, nextTotal, daysLeft, periodDays, renewsOn }. Reject with an Error and its message shows in the footer with Try again. |
| `resendInvite` | `(invite: SeatInvite, signal: AbortSignal) => Promise<void>` |  | Sends the invite email again. The button shows a spinner, then Sent. |
| `revokeInvite` | `(invite: SeatInvite, signal: AbortSignal) => Promise<void>` |  | Called when the undo window closes. Reject to put the invite back. |
| `undoSeconds` | `number` | `3` | How long Undo stays on a revoked invite. |
| `onQuoteChange` | `(quote: SeatQuote) => void` |  | Called whenever the stepper changes the quote. |
| `onSeatsChange` | `(seats: number, quote: SeatQuote) => void` |  | Called after a change is applied. |
| `onPhaseChange` | `(phase: "idle" \| "confirm" \| "saving" \| "done" \| "error") => void` |  | Called on every footer phase change. |
| `autoPlay` | `boolean` | `true when no handlers are passed` | Plays add three seats, pay, resend and revoke on a loop, pausing off screen. Any pointer or key press inside the card hands control to the person. |
| `className` | `string` |  | Extra class on the card. |

#### buildQuote

The proration math the card uses, exported so a server can check the same numbers: buildQuote(current, target, plan, period, now) returns a SeatQuote. Added seats cost delta x price x daysLeft / periodDays, rounded to cents; removals cost nothing today and apply at renewal.

No props.

### Dependencies

- `motion`
- `lucide-react`

### Keyboard

| Keys | Action |
| --- | --- |
| Tab | Moves through the stepper buttons, the seat count, invite actions and the footer buttons. |
| Arrow up / Arrow down | On the seat count (a spinbutton), adds or removes one seat. Arrow right and left do the same. |
| Page up / Page down | On the seat count, changes by five seats within the limits. |
| Home / End | On the seat count, jumps to the fewest seats allowed (members plus invites) or the plan maximum. |
| Space / Enter | Activates the focused button. Focus moves to Pay when the confirm step opens and back to Update seats after Back or a successful update. |

### Accessibility

- The card is a labelled section. The seat count is a spinbutton with min, max, value and a spoken value such as "15 seats".
- The seat meter is a single image with a full text label (used, members, invited, open, being added); the legend repeats the counts in text, so color is never the only signal.
- Limits stay explained, not silent: pressing past the minimum or the plan cap keeps the button focusable (aria-disabled) and shows why in the notice line.
- A polite live region announces review, update, resend, revoke and undo, and adds "Simulated, nothing was charged" (or sent) when no handlers are passed.
- Rolling numbers render the real value for screen readers and hide the digit strips.
- Every invite action has its own label, such as "Revoke invite to kai.tanaka@halcyon.so".

### Motion

- Numbers roll: each digit is a 0 to 9 strip that slides 240ms on an ease-out, with tabular numerals in a right-aligned slot so nothing shifts.
- Seat cells grow in from zero width and shrink out on a 240ms spring with no bounce; neighbours glide to make room.
- Text, icon and button swaps are single crossfades: old out in 100ms, new in over 160ms with a 2px rise.
- A revoked invite crossfades to an undo row, then collapses its measured height on a bounce-free spring.
- Press and hold on plus or minus repeats after 380ms, then every 70ms.
- Reduced motion keeps every state and number, swaps instantly and drops the rolls and cell growth. The demo loop pauses off screen.

### Responsive behavior

- Fills its container up to 560px and adapts with a container query, not the viewport.
- Below about 460px the padding tightens, the quote rows drop their muted notes and the legend hides the new seats item, which the notice line already states.
- Emails, notes and footer text truncate with an ellipsis; amounts and counts never wrap.
- Past 40 seats the meter groups cells into one segment per kind so it stays readable.

### Performance

- Plain DOM and CSS; digit rolls are CSS transforms and cell growth is a flex-grow spring.
- Every request is abortable and aborted on unmount; timers are cleared on unmount.
- The demo loop pauses when the card is off screen.

### Notes for AI agents

- Use for the seats or members section of a team billing page in any per-seat SaaS. Pass the subscription quantity as purchased and the real billing period so proration matches your processor.
- Proration here is a simple daily estimate. If your processor computes it (Stripe upcoming invoice preview), call it in onQuoteChange and pass the result to your confirm copy, or replace the numbers server side before charging.
- Pending invites hold seats, so the minimum is members plus invites. Revoking frees a seat at once with undo; the revoke handler runs after the undo window.
- Reject updateSeats with a human sentence ("Your card was declined. Nothing was charged."); it is shown verbatim with Try again.

### Keywords

seat management, team seats, per seat billing, seat stepper, proration, prorated charge, pending invites, resend invite, revoke invite, seat limit, team billing, subscription quantity, stripe seats

### Related

- billing-overview
- credit-topup
- button
- avatar
- text-shimmer
- checkout-summary

---

## Account health

A customer success card where a health score gauge, a renewal countdown and five sourced signals with sparklines lead into an AI risk summary and one recommended next step, like scheduling a QBR before usage slips further.

- Type: Block (composition)
- Access: Pro
- Built from: Button, SegmentedControl, TextShimmer
- Documentation: https://uiarc.dev/components/blocks/account-health

### Overview

Drop it into an account or renewal page and pass `account` (name, plan, ARR, logo, term start and renewal date) and `periods` (one per time range, each with a score, the previous score, signals, a summary and an action). Pass `summarize(input, signal)` to return the summary text from your model. The card handles the thinking, streaming, abort and error states. Pass `onAction(action, input, signal)` to book the QBR for real, and reject it to show the retry state. `period`/`onPeriodChange` control the time range, and `asOf` fixes the countdown date. Keep the same number of trend points in every period so the sparklines morph from one to the next. With no props it plays a sample Linear Enterprise account.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/account-health. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/account-health while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- A customer success or account page that needs a score, the signals behind it and a next step.
- Renewal prep views where the countdown and risk drivers matter more than raw metrics.
- Showing an AI written risk summary next to the evidence it was written from.

### When not to use

- Portfolio views across many accounts; use a table with a score column instead.
- Deep metric exploration with axes and ranges; use a full chart.
- Single KPI tiles with no recommendation; use a stat card.

### Usage

```tsx
import { AccountHealth } from "@/components/arc/blocks/account-health/account-health";

export function CustomerPanel({ account, periods }) {
  return (
    <AccountHealth
      account={account}
      periods={periods}
      summarize={async ({ account, period }, signal) => {
        const res = await fetch("/api/health-summary", { method: "POST", body: JSON.stringify({ id: account.name, period: period.id }), signal });
        return (await res.json()).text;
      }}
      onAction={async (action, { account }, signal) => {
        await fetch("/api/qbr", { method: "POST", body: JSON.stringify({ account: account.name }), signal });
      }}
    />
  );
}
```

### API

#### AccountHealth

A customer success card: customer and plan, a health score gauge with trend, a renewal countdown, signal rows with sparklines and status, and an AI risk summary that ends in one recommended next step. With no props it plays a sample Linear Enterprise account.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `account` | `AccountHealthAccount` | `Linear sample` | The customer: name, plan, arr (formatted string), logo (ReactNode, about 24px), termStart and renewalDate (Date or ISO date). |
| `periods` | `AccountHealthPeriod[]` | `30d and 90d samples` | One entry per time range: id, label, spanLabel, score, previousScore, signals, summary and action. Keep the same number of trend points across periods so sparklines morph. |
| `period` | `string` |  | Controls the selected period id. Pair with onPeriodChange. |
| `defaultPeriod` | `string` | `first period` | The period selected on mount when uncontrolled. |
| `onPeriodChange` | `(period: string) => void` |  | Called when someone picks another time range. |
| `summarize` | `(input: { account, period }, signal: AbortSignal) => Promise<string>` |  | Writes the risk summary. Return the full text and the card streams it in. Aborted when the period changes or the summary is regenerated. Leave it out to use each period's summary, simulated. |
| `onAction` | `(action, input: { account, period }, signal: AbortSignal) => Promise<void> \| void` |  | Runs the recommended action, such as booking a QBR. Reject to show the error state with a retry. Leave it out to simulate it. |
| `model` | `{ name: string; mark?: ReactNode }` | `{ name: "Claude Sonnet 5.5" }` | The model credited on the summary, with its 14px mark. Defaults to the Claude mark. |
| `asOf` | `Date \| string` | `today` | The date the renewal countdown counts from. The sample account uses Oct 27, 2026. |
| `className` | `string` |  | Extra class on the card. |

#### AccountHealthSignal

One signal row.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `id` (required) | `string` |  | Stable key, shared across periods. |
| `label` (required) | `string` |  | "Product usage", "Seat utilization", "Support tickets", "NPS", "Invoice status". |
| `detail` | `string` |  | One short line of evidence: "Analytics down 18%". |
| `value` (required) | `string` |  | The headline value, right aligned in tabular numerals. |
| `status` (required) | `"good" \| "watch" \| "risk"` |  | Shown as an icon plus Good, Watch or At risk, and colors the sparkline when not good. |
| `trend` | `number[]` |  | Sparkline points, oldest first. |
| `source` | `ReactNode` |  | The source's 14px mark, such as PostHog, Okta, Zendesk, Intercom or Stripe. |
| `sourceLabel` | `string` |  | Names the source for screen readers: "From Zendesk". |

#### AccountHealthAction

The recommended next step under the summary.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` (required) | `string` |  | Button label: "Schedule QBR". |
| `title` (required) | `string` |  | The recommendation as a sentence: "Schedule a QBR with Linear". |
| `reason` (required) | `string` |  | Why, in a few words: "Usage dropped 18% in Analytics". |
| `doneLabel` | `string` |  | Shown once the action has run: "Invite drafted for Tue, Nov 3, 10:00". |

### Dependencies

- `motion`
- `lucide-react`

### Keyboard

| Keys | Action |
| --- | --- |
| Tab | Moves through the time range, regenerate and action buttons. |
| ArrowLeft / ArrowRight | Switches the time range inside the segmented control. |
| Enter / Space | Regenerates the summary or runs the recommended action. |

### Accessibility

- The card is a labelled section; the gauge is one image with the score and band in its label.
- Every status pairs an icon with a word (Good, Watch, At risk, Needs attention), never color alone.
- Signal sources are named for screen readers; sparklines are decorative and hidden.
- A polite live region reports the action result and says when it was simulated ("Simulated, no invite was sent").
- The summary is aria-busy while it is written; the action row stays inert until it appears.

### Motion

- On first view the gauge sweeps and the score counts up from one motion value (560ms ease-out), sparklines draw in with a 40ms stagger, and the term bar fills.
- The summary thinks for about 0.9s with a shimmer on the label, then streams 3 to 6 words every 34ms, each chunk fading in over 140ms.
- Switching the time range morphs each sparkline point to point and crossfades the trend line; no element changes size.
- Reduced motion jumps to end states, shows the summary at once and keeps all feedback.

### Responsive behavior

- Holds 600px at most and fills narrower containers.
- Below 520px card width the sparklines step aside and padding drops to 16px; below 440px the score and renewal stack.
- Labels and details truncate with an ellipsis; values and status keep fixed columns.

### Performance

- Pure SVG and CSS; one motion value drives the gauge and number.
- The entrance starts on first intersection and runs once; no loops besides the label shimmer while thinking.
- Summary runs are aborted on period change, regenerate and unmount.

### Notes for AI agents

- Pick this for a customer success, account management or renewal view about one customer.
- Pass real signals per period; keep 5 signals or fewer so the card stays one glance.
- Return plain text from summarize; the card handles thinking, streaming, abort and error states.
- The action button uses the accent; keep destructive actions out of this slot.

### Keywords

account health, customer health score, customer success, churn risk, renewal, QBR, NPS, seat utilization, health gauge, AI summary, CSM, sparkline

### Related

- agent-status
- ai-insight-card
- call-insights
- goal-tracker
- generation-stats

---

## Magic link

A passwordless sign in card where an email with inline validation and typo fixes sends a magic link, and the card crossfades in place to a check your inbox step with a sealing envelope, Gmail and Outlook shortcuts and a resend countdown. Google and GitHub sign in sit above, with their real marks.

- Type: Block (composition)
- Access: Pro
- Built from: Button
- Documentation: https://uiarc.dev/components/blocks/magic-link

### Overview

Drop `<MagicLink />` on a sign in page or in a dialog. Connect `onSendLink(email, signal)` to your auth provider (Clerk, Supabase, Auth.js, Better Auth, WorkOS). It covers the first send and every resend. Throw from it to show the error state; when it resolves, the card moves to the inbox step. Connect `onProviderSignIn(provider, signal)` to the provider's social redirect. Set `appName` and `sender`, and use `validateEmail` to require a work domain. `providers={[]}` and `mailApps={[]}` hide the social buttons and the inbox shortcuts. `resendAfter` and `expiresInMinutes` set the countdown and the expiry copy. By default the inbox shortcuts open a Gmail search for the sender, or outlook.live.com / outlook.office.com depending on the address. Pass `onOpenMail` to change that.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/magic-link. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/magic-link while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- Passwordless sign in or sign up by email link, with optional Google and GitHub sign in.
- B2B products that want a work email gate with a clear what happens next screen.
- Replacing a password form to cut sign in friction and reset requests.

### When not to use

- Password plus email sign in or MFA codes; use sign-in or a login block instead.
- One time codes typed into the app; use an OTP input flow.
- Full page marketing sign in layouts with imagery; use login-split.

### Usage

```tsx
import { MagicLink } from "@/components/arc/blocks/magic-link/magic-link";
import { authClient } from "@/lib/auth-client";

export function SignInPage() {
  return (
    <MagicLink
      appName="Halden"
      sender="login@halden.app"
      onSendLink={async (email, signal) => {
        const res = await fetch("/api/auth/magic-link", {
          method: "POST",
          body: JSON.stringify({ email, redirectTo: "/dashboard" }),
          signal,
        });
        if (!res.ok) throw new Error("Send failed");
      }}
      onProviderSignIn={provider => authClient.signIn.social({ provider, callbackURL: "/dashboard" })}
      validateEmail={email => /@(gmail|yahoo)\./i.test(email) ? "Use your work email" : null}
      termsHref="/terms"
      privacyHref="/privacy"
    />
  );
}
```

### API

#### MagicLink

A passwordless sign in card. Google and GitHub buttons sit above an email field with inline validation and a typo check ("Did you mean maya@gmail.com?"). Send magic link shows a spinner, then the card crossfades in place to Check your inbox: an envelope seals the letter, the address and expiry are shown, Open Gmail and Open Outlook jump to the inbox, a resend countdown ticks in tabular numerals and Use a different email goes back with the field focused. Both steps share one grid cell and one footer hairline, so the card never changes size. With no props every send is simulated.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `appName` | `string` | `"Halden"` | Your product's name, used in the title ("Sign in to Halden") and the card's accessible name. |
| `sender` | `string` | `"login@halden.app"` | The address the link comes from. Shown on the inbox step and used by Open Gmail to search for the email. |
| `defaultEmail` | `string` | `""` | Prefills the email field, for example from a previous session or an invite. |
| `emailLabel` | `string` | `"Work email"` | The label above the email field. |
| `providers` | `("google" \| "github")[]` | `["google", "github"]` | Social sign in buttons, in order, with their real marks. One provider spans the row. Pass [] to hide the buttons and the divider. |
| `mailApps` | `("gmail" \| "outlook")[]` | `["gmail", "outlook"]` | Inbox shortcuts on the Check your inbox step. Pass [] to hide them. |
| `resendAfter` | `number` | `30` | Seconds before the link can be sent again. The countdown restarts after every resend. |
| `expiresInMinutes` | `number` | `15` | How long the link stays valid. Display only; enforce it on the server. |
| `onSendLink` | `(email: string, signal: AbortSignal) => Promise<void> \| void` |  | Sends the magic link, for the first send and every resend. Throw to show "We couldn't send the link" (or Retry resend). The signal aborts when the person goes back or the card unmounts. Leave it out to simulate a send; nothing is sent and a status message says so. |
| `onProviderSignIn` | `(provider: "google" \| "github", signal: AbortSignal) => Promise<void> \| void` |  | Starts a social sign in, usually a redirect to your auth provider. The button shows a spinner until it settles; throw to show an inline error. Leave it out to simulate one. |
| `onOpenMail` | `(app: "gmail" \| "outlook", email: string) => void` |  | Handles the inbox shortcuts. By default Gmail opens a search for the sender in a new tab, and Outlook opens outlook.live.com for personal addresses or outlook.office.com for work ones. |
| `validateEmail` | `(email: string) => string \| null \| undefined` |  | Extra validation after the format check, such as allowing only company domains. Return the error message to show, or nothing to accept. |
| `termsHref` | `string` | `"#"` | Link to your terms in the footer. |
| `privacyHref` | `string` | `"#"` | Link to your privacy policy in the footer. |
| `className` | `string` |  | Class on the root wrapper, which spans its container and centers the card. |

### Dependencies

- `motion`
- `lucide-react`

### Keyboard

| Keys | Action |
| --- | --- |
| Tab | Moves through Google, GitHub, the email field, Send magic link and the footer links; on the inbox step through the inbox shortcuts, Use a different email and Resend. |
| Enter | Submits the email field. On a typo hint, pressing Enter again sends to the address as typed. |
| Space / Enter | Activates the focused button, including the suggested address in a typo hint. |

### Accessibility

- The card is a labelled region ("Sign in to Halden"); the hidden step is inert, so it leaves the tab order and the accessibility tree.
- Focus follows the step: the Check your inbox heading takes focus when the link is sent, and Use a different email returns focus to the field with the address selected.
- The field has a real label, autocomplete="email" and an email keyboard on touch. Errors set aria-invalid, are linked with aria-describedby and announced as alerts, and carry an icon as well as color.
- A polite live region announces sends, resends and simulated actions ("Simulated, nothing was sent").
- Resend stays focusable during the countdown (aria-disabled), so focus never drops when a resend starts.

### Motion

- Steps crossfade in one grid cell: the old step fades out in 100ms, the new one fades in over 200ms with a 4px rise. Nothing resizes.
- The envelope plays once per send in about 0.8s: the letter drops in, the flap folds shut, a success check settles. It replays on every resend. No bounce, no loop.
- Messages under the field and resend labels swap with a single opacity crossfade inside reserved space; the countdown digits change in place in tabular numerals.
- Reduced motion drops the rise and the envelope travel and renders its sealed end state, keeping the crossfades short.

### Responsive behavior

- Fills its container up to 400px. Under 480px the padding and corner radius step down.
- Provider and inbox buttons stay in two equal columns down to 320px; long addresses truncate with an ellipsis and keep the full value in a tooltip.
- Touch targets are 44px buttons and 32px footer links; the email field opens the email keyboard.

### Performance

- Both steps stay mounted (the hidden one inert), so switching never measures or reflows the card.
- The countdown ticks every 250ms only while it runs and stops at zero. The envelope is one small inline SVG.
- Brand marks are inline SVG; no images or network requests.

### Notes for AI agents

- Use for passwordless email sign in or sign up. Wire onSendLink to your auth provider (Clerk, Supabase, Auth.js, Better Auth, WorkOS) and onProviderSignIn to its social redirect.
- Throw from onSendLink to show the error state; resolve to advance to the inbox step. Pass the AbortSignal to fetch.
- Keep it centered on a plain page or in a dialog; it is a self-contained card about 400px wide.
- Hide social sign in with providers={[]} for B2B email-only flows, and use validateEmail to require a work domain.

### Keywords

magic link, passwordless, email sign in, login, check your inbox, resend countdown, sign in with google, sign in with github, auth, open gmail

### Related

- sign-in
- login-centered
- login-split
- input
- button

---

## Feature voting

A public feature request board where votes roll digit by digit and the button fills with the accent. Top, New and Trending reorder the rows with one smooth move. A built-in composer suggests similar requests as you type, so people vote instead of posting duplicates.

- Type: Block (composition)
- Access: Pro
- Built from: Button, SegmentedControl, Avatar
- Documentation: https://uiarc.dev/components/blocks/feature-voting

### Overview

Pass your requests (votes, comments, status, createdAt, trend, tag with an optional Linear, Okta, Slack, Notion, GitHub or Figma mark, and recent voters) and wire onVote(id, voted, signal) and onSubmit(draft, signal) to your API. Both are optimistic and roll back if the promise rejects. Swap in findSimilar to check duplicates against your search index. Set onOpenRequest to make the titles open a detail page. Use disabled for signed-out visitors and loading for placeholder rows. With no props it renders a sample board with simulated live votes.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/feature-voting. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/feature-voting while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- A public feature request page where customers vote and suggest ideas.
- An in-app Give feedback panel that shows what is planned and shipped.
- A customer portal that needs to deflect duplicate requests before they are posted.

### When not to use

- A full roadmap with columns per stage: use a kanban style board.
- One off feedback on a single page or screen: use a short feedback form.
- Release notes of what already shipped: use changelog-feed.

### Usage

```tsx
import { FeatureVoting } from "@/components/arc/blocks/feature-voting/feature-voting";

export function RoadmapBoard({ requests, user }) {
  return (
    <FeatureVoting
      requests={requests}
      currentUser={{ name: user.name, src: user.avatarUrl }}
      onVote={async (id, voted, signal) => {
        const response = await fetch(`/api/requests/${id}/vote`, { method: voted ? "POST" : "DELETE", signal });
        if (!response.ok) throw new Error("Vote not saved");
      }}
      onSubmit={async (draft, signal) => {
        const response = await fetch("/api/requests", { method: "POST", body: JSON.stringify(draft), signal });
        if (!response.ok) throw new Error("Request not posted");
        return response.json();
      }}
      onOpenRequest={id => router.push(`/roadmap/${id}`)}
    />
  );
}
```

### API

#### FeatureVoting

A public feature request board in one card. Each row has a vote button whose count rolls digit by digit and fills with the accent when you vote, the request title, a status chip (Under review, Planned, In progress, Shipped) drawn as an icon plus label, the area or integration with its real mark (Linear, Okta, Slack, Notion, GitHub, Figma) and a comment count. Hovering a vote button shows a small card with the latest voters' faces and names. Top, New and Trending reorder the rows with one bounce free move; rows never reorder on their own, so nothing jumps under the pointer. Suggest a feature opens an inline composer that lists similar requests as you type, each with a Vote button so people vote instead of posting a duplicate. A footer line confirms every action, and the sample board drops in live votes from other customers while it is on screen.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `requests` | `FeatureRequest[]` | `sample board` | Requests on the board: { id, title, status?: "review" \| "planned" \| "progress" \| "shipped", votes, comments, createdAt (ISO date, for New), trend? (votes in the last 7 days, for Trending), tag?: { label, mark? }, voters?: { name, src? }[] (latest first), voted? }. A new array replaces the board and re-applies the current sort. |
| `title` | `string` | `"Feature requests"` | Heading of the card. |
| `description` | `string` | `"Vote on what we build next. We read every request."` | One muted line under the heading. |
| `defaultSort` | `"top" \| "new" \| "trending"` | `"top"` | Sort applied on mount. |
| `onSortChange` | `(sort: FeatureSort) => void` |  | Called when someone picks Top, New or Trending. Use it to persist the choice or refetch. |
| `onVote` | `(id: string, voted: boolean, signal: AbortSignal) => void \| Promise<void>` |  | Called after the optimistic vote or unvote. Reject to roll it back with an error line. The signal aborts when the same request is toggled again. Without it, votes are simulated and the footer says so. |
| `onSubmit` | `(draft: { title, details }, signal: AbortSignal) => Promise<FeatureRequest \| void>` |  | Posts a new request. Resolve with the saved request, or nothing to add the draft as Under review with your vote. Reject to keep the composer open with an error. Without it, posting is simulated (700ms). |
| `findSimilar` | `(query: string, requests: FeatureRequest[]) => FeatureRequest[]` | `findSimilarRequests` | Duplicate finder used while typing a title. The default ranks by shared words, prefixes and a few synonyms (sso, login, okta). Swap in a search API or embeddings lookup; the first three results show. |
| `onOpenRequest` | `(id: string) => void` |  | Turns each title into a button, for opening the request's detail page or comment thread. |
| `currentUser` | `{ name: string; src?: string }` | `Nathan Cole` | The signed in person. Shown first, as You, in the voters card after they vote. |
| `live` | `boolean` | `true for the sample board` | Drops in a vote from another customer every few seconds while the card is visible. Off with reduced motion. |
| `loading` | `boolean` | `false` | Shows four placeholder rows at the same row height. |
| `disabled` | `boolean` | `false` | Turns voting and suggesting off, for signed out visitors. Counts and statuses stay readable. |
| `className` | `string` |  | Class on the root element. |

#### findSimilarRequests

The built in duplicate finder, exported for server side checks: findSimilarRequests(query, requests, limit = 3).

No props.

#### sortRequests

Returns request ids in Top, New or Trending order: sortRequests(requests, sort).

No props.

### Dependencies

- `motion`
- `lucide-react`

### Keyboard

| Keys | Action |
| --- | --- |
| Tab | Moves through Suggest a feature, the sort control, then each vote button (and title, when onOpenRequest is set). |
| Enter / Space | Votes or removes your vote on the focused request. Focusing a vote button with the keyboard shows its voters. |
| Arrow keys | Move between Top, New and Trending inside the sort control. |
| Enter | In the title field, posts the request. Cmd or Ctrl + Enter posts from the details field. |
| Escape | Closes the composer and returns focus to Suggest a feature. |

### Accessibility

- Vote buttons are toggle buttons (aria-pressed) labelled with the request and its count, for example Vote for SAML single sign-on with Okta, 351 votes.
- Statuses are always an icon plus a word, never color alone.
- Every vote, duplicate vote and new post is announced through a polite status region; simulated actions say Simulated, nothing was sent.
- The similar requests list is linked to the title field with aria-describedby, and each Vote button names the request it votes for.
- The voters card is decorative (aria-hidden); the same count is in the vote button's label.

### Motion

- Counts roll only the digits that change, up for a vote and down for an unvote, in tabular numerals so widths never shift.
- Sorting moves rows with one 240ms bounce free spring on transform. Rows never reorder on a live vote, so nothing moves under the pointer.
- The composer, the similar requests list and a newly posted row open by animating their measured height; everything below glides instead of jumping.
- The vote chevron nudges up 3px once when you vote. A new or chosen row gets a brief accent wash.
- Footer messages crossfade. With reduced motion, rolls, moves and folds cut to their end state and live votes stop.

### Responsive behavior

- One column card from 320px up. Below 440px the button reads Suggest and padding tightens; below 360px the integration tag hides.
- Titles and the footer truncate with an ellipsis; row height never changes.
- The voters card appears on hover with a mouse and on keyboard focus; touch skips it.

### Performance

- Renders every request; paginate or virtualize past about 50 rows.
- Duplicate detection runs locally on each keystroke and is linear in the number of requests.
- The live vote timer pauses when the card is off screen or the tab is hidden.

### Notes for AI agents

- Use for a public or in-app feature request board, roadmap feedback widget or customer voice page.
- Wire onVote and onSubmit to your API; both are optimistic and roll back on rejection.
- Pass findSimilar backed by your search index or embeddings to catch duplicates across thousands of requests.
- Keep the card between 360 and 760px; for a full kanban roadmap with columns, use a dedicated roadmap layout instead.
- Set disabled for signed out visitors and render your own sign in prompt next to the card.

### Keywords

feature voting, feature requests, upvote, roadmap, feedback board, canny, product feedback, duplicate detection, customer ideas, vote button

### Related

- feedback-board
- changelog-feed
- ai-feature-launch
- segmented-control
- avatar

---

## Credit top-up

A card for buying AI credits. It shows the balance with a 14 day usage chart and how many days are left, three preset packs with bonus badges, a custom amount slider with a live price, auto top-up with a threshold and the saved Visa or Mastercard. When you buy, the new balance rolls in like an odometer.

- Type: Block (composition)
- Access: Pro
- Built from: Button, Slider, Switch
- Documentation: https://uiarc.dev/components/blocks/credit-topup

### Overview

Drop it into a billing page, an out of credits dialog or a top-up drawer. Pass `balance` controlled, plus `usage` (daily credits, oldest first) and `paymentMethods`. Wire `onPurchase(order, signal)` to charge a saved card: resolve when the credits are added, or throw an Error with a short message to show the error state with Try again. `pricing` ({ unitPrice, currency, bonusTiers }) drives every price and bonus. Price orders on the server with the exported `quoteCredits` and the same pricing object. `onAutoTopupChange` and `onPaymentMethodChange` report settings changes. With no props it runs a simulated purchase for a workspace at 840 credits.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/credit-topup. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/credit-topup while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- Selling prepaid AI credits or tokens with volume bonuses.
- A billing settings section where people also manage auto top-up and their card.
- An out of credits moment where the balance, burn rate and a one click refill belong together.

### When not to use

- Subscription plan changes with seats and billing cycles: use a plan picker or checkout-live.
- Collecting a new card number: use a card form or a hosted payment element, then pass the saved card here.
- Read-only usage reporting: use a usage meter or a chart.

### Usage

```tsx
import { CreditTopup } from "@/components/arc/blocks/credit-topup/credit-topup";

export function BillingCredits({ workspace }) {
  return (
    <CreditTopup
      balance={workspace.credits}
      usage={workspace.dailyUsage}
      paymentMethods={workspace.cards}
      onPurchase={async (order, signal) => {
        const res = await fetch("/api/credits/purchase", { method: "POST", body: JSON.stringify(order), signal });
        if (!res.ok) throw new Error((await res.json()).message ?? "Payment failed. Try again or change card.");
      }}
      onAutoTopupChange={settings => fetch("/api/credits/auto-topup", { method: "PUT", body: JSON.stringify(settings) })}
    />
  );
}
```

### API

#### CreditTopup

A card for buying AI credits: the balance with a 14 day usage chart and days left, preset packs with bonus badges, a custom amount slider with a live price, auto top-up with a threshold, the saved card, and a checkout that rolls the new balance in. With no props it plays a simulated purchase for a workspace at 840 credits.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `balance` | `number` |  | The current balance in credits, controlled. Any change rolls the numerals. Leave it out and the card keeps its own balance and adds each purchase to it. |
| `defaultBalance` | `number` | `840` | The starting balance when `balance` is left out. |
| `usage` | `CreditUsageDay[]` | `Oct 14 to Oct 27, 2026 sample` | Daily usage, oldest first: { date: ISO date, credits }. The last day is today. Drives the bar chart, its hover readout, and the days left estimate (average of the full days). |
| `packs` | `number[]` | `[1000, 5000, 20000]` | Preset pack sizes in credits, shown as a radio group. Keep it to three for the layout. |
| `pricing` | `CreditPricing` | `$0.01 a credit, +10% from 5,000, +15% from 20,000` | { unitPrice, currency, bonusTiers: { min, percent }[] }. Prices, bonus badges, the total and the per 1,000 rate all derive from it. |
| `range` | `{ min: number; max: number; step: number }` | `{ min: 500, max: 30000, step: 500 }` | The custom amount slider's range in credits. A slider value equal to a pack selects that pack. |
| `defaultCredits` | `number` | `the second pack` | The amount selected on mount. |
| `paymentMethods` | `CreditPaymentMethod[]` | `Visa 4242, Mastercard 5454` | Saved cards: { id, brand: "visa" \| "mastercard", last4, expires: "MM/YYYY" }. Change cycles through them. |
| `thresholds` | `number[]` | `[500, 1000, 2500]` | Choices for the auto top-up threshold. The balance reads as running low below the selected one. |
| `defaultAutoTopup` | `{ enabled: boolean; threshold: number }` | `{ enabled: false, threshold: 1000 }` | Auto top-up settings on mount. |
| `onAutoTopupChange` | `(settings: { enabled, threshold, credits }) => void` |  | Called when auto top-up is switched or its threshold changes. credits is the selected amount including bonus. |
| `onPaymentMethodChange` | `(id: string) => void` |  | Called when another saved card is chosen. |
| `onPurchase` | `(order: CreditOrder, signal: AbortSignal) => Promise<void>` |  | Charges the order { credits, bonus, total, price, currency, paymentMethodId }. Resolve once the credits are added; reject with an Error and its message shows with a Try again button. Aborted on unmount. Leave it out to simulate a 1.2s charge. |
| `onPurchased` | `(order: CreditOrder, balance: number) => void` |  | Called after a successful purchase with the new balance. |
| `className` | `string` |  | Extra class on the card. |

#### quoteCredits

The pricing helper the card uses: quoteCredits(credits, pricing) returns { credits, bonus, total, price, currency }. Use it on the server to price the same order.

No props.

### Dependencies

- `motion`
- `lucide-react`

### Keyboard

| Keys | Action |
| --- | --- |
| Tab | Moves through the packs, slider, auto top-up switch, threshold, Change and Buy credits. |
| ArrowLeft / ArrowRight | Moves between packs or thresholds and selects as it goes. Home and End jump to the first and last. |
| ArrowLeft / ArrowRight on the slider | Steps the custom amount by 500 credits. PageUp and PageDown take larger steps. |
| Space | Switches auto top-up. |
| Enter / Space | Buys the selected credits or changes the card. |

### Accessibility

- Packs and thresholds are radio groups with roving focus and labels that read the amount, price and bonus, such as "5,000 credits, $50, 10% bonus".
- Rolling numerals are aria-hidden; a visually hidden copy of each value is read instead, so screen readers never hear partial digits.
- A polite live region announces the charge, the result ("Added 5,500 credits. Nothing was charged.") and errors. Without onPurchase it says the checkout is simulated.
- Balance health is an icon plus a label (Running low, Healthy), never color alone. The usage chart is one image with a spoken summary.
- The Buy button stays focusable while processing (aria-busy) so keyboard focus is not lost.

### Motion

- After a purchase the balance rolls up odometer style over 0.9s: each digit rolls one way to its target and the lower places take one extra lap, so it reads as counting. New leading places open their width on a bounce-free spring.
- The total and price roll in 0.24s as the slider moves, in tabular numerals so nothing shifts.
- The pack selection ring and threshold pill glide between options on a 0.24s spring with no bounce. Status, health, days left and the saved card crossfade (100ms out, 160ms in, 2px rise).
- The card never changes size between idle, processing, done and error.
- Reduced motion: numbers and highlights jump to their end state; crossfades stay as plain fades.

### Responsive behavior

- Fluid up to 480px. Below about 450px container width the usage chart moves under the balance and stretches full width, and padding drops to 16px.
- Packs stay three across down to 320px; the bonus badge sits on the price line so amounts never truncate.
- Container queries, not viewport queries, so it adapts inside dialogs and sidebars.

### Performance

- Each digit is one transformed strip driven by a motion value: no re-renders while numbers roll.
- No timers or loops while idle; the only timeout clears the done message.
- Brand marks are inline SVG, about 1 KB.

### Notes for AI agents

- Use for usage-based AI products that sell prepaid credits: a billing page section, an out of credits dialog body, or a top-up drawer.
- Keep pricing on the server authoritative: price orders with the exported quoteCredits and the same pricing object, never trust the client total.
- Pass balance controlled when credits change elsewhere (live usage); the numerals roll on every change, so it doubles as a live balance.
- Wire onPurchase to a saved payment method charge (for example a Stripe PaymentIntent with off_session) and throw an Error with a short human message on decline.

### Keywords

credits, top up, buy credits, AI credits, prepaid, token balance, auto recharge, auto top-up, usage based billing, wallet, balance, odometer, rolling numbers, billing

### Related

- checkout-live
- payment-flow
- usage-meter
- slider
- switch
- button

---

## Goal tracker

A team goals card where objectives open into key results with owners, confidence and progress bars. A weekly check-in updates a value, confidence and note in place, fills the bar and recalculates the objective, and a quarter selector steps from last quarter's final scores to next quarter's planning.

- Type: Block (composition)
- Access: Pro
- Built from: Button, Avatar, SegmentedControl
- Documentation: https://uiarc.dev/components/blocks/goal-tracker

### Overview

Pass `quarters` (each with id, label, status of active, closed or planning, optional meta and footnote, and objectives with key results). For each key result, set start, target and current in the metric's own units. The card works out progress itself, so a target below the start value (latency, cost) works with no extra setup. Save check-ins in `onCheckIn(checkIn, { signal })`. The card updates once the promise resolves. If it throws, the form shows "Not saved" and a Retry button. Control the selector with `quarterId` and `onQuarterChange`, and set `autoPlay={false}` in production. Helpers (`keyResultProgress`, `objectiveProgress`, `formatGoalValue`) and `sampleGoalQuarters` are exported.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/goal-tracker. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/goal-tracker while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- Showing a team's quarterly objectives and key results with owners and confidence.
- Collecting a lightweight weekly check-in (value, confidence, note) without leaving the page.
- Comparing the active quarter against last quarter's final scores.

### When not to use

- A single KPI with a trend line; use a metric or stat card.
- Task or project tracking with assignees and due dates; use a task list or kanban block.
- Org-wide goal trees with parent and child alignment; this card is one level deep.

### Usage

```tsx
import { GoalTracker, type GoalCheckIn, type GoalQuarter } from "@/components/arc/blocks/goal-tracker/goal-tracker";

export function TeamGoals({ quarters }: { quarters: GoalQuarter[] }) {
  return (
    <GoalTracker
      title="Platform goals"
      quarters={quarters}
      onCheckIn={async (checkIn: GoalCheckIn, { signal }) => {
        const response = await fetch("/api/check-ins", { method: "POST", body: JSON.stringify(checkIn), signal });
        if (!response.ok) throw new Error("Check-in failed");
      }}
    />
  );
}
```

### API

#### GoalTracker

A team goals card. Objectives expand into key results with owners, confidence and progress bars; a key result opens a weekly check-in that updates its value, confidence and note, animates the bar and recalculates the objective. A quarter selector steps between closed, active and planning quarters. With no props it shows sample Q4 2026 goals and plays one check-in.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `quarters` | `GoalQuarter[]` | `sampleGoalQuarters` | Quarters, oldest first. Each has id, label, status (active, closed or planning), optional meta and footnote lines, and objectives. Seeds the card; saved check-ins update it in place. |
| `title` | `string` | `"Company goals"` | Card heading. |
| `quarterId` | `string` |  | Selected quarter id. Pair with onQuarterChange to control the selector. |
| `defaultQuarterId` | `string` | `the active quarter` | Quarter shown first when uncontrolled. |
| `onQuarterChange` | `(quarterId: string) => void` |  | Called when the person steps to another quarter. |
| `onCheckIn` | `(checkIn: GoalCheckIn, context: { signal: AbortSignal }) => Promise<void> \| void` |  | Saves a check-in: quarterId, objectiveId, keyResultId, value, previousValue, confidence and note. Throw to show the error state with Retry; the signal aborts when the person cancels. Leave it out to simulate a save. |
| `autoPlay` | `boolean` | `true with sample data, false with your own` | Plays one scripted check-in the first time the card scrolls into view. Any pointer or key input hands control back at once. |
| `className` | `string` |  | Extra class on the card. |

#### GoalKeyResult

One measurable result. Progress runs from start to target, so a target below start (latency, cost, ticket counts) also works.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `id` (required) | `string` |  | Stable id, returned in GoalCheckIn. |
| `title` (required) | `string` |  | What success looks like, such as "Checkout p95 latency under 400 ms". |
| `start` (required) | `number` |  | Value when the quarter began. |
| `target` (required) | `number` |  | Value that counts as 100%. |
| `current` (required) | `number` |  | Latest checked in value. |
| `prefix` | `string` |  | Text before the number, such as "$". |
| `unit` | `string` |  | Text after the number, such as "%", " ms" or "k". |
| `decimals` | `number` | `0` | Decimal places shown and pre-filled in the check-in. |
| `confidence` (required) | `"on-track" \| "at-risk" \| "off-track"` |  | Owner's confidence, shown as an icon and label and as the bar color. |
| `source` | `{ name: string; icon?: ReactNode }` |  | Where the number is synced from, shown as a small mark (Stripe, Linear, Vercel in the sample). |

#### GoalObjective

An objective with its owner and key results. Progress is the mean of its key results; confidence is their rounded mean.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `id` (required) | `string` |  | Stable id. |
| `title` (required) | `string` |  | The objective. |
| `owner` (required) | `{ name: string; avatar?: string }` |  | Owner shown with an avatar; initials when there is no image. |
| `keyResults` (required) | `GoalKeyResult[]` |  | Two to five key results reads best. |

### Dependencies

- `motion`
- `lucide-react`

### Keyboard

| Keys | Action |
| --- | --- |
| Tab | Moves through the quarter buttons, objectives, key results and the footer Check in button. |
| Enter / Space | On an objective, expands or collapses it. On a key result, opens its check-in with the value selected. |
| Arrow keys | In the check-in, moves between On track, At risk and Off track. |
| Enter | In the check-in, saves. |
| Escape | Cancels the check-in and returns focus to the key result. |

### Accessibility

- Objectives are disclosure buttons with aria-expanded and aria-controls; collapsed bodies are inert.
- Each key result button has a label with its value, target, progress and confidence, so the visual bar is not the only source.
- Confidence is always an icon plus a text label, never color alone.
- The check-in is a labelled form; the hidden form and hidden key results are inert so focus never lands on invisible controls.
- A polite live region announces saves, errors and the recalculated objective, and says when a save was simulated.

### Motion

- Bars fill once when the card first scrolls into view, then tween to new values (560ms ease-out) with percentages counting in tabular numerals.
- The objective bar follows its key result 120ms later so cause and effect read clearly.
- Key results and the check-in form share one grid cell and crossfade (100ms out, 160ms in), so the card never changes height when the form opens.
- Objective bodies open with a bounce-free 240ms spring on measured height; quarters crossfade with an 8px directional shift and the empty state borrows the previous height.
- Reduced motion keeps the end states, crossfades and feedback, and drops the fill travel, shifts and the scripted demo.

### Responsive behavior

- Fluid from 360px to 640px wide using container queries, so it adapts to its column rather than the viewport.
- Below 480px the bars shorten and the confidence picker moves under the value field; below 380px owner names collapse to avatars.
- Titles truncate with an ellipsis; numbers, labels and bars never wrap or shift.

### Performance

- Progress animations run on motion values and clip-path, so numbers and bars update without React re-renders.
- One IntersectionObserver for the first fill and one ResizeObserver for the quarter height; both disconnect on unmount.
- Designed for up to about five objectives with five key results each per quarter.

### Notes for AI agents

- Use for OKRs, team goals or quarterly targets inside a product: a settings or team page, a dashboard column, or a weekly review.
- Pass real data through quarters and persist check-ins in onCheckIn; the card updates optimistically after the promise resolves, and shows Retry if it throws.
- Set start, target and current in the metric's own units; the card computes progress, so decreasing targets need no special handling.
- Set autoPlay={false} in production. The sample data plays one demo check-in by default.
- Keep one card per team; for many teams, stack cards rather than adding more objectives to one card.

### Keywords

okr, goals, objectives, key results, goal tracker, check-in, progress bar, quarterly goals, confidence, lattice, team goals

### Related

- agent-tasks
- activity-feed
- account-health

---

## Spend alert

A budget and spend alert card where the threshold is set right on the live spend bar, with forecast, Email, Slack and PagerDuty toggles, a hard stop and a live preview of the Slack message the alert will post.

- Type: Block (composition)
- Access: Pro
- Built from: Switch, Button
- Documentation: https://uiarc.dev/components/blocks/spend-alert

### Overview

Drop SpendAlert into a billing or usage settings page. Pass `spend` and `period` from your usage API (the forecast is projected for you unless you pass `forecast`), set the starting `defaultValue` (budget, threshold, channels, hardStop), and set `destinations` for your email, Slack channel and PagerDuty service. Wire `onSave` and `onSendTest`: each receives the settings and an AbortSignal, and the card handles the loading, saved, error and unsaved-changes states. Without handlers, both actions are simulated and the live region says so. `onChange` reports every edit.

### Install

Arc Pro block: not in the public registry. Pro members install it with a Pro token (create one at https://uiarc.dev/account): add "@uiarc-pro": { "url": "https://uiarc.dev/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ARC_PRO_TOKEN}" } } to "registries" in components.json, set ARC_PRO_TOKEN, then run npx shadcn@latest add @uiarc-pro/spend-alert. Or copy the source from the Manual tab at https://uiarc.dev/components/blocks/spend-alert while signed in. Plans: https://uiarc.dev/pricing. Never reconstruct it.

### When to use

- Letting a team set a monthly budget and alert threshold for metered spend.
- Showing how close current and forecast spend are to an alert line.
- Choosing where cost alerts go and previewing the Slack message before saving.

### When not to use

- Read-only usage reporting with no settings; use usage-forecast or usage-billing instead.
- Per-seat plans with no metered spend.
- Complex multi-budget policies across many projects; use a table of budgets that opens this card per row.

### Usage

```tsx
import { SpendAlert } from "@/components/arc/blocks/spend-alert/spend-alert";

export function BillingAlerts({ usage }: { usage: { spend: number } }) {
  return (
    <SpendAlert
      project="Production"
      spend={usage.spend}
      defaultValue={{ budget: 5000, threshold: 80 }}
      destinations={{ email: "finance@acme.com", slack: "#eng-spend" }}
      onSave={async (settings, signal) => {
        const response = await fetch("/api/budget-alerts", { method: "PUT", body: JSON.stringify(settings), signal });
        if (!response.ok) throw new Error("Save failed");
      }}
    />
  );
}
```

### API

#### SpendAlert

Budget and spend alert settings in one card: a monthly budget, a threshold slider drawn on the live spend bar, Email, Slack and PagerDuty toggles, a hard stop switch, and a live preview of the Slack message the alert posts. Renders the full demo with no props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` | `string` | `"Spend alerts"` | Card title. |
| `project` | `string` | `"Production"` | Project or workspace the budget applies to. Used in the subtitle and the Slack message. |
| `scope` | `string` | `"Model API usage"` | What is being metered, shown in the subtitle. |
| `spend` | `number` | `3412.8` | Spend so far this period, drawn as the solid fill on the bar. |
| `forecast` | `number` |  | Projected spend at period end, drawn as the lighter fill. Defaults to a linear projection from spend and period. |
| `period` | `{ label: string; short: string; day: number; days: number; resetsOn: string }` | `{ label: "October", short: "Oct", day: 27, days: 31, resetsOn: "Nov 1" }` | Billing period used for the forecast, the crossing date and the reset copy. |
| `currency` | `string` | `"USD"` | ISO 4217 currency code for formatting. |
| `defaultValue` | `Partial<SpendAlertSettings>` | `{ budget: 5000, threshold: 80, channels: { email: true, slack: true, pagerduty: false }, hardStop: false }` | Initial settings. Missing fields fall back to the demo defaults. |
| `markers` | `number[]` | `[50, 80, 100]` | Threshold markers on the bar. The thumb snaps to them within 2% while dragging, and PageUp or PageDown jumps between them. |
| `destinations` | `Partial<Record<"email" \| "slack" \| "pagerduty", string>>` | `{ email: "finance@acme.com", slack: "#eng-spend", pagerduty: "Platform on-call" }` | Where each channel delivers. PagerDuty pages only at 100%. |
| `appName` | `string` | `"Acme Billing"` | Sender name in the Slack preview. |
| `lastSaved` | `string` | `"Last edited Oct 24 by Maya Chen"` | Footer copy while nothing has changed. |
| `onChange` | `(settings: SpendAlertSettings) => void` |  | Called on every edit. |
| `onSave` | `(settings: SpendAlertSettings, signal: AbortSignal) => Promise<void>` |  | Persist the settings. Without it the save is simulated. Reject to show the error state. |
| `onSendTest` | `(settings: SpendAlertSettings, signal: AbortSignal) => Promise<void>` |  | Send a test alert to the enabled channels. Without it the send is simulated. |
| `className` | `string` |  | Extra class on the card. |

### Dependencies

- `motion`
- `lucide-react`
- `@radix-ui/react-switch`

### Keyboard

| Keys | Action |
| --- | --- |
| Arrow keys | On the threshold slider, move the alert line by 1%. |
| Shift + Arrow keys | Move the alert line by 10%. |
| PageUp / PageDown | Jump to the next or previous marker. |
| Home / End | Set the threshold to 10% or 100%. |
| ArrowUp / ArrowDown | In the budget field, change the budget by 100 (Shift for 1,000). |
| Space | Toggle a focused channel or the hard stop switch. |

### Accessibility

- The threshold is a role="slider" labelled "Alert at" with aria-valuetext giving the percent and the amount.
- The budget field is labelled and described by its helper line, which also carries the invalid and over-budget messages with aria-invalid.
- Each channel switch has its own label; the hard stop switch is labelled by its row title.
- Save and test results land in a polite live region, including "Simulated, nothing was sent" when no handler is wired.
- Status is never color alone: every tone pairs an icon with a short label.

### Motion

- Spend and forecast fills grow in once when the card scrolls into view (720ms ease-out), then follow budget changes in 160ms.
- The thumb follows the pointer 1:1 while dragging and glides 160ms on clicks, marker jumps and keys.
- Status, helper and footer lines swap with a single crossfade in one grid cell, so nothing changes size.
- Switching Slack off crossfades the preview to a placeholder inside the same box. A test send washes the preview once.
- Reduced motion keeps every end state and drops the fill growth and glides.

### Responsive behavior

- Holds from 360px to 580px. Under 440px the gutter tightens, channel destinations move under their names and the footer actions go full width.
- Every line truncates with an ellipsis rather than wrapping, so state changes never change the card height.
- The slider rail is 28px tall for touch and keeps vertical page scroll (touch-action: pan-y).

### Performance

- Bar fills animate clip-path and the thumb animates left on one element; no layout animation on text.
- One IntersectionObserver runs until the first reveal, then disconnects.

### Notes for AI agents

- Use for usage-based billing settings: AI model spend, cloud cost budgets, API overage alerts.
- Pass spend and period from your usage API; forecast is derived unless you pass your own.
- Wire onSave and onSendTest with the AbortSignal; the card handles loading, success, error and dirty states.
- Keep it as one card in a settings page; do not wrap it in another card.

### Keywords

spend alert, budget alert, billing threshold, usage alert, cost alert, AI spend, slack notification preview, pagerduty, hard stop, budget settings

### Related

- usage-forecast
- usage-billing
- billing-overview
- switch
- slider