} ``` #### Props of PrecisionScrubField - `label` (required): `string`. Visible input label and accessible name for scrub and reset actions. - `value / defaultValue`: `number`, default `0 (defaultValue)`. Controlled or initial value in canonical units. - `onValueChange`: `(value: number) => void`. Receives canonical values while dragging, typing, resetting or using keys. - `onValueCommit`: `(value: number) => void`. Receives the value on pointer release, input blur, keyboard adjustment or reset. - `min / max`: `number`, default `-Infinity / Infinity`. Bounds in canonical units. - `step`: `number`, default `1`. Positive step in canonical units; Shift uses one tenth for fine adjustment. - `units`: `readonly ScrubUnit[]`. Display units with label and positive conversion factor, e.g. px = 1 and rem = 16. The first unit is initially selected. - `disabled`: `boolean`, default `false`. Disable the input, scrub handle, units and reset. - `className`: `string`. Classes for the outer wrapper. #### Keyboard - Arrow keys: Adjust from the scrub handle; Shift uses a tenth step and Alt ten steps. - Tab: Move through the enabled controls. Focus remains visible. #### Accessibility - Lathe controls expose accessible names, states and keyboard behavior. Layouts wrap at narrow widths and use semantic theme tokens. #### Motion - While scrubbing, the value chases the pointer on a short ease (about 110ms to catch up), so a fast flick rolls through the numbers instead of jumping. onValueCommit fires once it arrives. - A tick ruler under the field slides with the value as you scrub. - With reduced motion, the value follows the pointer directly. #### Customization ##### Connect your own data Use the typed props to connect application state. The source is installed into your project. ```tsx "use client" import * as React from "react" import { PrecisionScrubField } from "@/components/ui/precision-scrub-field" const units = [{ label: "px", factor: 1 }, { label: "rem", factor: 16 }] export default function PrecisionDemo() { const [width, setWidth] = React.useState(160) return

} ``` ### Radio Group A single-choice list of cards with sliding, fading, scaling, or instant selection and adjustable timing. Page: https://latheui.dev/components/radio-group Install: npx shadcn@latest add @latheui/radio-group #### Usage ```tsx import { RadioGroup } from "@/components/ui/radio-group" export default function Demo(){return } ``` #### Props of Radio Group - `options` (required): `RadioOption[]`. Labels, descriptions and disabled options. - `label` (required): `string`. Accessible group name. - `value / defaultValue`: `string`. Controlled or initial selection. - `animation`: `"slide" | "fade" | "scale" | "none"`, default `"slide"`. How the selected card is highlighted. Scale fades and grows in place; none also disables the dot animation. - `slideDuration`: `number`, default `Smooth spring`. Slide duration in milliseconds. When set, uses a timed ease-out instead of the default spring. Zero moves immediately. - `fadeInDuration`: `number`, default `200`. Milliseconds for the new highlight to appear in fade and scale modes. Also controls the scale-in timing. - `fadeOutDuration`: `number`, default `200`. Milliseconds for the old highlight to disappear in fade and scale modes. Also controls the scale-out timing. - `dotDuration`: `number`, default `200`. Milliseconds for the radio dot's opacity and size, and its circle's border color. Independent of the highlight timing. - `onValueChange`: `(value: string) => void`. Selection callback. #### Keyboard - Arrow keys: Move and select within the group. #### Accessibility - Radix provides roving focus and radio semantics. - Every option has a visible clickable label. #### Motion - Slide shares one outline between cards, using the smooth spring by default or a timed ease-out when slideDuration is set. - Fade crossfades the highlights in place. Scale adds a subtle growth from 96% to full size. Both use fadeInDuration and fadeOutDuration independently. - The dot stays inside its own circle and uses dotDuration independently of the card highlight. - All durations are in milliseconds; zero is instant and negative values are clamped to zero. With reduced motion or animation="none", selection updates immediately. #### Customization ##### Selection animation and timing Use fade for a stationary highlight, scale for a subtle pop, or none for instant selection. Set slideDuration to adjust the sliding outline. Fade-in, fade-out, and dot durations are independent, in milliseconds. ```tsx ``` ##### Composition Combine the control with your own layout. Semantic colors follow the active theme. ```tsx import { RadioGroup } from "@/components/ui/radio-group" export default function Demo(){return } ``` ### Segmented Control Picks one option from a small set. Behaves as a radio group, with a thumb that slides to the selection. Page: https://latheui.dev/components/segmented-control Install: npx shadcn@latest add @latheui/segmented-control #### Usage ```tsx import { SegmentedControl } from "@/components/ui/segmented-control" export function RangePicker() { const [range, setRange] = React.useState("week") return ( ) } ``` #### Props of SegmentedControl Generic over the option values, so onValueChange is typed to your union. Also accepts native div attributes. - `options` (required): `SegmentedOption[] | SegmentedOption[][]`. The segments, in order: { value, label, disabled? }. An array of arrays makes sections with a divider between. - `value`: `T`. Controlled selection. - `defaultValue`: `T`, default `first enabled option`. Initial selection when uncontrolled. - `onValueChange`: `(value: T) => void`. Called when the selection changes. - `size`: `"sm" | "md" | "lg"`, default `"md"`. Segment height: 28, 32 or 40px. - `fullWidth`: `boolean`, default `false`. Stretches to the container with equal-width segments. - `disabled`: `boolean`, default `false`. Disables every segment. - `name`: `string`. Adds a hidden input so the value submits with a form. - `inset`: `number`, default `2`. Space between the track's edge and the thumb, in px. - `gap`: `number`, default `2`. Space between segments, in px. - `radius`: `number | string`, default `8`. Track corner radius, in px or any CSS length. Use 999 for a pill. The thumb's radius is this less the inset. - `dividers`: `boolean`, default `false`. A hairline between every pair of segments, hidden beside the selected one. - `curve`: `Curve`, default `snappy spring`. How the thumb moves. Any curve from lib/animate or the Animation Lab: springs, bezier, elastic, steps and more. - `duration`: `number`. Milliseconds, for curves that are not springs. - `classNames`: `{ thumb?: string; segment?: string; divider?: string }`. Classes for the thumb, every segment and the dividers. #### Keyboard - Tab: Moves focus to the selected segment, then out of the group. - ArrowRight / ArrowDown: Selects the next enabled segment, wrapping to the first. - ArrowLeft / ArrowUp: Selects the previous enabled segment, wrapping to the last. - Home / End: Selects the first or last enabled segment. #### Accessibility - Uses the radiogroup and radio roles with a roving tab stop, so it is one stop in the tab order. - Pass aria-label or aria-labelledby to name the group. - Use it for two to five short options, or sections of them. For more, or for options that switch panels, use Select or Tabs. - Section dividers and hairlines are decorative and hidden from assistive tech; arrow keys move across every section. - If labels are icons only, give each icon an accessible name. #### Motion - The thumb moves to the selected segment with a snappy spring (stiffness 900, damping 48), or with the curve you pass. - One thumb moves in the track's local coordinates, beneath every label. Moving, scrolling, or resizing the control keeps it attached; only selection changes animate. - With reduced motion, the thumb jumps. #### Customization ##### A pill with a colored thumb ```tsx ``` ##### A curve from the Animation Lab Copy a curve from the Lab's JavaScript export and pass it as curve. ```tsx ``` ##### Typed values ```tsx type View = "grid" | "list" const [view, setView] = React.useState("grid") aria-label="View" value={view} onValueChange={setView} options={[ { value: "grid", label: "Grid" }, { value: "list", label: "List" }, ]} /> ``` ### Select A compact option picker with typeahead, keyboard navigation, a highlight that slides between options, and an ink checkmark. Page: https://latheui.dev/components/select Install: npx shadcn@latest add @latheui/select #### Usage ```tsx import { Select } from "@/components/ui/select" export default function Demo() { return

Workspace

} ``` ### Slider A precise range control with one or more thumbs and a live value readout. Page: https://latheui.dev/components/slider Install: npx shadcn@latest add @latheui/slider #### Usage ```tsx import { Slider } from "@/components/ui/slider" export default function Demo(){return

v+"%"}/>"$"+v}/>

} ``` #### Props of Slider - `label` (required): `string`. Visible and accessible name. - `value / defaultValue`: `number[]`, default `[50]`. One thumb per value; two values create a range. - `onValueChange / onValueCommit`: `(value: number[]) => void`. Live changes and committed changes. - `min / max / step`: `number`. Range and precision. Defaults to 0, 100, 1. - `formatValue`: `(value: number) => string`. Visible and spoken value formatting. - `editable`: `boolean`, default `false`. Single thumb only: the readout becomes a field you can type a value into. - `animateValue`: `boolean`, default `false`. Glide to values set from outside, such as a linked control or a timeline clip. A drag on this slider still follows the pointer. #### Keyboard - Arrow keys / Home / End: Adjust a thumb or move to its boundary. #### Accessibility - Each thumb has a label and formatted aria-valuetext. - Radix supplies keyboard control and form integration. #### Motion - Clicking the track sends the thumb there over 320ms, speeding up and then slowing down. - While dragging, the thumb chases the pointer on a 110ms ease-out: quick enough to feel direct, slow enough to see it glide. - With reduced motion, the thumb moves at once, for clicks and drags alike. #### Customization ##### Composition Combine the control with your own layout. Semantic colors follow the active theme. ```tsx import { Slider } from "@/components/ui/slider" export default function Demo(){return

v+"%"}/>"$"+v}/>

} ``` ### Spring Switch (Pro) A big, springy on and off switch. Click it or swipe the thumb across, and choose how much it bounces. Page: https://latheui.dev/components/spring-switch Install: npx shadcn@latest add @latheui/spring-switch #### Usage ```tsx import { SpringSwitch } from "@/components/ui/spring-switch" export function Setting() { return } ``` #### Props of SpringSwitch Also accepts native button attributes, such as id, name and disabled. - `checked`: `boolean`. Controlled state. - `defaultChecked`: `boolean`, default `false`. Initial state when uncontrolled. - `onCheckedChange`: `(checked: boolean) => void`. Called when the switch is clicked, swiped or set from the keyboard. - `damping`: `number`, default `18`. Spring damping. Lower is bouncier: 10 is playful, 32 calm. - `icons`: `{ on?: ReactNode; off?: ReactNode }`. Shown inside the thumb for each state. #### Keyboard - Space / Enter: Toggles the switch. - ArrowRight: Turns it on. - ArrowLeft: Turns it off. #### Accessibility - A native button with role switch and aria-checked, so it is announced as on or off. - Always label it, with a label element pointing at its id or with aria-label. - Swiping is an extra. Everything it does can be done with a click or the keyboard. - Vertical scrolling still works when a swipe starts on the switch. #### Motion - The thumb springs across with a stiffness of 380. Damping sets how far it overshoots and how often it bounces. - A swipe hands its speed to the spring, so a hard flick lands harder. - With reduced motion, the thumb jumps to its place. #### Customization ##### Change the on color ```tsx ``` ##### Change the size The track is sized from two CSS variables: the thumb and the padding around it. ```tsx ``` ### Switch Turns a setting on or off immediately. Click it, or swipe the thumb across. It stretches while pressed and springs into place. Page: https://latheui.dev/components/switch Install: npx shadcn@latest add @latheui/switch #### Usage ```tsx import { Switch } from "@/components/ui/switch" export function Setting() { return (

Email notifications

) } ``` #### Props of Switch Also accepts Radix Switch.Root props such as name, value, required and disabled. - `checked`: `boolean`. Controlled state. - `defaultChecked`: `boolean`, default `false`. Initial state when uncontrolled. - `onCheckedChange`: `(checked: boolean) => void`. Called when the switch is toggled. - `size`: `"sm" | "md"`, default `"md"`. Track size. - `disabled`: `boolean`, default `false`. Prevents interaction. #### Keyboard - Space / Enter: Toggles the switch. #### Accessibility - Built on Radix Switch: a button with role switch and aria-checked. - Always label it, with a label element pointing at its id or with aria-label. - A switch takes effect immediately. If the change only applies after a Save button, use a checkbox. - On and off are shown by thumb position as well as color. - Swiping is an extra: a click, a tap or the keyboard still toggle it. Vertical page scrolling still works when a touch starts on the switch. #### Motion - The thumb travels with the snappy spring and widens by 4px while the switch is pressed. - Swiping drags the thumb under the pointer. Let go past the middle and it switches; short of it, it springs back. A swipe that ends on the side it started from changes nothing. - With reduced motion, the thumb jumps and does not stretch. #### Customization ##### Change the on color ```tsx ``` ### Tag Input A token editor with duplicate prevention, removable chips and a keyboard workflow. Page: https://latheui.dev/components/tag-input Install: npx shadcn@latest add @latheui/tag-input #### Usage ```tsx import { TagInput } from "@/components/ui/tag-input" export default function Demo(){return } ``` #### Props of Tag Input - `label` (required): `string`. Visible input label. - `value / defaultValue`: `string[]`. Controlled or initial tags. - `onValueChange`: `(tags: string[]) => void`. Called after adding or removing a tag. - `maxTags`: `number`. Maximum tag count. - `name`: `string`. Submit one hidden form value per tag. #### Keyboard - Enter / ,: Add the typed tag. - Backspace: Remove the last tag when the input is empty. #### Accessibility - Removable chips are named buttons. - Additions, removals and duplicate errors are announced. - Composition input is preserved. #### Customization ##### Composition Combine the control with your own layout. Semantic colors follow the active theme. ```tsx import { TagInput } from "@/components/ui/tag-input" export default function Demo(){return } ``` ### Textarea A paper-like multiline field with an optional character counter. Page: https://latheui.dev/components/textarea Install: npx shadcn@latest add @latheui/textarea #### Usage ```tsx import { Textarea } from "@/components/ui/textarea" export default function Demo(){return

</div>}
```

#### Props of Textarea

- `label` (required): `string`. Visible label.
- `counter`: `boolean`, default `false`. Display character count.
- `expandable`: `boolean`, default `true`. Let people drag the corner to make the field taller.
- `maxHeight`: `number | string`. Tallest the field can be dragged, in pixels or any CSS length.
- `value / defaultValue`: `string`. Controlled text or initial text.
- `maxLength`: `number`. Native character limit.

#### Accessibility

- A native textarea retains multiline keyboard and form behavior.
- The character count is connected with aria-describedby.

#### Customization

##### Composition

Combine the control with your own layout. Semantic colors follow the active theme.

```tsx
import { Textarea } from "@/components/ui/textarea"
export default function Demo(){return <div className="w-full max-w-sm"><Textarea label="Project notes" placeholder="What are you working on?" counter maxLength={240}/></div>}
```

## Feedback

### Alert

An inline notice with a title, message and optional dismiss action.

Page: https://latheui.dev/components/alert
Install: npx shadcn@latest add @latheui/alert

#### Usage

```tsx
import * as React from "react"
import { Alert } from "@/components/ui/alert"
import { Button } from "@/components/ui/button"
export default function Demo(){const [show,setShow]=React.useState(true);return <div className="w-full max-w-md space-y-3">{show?<Alert title="Your workspace is ready" onDismiss={()=>setShow(false)}>Invite collaborators whenever you are ready.</Alert>:<Button variant="outline" onClick={()=>setShow(true)}>Show notice</Button>}<Alert title="Export paused" variant="danger">Check your connection and try again.</Alert></div>}
```

#### Props of Alert

- `title` (required): `string`. Notice heading.
- `variant`: `"info" | "danger"`, default `"info"`. Danger notices are announced assertively.
- `children`: `ReactNode`. Message or action content.
- `onDismiss`: `() => void`. Shows a named dismiss button. Called after a 200ms fade; immediate with reduced motion.

#### Accessibility

- Informational updates use role=status; urgent errors use role=alert.
- Icons are decorative. Dismiss controls are explicitly named.

#### Customization

##### Composition

Combine the control with your own layout. Semantic colors follow the active theme.

```tsx
import * as React from "react"
import { AnimatePresence, motion } from "motion/react"

import { Alert } from "@/components/ui/alert"
import { ease, useMotionSafe } from "@/lib/motion"

const notices = [
  {
    id: "ready",
    title: "Your workspace is ready",
    body: "Invite collaborators whenever you are ready.",
    variant: "info" as const,
  },
  {
    id: "paused",
    title: "Export paused",
    body: "Check your connection and try again.",
    variant: "danger" as const,
  },
]

export default function Demo() {
  const [open, setOpen] = React.useState(notices.map((notice) => notice.id))
  const { safe } = useMotionSafe()
  return (
    <div className="flex w-full max-w-md flex-col">
      {/* A dismissed alert fades, then its space closes so the ones below slide up. */}
      <AnimatePresence initial={false}>
        {notices
          .filter((notice) => open.includes(notice.id))
          .map((notice) => (
            <motion.div
              key={notice.id}
              exit={{ height: 0, marginBottom: 0 }}
              transition={safe({ duration: 0.28, ease: ease.out })}
              className="mb-3 overflow-hidden"
            >
              <Alert
                title={notice.title}
                variant={notice.variant}
                onDismiss={() => setOpen((ids) => ids.filter((id) => id !== notice.id))}
              >
                {notice.body}
              </Alert>
            </motion.div>
          ))}
      </AnimatePresence>
    </div>
  )
}
```

### Avatar

Portraits with an initials fallback, and a group that fans out on hover to name everyone, with the rest in a +N chip.

Page: https://latheui.dev/components/avatar
Install: npx shadcn@latest add @latheui/avatar

#### Usage

```tsx
import { Avatar, AvatarGroup } from "@/components/ui/avatar"

export function Team({ people }: { people: { name: string; src?: string }[] }) {
  return <AvatarGroup people={people} max={5} label="Team" />
}
```

#### Props of Avatar

Also accepts the Radix Avatar root's attributes.

- `name` (required): `string`. Accessible name, and the source of the initials.
- `src`: `string`. Image URL. The initials show while it loads, or if it fails.
- `size`: `"sm" | "md" | "lg"`, default `"md"`. 28, 36 or 48px.

#### Props of AvatarGroup

Also accepts native div attributes.

- `people` (required): `{ name: string; src?: string }[]`. Everyone in the group, first on top.
- `max`: `number`, default `4`. Avatars shown before the rest fold into a +N chip.
- `size`: `"sm" | "md" | "lg"`, default `"md"`. Size of every avatar.
- `overlap`: `number`, default `about a third of the size`. How far each avatar tucks under the one before, in px.
- `spread`: `boolean`, default `true`. Fan apart while the pointer or focus is on the group.
- `spreadGap`: `number`, default `4`. Space between avatars once spread, in px.
- `names`: `boolean`, default `true`. A tooltip with each person's name; makes avatars focusable to reach it.
- `label`: `string`, default `"People"`. Accessible name for the group.
- `curve`: `Curve`, default `snappy spring`. How avatars move apart. Any curve from the Animation Lab.
- `duration`: `number`. Milliseconds, for curves that are not springs.

#### Keyboard

- Tab: With names on, moves through the avatars and shows each name; the group fans out while focus is in it.

#### Accessibility

- Images and initials both expose the person's name.
- The group is a named group. The +N chip is read as the count and the names it stands for.
- With names on, each avatar takes focus so its tooltip is reachable from the keyboard, not only on hover.

#### Motion

- Avatars spread with a snappy spring (stiffness 520, damping 34), or your curve, and the one under the pointer lifts 3px.
- With reduced motion they move without springing.

#### Customization

##### A tight, bouncy group

```tsx
<AvatarGroup people={people} size="sm" overlap={12} spreadGap={8} curve={{ type: "spring", stiffness: 300, damping: 14 }} />
```

##### Still, with no tooltips

```tsx
<AvatarGroup people={people} spread={false} names={false} />
```

### Badge

A small label for status, counts and metadata, with an optional status dot.

Page: https://latheui.dev/components/badge
Install: npx shadcn@latest add @latheui/badge

#### Usage

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

export function Status() {
  return (
    <Badge variant="outline" dot dotClassName="bg-chart-4">
      Operational
    </Badge>
  )
}
```

#### Props of Badge

Also accepts every native span attribute.

- `variant`: `"neutral" | "outline" | "solid" | "destructive"`, default `"neutral"`. Visual style.
- `dot`: `boolean`, default `false`. Shows a status dot before the label.
- `pulse`: `boolean`, default `false`. Adds a ping animation to the dot.
- `dotClassName`: `string`. Classes for the dot, usually a background color. Defaults to the text color.

#### Accessibility

- The dot is decorative and hidden from assistive tech. The label must carry the meaning on its own, so never rely on dot color alone.
- A badge is not interactive. For a removable or clickable chip, wrap the content in a button.
- Long labels truncate with an ellipsis rather than wrapping. Keep the full text available elsewhere if it can be cut off.

#### Motion

- The pulse ping is hidden when reduced motion is requested. The dot itself stays.

#### Customization

##### Custom colors

Combine the outline variant with your own utilities.

```tsx
<Badge variant="outline" className="border-chart-2/40 bg-chart-2/10 text-chart-2">
  Beta
</Badge>
```

### Empty State

A calm placeholder with an icon, explanation and a next action.

Page: https://latheui.dev/components/empty-state
Install: npx shadcn@latest add @latheui/empty-state

#### Usage

```tsx
import * as React from "react"
import { EmptyState } from "@/components/ui/empty-state"
import { Button } from "@/components/ui/button"
export default function Demo(){const [created,setCreated]=React.useState(false);return <div className="w-full max-w-md">{created?<EmptyState title="Your first project is ready" description="A fresh canvas for your next idea." action={<Button variant="outline" size="sm" onClick={()=>setCreated(false)}>Reset preview</Button>}/>:<EmptyState title="Room for something new" description="Keep your ideas, files and collaborators together." action={<Button size="sm" onClick={()=>setCreated(true)}>Create a project</Button>}/>}</div>}
```

#### Props of Empty State

- `title` (required): `string`. Short empty-state heading.
- `description`: `string`. Explain the state and next step.
- `icon / action`: `ReactNode`. Decorative icon and a meaningful action.

#### Accessibility

- The title is a heading and the optional action is ordinary interactive content.
- The icon is decorative.

#### Customization

##### Composition

Combine the control with your own layout. Semantic colors follow the active theme.

### Progress

Bar and ring indicators with determinate and indeterminate states.

Page: https://latheui.dev/components/progress
Install: npx shadcn@latest add @latheui/progress

#### Usage

```tsx
import * as React from "react"
import { Progress } from "@/components/ui/progress"
import { Button } from "@/components/ui/button"
export default function Demo(){const [value,setValue]=React.useState(64);return <div className="w-full max-w-sm space-y-6"><Progress label="Export progress" value={value}/><div className="flex items-center justify-between"><Progress label="Storage used" value={value} variant="ring"/><Button variant="outline" size="sm" onClick={()=>setValue(value>=100?0:Math.min(100,value+12))}>Advance</Button></div></div>}
```

#### Props of Progress

- `label` (required): `string`. Accessible progress name.
- `value`: `number`. Current value. Omit for an indeterminate indicator.
- `max`: `number`, default `100`. Upper bound; values are clamped.
- `variant`: `"bar" | "ring"`, default `"bar"`. Indicator shape.
- `showValue`: `boolean`, default `true`. Show percentage text.

#### Accessibility

- Determinate progress exposes min, max and current values.
- Indeterminate progress omits aria-valuenow.
- Transitions and continuous animation respect reduced motion.

#### Customization

##### Composition

Combine the control with your own layout. Semantic colors follow the active theme.

### Skeleton

A placeholder shape that holds the layout while content loads.

Page: https://latheui.dev/components/skeleton
Install: npx shadcn@latest add @latheui/skeleton

#### Usage

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

export function ProfileLoading() {
  return (
    <div aria-busy="true" className="flex items-center gap-3">
      <Skeleton className="size-10 rounded-full" />
      <Skeleton className="h-4 w-40" />
    </div>
  )
}
```

#### Props of Skeleton

Accepts every native div attribute. Size and shape come from className.

- `className`: `string`. Width, height and radius of the placeholder.

#### Accessibility

- Skeletons are hidden from assistive tech. Put aria-busy on the region that is loading so the state is still exposed.
- If loading can take more than a few seconds, pair the skeleton with visible text or a status message.
- Reserve the same space as the final content to avoid layout shift.

#### Motion

- A slow opacity pulse. With reduced motion, the pulse stops and the block stays solid.

#### Customization

##### Lines of text

```tsx
<div className="flex flex-col gap-2">
  <Skeleton className="h-3.5 w-full" />
  <Skeleton className="h-3.5 w-11/12" />
  <Skeleton className="h-3.5 w-2/3" />
</div>
```

### Timeline (Pro)

An ordered activity trail with dates, details and completed markers.

Page: https://latheui.dev/components/timeline
Install: npx shadcn@latest add @latheui/timeline

#### Usage

```tsx
import { Timeline } from "@/components/ui/timeline"
export default function Demo(){return <Timeline autoComplete className="w-full max-w-sm" items={[{id:"1",title:"Project created",date:"Oct 10",dateTime:"2026-10-10",description:"A new home for your ideas.",complete:false},{id:"2",title:"Team invited",date:"Oct 11",dateTime:"2026-10-11",description:"Three collaborators joined.",complete:false},{id:"3",title:"First review",date:"Today",dateTime:"2026-10-12",description:"Feedback is taking shape."}]}/>}
```

#### Props of Timeline

- `animate`: `boolean`, default `true`. Fade each row into view in order. Reduced motion shows rows immediately.
- `stagger`: `number`, default `320`. Milliseconds between row entrances.
- `autoComplete`: `boolean`, default `false`. Start every marker unchecked, then animate each to a white background and check. Preview pause and restart control the sequence.
- `items` (required): `TimelineItem[]`. Stable ids, titles, visible dates, optional ISO dates, descriptions and completion states.

#### Accessibility

- Chronological entries use an ordered list and native time elements.
- Completion is also available as text.

#### Customization

##### Composition

Combine the control with your own layout. Semantic colors follow the active theme.

### Toast

Brief notifications called from anywhere. They stack, pause on hover, swipe away, track a promise, and hold a change back until its undo runs out.

Page: https://latheui.dev/components/toast
Install: npx shadcn@latest add @latheui/toast

#### Usage

```tsx
// app/layout.tsx: render one Toaster
import { Toaster } from "@/components/ui/toast"

export default function Layout({ children }: { children: React.ReactNode }) {
  return (
    <>
      {children}
      <Toaster />
    </>
  )
}

// anywhere on the client
import { toast } from "@/components/ui/toast"

toast.success("Changes saved")
```

#### Props of toast(title, options?)

Returns the toast id. toast.success, toast.error and toast.loading set the variant. toast.dismiss(id?) removes one toast, or all of them.

- `description`: `ReactNode`. Secondary line under the title.
- `variant`: `"default" | "success" | "error" | "loading"`, default `"default"`. Sets the icon and the live-region role.
- `duration`: `number`, default `4000`. Milliseconds before auto-dismiss. Loading toasts default to Infinity.
- `action`: `{ label: string; onClick: () => void }`. A button in the toast. Clicking it also dismisses the toast.
- `id`: `string`. Reuse an id to update an existing toast instead of adding one.

#### Props of toast.undo(title, options)

A change that can be taken back. Make the change in your UI right away, then finish it in onCommit, which runs only if Undo is not pressed in time. Accepts description, duration (default 6000) and id too.

- `onUndo` (required): `() => void`. Runs when Undo or the hotkey is pressed. Put things back here.
- `onCommit`: `() => void`. Runs once when the toast leaves without an undo: it timed out, was dismissed or swiped away, or was pushed out by newer toasts.
- `label`: `string`, default `"Undo"`. Button text.
- `hotkey`: `string | null`, default `"mod+z"`. Presses Undo on the newest undo toast. Ignored while typing in a field, which has its own undo. null turns it off.
- `undoneMessage`: `ReactNode`. Replaces the toast in place after an undo, for example "Restored". Without it the toast just leaves.

#### Props of toast.promise(promise, messages)

- `loading` (required): `ReactNode`. Title while the promise is pending.
- `success` (required): `ReactNode | (value) => ReactNode`. Title when it resolves.
- `error` (required): `ReactNode | (error) => ReactNode`. Title when it rejects.

#### Props of Toaster

- `position`: `"top-right" | "top-center" | "bottom-right" | "bottom-center"`, default `"bottom-right"`. Screen corner or edge.
- `limit`: `number`, default `4`. Most toasts shown at once. Older ones are dismissed, which commits a pending undo.
- `label`: `string`, default `"Notifications"`. Accessible name of the region.
- `className`: `string`. Classes for the fixed region.

#### Keyboard

- Tab: Reaches the action and dismiss buttons. Focus inside the stack pauses every timer.
- Enter / Space: Activates the focused action or dismiss button.
- Mod / Z: Presses Undo on the newest undo toast, unless focus is in a text field.

#### Accessibility

- Each toast is a live region: role status for ordinary messages and role alert for errors, which interrupt.
- Timers pause while the pointer or keyboard focus is inside the stack, so nothing disappears while it is being read or reached.
- Every toast has a dismiss button, so swiping is never the only way to remove one.
- Undo toasts give 6 seconds by default and stop counting while hovered or focused. The Undo button announces its shortcut with aria-keyshortcuts.
- Do not put the only path to an important action in a toast. It can time out before someone using a screen reader or switch access gets to it.

#### Motion

- Toasts enter from the screen edge with the smooth spring and the stack reflows around them.
- Drag a toast to the right to dismiss it. A short drag springs back.
- An undo toast's ring drains linearly over its duration and freezes while the stack is paused.
- With reduced motion, toasts fade in and out and the stack does not animate.

#### Customization

##### Position and limit

```tsx
<Toaster position="top-center" limit={3} />
```

##### Optimistic delete with undo

```tsx
function remove(item: Item) {
  setItems((items) => items.filter((i) => i.id !== item.id))
  toast.undo("Message deleted", {
    onUndo: () => setItems((items) => [...items, item]),
    onCommit: () => api.delete(item.id),
  })
}
```

##### Update a toast by id

```tsx
const id = toast.loading("Exporting…")
// later
toast.success("Export ready", { id, action: { label: "Download", onClick: download } })
```

### Tooltip

A short label for a control, shown on hover and keyboard focus, with an optional shortcut hint.

Page: https://latheui.dev/components/tooltip
Install: npx shadcn@latest add @latheui/tooltip

#### Usage

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

export function ArchiveButton() {
  return (
    <Tooltip content="Archive" shortcut={["E"]}>
      <Button variant="ghost" size="icon" aria-label="Archive">
        <ArchiveIcon />
      </Button>
    </Tooltip>
  )
}
```

#### Props of Tooltip

- `content` (required): `ReactNode`. The tooltip text.
- `children` (required): `ReactElement`. The trigger. One focusable element that accepts a ref.
- `shortcut`: `string[]`. Keys shown after the text. Display only.
- `side`: `"top" | "right" | "bottom" | "left"`, default `"top"`. Preferred side.
- `align`: `"start" | "center" | "end"`, default `"center"`. Alignment along the side.
- `sideOffset`: `number`, default `6`. Gap between trigger and tooltip in pixels.
- `delayDuration`: `number`, default `350`. Milliseconds before opening on hover.
- `open`: `boolean`. Controlled open state.
- `defaultOpen`: `boolean`, default `false`. Initial open state when uncontrolled.
- `onOpenChange`: `(open: boolean) => void`. Called when the tooltip opens or closes.
- `className`: `string`. Classes for the tooltip surface.

#### Props of TooltipProvider

Optional. Shares delay timing across the tooltips inside it.

- `delayDuration`: `number`, default `350`. Default open delay for tooltips inside.
- `skipDelayDuration`: `number`, default `300`. Window in which moving to another trigger opens it instantly.

#### Keyboard

- Tab: Focusing the trigger opens the tooltip without delay.
- Escape: Closes the tooltip.

#### Accessibility

- Built on Radix Tooltip. The trigger is described by the tooltip through aria-describedby.
- Tooltips do not open on touch. Never put information there that is not available some other way.
- A tooltip is a description, not a name. Icon-only triggers still need their own aria-label.
- The tooltip stays open while the pointer is over it, so it can be read and magnified.

#### Motion

- Scales from 94% from the side nearest the trigger with the snappy spring, and fades out in 160ms.
- With reduced motion, it fades without scaling.

#### Customization

##### Share delays app-wide

```tsx
import { TooltipProvider } from "@/components/ui/tooltip"

export function Providers({ children }: { children: React.ReactNode }) {
  return <TooltipProvider delayDuration={200}>{children}</TooltipProvider>
}
```

## Navigation

### Accordion

Stacked sections that expand to reveal their content, one at a time or several at once.

Page: https://latheui.dev/components/accordion
Install: npx shadcn@latest add @latheui/accordion

#### Usage

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

export function Faq() {
  return (
    <Accordion>
      <AccordionItem value="shipping">
        <AccordionTrigger>How long does shipping take?</AccordionTrigger>
        <AccordionContent>Two to four working days.</AccordionContent>
      </AccordionItem>
    </Accordion>
  )
}
```

#### Props of Accordion

Also accepts native div attributes.

- `type`: `"single" | "multiple"`, default `"single"`. Whether one or many items can be open.
- `value`: `string[]`. Controlled open items. An array for both types.
- `defaultValue`: `string[]`, default `[]`. Initially open items when uncontrolled.
- `onValueChange`: `(value: string[]) => void`. Called when the open items change.
- `collapsible`: `boolean`, default `true`. With type single, whether the open item can be closed again.
- `disabled`: `boolean`, default `false`. Disables every item.

#### Props of AccordionItem

- `value` (required): `string`. Unique identifier of the item.
- `disabled`: `boolean`, default `false`. Prevents the item from being toggled.

#### Props of AccordionTrigger

- `headingLevel`: `2 | 3 | 4 | 5 | 6`, default `3`. Level of the heading that wraps the button.

#### Props of AccordionContent

className styles the inner content wrapper.

#### Keyboard

- Enter / Space: Toggles the focused section.
- ArrowDown / ArrowUp: Moves focus to the next or previous trigger.
- Home / End: Moves focus to the first or last trigger.

#### Accessibility

- Built on Radix Accordion. Each trigger is a button inside a heading, with aria-expanded and aria-controls.
- Set headingLevel so the triggers fit the page outline. The default is h3.
- Closed content is removed from the DOM, so it is not reachable by keyboard or by find-in-page. If people need to search the content, keep sections open or use plain headings.

#### Motion

- Content height animates over 220ms while it fades, and the chevron rotates.
- With reduced motion, sections open and close instantly.

#### Customization

##### Bordered card style

```tsx
<Accordion className="rounded-lg border border-border px-4 [&>*:last-child]:border-b-0">
  …
</Accordion>
```

### Breadcrumb

A compact path trail with a clear current location.

Page: https://latheui.dev/components/breadcrumb
Install: npx shadcn@latest add @latheui/breadcrumb

#### Usage

```tsx
import { Breadcrumb } from "@/components/ui/breadcrumb"
export default function Demo(){return <Breadcrumb items={[{label:"Library",href:"/components"},{label:"Navigation",href:"/components"},{label:"Breadcrumb"}]}/>}
```

#### Props of Breadcrumb

- `items` (required): `BreadcrumbItem[]`. Ordered labels and optional hrefs. The last item is current.
- `onItemClick`: `(item, index, event) => void`. Called when a linked item is clicked. Call event.preventDefault() to handle the navigation yourself.
- `aria-label`: `string`, default `"Breadcrumb"`. Navigation landmark name.

#### Accessibility

- The trail is a named navigation landmark containing an ordered list.
- The current item has aria-current="page"; separators are decorative.

#### Motion

- A level that is removed fades out while sliding a few pixels back toward the trail. A new level arrives the same way.
- With reduced motion, levels fade without sliding.

#### Customization

##### Composition

Combine the control with your own layout. Semantic colors follow the active theme.

### Command Palette (Pro)

A keyboard-first launcher. Search across grouped commands, move with the arrow keys, and run with Enter.

Page: https://latheui.dev/components/command-palette
Install: npx shadcn@latest add @latheui/command-palette

#### Usage

```tsx
import { CommandPalette, type CommandGroup } from "@/components/ui/command-palette"

const groups: CommandGroup[] = [
  {
    heading: "Go to",
    items: [
      { id: "home", label: "Home", onSelect: () => router.push("/") },
      { id: "settings", label: "Settings", keywords: ["preferences"], onSelect: () => router.push("/settings") },
    ],
  },
]

// Opens with Cmd+K or Ctrl+K.
export function Commands() {
  return <CommandPalette groups={groups} />
}
```

#### Props of CommandPalette

- `groups` (required): `CommandGroup[]`. Commands, grouped under headings.
- `open`: `boolean`. Controlled open state.
- `defaultOpen`: `boolean`, default `false`. Initial open state when uncontrolled.
- `onOpenChange`: `(open: boolean) => void`. Called when the palette opens or closes.
- `onSelect`: `(item: CommandItem) => void`. Called for any selected item, after the item's own onSelect.
- `hotkey`: `string | null`, default `"k"`. Letter that toggles the palette with Cmd or Ctrl. null disables it.
- `placeholder`: `string`, default `"Type a command or search…"`. Input placeholder and accessible name.
- `label`: `string`, default `"Command palette"`. Accessible name of the dialog.
- `emptyMessage`: `ReactNode`, default `"No results found."`. Shown when nothing matches.
- `loading`: `boolean`, default `false`. Replaces the list with placeholder rows.
- `closeOnSelect`: `boolean`, default `true`. Closes the palette after a command runs.
- `className`: `string`. Classes for the panel.

#### Props of CommandItem

- `id` (required): `string`. Unique across all groups.
- `label` (required): `string`. Visible text. The search matches it, the keywords and the shortcut keys.
- `icon`: `ReactNode`. Shown before the label.
- `shortcut`: `string[]`. Optional shortcut hint. Nothing is shown without it. Typing its keys finds the item; binding the keys is up to you.
- `keywords`: `string[]`. Extra search terms.
- `disabled`: `boolean`. Shown but not selectable.
- `onSelect`: `() => void`. Runs when the item is chosen.

#### Keyboard

- Ctrl+K / ⌘K: Opens or closes the palette (configurable with hotkey).
- ArrowDown / ArrowUp: Moves the highlight, wrapping at the ends. Disabled items are skipped.
- Home / End: Moves to the first or last result.
- Enter: Runs the highlighted command.
- Escape: Closes the palette and returns focus to where it was.

#### Accessibility

- The input is a combobox that controls a listbox. Focus stays in the input, and the highlighted option is exposed with aria-activedescendant.
- The number of results is announced as you type through a status region.
- It is built on Radix Dialog, so focus is trapped while open and restored on close.
- Enter is ignored while an IME composition is in progress, so confirming a character does not run a command.
- Every command in the palette should also be reachable through the visible interface. The palette is a shortcut, not the only route.

#### Motion

- The panel drops 8px into place with the smooth spring. The highlight slides between rows.
- With reduced motion, the panel fades and the highlight jumps.

#### Customization

##### Open it from a button

Control the open state to add your own trigger alongside the shortcut.

```tsx
const [open, setOpen] = React.useState(false)

