# Cuelark UI: full reference

> Open-source React components for shadcn/ui: an AI agent UI kit (chat, reasoning, tool calls, plans, citations, traces), GSAP-animated effects and accessible Radix primitives. Themeable with CSS variables, installed as source with the shadcn CLI.

## Accordion

An accordion lets readers scan a list of headings and open only what they need. Cuelark's accordion adds CSS-counter numbering, a plus that turns into a close mark, and three surface styles, while each trigger stays inside a real heading for a clean document outline.

Install: `npx shadcn@latest add https://ui.cuelark.com/r/accordion.json` · Docs: https://ui.cuelark.com/components/accordion

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

<Accordion type="single" collapsible numbered>
  <AccordionItem value="item-1">
    <AccordionTrigger>Is it accessible?</AccordionTrigger>
    <AccordionContent>Yes. It follows the WAI-ARIA accordion pattern.</AccordionContent>
  </AccordionItem>
</Accordion>
```

### Props

- `Accordion.variant` (`"lined" | "dashed" | "separated"`, default `"lined"`): Divider style between items.
- `Accordion.numbered` (`boolean`, default `false`): Prefix triggers with 01, 02, … via CSS counters.
- `AccordionItem.value` (`string`): Unique value of the item.

### Accessibility

- Triggers are buttons inside <h3> headings with aria-expanded and aria-controls.
- Space and Enter toggle; arrow keys, Home and End move between triggers.
- Height animations are skipped when the user prefers reduced motion.

## Alert

Alerts call out information inline: a notice, a success, a warning, an error. The tone is carried by a rail and icon while text stays readable, and dismissible alerts fold away smoothly.

Install: `npx shadcn@latest add https://ui.cuelark.com/r/alert.json` · Docs: https://ui.cuelark.com/components/alert

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

<Alert tone="warning">
  <AlertTitle>Usage at 90%</AlertTitle>
  <AlertDescription>Upgrade to avoid throttling.</AlertDescription>
</Alert>
```

### Props

- `Alert.tone` (`"info" | "success" | "warning" | "destructive" | "neutral"`, default `"info"`): Color and icon.
- `Alert.icon` (`ReactNode | null`): Custom icon, or null for none.
- `Alert.onDismiss` (`() => void`): Adds a close button.

### Accessibility

- Warnings and errors use role=alert; others use role=status.
- Color is never the only signal: each tone has an icon.

## Alert Dialog

An alert dialog interrupts to confirm something that cannot be undone. Unlike a dialog it can't be dismissed by clicking outside. Cuelark's drops in slightly heavier than a dialog, and the destructive tone adds a red rail along the top.

Install: `npx shadcn@latest add https://ui.cuelark.com/r/alert-dialog.json` · Docs: https://ui.cuelark.com/components/alert-dialog

```tsx
import { AlertDialog, AlertDialogAction, AlertDialogCancel, AlertDialogContent, AlertDialogTitle, AlertDialogTrigger } from "@/components/ui/alert-dialog";

<AlertDialog>
  <AlertDialogTrigger asChild><Button variant="destructive">Delete</Button></AlertDialogTrigger>
  <AlertDialogContent tone="destructive">
    <AlertDialogTitle>Delete project?</AlertDialogTitle>
    <AlertDialogCancel>Cancel</AlertDialogCancel>
    <AlertDialogAction variant="destructive">Delete</AlertDialogAction>
  </AlertDialogContent>
</AlertDialog>
```

### Props

- `AlertDialogContent.tone` (`"default" | "destructive"`, default `"default"`): Destructive adds a red top rail.
- `AlertDialogAction.variant` (`"primary" | "destructive"`, default `"primary"`): Button style.

### Accessibility

- role=alertdialog; focus starts on Cancel, the safe choice.
- Outside clicks do not close it; Esc does.

## Animated Icon

Animated Icon brings any icon to life with GSAP: react-icons, lucide-react, an installed Cuelark icon or a raw SVG. Leave the animation on auto and it reads the icon's name to pick a motion that means something: bells ring, arrows nudge in their direction, gears turn, send icons fly off and return, refresh spins, charts grow, eyes blink, flags wave, pins drop. Or choose from 30 named animations, triggered on hover, click, mount, scroll or loop.

Install: `npx shadcn@latest add https://ui.cuelark.com/r/animated-icon.json` · Docs: https://ui.cuelark.com/components/animated-icon

```tsx
import { AnimatedIcon } from "@/components/ui/animated-icon";

<AnimatedIcon>
  <BellIcon />
</AnimatedIcon>

<AnimatedIcon animation="spin" trigger="click">
  <RefreshCwIcon />
</AnimatedIcon>
```

### Props

- `AnimatedIcon.animation` (`string`, default `"auto"`): auto, pop, ring, nudge-right, turn, fly, spin, twinkle, zoom, blink, wave, grow, drive, drop, draw and more.
- `AnimatedIcon.trigger` (`"hover" | "click" | "mount" | "inView" | "loop"`, default `"hover"`): When it plays.
- `AnimatedIcon.name` (`string`): Icon name for auto mode; read from the child when omitted.
- `AnimatedIcon.duration` (`number`): Override seconds.

### Accessibility

- Decorative motion only; the icon keeps its own label.
- With reduced motion or --cl-motion: 0 the effect stays still and the content remains fully usable.

## Animated List

Animated List turns a list into a live feed: new items spring in at the top while the others glide down to make room. Use it for notifications, activity streams and transactions on landing pages and dashboards.

Install: `npx shadcn@latest add https://ui.cuelark.com/r/animated-list.json` · Docs: https://ui.cuelark.com/components/animated-list

```tsx
import { AnimatedList } from "@/components/ui/animated-list";

<AnimatedList>{notifications}</AnimatedList>
```

### Props

- `AnimatedList.interval` (`number`, default `1400`): ms between items.
- `AnimatedList.loop` (`boolean`, default `true`): Cycle forever.
- `AnimatedList.max` (`number`, default `5`): Visible items.

### Accessibility

- A polite live region; consider loop={false} for screen-reader heavy pages.
- With reduced motion or --cl-motion: 0 the effect stays still and the content remains fully usable.

## Artifact

Artifact presents what an agent produced (a document, a component, a chart) in a panel beside the conversation, with a header of actions and a full-screen toggle.

Install: `npx shadcn@latest add https://ui.cuelark.com/r/artifact.json` · Docs: https://ui.cuelark.com/components/artifact

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

<Artifact kind="Document" title="Q4 notes" onClose={close}>…</Artifact>
```

### Props

- `Artifact.title · kind` (`ReactNode · string`): Header.
- `Artifact.onClose · onDownload` (`() => void`): Actions.
- `Artifact.actions` (`ReactNode`): Extra buttons.

### Accessibility

- Fully keyboard operable with visible focus.
- Live regions announce streaming updates politely.

## Aspect Ratio

Aspect Ratio reserves space for images, video and embeds at a fixed ratio, so the page does not jump while media loads, which also protects your Cumulative Layout Shift score.

Install: `npx shadcn@latest add https://ui.cuelark.com/r/aspect-ratio.json` · Docs: https://ui.cuelark.com/components/aspect-ratio

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

<AspectRatio ratio={16 / 9}>
  <img src="/cover.jpg" alt="" className="size-full object-cover" />
</AspectRatio>
```

### Props

- `AspectRatio.ratio` (`number`, default `1`): Width divided by height.

### Accessibility

- Purely layout; give media its own alt text.

## Avatar

Avatars represent people and teams. Cuelark avatars fall back to initials in a tint derived from the name, show presence dots, and AvatarGroup stacks people that fan apart on hover and collapses extras into +N.

Install: `npx shadcn@latest add https://ui.cuelark.com/r/avatar.json` · Docs: https://ui.cuelark.com/components/avatar

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

<Avatar status="online">
  <AvatarImage src="/ada.jpg" alt="Ada Lovelace" />
  <AvatarFallback name="Ada Lovelace" />
</Avatar>
```

### Props

- `Avatar.size` (`"xs" | "sm" | "md" | "lg" | "xl"`, default `"md"`): Size.
- `Avatar.shape` (`"circle" | "square"`, default `"circle"`): Shape.
- `Avatar.status` (`"online" | "away" | "busy" | "offline"`): Presence dot.
- `AvatarFallback.name` (`string`): Initials and a deterministic tint.
- `AvatarGroup.max` (`number`): Show this many, then +N.

### Accessibility

- Give AvatarImage an alt with the person's name.
- Status dots have a text label.

## Badge

Badges label status, category or version at a glance. Cuelark badges come in soft tinted tones, an optional status dot with a live pulse, and a mono uppercase style for version tags and metadata.

Install: `npx shadcn@latest add https://ui.cuelark.com/r/badge.json` · Docs: https://ui.cuelark.com/components/badge

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

<Badge variant="success" dot="pulse">Live</Badge>
```

### Props

- `Badge.variant` (`"neutral" | "primary" | "success" | "warning" | "destructive" | "outline" | "solid"`, default `"neutral"`): Color tone.
- `Badge.size` (`"sm" | "md"`, default `"md"`): Height and text size.
- `Badge.dot` (`boolean | "pulse"`, default `false`): Leading status dot; pulse adds a ping.
- `Badge.mono` (`boolean`, default `false`): Mono, uppercase, tracked text.
- `Badge.asChild` (`boolean`, default `false`): Render the child element (e.g. a link) with badge styles.

### Accessibility

- The status dot is decorative (aria-hidden); the text carries the meaning.
- The pulse animation is hidden for users who prefer reduced motion.
- Badge links get a visible focus outline.

## Border Beam

Border Beam draws a short comet of light that laps the border of its parent. Use it to mark the recommended plan, a new feature or an active state. It is one masked conic gradient rotated by GSAP: no SVG, no layout cost.

Install: `npx shadcn@latest add https://ui.cuelark.com/r/border-beam.json` · Docs: https://ui.cuelark.com/components/border-beam

```tsx
import { BorderBeam } from "@/components/ui/border-beam";

<div className="relative rounded-2xl border">
  …
  <BorderBeam />
</div>
```

### Props

- `BorderBeam.duration` (`number`, default `6`): Seconds per lap.
- `BorderBeam.color` (`string`, default `"var(--signal)"`): Beam color.
- `BorderBeam.size` (`number`, default `0.18`): Beam length (0–1 of the border).

### Accessibility

- Decorative and aria-hidden.
- With reduced motion or --cl-motion: 0 the effect stays still and the content remains fully usable.

## Branch

Branch lets people move between alternative versions of a message (regenerations or edits) with a small “2 / 3” control; the version slides in from the direction you moved.

Install: `npx shadcn@latest add https://ui.cuelark.com/r/branch.json` · Docs: https://ui.cuelark.com/components/branch

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

<Branch versions={[<p>v1</p>, <p>v2</p>]} />
```

### Props

- `Branch.versions` (`ReactNode[]`): Alternatives.
- `Branch.defaultIndex · onIndexChange` (`number`): Selection.

### Accessibility

- Fully keyboard operable with visible focus.
- Live regions announce streaming updates politely.

## Breadcrumb

Breadcrumbs show where a page sits in the site hierarchy and give one-click routes back up. Pair the component with BreadcrumbList JSON-LD (this site does) and Google shows the same trail in search results.

Install: `npx shadcn@latest add https://ui.cuelark.com/r/breadcrumb.json` · Docs: https://ui.cuelark.com/components/breadcrumb

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

<Breadcrumb>
  <BreadcrumbList>
    <BreadcrumbItem><BreadcrumbLink href="/">Home</BreadcrumbLink></BreadcrumbItem>
    <BreadcrumbSeparator />
    <BreadcrumbItem><BreadcrumbPage>Docs</BreadcrumbPage></BreadcrumbItem>
  </BreadcrumbList>