<Button variant="outline" onClick={() => setOpen(true)}>Search</Button>
<CommandPalette open={open} onOpenChange={setOpen} groups={groups} />
```

##### Smarter matching

Search is a case-insensitive match of every typed word against the label and keywords, or of the typed keys against the start of the shortcut. Replace the matches function at the top of the file to plug in fuzzy search.

```tsx
function matches(item: CommandItem, query: string) {
  return fuzzyScore(item.label, query) > 0.4
}
```

### Dropdown Menu

A menu of actions opened from a button, with submenus, checkbox and radio items, keyboard shortcut hints and type-ahead.

Page: https://latheui.dev/components/dropdown-menu
Install: npx shadcn@latest add @latheui/dropdown-menu

#### Usage

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

export function Example() {
  return (
    <DropdownMenu>
      <DropdownMenuTrigger asChild>
        <Button variant="outline">Options</Button>
      </DropdownMenuTrigger>
      <DropdownMenuContent>
        <DropdownMenuItem onSelect={rename}>Rename</DropdownMenuItem>
        <DropdownMenuItem destructive onSelect={remove}>
          Delete
        </DropdownMenuItem>
      </DropdownMenuContent>
    </DropdownMenu>
  )
}
```

#### Props of DropdownMenu

Also accepts Radix DropdownMenu.Root props such as modal and dir.

- `open`: `boolean`. Controlled open state.
- `defaultOpen`: `boolean`, default `false`. Initial open state when uncontrolled.
- `onOpenChange`: `(open: boolean) => void`. Called when the menu opens or closes.

#### Props of DropdownMenuContent

Also accepts Radix DropdownMenu.Content props.

- `align`: `"start" | "center" | "end"`, default `"start"`. Alignment against the trigger.
- `side`: `"top" | "right" | "bottom" | "left"`, default `"bottom"`. Preferred side. Flips when there is no room.
- `sideOffset`: `number`, default `6`. Gap between trigger and menu in pixels.

#### Props of DropdownMenuItem

Also accepts Radix DropdownMenu.Item props.

- `onSelect`: `(event: Event) => void`. Called when the item is chosen. Call event.preventDefault() to keep the menu open.
- `destructive`: `boolean`, default `false`. Styles the item as a destructive action.
- `shortcut`: `string | string[]`. Shortcut hint on the right, drawn with Kbd: "mod+d" shows ⌘D on Apple platforms and Ctrl+D elsewhere. Display only; bind the key yourself.
- `disabled`: `boolean`, default `false`. Skipped by pointer and keyboard.

#### Props of DropdownMenuCheckboxItem

- `checked`: `boolean | "indeterminate"`. Checked state.
- `onCheckedChange`: `(checked: boolean) => void`. Called when toggled.

#### Props of DropdownMenuRadioGroup, DropdownMenuRadioItem

- `value`: `string`. On the group: the selected value. On an item: its value.
- `onValueChange`: `(value: string) => void`. On the group: called when the selection changes.

#### Props of DropdownMenuSub

Wraps a DropdownMenuSubTrigger and its DropdownMenuSubContent. Also accepts Radix DropdownMenu.Sub props.

- `open`: `boolean`. Controlled open state of the submenu.
- `defaultOpen`: `boolean`, default `false`. Initial open state when uncontrolled.
- `onOpenChange`: `(open: boolean) => void`. Called when the submenu opens or closes.

#### Props of DropdownMenuSubContent

Also accepts Radix DropdownMenu.SubContent props.

- `sideOffset`: `number`, default `4`. Gap between the parent menu and the submenu in pixels.
- `alignOffset`: `number`, default `-5`. Shifts the submenu so its first item lines up with the trigger.

#### Props of DropdownMenuLabel, DropdownMenuSeparator

A non-interactive heading and a divider.

#### Keyboard

- Enter / Space / ArrowDown: On the trigger: opens the menu and focuses the first item.
- ArrowDown / ArrowUp: Moves between items.
- Home / End: Moves to the first or last item.
- A–Z: Type-ahead: moves to the next item starting with the typed characters.
- Enter / Space: Activates the focused item.
- ArrowRight: On a submenu trigger: opens the submenu and focuses its first item.
- ArrowLeft: In a submenu: closes it and returns focus to its trigger.
- Escape: Closes the menu and returns focus to the trigger.

#### Accessibility

- Built on Radix DropdownMenu, which implements the WAI-ARIA menu button pattern, including roving focus and type-ahead.
- Use a menu for actions. For choosing a form value, use a select; for navigation, use links.
- Disabled items stay visible and are announced as disabled, which is better than removing them when people expect to find them.
- The menu never grows taller than the space available; it scrolls instead.
- Submenus open on hover and with ArrowRight. While the pointer travels toward an open submenu, a safe area between it and the submenu stops items it crosses from taking over, so a diagonal move does not need to be precise.
- Shortcut hints read as words to screen readers, such as "Command D", not as symbols.

#### Motion

- The menu scales from 95% from the corner nearest the trigger with the snappy spring, and fades out in 160ms.
- Submenus scale from 96% from the edge nearest their trigger.
- With reduced motion, menus only fade.

#### Customization

##### Align to the right edge

```tsx
<DropdownMenuContent align="end" className="w-56">…</DropdownMenuContent>
```

### Hover Tabs (Pro)

Titles beside a panel. Point at a title, or reach it by keyboard, to show its content.

Page: https://latheui.dev/components/hover-tabs
Install: npx shadcn@latest add @latheui/hover-tabs

#### Usage

```tsx
import { HoverTabs } from "@/components/ui/hover-tabs"

const items = [
  { value: "plan", title: "Plan", description: "Scope the work.", image: { src: "/plan.png", alt: "Planning board" } },
  { value: "build", title: "Build", description: "Write and review.", image: { src: "/build.png", alt: "Code review" } },
]

export function Tour() {
  return <HoverTabs label="How it works" items={items} />
}
```

#### Props of HoverTabs

Also accepts native div attributes.

- `items` (required): `HoverTabItem[]`. The tabs, in order.
- `label` (required): `string`. Accessible name of the list.
- `value`: `string`. Controlled active item.
- `defaultValue`: `string`, default `first item`. Active item at first when uncontrolled.
- `onValueChange`: `(value: string) => void`. Called when the active item changes.

#### Props of HoverTabItem

- `value` (required): `string`. Unique among the items.
- `title` (required): `string`. The tab's text.
- `description`: `ReactNode`. A line under the title.
- `image`: `{ src: string; alt: string }`. Shown in the panel.
- `content`: `ReactNode`. Shown in the panel instead of the image.

#### Keyboard

- Tab: Moves to the active tab, then on to the panel's content.
- ArrowDown / ArrowUp: Moves to the next or previous tab and shows it, wrapping at the ends.
- Home / End: Moves to the first or last tab.

#### Accessibility

- It is a vertical tab list with one panel. Tabs activate on focus, which matches what hovering does for a pointer.
- Hover only reacts to a mouse. On touch, a tap selects a tab.
- The list stacks above the panel on small screens.
- Because tabs change on hover, keep panels to supporting visuals. Do not put controls in a panel that a passing pointer could take away.

#### Motion

- One highlight travels between titles and keeps its velocity when you change direction.
- The panel's content cross-fades, with the incoming content settling from a slight zoom.
- With reduced motion the highlight jumps and the content swaps without the zoom.

#### Customization

##### Controlled, with content panels

```tsx
const [tab, setTab] = React.useState("speed")

<HoverTabs
  label="Performance"
  value={tab}
  onValueChange={setTab}
  items={[
    { value: "speed", title: "Fast", content: <SpeedChart /> },
    { value: "uptime", title: "Reliable", content: <UptimeChart /> },
  ]}
/>
```

### Magnify Dock (Pro)

A row of items that swell under the pointer and settle back, with a label over the one you point at and a hop when clicked.

Page: https://latheui.dev/components/magnify-dock
Install: npx shadcn@latest add @latheui/magnify-dock

#### Usage

```tsx
import { MagnifyDock } from "@/components/ui/magnify-dock"

export function Apps() {
  return (
    <MagnifyDock
      label="Apps"
      items={[
        { id: "files", label: "Files", icon: <FolderIcon />, href: "/files" },
        { id: "mail", label: "Mail", icon: <MailIcon />, href: "/mail", active: true },
      ]}
    />
  )
}
```

#### Props of MagnifyDock

Also accepts native nav attributes.

- `items` (required): `{ id: string; label: string; icon: ReactNode; href?: string; onClick?: () => void; active?: boolean }[]`. The items. With href an item is a link; active adds a small dot beneath it.
- `label` (required): `string`. Accessible name for the dock.
- `size`: `number`, default `48`. Size of an item at rest, in px.
- `magnified`: `number`, default `80`. Size of the item under the pointer, in px.
- `range`: `number`, default `140`. How far from the pointer items still grow, in px.
- `gap`: `number`, default `10`. Space between items, in px.
- `radius`: `number | string`, default `14`. Item corners.
- `bounce`: `boolean`, default `true`. A small hop when an item is clicked.
- `stiffness`: `number`, default `380`. Spring stiffness for the swell. Higher is quicker.
- `damping`: `number`, default `28`. Spring damping for the swell. Lower is bouncier.
- `shelf`: `"bordered" | "plain" | "none" | "morph"`, default `"bordered"`. The surface behind the items: a panel with or without an outline, nothing, or an outlined shelf that rounds up around each item as it grows.

#### Keyboard

- Tab: Moves into the dock and through its items. The focused item grows and shows its label.
- ArrowRight / ArrowLeft: Moves to the next or previous item.

#### Accessibility

- The dock is a named navigation landmark. Items are links or buttons named by their labels.
- Labels show for keyboard focus as well as hover.
- With reduced motion items stay their resting size and do not hop.

#### Motion

- Each item's size follows a cosine of its distance from the pointer, on a spring, so neighbours rise and fall smoothly.
- A click hops the item 18px and back over 550ms.

#### Customization

##### A subtle dock

```tsx
<MagnifyDock label="Tools" items={items} size={40} magnified={56} range={100} bounce={false} />
```

### Mega Menu (Pro)

A navigation bar whose items open wide panels of grouped links. One panel resizes between items, and a safe triangle keeps it steady on a diagonal path.

Page: https://latheui.dev/components/mega-menu
Install: npx shadcn@latest add @latheui/mega-menu

#### Usage

```tsx
import { MegaMenu, type MegaMenuItem } from "@/components/ui/mega-menu"

const items: MegaMenuItem[] = [
  {
    label: "Product",
    sections: [
      {
        heading: "Features",
        links: [
          { title: "Intake", description: "Bring requests in from every tool you use", href: "/intake" },
          { title: "Plan and monitor", description: "Follow work from idea to launch", href: "/plan" },
        ],
      },
      { heading: "More", links: [{ title: "Changelog", href: "/changelog" }, { title: "Security", href: "/security" }] },
    ],
  },
  { label: "Pricing", href: "/pricing" },
]

export function Header() {
  return <MegaMenu items={items} />
}
```

#### Props of MegaMenu

Also accepts Radix NavigationMenu root props, such as delayDuration. An item's value is its label, so value="Product" opens that panel.

- `items` (required): `MegaMenuItem[]`. Top-level items, in order.
- `label`: `string`, default `"Main"`. Accessible name of the navigation landmark.
- `renderLink`: `(link: { href, className, children }) => ReactElement`, default `an <a>`. Renders every link. Return your router's link here.
- `safeTriangle`: `boolean`, default `true`. While the pointer moves from an open item toward its panel, other items it crosses do not take over and the gap does not close the panel.
- `safeTriangleTimeout`: `number`, default `300`. Milliseconds the pointer may rest on its way before the item under it takes over.
- `showSafeTriangle`: `boolean`, default `false`. Draws the triangle while it is active. For tuning and demos.

#### Props of MegaMenuItem

- `label` (required): `string`. Text in the bar.
- `href`: `string`. Makes the item a plain link. Used when there are no sections.
- `sections`: `MegaMenuSection[]`. Columns of the panel: { heading?, links }.

#### Props of MegaMenuLink

- `title` (required): `string`. Link text.
- `href` (required): `string`. Destination.
- `description`: `string`. A line under the title. Sections without descriptions are drawn as a compact list.
- `icon`: `ReactNode`. Shown before the title.

#### Keyboard

- Tab: Moves through the bar, and through an open panel's links.
- Enter / Space: Opens or closes an item's panel.
- ArrowLeft / ArrowRight: Moves between items in the bar.
- ArrowDown: Moves from an open item into its panel.
- Escape: Closes the panel and returns focus to its item.

#### Accessibility

- It is a navigation landmark built on Radix NavigationMenu. Items with panels are buttons that report whether they are expanded.
- Panels open on hover after a short delay and also on click, so they work on touch and for people who cannot hover precisely.
- Links are real links: they can be opened in a new tab and are found by screen reader link lists.
- On narrow screens a panel stacks its sections and never grows wider than the screen. For phones, pair it with a drawer.
- The safe triangle only follows a mouse. Clicks, touch and the keyboard switch panels at once.

#### Motion

- The panel fades and scales in, and its width and height ease between items over 200ms. The chevron turns.
- With reduced motion the panel appears and resizes at once.
- The safe triangle narrows as the pointer moves: each move must keep heading for the panel's near edge, with 8px of slack for a shaky hand.

#### Customization

##### Use your router's link

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

<MegaMenu
  items={items}
  renderLink={({ href, className, children }) => (
    <Link href={href} className={className}>
      {children}
    </Link>
  )}
/>
```

### Morph Menu (Pro)

A button that grows into its menu. The trigger stretches into a panel of options and shrinks back when one is chosen.

Page: https://latheui.dev/components/morph-menu
Install: npx shadcn@latest add @latheui/morph-menu

#### Usage

```tsx
import { CopyIcon, PencilIcon, Trash2Icon } from "lucide-react"
import { MorphMenu } from "@/components/ui/morph-menu"

export function FileActions() {
  return (
    <MorphMenu
      label="Options"
      onSelect={(item) => console.log(item.id)}
      items={[
        { id: "rename", label: "Rename", icon: <PencilIcon /> },
        { id: "duplicate", label: "Duplicate", icon: <CopyIcon />, shortcut: "⌘D" },
        { id: "delete", label: "Delete", icon: <Trash2Icon />, destructive: true, separator: true },
      ]}
    />
  )
}
```

#### Props of MorphMenu

- `label` (required): `string`. The trigger's text. It stays at the top of the open menu.
- `items` (required): `MorphMenuItem[]`. The options, in order.
- `onSelect`: `(item) => void`. Called with the chosen item. The menu then closes.
- `icon`: `ReactNode`. Shown before the label.
- `align`: `"start" | "end"`, default `"start"`. The edge of the trigger the menu grows from.
- `width`: `number`, default `264`. Width of the open menu in px.
- `open / defaultOpen`: `boolean`. Controlled or initial state.
- `onOpenChange`: `(open: boolean) => void`. Called when the menu opens or closes.

#### Props of MorphMenuItem

- `id` (required): `string`. Unique among the items.
- `label` (required): `string`. Row text.
- `description`: `string`. A second line under the label.
- `icon`: `ReactNode`. Shown before the label.
- `shortcut`: `string`. A key hint at the end of the row. Display only.
- `href`: `string`. Makes the row a link.
- `destructive`: `boolean`. Colors the row as a destructive action.
- `separator`: `boolean`. Draws a divider above the row.
- `disabled`: `boolean`. Skipped by the keyboard and ignores clicks.

#### Keyboard

- Enter / Space / Arrow Down: On the button, opens the menu on the first item.
- Arrow Up: On the button, opens the menu on the last item.
- Arrow Up / Arrow Down / Home / End: Moves between items, skipping disabled ones and wrapping around.
- Enter / Space: Chooses the item.
- Escape: Closes the menu and returns focus to the button.

#### Accessibility

- The trigger is a button with aria-haspopup, aria-expanded and aria-controls. The panel is a menu of menuitems, named by the label.
- The copy of the trigger at the top of the open menu is hidden from assistive tech; Escape or Tab closes the menu.
- Disabled items are marked aria-disabled and skipped by the arrow keys.
- A press outside the menu closes it.

#### Motion

- The trigger's surface stretches into the panel on a spring (stiffness 430, damping 36), its corners easing from a pill into a card. Closing runs it backwards into the button.
- Items arrive 22ms apart. A highlight slides between them on the hover spring, following the pointer and the arrow keys alike.
- With reduced motion, the menu fades in place.

#### Customization

##### A wider menu from the right

```tsx
<MorphMenu label="Account" align="end" width={320} items={items} />
```

### Navbar (Pro)

A top navigation bar with a hover pill that slides between links, an underline under the current page, a frosted look once scrolled, and a menu on narrow screens.

Page: https://latheui.dev/components/navbar
Install: npx shadcn@latest add @latheui/navbar

#### Usage

```tsx
import Link from "next/link"
import { usePathname } from "next/navigation"
import { Button } from "@/components/ui/button"
import { Navbar } from "@/components/ui/navbar"

const links = [
  { label: "Product", href: "/product" },
  { label: "Changelog", href: "/changelog", badge: "New" },
  { label: "Pricing", href: "/pricing" },
]

export function SiteHeader() {
  const pathname = usePathname()
  return (
    <Navbar
      brand={<Link href="/">Fieldwork</Link>}
      links={links}
      current={pathname}
      hideOnScroll
      actions={<Button size="sm">Get started</Button>}
      renderLink={(link, { children, ...props }) => <Link {...props}>{children}</Link>}
    />
  )
}
```

#### Props of Navbar

Also accepts header props.

- `links` (required): `{ label, href, badge? }[]`. The links, in order.
- `brand`: `ReactNode`. Your logo or name, on the left.
- `current`: `string`. The href of the current page. It gets the underline and aria-current.
- `actions`: `ReactNode`. Buttons on the right. In the narrow menu they sit under the links.
- `label`: `string`, default `"Main"`. Accessible name of the navigation landmark.
- `position`: `"sticky" | "fixed" | "static"`, default `"sticky"`. sticky and fixed stay at the top while the page scrolls.
- `hideOnScroll`: `boolean`, default `false`. Slides away while scrolling down, back on the way up.
- `container`: `RefObject<HTMLElement>`. The element that scrolls, when it is not the page.
- `renderLink`: `(link, props) => ReactNode`. Renders every link. Spread props onto your router's link; children is the label.

#### Keyboard

- Tab: Moves through the brand, links and actions. The focused link gets the hover pill.
- Enter / Space: On the menu button, opens or closes the narrow menu.
- Escape: Closes the narrow menu and returns focus to its button.

#### Accessibility

- Links sit in a nav landmark with its own name, and the current one has aria-current="page".
- The menu button says whether it opens or closes the menu, and points at the menu with aria-controls and aria-expanded.
- The underline is not the only sign of the current page: its text is also full strength while the others are muted.
- A press outside the open menu closes it.

#### Motion

- The hover pill slides between links on the hover spring, the stiffest Lathe has, so it keeps up with a fast pointer.
- Hide on scroll slides the bar up over 300ms once the page is 80px down, and ignores scrolls under 4px so a trackpad does not make it flicker. The frosted background fades in on the same timing.
- The menu opens on the smooth spring with its rows arriving 30ms apart, and the menu icon's lines turn into a cross.
- With reduced motion, the bar and menu appear and disappear without moving.

#### Customization

##### Always solid

```tsx
<Navbar className="border-border bg-background" links={links} />
```

##### Fixed over a hero image

With position="fixed" the bar floats over the page. Add top padding to the content under it.

```tsx
<Navbar position="fixed" links={links} brand={<Logo />} />
<main className="pt-14">…</main>
```

### Pagination

A page navigator with compact and neighboring ranges, text-only and outline styles, and optional sliding numbers.

Page: https://latheui.dev/components/pagination
Install: npx shadcn@latest add @latheui/pagination

#### Usage

```tsx
import * as React from "react"
import { Pagination } from "@/components/ui/pagination"
export default function Demo(){const [page,setPage]=React.useState(1);return <div className="space-y-3"><Pagination page={page} pageCount={12} onPageChange={setPage}/><p role="status" className="text-center text-xs text-muted-foreground">Page {page} of 12</p></div>}
```

#### Props of Pagination

- `variant`: `"solid" | "text" | "outline"`, default `"solid"`. Text uses no background, including on hover. Outline uses bordered buttons.
- `density`: `"normal" | "compact"`, default `"normal"`. Compact uses smaller buttons and removes gaps between numbers.
- `layout`: `"compact" | "siblings" | "all" | "simple"`, default `"siblings"`. Show the first and last pages with the current page and its neighbors (1 … 3 4 5 … 12), keep a fixed five-slot range, show all pages, or use a page counter.
- `siblingCount`: `number`, default `1`. Pages shown on each side of the current page in the siblings layout, from 0 to 3.
- `animation`: `"none" | "slide"`, default `"none"`. Slide numbers left when moving forward and right when moving backward. Reduced motion skips the animation.
- `page` (required): `number`. Current page, starting at 1.
- `pageCount` (required): `number`. Total page count.
- `onPageChange` (required): `(page: number) => void`. Called when another page is requested.

#### Accessibility

- The current page has aria-current="page".
- Previous and next controls are disabled at boundaries and have explicit names.

#### Customization

##### Composition

Combine the control with your own layout. Semantic colors follow the active theme.

### Scroll Rail (Pro)

A horizontal section driven by vertical scrolling. The frame pins, the strip travels sideways through any content, and a counter reads 01, 1, or your own labels.

Page: https://latheui.dev/components/scroll-rail
Install: npx shadcn@latest add @latheui/scroll-rail

#### Usage

```tsx
import {
  ScrollRail,
  ScrollRailCounter,
  ScrollRailItem,
  ScrollRailProgress,
  ScrollRailTrack,
} from "@/components/ui/scroll-rail"

export function HowItWorks() {
  return (
    // offset keeps the pinned frame below a 64px fixed header.
    <ScrollRail label="How it works" offset={64}>
      <ScrollRailTrack>
        <ScrollRailItem width="28rem">Sketch</ScrollRailItem>
        <ScrollRailItem width="20rem">Tune</ScrollRailItem>
        <ScrollRailItem width="28rem">Ship</ScrollRailItem>
      </ScrollRailTrack>
      <div className="flex items-center gap-4 px-6">
        <ScrollRailCounter format="pad" />
        <ScrollRailProgress className="flex-1" />
      </div>
    </ScrollRail>
  )
}
```

#### Props of ScrollRail

Also accepts section props. Anything inside it goes in the pinned frame, beside the track.

- `label` (required): `string`. Accessible name of the rail.
- `container`: `RefObject<HTMLElement>`. The element that scrolls. The page when not set.
- `offset`: `number`, default `0`. Pixels covered by something fixed at the top, such as a header. The frame pins below it.
- `height`: `number | string`. Height of the pinned frame. Fills the space below offset when not set.
- `speed`: `number`, default `1`. Pixels of vertical scroll per pixel of sideways travel. 2 moves the rail half as fast.
- `smooth`: `boolean | { stiffness, damping, mass }`, default `true`. Eases the strip after the scroll on a spring instead of moving in lockstep.
- `snap`: `boolean`, default `false`. Once scrolling stops, settles on the nearest item.
- `pin`: `"auto" | "always" | "never"`, default `"auto"`. auto pins whenever motion is allowed and the rail is at least breakpoint wide, including on phones, and is a swipeable strip otherwise.
- `breakpoint`: `number`, default `0`. Width in px below which auto becomes a strip. 0 pins at every width.
- `gap`: `number`, default `24`. Space between items in px.
- `onIndexChange`: `(index: number) => void`. Called as a new item comes into focus.
- `frameClassName`: `string`. Classes for the pinned frame.

#### Props of ScrollRailItem

A list item. Put anything in it.

- `width`: `string`, default `"min(26rem, 78vw)"`. Width as any CSS length. Items can differ; none gets wider than the frame.

#### Props of ScrollRailCounter

- `format`: `"pad" | "number" | string[] | (index, count) => ReactNode`, default `"pad"`. 01 / 05, 1 / 5, one label per item, or your own text. index counts from 0.
- `showTotal`: `boolean`. Shows the total after the position. On for "pad" and "number", off otherwise.
- `separator`: `ReactNode`, default `" / "`. Between the position and the total.

#### Props of ScrollRailProgress, ScrollRailDots

A line that fills from the first item to the last, and one dot per item that scrolls to it when clicked.

- `format`: `same as the counter`, default `"number"`. Dots only: names each dot for assistive tech.

#### Props of useScrollRail

For your own readouts and controls, inside a ScrollRail.

- `index`: `number`. The item in focus, from 0.
- `count`: `number`. How many items there are.
- `progress`: `MotionValue<number>`. 0 at the first item, 1 at the last.
- `pinned`: `boolean`. Whether the page's scroll drives the rail right now.
- `scrollTo`: `(index: number) => void`. Scrolls to bring an item into focus.

#### Keyboard

- Tab: Moves through the items' content. A focused item off to the side scrolls into view.
- Enter / Space: On a dot, scrolls to its item.

#### Accessibility

- The rail is a labelled section described as a carousel, and each item as a slide with its set size.
- The counter announces its position as plain text (Item 2 of 5) whatever format it shows.
- Content stays in normal reading order, so everything is reachable by keyboard and screen reader without scrolling.
- With reduced motion, auto becomes a plain sideways strip instead of a scroll-driven one.

#### Motion

- The strip follows the scroll on a soft spring (stiffness 260, damping 36), so a flick of the wheel glides instead of stepping. Turn it off with smooth={false}, or pass your own spring.
- The counter rolls up as you move forward and down as you move back.
- The current dot stretches and slides on the snappy spring.
- With snap, the rail settles on the nearest item 140ms after scrolling stops.

#### Customization

##### Slower travel under a fixed header

```tsx
<ScrollRail label="Work" offset={64} speed={1.6} snap>
  …
</ScrollRail>
```

##### Chapter names instead of numbers

```tsx
<ScrollRailCounter format={["Intro", "Design", "Build", "Ship"]} />
<ScrollRailCounter format={(i, count) => `Step ${i + 1} of ${count}`} />
```

##### A readout of your own

```tsx
function Caption({ titles }: { titles: string[] }) {
  const { index, scrollTo } = useScrollRail()
  return <button onClick={() => scrollTo(index + 1)}>Next: {titles[index + 1]}</button>
}
```

### Sidebar Menu (Pro)

A button that opens a panel of options from the side. Rows arrive one after another, a highlight follows the pointer, and groups open in place.

Page: https://latheui.dev/components/sidebar-menu
Install: npx shadcn@latest add @latheui/sidebar-menu

#### Usage

```tsx
import { HomeIcon, InboxIcon, SettingsIcon } from "lucide-react"
import { SidebarMenu, type SidebarMenuSection } from "@/components/ui/sidebar-menu"

const sections: SidebarMenuSection[] = [
  {
    items: [
      { id: "home", label: "Home", href: "/", icon: <HomeIcon /> },
      { id: "inbox", label: "Inbox", href: "/inbox", icon: <InboxIcon />, badge: 12 },
    ],
  },
  {
    heading: "Account",
    items: [{ id: "settings", label: "Settings", href: "/settings", icon: <SettingsIcon /> }],
  },
]

export function MobileNav({ current }: { current: string }) {
  return <SidebarMenu label="Menu" sections={sections} current={current} />
}
```

#### Props of SidebarMenu

- `label` (required): `string`. Title of the panel, and the default trigger's name.
- `sections` (required): `{ heading?, items }[]`. Groups of items, in order.
- `current`: `string`. The id or href of the current item. It gets a solid highlight and aria-current.
- `onSelect`: `(item) => void`. Called when an item is chosen. The panel then closes.
- `side`: `"left" | "right"`, default `"left"`. The edge the panel slides from.
- `open / defaultOpen`: `boolean`. Controlled or initial state.
- `onOpenChange`: `(open: boolean) => void`. Called when the panel opens or closes.
- `header`: `ReactNode`. Top of the panel, in place of the title. The title stays for screen readers.
- `footer`: `ReactNode`. Pinned to the bottom, such as an account row.
- `trigger`: `ReactElement`. Your own button. A menu icon button when not set.
- `width`: `number`, default `300`. Panel width in px, never wider than the screen.
- `renderLink`: `(item, props) => ReactNode`. Renders items with an href. Spread props onto your router's link.

#### Props of SidebarMenuItem

- `id` (required): `string`. Unique across the menu.
- `label` (required): `string`. Row text.
- `href`: `string`. Makes the row a link. Otherwise it is a button.
- `icon`: `ReactNode`. Shown before the label.
- `badge`: `ReactNode`. Shown at the end, such as a count.
- `items`: `SidebarMenuItem[]`. One level of sub-items, shown in a group that opens and closes.
- `disabled`: `boolean`. Dims the row and ignores it.

#### Keyboard

- Tab / Shift + Tab: Moves through the rows. Focus stays inside the panel while it is open.
- Enter / Space: Chooses a row, or opens and closes a group.
- Escape: Closes the panel and returns focus to the trigger.

#### Accessibility

- Built on Radix Dialog: focus moves into the panel, stays there, and returns to the trigger on close.
- The panel is titled with label, and its rows sit in a nav landmark of the same name.
- Groups are buttons with aria-expanded. The current item has aria-current.
- The current item is marked by a bar and a filled background, not by color alone.

#### Motion

- The panel slides in on the smooth spring while the page behind it dims.
- Rows arrive 25ms apart from the side the panel came from.
- The hover highlight slides between rows on the hover spring. Groups open by growing to their height, with the chevron turning.
- With reduced motion, the panel fades and nothing slides.

#### Customization

##### From the right, with your own button

```tsx
<SidebarMenu
  side="right"
  label="Account"
  sections={sections}
  trigger={<Button variant="outline">Account</Button>}
/>
```

##### Next.js links

```tsx
<SidebarMenu
  label="Menu"
  sections={sections}
  current={pathname}
  renderLink={(item, { children, ...props }) => <Link {...props}>{children}</Link>}
/>
```

### Stepper (Pro)

A numbered workflow trail with completed, current and upcoming steps.

Page: https://latheui.dev/components/stepper
Install: npx shadcn@latest add @latheui/stepper

#### Usage

```tsx
import * as React from "react"
import { Stepper } from "@/components/ui/stepper"
export default function Demo(){const [current,setCurrent]=React.useState(1);return <Stepper className="w-full max-w-xs" current={current} onStepChange={setCurrent} steps={[{label:"Workspace",description:"Name your studio."},{label:"Invite your team",description:"Bring your collaborators."},{label:"Ready to create",description:"Make something considered."}]}/>}
```

#### Props of Stepper

- `steps` (required): `StepperStep[]`. Ordered labels and optional descriptions.
- `current` (required): `number`. Current step index, starting at 0.
- `onStepChange`: `(index: number) => void`. Optional click handler. Apply your workflow rules in the callback.

#### Accessibility

- Steps use an ordered list; the current one has aria-current="step".
- Completion is conveyed in text and with a checkmark.

#### Customization

##### Composition

Combine the control with your own layout. Semantic colors follow the active theme.

### Tabs

Switches between panels in the same context. The active indicator slides between tabs instead of jumping.

Page: https://latheui.dev/components/tabs
Install: npx shadcn@latest add @latheui/tabs

#### Usage

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

export function Settings() {
  return (
    <Tabs defaultValue="general">
      <TabsList aria-label="Settings">
        <TabsTrigger value="general">General</TabsTrigger>
        <TabsTrigger value="security">Security</TabsTrigger>
      </TabsList>
      <TabsContent value="general">General settings</TabsContent>
      <TabsContent value="security">Security settings</TabsContent>
    </Tabs>
  )
}
```

#### Props of Tabs

Also accepts Radix Tabs.Root props such as orientation and activationMode.

- `value`: `string`. Controlled active tab.
- `defaultValue`: `string`. Initial active tab when uncontrolled. Set one, or no tab starts selected.
- `onValueChange`: `(value: string) => void`. Called when the active tab changes.
- `variant`: `"underline" | "pill"`, default `"underline"`. Indicator style, applied to the list and triggers.

#### Props of TabsList

Wraps the triggers. Give it an aria-label.

#### Props of TabsTrigger

- `value` (required): `string`. Matches the value of a TabsContent.
- `disabled`: `boolean`, default `false`. Skipped by pointer and arrow keys.

#### Props of TabsContent

- `value` (required): `string`. The tab this panel belongs to.

#### Keyboard

- Tab: Moves focus to the active tab, then into its panel.
- ArrowLeft / ArrowRight: Moves to and activates the previous or next tab.
- Home / End: Moves to the first or last tab.

#### Accessibility

- Built on Radix Tabs, which implements the WAI-ARIA tabs pattern with roving focus.
- Give TabsList an aria-label that says what the tabs switch between.
- The list scrolls sideways when the tabs do not fit, so no tab is ever unreachable on a narrow screen.
- Tabs change content in place. For moving between pages, use links instead.

#### Motion

- The indicator moves between tabs with the snappy spring. Panels fade in over 200ms.
- With reduced motion, the indicator jumps to the new tab.

#### Customization

##### Restyle the indicator

The indicator is the motion.span inside TabsTrigger. Change its classes there.

```tsx
className={
  underline
    ? "absolute inset-x-0 bottom-0 h-0.5 bg-chart-1"
    : "absolute inset-0 rounded-md bg-background shadow-sm ring-1 ring-border"
}
```

## Overlays

### Context Menu

A right-click menu of actions, with submenus, keyboard shortcut hints, disabled items and destructive actions.

Page: https://latheui.dev/components/context-menu
Install: npx shadcn@latest add @latheui/context-menu

#### Usage

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

export function Canvas() {
  return (
    <ContextMenu>
      <ContextMenuTrigger>
        <button type="button" className="h-40 w-full rounded-lg border border-dashed">
          Project canvas
        </button>
      </ContextMenuTrigger>
      <ContextMenuContent>
        <ContextMenuItem shortcut="mod+d" onSelect={duplicate}>Duplicate</ContextMenuItem>
        <ContextMenuSeparator />
        <ContextMenuItem destructive onSelect={remove}>Remove</ContextMenuItem>
      </ContextMenuContent>
    </ContextMenu>
  )
}
```

#### Props of ContextMenuTrigger

Wraps one focusable element, which opens the menu on right-click, long-press, the ContextMenu key or Shift+F10.

- `disabled`: `boolean`, default `false`. Lets the browser's own context menu show instead.

#### Props of ContextMenuItem

Also accepts Radix ContextMenu.Item props.

- `onSelect`: `(event: Event) => void`. Called when the item is chosen. Call event.preventDefault() to keep the menu open.
- `shortcut`: `string | string[]`. Shortcut hint on the right, drawn with Kbd: "mod+d" shows ⌘D on Apple platforms and Ctrl+D elsewhere. Display only; bind the key yourself.
- `destructive`: `boolean`, default `false`. Styles the item as a destructive action.
- `disabled`: `boolean`, default `false`. Skipped by pointer and keyboard.

#### Props of ContextMenuSub

Wraps a ContextMenuSubTrigger and its ContextMenuSubContent. Also accepts Radix ContextMenu.Sub props.

#### Props of ContextMenuSubContent

Also accepts Radix ContextMenu.SubContent props.

- `sideOffset`: `number`, default `4`. Gap between the parent menu and the submenu in pixels.
- `alignOffset`: `number`, default `-5`. Shifts the submenu so its first item lines up with the trigger.

#### Keyboard

- Shift / F10: Opens the menu on the focused trigger. The ContextMenu key does too.
- ArrowDown / ArrowUp: Moves between items.
- Enter / Space: Activates the focused item.
- ArrowRight / ArrowLeft: Opens a submenu from its trigger, or closes it and goes back.
- Escape: Closes the menu.

#### Accessibility

- Built on Radix ContextMenu, which supplies menu semantics, roving focus, type-ahead and Escape to close.
- Right-click is not the only way in: the trigger opens the menu from the keyboard with Shift+F10 or the ContextMenu key, and with a long press on touch.
- Shortcut hints read as words to screen readers, such as "Command D", not as symbols.
- While the pointer travels toward an open submenu, a safe area between it and the submenu stops items it crosses from taking over.

#### Motion

- The menu and its submenus scale in from the pointer or their trigger with the snappy spring, and fade out.
- With reduced motion, they only fade.

#### Customization

##### Nested actions

```tsx
<ContextMenuSub>
  <ContextMenuSubTrigger>Move to</ContextMenuSubTrigger>
  <ContextMenuSubContent>
    {folders.map((folder) => (
      <ContextMenuItem key={folder.id} onSelect={() => move(folder)}>
        {folder.name}
      </ContextMenuItem>
    ))}
  </ContextMenuSubContent>
</ContextMenuSub>
```

### Dialog

A modal for a focused task or decision. Traps focus, closes on Escape, and scrolls when tall.

Page: https://latheui.dev/components/dialog
Install: npx shadcn@latest add @latheui/dialog

#### Usage

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

export function Example() {
  return (
    <Dialog>
      <DialogTrigger asChild>
        <Button>Open</Button>
      </DialogTrigger>
      <DialogContent>
        <DialogHeader>
          <DialogTitle>Title</DialogTitle>
          <DialogDescription>What this dialog is for.</DialogDescription>
        </DialogHeader>
      </DialogContent>
    </Dialog>
  )
}
```

#### Props of Dialog

Also accepts Radix Dialog.Root props such as modal.

#### Props of DialogContent

Also accepts Radix Dialog.Content props such as onEscapeKeyDown, onInteractOutside and onOpenAutoFocus.

- `hideClose`: `boolean`, default `false`. Hides the corner close button.
- `className`: `string`. Classes for the panel. Set max-w-* to change the width.

#### Props of DialogTrigger, DialogClose

Buttons that open and close the dialog. Use asChild to render your own Button.

#### Props of DialogHeader, DialogFooter, DialogTitle, DialogDescription

Layout and text parts. DialogTitle is required for an accessible name.

#### Keyboard

- Escape: Closes the dialog.
- Tab / Shift+Tab: Cycles through the focusable elements inside the dialog.

#### Accessibility

- Built on Radix Dialog. Focus moves into the dialog when it opens, stays inside while it is open, and returns to the trigger when it closes.
- The title names the dialog and the description describes it. If you leave the title out visually, keep one with the sr-only class.
- Content behind the dialog is hidden from assistive tech and cannot be scrolled.
- For a confirmation that must not be dismissed by accident, pass role="alertdialog" and handle onInteractOutside.
- The footer stacks vertically on small screens with the primary action on top, where it is easiest to reach.

#### Motion

- The panel scales from 96% and rises 8px with the smooth spring. The overlay fades in 160ms.
- With reduced motion, the panel and overlay only fade.

#### Customization

##### Wider panel

```tsx
<DialogContent className="max-w-2xl">…</DialogContent>
```

##### Keep it open on outside click

```tsx
<DialogContent onInteractOutside={(event) => event.preventDefault()}>…</DialogContent>
```

### Drawer

A panel that slides in from the bottom, left or right edge, drags away, and handles focus like a dialog.

Page: https://latheui.dev/components/drawer
Install: npx shadcn@latest add @latheui/drawer

#### Usage

```tsx
import {
  Drawer,
  DrawerContent,
  DrawerDescription,
  DrawerHeader,
  DrawerTitle,
  DrawerTrigger,
} from "@/components/ui/drawer"

export function Example() {
  return (
    <Drawer>
      <DrawerTrigger asChild>
        <Button>Open</Button>
      </DrawerTrigger>
      <DrawerContent>
        <DrawerHeader>
          <DrawerTitle>Title</DrawerTitle>
          <DrawerDescription>What this drawer is for.</DrawerDescription>
        </DrawerHeader>
      </DrawerContent>
    </Drawer>
  )
}
```

#### Props of Drawer

Also accepts Radix Dialog.Root props.

#### Props of DrawerContent

Also accepts Radix Dialog.Content props.

- `side`: `"bottom" | "left" | "right"`, default `"bottom"`. The edge the drawer slides from.
- `dismissThreshold`: `number`, default `110`. Drag distance in pixels past which releasing closes the drawer.
- `className`: `string`. Classes for the panel.

#### Props of DrawerTrigger, DrawerClose, DrawerHeader, DrawerFooter, DrawerTitle, DrawerDescription

The same parts as Dialog. DrawerTitle is required for an accessible name.

#### Keyboard

- Escape: Closes the drawer.
- Tab / Shift+Tab: Cycles through the focusable elements inside the drawer.

#### Accessibility

- Built on Radix Dialog, so focus is trapped and restored and the page behind is inert.
- Dragging is an enhancement. Escape, the overlay and any DrawerClose button also close it, so always include a visible close or cancel action for people who cannot drag.
- Dragging starts from the handle on a bottom sheet, which leaves the body free to scroll and its text selectable. Side drawers do not have a handle and close with Escape, the overlay or a button.
- The bottom sheet is capped at 88% of the viewport height and respects the bottom safe area on phones.

#### Motion

- The panel slides from its edge with the gentle spring and follows the pointer while dragged.
- With reduced motion, the panel fades instead of sliding.

#### Customization

##### Full-width bottom sheet

The sheet is centered with a max width on large screens. Remove it for an edge-to-edge sheet.

```tsx
<DrawerContent className="max-w-none">…</DrawerContent>
```

### Hover Card

A quiet preview card for links, with delayed opening and collision-aware positioning.

Page: https://latheui.dev/components/hover-card
Install: npx shadcn@latest add @latheui/hover-card

#### Usage

```tsx
import { HoverCard, HoverCardTrigger, HoverCardContent } from "@/components/ui/hover-card"
export default function Demo(){return <HoverCard><HoverCardTrigger><a href="https://github.com" className="rounded-sm text-sm font-medium underline underline-offset-4 outline-none focus-visible:ring-2 focus-visible:ring-ring">@lathe-studio</a></HoverCardTrigger><HoverCardContent><p className="font-medium">Lathe Studio</p><p className="mt-1 text-muted-foreground">Small details. Considered interfaces.</p><p className="mt-3 text-xs text-muted-foreground">Building since 2026</p></HoverCardContent></HoverCard>}
```

#### Props of Hover Card

- `open / defaultOpen`: `boolean`. Controlled or initial visibility on the root.
- `onOpenChange`: `(open: boolean) => void`. Visibility callback.
- `openDelay`: `number`, default `150`. Milliseconds the pointer rests on the trigger before the card opens.
- `closeDelay`: `number`, default `100`. Milliseconds after the pointer leaves the trigger and the card before it closes.
- `children`: `ReactNode`. Compose Root, Trigger and Content. Trigger slots one child.
- `side / align / sideOffset`: `Radix placement props`. Content placement and collision avoidance.

#### Keyboard

- Escape: Dismiss the surface.

#### Accessibility

- Hover content supplements a link; keep essential information available without hovering.
- Radix provides delayed dismissal and collision handling.

#### Motion

- The card scales up from its link with the snappy spring and fades in. It fades out a little smaller.
- With reduced motion it only fades.

#### Customization

##### Composition

Combine the control with your own layout. Semantic colors follow the active theme.

### Link Peek (Pro)

A link that previews where it goes: the page's image, title and site, sliding along under the pointer and leaning as it moves.

Page: https://latheui.dev/components/link-peek
Install: npx shadcn@latest add @latheui/link-peek

#### Usage

```tsx
import { LinkPeek } from "@/components/ui/link-peek"

export function Note() {
  return (
    <p>
      Read the{" "}
      <LinkPeek href="https://example.com/guide" preview={{ image: "/og.png", title: "The guide", description: "Everything in one place." }}>
        full guide
      </LinkPeek>
      .
    </p>
  )
}
```

#### Props of LinkPeek

Also accepts native anchor attributes.

- `href` (required): `string`. Where the link goes.
- `preview` (required): `{ title: string; image?: string; description?: string; site?: string; favicon?: string }`. What the card shows. The site defaults to the link's domain.
- `follow`: `boolean`, default `true`. The card slides along the link to stay under the pointer.
- `tilt`: `number`, default `6`. Degrees the card leans with the pointer's speed. 0 keeps it level.
- `side`: `"top" | "bottom"`, default `"top"`. Which side of the link the card opens on.
- `width`: `number`, default `288`. Width of the card in px.
- `cardClassName`: `string`. Extra classes for the card.

#### Keyboard

- Tab: Focusing the link opens its preview; moving focus away closes it.

#### Accessibility

- It is a real link: it navigates like any other, and the preview is an extra.
- The preview opens on keyboard focus as well as hover, after a short delay.
- Its image is decorative; the title and description are plain text.
- With reduced motion the card stays centered and level.

#### Motion

- The card follows the pointer on a spring (stiffness 380, damping 32) and leans by its speed, up to the tilt, on a softer spring.
- It opens and closes with Hover Card's scale and fade.

#### Customization

##### Below the link, without following

```tsx
<LinkPeek href={href} preview={preview} side="bottom" follow={false} tilt={0}>docs</LinkPeek>
```

### Popover

An anchored surface for small settings, forms and contextual details.

Page: https://latheui.dev/components/popover
Install: npx shadcn@latest add @latheui/popover

#### Usage

```tsx
import { Popover, PopoverTrigger, PopoverContent, PopoverClose } from "@/components/ui/popover"
import { Button } from "@/components/ui/button"
export default function Demo(){return <Popover><PopoverTrigger><Button variant="outline">View settings</Button></PopoverTrigger><PopoverContent aria-label="Preview settings"><p className="font-medium">Preview settings</p><p className="mt-1 text-muted-foreground">Changes apply to this workspace only.</p><PopoverClose {...{asChild:true}}><Button className="mt-4" size="sm">Done</Button></PopoverClose></PopoverContent></Popover>}
```

#### Props of Popover

- `open / defaultOpen`: `boolean`. Controlled or initial visibility on the root.
- `onOpenChange`: `(open: boolean) => void`. Visibility callback.
- `children`: `ReactNode`. Compose Root, Trigger and Content. Trigger slots one child.
- `side / align / sideOffset`: `Radix placement props`. Content placement and collision avoidance.

#### Keyboard

- Escape: Dismiss the surface.

#### Accessibility

- Radix manages focus, Escape dismissal and outside interaction.
- Give Content a label when it has no visible title.

#### Customization

##### Composition

Combine the control with your own layout. Semantic colors follow the active theme.

### Radial Menu (Pro)

A button whose actions fan out around it. Click one, or press, drag toward it and let go in a single movement.

Page: https://latheui.dev/components/radial-menu
Install: npx shadcn@latest add @latheui/radial-menu

#### Usage

```tsx
import { RadialMenu } from "@/components/ui/radial-menu"

export function Create() {
  return (
    <RadialMenu
      label="Create"
      items={[
        { id: "note", label: "Note", icon: <PenLineIcon /> },
        { id: "photo", label: "Photo", icon: <CameraIcon /> },
      ]}
      onSelect={(id) => create(id)}
    />
  )
}
```

#### Props of RadialMenu

Also accepts native div attributes.

- `items` (required): `{ id: string; label: string; icon: ReactNode; disabled?: boolean }[]`. The actions, clockwise from startAngle.
- `onSelect`: `(id: string) => void`. Called with the chosen action's id.
- `open`: `boolean`. Controlled: whether the actions are out.
- `defaultOpen`: `boolean`, default `false`. Start with the actions out.
- `onOpenChange`: `(open: boolean) => void`. Called when the menu opens or closes.
- `label` (required): `string`. Accessible name for the button and its menu.
- `children`: `ReactNode`. What the button shows. A plus that turns to a cross when open, by default.
- `radius`: `number`, default `84`. Distance from the button's center to each action's, in px.
- `itemSize`: `number`, default `44`. Size of each action in px.
- `startAngle`: `number`, default `-90`. Where the first action sits, in degrees. -90 is straight up.
- `arc`: `number`, default `360`. Degrees the actions spread across. Less than 360 draws the ring as an arc with rounded ends.
- `stagger`: `number`, default `22`. Milliseconds between one action appearing and the next.
- `curve`: `Curve`, default `snappy spring`. How actions fly out. Any curve from the Animation Lab.
- `duration`: `number`. Milliseconds, for curves that are not springs.

#### Keyboard

- Enter / Space / ArrowDown: Opens the menu and focuses the first action.
- ArrowUp: Opens the menu and focuses the last action.
- ArrowRight / ArrowLeft: Moves around the ring.
- Enter / Space: On an action, chooses it.
- Escape: Closes the menu and returns focus to the button.

#### Accessibility

- The button announces that it opens a menu, and whether it is open. The actions are menu items named by their labels.
- Every action can be reached by clicking or with the keyboard; the drag is a shortcut, not the only way.
- A press outside closes the menu.
- With reduced motion actions appear in place, without flying out.

#### Motion

- Actions fly out from the button on a snappy spring, 22ms apart, while the ring behind them grows and turns into place.
- One highlight rides the ring and turns, the short way round, to the hovered or aimed action. During a drag it follows the pointer's direction once the pointer is 26px from the center.

#### Customization

##### Reactions above a button

```tsx
<RadialMenu label="React" items={reactions} startAngle={-180} arc={180} radius={96} />
```

### Share Panel (Pro)

A Share button whose panel copies the link, sets access, and sends to people or channels.

Page: https://latheui.dev/components/share-panel
Install: npx shadcn@latest add @latheui/share-panel

#### Usage

```tsx
import { SharePanel } from "@/components/ui/share-panel"

export function ShareDocument({ doc }: { doc: { id: string; title: string; url: string } }) {
  return (
    <SharePanel
      title={doc.title}
      link={doc.url}
      access={[
        { value: "team", label: "Team only" },
        { value: "link", label: "Anyone with the link" },
      ]}
      people={recentPeople}
      onSend={({ people, access }) => api.share(doc.id, people, access)}
    />
  )
}
```

#### Props of SharePanel

- `title` (required): `string`. Name of the thing being shared, used in the panel's heading.
- `link` (required): `string`. The link Copy writes to the clipboard.
- `access` (required): `{ value: string; label: string; description?: string }[]`. Who can open the link.
- `defaultAccess`: `string`, default `first option`. Access level selected first.
- `people`: `{ id: string; name: string; avatar?: string }[]`, default `[]`. Recent collaborators. Initials are shown without an avatar.
- `channels`: `{ id: string; label: string; icon?: ReactNode }[]`, default `[]`. Other places to post the link.
- `onSend`: `({ people, access }) => void | Promise<void>`. Sends to the chosen people. A pending promise shows progress; a rejection shows its message.
- `onChannel`: `(id: string, access: string) => void | Promise<void>`. Posts to a channel, with progress on that button.
- `onCopy`: `(access: string) => void`. Called after the link is copied.
- `label`: `string`, default `"Share"`. Text of the trigger button.
- `align`: `"start" | "center" | "end"`, default `"end"`. Edge of the button the panel lines up with.
- `className`: `string`. Classes for the trigger button.

#### Keyboard

- Enter / Space: Opens the panel, or activates the focused control.
- Tab: Moves through copy, access, channels, people and send.
- ArrowUp / ArrowDown: Changes the access level.
- Escape: Closes the panel and returns focus to the button.

#### Accessibility

- It is built on Radix Popover: the panel is a labelled dialog, focus moves into it on open and back to the button on close.
- Access levels are native radio buttons. People are toggle buttons that report whether they are chosen.
- Copies, selections, channel results and the send confirmation are announced through a status region.
- Sending with nobody chosen explains what is missing in text; a failed send shows the error and keeps the panel open.
- People is a short list of recents, not a directory search. For inviting by email, use a dialog with a form.

#### Motion

- The panel scales in from the button. People chips slide as they are chosen, and sending swaps the panel for a confirmation with a check that pops in.
- With reduced motion the panel and the confirmation fade.

#### Customization

##### Link only

Leave out people and channels for a compact copy-and-access panel.

```tsx
<SharePanel
  title="Design review"
  link={url}
  label="Copy link"
  access={[{ value: "link", label: "Anyone with the link" }]}
/>
```

## Data

### Animated Number

A number that animates to new values: digits roll like an odometer, or the whole number counts up. Formats with Intl for currency, percent and more.

Page: https://latheui.dev/components/animated-number
Install: npx shadcn@latest add @latheui/animated-number

#### Usage

```tsx
import { AnimatedNumber } from "@/components/ui/animated-number"

export function Revenue({ value }: { value: number }) {
  return (
    <AnimatedNumber
      value={value}
      format={{ style: "currency", currency: "USD" }}
      className="text-3xl font-semibold"
    />
  )
}
```

#### Props of AnimatedNumber

Also accepts native span attributes. Font size and weight come from className.

- `value` (required): `number`. The number to display.
- `format`: `Intl.NumberFormatOptions`. Formatting options, such as currency, percent or fraction digits.
- `animation`: `"roll" | "count"`, default `"roll"`. roll turns each digit's column to its new value. count runs the whole number through the values in between.
- `from`: `number`. With count, the value shown first, counted from as the component mounts. Without it the number starts at value.
- `duration`: `number`, default `1.6`. With count, seconds each change takes.
- `locale`: `string`, default `"en-US"`. Locale for grouping and symbols. Fixed by default so server and client output match.

#### Accessibility

- Screen readers get the formatted value as one piece of plain text. The rolling columns are hidden from them.
- The component does not announce changes on its own. If a change matters, wrap it in an element with aria-live="polite".
- Digits use tabular figures, so the number does not change width as it rolls.
- While counting, only the target value is exposed. The in-between values are hidden from assistive tech.

#### Motion

- Each digit column rolls to its new value with the snappy spring, settling in about a third of a second. Punctuation and symbols do not move.
- A count eases out over 1.6 seconds. A change made mid-count carries on from the value showing, without jumping.
- With reduced motion, digits change instantly without rolling or counting.

#### Customization

##### Announce updates

```tsx
<p aria-live="polite">
  <AnimatedNumber value={unread} /> unread
</p>
```

##### Compact notation

```tsx
<AnimatedNumber value={1284000} format={{ notation: "compact", maximumFractionDigits: 1 }} />
```

### Bar Chart (Pro)

An inspectable column chart with quiet gridlines, animated values and a text data alternative.

Page: https://latheui.dev/components/bar-chart
Install: npx shadcn@latest add @latheui/bar-chart

#### Usage

```tsx
import * as React from "react"
import { BarChart } from "@/components/ui/bar-chart"
import { Button } from "@/components/ui/button"
export default function Demo(){const [compare,setCompare]=React.useState(false);return <div className="w-full max-w-lg space-y-4"><BarChart label="Weekly sign-ups" data={["Mon","Tue","Wed","Thu","Fri","Sat"].map((label,i)=>({label,value:(compare?[32,64,48,84,58,72]:[48,32,72,64,92,52])[i]}))}/><Button variant="outline" size="sm" onClick={()=>setCompare(!compare)}>Switch week</Button></div>}
```

#### Props of Bar Chart

- `data` (required): `BarDatum[]`. Unique category labels and numeric values. Positive and negative values are supported.
- `label` (required): `string`. Chart title and accessible name.
- `formatValue`: `(value: number) => string`. Axis, inspection and table formatting.

#### Keyboard

- Tab: Inspect each bar.

#### Accessibility

- Bars can be focused and inspected by keyboard.
- A text data table provides all values.
- Animations respect reduced motion.

#### Customization

##### Composition

Combine the control with your own layout. Semantic colors follow the active theme.

### Clock Face (Pro)

A live clock: an analog dial with a sweeping or ticking second hand, or digits that roll over, in any time zone.

Page: https://latheui.dev/components/clock-face
Install: npx shadcn@latest add @latheui/clock-face

#### Usage

```tsx
import { ClockFace } from "@/components/ui/clock-face"

export function Offices() {
  return <ClockFace timeZone="Asia/Tokyo" caption="Tokyo" />
}
```

#### Props of ClockFace

Also accepts native div attributes. The accent is the --clock-accent variable, chart-1 by default.

- `variant`: `"analog" | "digital"`, default `"analog"`. A dial with hands, or rolling digits.
- `time`: `Date`. A fixed time to show. Without it the clock runs live.
- `timeZone`: `string`. IANA time zone, such as "Europe/London". The visitor's own by default.
- `caption`: `string`. A short caption on the face, such as a city.
- `motion`: `"smooth" | "tick"`, default `"smooth"`. Analog: a sweeping second hand, or one that springs from second to second.
- `numerals`: `"none" | "quarters" | "all" | "roman"`, default `"quarters"`. Analog: the numbers around the dial.
- `ticks`: `"minutes" | "hours" | "none"`, default `"minutes"`. Analog: the marks around the edge.
- `seconds`: `boolean`, default `true`. Show the second hand, or the seconds digits.
- `hour24`: `boolean`, default `false`. Digital: 24-hour time instead of AM and PM.
- `size`: `number`, default `220 analog, 64 digital`. The dial's diameter, or the digits' font size, in px.

#### Accessibility

- The clock is an image named by the time and its caption, for example "10:42 AM in Tokyo". The name changes once a minute, not every second.
- The time is read only in the browser, so server-rendered markup never shows the wrong time.
- With reduced motion the second hand ticks without springing and digits change without rolling.

#### Motion

- A smooth hand is redrawn every frame. A ticking hand springs past each mark (stiffness 700, damping 18) and only ever moves forward, so 59 to 0 never spins back.
- Digits roll up on a spring with a slight blur.
- It stops while its preview is paused.

#### Customization

##### A minimal dial in your accent

```tsx
<ClockFace numerals="none" ticks="hours" seconds={false} className="[--clock-accent:var(--primary)]" />
```

### Contribution Graph (Pro)

A commit-style heatmap: one square per day, darker when busier, read by pointer or keyboard.

Page: https://latheui.dev/components/contribution-graph
Install: npx shadcn@latest add @latheui/contribution-graph

#### Usage

```tsx
import { ContributionGraph } from "@/components/ui/contribution-graph"

const data = [
  { date: "2026-03-02", count: 4 },
  { date: "2026-03-03", count: 11 },
]

export function Activity() {
  return <ContributionGraph label="Commits in 2026" data={data} from="2026-01-01" to="2026-12-31" />
}
```

#### Props of ContributionGraph

Also accepts native div attributes.

- `data` (required): `{ date: string; count: number }[]`. Days with activity, as ISO dates. Missing days count as zero.
- `label` (required): `string`. Accessible name, for example “Commits in 2026”.
- `from`: `string`, default `first date in data`. First day shown, as an ISO date.
- `to`: `string`, default `last date in data`. Last day shown.
- `color`: `string`, default `"var(--chart-4)"`. Any CSS color. Busier days use more of it.
- `thresholds`: `[number, number, number, number]`, default `quarters of the busiest day`. Counts at which a day reaches levels 1 to 4.
- `weekStartsOn`: `0 | 1`, default `0`. 0 for Sunday, 1 for Monday.
- `cellSize`: `number`, default `12`. Size of a day in pixels. With fit, the largest a day gets.
- `cellGap`: `number`, default `3`. Space between days in pixels.
- `fit`: `boolean`, default `true`. Shrinks the days to fit the width the graph is given, so a whole year fits on a phone. Weekday names hide when rows get too short.
- `minCellSize`: `number`, default `4`. The smallest a day gets when fitting, in pixels.
- `formatDay`: `(count: number, date: Date) => string`. Wording for a day, used by the readout and screen readers.
- `locale`: `string`, default `"en-US"`. Locale for month and weekday names.

#### Keyboard

- Tab: Focuses the graph on the latest day.
- ArrowUp / ArrowDown: Moves one day.
- ArrowLeft / ArrowRight: Moves one week.
- Home / End: Moves to the first or last day.
- Escape: Clears the selection.

#### Accessibility

- The grid is exposed as a slider over the days. Its value text is the day's count and date, so each day can be read without a pointer.
- The readout is text under the graph instead of a floating tooltip, so it is never clipped and works on touch.
- Levels differ in lightness as well as hue, and the legend shows their order. Exact counts are always available in the readout.
- Dates are handled in UTC, so the same data draws the same graph in every time zone.

#### Motion

- The day being read grows slightly and gains a ring.
- With reduced motion it gains the ring without growing.

#### Customization

##### Color and levels

```tsx
<ContributionGraph
  label="Deploys"
  data={deploys}
  color="var(--chart-2)"
  thresholds={[1, 3, 6, 10]}
  formatDay={(count, date) => `${count} deploys on ${date.toDateString()}`}
/>
```

##### Bigger cells for short ranges

```tsx
<ContributionGraph label="Last 8 weeks" data={recent} cellSize={20} cellGap={4} weekStartsOn={1} />
```

### Data Table (Pro)

A typed table with sortable columns and loading, empty and error states. Scrolls sideways when narrow.

Page: https://latheui.dev/components/data-table
Install: npx shadcn@latest add @latheui/data-table

#### Usage

```tsx
import { DataTable, type DataTableColumn } from "@/components/ui/data-table"

type User = { id: string; name: string; seats: number }

const columns: DataTableColumn<User>[] = [
  { key: "name", header: "Name", accessor: (row) => row.name, sortable: true },
  { key: "seats", header: "Seats", accessor: (row) => row.seats, sortable: true, align: "right" },
]

export function Users({ users, loading }: { users: User[]; loading: boolean }) {
  return (
    <DataTable
      caption="Users"
      columns={columns}
      data={users}
      getRowId={(row) => row.id}
      loading={loading}
    />
  )
}
```

#### Props of DataTable<T>

Also accepts native div attributes for the scroll container.

- `rowSelection`: `boolean`, default `false`. Show row checkboxes and select-visible control.
- `selectedRows / defaultSelectedRows`: `string[]`. Controlled or initial selected row ids.
- `onSelectedRowsChange`: `(ids: string[]) => void`. Row selection callback.
- `pageSize`: `number`. Enables client-side pagination; omitted means all rows.
- `page / defaultPage`: `number`, default `1`. Controlled or initial page, starting at one.
- `onPageChange`: `(page: number) => void`. Page change callback.
- `columns` (required): `DataTableColumn<T>[]`. Column definitions.
- `data` (required): `T[]`. Rows.
- `getRowId` (required): `(row: T) => string`. Stable id for each row.
- `caption` (required): `string`. Names the table and its scroll region for assistive tech.
- `sort`: `SortState | null`. Controlled sort. Use with onSortChange for server-side sorting.
- `defaultSort`: `SortState | null`, default `null`. Initial sort when uncontrolled.
- `onSortChange`: `(sort: SortState | null) => void`. Called when a sortable header is clicked.
- `loading`: `boolean`, default `false`. Replaces the rows with placeholders.
- `loadingRows`: `number`, default `5`. Number of placeholder rows.
- `error`: `ReactNode`. When set, replaces the rows with this message.
- `onRetry`: `() => void`. Adds a “Try again” button to the error state.
- `emptyMessage`: `ReactNode`, default `"No results."`. Shown when there are no rows.

#### Props of DataTableColumn<T>

- `key` (required): `string`. Unique column id.
- `header` (required): `string`. Header text.
- `accessor`: `(row: T) => string | number`. Value used for sorting and, without cell, for display.
- `cell`: `(row: T) => ReactNode`. Custom cell content.
- `sortable`: `boolean`, default `false`. Makes the header a sort button. Needs an accessor.
- `align`: `"left" | "right"`, default `"left"`. Right-align numbers. Right-aligned cells use tabular figures.
- `className`: `string`. Classes for the column's header and cells.

#### Props of SortState

- `key` (required): `string`. The sorted column's key.
- `direction` (required): `"asc" | "desc"`. Sort direction.

#### Keyboard

- Tab: Moves to the table's scroll region, then through the sortable headers.
- Enter / Space: On a header: cycles ascending, descending, unsorted.
- ArrowLeft / ArrowRight: On the scroll region: scrolls a wide table sideways.

#### Accessibility

- A real table with column headers, a caption, and aria-sort on sortable columns.
- Sort controls are buttons inside the headers, so they are reachable and announced with the column name.
- The table sets aria-busy while loading. The error state is an alert, so it is announced when it appears.
- On narrow screens the table scrolls sideways inside a focusable, named region rather than squeezing its columns.
- Text is sorted with natural ordering, so “Item 10” comes after “Item 9”.

#### Motion

- The sort arrow rotates between ascending and descending. Rows do not animate, which keeps large tables fast and readable.
- With reduced motion, the arrow flips instantly.

#### Customization

##### Server-side sorting

Control the sort and fetch with it. Leave out the accessor-based ordering by passing rows that are already sorted.

```tsx
const [sort, setSort] = React.useState<SortState | null>(null)
const { data, isLoading } = useUsers({ sort })

<DataTable
  caption="Users"
  columns={columns}
  data={data ?? []}
  getRowId={(row) => row.id}
  sort={sort}
  onSortChange={setSort}
  loading={isLoading}
/>
```

##### Column widths

```tsx
{ key: "id", header: "ID", accessor: (row) => row.id, className: "w-28 font-mono" }
```

### Dotted Globe (Pro)

A slowly turning globe of dots with pulsing markers. Drag or use the arrow keys to spin it.

Page: https://latheui.dev/components/dotted-globe
Install: npx shadcn@latest add @latheui/dotted-globe

#### Usage

```tsx
import { DottedGlobe } from "@/components/ui/dotted-globe"

export function Presence() {
  return (
    <DottedGlobe
      label="Where our team works"
      markers={[
        { lat: 37.77, lng: -122.42, label: "San Francisco" },
        { lat: 35.68, lng: 139.69, label: "Tokyo" },
      ]}
    />
  )
}
```

#### Props of DottedGlobe

Also accepts native div attributes. It is square and fills its width; size it with className.

- `label` (required): `string`. Accessible name.
- `markers`: `{ lat: number; lng: number; label?: string }[]`. Places to mark, in degrees.
- `speed`: `number`, default `6`. Target degrees per second. Speed changes ease smoothly without restarting the canvas; 0 brings it to rest.
- `initialRotation`: `[lng: number, lat: number]`, default `[-20, 18]`. The point facing the viewer at first.
- `markerColor`: `string`, default `"var(--chart-1)"`. Color of the markers.
- `dotSize`: `number`, default `2.2`. Dot diameter in pixels.
- `dotCount`: `number`, default `12000`. Evenly distributed surface samples, including hidden ocean points. Clamped to 1,000–50,000. More points give closer spacing.
- `landColor`: `string`, default `inherited text color`. Base color of land dots. Accepts any CSS color.
- `countryColors`: `Record<string, string>`. Colors keyed by country ID from globeCountries in the world-countries library (ISO numeric strings where available, e.g. 250 for France).
- `showOcean`: `boolean`, default `false`. Draw dots over water as well as land.
- `oceanColor`: `string`, default `"var(--muted-foreground)"`. Color of ocean dots.
- `waterColor`: `string`, default `"transparent"`. Fill of the sphere behind the dots.
- `showOutline`: `boolean`, default `true`. Draw a fine outline around the sphere.
- `interactive`: `boolean`, default `true`. Allows dragging and the arrow keys.

#### Keyboard

- Tab: Focuses the globe.
- ArrowLeft / ArrowRight: Turns it 10 degrees and stops the spin.
- ArrowUp / ArrowDown: Tilts it 10 degrees, up to 60.

#### Accessibility

- The canvas is an image with a name. Marker labels are listed in visually hidden text, since position on a turning globe cannot be read by assistive tech.
- With reduced motion it does not turn on its own and the markers do not pulse. It can still be turned by hand.
- Land dots inherit the text color by default. All surface and marker colors can be overridden, including per-country colors.
- It stops drawing while it is scrolled out of view.

#### Motion

- Speed changes and drag momentum ease continuously toward the target speed without resetting rotation or marker pulses.
- Land dots, ocean dots and markers flatten into surface ellipses and fade to zero at the horizon, then pass behind the sphere. Surface drawing is clipped to the globe's outline.

#### Customization

##### A denser globe with ocean dots and country colors

```tsx
<DottedGlobe
  label="A connected world"
  className="max-w-lg"
  dotCount={24000}
  dotSize={1.8}
  landColor="#6ee7b7"
  showOcean
  oceanColor="#31566b"
  waterColor="#0b1422"
  countryColors={{ "250": "#fbbf24", "840": "#60a5fa" }}
/>
```

##### Face a region, in your colors

```tsx
<DottedGlobe
  label="Asia-Pacific"
  className="max-w-md text-chart-2"
  initialRotation={[120, 10]}
  speed={3}
  markerColor="var(--chart-3)"
  markers={regions}
/>
```

### Filter Bar (Pro)

Single-choice filter chips with anchored editors, removable values and a controlled filtering workflow.

Page: https://latheui.dev/components/filter-bar
Install: npx shadcn@latest add @latheui/filter-bar

#### Usage

```tsx
import { FilterBar } from "@/components/ui/filter-bar"

export default function Filters() {
  return <FilterBar label="Issue filters" filters={[{
    key: "status", label: "Status", options: [
      { value: "open", label: "Open" },
      { value: "closed", label: "Closed" },
    ],
  }]} />
}
```

#### Props of FilterBar

- `label` (required): `string`. Accessible name for the group.
- `filters` (required): `FilterDefinition[]`. Unique field keys, visible labels and single-choice options. Each option has value, label and optional disabled.
- `value / defaultValue`: `FilterValue[]`, default `[] (defaultValue)`. Controlled or initial selections: one { key, value } per field. Use unique keys and option values from filters.
- `onValueChange`: `(value: FilterValue[]) => void`. Called when adding, changing, removing or clearing a filter. Apply these values to data in your app.
- `disabled`: `boolean`, default `false`. Disable all editing actions and close editors.
- `className`: `string`. Style the wrapping group; chips wrap as space narrows.

#### Keyboard

- Tab: Move between chip editors, remove buttons, Add filter and Clear all.
- Enter / Space: Open an editor or choose its focused option.
- Escape: Close an editor and return focus to its trigger.

#### Accessibility

- Each chip has separately named edit and remove buttons. The selected option exposes aria-pressed.
- Popover supplies focus handling, dismissal and trigger focus return. Additions and removals are announced.
- Removing or clearing sends focus to Add filter. Unavailable fields and options are disabled.

#### Motion

- Chips reposition with the shared snappy spring. Popovers use the existing anchored scale and fade.
- Layout movement becomes instant with reduced motion.

#### Customization

##### Apply filters to your data

Own value and onValueChange to filter locally or translate selections into a server query. The bar never fetches or mutates your data.

```tsx
const [filters, setFilters] = React.useState<FilterValue[]>([])
const visible = tasks.filter((task) =>
  filters.every(({ key, value }) => task[key] === value)
)

<FilterBar label="Task filters" filters={definitions} value={filters} onValueChange={setFilters} />
```

### Gauge (Pro)

A half-ring meter with a readable value and configurable bounds.

Page: https://latheui.dev/components/gauge
Install: npx shadcn@latest add @latheui/gauge

#### Usage

```tsx
import * as React from "react"
import { Gauge } from "@/components/ui/gauge"
import { Slider } from "@/components/ui/slider"
export default function Demo(){const [value,setValue]=React.useState([72]);return <div className="flex w-full max-w-xs flex-col items-center gap-6"><Gauge value={value[0]} label="Capacity" formatValue={v=>v+"%"}/><Slider className="w-full" label="Adjust capacity" value={value} onValueChange={setValue}/></div>}
```

#### Props of Gauge

- `value` (required): `number`. Current reading, clamped to the bounds.
- `min / max`: `number`, default `0 / 100`. Meter bounds.
- `label` (required): `string`. Visible and accessible meter name.
- `formatValue`: `(value: number) => string`. Format reading and boundaries.

#### Accessibility

- The meter exposes current value, bounds and formatted value.
- The value and label are visible as text.
- A new value sweeps the arc over 600ms, and the number counts through every value on the way, in step with the arc.
- With reduced motion, both jump straight to the new value.

#### Customization

##### Composition

Combine the control with your own layout. Semantic colors follow the active theme.

### Line Chart (Pro)

A scrubbable chart with one line or several. Read any point by hover, drag or keys; lines morph on change.

Page: https://latheui.dev/components/line-chart
Install: npx shadcn@latest add @latheui/line-chart

#### Usage

```tsx
import { LineChart } from "@/components/ui/line-chart"

const data = [
  { label: "Mon", value: 42 },
  { label: "Tue", value: 48 },
  { label: "Wed", value: 61 },
]

export function Signups() {
  return <LineChart label="Signups this week" data={data} />
}
```

#### Props of LineChart

Also accepts native div attributes. The width follows the container.

- `data` (required): `{ label: string; value?: number; values?: Record<string, number>; color?: string }[]`. Points in order. Use value for one line, or values keyed by series for several. A point's color overrides the line color around it on one-line charts.
- `series`: `{ key: string; label: string; color?: string; dashed?: boolean; area?: boolean }[]`. The lines to draw. Leave it out for a single line read from value. Keep keys stable so lines morph.
- `hiddenSeries`: `string[]`. Controlled list of switched-off series keys.
- `defaultHiddenSeries`: `string[]`, default `[]`. Series switched off at first.
- `onHiddenSeriesChange`: `(keys: string[]) => void`. Called when a legend button is pressed.
- `legend`: `boolean`, default `true with several series`. Shows the buttons that switch lines on and off.
- `curve`: `"linear" | "smooth"`, default `"linear"`. Straight segments, or a smooth curve that never overshoots the data.
- `onActiveChange`: `(index: number | null, point) => void`. Called as the crosshair moves, and with null when it is released.
- `label` (required): `string`. Accessible name, for example “Revenue, last 30 days”.
- `height`: `number`, default `220`. Height of the plot and its axes in pixels.
- `color`: `string`, default `"var(--chart-1)"`. Line color. Any CSS color.
- `negativeColor`: `string`, default `color`. Color of the line and tint below zero.
- `colorTransition`: `"blend" | "step"`, default `"blend"`. How per-point colors meet: a gradient between points, or a hard change halfway between them.
- `area`: `boolean`, default `true`. Tints the area between the line and the baseline.
- `yAxis`: `"left" | "right" | false`, default `"left"`. Side of the value labels. false hides them.
- `xAxis`: `"bottom" | "top" | false`, default `"bottom"`. Side of the point labels. false hides them.
- `grid`: `"horizontal" | "vertical" | "both" | "none"`, default `"horizontal"`. Which grid lines to draw.
- `gridStyle`: `"dashed" | "dotted" | "solid"`, default `"dashed"`. How grid lines are drawn. The baseline is always solid.
- `readout`: `boolean`, default `true`. Shows the current point's value and label above the plot.
- `valueTransition`: `"none" | "roll" | "slide"`, default `"none"`. How the readout value changes: digits roll, or the number slides up for a rise and down for a fall.
- `labelTransition`: `"none" | "slide" | "fade"`, default `"none"`. How the readout label changes between points.
- `formatValue`: `(value: number) => string`, default `en-US grouping`. Formats the readout and the spoken value.
- `formatTick`: `(value: number) => string`, default `formatValue`. Formats the value axis labels, for example without a unit.
- `classNames`: `{ value?, caption?, axis?, grid?, baseline?, cursor? }`. Classes for each part. Text utilities for value, caption and axis; stroke utilities for grid, baseline and cursor.
- `loading`: `boolean`, default `false`. With data, dims the lines while new data loads. Without data, shows a placeholder.
- `emptyMessage`: `ReactNode`, default `"No data yet"`. Shown when data is empty.