</Breadcrumb>
```

### Props

- `BreadcrumbLink.asChild` (`boolean`, default `false`): Use your router's Link.
- `BreadcrumbSeparator.children` (`ReactNode`, default `"/"`): Custom separator.

### Accessibility

- A <nav aria-label="Breadcrumb"> with an ordered list.
- The current page has aria-current="page".

## Burst

Burst wraps any clickable element and throws a small spray of confetti from the click point. Pieces arc, spin and fall in a GSAP timeline, then clean themselves up. Save it for real milestones: finished onboarding, a first deploy, a like.

Install: `npx shadcn@latest add https://ui.cuelark.com/r/burst.json` · Docs: https://ui.cuelark.com/components/burst

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

<Burst><Button>Celebrate</Button></Burst>
```

### Props

- `Burst.count` (`number`, default `18`): Particles per click.
- `Burst.colors` (`string[]`, default `signal, ink, muted`): Particle colors.
- `Burst.disabled` (`boolean`, default `false`): Turn it off.

### Accessibility

- Particles are decorative and removed after 1.5s.
- With reduced motion or --cl-motion: 0 the effect stays still and the content remains fully usable.

## Button

Buttons trigger actions. Cuelark buttons have a pressed state you can feel (an inset highlight and a one-pixel travel), a loading state that keeps the button's width, and a built-in keyboard shortcut hint, so the shortcut is learned where the action lives.

Install: `npx shadcn@latest add https://ui.cuelark.com/r/button.json` · Docs: https://ui.cuelark.com/components/button

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

<Button kbd="⌘S" loading={saving}>Save</Button>
```

### Props

- `Button.variant` (`"primary" | "secondary" | "outline" | "ghost" | "destructive" | "link"`, default `"primary"`): Visual style.
- `Button.size` (`"xs" | "sm" | "md" | "lg" | "icon" | "icon-sm" | "icon-lg"`, default `"md"`): Height follows --cl-density.
- `Button.loading` (`boolean`, default `false`): Spinner, aria-busy, disabled; width is preserved.
- `Button.kbd` (`ReactNode`): Keyboard shortcut hint shown after the label.
- `Button.ping` (`boolean`, default `true (false for link)`): Ripple ring on press (GSAP, follows --cl-motion).
- `Button.asChild` (`boolean`, default `false`): Render the child element with button styles.

### Accessibility

- Native <button> semantics; icon-only buttons need an aria-label.
- Loading sets aria-busy and disables the button so double submits cannot happen.
- Focus is shown with a 2px outline offset from the button, visible on every variant.

## Button Group

Button Group joins buttons into a single control. Inner corners square off, borders merge, and the focused button rises above its neighbours so its focus ring is never clipped. Use it for split buttons, segmented toolbars and previous/next pairs.

Install: `npx shadcn@latest add https://ui.cuelark.com/r/button-group.json` · Docs: https://ui.cuelark.com/components/button-group

```tsx
import { ButtonGroup } from "@/components/ui/button-group";

<ButtonGroup>
  <Button variant="outline">Archive</Button>
  <Button variant="outline">Snooze</Button>
</ButtonGroup>
```

### Props

- `ButtonGroup.orientation` (`"horizontal" | "vertical"`, default `"horizontal"`): Direction.

### Accessibility

- role=group; add aria-label when the group's purpose is not obvious.

## Card

Cards group related content on one surface. Cuelark cards add optional print-style crop marks, raised, inset and ghost surfaces, a mono label slot, and a footer tray separated by a dashed rule. Titles can render as real headings for SEO.

Install: `npx shadcn@latest add https://ui.cuelark.com/r/card.json` · Docs: https://ui.cuelark.com/components/card

```tsx
import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@/components/ui/card";

<Card variant="raised" marks>
  <CardHeader>
    <CardTitle asChild><h3>Studio</h3></CardTitle>
    <CardDescription>For small teams.</CardDescription>
  </CardHeader>
  <CardContent>…</CardContent>
</Card>
```

### Props

- `Card.variant` (`"outline" | "raised" | "inset" | "ghost"`, default `"outline"`): Surface style.
- `Card.marks` (`boolean`, default `false`): Crop marks outside the corners (hidden globally with --cl-marks: 0).
- `Card.interactive` (`boolean`, default `false`): Hover lift and focus ring for clickable cards.
- `Card.spotlight` (`boolean`, default `false`): Accent glow that follows the pointer (GSAP quickTo).
- `CardTitle.asChild` (`boolean`, default `false`): Render your own heading element.
- `CardFooter.divided` (`boolean`, default `false`): Dashed rule and muted tray.

### Accessibility

- A card is a plain container; give titles a heading level that fits the page outline with asChild.
- Interactive cards show a focus ring when any link or button inside is focused.
- Crop marks are a decorative pseudo-element and are never announced.

## Chain of Thought

Chain of Thought lists an agent's steps on a vertical rail: completed steps tick, the active step shimmers, upcoming steps wait in dashes. Steps can carry detail such as search results or files touched.

Install: `npx shadcn@latest add https://ui.cuelark.com/r/chain-of-thought.json` · Docs: https://ui.cuelark.com/components/chain-of-thought

```tsx
import { ChainOfThought, ChainOfThoughtStep } from "@/components/ui/chain-of-thought";

<ChainOfThought>
  <ChainOfThoughtStep label="Searched docs" />
  <ChainOfThoughtStep status="active" label="Writing fix" />
</ChainOfThought>
```

### Props

- `ChainOfThought.title` (`ReactNode`, default `"Chain of thought"`): Header.
- `ChainOfThoughtStep.status` (`"complete" | "active" | "pending"`, default `"complete"`): Step state.
- `ChainOfThoughtStep.label` (`ReactNode`): Step text.

### Accessibility

- Fully keyboard operable with visible focus.
- Live regions announce streaming updates politely.

## Checkbox

Checkboxes toggle independent options. In Cuelark, the check mark draws itself in when ticked, the box sits in a recessed well until checked, and the indeterminate state makes select-all patterns straightforward.

Install: `npx shadcn@latest add https://ui.cuelark.com/r/checkbox.json` · Docs: https://ui.cuelark.com/components/checkbox

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

<label className="flex items-center gap-2">
  <Checkbox defaultChecked /> Email me updates
</label>
```

### Props

- `Checkbox.size` (`"sm" | "md" | "lg"`, default `"md"`): Box size.
- `Checkbox.checked` (`boolean | "indeterminate"`): Controlled state.

### Accessibility

- Uses role="checkbox" with aria-checked="mixed" for the indeterminate state.
- Wrap it in a <label> or point a label at it with htmlFor and id.
- Space toggles; inside a form it submits like a native checkbox.

## Checkpoint

Checkpoint marks a point you can rewind an agent's work to: a dashed rule with a small pill and a Restore action.

Install: `npx shadcn@latest add https://ui.cuelark.com/r/checkpoint.json` · Docs: https://ui.cuelark.com/components/checkpoint

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

<Checkpoint label="Before refactor" time="14:02" onRestore={restore} />
```

### Props

- `Checkpoint.label · time` (`ReactNode · string`): Text.
- `Checkpoint.onRestore` (`() => void`): Shows Restore.

### Accessibility

- Fully keyboard operable with visible focus.
- Live regions announce streaming updates politely.

## Code Block

Code Block renders code inside an agent's reply: filename and language, line numbers, highlighted lines in the signal color, a soft-wrap toggle and copy. It bundles no highlighter, so it stays light.

Install: `npx shadcn@latest add https://ui.cuelark.com/r/code-block.json` · Docs: https://ui.cuelark.com/components/code-block

```tsx
import { CodeBlock } from "@/components/ui/code-block";

<CodeBlock code={code} language="ts" filename="tax.ts" highlight={[2]} />
```

### Props

- `CodeBlock.code` (`string`): Source.
- `CodeBlock.language · filename` (`string`): Header.
- `CodeBlock.highlight` (`number[]`): Lines to mark.
- `CodeBlock.showLineNumbers` (`boolean`, default `true`): Gutter.

### Accessibility

- Fully keyboard operable with visible focus.
- Live regions announce streaming updates politely.

## Collapsible

Collapsible hides secondary content behind a trigger (extra files, advanced settings, long details) and animates to its real measured height, with the content fading as it opens.

Install: `npx shadcn@latest add https://ui.cuelark.com/r/collapsible.json` · Docs: https://ui.cuelark.com/components/collapsible

```tsx
import { Collapsible, CollapsibleContent, CollapsibleTrigger } from "@/components/ui/collapsible";

<Collapsible>
  <CollapsibleTrigger>Show more</CollapsibleTrigger>
  <CollapsibleContent>…</CollapsibleContent>
</Collapsible>
```

### Accessibility

- The trigger has aria-expanded and aria-controls.
- Height animation is skipped for reduced motion.

## Combobox

A combobox is a select you can type into: it filters long lists such as countries, users, frameworks. Cuelark's combobox pairs a popover with the command list, so results filter fuzzily and the highlight glides as you arrow through.

Install: `npx shadcn@latest add https://ui.cuelark.com/r/combobox.json` · Docs: https://ui.cuelark.com/components/combobox

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

<Combobox options={[{ value: "next", label: "Next.js" }]} placeholder="Framework" />
```

### Props

- `Combobox.options` (`{ value; label; keywords?; disabled? }[]`): The choices.
- `Combobox.value / defaultValue` (`string`): Controlled or initial value.
- `Combobox.onValueChange` (`(value: string) => void`): Called on select (empty string when cleared).
- `Combobox.placeholder · searchPlaceholder · emptyText` (`string`): Copy.

### Accessibility

- The trigger is role=combobox with aria-expanded.
- Typing filters; arrows move; Enter selects; Esc closes.

## Command

A command palette lets people jump anywhere and run any action from the keyboard. Cuelark's palette (built on cmdk) filters fuzzily, groups results under mono headings, shows shortcuts as keycaps, and its highlight glides between results as you arrow through.

Install: `npx shadcn@latest add https://ui.cuelark.com/r/command.json` · Docs: https://ui.cuelark.com/components/command

```tsx
import { CommandDialog, CommandInput, CommandItem, CommandList } from "@/components/ui/command";

<CommandDialog open={open} onOpenChange={setOpen}>
  <CommandInput placeholder="Search…" />
  <CommandList>
    <CommandItem>Profile</CommandItem>
  </CommandList>
</CommandDialog>
```

### Props

- `CommandDialog.title · description` (`string`): Screen-reader title and description.

### Accessibility

- The input controls a listbox; arrows move the active option.
- The dialog version has a screen-reader title.

## Compare Slider

Compare Slider overlays two layers and lets people drag a handle to reveal one over the other: before/after photos, image edits, light versus dark themes, old versus new designs. It clips with a hardware-accelerated clip-path, works with images, video or any component, follows arrow keys, and gives one gentle sweep on first view so people know it moves.

Install: `npx shadcn@latest add https://ui.cuelark.com/r/compare-slider.json` · Docs: https://ui.cuelark.com/components/compare-slider

```tsx
import { CompareSlider } from "@/components/ui/compare-slider";

<CompareSlider before={<img src="/before.jpg" alt="" />} after={<img src="/after.jpg" alt="" />} />
```

### Props

- `CompareSlider.before · after` (`ReactNode`): The two layers.
- `CompareSlider.beforeLabel · afterLabel` (`string`, default `"Before" · "After"`): Corner labels.
- `CompareSlider.defaultPosition` (`number`, default `50`): Start position (0–100).
- `CompareSlider.hover` (`boolean`, default `false`): Follow the pointer without dragging.

### Accessibility

- The handle is a slider (aria-valuenow) operated with arrow keys; Shift moves 10%.
- Give meaningful images alt text.

## Confirmation

Confirmation is the permission prompt for agent actions: sending email, spending money, running commands. The exact action is shown verbatim, high-risk actions must be held to approve so they can't be clicked through by reflex, and the decision collapses to a one-line receipt.

Install: `npx shadcn@latest add https://ui.cuelark.com/r/confirmation.json` · Docs: https://ui.cuelark.com/components/confirmation

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