#### Keyboard

- Tab: Focuses the chart and selects the latest point.
- ArrowLeft / ArrowRight: Moves to the previous or next point.
- PageUp / PageDown: Jumps about a sixth of the range.
- Home / End: Moves to the first or last point.
- Escape: Clears the selection and returns the readout to the latest point.

#### Accessibility

- The plot is exposed as a slider over the data points. Its value text is the point's label and formatted value, so a screen reader can step through the series one point at a time.
- While loading or empty, it is exposed as an image with the state in its name, and is not focusable.
- The readout is text above the plot rather than a floating tooltip, so it is never clipped, never covers the data, and works the same on touch.
- Value labels sit in their own column beside the plot, so the line never runs behind them.
- Legend buttons are toggle buttons that report whether their line is shown. With several lines, the slider's value text reads every visible line.
- Color alone does not carry the sign of a value: the zero line is drawn and the readout shows the number.
- Horizontal drags scrub the chart and vertical drags still scroll the page.
- A line chart shows shape, not exact values. If people need every number, offer the data as a table as well.

#### Motion

- The line draws in from left to right over 720ms and the area tint fades in after it.
- The crosshair glides from point to point on a spring while scrubbing.
- New data morphs each line from its current shape over 550ms, and the value scale moves with it. A line switched off lies down on the baseline as it fades.
- The readout can roll its digits or slide, set with valueTransition and labelTransition. It swaps with no animation by default.
- With reduced motion, the chart appears fully drawn, the cursor jumps and the readout swaps.

#### Customization

##### Several lines

Give each point a values object and list the series. A dashed line suits a comparison.

```tsx
<LineChart
  label="Visitors against the previous period"
  curve="smooth"
  data={[
    { label: "Mon", values: { current: 420, previous: 380 } },
    { label: "Tue", values: { current: 510, previous: 410 } },
  ]}
  series={[
    { key: "current", label: "This period" },
    { key: "previous", label: "Previous", color: "var(--muted-foreground)", dashed: true },
  ]}
/>
```

##### Axes, grid and type

Axis labels are HTML and grid lines are SVG, so text and stroke utilities restyle them.

```tsx
<LineChart
  label="Orders per week"
  data={orders}
  yAxis="right"
  xAxis="top"
  grid="both"
  gridStyle="dotted"
  classNames={{
    value: "font-mono text-3xl",
    axis: "font-mono text-chart-2",
    grid: "stroke-chart-2/25",
  }}
/>
```

##### Colors by sign or by point

negativeColor colors everything below zero. A color on a point wins over both series colors.

```tsx
<LineChart label="Net cash flow" data={net} color="var(--chart-4)" negativeColor="var(--destructive)" />

<LineChart
  label="Hours per phase"
  colorTransition="step"
  data={[
    { label: "Research", value: 18, color: "var(--chart-2)" },
    { label: "Design", value: 34, color: "var(--chart-5)" },
    { label: "Build", value: 62, color: "var(--chart-1)" },
  ]}
/>
```

##### Animated readout

```tsx
<LineChart label="Visitors" data={visitors} valueTransition="roll" labelTransition="slide" />
```

##### Color and format

```tsx
<LineChart
  label="Response time"
  data={latency}
  color="var(--chart-2)"
  area={false}
  formatValue={(ms) => `${ms} ms`}
/>
```

##### Replay the draw instead of morphing

New data morphs the lines. To draw them in from the left again instead, give the chart a key that changes with the dataset.

```tsx
<LineChart key={range} label="Revenue" data={series[range]} />
```

### Ring Chart (Pro)

Parts of a whole as a ring. Arcs morph with the data, and the middle rolls to the part you point at.

Page: https://latheui.dev/components/ring-chart
Install: npx shadcn@latest add @latheui/ring-chart

#### Usage

```tsx
import { RingChart } from "@/components/ui/ring-chart"

const sources = [
  { key: "plans", label: "Plans", value: 1832 },
  { key: "products", label: "Products", value: 1147 },
  { key: "services", label: "Services", value: 637 },
]

export function Earnings() {
  return (
    <RingChart
      label="Earnings by source"
      totalLabel="Earned"
      format={{ style: "currency", currency: "USD", maximumFractionDigits: 0 }}
      data={sources}
    />
  )
}
```

#### Props of RingChart

Also accepts native figure attributes.

- `data` (required): `{ key: string; label: string; value: number; color?: string }[]`. The parts. Zero and negative values are left out.
- `label` (required): `string`. Names the whole for assistive tech.
- `unit`: `string`. Caption under the total.
- `format`: `Intl.NumberFormatOptions`. Formatting for every number, for example currency.
- `totalLabel`: `string`, default `"Total"`. Caption above the number at rest.
- `size`: `number`, default `200`. Diameter in pixels. It shrinks to fit narrow containers.
- `thickness`: `number`, default `22`. Ring thickness in pixels.
- `rounding`: `number`, default `0`. How round the segment corners are, from 0 to 100. 0 cuts the ends square, a low number such as 30 softens the sharp corners with a slight curve, and 100 makes each end a half-circle. Very small segments take less so they never swell past their own width.
- `gap`: `number`, default `3`. Space between neighbouring segments in pixels, at any rounding. 0 joins them.
- `legend`: `boolean`, default `true`. Shows the list of parts.
- `callouts`: `boolean`, default `false`. Names each part on the ring with a leader line: slanted out from the arc, then level under the label. Adds room around the ring and moves the list below it.
- `activeKey`: `string | null`. Controlled pinned part.
- `defaultActiveKey`: `string | null`, default `null`. Initially pinned part.
- `onActiveChange`: `(key: string | null) => void`. Called when a part is pinned or unpinned.
- `hiddenKeys`: `string[]`. Controlled switched-off parts.
- `defaultHiddenKeys`: `string[]`, default `[]`. Parts switched off at first.
- `onHiddenKeysChange`: `(keys: string[]) => void`. Called when a row switches a part on or off.
- `emptyMessage`: `ReactNode`, default `"No data yet"`. Shown in the middle when the total is zero.

#### Keyboard

- Tab: Moves through the rows. The focused row's part is read out in the middle.
- Enter / Space: Switches the focused part on or off.
- Escape: Unpins the pinned part.

#### Accessibility

- The list is the keyboard path. Each row is a toggle button whose name carries the part's value and share.
- The ring and the number in the middle are hidden from assistive tech. A hidden summary and table list the total and every part instead.
- Switching a part off announces how many are hidden and the new total.
- Parts are told apart by their rows' labels, or their callouts, as well as by color. Keep it to about six parts; use a bar chart beyond that.

#### Motion

- Arcs sweep in from the top on first render. When data changes each arc's start and end angles spring to their new values, so an interrupted change carries on smoothly.
- The active arc steps 5px outward and the others dim. The number rolls to the active part's value.
- The number in the middle is sized so the longest value fits inside the ring, and keeps that size from one part to the next.
- Which part is active depends on where the pointer is in the ring, not on the arcs as drawn, so an arc that steps outward never slips out from under the pointer and flickers.
- Callouts spring to their arcs' new positions when the data changes, and dim with their arcs.
- With reduced motion arcs and numbers jump to their final state and nothing steps outward.

#### Customization

##### Rounding and gap

```tsx
<RingChart label="Earnings by source" data={sources} rounding={30} />
<RingChart label="Earnings by source" data={sources} rounding={60} gap={6} />
<RingChart label="Earnings by source" data={sources} rounding={100} gap={2} />
```

##### Callouts instead of a list

The callouts name the parts, so the list can go.

```tsx
<RingChart label="Earnings by source" data={sources} callouts legend={false} />
```

##### Currency, size and colors

```tsx
<RingChart
  label="Spend by category"
  totalLabel="Spend"
  format={{ style: "currency", currency: "USD", maximumFractionDigits: 0 }}
  size={160}
  thickness={14}
  data={[
    { key: "rent", label: "Rent", value: 4200, color: "var(--chart-2)" },
    { key: "payroll", label: "Payroll", value: 9100, color: "var(--chart-5)" },
  ]}
/>
```

##### Sync the pinned part with something else

```tsx
const [source, setSource] = React.useState<string | null>(null)

<RingChart label="Sources" data={sources} activeKey={source} onActiveChange={setSource} />
<SourcesTable highlight={source} />
```

### Sheet (Pro)

An editable spreadsheet with cell ranges, sorting, filtering, row selection and column resizing.

Page: https://latheui.dev/components/sheet
Install: npx shadcn@latest add @latheui/sheet

#### Usage

```tsx
import { Sheet } from "@/components/ui/sheet"
export default function Demo(){return <Sheet label="Project budget" columns={[{key:"project",header:"Project",width:180},{key:"owner",header:"Owner",width:140},{key:"budget",header:"Budget",type:"number",format:v=>v===""?"":"$"+Number(v).toLocaleString("en-US")}]} defaultRows={[{id:"1",project:"Identity system",owner:"Ada Chen",budget:4800},{id:"2",project:"Website refresh",owner:"Sam Rivera",budget:7200},{id:"3",project:"Product photos",owner:"Lee Morgan",budget:2400},{id:"4",project:"Launch campaign",owner:"Mia Patel",budget:3600}]}/>}
```

#### Props of Sheet

- `label` (required): `string`. Accessible grid name.
- `columns` (required): `SheetColumn[]`. Unique keys, headers, optional types, widths, editable state and value formatter.
- `rows / defaultRows`: `SheetRow[]`. Controlled or initial rows with stable unique ids.
- `onRowsChange`: `(rows: SheetRow[]) => void`. Called after edits, range clearing and row deletion.
- `toolbar / rowSelection`: `boolean`, default `true`. Search/actions toolbar and row checkboxes.
- `maxHeight`: `number`, default `360`. Grid scroll height in pixels.

#### Keyboard

- Arrow keys / Shift + Arrow keys: Move between cells or extend a range.
- Enter / F2: Edit the current cell.
- Escape: Cancel editing, or clear the selection.
- Delete / Backspace: Clear editable cells in the range.
- Ctrl/Cmd + A / Ctrl/Cmd + C: Select all cells or copy the range.

#### Accessibility

- The grid exposes row and column indices and a roving cell tab stop.
- Edits, sorting and clearing are announced.
- Read-only columns cannot be changed; numeric cells reject invalid numbers.
- Clicking outside the sheet or pressing Escape clears the selection. The last cell keeps the tab stop, so Tab brings you straight back.
- With several rows selected, checking or unchecking a row inside the selection does the same to every selected row.

#### Motion

- One outline glides between cells and ranges on a stiff spring; dragging across cells keeps it under the pointer.
- The outline fades out when the selection clears and reappears in place, not sliding in from where it was.

#### Customization

##### Composition

Combine the control with your own layout. Semantic colors follow the active theme.

### Sparkline

A small trend line for compact metrics, with optional area fill.

Page: https://latheui.dev/components/sparkline
Install: npx shadcn@latest add @latheui/sparkline

#### Usage

```tsx
import { Sparkline } from "@/components/ui/sparkline"
export default function Demo(){return <div className="flex w-full max-w-sm items-center justify-between gap-6 rounded-lg border border-border bg-card p-5"><div><p className="text-xs text-muted-foreground">Active projects</p><p className="mt-1 text-2xl font-medium tabular-nums">128</p><p className="mt-1 text-xs text-muted-foreground">+18 this month</p></div><Sparkline data={[12,18,16,24,20,32,28,38,42]} label="Projects trending upward" fillArea/></div>}
```

#### Props of Sparkline

- `data` (required): `number[]`. Ordered numeric samples. Empty and constant series are supported.
- `label` (required): `string`. Accessible trend description.
- `width`: `number | string`, default `112`. Width as px or any CSS length, such as "100%". A w-* class works too.
- `height`: `number | string`, default `36`. Height as px or any CSS length. An h-* class works too.
- `strokeWidth`: `number`, default `2`. Line thickness in screen pixels, at any size.
- `curve`: `"linear" | "smooth"`, default `"linear"`. Straight segments between points, or a smooth curve through them.
- `fillOpacity`: `number`, default `0.2`. Strength of the area fill at its top, from 0 to 1. Used with fillArea.
- `dot`: `boolean`, default `false`. Marks the latest value with a dot.
- `dotSize`: `number`, default `5`. Dot diameter in px.
- `color`: `string`. Line color as any CSS color. Without it the line uses the text color, so a text-* class sets it.
- `fillArea`: `boolean`, default `false`. Add a subtle gradient under the line.
- `animated`: `boolean`, default `false`. Glide the line to its new shape when data changes, instead of jumping.
- `stretch`: `boolean`, default `false`. Fill the box your className gives it at any aspect ratio, such as h-16 w-full, with an even 2px stroke. Without it the line keeps its shape and centers.

#### Accessibility

- The SVG has a trend label and a description containing sample values.
- The chart adds no keyboard stops.

#### Motion

- With animated, each point glides to its new height over about half a second when data changes. Series of different lengths blend too.
- With reduced motion the line changes at once.

#### Customization

##### Composition

Combine the control with your own layout. Semantic colors follow the active theme.

### World Map (Pro)

A dotted world map with labelled markers and routes that draw themselves. No map library or tiles.

Page: https://latheui.dev/components/world-map
Install: npx shadcn@latest add @latheui/world-map

#### Usage

```tsx
import { WorldMap } from "@/components/ui/world-map"

export function Regions() {
  return (
    <WorldMap
      label="Regions we serve"
      markers={[
        { lat: 37.77, lng: -122.42, label: "San Francisco" },
        { lat: 51.51, lng: -0.13, label: "London" },
      ]}
      arcs={[{ from: 0, to: 1 }]}
    />
  )
}
```

#### Props of WorldMap

Also accepts native figure attributes. The map scales to its container's width.

- `label` (required): `string`. Accessible name of the map.
- `markers`: `{ lat: number; lng: number; label: string }[]`, default `[]`. Places to mark, in degrees.
- `arcs`: `{ from: number; to: number }[]`, default `[]`. Routes between markers, by index.
- `color`: `string`, default `"var(--chart-1)"`. Color of markers and routes.
- `dotSize`: `number`, default `0.55`. Dot diameter as a share of the grid spacing, 0 to 1.
- `showLabels`: `boolean`, default `true`. Prints marker names on the map.
- `dotClassName`: `string`. Text color utilities for the land dots.

#### Accessibility

- The map is an image with a name, followed by a visually hidden list of every place and route, so nothing is conveyed by position alone.
- Labels are real SVG text with a background-colored outline, so they stay readable over the dots.
- The land is a 2.5 degree grid. It shows where things are in the world, not borders or coastlines, and small islands are missing.
- It is an equirectangular projection cropped to between 84°N and 58°S.

#### Motion

- Markers pop in one after another, then each route draws from its first marker to its second. Markers pulse slowly.
- With reduced motion everything is drawn at once and nothing pulses.

#### Customization

##### Colors

Markers and arcs take color; the land takes any text color utility.

```tsx
<WorldMap label="Offices" markers={offices} color="var(--chart-2)" dotClassName="text-chart-2/30" dotSize={0.8} />
```

## Media

### Anchored Annotations (Pro)

Place comments on image coordinates, inspect numbered anchors, and resolve or reopen annotations from an accessible list.

Page: https://latheui.dev/components/anchored-annotations
Install: npx shadcn@latest add @latheui/anchored-annotations

#### Usage

```tsx
"use client"
import { AnchoredAnnotations } from "@/components/ui/anchored-annotations"
export default function AnnotationDemo() {
  return <AnchoredAnnotations image={{ src: "/demo/photos/david-edelstein-n4dbvtudikw.webp", alt: "A pagoda with Mount Fuji behind the city" }} defaultValue={[{ id: "note-1", x: 32, y: 42, text: "Give the foreground a little more room." }, { id: "note-2", x: 72, y: 28, text: "The horizon feels right here.", resolved: true }]} />
}
```

#### Props of AnchoredAnnotations

- `image` (required): `{ src: string; alt: string }`. Image to annotate. Coordinates are percentages of its displayed area.
- `value / defaultValue`: `Annotation[]`, default `[] (defaultValue)`. Controlled or initial items with unique id, x, y, text and optional resolved flag.
- `onValueChange`: `(items: Annotation[]) => void`. Receives additions and resolve/reopen changes.
- `disabled`: `boolean`, default `false`. Disable new comments, coordinate changes and resolution. Existing comments remain readable.
- `className`: `string`. Classes for the section.

#### Keyboard

- Tab / Enter / Space: Navigate and activate numbered anchors, list comments and resolution controls.
- Tab: Move through the enabled controls. Focus remains visible.

#### Accessibility

- Lathe controls expose accessible names, states and keyboard behavior. Layouts wrap at narrow widths and use semantic theme tokens.
- Numbered anchors and the comment list expose the same notes. New comments return focus to the textarea; resolution never removes the focused control.

#### Motion

- Selection and direct manipulation do not require animated movement.
- Shared Lathe controls retain their reduced-motion behavior.

#### Customization

##### Connect your own data

Use the typed props to connect application state. The source is installed into your project.

### Carousel (Pro)

Scroll-snapping slides you move with buttons, dots, arrow keys or by dragging with the mouse.

Page: https://latheui.dev/components/carousel
Install: npx shadcn@latest add @latheui/carousel

#### Usage

```tsx
import { Carousel, CarouselItem } from "@/components/ui/carousel"

export function Gallery({ photos }: { photos: { src: string; alt: string }[] }) {
  return (
    <Carousel label="Photos">
      {photos.map((photo) => (
        <CarouselItem key={photo.src}>
          <img src={photo.src} alt={photo.alt} className="aspect-video w-full rounded-lg object-cover" />
        </CarouselItem>
      ))}
    </Carousel>
  )
}
```

#### Props of Carousel

Also accepts native section attributes.

- `label` (required): `string`. Accessible name of the carousel.
- `showDots`: `boolean`, default `true`. Shows the dot navigation.
- `onIndexChange`: `(index: number) => void`. Called with the index of the slide nearest the start edge.
- `trackClassName`: `string`. Classes for the scrolling track, for example gap-6.
- `children` (required): `ReactNode`. CarouselItem elements.

#### Props of CarouselItem

One slide. Accepts native div attributes.

- `className`: `string`, default `"basis-full"`. Set the slide width with a basis class.

#### Keyboard

- Tab: Focuses the track, then the dots and the previous and next buttons.
- ArrowLeft / ArrowRight: On the track: moves one slide.
- Home / End: On the track: moves to the first or last slide.

#### Accessibility

- The carousel is a labelled section with the carousel role description, and each slide is announced with its position, such as “2 of 4”.
- It never moves on its own. There is no autoplay, so there is nothing to pause.
- Every slide stays in the DOM and is reachable by scrolling, so content is not hidden from assistive tech or find-in-page.
- Touch and trackpad use native scrolling with snap points, which keeps momentum and edge behavior exactly as the platform does it.
- Previous and next are disabled at the ends rather than wrapping, so position is always clear.

#### Motion

- Buttons, dots and keys glide to the target slide on a spring. The active dot widens.
- A mouse drag follows the pointer one to one. Letting go carries the fling's speed into a spring that settles on the nearest slide, so a quick flick travels further than a slow pull. Grabbing a gliding track catches it in place.
- With reduced motion, the carousel jumps to the slide without animating.

#### Customization

##### Gap and slide width

```tsx
<Carousel label="Testimonials" trackClassName="gap-6">
  <CarouselItem className="basis-4/5 md:basis-1/3">…</CarouselItem>
</Carousel>
```

### Comparison Lens (Pro)

Inspect an aligned image through a movable lens. Pin the view, blend layers, or inspect an application-supplied difference image.

Page: https://latheui.dev/components/comparison-lens
Install: npx shadcn@latest add @latheui/comparison-lens

#### Usage

```tsx
"use client"
import { ComparisonLens } from "@/components/ui/comparison-lens"
export default function LensDemo() {
  return <ComparisonLens className="max-w-lg" before={{ src: "/demo/photos/compare-flat.webp", alt: "An autumn lake before color grading" }} after={{ src: "/demo/photos/compare-graded.webp", alt: "The same lake with its color graded" }} />
}
```

#### Props of ComparisonLens

- `before / after` (required): `{ src: string; alt: string }`. Aligned images with matching dimensions. Their descriptions identify the original and the lens layer.
- `difference`: `{ src: string; alt: string }`. Optional precomputed difference image. Lathe does not calculate pixel differences.
- `value / defaultValue`: `{ x: number; y: number }`, default `{ x: 50, y: 50 } (defaultValue)`. Controlled or initial position in percentages. Values are clamped to the image.
- `onValueChange`: `(position: LensPosition) => void`. Receives pointer and slider position changes.
- `disabled`: `boolean`, default `false`. Disable pointer tracking and controls.
- `controls`: `boolean`, default `true`. Show the caption, sliders, pin button and view picker. Turn off for just the image and its lens.
- `defaultRadius`: `number`, default `80`. Starting lens radius in pixels.
- `className`: `string`. Classes for the outer wrapper.

#### Keyboard

- Arrow keys: Move the focused horizontal, vertical or lens-size slider.
- Tab: Move through the enabled controls. Focus remains visible.

#### Accessibility

- Lathe controls expose accessible names, states and keyboard behavior. Layouts wrap at narrow widths and use semantic theme tokens.
- Pointer tracking is optional: position and size are also keyboard-accessible Lathe sliders. The lens image is decorative; its description is exposed in text.

#### Motion

- Selection and direct manipulation do not require animated movement.

#### Customization

##### Connect your own data

Use the typed props to connect application state. The source is installed into your project.

### Cursor Gallery (Pro)

A list of titles where pointing at one brings up its image, which trails the pointer, leans as it moves and crossfades as you go.

Page: https://latheui.dev/components/cursor-gallery
Install: npx shadcn@latest add @latheui/cursor-gallery

#### Usage

```tsx
import { CursorGallery } from "@/components/ui/cursor-gallery"

export function Work({ projects }: { projects: { name: string; year: string; cover: string; url: string }[] }) {
  return (
    <CursorGallery
      label="Selected work"
      items={projects.map((p) => ({ title: p.name, meta: p.year, image: p.cover, href: p.url }))}
    />
  )
}
```

#### Props of CursorGallery

Also accepts native div attributes.

- `items` (required): `{ title: string; meta?: string; image: string; href?: string }[]`. The rows. With href a row is a link; without, a button.
- `label` (required): `string`. Accessible name for the list.
- `onSelect`: `(item, index) => void`. Called when a row without an href is chosen.
- `imageWidth`: `number`, default `280`. Width of the image that follows the pointer, in px.
- `aspect`: `number`, default `4 / 3`. Width divided by height.
- `lag`: `number`, default `0.45`. How far the image trails the pointer, from 0 (glued) to 1 (lazy).
- `tilt`: `number`, default `8`. Degrees the image leans with the pointer's speed.
- `radius`: `number | string`, default `12`. Corner radius of the image.
- `dimOthers`: `boolean`, default `true`. Fade the other rows while one is under the pointer.

#### Keyboard

- Tab: Moves through the rows. The focused row's image appears at its end.

#### Accessibility

- Each row is a real link or button named by its title, so the list works fully without a pointer.
- The floating image is decorative; the row's title says what it shows.
- On touch screens there is no hover, so rows behave as plain links.
- With reduced motion the image appears in place, without trailing or leaning.

#### Motion

- The image follows the pointer on a spring whose stiffness comes from lag, and leans by its speed on a softer spring.
- It grows in from 60% as the pointer arrives and shrinks away as it leaves. Images crossfade with a slight zoom.

#### Customization

##### Glued to the pointer, level

```tsx
<CursorGallery label="Work" items={items} lag={0} tilt={0} />
```

### Curved Screen (Pro)

An image or a video on a gently curved 3D screen, built from thin strips, that leans toward the pointer.

Page: https://latheui.dev/components/curved-screen
Install: npx shadcn@latest add @latheui/curved-screen

#### Usage

```tsx
import { CurvedScreen } from "@/components/ui/curved-screen"

export function Reel() {
  return <CurvedScreen src="/reel.mp4" alt="Our studio reel" />
}
```

#### Props of CurvedScreen

Also accepts native div attributes. The screen takes 86% of the container's width.

- `src` (required): `string`. An image or a video. Same-origin or CORS-enabled, so it can be drawn.
- `alt` (required): `string`. Describes what is on the screen.
- `video`: `boolean`, default `from the extension`. Treat src as a video.
- `poster`: `string`. Shown before a video plays.
- `curvature`: `number`, default `64`. Degrees of arc the screen bends through. 0 is flat.
- `aspect`: `number`, default `16 / 9`. Width divided by height. The source is cropped to fill it.
- `strips`: `number`, default `32`. Vertical strips the curve is built from.
- `tilt`: `number`, default `5`. Degrees the screen leans toward the pointer.
- `reflection`: `boolean`, default `true`. A faint reflection under the screen.
- `autoPlay`: `boolean`, default `true`. Video: start playing, muted and looping.
- `perspective`: `number`, default `900`. Camera distance in px. Closer exaggerates the curve.
- `viewAngle`: `number`, default `7`. Degrees the camera looks down on the screen, so the top and bottom edges show the arc. 0 is head on.
- `edgeShade`: `number`, default `0.32`. How much darker the edges are than the middle, from 0 to 1.

#### Accessibility

- The screen is an image named by alt. For a video, add captions or a transcript nearby.
- A video gets a play and pause button. It never autoplays with reduced motion.
- The lean is for a mouse pointer only, and is off with reduced motion.

#### Motion

- Each strip draws its own slice of the source; a video is redrawn on every frame it plays.
- The lean follows the pointer on a soft spring (stiffness 120, damping 20).
- Strips nearer the edges are shaded a little, as a curved screen catches less light there.

#### Customization

##### An ultra-wide, deeply curved screen

```tsx
<CurvedScreen src="/landscape.jpg" alt="The valley" aspect={21 / 9} curvature={80} strips={48} />
```

### Depth Field (Pro)

Photos floating at different depths in 3D. The pointer steers the camera; a click brings one forward while the rest fade back.

Page: https://latheui.dev/components/depth-field
Install: npx shadcn@latest add @latheui/depth-field

#### Usage

```tsx
import { DepthField } from "@/components/ui/depth-field"

export function Moodboard({ photos }: { photos: { src: string; alt: string }[] }) {
  return <DepthField label="Moodboard" items={photos} className="h-[520px]" />
}
```

#### Props of DepthField

Also accepts native div attributes. Size it with className; it is 460px tall by default.

- `items` (required): `{ src: string; alt: string; title?: string }[]`. The photos.
- `label` (required): `string`. Accessible name for the field.
- `itemWidth`: `number`, default `150`. Width of a photo at the front of the field, in px.
- `aspect`: `number`, default `4 / 5`. Width divided by height.
- `depth`: `number`, default `900`. How far back the field goes, in px.
- `spread`: `number`, default `1`. How far photos spread toward the edges.
- `parallax`: `number`, default `1`. How much the camera turns with the pointer, from 0 to 2.
- `drift`: `boolean`, default `true`. A slow drift, so the field moves when nobody is pointing.
- `perspective`: `number`, default `900`. Camera distance in px.
- `seed`: `number`, default `3`. Changes the layout. The same seed always lays out the same way.
- `curve`: `Curve`, default `smooth spring`. How a chosen photo comes forward. Any curve from the Animation Lab.
- `duration`: `number`. Milliseconds, for curves that are not springs.

#### Keyboard

- Tab: Moves through the photos.
- Enter / Space: Brings the focused photo forward, or sends it back.
- Escape: Sends a chosen photo back.

#### Accessibility

- Each photo is a toggle button named by its title or alt text, pressed while it is forward.
- Photos overlap by design. Keep the count and size modest for the space, so each keeps a comfortable part showing to tap.
- The camera's drift stops while its preview is paused, and never runs with reduced motion.
- With reduced motion the camera stays still and photos move without travelling.

#### Motion

- Photos sit on a loose grid with a random nudge in each cell, so they never pile up, at random depths.
- The camera follows the pointer on a soft spring (stiffness 60, damping 18), plus a slow sway.
- A chosen photo flies to the front and straightens; the others fade to a quarter and blur.

#### Customization

##### Deeper, still and wide

```tsx
<DepthField label="Archive" items={photos} depth={1400} spread={1.2} drift={false} className="h-[600px]" />
```

### Expanding Card (Pro)

An image-first card that grows into a dialog with the rest of its story, then returns to its place.

Page: https://latheui.dev/components/expanding-card
Install: npx shadcn@latest add @latheui/expanding-card

#### Usage

```tsx
import { ExpandingCard } from "@/components/ui/expanding-card"

export function Feature() {
  return (
    <ExpandingCard
      image={{ src: "/fuji.jpg", alt: "Mount Fuji at dawn" }}
      eyebrow="Featured"
      title="Chasing Fuji"
      subtitle="Three days around the five lakes"
    >
      <p>The longer story, shown when the card is open.</p>
    </ExpandingCard>
  )
}
```

#### Props of ExpandingCard

- `image` (required): `{ src: string; alt: string }`. Shown on the card and at the top of the dialog.
- `title` (required): `string`. Card heading, and the dialog's title.
- `eyebrow`: `ReactNode`. Small label above the title.
- `subtitle`: `ReactNode`. Line under the title.
- `children` (required): `ReactNode`. Content shown only when expanded.
- `open`: `boolean`. Controlled open state.
- `defaultOpen`: `boolean`, default `false`. Initial state when uncontrolled.
- `onOpenChange`: `(open: boolean) => void`. Called when it opens or closes.
- `className`: `string`. Classes for the card.
- `panelClassName`: `string`. Classes for the expanded panel.

#### Keyboard

- Enter / Space: Opens the card.
- Tab: Moves through the dialog. Focus is kept inside it.
- Escape: Closes the dialog and returns focus to the card.

#### Accessibility

- The card is a button, and the expanded view is a modal dialog built on Radix Dialog, titled by the card's title.
- Focus moves into the dialog, stays inside it, and returns to the card on close.
- The image needs alt text that describes it; it appears in both states.
- Long stories scroll inside the dialog, which never grows taller than the screen.

#### Motion

- The card, its image and its heading travel to their places in the dialog on the smooth spring. The body text fades in once the card has mostly grown.
- Hovering lifts the card 3px and pressing it scales it down slightly.
- With reduced motion the dialog fades in and nothing travels.

#### Customization

##### A wider panel

```tsx
<ExpandingCard image={image} title="Case study" panelClassName="max-w-2xl" className="max-w-sm">
  {story}
</ExpandingCard>
```

### Flip Card (Pro)

A card that turns over to show its back, rolling the way the pointer moves: in from the left, it turns right; out the top, it turns up.

Page: https://latheui.dev/components/flip-card
Install: npx shadcn@latest add @latheui/flip-card

#### Usage

```tsx
import { FlipCard } from "@/components/ui/flip-card"

export function Place() {
  return (
    <FlipCard
      label="Harbor"
      className="h-64 w-48"
      front={<img src="/harbor.jpg" alt="" className="size-full object-cover" />}
      back={<p className="p-5 text-sm">Best an hour before sunset.</p>}
    />
  )
}
```

#### Props of FlipCard

Also accepts native div attributes. Size it with className; both faces fill it.

- `front` (required): `ReactNode`. The face shown first.
- `back` (required): `ReactNode`. The face shown when turned.
- `label` (required): `string`. Accessible name for the card.
- `flipped`: `boolean`. Controlled: whether the back is showing.
- `defaultFlipped`: `boolean`, default `false`. Start turned over.
- `onFlippedChange`: `(flipped: boolean) => void`. Called when the card turns.
- `trigger`: `"hover" | "press"`, default `"hover"`. Hover turns it as a mouse comes in and back as it leaves. Clicks, taps and keys always turn it.
- `axis`: `"auto" | "x" | "y"`, default `"auto"`. Auto follows the side the pointer crosses. X turns top over bottom, Y side over side.
- `perspective`: `number`, default `1100`. Camera distance in px. Lower is more dramatic.
- `curve`: `Curve`, default `soft spring`. How it turns. Any curve from the Animation Lab.
- `duration`: `number`. Milliseconds, for curves that are not springs.
- `faceClassName`: `string`. Classes for both faces, such as a background.

#### Keyboard

- Tab: Focuses the card.
- Enter / Space: Turns it over.

#### Accessibility

- The card is a toggle button: its pressed state says whether the back is showing.
- The hidden face is inert and hidden from assistive tech, so only the visible side is read and reachable.
- Hover turning only happens with a mouse. Touch and pen turn it with a tap.
- Because the card is a button, keep its faces free of links and other controls.

#### Motion

- A half turn about the axis the pointer crossed, with a soft spring (stiffness 170, damping 22) or your curve.
- Leaving by a different side than it came in turns it on that side's axis, and the back never ends up upside down.
- With reduced motion the card switches faces at once.

#### Customization

##### Click only, top over bottom

```tsx
<FlipCard trigger="press" axis="x" label="Note" front={front} back={back} />
```

##### A bouncier turn

```tsx
<FlipCard curve={{ type: "spring", stiffness: 220, damping: 12 }} label="Card" front={front} back={back} />
```

### Focus Rail (Pro)

A row of images with one in focus. The rest step back, smaller, dimmer and softer, with the gaps kept even at every size.

Page: https://latheui.dev/components/focus-rail
Install: npx shadcn@latest add @latheui/focus-rail

#### Usage

```tsx
import { FocusRail } from "@/components/ui/focus-rail"

export function Projects({ projects }: { projects: { image: string; name: string }[] }) {
  return (
    <FocusRail
      label="Projects"
      items={projects.map((p) => ({ src: p.image, alt: p.name, title: p.name }))}
      onSelect={(item) => console.log(item.title)}
    />
  )
}
```

#### Props of FocusRail

Also accepts native div attributes.

- `items` (required): `{ src: string; alt: string; title?: string; caption?: string }[]`. The images, in order.
- `label` (required): `string`. Accessible name for the rail.
- `index`: `number`. Controlled index of the item in focus.
- `defaultIndex`: `number`, default `0`. Item in focus to begin with.
- `onIndexChange`: `(index: number) => void`. Called as a new item comes into focus.
- `onSelect`: `(item, index) => void`. Called when the item in focus is clicked, or Enter or Space is pressed.
- `itemWidth`: `number`, default `240`. Width of the item in focus, in px.
- `aspect`: `number`, default `3 / 4`. Width divided by height.
- `gap`: `number`, default `16`. Space between items in px. Stays even as items shrink.
- `falloff`: `number`, default `0.14`. How much smaller each step from the focus gets.
- `minScale`: `number`, default `0.62`. The smallest an item gets.
- `blur`: `number`, default `1.5`. Blur added per step, in px, up to 8.
- `dim`: `number`, default `0.22`. Opacity lost per step.
- `loop`: `boolean`, default `false`. Wrap around instead of stopping at the ends.
- `fadeEdges`: `boolean`, default `true`. Fades the rail out toward its sides.
- `showCaption`: `boolean`, default `true`. Shows the focused item's title and caption.
- `radius`: `number | string`, default `16`. Corner radius of an item.
- `curve`: `Curve`, default `responsive spring`. How the rail settles. Any curve from the Animation Lab; springs carry the flick.
- `duration`: `number`. Milliseconds, for curves that are not springs.
- `renderItem`: `(item, { active }) => ReactNode`. Draw an item yourself instead of the image.

#### Keyboard

- Tab: Focuses the rail.
- ArrowRight / ArrowLeft: Moves the focus one item.
- Home / End: Moves to the first or last item.
- Enter / Space: Selects the item in focus.

#### Accessibility

- The rail is one focusable group with the carousel role description, so it is a single tab stop.
- The item that comes into focus is announced with its title, or its alt text, and its place.
- Sideways trackpad scrolling moves the rail; vertical scrolling still scrolls the page.
- Blur and dimming are visual only; the item in focus is always sharp and fully opaque.

#### Motion

- Each item's position, size, blur and opacity are worked out from its distance to the focus, so everything moves together as one.
- On release a flick carries on for a fifth of a second, then the rail settles with a spring (stiffness 300, damping 34), or your curve.
- Past the first or last item the rail stretches with growing resistance, never more than half a step, and springs back.

#### Customization

##### Square covers that loop

```tsx
<FocusRail label="Albums" items={albums} loop aspect={1} itemWidth={190} falloff={0.18} />
```

##### Flat: no blur or dimming

```tsx
<FocusRail label="Shots" items={items} blur={0} dim={0} falloff={0.08} />
```

### Image Compare

Before and after images under one draggable divider, with a native slider for keyboard and touch.

Page: https://latheui.dev/components/image-compare
Install: npx shadcn@latest add @latheui/image-compare

#### Usage

```tsx
import { ImageCompare } from "@/components/ui/image-compare"

export function Retouch() {
  return (
    <ImageCompare
      before={{ src: "/raw.jpg", alt: "Unedited photo" }}
      after={{ src: "/edited.jpg", alt: "Edited photo with warmer tones" }}
    />
  )
}
```

#### Props of ImageCompare

Also accepts native div attributes.

- `before` (required): `{ src: string; alt: string }`. Image shown left of the divider.
- `after` (required): `{ src: string; alt: string }`. Image shown right of the divider. It sets the component's aspect ratio.
- `value`: `number`. Controlled divider position, 0 to 100.
- `defaultValue`: `number`, default `50`. Initial position when uncontrolled.
- `onValueChange`: `(value: number) => void`. Called as the divider moves.
- `label`: `string`, default `"Comparison position"`. Accessible name of the slider.
- `labels`: `{ before: string; after: string } | null`, default `{ before: "Before", after: "After" }`. Corner captions. null hides them.

#### Keyboard

- ArrowLeft / ArrowRight: Moves the divider by 1%.
- PageUp / PageDown: Moves the divider by 10%.
- Home / End: Shows only the after image, or only the before image.

#### Accessibility

- The control is a native range input stretched over the images. It brings correct slider semantics, keyboard support and touch handling without custom pointer code.
- Its value text says how much of the before image is showing, for example “50% Before”.
- Both images need their own alt text that describes the difference, since the comparison is the point.
- Clicking or tapping anywhere moves the divider there, so the handle is not a small target.
- Use two images with the same dimensions. The before image is cropped to match the after image otherwise.

#### Motion

- The divider follows the pointer on a light spring: it tracks sub-pixel positions, eases into jumps and settles with a slight overshoot. The handle shrinks slightly while pressed.
- The handle stops at the edges so it is never cut off, while the divider line still reaches them.
- With reduced motion, the divider moves directly with no spring, and the press effect is removed.

#### Customization

##### Start mostly on one side

```tsx
<ImageCompare defaultValue={80} labels={{ before: "2019", after: "2026" }} before={before} after={after} />
```

### Lightbox (Pro)

Thumbnails that grow into a full-screen viewer. Swipe, or use the arrow keys or buttons, to move between.

Page: https://latheui.dev/components/lightbox
Install: npx shadcn@latest add @latheui/lightbox

#### Usage

```tsx
import { Lightbox, type LightboxImage } from "@/components/ui/lightbox"

const images: LightboxImage[] = [
  { src: "/photos/coast.jpg", alt: "Cliffs above a grey sea", width: 1600, height: 1067 },
  { src: "/photos/forest.jpg", alt: "Pine forest in fog", width: 1200, height: 1500 },
]

export function Photos() {
  return <Lightbox images={images} label="Trip photos" />
}
```

#### Props of Lightbox

Also accepts native ul attributes for the thumbnail list.

- `images` (required): `LightboxImage[]`. The images, in order.
- `label`: `string`, default `"Image viewer"`. Accessible name of the viewer dialog.
- `layout`: `"row" | "masonry"`, default `"row"`. Thumbnail row or responsive masonry columns.
- `minColumnWidth`: `number`, default `150`. Minimum masonry column width in pixels.
- `strip`: `boolean`, default `true`. Show the viewer thumbnail strip.
- `thumbnailClassName`: `string`. Classes for each thumbnail. Set the row height here.
- `onOpenChange`: `(index: number | null) => void`. Called with the open image's index, and null on close.

#### Props of LightboxImage

- `src` (required): `string`. Image URL. Also used as the item key, so it must be unique.
- `alt` (required): `string`. Describes the image.
- `width` (required): `number`. Intrinsic width in pixels.
- `height` (required): `number`. Intrinsic height in pixels.
- `caption`: `string`. Shown under the open image. Falls back to alt.

#### Keyboard

- Enter / Space: On a thumbnail: opens the viewer at that image.
- ArrowLeft / ArrowRight: Previous or next image.
- + / - / 0: Zoom in, zoom out, or reset zoom.
- Home / End: First or last image.
- Escape: Closes the viewer and moves focus to the thumbnail of the image that was showing.

#### Accessibility

- The viewer is a modal dialog built on Radix Dialog: focus is trapped inside, and on close it moves to the thumbnail of the image that was showing.
- Each thumbnail is a button named after its image. The position and description, such as “Image 2 of 6”, are announced as you move.
- Swiping is one of three ways to navigate. The buttons and arrow keys do the same, and the buttons move below the image on small screens where they are easier to reach.
- Width and height are required so thumbnails and the open image reserve their space before loading.
- The viewer is always dark, in both themes, so photographs are judged against a consistent background.

#### Motion

- Opening grows the thumbnail into place with the gentle spring, and closing returns it. The current image returns to its corresponding thumbnail after navigation.
- Moving between images slides 60px in the direction of travel. A drag that is not far enough springs back.
- With reduced motion, images cross-fade with no growing or sliding.

#### Customization

##### Taller thumbnails

```tsx
<Lightbox images={images} thumbnailClassName="h-40 sm:h-48" className="gap-3" />
```

##### Responsive sources

The viewer renders a plain img, so it works in any framework. To serve smaller thumbnails, point src at your image CDN and add srcSet in the component.

```tsx
<motion.img src={item.src} srcSet={`${item.src}?w=320 320w, ${item.src}?w=640 640w`} sizes="160px" />
```

### Now Playing (Pro)

A music card: cover art that leans toward the pointer, a scrubbable progress bar, transport controls and an accent picked from the artwork.

Page: https://latheui.dev/components/now-playing
Install: npx shadcn@latest add @latheui/now-playing

#### Usage

```tsx
import { NowPlaying } from "@/components/ui/now-playing"

const tracks = [
  { title: "Low Tide", artist: "Mara Vale", cover: "/covers/low-tide.jpg", duration: 214, src: "/audio/low-tide.mp3" },
]

export function Player() {
  return <NowPlaying tracks={tracks} />
}
```

#### Props of NowPlaying

Also accepts native section attributes.

- `tracks` (required): `{ title: string; artist: string; cover: string; duration: number; src?: string }[]`. The queue. With src the audio plays; without it, playback is simulated for designs and demos.
- `index`: `number`. Controlled index of the current track.
- `defaultIndex`: `number`, default `0`. Track to start on.
- `onIndexChange`: `(index: number) => void`. Called when the track changes.
- `playing`: `boolean`. Controlled: whether it is playing.
- `defaultPlaying`: `boolean`, default `false`. Start playing.
- `onPlayingChange`: `(playing: boolean) => void`. Called on play and pause.
- `layout`: `"card" | "bar"`, default `"card"`. A card with a large cover, or a compact row.
- `tilt`: `number`, default `10`. Degrees the cover leans toward the pointer. 0 keeps it flat.
- `glow`: `boolean`, default `true`. A blurred copy of the cover glowing behind it, brighter while playing.
- `accent`: `"auto" | string`, default `"auto"`. Color of the progress and the card's wash. Auto picks the cover's most vivid color.

#### Keyboard

- Tab: Moves between the progress bar and the controls.
- ArrowRight / ArrowLeft: On the progress bar, skips 5 seconds forward or back.
- Home / End: On the progress bar, goes to the start or end.
- Enter / Space: Presses the focused control.

#### Accessibility

- The card is a section named "Now playing". The title and artist are announced when the track changes.
- The progress bar is a slider whose value reads as time, for example "1:23 of 3:34".
- Play, pause, previous and next are labelled buttons. The play button's label changes with its state.
- The cover has alt text from the track title. The glow and the bars beside the title are decorative.
- Previous restarts the track once it is past three seconds, as music players do.

#### Motion

- The cover leans up to 10° toward a mouse pointer, on a spring, with a soft glare that follows it.
- Playing, the cover sits forward; paused, it settles back to 92%.
- Changing track slides the cover in from the side you skipped toward.
- Dragging the progress bar, the fill and a handle glide after the pointer and the times count along; the track seeks once, on release. Clicks and key presses glide the fill to the new spot.
- With reduced motion the cover stays flat and still, and the bars do not move.

#### Customization

##### Your own accent

```tsx
<NowPlaying tracks={tracks} accent="var(--chart-2)" />
```

##### Controlled playback

```tsx
const [playing, setPlaying] = React.useState(false)

<NowPlaying tracks={tracks} playing={playing} onPlayingChange={setPlaying} />
```

### Orbit Gallery (Pro)

Images on a tilted 3D ring. Drag or flick it and it settles on the nearest image; click one to bring it round to the front.

Page: https://latheui.dev/components/orbit-gallery
Install: npx shadcn@latest add @latheui/orbit-gallery

#### Usage

```tsx
import { OrbitGallery } from "@/components/ui/orbit-gallery"

export function Work({ projects }: { projects: { image: string; name: string; year: string }[] }) {
  return (
    <OrbitGallery
      label="Recent work"
      items={projects.map((p) => ({ src: p.image, alt: p.name, title: p.name, caption: p.year }))}
    />
  )
}
```

#### Props of OrbitGallery

Also accepts native div attributes.

- `items` (required): `{ src: string; alt: string; title?: string; caption?: string }[]`. The images, in order around the ring.
- `label` (required): `string`. Accessible name for the gallery.
- `index`: `number`. Controlled index of the item at the front. Changing it turns the ring the short way.
- `defaultIndex`: `number`, default `0`. Item at the front to begin with.
- `onIndexChange`: `(index: number) => void`. Called as a new item reaches the front.
- `itemWidth`: `number`, default `180`. Width of an item in px.
- `aspect`: `number`, default `4 / 5`. Width divided by height.
- `spacing`: `number`, default `28`. Space between neighbours along the ring, in px. Sets the ring's size.
- `radius`: `number`, default `from the items`. Ring radius in px, when you want a fixed size.
- `tilt`: `number`, default `-10`. Degrees the ring leans. Negative looks down onto it.
- `perspective`: `number`, default `1400`. Camera distance in px. Lower is more dramatic.
- `autoRotate`: `number`, default `0`. Degrees per second the ring turns on its own.
- `sensitivity`: `number`, default `0.28`. Degrees turned per pixel dragged.
- `fade`: `number`, default `0.7`. How far items behind the front fade, from 0 to 1.
- `showCaption`: `boolean`, default `true`. Shows the front item's title and caption under the ring.
- `curve`: `Curve`, default `gentle spring`. How the ring settles. Any curve from the Animation Lab; springs carry the speed of a flick.
- `duration`: `number`. Milliseconds, for curves that are not springs.
- `renderItem`: `(item, { active }) => ReactNode`. Draw an item yourself instead of the image.

#### Keyboard

- Tab: Focuses the gallery.
- ArrowRight / ArrowLeft: Turns to the next or previous item.
- Home / End: Turns to the first or last item.

#### Accessibility

- The ring is one focusable group with the carousel role description, so it is a single tab stop.
- The item that reaches the front is announced with its title, or its alt text, and its place, for example "Harbor, 2 of 8".
- The images themselves are decorative to assistive tech; their alt text is what gets announced.
- Vertical page scrolling still works when a touch starts on the ring.
- Auto-rotation stops while the pointer is over the ring or it has focus, and never runs with reduced motion.

#### Motion

- Dragging turns the ring directly. On release it carries on with the flick's speed for about a fifth of a second, then settles on the nearest item with a gentle spring (stiffness 210, damping 28), or your curve.
- Items dim and darken as they go round the back, so the front reads first.
- With reduced motion the ring jumps between items and does not turn on its own.

#### Customization

##### Album covers on a steep ring

```tsx
<OrbitGallery label="Albums" items={albums} itemWidth={140} aspect={1} tilt={-18} autoRotate={14} />
```

##### A curve from the Animation Lab

```tsx
<OrbitGallery label="Work" items={items} curve={{ type: "spring", stiffness: 160, damping: 11 }} />
```

##### Your own items

```tsx
<OrbitGallery
  label="Team"
  items={people}
  renderItem={(person, { active }) => (
    <div className={active ? "bg-primary text-primary-foreground" : "bg-muted"}>{person.title}</div>
  )}
/>
```

### Settle Grid (Pro)

Photos tossed loosely on a table that settle into a neat grid as they come into view, or in step with the scroll.

Page: https://latheui.dev/components/settle-grid
Install: npx shadcn@latest add @latheui/settle-grid

#### Usage

```tsx
import { SettleGrid } from "@/components/ui/settle-grid"

export function Contact({ shots }: { shots: { src: string; alt: string }[] }) {
  return <SettleGrid items={shots} columns={3} />
}
```

#### Props of SettleGrid

Also accepts native div attributes.

- `items` (required): `{ src: string; alt: string }[]`. The photos, in grid order.
- `columns`: `number`, default `3`. Columns in the settled grid.
- `gap`: `number`, default `12`. Space between photos, in px.
- `aspect`: `number`, default `4 / 5`. Width divided by height of each photo.
- `trigger`: `"view" | "scroll"`, default `"view"`. Settle once seen, or in step with the scroll. Ignored when settled is given.
- `settled`: `boolean`. Controlled: true lays the photos in the grid, false scatters them.
- `scatter`: `number`, default `1`. How wild the scatter is, from 0 to 1.5.
- `stagger`: `number`, default `55`. Milliseconds between one photo settling and the next.
- `container`: `RefObject<HTMLElement>`. The scrolling element for trigger="scroll", when not the window. Give it position: relative.
- `curve`: `Curve`, default `spring with a little give`. How each photo settles. Any curve from the Animation Lab.
- `duration`: `number`, default `900`. Milliseconds, for curves that are not springs.
- `radius`: `number | string`, default `10`. Corner radius of a photo.

#### Accessibility

- Photos are plain images with their alt text, in grid order, whatever pose they are in.
- With reduced motion the photos start in the grid and stay there.

#### Motion

- Scattered, each photo is drawn toward the middle of the grid, thrown off at random and turned up to 16°, always the same way.
- Photos settle in a shuffled order, 55ms apart, and their shadows tighten as they land.

#### Customization

##### A wilder toss with a quick settle

```tsx
<SettleGrid items={items} scatter={1.4} stagger={30} curve={{ type: "spring", stiffness: 260, damping: 20 }} />
```

### Shelf Flow (Pro)

Covers on a shelf: the one in front faces you, the rest turn on their sides and stack, with a soft reflection beneath.

Page: https://latheui.dev/components/shelf-flow
Install: npx shadcn@latest add @latheui/shelf-flow

#### Usage

```tsx
import { ShelfFlow } from "@/components/ui/shelf-flow"

export function Albums({ albums }: { albums: { title: string; artist: string; cover: string }[] }) {
  return (
    <ShelfFlow
      label="Albums"
      items={albums.map((a) => ({ src: a.cover, alt: a.title, title: a.title, caption: a.artist }))}
    />
  )
}
```

#### Props of ShelfFlow

Also accepts native div attributes.

- `items` (required): `{ src: string; alt: string; title?: string; caption?: string }[]`. The covers, in order.
- `label` (required): `string`. Accessible name for the shelf.
- `index`: `number`. Controlled index of the cover at the front.
- `defaultIndex`: `number`, default `the middle`. Cover at the front to begin with.
- `onIndexChange`: `(index: number) => void`. Called as a new cover reaches the front.
- `onSelect`: `(item, index) => void`. Called when the front cover is clicked, or Enter or Space is pressed.
- `itemWidth`: `number`, default `200`. Width of a cover in px.
- `aspect`: `number`, default `1`. Width divided by height.
- `angle`: `number`, default `62`. Degrees the side covers are turned.
- `opening`: `number`, default `0.62`. Space between the front cover and its neighbours, as a fraction of the cover width.
- `spacing`: `number`, default `0.24`. Space between stacked side covers, as a fraction of the cover width.
- `depth`: `number`, default `180`. How far back the side covers sit, in px.
- `perspective`: `number`, default `1000`. Camera distance in px.
- `reflection`: `boolean`, default `true`. A faded mirror image under each cover.
- `showCaption`: `boolean`, default `true`. The front cover's title and caption.
- `curve`: `Curve`, default `smooth spring`. How the shelf settles. Any curve from the Animation Lab.
- `duration`: `number`. Milliseconds, for curves that are not springs.

#### Keyboard

- Tab: Focuses the shelf.
- ArrowRight / ArrowLeft: Brings the next or previous cover to the front.
- Home / End: The first or last cover.
- Enter / Space: Selects the front cover.

#### Accessibility

- The shelf is one focusable group with the carousel role description. The cover reaching the front is announced with its title and place.
- Covers and reflections are decorative to assistive tech; titles and alt text carry the meaning.
- With reduced motion covers stay flat, without turning.

#### Motion

- Within one step of the front, position, turn and depth all blend, so covers swing round rather than snapping.
- Side covers darken a little with distance. The shelf settles on a spring (stiffness 260, damping 32), carrying a flick's speed.

#### Customization

##### Wide photos, a shallow turn

```tsx
<ShelfFlow label="Photos" items={photos} itemWidth={240} aspect={3 / 2} angle={45} reflection={false} />
```

### Shutter Reveal (Pro)

An image gallery that changes images in slices: sliding in, opening like blinds, or folding round in 3D.

Page: https://latheui.dev/components/shutter-reveal
Install: npx shadcn@latest add @latheui/shutter-reveal

#### Usage

```tsx
import { ShutterReveal } from "@/components/ui/shutter-reveal"

export function Featured({ shots }: { shots: { src: string; alt: string }[] }) {
  return <ShutterReveal label="Featured work" images={shots} interval={4000} />
}
```

#### Props of ShutterReveal

Also accepts native div attributes. Size it with className; it is 16:10 by default.

- `images` (required): `{ src: string; alt: string }[]`. The images, in order.
- `label` (required): `string`. Accessible name for the gallery.
- `index`: `number`. Controlled index of the image shown.
- `defaultIndex`: `number`, default `0`. Image to start on.
- `onIndexChange`: `(index: number) => void`. Called when the image changes.
- `slices`: `number`, default `8`. How many slices the next image arrives in.
- `orientation`: `"vertical" | "horizontal"`, default `"vertical"`. Columns or rows.
- `effect`: `"slide" | "blinds" | "fold"`, default `"slide"`. How each slice arrives.
- `order`: `"sweep" | "center" | "random"`, default `"sweep"`. The order slices start in. Random is seeded, so it repeats.
- `stagger`: `number`, default `45`. Milliseconds between one slice starting and the next.
- `interval`: `number`, default `0`. Milliseconds between images when playing on its own. 0 is off.
- `controls`: `boolean`, default `true`. Previous and next buttons, and the counter.
- `curve`: `Curve`, default `expo out`. How each slice moves. Any curve from the Animation Lab.
- `duration`: `number`, default `750`. Milliseconds each slice takes, for curves that are not springs.

#### Keyboard

- Tab: Focuses the gallery, then its buttons.
- ArrowRight / ArrowLeft: Next or previous image.

#### Accessibility

- The gallery is a focusable group with the carousel role description. Each new image is announced by its alt text and place.
- Slices are decoration; only the image's alt text is read.
- Playing on its own stops while the pointer or focus is on the gallery, and while a preview is paused.
- With reduced motion the next image fades in whole.

#### Motion

- Each slice moves on an expo-out curve over 750ms by default, starting 45ms after the one before it in the chosen order.
- A change started mid-change finishes the first at once, so clicks never queue up.

#### Customization

##### Venetian blinds from the middle

```tsx
<ShutterReveal label="Work" images={images} effect="blinds" order="center" slices={12} />
```

##### Folding rows on a spring

```tsx
<ShutterReveal label="Work" images={images} effect="fold" orientation="horizontal" curve={{ type: "spring", stiffness: 160, damping: 18 }} />
```

### Zoom Frame (Pro)

Media that starts as an inset, rounded card and opens to fill the view as the page scrolls, then softens as it leaves.

Page: https://latheui.dev/components/zoom-frame
Install: npx shadcn@latest add @latheui/zoom-frame

#### Usage

```tsx
import { ZoomFrame } from "@/components/ui/zoom-frame"

export function Hero() {
  return (
    <ZoomFrame overlay={<h1 className="text-6xl text-white">The studio</h1>}>
      <video src="/reel.mp4" autoPlay muted loop playsInline />
    </ZoomFrame>
  )
}
```

#### Props of ZoomFrame

Also accepts native section attributes. The section is as tall as the scroll it takes; the frame sticks to the top while it plays.

- `children` (required): `ReactNode`. The media: an img, a video, or anything that covers its box.
- `overlay`: `ReactNode`. Laid over the media, for a headline. It fades as the frame opens.
- `startWidth`: `number`, default `0.56`. Width of the closed frame, as a fraction of the view.
- `startHeight`: `number`, default `0.6`. Height of the closed frame, as a fraction of the view.
- `radius`: `number`, default `28`. Corner radius of the closed frame, in px.
- `length`: `number`, default `2.4`. How far the section scrolls, in view heights.
- `openAt`: `number`, default `0.6`. Fraction of the scroll at which the frame is fully open.
- `exit`: `"none" | "blur" | "fade"`, default `"blur"`. What happens over the rest of the scroll.
- `zoom`: `number`, default `1.18`. The media starts this much larger and settles as the frame opens.
- `viewportHeight`: `string`, default `"100dvh"`. Height of the view the frame fills. Use the scrolling container's height when it is not the window.
- `container`: `RefObject<HTMLElement>`. The element that scrolls, when it is not the window. Give it position: relative so the frame's place in it is measured from its top.
- `curve`: `Curve`, default `power 2, in and out`. How the frame opens against the scroll. Any curve from the Animation Lab.

#### Accessibility

- It adds no controls or roles: the media inside keeps its own alt text, captions and video controls.
- Overlay text sits on the media, so give it a shadow or a scrim for contrast.
- With reduced motion the frame is open from the start and nothing zooms or blurs; the section still scrolls past.

#### Motion

- Everything follows the scroll position, not time: scroll back up and it closes again.
- The frame opens by clipping, not scaling, so the media is never resampled; only its gentle zoom moves it.

#### Customization

##### On the window, opening fast

```tsx
<ZoomFrame openAt={0.4} length={2}>
  <img src="/hero.jpg" alt="The studio" />
</ZoomFrame>
```

## Gestures

### Card Stack (Pro)

A stack or a loose pile of cards. Throw the front card in any direction and it tucks in at the back.

Page: https://latheui.dev/components/card-stack
Install: npx shadcn@latest add @latheui/card-stack

#### Usage

```tsx
import { CardStack } from "@/components/ui/card-stack"

export function Quotes({ quotes }: { quotes: { id: string; text: string }[] }) {
  return (
    <CardStack
      label="Quotes"
      items={quotes}
      getId={(quote) => quote.id}
      getLabel={(quote) => quote.text}
      renderCard={(quote) => <p className="p-6 text-lg">{quote.text}</p>}
    />
  )
}
```

#### Props of CardStack

Also accepts native div attributes. Size the stack with className; every card fills it.

- `items` (required): `T[]`. The cards, front first.
- `getId` (required): `(item: T) => string`. A stable key per card.
- `getLabel` (required): `(item: T) => string`. Announced when the card comes to the front.
- `renderCard` (required): `(item: T) => ReactNode`. A card's content. It is clipped to the card's rounded corners.
- `label` (required): `string`. Accessible name for the stack.
- `index`: `number`. Controlled index of the front card.
- `defaultIndex`: `number`, default `0`. Initial front card when uncontrolled.
- `onIndexChange`: `(index: number) => void`. Called when another card comes to the front.
- `depth`: `number`, default `2`. Cards visible behind the front one.
- `layout`: `"stack" | "pile"`, default `"stack"`. A neat stack that rises behind the front card, or a loose pile like prints on a table.
- `offset`: `number`, default `12, or 14 in a pile`. Pixels each card behind rises. In a pile, how far cards stray.
- `scaleStep`: `number`, default `0.065`. How much smaller each card behind gets.
- `rotation`: `number`, default `5`. Degrees cards behind turn, alternating sides. In a pile, the most a card turns.
- `spreadOnHover`: `boolean`, default `true`. Fans the stack a little under a mouse pointer.
- `throwDistance`: `number`, default `80`. Pixels a drag must travel to throw the card. A flick faster than 500px/s throws it sooner.
- `curve`: `Curve`, default `soft spring`. How cards move between places. Any curve from the Animation Lab.
- `duration`: `number`. Milliseconds, for curves that are not springs.

#### Keyboard

- Space / Enter: Brings the next card forward.
- ArrowRight / ArrowDown: Next card.
- ArrowLeft / ArrowUp: Previous card.

#### Accessibility

- One button sits over the stack, so it is a single stop for the keyboard.
- The card that comes to the front is announced with its place in the stack, for example "Make room to play., 2 of 3".
- Cards are hidden from assistive tech, so keep anything a card needs to say in its label.
- Vertical scrolling still works when a touch swipe starts on the stack.

#### Motion

- Cards spring between places with a stiffness of 260 and a damping of 26, or with the curve you pass. Each place back is 12px higher, 6.5% smaller and turned 5° to alternate sides.
- A thrown card keeps its speed and direction, flies clear of the stack over the others, then slips in underneath. A click sends it up and to the right.
- Going back pulls the last card out from under the stack and lays it on top.
- Under a mouse pointer the stack fans out by half again.
- With reduced motion, cards jump to their places.

#### Customization

##### A pile of photos

```tsx
<CardStack layout="pile" depth={4} rotation={6} className="h-72 w-60" {...props} />
```

##### A tighter, springier stack

```tsx
<CardStack offset={8} scaleStep={0.04} curve={{ type: "spring", stiffness: 420, damping: 22 }} {...props} />
```

##### Show more of the stack

```tsx
<CardStack depth={4} className="h-56 w-72" {...props} />
```

### Elastic Strip (Pro)

A row of cards you drag sideways. Cards further from your grab trail behind, so the strip stretches and leans, then springs straight.

Page: https://latheui.dev/components/elastic-strip
Install: npx shadcn@latest add @latheui/elastic-strip

#### Usage

```tsx
import { ElasticStrip } from "@/components/ui/elastic-strip"

export function Picks({ albums }: { albums: { title: string; cover: string }[] }) {
  return (
    <ElasticStrip label="Picks" cardWidth={200}>
      {albums.map((album) => <img key={album.title} src={album.cover} alt={album.title} className="rounded-xl" />)}
    </ElasticStrip>
  )
}
```

#### Props of ElasticStrip

Also accepts native div attributes. Each child is one card; size the strip's height with className.

- `children` (required): `ReactNode`. The cards.
- `label` (required): `string`. Accessible name for the strip.
- `cardWidth`: `number`, default `220`. Width of a card, in px.
- `gap`: `number`, default `16`. Space between cards, in px.
- `elasticity`: `number`, default `0.7`. How much cards far from the grab trail behind, from 0 (rigid) to 1.
- `bend`: `number`, default `9`. Degrees a trailing card leans. 0 keeps cards upright.
- `snap`: `boolean`, default `true`. Settle with a card's edge at the start after a fling.

#### Keyboard

- Tab: Focuses the strip.
- ArrowRight / ArrowLeft: Moves one card.

#### Accessibility

- The strip is one focusable group with the carousel role description; arrow keys move it a card at a time.
- Sideways trackpad scrolling moves it; vertical scrolling still scrolls the page, including on touch.
- With reduced motion the cards move together, without trailing or leaning, and a fling does not coast.

#### Motion

- Every card chases the strip at its own rate, slower the further it is from the card you grabbed, so the strip stretches like a chain.
- A card leans by how far behind it is, from its bottom edge, and stretches slightly while it catches up.
- A fling coasts, slowing by 8% a frame, then settles on the nearest card. Past either end the strip gives a little and pulls back.

#### Customization

##### Loose as a chain

```tsx
<ElasticStrip label="Shots" elasticity={1} bend={18}>{cards}</ElasticStrip>
```

### File Dropzone (Pro)

Drop or browse for files. Validates type, size and count, explains rejections, and lists what was added.

Page: https://latheui.dev/components/file-dropzone
Install: npx shadcn@latest add @latheui/file-dropzone

#### Usage

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

export function Attachments() {
  const [files, setFiles] = React.useState<File[]>([])
  return (
    <FileDropzone
      files={files}
      onFilesChange={setFiles}
      accept=".pdf,image/*"
      maxSize={5 * 1024 * 1024}
      hint="PDF or images, up to 5 MB"
    />
  )
}
```

#### Props of FileDropzone

Also accepts native div attributes.

- `files`: `File[]`. Controlled list of accepted files.
- `onFilesChange`: `(files: File[]) => void`. Called with the full list when files are added or removed.
- `accept`: `string`. Allowed types, as on a file input: extensions, MIME types or wildcards such as image/*.
- `multiple`: `boolean`, default `true`. Allow more than one file. When false, a new file replaces the old one.
- `maxSize`: `number`. Largest allowed file, in bytes.
- `maxFiles`: `number`. Most files allowed in total.
- `disabled`: `boolean`, default `false`. Prevents adding and removing.
- `label`: `string`, default `"Drop files here, or click to browse"`. Main text in the drop area.
- `hint`: `string`. Second line, usually the constraints. Linked as the input's description.
- `name`: `string`. Name of the underlying file input.

#### Keyboard

- Tab: Focuses the file input, then each file's remove button.
- Enter / Space: On the drop area: opens the file browser. On a remove button: removes the file.

#### Accessibility

- The drop area is a label around a real file input. Clicking, tapping and the keyboard all open the system file browser, so dragging is never required.
- Rejected files are explained by name in an alert region, with the reason: wrong type, too large, a duplicate, or over the limit.
- State the constraints up front in hint. It is linked to the input, so it is read before someone picks a file rather than after they fail.
- Each remove button is named after its file. After removing, focus returns to the file input instead of being lost.
- Dropped files are validated against accept as well, since the browser only applies it to the file browser.

#### Motion

- The icon lifts 4px while files are dragged over the area. File rows grow in and collapse out over 220ms.
- With reduced motion, the icon stays put and rows appear and disappear instantly.

#### Customization

##### Uploading

The component collects and validates files; uploading is yours. Control the list and clear it when the upload finishes.

```tsx
async function upload() {
  await Promise.all(files.map((file) => send(file)))
  setFiles([])
}
```

##### Compact drop area

```tsx
<FileDropzone className="[&_label]:flex-row [&_label]:py-4" label="Attach files" />
```

### Resizable Panels (Pro)

Two panes with a draggable divider, percentage limits, keyboard resizing and optional collapse.

Page: https://latheui.dev/components/resizable-panels
Install: npx shadcn@latest add @latheui/resizable-panels

#### Usage

```tsx
import { ResizablePanels } from "@/components/ui/resizable-panels"

export default function Workspace() {
  return <ResizablePanels
    label="Workspace"
    collapsible
    primary={<div className="p-4">Files</div>}
    secondary={<div className="p-4">Editor</div>}
  />
}
```

#### Props of ResizablePanels

- `label` (required): `string`. Names the panel group and divider.
- `primary / secondary` (required): `React.ReactNode`. Content of the first and second pane. Overflow scrolls inside each pane.
- `value / defaultValue`: `number`, default `40 (defaultValue)`. Controlled or initial percentage of pane space assigned to the first pane. Zero collapses it when collapsible.
- `onValueChange`: `(value: number) => void`. Called during pointer or keyboard changes, with a percentage rounded to one decimal place.
- `min / max`: `number`, default `20 / 80`. Minimum and maximum first-pane percentages. Clamped to 5–95 with max at least min.
- `orientation`: `"horizontal" | "vertical"`, default `"horizontal"`. Horizontal places panes side by side; vertical stacks them.
- `collapsible`: `boolean`, default `false`. Allow zero size with Enter, Home, or dragging below half the minimum.
- `disabled`: `boolean`, default `false`. Disable resizing and remove the divider from the tab order.
- `className`: `string`. Override the outer frame, including its default h-64 height.

#### Keyboard

- ArrowLeft / ArrowRight: Resize a side-by-side split by 2 percentage points. Direction follows RTL layouts.
- ArrowUp / ArrowDown: Resize a stacked split by 2 percentage points.
- Shift / Arrow keys: Resize by 10 percentage points.
- Home / End: Move to the minimum (or collapse) and maximum.
- Enter: Collapse or restore the first pane when collapsible is enabled.

#### Accessibility

- The focusable separator exposes orientation, minimum, maximum, current percentage and the controlled pane ID.
- Collapsed content is inert and hidden from assistive technology.
- Pointer capture keeps dragging active outside the divider. Touch gestures on the handle do not scroll the page.

#### Motion

- The divider follows input directly without inertia or animated pane sizes.
- Only handle colors transition; no movement is introduced for reduced-motion users.

#### Customization

##### Save a preferred split

Keep the percentage in parent state and persist it using your app’s settings. Give stacked panels an explicit height.

```tsx
<ResizablePanels
  label="Editor and output"
  orientation="vertical"
  value={size}
  onValueChange={setSize}
  min={25}
  max={75}
  className="h-96"
  primary={<Editor />}
  secondary={<Output />}
/>
```

### Selection Area (Pro)

Drag a box across items to select them, as on a desktop. Caught items dip and keep an outline.

Page: https://latheui.dev/components/selection-area
Install: npx shadcn@latest add @latheui/selection-area

#### Usage

```tsx
import { SelectionArea, SelectionItem } from "@/components/ui/selection-area"

export function Files({ files }: { files: { id: string; name: string }[] }) {
  const [selected, setSelected] = React.useState<string[]>([])
  return (
    <SelectionArea label="Files" value={selected} onValueChange={setSelected} className="grid grid-cols-4 gap-3 p-4">
      {files.map((file) => (
        <SelectionItem key={file.id} id={file.id} className="p-3 data-selected:bg-accent">
          {file.name}
        </SelectionItem>
      ))}
    </SelectionArea>
  )
}
```

#### Props of SelectionArea

Also accepts native div attributes. Lay the items out with className: grid, flex or anything else.

- `label` (required): `string`. Accessible name of the group of items.
- `value`: `string[]`. Controlled selection, as item ids.
- `defaultValue`: `string[]`, default `[]`. Initial selection when uncontrolled.
- `onValueChange`: `(value: string[]) => void`. Called as the selection changes, including during a drag.

#### Props of SelectionItem

Also accepts motion.div props. Selected items carry data-selected for styling.

- `id` (required): `string`. Unique within the area.
- `children` (required): `ReactNode`. The item's content.

#### Keyboard

- Tab: Moves between items.
- Space / Enter: Selects or deselects the focused item.
- Ctrl+A / ⌘A: Selects everything.
- Escape: Clears the selection.

#### Accessibility

- The area is a multi-select listbox and each item is an option that reports whether it is selected, so everything the box does can be done from the keyboard.
- The number of selected items is announced as it changes.
- Dragging a box is a mouse and pen gesture. On touch it would fight scrolling, so touch users tap items to toggle them.
- Selection is shown by an outline as well as a background, so it does not rely on color alone.

#### Motion

- The box follows the pointer on a tight spring: it never visibly lags, but its edges round off instead of jittering. It fades out on release.
- An item dips to 94% and settles as it is selected.
- With reduced motion the box tracks the pointer exactly and items do not scale.

#### Customization

##### Style the selected state

```tsx
<SelectionItem id={photo.id} className="overflow-hidden data-selected:opacity-80 data-selected:ring-chart-2">
  <img src={photo.src} alt={photo.alt} />
</SelectionItem>
```

##### Act on the selection

```tsx
const [selected, setSelected] = React.useState<string[]>([])

<SelectionArea label="Photos" value={selected} onValueChange={setSelected}>{items}</SelectionArea>
<Button disabled={selected.length === 0} onClick={() => remove(selected)}>
  Delete {selected.length || ""}
</Button>
```

### Sortable List (Pro)

A list you reorder by dragging a handle, or entirely from the keyboard, with every move announced.

Page: https://latheui.dev/components/sortable-list
Install: npx shadcn@latest add @latheui/sortable-list

#### Usage

```tsx
import { SortableList } from "@/components/ui/sortable-list"

export function Steps() {
  const [steps, setSteps] = React.useState([
    { id: "1", title: "Collect requirements" },
    { id: "2", title: "Draft proposal" },
  ])

return (
    <SortableList
      label="Steps"
      items={steps}
      onReorder={setSteps}
      getId={(step) => step.id}
      getLabel={(step) => step.title}
      renderItem={(step) => <span className="text-sm">{step.title}</span>}
    />
  )
}
```

#### Props of SortableList<T>

Controlled only: it renders the order you give it.

- `items` (required): `T[]`. Items in their current order.
- `onReorder` (required): `(items: T[]) => void`. Called with the new order as items move.
- `getId` (required): `(item: T) => string`. Stable, unique id for an item.
- `getLabel` (required): `(item: T) => string`. Plain-text name, used for the handle's name and for announcements.
- `renderItem` (required): `(item: T, state: { dragging: boolean }) => ReactNode`. Row content. dragging is true while the row is lifted.
- `label` (required): `string`. Accessible name of the list.
- `className`: `string`. Classes for the list.
- `itemClassName`: `string`. Classes for each row.

#### Keyboard

- Tab: Moves between the reorder handles (and any controls in the rows).
- Space / Enter: Grabs the item, or drops it if it is already grabbed.
- ArrowUp / ArrowDown: Moves the grabbed item one position.
- Home / End: Moves the grabbed item to the top or bottom.
- Escape: Cancels and returns the item to where it started.

#### Accessibility

- Everything that can be done by dragging can be done from the keyboard. Drag and drop is never the only way to reorder.
- Grabbing, each move, dropping and cancelling are announced with the item's name and its position, such as “moved to position 2 of 4”.
- Each handle is a button named “Reorder” plus the item's label, with the instructions attached as its description.
- The handle is the only drag target. That leaves the row free for other controls and lets the page scroll normally when a finger lands on a row.
- Focus stays on the handle as the item moves, and moving focus away drops the item in place.

#### Motion

- A lifted row scales to 102% and gains a shadow. The other rows move out of the way with the smooth spring.
- With reduced motion, rows swap places instantly and the lifted row does not scale. The shadow still shows which row is held.

#### Customization

##### React to the lifted state

```tsx
renderItem={(item, { dragging }) => (
  <span className={dragging ? "font-medium" : undefined}>{item.title}</span>
)}
```

##### Save when the order settles

onReorder fires on every swap while dragging. Debounce it, or save on a separate effect.

```tsx
React.useEffect(() => {
  const timer = setTimeout(() => saveOrder(items.map((item) => item.id)), 600)
  return () => clearTimeout(timer)
}, [items])
```

### Swipe Deck (Pro)

A stack of cards you sort one at a time by swiping left or right. Buttons and arrow keys do the same thing.

Page: https://latheui.dev/components/swipe-deck
Install: npx shadcn@latest add @latheui/swipe-deck

#### Usage

```tsx
import { SwipeDeck } from "@/components/ui/swipe-deck"