<Confirmation risk="high" title="Delete 214 rows" command={sql} onApprove={run} />
```

### Props

- `Confirmation.title · description` (`ReactNode`): What and why.
- `Confirmation.command` (`string`): Shown verbatim.
- `Confirmation.risk` (`"low" | "high"`, default `"low"`): High requires hold.
- `Confirmation.onApprove · onDeny` (`() => void`): Decision callbacks.

### Accessibility

- Fully keyboard operable with visible focus.
- Live regions announce streaming updates politely.

## Context Menu

Context Menu opens actions where the user right-clicks or long-presses: canvases, file lists, table rows. It springs out from the pointer, shows shortcuts as keycaps and supports submenus and checkable items.

Install: `npx shadcn@latest add https://ui.cuelark.com/r/context-menu.json` · Docs: https://ui.cuelark.com/components/context-menu

```tsx
import { ContextMenu, ContextMenuContent, ContextMenuItem, ContextMenuTrigger } from "@/components/ui/context-menu";

<ContextMenu>
  <ContextMenuTrigger>Right-click</ContextMenuTrigger>
  <ContextMenuContent>
    <ContextMenuItem>Duplicate</ContextMenuItem>
  </ContextMenuContent>
</ContextMenu>
```

### Props

- `ContextMenuItem.variant` (`"default" | "destructive"`, default `"default"`): Destructive items are red.

### Accessibility

- Opens with the context-menu key and Shift+F10, not only right-click.
- Full menu keyboard support; Esc returns focus.

## Context Meter

Context Meter shows how much of the model's context window a conversation uses, as a ring that warms from ink to amber to red. Hover for the token breakdown and cost.

Install: `npx shadcn@latest add https://ui.cuelark.com/r/context-meter.json` · Docs: https://ui.cuelark.com/components/context-meter

```tsx
import { ContextMeter } from "@/components/ui/context-meter";

<ContextMeter used={84000} max={200000} cost={0.42} />
```

### Props

- `ContextMeter.used · max` (`number`): Tokens.
- `ContextMeter.breakdown` (`{ input?; output?; cached?; reasoning? }`): Hover detail.
- `ContextMeter.cost` (`number`): Dollars.

### Accessibility

- Fully keyboard operable with visible focus.
- Live regions announce streaming updates politely.

## Conversation

Conversation is the scroll container for AI chat. It follows the newest message while a reply streams, stops following the moment you scroll up to read, and offers a "Latest" pill to jump back. Edges fade so text never cuts off hard.

Install: `npx shadcn@latest add https://ui.cuelark.com/r/conversation.json` · Docs: https://ui.cuelark.com/components/conversation

```tsx
import { Conversation, ConversationContent } from "@/components/ui/conversation";

<Conversation className="h-[60vh]">
  <ConversationContent>{messages}</ConversationContent>
</Conversation>
```

### Accessibility

- role=log with polite announcements.
- The Latest pill is skipped by Tab while hidden.

## Cookie Consent

Cookie Consent is a banner that respects people: Accept all and Reject all carry equal weight, Customize expands per-category switches in place, the choice is remembered, and the page is never blocked. It slides up once, after the page has settled.

Install: `npx shadcn@latest add https://ui.cuelark.com/r/cookie-consent.json` · Docs: https://ui.cuelark.com/components/cookie-consent

```tsx
import { CookieConsent } from "@/components/ui/cookie-consent";

<CookieConsent onConsent={(c) => c.analytics && loadAnalytics()} />
```

### Props

- `CookieConsent.categories` (`{ id; label; description; required? }[]`, default `necessary, analytics, marketing`): Consent groups.
- `CookieConsent.onConsent` (`(consent: Record<string, boolean>) => void`): The choice.
- `CookieConsent.storageKey` (`string`, default `"cookie-consent"`): localStorage key.
- `CookieConsent.persist` (`boolean`, default `true`): Remember the choice.
- `CookieConsent.inline` (`boolean`, default `false`): Render in place.

### Accessibility

- A labelled region, not a modal: it never traps focus or blocks reading.
- Reject is as easy as Accept, as GDPR guidance expects.

## Copy Button

Copy Button copies text to the clipboard (install commands, API keys, links). The copy icon twists into a check, an optional label reads "Copied", and the result is announced to screen readers.

Install: `npx shadcn@latest add https://ui.cuelark.com/r/copy-button.json` · Docs: https://ui.cuelark.com/components/copy-button

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

<CopyButton value="npx shadcn@latest add …" />
```

### Props

- `CopyButton.value` (`string`): Text to copy.
- `CopyButton.label` (`string`): Visible label.
- `CopyButton.timeout` (`number`, default `1600`): ms the check stays.
- `CopyButton.onCopied` (`(value: string) => void`): Callback.

### Accessibility

- Icon-only buttons have an aria-label that changes to "Copied".
- A polite live region announces success.

## Countdown

Countdown counts down to a launch, sale or event in day, hour, minute and second tiles; each digit flips down as it changes. The remaining time is also rendered in a <time> element, so crawlers and screen readers get a real date rather than a stream of numbers.

Install: `npx shadcn@latest add https://ui.cuelark.com/r/countdown.json` · Docs: https://ui.cuelark.com/components/countdown

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

<Countdown to="2026-12-01T17:00:00Z" onComplete={openSale} />
```

### Props

- `Countdown.to` (`Date | string | number`): Target moment.
- `Countdown.units` (`("days" | "hours" | "minutes" | "seconds")[]`, default `all four`): Units to show.
- `Countdown.onComplete` (`() => void`): Fires once at zero.
- `Countdown.labels` (`boolean`, default `true`): Unit labels.

### Accessibility

- role=timer with a readable sentence; the visual tiles are aria-hidden so seconds are not announced every tick.

## Dialog

A dialog interrupts the page for a focused task. Cuelark dialogs open with a short, eased rise, frame the panel in crop marks, show an Esc hint next to the close button, and can put actions in a footer tray under a dashed rule.

Install: `npx shadcn@latest add https://ui.cuelark.com/r/dialog.json` · Docs: https://ui.cuelark.com/components/dialog

```tsx
import { Dialog, DialogContent, DialogDescription, DialogHeader, DialogTitle, DialogTrigger } from "@/components/ui/dialog";

<Dialog>
  <DialogTrigger asChild><Button>Open</Button></DialogTrigger>
  <DialogContent>
    <DialogHeader>
      <DialogTitle>Edit profile</DialogTitle>
      <DialogDescription>Visible to your team.</DialogDescription>
    </DialogHeader>
  </DialogContent>
</Dialog>
```

### Props

- `DialogContent.size` (`"sm" | "md" | "lg" | "xl"`, default `"md"`): Maximum width.
- `DialogContent.marks` (`boolean`, default `true`): Crop marks around the panel.
- `DialogContent.showClose` (`boolean`, default `true`): Close button with the Esc hint.
- `DialogFooter.divided` (`boolean`, default `false`): Dashed rule and muted tray.

### Accessibility

- Focus moves into the dialog on open, is trapped while open, and returns to the trigger on close.
- DialogTitle and DialogDescription are wired to aria-labelledby and aria-describedby.
- Esc and a click on the overlay close it; the page behind is inert to screen readers.

## Dock

A dock is an app-style launcher whose icons swell as the pointer approaches and neighbours make room, like the macOS Dock. Labels appear on hover and focus, active items get a dot, and keyboard focus lifts items too.

Install: `npx shadcn@latest add https://ui.cuelark.com/r/dock.json` · Docs: https://ui.cuelark.com/components/dock

```tsx
import { Dock, DockItem } from "@/components/ui/dock";

<Dock>
  <DockItem label="Home"><HomeIcon /></DockItem>
</Dock>
```

### Props

- `Dock.size` (`number`, default `40`): Resting item size (px).
- `Dock.magnification` (`number`, default `1.6`): Peak size multiplier.
- `Dock.distance` (`number`, default `120`): Falloff radius (px).
- `DockItem.label` (`string`): Tooltip and accessible name.
- `DockItem.active` (`boolean`): Shows the active dot.
- `DockItem.asChild` (`boolean`): Render a link.

### Accessibility

- A <nav> of buttons, each with an accessible name.
- With motion off it is a plain toolbar.

## Dot Field

Dot Field is a canvas dot grid for hero and section backgrounds. Dots near the pointer swell and light up in the signal color, and a click sends a ripple across the field. It reads your theme tokens, stays sharp on retina screens and pauses when off screen.

Install: `npx shadcn@latest add https://ui.cuelark.com/r/dot-field.json` · Docs: https://ui.cuelark.com/components/dot-field

```tsx
import { DotField } from "@/components/ui/dot-field";

<DotField className="h-96">…hero content…</DotField>
```

### Props

- `DotField.gap` (`number`, default `22`): Grid spacing (px).
- `DotField.radius` (`number`, default `120`): Pointer influence radius.
- `DotField.ripple` (`boolean`, default `true`): Click ripples.

### Accessibility

- The canvas is aria-hidden; children render normally above it.
- With reduced motion or --cl-motion: 0 the effect stays still and the content remains fully usable.

## Draw Path

Draw Path animates the strokes of any inline SVG as though drawn by hand (GSAP DrawSVGPlugin), on mount, on scroll into view, or scrubbed with the scroll position. Use it for signatures, hand-drawn underlines, diagrams and line icons.

Install: `npx shadcn@latest add https://ui.cuelark.com/r/draw-path.json` · Docs: https://ui.cuelark.com/components/draw-path

```tsx
import { DrawPath } from "@/components/ui/draw-path";

<DrawPath viewBox="0 0 100 20"><path d="M0 10 Q 50 0 100 10" /></DrawPath>
```

### Props

- `DrawPath.trigger` (`"mount" | "inView" | "scroll"`, default `"inView"`): When to draw.
- `DrawPath.duration` (`number`, default `1.4`): Seconds.

### Accessibility

- Add a <title> to meaningful SVGs.
- With reduced motion or --cl-motion: 0 the effect stays still and the content remains fully usable.

## Dropdown Menu

A dropdown menu lists actions behind a trigger: account menus, row actions, overflow menus. Cuelark menus spring from their trigger, show shortcuts as keycaps, use dashed separators and mono group labels, and support submenus, checkbox and radio items.

Install: `npx shadcn@latest add https://ui.cuelark.com/r/dropdown-menu.json` · Docs: https://ui.cuelark.com/components/dropdown-menu

```tsx
import { DropdownMenu, DropdownMenuContent, DropdownMenuItem, DropdownMenuTrigger } from "@/components/ui/dropdown-menu";

<DropdownMenu>
  <DropdownMenuTrigger asChild><Button>Open</Button></DropdownMenuTrigger>
  <DropdownMenuContent>
    <DropdownMenuItem>Profile</DropdownMenuItem>
  </DropdownMenuContent>
</DropdownMenu>
```

### Props

- `DropdownMenuItem.variant` (`"default" | "destructive"`, default `"default"`): Destructive items are red.
- `DropdownMenuItem.inset` (`boolean`): Indent to align with checkable items.

### Accessibility

- Full WAI-ARIA menu pattern with typeahead.
- Arrow keys navigate, Right opens submenus, Esc closes and returns focus.

## Empty

Empty states turn "nothing here" into a next step. The layout centres a crop-marked icon tile, a heading, one sentence of guidance and the primary action.

Install: `npx shadcn@latest add https://ui.cuelark.com/r/empty.json` · Docs: https://ui.cuelark.com/components/empty

```tsx
import { Empty, EmptyActions, EmptyDescription, EmptyIcon, EmptyTitle } from "@/components/ui/empty";

<Empty>
  <EmptyIcon><InboxIcon /></EmptyIcon>
  <EmptyTitle>No messages</EmptyTitle>
  <EmptyDescription>Connect a channel to start.</EmptyDescription>
</Empty>
```

### Accessibility

- EmptyTitle is a heading, so the state appears in the page outline.
- The icon is decorative.

## Field