export function Review({ candidates }: { candidates: { id: string; name: string }[] }) {
  return (
    <SwipeDeck
      label="Candidates"
      items={candidates}
      getId={(person) => person.id}
      getLabel={(person) => person.name}
      labels={{ left: "Pass", right: "Shortlist" }}
      onSwipe={(person, direction) => record(person.id, direction)}
      renderCard={(person) => <div className="p-4">{person.name}</div>}
    />
  )
}
```

#### Props of SwipeDeck<T>

Tracks which cards are gone internally. Change its key to reset it. Also accepts native div attributes.

- `items` (required): `T[]`. The cards, top first.
- `getId` (required): `(item: T) => string`. Stable, unique id for a card.
- `getLabel` (required): `(item: T) => string`. Plain-text name, used for the card's name and for announcements.
- `renderCard` (required): `(item: T) => ReactNode`. Card content.
- `label` (required): `string`. Accessible name of the deck.
- `onSwipe`: `(item: T, direction: "left" | "right") => void`. Called when a card leaves the deck.
- `labels`: `{ left: string; right: string }`, default `{ left: "Skip", right: "Save" }`. Names of the two outcomes, for the buttons, stamps and announcements.
- `empty`: `ReactNode`, default `"You are all caught up."`. Shown when no cards are left.
- `threshold`: `number`, default `110`. Drag distance in pixels past which releasing commits the swipe.

#### Keyboard

- Tab: Focuses the top card, then the two buttons.
- ArrowLeft / ArrowRight: On the top card: sends it left or right. Focus moves to the next card.
- Enter / Space: On a button: sends the top card that way.

#### Accessibility

- Swiping is a shortcut. The two buttons are always present and do exactly the same thing, so no gesture is required.
- Each decision is announced with the outcome, the card's name and the next card, for example “Save: Morning ridge. Next: Red valley.”
- Only the top card is exposed to assistive tech. The cards beneath are decorative until they reach the top.
- The direction stamp uses the outcome's name, not just a color or a tilt.
- Vertical drags still scroll the page; only horizontal movement moves the card.
- A swipe cannot be undone by the component. If the action matters, offer an undo, for example with a toast.

#### Motion

- The top card follows the drag and tilts up to 12 degrees. Released early, it springs back; past the threshold, it leaves in 280ms and the next cards move up.
- With reduced motion, the card does not tilt and fades out in place instead of flying off.

#### Customization

##### Undo with a toast

```tsx
onSwipe={(item, direction) => {
  save(item, direction)
  toast(`${direction === "right" ? "Saved" : "Skipped"} ${item.name}`, {
    action: { label: "Undo", onClick: () => revert(item) },
  })
}}
```

##### Card size

The deck is 4:5 and fills its width. Change the width on the root and the ratio inside the file.

```tsx
<SwipeDeck className="max-w-sm" … />
```

## Text

### Cinematic Text (Pro)

A headline whose words drift out of a heavy blur and settle into focus as it scrolls into view.

Page: https://latheui.dev/components/cinematic-text
Install: npx shadcn@latest add @latheui/cinematic-text

#### Usage

```tsx
import { CinematicText } from "@/components/ui/cinematic-text"

export function Hero() {
  return (
    <CinematicText as="h1" className="text-6xl font-semibold tracking-tight">
      Interfaces that move with intent.
    </CinematicText>
  )
}
```

#### Props of CinematicText

Also accepts native attributes of the element it renders.

- `children` (required): `string`. The text. It is split on spaces.
- `as`: `"h1" | "h2" | "h3" | "h4" | "p" | "span" | "div"`, default `"p"`. Element to render.
- `delay`: `number`, default `0`. Seconds before the first word starts.
- `stagger`: `number`, default `0.09`. Seconds between words.
- `duration`: `number`, default `0.9`. Seconds each word takes to settle.
- `blur`: `number`, default `14`. Blur radius in pixels each word starts from.
- `distance`: `number`, default `14`. Pixels each word drifts down.
- `once`: `boolean`, default `true`. Play once, or every time the text scrolls back into view.

#### Accessibility

- Screen readers get the full sentence once, as plain text. The animated words are hidden from them.
- Pick the element with as so the text keeps its place in the heading outline.
- The text is real text: it can be selected, translated and found with in-page search.
- Keep it to short lines. A reader should never wait on an animation to finish a paragraph.

#### Motion

- Each word fades in, drops 14px and sharpens from a 14px blur over 900ms, 90ms after the one before.
- It starts when 40% of the text is in view.
- With reduced motion the line is not split. It fades in as one block, with no blur or movement.

#### Customization

##### Slower and softer

```tsx
<CinematicText as="h1" stagger={0.16} duration={1.4} blur={24} className="text-7xl font-semibold">
  Take your time.
</CinematicText>
```

##### Replay on every visit

```tsx
<CinematicText once={false}>Seen again each time it scrolls into view.</CinematicText>
```

### Kbd

Keyboard shortcut hints drawn as keycaps. Labels follow the visitor's platform, and the caps press down while the real keys are held.

Page: https://latheui.dev/components/kbd
Install: npx shadcn@latest add @latheui/kbd

#### Usage

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

// ⌘K on Apple platforms, Ctrl K elsewhere
<Kbd keys="mod+k" />

// A sequence: G, then D
<Kbd keys="g d" />
```

#### Props of Kbd

Also accepts every native kbd attribute.

- `keys`: `string | string[]`. The shortcut. Join keys pressed together with +, such as "mod+shift+p", and separate steps of a sequence with a space, such as "g d". An array is one combination, one key per entry. Compact strings such as "⌘K" work too.
- `children`: `string`. A single key written out, used when keys is not given.
- `variant`: `"outline" | "soft" | "ghost"`, default `"outline"`. Keycap, tinted, or text only.
- `size`: `"sm" | "md" | "lg"`, default `"md"`. Cap height: 18, 20 or 24 pixels.
- `listen`: `boolean`, default `true`. Presses each cap while its key is held. All caps on a page share one set of listeners.
- `platform`: `"mac" | "other"`, default `detected`. Forces Apple or other labels, for example in a screenshot.
- `keyClassName`: `string`. Classes for each cap.

#### Props of Key names

Case does not matter. Anything else is shown as written, with single letters capitalized.

- `mod`: `⌘ / Ctrl`. Command on Apple platforms, Control elsewhere. Use it for cross-platform shortcuts.
- `cmd, ctrl, alt, shift`: `⌘ ⌃ ⌥ ⇧`. Specific modifiers. On Windows and Linux, ctrl, alt and shift are written out.
- `enter, esc, tab, space`: `↵ Esc Tab Space`. Common keys. return and escape work too.
- `backspace, delete`: `⌫ ⌦`. Written out on Windows and Linux.
- `up, down, left, right`: `↑ ↓ ← →`. Arrow keys.
- `plus`: `+`. The plus key, which can't be written inside a combination.

#### Props of Helpers

Exported alongside Kbd for binding the same shortcut strings.

- `matchesShortcut(event, keys)`: `boolean`. Whether a key event is exactly the shortcut, such as "mod+z". Extra modifiers do not match.
- `formatShortcut(keys)`: `string`. The shortcut as text in the platform's style: "⌘K" or "Ctrl+K". Useful for titles.
- `usePlatform()`: `"mac" | "other"`. The visitor's platform. Starts as mac on the server and the first render, so markup never mismatches.

#### Accessibility

- Uses kbd elements, nested for combinations, the way HTML describes keyboard input.
- Each symbol has a spoken name for screen readers, so ⌘⇧P is read as "Command Shift P", and sequences are read with "then" between steps.
- A hint is never the only way to an action. Keep a visible control for anything a shortcut does.
- Pressing only changes how the caps look. It never prevents or handles the key.

#### Motion

- A held key's cap sinks one pixel and loses its bottom edge in 75ms, and springs back on release.
- With reduced motion, caps change color but do not move.

#### Customization

##### Bind the shortcut you show

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

React.useEffect(() => {
  const onKeyDown = (event: KeyboardEvent) => {
    if (matchesShortcut(event, "mod+s")) {
      event.preventDefault()
      save()
    }
  }
  window.addEventListener("keydown", onKeyDown)
  return () => window.removeEventListener("keydown", onKeyDown)
}, [])

<Button onClick={save}>
  Save <Kbd keys="mod+s" variant="soft" size="sm" />
</Button>
```

##### Restyle the caps

```tsx
<Kbd keys="mod+k" keyClassName="rounded-full bg-muted px-2 border-transparent shadow-none" />
```

### Rise Text (Pro)

Letters rise into place one beat at a time, out of a clipped line. An entrance with a little character.

Page: https://latheui.dev/components/rise-text
Install: npx shadcn@latest add @latheui/rise-text

#### Usage

```tsx
import { RiseText } from "@/components/ui/rise-text"

export function Hero() {
  return (
    <h1 className="text-6xl font-semibold">
      <RiseText text="Make moves." />
    </h1>
  )
}
```

#### Props of RiseText

Also accepts native span attributes. Size, weight and color come from className.

- `text` (required): `string`. The text to show.
- `delay`: `number`, default `0`. Seconds before the first letter moves.
- `stagger`: `number`, default `0.055`. Seconds between one letter and the next.
- `duration`: `number`, default `1`. Seconds each letter takes to rise.
- `trigger`: `"mount" | "inView"`, default `"inView"`. Play as soon as it mounts, or once it scrolls into view.

#### Accessibility

- Screen readers get the text once, as plain text. The letters are hidden from them.
- Put it inside a heading or paragraph for the right semantics. It renders a span.

#### Motion

- Each letter rises from below its line with a slight tilt over one second, on a long ease out.
- It runs on the Web Animations API and plays once.
- With reduced motion, the text is shown complete.

#### Customization

##### Play again

Change the key to play the entrance from the start.

```tsx
<RiseText key={run} text="Make moves." />
```

### Stagger Text (Pro)

Text that swaps for a second line on hover, its letters rolling one after another under a wave of color.

Page: https://latheui.dev/components/stagger-text
Install: npx shadcn@latest add @latheui/stagger-text

#### Usage

```tsx
import { StaggerText } from "@/components/ui/stagger-text"

export function Tagline() {
  return <StaggerText text="Hover me" hoverText="Well done" className="text-5xl font-semibold" />
}
```

#### Props of StaggerText

Also accepts native span attributes. Size and weight come from className.

- `text` (required): `string`. Text at rest. This is what assistive tech reads.
- `hoverText` (required): `string`. Text while hovered or active.
- `interval`: `number`, default `28`. Milliseconds between letters.
- `colors`: `string[]`, default `chart tokens 1, 3 and 4`. Colors the letters pass through. Any CSS colors. An empty array turns the wave off.
- `active`: `boolean`. Controlled state.
- `onActiveChange`: `(active: boolean) => void`. Called when hover or a tap changes the state.

#### Accessibility

- Assistive tech reads only the resting text. The swap is decoration, so never put information in hoverText that is not available elsewhere.
- It is not focusable on its own. Inside a link or button, drive it with active from that element's hover and focus, as the second example does.
- It reserves the width of the longer line, so nothing around it moves when it swaps.

#### Motion

- Letters leave upward and arrive from below on the smooth spring, 28ms apart.
- Each letter takes an accent color as the wave reaches it and returns to the text color after.
- With reduced motion the lines cross-fade in place and the color wave still passes.

#### Customization

##### Your own colors and pace

```tsx
<StaggerText
  text="Design"
  hoverText="Engineer"
  interval={45}
  colors={["var(--chart-2)", "var(--chart-5)"]}
/>
```

### Text Morph (Pro)

Text that rearranges through shared letters as the phrase changes.

Page: https://latheui.dev/components/text-morph
Install: npx shadcn@latest add @latheui/text-morph

#### Usage

```tsx
import * as React from "react"
import { TextMorph } from "@/components/ui/text-morph"
import { Button } from "@/components/ui/button"
export default function Demo(){const [index,setIndex]=React.useState(0);const words=["Design with care","Build with purpose","Make it your own"];return <div className="flex max-w-full flex-col items-center gap-6"><TextMorph className="max-w-full text-xl font-medium">{words[index]}</TextMorph><Button variant="outline" size="sm" onClick={()=>setIndex((index+1)%words.length)}>Change phrase</Button></div>}
```

#### Props of Text Morph

- `children` (required): `string`. Phrase to display; change it to trigger the transition.
- `className`: `string`. Typography and layout.

#### Accessibility

- Screen readers receive the complete phrase once; animated letters are decorative.
- Reduced motion skips letter travel and shared-layout animation.

#### Customization

##### Composition

Combine the control with your own layout. Semantic colors follow the active theme.

### Text Shimmer

A restrained highlight that travels across text and stops with reduced motion.

Page: https://latheui.dev/components/text-shimmer
Install: npx shadcn@latest add @latheui/text-shimmer

#### Usage

```tsx
import { TextShimmer } from "@/components/ui/text-shimmer"
export default function Demo(){return <div className="space-y-2 text-center"><TextShimmer className="text-xl font-medium">Making room for your next idea</TextShimmer><p className="text-xs text-muted-foreground">A quiet moment of anticipation.</p></div>}
```

#### Props of Text Shimmer

- `children` (required): `string`. Readable text content.
- `duration`: `number`, default `2.5`. Seconds per highlight cycle.
- `className`: `string`. Typography and spacing.

#### Accessibility

- The effect keeps one readable text node.
- Reduced motion displays static text in the inherited color.

#### Customization

##### Composition

Combine the control with your own layout. Semantic colors follow the active theme.

### Word Drum (Pro)

A word in a sentence that rolls to the next on a 3D drum, with the words before and after curving away above and below.

Page: https://latheui.dev/components/word-drum
Install: npx shadcn@latest add @latheui/word-drum

#### Usage

```tsx
import { WordDrum } from "@/components/ui/word-drum"

export function Headline() {
  return (
    <h1>
      Interfaces that feel <WordDrum words={["calm", "quick", "crafted"]} />
    </h1>
  )
}
```

#### Props of WordDrum

Also accepts native span attributes. It sits inline and inherits the text style around it.

- `words` (required): `string[]`. The words, in order.
- `interval`: `number`, default `2200`. Milliseconds each word stays.
- `faces`: `number`, default `10`. Faces on the drum. More faces make a gentler curve; the words repeat to fill them.
- `direction`: `"up" | "down"`, default `"up"`. Which way the drum rolls.
- `peek`: `number`, default `0.55`. How much of the neighbouring words shows, from 0 to 1.
- `pauseOnHover`: `boolean`, default `true`. Stop while the pointer is over it.
- `label`: `string`. Read out instead of the changing words. The words joined with "or" by default.
- `curve`: `Curve`, default `spring with a little give`. How the drum turns. Any curve from the Animation Lab.
- `duration`: `number`. Milliseconds, for curves that are not springs.

#### Accessibility

- Screen readers hear one steady phrase, such as "calm or quick or crafted", rather than a word that keeps changing.
- The drum stops while its preview is paused or the pointer is on it.
- With reduced motion the words change without rolling.

#### Motion

- The drum turns one face at a time on a spring (stiffness 140, damping 17), so each word settles with a small overshoot.
- Faces fade as they turn away, by the cosine of their angle.

#### Customization

##### A quick, flat roll

```tsx
<WordDrum words={words} interval={1400} faces={16} peek={0.2} curve={{ type: "expo", direction: "out" }} duration={600} />
```

## Effects

### Dither Image (Pro)

Any image drawn in a few colors with a dither, that dissolves in pixel by pixel and shows the original under a lens.

Page: https://latheui.dev/components/dither-image
Install: npx shadcn@latest add @latheui/dither-image

#### Usage

```tsx
import { DitherImage } from "@/components/ui/dither-image"

export function Hero() {
  return <DitherImage src="/hero.jpg" alt="The studio at night" palette={["#0f380f", "#9bbc0f"]} lens={72} />
}
```

#### Props of DitherImage

Also accepts native canvas attributes. The width follows the container; the height follows the image.

- `src` (required): `string`. The image. Same-origin or served with CORS headers, so its pixels can be read.
- `alt` (required): `string`. Describes the image.
- `palette`: `string[]`, default `background and foreground`. Colors to draw with, darkest first. Any CSS color, theme variables included.
- `algorithm`: `"bayer" | "floyd-steinberg" | "atkinson"`, default `"bayer"`. An ordered pattern, or error diffusion that spreads each pixel's error to its neighbours.
- `pixelSize`: `number`, default `3`. Size of one dither pixel, in CSS pixels.
- `contrast`: `number`, default `1`. Multiplies the image's contrast before dithering.
- `brightness`: `number`, default `0`. Added to every pixel's lightness, from -1 to 1.
- `reveal`: `"none" | "dissolve"`, default `"dissolve"`. Dissolve brings the image in pixel by pixel, in the dither's own order.
- `revealDuration`: `number`, default `1400`. Milliseconds the reveal takes.
- `lens`: `number`, default `0`. Radius in px of a lens showing the original under the pointer. 0 is off.
- `replayKey`: `React.Key`. Change it to play the reveal again.

#### Accessibility

- The canvas is an image named by alt.
- Theme colors are read again when the color scheme changes, so a two-tone dither follows light and dark mode.
- The lens is a pointer extra; it hides the cursor only over the image.
- With reduced motion the image appears without dissolving.

#### Motion

- The dissolve turns pixels on in the order of an 8×8 Bayer matrix, so it has the same texture as the dither itself.
- It pauses with the preview, and plays once.

#### Customization

##### A four-color handheld palette

```tsx
<DitherImage src="/photo.jpg" alt="Portrait" palette={["#0f380f", "#306230", "#8bac0f", "#9bbc0f"]} algorithm="atkinson" pixelSize={4} />
```

##### Still, in theme colors

```tsx
<DitherImage src="/photo.jpg" alt="Portrait" reveal="none" palette={["var(--muted)", "var(--chart-1)"]} />
```

### Line Draw

SVG strokes that write themselves in, one after another. A signature, an underline or a checkmark.

Page: https://latheui.dev/components/line-draw
Install: npx shadcn@latest add @latheui/line-draw

#### Usage

```tsx
import { LineDraw } from "@/components/ui/line-draw"

export function Underline() {
  return <LineDraw viewBox="0 0 200 20" paths={["M2 14 Q100 2 198 12"]} className="w-48" />
}
```

#### Props of LineDraw

Also accepts native svg attributes. Size it with className.

- `paths` (required): `string[]`. SVG path data, drawn one after another in this order.
- `viewBox` (required): `string`. The coordinate space of the paths.
- `label`: `string`. Accessible name. Without one the drawing is hidden from assistive tech.
- `color`: `string`, default `"currentColor"`. Stroke color.
- `strokeWidth`: `number`, default `3`. Stroke width in viewBox units.
- `duration`: `number`, default `1.5`. Seconds each path takes to draw.
- `stagger`: `number`, default `0.22`. Seconds between the start of one path and the next.
- `guide`: `boolean`, default `false`. A faint copy of the paths underneath.
- `trigger`: `"mount" | "inView"`, default `"inView"`. Draw as soon as it mounts, or once it scrolls into view.

#### Accessibility

- With a label it is an image with that name. Without one it is decoration and hidden.
- To redraw on click, wrap it in a button with its own label, as the first example does.

#### Motion

- Each path's dash offset runs from hidden to drawn with an ease in and out, on the Web Animations API.
- Paths use a pathLength of 1, so your own paths need no measuring.
- With reduced motion, the drawing appears complete.

#### Customization

##### Draw again

Change the key to start from nothing.

```tsx
const [run, setRun] = React.useState(0)

<LineDraw key={run} paths={paths} viewBox="0 0 300 160" />
<Button onClick={() => setRun((n) => n + 1)}>Replay</Button>
```

### Marquee

An endless, seamless scroll of logos, quotes or cards, with a set speed, direction and hover behavior.

Page: https://latheui.dev/components/marquee
Install: npx shadcn@latest add @latheui/marquee

#### Usage

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

export function Customers({ logos }: { logos: { name: string; src: string }[] }) {
  return (
    <Marquee label="Our customers">
      {logos.map((logo) => (
        <img key={logo.name} src={logo.src} alt={logo.name} className="h-6" />
      ))}
    </Marquee>
  )
}
```

#### Props of Marquee

Also accepts native div attributes.

- `children` (required): `ReactNode`. The items. Each child is one item; they are repeated as needed to fill the loop.
- `speed`: `number`, default `40`. Pixels per second.
- `direction`: `"left" | "right" | "up" | "down"`, default `"left"`. Direction of travel.
- `hover`: `"pause" | "slow" | "none"`, default `"pause"`. What a hovering pointer, or keyboard focus inside, does.
- `slowFactor`: `number`, default `0.25`. Share of the speed kept while slowed.
- `gap`: `string`, default `"2rem"`. Space between items. Any CSS length.
- `fade`: `boolean`, default `true`. Fades items out at both ends.
- `label`: `string`. Accessible name for the group.

#### Keyboard

- Tab: Moves to links or buttons inside the items. The marquee pauses or slows while focus is inside.

#### Accessibility

- The items are in the page once. The copies that fill the loop are hidden from assistive tech and cannot be focused.
- Content that moves for more than five seconds needs a way to pause it. Hover and focus both pause by default; if you set hover to none, add your own control.
- With reduced motion nothing moves. The items sit in a row you can scroll.
- Do not put anything in a marquee that people must read or act on. It is for supporting content.

#### Motion

- The track moves at a constant speed, independent of frame rate.
- Hovering eases the speed down, and leaving eases it back, over about a third of a second.
- With reduced motion the track is still and scrollable.

#### Customization

##### Speed, direction and hover

```tsx
<Marquee speed={80} direction="right" hover="slow" slowFactor={0.1}>
  {items}
</Marquee>
```

##### No fade, tighter gap

```tsx
<Marquee fade={false} gap="0.75rem">{items}</Marquee>
```

### Particle Reveal (Pro)

Thousands of particles fly in from a scatter and settle into a word or an image, in any colors.

Page: https://latheui.dev/components/particle-reveal
Install: npx shadcn@latest add @latheui/particle-reveal

#### Usage

```tsx
import { ParticleReveal } from "@/components/ui/particle-reveal"

export function Wordmark() {
  return <ParticleReveal text="Lathe" className="text-8xl font-semibold" />
}
```

#### Props of ParticleReveal

Also accepts native canvas attributes. Pass text or src.

- `text`: `string`. Text to form. Text wider than the canvas is scaled down to fit.
- `src`: `string`. Image to form, contained and centred. It must be same-origin or served with CORS headers.
- `label`: `string`, default `text`. Accessible description. Required in practice for images.
- `height`: `number`, default `200`. Height in pixels. The width follows the container.
- `color`: `"source" | "grayscale" | string | string[]`, default `"source"`. Source pixel color, its lightness only, one color, or a left-to-right gradient.
- `gap`: `number`, default `4`. Pixels between particles. Smaller means more particles.
- `size`: `number`, default `84% of gap, 94% for circles`. Particle size in pixels.
- `shape`: `"square" | "circle"`, default `"square"`. Shape of a particle.
- `edges`: `"hard" | "soft"`, default `"hard"`. Soft starts particles closer and fades them in near the border, so the canvas's straight edges never show.
- `duration`: `number`, default `1800`. Milliseconds the shape takes to form. Lower is faster.
- `scatter`: `number`, default `1`. How far away particles start, as a multiple of the canvas size.
- `settle`: `"particles" | "real"`, default `"particles"`. What the shape ends as. Real hands over from the landed particles to the sharp text or image, tinted the same way.
- `settleDuration`: `number`, default `900`. Milliseconds the hand-over to the real text or image takes.
- `replayKey`: `React.Key`. Change it to play again.
- `onStart`: `() => void`. Called when the particles start to fly in, on first render and on every replay.
- `onComplete`: `() => void`. Called once the shape has fully formed, after the hand-over when settle is real. With reduced motion it follows onStart at once.

#### Accessibility

- The canvas is exposed as an image named by label, or by the text. Assistive tech gets the word, not the animation.
- Canvas text cannot be selected or searched. For a heading, keep a real heading in the page and treat this as its decoration.
- With reduced motion the finished shape is drawn at once: the real text or image when settle is real.
- The animation runs once and stops, so it does not need a pause control.

#### Motion

- Each particle travels from a random point to its place with an ease-out curve. Particles on the left arrive slightly before those on the right.
- The scatter is seeded, so it plays the same way every time.
- With settle="real", the dots swell over the first half of the hand-over until neighbours touch, then fade while the real text or image comes in, sharpening from a 3px blur.
- With reduced motion nothing travels.

#### Customization

##### Colors

```tsx
<ParticleReveal text="Solid" color="var(--chart-1)" />
<ParticleReveal text="Gradient" color={["#3b82f6", "#a855f7", "#f43f5e"]} />
<ParticleReveal src="/portrait.jpg" label="Portrait" color="grayscale" />
<ParticleReveal src="/portrait.jpg" label="Portrait" color="source" />
```

##### Density, speed and shape

```tsx
<ParticleReveal text="Dense" gap={2} size={1.5} duration={900} shape="circle" scatter={2} />
<ParticleReveal text="Drift" edges="soft" />
<ParticleReveal text="Arrive" settle="real" settleDuration={1200} />
```

### Path Marquee (Pro)

Items that travel without end along a curved arc, or along any path you draw, turning to follow it.

Page: https://latheui.dev/components/path-marquee
Install: npx shadcn@latest add @latheui/path-marquee

#### Usage

```tsx
import { PathMarquee } from "@/components/ui/path-marquee"

export function Logos({ logos }: { logos: { name: string; src: string }[] }) {
  return (
    <PathMarquee label="Customers" bend={0.4}>
      {logos.map((logo) => <img key={logo.name} src={logo.src} alt={logo.name} className="h-8" />)}
    </PathMarquee>
  )
}
```

#### Props of PathMarquee

Also accepts native div attributes. Size it with className; the path stretches to fill it.

- `children` (required): `ReactNode`. The items. Each child is one item.
- `label`: `string`. Accessible name for the group.
- `bend`: `number`, default `0.35`. How far the arc rises, as a fraction of the height. Negative bends down.
- `path`: `string`. An SVG path in a 0–1000 box. Overrides the arc.
- `speed`: `number`, default `60`. Pixels per second along the path.
- `direction`: `"forward" | "backward"`, default `"forward"`. Which way items travel.
- `gap`: `number`, default `28`. Pixels between items along the path.
- `orient`: `boolean`, default `true`. Turn each item to follow the path.
- `hover`: `"pause" | "slow" | "none"`, default `"slow"`. What a pointer or focus inside does.
- `fade`: `boolean`, default `true`. Fade items near both ends of the path.

#### Accessibility

- The items are read once, in order. The repeats that fill the path are hidden from assistive tech.
- It slows or pauses while the pointer or keyboard focus is inside, so links in it can be used.
- With reduced motion it stands still, with the items laid along the path.

#### Motion

- Items keep an even spacing along the path whatever its shape, measured along the curve rather than across.
- Speed changes ease in over about 180ms, so hovering slows it smoothly rather than stopping dead.

#### Customization

##### Upright text on a dip

```tsx
<PathMarquee label="Principles" bend={-0.3} orient={false} direction="backward">{words}</PathMarquee>
```

### Progressive Blur (Pro)

A blur that builds toward one edge, so content under a floating bar melts away instead of being cut off.

Page: https://latheui.dev/components/progressive-blur
Install: npx shadcn@latest add @latheui/progressive-blur

#### Usage

```tsx
import { ProgressiveBlur } from "@/components/ui/progressive-blur"

export function Feed({ children }: { children: React.ReactNode }) {
  return (
    <div className="relative h-96 overflow-hidden">
      <div className="h-full overflow-y-auto pb-24">{children}</div>
      <ProgressiveBlur side="bottom" />
      <nav className="absolute inset-x-0 bottom-4 flex justify-center">{/* your bar */}</nav>
    </div>
  )
}
```

#### Props of ProgressiveBlur

Also accepts native div attributes. It is absolutely positioned, so its parent needs position: relative.

- `side`: `"top" | "bottom" | "left" | "right"`, default `"bottom"`. Edge the blur is strongest at.
- `strength`: `number`, default `16`. Blur radius in pixels at that edge.
- `layers`: `number`, default `6`. Stacked blur layers. More is smoother and costs more to paint.
- `tint`: `boolean`, default `true`. Also fades toward the background color, which keeps anything on top readable.
- `className`: `string`. Sets the depth, for example h-28. Defaults to 6rem.

#### Props of ProgressiveBlurScroll

A scrolling area with blurred edges. Also accepts native div attributes; size it with className.

- `orientation`: `"vertical" | "horizontal"`, default `"vertical"`. Scroll direction, and so which edges blur.
- `size`: `number`, default `64`. Depth of each blurred edge in px, and the scroll distance over which it fades in.
- `strength`: `number`, default `12`. Blur radius in pixels at the very edge.
- `layers`: `number`, default `6`. Stacked blur layers.
- `tint`: `boolean`, default `true`. Also fades toward the background color.
- `label`: `string`. Names the scrolling area and makes it focusable for keyboard scrolling.
- `viewportClassName`: `string`. Classes for the element that scrolls, such as padding.

#### Accessibility

- ProgressiveBlurScroll with a label makes its scrolling area a named region that takes focus, so it can be scrolled with the keyboard.
- It is decoration: hidden from assistive tech and transparent to the pointer, so it never blocks what is underneath.
- Blurred content is hard to read by design. Leave padding at the end of the scrolling area so the last item can be scrolled clear of the blur.
- Anything placed on top of the blur still needs its own contrast against the content behind. The tint helps, a solid surface on the control helps more.

#### Motion

- Nothing animates on its own. The effect comes from content moving underneath it.
- ProgressiveBlurScroll's edges fade with the scroll position, so they follow the content rather than a timer.

#### Customization

##### A header that content scrolls under

```tsx
<ProgressiveBlur side="top" strength={12} className="h-20" />
```

##### A scrolling list with live edges

```tsx
<ProgressiveBlurScroll label="Messages" size={56} className="h-80">
  {messages}
</ProgressiveBlurScroll>
```

##### Blur only, no tint

Over photos or video the tint can look like a haze. Turn it off and raise the strength.

```tsx
<ProgressiveBlur tint={false} strength={24} layers={8} />
```

### Ripple Grid (Pro)

A grid of dots that sends a wave out from wherever you click. Distance does the choreography.

Page: https://latheui.dev/components/ripple-grid
Install: npx shadcn@latest add @latheui/ripple-grid

#### Usage

```tsx
import { RippleGrid } from "@/components/ui/ripple-grid"

export function Hero() {
  return <RippleGrid columns={12} rows={6} color="var(--chart-1)" />
}
```

#### Props of RippleGrid

Also accepts native button attributes.

- `columns`: `number`, default `9`. Dots across.
- `rows`: `number`, default `7`. Dots down.
- `color`: `string`, default `"var(--chart-4)"`. Color of the dots. Any CSS color.
- `dotSize`: `number`, default `11`. Size of each dot, in pixels.
- `spacing`: `number`, default `28`. Distance between dot centers, in pixels.
- `autoPlay`: `boolean`, default `true`. Send one wave out from the middle as the grid mounts.
- `label`: `string`, default `"Send a ripple"`. Accessible name of the grid's button.

#### Keyboard

- Space / Enter: Sends a wave out from the middle.

#### Accessibility

- The whole grid is one button, so it is a single stop for the keyboard rather than one per dot.
- The dots are decoration and hidden from assistive tech.

#### Motion

- Each dot grows and brightens for 850ms, delayed 65ms for every dot's width it sits from the click.
- The wave runs on the Web Animations API, so it is cheap and can be paused like any CSS animation.
- With reduced motion, nothing moves. The dots keep their resting state.

#### Customization

##### A wave on a timer

Clicks from code have no position, so they start in the middle.

```tsx
const ref = React.useRef<HTMLButtonElement>(null)
React.useEffect(() => {
  const timer = setInterval(() => ref.current?.click(), 3000)
  return () => clearInterval(timer)
}, [])

<RippleGrid ref={ref} />
```

### Squircle (Pro)

Continuous corners: the curve flows out of the straight edges instead of meeting them at a seam, like Apple's icons and Figma's corner smoothing.

Page: https://latheui.dev/components/squircle
Install: npx shadcn@latest add @latheui/squircle

#### Usage

```tsx
import { Squircle } from "@/components/ui/squircle"

export function Tile() {
  return (
    <Squircle radius={24} smoothing={0.6} borderWidth={1} className="bg-card p-6">
      Continuous corners
    </Squircle>
  )
}
```

#### Props of Squircle

Also accepts every native div attribute.

- `radius`: `number`, default `24`. Corner radius in pixels. Smoothing extends the curve past it, so a squircle reads softer than border-radius at the same value.
- `smoothing`: `number`, default `0.6`. 0 is a plain rounded corner, 1 is the smoothest. On a small box it eases off before the radius does, the way Figma's does.
- `borderWidth`: `number`, default `0`. A border inside the shape, which follows the curve.
- `borderColor`: `string`, default `"var(--border)"`. Any CSS color or variable.
- `asChild`: `boolean`, default `false`. Shapes the child element, such as a button or an img, instead of rendering a div.

#### Props of squirclePath(width, height, radius, smoothing?)

The outline as SVG path data, for drawing the same shape in a canvas, an SVG or a mask.

- `returns`: `string`. Path data starting at the top edge, in pixels from the top-left corner.

#### Accessibility

- Purely visual. It adds no role, and the border is hidden from assistive tech.
- Focus rings drawn with outline or box-shadow are clipped by the shape. On a focusable squircle, use an inset ring, or put the ring on a wrapper.
- Before the first measurement, and where clip paths are unavailable, it falls back to a plain rounded corner, so content is never left square or unclipped.

#### Motion

- The shape is measured with a ResizeObserver and redrawn whenever the box changes size, so it stays correct through layout animations.

#### Customization

##### Shadows

A clip path cuts off box-shadow. Put a drop-shadow filter on a wrapper and it follows the curve.

```tsx
<div className="drop-shadow-lg">
  <Squircle radius={20} className="bg-card p-5">…</Squircle>
</div>
```

##### A button

```tsx
<Squircle asChild radius={14}>
  <button type="button" className="h-11 bg-primary px-5 text-primary-foreground">
    Continue
  </button>
</Squircle>
```

## AI

### Assistant Message

One reply from an assistant. Streamed words fade in so the text fills from top to bottom, then copy, retry and feedback appear beneath it.

Page: https://latheui.dev/components/assistant-message
Install: npx shadcn@latest add @latheui/assistant-message

#### Usage

```tsx
import { AssistantMessage } from "@/components/ui/assistant-message"

export function Reply({ text, done, retry }: { text: string; done: boolean; retry: () => void }) {
  return (
    <AssistantMessage
      content={text}
      streaming={!done}
      onRetry={retry}
      onFeedback={(value) => sendFeedback(value)}
    />
  )
}
```

#### Props of AssistantMessage

Also accepts native article attributes.

- `content` (required): `string`. The reply so far. Blank lines separate paragraphs, lines starting with “- ” become bullets, and `backticks` mark code.
- `streaming`: `boolean`, default `false`. More text is arriving. New words fade in, and the actions wait until it is false.
- `avatar`: `ReactNode | false`. The assistant's picture. A small mark is shown when left out; false hides it.
- `name`: `string`, default `"Assistant"`. Who is speaking, for screen readers.
- `onRetry`: `() => void`. Shows a retry button.
- `feedback`: `"up" | "down" | null`. The rating, when controlled.
- `defaultFeedback`: `"up" | "down" | null`, default `null`. Starting rating.
- `onFeedback`: `(feedback: "up" | "down" | null) => void`. Shows thumbs up and down. Pressing the chosen one again clears it.
- `hideActions`: `boolean`, default `false`. Hides copy, retry and feedback.

#### Accessibility

- Each reply is an article headed with the assistant's name for screen reader navigation.
- While streaming the article is aria-busy, so assistive tech waits for the finished text instead of reading every fragment.
- The thumbs are toggle buttons with aria-pressed, and every action has a name.
- The picture is decorative and hidden from screen readers.

#### Motion

- Each new word fades in from a slight blur over 420ms, a word at a time, so a burst of text washes in from top to bottom.
- The actions rise in once the reply is complete.
- With reduced motion, words appear without fading.

#### Customization

##### Bigger reading text

```tsx
<AssistantMessage content={text} className="[&_p]:text-[17px] [&_p]:leading-8" />
```

### Chat Workspace (Pro)

A complete chat, ready to skin: replies that stream in, a box to write in, and a list of past conversations. Full page like a chatbot, or a side panel for an in-app copilot.

Page: https://latheui.dev/components/chat-workspace
Install: npx shadcn@latest add @latheui/chat-workspace

#### Usage

```tsx
import { ChatWorkspace } from "@/components/chat-workspace"

// Stream from your API route; yield text as it arrives.
async function* respond(prompt: string, history, { signal }) {
  const response = await fetch("/api/chat", { method: "POST", body: JSON.stringify({ prompt, history }), signal })
  const reader = response.body!.pipeThrough(new TextDecoderStream()).getReader()
  for (;;) {
    const { value, done } = await reader.read()
    if (done) return
    yield value
  }
}

export default function Page() {
  return (
    <main className="h-dvh p-4">
      <ChatWorkspace respond={respond} suggestions={["Summarize my week", "Draft a reply"]} />
    </main>
  )
}
```

#### Props of ChatWorkspace

Also accepts native section attributes. Give it a height; it fills it.

- `layout`: `"page" | "panel"`, default `"page"`. A full screen with a conversation list, or a narrow side panel.
- `respond` (required): `(prompt, history, { signal, model }) => AsyncIterable<string> | Promise<string>`. Produces a reply. Yield text to stream it, or return it whole. Stop aborts signal.
- `title`: `string`, default `"Assistant"`. Names the chat and the assistant.
- `subtitle`: `string`, default `"Typically replies instantly"`. Under the title, in the panel.
- `greeting`: `string`, default `"What can I help with?"`. Heading of an empty chat.
- `suggestions`: `string[]`, default `[]`. Prompts offered on an empty chat; pressing one sends it.
- `models`: `{ id; label; description? }[]`. Shows a model picker. The choice is passed to respond.
- `thinkingLabel`: `string`, default `"Thinking"`. Shown until the first words of a reply arrive.
- `avatar`: `ReactNode | false`. The assistant's picture on each reply and in the panel header.
- `onFeedback`: `(message, feedback) => void`. Called when a reply is rated.
- `onClose`: `() => void`. Shows a close button in the panel.
- `placeholder`: `string`. Placeholder of the prompt box.
- `defaultConversations`: `{ id; title; messages }[]`, default `[]`. Saved conversations listed on first render.
- `conversationActions`: `{ id; label; icon?; destructive?; onSelect(conversation) }[]`, default `[]`. Extra entries in each conversation's menu, between Rename and Delete.
- `onRenameConversation`: `(conversation, title) => void`. Called after a conversation is renamed.
- `onDeleteConversation`: `(conversation) => void`. Called after a conversation is deleted.