Field wires a label, any control, a description and an error message together with generated ids, aria-describedby and aria-invalid, so every form field is accessible without hand-written attributes.

Install: `npx shadcn@latest add https://ui.cuelark.com/r/field.json` · Docs: https://ui.cuelark.com/components/field

```tsx
import { Field, FieldControl, FieldDescription, FieldError, FieldLabel } from "@/components/ui/field";

<Field invalid={!!error}>
  <FieldLabel>Email</FieldLabel>
  <FieldControl><Input /></FieldControl>
  <FieldDescription>We never share it.</FieldDescription>
  <FieldError>{error}</FieldError>
</Field>
```

### Props

- `Field.invalid` (`boolean`, default `false`): Shows the error and sets aria-invalid.
- `Field.orientation` (`"vertical" | "horizontal"`, default `"vertical"`): Layout.

### Accessibility

- The error uses role=alert and is linked via aria-describedby.

## File Diff

File Diff shows a code change an agent proposes: added and removed lines with old and new line numbers, +/− stats, long unchanged runs folded away, and Accept/Reject. The header records the decision afterwards.

Install: `npx shadcn@latest add https://ui.cuelark.com/r/file-diff.json` · Docs: https://ui.cuelark.com/components/file-diff

```tsx
import { FileDiff } from "@/components/ui/file-diff";

<FileDiff filename="src/tax.ts" lines={diff} onAccept={apply} />
```

### Props

- `FileDiff.filename` (`string`): Path shown.
- `FileDiff.lines` (`{ type: "add" | "remove" | "context"; content }[]`): The diff.
- `FileDiff.onAccept · onReject` (`() => void`): Decision.
- `FileDiff.foldAfter` (`number`, default `6`): Fold long unchanged runs.

### Accessibility

- Fully keyboard operable with visible focus.
- Live regions announce streaming updates politely.

## File Dropzone

File Dropzone is a drag-and-drop upload area that also works by click and keyboard. While a file is dragged over, crop marks lock onto the zone and the icon lifts; dropped files list in with a stagger, oversized files get a clear message, and any file can be removed before upload.

Install: `npx shadcn@latest add https://ui.cuelark.com/r/file-dropzone.json` · Docs: https://ui.cuelark.com/components/file-dropzone

```tsx
import { FileDropzone } from "@/components/ui/file-dropzone";

<FileDropzone accept="image/*" maxSize={5_000_000} onFilesChange={setFiles} />
```

### Props

- `FileDropzone.onFilesChange` (`(files: File[]) => void`): Accepted files.
- `FileDropzone.accept` (`string`): Native accept filter.
- `FileDropzone.multiple` (`boolean`, default `true`): Allow several files.
- `FileDropzone.maxSize` (`number`): Max bytes per file.
- `FileDropzone.hint` (`ReactNode`): Helper text.

### Accessibility

- The zone is a button: Enter or Space opens the file browser.
- Rejections are announced with role=alert.

## File Tree

File Tree shows a project's files the way an agent sees them: folders that expand, changed files marked A, M or D in color, and a selected file for the diff or editor beside it.

Install: `npx shadcn@latest add https://ui.cuelark.com/r/file-tree.json` · Docs: https://ui.cuelark.com/components/file-tree

```tsx
import { FileTree } from "@/components/ui/file-tree";

<FileTree tree={tree} selected={path} onSelect={setPath} />
```

### Props

- `FileTree.tree` (`{ name; children?; status? }[]`): Nodes.
- `FileTree.selected · onSelect` (`string`): Selected file path.
- `FileTree.defaultExpanded` (`string[]`): Open folders.

### Accessibility

- Fully keyboard operable with visible focus.
- Live regions announce streaming updates politely.

## Flip Grid

Flip Grid animates layout changes with GSAP Flip: filter, sort or reflow the grid and every item glides from where it was to where it lands. New items scale in and removed ones fade out. Changing one key is all it takes.

Install: `npx shadcn@latest add https://ui.cuelark.com/r/flip-grid.json` · Docs: https://ui.cuelark.com/components/flip-grid

```tsx
import { FlipGrid, FlipGridItem } from "@/components/ui/flip-grid";

<FlipGrid layoutKey={filter} className="grid-cols-4">
  {items.map((i) => (
    <FlipGridItem key={i.id} id={i.id} hidden={!matches(i)}>…</FlipGridItem>
  ))}
</FlipGrid>
```

### Props

- `FlipGrid.layoutKey` (`string | number`): Change it to animate the next layout.

### Accessibility

- Children keep their semantics and DOM order.
- With reduced motion or --cl-motion: 0 the effect stays still and the content remains fully usable.

## Gradient Text

Gradient Text gives words a living highlight. In drift mode a soft glint of the signal color slides through the text on a loop; in spotlight mode the color sits under your pointer, as if you were lighting the line with a torch. The base color is always your foreground, so it reads on any theme, and the text stays real: selectable, translatable and indexed.

Install: `npx shadcn@latest add https://ui.cuelark.com/r/gradient-text.json` · Docs: https://ui.cuelark.com/components/gradient-text

```tsx
import { GradientText } from "@/components/ui/gradient-text";

Interfaces with a <GradientText>signal</GradientText>.
<GradientText variant="spotlight">Hover me</GradientText>
```

### Props

- `GradientText.variant` (`"drift" | "spotlight"`, default `"drift"`): Looping shimmer, or a highlight that follows the pointer.
- `GradientText.color` (`string`, default `signal, deepened`): Highlight color.
- `GradientText.duration` (`number`, default `3.2`): Seconds per drift sweep.
- `GradientText.asChild` (`boolean`, default `false`): Use your own element.

### Accessibility

- The resting color is the foreground, so contrast never depends on the animation.
- With reduced motion or --cl-motion: 0 the effect stays still and the content remains fully usable.

## Hold to Confirm

Hold to Confirm replaces the "Are you sure?" dialog for destructive actions: press and hold, a fill sweeps across the button, and the action fires only when it completes. Release early and it snaps back. It prevents accidental deletes without an extra click or modal, and works from the keyboard by holding Space or Enter.

Install: `npx shadcn@latest add https://ui.cuelark.com/r/hold-to-confirm.json` · Docs: https://ui.cuelark.com/components/hold-to-confirm

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

<HoldToConfirm onConfirm={deleteWorkspace}>Delete workspace</HoldToConfirm>
```

### Props

- `HoldToConfirm.onConfirm` (`() => void`): Fires when the hold completes.
- `HoldToConfirm.duration` (`number`, default `1400`): Hold time in ms.
- `HoldToConfirm.holdingLabel` (`ReactNode`, default `"Keep holding…"`): Label while holding.
- `HoldToConfirm.variant` (`"destructive" | "primary"`, default `"destructive"`): Fill color.

### Accessibility

- Holding Space or Enter confirms from the keyboard.
- The accessible name says "press and hold" so the interaction is discoverable.

## Hover Card

A hover card previews what is behind a link (a profile, a repository, a page) when sighted mouse users hover it. It opens after a short delay and springs from the link.

Install: `npx shadcn@latest add https://ui.cuelark.com/r/hover-card.json` · Docs: https://ui.cuelark.com/components/hover-card

```tsx
import { HoverCard, HoverCardContent, HoverCardTrigger } from "@/components/ui/hover-card";

<HoverCard>
  <HoverCardTrigger asChild><a href="#profile">@ada</a></HoverCardTrigger>
  <HoverCardContent>…</HoverCardContent>
</HoverCard>
```

### Props

- `HoverCard.openDelay` (`number`, default `250`): ms before opening.
- `HoverCard.closeDelay` (`number`, default `150`): ms before closing.

### Accessibility

- Hover cards are ignored by screen readers and keyboard-only users; never hide essential content in them.
- The trigger should be a normal link that works on its own.

## Inline Citation

Inline Citation puts a small numbered chip right after the claim it supports. Hover or focus previews the source (title, domain and the quoted passage); click opens it.

Install: `npx shadcn@latest add https://ui.cuelark.com/r/inline-citation.json` · Docs: https://ui.cuelark.com/components/inline-citation

```tsx
import { InlineCitation } from "@/components/ui/inline-citation";

Claim<InlineCitation index={1} source={{ title, url, excerpt }} />.
```

### Props

- `InlineCitation.index` (`number`): Number shown.
- `InlineCitation.source` (`{ title; url; excerpt? }`): The source.

### Accessibility

- Fully keyboard operable with visible focus.
- Live regions announce streaming updates politely.

## Input

Inputs collect short text. Cuelark inputs sit in a slightly recessed well that contrasts with raised buttons, take leading and trailing add-ons (icons, prefixes, units, keyboard hints) without extra wrappers, and show a soft focus halo and a clear invalid state.

Install: `npx shadcn@latest add https://ui.cuelark.com/r/input.json` · Docs: https://ui.cuelark.com/components/input

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

<Input placeholder="Search" leading={<SearchIcon />} trailing={<kbd className="cue-kbd">/</kbd>} />
```

### Props

- `Input.size` (`"sm" | "md" | "lg"`, default `"md"`): Height follows --cl-density.
- `Input.leading` (`ReactNode`): Content before the text; wraps the input in a field group.
- `Input.trailing` (`ReactNode`): Content after the text.
- `Input.aria-invalid` (`boolean`): Shows the destructive border and halo.

### Accessibility

- Always pair it with a <label> or aria-label; placeholders are not labels.
- Set aria-invalid and link the error text with aria-describedby.
- Add-ons are outside the input, so screen readers read only the value.

## Input OTP

An OTP input collects verification codes (2FA, email or SMS codes). It is one real input underneath, so paste, autofill from SMS and password managers all work, and each digit springs into its slot as it arrives.

Install: `npx shadcn@latest add https://ui.cuelark.com/r/input-otp.json` · Docs: https://ui.cuelark.com/components/input-otp

```tsx
import { InputOTP, InputOTPGroup, InputOTPSlot } from "@/components/ui/input-otp";

<InputOTP maxLength={6}>
  <InputOTPGroup>
    {[0, 1, 2, 3, 4, 5].map((i) => <InputOTPSlot key={i} index={i} />)}
  </InputOTPGroup>
</InputOTP>
```

### Props

- `InputOTP.containerClassName` (`string`): Classes for the slot container.
- `InputOTPSlot.index` (`number`): Which character this slot shows.

### Accessibility

- A single native input carries the value, so autocomplete="one-time-code" works.
- Give it an aria-label such as "Verification code".

## Item

Item is the row behind settings pages, lists and search results: a media slot, a title and description that truncate cleanly, and an actions slot. As a link it gets a hover surface.

Install: `npx shadcn@latest add https://ui.cuelark.com/r/item.json` · Docs: https://ui.cuelark.com/components/item

```tsx
import { Item, ItemActions, ItemContent, ItemDescription, ItemMedia, ItemTitle } from "@/components/ui/item";

<Item variant="outline">
  <ItemMedia><BellIcon /></ItemMedia>
  <ItemContent><ItemTitle>Notifications</ItemTitle></ItemContent>
  <ItemActions><Switch /></ItemActions>
</Item>
```

### Props

- `Item.variant` (`"default" | "outline" | "muted"`, default `"default"`): Surface.
- `Item.size` (`"sm" | "md"`, default `"md"`): Padding.
- `Item.asChild` (`boolean`): Render a link.

### Accessibility

- As a link, the whole row is one focusable target with a visible ring.

## Kbd

Kbd renders keyboard keys in docs and hints. It shares the theme's cue-kbd style with the shortcut hints in buttons, menus and tooltips, so shortcuts look the same everywhere.

Install: `npx shadcn@latest add https://ui.cuelark.com/r/kbd.json` · Docs: https://ui.cuelark.com/components/kbd

```tsx
import { Kbd, KbdGroup } from "@/components/ui/kbd";

<KbdGroup keys={["⌘", "K"]} />
```

### Props

- `KbdGroup.keys` (`string[]`): Keys in order.
- `KbdGroup.separator` (`ReactNode`): Between keys, e.g. "+".

### Accessibility

- Uses semantic <kbd>, nested for combinations as the HTML spec describes.

## Label

Labels name form controls so everyone, including screen-reader users, knows what to type. Cuelark labels add a required asterisk that is announced as "required", or a quiet mono "optional" tag for forms where most fields are required.

Install: `npx shadcn@latest add https://ui.cuelark.com/r/label.json` · Docs: https://ui.cuelark.com/components/label

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

<Label htmlFor="email" required>Email</Label>
<Input id="email" required />
```

### Props

- `Label.required` (`boolean`, default `false`): Asterisk announced as "required".
- `Label.optional` (`boolean`, default `false`): Mono "optional" tag.

### Accessibility

- Clicking the label focuses its control (htmlFor).
- The asterisk is aria-hidden; screen readers hear "required" instead.

## Magnetic

Magnetic makes a button or icon lean toward the pointer as it approaches and spring back elastically when it leaves. It suits a primary call to action on a landing page.

Install: `npx shadcn@latest add https://ui.cuelark.com/r/magnetic.json` · Docs: https://ui.cuelark.com/components/magnetic

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

<Magnetic><Button>Get started</Button></Magnetic>
```

### Props

- `Magnetic.strength` (`number`, default `0.35`): How far it follows (0–1).
- `Magnetic.reach` (`number`, default `24`): Extra px where the pull starts.

### Accessibility

- Purely visual; the child keeps its semantics and focus.
- Disabled with reduced motion.

## Marquee

Marquee loops content endlessly: logo walls, testimonials, tickers. GSAP drives a single track with two copies for a seamless loop, and hover eases it to a stop instead of freezing. With motion off it becomes a scrollable row.

Install: `npx shadcn@latest add https://ui.cuelark.com/r/marquee.json` · Docs: https://ui.cuelark.com/components/marquee

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

<Marquee speed={40}>{logos}</Marquee>
```

### Props

- `Marquee.speed` (`number`, default `40`): Pixels per second.
- `Marquee.reverse` (`boolean`, default `false`): Direction.
- `Marquee.pauseOnHover` (`boolean`, default `true`): Ease to a stop on hover.
- `Marquee.fade` (`boolean`, default `true`): Fade the edges.
- `Marquee.gap` (`string`, default `"2.5rem"`): Gap between items.

### Accessibility

- The duplicate copy is aria-hidden.
- Reduced motion stops the loop and allows manual scrolling.

## Message

Message renders one turn of an AI conversation. User turns sit in a compact bubble; assistant turns read as a full-width document with an avatar and quiet actions (copy, regenerate, rate) that appear on hover and are always visible on touch.

Install: `npx shadcn@latest add https://ui.cuelark.com/r/message.json` · Docs: https://ui.cuelark.com/components/message

```tsx
import { Message, MessageContent } from "@/components/ui/message";

<Message from="assistant">
  <MessageContent>…</MessageContent>
</Message>
```

### Props

- `Message.from` (`"user" | "assistant"`, default `"assistant"`): Side and style.
- `MessageAction.label` (`string`): Tooltip and accessible name.

### Accessibility

- Fully keyboard operable with visible focus.
- Live regions announce streaming updates politely.

## Model Selector

Model Selector picks the model for the next message: a compact pill for the composer toolbar, and a searchable list grouped by provider showing each model's context window and capabilities.

Install: `npx shadcn@latest add https://ui.cuelark.com/r/model-selector.json` · Docs: https://ui.cuelark.com/components/model-selector

```tsx
import { ModelSelector } from "@/components/ui/model-selector";

<ModelSelector models={models} value={model} onValueChange={setModel} />
```

### Props

- `ModelSelector.models` (`{ id; name; provider; context?; tags? }[]`): Choices.
- `ModelSelector.value / defaultValue · onValueChange` (`string`): Selection.

### Accessibility

- Fully keyboard operable with visible focus.
- Live regions announce streaming updates politely.

## Native Select

Native Select styles the browser's own select: people get the platform picker on mobile, autofill and form submission work for free, and it ships no JavaScript. It suits long forms and mobile-heavy pages.

Install: `npx shadcn@latest add https://ui.cuelark.com/r/native-select.json` · Docs: https://ui.cuelark.com/components/native-select

```tsx
import { NativeSelect } from "@/components/ui/native-select";

<NativeSelect name="country">
  <option value="in">India</option>
</NativeSelect>
```

### Props

- `NativeSelect.size` (`"sm" | "md" | "lg"`, default `"md"`): Height.

### Accessibility

- Native semantics, keyboard and screen-reader support.

## Number Field

A number field edits quantities: seats, prices, sizes. Cuelark's stepper repeats and accelerates while you hold −/+, supports arrow keys, Page Up/Down and Home/End, formats with Intl (currency, percent, units), and slides the value in from the direction it moved.

Install: `npx shadcn@latest add https://ui.cuelark.com/r/number-field.json` · Docs: https://ui.cuelark.com/components/number-field

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

<NumberField defaultValue={1} min={0} max={10} />
```

### Props

- `NumberField.value / defaultValue` (`number`, default `0`): Controlled or initial value.
- `NumberField.onValueChange` (`(value: number) => void`): Called with the clamped value.
- `NumberField.min · max · step` (`number`, default `-∞ · ∞ · 1`): Bounds and increment.
- `NumberField.formatOptions` (`Intl.NumberFormatOptions`): Display formatting.
- `NumberField.size` (`"sm" | "md" | "lg"`, default `"md"`): Height.

### Accessibility

- role=spinbutton with aria-valuenow, -min and -max.
- Steppers are skipped by Tab; the keyboard does everything from the input.

## Number Ticker

Number Ticker is an animated counter in the style of a mechanical odometer: each digit is a column that rolls to its value, with columns further right spinning further. It formats with Intl (currency, compact, percent), rolls from the old value when the number changes, and gives screen readers and crawlers the plain formatted number.

Install: `npx shadcn@latest add https://ui.cuelark.com/r/number-ticker.json` · Docs: https://ui.cuelark.com/components/number-ticker

```tsx
import { NumberTicker } from "@/components/ui/number-ticker";

<NumberTicker value={128450} format={{ style: "currency", currency: "USD" }} />
```

### Props