#### Keyboard

- Enter: Sends. Shift+Enter starts a new line.
- Tab: Moves through the conversation list, the thread's actions and the prompt box.
- Shift / F10: Opens a conversation's menu, as does its options button or a right click.

#### Accessibility

- The chat is a labelled section; the thread is an ordered list, and each of your messages starts with “You:” for screen readers.
- Replies are articles named for the assistant, aria-busy while they stream so they are read once complete.
- The conversation list is a navigation landmark, and its toggle reports aria-expanded. The open conversation is marked aria-current.
- Each conversation's menu opens from a right click, its labelled options button, or Shift+F10, and is a full menu with arrow-key navigation.
- The thread follows a growing reply only while you are at the bottom, so scrolling up to read is never interrupted.

#### Motion

- Messages rise 8px into place, replies wash in word by word, and the conversation list slides open and closed.
- With reduced motion, everything appears in place with at most a fade.

#### Customization

##### More conversation actions

```tsx
<ChatWorkspace
  respond={respond}
  conversationActions={[
    { id: "share", label: "Share", icon: <ShareIcon />, onSelect: (chat) => share(chat.id) },
    { id: "archive", label: "Archive", icon: <ArchiveIcon />, onSelect: (chat) => archive(chat.id) },
  ]}
  onDeleteConversation={(chat) => deleteChat(chat.id)}
/>
```

##### A non-streaming backend

```tsx
<ChatWorkspace
  layout="panel"
  respond={async (prompt) => {
    const response = await fetch("/api/answer", { method: "POST", body: prompt })
    return response.text()
  }}
/>
```

### Diff View

A change to one file, for review: its path, lines added and removed, numbered and highlighted lines, and buttons to accept or reject it.

Page: https://latheui.dev/components/diff-view
Install: npx shadcn@latest add @latheui/diff-view

#### Usage

```tsx
import { DiffView } from "@/components/ui/diff-view"

export function ProposedEdit({ path, before, after, apply }: { path: string; before: string; after: string; apply: () => void }) {
  return <DiffView path={path} before={before} after={after} onAccept={apply} onReject={() => {}} />
}
```

#### Props of DiffView

Also accepts native section attributes. diffLines(before, after) is exported for your own use.

- `path` (required): `string`. The file's path from the project root.
- `before`: `string`. The file before the change.
- `after`: `string`. The file after the change.
- `lines`: `{ type: "add" | "remove" | "same"; text; oldNumber?; newNumber? }[]`. Lines to show as they are, in place of before and after.
- `context`: `number`, default `3`. Unchanged lines kept around each change.
- `onAccept`: `() => void`. Shows a check button. The view then marks itself accepted.
- `onReject`: `() => void`. Shows an x button. The view then marks itself rejected.
- `decision`: `"pending" | "accepted" | "rejected"`. Show a decision made elsewhere instead of the buttons.

#### Keyboard

- Tab: Reaches reject, accept, each folded row and the scrollable lines.
- Arrow keys: On the focused lines: scroll long lines sideways.

#### Accessibility

- The view is a section named for its file, and the counts are read as “3 lines added, 2 lines removed”.
- Each changed line starts with “Added:” or “Removed:” for screen readers, so color is never the only signal. Line numbers are hidden from them.
- The accept and reject buttons name the file. The decision is announced through a status message.

#### Motion

- The buttons fade into the decision once one is made.

#### Customization

##### More context

```tsx
<DiffView path={path} before={before} after={after} context={6} />
```

### Image Result (Pro)

A generated image from waiting to done: “Generating image” shimmers over a drifting placeholder, then the time it took and the image washing in, with download, regenerate and feedback.

Page: https://latheui.dev/components/image-result
Install: npx shadcn@latest add @latheui/image-result

#### Usage

```tsx
import { ImageResult } from "@/components/ui/image-result"

export function Generated({ url, prompt, regenerate }: { url?: string; prompt: string; regenerate: () => void }) {
  return (
    <ImageResult
      status={url ? "done" : "generating"}
      src={url}
      alt={prompt}
      onRegenerate={regenerate}
      onFeedback={(value) => rate(value)}
    />
  )
}
```

#### Props of ImageResult

Also accepts native figure attributes.

- `status` (required): `"generating" | "done" | "error"`. Where generation is.
- `src`: `string`. The finished image.
- `alt` (required): `string`. Describes the image. Also used to name the download.
- `seconds`: `number`. How long it took. Measured from generating to done when left out.
- `aspectRatio`: `string`, default `"1 / 1"`. The frame's shape, so nothing jumps when the image arrives.
- `onRegenerate`: `() => void`. Shows a regenerate button, also after a failure.
- `onDownload`: `() => void`. Replaces the built-in download of src.
- `feedback`: `"up" | "down" | null`. The rating, when controlled.
- `defaultFeedback`: `"up" | "down" | null`, default `null`. Starting rating.
- `onFeedback`: `(feedback: "up" | "down" | null) => void`. Shows thumbs up and down.
- `generatingLabel`: `string`, default `"Generating image"`. Header text while it works.
- `errorLabel`: `string`, default `"Couldn't create the image"`. Header text when it fails.

#### Accessibility

- A figure with the image's description as its caption, for screen readers.
- The header is a polite live region, so “Generated in 8s” or the failure is announced.
- The placeholder is decorative. Download, regenerate and the thumbs have names, and the thumbs report aria-pressed.

#### Motion

- While generating, soft colour drifts under a fine dot grain, and the header shimmers.
- The image washes in from the top over 1.4s, sharpening from a blur.
- With reduced motion the placeholder holds still and the image simply fades in.

#### Customization

##### Wide images

```tsx
<ImageResult status={status} src={src} alt={prompt} aspectRatio="16 / 9" className="max-w-2xl" />
```

### Permission Request (Pro)

An agent asking before it acts: what it wants to do, how risky it is, what will change, and buttons to apply, always allow or deny.

Page: https://latheui.dev/components/permission-request
Install: npx shadcn@latest add @latheui/permission-request

#### Usage

```tsx
import { DiffView } from "@/components/ui/diff-view"
import { PermissionRequest } from "@/components/ui/permission-request"

export function ApproveEdit({ edit, respond }: { edit: { path: string; before: string; after: string }; respond: (ok: boolean) => void }) {
  return (
    <PermissionRequest
      title={`Edit ${edit.path}`}
      risk="low"
      onApprove={() => respond(true)}
      onDeny={() => respond(false)}
    >
      <DiffView path={edit.path} before={edit.before} after={edit.after} />
    </PermissionRequest>
  )
}
```

#### Props of PermissionRequest

Also accepts native section attributes.

- `title` (required): `ReactNode`. What the agent wants to do.
- `description`: `ReactNode`. Why, in a sentence.
- `risk`: `"low" | "medium" | "high"`. Shown as a badge: grey, amber or red.
- `icon`: `ReactNode`. The action's icon. A shield when left out.
- `children`: `ReactNode`. What will change, such as a Diff View or a command.
- `onApprove` (required): `() => void`. Called by Apply, or Enter.
- `onAlwaysAllow`: `() => void`. Shows an Always allow button.
- `onDeny` (required): `() => void`. Called by Deny, or Escape.
- `approveLabel`: `string`, default `"Apply"`. Text of the approve button.
- `denyLabel`: `string`, default `"Deny"`. Text of the deny button.
- `decision`: `"pending" | "approved" | "always" | "denied"`. Show a decision made elsewhere in place of the buttons.
- `shortcuts`: `boolean`, default `true`. Enter approves and Escape denies while focus is in the card.

#### Keyboard

- Enter: Approves, while focus is in the card but not on a button or field.
- Escape: Denies, while focus is in the card.

#### Accessibility

- The card is a section headed by what the agent wants to do, so it can be found and read on its own.
- The risk is written as words (“low risk”), not only colored.
- The shortcut hints are hidden from screen readers; the buttons keep plain names.
- Once decided, the outcome replaces the buttons and is announced as a status.

#### Motion

- The buttons fade into the outcome, which rises 4px into place. Reduced motion keeps only the fade.

#### Customization

##### Wording for your product

```tsx
<PermissionRequest
  title="Send 1,240 emails"
  risk="medium"
  approveLabel="Send"
  denyLabel="Not now"
  onApprove={send}
  onDeny={cancel}
/>
```

### Prompt Box

The box at the bottom of a chat. It grows as you type, takes files, picks a model, listens, and turns send into stop while a reply is written.

Page: https://latheui.dev/components/prompt-box
Install: npx shadcn@latest add @latheui/prompt-box

#### Usage

```tsx
import { PromptBox } from "@/components/ui/prompt-box"

export function Composer({ send }: { send: (text: string) => void }) {
  return (
    <PromptBox
      models={[
        { id: "fast", label: "Fast" },
        { id: "deep", label: "Deep" },
      ]}
      onSubmit={({ text }) => send(text)}
    />
  )
}
```

#### Props of PromptBox

Also accepts native form attributes other than onSubmit.

- `value`: `string`. The text, when controlled.
- `defaultValue`: `string`, default `""`. Starting text, when uncontrolled.
- `onValueChange`: `(value: string) => void`. Called as the text changes.
- `onSubmit`: `(submission: { text, files, model }) => void`. Sends the prompt. The box clears and keeps focus afterwards.
- `placeholder`: `string`, default `"Ask anything…"`. Shown while empty.
- `models`: `{ id: string; label: string; description?: string }[]`, default `[]`. Models for the picker. With none, the picker is hidden.
- `model`: `string`. The selected model id, when controlled.
- `defaultModel`: `string`. Starting model. The first one when left out.
- `onModelChange`: `(model: string) => void`. Called when a model is picked.
- `attachments`: `boolean`, default `true`. Shows the attach button.
- `accept`: `string`. File types to accept, as for a file input.
- `onVoice`: `(listening: boolean) => void`. Shows a microphone button. Called with true when dictation starts and false when it stops. Wire it to your speech recognition.
- `busy`: `boolean`, default `false`. A reply is being written: send becomes stop.
- `onStop`: `() => void`. Called by the stop button.
- `disabled`: `boolean`, default `false`. Disables the field and every button.
- `label`: `string`, default `"Message"`. Accessible name of the text field.

#### Keyboard

- Enter: Sends the prompt.
- Shift / Enter: Starts a new line.
- Tab: Moves through attach, the model picker, the microphone and send.

#### Accessibility

- A native form around a labelled textarea. Enter waits for an input method composition to finish.
- Every icon button has a name: Attach files, Dictate, Send and Stop. The microphone reports its state with aria-pressed.
- The model picker names the current model, and its menu is a radio group.
- Attached files are a list, each with its own Remove button.
- Send is disabled until there is text or a file.

#### Motion

- The field grows line by line up to eight lines, then scrolls.
- Attached files grow in above the field.
- With reduced motion the listening pulse is removed.

#### Customization

##### A compact box for a side panel

```tsx
<PromptBox
  attachments={false}
  placeholder="Ask about this page"
  className="rounded-xl p-2"
  onSubmit={({ text }) => ask(text)}
/>
```

### Support Bubble (Pro)

A support assistant in the corner of your site. It starts as a button with a “Need help?” bubble, opens into a chat, can ask who you are first, and hands over to a person when it is not sure.

Page: https://latheui.dev/components/support-bubble
Install: npx shadcn@latest add @latheui/support-bubble

#### Usage

```tsx
import { SupportBubble } from "@/components/support-bubble"

export function Support() {
  return (
    <SupportBubble
      respond={askHelpCenter}
      collect={{ email: "required" }}
      onRequestSupport={({ contact, transcript }) => createTicket(contact, transcript)}
    />
  )
}

// Stream an answer, and say when it is not sure so a person is offered.
async function* askHelpCenter(question: string) {
  const { answer, confident } = await searchDocs(question)
  yield answer
  if (!confident) yield { unsure: true }
}
```

#### Props of SupportBubble

- `respond` (required): `(prompt, history, { signal, contact }) => AsyncIterable<string | { unsure: true }> | Promise<string | { text; unsure? }>`. Produces a reply. Yield text to stream it; yield { unsure: true } to offer a person under it.
- `collect`: `{ name?, email?, phone?: boolean | "required" }`. Asks for these before chatting. true is optional; "required" must be filled.
- `onContact`: `(contact) => void`. Called once the contact form is sent.
- `escalation`: `"unsure" | "always" | false`, default `"unsure"`. When to offer a person: under unsure replies, in the header too, or never.
- `onRequestSupport`: `({ contact, transcript }) => void | Promise<void>`. Hands the conversation to your team. Resolve to confirm, reject to show it failed.
- `title`: `string`, default `"Assistant"`. The assistant's name, in the header.
- `subtitle`: `string`, default `"Typically replies instantly"`. Under the name.
- `avatar`: `ReactNode`. The assistant's picture, drawn however you like.
- `avatarSrc`: `string`. Or an image for it, also used on the launcher.
- `icon`: `ReactNode`. The closed launcher's icon.
- `teaser`: `string | false`, default `"Need help?"`. The bubble beside the closed launcher. It can be dismissed.
- `emptyTitle`: `string`, default `"Ask us anything"`. Heading before the first message.
- `emptyDescription`: `string`. Line under it.
- `placeholder`: `string`, default `"Write a message…"`. Placeholder of the message box.
- `open`: `boolean`. Whether the chat is open, when controlled.
- `defaultOpen`: `boolean`, default `false`. Starting state.
- `onOpenChange`: `(open: boolean) => void`. Called when it opens or closes.
- `side`: `"right" | "left"`, default `"right"`. Which bottom corner.
- `position`: `"fixed" | "absolute"`, default `"fixed"`. Pinned to the window, or inside a positioned parent for previews.

#### Keyboard

- Enter: On the launcher: opens the chat. In the box: sends.
- Escape: Closes the chat and returns focus to the launcher.

#### Accessibility

- The launcher is a button named for the assistant, with aria-expanded and aria-controls.
- The open chat is a non-modal dialog named for the assistant, so the page stays usable behind it.
- The contact form uses labelled fields with autocomplete hints, and required ones are marked.
- Offering a person, and the handover's progress, are announced through status messages.

#### Motion

- The chat rises and scales in from the launcher's corner on a spring; the launcher's icon turns into a close mark.
- The teaser slides in beside the launcher.
- With reduced motion everything fades in place.

#### Customization

##### Your brand on the launcher

```tsx
<SupportBubble
  respond={respond}
  avatarSrc="/support/mia.jpg"
  teaser="Questions? Ask Mia"
  className="[&>div>button:last-child]:bg-indigo-600"
/>
```

### Task Plan (Pro)

An agent's plan as a checklist it works through: a ring that fills as steps finish, what each step is doing, and a clear red mark when one fails.

Page: https://latheui.dev/components/task-plan
Install: npx shadcn@latest add @latheui/task-plan

#### Usage

```tsx
import { TaskPlan } from "@/components/ui/task-plan"

export function AgentPlan({ steps }: { steps: { title: string; status: "pending" | "running" | "done" | "failed" | "skipped" }[] }) {
  return <TaskPlan steps={steps} />
}
```

#### Props of TaskPlan

Also accepts native section attributes.

- `steps` (required): `{ id?, title, detail?, status, duration? }[]`. status is "pending", "running", "done", "failed" or "skipped". detail is a second line; duration is in milliseconds and shows once a step ends.
- `title`: `string`, default `"Plan"`. The heading, beside the count.
- `open`: `boolean`. Whether the steps show, when controlled.
- `defaultOpen`: `boolean`, default `true`. Starting state.
- `onOpenChange`: `(open: boolean) => void`. Called by the button on the right.

#### Keyboard

- Enter / Space: On the button at the right: shows or hides the steps.

#### Accessibility

- The plan is a section headed by its title and count, such as “Plan 3 of 5”, and the ring says the same in words.
- Steps are an ordered list. Each is read with its status, so a failure is never shown by color alone.
- The failed mark is an image named “A step failed”.

#### Motion

- The ring fills with a spring as steps finish, and the steps grow open and closed.
- The running step's title shimmers. With reduced motion the ring jumps, the shimmer stops and the spinner holds still.

#### Customization

##### Without the collapse

```tsx
<TaskPlan steps={steps} open className="[&_header_button]:hidden" />
```

### Thinking Pill

A small pill that says what an assistant is busy with. The status shimmers dark to light, and each new one slides in over the last.

Page: https://latheui.dev/components/thinking-pill
Install: npx shadcn@latest add @latheui/thinking-pill

#### Usage

```tsx
import { ThinkingPill } from "@/components/ui/thinking-pill"

export function AssistantStatus({ step }: { step: string }) {
  return <ThinkingPill status={step} />
}
```

#### Props of ThinkingPill

Also accepts native div attributes.

- `status` (required): `string`. What the assistant is doing, such as “Searching the web”.
- `icon`: `ReactNode`. Shown in place of the spinner. Decorative; the status carries the meaning.
- `shimmerDuration`: `number`, default `1.8`. Seconds per pass of the highlight.

#### Accessibility

- The pill is a polite live region, so each new status is read once, without interrupting.
- The spinner and icon are hidden from screen readers.
- The shimmer runs over one text node, so the status is read as plain words.

#### Motion

- A new status rises 10px into place with a soft blur, while the old one rises out.
- With reduced motion the statuses cross-fade, the highlight stops and the spinner holds still.

#### Customization

##### Bigger, on a dark surface

```tsx
<ThinkingPill
  status="Reading sources"
  className="h-10 bg-zinc-900 px-4 text-sm text-zinc-100"
/>
```

### Thought Trace

The reasoning behind a reply, folded into one line. It shimmers “Thinking”, then says how long it took; open it to see each thought, search, page read and tool call.

Page: https://latheui.dev/components/thought-trace
Install: npx shadcn@latest add @latheui/thought-trace

#### Usage

```tsx
import { ThoughtTrace } from "@/components/ui/thought-trace"

export function Reasoning({ done, steps }: { done: boolean; steps: { kind: "thought" | "search" | "read" | "tool"; text: string }[] }) {
  return <ThoughtTrace status={done ? "done" : "thinking"} steps={steps} />
}
```

#### Props of ThoughtTrace

Also accepts native div attributes.

- `status` (required): `"thinking" | "done"`. Whether the model is still reasoning.
- `steps` (required): `{ id?, kind?, text, detail? }[]`. The steps so far. kind is thought, search, read or tool, and picks the icon; detail is a second line such as a query, URL or command.
- `seconds`: `number`. How long it thought. Measured from the start of thinking to done when left out.
- `open`: `boolean`. Whether the steps show, when controlled.
- `defaultOpen`: `boolean`, default `false`. Starting state, when uncontrolled.
- `onOpenChange`: `(open: boolean) => void`. Called when the header is pressed.
- `icon`: `ReactNode`. Replaces the lightbulb, for example with a brain.
- `thinkingLabel`: `string`, default `"Thinking"`. Header text while thinking.
- `doneLabel`: `(seconds: number) => string`, default `Thought for 6s`. Header text when done.

#### Keyboard

- Enter / Space: On the header: shows or hides the steps.

#### Accessibility

- The header is a button with aria-expanded, tied to the step list with aria-controls.
- The header text is a polite live region, so the change from Thinking to the time taken is announced.
- The steps are an ordered list; icons are decorative, and the kind of step is in its text.

#### Motion

- “Thinking” has a light highlight travelling across darker text.
- Opening grows the list and turns the chevron with a spring. New steps rise 6px into place.
- With reduced motion, the shimmer stops and nothing moves; content still fades.

#### Customization

##### Your own wording

```tsx
<ThoughtTrace
  status={status}
  steps={steps}
  thinkingLabel="Working it out"
  doneLabel={(s) => `Worked for ${s} seconds`}
/>
```

### Tool Run (Pro)

One tool call by an agent on a single line: the tool, its argument, what it is for, how long it took and whether it worked. Open it for the details and output.

Page: https://latheui.dev/components/tool-run
Install: npx shadcn@latest add @latheui/tool-run

#### Usage

```tsx
import { ToolRun } from "@/components/ui/tool-run"

export function Call({ call }: { call: { tool: string; file: string; ms: number; ok: boolean; text: string } }) {
  return (
    <ToolRun
      name={call.tool}
      argument={call.file}
      description="Read the page"
      status={call.ok ? "done" : "error"}
      duration={call.ms}
      output={call.text}
    />
  )
}
```

#### Props of ToolRun

Also accepts native div attributes. formatDuration(ms) is exported too.

- `name` (required): `string`. The tool, such as read_file.
- `argument`: `string`. Its main argument, shown in brackets.
- `description`: `string`. What the call is for. It shimmers while running.
- `status` (required): `"pending" | "running" | "done" | "error"`. Shown as a badge on the icon; a failed call's name turns red.
- `duration`: `number`. Milliseconds it took, shown once it has finished.
- `icon`: `ReactNode`. The tool's icon. A terminal when left out.
- `meta`: `{ label: string; value: string }[]`. Small facts shown when open, such as the path and lines.
- `output`: `string`. The result, shown as code when open.
- `error`: `string`. Why it failed, shown when open.
- `children`: `ReactNode`. Anything else to show when open.
- `open`: `boolean`. Whether the details show, when controlled.
- `defaultOpen`: `boolean`, default `false`. Starting state.
- `onOpenChange`: `(open: boolean) => void`. Called when the line is pressed.

#### Keyboard

- Enter / Space: Shows or hides the details, when there are any.

#### Accessibility

- A call with details is a button with aria-expanded; one without is plain text.
- The status is read as a word (Waiting, Running, Done, Failed) after the call, not only shown as a badge.
- The output can be scrolled from the keyboard.

#### Motion

- The details grow open and the chevron turns with a spring.
- A running call's description shimmers; with reduced motion it is plain and the spinner holds still.

#### Customization

##### Your own detail

```tsx
<ToolRun name="screenshot" argument="/checkout" status="done" duration={1200}>
  <img src={url} alt="The checkout page" className="rounded-lg border" />
</ToolRun>
```

## Assemblies

### Activity Replay (Pro)

Inspect recorded application snapshots, play through ordered events, pin a comparison baseline, and jump to any checkpoint.

Page: https://latheui.dev/assemblies/activity-replay
Install: npx shadcn@latest add @latheui/activity-replay

#### Usage

```tsx
"use client"
import { ActivityReplay } from "@/components/activity-replay"
const events = [
  { id: "created", label: "Created", at: 0, detail: "Maya opened a project", snapshot: { name: "Untitled project", tasks: 0, status: "Draft" } },
  { id: "named", label: "Named", at: 2400, detail: "Project renamed", snapshot: { name: "Field notes", tasks: 0, status: "Draft" } },
  { id: "planned", label: "Planned", at: 6100, detail: "Three tasks added", snapshot: { name: "Field notes", tasks: 3, status: "Draft" } },
  { id: "shared", label: "Shared", at: 9400, detail: "Project shared with the team", snapshot: { name: "Field notes", tasks: 3, status: "In review" } },
]
export default function ReplayDemo() {
  return <div className="w-full max-w-xl"><ActivityReplay events={events} renderSnapshot={(snapshot, baseline) => <div className="space-y-4"><div className="flex flex-wrap items-center justify-between gap-3"><p className="text-lg font-medium tracking-tight">{snapshot.name}</p><span className="rounded-full border border-border px-2 py-1 text-xs">{snapshot.status}</span></div><p className="font-mono text-3xl tabular-nums">{snapshot.tasks}<span className="ml-2 font-sans text-xs text-muted-foreground">tasks</span></p>{baseline && <p className="border-t border-border pt-3 text-xs text-muted-foreground">Baseline: {baseline.name}, {baseline.tasks} tasks, {baseline.status}.</p>}</div>} /></div>
}
```

#### Props of ActivityReplay

- `events` (required): `readonly ReplayEvent<T>[]`. Ordered events with unique id, label, optional detail, nonnegative at timestamp in milliseconds and an application-owned snapshot.
- `renderSnapshot` (required): `(snapshot: T, baseline: T | undefined) => ReactNode`. Render state and its optional baseline. Snapshots are supplied by the application; Lathe does not record sessions.
- `value / defaultValue`: `string`, default `first event (defaultValue)`. Controlled or initially selected event id.
- `onValueChange`: `(id: string) => void`. Receives automatic and manual event changes.
- `interval`: `number`, default `1200`. Fixed playback interval between events in milliseconds; event timestamps remain metadata.
- `disabled`: `boolean`, default `false`. Disable navigation, speed changes and playback.
- `className`: `string`. Classes for the section.

#### Keyboard

- Arrow keys / Home / End: Move through the event scrubber. Manual navigation pauses playback.
- Tab: Move through the enabled controls. Focus remains visible.

#### Accessibility

- Lathe controls expose accessible names, states and keyboard behavior. Layouts wrap at narrow widths and use semantic theme tokens.
- Asynchronous failures are announced as alerts where persistence is involved. Progress and outcomes use status messages. Demos keep all data local.

#### Motion

- Snapshots fade between recorded states with a short, gentle slide. Checkpoint pills fade their selection backgrounds without a press-scale effect.
- Shared Lathe controls retain their reduced-motion behavior.
- Replay starts only after the user presses Play. Reduced motion preserves event navigation and content; timers are cleaned up on pause and unmount. Pausing or suspending a catalog preview also suspends event advancement.

#### Customization

##### Connect your own data

Replace the demo data and callbacks with your application. Honor AbortSignal in asynchronous callbacks so cancellation also stops transport work.

### Command Preview (Pro)

Find an action, edit its parameters, inspect proposed changes, then execute with cancellation, retry and optional undo.

Page: https://latheui.dev/assemblies/command-preview
Install: npx shadcn@latest add @latheui/command-preview

#### Usage

```tsx
"use client"
import * as React from "react"
import { Checkbox } from "@/components/ui/checkbox"
import {
  CommandPreview,
  type PreviewCommand,
} from "@/components/command-preview"
export default function CommandDemo() {
  const [archived, setArchived] = React.useState(false)
  const [fail, setFail] = React.useState(false)
  const commands: PreviewCommand[] = [
    {
      id: "archive",
      label: "Archive completed work",
      description: "Move finished projects out of the active workspace.",
      parameters: [
        {
          key: "workspace",
          label: "Workspace",
          defaultValue: "Studio",
          required: true,
        },
      ],
      preview: async (params, signal) => {
        await new Promise((resolve) => setTimeout(resolve, 250))
        if (signal.aborted) return null
        return (
          <div className="space-y-2">
            <p className="font-medium">
              3 projects will be archived in {params.workspace}.
            </p>
            <ul className="list-inside list-disc text-xs text-muted-foreground">
              <li>Brand exploration</li>
              <li>Autumn campaign</li>
              <li>Website audit</li>
            </ul>
            <p className="text-xs text-muted-foreground">
              Files stay available. This action supports undo.
            </p>
          </div>
        )
      },
      execute: async (_params, signal) => {
        await new Promise((resolve) => setTimeout(resolve, 500))
        if (signal.aborted) return
        if (fail) {
          setFail(false)
          throw new Error("The workspace is offline. Try again.")
        }
        setArchived(true)
      },
      undo: async (signal) => {
        if (!signal.aborted) setArchived(false)
      },
    },
    {
      id: "export",
      label: "Prepare project export",
      description: "Inspect the contents of a project archive.",
      parameters: [
        {
          key: "project",
          label: "Project",
          defaultValue: "Field notes",
          required: true,
        },
      ],
      preview: (params) => (
        <p className="text-xs">
          The export for {params.project} will contain 12 documents and 4
          images.
        </p>
      ),
      execute: async () => {
        await new Promise((resolve) => setTimeout(resolve, 300))
      },
    },
  ]
  return (
    <div className="w-full max-w-2xl space-y-3">
      <CommandPreview commands={commands} />
      <div className="flex flex-wrap justify-between gap-2 text-xs text-muted-foreground">
          <Checkbox
            label="Fail next action"
            checked={fail}
            onCheckedChange={(checked) => setFail(checked === true)}
            className="text-xs"
          />
        <span>{archived ? "3 projects archived" : "3 projects active"}</span>
      </div>
    </div>
  )
}
```

#### Props of CommandPreview

- `commands` (required): `readonly PreviewCommand[]`. Unique ids, labels, descriptions, optional parameter definitions, preview and execute callbacks, and optional undo. Keep command definitions consistent during a run.
- `commands[].parameters`: `{ key; label; defaultValue?; required? }[]`. String parameters. Required values prevent preview when blank.
- `commands[].preview`: `(parameters, signal) => ReactNode | Promise<ReactNode>`. Return a side-effect-free preview. Editing parameters invalidates it.
- `commands[].execute`: `(parameters, signal) => void | Promise<void>`. Run only after a successful preview. Honor signal; reject to show retry feedback.
- `commands[].undo`: `(signal) => void | Promise<void>`. Optional application-owned undo offered after successful execution. No undo control is shown otherwise.
- `disabled`: `boolean`, default `false`. Disable search, selection and actions.
- `className`: `string`. Classes for the section.

#### Keyboard

- Tab / Enter / Space: Navigate search, action buttons, parameters, preview, execution and undo.
- Tab: Move through the enabled controls. Focus remains visible.

#### Accessibility

#### Motion

- Selected command backgrounds fade in and out without scaling the text. Action details and prepared previews enter with a small slide and fade; reduced motion makes these changes immediate.
- Shared Lathe controls retain their reduced-motion behavior.

#### Customization

##### Connect your own data

Replace the demo data and callbacks with your application. Honor AbortSignal in asynchronous callbacks so cancellation also stops transport work.

### Conflict Resolver (Pro)

Resolve field-level differences between local and incoming changes, inspect the merged result, and save with retry.

Page: https://latheui.dev/assemblies/conflict-resolver
Install: npx shadcn@latest add @latheui/conflict-resolver

#### Usage

```tsx
"use client"
import * as React from "react"
import { Checkbox } from "@/components/ui/checkbox"
import { ConflictResolver } from "@/components/conflict-resolver"
const fields = [
  {
    key: "name",
    label: "Project name",
    local: "Field notes",
    incoming: "Field journal",
  },
  {
    key: "description",
    label: "Description",
    local: "A collection of things worth keeping.",
    incoming: "A quieter place for your best ideas.",
  },
  { key: "owner", label: "Owner", local: "Maya Chen", incoming: "Maya Chen" },
]
export default function ConflictDemo() {
  const [fail, setFail] = React.useState(false)
  return (
    <div className="w-full max-w-2xl space-y-3">
      <ConflictResolver
        fields={fields}
        onResolve={async (_merged, signal) => {
          await new Promise((resolve) => setTimeout(resolve, 450))
          if (signal.aborted) return
          if (fail) {
            setFail(false)
            throw new Error("Save interrupted. Your selections are preserved.")
          }
        }}
      />
        <Checkbox
          label="Fail next save"
          checked={fail}
          onCheckedChange={(checked) => setFail(checked === true)}
          className="text-xs text-muted-foreground"
        />
    </div>
  )
}
```

#### Props of ConflictResolver

- `fields` (required): `readonly ConflictField[]`. Unique key, label and local/incoming strings for each field. Equal values need no decision.
- `onResolve` (required): `(merged: Record<string, string>, signal: AbortSignal) => void | Promise<void>`. Persist the merged record. Reject to keep selections and allow retry; honor the signal to cancel.
- `title`: `string`, default `"Resolve changes"`. Visible heading and accessible section name.
- `disabled`: `boolean`, default `false`. Disable choices and saving.
- `className`: `string`. Classes for the section.

#### Keyboard

- Arrow keys: Move between local and incoming options in a field's Lathe radio group.
- Tab: Move through the enabled controls. Focus remains visible.

#### Accessibility

#### Motion

- Local and incoming choices ease between muted selection backgrounds and soft borders over 200 milliseconds, with no layout movement. Reduced motion switches immediately.
- Shared Lathe controls retain their reduced-motion behavior.

#### Customization

##### Connect your own data

Replace the demo data and callbacks with your application. Honor AbortSignal in asynchronous callbacks so cancellation also stops transport work.

### Dashboard (Pro)

A workspace that fits your product. Three navigation layouts, a responsive grid, and composable cards with gentle motion. Try every arrangement in the expanded playground.

Page: https://latheui.dev/assemblies/dashboard
Install: npx shadcn@latest add @latheui/dashboard

#### Usage

```tsx
import { Dashboard, DashboardCard, DashboardGrid } from "@/components/dashboard"

export default function Workspace() {
  return (
    <Dashboard layout="combined" aria-label="Workspace"
      topbar={<header className="p-4">Your brand and top navigation</header>}
      sidebar={<nav aria-label="Workspace" className="p-4">Your navigation</nav>}
      mobileNavigation={<nav aria-label="Mobile workspace" className="p-3">Compact navigation</nav>}>
      <DashboardGrid columns={4} gap={16}>
        <DashboardCard title="Revenue">Your metric component</DashboardCard>
        <DashboardCard title="Activity" span={3}>Your chart or table</DashboardCard>
      </DashboardGrid>
    </Dashboard>
  )
}
```

#### Props of Dashboard

Accepts native section attributes, children, className and style. Give the workspace an accessible name. Navigation slots are ordinary React nodes; your application owns routing and selection.

- `layout`: `"combined" | "topbar" | "sidebar"`, default `"combined"`. Both navigation regions, top navigation only, or sidebar only.
- `topbar / sidebar`: `ReactNode`. Replaceable navigation slots. The sidebar is visually hidden below 48rem of shell width.
- `mobileNavigation`: `ReactNode`. Compact navigation shown below 48rem when the layout includes a sidebar. Supply this to keep sidebar-only navigation reachable on mobile.
- `collapsed`: `boolean`, default `false`. Controlled sidebar width. Render icon-only sidebar content when collapsed and provide accessible names.
- `sidebarWidth / collapsedWidth`: `number`, default `208 / 64`. Expanded and collapsed sidebar widths in pixels.
- `contentClassName`: `string`. Override content padding or other content styles.

#### Props of DashboardGrid

Accepts native div attributes. Put it inside Dashboard to use its content container queries.

- `columns`: `2 | 3 | 4 | 6 | 12`, default `4`. Desktop columns. Below 32rem of content width, cards stack in one column.
- `gap`: `number`, default `16`. Space between cards in pixels.
- `rowHeight`: `number`. Optional minimum height per grid row in pixels; rows grow with content.

#### Props of DashboardCard

Accepts Motion section props, className, style and any React children. Stable keys preserve card state during grid changes.

- `title / description / action`: `ReactNode`. Optional heading, supporting text and header action.
- `span`: `number | "full"`, default `1`. Column span, clamped to available columns. Full spans the entire row.
- `rowSpan`: `number`, default `1`. Number of rows occupied by the card.
- `variant`: `"bordered" | "soft" | "plain"`, default `"bordered"`. Card surface treatment; override with className for accent cards.
- `contentClassName`: `string`. Styles the card body without changing its heading.

#### Keyboard

- Tab / Shift+Tab: Moves through navigation and controls; the expanded preview traps focus and restores it when closed.
- ArrowLeft / ArrowRight: Selects an option in segmented controls or adjusts a focused limit slider by $100.
- ArrowUp / ArrowDown / Enter: Navigates and chooses options in the Lathe Select menus.
- Escape: Closes an open Select menu first, or closes the expanded playground.

#### Accessibility

- Cards with titles are labelled sections. Navigation remains consumer-owned so you can supply real router links and aria-current.
- Container queries adapt to the available workspace, including inside previews. Wide content such as a table should provide its own horizontal scrolling wrapper.
- Hidden sidebars are inert. Supply mobileNavigation for small containers. Icon-only controls need accessible labels.
- The playground uses sample data only. Card and reward actions change local state; nothing is sent or persisted. Opening the expanded playground starts a fresh demo.

#### Motion

- Sidebar width changes use Lathe’s smooth spring. Card position changes animate without scaling their text, and new cards rise gently into place.
- The Dashboard Mockup preview has its own light and dark palettes. Its theme switch reveals the new colors in an expanding circular wave from the clicked control, without resetting dashboard state. Browsers without the View Transition API switch instantly.
- All shell and card movement respects reduced motion, including the preview’s theme reveal. The demo also animates selected navigation, numbers, charts and view changes.

#### Customization

##### Two levels of navigation

In the combined layout, the top navigation chooses a main page and the sidebar chooses a section within that page. Keep a section selection per page to remember where people left off. The demo moves section navigation below the header in top-only mode and provides compact navigation on mobile. Navigation stays in the slots, so you can use your own router and links.

```tsx
const sections = {
  overview: ["Summary", "Activity", "Budget"],
  manage: ["Cards", "Controls", "Limits"],
  rewards: ["Membership", "Benefits", "History"],
}
type Page = keyof typeof sections
const [page, setPage] = useState<Page>("overview")
const [selected, setSelected] = useState({
  overview: "Summary", manage: "Cards", rewards: "Membership",
})
const sectionNavigation = (
  <nav aria-label={page + " sections"}>
    {sections[page].map(section => (
      <button key={section} type="button"
        aria-current={selected[page] === section ? "page" : undefined}
        onClick={() => setSelected(current => ({ ...current, [page]: section }))}>
        {section}
      </button>
    ))}
  </nav>
)

<Dashboard layout="combined"
  topbar={<YourPageNavigation value={page} onValueChange={setPage} />}
  sidebar={sectionNavigation} mobileNavigation={sectionNavigation}>
  <YourPage page={page} section={selected[page]} />
</Dashboard>
```

##### Control the layout

Keep layout and collapse state wherever your app needs it. Contents stay mounted while the shell arrangement changes.

```tsx
const [layout, setLayout] = useState<DashboardLayout>("combined")
const [collapsed, setCollapsed] = useState(false)

<Dashboard layout={layout} collapsed={collapsed}
  topbar={<YourTopNavigation onLayoutChange={setLayout} />}
  sidebar={<YourSidebar collapsed={collapsed} onToggle={() => setCollapsed(!collapsed)} />}
  mobileNavigation={<YourMobileNavigation />}>
  {children}
</Dashboard>
```

##### Twelve-column composition

Use spans for a dense desktop grid. Spans clamp automatically when the workspace stacks on smaller screens. Pass existing Lathe components or any third-party React component as children; each keeps its own API.

```tsx
<DashboardGrid columns={12} gap={20} rowHeight={120}>
  <DashboardCard title="Revenue" span={4}><YourMetric /></DashboardCard>
  <DashboardCard title="Trends" span={8} rowSpan={2}><YourChart /></DashboardCard>
  <DashboardCard title="Tasks" span={4}><YourTaskList /></DashboardCard>
  <DashboardCard title="Transactions" span="full">
    <div className="overflow-x-auto"><YourTable /></div>
  </DashboardCard>
</DashboardGrid>
```

##### Make it yours

The primitives inherit Lathe’s semantic color tokens, including dark mode. The orange financial workspace is just an example composition, not built into the shell. Override surfaces, spacing and radii with className or style.

```tsx
<Dashboard className="rounded-3xl bg-muted/30" contentClassName="p-6">
  <DashboardGrid columns={3} gap={24}>
    <DashboardCard title="A custom surface" variant="plain"
      className="rounded-3xl bg-orange-600 text-white" span={2}>
      Any React content
    </DashboardCard>
  </DashboardGrid>
</Dashboard>
```

### Delivery Details (Pro)

A compact checkout step for contact, address and delivery method, with saving, confirmation and retry states.

Page: https://latheui.dev/assemblies/delivery-details
Install: npx shadcn@latest add @latheui/delivery-details

#### Usage

```tsx
import { DeliveryDetails } from "@/components/delivery-details"

export function DeliveryStep() {
  return <DeliveryDetails onContinue={async (values) => {
    const response = await fetch("/api/delivery", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify(values),
    })
    if (!response.ok) throw new Error("Could not save delivery details.")
  }} />
}
```

#### Props of DeliveryDetails

- `title`: `string`, default `"Delivery details"`. Visible heading and accessible section name.
- `defaultValues`: `Partial<DeliveryValues>`. Initial email, address, city, postalCode and method. Values are managed internally.
- `options`: `DeliveryOption[]`. Available methods with value, label, optional description and disabled state. Defaults to sample Standard and Express choices.
- `onContinue`: `(values: DeliveryValues) => void | Promise<void>`. Persist or validate delivery in your app. Resolve to confirm, reject with an error to offer retry. Omitting it confirms locally.
- `disabled`: `boolean`, default `false`. Disable all fields and submission.
- `className`: `string`. Override the compact card layout.

#### Props of DeliveryValues

- `email / address / city / postalCode` (required): `string`. Contact and delivery address fields.
- `method` (required): `string`. Selected delivery option value.

#### Keyboard

- Tab: Move through fields, method choices and Continue.
- Arrow keys: Choose a delivery method.
- Enter: Submit when all required fields are valid.

#### Accessibility

- A labelled section contains a native form with required fields and email validation.
- Field links each input to its visible label. RadioGroup supplies single-choice semantics and keyboard control.
- Progress and completion are announced, errors use role=alert, and fields are locked while saving.

#### Customization

##### Pair with Order Summary

Use this address step beside an order summary, and store the returned values in your checkout flow. Validate shipping rates on your server.

```tsx
<div className="grid items-start gap-5 md:grid-cols-2">
  <DeliveryDetails onContinue={saveDelivery} />
  <OrderSummary item={item} onPay={startPayment} />
</div>
```

### FAQ Section

Questions and answers beside a heading, with a search that filters as you type and a closing line for anything else.

Page: https://latheui.dev/assemblies/faq-section
Install: npx shadcn@latest add @latheui/faq-section

#### Usage

```tsx
import { FaqSection } from "@/components/faq-section"

// Renders with built-in sample questions.
export default function Page() {
  return <FaqSection contact={{ text: "Still stuck?", label: "Contact us", onSelect: openSupport }} />
}
```

#### Props of FaqSection

Also accepts native section attributes.

- `title`: `string`, default `"Questions"`. Heading and accessible name of the section.
- `description`: `string`. Line under the heading.
- `items`: `FaqItem[]`, default `sample questions`. Questions to show, in order. The first starts open.
- `searchable`: `boolean`, default `true`. Show the search field. Worth it from about six questions.
- `contact`: `{ text: string; label: string; onSelect: () => void } | null`. Text and action of the closing line. Pass null to leave it out.
- `reserveSpace`: `boolean`, default `false`. Keeps room for the longest answer, so opening a question never changes the section's height or moves the content after it.

#### Props of FaqItem

- `id` (required): `string`. Unique id.
- `question` (required): `string`. The question, shown on the trigger.
- `answer` (required): `ReactNode`. The answer. Text, links or any markup.
- `text`: `string`. Plain text of the answer for the search. Needed only when answer is not a string.

#### Keyboard

- Tab: Moves through the search field, each question and the contact button.
- Enter / Space: On a question: opens or closes its answer.

#### Accessibility

- The block is a labelled section, and the search field is named after the heading.
- Questions are accordion triggers that report whether their answer is open.
- The number of matching questions is announced as the search changes.
- When nothing matches, the message repeats the search text instead of leaving an empty list.
- The heading and the questions stack on small screens.

#### Motion

- Answers open and close with the accordion's height animation.
- With reduced motion answers appear at once.

#### Customization

##### Answers with markup

Give text alongside a rich answer so the search can still find it.

```tsx
<FaqSection
  items={[
    {
      id: "returns",
      question: "Can I send something back?",
      text: "Yes, within 30 days. See the returns policy.",
      answer: <>Yes, within 30 days. See the <a href="/returns">returns policy</a>.</>,
    },
  ]}
/>
```

### Import Workbench (Pro)

Bring in CSV data, map columns, preview transformations, correct invalid cells and import only after validation passes.

Page: https://latheui.dev/assemblies/import-workbench
Install: npx shadcn@latest add @latheui/import-workbench

#### Usage

```tsx
"use client"
import * as React from "react"
import { Checkbox } from "@/components/ui/checkbox"
import { ImportWorkbench } from "@/components/import-workbench"
const fields = [
  { key: "name", label: "Name", required: true },
  {
    key: "email",
    label: "Email",
    required: true,
    transform: (value: string) => value.trim().toLowerCase(),
    validate: (value: string) =>
      /^[^@\s]+@[^@\s]+\.[^@\s]+$/.test(value)
        ? undefined
        : "Enter a valid email.",
  },
  { key: "team", label: "Team" },
]
const csv =
  'name,email,team\nMaya Chen,maya@example.com,Design\nLeo Park,not-an-email,Engineering\n"River, Sam",sam@example.com,Research'
export default function ImportDemo() {
  const [fail, setFail] = React.useState(false)
  const [count, setCount] = React.useState(0)
  return (
    <div className="w-full max-w-2xl space-y-3">
      <ImportWorkbench
        fields={fields}
        initialCsv={csv}
        onImport={async (records, signal) => {
          await new Promise((resolve) => setTimeout(resolve, 500))
          if (signal.aborted) return
          if (fail) {
            setFail(false)
            throw new Error(
              "Connection interrupted. Your corrections are still here. Try again."
            )
          }
          setCount(records.length)
        }}
      />
      <div className="flex flex-wrap items-center justify-between gap-2 text-xs text-muted-foreground">
          <Checkbox
            label="Fail next import"
            checked={fail}
            onCheckedChange={(checked) => setFail(checked === true)}
            className="text-xs"
          />
        <span>{count} rows received by the demo</span>
      </div>
    </div>
  )
}
```

#### Props of ImportWorkbench

- `fields` (required): `readonly ImportField[]`. Unique key, label, optional required flag, pure transform and validation callbacks. A validator returns an error string or undefined.
- `onImport` (required): `(records: ImportRecord[], signal: AbortSignal) => void | Promise<void>`. Persist validated records. Reject to preserve corrections and show retry feedback. Honor signal for cancellation.
- `initialCsv`: `string`, default `empty string`. Initial text in the CSV editor; parsing begins with Preview columns.
- `maxRows`: `number`, default `500`. Maximum number of nonblank data rows.
- `maxBytes`: `number`, default `1000000`. Byte limit applied to uploaded and pasted UTF-8 data.
- `disabled`: `boolean`, default `false`. Disable editing, file selection and import.
- `className`: `string`. Classes for the section.

#### Keyboard

- Tab / Enter: Move between mapping selects and correction inputs; activate Preview or Import.
- Tab: Move through the enabled controls. Focus remains visible.

#### Accessibility

#### Motion

- Selection and direct manipulation do not require animated movement.
- Shared Lathe controls retain their reduced-motion behavior.

#### Customization

##### Connect your own data

Replace the demo data and callbacks with your application. Honor AbortSignal in asynchronous callbacks so cancellation also stops transport work.

### Metrics Dashboard (Pro)

A dense analytics view: four headline numbers that double as tabs, one chart you can inspect and compare against the previous period, and ranked lists of top pages and sources.

Page: https://latheui.dev/assemblies/metrics-dashboard
Install: npx shadcn@latest add @latheui/metrics-dashboard

#### Usage

```tsx
import { MetricsDashboard } from "@/components/metrics-dashboard"

// Renders with built-in sample data.
export default function Page() {
  return <MetricsDashboard title="Analytics" scope="example.com" />
}
```

#### Props of MetricsDashboard

Also accepts native section attributes.

- `title`: `string`, default `"Analytics"`. Heading of the view.
- `scope`: `string`, default `"example.com"`. What the numbers describe, shown under the heading.
- `data`: `Record<"7d" | "30d" | "90d", MetricsData>`, default `sample data`. Everything shown, for each range.
- `defaultRange`: `"7d" | "30d" | "90d"`, default `"30d"`. Range selected first.
- `loading`: `boolean`, default `false`. Dims the chart while new data loads.

#### Props of MetricsData

- `labels` (required): `string[]`. One label per point, shared by every metric.
- `metrics` (required): `Metric[]`. The headline numbers: id, label, value, change, series, previous, and optional format and lowerIsBetter.
- `pages` (required): `{ label: string; value: number }[]`. Rows for the top pages list.
- `sources` (required): `{ label: string; value: number }[]`. Rows for the sources list.

#### Keyboard

- Tab: Moves through the range switch, the selected metric, the compare switch and the chart.
- ArrowLeft / ArrowRight: On the metrics: selects the previous or next one. On the chart: reads the previous or next point.
- Home / End: First or last metric, or first or last point.

#### Accessibility

- It is a labelled section with a real heading. The headline numbers are a tab list that controls the chart's panel.
- Each change includes hidden text saying what it is compared against, shows direction with an arrow and a sign, and is only colored as bad when it moved the wrong way for that metric.
- The chart's name includes the metric and range, so it stays accurate as they change.
- Layout follows the width of the dashboard itself, not the window: the numbers form a two-by-two grid and the lists stack when it is narrow.

#### Motion

- Changing range rolls every number, slides the list bars and morphs the chart line. Choosing a metric slides the underline and morphs the line to the new series.
- Turning on the comparison raises the previous period's line from the baseline.
- With reduced motion everything changes at once.

#### Customization

##### Your own data

Pass data for each range. The types are exported from the file.

```tsx
import { MetricsDashboard, type MetricsData, type MetricsRange } from "@/components/metrics-dashboard"

const data: Record<MetricsRange, MetricsData> = await getMetrics()

<MetricsDashboard title="Acme" scope="acme.com" data={data} />
```

##### A metric where down is good

```tsx
{ id: "errors", label: "Error rate", value: 0.012, change: -0.08, lowerIsBetter: true,
  format: { style: "percent", maximumFractionDigits: 1 }, series, previous }
```

### Notification Inbox (Pro)

Grouped updates with unread filtering, individual and batch read actions, undo and a preferences slot.

Page: https://latheui.dev/assemblies/notification-inbox
Install: npx shadcn@latest add @latheui/notification-inbox

#### Usage

```tsx
import { NotificationInbox } from "@/components/notification-inbox"

export default function Updates() {
  return <NotificationInbox defaultItems={[{
    id: "review",
    title: "Your review is requested",
    description: "The new onboarding flow is ready.",
    time: "5 minutes ago",
    group: "Today",
  }]} />
}
```

#### Props of NotificationInbox

- `title`: `string`, default `"Inbox"`. Visible heading and accessible section name.
- `items / defaultItems`: `InboxNotification[]`, default `[] (defaultItems)`. Controlled or initial items, in display order. Use unique IDs. The component preserves the supplied group order.
- `onItemsChange`: `(items: InboxNotification[]) => void`. Receives the updated list after read or undo actions. Persist controlled read state in your app.
- `preferences`: `React.ReactNode`. Optional content for the preferences popover. Your app owns and persists these controls.
- `disabled`: `boolean`, default `false`. Disable read, undo and preferences actions. View filtering remains available.
- `className`: `string`. Override the compact max-w-lg card.
- `InboxNotification`: `{ id: string; title: string; description?: string; time: string; dateTime?: string; group: string; read?: boolean }`. Notification record. time is a display label, dateTime is an optional ISO timestamp, and read defaults to false.

#### Keyboard

- Tab: Move through view controls, read actions, preferences and Undo.
- Enter / Space: Activate a focused action.
- Escape: Close preferences and return focus to its trigger.

#### Accessibility

- A named section contains labelled groups and semantic notification lists. The unread count has a text alternative.
- Read state is exposed in text as well as by the dot. Actions have notification-specific names.
- Read actions and Undo return focus to the stable All control. A polite status announces changes.

#### Motion

- Remaining rows reposition using the shared snappy spring. No auto-dismiss timer competes with Undo.
- Reduced motion makes row movement instant; preferences uses the shared Popover behavior.

#### Customization

##### Persist read state

Control items to reconcile server updates. Undo affects only the IDs changed by the most recent read action, preserving unrelated items.

```tsx
<NotificationInbox
  items={notifications}
  onItemsChange={(next) => {
    setNotifications(next)
    saveReadState(next)
  }}
  preferences={<NotificationSettings />}
/>
```

### Order Summary (Pro)

The step before payment: a promo code chip, discount and tax lines, a rolling total and a stateful pay button.

Page: https://latheui.dev/assemblies/order-summary
Install: npx shadcn@latest add @latheui/order-summary

#### Usage

```tsx
import { OrderSummary } from "@/components/order-summary"

export function Checkout() {
  return (
    <OrderSummary
      item={{ name: "Pro plan", description: "10 seats", price: 240, period: "per year" }}
      tax={{ label: "VAT", rate: 0.2 }}
      promo={{ onApply: (code) => checkPromo(code) }}
      onPay={(totals) => pay(totals)}
    />
  )
}
```

#### Props of OrderSummary

Also accepts native section attributes.

- `item`: `OrderItem`, default `a sample order`. The product: name, price, and optional description, period and media. Always pass it in production.
- `adjustments`: `OrderLine[]`, default `[]`. Automatic lines: { id, label, amount, note? }. Negative amounts are discounts.
- `promo`: `{ onApply: (code) => PromoResult | Promise<PromoResult>; placeholder? }`. Enables the promo field. Resolve { ok: true, code, amount, label? } or { ok: false, message }.
- `tax`: `{ label?: string; rate?: number; note?: string }`. rate is a fraction of the discounted subtotal. Without it, note is shown.
- `currency`: `string`, default `"USD"`. ISO 4217 code.
- `locale`: `string`, default `"en-US"`. Locale for amounts.
- `title`: `string`, default `"Order summary"`. Heading and accessible name.
- `onPay`: `(totals: OrderTotals) => void | Promise<void>`. Takes the payment in the page. The button follows the promise it returns.
- `form`: `{ action; method?; fields? }`. Posts a native form instead, for hosted checkout pages. The total, currency and promo code are posted as hidden fields.
- `payLabel`: `(formattedTotal: string) => string`, default `"Pay $…"`. Text of the pay button.
- `secureNote`: `string`, default `"Encrypted payment"`. Text beside the lock.
- `disabled`: `boolean`, default `false`. Keeps the button visible but blocks payment.
- `footnote`: `ReactNode`. Small print under the button.

#### Props of OrderTotals

Passed to onPay.

- `subtotal` (required): `number`. The item price.
- `discount` (required): `number`. Everything taken off, including the promo code.
- `tax` (required): `number`. Tax on the discounted subtotal.
- `total` (required): `number`. What to charge, in major units.
- `currency` (required): `string`. ISO 4217 code.
- `promoCode` (required): `string | null`. The applied code, to re-check on your server.

#### Keyboard

- Enter: In the promo field: applies the code.
- Tab: Moves through the promo field, Apply or the chip's remove button, and the pay button.
- Enter / Space: On the chip's remove button: removes the code and returns focus to the field.

#### Accessibility

- It is a labelled section. Amounts are a description list, so each number is read with its label.
- A rejected code sets aria-invalid on the field and shows the reason as an alert linked to it.
- The pay button is a live region, so Processing and Paid are announced. A failed payment adds an alert with the reason and the button offers to try again.
- The total exposes its plain value once; the rolling digits are hidden from assistive tech.
- While processing, the button stays focusable and ignores presses instead of being disabled.

#### Motion

- The promo field swaps for a chip, its line opens in the list, and the total rolls to the new amount. A rejected code shakes the field for 360ms.
- The pay button's label rises in on each state change.
- With reduced motion nothing shakes or slides and the total changes at once.

#### Customization

##### A hosted checkout page

Most providers (Stripe Checkout, Paddle, Lemon Squeezy) redirect to a page they host. Post to a route of yours that creates the session and redirects. Re-compute the amount on the server from the item and promo code; never trust the posted total.

```tsx
// app/checkout/route.ts creates the session and redirects to it.
<OrderSummary
  item={item}
  promo={{ onApply: checkPromo }}
  form={{ action: "/checkout", fields: { priceId: item.priceId } }}
/>
```

##### Paying in the page with a provider SDK

Anything that returns a promise works: a card element's confirm call, a wallet sheet, or a bank link flow such as Plaid Link, wrapped so it resolves on success and rejects on exit.

```tsx
<OrderSummary
  item={item}
  onPay={async ({ total, currency, promoCode }) => {
    const { clientSecret } = await createPayment({ itemId: item.id, promoCode })
    const { error } = await stripe.confirmPayment({ elements, clientSecret, redirect: "if_required" })
    if (error) throw new Error(error.message)
  }}
/>

// A bank link flow: resolve when the account is linked, reject if the sheet is closed.
const linkBank = () =>
  new Promise<void>((resolve, reject) =>
    Plaid.create({ token: linkToken, onSuccess: (token) => exchange(token).then(resolve, reject), onExit: () => reject(new Error("Bank link cancelled.")) }).open()
  )
```

### Pricing Table (Pro)

Three plans side by side with a monthly and yearly switch. Prices roll to their new values when the billing period changes.

Page: https://latheui.dev/assemblies/pricing-table
Install: npx shadcn@latest add @latheui/pricing-table

#### Usage

```tsx
import { PricingTable } from "@/components/pricing-table"

// Renders with built-in sample plans.
export default function Page() {
  return <PricingTable onSelect={(plan, period) => startCheckout(plan.id, period)} />
}
```

#### Props of PricingTable

Also accepts native section attributes.

- `title`: `string`, default `"Plans"`. Heading of the block.
- `plans`: `PricingPlan[]`, default `sample plans`. Plans to show, in order.
- `defaultPeriod`: `"monthly" | "yearly"`, default `"monthly"`. Billing period selected first.
- `yearlyNote`: `string`, default `"Save 20%"`. Note beside the yearly option.
- `currency`: `string`, default `"USD"`. ISO currency code for the prices.
- `onSelect`: `(plan: PricingPlan, period: BillingPeriod) => void`. Called when a plan's button is pressed.

#### Props of PricingPlan

- `id` (required): `string`. Unique id.
- `name` (required): `string`. Plan name.
- `description` (required): `string`. One line on who it is for.
- `price` (required): `{ monthly: number; yearly: number } | null`. Price per month in each period. null shows priceLabel.
- `priceLabel`: `string`. Shown instead of a number, for example “Custom”.
- `features` (required): `string[]`. What the plan includes.
- `cta` (required): `string`. Button text.
- `featured`: `boolean`. Marks the plan as recommended.

#### Keyboard

- Tab: Moves through the billing switch and each plan's button.
- ArrowLeft / ArrowRight: On the billing switch: changes the period.

#### Accessibility

- The block is a labelled section, and each plan is a list item with its own heading.
- Each button's accessible name includes its plan, so three “Start” buttons are told apart.
- The recommended plan is marked with a text badge as well as a darker border.
- Prices expose their plain value to screen readers once, not digit by digit.
- Plans stack on small screens.

#### Motion

- Changing the billing period rolls each price's digits to the new value.
- With reduced motion prices change at once.

#### Customization

##### Your plans

```tsx
<PricingTable
  title="Pricing"
  currency="EUR"
  yearlyNote="2 months free"
  plans={[
    { id: "solo", name: "Solo", description: "For one person.", price: { monthly: 9, yearly: 7 }, features: ["1 seat"], cta: "Choose Solo" },
    { id: "team", name: "Team", description: "For a team.", price: { monthly: 39, yearly: 32 }, features: ["10 seats"], cta: "Choose Team", featured: true },
  ]}
/>
```

### Review Contact Sheet (Pro)

Select assets, compare aligned images, annotate a single image, approve or reject selections, and export a review with comments.

Page: https://latheui.dev/assemblies/review-contact-sheet
Install: npx shadcn@latest add @latheui/review-contact-sheet

#### Usage

```tsx
"use client"
import * as React from "react"
import { Checkbox } from "@/components/ui/checkbox"
import { ReviewContactSheet } from "@/components/review-contact-sheet"
const assets = [
  {
    id: "original",
    title: "Lake · original",
    src: "/demo/photos/compare-flat.webp",
    alt: "An autumn lake before color grading",
  },
  {
    id: "graded",
    title: "Lake · graded",
    src: "/demo/photos/compare-graded.webp",
    alt: "An autumn lake after color grading",
  },
  {
    id: "coast",
    title: "Coastal study",
    src: "/demo/photos/fermin-rodriguez-penelas-b8keuzqmnoq.webp",
    alt: "A bay at sunset",
  },
]
export default function ReviewDemo() {
  const [fail, setFail] = React.useState(false)
  return (
    <div className="w-full max-w-2xl space-y-3">
      <ReviewContactSheet
        defaultValue={assets}
        onReview={async (_ids, _decision, signal) => {
          await new Promise((resolve) => setTimeout(resolve, 400))
          if (signal.aborted) return
          if (fail) {
            setFail(false)
            throw new Error("Review could not be saved. Try again.")
          }
        }}
      />
        <Checkbox
          label="Fail next review"
          checked={fail}
          onCheckedChange={(checked) => setFail(checked === true)}
          className="text-xs text-muted-foreground"
        />
    </div>
  )
}
```

#### Props of ReviewContactSheet

- `value / defaultValue`: `ReviewAsset[]`, default `[] (defaultValue)`. Controlled or initial assets with unique id, title, src, alt and optional pending/approved/rejected status.
- `onValueChange`: `(assets: ReviewAsset[]) => void`. Receives updated decisions after persistence succeeds.
- `onReview`: `(ids: string[], decision, signal: AbortSignal) => void | Promise<void>`. Optional persistence callback. Reject for retry, honor signal for cancellation; omit for local review.
- `onAnnotationsChange`: `(assetId: string, notes: Annotation[]) => void`. Receive annotation edits for external persistence. Notes are also kept locally for export.
- `disabled`: `boolean`, default `false`. Disable selection, decisions, annotations and export.
- `className`: `string`. Classes for the section.

#### Keyboard

- Space / Tab / Enter: Select assets using checkboxes, open inspection and review. Closing inspection returns focus to its trigger.
- Tab: Move through the enabled controls. Focus remains visible.

#### Accessibility

#### Motion

- Selection and direct manipulation do not require animated movement.
- Shared Lathe controls retain their reduced-motion behavior.

#### Customization

##### Connect your own data

Replace the demo data and callbacks with your application. Honor AbortSignal in asynchronous callbacks so cancellation also stops transport work.

### Scenario Workbench (Pro)

Adjust model assumptions, pin a baseline, and compare calculated metrics and projection data in a chart and table.

Page: https://latheui.dev/assemblies/scenario-workbench
Install: npx shadcn@latest add @latheui/scenario-workbench

#### Usage

```tsx
"use client"
import { ScenarioWorkbench, type ScenarioResult } from "@/components/scenario-workbench"
const inputs = [{ key: "customers", label: "Starting customers", min: 10, max: 1000, defaultValue: 120, step: 10 }, { key: "growth", label: "Monthly growth (%)", min: 0, max: 25, defaultValue: 5 }, { key: "price", label: "Price per month", min: 1, max: 100, defaultValue: 24 }]
function calculate(values: Record<string, number>): ScenarioResult {
  const points = Array.from({ length: 6 }, (_, index) => ({ label: "Month " + (index + 1), value: Math.round(values.customers * (1 + values.growth / 100) ** index * values.price) }))
  return { metrics: [{ key: "revenue", label: "Month six revenue", value: points[5].value }, { key: "customers", label: "Month six customers", value: Math.round(points[5].value / values.price) }], points }
}
export default function ScenarioDemo() { return <div className="w-full max-w-3xl"><ScenarioWorkbench title="A small growth model" inputs={inputs} calculate={calculate} /><p className="mt-3 text-xs text-muted-foreground">Illustrative arithmetic supplied by the demo, not a forecast.</p></div> }
```

#### Props of ScenarioWorkbench

- `title` (required): `string`. Visible heading and chart label.
- `inputs` (required): `readonly ScenarioInput[]`. Unique key, label, finite min/max, defaultValue and optional step for each assumption.
- `calculate` (required): `(values: Record<string, number>) => ScenarioResult`. Pure synchronous application model returning metrics and uniquely labelled points. Errors are shown without discarding assumptions.
- `value / defaultValue`: `Record<string, number>`, default `input defaults (defaultValue)`. Controlled or initial canonical assumption values.
- `onValueChange`: `(values: Record<string, number>) => void`. Receives changed assumptions.
- `disabled`: `boolean`, default `false`. Disable assumptions and baseline actions.
- `className`: `string`. Classes for the section.

#### Keyboard

- Arrow keys: Adjust assumptions through scrub handles or native number inputs. The chart also supports keyboard inspection.
- Tab: Move through the enabled controls. Focus remains visible.

#### Accessibility

#### Motion

- Selection and direct manipulation do not require animated movement.
- Shared Lathe controls retain their reduced-motion behavior.

#### Customization

##### Connect your own data

Replace the demo data and callbacks with your application. Honor AbortSignal in asynchronous callbacks so cancellation also stops transport work.

### Sign In

A sign-in panel that also creates accounts, with provider buttons, validation and progress states. The preview sends nothing anywhere.

Page: https://latheui.dev/assemblies/sign-in
Install: npx shadcn@latest add @latheui/sign-in

#### Usage

```tsx
import { SignIn } from "@/components/sign-in"

export default function Page() {
  return (
    <SignIn
      providers={[{ id: "github", label: "Continue with GitHub" }]}
      onProvider={(id) => startOAuth(id)}
      onSubmit={async ({ email, password, remember }) => {
        const response = await fetch("/api/session", {
          method: "POST",
          headers: { "Content-Type": "application/json" },
          body: JSON.stringify({ email, password, remember }),
        })
        if (!response.ok) throw new Error("That email and password do not match.")
      }}
    />
  )
}
```

#### Props of SignIn

Also accepts native section attributes.

- `title`: `string`, default `"Welcome back"`. Heading and accessible name of the panel.
- `description`: `string`. Line under the heading.
- `createTitle`: `string`, default `"Create your account"`. Heading while creating an account.
- `createDescription`: `string`. Line under that heading.
- `mode`: `"sign-in" | "create"`. Which form shows. Leave it out to let the link under the form switch it.
- `defaultMode`: `"sign-in" | "create"`, default `"sign-in"`. The form shown first when mode is left out.
- `onModeChange`: `(mode: SignInMode) => void`. Called when the link under the form switches forms. Keep mode at "sign-in" and route here to send people to a separate sign-up page instead.
- `providers`: `SignInProvider[]`, default `[]`. Other ways in, each with id, label and optional icon. Shown above the form in both modes.
- `onSubmit`: `(values: SignInValues) => void | Promise<void>`. Signs in with email, password and remember. Return a promise to show progress; reject with an Error to show its message.
- `onProvider`: `(id: string) => void | Promise<void>`. Starts a provider's flow. Return a promise to show progress on that button.
- `onForgotPassword`: `(email: string) => void`. Called with whatever is in the email field.
- `onCreateAccount`: `(values: CreateAccountValues) => void | Promise<void>`. Creates the account with name, email and password. Return a promise to show progress; reject with an Error to show its message.

#### Keyboard

- Tab: Moves through the providers, fields, show-password button, checkbox and links.
- Enter: In a field: submits the form.
- Space: On the checkbox: toggles keeping the session.

#### Accessibility

- The panel is a labelled section around a native form, with autocomplete hints for password managers.
- Field errors appear after the first attempt, are tied to their fields and follow them as they are corrected.
- A refused sign-in is announced with role=alert.
- While one action runs, its button reports progress and the others are disabled.
- The divider between providers and the form is decorative and hidden from screen readers.
- Switching forms moves focus to the new form's first field, since the link that was pressed is replaced. The email carries over.
- A new password shows its strength as text as well as bars, and asks for at least 8 characters.

#### Motion

- The error line grows in and out so the button below does not jump.
- Switching between sign in and create account cross-fades the heading and form.
- With reduced motion the error appears at once.

#### Customization

##### Your own copy and width

```tsx
<SignIn
  title="Sign in to Northwind"
  description="Use your work email."
  className="max-w-md"
  onForgotPassword={(email) => router.push(`/reset?email=${encodeURIComponent(email)}`)}
  onSubmit={signIn}
  onCreateAccount={createAccount}
/>
```

##### Sign-up on its own page

```tsx
<SignIn
  mode="sign-in"
  onModeChange={(mode) => mode === "create" && router.push("/join")}
  onSubmit={signIn}
/>
```

### Stat Tiles (Pro)

A row of headline numbers, each with its trend line and change, that roll to new values when the range changes.

Page: https://latheui.dev/assemblies/stat-tiles
Install: npx shadcn@latest add @latheui/stat-tiles

#### Usage

```tsx
import { StatTiles } from "@/components/stat-tiles"

// Renders with built-in sample numbers.
export default function Page() {
  return <StatTiles onRangeChange={(range) => track("range", range)} />
}
```

#### Props of StatTiles

Also accepts native section attributes.

- `title`: `string`, default `"Overview"`. Heading and accessible name of the block.
- `tiles`: `StatTile[]`, default `sample tiles`. Tiles to show, in order.
- `ranges`: `{ value: string; label: string }[]`, default `7, 30 and 90 days`. Ranges offered by the switch, matching the keys of each tile's series. One range hides the switch.
- `defaultRange`: `string`, default `the second range`. Range selected first.
- `onRangeChange`: `(range: string) => void`. Called when the range changes.

#### Props of StatTile

- `id` (required): `string`. Unique id.
- `label` (required): `string`. Name of the number.
- `series` (required): `Record<string, number[]>`. One series per range, oldest first. The last point is the value shown, and the change is measured from the first.
- `format`: `Intl.NumberFormatOptions`. Formatting of the value, such as a currency or a percent.
- `lowerIsBetter`: `boolean`. Set when a fall is the good direction, such as response time.

#### Keyboard

- Tab: Moves to the range switch.
- ArrowLeft / ArrowRight: On the range switch: changes the range.

#### Accessibility

- The block is a labelled section, and the tiles are a list.
- Each trend line has a text name that includes its tile and range.
- Direction is carried by the arrow and the sign of the change, not by color alone.
- Values expose their plain number to screen readers once, not digit by digit.
- Columns follow the width of the block itself, so it fits a sidebar as well as a full page.

#### Motion

- Changing the range rolls each value's digits, and the change percentage's, to the new number.
- Each trend line glides to its new shape instead of jumping.
- The arrow turns between up and down, and shrinks away when nothing changed.
- The range text morphs letter by letter, and the warning color fades in and out.
- With reduced motion values, lines and the arrow change at once.

#### Customization

##### From your own data

Fetch one series per range and let the block work out the value and the change.

```tsx
<StatTiles
  title="This quarter"
  ranges={[{ value: "q", label: "Quarter" }]}
  tiles={[
    { id: "mrr", label: "MRR", format: { style: "currency", currency: "EUR" }, series: { q: mrrByWeek } },
    { id: "latency", label: "p95 latency", lowerIsBetter: true, series: { q: latencyByWeek } },
  ]}
/>
```

### Testimonial Wall (Pro)

A heading over rows of quotes that drift past in opposite directions and slow down under the pointer.

Page: https://latheui.dev/assemblies/testimonial-wall
Install: npx shadcn@latest add @latheui/testimonial-wall

#### Usage

```tsx
import { TestimonialWall } from "@/components/testimonial-wall"

// Renders with built-in sample quotes.
export default function Page() {
  return <TestimonialWall />
}
```

#### Props of TestimonialWall

Also accepts native section attributes.

- `title`: `string`, default `"What people say"`. Heading and accessible name of the block.
- `description`: `string`. Line under the heading.
- `items`: `Testimonial[]`, default `sample quotes`. What people said. Dealt out across the rows in order.
- `rows`: `1 | 2 | 3`, default `2`. Rows of quotes. Neighbouring rows travel in opposite directions.
- `speed`: `number`, default `28`. Pixels per second the rows travel.

#### Props of Testimonial

- `id` (required): `string`. Unique id.
- `quote` (required): `string`. What they said, without quotation marks.
- `name` (required): `string`. Who said it. Also gives the avatar its initials.
- `role`: `string`. Role and company.
- `avatar`: `string`. Image URL. Initials are shown without one.

#### Accessibility

- The block is a labelled section.
- Each row is a named group, and each quote is a figure with its author as the caption.
- Screen readers get every quote once. The copies that fill the loop are hidden from them.
- With motion the rows hold nothing focusable. With reduced motion each row becomes a scrolling region the keyboard can reach.
- A hovering pointer slows the rows enough to read a quote in place.

#### Motion

- Rows travel at a steady speed and ease down to a quarter of it under the pointer.
- With reduced motion the rows stand still and can be scrolled sideways.

#### Customization

##### Three rows with photos

```tsx
<TestimonialWall
  title="Loved by teams"
  rows={3}
  speed={36}
  items={quotes.map((quote) => ({
    id: quote.id,
    quote: quote.body,
    name: quote.author,
    role: `${quote.role}, ${quote.company}`,
    avatar: quote.photoUrl,
  }))}
/>
```

### Upload Manager (Pro)

A file queue with raster previews, per-file progress, cancellation, retry and application-owned upload transport.

Page: https://latheui.dev/assemblies/upload-manager
Install: npx shadcn@latest add @latheui/upload-manager

#### Usage

```tsx
import { UploadManager } from "@/components/upload-manager"

export default function Uploads() {
  return <UploadManager onUpload={async (file, { signal }) => {
    const body = new FormData()
    body.append("file", file)
    const response = await fetch("/api/uploads", { method: "POST", body, signal })
    if (!response.ok) throw new Error("Could not upload. Try again.")
  }} />
}
```

#### Props of UploadManager

- `title`: `string`, default `"Upload files"`. Visible heading and accessible section name.
- `onUpload` (required): `(file: File, context: UploadContext) => Promise<void>`. Required transport callback. Resolve only when the upload is confirmed; reject with an Error for a retryable message.
- `onEntriesChange`: `(entries: UploadEntry[]) => void`. Observe queue changes, including progress. The manager owns the queue; this callback does not control it.
- `accept`: `string`. Comma-separated extensions or MIME types, as on a file input. Validate uploads again on your server.
- `maxSize`: `number`, default `10485760`. Maximum bytes per file, enforced by FileDropzone.
- `maxFiles`: `number`, default `5`. Maximum queue length, including complete, failed and cancelled files. Remove a file to free a slot.
- `hint`: `string`. Optional dropzone help. Defaults to text derived from the file and size limits.
- `disabled`: `boolean`, default `false`. Disable adding files and queue actions. Existing uploads continue.
- `className`: `string`. Override the max-w-lg card layout.
- `UploadContext`: `{ signal: AbortSignal; onProgress: (percent: number) => void }`. Respect signal to stop work. Report percentages from 0 to 100 when available; progress is monotonic within an attempt.
- `UploadEntry`: `{ id: string; file: File; state: "uploading" | "complete" | "error" | "cancelled"; progress?: number; error?: string }`. Queue snapshot supplied to onEntriesChange. IDs remain stable across retries.

#### Keyboard

- Tab: Focus the file picker, Cancel, Retry and Remove actions.
- Enter / Space: Open the native picker or activate the focused queue action.

#### Accessibility

- The dropzone is a labelled native file input; drag-and-drop is an additional input method.
- Each active file has a named progressbar, determinate when progress is reported and indeterminate otherwise.
- Errors and completed or cancelled states remain visible in the row. Changes are announced in a polite status.
- Removing a row returns focus to the file input. Raster thumbnails are decorative and object URLs are revoked on removal or unmount.

#### Motion

- Rows reposition using the shared snappy spring; progress uses the existing Progress transition.
- Reduced motion disables row movement and indeterminate animation. No simulated progress runs inside the component.

#### Customization

##### Report real progress

Use an upload client that reports bytes transferred, pass its abort handling the signal, and resolve after the server confirms success. Cancellation and unmount ignore late results from old attempts.

```tsx
<UploadManager
  accept="image/*,.pdf"
  maxFiles={3}
  hint="Images and PDFs · Up to 3 files"
  onUpload={(file, { signal, onProgress }) =>
    uploadFile(file, {
      signal,
      onBytes: (sent, total) => onProgress((sent / total) * 100),
    })
  }
/>
```