- `NumberTicker.value` (`number`): The number.
- `NumberTicker.format` (`Intl.NumberFormatOptions`): Formatting.
- `NumberTicker.locale` (`string`): Locale (defaults to the user's).
- `NumberTicker.trigger` (`"mount" | "inView"`, default `"inView"`): First roll.
- `NumberTicker.duration` (`number`, default `1.2`): Seconds.

### Accessibility

- The formatted number is in a sr-only span; the columns are aria-hidden.
- Shows the final value instantly with reduced motion.

## Orbit

Orbit spaces its children evenly on a ring that turns around a center while the items stay upright: integrations, partner logos, team avatars. Stack two Orbits for inner and outer rings; hover slows the system down.

Install: `npx shadcn@latest add https://ui.cuelark.com/r/orbit.json` · Docs: https://ui.cuelark.com/components/orbit

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

<div className="relative h-80">
  <Orbit radius={120}>{icons}</Orbit>
</div>
```

### Props

- `Orbit.radius` (`number`, default `110`): Ring radius (px).
- `Orbit.duration` (`number`, default `24`): Seconds per revolution.
- `Orbit.reverse` (`boolean`, default `false`): Counter-clockwise.
- `Orbit.path` (`boolean`, default `true`): Dashed track.

### Accessibility

- Give icon items accessible names if they convey meaning.
- With reduced motion or --cl-motion: 0 the effect stays still and the content remains fully usable.

## Pagination

Pagination splits long lists into pages. Cuelark pagination uses real links so every page is crawlable, highlights the current page as a raised key, and ships pageRange(), which works out the visible pages and ellipses for you.

Install: `npx shadcn@latest add https://ui.cuelark.com/r/pagination.json` · Docs: https://ui.cuelark.com/components/pagination

```tsx
import { Pagination, PaginationContent, PaginationItem, PaginationLink, pageRange } from "@/components/ui/pagination";

{pageRange(page, total).map((p) => (
  <PaginationItem key={p}><PaginationLink href={`?page=${p}`} isActive={p === page}>{p}</PaginationLink></PaginationItem>
))}
```

### Props

- `PaginationLink.isActive` (`boolean`): Marks the current page (aria-current).
- `PaginationLink.asChild` (`boolean`): Use your router's Link.

### Accessibility

- <nav aria-label="Pagination"> with a list of links.
- Previous and Next have explicit aria-labels.

## Password Input

Password Input is a sign-up password field with a show/hide toggle and a live strength meter. Segments fill as rules pass, each rule in the checklist ticks off with a small pop, and the strength level is announced politely, so people know what is missing before they submit.

Install: `npx shadcn@latest add https://ui.cuelark.com/r/password-input.json` · Docs: https://ui.cuelark.com/components/password-input

```tsx
import { PasswordInput } from "@/components/ui/password-input";

<PasswordInput name="password" placeholder="At least 8 characters" />
```

### Props

- `PasswordInput.strength` (`boolean`, default `true`): Show meter and checklist.
- `PasswordInput.rules` (`{ label; test }[]`, default `length, number, case, symbol`): Your own rules.

### Accessibility

- The toggle is a pressed-state button with a clear label.
- Rule states are announced; autocomplete="new-password" helps password managers.

## Plan

Plan presents the steps an agent intends to take and waits for your go-ahead. Crop marks lock onto it as it arrives, long plans fold after a few steps, ⌘Enter runs and Esc rejects, and an optional countdown ring auto-runs unless you cancel it.

Install: `npx shadcn@latest add https://ui.cuelark.com/r/plan.json` · Docs: https://ui.cuelark.com/components/plan

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

<Plan steps={steps} onApprove={run} onReject={cancel} autoRun={10} />
```

### Props

- `Plan.steps` (`{ label; done? }[]`): The plan.
- `Plan.onApprove · onReject` (`() => void`): Decision callbacks.
- `Plan.autoRun` (`number`): Seconds before auto-approve.
- `Plan.visible` (`number`, default `4`): Steps before folding.
- `Plan.shortcuts` (`boolean`, default `true`): ⌘Enter / Esc while pending.

### Accessibility

- The countdown can be cancelled by keyboard and announces the remaining time.
- Shortcuts only bind while the plan is pending.

## Popover

A popover shows rich, interactive content anchored to a trigger, such as settings, pickers and small forms. It springs out of its anchor side, and with marks its crop marks close in as it opens.

Install: `npx shadcn@latest add https://ui.cuelark.com/r/popover.json` · Docs: https://ui.cuelark.com/components/popover

```tsx
import { Popover, PopoverContent, PopoverTrigger } from "@/components/ui/popover";

<Popover>
  <PopoverTrigger asChild><Button>Open</Button></PopoverTrigger>
  <PopoverContent marks>…</PopoverContent>
</Popover>
```

### Props

- `PopoverContent.marks` (`boolean`, default `false`): Crop marks around the panel.

### Accessibility

- Focus moves into the popover and returns to the trigger on close.
- Esc and outside clicks close it.

## Progress

Progress bars show how far along a task is: uploads, quotas, onboarding. Cuelark eases the fill to each new value with GSAP, offers a segmented style whose cells light up in a cascade, and an indeterminate state for unknown durations.

Install: `npx shadcn@latest add https://ui.cuelark.com/r/progress.json` · Docs: https://ui.cuelark.com/components/progress

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

<Progress value={64} aria-label="Upload" />
```

### Props

- `Progress.value` (`number | null`, default `0`): 0–max, or null for indeterminate.
- `Progress.segments` (`number`): Split into cells.
- `Progress.size` (`"sm" | "md" | "lg"`, default `"md"`): Bar thickness.

### Accessibility

- role=progressbar with aria-valuenow; give it an aria-label.
- Indeterminate bars omit aria-valuenow.

## Prompt Input

Prompt Input is the message composer for AI chat and agents. It grows with the text, sends on Enter (Shift+Enter for a new line), attaches files by button, paste or drop, hosts a model picker and context meter in its toolbar, and turns Send into Stop (Esc) while the agent works. A signal line sweeps its top edge on send.

Install: `npx shadcn@latest add https://ui.cuelark.com/r/prompt-input.json` · Docs: https://ui.cuelark.com/components/prompt-input

```tsx
import { PromptInput } from "@/components/ui/prompt-input";

<PromptInput status={status} onSubmit={({ text, files }) => send(text, files)} onStop={stop} />
```

### Props

- `PromptInput.onSubmit` (`({ text, files }) => void`): Called on send.
- `PromptInput.status` (`"idle" | "streaming"`, default `"idle"`): Streaming swaps Send for Stop.
- `PromptInput.onStop` (`() => void`): Stop button and Esc.
- `PromptInput.toolbar` (`ReactNode`): Extra controls.
- `PromptInput.attachments` (`boolean`, default `true`): Files by button, paste, drop.

### Accessibility

- Enter sends, Shift+Enter adds a line, IME composition is respected.
- Esc stops a running generation.

## Queue

Queue holds follow-ups you send while the agent is still working. They wait above the composer in order; reorder with Alt+↑/↓, remove with ×, and the agent takes them one at a time.

Install: `npx shadcn@latest add https://ui.cuelark.com/r/queue.json` · Docs: https://ui.cuelark.com/components/queue

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

<Queue items={queued} onItemsChange={setQueued} />
```

### Props

- `Queue.items · onItemsChange` (`{ id; text }[]`): The queue.
- `Queue.label` (`ReactNode`, default `"Queued"`): Header.

### Accessibility

- Each item is focusable: Alt+↑/↓ reorders, Delete removes.

## Radio Group

A radio group picks exactly one option. Cuelark adds RadioGroupCard, where a whole card is the radio (great for pricing plans and shipping options): the checked card is framed by crop marks that close in on it, and dots spring into place.

Install: `npx shadcn@latest add https://ui.cuelark.com/r/radio-group.json` · Docs: https://ui.cuelark.com/components/radio-group

```tsx
import { RadioGroup, RadioGroupItem } from "@/components/ui/radio-group";

<RadioGroup defaultValue="a">
  <RadioGroupItem value="a" id="a" />
  <RadioGroupItem value="b" id="b" />
</RadioGroup>
```

### Props

- `RadioGroupItem.value` (`string`): Value submitted when checked.
- `RadioGroupCard.value` (`string`): Value submitted when checked.

### Accessibility

- Arrow keys move and select within the group; Tab leaves it.
- Give the group an aria-label or a visible legend.

## Rating

A rating collects or displays a score, like product reviews or feedback. Hovering previews the score, and choosing one pops the stars up to it in a quick cascade. It is a proper radio group, and has a read-only mode for showing averages.

Install: `npx shadcn@latest add https://ui.cuelark.com/r/rating.json` · Docs: https://ui.cuelark.com/components/rating

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

<Rating defaultValue={4} label="Rate this template" />
```

### Props

- `Rating.value / defaultValue` (`number`, default `0`): Controlled or initial score.
- `Rating.onValueChange` (`(value: number) => void`): Called when a star is chosen.
- `Rating.max` (`number`, default `5`): Number of stars.
- `Rating.readOnly` (`boolean`, default `false`): Display only (role=img with a text label).
- `Rating.size` (`"sm" | "md" | "lg"`, default `"md"`): Star size.

### Accessibility

- Interactive ratings are a radiogroup with arrow-key navigation.
- Read-only ratings read as "Rating: 4 out of 5".

## Reasoning

Reasoning shows a model's thinking while it happens: a shimmering "Thinking…" beside the crop-mark spinner, the trace streaming into a faded window, then an automatic collapse to "Thought for 6s" when the answer starts, so the reply stays front and center.

Install: `npx shadcn@latest add https://ui.cuelark.com/r/reasoning.json` · Docs: https://ui.cuelark.com/components/reasoning

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

<Reasoning streaming={isThinking}>{reasoningText}</Reasoning>
```

### Props

- `Reasoning.streaming` (`boolean`, default `false`): Thinking in progress.
- `Reasoning.duration` (`number`): Seconds; measured when omitted.
- `Reasoning.label` (`string`, default `"Thinking…"`): Status while streaming.

### Accessibility

- Fully keyboard operable with visible focus.
- Live regions announce streaming updates politely.

## Reveal

Reveal animates content in as it scrolls into view, as a block or one child at a time. Anything already on screen at load is left alone, so there is no flash, and everything stays in the server HTML for crawlers.

Install: `npx shadcn@latest add https://ui.cuelark.com/r/reveal.json` · Docs: https://ui.cuelark.com/components/reveal

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

<Reveal stagger effect="rise">{cards}</Reveal>
```

### Props

- `Reveal.effect` (`"rise" | "fade" | "blur" | "scale" | "wipe"`, default `"rise"`): Style; wipe uncovers with a clip-path.
- `Reveal.scroller` (`Element | null`): The scrolling element when it is not the page.
- `Reveal.stagger` (`boolean`, default `false`): Animate direct children in turn.
- `Reveal.asChild` (`boolean`, default `false`): Use your own element.

### Accessibility

- Content is never hidden without JavaScript.
- Disabled with reduced motion.

## Rotating Text

Rotating Text cycles through words in place, as in "Components for dashboards / landing pages / docs". The old word rolls away letter by letter, the new one rolls in, and the box eases to the new width so the sentence never jumps.

Install: `npx shadcn@latest add https://ui.cuelark.com/r/rotating-text.json` · Docs: https://ui.cuelark.com/components/rotating-text

```tsx
import { RotatingText } from "@/components/ui/rotating-text";

Built for <RotatingText words={["dashboards", "docs"]} />
```

### Props

- `RotatingText.words` (`string[]`): Words to cycle.
- `RotatingText.interval` (`number`, default `2400`): ms per word.

### Accessibility

- Pauses on hover.
- With reduced motion it shows the first word only.

## Scramble Text

Scramble Text resolves a word like a terminal decoding a signal, on mount, on scroll or on hover. The real text is rendered on the server, so it is indexed and readable without JavaScript.

Install: `npx shadcn@latest add https://ui.cuelark.com/r/scramble-text.json` · Docs: https://ui.cuelark.com/components/scramble-text

```tsx
import { ScrambleText } from "@/components/ui/scramble-text";

<ScrambleText text="SIGNAL ACQUIRED" trigger="inView" />
```

### Props

- `ScrambleText.text` (`string`): Final text.
- `ScrambleText.trigger` (`"mount" | "inView" | "hover"`, default `"inView"`): When to scramble.
- `ScrambleText.chars` (`string`, default `"upperCase"`): Scramble characters.
- `ScrambleText.duration` (`number`, default `0.9`): Seconds.

### Accessibility

- Screen readers get the final text.
- No effect with reduced motion.

## Scroll Area

A scroll area gives a container slim, consistent scrollbars over native scrolling, so keyboard, touch and wheel all still work. Optional edge fades signal that there is more.

Install: `npx shadcn@latest add https://ui.cuelark.com/r/scroll-area.json` · Docs: https://ui.cuelark.com/components/scroll-area

```tsx
import { ScrollArea } from "@/components/ui/scroll-area";

<ScrollArea fade className="h-64">…</ScrollArea>
```

### Props

- `ScrollArea.fade` (`boolean`, default `false`): Fade the scroll edges.
- `ScrollArea.orientation` (`"vertical" | "horizontal" | "both"`, default `"vertical"`): Scroll axis.

### Accessibility

- Native scrolling underneath; the viewport is focusable for keyboard scrolling.

## Scroll Progress

Scroll Progress is a hairline that fills as the reader scrolls, either through the whole page or through one article. GSAP ScrollTrigger scrubs it with a little smoothing.

Install: `npx shadcn@latest add https://ui.cuelark.com/r/scroll-progress.json` · Docs: https://ui.cuelark.com/components/scroll-progress

```tsx
import { ScrollProgress } from "@/components/ui/scroll-progress";

<ScrollProgress />
```

### Props

- `ScrollProgress.target` (`string | Element`): Track an element instead of the page.
- `ScrollProgress.position` (`"fixed" | "static"`, default `"fixed"`): Fixed to the top or inline.
- `ScrollProgress.scroller` (`string | Element`): The scrolling element when it is not the page.

### Accessibility

- Decorative (role=presentation); it adds no announcements.

## Select

A select picks one option from a list. Cuelark's select is built on Radix for full keyboard support and typeahead; it opens with a spring from the trigger, the first options cascade in, and the chevron flips while open.

Install: `npx shadcn@latest add https://ui.cuelark.com/r/select.json` · Docs: https://ui.cuelark.com/components/select

```tsx
import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from "@/components/ui/select";

<Select>
  <SelectTrigger><SelectValue placeholder="Theme" /></SelectTrigger>
  <SelectContent>
    <SelectItem value="light">Light</SelectItem>
    <SelectItem value="dark">Dark</SelectItem>
  </SelectContent>
</Select>
```

### Props

- `SelectTrigger.size` (`"sm" | "md" | "lg"`, default `"md"`): Height follows --cl-density.
- `SelectContent.position` (`"popper" | "item-aligned"`, default `"popper"`): Below the trigger, or aligned to the selected item.

### Accessibility

- Typeahead jumps to options as you type.
- Arrow keys, Home and End move; Enter or Space selects.
- Works in native forms via a hidden select.

## Separator

Separators divide content. Cuelark adds the dashed rule used throughout the system and a labelled variant, the classic "or" between sign-in options.

Install: `npx shadcn@latest add https://ui.cuelark.com/r/separator.json` · Docs: https://ui.cuelark.com/components/separator

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

<Separator label="or" />
```

### Props

- `Separator.variant` (`"solid" | "dashed"`, default `"solid"`): Line style.
- `Separator.label` (`ReactNode`): Text in the middle (horizontal only).
- `Separator.orientation` (`"horizontal" | "vertical"`, default `"horizontal"`): Direction.

### Accessibility

- Decorative by default; pass decorative={false} for a semantic separator.

## Sheet

A sheet slides a panel in from an edge: filters, settings, carts, mobile navigation. Cuelark sheets slide in on the house ease, their sections settle in one after another, and the footer sits in a muted tray under a dashed rule.

Install: `npx shadcn@latest add https://ui.cuelark.com/r/sheet.json` · Docs: https://ui.cuelark.com/components/sheet

```tsx
import { Sheet, SheetContent, SheetHeader, SheetTitle, SheetTrigger } from "@/components/ui/sheet";

<Sheet>
  <SheetTrigger asChild><Button>Open</Button></SheetTrigger>
  <SheetContent side="right">
    <SheetHeader><SheetTitle>Settings</SheetTitle></SheetHeader>
  </SheetContent>
</Sheet>
```

### Props

- `SheetContent.side` (`"top" | "right" | "bottom" | "left"`, default `"right"`): Edge it slides from.

### Accessibility

- A modal dialog: focus is trapped and returns to the trigger.
- Esc closes; an Esc hint sits next to the close button.

## Shimmer Button

Shimmer Button is the call to action for hero sections: a band of light sweeps across the ink surface on a slow loop and pauses while hovered, so the button stays lively without becoming restless. Presses ping in the signal color.

Install: `npx shadcn@latest add https://ui.cuelark.com/r/shimmer-button.json` · Docs: https://ui.cuelark.com/components/shimmer-button

```tsx
import { ShimmerButton } from "@/components/ui/shimmer-button";

<ShimmerButton>Start building</ShimmerButton>
```

### Props

- `ShimmerButton.interval` (`number`, default `2.6`): Seconds between sweeps.
- `ShimmerButton.asChild` (`boolean`, default `false`): Render a link.

### Accessibility

- Native button semantics and a visible focus ring.
- With reduced motion or --cl-motion: 0 the effect stays still and the content remains fully usable.

## Skeleton

Skeletons hold the shape of content while it loads, which reduces layout shift and perceived wait. The sweep is CSS-only, so it runs before JavaScript hydrates.

Install: `npx shadcn@latest add https://ui.cuelark.com/r/skeleton.json` · Docs: https://ui.cuelark.com/components/skeleton

```tsx
import { Skeleton, SkeletonText } from "@/components/ui/skeleton";

<Skeleton className="size-10 rounded-full" />
<SkeletonText lines={3} />
```

### Props

- `SkeletonText.lines` (`number`, default `3`): Line count; the last is shorter.

### Accessibility

- Skeletons are aria-hidden; set aria-busy on the region that is loading.
- The sweep is removed for reduced motion.

## Slider

Sliders choose a value or range along a track. Cuelark sliders show a value bubble while you drag or focus a thumb, can label ticks under the track, and support range selection with two thumbs.

Install: `npx shadcn@latest add https://ui.cuelark.com/r/slider.json` · Docs: https://ui.cuelark.com/components/slider

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

<Slider defaultValue={[50]} showValue format={(v) => `${v}%`} />
```

### Props

- `Slider.showValue` (`boolean`, default `false`): Bubble above active thumbs.
- `Slider.format` (`(v: number) => string`, default `String`): Formats bubble and tick labels.
- `Slider.ticks` (`number[]`): Values to label under the track.

### Accessibility

- Thumbs are role=slider with aria-valuenow; give the slider an aria-label.
- Arrow keys step, Page Up/Down jump, Home/End go to the ends.

## Sources

Sources shows what an answer was based on: a compact "Used 5 sources" pill with stacked domain tiles that expands into a numbered list of links. Tiles are generated from the domain, so no third-party favicon requests leak your users' reading.

Install: `npx shadcn@latest add https://ui.cuelark.com/r/sources.json` · Docs: https://ui.cuelark.com/components/sources

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

<Sources sources={[{ title, url }]} />
```

### Props

- `Sources.sources` (`{ title; url }[]`): The sources.

### Accessibility

- Fully keyboard operable with visible focus.
- Live regions announce streaming updates politely.

## Spinner

Spinners say "working on it". The signature marks spinner is four crop marks that close in, turn a quarter and open again. The ring and dots variants are quieter alternatives.

Install: `npx shadcn@latest add https://ui.cuelark.com/r/spinner.json` · Docs: https://ui.cuelark.com/components/spinner

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

<Spinner variant="marks" label="Saving" />
```

### Props

- `Spinner.variant` (`"marks" | "ring" | "dots"`, default `"marks"`): Style.
- `Spinner.size` (`"sm" | "md" | "lg"`, default `"md"`): Size.
- `Spinner.label` (`string`, default `"Loading"`): Accessible status text.

### Accessibility

- role=status with an aria-label.
- With reduced motion the marks hold still; the ring slows down.

## Stack Trace

Stack Trace turns a raw error into something you can read: the message in red, your own frames with function, file and line, library and runtime frames folded away, and a copy button for the raw text.

Install: `npx shadcn@latest add https://ui.cuelark.com/r/stack-trace.json` · Docs: https://ui.cuelark.com/components/stack-trace

```tsx
import { StackTrace } from "@/components/ui/stack-trace";

<StackTrace trace={error.stack} />
```

### Props

- `StackTrace.trace` (`string`): Raw error text.
- `StackTrace.hideInternal` (`boolean`, default `true`): Fold node_modules and node: frames.

### Accessibility

- Fully keyboard operable with visible focus.
- Live regions announce streaming updates politely.

## Stepper

A stepper shows progress through a multi-step flow: onboarding, checkout, setup wizards. Completed steps turn into checks, the current step glows, the connector fills like ink toward it, and completed steps can be clickable.

Install: `npx shadcn@latest add https://ui.cuelark.com/r/stepper.json` · Docs: https://ui.cuelark.com/components/stepper

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

<Stepper steps={[{ title: "Account" }, { title: "Billing" }]} current={0} />
```

### Props

- `Stepper.steps` (`{ title; description? }[]`): The steps.
- `Stepper.current` (`number`): Zero-based current step.
- `Stepper.orientation` (`"horizontal" | "vertical"`, default `"horizontal"`): Layout.
- `Stepper.onStepClick` (`(index: number) => void`): Makes completed steps clickable.

### Accessibility

- An ordered list; the current step has aria-current="step".
- Clickable steps are buttons with a descriptive label.

## Streaming Text

Streaming Text renders an AI reply as it streams: each new chunk fades up out of a slight blur instead of popping in, a signal caret marks the writing edge, and text already on screen never moves.

Install: `npx shadcn@latest add https://ui.cuelark.com/r/streaming-text.json` · Docs: https://ui.cuelark.com/components/streaming-text

```tsx
import { StreamingText } from "@/components/ui/streaming-text";

<StreamingText text={partial} streaming={isStreaming} />
```

### Props

- `StreamingText.text` (`string`): Text so far.
- `StreamingText.streaming` (`boolean`): Shows the caret.

### Accessibility

- Fully keyboard operable with visible focus.
- Live regions announce streaming updates politely.

## Subagent

Subagent shows work the main agent handed off: the sub-agent's name and task, a live activity line while it runs, and its own transcript tucked inside on an indented rail, so it is always clear who did what.

Install: `npx shadcn@latest add https://ui.cuelark.com/r/subagent.json` · Docs: https://ui.cuelark.com/components/subagent

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

<Subagent name="research-agent" task="Find prior art" status="running" activity="Reading docs…" />
```

### Props

- `Subagent.name · task` (`string · ReactNode`): Who and what.
- `Subagent.status` (`"running" | "done" | "error"`, default `"running"`): State.
- `Subagent.activity` (`string`): Live line.
- `Subagent.duration` (`number`): Seconds.

### Accessibility

- Fully keyboard operable with visible focus.
- Live regions announce streaming updates politely.

## Suggestions

Suggestions offers follow-up prompts as chips under an answer or in an empty chat. They scroll sideways on small screens with a fading edge, and arrive in a short stagger.

Install: `npx shadcn@latest add https://ui.cuelark.com/r/suggestions.json` · Docs: https://ui.cuelark.com/components/suggestions

```tsx
import { Suggestion, Suggestions } from "@/components/ui/suggestions";

<Suggestions>
  <Suggestion onClick={() => send("Explain")}>Explain</Suggestion>
</Suggestions>
```

### Accessibility

- Fully keyboard operable with visible focus.
- Live regions announce streaming updates politely.

## Switch

A switch turns a setting on or off immediately. The Cuelark switch thumb stretches while pressed and settles when released, a small tactile cue that the press registered, and it comes in three sizes for dense settings lists.

Install: `npx shadcn@latest add https://ui.cuelark.com/r/switch.json` · Docs: https://ui.cuelark.com/components/switch

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

<Switch id="digest" defaultChecked />
```

### Props

- `Switch.size` (`"sm" | "md" | "lg"`, default `"md"`): Track and thumb size.

### Accessibility

- Uses role="switch" with aria-checked.
- Label it with a <label htmlFor> or aria-label.
- Space and Enter toggle; the press animation is skipped for reduced motion.

## Table

Tables present structured data. Cuelark tables are plain semantic HTML (fully crawlable), with hairline rows, mono tabular numerals that line up, optional zebra striping and a sticky header.

Install: `npx shadcn@latest add https://ui.cuelark.com/r/table.json` · Docs: https://ui.cuelark.com/components/table

```tsx
import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "@/components/ui/table";

<Table striped>
  <TableHeader><TableRow><TableHead>Name</TableHead><TableHead numeric>Amount</TableHead></TableRow></TableHeader>
  <TableBody>…</TableBody>
</Table>
```

### Props

- `Table.striped` (`boolean`): Zebra rows.
- `Table.stickyHeader` (`boolean`): Sticky thead.
- `TableHead · TableCell.numeric` (`boolean`): Right-aligned tabular figures.

### Accessibility

- Real <table> semantics with <th> headers and a <caption>.
- The container scrolls horizontally on small screens.

## Tabs

Tabs switch between views in the same place. Cuelark tabs have one indicator that glides and resizes to the active tab, in a segmented or underline style, and the active tab is styled before hydration too, so server-rendered pages never flash.

Install: `npx shadcn@latest add https://ui.cuelark.com/r/tabs.json` · Docs: https://ui.cuelark.com/components/tabs

```tsx
import { Tabs, TabsContent, TabsList, TabsTrigger } from "@/components/ui/tabs";

<Tabs defaultValue="overview">
  <TabsList>
    <TabsTrigger value="overview">Overview</TabsTrigger>
    <TabsTrigger value="settings">Settings</TabsTrigger>
  </TabsList>
  <TabsContent value="overview">…</TabsContent>
  <TabsContent value="settings">…</TabsContent>
</Tabs>
```

### Props

- `TabsList.variant` (`"segmented" | "underline"`, default `"segmented"`): Indicator style.

### Accessibility

- Implements the WAI-ARIA tabs pattern: tablist, tab and tabpanel roles with selection state.
- Arrow keys move between tabs (vertical lists use Up and Down); Home and End jump to the ends.
- The indicator is decorative and its motion is disabled for reduced motion.

## Tag Input

Tag Input collects several values in one field: skills, labels, recipients, keywords. Enter or a comma adds a tag, pasted comma lists split automatically, Tab accepts an inline suggestion, and Backspace on an empty field first highlights and then removes the last tag. Duplicates shake instead of being added twice.

Install: `npx shadcn@latest add https://ui.cuelark.com/r/tag-input.json` · Docs: https://ui.cuelark.com/components/tag-input

```tsx
import { TagInput } from "@/components/ui/tag-input";

<TagInput defaultValue={["React"]} suggestions={["Tailwind CSS", "GSAP"]} />
```

### Props

- `TagInput.value / defaultValue` (`string[]`): Controlled or initial tags.
- `TagInput.onValueChange` (`(tags: string[]) => void`): Called on change.
- `TagInput.suggestions` (`string[]`): Inline completions.
- `TagInput.max` (`number`): Maximum tags.

### Accessibility

- Every tag has a labelled remove button.
- Backspace arms before deleting, so a held key never wipes the list.

## Task

Task shows a checklist an agent is working through: a progress bar, finished items checked off, and the current one shimmering.

Install: `npx shadcn@latest add https://ui.cuelark.com/r/task.json` · Docs: https://ui.cuelark.com/components/task

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

<Task title="Migrate invoices" items={[{ label: "Write helper", status: "done" }]} />
```

### Props

- `Task.title` (`ReactNode`): Heading.
- `Task.items` (`{ label; status: "done" | "active" | "todo" }[]`): Items.

### Accessibility

- Fully keyboard operable with visible focus.
- Live regions announce streaming updates politely.

## Terminal

Terminal shows commands an agent runs and their output: always a dark console so it reads the same in both themes, prompts in signal, success and failure lines colored, new lines sliding in while it streams, and auto-scroll.

Install: `npx shadcn@latest add https://ui.cuelark.com/r/terminal.json` · Docs: https://ui.cuelark.com/components/terminal

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

<Terminal lines={output} streaming={running} />
```

### Props

- `Terminal.lines` (`string[]`): Output lines.
- `Terminal.title` (`string`): Title bar.
- `Terminal.streaming` (`boolean`): Live caret.

### Accessibility

- Fully keyboard operable with visible focus.
- Live regions announce streaming updates politely.

## Test Results

Test Results shows the outcome of a test run an agent executed: a pass/fail/skip bar, suites that open themselves when something fails, and the failing assertion right under its test.

Install: `npx shadcn@latest add https://ui.cuelark.com/r/test-results.json` · Docs: https://ui.cuelark.com/components/test-results

```tsx
import { TestResults } from "@/components/ui/test-results";

<TestResults suites={suites} />
```

### Props

- `TestResults.suites` (`{ name; tests: { name; status: "pass" | "fail" | "skip"; duration?; error? }[] }[]`): Results.

### Accessibility

- Fully keyboard operable with visible focus.
- Live regions announce streaming updates politely.

## Text Reveal

Text Reveal animates headings and copy piece by piece with GSAP SplitText: letters rising out of a mask, words focusing in, lines fading up, on mount or when scrolled into view. The full text is in the server HTML, so search engines index it and screen readers read it whole.

Install: `npx shadcn@latest add https://ui.cuelark.com/r/text-reveal.json` · Docs: https://ui.cuelark.com/components/text-reveal

```tsx
import { TextReveal } from "@/components/ui/text-reveal";

<TextReveal as="h1" split="chars">Interfaces with a cue.</TextReveal>
```

### Props

- `TextReveal.as` (`"h1" | "h2" | "h3" | "h4" | "p" | "span" | "div"`, default `"p"`): Element (use headings for SEO).
- `TextReveal.split` (`"chars" | "words" | "lines"`, default `"words"`): Animation unit.
- `TextReveal.effect` (`"rise" | "blur" | "fade"`, default `"rise"`): Style.
- `TextReveal.trigger` (`"mount" | "inView"`, default `"inView"`): When to play.
- `TextReveal.delay · stagger` (`number`): Timing in seconds.

### Accessibility

- SplitText's aria: "auto" keeps an accessible label, so screen readers don't hear letters.
- Skipped entirely with reduced motion.

## Text Shimmer

Text Shimmer sweeps a light through muted text, the status line for anything an agent is doing right now. CSS-only, and it rests as plain muted text for reduced motion.

Install: `npx shadcn@latest add https://ui.cuelark.com/r/text-shimmer.json` · Docs: https://ui.cuelark.com/components/text-shimmer

```tsx
import { TextShimmer } from "@/components/ui/text-shimmer";

<TextShimmer>Searching…</TextShimmer>
```

### Props

- `TextShimmer.duration` (`number`, default `1.6`): Seconds per sweep.

### Accessibility

- Fully keyboard operable with visible focus.
- Live regions announce streaming updates politely.

## Textarea

A textarea collects longer text such as messages, bios and descriptions. Cuelark's textarea can grow with its content using CSS field-sizing (no resize scripts), and shows a live, politely announced character count that turns amber near the limit.

Install: `npx shadcn@latest add https://ui.cuelark.com/r/textarea.json` · Docs: https://ui.cuelark.com/components/textarea

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

<Textarea autoGrow showCount maxLength={280} />
```

### Props

- `Textarea.autoGrow` (`boolean`, default `false`): Grow with content (field-sizing: content).
- `Textarea.showCount` (`boolean`, default `false`): Live count; with maxLength shows n / max.

### Accessibility

- The counter is an aria-live region, announced politely as you type.
- Pair with a <label>; set aria-invalid for errors.

## Tilt Card

Tilt Card leans toward the pointer in 3D with a glare that follows across the surface, then settles back with an elastic release. It suits product cards, membership cards and showcases.

Install: `npx shadcn@latest add https://ui.cuelark.com/r/tilt-card.json` · Docs: https://ui.cuelark.com/components/tilt-card

```tsx
import { TiltCard } from "@/components/ui/tilt-card";

<TiltCard className="p-6">…</TiltCard>
```

### Props

- `TiltCard.max` (`number`, default `10`): Maximum tilt in degrees.
- `TiltCard.glare` (`boolean`, default `true`): Pointer-following glare.

### Accessibility

- Purely visual; content and focus order are unchanged.
- With reduced motion or --cl-motion: 0 the effect stays still and the content remains fully usable.

## Timeline

Timelines show events in order: changelogs, histories, order tracking. With animate, the rail draws itself as you scroll and each marker lights up when the line reaches it.

Install: `npx shadcn@latest add https://ui.cuelark.com/r/timeline.json` · Docs: https://ui.cuelark.com/components/timeline

```tsx
import { Timeline, TimelineItem, TimelineTime, TimelineTitle } from "@/components/ui/timeline";

<Timeline animate>
  <TimelineItem>
    <TimelineTime dateTime="2026-10-27">Oct 27</TimelineTime>
    <TimelineTitle>1.0 released</TimelineTitle>
  </TimelineItem>
</Timeline>
```

### Props

- `Timeline.animate` (`boolean`, default `false`): Scroll-drawn rail.

### Accessibility

- An ordered list with <time datetime> elements.
- Content is visible without JavaScript; animation is an enhancement.

## Toast

Toasts confirm what just happened without interrupting: saved, deployed, failed. Call toast() from anywhere. Cuelark toasts rise in, show a hairline countdown that pauses on hover and focus, take an action, follow a promise from loading to success, and slide away.

Install: `npx shadcn@latest add https://ui.cuelark.com/r/toast.json` · Docs: https://ui.cuelark.com/components/toast

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

// once, near the root
<Toaster />

// anywhere
toast.success("Saved", { description: "All changes synced." });
```

### Props

- `toast(title, options).description` (`ReactNode`): Secondary text.
- `toast(title, options).duration` (`number`, default `4500`): ms; Infinity keeps it open.
- `toast(title, options).action` (`{ label; onClick }`): One inline action.
- `toast(title, options).id` (`string`): Update an existing toast.
- `Toaster.position` (`"bottom-right" | "bottom-left" | "top-right" | "top-left" | "bottom-center" | "top-center"`, default `"bottom-right"`): Stack position.

### Accessibility

- Toasts are status regions (errors are assertive alerts).
- Hover or focus pauses the countdown; every toast has a labelled dismiss button.

## Toggle

A toggle is a button that stays pressed, like Bold in an editor. Cuelark toggles sink into the surface when on and send the signature ping ring on press.

Install: `npx shadcn@latest add https://ui.cuelark.com/r/toggle.json` · Docs: https://ui.cuelark.com/components/toggle

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

<Toggle aria-label="Bold"><BoldIcon /></Toggle>
```

### Props

- `Toggle.variant` (`"ghost" | "outline"`, default `"ghost"`): Visual style.
- `Toggle.size` (`"sm" | "md" | "lg"`, default `"md"`): Height follows --cl-density.

### Accessibility

- Uses aria-pressed.
- Icon-only toggles need an aria-label.

## Toggle Group

A toggle group is a set of toggles where one or several can be on: view switchers, alignment, date ranges. The segmented style is a true segmented control: one raised chip glides to the pressed item with a slight overshoot.

Install: `npx shadcn@latest add https://ui.cuelark.com/r/toggle-group.json` · Docs: https://ui.cuelark.com/components/toggle-group

```tsx
import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group";

<ToggleGroup type="single" defaultValue="week">
  <ToggleGroupItem value="day">Day</ToggleGroupItem>
  <ToggleGroupItem value="week">Week</ToggleGroupItem>
</ToggleGroup>
```

### Props

- `ToggleGroup.variant` (`"segmented" | "outline" | "ghost"`, default `"segmented"`): Group style.
- `ToggleGroup.size` (`"sm" | "md" | "lg"`, default `"md"`): Height follows --cl-density.
- `ToggleGroupItem.value` (`string`): Item value.

### Accessibility

- Arrow keys move between items (roving focus).
- Single groups expose radio semantics; multiple groups use aria-pressed.

## Tool

Tool shows one tool call compactly: the mono tool name, a live status (shimmer and spinner while running, a signal check when done), and timing. Expand for the exact parameters and the result. Failed calls open themselves so errors are never hidden.

Install: `npx shadcn@latest add https://ui.cuelark.com/r/tool.json` · Docs: https://ui.cuelark.com/components/tool

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

<Tool name="web_search" status="running" input={{ query }} />
```

### Props

- `Tool.name` (`string`): Tool name.
- `Tool.status` (`"pending" | "running" | "success" | "error"`, default `"success"`): State.
- `Tool.input · output` (`unknown`): Pretty-printed JSON or text.
- `Tool.duration` (`number`): Seconds.
- `Tool.icon` (`ReactNode`): Tool icon.

### Accessibility

- Fully keyboard operable with visible focus.
- Live regions announce streaming updates politely.

## Tooltip

Tooltips name an icon or reveal a shortcut on hover and focus. Cuelark tooltips use an inverted surface for contrast on any background, take a keyboard shortcut hint, and share warm-up delay across a toolbar so moving between buttons feels instant.

Install: `npx shadcn@latest add https://ui.cuelark.com/r/tooltip.json` · Docs: https://ui.cuelark.com/components/tooltip

```tsx
import { Tooltip, TooltipContent, TooltipTrigger } from "@/components/ui/tooltip";

<Tooltip>
  <TooltipTrigger asChild><Button size="icon" aria-label="Bold"><BoldIcon /></Button></TooltipTrigger>
  <TooltipContent kbd="⌘B">Bold</TooltipContent>
</Tooltip>
```

### Props

- `TooltipContent.kbd` (`ReactNode`): Keyboard shortcut after the label.
- `TooltipContent.side` (`"top" | "right" | "bottom" | "left"`, default `"top"`): Preferred side.
- `TooltipContent.sideOffset` (`number`, default `6`): Distance from the trigger in px.
- `TooltipProvider.delayDuration` (`number`, default `150`): Hover delay before opening.
- `TooltipProvider.skipDelayDuration` (`number`, default `300`): Window in which the next tooltip opens instantly.

### Accessibility

- Opens on hover and on keyboard focus, closes on Esc.
- Content is linked to the trigger with aria-describedby.
- Never put essential information or interactive content only in a tooltip.

## Trace Waterfall

Trace Waterfall lays an agent run out on a timeline: nested agents, model calls and tool calls as bars, running spans growing live, failures in red. Hover a bar for duration, tokens and cost; collapse branches to focus. Built for observability panels and debugging views.

Install: `npx shadcn@latest add https://ui.cuelark.com/r/trace-waterfall.json` · Docs: https://ui.cuelark.com/components/trace-waterfall

```tsx
import { TraceWaterfall } from "@/components/ui/trace-waterfall";

<TraceWaterfall spans={trace} />
```

### Props

- `TraceWaterfall.spans` (`TraceSpan[]`): { id, name, kind, start, end?, tokens?, cost?, error?, children? }
- `TraceWaterfall.now` (`number`): Current time for running spans.

### Accessibility

- Fully keyboard operable with visible focus.
- Live regions announce streaming updates politely.

## Typewriter

Typewriter types a phrase with a signal-colored block caret, holds, deletes and moves to the next (GSAP TextPlugin). It starts when it scrolls into view, and the first phrase is server-rendered for search engines.

Install: `npx shadcn@latest add https://ui.cuelark.com/r/typewriter.json` · Docs: https://ui.cuelark.com/components/typewriter

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

<Typewriter text={["dashboards.", "landing pages."]} />
```

### Props

- `Typewriter.text` (`string | string[]`): Phrase(s) to type.
- `Typewriter.speed` (`number`, default `28`): Characters per second.
- `Typewriter.hold` (`number`, default `1.6`): Seconds before deleting.
- `Typewriter.loop` (`boolean`, default `true`): Cycle forever.
- `Typewriter.cursor` (`boolean`, default `true`): Block caret.

### Accessibility

- The first phrase is real text; the caret is aria-hidden.
- With reduced motion or --cl-motion: 0 the effect stays still and the content remains fully usable.

## Web Preview

Web Preview is a compact browser for previewing pages an agent builds or deploys: an address bar, reload, open-in-new-tab, and desktop, tablet and mobile widths that ease between sizes.

Install: `npx shadcn@latest add https://ui.cuelark.com/r/web-preview.json` · Docs: https://ui.cuelark.com/components/web-preview

```tsx
import { WebPreview } from "@/components/ui/web-preview";

<WebPreview url={deployUrl} />
```

### Props

- `WebPreview.url · onUrlChange` (`string`): Address.
- `WebPreview.children` (`ReactNode`): Render instead of an iframe.

### Accessibility

- Fully keyboard operable with visible focus.
- Live regions announce streaming updates politely.