# goodui

> Animated components and application blocks for shadcn/ui: scheduling and booking, dashboards, tables, billing, auth, onboarding, notifications and AI chat. React 19, Tailwind v4, works with Base UI and Radix shadcn. Twelve style packs (clean, brutal, glass, retro98, pixel, terminal, editorial, soft, neon, paper, swiss, luxe) via data-style on <html>; goodui Native has the same looks.

Every goodui component with its full docs and API. Index: https://goodui.dev/llms.txt

# Number flow

> Digits roll to the new value with locale formatting, prefixes and suffixes.

Animated rolling number for React and shadcn: digits roll to the new value

Page: https://goodui.dev/components/numbers/number-flow

## Install

```bash
npx shadcn@latest add @goodui/number-flow
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/number-flow.json`. The file lands in `components/goodui/number-flow.tsx`.

## When to use

- A live value that changes while the user watches: revenue on a dashboard, a cart total, seats left.
- Prices that switch with a monthly/yearly toggle, so the change is visible instead of a jump.
- Small counts next to controls (+ / - steppers) where each change should feel physical.

## When not to use

- A number that should count up once when it scrolls into view: use counter-up.
- Showing the change itself (+12.4%) rather than the value: use delta-badge.
- Values in a dense table that update often: use cell-flash, which signals the direction without moving the layout.

## Usage

```tsx
import { NumberFlow } from "@/components/goodui/number-flow"

export function PlanPrice({ yearly }: { yearly: boolean }) {
  return (
    <div className="flex items-baseline gap-1">
      <NumberFlow
        value={yearly ? 39 : 49}
        format={{ style: "currency", currency: "USD", maximumFractionDigits: 0 }}
        className="text-4xl font-semibold tracking-tight"
      />
      <span className="text-sm text-muted-foreground">per seat / month</span>
    </div>
  )
}
```

### Dashboard revenue in another locale

```tsx
<NumberFlow
  value={48295.5}
  locale="de-DE"
  format={{ style: "currency", currency: "EUR" }}
  className="text-3xl font-semibold"
/>
```

### Percent with prefix and suffix

```tsx
<NumberFlow value={0.684} format={{ style: "percent", maximumFractionDigits: 1 }} />
<NumberFlow value={1284} prefix="~" suffix=" bookings" />
```

## API

### NumberFlow

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| value (required) | `number` | — | Number to show. Changing it rolls each digit to its new value. |
| format | `Intl.NumberFormatOptions` | — | Intl.NumberFormat options, e.g. { style: "currency", currency: "USD" }. |
| locale | `string` | — | Locale passed to Intl.NumberFormat ("de-DE" gives 1.234,5). Defaults to the GooduiLocaleProvider language, else en-US. |
| prefix | `string` | `""` | Text placed before the formatted number, e.g. "~". |
| suffix | `string` | `""` | Text placed after the formatted number, e.g. " / mo". |
| className | `string` | — | Classes merged onto the root element. |

## Accessibility

- The formatted value is rendered once in an sr-only span; the rolling digit columns are aria-hidden, so screen readers never read ten digits per column.
- There is no aria-live region: wrap it in your own live region if a change must be announced.

## Motion

- Each digit is a 0-9 column that slides on a spring (stiffness 140, damping 20, mass 0.8). A 9 going to 0 rolls back down the column through every digit, it does not wrap.
- Separators, currency symbols, prefix and suffix swap instantly; only digits roll.
- Characters are keyed by their distance from the end, so units stay in their column when the number gains or loses digits.
- Reduced motion: the transition becomes duration 0, so digits snap to the new value.

## Performance

- Each digit is one motion span animating transform only. There are no timers; nothing runs while the value is stable.

## Notes for AI

- Pass a number to value and formatting through format (Intl.NumberFormatOptions) and locale; do not pre-format it into a string.
- For currency use format={{ style: "currency", currency: "USD" }}, not prefix="$".
- It animates on value change only; it does not count up on mount. Use counter-up for that.
- Give the font size and weight through className; the component sets tabular-nums itself.
- There is no labels prop: the only text it renders is the formatted value.

## FAQ

**Does it animate on first render?**

No. initial is false, so it shows the value immediately and only rolls when value changes. Use counter-up for a count from zero.

**Can it show decimals and currencies?**

Yes. Anything Intl.NumberFormat formats works: currency, percent, compact notation, fixed fraction digits, any locale. Each digit in the output rolls.

## Related

- counter-up: https://goodui.dev/components/numbers/counter-up
- delta-badge: https://goodui.dev/components/numbers/delta-badge
- cell-flash: https://goodui.dev/components/numbers/cell-flash
- stat-card: https://goodui.dev/components/core/stat-card

Last updated: 2026-11-02

---

# Shimmer button

> A light sweep runs across the button. Pure CSS; the sweep is removed for reduced motion.

Shimmer button for React and shadcn: CSS light sweep across a CTA

Page: https://goodui.dev/components/buttons/shimmer-button

## Install

```bash
npx shadcn@latest add @goodui/shimmer-button
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/shimmer-button.json`. The file lands in `components/goodui/shimmer-button.tsx`.

## When to use

- One call to action that should catch the eye on a landing or pricing page ("Start free trial").
- An upgrade prompt inside an app, where a slow sweep hints at the action without a badge.
- When you want a single standalone file with no variants to learn: one primary-colored button with a sweep.

## When not to use

- You already use the Core button: button with animation="shimmer" gives the same sweep plus every variant, tone, size and the loading state. That is the simpler choice in most apps.
- Several buttons on one screen: a looping sweep on each one competes for attention; keep shimmer to the main action and use button for the rest.
- Async actions that need loading, success and error feedback: use stateful-button.

## Pick by what matters

| Need | Use |
| --- | --- |
| Calmer, occasional sweep | duration={4} |
| Faster, more energetic sweep | duration={1.6} |
| Band visible on a light or custom background | shimmerColor="rgb(255 255 255 / 0.7)" or a brand color, plus your own className for the face |
| Same sweep with variants, tones and loading | button with animation="shimmer" |

## Usage

```tsx
import { Sparkles } from "lucide-react"
import { ShimmerButton } from "@/components/goodui/shimmer-button"

export function UpgradeCta({ onUpgrade }: { onUpgrade: () => void }) {
  return (
    <ShimmerButton onClick={onUpgrade}>
      <Sparkles />
      Upgrade to Pro
    </ShimmerButton>
  )
}
```

### Large hero button with a slower sweep

```tsx
<ShimmerButton duration={3.6} className="h-12 rounded-full px-8 text-base">
  Book your first cleaning
</ShimmerButton>
```

### Custom face and band color

```tsx
<ShimmerButton
  className="bg-emerald-600 text-white hover:bg-emerald-600/90"
  shimmerColor="rgb(255 255 255 / 0.6)"
>
  Accept quote · $240
</ShimmerButton>
```

## API

### ShimmerButton

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| duration | `number` | `2.4` | Seconds per sweep. |
| shimmerColor | `string` | — | Color of the light band. |

Also accepts every <button> attribute.

## Keyboard

| Keys | Action |
| --- | --- |
| Enter / Space | Activates the button (native <button>). |
| Tab | Moves focus; a focus ring shows on keyboard focus only. |

## Accessibility

- Renders a native <button> and passes every button attribute through, so type, disabled, form and aria-* work as usual.
- The light band is a ::after pseudo-element with pointer-events: none; it is not announced and never blocks clicks.
- Disabled buttons get 50% opacity and no pointer events.

## Motion

- A 45%-wide light band, skewed by -20deg, sweeps from left to right on an ease-in-out loop every `duration` seconds (2.4 s by default).
- Press scales the button to 0.98; hover deepens the shadow.
- Reduced motion: the sweep is removed (animation off, band hidden); the button stays fully usable.

## Performance

- The sweep is a CSS transform animation on one pseudo-element; no JavaScript runs while it loops.

## Notes for AI

- Pass content as children (icons go inline before or after the text); there is no variant, size or icon prop.
- Restyle the face with className (bg-*, h-*, rounded-*, px-*); the sweep follows the border radius because the button clips overflow.
- duration is in seconds, not milliseconds.
- Use it for one main action per screen; for full variant control use the Core button with animation="shimmer" instead.

## FAQ

**What is the difference from the Core button's shimmer animation?**

Both sweep a light band. The Core button adds variants, tones, sizes, icons and loading, and sweeps every 2.6 s; ShimmerButton is a single small file with a configurable duration and band color.

**The band is hard to see on my button.**

The default band is white at 45% opacity, made for a dark or saturated face. On a light face pass a stronger or darker shimmerColor.

## Related

- button: https://goodui.dev/components/core/button
- shiny-text: https://goodui.dev/components/text/shiny-text
- border-beam-button: https://goodui.dev/components/buttons/border-beam-button
- rainbow-button: https://goodui.dev/components/buttons/rainbow-button

Last updated: 2026-11-02

---

# Tabs indicator

> Tabs whose indicator glides between tabs on a shared-layout spring (underline with hover highlight, pill, or segmented with icons), with arrow-key navigation and panels that slide in the direction of travel while the height eases to fit.

Animated tabs with sliding indicator for React and shadcn: underline, pill and segmented

Page: https://goodui.dev/components/navigation/tabs-indicator

## Install

```bash
npx shadcn@latest add @goodui/tabs-indicator
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/tabs-indicator.json`. The file lands in `components/goodui/tabs-indicator.tsx`.

## When to use

- Switching between views of the same data: Upcoming / Pending / Past bookings.
- Short tab sets where a gliding indicator and sliding panels make the change easy to follow.
- Range pickers above a chart (Day / Week / Month / Year) with the pill variant and your own content below.

## When not to use

- Choosing a setting or filter value without panels: use segmented-control (radiogroup semantics).
- Moving between pages of the app: use links in your nav, or bottom-nav on mobile.
- Needing vertical tabs, enclosed folder tabs or more variants: use the tabs core component.

## Pick by what matters

| Need | Use |
| --- | --- |
| Section tabs under a heading | variant="underline" (default, with hover highlight) |
| Chips-like range picker | variant="pill" |
| Compact switcher with icons | variant="segmented" with icon on items |
| Tabs fill the card width | fullWidth |
| Built-in animated panels | content on each item |
| You render the content yourself | no content; read value / onValueChange |

## Usage

```tsx
import { TabsIndicator } from "@/components/goodui/tabs-indicator"

export function BookingTabs({ upcoming, pending, past }: { upcoming: React.ReactNode; pending: React.ReactNode; past: React.ReactNode }) {
  return (
    <TabsIndicator
      listLabel="Booking status"
      defaultValue="upcoming"
      items={[
        { value: "upcoming", label: "Upcoming", badge: 4, content: upcoming },
        { value: "pending", label: "Pending", badge: 2, content: pending },
        { value: "past", label: "Past", content: past },
        { value: "cancelled", label: "Cancelled", disabled: true },
      ]}
    />
  )
}
```

### Controlled pill range picker with your own content

```tsx
const [range, setRange] = React.useState("week")

<TabsIndicator
  variant="pill"
  listLabel="Revenue range"
  value={range}
  onValueChange={setRange}
  items={[
    { value: "day", label: "Day" },
    { value: "week", label: "Week" },
    { value: "month", label: "Month" },
    { value: "year", label: "Year" },
  ]}
/>
<RevenueChart range={range} />
```

### Segmented with icons and panels

```tsx
<TabsIndicator
  variant="segmented"
  fullWidth
  listLabel="Calendar view"
  defaultValue="day"
  items={[
    { value: "day", label: "Day", icon: CalendarDays, content: <DayView /> },
    { value: "week", label: "Week", icon: CalendarRange, content: <WeekView /> },
    { value: "month", label: "Month", icon: Calendar, content: <MonthView /> },
  ]}
/>
```

## API

### TabsIndicator

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| items (required) | `TabsIndicatorItem[]` | — | The tabs, in order. Give items content to get built-in panels. |
| value | `string` | — | Selected tab value (controlled). |
| defaultValue | `string` | — | Initially selected tab when uncontrolled; defaults to the first enabled item. |
| onValueChange | `(value: string) => void` | — | Called with the new value on click or arrow-key selection. |
| variant | `"underline" \| "pill" \| "segmented"` | `"underline"` | underline: line under the active tab plus a hover highlight. pill: filled primary pill. segmented: raised thumb in a muted track. |
| fullWidth | `boolean` | `false` | Stretch the tabs into equal columns. |
| listLabel | `string` | — | Accessible name of the tab list. |
| listClassName | `string` | — | Classes for the tablist element. |
| panelClassName | `string` | — | Classes for the tab panel (only rendered when items have content). |

Also accepts every <div> attribute.

## Keyboard

| Keys | Action |
| --- | --- |
| Tab | Focuses the selected tab, then the panel (one tab stop for the list). |
| ArrowRight / ArrowLeft | Selects and focuses the next or previous enabled tab, wrapping around. |
| Home / End | Selects the first or last enabled tab. |
| Enter / Space | Selects the focused tab (native <button>). |

## Accessibility

- Uses role="tablist" (aria-orientation horizontal, named by listLabel) with role="tab" buttons, aria-selected and a roving tabindex.
- With content, a role="tabpanel" is rendered, labelled by its tab and linked from the selected tab through aria-controls; the panel is focusable.
- Without content there is no tabpanel or aria-controls; if you render the panel yourself, add role="tabpanel" to it.
- Disabled items are skipped by the arrow keys.

## Motion

- The indicator (underline, pill or thumb) is one shared-layout element that glides to the selected tab on a spring (stiffness 420, damping 36, mass 0.8).
- Underline variant: a muted highlight follows the pointer between tabs on the same spring and fades out in 150 ms when the pointer leaves.
- Panels slide 28px in the direction of travel with a 2px blur and fade (spring 380 / 34, opacity 180 ms) while the container height eases to the new panel (0.35 s, no bounce).
- Reduced motion: the indicator jumps, panels swap without sliding or blur, and the height changes instantly.

## Notes for AI

- Pass tabs as items={[{ value, label, icon?, badge?, disabled?, content? }]}; there are no Tab or TabPanel child components.
- icon takes the component (icon: CalendarDays), not an element.
- Use content for built-in panels; if any item has content, a panel is rendered for the selected one.
- Always pass listLabel so the tablist has a name.
- The list scrolls horizontally with a hidden scrollbar when tabs overflow; do not wrap it in your own overflow container.

## FAQ

**How is this different from the core tabs component?**

tabs-indicator is a focused, items-based component with three variants and directional panels. The core tabs component has more variants (enclosed, soft, vertical), tones and sizes.

**Can several instances live on one page?**

Yes. The indicator's layoutId is scoped with useId, so indicators never jump between instances.

## Related

- tabs: https://goodui.dev/components/core/tabs
- segmented-control: https://goodui.dev/components/navigation/segmented-control
- bottom-nav: https://goodui.dev/components/navigation/bottom-nav
- stepper: https://goodui.dev/components/navigation/stepper

Last updated: 2026-11-02

---

# Segmented control

> iOS-style segmented control whose thumb springs to the chosen segment and squeezes while pressed, with sizes, icons, full-width mode, dividers that hide next to the thumb, and radio-group arrow keys.

iOS-style segmented control for React and shadcn with a sliding spring thumb

Page: https://goodui.dev/components/navigation/segmented-control

## Install

```bash
npx shadcn@latest add @goodui/segmented-control
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/segmented-control.json`. The file lands in `components/goodui/segmented-control.tsx`.

## When to use

- Choosing one of 2–5 short options that apply right away: Monthly / Yearly pricing, In person / Video / Phone.
- View switchers in a toolbar: list, grid, map (icon-only with ariaLabel).
- Filters that change the content below without navigating, where every option should stay visible.

## When not to use

- Switching between panels of content: use tabs-indicator (role tablist with panels).
- An on/off setting: use switch.
- More than about five options or long labels: use select.

## Pick by what matters

| Need | Use |
| --- | --- |
| Pricing period toggle | size="lg" with two options |
| Form field that fills its row | fullWidth |
| Compact toolbar view switcher | size="sm" with icon-only options and ariaLabel |
| Options with icons and text | icon={MapPin} label="In person" |

## Usage

```tsx
import { MapPin, Phone, Video } from "lucide-react"
import { SegmentedControl } from "@/components/goodui/segmented-control"

type AppointmentType = "in-person" | "video" | "phone"

export function AppointmentTypePicker({ value, onChange }: { value: AppointmentType; onChange: (v: AppointmentType) => void }) {
  return (
    <SegmentedControl
      aria-label="Appointment type"
      fullWidth
      value={value}
      onValueChange={(v) => onChange(v as AppointmentType)}
      options={[
        { value: "in-person", label: "In person", icon: MapPin },
        { value: "video", label: "Video", icon: Video },
        { value: "phone", label: "Phone", icon: Phone },
      ]}
    />
  )
}
```

### Billing period with a rolling price

```tsx
const [period, setPeriod] = React.useState("monthly")

<SegmentedControl
  aria-label="Billing period"
  size="lg"
  value={period}
  onValueChange={setPeriod}
  options={[
    { value: "monthly", label: "Monthly" },
    { value: "yearly", label: "Yearly (−20%)" },
  ]}
/>
<NumberFlow value={period === "yearly" ? 23 : 29} prefix="$" className="text-4xl font-semibold" />
```

### Icon-only view switcher

```tsx
<SegmentedControl
  aria-label="Layout"
  size="sm"
  defaultValue="list"
  options={[
    { value: "list", icon: List, ariaLabel: "List view" },
    { value: "grid", icon: LayoutGrid, ariaLabel: "Grid view" },
    { value: "map", icon: MapIcon, ariaLabel: "Map view" },
  ]}
/>
```

## API

### SegmentedControl

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| options (required) | `SegmentedControlOption[]` | — |  |
| value | `string` | — | Selected option value (controlled). |
| defaultValue | `string` | — | Initially selected option when uncontrolled; defaults to the first enabled option. |
| onValueChange | `(value: string) => void` | — | Called with the new value on click or arrow-key selection. |
| size | `"sm" \| "md" \| "lg"` | `"md"` | Height: sm 32px, md 36px, lg 44px. |
| fullWidth | `boolean` | `false` | Stretch to the container width with equal segments. |
| disabled | `boolean` | `false` | Disables the whole control. |

Also accepts every <div> attribute.

## Keyboard

| Keys | Action |
| --- | --- |
| Tab | Focuses the selected segment (one tab stop for the whole control). |
| ArrowRight / ArrowDown | Selects and focuses the next enabled segment, wrapping around. |
| ArrowLeft / ArrowUp | Selects and focuses the previous enabled segment, wrapping around. |
| Home / End | Selects the first or last enabled segment. |
| Enter / Space | Selects the focused segment (native <button>). |

## Accessibility

- The root is role="radiogroup" and each segment is a <button role="radio"> with aria-checked, using a roving tabindex.
- Give the group a name with aria-label (it is passed to the root). Icon-only options need ariaLabel.
- disabled on the root sets aria-disabled and disables every segment; disabled on an option skips it in keyboard navigation.

## Motion

- The thumb is one shared-layout element that slides to the selected segment on a spring (stiffness 500, damping 32, mass 0.9).
- While pressed, the thumb squeezes to 0.95 scale, and an unselected segment's label to 0.96.
- Hairline dividers between unselected neighbours fade out in 200 ms next to the thumb, like iOS.
- Reduced motion: no squeeze, and the thumb jumps to the new segment.

## Notes for AI

- options is an array of { value, label?, icon?, ariaLabel?, disabled? }; icon takes the component (icon: MapPin), not an element (<MapPin />).
- onValueChange gives a string; cast it to your union type if you need to.
- Always pass aria-label on the control; there is no visible group label built in.
- Use it for options that apply immediately; for panels of content use tabs-indicator.
- Arrow keys select immediately (they do not just move focus), like native radio buttons.

## FAQ

**Segmented control or tabs?**

A segmented control changes a setting or filter in place (radiogroup). Tabs switch between panels of content (tablist + tabpanel). Screen readers announce them differently.

**Can it be uncontrolled?**

Yes. Pass defaultValue (or nothing, then the first enabled option is selected) and read changes in onValueChange.

## Related

- tabs-indicator: https://goodui.dev/components/navigation/tabs-indicator
- tabs: https://goodui.dev/components/core/tabs
- switch: https://goodui.dev/components/core/switch
- select: https://goodui.dev/components/core/select

Last updated: 2026-11-02

---

# Stepper

> Horizontal or vertical stepper where the connecting line fills between steps, numbers morph into drawn checkmarks, a current-step ring glides to the active step, errors shake, and completed steps are clickable.

Animated stepper for React and shadcn: horizontal or vertical steps with progress line and checkmarks

Page: https://goodui.dev/components/navigation/stepper

## Install

```bash
npx shadcn@latest add @goodui/stepper
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/stepper.json`. The file lands in `components/goodui/stepper.tsx`.

## When to use

- Multi-step forms and checkouts: Service → Staff → Time → Confirm.
- Onboarding checklists in a vertical layout, with each step's form or action opening under it.
- Showing where the user is in a process and letting them jump back to finished steps.

## When not to use

- Background work the user only watches: use multi-step-loader.
- Switching between independent views: use tabs-indicator.
- Plain completion percentage without named steps: use progress (variant="steps").

## Pick by what matters

| Need | Use |
| --- | --- |
| Wizard header above a form | orientation="horizontal" (default) |
| Checklist with inline actions | orientation="vertical" with content on steps |
| Allow going back only | clickable="completed" (default) |
| Free navigation between steps | clickable="all" |
| Read-only progress display | clickable="none" |
| Flag a failed step | error: true on that step |

## Usage

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

const steps = [
  { title: "Service", description: "Balayage + gloss" },
  { title: "Stylist", description: "Priya" },
  { title: "Time", description: "Thu 2:30 PM" },
  { title: "Confirm" },
]

export function BookingWizard({ step, setStep }: { step: number; setStep: (n: number) => void }) {
  return (
    <div className="flex flex-col gap-6">
      <Stepper steps={steps} value={step} onValueChange={setStep} aria-label="Booking progress" />
      <div className="flex justify-between">
        <Button variant="outline" disabled={step === 0} onClick={() => setStep(step - 1)}>
          Back
        </Button>
        <Button onClick={() => setStep(Math.min(steps.length, step + 1))}>
          {step === steps.length - 1 ? "Book" : "Continue"}
        </Button>
      </div>
    </div>
  )
}
```

### Vertical setup checklist with inline actions

```tsx
<Stepper
  orientation="vertical"
  value={step}
  onValueChange={setStep}
  aria-label="Setup checklist"
  steps={[
    { title: "Connect your calendar", description: "Google Calendar", content: <Button size="sm" onClick={next}>Connect</Button> },
    { title: "Add your services", description: "3 services, 30–120 min", content: <Button size="sm" onClick={next}>Save services</Button> },
    { title: "Share your link", description: "book.studio.co/lena", content: <Button size="sm" onClick={next}>Copy link</Button> },
  ]}
/>
```

### Payment step failed

```tsx
<Stepper
  value={2}
  clickable="none"
  aria-label="Checkout"
  steps={[{ title: "Cart" }, { title: "Details" }, { title: "Payment", error: paymentFailed }, { title: "Done" }]}
/>
```

## API

### Stepper

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| steps (required) | `StepperStep[]` | — | The steps, in order. |
| value | `number` | — | Index of the current step. Use `steps.length` to show every step as complete. |
| defaultValue | `number` | `0` | Starting step when uncontrolled. |
| onValueChange | `(index: number) => void` | — | Called with the step index when a clickable step is clicked. |
| orientation | `"horizontal" \| "vertical"` | `"horizontal"` | horizontal: steps in a row with titles under the circles. vertical: a column that can open content under the current step. |
| clickable | `"completed" \| "all" \| "none"` | `"completed"` | Which steps can be clicked to jump to them. |
| labels | `Partial<StepperLabels>` | — | Text for built-in controls and screen readers; pass translations here. |

Also accepts every <ol> attribute.

## Keyboard

| Keys | Action |
| --- | --- |
| Tab | Moves between clickable steps (they are native buttons); other steps are not focusable. |
| Enter / Space | Jumps to the focused clickable step. |

## Accessibility

- Renders an <ol> of <li> items; the current one has aria-current="step". Pass aria-label on the stepper to name it.
- Each title is followed by an sr-only status ("completed", "current step", "not started", "needs attention"), translatable through labels.
- Clickable steps are real <button>s with a focus-visible ring; non-clickable steps are plain elements, so they are not in the tab order.
- The error state is shown by a red circle, a "!" mark and red title text, plus the sr-only status.

## Motion

- The line between two steps fills when the earlier one completes (0.45 s, ease [0.32, 0.72, 0, 1]).
- A completed step's number swaps for a check that draws in 300 ms while the circle pops to 1.14x and back in 0.4 s; an error step shakes sideways for 0.4 s.
- A soft ring around the current step glides to the next one through a shared layout animation (spring 300 / 30). Circle colors cross-fade over 300 ms.
- Vertical content under the current step opens to its height (0.4 s, no bounce).
- Reduced motion: no pop or shake, the check and lines appear at once, and the ring and content jump.

## Notes for AI

- value is the 0-based index of the current step; value={steps.length} shows every step complete.
- The stepper does not render Next/Back buttons or validate anything; keep the index in your state and change it from your own buttons.
- onValueChange only fires when a clickable step is clicked, not when you change value yourself.
- content only renders in the vertical orientation, under the current step.
- error overrides the status of that step wherever it is; clear it once the problem is fixed.

## FAQ

**Can users skip ahead?**

Only with clickable="all". The default "completed" lets them go back to finished steps but not forward.

**Does it work on mobile?**

The horizontal layout keeps every step in one row and hides descriptions below the sm breakpoint; for many steps or long titles use orientation="vertical".

## Related

- multi-step-loader: https://goodui.dev/components/feedback/multi-step-loader
- progress: https://goodui.dev/components/numbers/progress
- tabs-indicator: https://goodui.dev/components/navigation/tabs-indicator
- accordion-height: https://goodui.dev/components/lists/accordion-height

Last updated: 2026-11-02

---

# Dock

> macOS-style dock whose tiles magnify on a spring as the pointer nears, with tooltips, running dots, badges and a launch bounce, falling back to a simple press scale on touch.

macOS dock for React and shadcn: magnifying icon bar with tooltips, badges and launch bounce

Page: https://goodui.dev/components/navigation/dock

## Install

```bash
npx shadcn@latest add @goodui/dock
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/dock.json`. The file lands in `components/goodui/dock.tsx`.

## When to use

- A floating app switcher or quick-action bar in a dashboard (Dashboard, Calendar, Clients, Messages…).
- Portfolio or marketing pages that want a playful, recognisable navigation bar.
- Icon-only toolbars where tooltips and an "open" dot help people learn what each tile does.

## When not to use

- Primary navigation on phones: use bottom-nav; magnification needs a mouse and falls back to a press scale on touch.
- Toolbars with many text actions: use a plain button row; the dock only shows icons.
- Switching views inside one card: use tabs-indicator or segmented-control.

## Pick by what matters

| Need | Use |
| --- | --- |
| Classic macOS feel | defaults (size 44, magnification 68, distance 140) |
| Subtle growth | magnification close to size, e.g. size={40} magnification={54} |
| No magnification at all | magnification={size} |
| Group tiles | { id, separator: true } between items |
| Brand-colored tile | tileClassName="bg-gradient-to-br from-sky-400 to-blue-600 text-white" |

## Usage

```tsx
import { CalendarDays, LayoutDashboard, MessageSquare, Receipt, Settings, Users } from "lucide-react"
import { Dock } from "@/components/goodui/dock"

export function AppDock({ open, unread, onOpen }: { open: string; unread: number; onOpen: (id: string) => void }) {
  return (
    <Dock
      aria-label="Apps"
      items={[
        { id: "dashboard", label: "Dashboard", icon: LayoutDashboard, active: open === "dashboard", onClick: () => onOpen("dashboard") },
        { id: "calendar", label: "Calendar", icon: CalendarDays, active: open === "calendar", onClick: () => onOpen("calendar") },
        { id: "clients", label: "Clients", icon: Users, active: open === "clients", onClick: () => onOpen("clients") },
        { id: "messages", label: "Messages", icon: MessageSquare, badge: unread, onClick: () => onOpen("messages") },
        { id: "sep", separator: true },
        { id: "invoices", label: "Invoices", icon: Receipt, onClick: () => onOpen("invoices") },
        { id: "settings", label: "Settings", icon: Settings, onClick: () => onOpen("settings") },
      ]}
    />
  )
}
```

### Smaller dock without the launch bounce

```tsx
<Dock aria-label="Quick actions" size={36} magnification={52} distance={110} bounce={false} items={items} />
```

## API

### Dock

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| items (required) | `DockItem[]` | — | Tiles from left to right; { id, separator: true } draws a divider between groups. |
| size | `number` | `44` | Resting tile size in px. |
| magnification | `number` | `68` | Tile size in px right under the pointer. |
| distance | `number` | `140` | Pointer distance in px over which neighbours grow. |
| bounce | `boolean` | `true` | Bounce the icon when clicked, like an app launching. |
| labels | `Partial<DockLabels>` | — | Text for built-in controls and screen readers; pass translations here. |

Also accepts every <div> attribute.

## Keyboard

| Keys | Action |
| --- | --- |
| Tab | Focuses the dock (one tab stop) and shows that tile's tooltip. |
| ArrowRight / ArrowLeft | Moves focus to the next or previous tile, wrapping around; separators are skipped. Mirrored under dir="rtl". |
| Home / End | Moves focus to the first or last tile. |
| Enter / Space | Activates the focused tile (native <button>). |

## Accessibility

- The root is role="toolbar" with a roving tabindex; pass aria-label to name it. Separators are role="separator".
- Each tile is a <button> whose accessible name is label (read from sr-only text, so the visible count is part of it); its tooltip (role="tooltip") is linked through aria-describedby while shown, on hover or focus.
- active sets aria-current="page" and shows the dot under the tile.
- The badge count is part of the accessible name: "Messages, 3 new". Translate the suffix with labels.badge.

## Motion

- Tiles within distance of the mouse grow toward magnification with a cosine falloff, smoothed by a spring (stiffness 170, damping 14, mass 0.1). Only mouse pointers magnify.
- Clicking bounces the icon up 14px, then 5px, over 0.6 s (bounce). Tiles shrink to 0.9 while pressed.
- Tooltips spring up 6px into place (stiffness 500, damping 30); badges pop from scale 0 (stiffness 600, damping 22); the running dot scales in over 300 ms.
- On touch screens (hover: none) there is no magnification; tiles press to 0.9 and still bounce on tap.
- Reduced motion: no magnification, hover lift, press scale or bounce; tooltips and badges appear instantly.

## Performance

- Magnification runs on motion values, so pointer moves do not re-render React; each tile measures itself with getBoundingClientRect on pointer move.

## Notes for AI

- items is one array: { id, label, icon, onClick?, active?, badge?, tileClassName? } or { id, separator: true }. Every id must be unique.
- icon takes the component (icon: Users), not an element.
- active means "running/open" (dot + aria-current), not hovered; set it from your router or state.
- The dock has a fixed height of size + 20px and tiles grow upward; leave room above it for magnified tiles and tooltips.
- badge is a number (99+ above 99); 0 or undefined hides it. Don't repeat the count in label: screen readers already hear "Messages, 3 new".
- labels={{ badge: (n) => `${n} nuevos` }} translates the screen-reader count suffix.

## FAQ

**What happens on phones?**

Magnification is turned off when the device reports hover: none; tiles keep tooltips on focus, the press scale and the launch bounce.

**Can I put it at the bottom of the screen?**

Yes. Wrap it in a fixed container (e.g. fixed inset-x-0 bottom-4) — the dock itself is centered with mx-auto and sized to its content.

## Related

- bottom-nav: https://goodui.dev/components/navigation/bottom-nav
- notification-badge: https://goodui.dev/components/feedback/notification-badge
- tooltip-animated: https://goodui.dev/components/overlays/tooltip-animated
- magnetic-button: https://goodui.dev/components/buttons/magnetic-button

Last updated: 2026-11-02

---

# Bottom navigation

> Mobile bottom bar where a pill glides to the selected tab and its icon bounces, in a labelled or expanding variant, with popping badges and an optional raised center action.

Animated mobile bottom navigation bar for React and shadcn with badges and a center action

Page: https://goodui.dev/components/navigation/bottom-nav

## Install

```bash
npx shadcn@latest add @goodui/bottom-nav
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/bottom-nav.json`. The file lands in `components/goodui/bottom-nav.tsx`.

## When to use

- Primary navigation in a mobile web app or PWA with 3–5 top-level sections (Today, Calendar, Clients, Inbox).
- When one action deserves a raised button in the middle of the bar, such as "New booking".
- Showing unread counts or a "new" dot on sections without opening them.

## When not to use

- Desktop layouts: use a sidebar or top navigation; a bottom bar wastes space on wide screens.
- Switching views inside a page or card: use tabs-indicator or segmented-control.
- More than five destinations: move the rest into a "More" screen or a menu.

## Pick by what matters

| Need | Use |
| --- | --- |
| Labels always visible (most apps) | variant="pill" (default) |
| Compact bar, label only on the active tab | variant="expand" |
| One primary create action | centerAction={{ label, icon, onClick }} |
| Unread count | badge: 3 on the item (99+ above 99) |
| Something new, no count | badge: true |

## Usage

```tsx
import { CalendarDays, Home, Inbox, Plus, Users } from "lucide-react"
import { BottomNav } from "@/components/goodui/bottom-nav"

export function AppTabBar({ tab, onTab, unread, onNewBooking }: { tab: string; onTab: (v: string) => void; unread: number; onNewBooking: () => void }) {
  return (
    <BottomNav
      aria-label="Salon app"
      className="fixed inset-x-0 bottom-0 z-40"
      value={tab}
      onValueChange={onTab}
      items={[
        { value: "today", label: "Today", icon: Home },
        { value: "calendar", label: "Calendar", icon: CalendarDays },
        { value: "clients", label: "Clients", icon: Users },
        { value: "inbox", label: "Inbox", icon: Inbox, badge: unread },
      ]}
      centerAction={{ label: "New booking", icon: Plus, onClick: onNewBooking }}
    />
  )
}
```

### Expanding variant driven by the router

```tsx
const pathname = usePathname()
const router = useRouter()

<BottomNav
  variant="expand"
  value={pathname.split("/")[1] || "today"}
  onValueChange={(v) => router.push(`/${v}`)}
  items={items}
/>
```

## API

### BottomNav

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| items (required) | `BottomNavItem[]` | — | The tabs, left to right. With centerAction, the first half goes before it. |
| value | `string` | — | Selected tab value (controlled), e.g. derived from the current route. |
| defaultValue | `string` | — | Initially selected tab when uncontrolled; defaults to the first item. |
| onValueChange | `(value: string) => void` | — | Called with the tab's value when it is tapped. |
| variant | `"pill" \| "expand"` | `"pill"` | `pill`: pill behind the icon with labels always shown. `expand`: the active tab grows to show its label. |
| centerAction | `{ label: string; icon: React.ComponentType<{ className?: string }>; onClick?: () => void }` | — | Raised round button in the middle of the bar, e.g. "New booking". |
| labels | `Partial<BottomNavLabels>` | — | Text for built-in controls and screen readers; pass translations here. |

Also accepts every <nav> attribute.

## Keyboard

| Keys | Action |
| --- | --- |
| Tab | Moves through the tabs and the center action (every button is a tab stop). |
| ArrowRight / ArrowLeft | Moves focus to the next or previous tab, wrapping around; it does not select it. Mirrored under dir="rtl". |
| Home / End | Moves focus to the first or last tab. |
| Enter / Space | Selects the focused tab or runs the center action (native <button>). |

## Accessibility

- Renders a <nav> labelled by aria-label (default "Main"); the selected tab has aria-current="page".
- Each tab's accessible name is its visible label followed by sr-only ", 3 new" or ", new" when it has a badge (translate with labels.badgeCount / labels.badgeDot); the badge bubble itself is aria-hidden.
- The center action is a <button> named by centerAction.label.
- The bar adds bottom padding for env(safe-area-inset-bottom), so it clears the iPhone home indicator.

## Motion

- A tinted pill glides to the selected tab through a shared layout animation (spring 480 / 36, mass 0.9), and the chosen icon hops up 5px while scaling to 1.18 and back in 0.45 s.
- Expand variant: tabs resize with layout animation on the same spring and the active label fades in from 4px aside after 60 ms.
- Badges pop in from 0.3 scale on a spring (stiffness 600, damping 20) and pop again when the count changes.
- The center action lifts 2px on hover, presses to 0.9 and its icon turns 90° on hover (300 ms).
- Reduced motion: the pill and tabs move instantly, no hop, no badge pop, no lift, press or icon turn.

## Notes for AI

- The component is not fixed-positioned; add className="fixed inset-x-0 bottom-0 z-40" (and bottom padding on your page) yourself.
- Keep items to 3–5. With centerAction, the first Math.ceil(n / 2) items go left of it, so use an even count for a balanced bar.
- icon takes the component (icon: Home), not an element.
- For route-based navigation, derive value from the pathname and navigate in onValueChange; the tabs are buttons, not links.
- badge accepts a number or true; 0, false or undefined hides it.
- labels={{ badgeCount: (n) => `, ${n} nuevos`, badgeDot: ", nuevo" }} translates the screen-reader badge text.

## FAQ

**Are the tabs links?**

No, they are buttons that call onValueChange. Navigate with your router there, and set value from the current route so the pill follows back/forward navigation.

**Does the pill jump between two bars on the same page?**

No. Each bar has its own LayoutGroup and layoutId from useId.

## Related

- dock: https://goodui.dev/components/navigation/dock
- tabs-indicator: https://goodui.dev/components/navigation/tabs-indicator
- notification-badge: https://goodui.dev/components/feedback/notification-badge
- segmented-control: https://goodui.dev/components/navigation/segmented-control

Last updated: 2026-11-02

---

# Command palette morph

> A search field morphs into a command palette through a shared layout animation, with fuzzy matching, highlighted letters, grouped results, a sliding selection, arrow keys, Enter, Esc and Ctrl/Cmd+K.

Command palette (Cmd+K) for React and shadcn: search field that morphs into a fuzzy command menu

Page: https://goodui.dev/components/navigation/command-palette-morph

## Install

```bash
npx shadcn@latest add @goodui/command-palette-morph
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/command-palette-morph.json`. The file lands in `components/goodui/command-palette-morph.tsx`.

## When to use

- A global Cmd/Ctrl+K search in a dashboard: jump to pages, find clients, run actions like "New booking".
- A header search field that should open into something bigger without a jarring modal pop.
- Power-user shortcuts, with each command's keys shown next to it.

## When not to use

- Searching one list inline on a page: use search-expand or a plain input with filtering.
- Choosing a value for a form field: use select.
- A short menu of actions on a button: use dropdown-stagger.

## Pick by what matters

| Need | Use |
| --- | --- |
| Search field in the header | variant="field" (default) with triggerLabel |
| Compact icon in a toolbar or on mobile | variant="icon" (triggerLabel becomes its aria-label) |
| Second palette on the same page | hotkey={false} on all but one |
| Find records by email or number | keywords: ["maya@studio.co"] on the item |
| Open it from elsewhere | open + onOpenChange (controlled) |

## Usage

```tsx
import { CalendarDays, CalendarPlus, Receipt, UserPlus, UserRound, Users } from "lucide-react"
import { useRouter } from "next/navigation"
import { CommandPaletteMorph, type CommandPaletteItem } from "@/components/goodui/command-palette-morph"

export function AppSearch() {
  const router = useRouter()
  const items: CommandPaletteItem[] = [
    { id: "new-booking", label: "New booking", group: "Actions", icon: CalendarPlus, shortcut: ["N"], onSelect: () => router.push("/bookings/new") },
    { id: "add-client", label: "Add client", group: "Actions", icon: UserPlus, onSelect: () => router.push("/clients/new") },
    { id: "go-calendar", label: "Calendar", group: "Pages", icon: CalendarDays, shortcut: ["G", "C"], onSelect: () => router.push("/calendar") },
    { id: "go-clients", label: "Clients", group: "Pages", icon: Users, onSelect: () => router.push("/clients") },
    { id: "inv-2041", label: "INV-2041", group: "Invoices", icon: Receipt, hint: "Overdue · $240", onSelect: () => router.push("/invoices/2041") },
    { id: "c-maya", label: "Maya Chen", group: "Clients", icon: UserRound, hint: "12 visits", keywords: ["maya@studio.co"], onSelect: () => router.push("/clients/maya") },
  ]
  return <CommandPaletteMorph items={items} triggerLabel="Search clients, invoices…" />
}
```

### Icon trigger without the hotkey

```tsx
<CommandPaletteMorph items={items} variant="icon" hotkey={false} triggerLabel="Quick search" />
```

### One handler for every item, translated

```tsx
<CommandPaletteMorph
  items={items}
  onSelect={(item) => track("command", item.id)}
  placeholder="Suchen oder Befehl eingeben…"
  triggerLabel="Suchen…"
  emptyMessage="Keine Treffer"
  labels={{ dialog: "Befehlspalette", results: "Ergebnisse", navigate: "navigieren", select: "auswählen", resultCount: (n) => `${n} Ergebnisse` }}
/>
```

## API

### CommandPaletteMorph

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| items (required) | `CommandPaletteItem[]` | — | Everything the palette can find; items are listed in this order (grouped by group) until the user types. |
| open | `boolean` | — | Whether the palette is open (controlled). |
| defaultOpen | `boolean` | `false` | Initial open state when uncontrolled. |
| onOpenChange | `(open: boolean) => void` | — | Called when the palette opens or closes (trigger, hotkey, Esc, backdrop or a selection). |
| onSelect | `(item: CommandPaletteItem) => void` | — | Called with the chosen item, after the item's own onSelect. |
| placeholder | `string` | `"Search or type a command…"` | Placeholder of the search input inside the palette. |
| triggerLabel | `string` | `"Search…"` | Text on the field trigger. |
| variant | `"field" \| "icon"` | `"field"` | `field` looks like a search input; `icon` is a round icon button. |
| hotkey | `boolean` | `true` | Open and close with Ctrl+K / Cmd+K. Enable it on one palette per page. |
| emptyMessage | `React.ReactNode` | — | Shown when nothing matches; defaults to "No results" with the query. |
| labels | `Partial<CommandPaletteMorphLabels>` | — | Text for built-in controls and screen readers; pass translations here. |

Also accepts every <button> attribute.

## Keyboard

| Keys | Action |
| --- | --- |
| Ctrl+K / Cmd+K | Opens or closes the palette from anywhere on the page (when hotkey is on). |
| ArrowDown / ArrowUp | Moves the highlighted result, wrapping around, and scrolls it into view. |
| Enter | Runs the highlighted result and closes the palette. |
| Escape | Closes the palette and returns focus to the trigger. |
| Tab | Kept inside the palette: focus stays on the search input. |

## Accessibility

- The trigger is a <button> with aria-haspopup="dialog" and aria-expanded; the open palette is role="dialog" with aria-modal and an aria-label from labels.dialog.
- The input is a role="combobox" controlling a role="listbox"; the highlighted option is exposed through aria-activedescendant and aria-selected, and results sit in role="group" sections under their headings.
- A polite live region announces the result count (labels.resultCount) as the user types.
- Opening locks page scroll and focuses the input; closing restores scroll and focus.
- Built-in strings go through labels, including the default empty state (labels.noResults, labels.noMatch(query)); emptyMessage replaces it entirely.

## Motion

- The trigger's border box and search icon are shared-layout elements that morph into the palette panel and its icon on a spring (stiffness 380, damping 34, mass 0.9), and back on close.
- The backdrop fades in 200 ms; the input fades in after 80 ms and the results slide down 4px and fade in after 100 ms. Exits are 80 ms fades.
- The selection highlight glides between results on a stiff spring (stiffness 600, damping 42).
- Reduced motion: the panel, icon, backdrop, contents and highlight change instantly.

## Performance

- Filtering is a small in-memory fuzzy scorer over label and keywords, memoised per query. It is meant for hundreds of items, not a remote search; for server results, update items as the user types.

## Notes for AI

- Put navigation and actions in each item's onSelect; onSelect on the component runs after it for every item (analytics, logging).
- group is a plain string heading; items keep their order within a group until a query sorts them by score.
- Only one palette per page should keep hotkey on; pass hotkey={false} on the others.
- It renders position: fixed without a portal; do not place it inside an element with transform, filter or backdrop-filter, or the overlay will be clipped to it.
- shortcut is display only; wire real hotkeys yourself (for example with the kbd component's onTrigger).

## FAQ

**How does matching work?**

A substring match in the label scores highest (more at a word start); otherwise the letters must appear in order, with bonuses for consecutive letters and word starts. Keyword matches rank slightly lower and are not highlighted.

**Is it a drop-in for cmdk?**

No. It is a single component fed by an items array, not composable Command.* parts. That keeps it to one file, at the cost of custom item layouts.

## Related

- search-expand: https://goodui.dev/components/inputs/search-expand
- dropdown-stagger: https://goodui.dev/components/overlays/dropdown-stagger
- kbd: https://goodui.dev/components/core/kbd
- select: https://goodui.dev/components/core/select

Last updated: 2026-11-02

---

# Morphing dialog

> A service card expands into a booking dialog, with its image, title and price flying into place through a shared-layout spring, then folds back into the card on Esc or backdrop click.

Morphing dialog for React and shadcn: a card that expands into a modal

Page: https://goodui.dev/components/overlays/morphing-dialog

## Install

```bash
npx shadcn@latest add @goodui/morphing-dialog
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/morphing-dialog.json`. The file lands in `components/goodui/morphing-dialog.tsx`.

## When to use

- A grid of cards (services, plans, products, team members) where opening one should show its details without losing the user's place.
- Detail views that reuse the card's own image, title and price, so the move from card to dialog explains itself.
- Booking or checkout steps that start from a card: pick a time, confirm, close back into the card.

## When not to use

- Confirmations and plain forms opened from a button: a regular shadcn Dialog is clearer; there is no card to morph from.
- Long forms or lists on phones: use drawer-spring, which gives a bottom sheet with snap points.
- A small form tied to one button (add a note, apply a code): use popover-morph, which stays non-modal.

## Pick by what matters

| Need | Use |
| --- | --- |
| A card opens into a full detail dialog | morphing-dialog |
| A card grows in place, inside the page flow | expandable-card |
| A button opens a small floating form | popover-morph |
| Mobile-first sheet with half and full heights | drawer-spring |

## Usage

```tsx
import * as React from "react"
import { CalendarCheck } from "lucide-react"
import { Button } from "@/components/ui/button"
import {
  MorphingDialog,
  MorphingDialogClose,
  MorphingDialogContainer,
  MorphingDialogContent,
  MorphingDialogDescription,
  MorphingDialogMedia,
  MorphingDialogSubtitle,
  MorphingDialogTitle,
  MorphingDialogTrigger,
} from "@/components/goodui/morphing-dialog"

export function ServiceCard() {
  const [open, setOpen] = React.useState(false)

  return (
    <MorphingDialog open={open} onOpenChange={setOpen}>
      <MorphingDialogTrigger className="max-w-xs shadow-xs hover:shadow-md">
        <MorphingDialogMedia className="h-24 bg-gradient-to-br from-amber-300 to-rose-400" />
        <span className="block p-4">
          <MorphingDialogTitle>Balayage and gloss</MorphingDialogTitle>
          <MorphingDialogSubtitle>2 h 30 min · $185</MorphingDialogSubtitle>
        </span>
      </MorphingDialogTrigger>

      <MorphingDialogContainer>
        <MorphingDialogContent>
          <MorphingDialogClose />
          <MorphingDialogMedia className="h-40 shrink-0 bg-gradient-to-br from-amber-300 to-rose-400" />
          <div className="overflow-y-auto p-6">
            <MorphingDialogTitle>Balayage and gloss</MorphingDialogTitle>
            <MorphingDialogSubtitle>2 h 30 min · $185</MorphingDialogSubtitle>
            <MorphingDialogDescription className="mt-4 space-y-4">
              <p className="text-sm text-muted-foreground">
                Hand-painted highlights finished with a toning gloss and blow-dry. Includes a 10 minute consultation.
              </p>
              <Button className="w-full" onClick={() => setOpen(false)}>
                <CalendarCheck /> Book Tue 10:00 AM
              </Button>
            </MorphingDialogDescription>
          </div>
        </MorphingDialogContent>
      </MorphingDialogContainer>
    </MorphingDialog>
  )
}
```

### Focus a specific control when it opens

```tsx
<MorphingDialogDescription>
  <input data-autofocus placeholder="Promo code" className="h-9 w-full rounded-md border px-3" />
</MorphingDialogDescription>
```

### Slower, bouncier morph and a translated close button

```tsx
<MorphingDialog transition={{ type: "spring", bounce: 0.25, duration: 0.6 }}>
  {/* MorphingDialogTrigger as above */}
  <MorphingDialogContainer>
    <MorphingDialogContent>
      <MorphingDialogClose labels={{ close: "Schließen" }} />
      {/* media, title, subtitle, description */}
    </MorphingDialogContent>
  </MorphingDialogContainer>
</MorphingDialog>
```

## API

### MorphingDialog

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| children (required) | `React.ReactNode` | — | Content. |
| open | `boolean` | — | Controlled open state. Pair with onOpenChange. |
| defaultOpen | `boolean` | `false` | Initial open state when uncontrolled. |
| onOpenChange | `(open: boolean) => void` | — | Called with the next state when the trigger, Esc, the backdrop or a close control opens or closes it. |
| transition | `Transition` | — | Transition for the shared-layout morph. Reduced motion always snaps. |

### MorphingDialogTrigger

Also accepts every <motion.button> attribute.

### MorphingDialogContainer

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| children (required) | `React.ReactNode` | — | Content. |
| className | `string` | — | Classes for the fixed layer that centers the dialog (padding, alignment). |
| backdropClassName | `string` | — | Classes for the backdrop. |

### MorphingDialogContent

Also accepts every <motion.div> attribute.

### MorphingDialogMedia

Also accepts every <motion.div> attribute.

### MorphingDialogTitle

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| children (required) | `React.ReactNode` | — | Content. |
| className | `string` | — | Classes merged onto the root element. |

### MorphingDialogSubtitle

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| children (required) | `React.ReactNode` | — | Content. |
| className | `string` | — | Classes merged onto the root element. |

### MorphingDialogDescription

Also accepts every <motion.div> attribute.

### MorphingDialogClose

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| labels | `Partial<MorphingDialogLabels>` | — | Text for built-in controls and screen readers; pass translations here. |

Also accepts every <button> attribute.

## Keyboard

| Keys | Action |
| --- | --- |
| Enter / Space | On the card (a native <button>): opens the dialog. |
| Esc | Closes the dialog; focus returns to the card. |
| Tab / Shift+Tab | Cycles through the focusable elements inside the dialog; focus cannot leave it while open. |

## Accessibility

- The trigger is a real <button> with aria-haspopup="dialog" and aria-expanded.
- The content has role="dialog" and aria-modal="true"; MorphingDialogTitle becomes its accessible name and MorphingDialogDescription its description.
- On open, focus moves to the first [data-autofocus] element, else the first focusable element, else the dialog itself. On close, focus goes back to the card.
- Page scroll is locked while the dialog is open.
- MorphingDialogClose without children gets aria-label from labels.close (default "Close").

## Motion

- The card's surface, MorphingDialogMedia, MorphingDialogTitle and MorphingDialogSubtitle share layoutIds, so each flies from its place in the card to its place in the dialog on a spring (bounce 0.12, 0.42 s). Override it with the transition prop.
- The backdrop fades in and out over 200 ms. MorphingDialogDescription fades up 10px after an 80 ms delay (250 ms) and fades out in 80 ms on close.
- The card stays above its neighbours until it has flown back into place.
- Reduced motion: the morph snaps (duration 0) and the description appears without moving; only the backdrop still fades.

## Notes for AI

- Put the same MorphingDialogMedia, MorphingDialogTitle and MorphingDialogSubtitle in both the trigger and the content; parts that only exist on one side do not morph.
- The trigger is a <button>: lay out its text with <span> elements (as the dialog parts do) and never nest another button or a link in it.
- Set corner radius with style={{ borderRadius }} on the trigger or content, not a rounded-* class, or the corners distort during the morph.
- The dialog is position: fixed without a portal. Do not render it inside an element with transform or filter.
- Always include MorphingDialogTitle in the content (it names the dialog) and MorphingDialogDescription for the detail body (aria-describedby points to it only while it is rendered).

## FAQ

**Can I have many cards on one page?**

Yes. Wrap each card in its own MorphingDialog; layout ids are scoped per instance with useId.

**How do I close it after an action?**

Control it with open and onOpenChange and set open to false in your handler, or render MorphingDialogClose with your own children.

## Related

- expandable-card: https://goodui.dev/components/cards/expandable-card
- drawer-spring: https://goodui.dev/components/overlays/drawer-spring
- popover-morph: https://goodui.dev/components/overlays/popover-morph
- card: https://goodui.dev/components/core/card

Last updated: 2026-11-02

---

# Spring drawer

> A bottom sheet with half and full snap points plus side drawers on a spring; drag the handle and the release speed picks the snap point or closes it, while the backdrop fades with the drag.

Draggable bottom sheet and side drawer for React and shadcn with spring snap points

Page: https://goodui.dev/components/overlays/drawer-spring

## Install

```bash
npx shadcn@latest add @goodui/drawer-spring
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/drawer-spring.json`. The file lands in `components/goodui/drawer-spring.tsx`.

## When to use

- Detail panels on mobile, such as a booking or an order, that open at half height and drag up to full height.
- Side forms that keep the page visible behind them: a new client, an invoice line, filters.
- A left navigation drawer for small screens.

## When not to use

- A short confirmation or a single question: a centered dialog is faster to read; use morphing-dialog when it starts from a card.
- A small form tied to one button: use popover-morph, which is non-modal and stays next to its trigger.
- A list of actions on an item: use dropdown-stagger.

## Pick by what matters

| Need | Use |
| --- | --- |
| Mobile detail view that can grow | side="bottom" snapPoints={[0.5, 1]} |
| Sheet that fits its content | side="bottom" with no snapPoints (max 88dvh) |
| Form or editor next to the page | side="right" with footer for the actions |
| App navigation on small screens | side="left" |
| Must not close by accident (unsaved work) | dismissible={false}: no Esc, close button, backdrop close or drag-to-close |

## Usage

```tsx
import * as React from "react"
import { CalendarClock, XCircle } from "lucide-react"
import { Button } from "@/components/ui/button"
import { DrawerSpring } from "@/components/goodui/drawer-spring"

export function BookingSheet() {
  const [open, setOpen] = React.useState(false)
  const [snap, setSnap] = React.useState(0)

  return (
    <>
      <Button onClick={() => setOpen(true)}>
        <CalendarClock /> Booking details
      </Button>
      <DrawerSpring
        open={open}
        onOpenChange={setOpen}
        snapPoints={[0.55, 1]}
        onSnapChange={setSnap}
        title="Sofia Martinez"
        description={`Balayage and gloss · Tue 14 Nov, 2:30 PM · ${snap === 1 ? "full" : "half"} height`}
        footer={
          <div className="flex gap-2">
            <Button variant="outline" className="flex-1" onClick={() => setOpen(false)}>
              <XCircle /> Cancel booking
            </Button>
            <Button className="flex-1" onClick={() => setOpen(false)}>
              Check in
            </Button>
          </div>
        }
      >
        <ul className="space-y-3 text-sm">
          <li>2 h 30 min with Maya Chen</li>
          <li>Deposit paid: $40 of $185</li>
          <li>Note: prefers a cooler tone than last time.</li>
        </ul>
      </DrawerSpring>
    </>
  )
}
```

### Side form drawer with a footer submit

```tsx
<DrawerSpring
  side="right"
  open={open}
  onOpenChange={setOpen}
  title="New client"
  description="They get a welcome email with your booking link."
  footer={<Button type="submit" form="new-client" className="w-full">Save client</Button>}
>
  <form id="new-client" onSubmit={saveClient} className="space-y-3">
    <Input data-autofocus name="name" placeholder="Full name" />
    <Input name="email" type="email" placeholder="Email" />
  </form>
</DrawerSpring>
```

### Navigation drawer from the left

```tsx
<DrawerSpring side="left" open={nav} onOpenChange={setNav} title="Glow Studio" description="Hayes Valley">
  <nav className="flex flex-col gap-1">
    {["Calendar", "Clients", "Reports"].map((item) => (
      <button key={item} type="button" onClick={() => setNav(false)} className="rounded-lg px-3 py-2 text-start hover:bg-muted">
        {item}
      </button>
    ))}
  </nav>
</DrawerSpring>
```

## API

### DrawerSpring

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| title (required) | `React.ReactNode` | — | Heading of the drawer; it is also the dialog's accessible name. |
| open | `boolean` | — | Controlled open state. Pair with onOpenChange. |
| defaultOpen | `boolean` | `false` | Initial open state when uncontrolled. |
| onOpenChange | `(open: boolean) => void` | — | Called with false on Esc, the close button, a backdrop click or a drag past the lowest point. |
| side | `"bottom" \| "right" \| "left"` | `"bottom"` | "bottom" is a sheet with optional snap points; "right" and "left" are full-height side drawers. |
| snapPoints | `number[]` | — | Bottom sheet only: visible fractions of the sheet height, e.g. [0.5, 1] for half and full. |
| defaultSnap | `number` | `0` | Snap point index used when the sheet opens. |
| onSnapChange | `(index: number) => void` | — | Called with the index into the sorted snapPoints after a drag or a handle press moves the sheet. |
| description | `React.ReactNode` | — | Line under the title, linked to the dialog with aria-describedby. |
| footer | `React.ReactNode` | — | Sticky area under the scrolling body, for actions. |
| dismissible | `boolean` | `true` | When true (default), Esc, the close button, a backdrop click and dragging past the lowest point close the drawer. When false, none of them do and the close button is hidden: close it from your own controls (e.g. the footer). |
| className | `string` | — | Classes for the panel (width, height, radius). |
| bodyClassName | `string` | — | Classes for the scrolling body that wraps children. |
| children | `React.ReactNode` | — | Content. |
| labels | `Partial<DrawerSpringLabels>` | — | Text for built-in controls and screen readers; pass translations here. |

## Keyboard

| Keys | Action |
| --- | --- |
| Esc | Closes the drawer unless dismissible is false; focus returns to the element that had it before opening. |
| Tab / Shift+Tab | Cycles through focusable elements inside the drawer; focus cannot leave it while open. |
| Enter / Space | On the grab handle of a bottom sheet with two or more snapPoints: moves to the next snap point, wrapping back to the lowest. |

## Accessibility

- The panel has role="dialog" and aria-modal="true", named by title and described by description when you pass one.
- On open, focus goes to the first [data-autofocus] element, else the first focusable element after the grab handle (usually the close button). Add data-autofocus to a field if typing comes first.
- With snap points, the handle is a button labelled labels.expand or labels.collapse ("Expand sheet" / "Collapse sheet"); without them it is hidden from assistive tech and the tab order.
- The close button is labelled labels.close (default "Close") and is hidden when dismissible is false. Page scroll is locked while open.

## Motion

- Open, close and snap use a spring (stiffness 380, damping 38, mass 0.9) that starts with the release velocity of the drag; closing uses a stiffer spring (420 / 42).
- Dragging the header (handle, title, close row) moves the panel 1:1, with a rubber-band resistance past fully open. The body scrolls normally.
- On release the panel goes to the snap point nearest to where the throw would land (position + velocity × 0.2 s); a flick faster than 700 px/s always moves at least one step. With dismissible, closed is one of the targets.
- The backdrop opacity follows the panel between the lowest snap point and closed, so it fades while you drag down.
- Reduced motion: open, close and snap jump instantly (duration 0); dragging still follows the pointer.

## Performance

- Dragging updates a motion value, so the panel and backdrop move without React re-renders until release.

## Notes for AI

- title is required; it is the dialog's accessible name. Use description for one line of context.
- snapPoints only apply to side="bottom"; they are fractions of the sheet height (0 to 1) and are sorted ascending, so onSnapChange indexes refer to the sorted list.
- Put actions in footer, not at the end of children, so they stay visible while the body scrolls.
- It renders position: fixed without a portal: do not place it inside elements with transform or filter.
- dismissible={false} disables Esc, backdrop click and drag-to-close and hides the close button, so always give the user an explicit way out (e.g. Cancel / Save in footer).

## FAQ

**Does onSnapChange fire when the sheet opens?**

No. It fires after a drag release or a handle press moves the sheet. The opening snap point is defaultSnap.

**Can I drag it from the body?**

No. Only the header area drags, so scrolling content inside the body never fights the gesture.

## Related

- morphing-dialog: https://goodui.dev/components/overlays/morphing-dialog
- popover-morph: https://goodui.dev/components/overlays/popover-morph
- dropdown-stagger: https://goodui.dev/components/overlays/dropdown-stagger
- bottom-nav: https://goodui.dev/components/navigation/bottom-nav

Last updated: 2026-11-02

---

# Popover morph

> A small button such as "Add note" morphs into a floating form panel, its label sliding into the header, and shrinks back into the button on save, Esc or an outside click.

Popover that morphs from a button into a floating form, for React and shadcn

Page: https://goodui.dev/components/overlays/popover-morph

## Install

```bash
npx shadcn@latest add @goodui/popover-morph
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/popover-morph.json`. The file lands in `components/goodui/popover-morph.tsx`.

## When to use

- Quick input tied to one button: add a note to a booking, set a reminder, apply a discount code.
- Toolbars and record headers where a full dialog would interrupt the page.
- Small settings that should close as soon as the user clicks elsewhere.

## When not to use

- A list of actions or options: use dropdown-stagger, which has menu roles and arrow-key navigation.
- Read-only hints on hover: use tooltip-animated.
- Larger forms or anything that must not be lost on an outside click: use drawer-spring or morphing-dialog, which are modal.

## Pick by what matters

| Need | Use |
| --- | --- |
| Trigger near the top of the page | side="bottom" (default): the panel grows down from the trigger |
| Trigger near the bottom (composer, footer bar) | side="top": the panel grows up |
| Trigger at the right end of a toolbar | align="end" |
| Narrow panel for one field | width={280} |

## Usage

```tsx
import * as React from "react"
import { StickyNote } from "lucide-react"
import { Button } from "@/components/ui/button"
import { Textarea } from "@/components/ui/textarea"
import { PopoverMorph } from "@/components/goodui/popover-morph"

export function AddNote({ onAdd }: { onAdd: (text: string) => void }) {
  const [draft, setDraft] = React.useState("")

  return (
    <PopoverMorph label={<><StickyNote /> Add note</>} title={<><StickyNote /> Note for Sofia</>}>
      {({ close }) => (
        <form
          onSubmit={(e) => {
            e.preventDefault()
            if (!draft.trim()) return
            onAdd(draft.trim())
            setDraft("")
            close()
          }}
          className="space-y-2.5"
        >
          <Textarea value={draft} onChange={(e) => setDraft(e.target.value)} placeholder="Prefers a cooler tone than last time." rows={3} />
          <Button type="submit" size="sm" className="w-full">
            Save note
          </Button>
        </form>
      )}
    </PopoverMorph>
  )
}
```

### Discount code at the end of a toolbar

```tsx
<PopoverMorph
  label={<><TicketPercent /> {discount ?? "Discount"}</>}
  title={<><TicketPercent /> Apply a code</>}
  align="end"
  width={280}
>
  {({ close }) => (
    <form onSubmit={(e) => { e.preventDefault(); apply(code); close() }} className="flex gap-2">
      <Input data-autofocus value={code} onChange={(e) => setCode(e.target.value)} placeholder="WELCOME10" />
      <Button type="submit">Apply</Button>
    </form>
  )}
</PopoverMorph>
```

### Controlled, opening upward from a footer bar

```tsx
<PopoverMorph side="top" open={open} onOpenChange={setOpen} label={<><BellRing /> Remind</>}>
  <p className="text-sm text-muted-foreground">We will text the client 1 hour before.</p>
</PopoverMorph>
```

## API

### PopoverMorph

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| label (required) | `React.ReactNode` | — | Trigger content; it slides into the panel header when the popover opens. |
| children (required) | `React.ReactNode \| ((api: { close: () => void }) => React.ReactNode)` | — | Panel body. Pass a function to get close(), e.g. to close after a form submits. |
| title | `React.ReactNode` | — | Header text inside the panel. Defaults to the label. |
| open | `boolean` | — | Controlled open state. Pair with onOpenChange. |
| defaultOpen | `boolean` | `false` | Initial open state when uncontrolled. |
| onOpenChange | `(open: boolean) => void` | — | Called with the next state on trigger click, close(), Esc, an outside click or tabbing out. |
| side | `"bottom" \| "top"` | `"bottom"` | The panel grows down from the trigger, or up for "top". |
| align | `"start" \| "end"` | `"start"` | Preferred edge (logical: start is the left edge in LTR, the right edge in RTL); it flips when the panel would leave the viewport. |
| width | `number` | `320` | Panel width in px (capped to the viewport). |
| triggerClassName | `string` | — | Classes for the trigger button. |
| panelClassName | `string` | — | Classes for the floating panel. |
| labels | `Partial<PopoverMorphLabels>` | — | Text for built-in controls and screen readers; pass translations here. |

Also accepts every <div> attribute.

## Keyboard

| Keys | Action |
| --- | --- |
| Enter / Space | On the trigger (a native <button>): opens the panel and focuses the first [data-autofocus] or focusable element in the body. |
| Esc | Closes the panel and returns focus to the trigger. |
| Tab | Moves through the panel; tabbing out of it closes the panel. |

## Accessibility

- The trigger has aria-haspopup="dialog", aria-expanded, and aria-controls pointing at the panel while it is open.
- The panel has role="dialog" and is named by its header (title, or label when no title is given). It is non-modal: no focus trap and no scroll lock.
- The close button is labelled labels.close (default "Close").
- An outside click closes the panel without moving focus; Esc and the close button return focus to the trigger.

## Motion

- The trigger and the panel share one surface (layoutId), so the button grows into the panel on a spring (bounce 0.1, 0.38 s) and shrinks back on close. The label slides into the panel header.
- The close button pops in from scale 0.6; the body fades up 4px after a 60 ms delay (200 ms) and fades out in 60 ms.
- Reduced motion: the morph and the body appear without movement (duration 0).

## Notes for AI

- Pass the trigger content through label (icon + text), not as children; children is the panel body.
- Use the function child ({ close }) => … when a form should close after submitting; close() returns focus to the trigger.
- The panel is absolutely positioned inside an inline-block wrapper and covers the trigger while open. Give the parent room and do not clip it with overflow: hidden.
- align is logical (start = left in LTR, right in RTL) and only flips between start and end when the panel would leave the viewport; there is no vertical flip, so choose side yourself.
- The body unmounts whenever the panel closes (outside click, focus leaving), so keep draft state in the parent, as in the example, and keep long forms in a drawer or dialog.

## FAQ

**Why does the panel cover the button?**

It grows out of the button: the panel starts at the trigger's edge, so the label can slide straight into the header.

**Do I have to use the render function?**

No. Plain children work too; the panel then closes through its close button, Esc, an outside click, or your own open state.

## Related

- dropdown-stagger: https://goodui.dev/components/overlays/dropdown-stagger
- tooltip-animated: https://goodui.dev/components/overlays/tooltip-animated
- morphing-dialog: https://goodui.dev/components/overlays/morphing-dialog
- drawer-spring: https://goodui.dev/components/overlays/drawer-spring

Last updated: 2026-11-02

---

# Animated tooltip

> A tooltip springs out of the trigger's side and can lean toward the pointer over avatars; tooltips in a delay group open instantly once one is already showing.

Animated tooltip for React and shadcn with spring entry, pointer follow and delay groups

Page: https://goodui.dev/components/overlays/tooltip-animated

## Install

```bash
npx shadcn@latest add @goodui/tooltip-animated
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/tooltip-animated.json`. The file lands in `components/goodui/tooltip-animated.tsx`.

## When to use

- Icon-only toolbar buttons that need their name and shortcut on hover or keyboard focus.
- Avatar stacks where hovering a face shows the person's name and role (followPointer adds the lean).
- Rows of controls where moving from one to the next should show the next tooltip at once (wrap them in TooltipGroup).

## When not to use

- Content people need to click or select: tooltips ignore the pointer. Use popover-morph.
- Essential information on touch-first screens: it only shows after a long press there. Put the text on the page or in a badge.
- Long help text: the bubble does not wrap by default. Use a popover or inline helper text.

## Pick by what matters

| Need | Use |
| --- | --- |
| Toolbar of icon buttons | Wrap them in <TooltipGroup> (default delay 500 ms) so neighbours open instantly |
| Avatar stack or people list | followPointer with delay={0} |
| Trigger near the top edge | side="bottom" (there is no automatic flip) |
| Button inside a vertical sidebar | side="right" |

## Usage

```tsx
import { Download, Filter, Printer } from "lucide-react"
import { Button } from "@/components/ui/button"
import { TooltipAnimated, TooltipGroup } from "@/components/goodui/tooltip-animated"

export function BookingsToolbar() {
  return (
    <TooltipGroup delay={450}>
      <div className="flex gap-1 rounded-xl border bg-card p-1">
        <TooltipAnimated content="Show confirmed only">
          <Button variant="ghost" size="icon" aria-label="Filter">
            <Filter />
          </Button>
        </TooltipAnimated>
        <TooltipAnimated content="Print day sheet">
          <Button variant="ghost" size="icon" aria-label="Print">
            <Printer />
          </Button>
        </TooltipAnimated>
        <TooltipAnimated content="Export CSV">
          <Button variant="ghost" size="icon" aria-label="Export CSV">
            <Download />
          </Button>
        </TooltipAnimated>
      </div>
    </TooltipGroup>
  )
}
```

### Avatar stack that leans toward the pointer

```tsx
<div className="flex">
  {team.map((m) => (
    <TooltipAnimated
      key={m.name}
      followPointer
      delay={0}
      className="-ms-3 first:ms-0 hover:z-10 focus-within:z-10"
      content={<span className="flex flex-col items-center"><b>{m.name}</b><span className="opacity-70">{m.role}</span></span>}
    >
      <button type="button" className="size-10 rounded-full border-2 border-background bg-muted text-sm font-medium">
        {m.initials}
      </button>
    </TooltipAnimated>
  ))}
</div>
```

### Shortcut hint in the bubble

```tsx
<TooltipAnimated side="bottom" content={<>Next week <kbd className="ms-1 text-[10px]">→</kbd></>}>
  <Button variant="ghost" size="icon" aria-label="Next week"><ChevronRight /></Button>
</TooltipAnimated>
```

## API

### TooltipAnimated

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| children (required) | `React.ReactNode` | — | The trigger: one focusable element such as a button, so it gets aria-describedby and keyboard focus. Plain text (a string or number) is wrapped in a focusable span that carries aria-describedby. |
| content (required) | `React.ReactNode` | — | Tooltip text or node. It is also copied into a visually hidden element linked to the trigger with aria-describedby. |
| side | `"top" \| "bottom" \| "left" \| "right"` | `"top"` | Side of the trigger the tooltip appears on. There is no automatic flip. |
| delay | `number` | `400` | Open delay in ms. Inside a TooltipGroup the group's delay wins. |
| followPointer | `boolean` | `false` | The tooltip leans and slides toward the pointer (top and bottom sides). Turned off on touch screens. |
| disabled | `boolean` | `false` | Never open the tooltip. |
| contentClassName | `string` | — | Classes for the tooltip bubble. |

Also accepts every <span> attribute.

### TooltipGroup

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| children (required) | `React.ReactNode` | — | Content. |
| delay | `number` | `500` | Delay before the first tooltip in the group opens, in ms. |
| skipDelay | `number` | `300` | How long the group stays "warm" after a tooltip closes, in ms. |

## Keyboard

| Keys | Action |
| --- | --- |
| Tab | Focusing the trigger with the keyboard (:focus-visible) opens the tooltip at once; moving focus away hides it. |
| Esc | Hides the open tooltip. |

## Accessibility

- The content is copied into a visually hidden element and linked to the child with aria-describedby (merged with any aria-describedby it already has), so screen readers read it as the trigger's description. That hidden element has role="tooltip".
- The visible bubble is aria-hidden and pointer-events: none, so it never blocks the pointer or gets read twice.
- Opens on hover after the delay, at once on keyboard focus, and after a 450 ms long press on touch (then hides after 1.8 s). A mouse press on the trigger hides it.
- Icon-only triggers still need their own aria-label; the tooltip is a description, not a name.

## Motion

- Enter: the bubble springs out of the trigger's side (stiffness 520, damping 28, mass 0.7) from scale 0.6 and a 6px offset, with its transform origin on that side. Exit: fades and shrinks to 0.9 in 100 ms.
- Inside a warm TooltipGroup the next tooltip opens without the delay and with a quick 120 ms fade from scale 0.96 instead of the full spring.
- followPointer (top and bottom sides only) slides the bubble up to 40px toward the pointer and tilts it up to 10° on a spring (stiffness 260, damping 18). It is off on devices without a fine hover pointer.
- Reduced motion: opacity only, shown and hidden instantly; followPointer is off.

## Notes for AI

- Pass exactly one focusable element (a button or link) as the child; it receives aria-describedby. A plain string child is wrapped in a focusable span (tabIndex 0) that carries aria-describedby.
- Inside TooltipGroup the group's delay replaces each tooltip's delay prop.
- There is no collision detection or portal: pick side yourself and avoid ancestors with overflow: hidden that would clip the bubble.
- The bubble uses whitespace-nowrap; for a multi-line tooltip pass contentClassName="whitespace-normal w-56".
- className goes on the wrapping <span> (use it for stacking like -ms-3 hover:z-10); style the bubble with contentClassName.

## FAQ

**Why doesn't it open when I click the trigger?**

A mouse press hides the tooltip on purpose, and a mouse click does not count as keyboard focus. It opens on hover or on keyboard focus.

**How does the delay group work?**

After one tooltip in a TooltipGroup opens, the others open instantly while it is open and for skipDelay ms (default 300) after it closes.

## Related

- popover-morph: https://goodui.dev/components/overlays/popover-morph
- avatar: https://goodui.dev/components/core/avatar
- kbd: https://goodui.dev/components/core/kbd
- dock: https://goodui.dev/components/navigation/dock

Last updated: 2026-11-02

---

# Stagger dropdown

> A dropdown menu springs open while its items stagger in, with a highlight that glides between items, submenus, checkbox and radio items, and full keyboard navigation.

Animated dropdown menu for React and shadcn with staggered items, submenus and keyboard navigation

Page: https://goodui.dev/components/overlays/dropdown-stagger

## Install

```bash
npx shadcn@latest add @goodui/dropdown-stagger
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/dropdown-stagger.json`. The file lands in `components/goodui/dropdown-stagger.tsx`.

## When to use

- Row actions in a table or list: edit, reschedule, send a reminder, cancel.
- An account menu behind an avatar: profile, billing, team, sign out.
- View options for a list: checkbox items for what to show, radio items for the sort order.

## When not to use

- Picking a value for a form field: use select, which behaves like a form control and shows the chosen value.
- Searching across many commands: use command-palette-morph.
- A small form behind a button (a note, a code): use popover-morph.

## Pick by what matters

| Need | Use |
| --- | --- |
| Run an action | DropdownStaggerItem with onSelect (closes the menu) |
| Delete, cancel or remove | DropdownStaggerItem variant="destructive", after a separator |
| Toggle several options without closing | DropdownStaggerCheckboxItem (closeOnSelect defaults to false) |
| Choose one option such as a sort order | DropdownStaggerRadioGroup with DropdownStaggerRadioItem |
| A second level, such as time slots | DropdownStaggerSub |
| Icon-only trigger | triggerLabel plus a compact triggerClassName |

## Usage

```tsx
import { Bell, CalendarClock, Ellipsis, Pencil, XCircle } from "lucide-react"
import {
  DropdownStagger,
  DropdownStaggerItem,
  DropdownStaggerSeparator,
  DropdownStaggerSub,
} from "@/components/goodui/dropdown-stagger"

export function BookingActions({ client, cancelled, onAction }: { client: string; cancelled: boolean; onAction: (action: string) => void }) {
  return (
    <DropdownStagger
      align="end"
      triggerLabel={`Actions for ${client}`}
      triggerClassName="size-8 border-transparent bg-transparent px-0 shadow-none"
      trigger={<Ellipsis />}
    >
      <DropdownStaggerItem icon={<Pencil />} onSelect={() => onAction("edit")}>
        Edit booking
      </DropdownStaggerItem>
      <DropdownStaggerSub icon={<CalendarClock />} label="Reschedule">
        {["Today 5:45 PM", "Tomorrow 10:00 AM", "Fri 9:15 AM"].map((slot) => (
          <DropdownStaggerItem key={slot} onSelect={() => onAction(`move:${slot}`)}>
            {slot}
          </DropdownStaggerItem>
        ))}
      </DropdownStaggerSub>
      <DropdownStaggerItem icon={<Bell />} shortcut="⌘R" onSelect={() => onAction("remind")}>
        Send reminder
      </DropdownStaggerItem>
      <DropdownStaggerSeparator />
      <DropdownStaggerItem icon={<XCircle />} variant="destructive" disabled={cancelled} onSelect={() => onAction("cancel")}>
        Cancel booking
      </DropdownStaggerItem>
    </DropdownStagger>
  )
}
```

### View options with checkbox and radio items

```tsx
<DropdownStagger trigger={<><SlidersHorizontal /> View</>}>
  <DropdownStaggerLabel>Show</DropdownStaggerLabel>
  <DropdownStaggerCheckboxItem checked={showCancelled} onCheckedChange={setShowCancelled}>
    Cancelled bookings
  </DropdownStaggerCheckboxItem>
  <DropdownStaggerCheckboxItem checked={showPrices} onCheckedChange={setShowPrices}>
    Prices
  </DropdownStaggerCheckboxItem>
  <DropdownStaggerSeparator />
  <DropdownStaggerLabel>Sort by</DropdownStaggerLabel>
  <DropdownStaggerRadioGroup value={sort} onValueChange={setSort}>
    <DropdownStaggerRadioItem value="time">Start time</DropdownStaggerRadioItem>
    <DropdownStaggerRadioItem value="client">Client name</DropdownStaggerRadioItem>
    <DropdownStaggerRadioItem value="price">Highest value</DropdownStaggerRadioItem>
  </DropdownStaggerRadioGroup>
</DropdownStagger>
```

### Keep the menu open after an action

```tsx
<DropdownStaggerItem icon={<Copy />} onSelect={(e) => { e.preventDefault(); copyLink() }}>
  Copy link
</DropdownStaggerItem>
```

## API

### DropdownStagger

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| trigger (required) | `React.ReactNode` | — | Content of the trigger button. |
| children (required) | `React.ReactNode` | — | Items, labels, separators, radio groups and submenus. |
| triggerLabel | `string` | — | Accessible name when the trigger is icon-only. Rendered as sr-only text after the trigger content, so any visible text stays the start of the name. |
| triggerClassName | `string` | — | Classes for the trigger button. |
| contentClassName | `string` | — | Classes for the menu panel. |
| align | `"start" \| "end"` | `"start"` | Which edge of the trigger the menu lines up with (logical: start is the left edge in LTR, the right edge in RTL). It does not flip near the viewport edge. |
| open | `boolean` | — | Controlled open state. Pair with onOpenChange. |
| defaultOpen | `boolean` | `false` | Initial open state when uncontrolled. |
| onOpenChange | `(open: boolean) => void` | — | Called with the next state on trigger use, item selection, Esc, Tab or an outside click. |

Also accepts every <div> attribute.

### DropdownStaggerItem

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| children (required) | `React.ReactNode` | — | Content. |
| icon | `React.ReactNode` | — | Leading icon, tinted muted unless the item is destructive. |
| shortcut | `string` | — | Hint shown on the right, e.g. "⌘E". It is display text only; it does not bind the shortcut. |
| variant | `"default" \| "destructive"` | `"default"` | "destructive" colors the text and highlight with the destructive token. |
| disabled | `boolean` | — | Grays the item out; arrow keys and typeahead skip it and clicks do nothing. |
| onSelect | `(event: React.MouseEvent<HTMLButtonElement>) => void` | — | Call event.preventDefault() to keep the menu open. |
| closeOnSelect | `boolean` | `true` | Close the menu and return focus to the trigger after selecting. Defaults to true for items, false for checkbox and radio items. |
| className | `string` | — | Classes merged onto the root element. |

### DropdownStaggerCheckboxItem

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| children (required) | `React.ReactNode` | — | Content. |
| checked (required) | `boolean` | — | Whether the check is drawn. The item is always controlled. |
| onCheckedChange (required) | `(checked: boolean) => void` | — | Called with the toggled value on click, Enter or Space. |
| className | `string` | — | Classes merged onto the root element. |
| onSelect | `(event: React.MouseEvent<HTMLButtonElement>) => void` | — | Call event.preventDefault() to keep the menu open. |
| disabled | `boolean` | — | Grays the item out; arrow keys and typeahead skip it and clicks do nothing. |
| shortcut | `string` | — | Hint shown on the right, e.g. "⌘E". It is display text only; it does not bind the shortcut. |
| closeOnSelect | `boolean` | `false` | Close the menu and return focus to the trigger after selecting. Defaults to true for items, false for checkbox and radio items. |

### DropdownStaggerRadioGroup

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| value (required) | `string` | — | Value of the selected radio item. |
| onValueChange (required) | `(value: string) => void` | — | Called with the chosen item's value. |
| children (required) | `React.ReactNode` | — | Content. |
| label | `string` | — | Accessible name of the group. Without it, a DropdownStaggerLabel right before (or inside) the group names it. |
| aria-labelledby | `string` | — | Id of an element that names the group; overrides the automatic DropdownStaggerLabel link. |

### DropdownStaggerRadioItem

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| children (required) | `React.ReactNode` | — | Content. |
| value (required) | `string` | — | Value reported to the surrounding DropdownStaggerRadioGroup; checked when it equals the group's value. |
| className | `string` | — | Classes merged onto the root element. |
| onSelect | `(event: React.MouseEvent<HTMLButtonElement>) => void` | — | Call event.preventDefault() to keep the menu open. |
| disabled | `boolean` | — | Grays the item out; arrow keys and typeahead skip it and clicks do nothing. |
| shortcut | `string` | — | Hint shown on the right, e.g. "⌘E". It is display text only; it does not bind the shortcut. |
| closeOnSelect | `boolean` | `false` | Close the menu and return focus to the trigger after selecting. Defaults to true for items, false for checkbox and radio items. |

### DropdownStaggerSub

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| label (required) | `React.ReactNode` | — | Text of the item that opens the submenu; it also names the submenu. |
| children (required) | `React.ReactNode` | — | Content. |
| icon | `React.ReactNode` | — | Leading icon for the submenu item. |
| disabled | `boolean` | — | Grays the item out; the submenu cannot open. |
| className | `string` | — | Classes merged onto the root element. |

### DropdownStaggerLabel

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| children (required) | `React.ReactNode` | — | Content. |
| id | `string` | — |  |
| className | `string` | — | Classes merged onto the root element. |

### DropdownStaggerSeparator

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| className | `string` | — | Classes merged onto the root element. |

## Keyboard

| Keys | Action |
| --- | --- |
| Enter / Space / ArrowDown | On the trigger: opens the menu and focuses the first item. |
| ArrowUp | On the trigger: opens the menu and focuses the last item. |
| ArrowDown / ArrowUp | Moves to the next or previous enabled item, wrapping at the ends. |
| Home / End | Moves to the first or last enabled item. |
| Enter / Space | Activates the focused item, toggles a checkbox item or picks a radio item. |
| ArrowRight / Enter / Space | On a submenu item: opens the submenu and focuses its first item. |
| ArrowLeft | Inside a submenu: closes it and returns to its parent item. |
| Esc | Closes the submenu you are in, or the menu, returning focus to its trigger. |
| Tab | Closes the whole menu and returns focus to the trigger. |
| Letters | Typeahead: jumps to the next item whose text starts with the typed letters (600 ms window). |

## Accessibility

- The trigger is a <button> with aria-haspopup="menu", aria-expanded and aria-controls; triggerLabel adds sr-only text after the trigger content, so icon-only triggers get a name and visible text stays the start of it.
- The panel is role="menu" (aria-orientation vertical) labelled by its trigger. Items use menuitem, menuitemcheckbox and menuitemradio with aria-checked; submenu items have aria-haspopup and aria-expanded.
- A radio group is named by the DropdownStaggerLabel right before (or inside) it through aria-labelledby; pass label or aria-labelledby to name it yourself.
- Under dir="rtl" ArrowLeft opens a submenu and ArrowRight closes it; submenus open to the left first and items slide in from the other side.
- Disabled items get aria-disabled, are skipped by arrow keys and typeahead, and ignore clicks.
- Selecting an item, Esc and Tab return focus to the trigger; an outside click closes the menu without moving focus.
- Hovering an item moves focus to it, so the pointer and the keyboard share one highlight.

## Motion

- The panel springs in (stiffness 520, damping 36) from scale 0.95 and 6px above; submenus come from 6px to the side. Items stagger in 28 ms apart after 30 ms, each sliding 8px on a spring (stiffness 520, damping 32).
- Close: the panel fades and shrinks to 0.97 in 120 ms.
- A highlight glides between items with a shared layoutId (stiffness 700, damping 45). Checkbox checks draw their stroke (pathLength spring 400 / 30); radio dots pop in (spring 600 / 26).
- Submenus open after 90 ms of hover and close 160 ms after the pointer leaves, so diagonal moves do not drop them.
- Reduced motion: panels and items only change opacity, instantly; the highlight, check and dot jump without animating.

## Notes for AI

- Use onSelect, not onClick, on items. Call event.preventDefault() inside onSelect to keep the menu open.
- Checkbox items are controlled: always pass checked and onCheckedChange. Radio items only work inside DropdownStaggerRadioGroup with value and onValueChange.
- shortcut is display text only; bind the actual key yourself (for example with the kbd component's onTrigger).
- The menu is absolutely positioned inside an inline-block wrapper, with no portal and no vertical flip. Leave room below the trigger and avoid overflow: hidden on ancestors; use align="end" near the inline end (align is logical, so it mirrors under RTL).
- Keep item children as plain text where possible; typeahead matches on the item's text content.

## FAQ

**Where does a submenu open?**

Toward the inline end (right in LTR, left in RTL) when there is room, else the other side, else below the item, measured each time it opens.

**Can I control the open state?**

Yes: pass open and onOpenChange. defaultOpen works for the uncontrolled case.

## Related

- select: https://goodui.dev/components/core/select
- command-palette-morph: https://goodui.dev/components/navigation/command-palette-morph
- popover-morph: https://goodui.dev/components/overlays/popover-morph
- kbd: https://goodui.dev/components/core/kbd

Last updated: 2026-11-02

---

# Accordion height

> Accordion whose panels spring open to their real height (motion height:auto) with a rotating chevron, in single or multiple mode, with arrow-key, Home and End navigation between headers.

Animated accordion for React and shadcn that springs to its real height

Page: https://goodui.dev/components/lists/accordion-height

## Install

```bash
npx shadcn@latest add @goodui/accordion-height
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/accordion-height.json`. The file lands in `components/goodui/accordion-height.tsx`.

## When to use

- FAQ sections on pricing and help pages, where people scan questions and open one or two.
- Settings grouped by location, service or feature, each group opening to its controls.
- Long forms or details split into sections that would otherwise push the page far down.

## When not to use

- A list of records (appointments, invoices) with their own summary layout and actions: use expandable-row-list.
- Nested folders or categories: use tree-expand.
- Switching between a few views of equal weight: use tabs-indicator, so only one view is ever shown.

## Pick by what matters

| Need | Use |
| --- | --- |
| FAQ where one answer at a time keeps the page short | type="single" (default), collapsible stays true |
| Settings people compare side by side | type="multiple" |
| One section must always stay open | type="single" collapsible={false} |
| A self-contained card in a dashboard | variant="bordered" (default) |
| Sections as separate cards with a shadow on the open one | variant="separated" |
| Inline in a page or a sidebar, no card | variant="ghost" |

## Usage

```tsx
import { CalendarClock, CreditCard, Receipt } from "lucide-react"
import { AccordionHeight } from "@/components/goodui/accordion-height"

export function BillingFaq() {
  return (
    <AccordionHeight
      defaultValue={["trial"]}
      items={[
        {
          value: "trial",
          icon: <CalendarClock />,
          title: "What happens when my trial ends?",
          content: "Your workspace moves to the Free plan. Bookings and clients stay; online payments pause until you pick a plan.",
        },
        {
          value: "card",
          icon: <CreditCard />,
          title: "Can I change the card on file?",
          description: "Billing → Payment method",
          content: "Yes. The new card is used from the next invoice; nothing is charged when you switch.",
        },
        {
          value: "invoices",
          icon: <Receipt />,
          title: "Where do I find past invoices?",
          content: "Every invoice is listed under Billing → Invoices as a PDF with your company details.",
        },
      ]}
    />
  )
}
```

### Controlled, several open at once

```tsx
const [open, setOpen] = React.useState<string[]>(["downtown"])

<AccordionHeight
  type="multiple"
  variant="separated"
  value={open}
  onValueChange={setOpen}
  items={locations.map((l) => ({
    value: l.id,
    title: l.name,
    description: l.address,
    content: <OpeningHours location={l} />,
  }))}
/>
<button onClick={() => setOpen(locations.map((l) => l.id))}>Expand all</button>
```

### Ghost variant in a sidebar

```tsx
<AccordionHeight
  variant="ghost"
  items={[
    { value: "filters", title: "Filters", content: <StatusFilters /> },
    { value: "export", title: "Export", content: <ExportOptions />, disabled: !canExport },
  ]}
/>
```

## API

### AccordionHeight

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| items (required) | `AccordionHeightItem[]` | — | The sections, in order. |
| type | `"single" \| "multiple"` | `"single"` | "single" keeps one item open at a time, "multiple" lets any number stay open. |
| value | `string[]` | — | Open item values (controlled). |
| defaultValue | `string[]` | `[]` | Item values open on first render (uncontrolled). |
| onValueChange | `(value: string[]) => void` | — | Called with the new list of open item values whenever an item opens or closes. |
| collapsible | `boolean` | `true` | In single mode, clicking the open item closes it. |
| variant | `"bordered" \| "separated" \| "ghost"` | `"bordered"` | "bordered": one card with dividers. "separated": a card per item. "ghost": dividers only. |

Also accepts every <div> attribute.

## Keyboard

| Keys | Action |
| --- | --- |
| Enter / Space | Opens or closes the focused section (native <button>). |
| ArrowDown / ArrowUp | Moves focus to the next or previous header, wrapping at the ends and skipping disabled items. |
| Home / End | Moves focus to the first or last enabled header. |
| Tab | Moves through headers and into the open panels' content. |

## Accessibility

- Each header is a native <button> inside an <h3>, with aria-expanded and aria-controls pointing at its panel while it is open (closed panels are not in the DOM).
- Open panels have role="region" and aria-labelledby set to their header, so screen readers name them.
- Closed panels are unmounted, so their content is out of the tab order and hidden from assistive tech.
- Icons and the chevron are aria-hidden; the title is the accessible name.

## Motion

- Panels animate height from 0 to auto on a spring (bounce 0, 0.38 s), so content of any height opens fully with no max-height hack.
- Opacity fades in over 0.22 s and out over 0.16 s; the content slides down 8px as it opens and up 6px as it closes.
- The chevron turns 180° on a spring (stiffness 420, damping 30); an icon tile switches to the primary color.
- separated: the open card gains a soft shadow (CSS, 300 ms).
- Reduced motion: every transition has duration 0, so panels open and close instantly without the slide.

## Notes for AI

- Pass items as { value, title, content } with unique string values; value and defaultValue are arrays of those strings, even in single mode.
- Panels unmount when closed: keep form or toggle state in a parent, or it resets each time the panel reopens.
- Headers render as <h3>; there is no prop for the heading level.
- Do not put buttons or links in title or description: they render inside the header <button>.
- For an Expand all control, use the controlled value with type="multiple".

## FAQ

**Why does content inside a panel lose its state when I close it?**

Closed panels are removed from the DOM so they leave the tab order. Lift the state into the parent, as the demo does with its switches.

**Can I open a section from outside, e.g. from a link?**

Yes. Pass value and onValueChange, then set the array to include that item's value.

## Related

- expandable-row-list: https://goodui.dev/components/lists/expandable-row-list
- tree-expand: https://goodui.dev/components/lists/tree-expand
- expandable-card: https://goodui.dev/components/cards/expandable-card
- tabs-indicator: https://goodui.dev/components/navigation/tabs-indicator

Last updated: 2026-11-02

---

# List reorder

> Drag-to-reorder list with a grip handle, a lifted shadow on the dragged row, neighbours that spring into place, and Alt+Arrow keyboard moves announced to screen readers.

Drag and drop reorderable list for React and shadcn with keyboard moves

Page: https://goodui.dev/components/lists/list-reorder

## Install

```bash
npx shadcn@latest add @goodui/list-reorder
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/list-reorder.json`. The file lands in `components/goodui/list-reorder.tsx`.

## When to use

- Letting people set an order that matters: services on a booking page, staff priority, pipeline stages.
- Short lists (up to a few dozen rows) where dragging is faster than typing a position number.
- When the order must also be changeable from the keyboard, with screen reader announcements.

## When not to use

- Sorting data by a column (date, amount): sort the array and show it in table-row-presence.
- Dragging between columns or into nested groups (kanban, trees): this list reorders only within itself, vertically.
- Lists that only change by new items arriving: use animated-list.

## Pick by what matters

| Need | Use |
| --- | --- |
| Rows with their own buttons or inputs | handle="start" (default) or handle="end", so only the grip starts a drag |
| Simple rows where the whole row should be grabbable | handle="none": each row becomes focusable and moves with the arrow keys |

## Usage

```tsx
import * as React from "react"
import { ListReorder } from "@/components/goodui/list-reorder"

type Service = { id: string; name: string; minutes: number }

export function ServiceOrder() {
  const [services, setServices] = React.useState<Service[]>([
    { id: "cut", name: "Haircut", minutes: 45 },
    { id: "color", name: "Full color", minutes: 120 },
    { id: "blow", name: "Blow-dry", minutes: 30 },
    { id: "beard", name: "Beard trim", minutes: 20 },
  ])

  return (
    <ListReorder
      label="Services order on the booking page"
      items={services}
      onReorder={setServices}
      getKey={(s) => s.id}
      getLabel={(s) => s.name}
      renderItem={(s, { index }) => (
        <div className="flex items-center justify-between gap-3">
          <span className="truncate text-sm font-medium">
            {index + 1}. {s.name}
          </span>
          <span className="text-xs text-muted-foreground">{s.minutes} min</span>
        </div>
      )}
    />
  )
}
```

### Grip on the end, translated announcements

```tsx
<ListReorder
  items={stages}
  onReorder={setStages}
  getKey={(s) => s.id}
  getLabel={(s) => s.title}
  handle="end"
  labels={{
    handle: (label, pos, count) => `${label} neu anordnen, Position ${pos} von ${count}`,
    moved: (label, pos, count) => `${label} auf Position ${pos} von ${count} verschoben`,
  }}
  renderItem={(s) => <span className="text-sm">{s.title}</span>}
/>
```

### Whole row draggable

```tsx
<ListReorder
  handle="none"
  items={staff}
  onReorder={setStaff}
  getKey={(m) => m.id}
  getLabel={(m) => m.name}
  renderItem={(m) => <span className="text-sm font-medium">{m.name}</span>}
/>
```

## API

### ListReorder

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| items (required) | `T[]` | — | Items in their current order (controlled). |
| onReorder (required) | `(items: T[]) => void` | — | Called with the whole list in its new order after a drag step or keyboard move; store it back into `items`. |
| getKey (required) | `(item: T) => string` | — | Stable unique key of an item. Also the default for `getLabel`. |
| renderItem (required) | `(item: T, state: ListReorderRenderState) => React.ReactNode` | — | Content of a row. `state.index` is the current position, `state.dragging` is true while that row is held. |
| getLabel | `(item: T) => string` | `getKey` | Plain-text name of an item, used for the handle label and screen reader announcements. |
| handle | `"start" \| "end" \| "none"` | `"start"` | Where the grip sits. "none" makes the whole row draggable. |
| label | `string` | `"Reorderable list"` | Accessible name of the list. |
| itemClassName | `string` | — | Classes added to every row (<li>). |
| labels | `Partial<ListReorderLabels>` | — | Text for built-in controls and screen readers; pass translations here. |

Also accepts every <div> attribute.

## Keyboard

| Keys | Action |
| --- | --- |
| ArrowUp / ArrowDown | On a focused grip handle, moves that row up or down one position (stops at the ends). |
| ArrowUp / ArrowDown (handle="none") | On a focused row, moves that row one position. |
| Alt + ArrowUp / Alt + ArrowDown | With focus on anything inside a row, moves that row one position. |
| Tab | Moves between grip handles and the rows' own controls. |

## Accessibility

- With handle="none" each row is focusable (tabIndex 0, visible focus ring) and described by the same text as the grip label (labels.handle).
- The grip is a real <button> whose aria-label names the item and its position ("Reorder Haircut, position 2 of 4. Use the arrow keys to move.").
- Keyboard moves and drops are announced through an assertive live region, using getLabel for the item name.
- The list is a <ul> named by the label prop; every announcement and the handle label can be translated through labels.

## Motion

- Rows spring into their new place (stiffness 520, damping 42) as the dragged row passes them.
- The held row scales to 1.025 and gets a primary-tinted border and a large shadow (CSS, 200 ms).
- Reduced motion: no lift scale, and rows move to their new place instantly; dragging still works.

## Notes for AI

- The list is controlled: items plus onReorder are required, and onReorder must store the new array (setItems), or nothing moves.
- getKey must return a stable unique id, never the array index.
- Pass getLabel returning plain text; without it the key is read out to screen readers.
- With handle="none" the row itself takes focus and moves with plain arrows; keep renderItem free of extra buttons unless they are needed (Alt+Arrow still works from inside them).
- onReorder fires while dragging, not only on drop; debounce saving to the server.

## FAQ

**How do I save the new order?**

onReorder gives you the full array in its new order. Store it in state and persist it, preferably debounced, because it fires on every step of a drag.

**Does it work on touch screens?**

Yes. The grip (or the whole row with handle="none") sets touch-action: none so a drag does not scroll the page.

## Related

- table-row-presence: https://goodui.dev/components/lists/table-row-presence
- animated-list: https://goodui.dev/components/lists/animated-list
- expandable-row-list: https://goodui.dev/components/lists/expandable-row-list

Last updated: 2026-11-02

---

# Table row presence

> Data table where new rows grow in with a brief highlight, removed rows slide out and collapse, and re-sorting glides every row to its new position.

Animated data table for React and shadcn: rows enter, leave and re-sort smoothly

Page: https://goodui.dev/components/lists/table-row-presence

## Install

```bash
npx shadcn@latest add @goodui/table-row-presence
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/table-row-presence.json`. The file lands in `components/goodui/table-row-presence.tsx`.

## When to use

- Tables that change while people look at them: today's bookings, live orders, a queue being worked through.
- Re-sorting by a column, so people can follow where a row went instead of the table jumping.
- Removing or adding rows from row actions (cancel, archive, add), where a sudden jump hides what changed.

## When not to use

- Large tables (hundreds of rows) or virtualised grids: every row is a motion element; use a plain table there.
- Letting people set the order by hand: use list-reorder.
- Values updating inside a fixed set of rows (prices, stock counts): use cell-flash on the cells instead.

## Usage

```tsx
import * as React from "react"
import { TableRowPresence, type TableRowPresenceColumn } from "@/components/goodui/table-row-presence"

type Booking = { id: string; client: string; service: string; time: string; price: number }

const columns: TableRowPresenceColumn<Booking>[] = [
  { key: "client", header: "Client", cell: (b) => <span className="font-medium">{b.client}</span> },
  { key: "service", header: "Service", cell: (b) => b.service, className: "hidden sm:table-cell" },
  { key: "time", header: "Time", cell: (b) => b.time, className: "w-20" },
  { key: "price", header: "Price", cell: (b) => `$${b.price}`, align: "right" },
]

export function TodayBookings({ bookings }: { bookings: Booking[] }) {
  const [sortBy, setSortBy] = React.useState<"time" | "price">("time")
  const rows = [...bookings].sort((a, b) => (sortBy === "time" ? a.time.localeCompare(b.time) : b.price - a.price))

  return (
    <div className="space-y-3">
      <button type="button" onClick={() => setSortBy(sortBy === "time" ? "price" : "time")}>
        Sort by {sortBy === "time" ? "price" : "time"}
      </button>
      <TableRowPresence
        rows={rows}
        columns={columns}
        getRowId={(b) => b.id}
        caption="Bookings for today"
        empty="No bookings today."
      />
    </div>
  )
}
```

### Remove a row from an action in the row

```tsx
const columns: TableRowPresenceColumn<Invoice>[] = [
  { key: "number", header: "Invoice", cell: (i) => i.number },
  { key: "amount", header: "Amount", cell: (i) => formatMoney(i.amount), align: "right" },
  {
    key: "actions",
    header: <span className="sr-only">Actions</span>,
    align: "right",
    cell: (i) => (
      <button type="button" onClick={() => setInvoices((list) => list.filter((x) => x.id !== i.id))}>
        Archive
      </button>
    ),
  },
]
```

## API

### TableRowPresence

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| rows (required) | `T[]` | — | Rows in display order. Add, remove or re-sort this array and the table animates the difference. |
| columns (required) | `TableRowPresenceColumn<T>[]` | — | Column definitions, in order. |
| getRowId (required) | `(row: T) => string` | — | Stable unique id of a row; rows are matched across renders by it. |
| highlightNew | `boolean` | `true` | Briefly tint rows that arrive after the first render. |
| empty | `React.ReactNode` | `"No rows"` | Shown in a full-width row when there are no rows. |
| caption | `React.ReactNode` | — | Table caption, shown below the table. |
| onRowClick | `(row: T) => void` | — | Makes rows clickable: pointer cursor, and each row becomes focusable and activates with Enter or Space. |

Also accepts every <table> attribute.

## Accessibility

- Renders a real <table> with <th scope="col"> headers and an optional <caption>, so screen readers read it as a table.
- With onRowClick, rows are focusable (tabIndex 0, visible focus outline) and activate with Enter or Space when the row itself has focus; keys inside cell buttons and links are left alone.
- For an actions column with no visible header, pass header as <span className="sr-only">Actions</span>.

## Motion

- New rows fade in and slide 12px in from the left while each cell grows from 0 to its height on a spring (bounce 0, 0.42 s), so rows below slide down instead of jumping.
- Rows added after the first render get a primary tint that fades out over 2.2 s (highlightNew, on by default). Rows present on the first render appear without it.
- Removed rows slide 24px to the right and fade out (0.2 s, ease-in) while their cells collapse and the gap closes.
- Re-sorting moves every row to its new position with a layout animation on the same spring.
- The empty-state row fades in after 0.2 s, once the last row has left.
- Reduced motion: no slides, no layout glide and no height animation; the new-row tint is effectively off (0.01 s).

## Performance

- Every row and cell is a motion element, and layout animation measures rows on change. It suits dashboard-sized tables, not hundreds of rows.

## Notes for AI

- The table is driven by the rows array: add, remove or sort it in state; there are no add/remove/sort methods or props.
- getRowId must return a stable unique id (a database id), never the index, or every row animates on each sort.
- Columns are { key, header, cell(row) } objects; use className such as "hidden sm:table-cell" to hide columns on phones.
- Sorting UI is not built in: render your own sort buttons and pass the sorted array.
- onRowClick rows are keyboard reachable, but a row is not announced as a button; for a primary action also keep a labelled button or link in a cell. align left/right map to start/end, so they mirror under RTL.

## FAQ

**How do I animate a sort?**

Sort a copy of the array and pass it as rows. Rows keep their ids, so each one glides to its new position.

**Can I turn off the highlight on new rows?**

Yes, pass highlightNew={false}. Rows still slide and grow in.

## Related

- list-reorder: https://goodui.dev/components/lists/list-reorder
- cell-flash: https://goodui.dev/components/numbers/cell-flash
- animated-list: https://goodui.dev/components/lists/animated-list
- expandable-row-list: https://goodui.dev/components/lists/expandable-row-list

Last updated: 2026-11-02

---

# Animated list

> Notification stack where new items spring in from the top, older ones glide down, slightly dimmed in the depth variant, and items beyond the limit blur away.

Animated notification list for React and shadcn: new items spring in at the top

Page: https://goodui.dev/components/lists/animated-list

## Install

```bash
npx shadcn@latest add @goodui/animated-list
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/animated-list.json`. The file lands in `components/goodui/animated-list.tsx`.

## When to use

- Activity feeds and notification panels where new events arrive at the top: new bookings, payments, sign-ups.
- A compact "recent payments" or "latest orders" card that shows the last few items and drops older ones.
- Landing-page demos that simulate live activity by adding an item every few seconds.

## When not to use

- Temporary messages that confirm an action and then disappear: use toast-stack.
- Tabular data with columns, sorting or removal in the middle: use table-row-presence.
- Lists people reorder by hand: use list-reorder.

## Pick by what matters

| Need | Use |
| --- | --- |
| Plain feed inside a card | defaults (no depth, no fadeEdge) |
| Notification-stack look, older items slightly smaller and dimmer | depth |
| List that visually trails off at the bottom | fadeEdge |

## Usage

```tsx
import * as React from "react"
import { CalendarCheck } from "lucide-react"
import { AnimatedList } from "@/components/goodui/animated-list"

type Activity = { id: string; client: string; service: string; time: string }

export function BookingFeed({ activity }: { activity: Activity[] }) {
  // activity is newest first: prepend new events, e.g. setActivity((a) => [event, ...a])
  return (
    <AnimatedList
      items={activity}
      getKey={(a) => a.id}
      maxItems={4}
      depth
      label="New bookings"
      renderItem={(a) => (
        <div className="flex items-center gap-3 rounded-xl border bg-card p-3 shadow-sm">
          <CalendarCheck className="size-4 shrink-0 text-emerald-600 dark:text-emerald-400" aria-hidden="true" />
          <div className="min-w-0 flex-1 text-sm">
            <p className="truncate font-medium">{a.client} booked {a.service}</p>
            <p className="text-xs text-muted-foreground">{a.time}</p>
          </div>
        </div>
      )}
    />
  )
}
```

### Recent payments card with a faded edge

```tsx
<AnimatedList
  items={payments}
  getKey={(p) => p.id}
  maxItems={5}
  fadeEdge
  label="Recent payments"
  className="gap-0 rounded-xl border bg-card px-3 py-1"
  renderItem={(p) => (
    <div className="flex justify-between border-b py-2.5 text-sm">
      <span>{p.client}</span>
      <span className="tabular-nums">+${p.amount}</span>
    </div>
  )}
/>
```

## API

### AnimatedList

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| items (required) | `T[]` | — | Newest first. New items enter at the top and push the rest down. |
| getKey (required) | `(item: T) => string` | — | Stable unique key of an item; a new key is what makes an item animate in. |
| renderItem (required) | `(item: T, index: number) => React.ReactNode` | — | Content of one item; `index` is 0 for the newest. |
| maxItems | `number` | `5` | Items beyond this count leave the bottom of the stack. |
| depth | `boolean` | `false` | Dim and shrink older items slightly, like a notification stack. Dimming lowers text contrast, so use text-foreground/75 rather than text-muted-foreground for secondary text. |
| fadeEdge | `boolean` | `false` | Fade the bottom edge out. |
| label | `string` | `"Notifications"` | Accessible name for the live region. |

Also accepts every <ul> attribute.

## Accessibility

- The list is a <ul aria-live="polite" aria-relevant="additions"> (a real list, so its <li> items stay valid), so screen readers read new items without interrupting.
- label names the list (default "Notifications"); set it to what the feed is, e.g. "Recent payments".
- With depth, older items are dimmed; use text-foreground/75 instead of text-muted-foreground for their secondary text so it keeps 4.5:1 contrast.
- Keep each item's text short: the whole new item is what gets announced.

## Motion

- New items enter from 24px above, scaled to 0.92 and blurred 4px, on a spring (stiffness 380, damping 32, mass 0.9); the items below glide down with a layout animation.
- Items pushed past maxItems fade, shrink to 0.9 and blur out over 0.2 s.
- depth: each older item is 6% more transparent and 2% smaller, up to four steps.
- Reduced motion: items appear and disappear without movement, scale or blur, with no transition.

## Notes for AI

- items is newest first: add new entries with [item, ...items], not push, or they appear at the bottom.
- getKey must be stable and unique per item (an event id); index keys make every item re-animate.
- maxItems only limits what is shown (default 5); trim the array yourself if it can grow without bound.
- renderItem returns the whole card; the list adds no styling beyond a vertical gap-2, which className can override.
- Do not wrap it in another aria-live region; it already is one.

## FAQ

**How do I simulate live activity on a landing page?**

Prepend an item to the array on an interval (setInterval in useEffect, cleared on unmount). The list animates the rest.

**Why do new items appear at the bottom?**

The list expects newest first. Prepend new items instead of pushing them.

## Related

- toast-stack: https://goodui.dev/components/feedback/toast-stack
- notification-badge: https://goodui.dev/components/feedback/notification-badge
- table-row-presence: https://goodui.dev/components/lists/table-row-presence
- list-reorder: https://goodui.dev/components/lists/list-reorder

Last updated: 2026-11-02

---

# Tree expand

> File or category tree with spring expand/collapse, indentation guides, a selection highlight that glides between rows, and full arrow-key, Enter and type-ahead navigation.

Animated tree view for React and shadcn with keyboard navigation

Page: https://goodui.dev/components/lists/tree-expand

## Install

```bash
npx shadcn@latest add @goodui/tree-expand
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/tree-expand.json`. The file lands in `components/goodui/tree-expand.tsx`.

## When to use

- File and document browsers: invoices by year, client folders, exports.
- Picking from nested categories, e.g. services grouped by category on a booking form.
- Navigation for deep settings or docs where the hierarchy itself helps people find things.

## When not to use

- One level of sections with rich content inside: use accordion-height.
- Searching a large flat list of commands or pages: use command-palette-morph.
- Records with a summary row and actions: use expandable-row-list.

## Pick by what matters

| Need | Use |
| --- | --- |
| File browser where clicking a folder opens it | toggleOnSelect (default true) |
| Folders are selectable on their own (e.g. pick a target folder) | toggleOnSelect={false}: the chevron toggles, the row selects |
| Deep trees where levels are easy to lose | guides (default true), indent={18} |
| Shallow category picker | guides={false} indent={24} |

## Usage

```tsx
import * as React from "react"
import { FileText, Folder, FolderOpen } from "lucide-react"
import { TreeExpand, type TreeExpandNode } from "@/components/goodui/tree-expand"

const folder = { icon: <Folder />, openIcon: <FolderOpen /> }

const DOCUMENTS: TreeExpandNode[] = [
  {
    id: "invoices",
    label: "Invoices",
    ...folder,
    children: [
      { id: "inv-1042", label: "INV-1042 Ava Thompson.pdf", icon: <FileText />, meta: "84 KB" },
      { id: "inv-1043", label: "INV-1043 Noah Kim.pdf", icon: <FileText />, meta: "79 KB" },
    ],
  },
  {
    id: "contracts",
    label: "Contracts",
    ...folder,
    children: [{ id: "lease", label: "Studio lease 2026.pdf", icon: <FileText />, meta: "1.1 MB" }],
  },
  { id: "pricelist", label: "Price list.pdf", icon: <FileText />, meta: "156 KB" },
]

export function DocumentTree() {
  const [file, setFile] = React.useState<TreeExpandNode | null>(null)
  return (
    <div className="space-y-2">
      <TreeExpand
        label="Documents"
        nodes={DOCUMENTS}
        defaultExpanded={["invoices"]}
        onSelectedChange={(_, node) => setFile(node && !node.children ? node : null)}
      />
      <p className="text-xs text-muted-foreground">{file ? `Selected: ${file.label}` : "Nothing selected"}</p>
    </div>
  )
}
```

### Controlled expand / collapse all

```tsx
const [expanded, setExpanded] = React.useState<string[]>([])
const allFolders = ["invoices", "contracts"]

<button onClick={() => setExpanded(expanded.length ? [] : allFolders)}>
  {expanded.length ? "Collapse all" : "Expand all"}
</button>
<TreeExpand label="Documents" nodes={DOCUMENTS} expanded={expanded} onExpandedChange={setExpanded} />
```

### Category picker where only leaves are selectable

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

<TreeExpand
  label="Services"
  nodes={SERVICES}
  guides={false}
  indent={24}
  selected={service}
  onSelectedChange={(id, node) => {
    if (id && node && !node.children) setService(id)
  }}
/>
```

## API

### TreeExpand

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| nodes (required) | `TreeExpandNode[]` | — | Top-level nodes. |
| expanded | `string[]` | — | Expanded node ids (controlled). |
| defaultExpanded | `string[]` | `[]` | Node ids expanded on first render (uncontrolled). |
| onExpandedChange | `(expanded: string[]) => void` | — | Called with the new list of expanded ids when a folder opens or closes. |
| selected | `string \| null` | — | Selected node id (controlled). |
| defaultSelected | `string \| null` | `null` | Node id selected on first render (uncontrolled). |
| onSelectedChange | `(id: string \| null, node: TreeExpandNode \| null) => void` | — | Called with the id and node when a row is clicked or chosen with Enter or Space. |
| guides | `boolean` | `true` | Draw vertical indentation guides. |
| indent | `number` | `18` | Pixels per nesting level. |
| toggleOnSelect | `boolean` | `true` | Clicking a parent row (or pressing Enter on it) also expands or collapses it. |
| label | `string` | `"Tree"` | Accessible name of the tree. |

Also accepts every <ul> attribute.

## Keyboard

| Keys | Action |
| --- | --- |
| ArrowDown / ArrowUp | Moves focus to the next or previous visible row (no wrap). |
| ArrowRight | On a closed folder, expands it; on an open folder, moves to its first child. Mirrored (ArrowLeft) under dir="rtl". |
| ArrowLeft | On an open folder, collapses it; otherwise moves to the parent folder. Mirrored (ArrowRight) under dir="rtl". |
| Home / End | Moves focus to the first or last visible row. |
| Enter / Space | Selects the focused row; on a folder with toggleOnSelect, also opens or closes it. |
| a–z, 0–9 | Type-ahead: jumps to the next visible row whose label starts with the typed letters (letters typed within 600 ms combine). |
| Tab | The tree is one tab stop; focus enters on the focused, selected or first row. |

## Accessibility

- Uses the ARIA tree pattern: role="tree" named by label, role="treeitem" rows with aria-level, aria-expanded on folders, aria-selected, and role="group" for children.
- Roving tabindex: only one row is in the tab order, the rest are reached with the arrow keys.
- Disabled nodes get aria-disabled and cannot be selected; clicks, the chevron, Enter and the arrow keys never expand or collapse them, but they stay reachable with the arrow keys.
- The focus ring is drawn on the row only, not around the whole open subtree.
- Icons, chevrons and the selection highlight are aria-hidden.

## Motion

- Children open by animating height to auto on a spring (bounce 0, 0.34 s) with a 0.2 s fade in and a 0.14 s fade out.
- The chevron turns 90° and the selection highlight glides from row to row (shared layoutId), both on a spring (stiffness 500, damping 40).
- Reduced motion: all of these use duration 0, so folders open and the selection moves instantly.

## Notes for AI

- Node ids must be unique across the whole tree, not just among siblings.
- A node is a folder only if it has a non-empty children array; folder icons are just icon/openIcon.
- onSelectedChange fires for folders too; check node.children to accept only leaves.
- When passing selected (controlled), update it from onSelectedChange or the selection never moves.
- label on a node must be plain text: it is used for type-ahead.

## FAQ

**How do I expand or collapse everything?**

Pass expanded and onExpandedChange, then set expanded to every folder id, or to [].

**Can a folder be selected without opening it?**

Yes, set toggleOnSelect={false}. Clicking the row selects it; clicking the chevron or pressing ArrowRight/ArrowLeft opens and closes it.

## Related

- accordion-height: https://goodui.dev/components/lists/accordion-height
- expandable-row-list: https://goodui.dev/components/lists/expandable-row-list
- command-palette-morph: https://goodui.dev/components/navigation/command-palette-morph

Last updated: 2026-11-02

---

# Expandable row list

> Appointment rows that open inline into a raised card with notes and working actions, while neighbouring rows smoothly make room.

Expandable list rows for React and shadcn that open inline into a detail card

Page: https://goodui.dev/components/lists/expandable-row-list

## Install

```bash
npx shadcn@latest add @goodui/expandable-row-list
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/expandable-row-list.json`. The file lands in `components/goodui/expandable-row-list.tsx`.

## When to use

- Lists of records where details and actions only matter for one at a time: appointments, invoices, orders.
- Mobile-friendly alternative to a details page or side panel: the row opens in place and keeps context.
- Schedules where the row summary (time, client, status) is enough to scan, and notes or actions sit one tap away.

## When not to use

- Plain question-and-answer or settings sections with a title: use accordion-height.
- Data that needs columns, sorting and comparison across rows: use table-row-presence.
- A single card that expands into a large view: use expandable-card or morphing-dialog.

## Pick by what matters

| Need | Use |
| --- | --- |
| Focus on one record at a time | type="single" (default) |
| Compare details of several rows | type="multiple" |
| Tighter or looser lift around the open row | gap (default 10, px) |

## Usage

```tsx
import { ExpandableRowList } from "@/components/goodui/expandable-row-list"

type Appointment = { id: string; time: string; client: string; service: string; notes: string }

export function TodaySchedule({ appointments, onCancel }: { appointments: Appointment[]; onCancel: (id: string) => void }) {
  return (
    <ExpandableRowList
      items={appointments}
      getKey={(a) => a.id}
      renderRow={(a, { expanded }) => (
        <div className="flex items-center gap-3">
          <span className="w-12 shrink-0 text-xs font-medium tabular-nums">{a.time}</span>
          <div className="min-w-0 flex-1">
            <p className="truncate text-sm font-medium">{a.client}</p>
            <p className="truncate text-xs text-muted-foreground">{expanded ? "Details below" : a.service}</p>
          </div>
        </div>
      )}
      renderDetails={(a, { collapse }) => (
        <div className="space-y-3 text-sm">
          <p className="text-muted-foreground">{a.notes}</p>
          <div className="flex gap-2">
            <button type="button" onClick={collapse}>Close</button>
            <button type="button" onClick={() => onCancel(a.id)}>Cancel appointment</button>
          </div>
        </div>
      )}
    />
  )
}
```

### Controlled, several rows open

```tsx
const [open, setOpen] = React.useState<string[]>([])

<ExpandableRowList
  type="multiple"
  value={open}
  onValueChange={setOpen}
  items={invoices}
  getKey={(i) => i.id}
  renderRow={(i) => <InvoiceSummary invoice={i} />}
  renderDetails={(i) => <InvoiceLines invoice={i} />}
/>
```

## API

### ExpandableRowList

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| items (required) | `T[]` | — | Rows in display order. Adding or removing items animates the row height in or out. |
| getKey (required) | `(item: T) => string` | — | Stable unique key of a row. Any characters are fine: it is escaped before it goes into element ids. |
| renderRow (required) | `(item: T, state: { expanded: boolean }) => React.ReactNode` | — | The always-visible summary of a row. Keep it free of buttons: the whole row is the toggle. |
| renderDetails (required) | `(item: T, state: { collapse: () => void }) => React.ReactNode` | — | Details shown when the row opens. `collapse` closes it and returns focus to the row. |
| type | `"single" \| "multiple"` | `"single"` | "single" opens one row at a time. |
| value | `string[]` | — | Expanded row keys (controlled). |
| defaultValue | `string[]` | `[]` | Row keys open on first render (uncontrolled). |
| onValueChange | `(value: string[]) => void` | — | Called with the new list of open row keys when a row opens or closes. |
| gap | `number` | `10` | Space the open row lifts away from its neighbours, in px. |

Also accepts every <ul> attribute.

## Keyboard

| Keys | Action |
| --- | --- |
| Enter / Space | Opens or closes the focused row (native <button>). |
| ArrowDown / ArrowUp | Moves focus to the next or previous row, stopping at the ends. |
| Home / End | Moves focus to the first or last row. |
| Escape | With focus anywhere in an open row, including its details, closes it and returns focus to the row. |

## Accessibility

- Each row summary is a native <button> with aria-expanded and aria-controls pointing at its details while they are open (closed details are not in the DOM).
- Open details have role="region" and aria-labelledby set to the row, and unmount when closed.
- collapse() from renderDetails closes the row and moves focus back to its button, so keyboard users are not left on a removed element.
- renderRow renders inside the button: keep it free of buttons and links (nested interactive elements are invalid).

## Motion

- The open row lifts away from its neighbours by gap/2 above and below and becomes a bordered card with a shadow; margins and height move on a spring (bounce 0.12, 0.42 s), the card colors on a 300 ms CSS transition.
- Details grow to their height on the same spring; their opacity fades in over 0.18 s after 0.06 s, and the content slides down 6px.
- The chevron turns 180° on a spring (stiffness 420, damping 30).
- Rows added to or removed from items grow in or collapse out the same way.
- Reduced motion: every transition has duration 0; rows open, close, lift and appear instantly.

## Notes for AI

- Put actions (buttons, links) in renderDetails, never in renderRow, which renders inside the toggle button.
- getKey must be stable and unique, and free of spaces: it is used in element ids for aria-controls.
- Use the collapse function passed to renderDetails for Close or after an action, so focus returns to the row.
- In single mode, clicking the open row closes it; there is no prop to keep one row always open.
- Details unmount when the row closes: keep edited values in a parent if they must survive.

## FAQ

**How is this different from accordion-height?**

accordion-height renders a fixed header (icon, title, description). Here you render the whole row and the details yourself, and the open row lifts into a card, which suits records with actions.

**Can I remove a row from inside its details?**

Yes. Remove the item from the items array (for example in a Cancel handler); the row collapses out and its neighbours close the gap.

## Related

- accordion-height: https://goodui.dev/components/lists/accordion-height
- table-row-presence: https://goodui.dev/components/lists/table-row-presence
- expandable-card: https://goodui.dev/components/cards/expandable-card
- morphing-dialog: https://goodui.dev/components/overlays/morphing-dialog

Last updated: 2026-11-02

---

# Tag input

> Chips input where Enter, comma or paste adds tags that spring in, Backspace arms then removes, duplicates shake, with a filtered suggestions dropdown, validation and a max count.

Tag input (chips input) with suggestions for React and shadcn

Page: https://goodui.dev/components/inputs/tag-input

## Install

```bash
npx shadcn@latest add @goodui/tag-input
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/tag-input.json`. The file lands in `components/goodui/tag-input.tsx`.

## When to use

- Free-form lists of short values: skills, service names, labels, email invites.
- When users paste lists: comma, semicolon, tab or newline separated text becomes separate tags in one go.
- When you want to suggest known values but still accept new ones (suggestions plus free typing).
- Capped lists such as "invite up to 4 teammates", with a visible n/max counter.

## When not to use

- Choosing from a fixed list only, with no free text: use select or a group of checkbox items.
- A single value: use input or floating-label-input.
- Searching or running commands: use search-expand or command-palette-morph.

## Pick by what matters

| Need | Use |
| --- | --- |
| Known vocabulary, new values allowed | suggestions={[...]} (up to 6 matches show, already-added ones are hidden) |
| Strict format such as emails | validate={(t) => ok ? true : "error message"} |
| A hard limit | maxTags={n}; the input becomes read-only when full |
| "Design" and "design" are different | caseSensitive |
| Submitting with a plain <form> | name="tags" (posts one comma-joined hidden input) |

## Usage

```tsx
import * as React from "react"
import { TagInput } from "@/components/goodui/tag-input"

const SERVICES = ["Deep clean", "Move-out clean", "Window washing", "Carpet shampoo", "Oven interior"]

export function ServicesField() {
  const [services, setServices] = React.useState<string[]>(["Deep clean"])

  return (
    <div className="grid gap-2">
      <label htmlFor="services" className="text-sm font-medium">
        Services offered
      </label>
      <TagInput
        inputId="services"
        value={services}
        onValueChange={setServices}
        suggestions={SERVICES}
        placeholder="Type or pick a service…"
      />
    </div>
  )
}
```

### Email invites with validation and a limit

```tsx
const EMAIL = /^[^\s@]+@[^\s@]+\.[^\s@]{2,}$/

<TagInput
  aria-label="Invite teammates"
  value={invites}
  onValueChange={setInvites}
  maxTags={4}
  placeholder="name@company.com"
  validate={(t) => (EMAIL.test(t) ? true : `"${t}" is not a valid email`)}
/>
```

### Colored dot per tag and native form submit

```tsx
<TagInput
  name="labels"
  defaultValue={["Urgent", "VIP"]}
  renderTag={(t) => <span aria-hidden="true" className={`size-1.5 rounded-full ${t === "Urgent" ? "bg-rose-500" : "bg-emerald-500"}`} />}
/>
```

## API

### TagInput

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| value | `string[]` | — | Controlled list of tags. Pair with `onValueChange`. |
| defaultValue | `string[]` | — | Initial tags when uncontrolled. |
| onValueChange | `(tags: string[]) => void` | — | Called with the full new list whenever a tag is added or removed. |
| suggestions | `string[]` | `[]` | Offered in a dropdown while typing. Already-added tags are hidden. |
| maxTags | `number` | — | Maximum number of tags; shows an "n/max" counter and makes the input read-only when full. |
| placeholder | `string` | `"Add a tag…"` | Shown only while there are no tags. |
| validate | `(tag: string) => true \| string` | — | Return `true` to accept, or an error message to reject the tag. |
| caseSensitive | `boolean` | `false` | Treat "Design" and "design" as different tags. |
| name | `string` | — | Form field name; tags are submitted comma-separated in a hidden input. |
| disabled | `boolean` | — |  |
| inputId | `string` | — | id of the text input, for an external `<label htmlFor>`. |
| renderTag | `(tag: string) => React.ReactNode` | — | Optional visual for each chip (an icon, an avatar…). |
| labels | `Partial<TagInputLabels>` | — | Text for built-in controls and screen readers; pass translations here. |

Also accepts every <div> attribute.

## Keyboard

| Keys | Action |
| --- | --- |
| Enter / , | Adds the typed text as a tag, or the highlighted suggestion when one is highlighted. |
| Backspace | In an empty input: the first press highlights the last tag, the second removes it. |
| ArrowDown / ArrowUp | Opens the suggestions and moves the highlight, wrapping at the ends. |
| Escape | Closes the suggestions list when it is open. |

## Accessibility

- The text input is a combobox (aria-expanded, aria-controls, aria-autocomplete="list", aria-activedescendant) and the suggestions are a listbox of options.
- Added, removed, duplicate and limit messages are announced through a polite role="status" region; the texts come from the labels prop.
- Rejected tags set aria-invalid and link the visible error with aria-describedby.
- Each chip's remove button is a real button in the Tab order with an aria-label (labels.remove); Backspace in the empty input also removes the last tag. Focus returns to the input after a removal.
- Without inputId and an external <label htmlFor>, pass aria-label; the default name is labels.input ("Add tags").

## Motion

- Chips spring in from scale 0.6 with a blur (stiffness 500, damping 32) and leave in 0.15 s; neighbours glide with layout animation.
- A duplicate makes the existing chip shake for 0.4 s; an invalid tag or a full list shakes the whole field.
- The suggestions list springs open (stiffness 600, damping 38) and the highlight glides between options on a shared layout spring.
- Reduced motion: chips and the list only fade, shakes are skipped, layout animation and the highlight glide are off.

## Notes for AI

- Use value + onValueChange (string[]); there is no onChange for the tag list. The root's other props go to the outer <div>.
- All built-in text (remove, duplicate, limit, added, addedMany, removed, input) comes from the labels prop; pass translations there.
- validate returns true or an error string, not a boolean false.
- Link an external label with inputId + <label htmlFor>, or pass aria-label; do not put the label inside the component.
- Matching is case-insensitive by default, so "deep clean" counts as a duplicate of "Deep clean".
- Do not add a separate remove keyboard shortcut or an add button; Enter, comma, paste and Backspace already cover it.

## FAQ

**How do I submit the tags with a normal form?**

Pass name. A hidden input with that name holds the tags joined by commas.

**What happens when someone pastes a list?**

If the pasted text contains commas, semicolons, tabs or newlines it is split and every part goes through the same duplicate, limit and validate checks. Plain text without separators is pasted normally.

**Can I translate the messages?**

Yes. Pass labels with your own remove, duplicate, limit, added, addedMany and removed functions, and the input name string.

## Related

- input: https://goodui.dev/components/core/input
- floating-label-input: https://goodui.dev/components/inputs/floating-label-input
- select: https://goodui.dev/components/core/select
- badge: https://goodui.dev/components/core/badge

Last updated: 2026-11-02

---

# OTP input

> One-time code input from plain inputs with auto-advance, paste and SMS autofill, a blinking caret and popping digits, then a pulsing verify, green success bounce or red shake.

OTP input (one-time code, 2FA, PIN) for React and shadcn

Page: https://goodui.dev/components/inputs/otp-input

## Install

```bash
npx shadcn@latest add @goodui/otp-input
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/otp-input.json`. The file lands in `components/goodui/otp-input.tsx`.

## When to use

- Email or SMS verification codes during sign-up, login or checkout.
- Two-factor codes from an authenticator app.
- Short PINs such as a front-desk or register unlock, with mask on.
- When you want built-in verifying, success and error states driven by one async onComplete.

## When not to use

- Passwords or codes of unknown length: use input with type="password".
- Long license or coupon keys with mixed separators: use input or floating-label-input.
- Showing validation on an ordinary field: use input-shake around an input.

## Pick by what matters

| Need | Use |
| --- | --- |
| 6-digit SMS or email code | defaults (length 6, allow="numeric", groupSize 3) |
| Letters and digits, e.g. backup codes | allow="alphanumeric" (input is upper-cased) |
| PIN that should not be read over a shoulder | mask groupSize={0} length={4} |
| Check the code on your server | onComplete={async (c) => (await verify(c))} returning true or false |
| Status decided outside the component | status="verifying" \| "success" \| "error" \| "idle" |

## Usage

```tsx
import { OtpInput } from "@/components/goodui/otp-input"

export function VerifyEmail({ email }: { email: string }) {
  return (
    <div className="grid justify-items-center gap-3 text-center">
      <p className="text-sm text-muted-foreground">
        We sent a 6-digit code to <span className="font-medium text-foreground">{email}</span>
      </p>
      <OtpInput
        autoFocus
        name="code"
        onComplete={async (code) => {
          const res = await fetch("/api/verify-email", { method: "POST", body: JSON.stringify({ code }) })
          return res.ok
        }}
      />
    </div>
  )
}
```

### Masked 4-digit PIN with an instant check

```tsx
<OtpInput length={4} groupSize={0} mask aria-label="Front-desk PIN" onComplete={(pin) => pin === storedPin} />
```

### Controlled, with status from your own state

```tsx
const [code, setCode] = React.useState("")
const [status, setStatus] = React.useState<OtpStatus>("idle")

<OtpInput
  value={code}
  onValueChange={setCode}
  status={status}
  onComplete={async (c) => {
    setStatus("verifying")
    const ok = await verifyCode(c)
    setStatus(ok ? "success" : "error")
    return ok
  }}
/>
```

## API

### OtpInput

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| autoFocus | `boolean` | — | Focus the first cell on mount. |
| length | `number` | `6` | Number of cells. |
| value | `string` | — | Controlled code (no gaps, at most `length` characters). Pair with `onValueChange`. |
| defaultValue | `string` | `""` | Initial code when uncontrolled. |
| onValueChange | `(code: string) => void` | — | Called with the current code on every change, including paste, autofill and clear-on-error. |
| onComplete | `(code: string) => void \| boolean \| Promise<boolean \| void>` | — | Called once every cell is filled. Return (or resolve) `true` for success, `false` for error. While a returned promise is pending the cells pulse and are read-only. |
| status | `"idle" \| "verifying" \| "success" \| "error"` | — | Force a status from outside (e.g. after your own server check). |
| allow | `"numeric" \| "alphanumeric"` | `"numeric"` | Allowed characters. |
| mask | `boolean` | `false` | Show dots instead of characters (PINs). |
| groupSize | `number` | `3` | Put a separator after every N cells; 0 for none. |
| clearOnError | `boolean` | `true` | Empty the cells and refocus the first one after an error. |
| disabled | `boolean` | — |  |
| name | `string` | — | Form field name for a hidden input with the full code. |
| labels | `Partial<OtpInputLabels>` | — | Text for built-in controls and screen readers; pass translations here. |

Also accepts every <div> attribute.

## Keyboard

| Keys | Action |
| --- | --- |
| 0-9 (or letters with allow="alphanumeric") | Fills the cell and moves focus to the next one. |
| Backspace | Removes the character in the cell; on an empty cell removes the previous one and moves back. Later characters shift left. |
| Delete | Removes the character in the current cell; later characters shift left. |
| ArrowLeft / ArrowRight | Moves to the previous or next cell; ArrowRight only moves from a filled cell. |
| Home / End | Moves to the first cell, or to the first empty cell (the last cell when full). |

## Accessibility

- Cells are native <input> elements in a role="group" named by aria-label (default "Verification code"); each cell is labelled "Character n of length" through labels.character.
- The first cell has autoComplete="one-time-code", so iOS and Android can offer the SMS code; numeric mode sets inputMode="numeric".
- Verifying, success and error are announced in a polite role="status" region (labels.verifying, labels.success, labels.error). Cells get aria-invalid on error.
- Focusing a cell after the first empty one jumps to the first empty cell, so the code never has gaps.
- mask only hides the characters visually (dots); the inputs are not type="password".

## Motion

- Each digit pops in from below with a spring (stiffness 700, damping 26); an empty focused cell shows a caret blinking every 1.05 s.
- While a promise from onComplete is pending, the cells pulse in opacity on a 1 s loop, staggered by 90 ms per cell, and are read-only.
- Success bounces each cell up 6px for 0.4 s, staggered by 45 ms; error shakes the row for 0.45 s, and with clearOnError the cells empty and the first one is focused 650 ms later.
- Reduced motion: digits only fade, the caret stops blinking, and the pulse, bounce and shake are off. Clearing after an error still happens.

## Notes for AI

- Return true or false (or a promise of one) from onComplete; returning nothing leaves the status idle. A rejected promise counts as false.
- onComplete fires whenever the code becomes full, including paste, autofill and a parent setting value, so do not also call your verify from onValueChange.
- Pass status only if you manage it yourself; otherwise let onComplete drive it.
- Success and verifying lock the cells. To start over, set value to "" (controlled) or remount; there is no reset method.
- Do not render your own hidden input; use name to submit the code with a form.

## FAQ

**Does paste work?**

Yes. Pasted text is filtered to the allowed characters; a full-length paste always replaces the whole code, a shorter one fills from the focused cell.

**Does SMS autofill work?**

The first cell has autoComplete="one-time-code". When the browser fills it with the whole code, the code is spread over the cells and onComplete fires.

**How do I keep the wrong code visible after an error?**

Set clearOnError={false}. The row still shakes and the cells turn red.

## Related

- input-shake: https://goodui.dev/components/inputs/input-shake
- success-check: https://goodui.dev/components/feedback/success-check
- input: https://goodui.dev/components/core/input
- stepper: https://goodui.dev/components/navigation/stepper

Last updated: 2026-11-02

---

# Floating label input

> Input and textarea whose label springs up on focus or value, with prefix/suffix slots that fade in, an animated clear button, character counter and a slide-in error.

Floating label input and textarea for React and shadcn

Page: https://goodui.dev/components/inputs/floating-label-input

## Install

```bash
npx shadcn@latest add @goodui/floating-label-input
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/floating-label-input.json`. The file lands in `components/goodui/floating-label-input.tsx`.

## When to use

- Compact forms (checkout, billing, profile) where a label above every field takes too much room.
- Fields with a unit or fixed part: a currency prefix, "/hr", a domain suffix.
- Notes and messages with a length limit: FloatingLabelTextarea shows a counter that turns amber above 90%.
- Fields that need a clear button and an error that slides in under them.

## When not to use

- Dense settings pages and tables: a plain input with a label above scans faster.
- Several values in one field: use tag-input.
- Validation feedback around an input you already have (shadcn Input, select): use input-shake.

## Pick by what matters

| Need | Use |
| --- | --- |
| Single-line text, email, numbers | FloatingLabelInput |
| Multi-line notes with a limit | FloatingLabelTextarea with maxLength (counter appears) |
| Money or units | prefix="$" and/or suffix="/hr" (shown once the label floats) |
| Search-like fields people often reset | clearable (add onClear to react) |

## Usage

```tsx
import * as React from "react"
import { FloatingLabelInput } from "@/components/goodui/floating-label-input"

const EMAIL = /^[^\s@]+@[^\s@]+\.[^\s@]{2,}$/

export function BillingEmail() {
  const [email, setEmail] = React.useState("")
  const [touched, setTouched] = React.useState(false)
  const error = touched && !EMAIL.test(email) ? "Enter a valid email, like maya@brightclean.co" : undefined

  return (
    <FloatingLabelInput
      label="Billing email"
      type="email"
      autoComplete="email"
      value={email}
      onValueChange={setEmail}
      onBlur={() => setTouched(true)}
      error={error}
      description="Invoices and payout receipts go here."
      clearable
    />
  )
}
```

### Rate with prefix and suffix

```tsx
<FloatingLabelInput label="Hourly rate" inputMode="decimal" prefix="$" suffix="/hr" defaultValue="65" />
```

### Notes with a character counter

```tsx
import { FloatingLabelTextarea } from "@/components/goodui/floating-label-input"

<FloatingLabelTextarea
  label="Notes for your cleaner"
  placeholder="Gate code, parking, pets, rooms to skip…"
  maxLength={160}
  clearable
/>
```

## API

### FloatingLabelInput

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| label (required) | `React.ReactNode` | — | Text that sits inside the field and floats up on focus or when there is a value. |
| error | `React.ReactNode` | — | Error message; slides in under the field and turns it red. |
| description | `React.ReactNode` | — | Helper text shown when there is no error. |
| clearable | `boolean` | — | Show a clear (×) button when the field has a value. |
| onValueChange | `(value: string) => void` | — | Called with the new string on typing and on clear. The clear button also fires `onChange` with a real change event. |
| onClear | `() => void` | — | Called after the clear button empties the field. |
| inputClassName | `string` | — | Classes for the native input/textarea; `className` styles the root. |
| labels | `Partial<FloatingLabelInputLabels>` | — | Text for built-in controls and screen readers; pass translations here. |
| prefix | `React.ReactNode` | — | Shown before the value once the label floats, e.g. "$" or "https://". |
| suffix | `React.ReactNode` | — | Shown after the value once the label floats, e.g. "/hr" or ".com". |

Also accepts every <input> attribute.

### FloatingLabelTextarea

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| label (required) | `React.ReactNode` | — | Text that sits inside the field and floats up on focus or when there is a value. |
| error | `React.ReactNode` | — | Error message; slides in under the field and turns it red. |
| description | `React.ReactNode` | — | Helper text shown when there is no error. |
| clearable | `boolean` | — | Show a clear (×) button when the field has a value. |
| onValueChange | `(value: string) => void` | — | Called with the new string on typing and on clear. The clear button also fires `onChange` with a real change event. |
| onClear | `() => void` | — | Called after the clear button empties the field. |
| inputClassName | `string` | — | Classes for the native input/textarea; `className` styles the root. |
| labels | `Partial<FloatingLabelInputLabels>` | — | Text for built-in controls and screen readers; pass translations here. |

Also accepts every <textarea> attribute.

## Keyboard

| Keys | Action |
| --- | --- |
| Tab | Moves from the field to the clear button when it is shown (a native <button>; Enter or Space clears and refocuses the field). |

## Accessibility

- The label is a real <label htmlFor> tied to the native input or textarea, so clicking it focuses the field.
- error and description are linked with aria-describedby; the error has role="alert" and sets aria-invalid.
- The textarea counter becomes a polite live region once the value passes 90% of maxLength.
- prefix and suffix are aria-hidden; put the unit in the label too if it matters ("Hourly rate (USD)").
- The clear button's aria-label is labels.clear(label) ("Clear <label>", or "Clear field" via labels.field when label is not a string); pass labels to translate it.

## Motion

- The label moves up and scales to 0.78 on a spring (stiffness 520, damping 36) when the field is focused, has a value, or is filled by browser autofill.
- prefix and suffix fade in over 0.15 s once the label floats; the placeholder fades in only while focused.
- The clear button spins in from -90° and scale 0.5 on the same spring; the error slides down and grows to its height in 0.2 s.
- Reduced motion: the label jumps without a spring, the clear button and error only fade.

## Notes for AI

- Prefer onValueChange(value: string). onChange also works: the clear button fires a real input event, so onChange, onValueChange and onClear all run on clear (react-hook-form register works).
- Built-in text comes from the labels prop: clear(label) and field; pass translations there.
- className styles the outer wrapper; use inputClassName for the native input or textarea.
- label is required. placeholder is hidden until the field is focused, so do not rely on it as the label.
- FloatingLabelTextarea has no prefix or suffix; maxLength turns on the counter.
- Pass error only when there is one (undefined otherwise); any truthy error turns the field red and replaces description.

## FAQ

**Does it work with browser autofill?**

Yes for the input. A no-op CSS animation on :-webkit-autofill tells the component the field was filled, so the label floats even before a change event.

**Does the textarea grow with its content?**

It uses field-sizing: content, so it grows up to max-h-48 in browsers that support it and stays at its minimum height elsewhere.

## Related

- input: https://goodui.dev/components/core/input
- input-shake: https://goodui.dev/components/inputs/input-shake
- tag-input: https://goodui.dev/components/inputs/tag-input
- search-expand: https://goodui.dev/components/inputs/search-expand

Last updated: 2026-11-02

---

# Vanish input

> Search field with rotating, blurred-in placeholder hints; on submit the typed text dissolves into drifting particles drawn on a canvas.

Vanishing input with rotating placeholders and particle submit for React

Page: https://goodui.dev/components/inputs/vanish-input

## Install

```bash
npx shadcn@latest add @goodui/vanish-input
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/vanish-input.json`. The file lands in `components/goodui/vanish-input.tsx`.

## When to use

- A hero search or "Ask AI" prompt where the rotating hints teach what people can type.
- One-shot submissions (a question, a quick add) where the text clearing itself confirms it was sent.
- Landing pages and empty states that want one memorable input.

## When not to use

- Search that filters results as you type: use search-expand or a plain input; the dissolve only happens on submit.
- Form fields people need to review after submitting: use floating-label-input, the text is cleared on submit.
- Several on one screen: keep the effect to one primary input.

## Usage

```tsx
import { VanishInput } from "@/components/goodui/vanish-input"

const HINTS = ["Search Maya Chen", "Find invoice INV-2041", "Bookings next Tuesday", "Unpaid invoices over $500"]

export function GlobalSearch({ onSearch }: { onSearch: (q: string) => void }) {
  return (
    <VanishInput
      placeholders={HINTS}
      label="Search clients, bookings and invoices"
      submitLabel="Search"
      onSubmit={onSearch}
    />
  )
}
```

### Scheduling assistant prompt

```tsx
<VanishInput
  placeholders={["Move Friday's 9am to Monday", "Who hasn't booked in 60 days?"]}
  interval={3600}
  label="Ask the scheduling assistant"
  submitLabel="Ask"
  className="h-11 rounded-xl"
  onSubmit={(prompt) => sendToAssistant(prompt)}
/>
```

### Controlled, e.g. to refill from recent searches

```tsx
const [query, setQuery] = React.useState("")

<VanishInput value={query} onValueChange={setQuery} onSubmit={addToRecent} label="Search" />
<button type="button" onClick={() => setQuery("INV-2038")}>INV-2038</button>
```

## API

### VanishInput

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| name | `string` | — | name attribute of the text input, for native form handling. |
| placeholders | `string[]` | `["Search…"]` | Hints that rotate while the field is empty. |
| interval | `number` | `3000` | Milliseconds between placeholder changes. |
| value | `string` | — | Controlled text. It is set to "" when the text is submitted. |
| defaultValue | `string` | `""` | Initial text when uncontrolled. |
| onValueChange | `(value: string) => void` | — | Called on every keystroke, and with "" when the text is submitted. |
| onSubmit | `(value: string) => void` | — | Called with the text when the user presses Enter or the arrow button; the text then dissolves. |
| label | `string` | — | Accessible name of the input (defaults to the first placeholder). |
| submitLabel | `string` | `"Submit"` | aria-label of the arrow submit button. |
| inputClassName | `string` | — | Classes for the native input; `className` styles the pill-shaped form. |

Also accepts every <form> attribute.

## Keyboard

| Keys | Action |
| --- | --- |
| Enter | Submits the form: calls onSubmit with the trimmed text, then clears the field. Ignored when the text is empty or still dissolving. |

## Accessibility

- Renders a real <form> with a text <input> and a submit <button>, so Enter and the button both submit.
- The input's accessible name is label, or the first placeholder when label is not set; the rotating hints are aria-hidden.
- The arrow button is named by submitLabel (default "Submit") and is disabled while the field is empty.
- The particle canvas is aria-hidden. Nothing is announced on submit; announce the result yourself if it matters.

## Motion

- Placeholders change every interval ms (default 3000) while the field is empty: the old one slides up and blurs out, the new one rises in, 0.3 s each.
- On submit the text is drawn to a canvas and sampled into particles that drift up and to the right and fade, the end of the text first; the effect runs for at most 120 frames.
- The arrow icon sits rotated -90° while empty and springs upright (stiffness 500, damping 28) once there is text.
- Reduced motion: no particles, the field just clears; placeholders cross-fade in 0.15 s instead of sliding, and the arrow does not rotate.

## Performance

- Placeholder rotation stops while the field has text and while the tab is hidden.
- The particle loop runs only after a submit, stops when the tab is hidden, and is cancelled on unmount; the canvas resolution is capped at 2x device pixel ratio.

## Notes for AI

- onSubmit receives the trimmed string; the component clears the field itself, so do not reset value in onSubmit.
- Props other than the listed ones go to the <form>; there is no native onSubmit event passthrough.
- Give label when the placeholders are examples rather than a description of the field.
- className styles the pill-shaped form (height, radius); inputClassName styles the input.
- Keep placeholders short; long ones are truncated.

## FAQ

**What happens with reduced motion?**

The dissolve is skipped and the field simply clears after submit; placeholders still rotate, with a short fade.

**Can I keep the text after submitting?**

No, clearing is part of the effect. Use floating-label-input or input if the text should stay.

## Related

- search-expand: https://goodui.dev/components/inputs/search-expand
- command-palette-morph: https://goodui.dev/components/navigation/command-palette-morph
- floating-label-input: https://goodui.dev/components/inputs/floating-label-input
- typewriter: https://goodui.dev/components/text/typewriter

Last updated: 2026-11-02

---

# Input shake

> Validation wrapper for any input that shakes and slides in an error with an icon when invalid, and draws a check circle when valid.

Input validation with shake animation and error message for React and shadcn

Page: https://goodui.dev/components/inputs/input-shake

## Install

```bash
npx shadcn@latest add @goodui/input-shake
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/input-shake.json`. The file lands in `components/goodui/input-shake.tsx`.

## When to use

- Sign-up and login forms where a failed submit should be impossible to miss.
- Wrapping inputs you already have (shadcn Input, a native <select>) to add an error, a success check and a label without rebuilding them.
- Server-side errors ("This email already has a workspace") that should shake the field again on each failed submit.

## When not to use

- Errors while the user is still typing: show them on blur or submit; a shake on every keystroke is noise.
- Building a field from scratch: floating-label-input already has its own error slot.
- One-time codes: otp-input has its own error shake and success bounce.

## Usage

```tsx
import * as React from "react"
import { Input } from "@/components/ui/input"
import { InputShake, type InputShakeStatus } from "@/components/goodui/input-shake"

const EMAIL = /^[^\s@]+@[^\s@]+\.[^\s@]{2,}$/

export function WorkEmailField() {
  const [email, setEmail] = React.useState("")
  const [touched, setTouched] = React.useState(false)
  const [attempt, setAttempt] = React.useState(0)
  const error = !email ? "Enter your work email" : !EMAIL.test(email) ? "That email looks incomplete" : null
  const status: InputShakeStatus = !touched ? "idle" : error ? "invalid" : "valid"

  return (
    <form
      noValidate
      className="grid gap-3"
      onSubmit={(e) => {
        e.preventDefault()
        setTouched(true)
        setAttempt((a) => a + 1)
      }}
    >
      <InputShake label="Work email" status={status} message={error} successMessage="Looks good" shakeKey={attempt}>
        <Input type="email" value={email} onChange={(e) => setEmail(e.target.value)} onBlur={() => setTouched(true)} />
      </InputShake>
      <button type="submit">Create workspace</button>
    </form>
  )
}
```

### Native select with a hint

```tsx
<InputShake label="Plan" status={plan ? "valid" : touched ? "invalid" : "idle"} message="Pick a plan" hint="You can change it later.">
  <select className="h-9 w-full rounded-md border px-3" value={plan} onChange={(e) => setPlan(e.target.value)}>
    <option value="">Choose…</option>
    <option value="starter">Starter, $19/mo</option>
    <option value="pro">Pro, $49/mo</option>
  </select>
</InputShake>
```

## API

### InputShake

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| children (required) | `React.ReactElement<ChildProps>` | — | A single input-like element (native input, shadcn Input, select…). |
| status | `"idle" \| "invalid" \| "valid"` | `"idle"` | "invalid" shakes the field (on entry) and shows `message`; "valid" draws a check and shows `successMessage`. |
| message | `React.ReactNode` | — | Error text shown while invalid. |
| successMessage | `React.ReactNode` | — | Optional text shown while valid. |
| shakeKey | `number \| string` | — | Change this (e.g. a submit counter) to shake again while the field is still invalid. |
| label | `React.ReactNode` | — | Visible label rendered as a <label> linked to the child's id. |
| hint | `React.ReactNode` | — | Helper text shown when there is no message. |

Also accepts every <div> attribute.

## Accessibility

- label renders a <label> tied to the child's id (the child's own id is kept, or one is generated).
- The message (or hint) is linked to the child with aria-describedby, appended to any aria-describedby the child already has.
- While invalid the child gets aria-invalid and the error has role="alert", so it is read out when it appears. The success message has role="status", so it is announced politely.
- The error and check icons are decorative (aria-hidden); the text carries the meaning.

## Motion

- Becoming invalid shakes the field sideways for 0.42 s; changing shakeKey while still invalid shakes it again.
- The error icon spins in from -45° and scale 0.4 on a spring (stiffness 600, damping 22); the valid check draws its circle in 0.35 s and its tick in 0.25 s after a 0.18 s delay.
- The message slides down and grows to its height in 0.2 s; the hint only fades.
- Reduced motion: no shake, the icons and message only fade, and the check appears already drawn.

## Notes for AI

- Pass exactly one input-like element as children; it must accept id, className, aria-invalid and aria-describedby.
- The component does not validate. Compute status ("idle" | "invalid" | "valid") and message yourself.
- To shake on every failed submit, pass a counter as shakeKey and increment it in onSubmit.
- It adds pr-9 to the child for the icon; do not add your own icon on the right side.
- Keep status "idle" until the field is touched or submitted, so new forms do not open full of errors.

## FAQ

**Does it work with react-hook-form?**

Yes. Map fieldState.error to status="invalid" and message, and pass formState.submitCount as shakeKey.

**Why does it not shake on every keystroke?**

It shakes when status changes to invalid, or when shakeKey changes while invalid. Staying invalid while typing does not shake again.

## Related

- input: https://goodui.dev/components/core/input
- floating-label-input: https://goodui.dev/components/inputs/floating-label-input
- otp-input: https://goodui.dev/components/inputs/otp-input
- success-check: https://goodui.dev/components/feedback/success-check

Last updated: 2026-11-02

---

# Spring switch

> Switch with a springy thumb that squashes while pressed, icons that spin inside the thumb, three sizes, label and description.

Animated toggle switch for React and shadcn with a springy thumb and icons

Page: https://goodui.dev/components/inputs/switch-spring

## Install

```bash
npx shadcn@latest add @goodui/switch-spring
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/switch-spring.json`. The file lands in `components/goodui/switch-spring.tsx`.

## When to use

- Settings that take effect immediately: SMS reminders, auto-confirm bookings, email digests.
- Settings rows that need a label and a helper line that can change with the state.
- Mode toggles where an icon inside the thumb explains the state (sun/moon, check/x).

## When not to use

- A choice that is only applied when a form is submitted, or a list of items to tick: use checkbox-draw.
- Switching the whole site theme with a single icon button: use theme-toggle.
- Choosing between more than two options: use segmented-control.

## Pick by what matters

| Need | Use |
| --- | --- |
| Dense settings lists and tables | size="sm" |
| Standard settings rows | size="md" (default) with label and description |
| A prominent mode toggle | size="lg" with icons={{ on: <Moon />, off: <Sun /> }} |
| Label on the left, switch on the right (settings pages) | labelPosition="start" |

## Usage

```tsx
import * as React from "react"
import { SwitchSpring } from "@/components/goodui/switch-spring"

export function ReminderSettings() {
  const [sms, setSms] = React.useState(true)

  return (
    <div className="rounded-xl border bg-card p-4">
      <SwitchSpring
        checked={sms}
        onCheckedChange={setSms}
        label="SMS reminders"
        description={sms ? "Clients get a text 24 hours before each visit." : "Clients won't be reminded."}
        labelPosition="start"
      />
    </div>
  )
}
```

### Icons inside the thumb

```tsx
import { Moon, Sun } from "lucide-react"

<SwitchSpring
  size="lg"
  defaultChecked={false}
  icons={{ on: <Moon />, off: <Sun /> }}
  label="Quiet hours"
  description="Pause notifications from 9 pm to 7 am."
/>
```

### In a form, without a visible label

```tsx
<form action={saveBillingSettings}>
  <SwitchSpring name="autoRenew" defaultChecked aria-label="Auto-renew subscription" />
  <button type="submit">Save</button>
</form>
// Submits autoRenew=on or autoRenew=off
```

## API

### SwitchSpring

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| name | `string` | — | Form field name; a hidden input submits "on" when checked and "off" when not. |
| checked | `boolean` | — | Controlled on/off state; pair with onCheckedChange. |
| defaultChecked | `boolean` | `false` | Initial state when uncontrolled. |
| onCheckedChange | `(checked: boolean) => void` | — | Called with the new state on every toggle (click, Space or Enter). |
| size | `"sm" \| "md" \| "lg"` | `"md"` | "sm" 20×36px, "md" 24×44px, "lg" 32×56px track. |
| icons | `{ on: React.ReactNode; off: React.ReactNode }` | — | Icons drawn inside the thumb, e.g. { on: <Moon />, off: <Sun /> }. |
| label | `React.ReactNode` | — | Clickable label next to the switch; also its accessible name. |
| description | `React.ReactNode` | — | Muted helper text under the label, linked with aria-describedby. |
| labelPosition | `"start" \| "end"` | `"end"` | Put the label before the switch instead of after it. |

Also accepts every <button> attribute.

## Keyboard

| Keys | Action |
| --- | --- |
| Space / Enter | Toggles the switch (native <button>); the thumb squashes while the key is held. |
| Tab | Moves focus to the switch; a focus ring shows on keyboard focus only. |

## Accessibility

- Renders a native <button role="switch"> with aria-checked, so screen readers announce it as on or off.
- label renders a <label htmlFor> tied to the button, so clicking the text toggles it and it names the switch; description is linked with aria-describedby.
- Without label, pass aria-label so the switch has a name.
- The thumb and its icons are aria-hidden; the state comes from aria-checked only.

## Motion

- The thumb slides on a spring (stiffness 520, damping 24, mass 0.7).
- Pressing with the pointer or holding Space/Enter stretches the thumb to scaleX 1.22 and scaleY 0.9 on a stiffer spring, anchored to the side it rests on.
- Icons swap with a spin and scale: the old one turns away while the new one rotates in from ±120 degrees.
- The track color fades over 200 ms (CSS).
- Reduced motion: the thumb jumps without a spring, the squash is off, and icons cross-fade in 100 ms.

## Notes for AI

- Use checked + onCheckedChange (not value/onChange); onCheckedChange receives a boolean.
- className goes on the <button> track, not the wrapper; recolor the on state with a class like data-[state=checked]:bg-emerald-500.
- icons needs both on and off; pass lucide icons without size classes, the thumb sizes them.
- With name, the hidden input submits "on" or "off" (unlike a native checkbox, which omits unchecked values). Parse both on the server.
- Only sm, md and lg sizes exist; do not invent xs or xl.

## FAQ

**How do I change the on color?**

Pass a class for the checked state on className, e.g. data-[state=checked]:bg-emerald-500. By default it uses your theme's --primary.

**Does it submit with a form?**

Yes, when you pass name. A hidden input sends "on" when checked and "off" when not.

## Related

- switch: https://goodui.dev/components/core/switch
- checkbox-draw: https://goodui.dev/components/inputs/checkbox-draw
- theme-toggle: https://goodui.dev/components/buttons/theme-toggle
- segmented-control: https://goodui.dev/components/navigation/segmented-control

Last updated: 2026-11-02

---

# Drawn checkbox

> Checkbox whose check stroke draws itself in over a popping fill, with an indeterminate dash and an animated strike-through for checklists.

Animated checkbox for React and shadcn: drawn check, indeterminate dash, strike-through

Page: https://goodui.dev/components/inputs/checkbox-draw

## Install

```bash
npx shadcn@latest add @goodui/checkbox-draw
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/checkbox-draw.json`. The file lands in `components/goodui/checkbox-draw.tsx`.

## When to use

- Checklists and to-dos where ticking an item should feel done: onboarding steps, job checklists, launch tasks.
- A "select all" box above a list that shows a dash when only some items are selected.
- Consent and opt-in boxes in forms, with a label and helper text.

## When not to use

- A setting that applies immediately: use switch-spring.
- Picking one option out of several: use segmented-control.
- Plain form checkboxes where you want no motion at all: use checkbox.

## Pick by what matters

| Need | Use |
| --- | --- |
| Dense tables and row selection | size="sm" |
| Forms and settings | size="md" (default) with label and description |
| To-do lists | label plus strikethrough |
| Select all with partial selection | checked="indeterminate" when some, but not all, are selected |

## Usage

```tsx
import * as React from "react"
import { CheckboxDraw } from "@/components/goodui/checkbox-draw"

const TASKS = ["Confirm Friday's bookings", "Send invoice #1042", "Restock cleaning supplies"]

export function TodayChecklist() {
  const [done, setDone] = React.useState<string[]>([])
  const all = done.length === TASKS.length ? true : done.length === 0 ? false : "indeterminate"

  return (
    <div className="grid gap-3 rounded-xl border bg-card p-4">
      <CheckboxDraw
        checked={all}
        onCheckedChange={(v) => setDone(v ? TASKS : [])}
        label="Today's tasks"
        description={`${done.length} of ${TASKS.length} done`}
      />
      {TASKS.map((task) => (
        <CheckboxDraw
          key={task}
          checked={done.includes(task)}
          onCheckedChange={(v) => setDone((d) => (v ? [...d, task] : d.filter((t) => t !== task)))}
          label={task}
          strikethrough
        />
      ))}
    </div>
  )
}
```

### In a form

```tsx
<form action={createAccount}>
  <CheckboxDraw name="marketing" value="yes" label="Send me product updates" description="About one email a month." />
  <button type="submit">Create account</button>
</form>
// Submits marketing=yes when checked, marketing= (empty) when not
```

### Table row selection

```tsx
<CheckboxDraw size="sm" checked={selected.has(invoice.id)} onCheckedChange={(v) => toggle(invoice.id, v)} aria-label={`Select invoice ${invoice.number}`} />
```

## API

### CheckboxDraw

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| name | `string` | — | Form field name; renders a hidden input that submits `value` when checked and "" when not. |
| checked | `boolean \| "indeterminate"` | — | Controlled state: true, false or "indeterminate" (draws a dash, aria-checked="mixed"). |
| defaultChecked | `boolean \| "indeterminate"` | `false` | Initial state when uncontrolled; also accepts "indeterminate". |
| onCheckedChange | `(checked: boolean) => void` | — | Clicking an indeterminate box checks it. |
| size | `"sm" \| "md" \| "lg"` | `"md"` | Box size: "sm" 16px, "md" 20px, "lg" 24px. |
| label | `React.ReactNode` | — | Clickable label next to the box; also its accessible name. |
| description | `React.ReactNode` | — | Muted helper text under the label, linked with aria-describedby. |
| strikethrough | `boolean` | — | Draw a line through the label when checked (to-do lists). |
| value | `string` | `"on"` | Value submitted with `name` when checked. |

Also accepts every <button> attribute.

## Keyboard

| Keys | Action |
| --- | --- |
| Space / Enter | Toggles the checkbox (native <button>). From indeterminate it becomes checked. |
| Tab | Moves focus to the box; a focus ring shows on keyboard focus only. |

## Accessibility

- Renders a native <button role="checkbox"> with aria-checked set to true, false or "mixed" for indeterminate.
- label renders a <label htmlFor> tied to the box, so the text is clickable and names it; description is linked with aria-describedby.
- Without label, pass aria-label so the box has a name.
- The fill, check and dash are aria-hidden, and so is the strike-through line; the label text stays readable.

## Motion

- The fill pops from scale 0.4 on a spring (stiffness 600, damping 28) and fades in.
- The check stroke draws in over 240 ms after a 60 ms delay; the indeterminate dash draws in over 240 ms. Unchecking erases the stroke in 120 ms.
- Pressing scales the box to 0.82 with a short CSS overshoot (no focusable wrapper inside the aria-hidden mark).
- strikethrough: a line grows across the label over 320 ms after a 120 ms delay, and shrinks back in 180 ms when unchecked.
- Reduced motion: fill, check, dash and strike-through snap to their final state and the press scale is off.

## Notes for AI

- Use checked + onCheckedChange; onCheckedChange always receives a boolean, never "indeterminate".
- "indeterminate" is a state you compute (for select all), not something the user can toggle into.
- className goes on the box <button>, not the label wrapper.
- strikethrough only shows when label is set; it has no effect on a bare box.
- With name, the hidden input submits value (default "on") when checked and an empty string when not.

## FAQ

**How do I build a select-all checkbox?**

Compute checked as true when all items are selected, false when none are, and "indeterminate" otherwise. Clicking it calls onCheckedChange(true) from the indeterminate state.

**Why does Enter toggle it?**

It is a <button role="checkbox">, so Enter and Space both click it. A native <input type="checkbox"> only responds to Space.

## Related

- checkbox: https://goodui.dev/components/core/checkbox
- switch-spring: https://goodui.dev/components/inputs/switch-spring
- success-check: https://goodui.dev/components/feedback/success-check
- list-reorder: https://goodui.dev/components/lists/list-reorder

Last updated: 2026-11-02

---

# Slider with tooltip

> Single or range slider built from scratch with pointer and keyboard control, step snapping, marks and a value bubble that scales in while dragging.

Range slider with value tooltip for React and shadcn: single or two thumbs, marks, steps

Page: https://goodui.dev/components/inputs/slider-tooltip

## Install

```bash
npx shadcn@latest add @goodui/slider-tooltip
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/slider-tooltip.json`. The file lands in `components/goodui/slider-tooltip.tsx`.

## When to use

- Price or duration filters where a range reads better than two number fields: "$40 to $120", "30 to 90 min".
- Picking a value on a known scale where the exact number matters less than its position: discount %, team size, volume.
- Settings with a few named stops, using marks: Basic, Pro, Team.

## When not to use

- Exact numbers people already know, such as a quantity or an amount: use input.
- Two to four named options with no scale in between: use segmented-control.
- Showing progress that the user does not control: use progress or meter.

## Pick by what matters

| Need | Use |
| --- | --- |
| One value | value={[n]} (a one-item array) |
| A range with two thumbs | value={[from, to]}, plus minStepsBetweenThumbs to keep them apart |
| Bubble only while interacting | tooltip="auto" (default) |
| Value always visible | tooltip="always" (two close bubbles merge into one) |
| No bubble, show the value elsewhere | tooltip="never" |
| Named stops under the track | marks={[{ value, label }]} |

## Usage

```tsx
import * as React from "react"
import { SliderTooltip } from "@/components/goodui/slider-tooltip"

export function PriceFilter() {
  const [price, setPrice] = React.useState([40, 120])

  return (
    <div className="grid gap-4 rounded-xl border bg-card p-5 pt-10">
      <SliderTooltip
        value={price}
        onValueChange={setPrice}
        onValueCommit={(v) => console.log("fetch services between", v)}
        min={0}
        max={200}
        step={5}
        minStepsBetweenThumbs={2}
        formatValue={(v) => "$" + v}
        thumbLabels={["Minimum price", "Maximum price"]}
        marks={[{ value: 0 }, { value: 100 }, { value: 200 }]}
        name="price"
      />
    </div>
  )
}
```

### Single value with steps

```tsx
<SliderTooltip
  aria-label="Session length"
  defaultValue={[60]}
  min={15}
  max={120}
  step={15}
  showSteps
  formatValue={(v) => v + " min"}
/>
```

### Plan picker with named marks

```tsx
<SliderTooltip
  aria-label="Seats"
  defaultValue={[10]}
  min={1}
  max={50}
  tooltip="always"
  formatValue={(v) => v + " seats"}
  marks={[{ value: 1, label: "Solo" }, { value: 10, label: "Team" }, { value: 50, label: "Business" }]}
/>
```

## API

### SliderTooltip

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| value | `number[]` | — | One value for a single thumb, two for a range. |
| defaultValue | `number[]` | — | Initial values when uncontrolled; defaults to [min]. |
| onValueChange | `(value: number[]) => void` | — | Called on every change while dragging or pressing keys, with all thumb values. |
| onValueCommit | `(value: number[]) => void` | — | Fires when a drag ends or a key press changes the value (not when the value stays the same, e.g. at a bound). |
| min | `number` | `0` |  |
| max | `number` | `100` |  |
| step | `number` | `1` |  |
| minStepsBetweenThumbs | `number` | `0` | Minimum gap between range thumbs, in steps. |
| marks | `SliderMark[]` | — | Labelled ticks under the track; a mark without a label shows formatValue(value). |
| showSteps | `boolean` | — | Draw a dot at every step (only when there are 40 steps or fewer). |
| formatValue | `(value: number) => string` | `(v) => String(v)` | Formats the bubble, mark labels and aria-valuetext, e.g. (v) => `$${v}`. |
| tooltip | `"auto" \| "always" \| "never"` | `"auto"` | "auto" shows the bubble while dragging, hovering or keyboard-focused. |
| thumbLabels | `string[]` | — | Accessible names per thumb, e.g. ["Minimum price", "Maximum price"]. |
| disabled | `boolean` | — |  |
| name | `string` | — | Form field name; one hidden input per thumb. |
| labels | `Partial<SliderTooltipLabels>` | — | Text for built-in controls and screen readers; pass translations here. |

Also accepts every <div> attribute.

## Keyboard

| Keys | Action |
| --- | --- |
| Arrow Right / Arrow Up | Increases the focused thumb by one step (Arrow Left increases under dir="rtl"). |
| Arrow Left / Arrow Down | Decreases the focused thumb by one step (Arrow Right decreases under dir="rtl"). |
| Page Up / Page Down | Moves by a tenth of the range (or one step, whichever is larger). |
| Home / End | Moves to min / max, or as far as the other thumb allows in a range. |
| Tab | Moves between thumbs; keyboard focus shows the value bubble in auto mode. |

## Accessibility

- Each thumb is a focusable element with role="slider", aria-valuemin, aria-valuemax, aria-valuenow and aria-valuetext from formatValue.
- Range thumbs are named by thumbLabels, or labels.minimum / labels.maximum ("Minimum" and "Maximum") by default; a single thumb takes thumbLabels[0], the root aria-label or aria-labelledby, and falls back to labels.value ("Value").
- The root is role="group" and carries aria-label too.
- The value bubble and marks are aria-hidden; screen readers get the value from aria-valuetext.
- Clicking the track moves the nearest thumb and focuses it, so arrow keys continue from there.

## Motion

- The bubble scales in from 0.5 and rises 6px on a spring (stiffness 600, damping 30), and leaves in 120 ms.
- The dragged thumb grows to 1.18 on a spring; the thumbs themselves follow the pointer directly, with no lag.
- Reduced motion: the bubble only fades (100 ms) and the dragged thumb does not grow.

## Performance

- Dragging uses pointer capture on the track, so moves outside the slider keep working without window listeners.

## Notes for AI

- value and defaultValue are arrays: [n] for one thumb, [from, to] for a range. Passing a plain number is a type error.
- Use onValueChange for live UI and onValueCommit to fetch or save; commit fires when a drag ends or a key press actually changes the value (not at a bound).
- Built-in thumb names come from the labels prop (minimum, maximum, value); pass translations there.
- Thumbs cannot cross; minStepsBetweenThumbs is counted in steps, not in value units.
- With name, a range submits name[] twice (one per thumb); a single thumb submits name.
- Leave padding above the slider unless tooltip is "never": the bubble is positioned above the track and can overlap content there.

## FAQ

**How do I format the value as currency?**

Pass formatValue, e.g. (v) => "$" + v or an Intl.NumberFormat. It is used for the bubble, unlabelled marks and aria-valuetext.

**Does it support vertical sliders?**

No. It is horizontal only (aria-orientation="horizontal").

**Does it work right-to-left?**

Yes. Under dir="rtl" the track fills from the right, marks and bubbles mirror, dragging maps from the right edge, and Arrow Left increases.

## Related

- input: https://goodui.dev/components/core/input
- segmented-control: https://goodui.dev/components/navigation/segmented-control
- meter: https://goodui.dev/components/numbers/meter
- progress: https://goodui.dev/components/numbers/progress

Last updated: 2026-11-02

---

# Expanding search

> Search icon that springs open into a field with a recent-searches dropdown and a / shortcut; Esc or blur folds it back when empty.

Expanding search bar for React and shadcn: icon opens into a field with recent searches

Page: https://goodui.dev/components/inputs/search-expand

## Install

```bash
npx shadcn@latest add @goodui/search-expand
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/search-expand.json`. The file lands in `components/goodui/search-expand.tsx`.

## When to use

- App headers and toolbars with little room, where search is used often but should not take space when idle.
- Searching one list or table (clients, invoices, bookings) where recent queries are worth repeating.
- When users expect a / shortcut to jump to search, as on GitHub or YouTube.

## When not to use

- Searching across pages and running commands: use command-palette-morph.
- A search field that should always be visible, such as on a search results page: use input.
- Picking tags or several values from suggestions: use tag-input.

## Usage

```tsx
import * as React from "react"
import { useRouter } from "next/navigation"
import { SearchExpand } from "@/components/goodui/search-expand"

export function ClientSearch() {
  const router = useRouter()
  const [recent, setRecent] = React.useState(["Maya Chen", "Invoice 1042", "Friday deep clean"])

  return (
    <header className="flex items-center justify-between border-b px-4 py-2">
      <span className="font-semibold">Clients</span>
      <SearchExpand
        align="end"
        placeholder="Search clients…"
        recent={recent}
        onSubmit={(q) => {
          setRecent((r) => [q, ...r.filter((x) => x !== q)].slice(0, 6))
          router.push("/clients?q=" + encodeURIComponent(q))
        }}
        onClearRecent={() => setRecent([])}
      />
    </header>
  )
}
```

### Live filtering, no submit

```tsx
const [query, setQuery] = React.useState("")
const rows = invoices.filter((i) => i.client.toLowerCase().includes(query.toLowerCase()))

<SearchExpand value={query} onValueChange={setQuery} placeholder="Filter invoices…" shortcut={null} />
```

### Translated labels

```tsx
<SearchExpand
  placeholder="Kunden suchen…"
  labels={{ search: "Suche", open: "Suche öffnen", clear: "Suche löschen", recent: "Letzte Suchen", matching: "Passende Suchen", clearRecent: "Löschen" }}
/>
```

## API

### SearchExpand

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| value | `string` | — | Controlled query text; pair with onValueChange. |
| defaultValue | `string` | `""` | Initial query when uncontrolled. |
| onValueChange | `(value: string) => void` | — | Called on every keystroke, on clear and when a recent search fills the field. |
| onSubmit | `(query: string) => void` | — | Called with the trimmed query on Enter (never with an empty string). |
| open | `boolean` | — | Controlled open state; pair with onOpenChange. |
| defaultOpen | `boolean` | `false` | Start expanded when uncontrolled. |
| onOpenChange | `(open: boolean) => void` | — | Called when the field expands or folds back. |
| recent | `string[]` | `[]` | Shown in a dropdown while the field is focused; filtered by what is typed. |
| onRecentSelect | `(query: string) => void` | — | Defaults to filling the field and submitting. |
| onClearRecent | `() => void` | — | Shows a "Clear" button in the dropdown header when set. |
| placeholder | `string` | `"Search…"` | Placeholder text; also used as the input's aria-label. |
| expandedWidth | `number` | `280` | Width in px when open (it never exceeds the parent). |
| shortcut | `string \| null` | `"/"` | Global key that opens the search; `null` to disable. |
| align | `"start" \| "end"` | `"start"` | Which edge the dropdown aligns to; use "end" when the search sits on the right. |
| labels | `Partial<SearchExpandLabels>` | — | Text for built-in controls and screen readers; pass translations here. |

Also accepts every <div> attribute.

## Keyboard

| Keys | Action |
| --- | --- |
| / | Opens the search and focuses the field from anywhere on the page, unless focus is in an input, textarea, select or editable element. Change it with shortcut, or pass null to turn it off. |
| Enter / Space (on the icon) | Opens the search and focuses the field (native <button>). |
| Arrow Down / Arrow Up | Moves the highlight through recent searches, wrapping at both ends. |
| Enter | Runs the highlighted recent search, or submits the typed query. |
| Esc | First removes the highlight, then clears the text, then folds the search and returns focus to the icon. |

## Accessibility

- The wrapper has role="search". The icon is a <button> with aria-expanded and an aria-label ("Open search" / "Search").
- The field is an <input type="search" role="combobox"> with aria-expanded, aria-controls and aria-activedescendant pointing at the highlighted recent search, so focus stays in the field.
- Recent searches are a role="listbox" of role="option" items with aria-selected.
- While folded, the field is aria-hidden and out of the tab order; only the icon is focusable.
- The field's accessible name is the placeholder, so write a placeholder that describes the search. All built-in strings can be translated through labels.

## Motion

- The bar springs from 36px to expandedWidth (stiffness 420, damping 34) and the icon scales to 0.9.
- The recent-searches dropdown drops in from 6px above at 0.97 scale on a spring (stiffness 600, damping 38) and leaves in 120 ms.
- A highlight slides between recent searches with a shared layout animation; the clear button and / hint fade in.
- Reduced motion: the width changes without a spring, the dropdown and the clear button only fade, and the highlight jumps.

## Notes for AI

- onSubmit gets the trimmed query and never fires for an empty field; it does not close the search.
- recent is only data: the component never stores searches. Add the query to your own list in onSubmit.
- Picking a recent search fills the field and calls onSubmit; pass onRecentSelect to do something else instead.
- Use align="end" when the search sits at the end edge (right in LTR), so the dropdown does not overflow the screen. Alignment follows dir="rtl".
- Blur folds it back only when the field is empty; a typed query stays open.

## FAQ

**How many recent searches does it show?**

Up to six, filtered by what is typed. A recent search that exactly matches the typed text is hidden.

**Can I control whether it is open?**

Yes. Pass open and onOpenChange; otherwise it manages its own state, starting from defaultOpen.

## Related

- command-palette-morph: https://goodui.dev/components/navigation/command-palette-morph
- input: https://goodui.dev/components/core/input
- tag-input: https://goodui.dev/components/inputs/tag-input
- vanish-input: https://goodui.dev/components/inputs/vanish-input

Last updated: 2026-11-02

---

# File drop zone

> Drag-and-drop zone whose border pulses while files hover, then lists files with type icons, springy progress bars, size and type errors, and undo on remove.

Drag and drop file upload for React and shadcn with progress bars, validation and undo

Page: https://goodui.dev/components/inputs/file-drop-pulse

## Install

```bash
npx shadcn@latest add @goodui/file-drop-pulse
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/file-drop-pulse.json`. The file lands in `components/goodui/file-drop-pulse.tsx`.

## When to use

- Uploading documents to a record: receipts to an expense, contracts to a client, photos to a job.
- Imports where file type and size must be checked before anything is sent: CSV client lists, PDF invoices.
- Forms where users add several files and need to see each one's progress and remove mistakes.

## When not to use

- A single avatar or logo picker with a crop step: use an avatar with a plain file input instead.
- Pasting text or links: use input or tag-input.

## Pick by what matters

| Need | Use |
| --- | --- |
| Several files with a cap | multiple (default) with maxFiles |
| Exactly one file that a new drop replaces | multiple={false} |
| Restrict types | accept="image/*,.pdf,.csv" (MIME types, wildcards or extensions) |
| Restrict size | maxSize in bytes, e.g. 10 * 1024 * 1024 |

## Usage

```tsx
import { FileDropPulse } from "@/components/goodui/file-drop-pulse"

export function ReceiptUpload({ expenseId }: { expenseId: string }) {
  return (
    <FileDropPulse
      accept="image/*,.pdf"
      maxSize={10 * 1024 * 1024}
      maxFiles={5}
      title="Drop receipts here or browse"
      upload={(file, onProgress, signal) =>
        new Promise<void>((resolve, reject) => {
          const xhr = new XMLHttpRequest()
          xhr.open("POST", "/api/expenses/" + expenseId + "/receipts")
          xhr.upload.onprogress = (e) => e.lengthComputable && onProgress((e.loaded / e.total) * 100)
          xhr.onload = () => (xhr.status < 300 ? resolve() : reject(new Error("Server rejected " + file.name)))
          xhr.onerror = () => reject(new Error("Network error"))
          signal.addEventListener("abort", () => xhr.abort())
          const body = new FormData()
          body.append("file", file)
          xhr.send(body)
        })
      }
      onFilesChange={(items) => console.log(items.filter((i) => i.status === "done").length, "receipts uploaded")}
    />
  )
}
```

### Add files from elsewhere (paste, another button)

```tsx
import { FileDropPulse, type FileDropPulseHandle } from "@/components/goodui/file-drop-pulse"

const drop = React.useRef<FileDropPulseHandle>(null)

<FileDropPulse ref={drop} accept=".csv" multiple={false} hint="CSV export from your old booking tool" />
<button onClick={() => drop.current?.clear()}>Start over</button>
// drop.current?.addFiles(files) runs the same validation as a drop
```

## API

### FileDropPulse

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| title | `React.ReactNode` | — | Main line in the drop zone; defaults to labels.title. |
| ref | `React.Ref<FileDropPulseHandle>` | — | Imperative handle with addFiles(files) and clear(). |
| accept | `string` | — | Same format as the input `accept` attribute: "image/*,.pdf,.csv". |
| maxSize | `number` | — | Max size per file in bytes. |
| maxFiles | `number` | — | Max files kept in the list; failed files do not count, extra files are skipped with a notice. |
| multiple | `boolean` | `true` | Allow several files at once; when false a new file replaces the list (and cancels the replaced upload). |
| disabled | `boolean` | — |  |
| upload | `(file: File, onProgress: (percent: number) => void, signal: AbortSignal) => Promise<void>` | `simulate` | Upload one file and report progress 0–100. Defaults to a simulated upload. Reject (throw) to mark the file as failed. |
| onFilesChange | `(items: UploadItem[]) => void` | — | Called with the whole list whenever a file is added, progresses, finishes, fails or is removed (not on mount). |
| hint | `React.ReactNode` | — | Second line in the drop zone; defaults to accept, max size and max files. |
| labels | `Partial<FileDropPulseLabels>` | — | Text for built-in controls and screen readers; pass translations here. |

Also accepts every <div> attribute.

## Keyboard

| Keys | Action |
| --- | --- |
| Enter / Space | Opens the system file picker when the drop zone is focused. |
| Tab | Moves from the drop zone to each file's cancel/remove button and the Undo button. |

## Accessibility

- The drop zone is a focusable role="button" that opens a hidden native file input (kept outside the zone, so there is no nested interactive content), with the hint linked through aria-describedby.
- Each uploading or finished file has a role="progressbar" with aria-valuenow; every row has a cancel or remove button named with the file name ("Cancel receipt.pdf").
- A finished file gets sr-only "Uploaded" text; the skipped-files notice is role="alert" and the undo bar is role="status".
- disabled sets aria-disabled, removes the zone from the tab order and ignores drops.
- labels translates every built-in string: progress, cancel, remove and uploaded, the default title, "Release to upload", the validation errors, the default hint parts, the skipped notice and the Undo bar.

## Motion

- While files hover the zone, two rings pulse outward from its border every 1.3 s (CSS, offset by 0.65 s), the border turns solid primary, and the cloud icon lifts and bobs.
- New files rise in from 12px below on a spring (stiffness 420, damping 32); the list reflows with layout animation and removed files slide out sideways in 180 ms.
- Progress bars fill on a soft spring (stiffness 120, damping 22) and turn emerald with a popping check when done.
- Rejected files shake sideways for 400 ms.
- Reduced motion: one static ring instead of the pulse, no icon lift, no shake or layout animation; items fade in and out and progress bars jump.

## Notes for AI

- Without upload the component only simulates progress with random steps. Always pass upload in real apps and call onProgress with 0 to 100.
- Honor the AbortSignal in upload: it fires when the user cancels a file and on unmount. Throw (reject) to mark a file as failed; the error message is shown under the file.
- Validation happens before upload: wrong type or oversize files appear as failed rows and never call upload. Failed rows do not count toward maxFiles.
- onFilesChange receives the full list of UploadItem objects (file, progress, status, error). Read status === "done" to know what finished; it is not called with File[] and not on mount.
- With multiple={false} a new file replaces the current one even when maxFiles is set, and the replaced upload's AbortSignal fires.
- All built-in text comes from the labels prop (title, release, typeNotAllowed, tooLarge, skipped, upTo, maxFiles, removed, undo, plus the progress/cancel/remove strings); pass translations there.
- Removing a file that did not fail shows Undo for 5 seconds. Undo re-adds finished files as they were and restarts unfinished ones from zero, so upload may run twice for the same file.

## FAQ

**Does it upload files itself?**

No. You pass an upload function (fetch, XHR, S3 presigned URL, UploadThing…) that reports progress. Without it the progress is simulated, for demos.

**Can I show the uploaded files after a reload?**

Not through this component: it only lists files added in the current session. Render saved files in your own list next to it.

## Related

- input: https://goodui.dev/components/core/input
- progress: https://goodui.dev/components/numbers/progress
- toast-stack: https://goodui.dev/components/feedback/toast-stack
- input-shake: https://goodui.dev/components/inputs/input-shake

Last updated: 2026-11-02

---

# Ripple button

> Material-style ink ripple that grows from the exact press point and fades on release, pure CSS, across five variants and icon buttons.

Material ripple button for React and shadcn: ink ripple from the press point

Page: https://goodui.dev/components/buttons/ripple-button

## Install

```bash
npx shadcn@latest add @goodui/ripple-button
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/ripple-button.json`. The file lands in `components/goodui/ripple-button.tsx`.

## When to use

- Apps with a Material or Android-like feel, where every press should leave a visible ink mark.
- Touch-heavy UIs (booking flows, POS screens) where the ripple confirms the tap landed while the finger is still down.
- Icon buttons in toolbars and FABs, with centerRipple so the ink always starts from the middle.

## When not to use

- You already use the Core button and only want a quick ripple on click: button with animation="ripple" is simpler and also gives tones, loading and icon props.
- Async actions that need loading and success feedback: use stateful-button.
- Destructive actions that need a deliberate gesture: use hold-to-confirm.

## Pick by what matters

| Need | Use |
| --- | --- |
| Primary action | variant="default" |
| Secondary or toolbar actions | variant="outline", "secondary" or "ghost" |
| Delete or cancel | variant="destructive" |
| Round icon button | size="icon" centerRipple aria-label="…" |
| Branded ink | rippleColor="var(--chart-1)" rippleOpacity={0.3} |
| Ripple on click only, with tones and loading | button with animation="ripple" |

## Usage

```tsx
import { CalendarPlus } from "lucide-react"
import { RippleButton } from "@/components/goodui/ripple-button"

export function BookingActions({ onBook, onReschedule }: { onBook: () => void; onReschedule: () => void }) {
  return (
    <div className="flex gap-2">
      <RippleButton onClick={onBook}>
        <CalendarPlus />
        Book appointment
      </RippleButton>
      <RippleButton variant="outline" onClick={onReschedule}>
        Reschedule
      </RippleButton>
    </div>
  )
}
```

### Round icon button with a centered ripple

```tsx
<RippleButton size="icon" variant="ghost" centerRipple aria-label="Add client">
  <Plus />
</RippleButton>
```

### Slower, branded ink

```tsx
<RippleButton variant="secondary" rippleColor="var(--chart-1)" rippleOpacity={0.3} rippleDuration={800}>
  Send invoice
</RippleButton>
```

## API

### RippleButton

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| variant | `"outline" \| "default" \| "destructive" \| "ghost" \| "secondary"` | `"default"` | "default" \| "secondary" \| "outline" \| "ghost" \| "destructive", matching shadcn's button variants. |
| size | `"sm" \| "md" \| "lg" \| "icon"` | `"md"` | "sm" \| "md" \| "lg" \| "icon"; "icon" is a round 40px button. |
| rippleColor | `string` | — | Ripple color; defaults to the text color. |
| rippleOpacity | `number` | — | Ripple opacity at its peak (0–1). |
| rippleDuration | `number` | `550` | Milliseconds for the ripple to cover the button. |
| centerRipple | `boolean` | — | Always start the ripple from the center (good for icon buttons). |

Also accepts every <button> attribute.

## Keyboard

| Keys | Action |
| --- | --- |
| Enter / Space | Starts a ripple from the center on key down (not on auto-repeat) and fades it on key up; the native button activates as usual. |
| Tab | Moves focus; blurring the button fades any ripple. |

## Accessibility

- Renders a native <button>; every button attribute (type, disabled, aria-*) passes through.
- Ripples live in an aria-hidden layer with pointer-events: none, so they are never announced and never block clicks.
- size="icon" has no visible text: give it an aria-label.

## Motion

- Press: a circle big enough to cover the button grows from the press point in `rippleDuration` ms (550 by default) on cubic-bezier(.2,.6,.35,1).
- Release (pointer up, leave, cancel, key up or blur): the ink fades out over 420 ms and is removed after 520 ms. At most five ripples exist at once.
- Only the primary mouse button starts a ripple.
- Reduced motion: no ripple is created at all; the button keeps its normal hover colors.

## Performance

- The grow is a CSS transform keyframe and the fade an opacity transition; React only adds and removes a span per press.

## Notes for AI

- variant values are default, secondary, outline, ghost, destructive (shadcn names), not solid or primary.
- Sizes are sm, md, lg and icon; there is no xs or xl.
- rippleDuration is in milliseconds; rippleOpacity is 0 to 1.
- Pass icons as children; there are no iconLeft or iconRight props here.
- If you add your own onPointerDown or onKeyDown, it still runs; the ripple handlers call it after spawning.

## FAQ

**How is this different from the Core button's ripple?**

The Core button plays a fixed 0.6 s ripple on pointer down that fades by itself. RippleButton keeps the ink while you hold, fades it on release, ripples on Enter and Space too, and lets you set color, opacity, duration and centering.

**Can the ripple start from the center?**

Yes, pass centerRipple. Keyboard presses always start from the center.

## Related

- button: https://goodui.dev/components/core/button
- stateful-button: https://goodui.dev/components/buttons/stateful-button
- hold-to-confirm: https://goodui.dev/components/buttons/hold-to-confirm
- magnetic-button: https://goodui.dev/components/buttons/magnetic-button

Last updated: 2026-11-02

---

# Rainbow button

> Button with a seamlessly flowing rainbow border and a soft colored glow underneath, tuned to invert cleanly between light and dark themes.

Rainbow border button for React and shadcn: animated gradient border with glow

Page: https://goodui.dev/components/buttons/rainbow-button

## Install

```bash
npx shadcn@latest add @goodui/rainbow-button
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/rainbow-button.json`. The file lands in `components/goodui/rainbow-button.tsx`.

## When to use

- The single hero call to action on a landing page, especially for AI or creative products.
- Launch or announcement moments ("Try the new AI receptionist") where a colorful edge is on brand.
- Dark marketing sections, where the glow under the button reads well.

## When not to use

- Everyday app actions (save, filter, invite): use button; a rainbow edge in a form looks out of place.
- A subtler moving border that uses two brand colors: use border-beam-button.
- A gradient face without the moving border: button with variant="gradient" is simpler.

## Pick by what matters

| Need | Use |
| --- | --- |
| Maximum contrast, inverts with the theme | variant="solid" (black face in light, white in dark) |
| Quieter, page-colored face | variant="outline" |
| Brand colors instead of the rainbow | colors={[...5 CSS colors]} |
| Calmer flow | speed={6} |
| Pill CTA | pill |

## Usage

```tsx
import { ArrowRight } from "lucide-react"
import { RainbowButton } from "@/components/goodui/rainbow-button"

export function LaunchCta({ onStart }: { onStart: () => void }) {
  return (
    <RainbowButton size="lg" pill onClick={onStart}>
      Try the AI receptionist
      <ArrowRight className="rtl:rotate-180" />
    </RainbowButton>
  )
}
```

### Outline variant with brand colors

```tsx
<RainbowButton
  variant="outline"
  colors={["var(--chart-1)", "var(--chart-2)", "var(--chart-3)", "var(--chart-4)", "var(--chart-5)"]}
  speed={5}
>
  Join the beta
</RainbowButton>
```

## API

### RainbowButton

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| variant | `"solid" \| "outline"` | `"solid"` | "solid" inverts with the theme (black in light, white in dark); "outline" uses the page background. |
| size | `"sm" \| "md" \| "lg"` | `"md"` | "sm" \| "md" \| "lg": height, padding and corner radius (10, 12 or 14 px). |
| pill | `boolean` | — | Fully rounded ends. |
| colors | `string[]` | `DEFAULT_COLORS` | Five CSS colors for the flowing gradient. |
| speed | `number` | `3` | Seconds per loop. |
| borderWidth | `number` | `2` | Border thickness in px. |

Also accepts every <button> attribute.

## Keyboard

| Keys | Action |
| --- | --- |
| Enter / Space | Activates the button (native <button>). |
| Tab | Moves focus; the focus ring is offset from the border so it stays visible. |

## Accessibility

- Renders a native <button>; the gradient border, glow and face are aria-hidden spans with pointer-events: none.
- variant="solid" uses text-background on a foreground face, so text color follows the theme in light and dark.
- The focus ring has a 2px offset in the page background color, so it does not merge with the colored border.

## Motion

- The border and the glow share one gradient strip, twice the button width, that slides by half its width in a seamless linear loop every `speed` seconds (3 by default). Only transform is animated.
- Hover: the blurred glow under the button brightens and widens slightly over 0.3 s. Press scales to 0.98.
- Reduced motion: the gradient stops moving; the colored border and glow stay.

## Performance

- The loop is a CSS transform on two strips; no JavaScript runs while it animates. The glow uses a 14px blur, so keep it to one or two buttons per screen.

## Notes for AI

- colors takes up to five CSS colors; fewer are repeated to fill five slots.
- speed is seconds per loop (higher is slower); borderWidth is in px.
- Do not add bg-* classes to change the face: the face is an inner span. Choose variant="solid" or "outline" instead.
- Corner radius comes from size (10, 12 or 14 px) or pill; set radius through pill, not rounded-* classes, so border and face stay aligned.
- Use one rainbow button per screen; it is a hero accent, not a default button.

## FAQ

**Does it work in dark mode?**

Yes. The solid face inverts with the theme (black in light, white in dark) and the glow is toned down in dark mode.

**Can I use my brand colors?**

Yes, pass colors with five CSS colors or theme variables such as var(--chart-1).

## Related

- border-beam-button: https://goodui.dev/components/buttons/border-beam-button
- shimmer-button: https://goodui.dev/components/buttons/shimmer-button
- button: https://goodui.dev/components/core/button
- gradient-text: https://goodui.dev/components/text/gradient-text

Last updated: 2026-11-02

---

# Border beam button

> A short light beam rides around the button's rounded border with CSS offset-path, with a conic fallback and a static gradient for reduced motion.

Border beam button for React and shadcn: light beam running around the border

Page: https://goodui.dev/components/buttons/border-beam-button

## Install

```bash
npx shadcn@latest add @goodui/border-beam-button
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/border-beam-button.json`. The file lands in `components/goodui/border-beam-button.tsx`.

## When to use

- A secondary CTA that should feel alive without the loudness of a rainbow edge ("Watch the 2-minute demo").
- Highlighting one new action in an app header or empty state.
- Pairing with a solid primary button: the outline variant with a beam draws the eye to the second option.

## When not to use

- A beam around a card, input or any other element: use border-beam, which wraps any child and measures its radius.
- A full multicolor flowing border: use rainbow-button.
- Ordinary actions in forms and tables: use button; a moving border on every action is noise.

## Pick by what matters

| Need | Use |
| --- | --- |
| Secondary CTA next to a primary one | variant="outline" (default) |
| Primary CTA with a beam | variant="solid" |
| Pill shape | radius={999} |
| Two beams chasing each other | double |
| Brand colors | colorFrom="var(--chart-1)" colorTo="var(--chart-4)" |

## Usage

```tsx
import { PlayCircle } from "lucide-react"
import { BorderBeamButton } from "@/components/goodui/border-beam-button"

export function DemoCta({ onWatch }: { onWatch: () => void }) {
  return (
    <BorderBeamButton size="lg" radius={12} onClick={onWatch}>
      <PlayCircle />
      Watch the 2-minute demo
    </BorderBeamButton>
  )
}
```

### Solid pill with two beams in brand colors

```tsx
<BorderBeamButton
  variant="solid"
  radius={999}
  double
  colorFrom="var(--chart-1)"
  colorTo="var(--chart-4)"
  duration={6}
>
  Start free trial
</BorderBeamButton>
```

## API

### BorderBeamButton

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| variant | `"outline" \| "solid"` | `"outline"` | "outline" is a page-colored face with a hairline border; "solid" fills with the primary color. |
| size | `"sm" \| "md" \| "lg"` | `"md"` | "sm" \| "md" \| "lg": height and padding of the button. |
| radius | `number` | `10` | Corner radius in px (use 999 for a pill). Kept in sync with the beam path. |
| colorFrom | `string` | `"#ffaa40"` | Head color of the beam. |
| colorTo | `string` | `"#9c40ff"` | Tail color of the beam. |
| duration | `number` | `4` | Seconds per lap. |
| beamSize | `number` | `56` | Beam length in px. |
| borderWidth | `number` | `1.5` | Border thickness in px. |
| double | `boolean` | — | Two beams chasing each other half a lap apart. |

Also accepts every <button> attribute.

## Keyboard

| Keys | Action |
| --- | --- |
| Enter / Space | Activates the button (native <button>). |
| Tab | Moves focus; a focus ring shows on keyboard focus only. |

## Accessibility

- Renders a native <button>; the beam ring is an aria-hidden span with pointer-events: none.
- The label is never covered: the beam is masked to the border band only.

## Motion

- A short gradient beam (`beamSize`, 56 px by default) travels the rounded-rect edge with CSS offset-path in a linear loop, one lap every `duration` seconds (4 by default). double adds a second beam half a lap behind.
- Browsers without offset-path rect() get a rotating conic sweep masked to the same border band instead.
- Press scales to 0.98.
- Reduced motion: the beam is hidden and the border shows a static from-to gradient at 55% opacity.

## Performance

- CSS only; no JavaScript runs while the beam moves.

## Notes for AI

- Set the corner radius with the radius prop (px), not rounded-* classes: the beam path uses the same value.
- duration is seconds per lap; beamSize and borderWidth are px.
- variant is "outline" or "solid" only.
- For anything that is not a button (cards, inputs), use border-beam instead of this component.

## FAQ

**Why does the beam cut the corner on my button?**

The beam path uses the radius prop. If you round the button with a class instead, the two no longer match. Pass radius={…} (999 for a pill).

**What do older browsers show?**

Without offset-path rect() support, a rotating conic gradient sweeps around the same border band instead of the traveling beam.

## Related

- border-beam: https://goodui.dev/components/cards/border-beam
- rainbow-button: https://goodui.dev/components/buttons/rainbow-button
- shimmer-button: https://goodui.dev/components/buttons/shimmer-button
- button: https://goodui.dev/components/core/button

Last updated: 2026-11-02

---

# Magnetic button

> Button and its label are pulled toward a nearby cursor with a smooth falloff and spring back on leave; off for touch and reduced motion.

Magnetic button for React and shadcn: button that follows the cursor

Page: https://goodui.dev/components/buttons/magnetic-button

## Install

```bash
npx shadcn@latest add @goodui/magnetic-button
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/magnetic-button.json`. The file lands in `components/goodui/magnetic-button.tsx`.

## When to use

- A hero CTA or footer "Get started" on a marketing site where a playful, tactile hover fits the brand.
- Round icon buttons (social links, a floating chat button) that should feel physical under the mouse.
- Portfolio and agency pages where pointer interactions are part of the design.

## When not to use

- Dense app UI (tables, toolbars, forms): a moving target slows precise clicking. Use button.
- Touch-first screens: the effect is off on touch and coarse pointers, so it adds nothing there. Use button or ripple-button.
- A hover lift without pointer tracking: button with animation="lift" is simpler.

## Pick by what matters

| Need | Use |
| --- | --- |
| Subtle pull for an app-like CTA | strength={0.2} labelStrength={0.1} |
| Strong, playful pull | strength={0.5} labelStrength={0.3} radius={120} |
| Round icon button | size="icon" aria-label="…" |
| Only react when the cursor is on the button | radius={0} |

## Usage

```tsx
import { ArrowRight } from "lucide-react"
import { MagneticButton } from "@/components/goodui/magnetic-button"

export function FooterCta({ onStart }: { onStart: () => void }) {
  return (
    <MagneticButton size="lg" onClick={onStart}>
      Get started free
      <ArrowRight className="rtl:rotate-180" />
    </MagneticButton>
  )
}
```

### Round icon button with a stronger pull

```tsx
<MagneticButton size="icon" variant="outline" strength={0.5} radius={100} aria-label="Chat with support">
  <MessageCircle />
</MagneticButton>
```

## API

### MagneticButton

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| variant | `"outline" \| "default" \| "ghost" \| "secondary"` | `"default"` | "default" \| "secondary" \| "outline" \| "ghost", matching shadcn's button variants. |
| size | `"sm" \| "md" \| "lg" \| "icon"` | `"md"` | "sm" \| "md" \| "lg" \| "icon"; "icon" is a round 44px button. |
| strength | `number` | `0.35` | Share of the pointer offset the button follows (0–1). |
| labelStrength | `number` | `0.2` | Extra share for the label, for a parallax feel. |
| radius | `number` | `70` | Distance in px outside the button where the pull starts. |

Also accepts every <button> attribute.

## Keyboard

| Keys | Action |
| --- | --- |
| Enter / Space | Activates the button (native <button>). |
| Tab | Moves focus; a focus ring shows on keyboard focus only. Keyboard focus does not move the button. |

## Accessibility

- Renders a native <button> (motion.button) inside an inline-flex <span> wrapper that is used to measure the resting position.
- The effect only runs for a fine pointer that can hover (mouse, trackpad); touch input and keyboard users get a normal static button.
- Disabled buttons do not move.

## Motion

- The button moves toward the pointer by `strength` (0.35) of the offset and the label by `labelStrength` (0.2), both on a spring (stiffness 220, damping 15, mass 0.6).
- The pull is full over the button and eases to zero at `radius` px (70) outside it, using a smoothstep curve; leaving springs it back to the center.
- Tap scales to 0.95.
- Listening stops while the button is off-screen, while the tab is hidden and when the pointer is not fine.
- Reduced motion: no pull and no tap scale.

## Performance

- Uses motion values and springs, so pointer moves do not re-render React. The window pointermove listener is only attached while the button is visible.

## Notes for AI

- variant values are default, secondary, outline, ghost; sizes sm, md, lg, icon.
- strength and labelStrength are fractions of the pointer offset (0 to 1), not pixels; radius is in px.
- className goes on the button; the wrapping <span> is internal, so use a parent element for layout spacing.
- Pass icons and text as children; they move together as the label.

## FAQ

**Does it work on phones?**

It renders as a normal button. The pull only runs for a fine pointer that can hover (mouse or trackpad).

**Can I use it on several buttons?**

Yes. Each button only listens while it is visible, but keep it to a few buttons so the page does not feel jumpy.

## Related

- button: https://goodui.dev/components/core/button
- ripple-button: https://goodui.dev/components/buttons/ripple-button
- tilt-card: https://goodui.dev/components/cards/tilt-card
- shimmer-button: https://goodui.dev/components/buttons/shimmer-button

Last updated: 2026-11-02

---

# Stateful button

> Async button that morphs idle to spinner to drawn check or shaking error, with a spring width change between labels.

Async loading button for React and shadcn: spinner, success check and error shake

Page: https://goodui.dev/components/buttons/stateful-button

## Install

```bash
npx shadcn@latest add @goodui/stateful-button
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/stateful-button.json`. The file lands in `components/goodui/stateful-button.tsx`.

## When to use

- Any action that calls the server and should report the result in place: save settings, send invoice, charge card.
- Form submits where a toast would be too far from the button ("Saved" right where the user clicked).
- Retry flows: after an error the button shakes, shows "Try again" and is clickable again.

## When not to use

- Only a spinner, no success or error state: button with loading is simpler and keeps all variants and tones.
- Destructive actions that need a deliberate gesture: use hold-to-confirm.
- Results that need more than two words (validation messages, partial failures): show them in alert or toast-stack.

## Pick by what matters

| Need | Use |
| --- | --- |
| The handler returns a promise | onClick={async () => …} (states run by themselves) |
| State comes from your own data layer (React Query, server actions) | state={…} and onStateChange |
| Keep "Done" on screen | resetAfter={0} |
| Text while loading | loadingText="Sending…" |
| Secondary placement | variant="outline" or "secondary" |

## Usage

```tsx
import { Send } from "lucide-react"
import { StatefulButton } from "@/components/goodui/stateful-button"

export function SendInvoiceButton({ invoiceId }: { invoiceId: string }) {
  return (
    <StatefulButton
      loadingText="Sending…"
      successText="Invoice sent"
      errorText="Try again"
      onClick={async () => {
        const res = await fetch("/api/invoices/" + invoiceId + "/send", { method: "POST" })
        if (!res.ok) throw new Error("Send failed")
      }}
    >
      <Send />
      Send invoice
    </StatefulButton>
  )
}
```

### Controlled by your own mutation state

```tsx
const [state, setState] = React.useState<StatefulButtonState>("idle")

<StatefulButton
  state={state}
  onStateChange={setState}
  onClick={() => {
    setState("loading")
    saveSettings().then(() => setState("success"), () => setState("error"))
  }}
>
  Save settings
</StatefulButton>
```

### Keep the success state

```tsx
<StatefulButton variant="outline" resetAfter={0} successText="Connected" onClick={connectCalendar}>
  Connect Google Calendar
</StatefulButton>
```

## API

### StatefulButton

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| onClick | `(event: React.MouseEvent<HTMLButtonElement>) => void \| Promise<unknown>` | — | Return a promise to drive the states: pending → loading, resolved → success, rejected → error. |
| state | `"idle" \| "loading" \| "success" \| "error"` | — | Control the state yourself instead. |
| onStateChange | `(state: StatefulButtonState) => void` | — | Called on every state change, including the automatic return to idle. |
| variant | `"outline" \| "default" \| "secondary"` | `"default"` | "default" \| "outline" \| "secondary": idle look; success turns emerald and error destructive in every variant. |
| size | `"sm" \| "md" \| "lg"` | `"md"` | "sm" \| "md" \| "lg": height, text size and padding. |
| loadingText | `React.ReactNode` | — | Shown next to the spinner while loading; empty by default (spinner only). |
| successText | `React.ReactNode` | — | Shown next to the drawn check after success. |
| errorText | `React.ReactNode` | — | Shown next to the drawn cross after a failure; clicking again retries. |
| resetAfter | `number` | `2200` | Milliseconds before success/error returns to idle; 0 keeps it. |
| labels | `Partial<StatefulButtonLabels>` | — | Text for built-in controls and screen readers; pass translations here. |
| sound | `boolean \| SoundName` | — | Plays "tap" on click, then "success" or "error" with the result, when the visitor has sounds on (lib/goodui-sounds); a sound name replaces the tap. Off by default. |

Also accepts every <button> attribute.

## Keyboard

| Keys | Action |
| --- | --- |
| Enter / Space | Runs onClick (native <button>). Ignored while loading or showing success. |
| Tab | Moves focus; a focus ring shows on keyboard focus only. |

## Accessibility

- A polite live region announces "Working…", "Done" or "Something went wrong" (labels.loading / success / error) as the state changes.
- The success (emerald-700) and error fills keep white text at 4.5:1 in light and dark.
- While loading it sets aria-busy; while loading or showing success it sets aria-disabled and ignores clicks, but stays focusable.
- The spinner, check and cross are aria-hidden SVGs; the visible text comes from children, loadingText, successText and errorText.

## Motion

- Labels swap with a vertical slide and a 3px blur on a spring (stiffness 500, damping 34); the button width springs to the new label (stiffness 420, damping 34).
- Success draws a check in 0.3 s; error draws a cross stroke by stroke and shakes the button sideways over 0.42 s.
- Success and error return to idle after `resetAfter` ms (2200), unless the state is controlled.
- Reduced motion: labels cross-fade in 0.1 s, the width changes instantly, there is no shake or tap scale, and the check and cross appear already drawn. The spinner keeps turning, slower.

## Notes for AI

- Make onClick return a promise (an async function) to get the automatic states; a handler that returns nothing leaves the button idle.
- Throw or reject to show the error state; returning a value or resolving shows success.
- When you pass state, the button is controlled: it never resets by itself, so set it back to "idle" yourself.
- Built-in text comes from the labels prop: loading, success and error (screen reader messages) plus successText and errorText (default visible texts). The successText and errorText props still override the visible text.
- Import the StatefulButtonState type from the same file when typing controlled state.

## FAQ

**How do I show an error message?**

errorText shows a short label like "Try again". For a full message, catch the error in your handler, show it in an alert or toast, and rethrow so the button shows the error state.

**Can I translate the screen reader announcements?**

Not through props yet: the live region uses fixed English strings. The visible texts are all props.

## Related

- button: https://goodui.dev/components/core/button
- hold-to-confirm: https://goodui.dev/components/buttons/hold-to-confirm
- success-check: https://goodui.dev/components/feedback/success-check
- toast-stack: https://goodui.dev/components/feedback/toast-stack

Last updated: 2026-11-02

---

# Copy button

> Copy-to-clipboard button whose icon blurs from copy into a drawn check with a popping Copied! tooltip, plus a fallback when the Clipboard API is blocked.

Copy to clipboard button for React and shadcn with Copied! tooltip

Page: https://goodui.dev/components/buttons/copy-button

## Install

```bash
npx shadcn@latest add @goodui/copy-button
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/copy-button.json`. The file lands in `components/goodui/copy-button.tsx`.

## When to use

- Next to API keys, webhook URLs, invite links and booking links that people paste elsewhere.
- In code blocks and docs, as a small icon-only button in the corner.
- Sharing panels ("Copy link") where a visible label and a Copied! confirmation help.

## When not to use

- Sharing to other apps on mobile: use the Web Share API (navigator.share) with a button; copy is the fallback.
- Actions that do more than copy (create a link on the server first, then copy): use stateful-button, or pass an async value function here if the server call is quick.

## Pick by what matters

| Need | Use |
| --- | --- |
| Corner of a code block | defaults (variant="ghost", size icon-sm) |
| Visible "Copy link" text | label="Copy link" (size becomes sm) |
| Inside a form row next to an input | variant="outline" size="icon" |
| Text produced on demand | value={async () => …} |
| No floating tooltip | tooltip={false} |

## Usage

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

export function BookingLink({ url }: { url: string }) {
  return (
    <div className="flex items-center gap-2 rounded-lg border bg-muted/40 py-1.5 ps-3 pe-1.5">
      <span className="truncate font-mono text-sm">{url}</span>
      <CopyButton value={url} label="Copy link" variant="outline" className="ms-auto" />
    </div>
  )
}
```

### Icon-only, for a code block

```tsx
<div className="relative rounded-lg bg-muted p-4 font-mono text-sm">
  <CopyButton value="npx shadcn@latest add copy-button" hint="Copy command" className="absolute end-2 top-2" />
  npx shadcn@latest add copy-button
</div>
```

### Copy a value created on demand

```tsx
<CopyButton
  label="Copy invite link"
  value={async () => (await createInvite(teamId)).url}
  onCopied={() => track("invite_copied")}
/>
```

## API

### CopyButton

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| value (required) | `string \| (() => string \| Promise<string>)` | — | Text to copy, or a function that returns it (can be async). |
| timeout | `number` | `1600` | Milliseconds the "copied" state stays. |
| onCopied | `(text: string) => void` | — | Called with the copied text after a successful copy. |
| onCopyError | `(text: string) => void` | — | Called with the text when both the Clipboard API and the fallback fail, or with "" when the value function throws or rejects. |
| label | `React.ReactNode` | — | Visible text beside the icon; leave empty for an icon-only button. |
| copiedLabel | `string` | — | Text shown in the tooltip (and the label) after copying. |
| failedLabel | `string` | — | Tooltip text when copying is blocked; defaults to a ⌘C / Ctrl+C hint. |
| hint | `string` | — | Hint shown in the tooltip on hover for icon-only buttons. |
| variant | `"outline" \| "default" \| "ghost" \| "secondary"` | `"ghost"` | "ghost" \| "outline" \| "secondary" \| "default". Ghost also turns the icon emerald after copying. |
| size | `"sm" \| "md" \| "icon" \| "icon-sm"` | — | "icon-sm" \| "icon" \| "sm" \| "md". Defaults to "icon-sm" without a label and "sm" with one. |
| tooltip | `boolean` | `true` | Show the floating tooltip. |
| labels | `Partial<CopyButtonLabels>` | — | Text for built-in controls and screen readers; pass translations here. |
| sound | `boolean \| SoundName` | — | Plays "pop" after a copy (and "error" when it fails) when the visitor has sounds on (lib/goodui-sounds); a sound name replaces the pop. Off by default. |

Also accepts every <button> attribute.

## Keyboard

| Keys | Action |
| --- | --- |
| Enter / Space | Copies (native <button>). |
| Tab | Focus shows the hint tooltip on keyboard focus (focus-visible) for icon-only buttons. |

## Accessibility

- Icon-only buttons get aria-label from hint ("Copy") unless you pass aria-label.
- A polite live region announces "Copied to clipboard" or a failure message; the tooltip itself is aria-hidden.
- If the Clipboard API is blocked, it falls back to a hidden textarea with execCommand("copy") and returns focus to where it was.
- If both fail, the tooltip tells the user to press ⌘C on Apple devices or Ctrl+C elsewhere.

## Motion

- The copy icon blurs and scales out while a check scales in and draws itself in 0.25 s; the tooltip pops on a spring (stiffness 600, damping 26).
- Press scales to 0.95. The copied state lasts `timeout` ms (1600); a failure lasts 1.2 s longer.
- Reduced motion: icon and tooltip cross-fade in 0.1 s and the check appears already drawn.

## Notes for AI

- value is required: a string, or a function returning a string or a promise of one. Do not pass children; use label for visible text.
- The button calls your onClick first; call event.preventDefault() there to cancel the copy.
- Variants are ghost (default), outline, secondary, default; sizes icon-sm, icon, sm, md.
- Built-in text comes from the labels prop (hint, copied, blocked(mac), copiedAnnouncement, failedAnnouncement); the hint, copiedLabel and failedLabel props still override the visible texts.
- If value is an async function that throws or rejects, the button shows the failed state and onCopyError is called with "".

## FAQ

**Does it work on http:// or inside iframes?**

When the Clipboard API is not available (insecure context) or throws, it falls back to a hidden textarea and execCommand("copy"). If that also fails, it shows a ⌘C / Ctrl+C hint.

**Can I copy rich text or images?**

No. It copies plain text only.

## Related

- button: https://goodui.dev/components/core/button
- tooltip-animated: https://goodui.dev/components/overlays/tooltip-animated
- input: https://goodui.dev/components/core/input
- kbd: https://goodui.dev/components/core/kbd

Last updated: 2026-11-02

---

# Hold to confirm

> Press-and-hold button for destructive actions: a fill sweeps across with the label flipping color at its edge, early release rewinds it, works with Space and Enter.

Hold to confirm button for React and shadcn: press and hold to delete

Page: https://goodui.dev/components/buttons/hold-to-confirm

## Install

```bash
npx shadcn@latest add @goodui/hold-to-confirm
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/hold-to-confirm.json`. The file lands in `components/goodui/hold-to-confirm.tsx`.

## When to use

- Destructive actions that should not happen by accident but do not deserve a dialog: delete a booking, remove a team member, cancel a subscription.
- Kiosk and touch screens (check-in, POS) where a confirm dialog is slow and easy to tap through.
- Confirming irreversible bulk actions inside a row or toolbar, where a modal would break the flow.

## When not to use

- Actions that need explanation or a typed confirmation (deleting a whole workspace): use a dialog such as morphing-dialog.
- Ordinary, reversible actions: use button, and offer undo in a toast-stack instead of slowing everyone down.
- Non-destructive async actions that need loading, success and error states: use stateful-button.

## Pick by what matters

| Need | Use |
| --- | --- |
| Delete or cancel | variant="destructive" (default) |
| Non-destructive but deliberate (publish, send to all clients) | variant="default" |
| Neutral surface | variant="outline" |
| Very serious action | duration={2500} |
| Stay in the done state | resetAfter={0} |

## Usage

```tsx
import { Trash2 } from "lucide-react"
import { HoldToConfirm } from "@/components/goodui/hold-to-confirm"

export function CancelBooking({ onCancel }: { onCancel: () => void }) {
  return (
    <HoldToConfirm
      onConfirm={onCancel}
      holdingLabel="Keep holding…"
      confirmedLabel="Booking cancelled"
      tapHint="Hold to cancel"
    >
      <Trash2 />
      Cancel booking
    </HoldToConfirm>
  )
}
```

### Publish to every client, primary color

```tsx
<HoldToConfirm variant="default" duration={1200} confirmedLabel="Published" onConfirm={publishSchedule}>
  Publish schedule to 48 clients
</HoldToConfirm>
```

## API

### HoldToConfirm

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| duration | `number` | `1500` | Milliseconds the button must be held. |
| onConfirm | `() => void` | — | Called once when the hold completes. There is no onClick: a tap only shows the hint. |
| variant | `"outline" \| "default" \| "destructive"` | `"destructive"` | "destructive" \| "default" \| "outline": resting look and fill color (red, primary, foreground). |
| size | `"sm" \| "md" \| "lg"` | `"md"` | "sm" \| "md" \| "lg": height, padding and corner radius. |
| holdingLabel | `React.ReactNode` | — | Label while holding. |
| confirmedLabel | `React.ReactNode` | — | Label after confirming. |
| tapHint | `React.ReactNode` | — | Shown briefly when the button is only tapped. |
| resetAfter | `number` | `2000` | Milliseconds before returning to idle after confirming; 0 stays confirmed. |
| labels | `Partial<HoldToConfirmLabels>` | — | Text for built-in controls and screen readers; pass translations here. |
| sound | `boolean \| SoundName` | — | Plays a "tick" when the hold starts and "confirm" when it completes, when the visitor has sounds on (lib/goodui-sounds); a sound name replaces the confirm. Off by default. |

Also accepts every <button> attribute.

## Keyboard

| Keys | Action |
| --- | --- |
| Space / Enter (hold) | Starts filling on key down (auto-repeat ignored); releasing early rewinds it. |
| Tab | Moving focus away (blur) cancels a hold in progress. |

## Accessibility

- Renders a native <button type="button"> with aria-describedby pointing to a hidden "Press and hold for N seconds to confirm." hint (labels.instructions).
- An assertive live region announces the confirmed label when it is a string, otherwise "Confirmed" (labels.confirmed).
- The destructive variant's text and fill are darkened just enough to keep 4.5:1 contrast in light and dark.
- Works with mouse, touch and keyboard. The context menu and iOS callout are suppressed so a long touch does not open them.
- A quick tap shows tapHint and shakes gently, teaching the gesture instead of failing silently.

## Motion

- Holding sweeps a fill across the button with a linear clip-path over `duration` ms (1500); the fill carries its own copy of the label, so the text color flips exactly at the fill edge. Under dir="rtl" the fill sweeps from the right.
- Press scales to 0.97 on a spring; releasing early springs the fill back (stiffness 260, damping 30).
- Confirming pops the button (0.97 → 1.04 → 1 over 0.35 s) and vibrates for 25 ms where supported. After `resetAfter` ms (2000) the fill rewinds over 0.4 s.
- Reduced motion: the fill still tracks the hold (it is the progress indicator), but there is no scale, pop or shake, and rewinds are instant.

## Notes for AI

- Use onConfirm, not onClick: onClick is not accepted, and a normal click only shows the hint.
- duration and resetAfter are milliseconds; resetAfter={0} keeps the confirmed state.
- holdingLabel, confirmedLabel and tapHint are visible texts; built-in text comes from the labels prop (instructions(seconds), confirmed, and the confirmedLabel / tapHint defaults), so pass translations there.
- Variants are destructive (default), default, outline; sizes sm, md, lg.

## FAQ

**What happens if the user lets go early?**

The fill springs back to empty and nothing is called. If they let go within the first 20% it also shows tapHint and shakes.

**Is it safe for keyboard users?**

Yes. Holding Space or Enter fills it the same way, and moving focus away cancels.

## Related

- stateful-button: https://goodui.dev/components/buttons/stateful-button
- button: https://goodui.dev/components/core/button
- morphing-dialog: https://goodui.dev/components/overlays/morphing-dialog
- toast-stack: https://goodui.dev/components/feedback/toast-stack

Last updated: 2026-11-02

---

# Liquid glass button

> Frosted glass button and pill toolbar with backdrop blur, rim light and a specular highlight that follows the pointer, falling back to a solid tint without backdrop-filter.

Liquid glass button and toolbar for React and shadcn: frosted glassmorphism UI

Page: https://goodui.dev/components/buttons/liquid-glass-button

## Install

```bash
npx shadcn@latest add @goodui/liquid-glass-button
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/liquid-glass-button.json`. The file lands in `components/goodui/liquid-glass-button.tsx`.

## When to use

- Controls floating over photos, maps, video or colorful gradients, where a solid button would cover the content.
- A floating view switcher (List / Calendar / Map) over a busy screen: LiquidGlassToolbar with a gliding lens.
- Hero sections with an aurora or image background that call for an iOS-style glass look.

## When not to use

- On a plain white or dark page: glass has nothing to blur and looks washed out. Use button (variant="glass" if you still want the look on a tinted card).
- Switching views in a normal app header: use segmented-control or tabs-indicator, which have proper tab semantics.
- Long-lived app navigation on mobile: use bottom-nav.

## Pick by what matters

| Need | Use |
| --- | --- |
| Over bright or colorful backdrops | tone="light" (default) |
| Over dark photos or night scenes | tone="dark" |
| Single action | LiquidGlassButton |
| Pick one view of several | LiquidGlassToolbar + LiquidGlassToolbarItem |
| Text labels hidden on phones | compact on each item, with the text wrapped in a <span> |
| Preview the no-blur fallback | fallback |

## Usage

```tsx
import { CalendarDays, LayoutList, Map } from "lucide-react"
import { LiquidGlassToolbar, LiquidGlassToolbarItem } from "@/components/goodui/liquid-glass-button"

export function ViewSwitcher({ view, onViewChange }: { view: string; onViewChange: (v: string) => void }) {
  return (
    <LiquidGlassToolbar value={view} onValueChange={onViewChange} aria-label="Bookings view">
      <LiquidGlassToolbarItem value="list" compact>
        <LayoutList />
        <span>List</span>
      </LiquidGlassToolbarItem>
      <LiquidGlassToolbarItem value="calendar" compact>
        <CalendarDays />
        <span>Calendar</span>
      </LiquidGlassToolbarItem>
      <LiquidGlassToolbarItem value="map" compact>
        <Map />
        <span>Map</span>
      </LiquidGlassToolbarItem>
    </LiquidGlassToolbar>
  )
}
```

### Single glass button over a photo

```tsx
<div className="relative h-64 overflow-hidden rounded-2xl bg-[url(/salon.jpg)] bg-cover">
  <LiquidGlassButton size="lg" className="absolute start-4 bottom-4">
    Book this stylist
  </LiquidGlassButton>
</div>
```

### Dark tone icon button

```tsx
<LiquidGlassButton tone="dark" size="icon" aria-label="Share">
  <Share2 />
</LiquidGlassButton>
```

## API

### LiquidGlassButton

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| tone | `"light" \| "dark"` | `"light"` | "light" is a white tint for colorful or bright backdrops; "dark" a smoky tint. |
| blur | `number` | `14` | Backdrop blur in px. |
| fallback | `boolean` | — | Force the no-backdrop-filter look (to preview the fallback). |
| size | `"sm" \| "md" \| "lg" \| "icon"` | `"md"` | "sm" \| "md" \| "lg" \| "icon"; "icon" is a round 44px button. |

Also accepts every <button> attribute.

### LiquidGlassToolbar

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| tone | `"light" \| "dark"` | `"light"` | "light" is a white tint for colorful or bright backdrops; "dark" a smoky tint. |
| blur | `number` | `16` | Backdrop blur in px. |
| fallback | `boolean` | — | Force the no-backdrop-filter look (to preview the fallback). |
| value | `string` | — | Controlled selected item (the item's value). |
| defaultValue | `string` | — | Initially selected item when uncontrolled. |
| onValueChange | `(value: string) => void` | — | Called with the item's value when an item is clicked. |

Also accepts every <div> attribute.

### LiquidGlassToolbarItem

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| value (required) | `string` | — | Identifies the item; when it matches the toolbar's value the item is selected (aria-pressed). |
| compact | `boolean` | — | Hide the text label on small screens and keep only the icon. |

Also accepts every <button> attribute.

## Keyboard

| Keys | Action |
| --- | --- |
| Enter / Space | Activates a button or selects a toolbar item (native <button>). |
| Arrow Left / Arrow Right | Toolbar: moves focus to the previous or next enabled item, wrapping at the ends (swapped under dir="rtl"). |
| Home / End | Toolbar: moves focus to the first or last enabled item. |
| Tab | Toolbar: only the selected item is in the tab order (all items when nothing is selected). |

## Accessibility

- LiquidGlassToolbar has role="toolbar" and aria-orientation="horizontal"; give it an aria-label.
- Toolbar items are <button>s with aria-pressed showing the selected one.
- Text is white with a soft shadow; on very light backdrops check legibility, or use fallback, which (in the light tone) puts dark text on a near-opaque white tint.
- Browsers without backdrop-filter automatically get the solid fallback tint.

## Motion

- Button: hover scales to 1.03, press to 0.95, on a spring (stiffness 500, damping 26).
- A specular highlight follows the pointer through CSS variables and brightens on hover over 0.35 s.
- Toolbar: the selected lens glides between items with a shared layout animation (spring, stiffness 420, damping 32).
- Reduced motion: no hover or press scale, the lens jumps instead of gliding, and the highlight changes without a transition.

## Performance

- The highlight writes CSS variables on pointer move, so it never re-renders React. backdrop-filter costs GPU time; avoid dozens of glass elements over video.

## Notes for AI

- Place it over something worth blurring (image, gradient, aurora); on a flat background it looks like a washed-out button.
- Toolbar items need a unique value; control the toolbar with value/onValueChange or set defaultValue.
- compact hides a <span> child of the item below the sm breakpoint, so wrap the text label in <span> and keep the icon outside it.
- Sizes are sm, md, lg, icon; tone is light or dark. The glass button is always fully rounded.
- Icon-only items and buttons need an aria-label.

## FAQ

**What happens in browsers without backdrop-filter?**

An @supports rule switches to a near-opaque white (light tone) or smoky (dark tone) tint with readable text. Pass fallback to preview it anywhere.

**Is the toolbar a tab list?**

No. It is a toolbar of toggle buttons (aria-pressed). For tab panels, use tabs or tabs-indicator.

## Related

- segmented-control: https://goodui.dev/components/navigation/segmented-control
- button: https://goodui.dev/components/core/button
- aurora: https://goodui.dev/components/backgrounds/aurora
- dock: https://goodui.dev/components/navigation/dock

Last updated: 2026-11-02

---

# Theme toggle

> Light/dark toggle that reveals the new theme as a circle from the click point with the View Transitions API while the sun morphs into a moon.

Dark mode toggle for React and shadcn: circular reveal with View Transitions

Page: https://goodui.dev/components/buttons/theme-toggle

## Install

```bash
npx shadcn@latest add @goodui/theme-toggle
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/theme-toggle.json`. The file lands in `components/goodui/theme-toggle.tsx`.

## When to use

- The light/dark switch in an app header, settings menu or marketing navbar.
- Sites that toggle the `dark` class on <html> (the shadcn default) and want a polished switch without extra libraries.
- A settings row where a labeled switch is clearer: variant="pill".

## When not to use

- You need a third "System" option: use segmented-control with Light / Dark / System and set the class yourself.
- Your app is already wired to next-themes: call its setTheme from a button (or segmented-control); this component flips the <html> class directly and does not talk to next-themes.
- Toggling an ordinary setting: use switch.

## Pick by what matters

| Need | Use |
| --- | --- |
| Compact icon in a header | variant="icon" (default) |
| Two-icon switch in a settings panel | variant="pill" (role="switch") |
| No circular reveal | transition="none" |
| Remember the choice | storageKey="theme" plus a small script that applies it before paint |

## Usage

```tsx
import { ThemeToggle } from "@/components/goodui/theme-toggle"

export function AppHeader() {
  return (
    <header className="flex h-14 items-center justify-between border-b px-4">
      <span className="font-semibold">Brightside Cleaning</span>
      <ThemeToggle storageKey="theme" />
    </header>
  )
}
```

### Apply the saved theme before first paint (Next.js app/layout.tsx)

```tsx
<html lang="en" suppressHydrationWarning>
  <head>
    <script
      dangerouslySetInnerHTML={{
        __html: "try{if(localStorage.getItem('theme')==='dark'){document.documentElement.classList.add('dark')}}catch(e){}",
      }}
    />
  </head>
  <body>{children}</body>
</html>
```

### Pill switch with translated labels

```tsx
<ThemeToggle
  variant="pill"
  labels={{ darkTheme: "Modo oscuro", toLight: "Cambiar a tema claro", toDark: "Cambiar a tema oscuro" }}
  onThemeChange={(theme) => saveUserPreference({ theme })}
/>
```

## API

### ThemeToggle

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| onThemeChange | `(theme: Theme) => void` | — | Called after the `dark` class on <html> changes. |
| duration | `number` | `550` | Milliseconds for the circular reveal. |
| transition | `"circle" \| "none"` | `"circle"` | "circle" uses the View Transitions API when available; "none" switches instantly. |
| storageKey | `string` | — | Save the choice in localStorage under this key and apply the saved choice on mount (off by default). Add a head script to avoid a flash before hydration. |
| variant | `"icon" \| "pill"` | `"icon"` | "icon" is a round icon button; "pill" a two-icon switch. |
| labels | `Partial<ThemeToggleLabels>` | — | Text for built-in controls and screen readers; pass translations here. |

Also accepts every <button> attribute.

## Keyboard

| Keys | Action |
| --- | --- |
| Enter / Space | Toggles the theme (native <button>); keyboard toggles start the reveal from the button center. |
| Tab | Moves focus; a focus ring shows on keyboard focus only. |

## Accessibility

- variant="icon": a <button> whose aria-label says what will happen ("Switch to dark theme" / "Switch to light theme").
- variant="pill": role="switch" with aria-checked for dark and aria-label "Dark theme".
- All three strings come from labels, so they can be translated.
- It also sets color-scheme on <html>, so native scrollbars and form controls follow the theme.

## Motion

- With the View Transitions API, the new theme spreads as a circle from the click point (or the button center for keyboard) over `duration` ms (550) on cubic-bezier(0.4, 0, 0.2, 1).
- The icon morphs on a spring (stiffness 260, damping 22): the sun's core grows into a moon as a mask circle slides in and the rays spin away; the icon variant also turns once (stiffness 120, damping 16). The pill thumb slides on a spring (500, 32).
- The theme found on mount is shown without animation; only real changes animate.
- transition="none" or no View Transitions support: the theme switches instantly while the icon still morphs.
- Reduced motion: the theme switches instantly, the icon and pill thumb change without animation, and there is no tap scale.

## Notes for AI

- It toggles the `dark` class and color-scheme on document.documentElement; it does not render children and has no value prop. It mirrors outside class changes through a MutationObserver.
- storageKey saves the choice and applies the saved choice when the toggle mounts. That happens after hydration, so also add the small <head> script that applies it before paint, or the page can flash.
- If you use next-themes, do not combine it with this component; both would write the <html> class.
- The button is invisible (opacity 0) until mounted, to avoid showing the wrong icon during hydration.
- Translate through labels: toLight, toDark, darkTheme.

## FAQ

**Why does my page flash light on reload?**

With storageKey the toggle saves the choice and re-applies it on mount, but it cannot run before the first paint. Add a tiny inline script in <head> that reads the key and adds the dark class.

**Which browsers show the circular reveal?**

Browsers that support document.startViewTransition. Others switch instantly, with the icon still animating.

## Related

- switch: https://goodui.dev/components/core/switch
- segmented-control: https://goodui.dev/components/navigation/segmented-control
- switch-spring: https://goodui.dev/components/inputs/switch-spring
- button: https://goodui.dev/components/core/button

Last updated: 2026-11-02

---

# Text reveal

> Reveals a heading word by word or letter by letter with a staggered blur, fade and rise when it scrolls into view or on demand.

Text reveal animation for React and shadcn: word by word blur-in on scroll

Page: https://goodui.dev/components/text/text-reveal

## Install

```bash
npx shadcn@latest add @goodui/text-reveal
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/text-reveal.json`. The file lands in `components/goodui/text-reveal.tsx`.

## When to use

- A section heading or tagline that should reveal word by word when it scrolls into view.
- Step-by-step flows where text must hide and show again on demand (play={true/false}), such as onboarding slides.
- Sequencing: start the next animation when the text finishes, with onComplete.

## When not to use

- A normal heading that just needs an entrance: heading with animation="words", "letters" or "blur-in" is simpler and also gives size, font and treatment. Use TextReveal only when you need play control, replays, onComplete or custom timing.
- Paragraphs and body copy: staggering long text slows reading. Use text with animation="fade-up" or no animation.
- Rotating one word inside a sentence: use word-rotate.

## Pick by what matters

| Need | Use |
| --- | --- |
| Headline that reveals once on scroll | defaults (by="word", trigger="view", once) |
| Short, punchy word (logo, number) | by="char" |
| Replay every time it enters the viewport | once={false} |
| Above the fold, right away | trigger="mount" |
| Driven by your own state (slides, tabs) | play={isActive} |
| Entrance on a Core heading with no extra control | heading with animation="words" |

## Usage

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

export function FeaturesIntro() {
  return (
    <section className="py-24 text-center">
      <TextReveal
        as="h2"
        text="Every booking, invoice and reminder in one calm place"
        className="mx-auto max-w-2xl text-4xl font-semibold tracking-tight text-balance"
      />
    </section>
  )
}
```

### Controlled by a slide index

```tsx
<TextReveal
  as="h3"
  text={slides[index].title}
  key={index}
  play={active}
  onComplete={() => setShowCta(true)}
/>
```

### Letter by letter, faster

```tsx
<TextReveal as="h1" by="char" text="Brightside" trigger="mount" stagger={0.03} blur={4} className="text-6xl font-black" />
```

## API

### TextReveal

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| text (required) | `string` | — | The text to reveal; a plain string so it can be split (screen readers get it whole). |
| by | `"word" \| "char"` | `"word"` | Animate word by word or character by character. |
| as | `"h1" \| "h2" \| "h3" \| "h4" \| "p" \| "span" \| "div"` | `"p"` | Element to render, e.g. "h1" for a page title. |
| trigger | `"view" \| "mount"` | `"view"` | "view" plays when the text scrolls into view, "mount" plays right away. Ignored when `play` is set. |
| play | `boolean` | — | Controlled mode: true reveals, false hides. Leave undefined to use `trigger`. |
| once | `boolean` | `true` | With trigger="view": play only the first time it enters the viewport. |
| delay | `number` | `0` | Seconds before the first word or character. |
| stagger | `number` | — | Seconds between two words or characters. Defaults to 0.06 for words and 0.018 for characters. |
| duration | `number` | `0.5` | Seconds per unit. |
| blur | `number` | `8` | Starting blur in px. |
| onComplete | `() => void` | — | Called when the last word or character has finished revealing. |

Also accepts every <element> attribute.

## Accessibility

- The full text is rendered once in an sr-only span; the animated pieces are aria-hidden, so screen readers read it as one sentence.
- Use as="h1"…"h4" so the heading keeps its place in the document outline.
- Words are kept whole (each word is a no-wrap inline-block), so lines never break inside a word.

## Motion

- Each word (or character) rises 0.35em, fades in and unblurs from `blur` px (8) over `duration` s (0.5) on ease [0.22, 1, 0.36, 1].
- Units are staggered by `stagger` s: 0.06 for words, 0.018 for characters by default, after `delay`.
- trigger="view" plays when 35% of the element is visible; play={false} hides it again in 0.2 s.
- Reduced motion: no rise, blur or stagger; the whole text fades in over 0.2 s.

## Notes for AI

- text must be a plain string; markup and links inside it are not supported. Style the whole element with className.
- Set as for semantics (default is <p>); styling does not come from as.
- play overrides trigger. Leave play undefined to use trigger.
- Durations, delay and stagger are seconds, not milliseconds.
- To replay a new string, change text or key; with once (the default), a scroll-triggered reveal only plays the first time.
- by="char" splits into grapheme clusters (emoji and combining marks stay whole). Arabic-script text animates by word instead, because splitting joined letters breaks their shapes; RTL text otherwise works as is.

## FAQ

**Should I use this or the Core heading's animation?**

For a heading that animates once on view, the Core heading with animation="words" or "letters" is simpler. TextReveal adds controlled play, replays, onComplete and custom stagger, duration and blur.

**Is the text in the HTML before it animates?**

Yes. The full string is rendered in an sr-only span and as split words; only their opacity, position and blur animate.

## Related

- heading: https://goodui.dev/components/core/heading
- text: https://goodui.dev/components/core/text
- word-rotate: https://goodui.dev/components/text/word-rotate
- typewriter: https://goodui.dev/components/text/typewriter

Last updated: 2026-11-02

---

# Typewriter

> Types and deletes a list of phrases with a human rhythm and a caret that only blinks while idle; works as an animated input placeholder.

Typewriter effect for React and shadcn: typing text and animated placeholder

Page: https://goodui.dev/components/text/typewriter

## Install

```bash
npx shadcn@latest add @goodui/typewriter
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/typewriter.json`. The file lands in `components/goodui/typewriter.tsx`.

## When to use

- A hero line that types several use cases in turn ("Book a deep clean…", "Send a quote…").
- An animated placeholder behind a search or AI prompt input, paused while the input is focused.
- Chat or assistant previews where text should appear as if typed.

## When not to use

- Swapping one word inside a sentence: use word-rotate, which keeps the sentence readable at all times.
- Streaming real AI output: render the streamed tokens directly; this component types fixed phrases on a timer.
- Text that must be readable immediately (prices, instructions): use text.

## Pick by what matters

| Need | Use |
| --- | --- |
| Loop through several phrases | phrases={[…]} (loop is on by default) |
| Type once and stop | phrases="…" loop={false} |
| Animated input placeholder | paused={focused \|\| value !== ""}, positioned over the input |
| Slower, more deliberate typing | typeSpeed={90} pause={2400} |

## Usage

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

export function Hero() {
  return (
    <h1 className="text-4xl font-semibold tracking-tight">
      Your front desk can now{" "}
      <Typewriter
        className="text-primary"
        phrases={["book deep cleans", "send quotes", "remind no-shows", "collect deposits"]}
      />
    </h1>
  )
}
```

### Animated placeholder for an AI prompt input

```tsx
const [value, setValue] = React.useState("")
const [focused, setFocused] = React.useState(false)

<div className="relative">
  <input
    value={value}
    onChange={(e) => setValue(e.target.value)}
    onFocus={() => setFocused(true)}
    onBlur={() => setFocused(false)}
    aria-label="Ask the assistant"
    className="h-11 w-full rounded-lg border bg-background px-3"
  />
  {!value && (
    <Typewriter
      paused={focused}
      phrases={["Move Maya's 3pm to Friday", "Who hasn't paid this month?", "Draft a quote for a 3-bed move-out"]}
      className="pointer-events-none absolute inset-y-0 start-3 flex items-center text-muted-foreground"
    />
  )}
</div>
```

## API

### Typewriter

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| phrases (required) | `string \| string[]` | — | One phrase or a list of phrases typed one after another. |
| typeSpeed | `number` | `55` | Milliseconds per typed character (lightly randomised so it feels human). |
| deleteSpeed | `number` | `28` | Milliseconds per deleted character. |
| pause | `number` | `1600` | Milliseconds a finished phrase stays on screen. |
| startDelay | `number` | `300` | Milliseconds before the first character. |
| loop | `boolean` | `true` | Start again from the first phrase after the last one. |
| caret | `boolean` | `true` | Show the blinking caret. |
| caretClassName | `string` | — | Classes for the caret, e.g. a color or width. |
| paused | `boolean` | `false` | Freeze typing where it is, for example while an input is focused. |
| onPhraseComplete | `(index: number) => void` | — | Called with the phrase index each time a phrase is fully typed. |

Also accepts every <span> attribute.

## Accessibility

- Screen readers get every phrase at once in an sr-only span; the typed characters and the caret are aria-hidden.
- When used as a placeholder, give the input its own aria-label; the typed text is decoration.

## Motion

- Types one character every `typeSpeed` ms (55), randomized between 0.6x and 1.4x so it feels human; deletes at `deleteSpeed` ms (28) per character.
- A finished phrase stays for `pause` ms (1600); the first character waits `startDelay` ms (300).
- The caret blinks (1.05 s, step-end) only while idle and stays solid while typing or deleting.
- Reduced motion: whole phrases appear without typing and swap every 1.5 × pause; the caret does not blink.

## Notes for AI

- The prop is phrases (a string or string[]), not text, words or strings.
- All timing props are milliseconds.
- paused freezes typing where it is; use it while an input is focused instead of unmounting.
- loop={false} stops after the last phrase stays on screen; with one phrase and loop on, it deletes and retypes the same phrase.
- It renders a <span>, so put it inside your heading or paragraph rather than wrapping them.

## FAQ

**Does the caret take my text color?**

Yes, it is bg-current. Change it with caretClassName, for example caretClassName="bg-primary".

**Can I know when a phrase finishes?**

onPhraseComplete is called with the phrase index each time a phrase is fully typed.

## Related

- word-rotate: https://goodui.dev/components/text/word-rotate
- text-reveal: https://goodui.dev/components/text/text-reveal
- scramble-text: https://goodui.dev/components/text/scramble-text
- text-morph: https://goodui.dev/components/text/text-morph

Last updated: 2026-11-02

---

# Word rotate

> Swaps words in place with a vertical slide and blur while the box springs to each word's width, so the sentence glides instead of jumping.

Rotating words animation for React and shadcn: word flip in a headline

Page: https://goodui.dev/components/text/word-rotate

## Install

```bash
npx shadcn@latest add @goodui/word-rotate
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/word-rotate.json`. The file lands in `components/goodui/word-rotate.tsx`.

## When to use

- Hero headlines that cycle the audience or use case ("Scheduling for cleaners / salons / tutors").
- Short inline swaps inside a sentence, where the rest of the sentence should glide rather than jump.
- Feature carousels where the highlighted word should follow your own index (controlled mode).

## When not to use

- Showing whole sentences one after another: use typewriter or text-reveal.
- Changing a value people read (status, count): use text-morph for labels or number-flow for numbers.
- Key information such as a price or plan name: put it in static text (text or heading); a rotating word is easy to miss.

## Pick by what matters

| Need | Use |
| --- | --- |
| Auto-rotate in a headline | words={[…]} (interval 2400 ms) |
| Synced to your own carousel or tabs | index={i} onIndexChange={setI} |
| Centered headline | align="center" |
| Stop rotating (e.g. on hover) | paused |

## Usage

```tsx
import { WordRotate } from "@/components/goodui/word-rotate"

export function Hero() {
  return (
    <h1 className="text-4xl font-semibold tracking-tight">
      Online booking for{" "}
      <WordRotate words={["cleaners", "hair salons", "dog groomers", "tutors"]} className="text-primary" />
    </h1>
  )
}
```

### Controlled, synced with a feature list

```tsx
const [i, setI] = React.useState(0)

<h2 className="text-3xl font-semibold">
  <WordRotate words={["Bookings", "Invoices", "Reminders"]} index={i} onIndexChange={setI} align="center" />
  {" "}on autopilot
</h2>
```

## API

### WordRotate

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| words (required) | `string[]` | — | Words or short phrases shown one at a time, in order. |
| interval | `number` | `2400` | Milliseconds each word stays before the next one. |
| index | `number` | — | Controlled index of the visible word. |
| defaultIndex | `number` | `0` | Starting word when uncontrolled. |
| onIndexChange | `(index: number) => void` | — | Called with the next index on every automatic rotation. |
| paused | `boolean` | `false` | Stop auto-rotating (controls and `index` still work). |
| align | `"start" \| "center" \| "end"` | `"start"` | Where the word sits while the box resizes. |

Also accepts every <span> attribute.

## Accessibility

- An sr-only span holds the current word; the animated copies are aria-hidden.
- It is not a live region, so screen readers are not interrupted on every rotation.

## Motion

- The outgoing word slides up 0.7em and blurs while the next slides in from below, on a spring (stiffness 300, damping 30, mass 0.7).
- The box width springs to the incoming word (stiffness 260, damping 30, mass 0.8), so the words around it glide; the very first measurement is applied without animation.
- Rotation waits `interval` ms (2400) per word and pauses while off-screen, while the tab is hidden and when paused is set.
- Reduced motion: words cross-fade in 0.15 s and the width changes instantly.

## Notes for AI

- words is required and needs at least two entries to rotate.
- interval is milliseconds.
- In controlled mode, update index from onIndexChange, or rotation stops at the same word.
- It renders an inline-block <span>; put it inside your heading and style color and weight with className.
- Keep the words similar in length when possible, so the sentence does not reflow heavily.

## FAQ

**Why does the sentence not jump when the word changes?**

The word sits in a box whose width springs to the next word's measured width, so neighbouring words move smoothly. It re-measures when fonts load.

**Can I drive it from buttons?**

Yes, pass index (and onIndexChange); setting paused stops only the automatic rotation.

## Related

- typewriter: https://goodui.dev/components/text/typewriter
- text-morph: https://goodui.dev/components/text/text-morph
- text-reveal: https://goodui.dev/components/text/text-reveal
- heading: https://goodui.dev/components/core/heading

Last updated: 2026-11-02

---

# Shiny text

> A soft light band sweeps across muted text on a loop or on hover, made for badges like "New: AI receptionist". Pure CSS.

Shiny text effect for React and shadcn: light sweep across text

Page: https://goodui.dev/components/text/shiny-text

## Install

```bash
npx shadcn@latest add @goodui/shiny-text
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/shiny-text.json`. The file lands in `components/goodui/shiny-text.tsx`.

## When to use

- Announcement pills and eyebrow labels ("New: AI receptionist →") that should glint without being loud.
- Inline text inside a link or button that shines while it is hovered or focused (trigger="hover").
- "Thinking…" or "Generating…" status text in AI features.

## When not to use

- A whole heading with a shimmer: heading with treatment="shimmer" is simpler and keeps size, font and tone in one component.
- A badge that shines: badge with animation="shine" sweeps the whole pill. Use ShinyText when only the text should shine.
- Colorful gradient text without a sweep: use gradient-text.

## Pick by what matters

| Need | Use |
| --- | --- |
| Always-on glint for a badge or label | trigger="loop" (default) |
| Shine only while a link or button is hovered or focused | trigger="hover" inside the <a> or <button> |
| Shine when a larger card is hovered | trigger="hover" + data-shiny-group on the card |
| Brand-colored band | shineColor="var(--primary)" |
| Wider, softer band | spread={16} |

## Usage

```tsx
import { ArrowRight } from "lucide-react"
import { ShinyText } from "@/components/goodui/shiny-text"

export function Announcement() {
  return (
    <a
      href="/changelog/ai-receptionist"
      className="inline-flex items-center gap-1.5 rounded-full border bg-background px-3 py-1 text-sm"
    >
      <ShinyText trigger="hover">New: AI receptionist answers missed calls</ShinyText>
      <ArrowRight className="size-3.5 text-muted-foreground rtl:rotate-180" />
    </a>
  )
}
```

### AI status text

```tsx
<ShinyText duration={2} className="text-sm font-medium">
  Drafting your quote…
</ShinyText>
```

### Shine when a whole card is hovered

```tsx
<div data-shiny-group className="rounded-xl border p-4">
  <ShinyText trigger="hover" shineColor="var(--primary)">Pro plan · 2 months free</ShinyText>
</div>
```

## API

### ShinyText

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| duration | `number` | `2.8` | Seconds per cycle (the sweep takes about two thirds of it). |
| trigger | `"loop" \| "hover"` | `"loop"` | "loop" sweeps forever; "hover" sweeps while the text or its parent link/button is hovered or focused. |
| baseColor | `string` | — | Text color at rest. Defaults to muted-foreground. |
| shineColor | `string` | — | Color of the light band. Defaults to foreground. |
| spread | `number` | `9` | Half-width of the band, as a percent of the gradient. |

Also accepts every <span> attribute.

## Accessibility

- The text stays real text in a <span>; only its paint changes, so screen readers and copy-paste are unaffected.
- Resting color is muted-foreground by default; for small text on tinted backgrounds pass a stronger baseColor.
- Browsers without background-clip: text show the base color with no sweep.

## Motion

- A light band (half-width `spread` %, 9 by default) sweeps from left to right on ease-in-out, then rests off the text for the last third of each `duration` s cycle (2.8).
- trigger="hover" runs the loop while the text, or a parent <a>, <button> or [data-shiny-group], is hovered or has keyboard focus.
- Reduced motion: no sweep; the text shows in its base color.

## Performance

- Pure CSS (background-position on a clipped gradient); no JavaScript runs.

## Notes for AI

- Children are the text; there is no text prop.
- Do not set a text color class (text-*): the color is painted by the gradient. Use baseColor and shineColor.
- duration is seconds per cycle; spread is a percentage.
- For hover on a larger area, add data-shiny-group to the container instead of handling hover in JavaScript.

## FAQ

**Why does my text-* color class not work?**

The fill is a background clipped to the text, with a transparent text color. Use baseColor for the resting color and shineColor for the band.

**Heading treatment="shimmer" or ShinyText?**

For a heading, the Core heading's shimmer is the simpler choice. ShinyText is for inline text anywhere, with a hover trigger and custom colors and band width.

## Related

- gradient-text: https://goodui.dev/components/text/gradient-text
- heading: https://goodui.dev/components/core/heading
- badge: https://goodui.dev/components/core/badge
- shimmer-button: https://goodui.dev/components/buttons/shimmer-button

Last updated: 2026-11-02

---

# Gradient text

> Text filled with a slowly drifting multi-stop gradient, with Aurora, Sunset, Ocean and theme palettes tuned separately for light and dark.

Animated gradient text for React and shadcn: theme-aware gradient headings

Page: https://goodui.dev/components/text/gradient-text

## Install

```bash
npx shadcn@latest add @goodui/gradient-text
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/gradient-text.json`. The file lands in `components/goodui/gradient-text.tsx`.

## When to use

- One or two key words in a hero headline ("Bookings that run themselves", with only the last two words in gradient).
- A product or plan name that should carry the brand colors.
- When the same gradient must look good in light and dark: the presets have separate, deeper light-mode colors.

## When not to use

- A heading that only needs a gradient: heading with treatment="gradient" (or emphasis="gradient" for the _italic_ words) is simpler and keeps size, font and tone in one component.
- A light sweep on muted text: use shiny-text.
- Body copy, links and small labels: gradients lower legibility at small sizes. Use text with a tone.

## Pick by what matters

| Need | Use |
| --- | --- |
| Cool, techy | palette="aurora" (default) |
| Warm, friendly | palette="sunset" |
| Calm blues | palette="ocean" |
| Follow the theme's chart colors | palette="brand" |
| Exact brand colors | colors={["#…", "#…", "#…"]} |
| Static gradient | animate={false} |

## Usage

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

export function Hero() {
  return (
    <h1 className="text-5xl font-bold tracking-tight">
      Bookings that <GradientText>run themselves</GradientText>
    </h1>
  )
}
```

### Brand palette, static

```tsx
<GradientText palette="brand" animate={false} className="font-semibold">
  Brightside Pro
</GradientText>
```

### Custom colors, slower drift

```tsx
<GradientText colors={["#7c3aed", "#db2777", "#f59e0b"]} duration={14}>
  Black Friday: 40% off annual plans
</GradientText>
```

## API

### GradientText

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| palette | `"aurora" \| "sunset" \| "ocean" \| "brand"` | `"aurora"` | Theme-aware preset. "brand" follows the theme's chart colors. |
| colors | `string[]` | — | Custom stops; overrides `palette`. The first color is repeated at the end for a seamless loop. |
| animate | `boolean` | `true` | Move the gradient. |
| duration | `number` | `8` | Seconds per loop. |

Also accepts every <span> attribute.

## Accessibility

- The text stays real text; only the paint is a gradient, so screen readers and copy-paste are unaffected.
- Light-mode presets use deeper colors and dark-mode presets brighter ones, chosen to keep the text readable on each background. Check contrast yourself for custom colors.
- Browsers without background-clip: text show the first palette color as a solid text color.

## Motion

- The gradient (200% wide) drifts horizontally in a seamless linear loop, one cycle every `duration` s (8).
- Text that wraps onto several lines gets the gradient per line (box-decoration-break: clone).
- Reduced motion: the gradient stops moving and stays visible.

## Performance

- Pure CSS (background-position animation); no JavaScript runs.

## Notes for AI

- Wrap only the words that need emphasis, not whole paragraphs.
- Do not add text-* color classes; the color comes from the gradient. Pick a palette or pass colors.
- colors needs at least two colors; the first is repeated at the end so the loop is seamless. One color is ignored.
- Custom colors apply in both themes; pick colors that work on light and dark or use a preset.

## FAQ

**Heading treatment="gradient" or GradientText?**

For a whole heading, or emphasized words in it, the Core heading is simpler. GradientText works inline in any element and adds four palettes, custom colors and a drifting animation.

**Does "brand" follow my theme?**

Yes, it uses --chart-1, --chart-2, --chart-4 and --chart-5 from your theme.

## Related

- heading: https://goodui.dev/components/core/heading
- shiny-text: https://goodui.dev/components/text/shiny-text
- highlighter: https://goodui.dev/components/text/highlighter
- aurora: https://goodui.dev/components/backgrounds/aurora

Last updated: 2026-11-02

---

# Scramble text

> Text scrambles through random glyphs and resolves left to right on mount, on view, on hover or on demand; renders the real text on the server.

Scramble text effect for React and shadcn: decrypt and hacker text animation

Page: https://goodui.dev/components/text/scramble-text

## Install

```bash
npx shadcn@latest add @goodui/scramble-text
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/scramble-text.json`. The file lands in `components/goodui/scramble-text.tsx`.

## When to use

- Short technical labels that should feel computed: API key names, status codes, "Deploying…".
- Nav links or buttons that scramble once on hover for a developer-tool vibe (trigger="hover").
- Revealing a generated value (a confirmation code, a booking reference) after an action, with replay.

## When not to use

- Headlines and long sentences: random glyphs make them unreadable for most of the animation. Use text-reveal.
- Switching between two readable labels: use text-morph, which keeps shared letters in place.
- Numbers that change: use number-flow.

## Pick by what matters

| Need | Use |
| --- | --- |
| Play on page load | trigger="mount" (default) |
| Play when it scrolls into view | trigger="view" |
| Play on hover | trigger="hover" |
| Play from your code | trigger="manual" and change replay (e.g. a counter) |
| Numbers-only glyphs | characters="0123456789" |

## Usage

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

export function BookingConfirmed({ reference }: { reference: string }) {
  return (
    <div className="rounded-xl border bg-card p-6 text-center">
      <p className="text-sm text-muted-foreground">Booking reference</p>
      <ScrambleText text={reference} trigger="view" className="font-mono text-2xl font-semibold tracking-widest" />
    </div>
  )
}
```

### Replay from a button

```tsx
const [run, setRun] = React.useState(0)

<ScrambleText text="sk_live_••••4f2a" trigger="manual" replay={run} className="font-mono" />
<button onClick={() => setRun((n) => n + 1)}>Regenerate key</button>
```

### Hover scramble on a nav link

```tsx
<a href="/docs" className="font-mono text-sm uppercase">
  <ScrambleText text="Documentation" trigger="hover" duration={600} />
</a>
```

## API

### ScrambleText

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| text (required) | `string` | — | The final text; it is rendered as-is on the server and before the first run. |
| trigger | `"mount" \| "view" \| "hover" \| "manual"` | `"mount"` | When to play: on mount, when scrolled into view, on hover/focus (of the text or its closest link/button), or only via `replay`. |
| replay | `number \| string` | — | Change this value (e.g. a counter) to play again. |
| duration | `number` | `900` | Milliseconds until the last character resolves. |
| speed | `number` | `45` | Milliseconds between glyph changes. |
| characters | `string` | `GLYPHS` | Glyphs used while scrambling. |
| scrambledClassName | `string` | — | Classes for the not-yet-resolved part (default: 60% opacity of the current color). |
| onComplete | `() => void` | — | Called when the last character has resolved. |

Also accepts every <span> attribute.

## Accessibility

- The real text is always in an sr-only span; the scrambling copy is aria-hidden, so screen readers never read random glyphs.
- The real text is rendered on the server and before the first run; randomness only happens after mount, so there is no hydration mismatch.
- trigger="hover" also plays on keyboard focus: the span itself is not focusable, so it listens to its closest link, button or [tabindex] ancestor (focus and pointer enter). Put it inside a link or button for keyboard users to get the same effect.

## Motion

- Characters resolve left to right over `duration` ms (900); the unresolved tail re-rolls random glyphs every `speed` ms (45). Spaces are kept.
- The unresolved part is the current color at 60% opacity, so it keeps contrast on muted or tinted backgrounds (override with scrambledClassName).
- Reduced motion: no scramble; the real text is shown and onComplete is not called.

## Performance

- Uses requestAnimationFrame for at most `duration` ms per run and cancels on unmount; nothing runs between plays.

## Notes for AI

- Use the text prop; children are not accepted.
- duration and speed are milliseconds.
- replay replays on every change of its value, whatever the trigger; the first value does not play.
- Pair it with a monospace font (font-mono) so the width does not jump while glyphs change.

## FAQ

**Why does the width jump while scrambling?**

Random glyphs have different widths in proportional fonts. Use a monospace font, or restrict characters to glyphs of similar width.

**Is the real text in the server HTML?**

Yes. The server and the first client render show the real text; the scramble only starts after mount.

## Related

- text-morph: https://goodui.dev/components/text/text-morph
- typewriter: https://goodui.dev/components/text/typewriter
- text-reveal: https://goodui.dev/components/text/text-reveal
- number-flow: https://goodui.dev/components/numbers/number-flow

Last updated: 2026-11-02

---

# Highlighter

> Draws a marker highlight, hand-drawn underline, circle, box or strike-through behind a phrase when it scrolls into view, in six colors.

Text highlighter animation for React and shadcn: marker, underline and circle

Page: https://goodui.dev/components/text/highlighter

## Install

```bash
npx shadcn@latest add @goodui/highlighter
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/highlighter.json`. The file lands in `components/goodui/highlighter.tsx`.

## When to use

- Drawing attention to the key phrase of a landing-page paragraph as it scrolls into view ("cut no-shows by 40%").
- Pricing and comparison copy: circle the saving, strike the old price.
- Onboarding and docs, to point at the one thing to notice, controlled by your own state.

## When not to use

- A highlighted word inside a heading: heading with treatment="highlight" or "underline-squiggle" and *marked* words is simpler.
- Search-result matches in lists and tables: use a plain <mark>; animation there is distracting.
- Coloring a word without a mark: use gradient-text or text with a tone.

## Pick by what matters

| Need | Use |
| --- | --- |
| Marker behind a phrase (wraps across lines) | action="highlight" (default) |
| Hand-drawn underline | action="underline" |
| Circle a number or price | action="circle" |
| Box a term | action="box" |
| Old price | action="strike" color="rose" |
| Follow the theme color | color="primary" |
| Draw from your own state | show={step === 2} |

## Usage

```tsx
import { Highlighter } from "@/components/goodui/highlighter"

export function Benefit() {
  return (
    <p className="max-w-xl text-lg text-muted-foreground">
      Automatic SMS reminders{" "}
      <Highlighter className="text-foreground">cut no-shows by 40%</Highlighter>
      {" "}for salons in their first month, and clients can{" "}
      <Highlighter action="underline" color="sky" delay={0.4}>reschedule in one tap</Highlighter>.
    </p>
  )
}
```

### Old and new price

```tsx
<p className="text-2xl font-semibold">
  <Highlighter action="strike" color="rose">$49</Highlighter>{" "}
  <Highlighter action="circle" color="emerald" delay={0.5} padding={8}>$29</Highlighter>
  <span className="text-base text-muted-foreground"> / month</span>
</p>
```

### Controlled by an onboarding step

```tsx
<Highlighter action="box" color="primary" show={step === 2}>Connect your calendar</Highlighter>
```

## API

### Highlighter

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| action | `"highlight" \| "underline" \| "circle" \| "box" \| "strike"` | `"highlight"` | Marker highlight (wraps across lines), or a hand-drawn underline, circle, box or strike-through. |
| color | `"amber" \| "emerald" \| "sky" \| "rose" \| "violet" \| "primary"` | `"amber"` | Marker and stroke color, tuned for light and dark; "primary" follows the theme. |
| show | `boolean` | — | Controlled: true draws, false erases. Leave undefined to draw when scrolled into view. |
| once | `boolean` | `true` | With automatic triggering: draw only the first time it enters the viewport. |
| delay | `number` | `0` | Seconds before drawing starts. |
| duration | `number` | `0.8` | Seconds the stroke takes. |
| strokeWidth | `number` | `2` | Stroke width in px for underline, circle, box and strike (not used by highlight). |
| padding | `number` | `6` | Extra space in px between the text and a circle or box. |

Also accepts every <span> attribute.

## Accessibility

- The text stays plain text in a <span>; the drawn shapes are an aria-hidden SVG with pointer-events: none.
- The marker is decoration: if the emphasis carries meaning, also use <strong> or <em> inside it.
- Each color has separate light and dark values; the dark-mode marker is a translucent tint (about 30% opacity) that light text shows through.

## Motion

- highlight: the marker grows from left to right by animating background-size over `duration` s (0.8) on cubic-bezier(0.65, 0, 0.35, 1), after `delay` s. It wraps across lines.
- underline, circle, box, strike: an SVG path built from the measured text size draws itself (pathLength) with the same duration, delay and easing.
- Without show, it draws when 80% of the phrase is visible, once by default (once={false} erases and redraws on each visit).
- Reduced motion: marks appear at once, without drawing.

## Notes for AI

- Wrap only the phrase to mark; children are the text.
- Durations and delay are seconds. strokeWidth and padding (px) only affect the SVG actions, not highlight.
- Colors are amber, emerald, sky, rose, violet and primary; there is no custom color prop.
- underline, circle, box and strike turn the span into an inline-block, so keep those phrases short enough to stay on one line; use highlight for phrases that wrap.
- Stagger several highlights with delay rather than separate timers.

## FAQ

**Does the marker work across line breaks?**

Yes, action="highlight" is a CSS background on the inline text, so it follows every line. The SVG actions make the phrase an inline-block, so they belong on short phrases.

**Does it redraw when the text resizes?**

Yes. The SVG actions re-measure with a ResizeObserver, so shapes keep fitting after font loads and layout changes.

## Related

- heading: https://goodui.dev/components/core/heading
- gradient-text: https://goodui.dev/components/text/gradient-text
- text-reveal: https://goodui.dev/components/text/text-reveal
- text: https://goodui.dev/components/core/text

Last updated: 2026-11-02

---

# Text morph

> Morphs between strings letter by letter: shared characters spring to their new positions while the rest blur in and out.

Text morph animation for React and shadcn: smooth label change letter by letter

Page: https://goodui.dev/components/text/text-morph

## Install

```bash
npx shadcn@latest add @goodui/text-morph
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/text-morph.json`. The file lands in `components/goodui/text-morph.tsx`.

## When to use

- Button and status labels that change in place: "Save" → "Saving" → "Saved", "Follow" → "Following".
- Toggle labels such as "Monthly" / "Yearly" on a pricing switch.
- Short headings that swap with app state ("3 bookings today" → "4 bookings today").

## When not to use

- Changing numbers that should roll like an odometer: use number-flow.
- Rotating through a list of words on a timer: use word-rotate.
- A button that needs full loading, success and error states: use stateful-button.

## Usage

```tsx
import * as React from "react"
import { TextMorph } from "@/components/goodui/text-morph"

export function FollowButton() {
  const [following, setFollowing] = React.useState(false)
  return (
    <button
      type="button"
      onClick={() => setFollowing((f) => !f)}
      className="inline-flex h-9 items-center rounded-lg border px-4 text-sm font-medium"
    >
      <TextMorph text={following ? "Following" : "Follow"} />
    </button>
  )
}
```

### Billing period toggle label

```tsx
<TextMorph text={yearly ? "Billed yearly · save 20%" : "Billed monthly"} className="text-sm text-muted-foreground" />
```

## API

### TextMorph

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| text (required) | `string` | — | The current string; change it to morph. Characters both strings share slide into place. |

Also accepts every <span> attribute.

## Accessibility

- An sr-only span holds the current string; the animated letters are aria-hidden.
- Inside a button, the button's accessible name follows the current text. It is not a live region; add one yourself if a status change must be announced.

## Motion

- Each character is keyed by itself and its occurrence, so letters both strings share slide to their new position with a layout spring (stiffness 420, damping 34, mass 0.6).
- Letters that leave fade out, blur 4px and shrink to 0.9; new letters do the reverse, over 0.22 s.
- Reduced motion: letters swap instantly, with no slide, blur or fade.

## Notes for AI

- The only prop besides HTML attributes is text (a string); children are not supported.
- Keep strings short (labels, not paragraphs): every character is its own animated span.
- It renders an inline-flex span with white-space: pre, so it never wraps; do not use it for multi-line text.
- Matching is case-sensitive: "Save" and "save" share only "ave".

## FAQ

**Why do some letters slide and others fade?**

Characters present in both strings keep their identity and slide; characters that exist in only one string fade and blur in or out.

## Related

- number-flow: https://goodui.dev/components/numbers/number-flow
- word-rotate: https://goodui.dev/components/text/word-rotate
- stateful-button: https://goodui.dev/components/buttons/stateful-button
- scramble-text: https://goodui.dev/components/text/scramble-text

Last updated: 2026-11-02

---

# Scroll velocity

> Rows of large text drift in opposite directions and speed up or flip with your scroll speed and direction.

Scroll velocity text for React and shadcn: marquee that speeds up with scroll

Page: https://goodui.dev/components/text/scroll-velocity

## Install

```bash
npx shadcn@latest add @goodui/scroll-velocity
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/scroll-velocity.json`. The file lands in `components/goodui/scroll-velocity.tsx`.

## When to use

- A bold band of large text between landing-page sections (services, cities, client types) that reacts to scrolling.
- Agency and portfolio sites where scroll-linked motion is part of the brand.
- Rows of custom content (logos, chips) that should drift and respond to scroll speed, using ScrollVelocityRow.

## When not to use

- A steady logo or testimonial ticker that should not react to scrolling: use marquee, which is CSS-only and pauses on hover.
- Inside dense app screens: moving text competes with the data. Use a static heading.
- Text people must read in full: it is constantly moving, so put essential copy in static text.

## Pick by what matters

| Need | Use |
| --- | --- |
| Rows of big words | ScrollVelocity with items={[…]} |
| Custom content per row (logos, chips) | ScrollVelocityRow with children |
| Calmer drift | baseVelocity={20} |
| Constant speed, no scroll reaction | velocityFactor={0} (or use marquee) |
| Inside a scrolling panel | scrollContainer={panelRef} |

## Usage

```tsx
import { ScrollVelocity } from "@/components/goodui/scroll-velocity"

export function ServicesBand() {
  return (
    <section className="overflow-hidden py-16">
      <ScrollVelocity
        items={["Deep cleans · Move-outs · Offices", "Windows · Carpets · Post-construction"]}
        baseVelocity={30}
        rowClassName="text-5xl font-bold tracking-tight sm:text-7xl"
      />
    </section>
  )
}
```

### A row of client logos with ScrollVelocityRow

```tsx
<ScrollVelocityRow baseVelocity={-25}>
  {logos.map((l) => (
    <img key={l.name} src={l.src} alt={l.name} className="mx-8 h-8 w-auto opacity-70" />
  ))}
</ScrollVelocityRow>
```

## API

### ScrollVelocity

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| items (required) | `string[]` | — | One string per row. Rows alternate direction. |
| baseVelocity | `number` | `40` | Pixels per second at rest. |
| scrollContainer | `React.RefObject<HTMLElement \| null>` | — | Scrollable element to track. Defaults to the window. |
| velocityFactor | `number` | `1` | How strongly scroll speed boosts the rows. 0 turns the effect off. |
| separator | `React.ReactNode` | `"·"` | Shown between repeats of a row. |
| rowClassName | `string` | — | Classes for every row, e.g. the font size and weight. |

Also accepts every <div> attribute.

### ScrollVelocityRow

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| children (required) | `React.ReactNode` | — | Content of one repeat; it is copied as many times as needed to fill the row. |
| baseVelocity | `number` | `40` | Pixels per second at rest. Negative moves to the right. |
| scrollContainer | `React.RefObject<HTMLElement \| null>` | — | Scrollable element to track. Defaults to the window. |
| velocityFactor | `number` | `1` | How strongly scroll speed boosts the row. 0 turns the effect off. |

Also accepts every <div> attribute.

## Accessibility

- ScrollVelocity puts all items once in an sr-only paragraph and marks the moving rows aria-hidden.
- ScrollVelocityRow alone marks only the extra copies aria-hidden; the first copy stays readable, so give images alt text.
- Reduced motion keeps rows still, so the text can be read.
- With scrollContainer, make that container keyboard-scrollable: tabIndex={0}, an aria-label (or role="region" with a name) and a visible focus ring.

## Motion

- Each row drifts at `baseVelocity` px per second (40); ScrollVelocity alternates direction per row. Positive values move left.
- Scroll speed is smoothed with a spring (damping 50, stiffness 400) and adds 5x the base speed per 1000 px/s of scroll, times `velocityFactor`; scrolling up flips the direction.
- Content is repeated enough times to cover the row plus one copy, and wraps seamlessly.
- Rows stop while off-screen. Reduced motion: rows do not move at all.

## Performance

- Moves one motion value per row on requestAnimationFrame (frame delta capped at 50 ms), so React does not re-render while it runs. A ResizeObserver recomputes the copy count.

## Notes for AI

- ScrollVelocity takes items (string[]), one row each; ScrollVelocityRow takes children.
- baseVelocity is px per second; negative values move to the right.
- Style the text size with rowClassName (ScrollVelocity) or className (ScrollVelocityRow).
- It tracks the window scroll by default; pass scrollContainer (a ref) when the page scrolls inside a div.

## FAQ

**Marquee or ScrollVelocity?**

Marquee is a steady CSS ticker that pauses on hover. ScrollVelocity is driven by JavaScript and reacts to scroll speed and direction.

**Can it track a scrolling div instead of the window?**

Yes, pass scrollContainer with a ref to that element.

## Related

- marquee: https://goodui.dev/components/backgrounds/marquee
- text-reveal: https://goodui.dev/components/text/text-reveal
- gradient-text: https://goodui.dev/components/text/gradient-text
- word-rotate: https://goodui.dev/components/text/word-rotate

Last updated: 2026-11-02

---

# Spotlight card

> A soft spotlight and a lit border follow the pointer across a card; in a group, neighboring cards' borders light up too.

Spotlight card for React and shadcn: cursor-following glow and lit border

Page: https://goodui.dev/components/cards/spotlight-card

## Install

```bash
npx shadcn@latest add @goodui/spotlight-card
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/spotlight-card.json`. The file lands in `components/goodui/spotlight-card.tsx`.

## When to use

- Feature grids and bento layouts on a landing page, where a soft light following the cursor adds depth.
- A grid of plans, integrations or services where neighboring borders should light up together (SpotlightGroup).
- Dark sections, where the lit border reads especially well.

## When not to use

- A single card that also needs variants, tones, padding and header/footer parts: card with animation="spotlight" is simpler and gives the same effect.
- Clickable rows in dense lists and tables: use a plain hover background; a spotlight per row is noisy.
- Touch-first screens: the effect needs a hovering pointer. Use card or tilt-card for a press response.

## Pick by what matters

| Need | Use |
| --- | --- |
| One card with the effect | SpotlightCard |
| A grid where neighboring borders light up together | SpotlightGroup around SpotlightCards |
| Brand-colored light | spotlightColor="color-mix(in oklch, var(--primary) 12%, transparent)" borderColor="var(--primary)" |
| Card with a 2px border | borderWidth={2} plus border-2 |
| Single card with variants and tones | card with animation="spotlight" |

## Usage

```tsx
import { CalendarCheck, CreditCard, MessageSquare } from "lucide-react"
import { SpotlightCard, SpotlightGroup } from "@/components/goodui/spotlight-card"

const features = [
  { icon: CalendarCheck, title: "Online booking", text: "Clients pick a slot from your real availability." },
  { icon: MessageSquare, title: "SMS reminders", text: "Automatic reminders 24 hours and 2 hours before." },
  { icon: CreditCard, title: "Deposits", text: "Take a card deposit when the booking is made." },
]

export function Features() {
  return (
    <SpotlightGroup className="grid gap-4 sm:grid-cols-3">
      {features.map((f) => (
        <SpotlightCard key={f.title} className="p-6">
          <f.icon className="size-5 text-primary" />
          <h3 className="mt-4 font-semibold">{f.title}</h3>
          <p className="mt-1 text-sm text-muted-foreground">{f.text}</p>
        </SpotlightCard>
      ))}
    </SpotlightGroup>
  )
}
```

### Single card in the brand color

```tsx
<SpotlightCard
  className="p-6"
  size={420}
  spotlightColor="color-mix(in oklch, var(--primary) 12%, transparent)"
  borderColor="var(--primary)"
>
  <h3 className="font-semibold">Pro plan</h3>
  <p className="text-sm text-muted-foreground">Unlimited staff and locations.</p>
</SpotlightCard>
```

## API

### SpotlightCard

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| spotlightColor | `string` | — | Fill color of the soft spotlight. |
| borderColor | `string` | — | Color of the lit border. |
| size | `number` | `360` | Diameter of the spotlight in px. |
| borderWidth | `number` | `1` | Border width the highlight should cover, in px (match the card's border). |

Also accepts every <div> attribute.

### SpotlightGroup

Also accepts every <div> attribute.

## Accessibility

- SpotlightCard is a plain <div> with card styles; the light is drawn with pseudo-elements that ignore the pointer and are not announced.
- If the whole card is clickable, put a real link or button inside it; the card itself is not focusable.
- The effect follows the pointer only; keyboard users see a normal card.

## Motion

- A soft radial fill (`size` px, 360) and a lit border ring (75% of that size) follow the pointer and fade in and out over 0.35 s.
- Inside a SpotlightGroup, moving anywhere over the group lights the borders of every card near the pointer, while only the hovered card gets the fill.
- The light follows the pointer directly; nothing loops.
- Reduced motion: the fade in and out is instant.

## Performance

- Pointer moves only write two CSS variables; React does not re-render. SpotlightGroup batches updates to one per animation frame.

## Notes for AI

- Put padding and layout on SpotlightCard with className (p-6 …); it already has rounded-xl, border, bg-card.
- SpotlightGroup is a plain div: give it the grid classes. Cards can be nested at any depth inside it.
- Colors are any CSS color; use translucent fills (color-mix with transparent), or the content gets washed out.
- Match borderWidth to the card's border width so the lit ring covers it exactly.

## FAQ

**Core card animation="spotlight" or SpotlightCard?**

For one card, the Core card is simpler and adds variants, tones and parts. SpotlightCard adds SpotlightGroup (linked borders across a grid) and custom colors, size and border width.

**Do the cards have to be direct children of SpotlightGroup?**

No. The group finds every SpotlightCard inside it at any depth, so wrappers and grid cells are fine.

## Related

- card: https://goodui.dev/components/core/card
- tilt-card: https://goodui.dev/components/cards/tilt-card
- glow-border: https://goodui.dev/components/cards/glow-border
- border-beam: https://goodui.dev/components/cards/border-beam

Last updated: 2026-11-02

---

# Tilt card

> Tilts toward the pointer on a spring with a moving glare, a shifting shadow and layers that float at their own depth.

3D tilt card for React and shadcn: hover tilt with glare and parallax layers

Page: https://goodui.dev/components/cards/tilt-card

## Install

```bash
npx shadcn@latest add @goodui/tilt-card
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/tilt-card.json`. The file lands in `components/goodui/tilt-card.tsx`.

## When to use

- Showcase cards on a landing page: a pricing plan, a product shot, a gift card or membership card.
- Cards with layered content (badge, avatar, price) that should float at different depths with TiltCardLayer.
- Portfolio and template galleries, where a tactile hover invites a click.

## When not to use

- A card that only needs a simple tilt plus variants, tones and header/footer parts: card with animation="tilt" is simpler. Use TiltCard for springs, glare control and depth layers.
- Data-heavy cards (tables, charts, forms): tilting makes text harder to read and click. Use card with animation="lift".
- Large grids of many cards: one tilting card draws the eye, twenty feel restless. Use spotlight-card with SpotlightGroup.

## Pick by what matters

| Need | Use |
| --- | --- |
| Subtle, app-friendly tilt | maxTilt={6} scale={1.01} |
| Dramatic showcase | maxTilt={15} perspective={600} |
| No glare | glare={false} |
| Floating badge or image | <TiltCardLayer depth={40}>…</TiltCardLayer> |
| Turn it off conditionally | disabled |

## Usage

```tsx
import { TiltCard, TiltCardLayer } from "@/components/goodui/tilt-card"

export function MembershipCard() {
  return (
    <TiltCard className="w-80 bg-gradient-to-br from-violet-600 to-indigo-700 p-6 text-white">
      <TiltCardLayer depth={20}>
        <p className="text-xs tracking-widest text-white/70 uppercase">Glow Studio</p>
      </TiltCardLayer>
      <TiltCardLayer depth={50} className="mt-10">
        <p className="text-2xl font-semibold">Gold membership</p>
        <p className="text-sm text-white/80">Unlimited blow-dries · 10% off color</p>
      </TiltCardLayer>
      <TiltCardLayer depth={30} className="mt-8 flex items-end justify-between">
        <span className="text-sm">Maya Chen</span>
        <span className="font-mono text-sm">$89/mo</span>
      </TiltCardLayer>
    </TiltCard>
  )
}
```

### Calm pricing card

```tsx
<TiltCard maxTilt={6} scale={1.01} glareOpacity={0.2} className="p-6" containerClassName="h-full">
  <h3 className="font-semibold">Team</h3>
  <p className="mt-2 text-3xl font-bold">$49<span className="text-base font-normal text-muted-foreground">/mo</span></p>
</TiltCard>
```

## API

### TiltCard

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| maxTilt | `number` | `10` | Maximum tilt in degrees. |
| scale | `number` | `1.02` | Scale while hovered. |
| glare | `boolean` | `true` | Show a light glare that follows the pointer. |
| glareOpacity | `number` | `0.35` | Peak opacity of the glare. |
| perspective | `number` | `900` | CSS perspective in px; lower is more dramatic. |
| disabled | `boolean` | `false` | Keep the card flat (no tilt, glare or scale). |
| containerClassName | `string` | — | Classes for the outer element that holds the perspective and receives the pointer. |

Also accepts every <div> attribute.

### TiltCardLayer

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| depth | `number` | `30` | How far the layer floats above the card, in px. |

Also accepts every <div> attribute.

## Accessibility

- TiltCard renders two plain <div>s (a perspective container and the card); it adds no roles. Put real links or buttons inside for interaction.
- The glare layer is aria-hidden and ignores the pointer.
- Touch, keyboard and reduced-motion users get a flat card with the same content.

## Motion

- The card rotates toward the pointer by up to `maxTilt` degrees (10) and scales to `scale` (1.02), on a spring (stiffness 220, damping 22, mass 0.6).
- A radial glare follows the pointer at up to `glareOpacity` (0.35), and the shadow shifts against the tilt and fades in on hover (spring, stiffness 200, damping 26).
- TiltCardLayer children float `depth` px (30) above the card with translateZ, so they move with parallax.
- Leaving the card springs it back flat. Touch input is ignored.
- Reduced motion or disabled: no tilt, scale, glare or shadow shift; the card stays flat.

## Performance

- Pointer moves only set motion values, so React does not re-render. Effects use transform, opacity and box-shadow.

## Notes for AI

- className styles the card (padding, background); containerClassName styles the outer element that holds the perspective and receives the pointer (sizing in grids, e.g. h-full).
- TiltCardLayer only floats when every element between it and the card keeps transform-style: preserve-3d and has no overflow: hidden.
- maxTilt is degrees, perspective and depth are px, scale is a factor (1.02 means 2% larger).
- The card already has rounded-xl, border, bg-card; override with className.

## FAQ

**Why is my layer not floating?**

Some element between the layer and the card flattens 3D: overflow: hidden, or a wrapper without transform-style: preserve-3d. Make TiltCardLayer a direct child of TiltCard, or nest layers inside layers.

**Core card animation="tilt" or TiltCard?**

The Core card's tilt is a CSS transition with a light sheen and works with all card variants. TiltCard adds springs, a glare you can tune, a moving shadow and parallax layers.

## Related

- card: https://goodui.dev/components/core/card
- spotlight-card: https://goodui.dev/components/cards/spotlight-card
- magnetic-button: https://goodui.dev/components/buttons/magnetic-button
- glow-border: https://goodui.dev/components/cards/glow-border

Last updated: 2026-11-02

---

# Border beam

> Wraps any card or input and runs a light beam around its border, matching the element's corner radius automatically.

Border beam animation for React and shadcn: light beam around any card or input

Page: https://goodui.dev/components/cards/border-beam

## Install

```bash
npx shadcn@latest add @goodui/border-beam
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/border-beam.json`. The file lands in `components/goodui/border-beam.tsx`.

## When to use

- Highlighting the recommended pricing plan or the one card that is new.
- Drawing the eye to an input that matters (an AI prompt box, a search field) without changing its style.
- Hero product screenshots and code blocks that need a subtle sign of life.

## When not to use

- A Core card that just needs a moving border: card with animation="border-beam" is simpler. Use BorderBeam to wrap anything else (inputs, images, your own cards) or to tune size, speed, colors and beam count.
- A button: use border-beam-button, which is built for it and keeps a static gradient for reduced motion.
- A soft colored glow around the whole edge: use glow-border.

## Pick by what matters

| Need | Use |
| --- | --- |
| Recommended plan card | defaults around the card |
| Two beams chasing each other | beams={2} |
| Calmer | duration={10} |
| Card with a 2px border | borderWidth={2} |
| Several beams out of sync | delay={…} on each |
| Radius the measurement gets wrong | radius={16} |

## Usage

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

export function RecommendedPlan() {
  return (
    <BorderBeam className="rounded-2xl" beams={2} duration={8}>
      <div className="rounded-2xl border bg-card p-6">
        <p className="text-sm font-medium text-primary">Most popular</p>
        <h3 className="mt-1 text-xl font-semibold">Team</h3>
        <p className="mt-4 text-3xl font-bold">$49<span className="text-base font-normal text-muted-foreground">/month</span></p>
        <p className="mt-2 text-sm text-muted-foreground">Up to 10 staff, online payments, SMS reminders.</p>
      </div>
    </BorderBeam>
  )
}
```

### Around an AI prompt input

```tsx
<BorderBeam className="w-full max-w-md" colorFrom="#a855f7" colorTo="#38bdf8" size={60} duration={4}>
  <input
    aria-label="Ask the assistant"
    placeholder="Move all Friday bookings to Saturday…"
    className="h-11 w-full rounded-lg border bg-background px-3 text-sm"
  />
</BorderBeam>
```

## API

### BorderBeam

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| size | `number` | `80` | Length of the beam in px. |
| duration | `number` | `6` | Seconds per lap. |
| delay | `number` | `0` | Seconds to offset the start (useful for several beams). |
| colorFrom | `string` | `"var(--chart-1)"` | Head color of the beam. Defaults to the theme's --chart-1. |
| colorTo | `string` | `"var(--chart-4)"` | Tail color of the beam. Defaults to the theme's --chart-4. |
| borderWidth | `number` | `1` | Width of the lit ring in px; match the border of the wrapped element. |
| radius | `number` | — | Corner radius of the path. Defaults to the wrapped element's own radius. |
| reverse | `boolean` | `false` | Run the beam the other way around the border. |
| beams | `1 \| 2` | `1` | Number of beams, spaced evenly around the border. |

Also accepts every <div> attribute.

## Accessibility

- The beam layer is aria-hidden with pointer-events: none, so the wrapped element works exactly as before (focus, typing, clicks).
- BorderBeam adds a wrapper <div> but no roles.

## Motion

- A gradient beam `size` px long (80) travels the border on a CSS offset-path rect() that uses the same corner radius, one lap every `duration` s (6), linear. beams={2} spaces two beams half a lap apart; reverse runs it the other way.
- The beam pauses while the element is off-screen.
- Reduced motion: the beam is hidden; the wrapped element's own border stays.
- Browsers without offset-path rect() support: the beam is hidden.

## Performance

- CSS animation on one or two small elements; an IntersectionObserver pauses it off-screen.

## Notes for AI

- Wrap exactly one element whose box matches the wrapper: the beam follows the wrapper's edges. Make the child fill it (w-full) or size the wrapper with className.
- The corner radius is read once from the first child (or the wrapper) on mount; if it changes later, pass radius explicitly.
- Match borderWidth to the child's border width so the lit ring lines up with it.
- Default colors are the theme's --chart-1 and --chart-4; size is px, duration and delay are seconds.

## FAQ

**Why is there no beam?**

The beam is hidden for reduced motion and in browsers without offset-path rect(). Without a radius prop, it also waits until the radius has been measured after mount.

**Core card animation="border-beam" or BorderBeam?**

The Core card's beam is a rotating conic gradient built into the card. BorderBeam wraps any element and runs a beam along the exact rounded-rect path, with size, speed, colors, direction and two beams.

## Related

- border-beam-button: https://goodui.dev/components/buttons/border-beam-button
- glow-border: https://goodui.dev/components/cards/glow-border
- card: https://goodui.dev/components/core/card
- spotlight-card: https://goodui.dev/components/cards/spotlight-card

Last updated: 2026-11-02

---

# Glow border

> A slowly rotating gradient arc travels around the card border with a soft glow that intensifies on hover and focus.

Glowing gradient border card for React and shadcn: rotating conic glow

Page: https://goodui.dev/components/cards/glow-border

## Install

```bash
npx shadcn@latest add @goodui/glow-border
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/glow-border.json`. The file lands in `components/goodui/glow-border.tsx`.

## When to use

- The selected or recommended plan on a pricing page (active keeps the glow on).
- Feature or AI cards on a dark landing section, where a soft colored halo adds depth.
- Forms or prompt boxes whose glow should strengthen while the user is typing inside (focus-within).

## When not to use

- A Core card that only needs a glow on hover: card with animation="glow" (or shadow="glow") is simpler and keeps variants and parts.
- A thin traveling highlight instead of a halo: use border-beam.
- Many cards in a grid: one glowing card stands out, many cancel each other. Use spotlight-card with SpotlightGroup.

## Pick by what matters

| Need | Use |
| --- | --- |
| Selected plan | active |
| Brand colors | colors={["var(--primary)", "#22d3ee"]} |
| Stronger halo at rest | restOpacity={0.45} blur={20} |
| Thicker border | borderWidth={2} |
| Padding on the content | innerClassName="p-6" |

## Usage

```tsx
import { GlowBorder } from "@/components/goodui/glow-border"

export function PlanCard({ selected, onSelect }: { selected: boolean; onSelect: () => void }) {
  return (
    <GlowBorder active={selected} innerClassName="p-6">
      <h3 className="font-semibold">Business</h3>
      <p className="mt-2 text-3xl font-bold">$99<span className="text-base font-normal text-muted-foreground">/month</span></p>
      <p className="mt-2 text-sm text-muted-foreground">Unlimited locations, priority support, API access.</p>
      <button
        type="button"
        onClick={onSelect}
        aria-pressed={selected}
        className="mt-6 h-10 w-full rounded-lg bg-primary text-sm font-medium text-primary-foreground"
      >
        {selected ? "Selected" : "Choose Business"}
      </button>
    </GlowBorder>
  )
}
```

### Prompt box that glows while typing

```tsx
<GlowBorder colors={["#a855f7", "#ec4899", "#f59e0b"]} innerClassName="p-2" duration={4}>
  <textarea
    aria-label="Describe the job"
    placeholder="3-bed move-out clean, Friday morning, pets in the house…"
    className="min-h-24 w-full resize-none bg-transparent p-2 text-sm outline-none"
  />
</GlowBorder>
```

## API

### GlowBorder

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| colors | `string[]` | `["var(--chart-1)", "var(--chart-4)", "var(--chart-5)"]` | Colors of the moving arc. Defaults to the theme's chart colors. |
| duration | `number` | `6` | Seconds per rotation. |
| borderWidth | `number` | `1` | Border width in px. |
| blur | `number` | `14` | Glow blur in px. |
| restOpacity | `number` | `0.25` | Glow opacity at rest and on hover/focus (0–1). |
| hoverOpacity | `number` | `0.75` | Glow opacity on hover, with focus inside, or while active (0 to 1). |
| active | `boolean` | `false` | Keep the intense state on, e.g. for a selected plan. |
| innerClassName | `string` | — | Classes for the inner surface. |

Also accepts every <div> attribute.

## Accessibility

- Two plain <div>s (border and inner surface); the glow is a pseudo-element that ignores the pointer and is not announced.
- The glow strengthens on :focus-within, so keyboard users get the same emphasis as hover.
- active is visual only: if it means "selected", also expose it on the control (aria-pressed, a radio, or text).

## Motion

- A conic gradient arc covering about half of the circle rotates around the border once every `duration` s (6), linear; a blurred copy (`blur` px, 14) glows behind it.
- On hover, focus inside, or when active, the glow rises from `restOpacity` (0.25) to `hoverOpacity` (0.75) and blurs 1.4x more, over 0.4 s. In dark mode the resting glow is 1.6x stronger.
- Rotation pauses while the card is off-screen.
- Reduced motion: the arc stops rotating and the glow change is instant. Browsers without @property support show the arc without rotation.

## Performance

- CSS only, animating one registered custom property; an IntersectionObserver pauses it off-screen. The blurred glow costs paint time, so keep it to a few cards per screen.

## Notes for AI

- Content padding goes in innerClassName (the inner surface); className styles the outer border box (radius, width).
- The outer box is rounded-xl; change it with className (rounded-2xl) and the inner surface follows (rounded-[inherit]).
- colors defaults to the theme's --chart-1, --chart-4, --chart-5; pass two or more CSS colors for brand colors.
- The inner surface is bg-card; override it with innerClassName if the card sits on a different surface.

## FAQ

**Why does the arc not rotate in my browser?**

Rotation animates a registered CSS custom property (@property). Browsers without it show the arc in a fixed position.

**Can I keep the glow on without hover?**

Yes, pass active. It uses the same strength as hover.

## Related

- border-beam: https://goodui.dev/components/cards/border-beam
- spotlight-card: https://goodui.dev/components/cards/spotlight-card
- card: https://goodui.dev/components/core/card
- aurora: https://goodui.dev/components/backgrounds/aurora

Last updated: 2026-11-02

---

# Progressive blur

> Blur that grows stronger toward the edge of a scroll container, built from stacked backdrop-filter layers; shown on a scrolling bookings list.

Progressive blur for React and shadcn: gradient blur at the edge of a scroll list

Page: https://goodui.dev/components/cards/progressive-blur

## Install

```bash
npx shadcn@latest add @goodui/progressive-blur
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/progressive-blur.json`. The file lands in `components/goodui/progressive-blur.tsx`.

## When to use

- The bottom (or top) edge of a scrolling list, so items soften away instead of being cut off: bookings, messages, notifications.
- Under a sticky header or floating toolbar, where content should blur as it scrolls beneath.
- Image cards with a caption at the bottom, where a blur band keeps the text readable over the photo.

## When not to use

- Hinting that a horizontal row continues: a plain mask fade is cheaper; marquee has one built in for moving rows.
- Long, fast-scrolling pages on low-end phones: stacked backdrop-filter layers cost GPU time. Use a gradient fade (fadeColor alone, or a CSS mask) there.
- Hiding content for privacy or paywalls: blur is not access control.

## Pick by what matters

| Need | Use |
| --- | --- |
| Bottom of a scroll list | side="bottom" (default) |
| Under a sticky header | side="top" |
| Also fade into the card color | fadeColor="var(--card)" |
| Smoother | layers={8} |
| Cheaper | layers={3} |
| Fixed height band | size={96} (px) or size="6rem" |

## Usage

```tsx
import { ProgressiveBlur } from "@/components/goodui/progressive-blur"

const bookings = [
  { time: "09:00", client: "Maya Chen", service: "Deep clean · 3 bed" },
  { time: "11:30", client: "Leo Park", service: "Move-out clean" },
  { time: "13:00", client: "Ana Silva", service: "Windows" },
  { time: "15:30", client: "Sam Ortiz", service: "Office · weekly" },
  { time: "17:00", client: "Iris Novak", service: "Carpet steam" },
]

export function TodayList() {
  return (
    <div className="relative h-72 overflow-hidden rounded-xl border bg-card">
      <ul className="h-full divide-y overflow-y-auto pb-16">
        {bookings.map((b) => (
          <li key={b.time} className="flex gap-4 px-4 py-3 text-sm">
            <span className="w-12 font-mono text-muted-foreground">{b.time}</span>
            <span className="font-medium">{b.client}</span>
            <span className="ms-auto text-muted-foreground">{b.service}</span>
          </li>
        ))}
      </ul>
      <ProgressiveBlur side="bottom" size={80} fadeColor="var(--card)" />
    </div>
  )
}
```

### Blur under a sticky header

```tsx
<div className="relative h-[480px] overflow-hidden">
  <header className="absolute inset-x-0 top-0 z-20 h-14 px-4">Messages</header>
  <ProgressiveBlur side="top" size={88} blur={10} />
  <div className="h-full overflow-y-auto pt-14">{/* messages */}</div>
</div>
```

## API

### ProgressiveBlur

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| side | `"top" \| "bottom" \| "left" \| "right"` | `"bottom"` | Edge the blur sits on; it grows toward that edge. |
| size | `string \| number` | `"35%"` | Size of the blurred band (any CSS length). |
| blur | `number` | `8` | Blur in px at the very edge. |
| layers | `number` | `6` | Number of stacked layers; more is smoother, fewer is cheaper. |
| fadeColor | `string` | — | Also fade to this color at the edge (e.g. "var(--card)"). Off when undefined. |

Also accepts every <div> attribute.

## Accessibility

- The blur is aria-hidden and has pointer-events: none, so content under it stays clickable and scrollable.
- Leave scroll padding (pb-16 or similar) so the last item can scroll fully out from under the blur.
- Give the scroll container tabIndex={0} and an aria-label (unless it already holds focusable items), so keyboard users can scroll it.

## Motion

- No animation: the blur is static and only changes as content scrolls beneath it, so reduced motion needs no special handling.

## Performance

- Each layer is one backdrop-filter element; the blur doubles per layer up to `blur` px (8). Fewer layers are cheaper, more are smoother (default 6).
- Keep it to a few instances per screen, especially on mobile.

## Notes for AI

- Place it inside a relative (and usually overflow-hidden) wrapper, as a sibling of the scroll container, not inside the scrolling element.
- size accepts a number (px) or any CSS length; blur is px at the very edge.
- side uses physical edges (top, bottom, left, right); it does not flip in RTL.
- fadeColor should match the surface behind the list (var(--card), var(--background)).
- It renders at z-10; raise sticky headers above it if they should stay sharp.

## FAQ

**Why use several layers instead of one blur?**

A single backdrop-filter has one strength. Stacking masked layers whose blur doubles toward the edge makes the blur grow smoothly.

**Browsers without backdrop-filter?**

The layers then do nothing; add fadeColor so the edge still fades.

## Related

- marquee: https://goodui.dev/components/backgrounds/marquee
- card: https://goodui.dev/components/core/card
- animated-list: https://goodui.dev/components/lists/animated-list
- spotlight-card: https://goodui.dev/components/cards/spotlight-card

Last updated: 2026-11-02

---

# Expandable card

> A card expands in place on a spring to reveal details, such as a staff profile with bookable slots or a plan's full feature list.

Expandable card for React and shadcn: card that expands in place to show details

Page: https://goodui.dev/components/cards/expandable-card

## Install

```bash
npx shadcn@latest add @goodui/expandable-card
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/expandable-card.json`. The file lands in `components/goodui/expandable-card.tsx`.

## When to use

- Staff or service cards that open to show bookable time slots, prices or a bio, without leaving the list.
- Pricing plans whose full feature list opens on demand.
- Settings sections and FAQ-style cards where each card is independent (several can be open).

## When not to use

- A list where only one section should be open at a time: use accordion-height.
- Details that deserve their own focus and backdrop (a full profile, a long form): use morphing-dialog or drawer-spring.
- Expanding table rows: use expandable-row-list.

## Pick by what matters

| Need | Use |
| --- | --- |
| Open by default | defaultOpen |
| Open state in your own state or URL | open={…} onOpenChange={…} |
| Custom indicator instead of the chevron | chevron={false} on ExpandableCardTrigger |

## Usage

```tsx
import { ExpandableCard, ExpandableCardContent, ExpandableCardTrigger } from "@/components/goodui/expandable-card"

const slots = ["09:00", "10:30", "13:00", "15:30"]

export function StylistCard() {
  return (
    <ExpandableCard className="w-full max-w-sm">
      <ExpandableCardTrigger>
        <span className="block font-medium">Maya Chen</span>
        <span className="block text-sm text-muted-foreground">Senior stylist · color specialist</span>
      </ExpandableCardTrigger>
      <ExpandableCardContent>
        <p className="text-sm text-muted-foreground">Next free slots on Friday:</p>
        <div className="mt-3 grid grid-cols-4 gap-2">
          {slots.map((t) => (
            <button key={t} type="button" className="h-9 rounded-md border text-sm hover:bg-muted">
              {t}
            </button>
          ))}
        </div>
      </ExpandableCardContent>
    </ExpandableCard>
  )
}
```

### Controlled, one card open at a time

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

{plans.map((p) => (
  <ExpandableCard key={p.id} open={openId === p.id} onOpenChange={(o) => setOpenId(o ? p.id : null)}>
    <ExpandableCardTrigger>{p.name} · {p.price}</ExpandableCardTrigger>
    <ExpandableCardContent>
      <ul className="list-disc ps-5 text-sm">{p.features.map((f) => <li key={f}>{f}</li>)}</ul>
    </ExpandableCardContent>
  </ExpandableCard>
))}
```

## API

### ExpandableCard

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| open | `boolean` | — | Controlled open state. |
| defaultOpen | `boolean` | `false` | Initial open state when uncontrolled. |
| onOpenChange | `(open: boolean) => void` | — | Called when the trigger or Esc opens or closes the card. |

Also accepts every <div> attribute.

### ExpandableCardTrigger

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| chevron | `boolean` | `true` | Show the rotating chevron on the right. |

Also accepts every <button> attribute.

### ExpandableCardContent

Also accepts every <div> attribute.

## Keyboard

| Keys | Action |
| --- | --- |
| Enter / Space | On the trigger: opens or closes the card (native <button>). |
| Escape | Closes the card while focus is anywhere inside it; the event does not bubble further. |
| Tab | Moves through the trigger and then the content's controls when open. |

## Accessibility

- ExpandableCardTrigger is a real <button> with aria-expanded and aria-controls pointing to the content.
- ExpandableCardContent has role="region" named by the trigger (aria-labelledby) and is removed from the DOM when closed, so hidden controls are never tabbable.
- When Escape closes the card from inside the content, focus returns to the trigger.
- The chevron is aria-hidden; the trigger's text is its accessible name, so keep it descriptive.

## Motion

- The content grows to its natural height on a spring (stiffness 260, damping 32, mass 0.8) while fading in over 0.2 s; the inner content then rises 6px and fades in over 0.25 s after 0.05 s.
- The chevron rotates 180° on a spring (stiffness 300, damping 24). The card's shadow deepens over 300 ms when open.
- Closing runs the same animation in reverse.
- Reduced motion: content and chevron change instantly.

## Notes for AI

- Always compose the three parts: ExpandableCard > ExpandableCardTrigger + ExpandableCardContent. The parts throw outside an ExpandableCard.
- Padding is built in (p-4 on the trigger, px-4 pb-4 on the content); do not add padding to the card itself.
- Trigger children go in a flexible span next to the chevron; use block spans for title and subtitle lines.
- Do not put another button inside ExpandableCardTrigger: it is already a <button>.
- For accordion behavior (one open), control open from the parent as in the example.

## FAQ

**Can several cards be open at once?**

Yes, each card has its own state. Control open from a parent to allow only one.

**Does it animate to height: auto?**

Yes. The content's height animates with motion from 0 to auto, so it works with content of any size.

## Related

- accordion-height: https://goodui.dev/components/lists/accordion-height
- expandable-row-list: https://goodui.dev/components/lists/expandable-row-list
- morphing-dialog: https://goodui.dev/components/overlays/morphing-dialog
- card: https://goodui.dev/components/core/card

Last updated: 2026-11-02

---

# Dot grid

> A dot or line grid background with a radial, top or edge fade and an optional glow that follows the pointer. Pure CSS.

Dot grid background for React and shadcn: dot and grid pattern with fade and cursor glow

Page: https://goodui.dev/components/backgrounds/dot-grid

## Install

```bash
npx shadcn@latest add @goodui/dot-grid
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/dot-grid.json`. The file lands in `components/goodui/dot-grid.tsx`.

## When to use

- Behind a hero, pricing header or empty state, to add texture without color.
- Developer-tool and SaaS pages that want a blueprint or graph-paper feel (variant="lines").
- Interactive sections where the grid should brighten around the cursor (highlight).

## When not to use

- Moving texture: use flickering-grid (canvas) or particles.
- Soft colored light instead of a pattern: use aurora.
- Behind dense text or tables: the pattern makes small text harder to read. Use a plain bg-muted surface.

## Pick by what matters

| Need | Use |
| --- | --- |
| Dots fading out from the center | variant="dots" fade="radial" (defaults) |
| Graph-paper lines | variant="lines" gap={32} |
| Pattern under a header that fades downward | fade="top" |
| Soft edges on all sides | fade="edges" |
| Glow following the cursor | highlight |

## Usage

```tsx
import { DotGrid } from "@/components/goodui/dot-grid"

export function Hero() {
  return (
    <section className="relative overflow-hidden py-28 text-center">
      <DotGrid highlight />
      <div className="relative">
        <h1 className="text-5xl font-bold tracking-tight">Run your cleaning business from one screen</h1>
        <p className="mt-4 text-muted-foreground">Bookings, crews, invoices and reminders.</p>
      </div>
    </section>
  )
}
```

### Line grid under a pricing header

```tsx
<header className="relative overflow-hidden py-20">
  <DotGrid variant="lines" gap={32} fade="top" />
  <h2 className="relative text-center text-4xl font-semibold">Simple pricing</h2>
</header>
```

### Brand-tinted dots

```tsx
<DotGrid gap={18} size={1.2} color="color-mix(in oklch, var(--primary) 35%, transparent)" fade="edges" />
```

## API

### DotGrid

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| variant | `"dots" \| "lines"` | `"dots"` | "dots" is a dot pattern; "lines" a square line grid. |
| gap | `number` | `22` | Distance between dots or lines, in px. |
| size | `number` | `1` | Dot radius or line width, in px. |
| fade | `"none" \| "bottom" \| "top" \| "radial" \| "edges"` | `"radial"` | Where the pattern fades out: "radial" \| "top" \| "bottom" \| "edges" \| "none". |
| highlight | `boolean` | `false` | Brighten the pattern around the pointer (listens on the parent element). |
| highlightColor | `string` | `"color-mix(in oklch, var(--chart-1) 90%, transparent)"` | Color of the pattern inside the pointer highlight. Defaults to the theme's --chart-1. |
| highlightRadius | `number` | `180` | Radius of the pointer highlight, in px. |

Also accepts every <div> attribute.

## Accessibility

- The grid is aria-hidden and has pointer-events: none, so it is never announced and never blocks clicks.
- The default color is the foreground at low opacity (22% for dots, 9% for lines), so it follows light and dark themes.

## Motion

- The pattern itself does not move.
- With highlight, a brighter copy of the pattern shows in a circle (`highlightRadius` px, 180) around the pointer and fades in and out over 0.4 s.
- Reduced motion: the highlight appears and disappears without the fade.

## Performance

- The pattern is CSS gradients. The highlight listens to pointer moves on the parent element and updates two CSS variables once per animation frame; React does not re-render.

## Notes for AI

- Place it as the first child of a relative (usually overflow-hidden) parent, and give the content after it position: relative so it paints above.
- highlight listens on the parent element, so the glow works across the whole section, not only over the grid.
- gap, size and highlightRadius are px; color is any CSS color.
- fade values: radial, top, bottom, edges, none.

## FAQ

**Does it work in dark mode?**

Yes. The default color mixes the theme's --foreground with transparency, so it adapts to light and dark.

**Why do I not see the cursor glow?**

highlight is off by default and the glow is drawn only while the pointer is over the parent element. Check that the parent is the section you hover.

## Related

- flickering-grid: https://goodui.dev/components/backgrounds/flickering-grid
- aurora: https://goodui.dev/components/backgrounds/aurora
- particles: https://goodui.dev/components/backgrounds/particles
- spotlight-card: https://goodui.dev/components/cards/spotlight-card

Last updated: 2026-11-02

---

# Flickering grid

> A canvas grid of small squares that flicker in opacity, follows the theme color, is sharp on retina and pauses off-screen.

Flickering grid background for React and shadcn: animated canvas squares

Page: https://goodui.dev/components/backgrounds/flickering-grid

## Install

```bash
npx shadcn@latest add @goodui/flickering-grid
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/flickering-grid.json`. The file lands in `components/goodui/flickering-grid.tsx`.

## When to use

- Hero and CTA sections of developer tools and AI products that want a living, digital texture.
- Behind a status or "system online" panel, where subtle flicker suggests activity.
- Cards and banners that should follow the theme color, including after a light/dark switch.

## When not to use

- A still pattern: use dot-grid, which is pure CSS and costs nothing at runtime.
- Soft, calm motion: use aurora.
- Behind long reading content or data tables: constant flicker pulls the eye. Use dot-grid with fade.

## Pick by what matters

| Need | Use |
| --- | --- |
| Barely-there texture | maxOpacity={0.12} flickerChance={0.15} |
| Brand colored | color="var(--primary)" |
| Chunkier pixels | squareSize={6} gap={4} |
| Cheaper on low-end devices | fps={15} |
| Freeze it | paused |

## Usage

```tsx
import { FlickeringGrid } from "@/components/goodui/flickering-grid"

export function ApiCta() {
  return (
    <section className="relative overflow-hidden rounded-2xl border bg-card px-6 py-20 text-center">
      <FlickeringGrid color="var(--primary)" maxOpacity={0.18} className="[mask-image:radial-gradient(ellipse_at_center,black,transparent_75%)]" />
      <div className="relative">
        <h2 className="text-3xl font-semibold">Sync bookings with your own app</h2>
        <p className="mt-2 text-muted-foreground">REST API and webhooks on every plan.</p>
      </div>
    </section>
  )
}
```

## API

### FlickeringGrid

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| squareSize | `number` | `4` | Side of each square, in px. |
| gap | `number` | `6` | Space between squares, in px. |
| flickerChance | `number` | `0.3` | Share of squares that change per second (0–1). |
| maxOpacity | `number` | `0.25` | Highest square opacity (0–1). |
| fps | `number` | `30` | Frames per second; flicker reads fine at 24–30 and costs half of 60. |
| paused | `boolean` | `false` | Stop flickering and keep the current frame. |

Also accepts every <div> attribute.

## Accessibility

- The canvas wrapper is aria-hidden and has pointer-events: none.
- Keep maxOpacity low behind text; the default is 0.25.

## Motion

- Each frame, a share of squares (`flickerChance` per second, 0.3) picks a new random opacity between 0 and `maxOpacity`. It draws at `fps` frames per second (30).
- It pauses while off-screen, while the tab is hidden and when paused is set.
- Reduced motion: one still frame is drawn and nothing animates.

## Performance

- Canvas 2D, sized to the container with devicePixelRatio (capped at 2) so squares stay sharp on retina screens. A ResizeObserver redraws on resize.
- The color is resolved once and re-read when the class, style or data-theme attribute of <html> changes or the system color scheme changes, not every frame.

## Notes for AI

- Place it inside a relative parent; it fills it with absolute inset-0. Give the content after it position: relative.
- color accepts any CSS color or variable (oklch, var(--primary)); it is resolved for canvas automatically.
- squareSize and gap are px; flickerChance and maxOpacity are 0 to 1.
- To fade the edges, add a mask with className, as in the usage example; there is no fade prop.

## FAQ

**Does it follow dark mode?**

Yes. With the default var(--foreground), or any theme variable, it re-reads the color when the theme class on <html> changes.

**Does it keep running when nobody sees it?**

No. It stops while off-screen, in a hidden tab and when paused, and draws at 30 fps by default. Lower fps for even less work.

## Related

- dot-grid: https://goodui.dev/components/backgrounds/dot-grid
- particles: https://goodui.dev/components/backgrounds/particles
- aurora: https://goodui.dev/components/backgrounds/aurora
- glow-border: https://goodui.dev/components/cards/glow-border

Last updated: 2026-11-02

---

# Aurora

> Soft colored light drifts slowly behind a section, with light and dark palettes and only transform animations for low CPU.

Aurora background for React and shadcn: soft animated gradient mesh

Page: https://goodui.dev/components/backgrounds/aurora

## Install

```bash
npx shadcn@latest add @goodui/aurora
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/aurora.json`. The file lands in `components/goodui/aurora.tsx`.

## When to use

- Hero sections and sign-up pages that need color and calm motion behind the headline.
- Behind glass UI (liquid-glass-button), which needs something colorful to blur.
- Pricing or CTA banners that should follow the theme (palette="brand").

## When not to use

- Behind data-dense app screens: moving color behind numbers is distracting. Use a plain background or dot-grid.
- A crisp, technical texture: use dot-grid or flickering-grid.
- Text that needs a gradient: use gradient-text.

## Pick by what matters

| Need | Use |
| --- | --- |
| Cool teal and violet | palette="aurora" (default) |
| Warm peach and pink | palette="sunset" |
| Calm blues | palette="ocean" |
| Follow the theme's chart colors | palette="brand" |
| Exact colors in both themes | colors={["#…", "#…", "#…", "#…"]} |
| Quieter | intensity={0.5} speed={0.6} |

## Usage

```tsx
import { Aurora } from "@/components/goodui/aurora"

export function SignupHero() {
  return (
    <section className="relative overflow-hidden rounded-3xl border px-6 py-24 text-center">
      <Aurora palette="brand" intensity={0.8} />
      <div className="relative">
        <h1 className="text-4xl font-semibold tracking-tight">Start taking bookings today</h1>
        <p className="mt-3 text-muted-foreground">14-day free trial. No card needed.</p>
      </div>
    </section>
  )
}
```

### Sunset palette behind a glass toolbar

```tsx
<div className="relative h-80 overflow-hidden rounded-2xl">
  <Aurora palette="sunset" speed={1.4} />
  <div className="absolute inset-x-0 top-6 flex justify-center">
    <LiquidGlassToolbar defaultValue="week" aria-label="Calendar range">
      <LiquidGlassToolbarItem value="day">Day</LiquidGlassToolbarItem>
      <LiquidGlassToolbarItem value="week">Week</LiquidGlassToolbarItem>
    </LiquidGlassToolbar>
  </div>
</div>
```

## API

### Aurora

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| palette | `"aurora" \| "sunset" \| "ocean" \| "brand"` | `"aurora"` | Theme-aware preset; "brand" mixes the theme's chart colors. |
| colors | `[string, string, string, string]` | — | Custom colors for the four blobs (overrides the palette in both themes). |
| speed | `number` | `1` | Speed multiplier; 1 is a slow drift. |
| intensity | `number` | `0.9` | Blob opacity, 0–1. |

Also accepts every <div> attribute.

## Accessibility

- The layer is aria-hidden and has pointer-events: none.
- Light-mode palettes are pale and dark-mode palettes deep, so foreground text keeps its usual color on top. Check contrast yourself with custom colors or high intensity.

## Motion

- Four radial-gradient blobs drift, scale and alternate direction on ease-in-out loops of 18, 22, 26 and 20 s, divided by `speed`.
- Only transform is animated; the blobs are soft gradients, not filter: blur.
- It pauses while off-screen and while the tab is hidden.
- Reduced motion: the blobs stay still; the colors remain.

## Performance

- CSS keyframes on four elements, transform only, so the compositor does the work and no JavaScript runs per frame.

## Notes for AI

- Place it inside a relative overflow-hidden parent; it fills it with absolute inset-0. Give the content after it position: relative.
- colors must be exactly four CSS colors and replaces the palette in both light and dark.
- speed is a multiplier (2 is twice as fast); intensity is blob opacity from 0 to 1.
- The "brand" palette mixes --chart-1, --chart-2, --chart-4 and --chart-5 with the background, so it follows the theme.

## FAQ

**Does it change between light and dark?**

Yes. Every preset has a pale light-mode set and a deeper dark-mode set. Custom colors are used in both.

**Can I make it static?**

There is no off switch for the motion besides reduced motion; for a still look use a very low speed, or a CSS gradient background.

## Related

- dot-grid: https://goodui.dev/components/backgrounds/dot-grid
- particles: https://goodui.dev/components/backgrounds/particles
- gradient-text: https://goodui.dev/components/text/gradient-text
- liquid-glass-button: https://goodui.dev/components/buttons/liquid-glass-button

Last updated: 2026-11-02

---

# Particles

> Canvas particles drift gently, link up with fine lines and move out of the pointer's way; density scales with the area.

Particles background for React and shadcn: connected dots that react to the cursor

Page: https://goodui.dev/components/backgrounds/particles

## Install

```bash
npx shadcn@latest add @goodui/particles
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/particles.json`. The file lands in `components/goodui/particles.tsx`.

## When to use

- Hero sections of AI, data or network products, where linked dots suggest connections.
- Login and sign-up screens that need gentle motion behind a centered form.
- Interactive landing sections where the background should move out of the cursor's way.

## When not to use

- A still texture: use dot-grid.
- Soft color without detail: use aurora, which is CSS-only.
- Behind dense app UI or long text: moving dots and lines compete with content. Use dot-grid with a fade.

## Pick by what matters

| Need | Use |
| --- | --- |
| Constellation with lines | defaults (connect, repel) |
| Floating dust, no lines | connect={false} density={2} |
| Background only, no pointer reaction | repel={false} |
| Brand colored | color="var(--primary)" |
| Lighter on low-end devices | density={0.8} maxParticles={120} or connect={false} |

## Usage

```tsx
import type { ReactNode } from "react"
import { Particles } from "@/components/goodui/particles"

export function LoginBackdrop({ children }: { children: ReactNode }) {
  return (
    <main className="relative grid min-h-svh place-items-center overflow-hidden bg-background">
      <Particles color="var(--primary)" density={1.2} />
      <div className="relative w-full max-w-sm rounded-2xl border bg-card p-6 shadow-sm">{children}</div>
    </main>
  )
}
```

### Dust only, no lines, no pointer reaction

```tsx
<Particles connect={false} repel={false} density={2} size={[0.5, 1.2]} speed={6} />
```

## API

### Particles

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| density | `number` | `1.4` | Particles per 10,000 px² of area. |
| maxParticles | `number` | `220` | Hard cap on the particle count. |
| size | `[number, number]` | `[0.6, 1.8]` | Radius range in px. |
| speed | `number` | `10` | Drift speed in px per second. |
| connect | `boolean` | `true` | Draw lines between nearby particles. |
| linkDistance | `number` | `110` | Max distance for a connecting line, in px. |
| repel | `boolean` | `true` | Push particles away from the pointer (listens on the parent element). |
| repelRadius | `number` | `110` | Distance in px within which the pointer pushes particles away. |

Also accepts every <div> attribute.

## Accessibility

- The canvas wrapper is aria-hidden and has pointer-events: none, so content above it stays clickable.
- Reduced motion shows one still frame.

## Motion

- Each particle drifts in its own direction at 40% to 100% of `speed` px per second (10) and wraps around the edges.
- With connect, particles closer than `linkDistance` px (110) are joined by thin lines that fade with distance.
- With repel, the pointer pushes particles within `repelRadius` px (110) away; they ease back to their own drift.
- It pauses while off-screen and while the tab is hidden. Reduced motion: one still frame is drawn.

## Performance

- Canvas 2D, devicePixelRatio capped at 2. The count is density per 10,000 px² of area, capped by maxParticles (220).
- Lines are checked between every pair of particles, so cost grows quickly with the count; lower density or turn off connect on large areas.
- The color is resolved once and re-read when the theme class on <html> or the system color scheme changes.

## Notes for AI

- Place it inside a relative parent; it fills it with absolute inset-0. Give the content after it position: relative.
- repel listens to pointer moves on the parent element, since the canvas itself ignores the pointer.
- size is a [min, max] radius tuple in px; speed is px per second.
- color accepts any CSS color or variable and is resolved for canvas automatically.

## FAQ

**Is this tsParticles or particles.js?**

No. It is a small hand-written Canvas 2D component with no dependencies.

**Does it follow dark mode?**

Yes. With the default var(--foreground), or any theme variable, it re-reads the color when the theme changes.

## Related

- dot-grid: https://goodui.dev/components/backgrounds/dot-grid
- flickering-grid: https://goodui.dev/components/backgrounds/flickering-grid
- aurora: https://goodui.dev/components/backgrounds/aurora
- spotlight-card: https://goodui.dev/components/cards/spotlight-card

Last updated: 2026-11-02

---

# Marquee

> An endless horizontal or vertical marquee with faded edges that pauses on hover, shown with customer logos, testimonials and a live bookings ticker.

Infinite marquee for React and shadcn: logo scroller and testimonial ticker

Page: https://goodui.dev/components/backgrounds/marquee

## Install

```bash
npx shadcn@latest add @goodui/marquee
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/marquee.json`. The file lands in `components/goodui/marquee.tsx`.

## When to use

- A "trusted by" row of customer logos under a hero.
- Testimonial walls: two or three rows moving in opposite directions, or vertical columns.
- A live ticker of recent bookings or sign-ups ("Maya booked a deep clean · 2 min ago").

## When not to use

- Text that should react to scroll speed: use scroll-velocity.
- Content people must read or click in order (pricing, steps): use a static grid; moving items are hard to compare.
- A carousel with prev/next controls and one item at a time: a marquee has no paging. Use a carousel component.

## Pick by what matters

| Need | Use |
| --- | --- |
| Logo row | defaults (horizontal, faded edges, pauses on hover) |
| Second row moving the other way | reverse |
| Vertical testimonial columns | vertical with a fixed height (className="h-96") |
| Slower | duration={60} |
| Content shorter than the container | repeat={4} |
| Never pause | pauseOnHover={false} |

## Usage

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

const reviews = [
  { name: "Maya C.", text: "Our no-shows dropped by half in the first month." },
  { name: "Leo P.", text: "Clients book at midnight. I wake up to a full calendar." },
  { name: "Ana S.", text: "Deposits alone paid for the subscription." },
  { name: "Sam O.", text: "Crew schedules finally live in one place." },
]

export function Testimonials() {
  return (
    <section className="space-y-4 py-16">
      <Marquee gap="1rem" duration={45}>
        {reviews.map((r) => (
          <figure key={r.name} className="w-72 rounded-xl border bg-card p-4">
            <blockquote className="text-sm">{r.text}</blockquote>
            <figcaption className="mt-3 text-xs text-muted-foreground">{r.name}</figcaption>
          </figure>
        ))}
      </Marquee>
    </section>
  )
}
```

### Logo row

```tsx
<Marquee duration={30} gap="3rem" fadeSize="20%">
  {logos.map((l) => (
    <img key={l.name} src={l.src} alt={l.name} className="h-7 w-auto opacity-60 grayscale" />
  ))}
</Marquee>
```

### Vertical column

```tsx
<Marquee vertical reverse duration={35} className="h-[420px]">
  {reviews.map((r) => <ReviewCard key={r.name} {...r} />)}
</Marquee>
```

## API

### Marquee

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| reverse | `boolean` | `false` | Scroll toward the inline start (right-to-left in LTR, left-to-right under dir="rtl") or bottom-to-top when false; the other way when true. |
| pauseOnHover | `boolean` | `true` | Pause while the pointer is over it or focus is inside it. |
| vertical | `boolean` | `false` | Scroll vertically instead of horizontally; give the marquee a height. |
| duration | `number` | `40` | Seconds for one copy to pass. |
| gap | `string` | `"1rem"` | Space between items and between copies (any CSS length). |
| repeat | `number` | `3` | How many copies to render; raise it if the content is shorter than the container. |
| fade | `boolean` | `true` | Fade the edges with a mask. |
| fadeSize | `string` | `"12%"` | Length of each faded edge (any CSS length). |
| align | `"start" \| "center" \| "end" \| "stretch"` | — | Cross-axis alignment of the items. Defaults to center (horizontal) or stretch (vertical). |

Also accepts every <div> attribute.

## Keyboard

| Keys | Action |
| --- | --- |
| Tab | Focus moves only through the first copy (the duplicates are inert); with pauseOnHover, focus inside pauses the marquee. |

## Accessibility

- Only the first copy is exposed: the extra copies are aria-hidden and inert, so screen readers read each item once and Tab skips the duplicates.
- pauseOnHover (default) also pauses while focus is inside, so links in the marquee can be read and clicked.
- Reduced motion turns it into a plain scrollable row (or column) with only one copy, so every item stays reachable.

## Motion

- Each copy slides by its own length plus the gap in a seamless linear loop; one copy passes every `duration` s (40).
- Edges fade with a mask (`fadeSize`, 12%).
- It pauses on hover and focus (pauseOnHover), while off-screen and while the tab is hidden.
- Reduced motion: no movement; duplicates are hidden and the row becomes scrollable.

## Performance

- CSS transform animation; no JavaScript runs per frame. An IntersectionObserver pauses it off-screen.

## Notes for AI

- Children are the items, rendered directly inside each track; do not wrap them in an extra flex container.
- gap and fadeSize take CSS lengths as strings ("1rem", "12%"), not numbers. duration is seconds.
- vertical needs a height on the marquee (className="h-96").
- Under dir="rtl" a horizontal marquee moves left-to-right so the copies loop seamlessly; reverse flips it as usual.
- Do not put aria-label on plain divs inside items (it is not allowed there); use role="img" with the label, or sr-only text, e.g. for a star rating.
- Give images alt text: the first copy is the accessible one.
- If you see a gap at the end of the loop, raise repeat; the content must be at least as long as the container.

## FAQ

**Why does the loop show an empty gap?**

The copies together must cover the container. Raise repeat (default 3) for short content or wide screens.

**Can people click links inside it?**

Yes. It pauses on hover and focus by default, and only the first copy is focusable.

## Related

- scroll-velocity: https://goodui.dev/components/text/scroll-velocity
- animated-list: https://goodui.dev/components/lists/animated-list
- card: https://goodui.dev/components/core/card
- progressive-blur: https://goodui.dev/components/cards/progressive-blur

Last updated: 2026-11-02

---

# Counter up

> Counts from 0 (or from) to the value with an ease-out curve when it scrolls into view, with locale formatting, once or replay-on-return, and counts from the current value when it changes.

Count up animation on scroll for React and shadcn: animated stats counter

Page: https://goodui.dev/components/numbers/counter-up

## Install

```bash
npx shadcn@latest add @goodui/counter-up
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/counter-up.json`. The file lands in `components/goodui/counter-up.tsx`.

## When to use

- Stats rows on a landing page ("12,480 bookings this year") that should count when they scroll into view.
- KPI cards on first load, so the numbers draw the eye once.
- A total that changes later (new clients added): it counts from the current value to the new one.

## When not to use

- A live value that changes often and should feel like an odometer: use number-flow.
- Numbers in tables or forms that people read and compare: plain text, motion slows reading there.
- Showing a change (+8.2%) rather than a total: use delta-badge.

## Pick by what matters

| Need | Use |
| --- | --- |
| Count once when the section first appears | defaults (once is true) |
| Replay every time it comes back into view | once={false} |
| Inside a scrolling panel instead of the page | root={panelRef} |
| Start only when fully visible | amount={1} |
| Stagger a row of stats | delay={index * 0.08} |

## Usage

```tsx
import { CounterUp } from "@/components/goodui/counter-up"

const stats = [
  { label: "Bookings this year", value: 12480 },
  { label: "Revenue", value: 384920, format: { style: "currency", currency: "USD", maximumFractionDigits: 0 } as Intl.NumberFormatOptions },
  { label: "Average rating", value: 4.9, suffix: " / 5" },
  { label: "Clients who rebook", value: 68, suffix: "%" },
]

export function Stats() {
  return (
    <div className="grid grid-cols-2 gap-4 sm:grid-cols-4">
      {stats.map((s, i) => (
        <div key={s.label} className="rounded-xl border bg-card p-4">
          <div className="text-xs text-muted-foreground">{s.label}</div>
          <CounterUp
            value={s.value}
            format={s.format}
            suffix={s.suffix}
            delay={i * 0.08}
            className="mt-1 text-2xl font-semibold tracking-tight"
          />
        </div>
      ))}
    </div>
  )
}
```

### Count from a baseline and chain an action

```tsx
<CounterUp
  value={2847}
  from={2600}
  duration={0.9}
  onComplete={() => setShowBadge(true)}
/>
```

### Replay inside a scroll container

```tsx
const panel = React.useRef<HTMLDivElement>(null)

<div ref={panel} className="h-64 overflow-y-auto">
  …
  <CounterUp value={1260} suffix=" h" once={false} root={panel} amount={0.9} />
</div>
```

## API

### CounterUp

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| value (required) | `number` | — | Target value. Changing it later counts from the current value to the new one. |
| from | `number` | `0` | Start value for the first count. |
| duration | `number` | `1.6` | Seconds the count takes. |
| delay | `number` | `0` | Seconds to wait after the element enters the viewport. |
| ease | `Easing \| Easing[]` | `[0.16, 1, 0.3, 1]` | motion easing for the count; defaults to a strong ease-out [0.16, 1, 0.3, 1]. |
| format | `Intl.NumberFormatOptions` | — | Intl.NumberFormat options, e.g. { style: "currency", currency: "USD" }. |
| locale | `string` | — | Locale passed to Intl.NumberFormat ("de-DE" gives 1.234,5). Defaults to the GooduiLocaleProvider language, else en-US. |
| prefix | `string` | `""` | Text placed before the formatted number. |
| suffix | `string` | `""` | Text placed after the formatted number, e.g. "%" or " / 5". |
| once | `boolean` | `true` | Count only the first time it scrolls into view. With false it resets when it leaves and replays on return. |
| amount | `number` | `0.5` | Share of the element that must be visible before it starts, 0 to 1. |
| root | `React.RefObject<Element \| null>` | — | Scroll container to observe instead of the viewport. |
| onComplete | `() => void` | — | Called when a count finishes (also right away when reduced motion skips it). |

Also accepts every <span> attribute.

## Accessibility

- The final formatted value sits in an sr-only span from the start; the counting text is aria-hidden, so screen readers read the real number, not intermediate frames.
- The rest of the props go to the root <span>, so you can add aria-describedby or an id.

## Motion

- Counts with motion's animate() over duration (default 1.6 s) on the ease [0.16, 1, 0.3, 1], starting when amount (default 0.5) of the element is visible, after delay.
- Intermediate frames keep the target's decimal places (4.9 counts as 0.0, 0.1…), unless format sets fraction digits or uses currency.
- With once={false} it resets to from when it leaves the view and counts again on return.
- Reduced motion: the final value is written immediately and onComplete still fires.

## Performance

- Each frame writes textContent directly on the DOM node, so counting never re-renders React. The animation is stopped on unmount or when value changes mid-count.

## Notes for AI

- Pass the target as a number to value; format with format and locale, not by building a string.
- Use suffix for units ("%", " h", " / 5") and format.style "currency" for money.
- For a counter inside an overflow container, pass that container's ref as root, or it will count as soon as the page shows it.
- To replay on a button click, change its key (it remounts and counts from from); there is no replay method.
- It renders an inline-block span: put typography classes on it directly.

## FAQ

**Why does it start at 0 before scrolling into view?**

The server and the first render show from (default 0). The count starts when the element is in view, so a stat below the fold is still at 0 until the user gets there.

**What happens when value changes after the first count?**

It counts from the number currently shown to the new value with the same duration and ease, instead of restarting from from.

## Related

- number-flow: https://goodui.dev/components/numbers/number-flow
- stat-card: https://goodui.dev/components/core/stat-card
- delta-badge: https://goodui.dev/components/numbers/delta-badge
- text-reveal: https://goodui.dev/components/text/text-reveal

Last updated: 2026-11-02

---

# Usage meter

> Labeled usage meter like "SMS credits 7,420 / 10,000" whose fill springs to the new value and shifts to amber and rose near the limit, with optional per-seat segments.

Usage meter for React and shadcn: plan limits bar that turns amber and red near the limit

Page: https://goodui.dev/components/numbers/meter

## Install

```bash
npx shadcn@latest add @goodui/meter
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/meter.json`. The file lands in `components/goodui/meter.tsx`.

## When to use

- Plan limits on a billing or settings page: "SMS credits 7,420 / 10,000", storage in GB, API calls.
- Seat usage, where segments={seats} shows one block per seat.
- Any measured amount within a known range where getting close to the limit matters.

## When not to use

- Progress of a task that finishes (upload, import, onboarding): use progress, which uses role="progressbar".
- A single percentage in a compact space such as a card corner: use circular-progress.
- A trend over time rather than a current level: use sparkline-draw.

## Pick by what matters

| Need | Use |
| --- | --- |
| Plain quota | label, value, max (defaults warn at 75%, danger at 90%) |
| Units like GB | unit=" GB" and format={{ maximumFractionDigits: 1 }} |
| One block per seat or slot | segments={max} |
| A message that changes with the level | hint={({ tone, percent }) => …} |
| Stricter or looser thresholds | warnAt={0.6} dangerAt={0.85} |

## Usage

```tsx
import { Meter, type MeterTone } from "@/components/goodui/meter"

function smsHint({ tone, percent }: { tone: MeterTone; percent: number }) {
  if (tone === "danger") return `${percent}% used. Reminders pause at 10,000. Top up to keep them sending.`
  if (tone === "warning") return `${percent}% used. At this pace you run out before Dec 1.`
  return `${percent}% used. Renews Dec 1.`
}

export function PlanUsage({ sms, storageGb, seats }: { sms: number; storageGb: number; seats: number }) {
  return (
    <div className="flex flex-col gap-5 rounded-xl border bg-card p-5">
      <Meter label="SMS credits" value={sms} max={10000} hint={smsHint} />
      <Meter
        label="Photo storage"
        value={storageGb}
        max={20}
        unit=" GB"
        format={{ minimumFractionDigits: 1, maximumFractionDigits: 1 }}
      />
      <Meter label="Team seats" value={seats} max={10} segments={10} size="lg" hint={`${10 - seats} seats left`} />
    </div>
  )
}
```

### API quota with custom thresholds

```tsx
<Meter
  label="API requests this month"
  value={84210}
  max={100000}
  warnAt={0.6}
  dangerAt={0.85}
  format={{ notation: "compact" }}
  size="sm"
/>
```

## API

### Meter

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| label (required) | `React.ReactNode` | — | Name shown above the bar and used as the meter's accessible name, e.g. "SMS credits". |
| value (required) | `number` | — | Amount used. It rolls with NumberFlow and the fill springs to it; it is clamped between 0 and max for the bar. |
| max (required) | `number` | — | Limit the value is measured against, e.g. 10000 credits. |
| format | `Intl.NumberFormatOptions` | — | Formats value and max, e.g. { maximumFractionDigits: 1 }. |
| locale | `string` | — | Locale passed to Intl.NumberFormat for value and max. Defaults to the GooduiLocaleProvider language, else en-US. |
| unit | `string` | `""` | Text after the numbers, e.g. " GB". |
| warnAt | `number` | `0.75` | Share of max (0 to 1) where the bar turns amber. |
| dangerAt | `number` | `0.9` | Share of max (0 to 1) where the bar turns rose. |
| segments | `number` | — | Split the bar into this many segments, e.g. one per seat. |
| hint | `React.ReactNode \| ((state: { tone: MeterTone; percent: number }) => React.ReactNode)` | — | Small line under the bar. Receives the current tone and percentage. |
| size | `"sm" \| "md" \| "lg"` | `"md"` | Bar height: sm 6px, md 8px, lg 12px. |
| labels | `Partial<MeterLabels>` | — | Text for built-in controls and screen readers; pass translations here. |

Also accepts every <div> attribute.

## Accessibility

- The bar is role="meter" with aria-valuemin 0, aria-valuemax max and aria-valuenow, and is named by the label through aria-labelledby.
- aria-valuetext reads "7,420 of 10,000, 74%" (with the unit after max). Translate it with labels.valueText(value, max, percent).
- The visible numbers use number-flow, which keeps one sr-only copy of the value; the " / max" text is aria-hidden because the meter already announces it.
- Tone is never the only signal: the numbers and percent are always shown, and hint can say it in words.

## Motion

- The fill is translated (not resized) on a spring (stiffness 120, damping 20, mass 0.9). With segments, each segment starts 25 ms after the previous one.
- The value digits roll through number-flow; the fill and hint colors cross-fade over 500 ms when the tone changes.
- At 0 the fill fades out (150 ms after a 300 ms delay) so no sliver stays at the track edge.
- Reduced motion: the fill and digits jump to the new value with duration 0.

## Notes for AI

- value and max are raw numbers; pass unit and format instead of building "12.6 GB" yourself.
- Tone is computed from value / max against warnAt and dangerAt (shares from 0 to 1, not percents). There is no tone prop to force a color.
- hint can be a function of { tone, percent }; use it for the message instead of reading the tone outside.
- segments should usually equal max for seats (segments={10} with max={10}); with other values each segment covers max / segments.
- Values above max are clamped to a full bar but the number still shows the real value.
- labels={{ valueText: (v, m, p) => `${v} von ${m}, ${p} %` }} translates aria-valuetext; v and m arrive formatted. Under RTL the bar fills from the right.

## FAQ

**Meter or progress?**

Meter for a level within a range that does not "finish" (quota, storage). Progress for work moving toward done. They also use different ARIA roles.

**Can I change the colors?**

Normal uses bg-primary from your theme; warning is amber and danger is rose, with dark-mode shades. Change the FILL and TEXT maps in the installed file to use other colors.

## Related

- progress: https://goodui.dev/components/numbers/progress
- circular-progress: https://goodui.dev/components/numbers/circular-progress
- number-flow: https://goodui.dev/components/numbers/number-flow
- stat-card: https://goodui.dev/components/core/stat-card

Last updated: 2026-11-02

---

# Progress

> Linear progress in four variants: spring-filled determinate, indeterminate double sweep, moving stripes and segmented steps.

Animated progress bar for React and shadcn: determinate, indeterminate, striped and steps

Page: https://goodui.dev/components/numbers/progress

## Install

```bash
npx shadcn@latest add @goodui/progress
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/progress.json`. The file lands in `components/goodui/progress.tsx`.

## When to use

- Uploads, imports and exports where you know how far along the work is.
- Background work of unknown length ("Syncing Google Calendar…"): the indeterminate variant.
- Onboarding or setup flows where a few equal steps should read as segments.

## When not to use

- Quota or plan usage that never finishes: use meter, which warns near the limit.
- A named, clickable list of steps the user moves through: use stepper.
- Short waits under a second or loading a whole panel: use spinners or skeleton-auto.

## Pick by what matters

| Need | Use |
| --- | --- |
| Known progress (upload, import) | variant="determinate" with value and max |
| Unknown duration | variant="indeterminate" (value is ignored) |
| Long job that should look busy while it moves | variant="striped" |
| A handful of equal steps | variant="steps" steps={n} max={n} value={finished} |
| Thin bar in a header or card | size="sm" |

## Usage

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

export function ImportStatus({ imported, total }: { imported: number; total: number }) {
  return (
    <div className="flex flex-col gap-5 rounded-xl border bg-card p-5">
      <Progress label="Uploading client-photos.zip" value={64} showValue />
      <Progress
        variant="striped"
        label={`Importing clients · ${imported.toLocaleString()} of ${total.toLocaleString()}`}
        value={imported}
        max={total}
        showValue
        size="lg"
        indicatorClassName="bg-emerald-500"
      />
    </div>
  )
}
```

### Unknown duration, then done

```tsx
<Progress
  variant={syncing ? "indeterminate" : "determinate"}
  value={100}
  label={syncing ? "Syncing Google Calendar…" : "Calendar synced"}
  size="sm"
  indicatorClassName="bg-sky-500"
/>
```

### Onboarding steps

```tsx
const steps = ["Business details", "Services and prices", "Opening hours", "Invite your team", "Go live"]

<Progress variant="steps" steps={steps.length} max={steps.length} value={finished} label="Studio setup" showValue />
```

## API

### Progress

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| value | `number` | `0` | Current value, 0 to max. Ignored by the indeterminate variant. |
| max | `number` | `100` | Value that counts as complete. For steps, set it to the step count so value is the number of finished steps. |
| variant | `"determinate" \| "indeterminate" \| "striped" \| "steps"` | `"determinate"` | determinate: spring fill. indeterminate: looping sweep for unknown duration. striped: fill with moving stripes. steps: one segment per step. |
| steps | `number` | `4` | Number of segments for the steps variant. |
| size | `"sm" \| "md" \| "lg"` | `"md"` | Bar height: sm 4px, md 8px, lg 12px. |
| label | `React.ReactNode` | — | Optional label above the bar. |
| showValue | `boolean` | `false` | Show the percentage (or "step x of n") next to the label. |
| indicatorClassName | `string` | — | Classes for the filled part, e.g. "bg-emerald-500". |
| labels | `Partial<ProgressLabels>` | — | Text for built-in controls and screen readers; pass translations here. |

Also accepts every <div> attribute.

## Accessibility

- Renders role="progressbar" with aria-valuemin, aria-valuemax, aria-valuenow and aria-valuetext ("64%" or "Step 3 of 5").
- With a label, the bar is named by it through aria-labelledby; without one it gets aria-label="Progress". Both built-in strings go through labels (progress, stepOf).
- The indeterminate variant drops the value attributes and sets aria-busy="true".

## Motion

- Determinate, striped and each step segment translate the fill on a spring (stiffness 110, damping 22, mass 0.8); at 0 the fill fades out after 300 ms.
- Indeterminate: two bars sweep across on a 1.6 s CSS loop, the second starting 0.8 s later.
- Striped: the stripes slide on a 0.8 s linear loop while the fill springs to the value.
- Reduced motion: fills jump with duration 0, stripes stop moving, and the indeterminate sweep becomes a static full-width bar at 45% opacity.

## Performance

- Only transform and opacity animate. The indeterminate and striped loops are CSS keyframes, so no JavaScript runs per frame.

## Notes for AI

- value is on the 0 to max scale (default max 100), not 0 to 1.
- For steps, pass steps and max as the same number and value as the count of finished steps; value 2 of 5 reads "Step 3 of 5".
- Color the fill with indicatorClassName ("bg-emerald-500"), not className, which goes on the wrapper.
- showValue is ignored by the indeterminate variant; value is ignored too.
- labels={{ progress: "Fortschritt", stepOf: (s, n) => `Schritt ${s} von ${n}` }} translates the fallback name and the steps text. Under RTL the track is mirrored, so bars fill from the right.

## FAQ

**How do I switch from indeterminate to a real value?**

Change variant from "indeterminate" to "determinate" and pass value; the fill springs in from the start of the track.

**Do the step segments fill one after another?**

Each segment springs on its own share of the value at the same time. When value goes up by one step, only that segment fills, so stepping through looks sequential.

## Related

- meter: https://goodui.dev/components/numbers/meter
- circular-progress: https://goodui.dev/components/numbers/circular-progress
- stepper: https://goodui.dev/components/navigation/stepper
- multi-step-loader: https://goodui.dev/components/feedback/multi-step-loader

Last updated: 2026-11-02

---

# Circular progress

> SVG ring or 270° gauge whose arc springs to the value via stroke-dashoffset, with a rolling percentage or custom label in the center.

Circular progress ring and gauge for React and shadcn with an animated percentage

Page: https://goodui.dev/components/numbers/circular-progress

## Install

```bash
npx shadcn@latest add @goodui/circular-progress
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/circular-progress.json`. The file lands in `components/goodui/circular-progress.tsx`.

## When to use

- A single percentage that deserves a visual: goal reached, utilization, profile completion.
- Revenue or target gauges on a dashboard (variant="gauge") with your own center label.
- Small per-row indicators, such as each staff member's schedule load at 44px.

## When not to use

- Quota with a used / limit readout and warnings: use meter.
- Long task progress in a form or dialog: use progress, a linear bar reads more precisely.
- Comparing several values against each other: use a bar chart; rings are hard to compare.

## Pick by what matters

| Need | Use |
| --- | --- |
| Plain percentage | variant="ring" (default) with value |
| Speedometer-style goal | variant="gauge" with max={goal} |
| Money or other units in the center | label={<NumberFlow … />} plus your own aria-valuetext |
| Tiny inline ring | size={44} strokeWidth={4} label={null} |
| Color by status | indicatorClassName="text-emerald-500" (the arc uses currentColor) |

## Usage

```tsx
import { CircularProgress } from "@/components/goodui/circular-progress"
import { NumberFlow } from "@/components/goodui/number-flow"

export function RevenueGoal({ revenue, goal }: { revenue: number; goal: number }) {
  return (
    <CircularProgress
      variant="gauge"
      value={revenue}
      max={goal}
      size={152}
      strokeWidth={12}
      indicatorClassName="text-[var(--chart-2)]"
      aria-label="November revenue goal"
      aria-valuetext={`${revenue} of ${goal} dollars`}
      label={
        <NumberFlow
          value={revenue}
          format={{ style: "currency", currency: "USD", notation: "compact", maximumFractionDigits: 1 }}
          className="font-semibold tracking-tight"
        />
      }
      sublabel="of $25k goal"
    />
  )
}
```

### Utilization ring with rolling percentage

```tsx
<CircularProgress value={72} size={136} sublabel="booked" aria-label="Chair utilization this week" />
```

### Per-row load indicator

```tsx
<CircularProgress
  value={member.load}
  size={44}
  strokeWidth={4}
  indicatorClassName={member.load >= 90 ? "text-rose-500" : member.load >= 75 ? "text-amber-500" : "text-emerald-500"}
  aria-label={`${member.name} schedule load`}
/>
```

## API

### CircularProgress

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| value (required) | `number` | — | Current value on the 0 to max scale; the arc springs to it. |
| aria-label | `string` | `"Progress"` | Defines a string value that labels the current element. Accessible name for the progress bar. |
| max | `number` | `100` | Value that fills the whole ring or gauge. |
| size | `number` | `120` | Diameter in px. |
| strokeWidth | `number` | — | Ring thickness in px. Defaults to 9% of the size. |
| variant | `"ring" \| "gauge"` | `"ring"` | "ring" is a full circle, "gauge" is a 270° arc open at the bottom. |
| label | `React.ReactNode` | — | Center content. Defaults to the rolling percentage. Pass null to hide it. |
| sublabel | `React.ReactNode` | — | Small line under the center label. |
| indicatorClassName | `string` | — | Classes for the arc; it is drawn with currentColor, e.g. "text-emerald-500". |
| trackClassName | `string` | — | Classes for the track; drawn with currentColor. |

Also accepts every <div> attribute.

## Accessibility

- The root is role="progressbar" with aria-valuemin 0, aria-valuemax max, aria-valuenow and aria-valuetext as a rounded percent.
- aria-label defaults to "Progress"; pass a specific one ("Chair utilization this week").
- The SVG and the center label are aria-hidden. When the label shows something other than a percent, pass your own aria-valuetext; it overrides the default.

## Motion

- On mount the arc springs from empty to the value via stroke-dashoffset (stiffness 70, damping 18, mass 1), and again on every change.
- The default center label is number-flow, so the percentage digits roll with the arc.
- At 0 the arc fades out in 150 ms, because a round cap would still paint a dot.
- Reduced motion: the arc and digits jump to the value with duration 0.

## Notes for AI

- value is on the 0 to max scale (default max 100); for a goal pass max={goal} instead of computing a percent.
- Color the arc with a text-* class in indicatorClassName and the track with trackClassName; the stroke uses currentColor, so bg-* does nothing.
- label={null} hides the center; leaving label undefined shows the rolling percentage.
- size is a number in px, not a Tailwind class; strokeWidth defaults to 9% of size (at least 3).
- With a custom label, also pass aria-valuetext so screen readers hear the same thing.

## FAQ

**Where does the gauge's gap go?**

The gauge is a 270° arc that starts at 7:30 and ends at 4:30, so the open part is at the bottom. The center label is nudged down slightly to sit in the middle of the arc.

**How big is the center text?**

It scales with size: 20% of the diameter for the label (at least 11px) and 9% for the sublabel (at least 10px).

## Related

- progress: https://goodui.dev/components/numbers/progress
- meter: https://goodui.dev/components/numbers/meter
- number-flow: https://goodui.dev/components/numbers/number-flow
- stat-card: https://goodui.dev/components/core/stat-card

Last updated: 2026-11-02

---

# Sparkline draw

> Smooth monotone sparkline that draws itself in, fades in a gradient area, shows point values on hover or arrow keys, and redraws when the data changes.

Animated sparkline for React and shadcn: self-drawing line chart with hover tooltip

Page: https://goodui.dev/components/numbers/sparkline-draw

## Install

```bash
npx shadcn@latest add @goodui/sparkline-draw
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/sparkline-draw.json`. The file lands in `components/goodui/sparkline-draw.tsx`.

## When to use

- A trend under a KPI: revenue, bookings or no-show rate over the last 14 days.
- Dashboards where each card needs a small chart without pulling in a chart library.
- Compact trends where hovering or arrowing to a point should show its date and value.

## When not to use

- A full chart with axes, gridlines or several series: use a charting library (shadcn chart / Recharts).
- A single current value against a limit: use meter or circular-progress.
- Just the change between two periods: use delta-badge.

## Pick by what matters

| Need | Use |
| --- | --- |
| Default dashboard trend | curve="smooth" area tooltip endDot (all defaults) |
| Exact values matter more than looks | curve="linear" |
| Decorative, non-interactive | tooltip={false} (also removes it from the tab order) |
| Negative metric in red | color="#f43f5e" or any CSS color |
| Plain line only | area={false} endDot={false} |

## Usage

```tsx
import { SparklineDraw } from "@/components/goodui/sparkline-draw"

const days = ["Oct 26", "Oct 27", "Oct 28", "Oct 29", "Oct 30", "Oct 31", "Nov 1"]
const revenue = [2240, 2610, 2380, 2950, 3080, 3460, 3720]
const usd = new Intl.NumberFormat("en-US", { style: "currency", currency: "USD", maximumFractionDigits: 0 })

export function RevenueCard() {
  return (
    <div className="rounded-xl border bg-card p-4">
      <div className="text-xs text-muted-foreground">Revenue</div>
      <div className="mt-1 text-2xl font-semibold tabular-nums">{usd.format(3720)}</div>
      <SparklineDraw
        data={revenue}
        pointLabels={days}
        formatValue={(v) => usd.format(v)}
        height={56}
        className="mt-3"
        aria-label="Revenue, last 7 days"
      />
    </div>
  )
}
```

### No-show rate in rose, straight segments

```tsx
<SparklineDraw
  data={[6.2, 5.8, 6.4, 5.1, 4.9, 4.4, 3.9, 3.1]}
  color="#f43f5e"
  curve="linear"
  formatValue={(v) => `${v}%`}
/>
```

### Translated screen reader text

```tsx
<SparklineDraw
  data={bookings}
  labels={{
    point: (n) => `Punkt ${n}`,
    summary: (first, last, low, high) => `Verlauf von ${first} bis ${last}, Minimum ${low}, Maximum ${high}`,
    noData: "Keine Daten",
  }}
/>
```

## API

### SparklineDraw

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| data (required) | `number[]` | — | Values in order, oldest first. The line scales between their min and max; changed values redraw the line. |
| color | `string` | `"var(--chart-1)"` | Any CSS color. Defaults to the theme's first chart color. |
| pointLabels | `string[]` | — | One label per point, shown in the tooltip (e.g. dates). |
| height | `number` | `48` | Height in px. The width follows the container. |
| strokeWidth | `number` | `2` | Line thickness in px; the end dot and padding grow with it. |
| area | `boolean` | `true` | Gradient fill under the line. |
| curve | `"smooth" \| "linear"` | `"smooth"` | smooth: monotone curve that never overshoots the data. linear: straight segments. |
| tooltip | `boolean` | `true` | Show the hovered point's value. Arrow keys move it when focused. |
| endDot | `boolean` | `true` | Pulsing dot on the latest point. |
| duration | `number` | `0.9` | Seconds the line takes to draw. |
| formatValue | `(value: number, index: number) => string` | — | Formats values for the tooltip and screen readers. index is -1 for the low and high in the summary. |
| labels | `Partial<SparklineDrawLabels>` | — | Text for built-in controls and screen readers; pass translations here. |

Also accepts every <div> attribute.

## Keyboard

| Keys | Action |
| --- | --- |
| Tab | Focuses the sparkline (only when tooltip is on) and shows the latest point. |
| ArrowLeft / ArrowRight | Moves the highlighted point one step. |
| Home / End | Jumps to the first or last point. |
| Escape | Hides the highlight and tooltip. |

## Accessibility

- The root is role="group" with aria-roledescription="sparkline" and an aria-label summary built from the data ("Trend from $2,240 to $3,720, low …, high …"); your aria-label replaces it.
- The highlighted point is announced through a polite live region as "<point label>: <value>", falling back to "Point n".
- All built-in text goes through labels (point, summary, noData) for translation; per-point names come from pointLabels.
- The SVG is aria-hidden; the focus ring is the focus-visible ring token.

## Motion

- The line draws in with pathLength over duration (default 0.9 s) on ease [0.65, 0, 0.35, 1]. The gradient area fades in over 0.6 s starting at 45% of that, and the end dot appears at 90%.
- The end dot sends out a ring every 2 s (scale to 2.6 while fading).
- The hover crosshair and point follow the pointer on a stiff spring (stiffness 600, damping 40).
- New values remount the paths so the line draws again; a container resize only reshapes it.
- Reduced motion: the line, area and dot appear at once, the ring is hidden and the crosshair snaps.

## Performance

- One ResizeObserver per sparkline keeps the SVG at the container width; there are no timers, and the ring is a CSS animation.

## Notes for AI

- Per-point names (dates) go in pointLabels, not labels; labels is only for translating built-in screen reader text.
- pointLabels must be the same length and order as data.
- Pass an aria-label that names the metric and period ("Revenue, last 14 days"); the auto summary does not know what the numbers are.
- Width follows the parent; set height in px through the height prop, not a Tailwind h-* class.
- color takes any CSS color or variable (default var(--chart-1)); do not pass a Tailwind class.

## FAQ

**Does the smooth curve invent peaks?**

No. It uses monotone cubic interpolation (Fritsch–Carlson), so the curve never goes above a peak or below a dip in your data.

**What does it render on the server?**

An SVG at a 240px width that is replaced by the measured container width after mount.

**Does it redraw on every re-render?**

No. It redraws only when the values change, because the paths are keyed by the joined data.

## Related

- delta-badge: https://goodui.dev/components/numbers/delta-badge
- stat-card: https://goodui.dev/components/core/stat-card
- counter-up: https://goodui.dev/components/numbers/counter-up
- number-flow: https://goodui.dev/components/numbers/number-flow

Last updated: 2026-11-02

---

# Delta badge

> "+12.4%" change badge whose digits roll, arrow rotates to the new direction and background pulses green or red, with an inverted mode for metrics where down is good.

Percent change badge for React and shadcn: animated +12.4% delta with up and down arrows

Page: https://goodui.dev/components/numbers/delta-badge

## Install

```bash
npx shadcn@latest add @goodui/delta-badge
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/delta-badge.json`. The file lands in `components/goodui/delta-badge.tsx`.

## When to use

- Next to a KPI to show the change from the previous period: "+12.4%" revenue vs last week.
- Metrics where down is good (cancellations, churn, costs) with goodWhen="down", so a drop shows green.
- Comparison tables that refresh, where the change should be noticed when it updates.

## When not to use

- Showing the value itself rather than its change: use number-flow.
- Signalling that a table cell just changed, up or down: use cell-flash.
- Status labels like "Paid" or "Overdue": use badge.

## Pick by what matters

| Need | Use |
| --- | --- |
| Inline in a KPI card or table | variant="soft" (default) |
| Strong emphasis on a hero stat | variant="solid" |
| Quiet, on busy backgrounds | variant="outline" |
| Lower is better (churn, no-shows, cost) | goodWhen="down" |
| Absolute change, not percent | suffix="" or suffix=" pts" |

## Usage

```tsx
import { DeltaBadge } from "@/components/goodui/delta-badge"

const rows = [
  { label: "Revenue", value: "$48,295", delta: 12.4 },
  { label: "Bookings", value: "1,284", delta: 4.1 },
  { label: "Cancellations", value: "38", delta: -3.2, goodWhen: "down" as const },
]

export function WeekOverWeek() {
  return (
    <div className="divide-y rounded-xl border bg-card">
      {rows.map((r) => (
        <div key={r.label} className="flex items-center justify-between px-4 py-3">
          <div>
            <div className="text-sm font-medium">{r.label}</div>
            <div className="text-xs text-muted-foreground tabular-nums">{r.value}</div>
          </div>
          <DeltaBadge value={r.delta} goodWhen={r.goodWhen} />
        </div>
      ))}
    </div>
  )
}
```

### Small solid and outline badges

```tsx
<DeltaBadge value={12.4} variant="solid" size="sm" />
<DeltaBadge value={-3.2} goodWhen="down" variant="outline" size="sm" />
<DeltaBadge value={0} size="sm" />
```

### Whole-number change without the arrow

```tsx
<DeltaBadge value={7} decimals={0} suffix=" pts" hideIcon />
```

## API

### DeltaBadge

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| value (required) | `number` | — | The change, e.g. 12.4 for +12.4%. |
| decimals | `number` | `1` | Decimals shown. |
| suffix | `string` | `"%"` | Text after the number; use "" or " pts" for non-percent changes. |
| goodWhen | `"up" \| "down"` | `"up"` | Which direction is good. Use "down" for churn, no-shows or costs. |
| variant | `"soft" \| "solid" \| "outline"` | `"soft"` | soft: tinted background, solid: filled green or red with white text, outline: colored border and text. |
| size | `"sm" \| "md"` | `"md"` | sm is 20px tall with 11px text, md is 24px with 12px text. |
| hideIcon | `boolean` | `false` | Hide the arrow icon. |
| labels | `Partial<DeltaBadgeLabels>` | — | Text for built-in controls and screen readers; pass translations here. |

Also accepts every <span> attribute.

## Accessibility

- An sr-only span reads the change in words, e.g. "Up 12.4%", "Down 3.2%" or "No change, 0.0%"; the arrow, sign and rolling digits are aria-hidden. Translate the words with labels (up, down, flat).
- Green and red are not the only signal: the sign, the arrow direction and the words all say the direction.
- There is no aria-live region; changes are not announced on their own.

## Motion

- Digits roll through number-flow. The arrow rotates on a spring (stiffness 260, damping 18): up at 0°, down at 180°, sideways at 90° for no change.
- When the rounded value changes, a tinted ring grows to 1.35x and fades over 0.6 s, and the number scales 1 → 1.12 → 1 in 0.35 s. Nothing pulses on first render.
- Background and text colors cross-fade over 300 ms when the tone flips.
- Reduced motion: no ring and no scale pulse; the arrow and digits snap to the new state.

## Notes for AI

- value is the change itself in percent units (12.4 means +12.4%), not a ratio (0.124) and not the new total.
- Do not add a + or − yourself; the badge adds the sign and uses the true minus character.
- Color comes from direction and goodWhen; there is no tone prop. Use goodWhen="down" for cancellations, churn, refunds and costs.
- The value is rounded to decimals (default 1) before deciding the direction, so 0.04 shows as flat "0.0%".
- labels={{ up: (a) => `Plus ${a}`, down: (a) => `Minus ${a}`, flat: (a) => `Unverändert, ${a}` }} translates the screen-reader text; a is the formatted amount with suffix.

## FAQ

**Why is my drop shown in green?**

goodWhen="down" is set, so a decrease counts as good. Remove it for metrics where up is good.

**Does it work in a table that re-renders often?**

Yes. It only pulses when the rounded value actually changes, so re-renders with the same value do nothing.

## Related

- number-flow: https://goodui.dev/components/numbers/number-flow
- stat-card: https://goodui.dev/components/core/stat-card
- cell-flash: https://goodui.dev/components/numbers/cell-flash
- badge: https://goodui.dev/components/core/badge

Last updated: 2026-11-02

---

# Cell flash

> Wraps a table value and briefly flashes it green when it rises, red when it falls, with a fading ▲/▼, like a trading terminal.

Flash table cell on value change in React: green up, red down, like a trading terminal

Page: https://goodui.dev/components/numbers/cell-flash

## Install

```bash
npx shadcn@latest add @goodui/cell-flash
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/cell-flash.json`. The file lands in `components/goodui/cell-flash.tsx`.

## When to use

- Live tables (revenue per staff member, order counts, prices) where you want the eye drawn to what just changed.
- Totals that update from a websocket or polling, to show the direction of the change at a glance.
- Status columns (strings) that should blink when they change, without implying up or down.

## When not to use

- A big hero number that should animate its digits: use number-flow.
- Showing the size of a change persistently (+12.4%): use delta-badge.
- Values that change many times a second: the flashes overlap into noise; throttle the updates first or show a sparkline-draw.

## Pick by what matters

| Need | Use |
| --- | --- |
| Numbers that rise and fall | value={n} (direction is computed) |
| Formatted display | value={n} with children={usd.format(n)} |
| Text status that changed | value={status} (flashes neutral sky blue) |
| Direction known from the server | direction="up" \| "down" \| "neutral" |
| Calmer table | indicator={false} or a shorter duration |

## Usage

```tsx
import { CellFlash } from "@/components/goodui/cell-flash"
import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "@/components/ui/table"

const usd = new Intl.NumberFormat("en-US", { style: "currency", currency: "USD", maximumFractionDigits: 0 })

type Staff = { name: string; bookings: number; revenue: number }

export function StaffToday({ rows }: { rows: Staff[] }) {
  return (
    <Table>
      <TableHeader>
        <TableRow>
          <TableHead>Staff</TableHead>
          <TableHead className="text-right">Bookings</TableHead>
          <TableHead className="text-right">Revenue</TableHead>
        </TableRow>
      </TableHeader>
      <TableBody>
        {rows.map((r) => (
          <TableRow key={r.name}>
            <TableCell>{r.name}</TableCell>
            <TableCell className="text-right">
              <CellFlash value={r.bookings} />
            </TableCell>
            <TableCell className="pr-6 text-right font-medium">
              <CellFlash value={r.revenue}>{usd.format(r.revenue)}</CellFlash>
            </TableCell>
          </TableRow>
        ))}
      </TableBody>
    </Table>
  )
}
```

### Status text and a forced direction

```tsx
<CellFlash value={order.status}>{order.status}</CellFlash>
<CellFlash value={price.updatedAt} direction={price.change > 0 ? "up" : "down"} duration={600}>
  {price.formatted}
</CellFlash>
```

## API

### CellFlash

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| value (required) | `number \| string` | — | The value to watch. Numbers flash green when they rise and red when they fall; other values flash neutral. |
| children | `React.ReactNode` | — | Rendered content. Defaults to the value. |
| direction | `"up" \| "down" \| "neutral"` | — | Force a direction instead of comparing with the previous value. |
| duration | `number` | `900` | Flash length in ms. |
| indicator | `boolean` | `true` | Show a small ▲/▼ that fades out with the flash. |

Also accepts every <span> attribute.

## Accessibility

- The flash background and the ▲/▼ arrow are aria-hidden; screen readers only read the content, and changes are not announced.
- Direction is shown by color and by the arrow; turn indicator off only where the color alone is acceptable.

## Motion

- On each change a tinted background fades from full to zero over duration (default 900 ms) on a cubic-bezier(.3,0,.4,1).
- The ▲ or ▼ slides 3px into place (from below for up, from above for down), holds, then fades out within the same duration.
- Nothing flashes on mount or when a re-render passes the same value.
- Reduced motion: the arrow only fades, without sliding; the background fade stays because it is opacity only.

## Performance

- Pure CSS animations keyed by a change counter; no timers or JavaScript per frame. The flash and arrow are absolutely positioned, so they never shift the table layout.

## Notes for AI

- Pass the raw number to value and the formatted text as children; with only a formatted string as value it cannot tell up from down.
- Strings and mixed types flash neutral (sky); only number-to-number changes get green or red.
- The wrapper has -mx-1.5 px-1.5 so the highlight extends past the text without moving it; do not remove that padding in tight cells.
- Keep the row key stable (an id, not the index) so a re-sort does not make every cell flash.

## FAQ

**Can I change the colors?**

They are emerald, rose and sky with dark-mode shades, in the BG and FG maps at the top of the installed file.

**Where does the arrow go?**

Just after the value, absolutely positioned outside the text box, so it never pushes the layout. Leave a little end padding in the cell for it.

## Related

- delta-badge: https://goodui.dev/components/numbers/delta-badge
- number-flow: https://goodui.dev/components/numbers/number-flow
- table-row-presence: https://goodui.dev/components/lists/table-row-presence
- sparkline-draw: https://goodui.dev/components/numbers/sparkline-draw

Last updated: 2026-11-02

---

# Toast stack

> Self-contained toaster with toast() API: cards stack and expand on hover, swipe away with a drag, morph from loading to success or error for promises, and pause their timers on hover.

Stacked toast notifications for React and shadcn: toast() API, swipe to dismiss, promise toasts

Page: https://goodui.dev/components/feedback/toast-stack

## Install

```bash
npx shadcn@latest add @goodui/toast-stack
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/toast-stack.json`. The file lands in `components/goodui/toast-stack.tsx`.

## When to use

- Short confirmations after an action: "Booking confirmed", "Invoice sent".
- Async work that should show loading, then success or error, in the same toast (toast.promise).
- Reversible actions with an Undo button ("Appointment cancelled" + Undo).
- Background events the user did not trigger directly, such as going offline.

## When not to use

- Errors the user must fix before going on (form validation): show them inline with input-shake or an alert.
- Persistent page-level state such as a trial ending: use an alert banner.
- A running list of activity the user can scroll back through: use animated-list.

## Pick by what matters

| Need | Use |
| --- | --- |
| Plain message | toast("Saved") |
| Outcome with an icon | toast.success / .error / .warning / .info |
| Async request | toast.promise(fn, { loading, success, error }) |
| Update an existing toast | toast(title, { id }) with the same id |
| Must stay until closed | duration: Infinity (loading toasts never close on their own) |
| Always show the full list | <Toaster expand /> |

## Usage

```tsx
// app/layout.tsx: mount the toaster once
import { Toaster } from "@/components/goodui/toast-stack"

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        {children}
        <Toaster position="bottom-right" />
      </body>
    </html>
  )
}

// anywhere in a client component
import { toast } from "@/components/goodui/toast-stack"

function cancelAppointment(client: string, time: string) {
  toast("Appointment cancelled", {
    description: `${client} on ${time}`,
    duration: 6000,
    action: { label: "Undo", onClick: () => toast.success("Appointment restored") },
  })
}
```

### Loading, then success or error

```tsx
toast.promise(() => sendInvoice(1042), {
  loading: "Sending invoice #1042…",
  description: "Emailing a PDF to the client",
  success: (id) => `Invoice #${id} sent`,
  error: () => "Invoice #1042 could not be sent. Try again.",
  action: { label: "View", onClick: () => router.push("/invoices/1042") },
})
```

### Manual loading toast updated by id

```tsx
const id = toast.loading("Syncing Google Calendar…")
await sync()
toast.success("Calendar synced", { id })
```

### Translated toaster

```tsx
<Toaster position="top-center" labels={{ notifications: "Benachrichtigungen (Alt+T)", close: "Schließen" }} />
```

## API

### Toaster

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| position | `"top-left" \| "top-center" \| "top-right" \| "bottom-left" \| "bottom-center" \| "bottom-right"` | `"bottom-right"` | Screen corner or edge the stack is pinned to; top positions stack downward, bottom ones upward. |
| visibleToasts | `number` | `3` | Toasts visible in the collapsed stack. |
| duration | `number` | `4000` | Default auto-dismiss time in ms. |
| gap | `number` | `12` | Space between toasts when expanded, in px. |
| expand | `boolean` | `false` | Keep the stack expanded instead of expanding on hover. |
| showTimer | `boolean` | `true` | Thin bar showing the time left. |
| labels | `Partial<ToasterLabels>` | — | Text for built-in controls and screen readers; pass translations here. |
| sound | `boolean \| SoundName` | — | Plays a sound for each new toast by type (success, error, warning, otherwise "notify") when the visitor has sounds on (lib/goodui-sounds); a sound name is used for every type. Off by default. |

Also accepts every <section> attribute.

## Keyboard

| Keys | Action |
| --- | --- |
| Alt+T | Moves focus to the newest toast (listened for on window while the Toaster is mounted). |
| Tab | Moves between toasts and their action and close buttons; focus inside the stack expands it and pauses timers. |
| Escape | Closes the focused toast, unless dismissible is false. |

## Accessibility

- The toaster is a <section> with aria-live="polite" and aria-relevant="additions text", labelled "Notifications (Alt+T)", so new toasts and text changes (a promise resolving) are announced.
- Each toast is a focusable list item; the close button has an aria-label from labels.close.
- Timers pause while the pointer is over the stack, while focus is inside it and while the tab is hidden, so nothing disappears while someone is reading it.
- Built-in strings (notifications, close) go through the labels prop for translation.

## Motion

- New toasts enter 24px from the edge at 0.96 scale; position, scale and height move on a spring (stiffness 380, damping 34, mass 0.9). Exit is a 180 ms fade to 0.94 scale.
- Collapsed, older toasts scale down 5% per level and peek out 10px each; hover or focus fans them out to their real heights.
- Dragging sideways fades the card; past 80px or a 600 px/s flick it flies off in 200 ms and closes. Otherwise it snaps back.
- When the type changes (loading to success), the icon pops in on a spring from 0.4 scale and -45° rotation. A thin bar at the bottom shrinks over the duration.
- Reduced motion: toasts fade without moving, the timer bar is hidden, the icon swap is a fade and the loading spinner slows to 2.4 s per turn.

## Performance

- The store is a tiny module-level list read with useSyncExternalStore; only the Toaster re-renders when toasts change. Timers are one setTimeout per visible toast, with the remaining time kept across pauses.

## Notes for AI

- Mount <Toaster /> exactly once (root layout); call toast() from anywhere on the client. The store is global, so a second Toaster would show the same toasts twice.
- toast() returns the id; toast.promise() returns the promise, not an id. Pass options.id to toast.promise if you need to dismiss it.
- Pass the promise as a function (() => save()) or a promise; success and error can be functions of the result or error.
- Only one action per toast; clicking it runs onClick and closes the toast. There is no cancel button option.
- Do not use toasts for validation errors or anything that needs a decision; they auto-close after 4 s by default.

## FAQ

**Is it compatible with Sonner?**

The call shapes are similar (toast(), toast.success, toast.promise, toast.dismiss) but it is a separate, self-contained store. Replace the import and keep one Toaster.

**What happens if the user closes a loading toast before the promise settles?**

It stays closed: the success or error update only applies if the toast is still in the list.

**How do I keep a toast open?**

Pass duration: Infinity, or use type loading. Updating a toast by id restarts its timer.

## Related

- alert: https://goodui.dev/components/core/alert
- animated-list: https://goodui.dev/components/lists/animated-list
- notification-badge: https://goodui.dev/components/feedback/notification-badge
- success-check: https://goodui.dev/components/feedback/success-check

Last updated: 2026-11-02

---

# Notification badge

> Count badge for icon buttons that springs in, bumps when the count rises, rolls its digits, caps at 99+ and offers a pulse ring or dot variant.

Animated notification badge for React and shadcn: unread count on an icon button

Page: https://goodui.dev/components/feedback/notification-badge

## Install

```bash
npx shadcn@latest add @goodui/notification-badge
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/notification-badge.json`. The file lands in `components/goodui/notification-badge.tsx`.

## When to use

- An unread or pending count on an icon button: booking requests on a bell, emails on an inbox icon.
- A simple "something new" dot on a messages icon (dot).
- Counts that rise while the user watches, where the bump draws the eye without a toast.

## When not to use

- A standalone status or count label in text: use badge.
- Telling the user what happened, not just how many: use toast-stack.
- Counts on mobile tab bar items: bottom-nav and dock have their own badges.

## Pick by what matters

| Need | Use |
| --- | --- |
| Exact count | count={n} (caps at 99+ by default) |
| Just "there is something" | dot |
| Urgent, keep pinging | pulse |
| Calm, on-brand count | tone="primary" |
| Show 0 instead of hiding | showZero |

## Usage

```tsx
import { Bell } from "lucide-react"
import { NotificationBadge } from "@/components/goodui/notification-badge"

export function BookingRequestsButton({ count, onOpen }: { count: number; onOpen: () => void }) {
  return (
    <NotificationBadge count={count} pulse label="booking requests">
      <button
        type="button"
        aria-label="Booking requests"
        onClick={onOpen}
        className="grid size-10 place-items-center rounded-full hover:bg-muted"
      >
        <Bell className="size-5" />
      </button>
    </NotificationBadge>
  )
}
```

### Dot for new messages

```tsx
<NotificationBadge count={hasNew ? 1 : 0} dot tone="emerald" label="new messages">
  <button type="button" aria-label="Messages"><MessageSquare /></button>
</NotificationBadge>
```

### Large inbox with a custom cap

```tsx
<NotificationBadge count={1240} max={999} tone="primary" label="emails">
  <button type="button" aria-label="Inbox"><Inbox /></button>
</NotificationBadge>
```

## API

### NotificationBadge

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| children (required) | `React.ReactNode` | — | The element the badge sits on, usually an icon button. |
| count (required) | `number` | — | Number shown in the badge. At 0 the badge hides (unless showZero); a higher count bumps it. |
| max | `number` | `99` | Above this the badge reads "99+". |
| dot | `boolean` | `false` | A plain dot instead of a number. |
| pulse | `boolean` | `false` | A ring that keeps pinging outward while the count is above zero. |
| showZero | `boolean` | `false` | Keep the badge visible at 0. |
| tone | `"red" \| "primary" \| "emerald" \| "amber"` | `"red"` | Badge color: red (rose) for alerts, primary for your theme color, emerald or amber. |
| placement | `"top-right" \| "top-left" \| "bottom-right"` | `"top-right"` | Badge corner. Left and right are mirrored under RTL (right means the inline end). |
| label | `string` | `"unread"` | Words for screen readers after the count. |
| labels | `Partial<NotificationBadgeLabels>` | — | Text for built-in controls and screen readers; pass translations here. |
| badgeClassName | `string` | — | Classes for the badge itself; className goes on the wrapper around children. |

Also accepts every <span> attribute.

## Accessibility

- The visible badge is aria-hidden; an sr-only polite live region reads "3 booking requests", or "More than 99 …" above max, and is empty at 0.
- label is the word after the count (default "unread"); pass a translated phrase. Translate the capped wording with labels.moreThan.
- Give the wrapped button its own aria-label; the badge does not label it.

## Motion

- The badge springs in from scale 0 when the count leaves 0 and springs out when it returns (stiffness 520, damping 22).
- When the count goes up from a non-zero value, it swells to 1.3x in 100 ms and settles back on a bouncy spring (stiffness 520, damping 13). Digits roll through number-flow.
- pulse adds a ring that pings outward every 1.6 s while the count is above 0.
- Reduced motion: the badge fades in and out, there is no bump or ping, and the digits snap.

## Notes for AI

- Wrap the icon button as children; the badge positions itself on its corner. Do not position it yourself.
- count is a number; the component formats "99+" from max. Do not pass "99+" strings.
- label is the screen reader noun ("booking requests"), not the button's name.
- dot still announces the count to screen readers, so pass a real count (1) rather than true.
- placement is mirrored under RTL: top-right sits on the inline end (the left corner in RTL).
- labels={{ moreThan: (max) => `Mehr als ${max}` }} translates the screen-reader text for capped counts.

## FAQ

**Why doesn't it bump when the count goes from 0 to 1?**

Going from 0 the badge springs in instead; the bump only plays when an already visible count rises.

**Does it animate on first render?**

No. AnimatePresence has initial={false}, so a badge that is there on mount just appears.

## Related

- badge: https://goodui.dev/components/core/badge
- toast-stack: https://goodui.dev/components/feedback/toast-stack
- bottom-nav: https://goodui.dev/components/navigation/bottom-nav
- dock: https://goodui.dev/components/navigation/dock

Last updated: 2026-11-02

---

# Skeleton auto

> SkeletonSwap traces its children's text lines, controls and avatars (<img> or data-skeleton elements) into shimmer blocks with one shared sweep, then cross-fades to the real content; includes line, circle and block primitives.

Auto skeleton loader for React and shadcn: shimmer placeholders traced from your real layout

Page: https://goodui.dev/components/feedback/skeleton-auto

## Install

```bash
npx shadcn@latest add @goodui/skeleton-auto
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/skeleton-auto.json`. The file lands in `components/goodui/skeleton-auto.tsx`.

## When to use

- Cards, lists and profiles that load data, where you want a skeleton shaped exactly like the result without drawing one by hand.
- Layouts that change often: the skeleton follows the markup, so it never drifts out of date.
- Hand-made skeletons too: Skeleton, SkeletonLine and SkeletonCircle share the same shimmer.

## When not to use

- Short waits in a button or input: use spinners.
- Operations with known progress: use progress.
- Multi-stage tasks the user should follow step by step: use multi-step-loader.

## Pick by what matters

| Need | Use |
| --- | --- |
| Skeleton shaped like the real content | <SkeletonSwap loading> with placeholder data as children |
| Full control over the shapes | fallback={…} built from SkeletonLine / SkeletonCircle / Skeleton |
| Avatar or chart as one solid block | data-skeleton on that element |
| Leave a part out (badges, decorations) | data-skeleton-ignore on that element |
| Standalone placeholder block | <Skeleton className="h-24 w-full rounded-xl" /> |

## Usage

```tsx
import { Avatar, AvatarFallback } from "@/components/ui/avatar"
import { SkeletonSwap } from "@/components/goodui/skeleton-auto"

const placeholder = { name: "Maya Chen", email: "maya.chen@hey.com", notes: "Prefers Priya for color. Patch test before every appointment." }

export function ClientCard({ client, loading }: { client?: typeof placeholder; loading: boolean }) {
  const c = client ?? placeholder
  return (
    <SkeletonSwap loading={loading} className="rounded-xl border bg-card p-5">
      <div className="flex items-center gap-3">
        <Avatar className="size-12" data-skeleton>
          <AvatarFallback>{c.name.split(" ").map((n) => n[0]).join("")}</AvatarFallback>
        </Avatar>
        <div className="min-w-0">
          <div className="font-semibold">{c.name}</div>
          <div className="text-sm text-muted-foreground">{c.email}</div>
        </div>
      </div>
      <p className="mt-4 text-sm text-muted-foreground">{c.notes}</p>
    </SkeletonSwap>
  )
}
```

### Hand-made fallback

```tsx
<SkeletonSwap
  loading={loading}
  className="rounded-xl border bg-card p-4"
  fallback={
    <div className="flex items-center gap-3">
      <SkeletonCircle size={36} />
      <div className="flex flex-1 flex-col gap-2">
        <SkeletonLine width="45%" />
        <SkeletonLine width="70%" className="h-2.5" />
      </div>
    </div>
  }
>
  <LocationSummary location={location} />
</SkeletonSwap>
```

### Primitives on their own

```tsx
<div className="flex flex-col gap-2">
  <Skeleton className="h-32 w-full rounded-xl" />
  <SkeletonLine width="60%" />
  <SkeletonLine width={120} />
</div>
```

## API

### Skeleton

Also accepts every <div> attribute.

### SkeletonLine

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| width | `number \| string` | `"100%"` | CSS width, e.g. "60%" or 120. |

Also accepts every <div> attribute.

### SkeletonCircle

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| size | `number` | `40` | Diameter in px. |

Also accepts every <div> attribute.

### SkeletonSwap

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| loading (required) | `boolean` | — | While true, the children are hidden and the skeleton shows; set it to false to cross-fade to the content. |
| children (required) | `React.ReactNode` | — | The real content. While loading, render it with placeholder data: it stays invisible and its layout is traced into skeleton blocks. Mark parts with data-skeleton (one solid block) or data-skeleton-ignore (skip). |
| fallback | `React.ReactNode` | — | Hand-made skeleton instead of the traced one. |
| loadingLabel | `string` | `"Loading…"` | Announced to screen readers while loading. |

Also accepts every <div> attribute.

## Accessibility

- While loading, the root has aria-busy and an sr-only role="status" says loadingLabel (default "Loading…"; pass a translation).
- The placeholder content is inert and aria-hidden while loading, so nobody can focus or read the fake data; the skeleton layer is aria-hidden too.

## Motion

- One highlight band sweeps across every block every 1.7 s; each block offsets it by its own x position, so it reads as a single sweep over the whole layout.
- Switching loading cross-fades the skeleton and the content over 350 ms (ease [0.4, 0, 0.2, 1]).
- Reduced motion: the sweep is hidden, blocks stay static and the cross-fade shortens to 150 ms.

## Performance

- Tracing walks the content's DOM once per change: one block per wrapped text line (via Range rects) and one per image, svg, video, canvas, input, textarea, select, button, picture, iframe, progress, meter or data-skeleton element.
- It re-traces on resize (ResizeObserver) and DOM mutations (MutationObserver), batched to one animation frame, and only while loading is true.

## Notes for AI

- Render the real component with realistic placeholder data while loading; empty strings produce no text lines and therefore no skeleton.
- Mark avatars, charts and thumbnails with data-skeleton so they become one block; a text-only avatar fallback would otherwise trace as a short text line.
- className goes on the root (it keeps your padding and border); the skeleton is positioned against its padding box.
- With fallback, nothing is traced; the fallback sits in the same grid cell as the content.
- Elements with display: none or visibility: hidden are skipped automatically.

## FAQ

**Does it work on the server?**

Blocks are measured in the browser in a layout effect, so the server HTML has the invisible content (keeping the right size) and the blocks appear before the first paint after hydration.

**Why are my text bars shorter than the line?**

Each bar is 62% of the line height (at least 6px) and centered on it, like real glyphs, and is clipped to its parent's box.

## Related

- spinners: https://goodui.dev/components/feedback/spinners
- progress: https://goodui.dev/components/numbers/progress
- multi-step-loader: https://goodui.dev/components/feedback/multi-step-loader
- card: https://goodui.dev/components/core/card

Last updated: 2026-11-02

---

# Spinners

> Six CSS-only loaders (ring, dots, bars, pulse, orbit, typing) sized in px or presets and painted with currentColor.

CSS loading spinners for React and shadcn: ring, dots, bars, pulse, orbit and typing

Page: https://goodui.dev/components/feedback/spinners

## Install

```bash
npx shadcn@latest add @goodui/spinners
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/spinners.json`. The file lands in `components/goodui/spinners.tsx`.

## When to use

- Inside a button or input while a request runs ("Saving…").
- Short waits where the layout of the result is unknown or small.
- A chat or assistant reply in progress: the typing variant.

## When not to use

- Loading a card, list or page whose shape you know: use skeleton-auto, which avoids layout shift.
- Work with known progress (uploads, imports): use progress.
- Multi-stage operations the user should follow: use multi-step-loader.

## Pick by what matters

| Need | Use |
| --- | --- |
| Default in buttons and fields | variant="ring" size="sm" |
| Softer, friendly loading | variant="dots" or "pulse" |
| Audio or data processing feel | variant="bars" |
| Someone is typing / AI is replying | variant="typing" |
| Larger standalone loader | variant="orbit" size="xl" |

## Usage

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

export function SaveButton({ saving }: { saving: boolean }) {
  return (
    <Button disabled={saving} aria-busy={saving}>
      {saving && <Spinner variant="ring" size="sm" label={null} />}
      {saving ? "Saving…" : "Save changes"}
    </Button>
  )
}
```

### Assistant typing indicator

```tsx
<div className="flex items-center gap-2 text-muted-foreground">
  <SpinnerTyping size={20} label="Assistant is typing" />
</div>
```

### Colored with text classes

```tsx
<Spinner variant="orbit" size="xl" className="text-primary" label="Loading calendar" />
<SpinnerBars size="lg" className="text-emerald-500" />
```

## API

### Spinner

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| variant | `"ring" \| "dots" \| "bars" \| "pulse" \| "orbit" \| "typing"` | `"ring"` | Loader style: ring, dots, bars, pulse, orbit or typing. |
| size | `"xs" \| "sm" \| "md" \| "lg" \| "xl" \| number` | `"md"` | Preset or a size in px. |
| label | `string \| null` | `"Loading"` | Read by screen readers. Pass null when a parent already announces the busy state. |

Also accepts every <span> attribute.

### SpinnerRing

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| label | `string \| null` | — | Read by screen readers. Pass null when a parent already announces the busy state. |
| size | `"xs" \| "sm" \| "md" \| "lg" \| "xl" \| number` | — | Preset or a size in px. |

Also accepts every <span> attribute.

### SpinnerDots

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| label | `string \| null` | — | Read by screen readers. Pass null when a parent already announces the busy state. |
| size | `"xs" \| "sm" \| "md" \| "lg" \| "xl" \| number` | — | Preset or a size in px. |

Also accepts every <span> attribute.

### SpinnerBars

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| label | `string \| null` | — | Read by screen readers. Pass null when a parent already announces the busy state. |
| size | `"xs" \| "sm" \| "md" \| "lg" \| "xl" \| number` | — | Preset or a size in px. |

Also accepts every <span> attribute.

### SpinnerPulse

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| label | `string \| null` | — | Read by screen readers. Pass null when a parent already announces the busy state. |
| size | `"xs" \| "sm" \| "md" \| "lg" \| "xl" \| number` | — | Preset or a size in px. |

Also accepts every <span> attribute.

### SpinnerOrbit

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| label | `string \| null` | — | Read by screen readers. Pass null when a parent already announces the busy state. |
| size | `"xs" \| "sm" \| "md" \| "lg" \| "xl" \| number` | — | Preset or a size in px. |

Also accepts every <span> attribute.

### SpinnerTyping

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| label | `string \| null` | — | Read by screen readers. Pass null when a parent already announces the busy state. |
| size | `"xs" \| "sm" \| "md" \| "lg" \| "xl" \| number` | — | Preset or a size in px. |

Also accepts every <span> attribute.

## Accessibility

- By default the root is role="status" with an sr-only "Loading" text, so screen readers announce it.
- label replaces that text (translate it here); label={null} drops the role and hides the spinner from assistive tech, for when a parent already says it is busy.

## Motion

- ring turns every 0.75 s; dots scale and fade over 1.1 s, staggered 0.15 s; bars stretch over 0.9 s, staggered 0.12 s; pulse sends two rings 0.7 s apart on a 1.4 s loop; orbit's outer dot circles in 1.2 s and the inner one reverses in 0.8 s; typing dots hop over 1 s.
- Reduced motion: nothing rotates, scales or hops. Every variant becomes a slow 1.6 s opacity fade, so it still reads as busy.

## Performance

- Pure CSS keyframes on transform and opacity; no JavaScript, no timers. The stylesheet is shared by every spinner on the page.

## Notes for AI

- Size with the size prop (xs 12, sm 16, md 24, lg 32, xl 48, or a number in px); the parts are sized in em from it, so Tailwind size-* classes alone will not scale the inside.
- Color with a text-* class or by inheriting currentColor; there is no color prop.
- Inside a button that already says "Saving…", pass label={null} so it is not announced twice.
- SpinnerRing, SpinnerDots, SpinnerBars, SpinnerPulse, SpinnerOrbit and SpinnerTyping are shortcuts for Spinner with that variant.

## FAQ

**Why is the spinner still moving with reduced motion on?**

It switches to a gentle opacity fade instead of stopping, so people can still tell something is loading.

**Does it line up with text?**

Yes. Each spinner is an inline-flex box of 1em (its font-size is the size in px) with vertical-align: middle, so it sits on the text line next to a label.

## Related

- skeleton-auto: https://goodui.dev/components/feedback/skeleton-auto
- progress: https://goodui.dev/components/numbers/progress
- multi-step-loader: https://goodui.dev/components/feedback/multi-step-loader
- button: https://goodui.dev/components/core/button

Last updated: 2026-11-02

---

# Multi-step loader

> Card or overlay that ticks through steps like "Reserving slot…" with spinners, drawn checkmarks and a filling rail, ending on an animated success state.

Multi-step loader for React and shadcn: step-by-step progress with checkmarks and success state

Page: https://goodui.dev/components/feedback/multi-step-loader

## Install

```bash
npx shadcn@latest add @goodui/multi-step-loader
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/multi-step-loader.json`. The file lands in `components/goodui/multi-step-loader.tsx`.

## When to use

- A request that runs several stages the user should see: check availability, reserve, charge deposit, send confirmation.
- Imports and migrations ("Reading clients.csv", "Merging 18 duplicates") shown as a blocking overlay until done.
- Turning a long wait into visible progress, ending on a clear success state with a next action.

## When not to use

- A single short request: use spinners in the button, or a toast-stack promise toast.
- Steps the user fills in and navigates between: use stepper.
- Progress measured in percent or bytes: use progress.

## Pick by what matters

| Need | Use |
| --- | --- |
| Inline in a page or panel | variant="card" (default) |
| Block the page until done | variant="overlay" with open and onOpenChange |
| Driven by real work | step={index} (controlled); steps.length means done |
| Demo or optimistic timing | running with stepDuration={ms} or an array per step |
| Next action at the end | successAction={<Button …/>} |

## Usage

```tsx
import { MultiStepLoader } from "@/components/goodui/multi-step-loader"
import { Button } from "@/components/ui/button"

const steps = [
  { label: "Checking availability…", description: "Thu, Nov 6 · 2:30 PM with Priya" },
  { label: "Reserving your slot…", description: "Held for you for 10 minutes" },
  { label: "Charging the $40 deposit…", description: "Visa ending 4242" },
  { label: "Sending confirmation…", description: "Email and SMS to Maya Chen" },
]

export function BookingProgress({ step, onViewBooking }: { step: number; onViewBooking: () => void }) {
  return (
    <MultiStepLoader
      steps={steps}
      step={step}
      title="Booking Balayage + gloss"
      successTitle="You're booked"
      successDescription="Thu, Nov 6 · 2:30 PM · Glow Studio"
      successAction={
        <Button size="sm" onClick={onViewBooking}>
          View booking
        </Button>
      }
    />
  )
}
```

### Blocking import overlay

```tsx
<MultiStepLoader
  variant="overlay"
  open={open}
  onOpenChange={setOpen}
  steps={["Reading clients.csv", "Matching 1,240 clients", "Merging 18 duplicates", "Importing visit history"]}
  stepDuration={850}
  title="Importing from Square"
  successTitle="1,222 clients imported"
  successAction={<Button size="sm" onClick={() => setOpen(false)}>Done</Button>}
/>
```

### Timed steps with a pause

```tsx
<MultiStepLoader steps={steps} running={!paused} stepDuration={[1100, 900, 1300, 1000]} onComplete={() => track("booking_done")} />
```

## API

### MultiStepLoader

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| steps (required) | `MultiStep[]` | — | Steps in order: a string, or { label, description } where the description shows under the active step. |
| step | `number` | — | Controlled active step (0-based). steps.length means everything is done. |
| running | `boolean` | — | Auto-advance while true (uncontrolled only). |
| stepDuration | `number \| number[]` | — | Ms per step when auto-advancing. A number per step is allowed. |
| onStepChange | `(step: number) => void` | — | Called with the new step index when auto-advancing (uncontrolled mode only). |
| onComplete | `() => void` | — | Called once every step is done. |
| title | `React.ReactNode` | — | Heading while the steps run. |
| successTitle | `React.ReactNode` | — | Heading on the final success state, next to an animated check. |
| successDescription | `React.ReactNode` | — | Line under successTitle. |
| successAction | `React.ReactNode` | — | Rendered under the success message, e.g. a "View booking" button. |
| variant | `"card" \| "overlay"` | `"card"` | "overlay" covers the page with a blurred backdrop and a centered card. |
| open | `boolean` | `true` | Overlay only. |
| onOpenChange | `(open: boolean) => void` | — | Overlay only. Esc and the backdrop close it once all steps are done. |
| labels | `Partial<MultiStepLoaderLabels>` | — | Text for built-in controls and screen readers; pass translations here. |

Also accepts every <div> attribute.

## Keyboard

| Keys | Action |
| --- | --- |
| Escape | Overlay only: closes it through onOpenChange(false), but only after every step is done. |
| Tab / Shift+Tab | Overlay only: cycles through focusable elements inside the dialog (e.g. successAction); focus cannot leave it. |

## Accessibility

- An sr-only role="status" polite region announces the current step label (when it is a string) and then successTitle, or "Done" when successTitle is not a string.
- The overlay is role="dialog" with aria-modal, labelled by the title; it takes focus on open, keeps Tab and Shift+Tab inside, and gives focus back to the previously focused element on close.
- The "Step x of n" line and the fallback announcements go through labels (stepOf, done) for translation.

## Motion

- The active step shows a spinner turning every 0.8 s. A finished step pops into a green circle (spring 520 / 24 from 0.4 scale) and its check draws in 280 ms.
- The line to the next step fills top-down in 350 ms after a 100 ms delay; the header rail fills on a spring (stiffness 300, damping 30).
- The active step's description opens to its height in 220 ms. At the end the header slides to a success-check and the successAction row opens after 200 ms.
- Overlay: the backdrop fades in 200 ms and the card springs from 0.95 scale (stiffness 420, damping 32).
- Reduced motion: icons, lines, descriptions and the overlay change with fades or instantly; the spinner keeps turning, slower (2.4 s).

## Notes for AI

- Pick one mode: controlled (step, you advance it as work finishes) or timed (running + stepDuration). onStepChange only fires in timed mode.
- step is 0-based and step === steps.length means done; that is when onComplete fires and the success state shows.
- The overlay cannot be dismissed while running; Esc and backdrop clicks only close it after the last step. Give successAction a close button.
- To restart a timed run, change its key; there is no reset method.
- Keep step labels short and present-tense with an ellipsis ("Reserving your slot…"); put details in description.
- labels={{ stepOf: (s, n) => `Schritt ${s} von ${n}`, done: "Fertig" }} translates the built-in text; title and successTitle are props.

## FAQ

**How do I tie it to a real API call?**

Keep the step index in state, pass it as step, and increment it as each stage of your request resolves. Set it to steps.length when the last one finishes.

**Can a step fail?**

There is no error state. On failure, close the overlay or replace the card and show the error with an alert or a toast.

## Related

- success-check: https://goodui.dev/components/feedback/success-check
- progress: https://goodui.dev/components/numbers/progress
- stepper: https://goodui.dev/components/navigation/stepper
- spinners: https://goodui.dev/components/feedback/spinners

Last updated: 2026-11-02

---

# Confetti

> Hand-written canvas 2D confetti with flipping paper physics, fired over the page from an element or inside a contained canvas via ref, and a no-op under reduced motion.

Confetti for React and shadcn without canvas-confetti: burst from a button or inside a card

Page: https://goodui.dev/components/feedback/confetti

## Install

```bash
npx shadcn@latest add @goodui/confetti
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/confetti.json`. The file lands in `components/goodui/confetti.tsx`.

## When to use

- A real milestone: first booking received, plan upgraded, onboarding finished, goal reached.
- Payment success screens, fired once from the confirm button or from inside the receipt card.
- Playful moments in consumer apps where a burst from the clicked element feels rewarding.

## When not to use

- Routine saves and confirmations: use a toast-stack success toast; confetti on every action quickly gets annoying.
- The success state itself: pair confetti with success-check so the result is clear even with reduced motion.
- Continuous decorative motion: use particles.

## Pick by what matters

| Need | Use |
| --- | --- |
| Burst over the whole page from a button | fireConfetti({ element: e.currentTarget }) |
| Burst at a pointer position | fireConfetti({ origin: { x: e.clientX, y: e.clientY } }) |
| Confetti clipped to one card | <Confetti ref={ref} /> in a relative overflow-hidden parent, then ref.current.fire() |
| Side cannons | two fire calls with angle 60 and 120 from the bottom corners |
| Soft, brand-colored | colors={[…]} shapes={["circle"]} startVelocity 22, gravity 0.6 |

## Usage

```tsx
import { PartyPopper } from "lucide-react"
import { fireConfetti } from "@/components/goodui/confetti"
import { Button } from "@/components/ui/button"

export function PublishBookingPage({ onPublish }: { onPublish: () => Promise<void> }) {
  return (
    <Button
      onClick={async (e) => {
        const button = e.currentTarget
        await onPublish()
        fireConfetti({ element: button, particleCount: 120, spread: 80 })
      }}
    >
      <PartyPopper /> Publish booking page
    </Button>
  )
}
```

### Contained in a payment card, two cannons

```tsx
const confetti = React.useRef<ConfettiHandle>(null)
const card = React.useRef<HTMLDivElement>(null)

function onPaid() {
  const rect = card.current?.getBoundingClientRect()
  if (!rect) return
  confetti.current?.fire({ origin: { x: rect.left + 8, y: rect.bottom - 8 }, angle: 60, spread: 50, startVelocity: 30, particleCount: 60 })
  confetti.current?.fire({ origin: { x: rect.right - 8, y: rect.bottom - 8 }, angle: 120, spread: 50, startVelocity: 30, particleCount: 60 })
}

<div ref={card} className="relative overflow-hidden rounded-2xl border bg-card p-5">
  <Confetti ref={confetti} />
  …
</div>
```

### Gentle brand-colored burst

```tsx
fireConfetti({
  element: e.currentTarget,
  particleCount: 45,
  spread: 120,
  startVelocity: 22,
  gravity: 0.6,
  shapes: ["circle"],
  colors: ["#a78bfa", "#c4b5fd", "#f0abfc", "#fbcfe8"],
  scalar: 0.8,
})
```

## API

### Confetti

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| ref | `React.Ref<ConfettiHandle>` | — | Receives { fire(options), clear() } to burst inside this canvas. |
| sound | `boolean \| SoundName` | — | Default `sound` for fire(): "celebrate" (true) or a sound name, when the visitor has sounds on. Off by default. |

Also accepts every <canvas> attribute.

## Accessibility

- Both canvases are aria-hidden and pointer-events: none, so they never block clicks or reach screen readers.
- Confetti is decoration only: announce the success itself in text (success-check, a toast or a heading).

## Motion

- Each piece launches in a cone around angle (default 90°, straight up; spread 70°) at 50–120% of startVelocity (38), slows by decay (0.91) per frame, falls with gravity, wobbles sideways and flips by scaling one axis with cos(), like paper.
- Pieces live about 220 frames (±20%) and fade out over the last 35% of their life; anything that falls 40px below the canvas is dropped.
- Physics is frame-rate independent (normalised to 60 fps, capped at 3 frames per step).
- Reduced motion: fireConfetti() and ref.fire() do nothing at all.

## Performance

- Canvas 2D drawn by hand, no dependencies. The loop runs only while pieces are alive, pauses while the tab is hidden, and the contained canvas also pauses when scrolled off-screen (IntersectionObserver).
- The page canvas is created on the first fireConfetti() call and removed when the last piece is gone. Device pixel ratio is capped at 2.

## Notes for AI

- Call fireConfetti() in an event handler or effect, never during render.
- origin is in viewport px (clientX / clientY) for both fireConfetti and ref.fire; the contained canvas converts it.
- angle is in degrees where 90 is up, 0 is right and 180 is left; spread is the cone width in degrees.
- The <Confetti /> canvas is absolute inset-0: put it in a parent with position relative (and overflow-hidden to clip).
- Do not install or import canvas-confetti; the option names (particleCount, spread, startVelocity, decay, ticks, scalar) are already similar.

## FAQ

**Is the API the same as canvas-confetti?**

Close but not identical: the main options share names, while origin is in viewport px instead of 0–1 fractions, and element bursts from an element's center.

**Why does nothing happen on my machine?**

Your OS probably has reduced motion turned on; confetti is a no-op then. Show the success another way too.

## Related

- success-check: https://goodui.dev/components/feedback/success-check
- toast-stack: https://goodui.dev/components/feedback/toast-stack
- particles: https://goodui.dev/components/backgrounds/particles
- multi-step-loader: https://goodui.dev/components/feedback/multi-step-loader

Last updated: 2026-11-02

---

# Success check

> Check or X in a circle that draws its stroke, fills, then pops with a ray-and-ring burst, for payment and booking result screens.

Animated success checkmark for React and shadcn: drawn check or error X with a burst

Page: https://goodui.dev/components/feedback/success-check

## Install

```bash
npx shadcn@latest add @goodui/success-check
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/success-check.json`. The file lands in `components/goodui/success-check.tsx`.

## When to use

- Result screens: payment received, booking confirmed, form submitted.
- The error counterpart on the same screen (variant="error"), so success and failure share one layout.
- Small inline ticks in a checklist that fills in, using burst={false}, a small size and a staggered delay.

## When not to use

- A checkbox the user toggles: use checkbox-draw.
- Confirming routine actions without changing the screen: use a toast-stack success toast.
- Showing progress through several stages before the result: use multi-step-loader, which ends on this check.

## Pick by what matters

| Need | Use |
| --- | --- |
| Big result icon | size={72} (default) with burst |
| Failure | variant="error" |
| Inline list ticks | size={20} burst={false} delay={i * 0.15} |
| Brand color | className="text-primary" (everything uses currentColor) |
| Replay on retry | playKey={attempt} |

## Usage

```tsx
import { SuccessCheck } from "@/components/goodui/success-check"
import { Button } from "@/components/ui/button"

export function PaymentResult({ ok, attempt, onRetry }: { ok: boolean; attempt: number; onRetry: () => void }) {
  return (
    <div className="flex flex-col items-center gap-3 text-center">
      <SuccessCheck variant={ok ? "success" : "error"} playKey={attempt} size={76} />
      <h2 className="text-lg font-semibold">{ok ? "Deposit paid" : "Card declined"}</h2>
      <p className="text-sm text-muted-foreground">
        {ok ? "$40 deposit for Thu, Nov 6 · 2:30 PM" : "Visa ending 4242 was declined. Try another card."}
      </p>
      {!ok && <Button onClick={onRetry}>Try again</Button>}
    </div>
  )
}
```

### Checklist ticks that land one after another

```tsx
{["Deposit received", "Slot reserved", "Confirmation sent"].map((item, i) => (
  <div key={item} className="flex items-center gap-2 text-sm">
    <SuccessCheck size={20} burst={false} delay={i * 0.15} aria-hidden />
    {item}
  </div>
))}
```

## API

### SuccessCheck

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| variant | `"success" \| "error"` | `"success"` | "success" draws a check, "error" draws an X. |
| size | `number` | `72` | Diameter in px. The burst reaches about 15% beyond it. |
| burst | `boolean` | `true` | Rays and a ring that shoot outward once the mark lands. |
| delay | `number` | `0` | Seconds before the drawing starts. |
| playKey | `React.Key` | — | Change it to play the animation again. |
| label | `string` | — | Accessible name. Defaults to "Success" or "Error". |

Also accepts every <span> attribute.

## Accessibility

- The root is role="img" with aria-label "Success" or "Error"; pass label for a specific or translated name ("Payment received").
- It is not a live region. If the result appears without navigation, put the message in a role="status" element so it is announced.
- Color is not the only signal: success draws a check and error draws an X.

## Motion

- The circle outline draws in 0.5 s, the tinted fill springs in from 0.6 scale at 0.28 s (stiffness 260, damping 18), then the check draws in 0.32 s from 0.42 s (the X draws its two strokes at 0.42 s and 0.58 s).
- At about 0.6 s the icon pops to 1.08x and back in 0.35 s, while a ring expands to 1.4x and fades over 0.7 s and eight rays shoot out over 0.5 s. All times shift by delay.
- Strokes stay transparent until their own draw starts, so round caps never show a dot early.
- Reduced motion: the finished icon is shown at once, with no pop and no burst. The setting is read after mount, so server and client render the same markup.

## Notes for AI

- Replay by changing playKey (or variant); do not remount the parent just to replay it.
- size is a number in px; color comes from className text-* (defaults emerald for success, rose for error).
- Use burst={false} at small sizes; the burst reaches about 15% beyond the circle and can clip in tight rows.
- Pass label when the meaning is more specific than "Success" or "Error", or when your UI is not in English.

## FAQ

**How do I show it after a request finishes?**

Render it when the result arrives (or change playKey); it plays on mount. Add confetti for big moments.

**Can I change the timing?**

delay shifts the whole sequence. The durations are fixed in the component; edit the t() calls in the installed file to change them.

## Related

- multi-step-loader: https://goodui.dev/components/feedback/multi-step-loader
- confetti: https://goodui.dev/components/feedback/confetti
- checkbox-draw: https://goodui.dev/components/inputs/checkbox-draw
- toast-stack: https://goodui.dev/components/feedback/toast-stack

Last updated: 2026-11-02

---

# Button

> One button with ten variants, six tones, seven shadows, ten animations, three shapes and five sizes that all combine, plus loading and icon slots.

Animated button for React and shadcn: 10 variants, 6 tones, 10 hover effects

Page: https://goodui.dev/components/core/button

## Install

```bash
npx shadcn@latest add @goodui/button
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/button.json`. The file lands in `components/goodui/button.tsx`.

## When to use

- Any action on a page: submit a form, open a dialog, start a checkout.
- When one product needs several button styles that still match: solid for the primary action, soft or outline for secondary, ghost in toolbars.
- Marketing pages that want motion (shine, shimmer, arrow) without a second library.

## When not to use

- Navigating to another page: use link (or render an <a> with the same classes), so the browser treats it as a link.
- Turning a setting on and off: use switch.
- Choosing one option from a few: use tabs or a segmented control.

## Pick by what matters

| Need | Use |
| --- | --- |
| The one main action on the screen | variant="solid" (add shadow="glow" for a hero CTA) |
| Secondary actions next to a primary one | variant="soft" or "outline" |
| Toolbars and dense tables | variant="ghost" size="sm", iconOnly for single icons |
| Destructive actions | tone="danger" with variant="soft"; solid only inside a confirm dialog |
| Playful or retro brands | variant="neo" or "pushable" |
| On photos or colorful backgrounds | variant="glass" |

## Usage

```tsx
import { ArrowRight } from "lucide-react"
import { Button } from "@/components/goodui/button"

export function Hero() {
  return (
    <div className="flex gap-3">
      <Button size="lg" shadow="glow" animation="arrow" iconRight={<ArrowRight />}>
        Start free trial
      </Button>
      <Button size="lg" variant="outline" tone="neutral">
        Book a demo
      </Button>
    </div>
  )
}
```

### Async action with loading

```tsx
const [saving, setSaving] = React.useState(false)

<Button loading={saving} onClick={async () => { setSaving(true); await save(); setSaving(false) }}>
  Save changes
</Button>
```

### Icon-only toolbar button

```tsx
<Button variant="ghost" tone="neutral" size="sm" iconOnly aria-label="Notifications">
  <Bell />
</Button>
```

## API

### Button

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| variant | `"solid" \| "soft" \| "outline" \| "ghost" \| "link" \| "gradient" \| "glass" \| "neo" \| "pushable" \| "dashed"` | `"solid"` |  |
| tone | `"primary" \| "neutral" \| "success" \| "warning" \| "danger" \| "info"` | `"primary"` |  |
| shadow | `"none" \| "sm" \| "md" \| "lg" \| "glow" \| "hard" \| "inner"` | `"none"` |  |
| animation | `"none" \| "lift" \| "press" \| "shine" \| "shimmer" \| "ripple" \| "pulse" \| "arrow" \| "glow" \| "bounce"` | `"none"` |  |
| shape | `"square" \| "rounded" \| "pill"` | `"rounded"` |  |
| size | `"xs" \| "sm" \| "md" \| "lg" \| "xl"` | `"md"` |  |
| iconOnly | `boolean` | — | Square button for a single icon. |
| fullWidth | `boolean` | — |  |
| loading | `boolean` | — | Shows a spinner, keeps the width and disables the button. |
| iconLeft | `React.ReactNode` | — |  |
| iconRight | `React.ReactNode` | — |  |
| sound | `boolean \| SoundName` | — | Plays "tap" on click when the visitor has sounds on (lib/goodui-sounds); pass a sound name to pick another. Off by default. |

Also accepts every <button> attribute.

## Keyboard

| Keys | Action |
| --- | --- |
| Enter / Space | Activates the button (native <button>). |
| Tab | Moves focus; a focus ring shows on keyboard focus only. |

## Accessibility

- Renders a native <button>, so roles, focus and form submission work without extra code.
- loading sets disabled and aria-busy and keeps the width, so the layout does not jump.
- iconOnly buttons need an aria-label; the icon itself is decorative.

## Motion

- Hover: lift rises 2px in 180 ms, glow blooms a tone-colored shadow, shine sweeps a highlight once, arrow nudges the icons.
- Press: press scales to 0.95, bounce springs back from 0.92, ripple grows from the pointer.
- Looping: shimmer sweeps every 2.6 s and pulse sends a ring every 2 s; keep looping buttons to one per screen.
- Reduced motion: transitions, sweeps, rings and ripples are off; the loading spinner slows down instead of stopping.

## Performance

- All effects are CSS (transform, opacity, background-position) on the compositor; no JavaScript runs on hover. ripple adds one short-lived span per click.

## Notes for AI

- Layers are independent props: variant, tone, shadow, animation, shape, size. Combine them; do not write custom classes for colors.
- Use tone for meaning (danger, success) instead of hard-coded colors like bg-red-500.
- Pass icons through iconLeft and iconRight, not as children, so spacing and the arrow animation work.
- For links use <a> or the link component; do not wrap Button in <a>.
- Keep looping animations (shimmer, pulse) to one button per screen.

## FAQ

**Does it work with my shadcn theme?**

Yes. Colors come from your theme tokens (--primary, --foreground…) through the tone variables, so it follows your theme and dark mode.

**Can I use it as a link?**

Use the link component for navigation. If you need the button look on a link, copy the classes onto an <a>.

## Related

- link: https://goodui.dev/components/core/link
- badge: https://goodui.dev/components/core/badge
- shimmer-button: https://goodui.dev/components/buttons/shimmer-button
- magnetic-button: https://goodui.dev/components/buttons/magnetic-button
- rainbow-button: https://goodui.dev/components/buttons/rainbow-button

Last updated: 2026-11-02

---

# Badge

> One badge, every layer: solid, soft, outline, status dot, gradient, glass and neo in six tones, with pulse, shine, bounce-in and count-pop animations, icons, removable chips and clickable filters.

Status badge for React and shadcn: 7 variants, 6 tones, pulse dot, removable chips

Page: https://goodui.dev/components/core/badge

## Install

```bash
npx shadcn@latest add @goodui/badge
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/badge.json`. The file lands in `components/goodui/badge.tsx`.

## When to use

- Showing a status next to a record: Confirmed, Pending, No-show, Overdue.
- Tags and filters on a list, removable (× button) or clickable (real <button>) without extra wrappers.
- Small counts and plan labels: 3 unread, 99+, Pro, Beta.
- A live indicator such as "Online" or "Recording" with a pinging dot.

## When not to use

- An unread count pinned to the corner of an icon or avatar: use notification-badge.
- A trend number like +12% next to a KPI: use delta-badge, or the delta built into stat-card.
- The main action on a screen: use button; a clickable badge reads as a filter or tag, not a call to action.

## Pick by what matters

| Need | Use |
| --- | --- |
| Status column in a table | variant="soft" (default) with tone="success" \| "warning" \| "danger" |
| Neutral status where the color should stay quiet | variant="dot" with the tone coloring only the dot |
| Something live or online right now | animation="pulse" (works best with variant="dot") |
| Unread or cart counts that change | animation="count" with a number child and max={99} |
| Plan or feature labels on marketing pages | variant="gradient" or animation="shine" |
| Tags a user can remove | removable with onRemove |
| Filter chips a user can toggle | clickable, switching variant="solid" / "outline" by state |

## Usage

```tsx
import { Check, Clock } from "lucide-react"
import { Badge } from "@/components/goodui/badge"

const bookings = [
  { client: "Maya Chen", time: "09:30", status: "Confirmed" },
  { client: "Leo Park", time: "11:00", status: "Pending" },
  { client: "Ana Ruiz", time: "13:15", status: "No-show" },
] as const

const tone = { Confirmed: "success", Pending: "warning", "No-show": "danger" } as const

export function TodayBookings() {
  return (
    <ul className="divide-y rounded-lg border">
      {bookings.map((b) => (
        <li key={b.client} className="flex items-center justify-between px-4 py-3 text-sm">
          <span>
            {b.time} · {b.client}
          </span>
          <Badge tone={tone[b.status]} icon={b.status === "Confirmed" ? <Check /> : b.status === "Pending" ? <Clock /> : undefined}>
            {b.status}
          </Badge>
        </li>
      ))}
    </ul>
  )
}
```

### Removable tags

```tsx
const [tags, setTags] = React.useState(["Haircut", "Color", "VIP"])

<div className="flex flex-wrap gap-1.5">
  {tags.map((t) => (
    <Badge key={t} variant="outline" tone="neutral" removable onRemove={() => setTags((all) => all.filter((x) => x !== t))}>
      {t}
    </Badge>
  ))}
</div>
```

### Toggleable filter chips

```tsx
const [active, setActive] = React.useState<string[]>(["Paid"])
const toggle = (f: string) => setActive((a) => (a.includes(f) ? a.filter((x) => x !== f) : [...a, f]))

{["Today", "Paid", "Walk-ins"].map((f) => (
  <Badge key={f} clickable size="md" variant={active.includes(f) ? "solid" : "outline"} aria-pressed={active.includes(f)} onClick={() => toggle(f)}>
    {f}
  </Badge>
))}
```

### Live count with overflow

```tsx
<Badge variant="solid" tone="danger" size="xs" animation="count" max={99}>
  {unread}
</Badge>
```

## API

### Badge

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| variant | `"solid" \| "soft" \| "outline" \| "dot" \| "gradient" \| "glass" \| "neo"` | `"soft"` | How it is painted: solid fill, soft tint (default), outline, neutral with a colored dot, gradient, frosted glass or neo-brutalist. |
| tone | `"primary" \| "neutral" \| "success" \| "warning" \| "danger" \| "info"` | `"primary"` | Color by meaning; drives every variant through CSS variables. |
| shadow | `"none" \| "sm" \| "md" \| "glow"` | `"none"` | Drop shadow; glow uses the tone color. Ignored by neo, which has its own offset shadow. |
| animation | `"none" \| "pulse" \| "shine" \| "bounce-in" \| "count"` | `"none"` | pulse pings a status dot, shine sweeps a light, bounce-in plays on mount, count pops when the content changes. |
| shape | `"square" \| "rounded" \| "pill"` | `"pill"` |  |
| size | `"xs" \| "sm" \| "md"` | `"sm"` |  |
| icon | `React.ReactNode` | — | Leading icon. On the dot variant it replaces the dot. |
| removable | `boolean` | — | Shows a × button; the badge animates out, then calls onRemove. |
| onRemove | `() => void` | — | Called after the exit animation (instantly with reduced motion). Remove the item from your state here. |
| clickable | `boolean` | — | Renders a real <button> with hover and focus states. |
| max | `number` | — | Numbers above max render as "max+". |
| disabled | `boolean` | — | Dims the badge and disables its button (clickable) or × button. |
| labels | `Partial<BadgeLabels>` | — | Text for built-in controls and screen readers; pass translations here. |

Also accepts every <element> attribute.

## Keyboard

| Keys | Action |
| --- | --- |
| Enter / Space | Activates a clickable badge (native <button>) and the × remove button. |
| Tab | Moves focus to a clickable badge and to its × button; focus rings show on keyboard focus only. |

## Accessibility

- A plain badge is a <span>; clickable renders a real <button type="button">, so add aria-pressed yourself when it toggles a filter.
- The × button has aria-label "Remove" (change it with labels.remove). Inside a clickable badge it becomes a focusable role="button" span, since buttons cannot nest; when the badge is disabled that span leaves the tab order and ignores clicks and keys.
- Icons and the status dot are aria-hidden; the text carries the meaning, so do not rely on the tone color alone.
- disabled dims the badge and disables its <button> (the clickable badge, or the × on a plain badge).

## Motion

- pulse: a copy of the dot scales to 2.6× and fades, every 1.6 s. Without variant="dot" or an icon, a dot is added in front of the text.
- shine: a light sweeps across the badge every 3 s. bounce-in: scales in from 0.3 with overshoot in 500 ms, once on mount.
- count: when the text or number changes, the badge pops from 1.18× and the new value slides up in 380 ms. Never on first render.
- Remove: the badge scales to 0.6 and fades out in 180 ms, then onRemove fires. Clickable badges scale to 0.96 on press (neo badges shift into their shadow).
- Reduced motion: every animation and transition is off, the pulse ring and shine are hidden, and remove happens instantly.

## Performance

- All animations are CSS keyframes on transform and opacity, shipped once through a shared <style> tag. No JavaScript runs per frame.

## Notes for AI

- Layers are independent props: variant, tone, shadow, animation, shape, size. Default is variant="soft" tone="primary" shape="pill" size="sm".
- Map meaning to tone (success, warning, danger, info, neutral); do not add bg-* or text-* color classes.
- removable hides the badge itself after the exit animation; still remove the item from your state in onRemove, or it comes back when its label or removable changes.
- max only applies when children is a number: <Badge max={99}>{count}</Badge> renders "99+". It does nothing for strings.
- Pass icons through icon, not as children. labels={{ remove: "Entfernen" }} translates the × button's aria-label.

## FAQ

**How do I make a status dot without the pulse?**

Use variant="dot". The tone colors only the dot and the badge stays neutral. Add animation="pulse" when it should ping.

**Can a badge be both clickable and removable?**

Yes. The badge renders a <button> and the × becomes a focusable role="button" span that handles Enter and Space and stops the click from reaching the badge.

## Related

- notification-badge: https://goodui.dev/components/feedback/notification-badge
- delta-badge: https://goodui.dev/components/numbers/delta-badge
- button: https://goodui.dev/components/core/button
- avatar: https://goodui.dev/components/core/avatar

Last updated: 2026-11-02

---

# Card

> Eight surfaces (elevated, glass, gradient border, neo, inset…) with shadow, padding, radius and accent stripes, plus hover layers (lift, 3D tilt, pointer spotlight, glow, scale) and a looping border beam.

Card component for React and shadcn: 8 surfaces, hover tilt, spotlight and border beam

Page: https://goodui.dev/components/core/card

## Install

```bash
npx shadcn@latest add @goodui/card
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/card.json`. The file lands in `components/goodui/card.tsx`.

## When to use

- Grouping one thing on a dashboard or settings page: a plan, a booking, a client, a report.
- Pricing and feature grids where one card should stand out (accent, gradient-border, shadow="glow").
- Clickable tiles that need hover feedback (lift, tilt, spotlight) without another library.
- Empty states and drop zones: variant="dashed".

## When not to use

- A single KPI with a delta and sparkline: use stat-card, which is built on the same look.
- Content that opens into a bigger view: use expandable-card or morphing-dialog.
- Splitting sections of one long form: a separator keeps the page lighter than a stack of cards.

## Pick by what matters

| Need | Use |
| --- | --- |
| Default dashboard surface | variant="elevated" (default) or "outline" for flat UIs |
| Grouped settings inside a page that is already a card | variant="inset" or "soft" |
| The recommended pricing plan | variant="gradient-border" or accent="top" with shadow="glow" |
| Status or category color on a list of cards | accent="left" with a tone |
| Clickable tiles in a grid | animation="lift" (calm) or "spotlight" (pointer-following border light) |
| Hero or showcase card on a marketing page | animation="tilt" or "border-beam" |
| Over photos or gradients | variant="glass" |
| Empty state or upload area | variant="dashed" |

## Usage

```tsx
import { CalendarPlus } from "lucide-react"
import { Card, CardFooter } from "@/components/goodui/card"
import { Badge } from "@/components/goodui/badge"
import { Button } from "@/components/goodui/button"

export function NextBooking() {
  return (
    <Card
      className="max-w-sm"
      accent="left"
      tone="success"
      icon={<CalendarPlus />}
      title="Balayage with Maya"
      description="Tomorrow, 09:30 · Chair 2"
      action={<Badge tone="success">Paid</Badge>}
      footer={
        <>
          <Button size="sm">Check in</Button>
          <Button size="sm" variant="ghost" tone="neutral">
            Reschedule
          </Button>
        </>
      }
    >
      2 hours · $180 deposit received. Client asked for a patch test.
    </Card>
  )
}
```

### Featured pricing plan

```tsx
<Card variant="gradient-border" shadow="glow" animation="lift" title="Studio" description="For teams up to 10 stylists">
  <p className="text-3xl font-semibold">$29<span className="text-sm text-muted-foreground">/month</span></p>
  <CardFooter separated>
    <Button className="w-full">Start free trial</Button>
  </CardFooter>
</Card>
```

### Media card with parts

```tsx
<Card padding="sm" animation="spotlight" tone="info">
  <CardMedia>
    <img src="/reports/october.png" alt="Revenue chart for October" />
  </CardMedia>
  <CardHeader>
    <CardTitle>October revenue</CardTitle>
    <CardDescription>Up 12% on September</CardDescription>
  </CardHeader>
</Card>
```

## API

### Card

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| variant | `"elevated" \| "outline" \| "soft" \| "glass" \| "gradient-border" \| "neo" \| "inset" \| "dashed"` | `"elevated"` | Surface: elevated (default), outline, soft tint, frosted glass, gradient border, neo-brutalist, inset well or dashed. |
| tone | `"primary" \| "neutral" \| "success" \| "warning" \| "danger" \| "info"` | `"primary"` | Color for the accent stripe, glow, soft tint, gradient border, hover light and icon tile. |
| shadow | `"none" \| "sm" \| "md" \| "lg" \| "xl" \| "glow"` | `"none"` | Drop shadow; glow uses the tone color. Ignored by neo, which has its own offset shadow. |
| animation | `"none" \| "lift" \| "tilt" \| "spotlight" \| "glow" \| "border-beam" \| "scale"` | `"none"` | Motion layer. lift, scale and glow react to hover; tilt and spotlight follow the pointer; border-beam is not a hover effect: it loops a light around the border continuously (off with reduced motion). |
| padding | `"none" \| "sm" \| "md" \| "lg"` | `"md"` | Inner spacing and gap between parts; CardMedia and separated footers bleed by this amount. |
| radius | `"none" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl"` | `"lg"` |  |
| accent | `"none" \| "top" \| "left"` | `"none"` | A tone-colored stripe on the top or left edge. |
| fullWidth | `boolean` | `true` | false shrinks the card to its content. |
| title | `React.ReactNode` | — | Shorthand: renders a CardHeader with this title. |
| description | `React.ReactNode` | — | Shorthand: muted line under the title. |
| icon | `React.ReactNode` | — | Shorthand: icon in a tinted tile beside the title. |
| action | `React.ReactNode` | — | Shorthand: element on the right of the header (a badge, a menu button). |
| footer | `React.ReactNode` | — | Shorthand: renders a CardFooter. |

Also accepts every <div> attribute.

### CardHeader

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| icon | `React.ReactNode` | — | Icon shown in a tinted tile on the left. |
| action | `React.ReactNode` | — | Element on the right (badge, menu, button). |

Also accepts every <div> attribute.

### CardTitle

Also accepts every <h3> attribute.

### CardDescription

Also accepts every <p> attribute.

### CardContent

Also accepts every <div> attribute.

### CardFooter

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| separated | `boolean` | — | Full-bleed top border above the footer. |

Also accepts every <div> attribute.

### CardMedia

Also accepts every <div> attribute.

## Accessibility

- Renders a plain <div>; the title shorthand and CardTitle render an <h3>. If your heading order needs another level, put your own heading inside CardHeader instead of CardTitle.
- The header icon tile is aria-hidden; put the meaning in the title.
- A focus ring is styled for keyboard focus, but the card is not focusable by default. If the whole card is clickable, put a real <a> or <button> inside rather than adding onClick to the div.

## Motion

- lift: rises 4px with a deeper shadow in 250 ms (neo cards shift up-left into a bigger offset shadow). scale: grows to 1.02 in 250 ms. glow: a tone-colored ring and bloom fade in over 300 ms.
- tilt: rotates up to 4° on X and 5° on Y toward the pointer with a soft glare, and eases back in 500 ms on leave.
- spotlight: a tone-colored light and a brighter border follow the pointer and fade in over 300 ms.
- border-beam: a light runs around the border every 4 s, all the time, not only on hover.
- Touch pointers do not trigger tilt or spotlight.
- Reduced motion: transforms and transitions are off, so lift, scale and tilt do not move and border-beam is hidden. Spotlight and glow still appear, without fading.

## Performance

- tilt and spotlight write CSS variables on pointermove (no React re-render). border-beam animates a registered @property angle, so keep it to one or two cards per screen.

## Notes for AI

- Layers are independent props: variant, tone, shadow, animation, padding, radius, accent. tone colors accent, glow, soft tint, gradient-border, spotlight, beam and the icon tile.
- For the common layout use the shorthand props (title, description, icon, action, footer). Use the parts (CardHeader, CardTitle, CardDescription, CardContent, CardFooter, CardMedia) for custom layouts; do not mix the shorthand header with a second CardHeader.
- A string child is wrapped in CardContent only when a header is present; other children render as they are.
- CardMedia and CardFooter separated go full-bleed using the card padding, so they need padding other than "none".
- shadow is ignored on variant="neo", which has its own offset shadow. fullWidth={false} shrinks the card to its content.

## FAQ

**Is it compatible with shadcn's Card?**

The parts have the same names (CardHeader, CardTitle, CardDescription, CardContent, CardFooter) and data-slot attributes, plus CardMedia and the layer props. CardAction is replaced by the action prop on Card or CardHeader.

**Why does my tilt card not move on a phone?**

Tilt and spotlight ignore touch pointers on purpose, so scrolling a list of cards does not wobble them.

## Related

- stat-card: https://goodui.dev/components/core/stat-card
- spotlight-card: https://goodui.dev/components/cards/spotlight-card
- tilt-card: https://goodui.dev/components/cards/tilt-card
- border-beam: https://goodui.dev/components/cards/border-beam

Last updated: 2026-11-02

---

# Input

> Six field styles with top, floating, inline or hidden labels, focus ring, glow, underline-grow or lift, error shake with sliding messages, icon and text addons, clear button, counter and auto-growing textarea.

Input and textarea for React and shadcn: floating label, error shake, addons, clear button

Page: https://goodui.dev/components/core/input

## Install

```bash
npx shadcn@latest add @goodui/input
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/input.json`. The file lands in `components/goodui/input.tsx`.

## When to use

- Any single-line text field in a form: name, email, price, URL, search.
- Validated forms that need an error or success message under the field, with a shake on a failed submit.
- Fields with units or prefixes: https:// before a domain, $ before a price, .com after a subdomain.
- Notes and messages that should grow with the text: multiline with autoResize.

## When not to use

- Picking from a fixed list of options: use select.
- A one-time code: use otp-input. Several values as chips: use tag-input.
- A search box that expands from an icon in a toolbar: use search-expand.

## Pick by what matters

| Need | Use |
| --- | --- |
| Standard form field | variant="outline" labelMode="top" (defaults) |
| Compact forms where labels sit inside | labelMode="floating" (or "inline" for short labels like "To:") |
| Filter or search bar in a toolbar | variant="filled" or "ghost", labelMode="none", leading={<Search />}, clearable |
| Minimal settings or sign-in pages | variant="underline" with animation="underline-grow" |
| Playful or retro brands | variant="neo" with animation="lift" |
| Over photos or gradients | variant="glass" |
| Validation feedback | state="error" \| "success" with message; shakeKey to shake again on each submit |

## Usage

```tsx
import * as React from "react"
import { Mail } from "lucide-react"
import { Input } from "@/components/goodui/input"

export function InviteField() {
  const [email, setEmail] = React.useState("")
  const [error, setError] = React.useState("")
  const [attempt, setAttempt] = React.useState(0)

  const submit = (e: React.FormEvent) => {
    e.preventDefault()
    setAttempt((n) => n + 1)
    setError(email.includes("@") ? "" : "Enter a valid work email.")
  }

  return (
    <form onSubmit={submit} className="flex max-w-sm flex-col gap-3">
      <Input
        type="email"
        label="Invite a teammate"
        description="They get an email with a link to join your studio."
        placeholder="name@studio.com"
        leading={<Mail />}
        clearable
        value={email}
        onValueChange={setEmail}
        state={error ? "error" : "default"}
        message={error}
        shakeKey={attempt}
      />
      <button type="submit" className="self-start text-sm font-medium underline">
        Send invite
      </button>
    </form>
  )
}
```

### Floating label

```tsx
<Input labelMode="floating" label="Business name" defaultValue="Glow Studio" />
```

### Addons and prefix

```tsx
<Input label="Booking page" addonBefore="https://" addonAfter=".goodui.app" placeholder="glow-studio" />
<Input label="Deposit" leading="$" trailing="USD" inputMode="decimal" placeholder="50.00" />
```

### Growing textarea with counter

```tsx
<Input multiline autoResize rows={2} label="Note for the client" maxLength={280} showCount placeholder="Please arrive 10 minutes early." />
```

## API

### Input

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| variant | `"outline" \| "filled" \| "underline" \| "ghost" \| "neo" \| "glass"` | `"outline"` | Field style: outline (default), filled, underline, ghost, neo-brutalist or frosted glass. |
| tone | `"primary" \| "neutral" \| "success" \| "warning" \| "danger" \| "info"` | `"primary"` | Focus color (ring, border, floating label). Overridden by state="error" or "success". |
| size | `"sm" \| "md" \| "lg"` | `"md"` |  |
| shape | `"square" \| "rounded" \| "pill"` | `"rounded"` |  |
| shadow | `"none" \| "sm" \| "md" \| "inner"` | `"none"` | Field shadow; inner draws an inset shadow. Ignored by neo, which has its own offset shadow. |
| animation | `"none" \| "ring" \| "glow" \| "underline-grow" \| "lift"` | `"ring"` | How the field reacts to focus. |
| label | `React.ReactNode` | — | Field label; placement is set by labelMode. |
| labelMode | `"top" \| "floating" \| "inline" \| "none"` | `"top"` | top: above the field. floating: inside, floats up on focus. inline: inside, before the value. none: screen-reader only. |
| description | `React.ReactNode` | — | Helper text under the field (hidden while a message shows). |
| state | `"default" \| "error" \| "success"` | `"default"` | Validation state: colors the field, adds an icon, sets aria-invalid on error and shows message. |
| message | `React.ReactNode` | — | Error or success text; slides in under the field. |
| shake | `boolean` | `true` | Shake the field when it enters the error state. |
| shakeKey | `React.Key` | — | Change it (e.g. a submit counter) to shake again while already in the error state. |
| leading | `React.ReactNode` | — | Icon or short text inside the field, before the value. |
| trailing | `React.ReactNode` | — | Icon or short text inside the field, after the value. |
| addonBefore | `React.ReactNode` | — | Attached segment before the field, e.g. "https://". |
| addonAfter | `React.ReactNode` | — | Attached segment after the field, e.g. ".com". |
| clearable | `boolean` | — | Shows a × button while the field has a value. |
| showCount | `boolean` | — | Shows "12/80" when maxLength is set. |
| multiline | `boolean` | — | Renders a <textarea>. |
| rows | `number` | `3` | Visible rows of the textarea (multiline only). |
| autoResize | `boolean` | — | Textarea grows with its content. |
| value | `string` | — | Controlled value. |
| defaultValue | `string` | — | Initial value when uncontrolled. |
| onValueChange | `(value: string) => void` | — | Called with the new string on typing and when the clear button empties the field. |
| onChange | `(e: React.ChangeEvent<HTMLInputElement \| HTMLTextAreaElement>) => void` | — | Native change event. The clear button fires it too (with an empty value), so form libraries see the reset. |
| fullWidth | `boolean` | `true` | false shrinks the field to its content width. |
| fieldClassName | `string` | — | Class for the field box (the root gets className). |
| labels | `Partial<InputLabels>` | — | Text for built-in controls and screen readers; pass translations here. |

Also accepts every <input> attribute.

## Accessibility

- Renders a real <input> or <textarea> with a <label htmlFor>; the id is generated with useId unless you pass one.
- labelMode="none" keeps the label for screen readers: a string label becomes aria-label, any other node becomes an sr-only <label>.
- state="error" sets aria-invalid. The description or message is linked with aria-describedby and sits in an aria-live="polite" region, so new errors are announced.
- The clear button has aria-label "Clear" (labels.clear) and returns focus to the field.
- Error and success also show an icon, so the state does not rely on color alone.

## Motion

- Focus: ring adds a 3px tone-colored ring in 200 ms (default), glow adds a soft bloom in 300 ms, lift raises the field 2px, underline-grow draws a bar from the center in 300 ms.
- Floating label: moves up and scales to 0.78 in 180 ms when the field is focused or has a value.
- Message: slides down and expands its height on a spring (stiffness 500, damping 36); the description cross-fades in 150 ms.
- Shake: a 420 ms horizontal shake when the field enters the error state, when the error text changes, or when shakeKey changes.
- Reduced motion: no shake, no lift and no CSS transitions; messages appear and disappear instantly.

## Notes for AI

- Use value + onValueChange (string) for controlled fields; onChange still receives the native event. The clear button fires a real input event, so both onChange and onValueChange get "".
- ref reaches the <input> (or <textarea>), and uncontrolled fields stay native (defaultValue), so react-hook-form's register() works directly.
- Validation is yours: set state="error" and message. Increment shakeKey on every failed submit so the field shakes even if the message did not change.
- tone only changes the focus color. state="error" or "success" overrides it, so do not set tone="danger" for errors.
- className goes on the outer wrapper (label, field and message); use fieldClassName to style the field box itself.
- showCount needs maxLength. autoResize and rows only apply with multiline. labels={{ clear: "Löschen" }} translates the clear button.

## FAQ

**How do I use it with react-hook-form?**

Spread register("email") onto it: ref, name, onChange and onBlur reach the native field, and the clear button reports the empty value. Or use a Controller with value and onValueChange. Pass fieldState.error?.message to message with state="error".

**Can I show the error only after submit?**

Yes. The component never validates on its own; it shows exactly the state and message you pass, whenever you pass them.

## Related

- select: https://goodui.dev/components/core/select
- floating-label-input: https://goodui.dev/components/inputs/floating-label-input
- otp-input: https://goodui.dev/components/inputs/otp-input
- tag-input: https://goodui.dev/components/inputs/tag-input

Last updated: 2026-11-02

---

# Avatar

> Six sizes and four shapes including squircle, status dots with pulse, solid, gradient and rotating story rings, image fade-in with name-based gradient initials, and groups that cap with +N and fan out on hover.

Avatar for React and shadcn: initials fallback, status dot, story ring and avatar group

Page: https://goodui.dev/components/core/avatar

## Install

```bash
npx shadcn@latest add @goodui/avatar
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/avatar.json`. The file lands in `components/goodui/avatar.tsx`.

## When to use

- Showing who a record belongs to: the client on a booking, the assignee on a task, the author of a comment.
- Team and attendee lists where some people have no photo: initials on a gradient derived from the name, the same colors every time.
- Presence in chat or team views: online, away, busy or offline dots.
- Stacks of people on a card or table row ("Maya, Leo and 5 more") with AvatarGroup and max.

## When not to use

- An unread count on top of an avatar: wrap it with notification-badge.
- A logo or product image in a list: use a plain <img>; avatars imply a person.
- A text-only status like "Online" without a face: use badge with variant="dot".

## Pick by what matters

| Need | Use |
| --- | --- |
| Lists and tables | size="sm" or "md", shape="circle" (defaults) |
| Workspaces, teams or companies | shape="rounded" or "squircle" to tell them apart from people |
| Presence | status="online" \| "away" \| "busy" \| "offline", statusPulse for live |
| Highlight the current user or a selected person | ring="solid" with a tone |
| Unseen stories or a live host | ring="story" animation="spin" |
| Attendees on a booking card | AvatarGroup max={4} tooltips |

## Usage

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

const team = [
  { name: "Maya Chen", src: "/team/maya.jpg" },
  { name: "Leo Park", src: "/team/leo.jpg" },
  { name: "Ana Ruiz" },
  { name: "Sam Okafor" },
  { name: "Priya Nair" },
  { name: "Tom Becker" },
]

export function StylistRow() {
  return (
    <div className="flex items-center justify-between rounded-lg border p-4">
      <div className="flex items-center gap-3">
        <Avatar name="Maya Chen" src="/team/maya.jpg" size="lg" status="online" />
        <div className="text-sm">
          <p className="font-medium">Maya Chen</p>
          <p className="text-muted-foreground">Senior stylist · 6 bookings today</p>
        </div>
      </div>
      <AvatarGroup size="sm" max={4} tooltips>
        {team.map((p) => (
          <Avatar key={p.name} name={p.name} src={p.src} />
        ))}
      </AvatarGroup>
    </div>
  )
}
```

### Story ring

```tsx
<Avatar name="Glow Studio" src="/brand/glow.png" size="xl" ring="story" animation="spin" />
```

### Clickable +N chip

```tsx
<AvatarGroup max={3} onMoreClick={() => setShowAttendees(true)}>
  {attendees.map((a) => <Avatar key={a.id} name={a.name} src={a.avatarUrl} />)}
</AvatarGroup>
```

### Initials only

```tsx
<Avatar name="Ana Ruiz" shape="squircle" ring="solid" tone="success" />
```

## API

### Avatar

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| src | `string` | — | Image URL. While it loads, or if it fails, the initials or fallback show. |
| alt | `string` | — | Accessible name; defaults to name. |
| name | `string` | — | Used for the initials, the fallback gradient and the default alt text. |
| size | `"xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl"` | — | 24, 32, 40, 48, 64 or 80px. Inherits from AvatarGroup, else md. |
| shape | `"circle" \| "rounded" \| "square" \| "squircle"` | — | Inherits from AvatarGroup, else circle. |
| status | `"none" \| "online" \| "away" \| "busy" \| "offline"` | `"none"` | Presence dot in the bottom corner, with screen-reader text. |
| statusPulse | `boolean` | — | Pings the status dot. |
| ring | `"none" \| "solid" \| "gradient" \| "story"` | `"none"` | Ring around the avatar with a gap: solid (tone color), gradient (tone based) or story (Instagram-style). |
| tone | `"primary" \| "neutral" \| "success" \| "warning" \| "danger" \| "info"` | `"primary"` | Color of the solid ring and the status-free accents. |
| animation | `"none" \| "spin" \| "pulse" \| "pop-in"` | `"none"` | spin rotates a gradient or story ring; pulse breathes the ring; pop-in plays on mount. |
| shadow | `"none" \| "sm" \| "md" \| "lg"` | `"none"` | Drop shadow that follows the shape. |
| fallback | `React.ReactNode` | — | Content shown when there is no image and no name. |
| labels | `Partial<AvatarLabels>` | — | Text for built-in controls and screen readers; pass translations here. |

Also accepts every <span> attribute.

### AvatarGroup

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| size | `"xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl"` | `"md"` | Size for every avatar in the group. |
| shape | `"circle" \| "rounded" \| "square" \| "squircle"` | `"circle"` | Shape for every avatar and the "+N" chip. |
| overlap | `"none" \| "sm" \| "md" \| "lg"` | `"md"` | How much neighbours overlap. |
| max | `number` | — | Show at most this many avatars, then a "+N" chip. |
| spread | `boolean` | `true` | Avatars fan out when the group is hovered. |
| tooltips | `boolean` | — | Shows each avatar's name above it on hover. |
| onMoreClick | `() => void` | — | Makes the "+N" chip a button. |
| labels | `Partial<AvatarGroupLabels>` | — | Text for built-in controls and screen readers; pass translations here. |

Also accepts every <div> attribute.

## Keyboard

| Keys | Action |
| --- | --- |
| Enter / Space | Activates the "+N" chip when onMoreClick is set (native <button>). |

## Accessibility

- With an image, the <img> gets alt from alt or name. Without one, the avatar is role="img" with aria-label from alt or name, and the initials are aria-hidden.
- The status dot carries visually hidden text ("online", "away"…), translatable with labels.
- The "+N" chip has an aria-label ("5 more", or "Show 5 more" when it is a button); translate both with AvatarGroup labels.
- Group tooltips are CSS-only and appear on hover, not on focus. Do not put information there that is not also available elsewhere.

## Motion

- The image fades in over 350 ms once loaded; an image already in cache shows immediately.
- spin rotates a gradient or story ring every 3 s. pulse makes the ring breathe (scale 1.07, every 2 s), or sends a halo outward when there is no ring. pop-in scales from 0.4 with overshoot in 500 ms on mount.
- statusPulse pings the status dot to 2.4× every 1.6 s.
- AvatarGroup: hovering the group fans the avatars apart in 300 ms and the hovered one rises 3px; tooltips fade in over 150 ms.
- Reduced motion: every animation and transition is off, the halo and status ping are hidden and the group does not fan out.

## Notes for AI

- Always pass name, even with src: it drives the initials and gradient fallback when the image fails, and the alt text.
- Initials use the first letter of the first and last words ("Maya Chen" → MC); a single word gives one letter.
- Inside AvatarGroup, set size and shape on the group; children inherit them. Avatars need a key and a name for tooltips.
- spin only shows on ring="gradient" or "story"; a solid ring has nothing to rotate.
- The ring gap and status border use the page background. On a card, set the CSS variable on the avatar or group: className="[--pc-av-gap:var(--card)]".

## FAQ

**What happens if the image URL is broken?**

onError switches to the initials on the name-based gradient, or to fallback (a user icon by default) when there is no name. A new src resets it.

**Are the initials colors stable?**

Yes. The gradient hue comes from a deterministic hash of the name, so the same name gets the same colors on the server and the client.

## Related

- notification-badge: https://goodui.dev/components/feedback/notification-badge
- badge: https://goodui.dev/components/core/badge
- card: https://goodui.dev/components/core/card
- animated-list: https://goodui.dev/components/lists/animated-list

Last updated: 2026-11-02

---

# Alert

> Soft, solid, outline, left-accent, glass, neo and full-width banner alerts with tone-picked icons, actions, slide, fade, shake or pop entrances, smooth collapse on dismiss and a pausable auto-dismiss countdown.

Alert and banner for React and shadcn: dismissible, auto-dismiss countdown, 7 variants

Page: https://goodui.dev/components/core/alert

## Install

```bash
npx shadcn@latest add @goodui/alert
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/alert.json`. The file lands in `components/goodui/alert.tsx`.

## When to use

- A message tied to one page or section: a failed payment, an expiring trial, a sync that needs attention.
- Form-level errors above a form ("We could not save your changes") with a Retry action.
- A full-width announcement bar at the top of an app: variant="banner".
- Short confirmations that go away on their own: autoDismiss with a countdown bar that pauses on hover.

## When not to use

- Feedback that floats above the page after an action ("Booking saved"): use toast-stack.
- An error on one field: use the state and message props of input.
- A question that needs an answer before continuing: use a dialog such as morphing-dialog.

## Pick by what matters

| Need | Use |
| --- | --- |
| Inline message in a page or card | variant="soft" (default) with a tone |
| Critical problem the user must notice | variant="solid" tone="danger", animation="shake" when it appears after an action |
| Quiet note inside a dense settings page | variant="left-accent" or "outline", size="sm" |
| Site-wide announcement or trial notice | variant="banner" with actions and dismissible |
| Confirmation that clears itself | autoDismiss (5 s) or autoDismiss={8000}, tone="success" |
| Over a photo or gradient hero | variant="glass" |

## Usage

```tsx
import { Alert } from "@/components/goodui/alert"
import { Button } from "@/components/goodui/button"

export function PaymentFailed() {
  return (
    <Alert
      tone="danger"
      title="Your last payment failed"
      animation="slide-down"
      dismissible
      actions={
        <>
          <Button size="sm" tone="danger">
            Update card
          </Button>
          <Button size="sm" variant="ghost" tone="neutral">
            View invoice
          </Button>
        </>
      }
    >
      We could not charge the Visa ending in 4242 for $29.00. Online bookings pause in 3 days.
    </Alert>
  )
}
```

### Announcement banner

```tsx
<Alert variant="banner" tone="primary" dismissible actions={<a href="/billing" className="font-semibold underline">Upgrade</a>}>
  Your trial ends in 3 days. Keep online booking and SMS reminders.
</Alert>
```

### Auto-dismissing confirmation

```tsx
<Alert tone="success" autoDismiss={6000} animation="pop" title="Reminder sent" onDismiss={() => setSent(false)}>
  Maya gets an SMS 24 hours before her 09:30 appointment.
</Alert>
```

### Controlled

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

<Alert open={open} onOpenChange={setOpen} dismissible tone="warning" title="Calendar sync paused">
  Reconnect Google Calendar to keep availability up to date.
</Alert>
```

## API

### Alert

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| variant | `"soft" \| "solid" \| "outline" \| "left-accent" \| "glass" \| "neo" \| "banner"` | `"soft"` | soft (default), solid, outline, left-accent stripe, frosted glass, neo-brutalist, or banner (full-width bar, centered, ignores size and shape). |
| tone | `"primary" \| "neutral" \| "success" \| "warning" \| "danger" \| "info"` | `"info"` | Color and default icon. danger and warning use role="alert", the rest role="status". |
| shadow | `"none" \| "sm" \| "md" \| "lg"` | `"none"` | Drop shadow. Ignored by neo, which has its own offset shadow. |
| animation | `"none" \| "slide-down" \| "fade" \| "shake" \| "pop"` | `"none"` | Entrance animation, played on mount. |
| shape | `"square" \| "rounded" \| "pill"` | `"rounded"` |  |
| size | `"sm" \| "md" \| "lg"` | `"md"` |  |
| title | `React.ReactNode` | — | Bold first line; children render as the description under it. |
| icon | `React.ReactNode` | — | Replaces the tone's icon. |
| hideIcon | `boolean` | — | Hides the icon entirely. |
| actions | `React.ReactNode` | — | Buttons or links, shown under the text (inline on the banner). |
| dismissible | `boolean` | — | Shows a × button. |
| autoDismiss | `boolean \| number` | — | Close automatically after this many ms (true = 5000), with a countdown bar. Pauses on hover and focus. |
| open | `boolean` | — | Controlled visibility. |
| defaultOpen | `boolean` | `true` | Initial visibility when uncontrolled. |
| onOpenChange | `(open: boolean) => void` | — | Called with false when the × button or the auto-dismiss timer closes it. |
| onDismiss | `() => void` | — | Called after the collapse animation finishes. |
| fullWidth | `boolean` | `true` | false shrinks the alert to its content. |
| labels | `Partial<AlertLabels>` | — | Text for built-in controls and screen readers; pass translations here. |

Also accepts every <div> attribute.

## Keyboard

| Keys | Action |
| --- | --- |
| Tab | Focusing anything inside the alert (an action or the × button) pauses autoDismiss until focus leaves. |
| Enter / Space | Activates the × button (native <button>). |

## Accessibility

- tone="danger" and "warning" render role="alert" (announced immediately); other tones render role="status".
- The tone icon is aria-hidden; the title and text carry the meaning.
- The × button has aria-label "Dismiss" (labels.dismiss). The countdown bar is aria-hidden.
- autoDismiss pauses while the pointer is over the alert or focus is inside it, so people can read it and reach its actions.

## Motion

- Entrance on mount: slide-down drops in 10px and fades in 350 ms, fade fades in 350 ms, pop scales from 0.94 with overshoot in 400 ms, shake shakes sideways for 500 ms.
- Dismiss: fades out in 180 ms while the height collapses over 280 ms (after an 80 ms delay), so content below slides up; onDismiss fires when it finishes.
- autoDismiss: a 3px bar shrinks linearly over the duration and freezes while paused.
- Reduced motion: no entrance animation and no transitions, the collapse is instant and the countdown bar is hidden (the timer still runs).

## Notes for AI

- Default is variant="soft" tone="info". tone picks the icon too (primary Sparkles, neutral Bell, success CircleCheck, warning TriangleAlert, danger CircleAlert, info Info); override with icon or hideIcon.
- children is the description; title is the bold line. Put buttons in actions, not in children.
- Uncontrolled alerts hide themselves on dismiss and come back when the string title or text changes. Use open and onOpenChange when the parent decides.
- autoDismiss={true} means 5000 ms; a number is milliseconds. It needs no dismissible to work.
- variant="banner" centers its content, shows actions inline and ignores size and shape. labels={{ dismiss: "Schließen" }} translates the × button.

## FAQ

**What is the difference between onOpenChange and onDismiss?**

onOpenChange(false) fires the moment the alert is closed (× or timer). onDismiss fires after the collapse animation, when the alert has left the layout.

**Can the banner stick to the top of the page?**

Yes. Wrap it in your own sticky container (for example <div className="sticky top-0 z-50">); the alert itself is not positioned.

## Related

- toast-stack: https://goodui.dev/components/feedback/toast-stack
- badge: https://goodui.dev/components/core/badge
- button: https://goodui.dev/components/core/button
- input: https://goodui.dev/components/core/input

Last updated: 2026-11-02

---

# Tabs

> Six variants (underline, pill, segmented, enclosed folder tabs, soft, vertical line), a sliding, fading or static indicator, fade or directional slide panels, tones, sizes, shapes, shadows and orientation, with icons, count badges, arrow keys and a one-line items API.

Animated tabs for React and shadcn: sliding indicator, segmented, pill and vertical tabs

Page: https://goodui.dev/components/core/tabs

## Install

```bash
npx shadcn@latest add @goodui/tabs
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/tabs.json`. The file lands in `components/goodui/tabs.tsx`.

## When to use

- Switching between views of the same thing without leaving the page: a client's Bookings, Invoices and Notes.
- Settings pages with sections in a side list: variant="vertical-line" or orientation="vertical".
- Filtering one list by status with counts: All 24, Upcoming 9, Cancelled 2.
- A compact view switch (Day / Week / Month) above a calendar: variant="segmented".

## When not to use

- Navigating between pages with their own URLs: use links in your nav, or bottom-nav on mobile.
- A stand-alone two or three option toggle that is not tied to panels: use segmented-control.
- Steps that must be done in order: use stepper.

## Pick by what matters

| Need | Use |
| --- | --- |
| Page or card sections | variant="underline" (default) with indicator="slide" |
| View switch above a calendar or chart | variant="segmented" size="sm" |
| Status filters with counts | variant="pill" or "soft" with count on each tab |
| Folder-style tabs attached to a panel | variant="enclosed" (the panel gets the border and card background) |
| Settings sidebar | variant="vertical-line" |
| Equal-width tabs on mobile | fullWidth |
| Calm UI with no motion | indicator="none" transition="none" |

## Usage

```tsx
import { CalendarDays, FileText, StickyNote } from "lucide-react"
import { Tabs, TabsContent, TabsList, TabsTrigger } from "@/components/goodui/tabs"

export function ClientTabs() {
  return (
    <Tabs defaultValue="bookings" transition="slide">
      <TabsList aria-label="Client details">
        <TabsTrigger value="bookings" icon={<CalendarDays />} count={3}>
          Bookings
        </TabsTrigger>
        <TabsTrigger value="invoices" icon={<FileText />}>
          Invoices
        </TabsTrigger>
        <TabsTrigger value="notes" icon={<StickyNote />}>
          Notes
        </TabsTrigger>
      </TabsList>
      <TabsContent value="bookings">3 upcoming appointments, next on Friday at 09:30.</TabsContent>
      <TabsContent value="invoices">2 paid invoices, $340 total this year.</TabsContent>
      <TabsContent value="notes">Prefers Maya. Sensitive scalp, patch test before color.</TabsContent>
    </Tabs>
  )
}
```

### One-liner with items

```tsx
<Tabs
  variant="segmented"
  size="sm"
  listLabel="Calendar view"
  items={[
    { value: "day", label: "Day", content: <DayView /> },
    { value: "week", label: "Week", content: <WeekView /> },
    { value: "month", label: "Month", content: <MonthView /> },
  ]}
/>
```

### Controlled status filter

```tsx
const [status, setStatus] = React.useState("upcoming")

<Tabs value={status} onValueChange={setStatus} variant="pill" tone="neutral" transition="none">
  <TabsList aria-label="Booking status">
    <TabsTrigger value="upcoming" count={9}>Upcoming</TabsTrigger>
    <TabsTrigger value="past" count={124}>Past</TabsTrigger>
    <TabsTrigger value="cancelled" count={2}>Cancelled</TabsTrigger>
  </TabsList>
</Tabs>
```

### Settings sidebar

```tsx
<Tabs variant="vertical-line" defaultValue="profile">
  <TabsList aria-label="Settings">
    <TabsTrigger value="profile">Profile</TabsTrigger>
    <TabsTrigger value="billing">Billing</TabsTrigger>
    <TabsTrigger value="team">Team</TabsTrigger>
  </TabsList>
  <TabsContent value="profile"><ProfileForm /></TabsContent>
  <TabsContent value="billing"><BillingForm /></TabsContent>
  <TabsContent value="team"><TeamForm /></TabsContent>
</Tabs>
```

## API

### Tabs

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| value | `string` | — | Active tab value (controlled). |
| defaultValue | `string` | — | Initially active tab when uncontrolled; defaults to the first enabled tab. |
| onValueChange | `(value: string) => void` | — | Called with the new value when a tab is clicked or picked with the keyboard. |
| variant | `"underline" \| "pill" \| "segmented" \| "enclosed" \| "soft" \| "vertical-line"` | `"underline"` | Look of the list and marker: underline, pill, segmented, enclosed (folder tabs), soft or vertical-line. |
| tone | `"primary" \| "neutral" \| "success" \| "warning" \| "danger" \| "info"` | `"primary"` | Color of the active marker, text and count. |
| indicator | `"none" \| "slide" \| "fade"` | `"slide"` | How the active marker moves between tabs. |
| transition | `"none" \| "fade" \| "slide"` | `"fade"` | How a panel enters when its tab is selected. |
| size | `"sm" \| "md" \| "lg"` | `"md"` |  |
| shape | `"auto" \| "square" \| "rounded" \| "pill"` | `"auto"` | Corner style of tabs and marker. "auto" picks the natural one for the variant. |
| shadow | `"none" \| "sm" \| "md" \| "glow"` | `"none"` | Shadow under the active marker. |
| orientation | `"horizontal" \| "vertical"` | `"horizontal"` | Lays the list out vertically beside the panel. Ignored by enclosed; vertical-line is always vertical. |
| fullWidth | `boolean` | `false` | Stretch the tabs into equal columns. |
| sound | `boolean \| SoundName` | — | Plays "tick" when a tab is selected and the visitor has sounds on (lib/goodui-sounds); pass a sound name to pick another. Off by default. |
| items | `TabsItem[]` | — | Shortcut: renders the list and the panels for you. |
| listLabel | `string` | — | Accessible name of the tab list when using `items`. |

Also accepts every <div> attribute.

### TabsList

Also accepts every <div> attribute.

### TabsTrigger

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| value (required) | `string` | — | Matches the TabsContent with the same value. |
| icon | `React.ReactNode` | — | Icon before the label. |
| count | `React.ReactNode` | — | Small count after the label. |

Also accepts every <button> attribute.

### TabsContent

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| value (required) | `string` | — | Shown when the TabsTrigger with this value is active. |
| keepMounted | `boolean` | — | Keep the panel in the DOM (hidden) when inactive, e.g. to preserve form state. |

Also accepts every <div> attribute.

## Keyboard

| Keys | Action |
| --- | --- |
| Arrow Right / Arrow Down | Focuses and selects the next tab, wrapping to the first; disabled tabs are skipped. |
| Arrow Left / Arrow Up | Focuses and selects the previous tab, wrapping to the last. |
| Home / End | Focuses and selects the first or last enabled tab. |
| Tab | Moves focus from the active tab into its panel (only the active tab is in the tab order). |

## Accessibility

- WAI-ARIA tabs pattern: role="tablist" with aria-orientation, role="tab" with aria-selected and aria-controls, role="tabpanel" with aria-labelledby. Ids come from useId. aria-controls is only set while that panel is in the DOM (the active one, or keepMounted panels), so it never points at a missing element.
- Arrow keys follow reading direction: under dir="rtl" ArrowLeft moves to the next tab. The underline, vertical-line marker and slide transition mirror too.
- Roving tabindex: only the active tab is focusable with Tab; arrows move between tabs and select them (automatic activation).
- Give the list a name: aria-label on TabsList, or listLabel when using items.
- Panels are focusable (tabIndex 0) with a visible focus ring, so keyboard users can reach panels that have no focusable content.

## Motion

- indicator="slide" (default): the active marker moves between tabs as a shared layout element on a spring (stiffness 520, damping 40, mass 0.9).
- indicator="fade": the marker appears in place, fading and scaling from 0.94 in 220 ms. Tab text and background colors transition in 200 ms.
- transition="fade" (default): the new panel fades and rises 4px in 240 ms. "slide": it slides in 14px from the side you moved toward, in 280 ms.
- Nothing animates on first render; panel and fade animations start after the first tab change.
- Reduced motion: the marker jumps instead of sliding and panels appear without animation.

## Notes for AI

- Use either the parts (Tabs, TabsList, TabsTrigger, TabsContent) or the items prop, not both; children win over items.
- value strings must match between TabsTrigger and TabsContent. Use value + onValueChange for controlled tabs, defaultValue otherwise; without either, the first enabled tab is selected.
- Put icons in icon and counts in count, not inside children, so spacing and the active count color work.
- variant="vertical-line" is always vertical; orientation="vertical" is ignored by enclosed. Vertical tabs stack above the panel below the sm breakpoint.
- Panels unmount when inactive; add keepMounted on TabsContent to keep form state. Tabs has no built-in text, so there is no labels prop.

## FAQ

**Can I use tabs only as a filter, without panels?**

Yes. Render Tabs and TabsList with triggers and no TabsContent, and react to onValueChange.

**Does it scroll when there are too many tabs?**

Horizontal lists scroll sideways with the scrollbar hidden; tabs keep their width and do not wrap.

## Related

- segmented-control: https://goodui.dev/components/navigation/segmented-control
- tabs-indicator: https://goodui.dev/components/navigation/tabs-indicator
- stepper: https://goodui.dev/components/navigation/stepper
- bottom-nav: https://goodui.dev/components/navigation/bottom-nav

Last updated: 2026-11-02

---

# Switch

> iOS, Material 3, square, neo-brutalist, icon thumb and ON/OFF label variants with none, smooth, spring and bounce motion, six tones, three sizes, track shadows, sun/moon or check/x glyphs, label and description on either side, and a loading state.

Toggle switch for React and shadcn: iOS, Material 3, neo and ON/OFF variants with spring motion

Page: https://goodui.dev/components/core/switch

## Install

```bash
npx shadcn@latest add @goodui/switch
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/switch.json`. The file lands in `components/goodui/switch.tsx`.

## When to use

- Settings that take effect immediately: SMS reminders on, online booking off, auto-renew.
- A settings list where each row has a title, a description and the toggle at the end: labelPosition="left".
- Toggles that save to a server: loading shows a spinner in the thumb and blocks extra clicks.

## When not to use

- Choices that only apply after the user presses Save, or agreeing to terms: use checkbox.
- Picking one of several options: use tabs, segmented-control or a RadioGroup from checkbox.
- A single light/dark button in a header: use theme-toggle.

## Pick by what matters

| Need | Use |
| --- | --- |
| Default app settings | variant="ios" (default) with animation="spring" |
| Android-like or Material apps | variant="material" (the thumb grows when on) |
| State that must be readable without color | variant="icon-thumb" (check / x) or "label-inside" (ON / OFF) |
| Theme switch in a settings page | icons="theme" (sun / moon in the thumb) |
| Retro or playful brands | variant="neo" or "square" |
| Calm, no-bounce motion | animation="smooth" or "none" |
| Settings row | label, description and labelPosition="left" |

## Usage

```tsx
import * as React from "react"
import { Switch } from "@/components/goodui/switch"

export function ReminderSettings() {
  const [sms, setSms] = React.useState(true)
  const [saving, setSaving] = React.useState(false)

  const toggleSms = async (next: boolean) => {
    setSaving(true)
    await fetch("/api/settings", { method: "PATCH", body: JSON.stringify({ smsReminders: next }) })
    setSms(next)
    setSaving(false)
  }

  return (
    <div className="flex max-w-md flex-col gap-4">
      <Switch
        checked={sms}
        onCheckedChange={toggleSms}
        loading={saving}
        label="SMS reminders"
        description="Clients get a text 24 hours before their appointment."
        labelPosition="left"
      />
      <Switch defaultChecked label="Online booking" labelPosition="left" tone="success" name="onlineBooking" />
    </div>
  )
}
```

### ON / OFF in the track

```tsx
<Switch variant="label-inside" defaultChecked aria-label="Auto-renew" />
```

### Translated track text

```tsx
<Switch variant="label-inside" onText="AN" offText="AUS" label="Erinnerungen" />
```

### Theme switch

```tsx
<Switch icons="theme" variant="material" size="lg" checked={dark} onCheckedChange={setDark} aria-label="Dark mode" />
```

## API

### Switch

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| defaultChecked | `boolean` | `false` | Initial state when uncontrolled. |
| name | `string` | — | Submits "on" (or `value`) under this name in a form when checked. |
| checked | `boolean` | — | On state (controlled). |
| onCheckedChange | `(checked: boolean) => void` | — | Called with the new state on click, Space or Enter (not while loading). |
| variant | `"ios" \| "material" \| "square" \| "neo" \| "icon-thumb" \| "label-inside"` | `"ios"` | Track and thumb style: ios (default), material, square, neo, icon-thumb (check/x) or label-inside (ON/OFF). |
| tone | `"primary" \| "neutral" \| "success" \| "warning" \| "danger" \| "info"` | `"primary"` | Track color when on. |
| animation | `"none" \| "smooth" \| "spring" \| "bounce"` | `"spring"` | How the thumb travels: spring (default), smooth ease, bounce with squash, or none. |
| shadow | `"none" \| "sm" \| "inner" \| "glow"` | `"none"` | Track shadow; glow only shows when on. |
| size | `"sm" \| "md" \| "lg"` | `"md"` |  |
| icons | `"auto" \| "none" \| "check" \| "theme"` | `"auto"` | Glyphs inside the thumb. "auto" shows check/x on icon-thumb and nothing elsewhere. |
| checkedIcon | `React.ReactNode` | — | Custom thumb glyphs, override `icons`. |
| uncheckedIcon | `React.ReactNode` | — | Custom thumb glyph for the off state. |
| onText | `string` | `"ON"` | Text inside the track for the label-inside variant. |
| offText | `string` | `"OFF"` | Off text for the label-inside variant. |
| label | `React.ReactNode` | — | Visible label; the row becomes a <label> linked with aria-labelledby. |
| description | `React.ReactNode` | — | Muted helper text under the label, linked with aria-describedby. |
| labelPosition | `"left" \| "right"` | `"right"` | Where the text sits. "left" makes a full-width settings row with the switch at the end. |
| loading | `boolean` | — | Shows a spinner in the thumb and blocks toggling, e.g. while saving. |
| value | `string` | — | Value submitted with name when checked; defaults to "on". |
| sound | `boolean \| SoundName` | — | Plays "toggle-on" / "toggle-off" when the visitor has sounds on (lib/goodui-sounds); pass a sound name to use one sound for both. Off by default. |

Also accepts every <button> attribute.

## Keyboard

| Keys | Action |
| --- | --- |
| Space / Enter | Toggles the switch (native <button>); does nothing while loading or disabled. |
| Tab | Moves focus to the switch; a focus ring shows on keyboard focus only. |

## Accessibility

- A native <button role="switch"> with aria-checked, so screen readers announce on and off.
- label and description are linked with aria-labelledby and aria-describedby, and the whole row is a <label>, so clicking the text toggles it.
- Without label, pass aria-label. The thumb, its glyphs and the ON / OFF text are aria-hidden.
- loading sets aria-busy and ignores clicks; disabled disables the button and dims the row.
- icon-thumb and label-inside show the state with a glyph or text, not only with color.

## Motion

- spring (default): the thumb slides on a spring (stiffness 620, damping 36). smooth: a 200 ms ease. bounce: a looser spring (stiffness 520, damping 13) with a squash and stretch of the thumb over 340 ms. none: it jumps.
- Press: the thumb stretches toward the travel direction (material grows to 1.12; neo pushes the whole track into its shadow).
- material shrinks the thumb when off unless it shows a glyph. Glyphs swap with a rotate and scale (300 ms, slight overshoot) and a 200 ms fade. Track color changes in 220 ms.
- Reduced motion: the thumb jumps with no press stretch and no transitions; the loading spinner slows to 1.6 s per turn instead of stopping.

## Notes for AI

- The callback is onCheckedChange(checked: boolean), not onChange. Use checked for controlled, defaultChecked otherwise.
- Pass label (and description) as props instead of wrapping the switch in your own <label>; without label, set aria-label.
- For native forms pass name (and optionally value): a hidden checkbox submits "on" (or value) when checked.
- onText and offText (default "ON" / "OFF") are only used by variant="label-inside"; translate them there. There is no labels prop.
- className goes on the track when there is no label or description, and on the row otherwise. tone only colors the on state.

## FAQ

**How do I show a save in progress?**

Set loading while your request runs. The thumb shows a spinner, aria-busy is set and clicks are ignored; set checked when the request succeeds.

**Switch or checkbox?**

A switch applies immediately, like a light switch. A checkbox is a choice that is submitted later with a form.

## Related

- checkbox: https://goodui.dev/components/core/checkbox
- switch-spring: https://goodui.dev/components/inputs/switch-spring
- theme-toggle: https://goodui.dev/components/buttons/theme-toggle
- segmented-control: https://goodui.dev/components/navigation/segmented-control

Last updated: 2026-11-02

---

# Checkbox & Radio

> Checkbox and RadioGroup on real inputs with default, filled, outline, circle, neo and whole-card variants, draw, pop and bounce animations, tones, sizes, shadows, indeterminate, invalid and descriptions.

Animated checkbox and radio group for React and shadcn: draw-in check, card options, indeterminate

Page: https://goodui.dev/components/core/checkbox

## Install

```bash
npx shadcn@latest add @goodui/checkbox
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/checkbox.json`. The file lands in `components/goodui/checkbox.tsx`.

## When to use

- Choices submitted with a form: accept the terms, pick add-ons, choose notification channels.
- Select-all in a table header with some rows selected: indeterminate.
- Plan, time slot or payment method pickers where each option is a card with a price: variant="card" on RadioGroup.
- One choice from a short visible list (2 to 5 options): RadioGroup with Radio.

## When not to use

- A setting that applies immediately: use switch.
- One choice from a long list: use select.
- Switching views or filters at the top of a list: use tabs or segmented-control.

## Pick by what matters

| Need | Use |
| --- | --- |
| Standard form checkbox | variant="default" animation="draw" (defaults) |
| Options with a price or details | variant="card" with description and children |
| Round checkboxes (to-do lists, image pickers) | variant="circle" |
| Quieter checked state | variant="outline" (tinted box with a colored mark) |
| Playful or retro brands | variant="neo" with animation="bounce" |
| Snappy feedback in dense tables | animation="pop" size="sm" |
| Settings list with the box at the end | labelPosition="left" |

## Usage

```tsx
import * as React from "react"
import { Checkbox, Radio, RadioGroup } from "@/components/goodui/checkbox"

export function BookingOptions() {
  const [plan, setPlan] = React.useState("monthly")
  const [terms, setTerms] = React.useState(false)

  return (
    <form className="flex max-w-md flex-col gap-5">
      <RadioGroup value={plan} onValueChange={setPlan} variant="card" name="plan" aria-label="Billing period">
        <Radio value="monthly" label="Monthly" description="$29 per month, cancel any time" />
        <Radio value="yearly" label="Yearly" description="$290 per year, two months free">
          <span className="mt-1 text-xs font-medium text-emerald-600 dark:text-emerald-400">Most popular</span>
        </Radio>
      </RadioGroup>
      <Checkbox name="sms" defaultChecked label="SMS reminders" description="Text clients 24 hours before each booking." />
      <Checkbox checked={terms} onCheckedChange={setTerms} label="I accept the terms of service" required />
    </form>
  )
}
```

### Select all with indeterminate

```tsx
const all = selected.length === rows.length
const some = selected.length > 0 && !all

<Checkbox
  aria-label="Select all bookings"
  checked={all}
  indeterminate={some}
  onCheckedChange={(on) => setSelected(on ? rows.map((r) => r.id) : [])}
  size="sm"
/>
```

### Horizontal radio group

```tsx
<RadioGroup orientation="horizontal" defaultValue="card" aria-label="Payment method" animation="pop">
  <Radio value="card" label="Card" />
  <Radio value="cash" label="Cash" />
  <Radio value="invoice" label="Invoice" />
</RadioGroup>
```

## API

### Checkbox

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| children | `React.ReactNode` | — | Extra content under the description (prices, badges), handy with the card variant. |
| variant | `"default" \| "filled" \| "outline" \| "circle" \| "neo" \| "card"` | `"default"` | Box style: default, filled, outline (tinted when checked), circle, neo, or card (the whole card is the hit area). |
| tone | `"primary" \| "neutral" \| "success" \| "warning" \| "danger" \| "info"` | `"primary"` | Color when checked. |
| animation | `"none" \| "draw" \| "pop" \| "bounce"` | `"draw"` | How the mark appears: draw (stroke, default), pop, bounce or none. |
| shadow | `"none" \| "sm" \| "glow"` | `"none"` | Box shadow; glow only shows when checked. |
| size | `"sm" \| "md" \| "lg"` | `"md"` |  |
| label | `React.ReactNode` | — | Visible label, linked with aria-labelledby. |
| description | `React.ReactNode` | — | Muted helper text under the label, linked with aria-describedby. |
| labelPosition | `"left" \| "right"` | — | Which side of the box the text sits on. "left" spreads the row (text start, box end). |
| invalid | `boolean` | — | Shows the danger state, e.g. an unaccepted required checkbox. |
| checked | `boolean` | — | Checked state (controlled). |
| defaultChecked | `boolean` | `false` | Initial state when uncontrolled. |
| onCheckedChange | `(checked: boolean) => void` | — | Called with the new checked state. |
| onChange | `React.ChangeEventHandler<HTMLInputElement>` | — | Native change event of the hidden input. |
| indeterminate | `boolean` | `false` | Shows a dash, e.g. a "select all" with some rows selected. Clicking it checks the box. |
| sound | `boolean \| SoundName` | — | Plays "pop" when checked and "tick" when unchecked, when the visitor has sounds on (lib/goodui-sounds); pass a sound name to use one sound for both. Off by default. |

Also accepts every <input> attribute.

### RadioGroup

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| variant | `"default" \| "filled" \| "outline" \| "circle" \| "neo" \| "card"` | `"default"` | Box style: default, filled, outline (tinted when checked), circle, neo, or card (the whole card is the hit area). |
| tone | `"primary" \| "neutral" \| "success" \| "warning" \| "danger" \| "info"` | `"primary"` | Color when checked. |
| animation | `"none" \| "draw" \| "pop" \| "bounce"` | `"draw"` | How the mark appears: draw (stroke, default), pop, bounce or none. |
| shadow | `"none" \| "sm" \| "glow"` | `"none"` | Box shadow; glow only shows when checked. |
| size | `"sm" \| "md" \| "lg"` | `"md"` |  |
| value | `string` | — | Selected radio value (controlled). |
| defaultValue | `string` | — | Initially selected value when uncontrolled. |
| onValueChange | `(value: string) => void` | — | Called with the value of the newly selected radio. |
| name | `string` | — | Form field name. Generated when omitted. |
| disabled | `boolean` | — | Disables every radio in the group. |
| orientation | `"vertical" \| "horizontal"` | `"vertical"` | horizontal lays the radios out in equal columns. |
| labelPosition | `"left" \| "right"` | — | Default text side for every radio. |

Also accepts every <div> attribute.

### Radio

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| value (required) | `string` | — | Value reported to RadioGroup and submitted with the form. |
| children | `React.ReactNode` | — | Extra content under the description (prices, badges), handy with the card variant. |
| variant | `"default" \| "filled" \| "outline" \| "circle" \| "neo" \| "card"` | — | Box style: default, filled, outline (tinted when checked), circle, neo, or card (the whole card is the hit area). |
| tone | `"primary" \| "neutral" \| "success" \| "warning" \| "danger" \| "info"` | — | Color when checked. |
| animation | `"none" \| "draw" \| "pop" \| "bounce"` | — | How the mark appears: draw (stroke, default), pop, bounce or none. |
| shadow | `"none" \| "sm" \| "glow"` | — | Box shadow; glow only shows when checked. |
| size | `"sm" \| "md" \| "lg"` | — |  |
| label | `React.ReactNode` | — | Visible label, linked with aria-labelledby. |
| description | `React.ReactNode` | — | Muted helper text under the label, linked with aria-describedby. |
| labelPosition | `"left" \| "right"` | — | Which side of the box the text sits on. "left" spreads the row (text start, box end). |
| invalid | `boolean` | — | Shows the danger state, e.g. an unaccepted required checkbox. |

Also accepts every <input> attribute.

## Keyboard

| Keys | Action |
| --- | --- |
| Space | Toggles the focused checkbox or selects the focused radio (native <input>). |
| Arrow keys | Move and select within a RadioGroup, because its radios share one name (native behavior). |
| Tab | Moves focus; the box (or the whole card) shows a tone-colored focus ring on keyboard focus only. |

## Accessibility

- Real <input type="checkbox"> and <input type="radio"> elements sit invisibly on the box, so forms, required, autofill and screen readers work natively.
- Each option is a <label>, so the text and the whole card are click targets. label and description are linked with aria-labelledby and aria-describedby.
- indeterminate sets the native indeterminate property, which screen readers announce as mixed.
- Checkbox invalid sets aria-invalid; on Radio it only changes the color, so also show an error message.
- RadioGroup renders role="radiogroup"; give it a name with aria-label or aria-labelledby. Without label, give a Checkbox an aria-label.

## Motion

- draw (default): the check stroke draws in over 300 ms after a 50 ms delay and retracts in 260 ms; a radio dot scales in over 200 ms.
- pop: the box pops from 0.72 past 1.14 back to 1 in 340 ms when checked. bounce: the mark springs in with overshoot over 380 ms while the box squishes for 400 ms.
- Press: the box shrinks to 0.9 (neo shifts into its shadow). Colors and borders change in 160 ms.
- pop and bounce only play after the user has interacted, never on first render.
- Reduced motion: no transitions or keyframes; the check and dot appear fully drawn at once.

## Notes for AI

- Callbacks: Checkbox uses onCheckedChange(checked: boolean); RadioGroup uses onValueChange(value: string). onChange still gets the native event.
- Radio must be inside RadioGroup and needs a value. Set variant, tone, animation, shadow and size once on RadioGroup; a Radio can override them.
- Compute indeterminate from your data (some selected, not all); clicking calls onCheckedChange with the new checked value, so clear indeterminate there. If you keep it true, the native indeterminate flag is re-applied after the click, so the box and screen readers stay in sync.
- ref reaches the hidden native <input type="checkbox">, and an uncontrolled Checkbox stays native (defaultChecked), so react-hook-form's register() works.
- children render under the description, inside the label: put prices or badges there, not interactive elements like links or buttons.
- There is no built-in text, so no labels prop. RadioGroup generates name when you omit it; pass name for native form submission.

## FAQ

**Does it work with react-hook-form?**

Yes. Spread register("terms") onto a Checkbox (the ref reaches the native input), or use a Controller: pass field.value to checked (or value on RadioGroup) and field.onChange to onCheckedChange (or onValueChange).

**How do I make the whole card selectable?**

Use variant="card". The card is the <label>, so clicking anywhere on it selects the option, and it gets a tone-colored border when checked.

## Related

- switch: https://goodui.dev/components/core/switch
- checkbox-draw: https://goodui.dev/components/inputs/checkbox-draw
- select: https://goodui.dev/components/core/select
- segmented-control: https://goodui.dev/components/navigation/segmented-control

Last updated: 2026-11-02

---

# Separator

> Line, dashed, dotted, gradient, double, glow and ornament separators with diamond, dot or icon marks, labels at the center, start or end, tones, thickness, vertical orientation, a draw-in-on-view and a shimmer animation.

Separator and divider for React and shadcn: labeled, dashed, gradient, ornament and draw-in

Page: https://goodui.dev/components/core/separator

## Install

```bash
npx shadcn@latest add @goodui/separator
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/separator.json`. The file lands in `components/goodui/separator.tsx`.

## When to use

- Splitting sections of a settings page or a long form without boxing each one in a card.
- An "or" between two sign-in methods, or a date between groups of messages: label.
- Between items in a toolbar or a row of stats: orientation="vertical".
- Section breaks on marketing pages with a little decoration: ornament, gradient or glow, optionally drawing in on scroll.

## When not to use

- Separating rows of a table or list: use border classes on the rows; a component per row is overkill.
- Grouping related content that needs its own background or actions: use card.
- A section title: use heading; a label on a separator is for short markers like "or" or a date.

## Pick by what matters

| Need | Use |
| --- | --- |
| Plain divider in app UI | variant="line" tone="neutral" (defaults) |
| "or" between two options | label="or" (labelStyle="caps" for OR) |
| Date or group marker in a feed | label with labelStyle="pill", labelPosition="start" for left-aligned |
| Soft divider on a landing page | variant="gradient" (fades at the edges) |
| Decorative section break | variant="ornament" (diamond) or ornament="dots" \| "icon" |
| Divider that reveals on scroll | animation="draw" |
| Toolbar or stat row | orientation="vertical" inside a flex row |

## Usage

```tsx
import { Separator } from "@/components/goodui/separator"
import { Button } from "@/components/goodui/button"
import { Input } from "@/components/goodui/input"

export function SignIn() {
  return (
    <div className="flex max-w-sm flex-col gap-4">
      <Button variant="outline" tone="neutral">
        Continue with Google
      </Button>
      <Separator label="or" labelStyle="caps" />
      <Input type="email" label="Work email" placeholder="name@studio.com" />
      <Button>Send magic link</Button>
    </div>
  )
}
```

### Vertical in a stat row

```tsx
<div className="flex h-10 items-center gap-4 text-sm">
  <span>12 bookings</span>
  <Separator orientation="vertical" />
  <span>$1,840 revenue</span>
  <Separator orientation="vertical" />
  <span>2 no-shows</span>
</div>
```

### Date marker in an activity feed

```tsx
<Separator label="Yesterday" labelStyle="pill" labelPosition="start" variant="dashed" />
```

### Decorative break that draws in

```tsx
<Separator variant="ornament" tone="primary" animation="draw" thickness="medium" />
```

## API

### Separator

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| variant | `"line" \| "dashed" \| "dotted" \| "gradient" \| "double" \| "glow" \| "ornament"` | `"line"` | Line style: line, dashed, dotted, gradient (fades at the edges), double, glow, or ornament (gradient with a diamond). |
| tone | `"neutral" \| "primary" \| "success" \| "warning" \| "danger" \| "info"` | `"neutral"` | neutral (default) uses the theme border color; other tones color the line, marks and labels. |
| ornament | `"none" \| "diamond" \| "dot" \| "dots" \| "icon"` | `"none"` | Mark in the middle. The ornament variant defaults to a diamond. |
| icon | `React.ReactNode` | — | Custom glyph for ornament="icon". |
| label | `React.ReactNode` | — | Short text on the line, e.g. "or" or a date. |
| labelPosition | `"center" \| "start" \| "end"` | `"center"` | Where the label sits along the line. |
| labelStyle | `"plain" \| "pill" \| "caps"` | `"plain"` | plain muted text, a bordered pill, or small spaced capitals. |
| orientation | `"horizontal" \| "vertical"` | `"horizontal"` |  |
| thickness | `"thin" \| "medium" \| "thick"` | `"thin"` | Line weight: 1, 2 or 4px (dots and dashes scale with it). |
| animation | `"none" \| "draw" \| "shimmer"` | `"none"` | "draw" grows the line the first time it scrolls into view; "shimmer" sends a light along it. |
| decorative | `boolean` | `true` | Purely visual (role="none"), like shadcn. Set false to expose it to assistive tech. |

Also accepts every <div> attribute.

## Accessibility

- Decorative by default (role="none"), like shadcn's separator. Set decorative={false} to render role="separator" with aria-orientation.
- Ornaments and icons are aria-hidden. A label is plain text, so screen readers still read it.
- Lines and dots are CSS backgrounds, not text characters, so nothing extra is announced.

## Motion

- draw: the first time 60% of the separator is in view, the line grows from the center (or from the label) over 800 ms; the ornament and label pop in with a slight overshoot after 200 ms. It plays once.
- shimmer: a light sweeps along the line every 2.8 s (top to bottom when vertical).
- Reduced motion: no transitions or animations; draw shows the full line at once and shimmer is hidden.

## Performance

- draw uses one IntersectionObserver per separator and disconnects it after the first reveal. shimmer is a CSS transform animation.

## Notes for AI

- Default is a neutral 1px line. tone="neutral" uses the theme border color; other tones color the line, marks and pill or caps labels.
- Pass text through label, not children (children is not accepted). labelPosition only matters when there is a label.
- variant="ornament" adds a diamond by default; ornament adds a mark to any variant; ornament="icon" uses icon or a built-in sparkle.
- Vertical separators stretch to the parent's height (self-stretch, min 24px), so the parent needs a height or align-items: stretch.
- There is no built-in text, so there is no labels prop.

## FAQ

**Is it compatible with shadcn's Separator?**

Yes for the common props: orientation and decorative work the same way. Everything else is an extra layer with a default that renders a plain line.

**Why does my vertical separator not show?**

It takes the parent's height. Put it in a flex row with a height (for example h-6 or h-10) or with items-stretch.

## Related

- card: https://goodui.dev/components/core/card
- heading: https://goodui.dev/components/core/heading
- text: https://goodui.dev/components/core/text
- breadcrumb: https://goodui.dev/components/core/breadcrumb

Last updated: 2026-11-02

---

# Breadcrumb

> Slash, chevron, dot, pill, arrow-step and underline trails with four current-page styles, tones, sizes, a staggered fade or sliding hover underline, and long trails that collapse into a keyboard-friendly menu.

Breadcrumb for React and shadcn: collapsible trail, pill and arrow-step styles, next/link support

Page: https://goodui.dev/components/core/breadcrumb

## Install

```bash
npx shadcn@latest add @goodui/breadcrumb
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/breadcrumb.json`. The file lands in `components/goodui/breadcrumb.tsx`.

## When to use

- Showing where a page sits in a hierarchy and linking back up: Clients / Maya Chen / Invoices / INV-0042.
- Deep admin pages where the middle of the trail should collapse into a "…" menu on small screens: maxItems.
- A short, fixed flow shown as connected segments (Cart → Details → Payment): variant="arrow-steps".

## When not to use

- A multi-step form where steps have states (done, current, error): use stepper.
- Top-level navigation between sections of the app: use tabs or bottom-nav.
- Pages that are not in a hierarchy (a flat list of settings): a page heading is enough.

## Pick by what matters

| Need | Use |
| --- | --- |
| Default app header | variant="chevron" current="bold" (defaults) |
| File-path or URL-like trails | variant="slash" |
| Very light trails in dense UIs | variant="dot" size="sm" |
| Chips or filter-like trails | variant="pill" with current="tone" or "badge" |
| Short linear flow | variant="arrow-steps" |
| Long trails on mobile | maxItems={3} (keeps the first item and the last two) |
| Hover feedback on links | animation="underline"; animation="fade" staggers the crumbs in on mount |

## Usage

```tsx
import Link from "next/link"
import { Home } from "lucide-react"
import { Breadcrumb } from "@/components/goodui/breadcrumb"

export function InvoiceBreadcrumb() {
  return (
    <Breadcrumb
      linkAs={Link}
      maxItems={4}
      items={[
        { label: "Dashboard", href: "/", icon: <Home /> },
        { label: "Clients", href: "/clients" },
        { label: "Maya Chen", href: "/clients/maya-chen" },
        { label: "Invoices", href: "/clients/maya-chen/invoices" },
        { label: "INV-0042" },
      ]}
    />
  )
}
```

### Arrow steps

```tsx
<Breadcrumb
  variant="arrow-steps"
  tone="success"
  items={[{ label: "Service", href: "/book" }, { label: "Time", href: "/book/time" }, { label: "Details" }]}
/>
```

### Client-side navigation without hrefs

```tsx
<Breadcrumb
  variant="pill"
  current="badge"
  items={[
    { label: "Reports", onClick: () => setView("reports") },
    { label: "Revenue", onClick: () => setView("revenue") },
    { label: "October" },
  ]}
/>
```

## API

### Breadcrumb

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| items (required) | `BreadcrumbItem[]` | — | The trail, root first. The last item is the current page. |
| variant | `"slash" \| "chevron" \| "dot" \| "pill" \| "arrow-steps" \| "underline"` | `"chevron"` | Separator and crumb style: slash, chevron (default), dot, pill, arrow-steps or underline. |
| tone | `"primary" \| "neutral" \| "success" \| "warning" \| "danger" \| "info"` | `"primary"` | Color of the current item (tone and badge styles), pill and arrow-step highlights, and focus rings. |
| size | `"sm" \| "md" \| "lg"` | `"md"` |  |
| current | `"bold" \| "muted" \| "tone" \| "badge"` | `"bold"` | Style of the current (last) item. |
| animation | `"none" \| "fade" \| "underline"` | `"none"` | fade staggers the crumbs in on mount; underline grows an underline under hovered links. |
| maxItems | `number \| string` | `0` | Collapse the middle into a "…" menu when there are more items than this. 0 never collapses. Numeric strings work too. |
| itemsBeforeCollapse | `number` | `1` | Items kept before the "…" when collapsed. |
| itemsAfterCollapse | `number` | `2` | Items kept after the "…" when collapsed (including the current page). |
| separator | `React.ReactNode` | — | Custom separator, replaces the variant's. |
| linkAs | `React.ElementType` | — | Link component, e.g. next/link. Receives href, className and children. |
| labels | `Partial<BreadcrumbLabels>` | — | Text for built-in controls and screen readers; pass translations here. |

Also accepts every <nav> attribute.

## Keyboard

| Keys | Action |
| --- | --- |
| Enter / Space | Follows a link or opens the "…" menu. |
| Arrow Down | On the "…" button, opens the menu. Inside the menu, moves to the next hidden page (wraps). |
| Arrow Up | Moves to the previous hidden page in the menu (wraps). |
| Home / End | Moves to the first or last hidden page in the menu. |
| Escape | Closes the menu and returns focus to the "…" button. |
| Tab | Closes the menu and continues to the next focusable element. |

## Accessibility

- A <nav> with aria-label "Breadcrumb" (override with aria-label) around an ordered list.
- The last item is the current page: it renders as text with aria-current="page", even if it has an href.
- Separators are aria-hidden list items with role="presentation", so screen readers only read the pages.
- The "…" button has aria-haspopup="menu", aria-expanded and aria-label "Show 3 more"; the menu is role="menu" named "Hidden pages". Translate both with labels.showMore and labels.hiddenPages.
- RTL-ready: under dir="rtl" chevrons and arrow-step shapes mirror, the menu opens from the start edge and the fade entrance slides the other way.
- Opening the menu focuses its first item; clicking outside closes it.

## Motion

- fade: crumbs slide in 6px and fade over 400 ms on mount, 55 ms apart.
- underline: an underline grows under the hovered link in 280 ms (variant="underline" already shows static underlines and skips it).
- The "…" menu fades, drops 4px and scales from 0.97 in 160 ms.
- Reduced motion: no entrance, no underline growth and no transitions; the menu appears instantly.

## Notes for AI

- Pass the whole trail in items, root first; the last item is always the current page. Do not render separators yourself.
- Use linkAs={Link} for next/link or react-router; it receives href, onClick, className and children. Items without href but with onClick render as <button>.
- maxItems collapses only when items.length is above it and above itemsBeforeCollapse + itemsAfterCollapse (defaults 1 and 2).
- separator replaces the variant's separator for every gap; arrow-steps has no separators.
- labels={{ showMore: (n) => `${n} weitere anzeigen`, hiddenPages: "Ausgeblendete Seiten" }} translates the menu; the nav name comes from aria-label.

## FAQ

**How do I use it with Next.js?**

Import Link from next/link and pass linkAs={Link}. Every crumb with an href renders through it, including the links in the "…" menu.

**Can I show a long trail on mobile?**

Set maxItems. The middle collapses into a "…" button that opens a keyboard-friendly menu, and long labels are truncated at 16rem.

## Related

- stepper: https://goodui.dev/components/navigation/stepper
- tabs: https://goodui.dev/components/core/tabs
- link: https://goodui.dev/components/core/link
- separator: https://goodui.dev/components/core/separator

Last updated: 2026-11-02

---

# Pagination

> Outline, soft, ghost, pill, neo, minimal and carousel-dot pagination with a sliding active marker or press feedback, tones, sizes and shapes, plus first/last, range info, page-size select and jump-to-page.

Pagination for React and shadcn: sliding active page, rows per page, jump to page, carousel dots

Page: https://goodui.dev/components/core/pagination

## Install

```bash
npx shadcn@latest add @goodui/pagination
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/pagination.json`. The file lands in `components/goodui/pagination.tsx`.

## When to use

- Paging through a table of bookings, invoices or clients, with "21–30 of 248" and a rows-per-page select.
- Search or list pages where people jump to a page number: showJump.
- Compact "Page 3 of 12" controls in a card footer or a mobile view: variant="minimal".
- Dot indicators under a carousel or onboarding slides: variant="dots".

## When not to use

- Feeds where people just keep reading: load more on scroll or with a button instead of pages.
- A multi-step form: use stepper.
- Switching between a few named views: use tabs.

## Pick by what matters

| Need | Use |
| --- | --- |
| Data tables | variant="outline" (default) with totalItems, showInfo and showPageSize |
| Quiet pagination under a list | variant="ghost" or "soft" |
| Pages sitting in one rounded track | variant="pill" |
| Small spaces and mobile | variant="minimal" ("Page 3 of 12"), showJump makes the number editable |
| Carousels and slides | variant="dots" |
| Very long result sets | showFirstLast and showJump; siblings={2} shows more neighbours |
| Playful or retro brands | variant="neo" animation="press" |

## Usage

```tsx
import * as React from "react"
import { Pagination } from "@/components/goodui/pagination"

export function InvoicesFooter({ total }: { total: number }) {
  const [page, setPage] = React.useState(1)
  const [pageSize, setPageSize] = React.useState(25)

  return (
    <Pagination
      aria-label="Invoices pages"
      page={page}
      onPageChange={setPage}
      totalItems={total}
      pageSize={pageSize}
      onPageSizeChange={setPageSize}
      pageSizeOptions={[25, 50, 100]}
      showInfo
      showPageSize
      showLabels
    />
  )
}
```

### Minimal with editable page number

```tsx
<Pagination variant="minimal" totalPages={12} defaultPage={3} showJump size="sm" />
```

### Carousel dots

```tsx
<Pagination variant="dots" totalPages={slides.length} page={slide} onPageChange={setSlide} aria-label="Testimonials" />
```

### Translated

```tsx
<Pagination
  totalItems={248}
  showInfo
  labels={{
    previousPage: "Vorherige Seite",
    nextPage: "Nächste Seite",
    goToPage: (p) => `Seite ${p}`,
    range: (from, to, total) => `${from}–${to} von ${total}`,
  }}
/>
```

## API

### Pagination

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| page | `number` | — | Current page, 1-based (controlled). Clamped to 1…total. |
| defaultPage | `number` | `1` | Initial page when uncontrolled. |
| onPageChange | `(page: number) => void` | — | Called with the new 1-based page. |
| totalPages | `number` | `1` | Number of pages. Ignored when `totalItems` is set. |
| totalItems | `number` | — | Total rows; with `pageSize` it sets the page count and the "21–30 of 248" info. |
| pageSize | `number` | — | Rows per page (controlled). |
| defaultPageSize | `number` | `10` | Initial rows per page when uncontrolled. |
| onPageSizeChange | `(size: number) => void` | — | Called when the rows select changes; the page is adjusted to keep the first visible row. |
| pageSizeOptions | `number[]` | `[10, 25, 50, 100]` | Choices in the rows-per-page select. |
| siblings | `number` | `1` | Pages shown on each side of the current one. |
| boundaries | `number` | `1` | Pages always shown at the start and end. |
| variant | `"outline" \| "soft" \| "ghost" \| "pill" \| "neo" \| "minimal" \| "dots"` | `"outline"` | outline (default), soft, ghost, pill (pages in a track), neo, minimal ("Page 3 of 12") or dots (carousels). |
| tone | `"primary" \| "neutral" \| "success" \| "warning" \| "danger" \| "info"` | `"primary"` | Color of the active page marker and focus rings. |
| animation | `"none" \| "slide" \| "press"` | `"slide"` | slide glides the active marker between pages; press shrinks buttons while pressed. |
| size | `"sm" \| "md" \| "lg"` | `"md"` |  |
| shape | `"rounded" \| "circle" \| "square"` | `"rounded"` | Button corners. The pill variant is always round. |
| showFirstLast | `boolean` | `false` | Adds first-page and last-page buttons. |
| showPrevNext | `boolean` | `true` | Shows the previous and next arrows. |
| showLabels | `boolean` | `false` | "Previous"/"Next" text next to the arrows (hidden on phones). |
| showInfo | `boolean` | `false` | "21–30 of 248" (with totalItems) or "Page 3 of 12". |
| showPageSize | `boolean` | `false` | Adds a rows-per-page select. |
| showJump | `boolean` | `false` | A "Go to" input. In the minimal variant the page number itself becomes editable. |
| labels | `Partial<PaginationLabels>` | — | Text for built-in controls and screen readers; pass translations here. |

Also accepts every <nav> attribute.

## Keyboard

| Keys | Action |
| --- | --- |
| Enter / Space | Activates the focused page, arrow or "…" button (native <button>). |
| Enter | In the jump-to field, goes to the typed page (clamped to 1…total). In the minimal variant leaving the field also applies it. |
| Tab | Moves through the controls; focus rings show on keyboard focus only. |

## Accessibility

- A <nav> with aria-label "Pagination" (override with aria-label, recommended when a page has more than one).
- The current page button has aria-current="page" ("true" on dots). Every button has a name: "Page 4", "Next page", "Forward 3 pages", "Slide 2 of 5", all in labels.
- Under dir="rtl" the previous/next, first/last and skip icons are mirrored so they point the way the page list reads.
- Disabled arrows on the first and last page are real disabled buttons.
- The "21–30 of 248" text and the minimal "Page 3 of 12" sit in aria-live="polite" regions, so page changes are announced.
- The rows select is a native <select> inside a <label>; the jump field is a numeric input with aria-label "Go to page".

## Motion

- slide (default): the active marker glides to the new page as a shared layout element on a spring (stiffness 520, damping 40); on dots, the wide active dot travels and the window shifts.
- press: buttons shrink to 0.9 while pressed (neo pushes into its shadow). Colors change in 150 ms.
- The "…" buttons swap to a double arrow on hover or focus, showing they skip several pages.
- Reduced motion: the marker jumps, transitions are off and there is no press effect.

## Notes for AI

- Pages are 1-based. Use page + onPageChange (controlled) or defaultPage; the page is clamped to 1…total.
- Pass totalItems (with pageSize) for tables: it computes the page count and the range info. totalPages is ignored when totalItems is set.
- Changing page size keeps the first visible row on screen, so onPageChange can fire together with onPageSizeChange; handle both.
- "…" buttons are clickable and skip max(3, siblings × 2 + 3) pages. The page list keeps a constant length, so the control does not jump in width.
- Every built-in string is in labels (previous, nextPage, goToPage, range, pageOf, rows, goTo…); functions take numbers. The nav name comes from aria-label.

## FAQ

**Can I use it with server-side paging?**

Yes. Keep page in the URL or state, fetch on onPageChange and pass totalItems from your API's count. The component never slices data itself.

**Is paginationRange exported?**

Yes. paginationRange(page, total, siblings, boundaries) returns the numbers and "start-ellipsis" / "end-ellipsis" markers, if you want the same logic in your own markup.

## Related

- table-row-presence: https://goodui.dev/components/lists/table-row-presence
- segmented-control: https://goodui.dev/components/navigation/segmented-control
- select: https://goodui.dev/components/core/select
- tabs: https://goodui.dev/components/core/tabs

Last updated: 2026-11-02

---

# Heading

> Layered heading: semantic level and size decoupled, sans/serif/mono/display font slots you map to your own fonts, eight ink treatments (gradient, muted tail, outline, marker highlight, hand-drawn squiggle, shimmer…), serif-italic emphasis via _words_, and on-view word, letter and mask reveals.

Animated heading for React and shadcn: gradient, highlight, squiggle underline and word reveal

Page: https://goodui.dev/components/core/heading

## Install

```bash
npx shadcn@latest add @goodui/heading
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/heading.json`. The file lands in `components/goodui/heading.tsx`.

## When to use

- Page and section titles where the visual size should not dictate the semantic level: an h2 that looks like a display title.
- Landing page heroes with one emphasized phrase: *marker highlight*, a hand-drawn squiggle or _serif italic_ words.
- Section titles that reveal once as they scroll into view: words, letters or mask.
- Keeping every heading on one type scale and font set: map your fonts once with CSS variables.

## When not to use

- Body copy, captions, eyebrows and quotes: use text.
- Words that cycle or type themselves: use word-rotate or typewriter.
- A short shiny label in app UI: use shiny-text; Heading is for titles.

## Pick by what matters

| Need | Use |
| --- | --- |
| App page title | as="h1" size="lg" (no treatment, no animation) |
| Landing hero | as="h1" size="display" treatment="gradient" or "highlight", animation="words" |
| Editorial or premium feel | font="serif", or keep sans and use _words_ with emphasis="serif" |
| A two-part title where the second half is quieter | treatment="muted-tail" |
| Hand-made, friendly emphasis | treatment="underline-squiggle" with *one phrase* |
| Big outline type on a dark band | treatment="outline" (marked words stay filled) |
| Section reveals while scrolling | animation="mask" (clean) or "fade-up" (subtle) |

## Usage

```tsx
import { Heading } from "@/components/goodui/heading"

export function Hero() {
  return (
    <section className="mx-auto max-w-3xl py-20 text-center">
      <Heading as="h1" size="display" align="center" treatment="highlight" animation="words">
        Fill every chair, *without the phone tag*
      </Heading>
    </section>
  )
}
```

### Serif emphasis

```tsx
<Heading as="h2" size="2xl">Bookings, payments and reminders, _finally in one place_</Heading>
```

### Muted tail

```tsx
<Heading size="xl" treatment="muted-tail">Get paid faster. Deposits and no-show fees, collected automatically.</Heading>
```

### Map your own fonts (layout.tsx)

```tsx
import { Fraunces, Inter } from "next/font/google"

const inter = Inter({ subsets: ["latin"], variable: "--font-heading-sans" })
const fraunces = Fraunces({ subsets: ["latin"], variable: "--font-heading-serif" })

<html className={`${inter.variable} ${fraunces.variable}`}>
```

## API

### Heading

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| as | `"h1" \| "h2" \| "h3" \| "h4" \| "h5" \| "h6"` | `"h2"` | Semantic level. Size is independent, so an h3 can look like a display heading. |
| size | `"display" \| "2xl" \| "xl" \| "lg" \| "md" \| "sm"` | `"xl"` | Visual scale; display, 2xl and xl scale fluidly with the viewport. |
| weight | `"auto" \| "light" \| "normal" \| "medium" \| "semibold" \| "bold" \| "black"` | `"auto"` | "auto" picks per font: sans semibold, serif medium, mono semibold, display extrabold. |
| tracking | `"tighter" \| "tight" \| "normal" \| "wide"` | `"tight"` | Letter spacing. |
| font | `"sans" \| "serif" \| "mono" \| "display"` | `"sans"` | Font slot, mapped with --font-heading-sans / -serif / -mono / -display. |
| treatment | `"plain" \| "tinted" \| "gradient" \| "muted-tail" \| "outline" \| "highlight" \| "underline-squiggle" \| "shimmer"` | `"plain"` | How the ink is painted: plain, tinted, gradient, muted-tail, outline, highlight (*marks*), underline-squiggle or shimmer. |
| emphasis | `"italic" \| "serif" \| "tone" \| "gradient"` | `"serif"` | Style of <em> / _underscored_ words. |
| tone | `"primary" \| "neutral" \| "success" \| "warning" \| "danger" \| "info"` | `"primary"` | Accent color used by every treatment and emphasis. |
| animation | `"none" \| "fade-up" \| "blur-in" \| "words" \| "letters" \| "mask"` | `"none"` | Entrance animation, played once when the heading scrolls into view. |
| align | `"start" \| "center" \| "end"` | `"start"` | Text alignment (logical, so start follows the writing direction). |
| balance | `boolean` | `true` | Balanced line breaks (text-wrap: balance). |
| markup | `boolean` | `true` | Parse *mark* and _em_ in string children. |
| children | `React.ReactNode` | — | Content. |

Also accepts every <h2> attribute.

## Accessibility

- Renders the real heading element from as (h1–h6, default h2); size only changes the look, so keep the outline in order.
- With words, letters or mask, screen readers get the whole sentence once from a visually hidden copy; the split, animated copy is aria-hidden. If children contain React elements, there is no hidden copy and the visible text is read.
- *marks* become <mark> and _words_ become <em>, so emphasis stays in the markup. The squiggle SVG is aria-hidden.
- treatment="outline" keeps marked words filled; outline-only text is harder to read, so keep it for short, large titles.

## Motion

- Entrances play once when 20% of the heading is in view: fade-up rises 0.35em in 700 ms, blur-in sharpens from a 14px blur in 900 ms.
- words: each word rises and unblurs in 650 ms, 70 ms apart. letters: each letter in 500 ms, 24 ms apart. mask: words slide up from behind a clip in 800 ms, 65 ms apart.
- With an entrance, the highlight marker sweeps in (700 ms) and the squiggle draws (800 ms) after the text has arrived.
- shimmer: a light passes across the text every 3.4 s, continuously.
- Reduced motion: no entrances, no shimmer; the text, marker and squiggle are shown in their final state.

## Performance

- One IntersectionObserver per animated heading, disconnected after it plays. Split animations with gradient, shimmer or gradient emphasis measure word positions once and on resize (ResizeObserver) so the gradient stays continuous.

## Notes for AI

- Set as for semantics and size for looks; do not pick a level to get a size. Default is as="h2" size="xl".
- Inline markup only works in string children: *phrase* → highlighted mark, _phrase_ → emphasis. Pass markup={false} for titles that contain literal * or _.
- highlight and underline-squiggle mark the last word automatically when the text has no *mark*; muted-tail mutes the second sentence or the last ~40% of the words.
- Do not add bg-clip-text or gradient classes yourself; use treatment and tone. Fonts come from --font-heading-sans, -serif, -mono and -display.
- Headings with an entrance start invisible until they scroll into view, so avoid animation on titles above the fold in app UI. There is no built-in text, so no labels prop.

## FAQ

**Can I use my own fonts?**

Yes. Set --font-heading-sans, --font-heading-serif, --font-heading-mono and --font-heading-display on :root or <html> (next/font's variable option does this). Without them, sans, serif and mono fall back to --font-sans, --font-serif and --font-mono when set, then to system stacks.

**How do I use the outline treatment on a card?**

The fill uses --pc-surface, falling back to the page background. On a card, set className="[--pc-surface:var(--card)]".

## Related

- text: https://goodui.dev/components/core/text
- highlighter: https://goodui.dev/components/text/highlighter
- gradient-text: https://goodui.dev/components/text/gradient-text
- text-reveal: https://goodui.dev/components/text/text-reveal

Last updated: 2026-11-02

---

# Text

> Every body-copy role in one primitive: paragraph, lead, small, caption, overline, eyebrow pill, quote with attribution and inline code, with tones, readable measures, truncate or line clamp, and on-view entrances.

Text and typography component for React and shadcn: lead, caption, eyebrow, quote and line clamp

Page: https://goodui.dev/components/core/text

## Install

```bash
npx shadcn@latest add @goodui/text
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/text.json`. The file lands in `components/goodui/text.tsx`.

## When to use

- Every piece of body copy, so paragraphs, leads, captions and small print share one scale and one set of colors.
- The small labels around a title: an overline ("PRICING") or an eyebrow pill ("New · SMS reminders").
- Testimonials and pull quotes with attribution: variant="quote".
- Previews that must stay short: truncate for one line, lineClamp for a few.

## When not to use

- Titles and section headings: use heading.
- A status or count chip: use badge; an eyebrow is a label, not a status.
- Code blocks with several lines: use a <pre> with your highlighter; variant="code" is for inline snippets.

## Pick by what matters

| Need | Use |
| --- | --- |
| Body copy | variant="paragraph" (default) with measure="normal" for readable lines |
| Intro under a hero heading | variant="lead" |
| Helper text, timestamps, footnotes | variant="caption" or "small" |
| Label above a section title | variant="overline" or "eyebrow" (pill with a dot) |
| Testimonial | variant="quote" with attribution |
| Inline code, keys, IDs | variant="code" (renders <code>) |
| Card previews and table cells | truncate or lineClamp={2} |
| Colored meaning (error, success text) | tone="danger" \| "success" \| "warning" \| "info" |

## Usage

```tsx
import { Heading } from "@/components/goodui/heading"
import { Text } from "@/components/goodui/text"

export function PricingIntro() {
  return (
    <header className="flex flex-col items-center gap-4 text-center">
      <Text variant="eyebrow" tone="success">
        New · Two-way SMS reminders
      </Text>
      <Heading as="h2" size="2xl" align="center">
        Simple pricing for busy studios
      </Heading>
      <Text variant="lead" measure="narrow" align="center" animation="fade-up">
        One plan per location. Unlimited bookings, deposits and <mark>no per-seat fees</mark>.
      </Text>
    </header>
  )
}
```

### Testimonial

```tsx
<Text variant="quote" tone="primary" attribution="Maya Chen, owner of Glow Studio">
  No-shows dropped by half in the first month. The deposit step paid for itself.
</Text>
```

### Clamped note in a card

```tsx
<Text variant="small" tone="muted" lineClamp={2}>
  Client prefers Maya, sensitive scalp, patch test 48 hours before any color service. Parking at the back entrance.
</Text>
```

### Inline code and error text

```tsx
<Text variant="small">
  Your API key starts with <code>pk_live_</code>.
</Text>
<Text variant="caption" tone="danger" role="alert">
  The webhook URL must start with https://
</Text>
```

## API

### Text

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| variant | `"paragraph" \| "lead" \| "small" \| "caption" \| "overline" \| "eyebrow" \| "quote" \| "code"` | `"paragraph"` | Text role; sets the default element, size, weight, font and color. |
| as | `"p" \| "span" \| "div" \| "blockquote" \| "figcaption" \| "label" \| "code" \| "small" \| "li" \| "strong" \| "em"` | — | Element to render. Defaults per variant (p, blockquote for quote, code for code). |
| tone | `"auto" \| "default" \| "muted" \| "primary" \| "neutral" \| "success" \| "warning" \| "danger" \| "info"` | `"auto"` | Color: auto keeps the variant's color; default and muted use theme text colors; the rest are accent tones (also color <mark>). |
| size | `"auto" \| "xs" \| "sm" \| "base" \| "lg" \| "xl" \| "2xl"` | `"auto"` | Font size; auto uses the variant's. |
| weight | `"auto" \| "normal" \| "medium" \| "semibold" \| "bold"` | `"auto"` | Font weight; auto uses the variant's. |
| font | `"auto" \| "sans" \| "serif" \| "mono"` | `"auto"` | Font family; serif and mono use --font-serif and --font-mono. auto uses the variant's. |
| measure | `"none" \| "narrow" \| "normal" \| "wide"` | `"none"` | Max line length: narrow 45ch, normal 65ch, wide 80ch. |
| align | `"start" \| "center" \| "end" \| "justify"` | `"start"` | Text alignment (start and end follow the writing direction). |
| truncate | `boolean` | — | Single line with an ellipsis. |
| lineClamp | `number \| "none" \| "1" \| "2" \| "3" \| "4" \| "5" \| "6"` | `"none"` | Clamp to N lines with an ellipsis. |
| animation | `"none" \| "fade-in" \| "fade-up" \| "blur-in" \| "reveal"` | `"none"` | Entrance animation, played once when the text scrolls into view. |
| attribution | `React.ReactNode` | — | Quote variant: who said it. |
| ref | `React.Ref<HTMLElement>` | — |  |

Also accepts every <element> attribute.

## Accessibility

- Renders a semantic element per variant: <p> by default, <blockquote> for quote with a <cite> for attribution, <code> for code. Override with as (span, div, label, li, figcaption…).
- <mark> inside the text gets a tone-colored marker but stays a real <mark>.
- truncate and lineClamp only hide overflow visually; the full text is still in the DOM, so add a title or a way to read the rest when it matters.
- Tones only change color; for errors also add context (an icon or role="alert" where it should be announced).

## Motion

- Entrances play once when 20% of the text is in view: fade-in (700 ms), fade-up rises 10px (700 ms), blur-in from an 8px blur (800 ms), reveal wipes in from the start edge (left, or right under dir="rtl") (900 ms).
- Reduced motion: no entrance; the text is visible immediately.

## Notes for AI

- Pick the role with variant and leave size, weight and font on "auto"; they follow the variant. Override only when the design needs it.
- tone="auto" keeps the variant's natural color (lead, caption and overline are muted). Use tone="muted" or an accent tone instead of text-muted-foreground or text-red-500 classes.
- attribution only renders with variant="quote"; it is added inside the blockquote with an em dash.
- lineClamp takes a number (or "1"…"6"); truncate wins when both are set. measure caps the width at 45, 65 or 80ch.
- Animated text starts invisible until it scrolls into view, so avoid animation on text above the fold in app UI. There is no built-in text, so no labels prop.

## FAQ

**Can I use my serif and mono fonts?**

Yes. The quote variant and font="serif" use --font-serif, code and font="mono" use --font-mono, with system fallbacks.

**Does it replace shadcn's typography classes?**

It covers the same roles (p, lead, small, muted, blockquote, inline code) as one component with props, plus caption, overline, eyebrow, clamping and entrances.

## Related

- heading: https://goodui.dev/components/core/heading
- badge: https://goodui.dev/components/core/badge
- link: https://goodui.dev/components/core/link
- kbd: https://goodui.dev/components/core/kbd

Last updated: 2026-11-02

---

# Link

> Inline link with seven underline styles (static, slide-in, grow from center, marker sweep, nudging arrow), line decorations, tones, leading icons and automatic external-link handling. Works with next/link via as.

Animated link for React and shadcn: sliding underline, marker highlight, arrow and next/link support

Page: https://goodui.dev/components/core/link

## Install

```bash
npx shadcn@latest add @goodui/link
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/link.json`. The file lands in `components/goodui/link.tsx`.

## When to use

- Inline links in body copy, help text and footers that should match the theme instead of the browser default.
- "Learn more", "View all bookings" and other call-to-action text links: underline="arrow".
- Links to other sites: http(s) URLs open in a new tab with a ↗ icon and screen-reader text automatically.
- Navigation links in a header or footer with a hover effect: slide or grow-center.

## When not to use

- Actions that do not navigate (save, delete, open a dialog): use button, or button with variant="link" for the look.
- A trail of parent pages: use breadcrumb.
- A copy-to-clipboard value: use copy-button.

## Pick by what matters

| Need | Use |
| --- | --- |
| Links inside paragraphs | underline="always" (readable without hover) with tone="inherit" or "primary" |
| Quiet links in footers and meta text | tone="muted" underline="hover" |
| Header navigation | underline="slide" or "grow-center", tone="neutral" |
| "Learn more" call to action | underline="arrow" |
| Playful marketing copy | underline="highlight" (marker fills the text on hover) |
| Glossary terms and definitions | underline="always" decoration="dotted" |

## Usage

```tsx
import NextLink from "next/link"
import { Link } from "@/components/goodui/link"
import { Text } from "@/components/goodui/text"

export function DepositNote() {
  return (
    <div className="flex flex-col gap-2">
      <Text variant="small" tone="muted">
        Deposits are refunded automatically when a client cancels more than 24 hours ahead. Read the{" "}
        <Link as={NextLink} href="/help/deposits" underline="always" tone="inherit">
          deposit policy
        </Link>{" "}
        or check{" "}
        <Link href="https://stripe.com/docs/refunds" underline="always" tone="inherit">
          Stripe's refund guide
        </Link>
        .
      </Text>
      <Link as={NextLink} href="/settings/payments" underline="arrow" size="sm">
        Set up deposits
      </Link>
    </div>
  )
}
```

### Header navigation

```tsx
<nav className="flex gap-6 text-sm">
  <Link as={NextLink} href="/features" tone="neutral" underline="slide">Features</Link>
  <Link as={NextLink} href="/pricing" tone="neutral" underline="slide">Pricing</Link>
  <Link as={NextLink} href="/changelog" tone="neutral" underline="slide">Changelog</Link>
</nav>
```

### With a leading icon

```tsx
<Link href="mailto:support@glowstudio.com" iconLeft={<Mail />} tone="muted">
  support@glowstudio.com
</Link>
```

## API

### Link

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| underline | `"none" \| "always" \| "hover" \| "slide" \| "grow-center" \| "highlight" \| "arrow"` | `"hover"` | none, always, hover (static) or an animated effect: slide, grow-center, highlight (marker fill), arrow. |
| decoration | `"solid" \| "dotted" \| "dashed" \| "wavy"` | `"solid"` | Line style for underline="always" and "hover". |
| tone | `"inherit" \| "muted" \| "primary" \| "neutral" \| "success" \| "warning" \| "danger" \| "info"` | `"primary"` | Link color; inherit follows the surrounding text, muted brightens on hover. |
| weight | `"inherit" \| "normal" \| "medium" \| "semibold" \| "bold"` | `"medium"` | Font weight; inherit keeps the parent's. |
| size | `"inherit" \| "xs" \| "sm" \| "base" \| "lg"` | `"inherit"` | Font size; inherit keeps the parent's. |
| external | `boolean` | — | Opens in a new tab with an icon. Defaults to true for absolute http(s) URLs. |
| externalIcon | `boolean` | `true` | Show the ↗ icon on external links. |
| iconLeft | `React.ReactNode` | — | Icon before the text, sized to 1em. |
| as | `React.ElementType` | — | Render another element, e.g. next/link. It receives href, className and the rest. |
| labels | `Partial<LinkLabels>` | — | Text for built-in controls and screen readers; pass translations here. |

Also accepts every <a> attribute.

## Keyboard

| Keys | Action |
| --- | --- |
| Enter | Follows the link (native <a>, or your router's link through as). |
| Tab | Moves focus; a tone-colored outline shows on keyboard focus, and slide, grow-center, highlight and arrow play their hover effect on focus too. |

## Accessibility

- Renders a real <a> (or the element passed in as), so middle-click, open in new tab and prefetching keep working.
- External links get target="_blank", rel="noopener noreferrer" and a visually hidden " (opens in a new tab)". Translate it with labels={{ newTab: "…" }}.
- The arrow, ↗ icon and iconLeft are aria-hidden; the link text carries the meaning.
- underline="always" is the safest choice inside paragraphs, because the link does not rely on color alone.

## Motion

- slide: an underline grows from the start edge (left, or right under dir="rtl") in 380 ms on hover or focus and retracts toward the end. grow-center grows from the middle.
- highlight: a thin marker under the text fills the whole line height in 300 ms.
- arrow: the arrow nudges forward by 0.22em in 250 ms. External icons move up and outward on hover. Under dir="rtl" the arrow and ↗ icon are mirrored and move the other way.
- Reduced motion: no transitions; hover states switch instantly.

## Notes for AI

- For Next.js pass as={NextLink} (import NextLink from "next/link"); do not wrap Link in another <a> or <Link>. TextLink is the same component, exported for files that already import next/link as Link.
- Default is underline="hover" tone="primary" weight="medium". Use tone="inherit" to take the color of the surrounding text.
- external is detected from absolute http(s) or protocol-relative hrefs; pass external={false} for your own domain or externalIcon={false} to hide only the icon. target and rel you pass win.
- underline="arrow" replaces the external icon. Pass leading icons through iconLeft, not children, so they stay aligned.
- decoration (solid, dotted, dashed, wavy) only affects underline="always" and "hover".
- labels={{ newTab }} translates the screen-reader note on external links (default "(opens in a new tab)").

## FAQ

**Why does my link open in a new tab?**

Its href starts with http://, https:// or //, so it is treated as external. Pass external={false} for links to your own site with full URLs.

**Does the arrow wrap onto its own line?**

No. With string children, the last word and the arrow (or ↗ icon) are kept together with white-space: nowrap.

## Related

- button: https://goodui.dev/components/core/button
- breadcrumb: https://goodui.dev/components/core/breadcrumb
- text: https://goodui.dev/components/core/text
- highlighter: https://goodui.dev/components/text/highlighter

Last updated: 2026-11-02

---

# Kbd

> Keyboard keys and combos in flat, raised 3D, outline, glass, neo and solid styles. Keycaps depress when the real keys are pressed, Mod maps to ⌘ or Ctrl, and onTrigger turns any combo or G-then-T sequence into a working hotkey.

Keyboard shortcut (kbd) component for React and shadcn: ⌘/Ctrl aware keycaps and working hotkeys

Page: https://goodui.dev/components/core/kbd

## Install

```bash
npx shadcn@latest add @goodui/kbd
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/kbd.json`. The file lands in `components/goodui/kbd.tsx`.

## When to use

- Showing a shortcut next to a menu item, button or search box: ⌘K, Ctrl+S, Esc.
- Shortcut cheat sheets and onboarding tips, with keycaps that press down when the real keys do.
- Wiring the shortcut you display at the same time: onTrigger turns the same combo into a working hotkey, including G-then-T sequences.

## When not to use

- A full command menu: use command-palette-morph and show its shortcut with Kbd.
- Inline code or identifiers (API keys, file names): use text with variant="code".
- Status or count labels: use badge.

## Pick by what matters

| Need | Use |
| --- | --- |
| Hints inside menus and inputs | variant="flat" or "outline", size="xs", animation="none" |
| Docs and cheat sheets | variant="raised" (default) with animation="press" |
| Branded or highlighted shortcut | variant="solid" with a tone, or animation="glow" |
| On images or gradients | variant="glass" |
| Playful or retro brands | variant="neo" |
| Two-key sequences like G then D | separator="then" with onTrigger |
| Words instead of symbols (Shift, Enter, Cmd) | symbols={false} |

## Usage

```tsx
import { useRouter } from "next/navigation"
import { Search } from "lucide-react"
import { Kbd } from "@/components/goodui/kbd"

export function SearchTrigger({ onOpen }: { onOpen: () => void }) {
  const router = useRouter()

  return (
    <div className="flex items-center gap-4">
      <button type="button" onClick={onOpen} className="flex w-64 items-center gap-2 rounded-lg border px-3 py-2 text-sm text-muted-foreground">
        <Search className="size-4" />
        Search clients and bookings
        <Kbd keys="Mod+K" size="xs" variant="flat" className="ms-auto" onTrigger={onOpen} />
      </button>
      <span className="flex items-center gap-2 text-xs text-muted-foreground">
        Go to calendar <Kbd keys={["G", "C"]} separator="then" onTrigger={() => router.push("/calendar")} />
      </span>
    </div>
  )
}
```

### Cheat sheet row

```tsx
<div className="flex items-center justify-between text-sm">
  <span>New booking</span>
  <Kbd keys="Mod+Shift+B" size="md" />
</div>
```

### Single key

```tsx
<Kbd variant="outline" size="xs" animation="none">Esc</Kbd>
```

### Translated screen-reader names

```tsx
<Kbd
  keys={["G", "T"]}
  separator="then"
  labels={{ then: "dann", keyName: (name) => (name === "Command" ? "Befehl" : name === "Control" ? "Steuerung" : name) }}
/>
```

## API

### Kbd

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| keys | `string[] \| string` | — | Keys of the combo: ["Mod", "Shift", "P"] or "Mod+Shift+P". |
| children | `React.ReactNode` | — | Single key content, used when `keys` is not set. |
| variant | `"flat" \| "raised" \| "outline" \| "glass" \| "neo" \| "solid"` | `"raised"` | Keycap style: flat, raised 3D (default), outline, glass, neo or solid. |
| tone | `"primary" \| "neutral" \| "success" \| "warning" \| "danger" \| "info"` | `"neutral"` | Keycap accent color; neutral (default) keeps it gray. |
| size | `"xs" \| "sm" \| "md" \| "lg"` | `"sm"` |  |
| shape | `"square" \| "rounded" \| "pill"` | `"rounded"` |  |
| separator | `"plus" \| "none" \| "then"` | `"plus"` | Between keys: plus (a combo), none, or then (a sequence; onTrigger then waits for the keys in order). |
| font | `"sans" \| "mono"` | `"sans"` | Keycap font; mono uses --font-mono. |
| symbols | `boolean` | `true` | Show ⌘ ⇧ ⌥ ↵ ⌫ arrows instead of words. |
| animation | `"none" \| "press" \| "glow"` | `"press"` | press depresses a keycap while its real key is held; glow adds a tone glow. none adds no key listeners. |
| onTrigger | `(e: KeyboardEvent) => void` | — | Fires when every key of the combo is down (or, with separator="then", when the sequence is typed). |
| preventDefault | `boolean` | `true` | Prevent the browser default when onTrigger fires (e.g. Ctrl+K focusing the address bar). |
| allowInInputs | `boolean` | `false` | Fire in text fields too. By default combos without Mod/Ctrl/Cmd/Alt are ignored while typing. |
| labels | `Partial<KbdLabels>` | — | Text for built-in controls and screen readers; pass translations here. |

Also accepts every <kbd> attribute.

## Keyboard

| Keys | Action |
| --- | --- |
| The keys you pass | With animation="press" or "glow" (or onTrigger), each keycap reacts while its real key is held. Listeners are on window, so focus can be anywhere. |
| The full combo (e.g. Mod+K) | Calls onTrigger once when every key is down (not on auto-repeat) and prevents the browser default unless preventDefault={false}. |
| Sequences (separator="then") | Calls onTrigger when the keys are typed in order with less than 1.2 s between them; modifier presses are ignored. |

## Accessibility

- Renders a <kbd> wrapping one <kbd> per key, the HTML pattern for key combinations.
- Symbols (⌘ ⇧ ⌥ ↵ ↑…) are aria-hidden and paired with visually hidden names ("Command", "Shift", "Up arrow"). Translate them with labels.keyName; labels.then translates the visible "then".
- The + and "then" separators are aria-hidden.
- Single-key and Shift-only hotkeys are ignored while typing in inputs, textareas, selects and contenteditable, so they do not steal text input. Combos with Mod, Ctrl, Cmd or Alt still fire; allowInInputs makes all of them fire.

## Motion

- press (default): a keycap depresses for as long as its key is held, in 90 ms. raised and solid move down 2px and lose their bottom edge, neo slides into its shadow, flat, outline and glass shrink to 0.92 and tint.
- glow: the held keycap also gets a tone-colored ring and glow.
- Reduced motion: keycaps do not move; only the background color changes while a key is held.

## Performance

- Every Kbd with animation other than "none", or with onTrigger, adds keydown, keyup and blur listeners on window. In long static lists (menus with 20 shortcuts), use animation="none" and keep onTrigger to the ones you need.

## Notes for AI

- Write "Mod" for the platform modifier: it shows ⌘ on Mac and Ctrl elsewhere and matches Meta or Control. keys accepts "Mod+Shift+P" or ["Mod", "Shift", "P"]; "Ctrl++" means the plus key.
- Use children only for a single key without keys. Do not render your own + between Kbd elements; pass all keys to one Kbd.
- onTrigger replaces a separate hotkey hook for that shortcut; do not register the same combo twice. Set preventDefault={false} if the browser action should still happen.
- The platform is detected after mount, so the first server render shows Ctrl; that is expected.
- Default is variant="raised" tone="neutral" size="sm" symbols animation="press".

## FAQ

**Can it replace a hotkeys library?**

For shortcuts that are also shown on screen, yes: onTrigger handles combos, Mac/Windows modifiers, auto-repeat, inputs and G-then-T sequences. It only listens while the Kbd is mounted.

**Does it work on Mac and Windows?**

Yes. Mod shows ⌘ on Mac (detected from the platform after mount) and Ctrl elsewhere, and Alt shows ⌥ on Mac. Releasing any modifier or leaving the window releases every keycap, so none get stuck after ⌘+Tab.

## Related

- command-palette-morph: https://goodui.dev/components/navigation/command-palette-morph
- text: https://goodui.dev/components/core/text
- badge: https://goodui.dev/components/core/badge
- button: https://goodui.dev/components/core/button

Last updated: 2026-11-02

---

# Stat Card

> KPI card with seven variants, tones, shadows and sizes: count-up or rolling NumberFlow values, auto-toned delta badges (invertible for no-show rates), line, area or bar sparklines that draw in, icons, footers and a skeleton state.

KPI stat card for React and shadcn: count-up value, delta badge and sparkline

Page: https://goodui.dev/components/core/stat-card

## Install

```bash
npx shadcn@latest add @goodui/stat-card
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/stat-card.json`. The file lands in `components/goodui/stat-card.tsx`.

## When to use

- The row of headline numbers at the top of a dashboard: revenue, bookings, new clients, no-show rate.
- A metric with its change since last period and a small trend line, without pulling in a chart library.
- Metrics that load asynchronously: loading shows a matching skeleton.
- Live numbers that update in place: numberFlow rolls the digits on every change.

## When not to use

- A full chart with axes, tooltips and several series: use a chart component.
- Just an animated number in a sentence or table cell: use number-flow or counter-up.
- A trend chip on its own: use delta-badge. A tiny trend line on its own: use sparkline-draw.

## Pick by what matters

| Need | Use |
| --- | --- |
| Default dashboard row | variant="outline" (default) with data and chart="area" |
| One hero metric that stands out | variant="gradient" or shadow="glow" |
| Calm, tinted cards grouped by category | variant="soft" with a tone per group |
| Icon-led cards in a sidebar or narrow column | variant="split" with icon, size="sm" |
| Daily counts (bookings per day) | chart="bars" |
| Lower is better (no-shows, churn, wait time) | invertDelta |
| Real-time values | numberFlow (digits roll on each change), animation="draw" |
| Static reports or print | animation="none" |

## Usage

```tsx
import { CalendarCheck, DollarSign, UserX } from "lucide-react"
import { StatCard } from "@/components/goodui/stat-card"

export function DashboardStats() {
  return (
    <div className="grid gap-4 sm:grid-cols-3">
      <StatCard
        label="Revenue"
        value={48210}
        format={{ style: "currency", currency: "USD", maximumFractionDigits: 0 }}
        delta={12.4}
        deltaLabel="vs last month"
        data={[31, 34, 33, 38, 41, 39, 45, 48]}
        icon={<DollarSign />}
      />
      <StatCard label="Bookings" value={1284} delta={4.1} data={[38, 42, 40, 51, 47, 55, 61]} chart="bars" icon={<CalendarCheck />} tone="info" />
      <StatCard label="No-show rate" value={3.2} suffix="%" delta={-0.8} invertDelta deltaSuffix=" pts" icon={<UserX />} tone="warning" footer="Deposits enabled since Oct 4" />
    </div>
  )
}
```

### Loading state

```tsx
<StatCard label="Revenue" value={data?.revenue ?? 0} loading={isLoading} data={data?.trend} />
```

### Compact numbers with rolling digits

```tsx
<StatCard label="Page views" value={views} compact numberFlow variant="soft" tone="success" />
```

### Clickable card

```tsx
<a href="/reports/revenue" className="block rounded-xl outline-none focus-visible:ring-3 focus-visible:ring-ring/50">
  <StatCard label="Revenue" value={48210} prefix="$" interactive />
</a>
```

## API

### StatCard

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| label (required) | `React.ReactNode` | — | Metric name shown above the value. |
| value (required) | `number \| string` | — | A number (animated and formatted) or any preformatted string. Numeric strings like "1,284" count too. |
| prefix | `string` | `""` | Text before the formatted number, e.g. "$". |
| suffix | `string` | `""` | Text after the formatted number, e.g. "%" or " ms". |
| format | `Intl.NumberFormatOptions` | — | Intl.NumberFormat options, e.g. { style: "currency", currency: "USD" }. |
| compact | `boolean` | — | Short notation: 12.4K, 1.2M. |
| locale | `string` | — | Locale for number formatting. Defaults to the GooduiLocaleProvider language, else en-US. |
| delta | `number \| string` | — | Change in percent, e.g. 12.5 or -3. |
| deltaLabel | `React.ReactNode` | — | Muted text beside the value, e.g. "vs last month". |
| deltaSuffix | `string` | `"%"` | Unit after the delta number; "%" by default. |
| invertDelta | `boolean` | — | A drop is good news (cancellations, no-shows, wait time). |
| data | `number[] \| string` | — | Sparkline points: [12, 18, 15] or "12,18,15". |
| chart | `"line" \| "area" \| "bars"` | `"area"` | Sparkline style for data: line, area (default) or bars. |
| icon | `React.ReactNode` | — | Icon in a tinted tile beside the label, or in the side block with variant="split". |
| footer | `React.ReactNode` | — | Muted line at the bottom of the card. |
| variant | `"plain" \| "outline" \| "soft" \| "gradient" \| "glass" \| "neo" \| "split"` | `"outline"` | Surface: plain, outline (default), soft, gradient, glass, neo, or split (icon block on the start side). |
| tone | `"primary" \| "neutral" \| "success" \| "warning" \| "danger" \| "info"` | `"primary"` | Accent for the icon, sparkline, soft and gradient surfaces and glow. Delta colors are separate (good/bad). |
| shadow | `"none" \| "sm" \| "md" \| "lg" \| "glow"` | `"none"` | Drop shadow; glow uses the tone. Ignored by neo. |
| shape | `"square" \| "rounded" \| "round"` | `"rounded"` | Corner radius: square, rounded or round. |
| size | `"sm" \| "md" \| "lg"` | `"md"` |  |
| animation | `"none" \| "count" \| "draw" \| "full"` | `"full"` | count counts the value up on view, draw draws the sparkline in, full does both. |
| numberFlow | `boolean` | — | Roll digits with NumberFlow. |
| loading | `boolean` | — | Skeleton state while the metric loads. |
| interactive | `boolean` | — | Hover lift, for cards that link somewhere. |
| labels | `Partial<StatCardLabels>` | — | Text for built-in controls and screen readers; pass translations here. |

Also accepts every <div> attribute.

## Accessibility

- The counting number is aria-hidden; screen readers read the final formatted value from a visually hidden copy, once. With numberFlow, NumberFlow handles its own screen-reader text.
- The delta adds visually hidden "increase", "decrease" or "no change" after the number, so the trend does not rely on the arrow or color. Translate with labels.
- The sparkline and its end dot are aria-hidden; describe the trend in deltaLabel or footer if it matters.
- loading sets aria-busy on the card.
- interactive only adds a hover lift; the card is a <div>, so wrap it in a link or button for keyboard access.

## Motion

- count: when 30% of the card is in view, the value counts up from 0 over 1.2 s with an ease-out curve; later value changes tween from the current number.
- draw: the line draws in over 1.1 s, the area fades in, then the end dot pops in at 1.1 s; bars grow from the bottom, 40 ms apart. full (default) does count and draw together.
- numberFlow: digits roll to the new value on every change instead of tweening.
- interactive: the card lifts 2px in 200 ms on hover (neo cards grow their offset shadow). The loading skeleton shimmers every 1.4 s.
- Reduced motion: the value shows the final number at once, the chart is drawn, the skeleton is static and the hover lift does not animate.

## Performance

- One IntersectionObserver per card, disconnected after the first reveal. The count-up uses requestAnimationFrame for 1.2 s; the sparkline is measured with a ResizeObserver and redrawn only when its size changes.

## Notes for AI

- value can be a number or a string. Numeric strings like "1,284" animate; other strings ("2h 15m", "N/A") are shown as they are.
- Use format (Intl.NumberFormat options) for currency and percent, or prefix and suffix for simple units. Do not pre-format numbers you want animated.
- delta is a change in percent by default; set deltaSuffix for other units (" pts", ""). Trend color is automatic: up is good unless invertDelta.
- data needs at least 2 points to draw a sparkline; it accepts [12, 18, 15] or "12,18,15".
- Default is variant="outline" tone="primary" chart="area" animation="full" locale="en-US"; pass locale for other number formats. labels translates the delta's screen-reader words.

## FAQ

**How do I show currency?**

Pass format={{ style: "currency", currency: "EUR" }} and optionally locale="de-DE". The count-up formats every frame with the same formatter.

**Why is my sparkline missing?**

It only renders with 2 or more finite points in data. With loading set it shows a skeleton in its place.

## Related

- number-flow: https://goodui.dev/components/numbers/number-flow
- delta-badge: https://goodui.dev/components/numbers/delta-badge
- sparkline-draw: https://goodui.dev/components/numbers/sparkline-draw
- card: https://goodui.dev/components/core/card

Last updated: 2026-11-02

---

# Select

> Fully custom single or multi select: outline, filled, ghost, underline, pill and neo triggers; icons, avatars, descriptions and groups; search with match highlight, chips, clear, type-ahead and full keyboard; animated menu that flips up when space runs out.

Custom select and multi-select for React and shadcn: search, chips, groups, avatars and full keyboard

Page: https://goodui.dev/components/core/select

## Install

```bash
npx shadcn@latest add @goodui/select
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/select.json`. The file lands in `components/goodui/select.tsx`.

## When to use

- Picking one option from a list that is too long for radio buttons: a service, a staff member, a location.
- Picking several options shown as chips: add-on services, tags, team members (multiple).
- Long lists that need search, with matches highlighted: searchable, matching labels, descriptions, groups and keywords.
- Options that need more than text: avatars for people, icons for services, a description line, grouped sections.

## When not to use

- Two to five options that fit on screen: use checkbox (RadioGroup) or segmented-control, so all choices are visible.
- Free-form tags the user types: use tag-input.
- Actions in a menu (Edit, Duplicate, Delete): use dropdown-stagger; a select holds a value.

## Pick by what matters

| Need | Use |
| --- | --- |
| Forms | variant="outline" (default) |
| Filters in a toolbar | variant="ghost" or "pill", size="sm" |
| Dense settings or tables | variant="filled" or "underline" |
| Choose people | options with avatar (URL, or true for initials) and description |
| More than ~10 options | searchable, with group on the options |
| Several values | multiple with maxChips; clearable to reset |
| Calm menu | animation="fade-scale" (default) or "none"; "stagger" for short showcase lists |
| Playful or retro brands | variant="neo" |

## Usage

```tsx
import * as React from "react"
import { Scissors } from "lucide-react"
import { Select, type SelectOption } from "@/components/goodui/select"

const stylists: SelectOption[] = [
  { value: "maya", label: "Maya Chen", description: "Color specialist", avatar: "/team/maya.jpg", group: "Downtown" },
  { value: "leo", label: "Leo Park", description: "Barber", avatar: true, group: "Downtown" },
  { value: "ana", label: "Ana Ruiz", description: "Senior stylist", avatar: true, group: "Riverside" },
  { value: "sam", label: "Sam Okafor", description: "On leave until Dec 1", avatar: true, group: "Riverside", disabled: true },
]

export function BookingForm() {
  const [stylist, setStylist] = React.useState<string | null>("maya")
  const [extras, setExtras] = React.useState<string[]>([])

  return (
    <form className="flex flex-col gap-4">
      <Select aria-label="Stylist" options={stylists} value={stylist} onValueChange={setStylist} searchable clearable name="stylist" />
      <Select
        aria-label="Add-on services"
        multiple
        icon={<Scissors />}
        placeholder="Add services"
        options="Deep conditioning, Scalp massage, Blow-dry, Toner, Brow tint"
        value={extras}
        onValueChange={setExtras}
        name="extras"
      />
    </form>
  )
}
```

### Toolbar filter

```tsx
<Select aria-label="Location" variant="pill" size="sm" className="w-44" options={["All locations", "Downtown", "Riverside"]} defaultValue="All locations" />
```

### Translated

```tsx
<Select
  aria-label="Mitarbeiter"
  options={staff}
  multiple
  clearable
  searchable
  placeholder="Auswählen…"
  searchPlaceholder="Suchen…"
  emptyText="Keine Treffer"
  labels={{ clear: "Auswahl löschen", selectedHint: (s) => `${s} ausgewählt. Rücktaste entfernt den letzten.` }}
/>
```

## API

### Select

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| id | `string` | — | Goes on the combobox trigger, so <label htmlFor> works. |
| aria-label | `string` | — | Defines a string value that labels the current element. Names the trigger and the listbox. Pass one unless a visible <label htmlFor={id}> points at the select. |
| options | `(SelectOption \| string)[] \| string` | — | Option objects, plain strings, or one comma-separated string: "Haircut, Beard trim". |
| placeholder | `string` | — | Trigger text when nothing is selected. |
| variant | `"outline" \| "filled" \| "ghost" \| "underline" \| "pill" \| "neo"` | — | Trigger style: outline (default), filled, ghost, underline, pill or neo. |
| tone | `"primary" \| "neutral" \| "success" \| "warning" \| "danger" \| "info"` | — | Accent for focus ring, selected option, checkboxes and chips. |
| size | `"sm" \| "md" \| "lg"` | — |  |
| shadow | `"none" \| "sm" \| "md" \| "lg"` | — | Trigger shadow. Ignored by neo. |
| animation | `"none" \| "fade-scale" \| "slide" \| "stagger"` | — | How the menu opens: fade-scale (default), slide (unrolls), stagger (options one by one) or none. |
| searchable | `boolean` | — | Search box at the top of the menu. |
| searchPlaceholder | `string` | — | Placeholder and accessible name of the search box. |
| clearable | `boolean` | — | × button that resets the value. |
| disabled | `boolean` | — |  |
| invalid | `boolean` | — | Red border and aria-invalid on the trigger. |
| icon | `React.ReactNode` | — | Leading icon in the trigger. |
| name | `string` | — | Form field name (renders hidden inputs). |
| emptyText | `string` | — | Shown when the search has no matches. |
| maxChips | `number` | — | Multiple: chips shown before "+N". |
| open | `boolean` | — | Menu open state (controlled). |
| defaultOpen | `boolean` | — | Initial open state when uncontrolled. |
| onOpenChange | `(open: boolean) => void` | — | Called when the menu opens or closes. |
| menuClassName | `string` | — | Class for the dropdown menu. |
| labels | `Partial<SelectLabels>` | — | Text for built-in controls and screen readers; pass translations here. |
| multiple | `false` | — | true picks several values, shown as chips; value then becomes string[]. |
| value | `string \| null` | — | Selected value (controlled): a string or null, or string[] with multiple. |
| defaultValue | `string \| null` | — | Initial value when uncontrolled (string[] with multiple). |
| onValueChange | `(value: string \| null) => void` | — | Called with the picked value (null after clearing), or with the full string[] with multiple. |

Also accepts every <div> attribute.

## Keyboard

| Keys | Action |
| --- | --- |
| Arrow Down / Arrow Up / Enter / Space | On the closed trigger, opens the menu with the selected (or first enabled) option active. |
| Arrow Down / Arrow Up | Moves the active option, wrapping and skipping disabled ones. |
| Home / End | Jumps to the first or last enabled option (not while typing in the search box). |
| Enter | Picks the active option. Single select closes; multiple toggles and stays open. |
| Space | Same as Enter, except inside the search box where it types a space. |
| Letters | Type-ahead: jumps to the next option starting with the typed text (opens the menu if closed). With searchable, typing on the closed trigger opens the menu and starts the search. |
| Backspace | With multiple and the menu closed, removes the last selected value. |
| Escape | Closes the menu and returns focus to the trigger. |
| Tab | Closes the menu and moves focus on. |

## Accessibility

- The trigger is a <button role="combobox"> with aria-haspopup="listbox", aria-expanded, aria-controls and aria-activedescendant; with searchable, the search input takes the combobox role and the active descendant.
- The menu is role="listbox" (aria-multiselectable with multiple), options are role="option" with aria-selected and aria-disabled, and groups are role="group" named after the group.
- There is no built-in visible label: pass aria-label, which names both the trigger and the listbox.
- With multiple, a visually hidden text lists the selected values and mentions Backspace (labels.selectedHint). Each chip's × is a real button in the tab order named "Remove Haircut" (labels.remove); focus returns to the trigger after removing. The clear button is named "Clear selection" (labels.clear).
- id goes on the combobox button, so <label htmlFor={id}> names it; without aria-label the listbox is labelled by the trigger.
- invalid sets aria-invalid on the trigger and a red border.

## Motion

- fade-scale (default): the menu fades in, scales from 0.96 and moves 4px on a spring (stiffness 520, damping 34, mass 0.7). slide: it unrolls with a clip from the trigger side and moves 10px. stagger: options slide in 6px, 28 ms apart, 220 ms each.
- The menu closes with a 120 ms fade. It opens upward when there is not enough room below and more room above.
- Chips pop in and out (scale from 0.8) and the others shift into place. The chevron turns 180° in 200 ms; the underline variant draws its bar in 250 ms.
- Reduced motion: the menu, options and chips appear and disappear without animation, and trigger transitions are off.

## Notes for AI

- Single: value is string | null and onValueChange(string | null) (null after clear). With multiple: value is string[] and onValueChange(string[]). Do not mix them.
- options accepts objects { value, label, description?, icon?, avatar?, group?, disabled?, keywords? }, plain strings, or one comma-separated string. Options of the same group should be listed together.
- The menu renders inside the component (no portal). Avoid overflow: hidden on parents, or give the parent room; it flips up when space below runs out.
- Default width is w-72; set className="w-full" in forms. name renders hidden inputs (one per value with multiple) for native form posts.
- Built-in text: placeholder, searchPlaceholder and emptyText are props; labels has clear, selectedHint and remove (chip ×).

## FAQ

**Can I use it with a <label> element?**

Yes. Pass id to Select and point <label htmlFor> at it: the id goes on the combobox button. Without a visible label, pass aria-label.

**How does search match?**

It ignores case and accents and matches anywhere in the label, description, group name and keywords. The matched part of the label is underlined.

## Related

- input: https://goodui.dev/components/core/input
- checkbox: https://goodui.dev/components/core/checkbox
- segmented-control: https://goodui.dev/components/navigation/segmented-control
- tag-input: https://goodui.dev/components/inputs/tag-input

Last updated: 2026-11-02

---

# Dialog & Sheet

> Modal dialog, alert dialog and sheet in one: default, soft, glass and neo surfaces in six tones; center, top, start/end/left/right and draggable bottom sheets, fullscreen, and a phone override to fullscreen or sheet; scale, slide, blur, fade or morph-from-trigger entrances; async confirm with spinner and inline error, type-to-confirm, nested dialogs that step back, focus trap and restore, and scroll lock without layout shift.

Accessible React dialog, alert dialog and sheet in one component: async confirm, nested dialogs, morph animation

Page: https://goodui.dev/components/core/dialog

## Install

```bash
npx shadcn@latest add @goodui/dialog
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/dialog.json`. The file lands in `components/goodui/dialog.tsx`.

## When to use

- A task that needs the user's full attention before going back to the page: edit an appointment, invite a teammate, pay an invoice.
- Confirming a destructive or costly action: role="alertdialog" with onConfirm, and confirmPhrase for things like deleting a workspace.
- Side panels for details and filters (placement="end" or "start") and mobile bottom sheets (placement="bottom", or mobile="sheet" on a center dialog).
- Actions that call a server: return a promise from onConfirm and the dialog shows a spinner, waits, and keeps the error on screen if it throws.

## When not to use

- Small anchored content the user can ignore (a date filter, a share menu): use popover; it doesn't block the page.
- A short hint on hover or focus: use tooltip.
- Feedback that needs no answer ("Saved"): use a toast or alert; a modal interrupts for nothing.
- Long multi-page flows: give them their own route; a dialog is for one focused task.

## Pick by what matters

| Need | Use |
| --- | --- |
| Confirm a destructive action | role="alertdialog" tone="danger" with onConfirm (+ confirmPhrase for irreversible ones) |
| A form | placement="center" (default) with children; mobile="fullscreen" for long forms on phones |
| Details or filters beside the page | placement="end" (or "start"); they follow the reading direction |
| Phones | mobile="sheet" turns a center dialog into a draggable bottom sheet under 640px |
| Command palette or search | placement="top" size="lg" |
| Delight on a marketing page | animation="morph" (grows out of the trigger) or "blur" |
| On photos or colorful backgrounds | variant="glass" with overlay="blur" |
| Playful or retro brands | variant="neo" |

## Usage

```tsx
import { Trash2 } from "lucide-react"
import { Button } from "@/components/goodui/button"
import { Dialog } from "@/components/goodui/dialog"

export function DeleteClient({ onDelete }: { onDelete: () => Promise<void> }) {
  return (
    <Dialog
      role="alertdialog"
      tone="danger"
      icon={<Trash2 />}
      title="Delete client?"
      description="Omar Haddad and his 14 past bookings will be removed. This can't be undone."
      confirmText="Delete client"
      onConfirm={onDelete}
      trigger={
        <Button variant="soft" tone="danger">
          Delete client
        </Button>
      }
    />
  )
}
```

### Form dialog with a custom footer and close()

```tsx
<Dialog
  title="Edit appointment"
  description="Changes are texted to the client."
  mobile="fullscreen"
  trigger={<Button variant="outline">Edit</Button>}
  footer={({ close }) => (
    <>
      <Button variant="ghost" tone="neutral" onClick={close}>Cancel</Button>
      <Button onClick={async () => { await save(); close() }}>Save</Button>
    </>
  )}
>
  <AppointmentForm />
</Dialog>
```

### Side sheet

```tsx
<Dialog placement="end" size="md" title="Invite to your team" trigger={<Button>Invite</Button>}>
  {({ close }) => <InviteForm onSent={close} />}
</Dialog>
```

### Type to confirm, with an error from the server

```tsx
<Dialog
  role="alertdialog"
  tone="danger"
  title="Cancel your subscription?"
  confirmPhrase="CANCEL"
  confirmText="Cancel subscription"
  onConfirm={async () => {
    const res = await fetch("/api/subscription", { method: "DELETE" })
    if (!res.ok) throw new Error("Couldn't reach billing. Nothing was changed.")
  }}
  trigger={<Button variant="ghost" tone="danger">Cancel plan</Button>}
/>
```

### Controlled, opened from code

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

<Dialog open={open} onOpenChange={setOpen} placement="bottom" title="Pick a time">
  {({ close }) => <Slots onPick={(t) => { book(t); close() }} />}
</Dialog>
```

### Nested dialog

```tsx
<Dialog title="Edit appointment" trigger={<Button>Edit</Button>}>
  <Dialog size="sm" title="Choose a stylist" trigger={<Button size="xs" variant="soft">Change</Button>}>
    {({ close }) => <StylistList onPick={close} />}
  </Dialog>
</Dialog>
```

## API

### Dialog

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| trigger | `React.ReactElement<TriggerProps>` | — | Element that opens the dialog (a button). It gets aria-haspopup, aria-expanded and aria-controls, and morph grows out of it. |
| open | `boolean` | — | Open state (controlled). |
| defaultOpen | `boolean` | `false` | Initial open state when uncontrolled. |
| onOpenChange | `(open: boolean) => void` | — |  |
| role | `"dialog" \| "alertdialog"` | `"dialog"` | alertdialog: for confirmations that interrupt. Outside click does not close it, there is no × by default, and focus starts on Cancel. |
| title | `React.ReactNode` | — | Heading; names the dialog for screen readers. Without it, pass aria-label. |
| description | `React.ReactNode` | — | Muted text under the title; describes the dialog for screen readers. |
| icon | `React.ReactNode` | — | Icon in a tone-tinted tile above or beside the title. |
| children | `React.ReactNode \| ((api: DialogApi) => React.ReactNode)` | — | Body. A function receives { close }. |
| footer | `React.ReactNode \| ((api: DialogApi) => React.ReactNode)` | — | Custom footer; replaces the built-in Cancel / Confirm buttons. A function receives { close }. |
| variant | `"default" \| "soft" \| "glass" \| "neo"` | `"default"` | Surface: default, soft (tone tint), glass (frosted) or neo (thick border, hard shadow). |
| tone | `"primary" \| "neutral" \| "success" \| "warning" \| "danger" \| "info"` | `"primary"` | Accent for the icon tile, confirm button, soft tint and focus ring. |
| placement | `"center" \| "top" \| "start" \| "end" \| "left" \| "right" \| "bottom" \| "fullscreen"` | `"center"` | Where it appears. Sheets slide from their edge with any animation except fade, blur and none. |
| mobile | `"same" \| "fullscreen" \| "sheet"` | `"same"` | Below 640px, a center or top dialog can become fullscreen or a bottom sheet. |
| size | `"sm" \| "md" \| "lg" \| "xl" \| "full"` | `"md"` | Width for dialogs and side sheets, max width for the bottom sheet. full fills the screen. |
| radius | `"none" \| "sm" \| "md" \| "lg" \| "xl"` | `"lg"` |  |
| shadow | `"none" \| "sm" \| "md" \| "lg" \| "xl"` | `"lg"` | Drop shadow. Ignored by neo, which has its own offset shadow. |
| animation | `"none" \| "fade" \| "scale" \| "slide" \| "morph" \| "blur"` | `"scale"` | How it enters and leaves. morph grows out of the trigger (falls back to scale without one). Reduced motion uses a short fade. |
| overlay | `"dim" \| "blur" \| "none"` | `"dim"` | Backdrop: dim (default), blur (frosted page) or none (transparent, still blocks the page). |
| showClose | `boolean` | — | × button in the corner. Default: true for dialog, false for alertdialog. |
| closeOnEsc | `boolean` | `true` | Esc closes. When false (or while confirming), Esc gives a small bump instead. |
| closeOnOutsideClick | `boolean` | — | Click on the backdrop closes. Default: true for dialog, false for alertdialog. |
| dragToClose | `boolean` | `true` | Bottom sheet: drag the handle down to close. |
| onConfirm | `() => unknown` | — | Shows Cancel and Confirm. May return a promise: the button shows a spinner and the dialog waits; a throw keeps it open and shows the error. |
| confirmText | `React.ReactNode` | — | Confirm button text (default labels.confirm). |
| cancelText | `React.ReactNode` | — | Cancel button text (default labels.cancel). |
| confirmTone | `"primary" \| "neutral" \| "success" \| "warning" \| "danger" \| "info"` | — | Confirm button tone; defaults to tone. |
| closeOnConfirm | `boolean` | `true` | Close after onConfirm succeeds. |
| confirmPhrase | `string` | — | The user must type this exact text before Confirm is enabled (deleting a workspace). |
| initialFocus | `React.RefObject<HTMLElement \| null>` | — | Element to focus on open. Default: an autoFocus element, Cancel for alertdialog, the first field or button, else the panel. |
| returnFocus | `boolean` | `true` | Return focus to the element that had it before opening. |
| sound | `boolean \| SoundName` | — | Plays "open" and "close" when the visitor has sounds on (lib/goodui-sounds); a sound name replaces the open sound. Off by default. |
| labels | `Partial<DialogLabels>` | — | Text for built-in controls; pass translations here. |

Also accepts every <div> attribute.

## Keyboard

| Keys | Action |
| --- | --- |
| Enter / Space | On the trigger: opens the dialog (native button). |
| Tab / Shift+Tab | Moves focus inside the dialog; at the last or first control it wraps around. |
| Esc | Closes the top dialog only. With closeOnEsc={false}, or while onConfirm is running, the panel gives a small bump instead. |
| Enter | In the type-to-confirm field: confirms once the phrase matches. |

## Accessibility

- The panel has role="dialog" (or "alertdialog") and aria-modal="true", is named by the title (aria-labelledby) and described by the description (aria-describedby). Without a title, pass aria-label.
- The trigger gets aria-haspopup="dialog", aria-expanded and aria-controls.
- Focus moves in on open: initialFocus, else an autoFocus or data-autofocus element, else the type-to-confirm field, else Cancel for alertdialog (the least destructive choice), else the first control in the body, else the panel. It returns to the element that had it before opening.
- Tab and Shift+Tab are trapped inside the panel. The page behind is not made inert; aria-modal tells assistive tech to stay in the dialog, and the backdrop blocks pointer input.
- While onConfirm runs, the panel has aria-busy and the confirm button is disabled with a spinner. A thrown error is shown in a role="alert" message.
- The × button is a real button named by labels.close; the drag handle of the bottom sheet is decorative (Esc and the backdrop still close it).
- Every built-in string (Close, Cancel, Confirm, the type-to-confirm label, the generic error) comes from labels, so it can be translated. start/end sheets and the panel follow the reading direction.

## Motion

- Enter (Web Animations, easing cubic-bezier(.16,1,.3,1)): scale from 0.94 in 260 ms, slide up 24px in 300 ms, blur from 14px in 320 ms, fade in 180 ms, morph from the trigger's box in 420 ms. Sheets slide in from their edge in 380 ms.
- Exit plays the entrance backwards in 60% of the time. The backdrop fades in over 220 ms and out with the panel. Morph shrinks back into the trigger.
- Nested: the dialog behind steps back (scale 0.94, up 14px) with a 320 ms transition. A refused close (alertdialog backdrop, Esc while confirming) bumps the panel to 1.025 for 240 ms.
- Bottom sheets follow the finger when dragged by the handle and close when let go past 35% of their height or 140px, whichever is less, or on a quick downward flick.
- Reduced motion: every entrance becomes a 140 ms fade (100 ms out), the dialog behind steps back without a transition, and there is no bump. animation="none" adds no animation at all.

## Performance

- Nothing is rendered until the dialog opens; the portal unmounts after the exit animation.
- Animations run on transform and opacity through the Web Animations API. blur also animates filter, and glass uses backdrop-filter; both cost more on low-end phones.
- Scroll lock is shared: any number of open dialogs set overflow hidden on <html> once and restore it when the last one closes. scrollbar-gutter: stable (or padding where unsupported) keeps the page from shifting.

## Notes for AI

- Pass the opener as trigger={<Button>…</Button>}; do not wrap Dialog in your own click handler. For dialogs opened from code use open + onOpenChange.
- For confirmations pass onConfirm (sync or async) instead of building Cancel/Confirm buttons; throw an Error to keep the dialog open and show its message.
- Use role="alertdialog" for destructive confirmations; it turns off outside-click close and the × button by default.
- children and footer can be functions receiving { close }; use them to close after an action inside the dialog.
- Sheets are placement="start" | "end" | "left" | "right" | "bottom"; prefer start/end so RTL works.
- Always give a title (or aria-label). Do not add role or aria-modal yourself.
- Do not nest a Dialog's trigger inside another interactive element.

## FAQ

**Can I open it without a trigger?**

Yes. Leave out trigger and control it with open and onOpenChange. morph then grows out of whatever had focus when it opened.

**How do I stop it from closing?**

closeOnEsc={false} and closeOnOutsideClick={false}. While an onConfirm promise is pending, Esc and the backdrop are ignored automatically.

**Does it work inside a scrolling container or a transformed parent?**

Yes. It renders into document.body through a portal, so overflow and transforms of parents don't clip it.

**Why does my page not jump when the dialog opens?**

The scroll lock keeps a stable scrollbar gutter (or adds padding equal to the scrollbar width in browsers without scrollbar-gutter).

## Related

- popover: https://goodui.dev/components/core/popover
- tooltip: https://goodui.dev/components/core/tooltip
- button: https://goodui.dev/components/core/button
- alert: https://goodui.dev/components/core/alert
- morphing-dialog: https://goodui.dev/components/overlays/morphing-dialog
- drawer-spring: https://goodui.dev/components/overlays/drawer-spring

Last updated: 2026-11-03

---

# Tooltip

> Dark, light, tone, glass and neo tooltips with sizes, shapes, shadows and an optional arrow; twelve placements that flip and shift at the screen edge, scale, fade, slide or spring entrances, rich title + keyboard-shortcut content, delay groups that open instantly after the first, follow-cursor for charts and touch long-press.

React tooltip with keyboard shortcuts, delay groups, follow-cursor and touch long-press

Page: https://goodui.dev/components/core/tooltip

## Install

```bash
npx shadcn@latest add @goodui/tooltip
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/tooltip.json`. The file lands in `components/goodui/tooltip.tsx`.

## When to use

- Naming icon-only buttons in toolbars and tables, with the keyboard shortcut (shortcut="Mod+N").
- A one-line explanation of a status, a badge or a truncated value.
- Charts and heatmaps where the hint should follow the pointer (followCursor).
- Explaining why a control is disabled (wrap the disabled button in a focusable span).

## When not to use

- Anything the user must read or click (links, buttons, forms): use popover; tooltips vanish on blur and can't hold focus.
- Information needed on touch devices to finish a task: show it inline; long-press is a fallback, not a primary path.
- The only name of an icon button: the button still needs aria-label; the tooltip is a description.

## Pick by what matters

| Need | Use |
| --- | --- |
| App chrome, toolbars | variant="dark" (default), wrapped in TooltipGroup |
| Dark UIs or busy screens | variant="light" |
| Status meaning (paid, overdue) | variant="tone" with tone |
| Over photos or gradients | variant="glass" |
| Playful brands | variant="neo" |
| Shortcut hints | title + shortcut (Mod is ⌘ on Mac, Ctrl elsewhere) |
| Charts | followCursor with content that changes as the pointer moves |

## Usage

```tsx
import { Bell, CalendarPlus } from "lucide-react"
import { Button } from "@/components/goodui/button"
import { Tooltip, TooltipGroup } from "@/components/goodui/tooltip"

export function Toolbar() {
  return (
    <TooltipGroup>
      <Tooltip title="New booking" content="For the selected slot" shortcut="Mod+N">
        <Button size="sm" iconLeft={<CalendarPlus />}>New</Button>
      </Tooltip>
      <Tooltip content="3 unread notifications" variant="tone" tone="danger" side="bottom">
        <Button size="sm" variant="ghost" iconOnly aria-label="Notifications">
          <Bell />
        </Button>
      </Tooltip>
    </TooltipGroup>
  )
}
```

### Disabled button

```tsx
// Disabled buttons get no pointer or focus events, so wrap them.
<Tooltip content="Refunds open after the payout clears">
  <span tabIndex={0}>
    <Button disabled>Refund</Button>
  </span>
</Tooltip>
```

### Follow the cursor over a chart

```tsx
const [i, setI] = React.useState(0)

<Tooltip followCursor delay={0} animation="fade" title={hours[i]} content={`${load[i]} of 8 chairs booked`}>
  <div tabIndex={0} onPointerMove={(e) => setI(indexFromX(e))}>{bars}</div>
</Tooltip>
```

### Keep it open to show feedback

```tsx
<Tooltip content={copied ? "Copied!" : "Copy link"} open={copied ? true : undefined}>
  <Button onClick={copy}>Copy link</Button>
</Tooltip>
```

## API

### Tooltip

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| children (required) | `React.ReactNode` | — | The trigger: one element (a button, an icon, a link). Text is wrapped in a focusable span. |
| content | `React.ReactNode` | — | Tooltip body (with a title, the muted second line). |
| title | `React.ReactNode` | — | Bold first line for rich tooltips; content becomes the muted second line. |
| shortcut | `string \| string[]` | — | Keyboard shortcut shown as keycaps: "Mod+K" or ["Shift", "D"]. Mod is ⌘ on Mac and Ctrl elsewhere. |
| variant | `"dark" \| "light" \| "tone" \| "glass" \| "neo"` | `"dark"` | Paint: dark (default, dark in both themes), light (light in both themes), tone (filled with the tone), glass, neo. |
| tone | `"primary" \| "neutral" \| "success" \| "warning" \| "danger" \| "info"` | `"primary"` | Color for the tone and neo variants. |
| size | `"sm" \| "md" \| "lg"` | `"md"` |  |
| shape | `"square" \| "rounded" \| "pill"` | `"rounded"` |  |
| shadow | `"none" \| "sm" \| "md" \| "lg"` | `"md"` | Drop shadow. Ignored by neo, which has its own offset shadow. |
| animation | `"none" \| "fade" \| "scale" \| "slide" \| "spring"` | `"scale"` | How it appears: scale (default), fade, slide, spring or none. Reduced motion uses a short fade. |
| side | `"top" \| "bottom" \| "left" \| "right" \| "start" \| "end"` | `"top"` | Preferred side; flips to the opposite side when there is no room. |
| align | `"start" \| "center" \| "end"` | `"center"` | Alignment along the side. start/end follow the reading direction. |
| offset | `number` | `8` | Gap between trigger and tooltip, in px. |
| arrow | `boolean` | `true` |  |
| delay | `number` | `500` | Hover delay before opening, in ms. Inside a TooltipGroup the group's delay is used. Focus opens at once. |
| closeDelay | `number` | `100` | Grace period before closing after the pointer leaves, so the pointer can move onto the tooltip, in ms. |
| longPressDelay | `number` | `500` | Touch: how long to press before the tooltip shows, in ms. It hides 1.5 s after release or on the next tap. |
| followCursor | `boolean` | `false` | Position at the pointer and follow it while it moves over the trigger (charts, heatmaps). |
| open | `boolean` | — | Open state (controlled). |
| defaultOpen | `boolean` | `false` | Initial open state when uncontrolled. |
| onOpenChange | `(open: boolean) => void` | — |  |
| disabled | `boolean` | `false` | Never open. |
| portal | `boolean` | `true` | Render into document.body so overflow and z-index of parents can't clip it. |
| labels | `Partial<TooltipLabels>` | — | Text for screen readers; pass translations here. |

Also accepts every <div> attribute.

### TooltipGroup

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| children (required) | `React.ReactNode` | — | Content. |
| delay | `number` | `500` | Delay before the first tooltip in the group opens, in ms. |
| skipDelay | `number` | `400` | After a tooltip closes, how long the next one still opens instantly, in ms. |

## Keyboard

| Keys | Action |
| --- | --- |
| Tab | Focusing the trigger with the keyboard shows the tooltip at once; moving focus away hides it. |
| Esc | Hides the open tooltip. It is handled first, so a dialog behind the tooltip stays open. |

## Accessibility

- The bubble has role="tooltip". The trigger's aria-describedby points at it while it is open, and at a hidden copy of the same text while it is closed, so screen readers announce the description on focus either way. Existing aria-describedby values are kept.
- It opens on hover (after delay), on keyboard focus (focus-visible, at once) and on touch long-press; it never opens on mouse click.
- The pointer can move from the trigger onto the tooltip without it closing (closeDelay), and Esc dismisses it.
- The shortcut keycaps come from the kbd component, which gives each special key a spoken name; a translatable "Shortcut:" prefix (labels.shortcut) is read before them.
- The tooltip is a description, not a name: icon-only triggers still need aria-label.

## Motion

- scale: from 0.9 in 160 ms. slide: 5px toward its side in 200 ms. spring: from 0.55 on a spring (stiffness 620, damping 22). fade: opacity only, 140 ms. Every variant fades out in 100 ms.
- Scale and spring grow from the arrow tip, so the tooltip seems to come out of the trigger.
- Inside a TooltipGroup, tooltips that open instantly after the first skip the movement and fade in over 60 ms.
- Reduced motion: a 100 ms fade, no movement. animation="none" shows and hides instantly.

## Performance

- Nothing renders until the tooltip opens (apart from the hidden description). Positioning runs on open, scroll, resize and size changes, not every frame; followCursor repositions on pointer move.

## Notes for AI

- The trigger is the child: one element (Button, a, span with tabIndex=0). Text children are wrapped in a focusable span automatically.
- Use content for the body, title for a bold first line, shortcut for keys ("Mod+K", "Shift+F" or an array). Don't build keycaps by hand.
- Wrap toolbars in TooltipGroup so only the first tooltip waits.
- side accepts start and end for RTL-safe placement; the tooltip flips and shifts to stay on screen by itself.
- Don't put links or buttons inside a tooltip; use popover.

## FAQ

**Does it work on phones?**

Yes: press and hold the trigger (longPressDelay, 500 ms by default). The tooltip hides 1.5 s after release or on the next tap, and the release doesn't click the button.

**Can I control it?**

Yes: open, defaultOpen and onOpenChange. open={undefined} hands control back to hover and focus.

**Why doesn't it show on my disabled button?**

Browsers send no pointer or focus events to disabled buttons. Wrap the button in a <span tabIndex={0}>.

## Related

- popover: https://goodui.dev/components/core/popover
- kbd: https://goodui.dev/components/core/kbd
- button: https://goodui.dev/components/core/button
- dialog: https://goodui.dev/components/core/dialog
- tooltip-animated: https://goodui.dev/components/overlays/tooltip-animated

Last updated: 2026-11-03

---

# Popover

> Anchored popover with an arrow in default, soft, glass, neo and inverted surfaces, tones, sizes, radii and shadows; side and align that flip and shift to stay on screen, match-trigger-width, scale, fade, slide or spring entrances, header, close button and footer slots, and modal (focus trapped) or non-modal (Tab flows back to the page) behavior, shown as a date filter, share menu, switcher and inline note form.

React popover with arrow, collision flipping and modal or non-modal focus: date filters, share menus, mini forms

Page: https://goodui.dev/components/core/popover

## Install

```bash
npx shadcn@latest add @goodui/popover
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/popover.json`. The file lands in `components/goodui/popover.tsx`.

## When to use

- Filters next to the control that opens them: a date range, a status filter, a location switcher.
- Small actions on one item: share a link, add a note to a booking, set a reminder.
- Extra information or settings that need buttons or fields, which a tooltip can't hold.
- Account or workspace switchers that should be exactly as wide as their trigger (matchTriggerWidth).

## When not to use

- Picking one value from a list: use select; it has listbox keyboard behavior and form support.
- A task that must be finished or cancelled before anything else: use dialog.
- A hint on hover: use tooltip.
- A menu of commands: use dropdown-stagger; menus use arrow keys, popovers use Tab.

## Pick by what matters

| Need | Use |
| --- | --- |
| Filters and switchers | variant="default", align="start" |
| Inline forms that shouldn't lose input to a stray click | modal (focus trapped, page blocked until saved or dismissed) |
| Switchers and comboboxes | matchTriggerWidth with arrow={false} |
| Highlighted tips | variant="soft" with a tone |
| Dark callouts | variant="inverted" |
| Over photos or gradients | variant="glass" |
| Playful brands | variant="neo" |

## Usage

```tsx
import * as React from "react"
import { Calendar, ChevronDown } from "lucide-react"
import { Button } from "@/components/goodui/button"
import { Popover } from "@/components/goodui/popover"

export function DateFilter({ value, onChange }: { value: string; onChange: (v: string) => void }) {
  const [draft, setDraft] = React.useState(value)
  return (
    <Popover
      align="start"
      title="Date range"
      onOpenChange={(open) => open && setDraft(value)}
      trigger={
        <Button variant="outline" iconLeft={<Calendar />} iconRight={<ChevronDown />}>
          {value}
        </Button>
      }
      footer={({ close }) => (
        <Button size="sm" onClick={() => { onChange(draft); close() }}>
          Apply
        </Button>
      )}
    >
      <Presets value={draft} onChange={setDraft} />
    </Popover>
  )
}
```

### Share menu that closes after an action

```tsx
<Popover title="Share booking page" size="sm" align="end" trigger={<Button>Share</Button>}>
  {({ close }) => <ShareTargets onShared={close} />}
</Popover>
```

### Modal mini form

```tsx
<Popover
  modal
  side="start"
  variant="soft"
  tone="warning"
  title="Note for Maya"
  trigger={<Button size="sm" variant="ghost">Note</Button>}
  footer={({ close }) => <Button size="sm" onClick={() => { save(); close() }}>Save note</Button>}
>
  <textarea aria-label="Note" />
</Popover>
```

### Location switcher as wide as its trigger

```tsx
<Popover matchTriggerWidth arrow={false} align="start" aria-label="Switch location" trigger={<Button className="w-56">Downtown</Button>}>
  {({ close }) => <LocationList onPick={close} />}
</Popover>
```

## API

### Popover

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| trigger (required) | `React.ReactElement<TriggerProps>` | — | The element that toggles the popover (a button). It gets aria-expanded, aria-controls and aria-haspopup. |
| children | `React.ReactNode \| ((api: PopoverApi) => React.ReactNode)` | — | Body. A function receives { close } for buttons that should close the popover. |
| title | `React.ReactNode` | — | Header title; also names the popover for screen readers. Without it, pass aria-label. |
| description | `React.ReactNode` | — | Muted line under the title. |
| footer | `React.ReactNode \| ((api: PopoverApi) => React.ReactNode)` | — | Footer row (actions). A function receives { close }. |
| showClose | `boolean` | — | × button in the header. Defaults to true when there is a title. |
| variant | `"default" \| "soft" \| "glass" \| "neo" \| "inverted"` | `"default"` | Surface: default (your popover color), soft (tone tint), glass, neo or inverted (dark on light). |
| tone | `"primary" \| "neutral" \| "success" \| "warning" \| "danger" \| "info"` | `"primary"` |  |
| size | `"sm" \| "md" \| "lg" \| "auto"` | `"md"` | Width and padding: sm 16rem, md 20rem, lg 26rem, auto fits the content. |
| radius | `"none" \| "sm" \| "md" \| "lg" \| "xl"` | `"lg"` |  |
| shadow | `"none" \| "sm" \| "md" \| "lg" \| "xl"` | `"lg"` | Drop shadow. Ignored by neo, which has its own offset shadow. |
| animation | `"none" \| "fade" \| "scale" \| "slide" \| "spring"` | `"scale"` | How it opens: scale (default), fade, slide, spring or none. Reduced motion uses a short fade. |
| side | `"top" \| "bottom" \| "left" \| "right" \| "start" \| "end"` | `"bottom"` | Preferred side; flips to the opposite side when there is no room. |
| align | `"start" \| "center" \| "end"` | `"center"` | Alignment along the side. start/end follow the reading direction. |
| offset | `number` | `8` | Gap between trigger and popover, in px. |
| arrow | `boolean` | `true` |  |
| avoidCollisions | `boolean` | `true` | false keeps the requested side and alignment even when the popover leaves the screen. |
| matchTriggerWidth | `boolean` | `false` | Same width as the trigger (account switchers, comboboxes). Overrides size width. |
| modal | `boolean` | `false` | true traps focus inside and blocks the page behind with a transparent layer. |
| closeOnOutsideClick | `boolean` | `true` |  |
| closeOnEsc | `boolean` | `true` |  |
| open | `boolean` | — | Open state (controlled). |
| defaultOpen | `boolean` | `false` | Initial open state when uncontrolled. |
| onOpenChange | `(open: boolean) => void` | — |  |
| initialFocus | `React.RefObject<HTMLElement \| null>` | — | Element to focus on open. Default: the first focusable element in the body, else the panel. |
| returnFocus | `boolean` | `true` | Return focus to the trigger after closing with Esc, the close button or close(). |
| portal | `boolean` | `true` | Render into document.body so overflow and z-index of parents can't clip it. |
| labels | `Partial<PopoverLabels>` | — | Text for built-in controls; pass translations here. |

Also accepts every <div> attribute.

## Keyboard

| Keys | Action |
| --- | --- |
| Enter / Space | On the trigger: opens or closes the popover (native button). Focus moves to the first control in the body. |
| Tab / Shift+Tab | Non-modal: moves through the popover as if it sat right after the trigger; Tab past the last control closes it and focuses the next control on the page, Shift+Tab before the first closes it and returns to the trigger. Modal: wraps around inside. |
| Esc | Closes the popover (not a dialog behind it) and returns focus to the trigger. |

## Accessibility

- The panel has role="dialog", is named by the title (aria-labelledby) and described by the description; without a title, pass aria-label. modal adds aria-modal="true".
- The trigger gets aria-haspopup="dialog", aria-expanded and aria-controls.
- Focus moves in on open (initialFocus, else the first control in the body, else the panel) and returns to the trigger after Esc, the close button or close(). An outside click doesn't pull focus back, so the clicked control keeps it.
- Outside-click detection follows the React tree, so popovers, selects and menus rendered in portals inside the popover don't close it.
- The × button is named by labels.close for translation. The arrow is decorative.

## Motion

- scale: from 0.94 in 180 ms. slide: 6px from the trigger in 220 ms. spring: from 0.8 on a spring (stiffness 520, damping 26). fade: opacity only, 150 ms. Every variant leaves in 120 ms.
- Scale and spring grow from the arrow tip.
- Reduced motion: a 100 ms fade, no movement. animation="none" opens and closes instantly.

## Performance

- Nothing renders until it opens. Position is recomputed on open, scroll, resize and when the panel or trigger changes size, not on every frame.
- The body scrolls when the space on the chosen side is smaller than the content, instead of the panel leaving the screen.

## Notes for AI

- Pass the opener as trigger={<Button>…</Button>} and the body as children. Use footer for actions.
- children and footer can be functions receiving { close }; call close() after applying or saving.
- Prefer side="start" / "end" over left/right so RTL works. The popover flips and shifts by itself; pass avoidCollisions={false} only when you really need a fixed side.
- Don't put a Popover trigger inside another button. Don't use it for menus or selects.
- Give it a title or an aria-label.

## FAQ

**Can it be controlled?**

Yes: open, defaultOpen and onOpenChange. onOpenChange(true) is a good place to reset a draft to the saved value.

**Does it work inside a dialog?**

Yes. It renders into document.body above the dialog, Esc closes only the popover, and clicks inside it don't count as clicks outside the dialog.

**Why does the body scroll?**

When the space on the chosen side is smaller than the popover, it gets a max height and the body scrolls.

## Related

- dialog: https://goodui.dev/components/core/dialog
- tooltip: https://goodui.dev/components/core/tooltip
- select: https://goodui.dev/components/core/select
- button: https://goodui.dev/components/core/button
- popover-morph: https://goodui.dev/components/overlays/popover-morph
- dropdown-stagger: https://goodui.dev/components/overlays/dropdown-stagger

Last updated: 2026-11-03

---

# Dropdown Menu

> Menu button and right-click context menu with default, glass, neo, inverted and flat surfaces, soft, solid, bar or outline highlights, tones, sizes, shapes and shadows; icons, descriptions, badges and live keyboard shortcuts, checkbox items, radio groups, labelled groups, destructive items and nested sub-menus with hover intent and a safe triangle; scale, fade, slide or stagger entrances, type-ahead and full APG keyboard, portaled and flipped to stay on screen.

Dropdown menu and context menu for React and shadcn: sub-menus, checkbox and radio items, shortcuts, full keyboard

Page: https://goodui.dev/components/core/dropdown-menu

## Install

```bash
npx shadcn@latest add @goodui/dropdown-menu
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/dropdown-menu.json`. The file lands in `components/goodui/dropdown-menu.tsx`.

## When to use

- A list of actions behind one button: row actions in a table (Edit, Duplicate, Cancel booking), an Export button, a user menu.
- Right-click menus on a canvas, calendar or file list (mode="context"), with long-press on touch.
- Toggles and one-of-many settings that belong with the actions: visible columns (checkbox items), sort order or status (radio group).
- Deep action trees that need sub-menus, with keyboard shortcuts shown next to each action and optionally bound as hotkeys.

## When not to use

- Picking a form value from a list: use select; a menu runs actions and does not hold a form value.
- Typing to search thousands of options: use combobox.
- Two or three actions that fit on screen: show them as buttons, so nothing is hidden.
- Site navigation with many links: use a navigation menu or sidebar; menus are for actions on the current thing.

## Pick by what matters

| Need | Use |
| --- | --- |
| Row actions in tables and lists | an iconOnly Button as trigger, align="end", size="sm" |
| Calm app menus | variant="default", highlight="soft", animation="scale" (default) |
| Dense pro tools (editors, calendars) | highlight="bar" or "outline", size="sm", animation="fade" |
| macOS-like menus over content | variant="inverted" or "glass" |
| Playful or retro brands | variant="neo" with highlight="solid" |
| Right-click on a surface | mode="context" and wrap the surface as children |
| Shortcuts that actually work | shortcut on items plus bindShortcuts |

## Usage

```tsx
import { MoreHorizontal, Pencil, Copy, CalendarClock, Trash2 } from "lucide-react"
import { Button } from "@/components/goodui/button"
import { DropdownMenu } from "@/components/goodui/dropdown-menu"

export function BookingActions({ booking }: { booking: { id: string; client: string } }) {
  const [remind, setRemind] = React.useState(true)
  const [status, setStatus] = React.useState("confirmed")
  return (
    <DropdownMenu
      align="end"
      trigger={
        <Button variant="ghost" tone="neutral" size="sm" iconOnly aria-label={`Actions for ${booking.client}`}>
          <MoreHorizontal />
        </Button>
      }
      items={[
        { label: "Edit booking", icon: <Pencil />, shortcut: "Mod+E", onSelect: () => edit(booking.id) },
        { label: "Duplicate", icon: <Copy />, shortcut: "Mod+D", onSelect: () => duplicate(booking.id) },
        {
          type: "sub",
          label: "Reschedule",
          icon: <CalendarClock />,
          items: [
            { label: "Tomorrow, same time", onSelect: () => moveBy(booking.id, 1) },
            { label: "Next week", onSelect: () => moveBy(booking.id, 7) },
          ],
        },
        { type: "separator" },
        { type: "checkbox", id: "remind", label: "Send reminder", checked: remind, onCheckedChange: setRemind },
        {
          type: "radio",
          id: "status",
          label: "Status",
          value: status,
          onValueChange: setStatus,
          options: [
            { value: "confirmed", label: "Confirmed" },
            { value: "pending", label: "Pending deposit" },
          ],
        },
        { type: "separator" },
        { label: "Cancel booking", icon: <Trash2 />, destructive: true, onSelect: () => cancel(booking.id) },
      ]}
    />
  )
}
```

### Context menu on a calendar

```tsx
<DropdownMenu
  mode="context"
  items={[
    { label: "New booking here", icon: <CalendarPlus />, onSelect: create },
    { label: "Block this time", onSelect: block },
  ]}
>
  <WeekGrid />
</DropdownMenu>
```

### Live hotkeys

```tsx
<DropdownMenu
  bindShortcuts
  label="Export"
  items={[
    { label: "Download PDF", shortcut: "Mod+Shift+F", onSelect: downloadPdf },
    { label: "Email to client", shortcut: "Mod+Shift+E", onSelect: email },
  ]}
/>
```

### Translated

```tsx
<DropdownMenu
  items={items}
  labels={{ trigger: "Aktionen", contextMenu: "Kontextmenü", keyName: (k) => ({ Ctrl: "Strg", Shift: "Umschalt", Del: "Entf" })[k] ?? k }}
/>
```

## API

### DropdownMenu

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| items (required) | `DropdownMenuItem[]` | — |  |
| aria-label | `string` | — | Defines a string value that labels the current element. Names the menu. Defaults to the trigger's text (menu) or labels.contextMenu (context). |
| mode | `"menu" \| "context"` | `"menu"` | menu opens from the trigger; context opens at the pointer on right-click (or long-press) inside children. |
| trigger | `React.ReactElement` | — | Your trigger element (usually a button). It gets the ARIA and handlers. Without it a built-in button is shown. |
| label | `React.ReactNode` | — | Text of the built-in trigger. |
| children | `React.ReactNode` | — | Context mode: the area that opens the menu on right-click. |
| variant | `"default" \| "glass" \| "neo" \| "inverted" \| "flat"` | `"default"` | Menu surface: default (popover), glass, neo, inverted or flat. |
| tone | `"primary" \| "neutral" \| "success" \| "warning" \| "danger" \| "info"` | `"primary"` | Accent for the highlight, check marks and bars. |
| highlight | `"soft" \| "solid" \| "bar" \| "outline"` | `"soft"` | How the active item is painted: soft tint, solid tone fill, a bar at the start edge, or an outline. |
| size | `"sm" \| "md" \| "lg"` | `"md"` |  |
| shadow | `"none" \| "sm" \| "md" \| "lg"` | `"md"` |  |
| shape | `"square" \| "rounded" \| "pill"` | `"rounded"` |  |
| animation | `"none" \| "fade" \| "scale" \| "slide" \| "stagger"` | `"scale"` | How menus open. stagger cascades the items in. Reduced motion turns it into a short fade. |
| side | `"top" \| "bottom" \| "left" \| "right"` | `"bottom"` | Preferred side; flips when there is no room. |
| align | `"start" \| "center" \| "end"` | `"start"` | Alignment along the side; start follows the reading direction. |
| sideOffset | `number` | `6` | Gap between trigger and menu in px. |
| open | `boolean` | — |  |
| defaultOpen | `boolean` | `false` |  |
| onOpenChange | `(open: boolean) => void` | — |  |
| bindShortcuts | `boolean` | — | Also run items' shortcuts as global hotkeys while the page is focused. |
| loop | `boolean` | `true` | Arrow keys wrap from the last item to the first. |
| disabled | `boolean` | — |  |
| menuClassName | `string` | — | Class for every menu panel (root and sub-menus). |
| labels | `Partial<DropdownMenuLabels>` | — | Text for built-in controls and screen readers; pass translations here. |

Also accepts every <div> attribute.

## Keyboard

| Keys | Action |
| --- | --- |
| Enter / Space | On the trigger: opens the menu and focuses the first item. |
| Arrow Down / Arrow Up | On the trigger: opens the menu on the first or last item. In the menu: moves between items, skipping disabled ones and wrapping (loop). |
| Home / End (also Page Up / Page Down) | First or last item. |
| Arrow Right (Arrow Left in RTL) | On a sub-menu item: opens the sub-menu and focuses its first item. |
| Arrow Left (Arrow Right in RTL) | In a sub-menu: closes it and returns focus to its parent item. |
| Enter / Space | Activates the item: runs onSelect, toggles a checkbox, picks a radio, opens a sub-menu. Links follow their href. |
| Letters | Type-ahead: focuses the next item whose label starts with the typed text. |
| Escape | Closes the current level; on the root menu returns focus to the trigger (or the element that was focused before a context menu). |
| Tab | Closes every level, returns focus to the trigger and lets Tab continue from there. |
| Shift + F10 / Menu key | In context mode, on a focused element inside the area: opens the menu at that element with the first item focused. |
| Item shortcuts | With bindShortcuts, each item's shortcut runs it from anywhere on the page (plain-letter combos are ignored while typing in a field). |

## Accessibility

- Follows the WAI-ARIA menu button pattern: the trigger gets aria-haspopup="menu", aria-expanded and aria-controls; the panel is role="menu" labelled by the trigger (or aria-label).
- Items are role="menuitem", "menuitemcheckbox" or "menuitemradio" with aria-checked; sub-menu items carry aria-haspopup and aria-expanded; groups are role="group" labelled by their visible label; separators are role="separator".
- Focus really moves to items (roving focus), so screen readers announce each item. Disabled items stay visible with aria-disabled and are skipped by the arrow keys.
- Shortcuts are visible keycaps and are exposed as aria-keyshortcuts (Mod becomes Meta on Mac and Control elsewhere).
- Your trigger element keeps its own name; icon-only triggers need an aria-label. Context menus are named by labels.contextMenu.
- Menus are portaled to document.body, so overflow: hidden parents never clip them, and they flip and shift to stay in the viewport.

## Motion

- scale (default): the menu fades in from 0.94 scale at the edge facing the trigger on a spring (stiffness 560, damping 36, mass 0.6). fade: 160 ms opacity. slide: moves 8px in from the trigger's side. stagger: items slide in 6px, 24 ms apart, 200 ms each.
- Menus close with a 100 ms fade. Check marks and radio dots pop in with a short overshoot; the bar highlight grows in 160 ms; the built-in trigger's chevron turns 180°.
- Reduced motion: menus only fade (100 ms), items do not cascade and CSS transitions are off. Nothing depends on the animation to work.

## Performance

- Menus mount only while open. Placement is measured once per open and updated on scroll, resize and size changes, throttled to one animation frame.
- Item lists are not virtualized; for hundreds of options use combobox.

## Notes for AI

- items is data: actions { label, icon?, description?, shortcut?, badge?, destructive?, href?, onSelect?, disabled?, keepOpen? }, { type: "checkbox", id, … }, { type: "radio", id, options }, { type: "sub", label, items }, { type: "group", label?, items }, { type: "label" }, { type: "separator" }.
- Pass your own trigger element (e.g. <Button iconOnly aria-label=…>); it is cloned with ref, ARIA and click/key handlers. Without trigger a built-in button shows label.
- Checkbox items stay open after a toggle and radio items close; flip that with keepOpen.
- Checkbox and radio state is uncontrolled via defaultChecked/defaultValue, or controlled via checked/value with onCheckedChange/onValueChange.
- Shortcuts use Mod for ⌘ on Mac and Ctrl elsewhere: "Mod+Shift+E". They are display-only unless bindShortcuts is set.
- Use mode="context" with children for right-click menus; do not attach onContextMenu yourself.
- Do not use it as a form select; use select or combobox for values.

## FAQ

**Does the menu get clipped inside a scrolling table?**

No. It renders in a portal on document.body with fixed positioning, flips to the other side when there is no room and shifts to stay inside the viewport.

**How do sub-menus behave with the mouse?**

They open after about 110 ms of hover. While you move the pointer diagonally toward an open sub-menu, a safe triangle keeps it open even if you cross other items.

**Can items be links?**

Yes, give an item href (and target). It renders an <a role="menuitem">, so middle-click and open-in-new-tab work.

## Related

- select: https://goodui.dev/components/core/select
- combobox: https://goodui.dev/components/core/combobox
- button: https://goodui.dev/components/core/button
- kbd: https://goodui.dev/components/core/kbd

Last updated: 2026-11-03

---

# Combobox

> Autocomplete combobox (ARIA 1.2) with outline, filled, ghost, underline, pill and neo fields, tones, sizes and shadows; local ranked matching or debounced async search with abort, cache, loading, empty and error-with-retry states, every matched word highlighted, groups, avatars, single or multi-select chips, an “Add …” create row and automatic virtualization for 10,000+ rows, in a portaled list that flips above the field.

Autocomplete combobox for React and shadcn: async search, highlight, chips, create option and 10k-row virtualization

Page: https://goodui.dev/components/core/combobox

## Install

```bash
npx shadcn@latest add @goodui/combobox
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/combobox.json`. The file lands in `components/goodui/combobox.tsx`.

## When to use

- Searching a set too big to scroll: clients, products, cities, users, where the user types and the list narrows.
- Server-side search: loadOptions runs after a debounce, cancels stale requests with an AbortSignal, caches per query and shows loading, empty and error states.
- Free-form values with suggestions: creatable adds an “Add …” row, for tags, new clients or invite-by-email.
- Very long local lists (thousands of rows): rows are virtualized automatically above virtualThreshold.

## When not to use

- Picking from a short, known list (under ~15 options): use select, a picker that does not need typing.
- Running actions (Edit, Delete): use dropdown-menu.
- A global command palette (⌘K) that mixes navigation and actions: use a command dialog.
- Typing tags with no suggestions at all: use tag-input.

## Pick by what matters

| Need | Use |
| --- | --- |
| Forms | variant="outline" (default), with a <label htmlFor> pointing at id |
| API search | loadOptions + minChars (2 is typical) + debounce; keep options for labels of already-chosen values |
| Several values | multiple: chips in the field, Backspace removes the last |
| Unknown values allowed | creatable with onCreate returning the saved option |
| Thousands of local rows | plain options; virtualization switches on above virtualThreshold (100 rows) |
| Toolbars | variant="ghost" or "pill", size="sm" |
| Calm list | animation="fade-scale" (default) or "none"; "stagger" only for short lists |

## Usage

```tsx
import * as React from "react"
import { Search } from "lucide-react"
import { Combobox, type ComboboxOption } from "@/components/goodui/combobox"

export function ClientField() {
  const [client, setClient] = React.useState<string | null>(null)
  return (
    <div className="flex flex-col gap-1.5">
      <label htmlFor="client" className="text-sm font-medium">Client</label>
      <Combobox
        id="client"
        className="w-full"
        icon={<Search />}
        placeholder="Search clients…"
        minChars={2}
        loadOptions={async (query, { signal }) => {
          const res = await fetch(`/api/clients?q=${encodeURIComponent(query)}`, { signal })
          const rows: { id: string; name: string; email: string }[] = await res.json()
          return rows.map((r) => ({ value: r.id, label: r.name, description: r.email, avatar: true }))
        }}
        creatable
        onCreate={async (name) => {
          const saved = await createClient(name)
          return { value: saved.id, label: saved.name }
        }}
        value={client}
        onValueChange={setClient}
        clearable
        name="clientId"
      />
    </div>
  )
}
```

### Multiple with groups and invite-by-email

```tsx
<Combobox
  aria-label="Invitees"
  multiple
  creatable
  options={team.map((m) => ({ value: m.email, label: m.name, description: m.email, group: m.role, avatar: true }))}
  value={emails}
  onValueChange={setEmails}
  labels={{ create: (t) => `Invite “${t}” by email` }}
/>
```

### 10,000 local rows

```tsx
<Combobox aria-label="Product" options={catalog} variant="filled" onValueChange={(value, option) => addLine(option)} />
```

### Translated

```tsx
<Combobox
  aria-label="Kunde"
  options={clients}
  placeholder="Kunden suchen…"
  labels={{
    clear: "Leeren",
    toggle: "Vorschläge anzeigen",
    create: (t) => `„${t}“ anlegen`,
    loading: "Suche…",
    empty: (q) => (q ? `Keine Treffer für „${q}“` : "Keine Einträge"),
    error: "Ergebnisse konnten nicht geladen werden.",
    retry: "Erneut versuchen",
    minChars: (n) => `Mindestens ${n} Zeichen eingeben`,
    results: (n) => `${n} Ergebnisse`,
  }}
/>
```

## API

### Combobox

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| id | `string` | — | Goes on the input, so <label htmlFor> works. |
| aria-label | `string` | — | Defines a string value that labels the current element. Names the input and the list. Pass one unless a visible <label htmlFor={id}> points at the input. |
| options | `RawOption[]` | — | Local options (objects or strings). With loadOptions they are shown before typing and used to label values. |
| loadOptions | `(query: string, ctx: { signal: AbortSignal }) => Promise<RawOption[]>` | — | Async search. Called after the debounce with the typed text; aborted when the text changes. |
| debounce | `number` | — | Debounce for loadOptions in ms. |
| minChars | `number` | — | Characters needed before loadOptions runs. |
| cache | `boolean` | — | Cache loadOptions results per query for the life of the component. |
| filter | `((option: ComboboxOption, query: string) => boolean) \| false` | — | Custom local match. false shows options unfiltered (when you filter yourself). |
| creatable | `boolean` | — | Shows an "Add “text”" row when no option matches the typed text exactly. |
| onCreate | `(text: string) => RawOption \| void \| Promise<RawOption \| void>` | — | Called with the typed text when the create row is picked. Return the new option (or nothing to use the text). |
| placeholder | `string` | — |  |
| variant | `"outline" \| "filled" \| "ghost" \| "underline" \| "pill" \| "neo"` | — | Field style: outline (default), filled, ghost, underline, pill or neo. |
| tone | `"primary" \| "neutral" \| "success" \| "warning" \| "danger" \| "info"` | — | Accent for the focus ring, active row, checks and chips. |
| size | `"sm" \| "md" \| "lg"` | — |  |
| shadow | `"none" \| "sm" \| "md" \| "lg"` | — | Field shadow. Ignored by neo. |
| animation | `"none" \| "fade-scale" \| "slide" \| "stagger"` | — | How the list opens: fade-scale (default), slide, stagger (rows one by one; off when virtualized) or none. |
| clearable | `boolean` | — | × button that clears the value and the text. |
| disabled | `boolean` | — |  |
| invalid | `boolean` | — | Red border and aria-invalid on the input. |
| icon | `React.ReactNode` | — | Leading icon in the field. |
| name | `string` | — | Form field name (renders hidden inputs with the value). |
| openOnFocus | `boolean` | — | Open the list when the input gets focus (by default it opens on typing, click or ↓). |
| virtualThreshold | `number` | — | Rows above which the list is virtualized. |
| inputValue | `string` | — | Text in the input (controlled). |
| defaultInputValue | `string` | — |  |
| onInputValueChange | `(text: string) => void` | — |  |
| open | `boolean` | — |  |
| defaultOpen | `boolean` | — |  |
| onOpenChange | `(open: boolean) => void` | — |  |
| menuClassName | `string` | — | Class for the popup. |
| labels | `Partial<ComboboxLabels>` | — | Text for built-in controls and screen readers; pass translations here. |
| multiple | `false` | — | true picks several values shown as chips; value then becomes string[]. |
| value | `string \| null` | — | Selected value (controlled): a string or null, or string[] with multiple. |
| defaultValue | `string \| null` | — |  |
| onValueChange | `(value: string \| null, option: ComboboxOption \| null) => void` | — | Called with the new value and its option (null after clearing). |

Also accepts every <div> attribute.

## Keyboard

| Keys | Action |
| --- | --- |
| Typing | Opens the list and filters it (or starts the async search after the debounce); the first match is highlighted. |
| Arrow Down / Arrow Up | Opens the list (on the first or last row) or moves the highlight, wrapping and skipping disabled rows. |
| Alt + Arrow Down / Alt + Arrow Up | Opens the list without moving the highlight / closes it. |
| Home / End | While the list is open: first or last row. With Shift, or while closed, they move the text caret as usual. |
| Page Up / Page Down | While the list is open: moves the highlight 10 rows. |
| Enter | Picks the highlighted row (or creates from the “Add …” row). Single closes the list; multiple adds a chip, clears the text and stays open. |
| Escape | Closes the list. Pressed again: brings back the selected label (or clears typed text); with clearable and nothing typed, clears the value. |
| Backspace | With multiple and an empty input, removes the last chip. |
| Tab | Closes the list and moves on; typed text that was not picked snaps back to the selection. |

## Accessibility

- The input is role="combobox" with aria-autocomplete="list", aria-expanded, aria-controls and aria-activedescendant (ARIA 1.2); focus stays in the input while the highlight moves.
- The popup is role="listbox" (aria-multiselectable with multiple, aria-busy while loading) with role="option" rows carrying aria-selected, aria-disabled, aria-posinset and aria-setsize, so virtualized lists still announce the full count.
- A polite live region announces the result count, “Searching…”, empty and error messages (all from labels).
- Pass aria-label, or id with a visible <label htmlFor>. Chips are listed in visually hidden text referenced by aria-describedby; each chip's × is a button named by labels.remove.
- The chevron button is out of the tab order (keyboard users have Arrow Down) and is named by labels.toggle. invalid sets aria-invalid.
- Matched text is wrapped in <mark>, ignoring case and accents, and every word of the query is highlighted.

## Motion

- fade-scale (default): the list fades in from 0.97 scale and 4px on a spring (stiffness 520, damping 34, mass 0.7). slide: unrolls from the field with a clip and 10px move. stagger: rows slide in 4px, 25 ms apart (off for virtualized lists).
- The list closes with a 120 ms fade. Chips pop in and out (scale from 0.8) and the others shift into place; the underline variant draws its bar in 250 ms.
- Reduced motion: the list only fades, rows do not stagger, chips appear without layout animation, CSS transitions are off and the loading spinner slows down.

## Performance

- Local matching uses a pre-folded index built once per options change; each keystroke is one pass that checks every word and ranks label prefix, word start, then anywhere.
- Above virtualThreshold (100 rows by default) only the rows in view plus a 200px margin are rendered; rows get a fixed height (taller when options have descriptions), so End, PageDown and scrolling stay smooth on 10k+ rows.
- Async search is debounced (250 ms), aborts the previous request through AbortSignal and caches results per query (cache={false} to turn off).

## Notes for AI

- Single: value is string | null and onValueChange(value, option). Multiple: value is string[] and onValueChange(values, options). Do not mix them.
- options accepts objects { value, label, description?, icon?, avatar?, group?, disabled?, keywords? } or plain strings.
- With loadOptions, return options for the typed query (the component does not filter them again); pass options too so already-chosen values have labels before the first search.
- onCreate may be async and should return the saved option; without onCreate the typed text becomes both value and label.
- The popup is portaled to document.body and flips above the field when there is no room below; no overflow tricks are needed.
- Default width is w-72; use className="w-full" in forms. name renders hidden inputs for native form posts.
- Use select instead for short fixed lists; combobox is for typing to search.

## FAQ

**How is this different from select?**

Select is a button that opens a list to pick from (with optional search inside the menu). Combobox is a text input: the user types first, results can come from a server, unknown values can be created, and lists can be virtualized.

**What happens to typed text that was not picked?**

On blur or Escape it snaps back to the selected option's label (or clears in multiple mode). Emptying the text and leaving clears a single value.

**Can I render 50,000 options?**

Yes, rows are virtualized, but the matching still scans every option per keystroke; for very large or remote data use loadOptions.

## Related

- select: https://goodui.dev/components/core/select
- dropdown-menu: https://goodui.dev/components/core/dropdown-menu
- input: https://goodui.dev/components/core/input
- tag-input: https://goodui.dev/components/inputs/tag-input

Last updated: 2026-11-03

---

# Date Picker

> Date picker and calendar with no date library: single, range (two months side by side) and multiple modes, presets, time inputs, min/max, disabled weekdays, booked days, ISO week numbers, month/year quick switch, typed dates parsed in the locale's order via Intl with the locale's first weekday, popover or inline, six field variants, tones, solid/soft/ring selection, day shapes, sizes and slide, fade or scale month animations with APG grid keyboard.

Date picker and range calendar for React and shadcn without a date library: presets, time, booked days, typed dates

Page: https://goodui.dev/components/core/date-picker

## Install

```bash
npx shadcn@latest add @goodui/date-picker
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/date-picker.json`. The file lands in `components/goodui/date-picker.tsx`.

## When to use

- Booking forms: pick a day and a time, with past days, closed weekdays and fully booked days blocked.
- Report filters: a date range with presets (Last 7 days, This month…) and two months side by side.
- Picking several separate days (staff days off, class dates) with mode="multiple".
- Any app that needs locale-correct names, digits, typed formats and first day of the week without shipping date-fns or dayjs.

## When not to use

- Birth dates and other far-away dates people know by heart: three selects or a plain typed field are faster than paging through years.
- A week or month calendar of events with drag and drop: use the scheduler.
- Only a time of day: use a time input.

## Pick by what matters

| Need | Use |
| --- | --- |
| Forms | variant="outline" (default) with a <label htmlFor> pointing at id |
| Appointments | time, min, disabledWeekdays and booked; minuteStep for the slot length |
| Reports and analytics | mode="range" with presets; max={today} to block the future |
| Always-visible calendar in a page or sidebar | inline |
| Several separate days | mode="multiple" (popover stays open, Done closes) |
| Calm UI | selection="soft" or "ring", animation="fade" |
| Playful or retro brands | variant="neo", shape="square" |

## Usage

```tsx
import * as React from "react"
import { DatePicker, type DateRange } from "@/components/goodui/date-picker"

export function BookingFields({ bookedDays }: { bookedDays: Date[] }) {
  const [when, setWhen] = React.useState<Date | null>(null)
  const [period, setPeriod] = React.useState<DateRange | null>(null)
  const [today, setToday] = React.useState<Date>()
  React.useEffect(() => setToday(new Date()), [])

  return (
    <form className="grid gap-4">
      <label htmlFor="when" className="text-sm font-medium">Appointment</label>
      <DatePicker
        id="when"
        className="w-full"
        time
        minuteStep={30}
        min={today}
        disabledWeekdays={[0]}
        booked={bookedDays}
        presets
        value={when}
        onValueChange={setWhen}
        name="startsAt"
      />
      <DatePicker mode="range" presets max={today} value={period} onValueChange={setPeriod} aria-label="Report period" />
    </form>
  )
}
```

### Inline range for a stay, with week numbers

```tsx
<DatePicker inline mode="range" months={2} weekNumbers booked={booked} value={stay} onValueChange={setStay} aria-label="Stay dates" />
```

### Custom presets

```tsx
<DatePicker
  mode="range"
  aria-label="Billing period"
  presets={[
    { label: "This quarter", value: (t) => ({ from: new Date(t.getFullYear(), Math.floor(t.getMonth() / 3) * 3, 1), to: t }) },
    { label: "Year to date", value: (t) => ({ from: new Date(t.getFullYear(), 0, 1), to: t }) },
  ]}
/>
```

### German locale (Monday first, 24.12.2026)

```tsx
<DatePicker
  locale="de-DE"
  aria-label="Rechnungsdatum"
  labels={{ openCalendar: "Kalender öffnen", dialog: "Datum wählen", prevMonth: "Vorheriger Monat", nextMonth: "Nächster Monat", today: "Heute", formatDay: "TT", formatMonth: "MM", formatYear: "JJJJ" }}
/>
```

## API

### DatePicker

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| id | `string` | — | Goes on the text input, so <label htmlFor> works. |
| aria-label | `string` | — | Defines a string value that labels the current element. Names the field or the inline calendar. |
| locale | `string` | — | BCP 47 locale for names, digits, the typed format and the first day of the week. Defaults to the GooduiLocaleProvider language, else en-US. |
| weekStartsOn | `number` | — | 0 = Sunday … 6 = Saturday. Defaults to the locale's first day (Intl.Locale week info), else Monday (Sunday for en-US). |
| min | `Date` | — | Earliest selectable day. |
| max | `Date` | — | Latest selectable day. |
| disabledDays | `Date[] \| ((date: Date) => boolean)` | — | Days that cannot be picked: a list of dates or a test function. |
| disabledWeekdays | `number[]` | — | Weekdays that cannot be picked (0 = Sunday), e.g. [0, 6] for weekends. |
| booked | `Date[] \| ((date: Date) => boolean)` | — | Days shown as booked (struck through) and not pickable. A range cannot span a booked or disabled day. |
| weekNumbers | `boolean` | — | ISO week numbers in a first column. |
| months | `1 \| 2` | — | Months shown side by side. Default: 2 for range on wide screens, else 1. |
| presets | `boolean \| DatePickerPreset[]` | — | true for the built-in presets of the mode, or your own list. |
| time | `boolean` | — | Adds time inputs (single: one, range: start and end). |
| minuteStep | `number` | — | Minute step of the time inputs. |
| inline | `boolean` | — | Render the calendar on the page instead of a field with a popover. |
| placeholder | `string` | — | Field placeholder. Defaults to the locale's format, e.g. MM/DD/YYYY. |
| variant | `"outline" \| "filled" \| "ghost" \| "underline" \| "pill" \| "neo"` | — | Field style and surface: outline (default), filled, ghost, underline, pill or neo. |
| tone | `"primary" \| "neutral" \| "success" \| "warning" \| "danger" \| "info"` | — | Accent for picked days, range band, today dot and focus. |
| selection | `"solid" \| "soft" \| "ring"` | — | How picked days are painted: solid fill, soft tint or ring. |
| shape | `"circle" \| "rounded" \| "square"` | — | Day cell shape. |
| size | `"sm" \| "md" \| "lg"` | — |  |
| shadow | `"none" \| "sm" \| "md" \| "lg"` | — | Surface shadow (popover and inline calendar). |
| animation | `"none" \| "fade" \| "slide" \| "scale"` | — | Popover open and month change: slide (default), fade, scale or none. Reduced motion: fade only. |
| clearable | `boolean` | — | × button in the field. |
| closeOnSelect | `boolean` | — | Close the popover after a full pick (single day, or range end) when there is no time input. |
| disabled | `boolean` | — |  |
| invalid | `boolean` | — |  |
| month | `Date` | — | Displayed month (controlled), any day in it. |
| defaultMonth | `Date` | — |  |
| onMonthChange | `(month: Date) => void` | — |  |
| open | `boolean` | — |  |
| defaultOpen | `boolean` | — |  |
| onOpenChange | `(open: boolean) => void` | — |  |
| name | `string` | — | Hidden input(s) with ISO dates (yyyy-mm-dd, or with time yyyy-mm-ddThh:mm) for form posts. |
| labels | `Partial<DatePickerLabels>` | — | Text for built-in controls and screen readers; pass translations here. |
| mode | `"single"` | — |  |
| value | `Date \| null` | — | to is null while the end is being picked. |
| defaultValue | `Date \| null` | — |  |
| onValueChange | `(value: Date \| null) => void` | — |  |

Also accepts every <div> attribute.

## Keyboard

| Keys | Action |
| --- | --- |
| Arrow Down (before typing) / Alt + Arrow Down | In the text field: opens the calendar with the selected day (or today) focused. |
| Enter (in the field) | Reads the typed date in the locale's order (also ISO 2026-11-24, month names, and an optional time like 2:30 pm). Invalid or blocked dates mark the field invalid and keep the text. |
| Escape (in the field) | Throws away typed text and shows the current value again. |
| Arrow Left / Arrow Right | Previous / next day (mirrored in RTL). Crossing the edge turns the month. |
| Arrow Up / Arrow Down | Same weekday in the previous / next week. |
| Home / End | First / last day of the week (follows weekStartsOn). |
| Page Up / Page Down | Same day in the previous / next month; with Shift, previous / next year. |
| Enter / Space | Picks the focused day (single closes the popover unless time is on; range picks start then end; multiple toggles). |
| Escape | In the month or year grid: back to days. Otherwise closes the popover and returns focus to what opened it. |
| Tab / Shift + Tab | Moves through presets, navigation, the day grid (one tab stop), time and footer, and stays inside the popover dialog. |
| Arrows / Home / End / Enter (month and year grids) | Move by one (left/right) or a row of three (up/down), jump to the ends, pick. |

## Accessibility

- The popover is role="dialog" with aria-modal and keeps focus inside (WAI-ARIA date picker dialog). The calendar button has aria-haspopup="dialog", aria-expanded and aria-controls; focus returns to it (or the field) on close.
- Each month is a role="grid" table labelled by its caption, with weekday column headers (abbr holds the full weekday name). Days are buttons with a full date label such as “Tuesday, November 24, 2026”, plus “Today”, “Booked” or “Unavailable” when they apply; the cell carries aria-selected.
- Roving tabindex: the grid is a single tab stop and arrow keys move a real focus. Disabled and booked days stay focusable (so keyboard users can pass over them) but have aria-disabled and cannot be picked.
- The visible month is announced in a polite live region when it changes. Week numbers are row headers named “Week 47”.
- The text field has no visible label of its own: use aria-label or id with <label htmlFor>. Invalid typed input sets aria-invalid and an alert with labels.invalid.
- Names, digits, weekday headers and the typed format come from Intl for the locale prop; every built-in string is in labels.

## Motion

- slide (default): the popover moves 8px in; changing the month slides the grid 36px toward the direction of travel (mirrored in RTL) with a fade, on a spring (stiffness 420, damping 36, mass 0.7). fade: the popover fades and months crossfade. scale: the popover grows from 0.95 and the month/year grids from 0.94, months slide as in slide.
- The popover closes with a 120 ms fade. The range band follows the pointer (and keyboard focus) as a lighter preview before the end is picked.
- Reduced motion: popover, months and grids only fade (120 ms), and CSS transitions on the field and days are off.

## Performance

- No dependencies: date math uses the Date constructor in local time, and all Intl formatters are created once per locale.
- Grids always have six rows, so switching months never changes the height. The popover mounts only while open.

## Notes for AI

- mode decides the value shape: single → Date | null, range → { from: Date; to: Date | null } | null (to is null while the end is being picked), multiple → Date[].
- Before hydration there is no today: pass min/max/booked that depend on today from state set in useEffect, never from new Date() during render.
- Without time, values are local midnight. With time, the time inputs set hours and minutes on the picked days.
- A range cannot cross a booked or disabled day; clicking past one starts a new range there.
- locale defaults to en-US (not the browser's language) so server and client render the same text; pass the user's locale explicitly.
- name renders hidden ISO inputs: name for single, nameFrom and nameTo for range, one per day for multiple.
- Do not add a date library for formatting; use the locale prop and labels.

## FAQ

**How does typed parsing work?**

The field reads digits in the order the locale writes dates (MM/DD/YYYY for en-US, DD.MM.YYYY for de-DE, YYYY/MM/DD for ja-JP), ISO dates, month names in the locale, two-digit years and an optional trailing time. A missing year uses the current one.

**How is the first day of the week chosen?**

weekStartsOn wins. Otherwise the browser's Intl.Locale week info for the locale is used, with a fallback of Sunday for en-US and similar regions and Monday elsewhere.

**Can it show two months on phones?**

Range mode shows two months from 640px up and one below; set months to force either.

## Related

- input: https://goodui.dev/components/core/input
- select: https://goodui.dev/components/core/select
- combobox: https://goodui.dev/components/core/combobox
- scheduler: https://goodui.dev/r/scheduler.json

Last updated: 2026-11-03

---

# Multi-step Form

> Wizard with numbered, progress-bar or vertical step headers, sync and async per-step validation that blocks Continue and focuses the first invalid field, optional steps with Skip, an auto review step with Edit links, async submit with loading, error retry and success, draft persistence, direction-aware slide or fade transitions and screen-reader step announcements, in card, outline, plain, glass and neo shells with tones and sizes.

Multi-step form (wizard) for React and shadcn: per-step validation, async checks, review step and drafts

Page: https://goodui.dev/components/core/multi-step-form

## Install

```bash
npx shadcn@latest add @goodui/multi-step-form
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/multi-step-form.json`. The file lands in `components/goodui/multi-step-form.tsx`.

## When to use

- Long forms that read better in chapters: booking signups, onboarding, checkout, applications.
- Forms where later questions depend on earlier answers, or where one step needs a server check (email taken, address valid) before going on.
- Flows people leave and come back to: onPersist hands you a snapshot to save as a draft.

## When not to use

- Short forms (under about six fields): one page is faster; use input, select and checkbox directly.
- Showing progress of something the system does (saving, uploading): use multi-step-loader.
- A purely visual progress indicator without a form: use stepper.
- Settings people edit in any order: use tabs with a form per tab.

## Pick by what matters

| Need | Use |
| --- | --- |
| 3–6 short steps | header="numbered" (default) |
| Many steps or narrow cards | header="progress" |
| Long flows on desktop (checkout, applications) | header="vertical" |
| Confirm before sending | review, with fieldLabels or a summary per step |
| Steps people may skip | optional: true on the step |
| Jump around freely | navigation="free" (the current step still validates) |
| Calm transitions | transition="fade" or "none" |

## Usage

```tsx
import { MultiStepForm, type FormStep } from "@/components/goodui/multi-step-form"
import { Input } from "@/components/goodui/input"

type Signup = { name: string; email: string; company: string }

const isEmailFree = async (email: string) => (await fetch("/api/email-free?email=" + encodeURIComponent(email))).ok

const steps: FormStep<Signup>[] = [
  {
    id: "you",
    title: "About you",
    fields: ["name", "email"],
    validate: async (v) => ({
      name: v.name.trim() ? undefined : "Enter your name.",
      email: (await isEmailFree(v.email)) ? undefined : "That email already has an account.",
    }),
    content: ({ values, setValue, error }) => (
      <>
        <Input label="Name" name="name" value={values.name} onValueChange={(s) => setValue("name", s)}
          state={error("name") ? "error" : "default"} message={error("name")} />
        <Input label="Email" name="email" type="email" value={values.email} onValueChange={(s) => setValue("email", s)}
          state={error("email") ? "error" : "default"} message={error("email")} />
      </>
    ),
  },
  {
    id: "company",
    title: "Company",
    optional: true,
    fields: ["company"],
    content: ({ values, setValue }) => <Input label="Company" value={values.company} onValueChange={(s) => setValue("company", s)} />,
  },
]

export function SignupWizard() {
  return (
    <MultiStepForm<Signup>
      steps={steps}
      review
      defaultValues={{ name: "", email: "", company: "" }}
      onSubmit={async (values) => {
        await fetch("/api/signup", { method: "POST", body: JSON.stringify(values) })
      }}
    />
  )
}
```

### Save and restore drafts

```tsx
const [draft, setDraft] = React.useState<MultiStepFormSnapshot<Signup> | null>(null)
React.useEffect(() => {
  const raw = localStorage.getItem("signup-draft")
  if (raw) setDraft(JSON.parse(raw))
}, [])

<MultiStepForm<Signup>
  key={draft ? "draft" : "new"}
  steps={steps}
  defaultValues={draft?.values ?? empty}
  defaultStep={draft?.step}
  defaultCompleted={draft?.completed}
  onPersist={(snap) => localStorage.setItem("signup-draft", JSON.stringify(snap))}
/>
```

### Focus a custom control on error

```tsx
// Select, ToggleGroup and other composite controls: wrap them with data-field so the first
// invalid one gets focus.
<div data-field="plan">
  <ToggleGroup aria-label="Plan" value={values.plan} onValueChange={(p) => setValue("plan", p)} items={plans} />
  {error("plan") && <p className="text-xs text-red-600">{error("plan")}</p>}
</div>
```

### Custom success

```tsx
<MultiStepForm steps={steps} onSubmit={save}
  success={({ values, reset }) => (
    <div className="text-center">
      <p className="font-semibold">Welcome, {values.name}!</p>
      <button onClick={reset}>Add another</button>
    </div>
  )} />
```

## API

### MultiStepForm

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| steps (required) | `FormStep<V>[]` | — |  |
| values | `V` | — | Form values (controlled). |
| defaultValues | `V` | — | Initial values when uncontrolled; also what "Start over" resets to. Pass a saved draft here to restore it. |
| onValuesChange | `(values: V) => void` | — | Called with all values after every change. |
| step | `number` | — | Current step index (controlled). The review step is index steps.length. |
| defaultStep | `number` | `0` | Initial step when uncontrolled, e.g. from a saved draft. |
| onStepChange | `(step: number) => void` | — |  |
| defaultCompleted | `string[]` | — | Step ids already completed or skipped, e.g. from a saved draft (marks them done in the header). |
| review | `boolean` | `false` | Adds a review step that summarizes every step with Edit links. |
| fieldLabels | `Partial<Record<keyof V & string, string>>` | — | Labels for the auto review summary: { email: "Email" }. Unlisted names are humanized. |
| onSubmit | `(values: V) => void \| Promise<void>` | — | Called with all values after every step passed. May be async; a thrown Error's message is shown with a retry. |
| success | `React.ReactNode \| ((ctx: { values: V; reset: () => void }) => React.ReactNode)` | — | Shown after a successful submit. A function gets the values and a reset(). |
| onPersist | `(snapshot: MultiStepFormSnapshot<V>) => void` | — | Called after every value or step change with a serializable snapshot, for saving drafts. |
| navigation | `"linear" \| "free"` | `"linear"` | linear: steps ahead are clickable only once visited. free: any step is clickable (the current one still validates). |
| header | `"numbered" \| "progress" \| "vertical" \| "none"` | `"numbered"` | Step header: numbered circles with connecting lines, a progress bar, a vertical list beside the form, or none. |
| transition | `"slide" \| "fade" \| "none"` | `"slide"` | Panel transition between steps: slide follows the direction (and flips in RTL), fade, or none. |
| variant | `"card" \| "outline" \| "plain" \| "glass" \| "neo"` | `"card"` | Shell: card (default), outline, plain (no box), glass or neo. |
| tone | `"primary" \| "neutral" \| "success" \| "warning" \| "danger" \| "info"` | `"primary"` | Accent of the step header, bar and primary button. |
| size | `"sm" \| "md" \| "lg"` | `"md"` |  |
| shadow | `"none" \| "sm" \| "md" \| "lg"` | `"none"` | Shell shadow. Ignored by neo, which has its own offset shadow. |
| headingAs | `"h2" \| "h3" \| "h4"` | `"h3"` | Heading element for step titles. |
| labels | `Partial<MultiStepFormLabels>` | — | Text for buttons, header and screen readers; pass translations here. |

Also accepts every <form> attribute.

## Keyboard

| Keys | Action |
| --- | --- |
| Enter (in a text field) | Submits the step: validates and moves on, like the primary button. |
| Tab | Through the step header (visited steps), the fields, then Back, Skip and Continue / Submit. |
| Enter / Space on a step in the header | Jumps to that step (back freely; forward only after the current step validates). |

## Accessibility

- Renders a native <form noValidate>; the primary button is type="submit", Back and Skip are type="button".
- The header is a <nav> with an ordered list; the current step has aria-current="step" and each step has a hidden status ("completed", "skipped", "needs attention").
- On every step change a polite live region announces "Step 2 of 4: Contact" and focus moves to the new step's heading, so keyboard and screen-reader users start at the top of the step.
- When validation fails, the live region announces how many fields need attention and focus moves to the first invalid field (found by data-field, then name, then id). Step-level errors and submit errors render with role="alert".
- While an async validator or onSubmit runs, the primary button shows a spinner with aria-busy and the live region says "Checking…" or "Submitting…".
- Every built-in string (buttons, announcements, status words, review texts) goes through labels.

## Motion

- slide: the outgoing step leaves 28px against the direction in 140 ms and the new one enters with a spring (stiffness 420, damping 38); directions flip under dir="rtl".
- fade: opacity with a 6px rise. none: instant.
- Header lines fill over 400 ms as steps complete; the progress bar eases over 450 ms. The default success check pops in with a spring and draws its stroke over 500 ms.
- Reduced motion: step changes are instant and all CSS transitions and animations inside the form are off.

## Performance

- Only the current step is mounted. Validators run on Continue, on header jumps and once more for every non-skipped step on submit, never on keystrokes.
- onPersist runs after every value change; debounce it yourself if it writes to a server.

## Notes for AI

- Type the form: MultiStepForm<Values> with FormStep<Values>[]; setValue is typed per key.
- validate returns nothing when valid, a string for a step-level error, or { field: "message" }. It may be async. Do not throw for validation errors (a thrown Error is shown as a step error).
- Pass errors to fields yourself (Input state="error" message={error("email")}); the wizard does not reach into your inputs.
- List each step's fields in order: they decide which invalid field gets focus and what the auto review shows.
- Any extra <button> inside step content must be type="button", or it submits the step.
- Do not nest another <form> inside a step.
- The review step index is steps.length; controlled step values must account for it.

## FAQ

**Can I use react-hook-form or zod?**

Yes. Keep your values in the wizard (or control them with values + onValuesChange) and call your schema inside validate, returning its field messages as an object.

**What happens if a user jumps ahead with navigation="free" and skips a required step?**

Submit validates every step that was not skipped as optional, jumps back to the first invalid one and focuses its first invalid field.

**Can a step be async on submit only?**

Validators run on Continue and again on submit. If a check is expensive, cache its result in your validator.

## Related

- stepper: https://goodui.dev/components/navigation/stepper
- input: https://goodui.dev/components/core/input
- select: https://goodui.dev/components/core/select
- checkbox: https://goodui.dev/components/core/checkbox
- number-input: https://goodui.dev/components/core/number-input
- toggle-group: https://goodui.dev/components/core/toggle-group
- multi-step-loader: https://goodui.dev/components/feedback/multi-step-loader

Last updated: 2026-11-03

---

# Number Input

> Numeric spinbutton with split, end or stacked steppers, press-and-hold acceleration, min/max/step and large steps, Intl currency, percent and unit formatting over a raw value, arrow, PageUp/PageDown, Home/End and focused-wheel stepping, slide or pop step feedback and an invalid state, in the six input variants with tones, sizes, shapes and shadows.

Number input for React and shadcn: steppers, press-and-hold, currency, percent and unit formatting

Page: https://goodui.dev/components/core/number-input

## Install

```bash
npx shadcn@latest add @goodui/number-input
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/number-input.json`. The file lands in `components/goodui/number-input.tsx`.

## When to use

- Quantities with a sensible range: seats, guests, items in a cart, team size.
- Money, percentages and units that should read formatted ($1,250.00, 15%, 45 minutes) but stay a raw number in state.
- Values people nudge more than type: buffers between bookings, session length in 15-minute steps, discounts in 5% steps.

## When not to use

- Picking a value on a wide continuous range where precision does not matter: use slider-tooltip.
- Codes that only look numeric (PINs, ZIP codes, card numbers): use input or otp-input, they are not quantities.
- Two to five fixed choices (1, 2, 4 guests): use toggle-group so every option is visible.

## Pick by what matters

| Need | Use |
| --- | --- |
| Quantity with big tap targets (mobile, POS) | steppers="split" with shape="pill" |
| Compact form field | steppers="stacked" or "end" (default) |
| Plain typed number | steppers="none" |
| Money | format={{ style: "currency", currency: "EUR" }} and a locale |
| Percent | format={{ style: "percent" }}; the value is a fraction (0.15) |
| Durations and units | format={{ style: "unit", unit: "minute", unitDisplay: "long" }} |
| Keep out-of-range values and flag them | clampOnBlur={false} with message |

## Usage

```tsx
import * as React from "react"
import { NumberInput } from "@/components/goodui/number-input"

export function SeatsField() {
  const [seats, setSeats] = React.useState<number | null>(5)
  const [discount, setDiscount] = React.useState<number | null>(0.1)

  return (
    <div className="grid gap-4 sm:grid-cols-2">
      <NumberInput label="Seats" value={seats} onValueChange={setSeats} min={1} max={250} steppers="split" name="seats" />
      <NumberInput
        label="Discount"
        value={discount}
        onValueChange={setDiscount}
        min={0}
        max={0.5}
        step={0.05}
        format={{ style: "percent" }}
        description="Applied to every seat."
      />
    </div>
  )
}
```

### Currency in a fixed locale

```tsx
<NumberInput
  label="Deposit"
  locale="de-DE"
  format={{ style: "currency", currency: "EUR" }}
  min={0}
  step={50}
  largeStep={500}
  defaultValue={1250}
/>
```

### Flag instead of clamping

```tsx
<NumberInput label="Guests per table" min={1} max={8} clampOnBlur={false} message="Tables seat up to 8 guests." trailing="guests" />
```

### Duration with stacked steppers

```tsx
<NumberInput label="Session length" min={15} max={240} step={15} defaultValue={45} steppers="stacked"
  format={{ style: "unit", unit: "minute", unitDisplay: "long" }} />
```

## API

### NumberInput

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| value | `number \| null` | — | Raw numeric value (controlled); null when empty. Formatting never changes it. |
| defaultValue | `number \| null` | `null` | Initial value when uncontrolled. |
| onValueChange | `(value: number \| null) => void` | — | Called with the raw number (or null) while typing, on every step and when the value is clamped on blur. |
| onChange | `React.ChangeEventHandler<HTMLInputElement>` | — | Native change event of the text field (fires while typing only). |
| min | `number` | — |  |
| max | `number` | — |  |
| step | `number` | `1` | Amount added by a stepper, ↑ / ↓ or the wheel. |
| largeStep | `number` | — | Amount added by PageUp / PageDown and Shift + wheel. Defaults to step × 10. |
| format | `Intl.NumberFormatOptions` | — | Intl.NumberFormat options for the display, e.g. { style: "currency", currency: "EUR" } or { style: "percent" }. Percent values are fractions (0.15 shows as 15%); you type 15 while editing. |
| locale | `string` | — | BCP 47 locale for formatting and parsing. Defaults to the GooduiLocaleProvider language, else the browser's language after mount ("en-US" on the server). |
| clampOnBlur | `boolean` | `true` | Snap out-of-range values back to min / max when the field loses focus. false keeps them and marks the field invalid. |
| holdToRepeat | `boolean` | `true` | Repeat while a stepper is held down, accelerating the longer it is held. |
| wheel | `boolean` | `true` | Step with the mouse wheel while the field has focus. |
| sound | `boolean \| SoundName` | — | Plays a "tick" on every step (a little higher for +, lower for −) when the visitor has sounds on (lib/goodui-sounds); pass a sound name to pick another. Off by default. |
| steppers | `"split" \| "end" \| "stacked" \| "none"` | `"end"` | Stepper buttons: split puts − and + on either side, end groups them after the value, stacked shows ▲ ▼. |
| align | `"start" \| "center" \| "end"` | — | Text alignment of the value. Defaults to center for split steppers, start otherwise. |
| variant | `"outline" \| "filled" \| "underline" \| "ghost" \| "neo" \| "glass"` | `"outline"` | Field style: outline (default), filled, underline, ghost, neo-brutalist or frosted glass. |
| tone | `"primary" \| "neutral" \| "success" \| "warning" \| "danger" \| "info"` | `"primary"` | Focus color and stepper hover color. |
| size | `"sm" \| "md" \| "lg"` | `"md"` |  |
| shape | `"square" \| "rounded" \| "pill"` | `"rounded"` |  |
| shadow | `"none" \| "sm" \| "md" \| "inner"` | `"none"` | Field shadow; inner draws an inset shadow. Ignored by neo, which has its own offset shadow. |
| animation | `"none" \| "ring" \| "glow" \| "lift"` | `"ring"` | How the field reacts to focus. |
| stepAnimation | `"none" \| "slide" \| "pop"` | `"slide"` | How the value reacts to a step: slide (up or down with the direction), pop (scale bump) or none. |
| label | `React.ReactNode` | — | Visible label above the field. |
| description | `React.ReactNode` | — | Helper text under the field (hidden while a message shows). |
| message | `React.ReactNode` | — | Error text under the field; shown when invalid. |
| invalid | `boolean` | — | Red field and aria-invalid. Also set automatically for out-of-range values when clampOnBlur is false. |
| leading | `React.ReactNode` | — | Icon or short text before the value. |
| trailing | `React.ReactNode` | — | Icon or short text after the value (e.g. "guests"). |
| fullWidth | `boolean` | — | Stretch to the container. By default the field is 12rem wide (override with className). |
| fieldClassName | `string` | — | Class for the field box (the root gets className). |
| labels | `Partial<NumberInputLabels>` | — | Text for built-in controls and screen readers; pass translations here. |

Also accepts every <input> attribute.

## Keyboard

| Keys | Action |
| --- | --- |
| ↑ / ↓ | Add or subtract step (Shift: largeStep). |
| PageUp / PageDown | Add or subtract largeStep (default step × 10). |
| Home / End | Jump to min / max, when they are set. |
| Enter | Parses and clamps what you typed (with clampOnBlur); focus stays in the field. |
| Esc | Reverts to the value the field had when it got focus. |
| Mouse wheel | Steps only while the field has focus (Shift + wheel: largeStep), so the page still scrolls. |

## Accessibility

- The field is an <input> with role="spinbutton", aria-valuenow, aria-valuemin, aria-valuemax and aria-valuetext set to the formatted value ("$1,250.00").
- The − and + buttons are out of the tab order (keyboard users have the arrow keys), carry translatable aria-labels and aria-controls pointing at the field, and still step once when activated without a pointer.
- label renders a real <label htmlFor>; without one, pass aria-label. description and message are linked with aria-describedby, and the message region is aria-live.
- invalid (or an out-of-range value with clampOnBlur={false}) sets aria-invalid and the danger color.
- name renders a hidden input with the raw number, so native forms submit 1250, not "1.250,00 €".

## Motion

- Focus: ring (3px tone ring, 200 ms), glow (soft tone halo, 300 ms) or lift (rises 2px). none is static.
- Step: slide moves the value 7px in the step direction and fades it in over 170 ms; pop scales it to 1.09 and back over 220 ms. Both use the Web Animations API on the input, so React does not re-render for them.
- Reduced motion: transitions and the step animation are skipped (checked with matchMedia at step time).

## Performance

- Press-and-hold runs one setTimeout chain (first repeat after 400 ms, then from about 126 ms down to 28 ms between steps) and stops on pointerup, pointercancel, window blur, reaching a bound or unmount.
- Intl.NumberFormat instances are memoized on locale and the format object; pass a stable format object (a constant or useMemo) to avoid rebuilding them on every render.

## Notes for AI

- value and onValueChange are numbers (or null for empty), never strings. Do not parse the display text yourself.
- Percent values are fractions: 0.15 shows as 15% and the user types 15 while editing.
- Without locale the first render uses en-US and switches to the browser language after mount; pass locale when the text must not change after hydration.
- Use format for currency, percent and units; do not put "$" in leading. Use trailing for plain words like "guests".
- onValueChange fires while typing with the unclamped number, then again on blur with the clamped one. Validate on blur or submit, not on every keystroke.
- Layers (variant, tone, size, shape, shadow, animation, stepAnimation, steppers) match the input component, so mixed forms look consistent.

## FAQ

**Why does the field show 1250 while I edit and 1.250,00 € after?**

Editing a formatted string is error-prone, so the focused field shows the plain number in your locale and formats again on blur. The value prop never changes format.

**Can I allow empty?**

Yes. Clearing the field reports null; stepping from empty starts at min (or 0).

**Does it work with react-hook-form?**

Use it as a controlled field (Controller) with value and onValueChange, or pass name for native form submission of the raw number.

## Related

- input: https://goodui.dev/components/core/input
- slider-tooltip: https://goodui.dev/components/inputs/slider-tooltip
- select: https://goodui.dev/components/core/select
- toggle-group: https://goodui.dev/components/core/toggle-group
- multi-step-form: https://goodui.dev/components/core/multi-step-form

Last updated: 2026-11-03

---

# Rating

> Star, heart, circle, bolt, diamond or custom-icon rating in solid, soft, outline, glow and neo styles: half steps, hover preview, clear, animated clip fill with pop or wave, value, count and word labels, read-only exact averages, RTL fill and arrow flipping, with radiogroup or slider semantics.

Star rating for React and shadcn: half stars, hover preview, keyboard and read-only averages

Page: https://goodui.dev/components/core/rating

## Install

```bash
npx shadcn@latest add @goodui/rating
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/rating.json`. The file lands in `components/goodui/rating.tsx`.

## When to use

- Collecting a review after an appointment, order or support chat.
- Showing an average next to a person, product or place (4.7 with 1,284 reviews), including exact fractions.
- Quick satisfaction scores with words per level (Poor … Excellent).

## When not to use

- Scores above 10 points or continuous values: use slider-tooltip or number-input.
- Yes/no feedback (helpful or not): use toggle-group with two items.
- Picking one of a few labeled options: use RadioGroup from checkbox, so every label is visible.

## Pick by what matters

| Need | Use |
| --- | --- |
| Review form | interactive with itemLabels and showLabel, animation="pop" or "wave" |
| Averages in lists and cards | readOnly size="xs" with showValue and count |
| Finer input | precision={0.5} (half steps, slider semantics) |
| Favorites or mood | icon="heart" with tone="danger" |
| Brand icon | icon={<YourIcon />}; lucide icons are filled with CSS |
| Playful brands | variant="neo" or "glow" |

## Usage

```tsx
import * as React from "react"
import { Rating } from "@/components/goodui/rating"

export function ReviewForm() {
  const [score, setScore] = React.useState(0)
  return (
    <form className="flex flex-col gap-3">
      <Rating
        aria-label="Rate your appointment"
        value={score}
        onValueChange={setScore}
        size="lg"
        itemLabels={["Poor", "Fair", "Good", "Great", "Excellent"]}
        showLabel
        name="score"
      />
      <button disabled={!score}>Send review</button>
    </form>
  )
}
```

### Read-only average with count

```tsx
<Rating value={4.7} readOnly size="xs" showValue count={1284} />
```

### Half steps

```tsx
<Rating defaultValue={3.5} precision={0.5} showValue variant="glow" aria-label="Product quality" />
```

### Translated labels

```tsx
<Rating
  labels={{
    group: "Bewertung",
    item: (n) => `${n} Sterne`,
    readOnly: (v, max) => `Bewertet mit ${v} von ${max}`,
    countSr: (c) => `${c} Bewertungen`,
  }}
/>
```

## API

### Rating

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| value | `number` | — | Current rating (controlled); 0 means no rating. |
| defaultValue | `number` | `0` | Initial rating when uncontrolled. |
| onValueChange | `(value: number) => void` | — | Called with the new rating; 0 after clearing. |
| max | `number` | `5` | Number of icons. |
| precision | `1 \| 0.5` | `1` | 1 for whole icons (radiogroup), 0.5 for half steps (slider). |
| readOnly | `boolean` | — | Display only: no hover or focus, shows exact fractions. |
| disabled | `boolean` | — |  |
| clearable | `boolean` | `true` | Picking the current value again, Backspace, Delete or 0 clears the rating. |
| hoverPreview | `boolean` | `true` | Fill previews under the pointer before you click. |
| sound | `boolean \| SoundName` | — | Plays a "tick" per icon under the pointer (pitched up along the row) and a "pop" on pick, when the visitor has sounds on (lib/goodui-sounds); a sound name replaces the pop. Off by default. |
| icon | `RatingIcon \| React.ReactNode` | `"star"` | Built-in icon name, or your own icon node (a lucide icon works: it gets filled with CSS). |
| emptyIcon | `React.ReactNode` | — | Different icon for the empty state; defaults to `icon`. |
| variant | `"solid" \| "soft" \| "outline" \| "glow" \| "neo"` | `"solid"` | How icons are painted: solid (default), soft (tinted empties), outline (stroked empties), glow, or neo. |
| tone | `"primary" \| "neutral" \| "success" \| "warning" \| "danger" \| "info"` | `"warning"` | Fill color. Defaults to warning, the classic gold. |
| size | `"xs" \| "sm" \| "md" \| "lg" \| "xl"` | `"md"` |  |
| animation | `"none" \| "fill" \| "pop" \| "wave"` | `"pop"` | What moves when the rating changes. Reduced motion turns all of it off. |
| showValue | `boolean` | — | Shows the number ("4.5") after the icons. |
| count | `number` | — | Review count shown after the value, e.g. 1284 → "(1,284)". |
| itemLabels | `string[]` | — | Word per icon ("Poor" … "Excellent"); read with the radios and shown when showLabel is set. |
| showLabel | `boolean` | — | Shows the word for the current or hovered value after the icons. |
| name | `string` | — | Form field name (renders a hidden input with the number). |
| iconsClassName | `string` | — | Class for the icon row. |
| labels | `Partial<RatingLabels>` | — | Text for screen readers and the count; pass translations here. |

Also accepts every <div> attribute.

## Keyboard

| Keys | Action |
| --- | --- |
| → / ↑ | Raise by one step (← in RTL). |
| ← / ↓ | Lower by one step (→ in RTL); reaches 0 only when clearable. |
| Home / End | Lowest step / max. |
| 1 – 9 | Set that rating directly. |
| 0 / Backspace / Delete | Clear the rating (clearable). |
| Space / Enter | Whole steps: pick the focused icon (again clears it when clearable). |
| Tab | One tab stop for the whole control (roving tabindex). |

## Accessibility

- Whole steps render role="radiogroup" with one role="radio" per icon, aria-checked, roving tabindex and names like "4 stars, Great".
- Half steps render one role="slider" with aria-valuenow and aria-valuetext ("3.5 out of 5"), since a radio per half icon reads badly.
- readOnly renders role="img" named "Rated 4.7 out of 5"; the visible count is hidden from screen readers and replaced by "1,284 reviews".
- Pass aria-label or aria-labelledby to say what is being rated; the default name is "Rating". Every built-in string goes through labels.
- name renders a hidden input with the number for native forms.

## Motion

- fill: the icon fill grows from the inline start with a clip-path transition (280 ms), also while previewing on hover.
- pop: fill plus the picked icon springs to 1.32× with a slight tilt and back (320 ms). wave: every filled icon pops in turn, 55 ms apart.
- The hovered icon scales to 1.14 (180 ms). none is static.
- Reduced motion: transitions, hover scale and pops are off; values still update instantly.

## Performance

- Pops use the Web Animations API on the icon elements, so they cost no React renders. Read-only ratings attach no pointer or keyboard handlers.

## Notes for AI

- value is a number from 0 to max; 0 means no rating. onValueChange receives 0 after clearing.
- Use readOnly for averages; it shows exact fractions (4.3 fills 30% of the fifth star) regardless of precision.
- precision is 1 or 0.5 only.
- Pass icon as a name (star, heart, circle, bolt, diamond) or a node; do not draw your own stars around it.
- Use tone for color (warning is the classic gold default); do not wrap it in a text color class.

## FAQ

**Does the fill follow right-to-left layouts?**

Yes. The fill grows from the inline start, so under dir="rtl" it runs right to left, half clicks use the right half as the lower value, and the arrow keys flip.

**Can I use emoji or my own SVG?**

Any React node works as icon. SVGs are filled through CSS fill and stroke, so single-color icons look right; multi-color emoji only clip, they do not recolor.

## Related

- toggle-group: https://goodui.dev/components/core/toggle-group
- checkbox: https://goodui.dev/components/core/checkbox
- slider-tooltip: https://goodui.dev/components/inputs/slider-tooltip
- number-input: https://goodui.dev/components/core/number-input
- stat-card: https://goodui.dev/components/core/stat-card

Last updated: 2026-11-03

---

# Toggle Group

> Single (radiogroup) or multiple (aria-pressed) toggle buttons in outline, soft, solid, segmented, neo and glass styles with a sliding, fading or popping active marker, text or icon items, tones, sizes, shapes, shadows, attached or spaced, vertical, full width, disabled items and roving arrow-key focus that flips in RTL.

Toggle group and segmented control for React and shadcn: single or multiple, sliding indicator, keyboard

Page: https://goodui.dev/components/core/toggle-group

## Install

```bash
npx shadcn@latest add @goodui/toggle-group
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/toggle-group.json`. The file lands in `components/goodui/toggle-group.tsx`.

## When to use

- Switching a view or mode in place: Day / Week / Month, list / grid, monthly / yearly billing.
- Picking one of two to five short options that should all stay visible (single).
- Turning several independent options on and off in one row: working days, filters, text formatting (multiple).

## When not to use

- Switching between panels of content: use tabs, which wires tabpanels and aria-controls.
- More than about six options or long labels: use select.
- A single on/off setting: use switch.
- Navigation between pages: use links.

## Pick by what matters

| Need | Use |
| --- | --- |
| iOS-style segmented control | variant="segmented" (or "solid" for a filled marker) |
| Toolbar of joined buttons | variant="outline" (attached by default) |
| Light filter chips | variant="soft" shape="pill" |
| Several values | type="multiple" (aria-pressed buttons) |
| Icon-only buttons | items with icon and aria-label (title adds a tooltip) |
| On photos or gradients | variant="glass" |
| Playful or retro brands | variant="neo"; attached={false} spaces the buttons |

## Usage

```tsx
import * as React from "react"
import { CalendarDays, CalendarRange, LayoutList } from "lucide-react"
import { ToggleGroup, ToggleGroupItem } from "@/components/goodui/toggle-group"

export function CalendarToolbar() {
  const [view, setView] = React.useState<string | null>("week")
  const [days, setDays] = React.useState<string[]>(["Mon", "Tue", "Wed"])

  return (
    <div className="flex flex-wrap gap-4">
      <ToggleGroup
        aria-label="Calendar view"
        variant="segmented"
        value={view}
        onValueChange={setView}
        items={[
          { value: "day", label: "Day", icon: <CalendarDays /> },
          { value: "week", label: "Week", icon: <CalendarRange /> },
          { value: "agenda", label: "Agenda", icon: <LayoutList /> },
        ]}
      />
      <ToggleGroup type="multiple" aria-label="Working days" value={days} onValueChange={setDays}>
        {["Mon", "Tue", "Wed", "Thu", "Fri"].map((d) => (
          <ToggleGroupItem key={d} value={d}>
            {d}
          </ToggleGroupItem>
        ))}
      </ToggleGroup>
    </div>
  )
}
```

### Billing period

```tsx
<ToggleGroup variant="segmented" shape="pill" aria-label="Billing period" defaultValue="yearly"
  items={[{ value: "monthly", label: "Monthly" }, { value: "yearly", label: "Yearly −20%" }]} />
```

### Icon-only layout switch

```tsx
<ToggleGroup variant="outline" tone="neutral" size="sm" aria-label="Layout" defaultValue="list"
  items={[
    { value: "list", icon: <List />, "aria-label": "List", title: "List" },
    { value: "grid", icon: <LayoutGrid />, "aria-label": "Grid", title: "Grid" },
  ]} />
```

### Clearable single choice

```tsx
<ToggleGroup deselectable aria-label="Reminder" items={[{ value: "sms", label: "SMS" }, { value: "email", label: "Email" }]} />
```

## API

### ToggleGroup

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| items | `ToggleGroupOption[]` | — | Shortcut: renders a ToggleGroupItem per option. Or pass <ToggleGroupItem> children. |
| variant | `"outline" \| "soft" \| "solid" \| "segmented" \| "neo" \| "glass"` | — | How the group is painted. outline and neo draw joined buttons; soft, solid, segmented and glass sit in a track. |
| tone | `"primary" \| "neutral" \| "success" \| "warning" \| "danger" \| "info"` | — | Color of the active item. |
| size | `"sm" \| "md" \| "lg"` | — |  |
| shape | `"square" \| "rounded" \| "pill"` | — |  |
| shadow | `"none" \| "sm" \| "md" \| "glow"` | — | Group shadow; glow puts a tone-colored glow under the active marker instead. |
| animation | `"none" \| "slide" \| "fade" \| "pop"` | — | slide glides one marker between items (single only; multiple falls back to fade). Reduced motion snaps. |
| orientation | `"horizontal" \| "vertical"` | — |  |
| attached | `boolean` | — | outline and neo: buttons share borders in one box. false spaces them apart. |
| fullWidth | `boolean` | — | Items share the full width equally. |
| disabled | `boolean` | — | Disables every item. |
| name | `string` | — | Form field name (renders hidden inputs with the selected values). |
| type | `"single"` | — | single: one value (a radiogroup). multiple: any number (each item has aria-pressed). |
| value | `string \| null` | — | Selected value (controlled): a string or null; string[] with type="multiple". |
| defaultValue | `string \| null` | — | Initial value when uncontrolled. |
| onValueChange | `(value: string \| null) => void` | — | Called with the new value (string \| null, or string[] with type="multiple"). |
| deselectable | `boolean` | — | single: clicking the active item clears the value. |

Also accepts every <div> attribute.

### ToggleGroupItem

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| value (required) | `string` | — | Value reported to the group. |
| icon | `React.ReactNode` | — | Icon before the label; with no label the item becomes square (pass aria-label). |

Also accepts every <button> attribute.

## Keyboard

| Keys | Action |
| --- | --- |
| Tab | Enters the group on the selected item (single) or the last focused item (multiple); one tab stop. |
| → / ↓ | Next enabled item, wrapping (← in RTL). In single mode it also selects it. |
| ← / ↑ | Previous enabled item, wrapping (→ in RTL). In single mode it also selects it. |
| Home / End | First / last enabled item. |
| Space / Enter | Toggles the focused item (multiple) or selects it (single; clears it with deselectable). |

## Accessibility

- type="single" renders role="radiogroup" with role="radio" items and aria-checked (the radio pattern: arrows move and select).
- type="multiple" renders role="group" with native buttons and aria-pressed; arrows only move focus.
- Give the group a name with aria-label or aria-labelledby. Icon-only items need an aria-label; the icon is decorative.
- Disabled items are skipped by the arrow keys and keep the native disabled attribute.
- name renders hidden inputs with the selected values for native forms.

## Motion

- slide (single): one marker glides between items with a motion layout spring (stiffness 520, damping 40) and keeps its corner radius while it stretches.
- fade: the marker fades and scales in from 0.94 over 200 ms. pop: it springs in from 0.6 over 340 ms. Both run only after the first interaction.
- Items scale to 0.96 while pressed (neo moves into its shadow instead). none is static.
- Reduced motion: the marker snaps (no layout animation), and press, fade and pop are off.

## Performance

- The roving tab stop is computed from the DOM after each render without extra renders unless it changes. Multiple mode never uses layout animations.

## Notes for AI

- value is a string (or null) for single and string[] for type="multiple"; onValueChange matches.
- Use items for simple lists; use ToggleGroupItem children when you need custom content per item.
- Do not use it to show different content panels; that is tabs.
- Single mode cannot be emptied by clicking unless deselectable is set, like radio buttons.
- variant, tone, size, shape, shadow, animation, orientation and attached are independent layers; combine them instead of adding color classes.

## FAQ

**Radio semantics or aria-pressed?**

Single uses the radio pattern because exactly one value is chosen; multiple uses aria-pressed toggle buttons because each item is independent. Both follow the WAI-ARIA APG patterns.

**Why is my marker not sliding?**

The sliding marker is single-mode only and turns off with reduced motion. Multiple mode fades or pops each active item.

## Related

- tabs: https://goodui.dev/components/core/tabs
- button: https://goodui.dev/components/core/button
- select: https://goodui.dev/components/core/select
- switch: https://goodui.dev/components/core/switch
- checkbox: https://goodui.dev/components/core/checkbox

Last updated: 2026-11-03

---

# Table

> Lined, striped, bordered, card-row and minimal tables with tones, three densities, shadows and corner shapes, tint, accent-bar or lift hover, row state tones and selection, sortable headers with aria-sort, sticky header, caption, footer totals, skeleton and empty states, fade or stagger entrances, and rows that stack into labelled cards on small containers.

Beautiful React table for shadcn: striped, bordered or card rows, sticky header, row states and mobile stacking

Page: https://goodui.dev/components/core/table

## Install

```bash
npx shadcn@latest add @goodui/table
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/table.json`. The file lands in `components/goodui/table.tsx`.

## When to use

- Showing a small or medium static list: invoices, a team, today's schedule, plan comparisons.
- Rows that carry a state: overdue invoices tinted red, drafts grey (rowTone or TableRow tone).
- Simple client-side sorting by clicking headers, with an accessible sort button and aria-sort.
- Tables that must stay readable on phones: stack turns rows into label/value cards below a container width.

## When not to use

- Thousands of rows, inline editing, filters, column resizing or export: use data-grid.
- A list of items with avatars and actions and no columns to compare: use a list or card layout.
- Key figures at a glance: use stat-card.

## Pick by what matters

| Need | Use |
| --- | --- |
| Default app table | variant="lined" (default) |
| Long rows that are hard to follow | variant="striped" |
| Dense comparisons, spreadsheets-like | variant="bordered" density="compact" |
| Rows that feel like separate items (team, bookings) | variant="cards" hover="lift" |
| Inside a card that already has a border | variant="minimal" |
| Status per row | rowTone with columns + data, or tone on TableRow |
| Long tables | stickyHeader with maxHeight |
| Phones | stack="md" plus primary on the title column |

## Usage

```tsx
import { Table, type TableColumn } from "@/components/goodui/table"

type Invoice = { id: string; client: string; due: string; amount: number; status: "paid" | "overdue" }

const columns: TableColumn<Invoice>[] = [
  { key: "id", header: "Invoice", primary: true },
  { key: "client", header: "Client", sortable: true },
  { key: "due", header: "Due" },
  {
    key: "amount",
    header: "Amount",
    numeric: true,
    sortable: true,
    render: (r) => r.amount.toLocaleString("en-US", { style: "currency", currency: "USD" }),
  },
]

export function Invoices({ invoices }: { invoices: Invoice[] }) {
  return (
    <Table
      aria-label="Invoices"
      columns={columns}
      data={invoices}
      rowTone={(r) => (r.status === "overdue" ? "danger" : "none")}
      stack="md"
      caption="October invoices"
    />
  )
}
```

### Parts, like a plain <table>

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

<Table variant="striped" density="compact" aria-label="Schedule">
  <TableHeader>
    <TableRow>
      <TableHead>Time</TableHead>
      <TableHead>Client</TableHead>
      <TableHead numeric>Price</TableHead>
    </TableRow>
  </TableHeader>
  <TableBody>
    <TableRow tone="info">
      <TableCell label="Time">09:30</TableCell>
      <TableCell label="Client">Omar D.</TableCell>
      <TableCell label="Price" numeric>$40</TableCell>
    </TableRow>
  </TableBody>
</Table>
```

### Controlled sort (you sort the data)

```tsx
const [sort, setSort] = React.useState<TableSort | null>({ key: "rating", direction: "desc" })
const rows = React.useMemo(() => sortTeam(team, sort), [team, sort])

<Table columns={columns} data={rows} sort={sort} onSortChange={setSort} variant="cards" hover="lift" />
```

### Clickable, selectable rows

```tsx
<Table
  columns={columns}
  data={team}
  selectedKeys={picked}
  onRowClick={(r) => togglePicked(r.id)}
  aria-label="Team"
/>
```

## API

### Table

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| variant | `"lined" \| "striped" \| "bordered" \| "cards" \| "minimal"` | `"lined"` | lined (default), striped, bordered (every cell), cards (each row a separate card) or minimal (no frame). |
| tone | `"primary" \| "neutral" \| "success" \| "warning" \| "danger" \| "info"` | `"primary"` | Accent for the sort arrow, selected rows, the accent hover bar and focus rings. |
| density | `"compact" \| "normal" \| "relaxed"` | `"normal"` | Cell padding and text size. |
| shadow | `"none" \| "sm" \| "md" \| "lg"` | `"none"` | Frame shadow. Ignored by minimal. |
| shape | `"square" \| "rounded" \| "soft"` | `"rounded"` | Corner radius of the frame (and of each row in cards). |
| animation | `"none" \| "fade" \| "stagger"` | `"none"` | fade or stagger rows in on mount; remount (change key) to replay. |
| hover | `"none" \| "tint" \| "accent" \| "lift"` | `"tint"` | Row hover style. |
| stack | `"never" \| "sm" \| "md" \| "lg"` | `"never"` | Below this container width (sm 480px, md 640px, lg 768px) rows turn into cards with a label per value. |
| stickyHeader | `boolean` | `false` | Keeps the header visible while scrolling. With maxHeight it sticks inside the table's own scroll box. |
| maxHeight | `number \| string` | — | Makes the table scroll inside a box of this height (px number or CSS length). |
| caption | `React.ReactNode` | — |  |
| captionSide | `"top" \| "bottom"` | `"bottom"` |  |
| columns | `TableColumn<T>[]` | — | Columns for the data shorthand. With children, columns and data are ignored. |
| data | `T[]` | — |  |
| rowKey | `(row: T, index: number) => string` | — | Stable key per row; defaults to row.id, then the index. |
| rowTone | `(row: T, index: number) => TableRowTone \| undefined` | — | State color per row: a tinted background and a start-edge marker. |
| selectedKeys | `string[]` | — | Keys of rows drawn as selected. |
| onRowClick | `(row: T, index: number) => void` | — | Makes rows clickable and focusable (Enter or Space activates). |
| sort | `TableSort \| null` | — | Sort (controlled). null means unsorted. |
| defaultSort | `TableSort \| null` | `null` |  |
| onSortChange | `(sort: TableSort \| null) => void` | — | Called when a sortable header is clicked: asc, desc, then unsorted. With sort controlled, sort the data yourself. |
| loading | `boolean` | `false` | Shows skeleton rows instead of data. |
| loadingRows | `number` | `4` | Number of skeleton rows. |
| empty | `React.ReactNode` | — | Replaces the default empty text. |
| tableClassName | `string` | — | Classes for the inner <table>. className goes on the outer frame. |
| children | `React.ReactNode` | — | Parts, for full control of the markup. |
| labels | `Partial<TableLabels>` | — | Text for built-in controls and screen readers; pass translations here. |

Also accepts every <table> attribute.

### TableHeader

Also accepts every <thead> attribute.

### TableBody

Also accepts every <tbody> attribute.

### TableFooter

Also accepts every <tfoot> attribute.

### TableRow

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| tone | `"none" \| TableTone` | — | State color: tinted background and a start-edge marker (paid, overdue, pending…). |
| selected | `boolean` | — | Draws the row as selected (tone tint + marker) and sets aria-selected. |

Also accepts every <tr> attribute.

### TableHead

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| align | `"start" \| "center" \| "end"` | — |  |
| numeric | `boolean` | — | End-aligned tabular figures. |
| sortable | `boolean` | — | Wraps the header text in a sort button with an arrow. |
| sort | `TableSortDirection \| false` | — | Current direction for this column, or false when unsorted. |
| onSort | `() => void` | — |  |

Also accepts every <th> attribute.

### TableCell

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| align | `"start" \| "center" \| "end"` | — |  |
| numeric | `boolean` | — |  |
| label | `string` | — | Label shown before the value when rows are stacked as cards. |
| primary | `boolean` | — | In stacked mode this cell is the card title. |
| hideWhenStacked | `boolean` | — | Hidden when rows are stacked as cards. |

Also accepts every <td> attribute.

### TableCaption

Also accepts every <caption> attribute.

## Keyboard

| Keys | Action |
| --- | --- |
| Tab | Moves through sort buttons in the header and, when onRowClick is set, through the rows. |
| Enter / Space | On a sort button: asc, desc, then unsorted. On a clickable row: calls onRowClick. |
| Arrow keys | When the table scrolls (maxHeight, or wider than its container), Tab focuses the scroll box and arrows scroll it. |

## Accessibility

- It renders a real <table> with <th scope="col">, so screen readers announce headers with each cell. Pass aria-label or a caption to name it.
- Sortable headers are <button>s inside the <th>; the <th> gets aria-sort (ascending or descending) and the button reads ", sorted ascending" (labels.sortedAscending / sortedDescending).
- Selected rows get aria-selected. Row tones are color plus a start-edge bar; also show the state as text (a badge) so it does not rely on color alone.
- When stack is set, explicit table, rowgroup, row, columnheader and cell roles are added, because display:block can drop table semantics in some browsers. Stacked cells show their column label from data-label (columns: label or header text; parts: the label prop).
- Loading shows skeleton rows with a visually hidden "Loading" (labels.loading) and aria-busy on the body; the empty state text comes from empty or labels.empty.
- When the table can scroll (maxHeight, or wider than its container), the scroll box becomes a focusable role="region" named by the caption, the table's aria-label or labels.scrollRegion, so keyboard users can scroll it.

## Motion

- fade: body rows fade in over 350 ms on mount. stagger: rows rise 6px and fade in over 400 ms, 35 ms apart, capped at the 13th row (455 ms). Remount (change key) to replay.
- hover lift moves the row up 1px over 180 ms; tint and accent change the background; the sort arrow turns 180° in 200 ms between ascending and descending.
- Reduced motion: entrances, transitions and the lift are off, and the skeleton shimmer stops.

## Performance

- Pure CSS for every layer (one shared <style> tag). The only measurement is one ResizeObserver that checks horizontal overflow to make the scroll box focusable. Sorting with columns + data is a stable in-memory sort with Intl.Collator (numeric, case-insensitive).
- It renders every row. For hundreds of rows or more, use data-grid, which virtualizes.

## Notes for AI

- Two APIs: columns + data (sorting, empty, loading, footer, stacking labels handled for you) or the parts (Table, TableHeader, TableBody, TableFooter, TableRow, TableHead, TableCell, TableCaption). With children, columns and data are ignored.
- Column objects: { key, header, label?, accessor?, render?, sortValue?, sortable?, align?, numeric?, width?, footer?, primary?, hideWhenStacked?, className? }. key is also the property read from each row.
- With sort controlled (sort + onSortChange) the table does not sort data; sort it yourself. Uncontrolled (defaultSort) sorts for you; empty values stay last.
- className goes on the outer frame; tableClassName and other props go on the <table>. stickyHeader sticks to the page unless maxHeight makes the table its own scroll box.
- Row keys default to row.id, then the index; pass rowKey when ids are missing. Do not invent props like pagination or filters: use data-grid.

## FAQ

**How do I make it work on mobile?**

Set stack="sm", "md" or "lg". Below 480, 640 or 768px of container width (a container query, so it reacts to the table's own width, not the viewport) each row becomes a card with a label before every value. Mark the title column primary and hide minor ones with hideWhenStacked.

**Can I use it with server-side sorting?**

Yes: pass sort and onSortChange, fetch sorted data in the handler, and pass the result as data.

## Related

- data-grid: https://goodui.dev/components/core/data-grid
- pagination: https://goodui.dev/components/core/pagination
- badge: https://goodui.dev/components/core/badge
- avatar: https://goodui.dev/components/core/avatar
- stat-card: https://goodui.dev/components/core/stat-card

Last updated: 2026-11-03

---

# Data Grid

> Virtualized data grid for 100k+ rows with typed columns (number, currency, percent, date, boolean, badge, avatar, actions) formatted by Intl, multi-sort, per-column filters and global search, resize, drag reorder, pin, hide, Shift-range selection with a bulk action bar, inline editing with sync or async validation, spreadsheet keyboard navigation, expandable rows, footer aggregates, CSV and real .xlsx export, loading, empty and error states, server mode with pagination, RTL and tones, densities and variants.

React data grid for shadcn with 100k-row virtualization, inline editing, filters and real Excel export

Page: https://goodui.dev/components/core/data-grid

## Install

```bash
npx shadcn@latest add @goodui/data-grid
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/data-grid.json`. The file lands in `components/goodui/data-grid.tsx`.

## When to use

- Large lists people work in: bookings, orders, invoices, clients, with thousands to 100,000+ rows in one scroll.
- Spreadsheet-like work: inline editing with validation, keyboard navigation, bulk actions on selected rows.
- Back-office views that need per-column filters, global search, multi-sort, column resize/reorder/pin/hide and CSV or .xlsx export.
- Server-backed lists: mode="server" reports sort, filters, search and page in one onQueryChange.

## When not to use

- A short static table (an invoice, a pricing comparison, a team of five): use table, which is lighter and fully semantic.
- Rows that are really cards with free layout: use a list or cards.
- Pivoting, grouping rows by column or charts inside the grid: not built in.

## Pick by what matters

| Need | Use |
| --- | --- |
| Default app grid | variant="lined" density="normal" |
| Very long rows | variant="striped" |
| Spreadsheet feel | variant="bordered" density="compact" |
| Inside a card | variant="minimal" shadow="none" |
| Many rows in one scroll | client mode (default): virtualized, no pagination needed |
| Page-by-page in the browser | pagination |
| Rows live on the server | mode="server" with rowCount and onQueryChange |
| Calm UI | animation="fade" (default) or "none"; "spring" adds row glides and an edit flash |

## Usage

```tsx
import * as React from "react"
import { Bell } from "lucide-react"
import { DataGrid, type DataGridColumn } from "@/components/goodui/data-grid"

type Booking = { id: string; client: string; status: string; date: string; price: number; deposit: boolean }

export function Bookings({ initial }: { initial: Booking[] }) {
  const [rows, setRows] = React.useState(initial)

  // Keep columns stable (useMemo or module scope): the grid caches sort keys and the search index per columns + data.
  const columns = React.useMemo<DataGridColumn<Booking>[]>(
    () => [
      { id: "client", header: "Client", type: "avatar", pin: "start", aggregate: "count" },
      {
        id: "status",
        header: "Status",
        type: "badge",
        editable: true,
        options: [
          { value: "confirmed", label: "Confirmed", tone: "success" },
          { value: "pending", label: "Pending", tone: "warning" },
        ],
      },
      { id: "date", header: "Date", type: "date", editable: true },
      {
        id: "price",
        header: "Price",
        type: "currency",
        editable: true,
        aggregate: "sum",
        validate: (v) => (typeof v === "number" && v > 0 ? null : "Price must be above $0"),
      },
      { id: "deposit", header: "Deposit", type: "boolean", editable: true },
      { id: "actions", header: "", type: "actions", pin: "end", actions: [{ label: "Remind", icon: <Bell />, onClick: (b) => remind(b) }] },
    ],
    [],
  )

  return (
    <DataGrid
      aria-label="Bookings"
      columns={columns}
      data={rows}
      selectable
      exportFileName="bookings"
      onCellEdit={({ rowKey, columnId, value }) =>
        setRows((r) => r.map((b) => (b.id === rowKey ? { ...b, [columnId]: value } : b)))
      }
    />
  )
}
```

### Server mode with pagination

```tsx
const [query, setQuery] = React.useState<DataGridQuery>({ sort: [], filters: {}, search: "", page: 1, pageSize: 25 })
const { rows, total, loading, error, refetch } = useInvoices(query)

<DataGrid
  aria-label="Invoices"
  mode="server"
  columns={columns}
  data={rows}
  rowCount={total}
  loading={loading}
  error={error}
  onRetry={refetch}
  sort={query.sort}
  filters={query.filters}
  page={query.page}
  pageSize={query.pageSize}
  onQueryChange={setQuery}
/>
```

### Async save with a server error

```tsx
<DataGrid
  columns={columns}
  data={rows}
  onCellEdit={async ({ rowKey, columnId, value }) => {
    const res = await fetch(`/api/bookings/${rowKey}`, { method: "PATCH", body: JSON.stringify({ [columnId]: value }) })
    if (!res.ok) return "Couldn't save, try again" // shown under the cell, editor stays open
    setRows((r) => r.map((b) => (b.id === rowKey ? { ...b, [columnId]: value } : b)))
  }}
/>
```

### Bulk actions and expandable rows

```tsx
<DataGrid
  columns={columns}
  data={rows}
  selectable
  bulkActions={[
    { label: "Confirm", onClick: (_rows, keys) => confirmMany(keys) },
    { label: "Cancel", tone: "danger", onClick: (_rows, keys) => cancelMany(keys) },
  ]}
  renderExpanded={(b) => <BookingNotes booking={b} />}
/>
```

### Export helpers on their own

```tsx
import { buildCsv, buildXlsx, downloadFile } from "@/components/goodui/data-grid"

const bytes = buildXlsx(
  [{ header: "Client", width: 24 }, { header: "Amount", format: '"$"#,##0.00' }, { header: "Due", format: "yyyy-mm-dd" }],
  invoices.map((i) => [i.client, i.amount, new Date(i.due)]),
  "Invoices",
)
downloadFile(bytes, "invoices.xlsx", "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet")
```

## API

### DataGrid

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| columns (required) | `DataGridColumn<T>[]` | — |  |
| data (required) | `T[]` | — | Rows. In server mode: the current page. |
| aria-label | `string` | — | Defines a string value that labels the current element. Names the grid. |
| getRowId | `(row: T, index: number) => string` | — | Stable key per row; defaults to row.id, then the index. |
| variant | `"lined" \| "striped" \| "bordered" \| "minimal"` | `"lined"` | lined (default), striped, bordered or minimal (no frame). |
| tone | `"primary" \| "neutral" \| "success" \| "warning" \| "danger" \| "info"` | `"primary"` | Accent for sort arrows, selection, focus ring, chips and edits. |
| density | `"compact" \| "normal" \| "relaxed"` | `"normal"` | Row height and cell padding: compact 34px, normal 42px, relaxed 54px. |
| shadow | `"none" \| "sm" \| "md" \| "lg"` | `"sm"` | Frame shadow. Ignored by minimal. |
| shape | `"square" \| "rounded" \| "soft"` | `"rounded"` | Frame corner radius. |
| animation | `"none" \| "fade" \| "spring"` | `"fade"` | fade: menus and bulk bar fade. spring: they spring in, rows glide to new positions and edited cells flash. none: static. |
| height | `number \| string` | `480` | Maximum height of the scroll area (px number or CSS length). Shorter data shrinks the grid. |
| rowHeight | `number` | — | Overrides the density's row height (px). |
| locale | `string` | — | BCP 47 locale for Intl number and date formatting. Defaults to the GooduiLocaleProvider language, else en-US. |
| currency | `string` | `"USD"` | Default ISO currency for currency columns. |
| timeZone | `string` | — | Time zone for datetime columns (date-only values are always local calendar days). |
| rowTone | `(row: T) => DataGridRowTone \| undefined` | — | State color per row: tinted background and a start-edge marker. |
| toolbar | `boolean` | `true` | Shows the toolbar (search, filter chips, Columns, Export). |
| toolbarExtra | `React.ReactNode` | — | Extra toolbar content, placed before Columns and Export. |
| searchable | `boolean` | `true` |  |
| exportable | `boolean` | `true` |  |
| exportFileName | `string` | `"export"` | File name without extension. |
| columnMenu | `boolean` | `true` | Per-column menu with filter, sort, pin, move and hide. |
| showStatus | `boolean` | `true` | Row count line under the grid. |
| selectable | `boolean` | `false` | Adds a checkbox column. |
| selectedKeys | `string[]` | — |  |
| defaultSelectedKeys | `string[]` | `NO_KEYS` |  |
| onSelectionChange | `(keys: string[]) => void` | — |  |
| bulkActions | `DataGridBulkAction<T>[]` | — | Buttons in the floating bar shown while rows are selected. |
| sort | `DataGridSort[]` | — |  |
| defaultSort | `DataGridSort[]` | `NO_SORT` |  |
| onSortChange | `(sort: DataGridSort[]) => void` | — |  |
| filters | `DataGridFilters` | — |  |
| defaultFilters | `DataGridFilters` | `NO_FILTERS` |  |
| onFiltersChange | `(filters: DataGridFilters) => void` | — |  |
| search | `string` | — |  |
| defaultSearch | `string` | `""` |  |
| onSearchChange | `(search: string) => void` | — |  |
| columnState | `Partial<DataGridColumnState>` | — | Column order, widths, pins and hidden ids (controlled). Missing parts fall back to the column definitions. |
| defaultColumnState | `Partial<DataGridColumnState>` | `NO_STATE` |  |
| onColumnStateChange | `(state: DataGridColumnState) => void` | — |  |
| renderExpanded | `(row: T) => React.ReactNode` | — | Content of a row's expanded detail panel; adds an expand column. |
| expandedKeys | `string[]` | — |  |
| defaultExpandedKeys | `string[]` | `NO_KEYS` |  |
| onExpandedChange | `(keys: string[]) => void` | — |  |
| onCellEdit | `(edit: DataGridCellEdit<T>) => void \| string \| null \| Promise<void \| string \| null>` | — | Called with a validated edit. Update your data here. Return (or resolve) a string to show it as an error and keep the editor open. |
| aggregates | `Record<string, React.ReactNode>` | — | Footer values from the server, by column id (server mode, or to override). |
| loading | `boolean` | `false` | Skeleton rows when there is no data yet; a progress bar over existing rows. |
| error | `boolean \| React.ReactNode` | — | true or a message shows the error state. |
| onRetry | `() => void` | — | Adds a retry button to the error state. |
| emptyState | `React.ReactNode` | — | Replaces the empty-state content (no data, no filters). |
| mode | `"client" \| "server"` | `"client"` | client: the grid searches, filters, sorts and (optionally) pages. server: it only reports the query; data is the current page. |
| pagination | `boolean` | `false` | Client mode: pages instead of one virtualized scroll. Server mode pages whenever rowCount is set. |
| page | `number` | — |  |
| defaultPage | `number` | `1` |  |
| onPageChange | `(page: number) => void` | — |  |
| pageSize | `number` | — |  |
| defaultPageSize | `number` | `25` |  |
| onPageSizeChange | `(size: number) => void` | — |  |
| pageSizeOptions | `number[]` | `[10, 25, 50, 100]` |  |
| rowCount | `number` | — | Server mode: total rows on the server. |
| onQueryChange | `(query: DataGridQuery) => void` | — | Server mode: the full query after any sort, filter, search (debounced 250 ms) or page change. |
| overscan | `number` | `6` | Rows rendered beyond the viewport on each side. |
| labels | `Partial<DataGridLabels>` | — | Text for built-in controls and screen readers; pass translations here. |

Also accepts every <div> attribute.

## Keyboard

| Keys | Action |
| --- | --- |
| Tab | The grid is one tab stop; focus lands on the last active cell (roving tabindex). |
| Arrow keys | Move between cells, header row included. Left and Right are mirrored under dir="rtl". |
| Home / End | First or last cell of the row. |
| Ctrl+Home / Ctrl+End | First header cell (and scroll to the top) / last cell of the last row. |
| Page Up / Page Down | Move up or down by one viewport of rows. |
| Enter (header) | Sort: ascending, descending, off. Shift+Enter adds the column to a multi-sort (shift-click works too). |
| Alt+Arrow Down, Shift+F10 or the Menu key (header) | Open the column menu: filter, sort, pin, move, hide. Escape closes it and returns focus. |
| Alt+Arrow Left / Right (header) | Resize the column by 16px. |
| Alt+Shift+Arrow Left / Right (header) | Move the column one place within its pin group. |
| Enter or F2 (cell) | Edit an editable cell (text selected). Booleans toggle. On the select or expand column, toggles. On an actions cell, focuses its first button. |
| Any character (cell) | Starts editing a text or number cell with that character. |
| Enter / Tab / Shift+Tab / Escape (editor) | Save and stay / save and move right / save and move left / cancel. Leaving the editor saves. |
| Space | Toggles the row checkbox on the select column (Shift+Space on any cell), a boolean cell, or the detail panel on the expand column. On the header checkbox, selects all filtered rows. |
| Ctrl/Cmd+A | Selects all filtered rows (selectable grids). |
| Escape / Arrow Left/Right / Tab (inside an actions cell) | Back to the cell / cycle between the cell's buttons. |

## Accessibility

- role="grid" with aria-rowcount (all rows, not just rendered ones), aria-colcount, aria-multiselectable when selectable, and aria-busy while loading. Rows carry aria-rowindex and aria-selected; cells carry aria-colindex. The expand toggle is a button with aria-expanded (aria-expanded on a row is only valid in a treegrid).
- Column headers have aria-sort and read "sorted ascending, sort priority 2" for multi-sort; aria-describedby points to a hint for the header keys (labels.headerHint). Editable cells are described by labels.editHint; read-only cells get aria-readonly when editing is enabled.
- The editor is a real <input> (text, date or datetime-local) or <select> named after the column. Validation errors are role="alert" and linked with aria-describedby and aria-invalid.
- Checkboxes are real inputs named "Select Maya Chen" (labels.selectRow, from the first text or avatar column). Expand buttons say "Show details for …". Icon-only actions are named "Send reminder, Maya Chen".
- Column menu, Columns and Export panels are portaled role="dialog" popovers: focus moves in, Tab is kept inside, Escape returns focus to the header or button that opened them.
- The row count is announced in a polite live region. Pass aria-label (or labels.grid) to name the grid.

## Motion

- fade (default): menus fade in 140 ms, the bulk action bar fades in 150 ms, detail panels fade in 180 ms, edited cells flash the tone color for 900 ms.
- spring: menus scale from 0.96 and move 4px (spring stiffness 520, damping 34, mass 0.7); the bulk bar rises 16px (stiffness 480, damping 32); rows glide to new positions over 280 ms after sorting or expanding; detail panels drop in 6px.
- none: no motion, no transitions, static skeleton and loading bar.
- Reduced motion behaves like none (after mount, so server and client render the same); CSS transitions and keyframes are also off through prefers-reduced-motion.

## Performance

- Rows are virtualized: only the visible window plus 6 rows each side (overscan) is in the DOM, positioned with transforms; expanded detail panels are measured with ResizeObserver. In our 100,000-row demo the body holds about 15 row elements at a 460px height.
- Sorting ranks text values once with Intl.Collator and caches numeric sort keys per column; the search index is built once (on search focus) with each distinct value formatted once. Caches are keyed by data and columns identity, so keep both stable.
- Search, filters and sort run through useDeferredValue so typing stays responsive. Edits replace one row in your array.
- Export builds CSV or a store-only .xlsx (ZIP written in the component, no dependencies) from the filtered, sorted, visible columns, or only the selected rows.

## Notes for AI

- Always pass a stable columns array (useMemo or module scope) and an id per row (or getRowId). Cell values are read from row[column.id] unless accessor is set.
- column.type drives format, alignment, sort, filter kind, editor and export cell type: text, number, currency, percent (0.25 = 25%), date ("YYYY-MM-DD" is a local day), datetime, boolean, badge (with options and tones), avatar (image, subtitle), actions.
- Edits do not mutate data: handle onCellEdit and update your state. Return or resolve a string to reject with a message. validate runs first.
- In mode="server" the grid does not sort, filter, search or page; it reports a DataGridQuery via onQueryChange (search debounced 250 ms). data is the current page and rowCount the total; aggregates come from the aggregates prop.
- Pins are "start"/"end" (logical, RTL-safe). On narrow grids, pins yield when they would cover more than about 55% of the width. Column order, widths, pins and hidden ids are one columnState object (controlled or uncontrolled).
- Every built-in string is in labels; number and date formatting follows locale (default en-US), currency and timeZone.
- Drag-to-reorder uses mouse or pen; on touch use the column menu's Move left/right.

## FAQ

**Is the Excel export a real .xlsx?**

Yes. It writes the Open XML parts (workbook, sheet, styles) into a ZIP in the browser, with typed numbers, dates and booleans, number formats per column (currency symbol, percent, yyyy-mm-dd), a bold frozen header row, an auto filter and column widths. CSV is UTF-8 with a BOM so Excel reads accents, and text starting with = + - @ is escaped against formula injection.

**How many rows can it handle?**

The demo runs 100,000 rows in client mode with sorting, filtering, search, selection and export. Beyond what fits in browser memory, use mode="server".

**Can I keep column layout between visits?**

Yes. Store the object from onColumnStateChange (order, widths, pinned, hidden) and pass it back as defaultColumnState or columnState.

**Does it work right to left?**

Yes. Layout uses logical properties, pins use start/end, arrow keys and resize drags mirror under dir="rtl", and popovers follow the direction.

## Related

- table: https://goodui.dev/components/core/table
- pagination: https://goodui.dev/components/core/pagination
- select: https://goodui.dev/components/core/select
- checkbox: https://goodui.dev/components/core/checkbox
- badge: https://goodui.dev/components/core/badge
- avatar: https://goodui.dev/components/core/avatar

Last updated: 2026-11-03

---

# Chat message

> User, assistant and system messages with avatars, grouping, a hover actions row (copy, good/bad, retry, edit), markdown-ish rendering of lists, quotes and fenced code into CodeBlocks, and a blinking caret while the answer streams.

AI chat message component for React: user and assistant bubbles with markdown, streaming caret and actions

Page: https://goodui.dev/components/ai/chat-message

## Install

```bash
npx shadcn@latest add @goodui/chat-message
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/chat-message.json`. The file lands in `components/goodui/chat-message.tsx`.

## When to use

- Any assistant conversation: the user's prompt in a bubble, the assistant's answer as formatted text with copy, feedback and retry.
- Answers that arrive progressively: pass the text so far and streaming, and the caret blinks at the end until it is complete.
- Rich replies with lists, inline code and fenced code blocks, which become copyable CodeBlocks automatically.
- Follow-up messages from the same author (grouped) and system notes centred between messages.

## When not to use

- Human-to-human messaging with read receipts and reactions: build on a plain list; this is tuned for assistant answers.
- Full markdown (tables, nested lists, HTML): render with a markdown library and pass the result as children instead of content.
- The input itself: use chat-composer.

## Pick by what matters

| Need | Use |
| --- | --- |
| Assistant text on the page, user in a bubble (ChatGPT style) | variant="flat" (default) |
| Both sides in bubbles | variant="bubble" |
| Brand-colored user bubble | tone="primary" |
| Answer still arriving | streaming (caret, actions hidden) |
| Custom body, e.g. StreamingText or cards | children instead of content |
| Only the markdown renderer | <MessageMarkdown text=… /> |

## Usage

```tsx
import { ChatMessage } from "@/components/goodui/chat-message"

export function Thread({ messages }: { messages: { id: string; role: "user" | "assistant"; text: string; done: boolean }[] }) {
  return (
    <div className="flex flex-col">
      {messages.map((m, i) => (
        <ChatMessage
          key={m.id}
          role={m.role}
          name={m.role === "assistant" ? "Aiko" : "Lena"}
          content={m.text}
          streaming={!m.done}
          grouped={messages[i - 1]?.role === m.role}
          onFeedback={(v) => rate(m.id, v)}
          onRetry={() => regenerate(m.id)}
        />
      ))}
    </div>
  )
}
```

### Streaming with StreamingText as the body

```tsx
<ChatMessage role="assistant" name="Aiko" streaming={!done} copyText={answer}>
  <StreamingText text={answer} streaming={!done} onComplete={() => setDone(true)} className="block text-[15px] leading-7" />
</ChatMessage>
```

### Tool calls under the answer

```tsx
<ChatMessage role="assistant" content="I found a slot and held it for ten minutes.">
  <div className="mt-3 flex flex-col gap-2">
    <ToolCall name="find_free_slot" args={{ stylist: "Lena" }} status="success" duration={640} />
  </div>
</ChatMessage>
```

### Failed user message with retry

```tsx
<ChatMessage role="user" content="Book Maya for Saturday" status="error" onRetry={resend} />
```

## API

### ChatMessage

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| role (required) | `"user" \| "assistant" \| "system"` | — |  |
| onCopy | `(text: string) => void` | — |  |
| content | `string` | — | Message text, rendered markdown-ish. Children render under it (tool calls, cards, custom content). |
| name | `string` | — | Author shown above assistant messages; also the fallback for the avatar initials. |
| avatar | `React.ReactNode` | — | Image URL or any node (icon, initials). Defaults to a sparkle for assistants and the user's initial. |
| time | `string` | — | Short time or date text, e.g. "14:32". |
| status | `"sending" \| "sent" \| "error"` | — | Delivery state for user messages. |
| streaming | `boolean` | `false` | The answer is still arriving: shows a caret and hides the actions row. |
| grouped | `boolean` | `false` | A follow-up message from the same author: no avatar or name, tighter spacing. |
| variant | `"flat" \| "bubble"` | `"flat"` | flat: assistant text sits on the page, user text in a bubble. bubble: both in bubbles. |
| tone | `"neutral" \| "primary"` | `"neutral"` | User bubble color. |
| actions | `boolean` | `true` | Show the actions row (copy and the handlers you pass). |
| copyText | `string` | — | Text copied by the copy action; defaults to content. |
| onFeedback | `(value: ChatFeedback) => void` | — | Thumbs up/down; clicking the active one clears it. |
| feedback | `"up" \| "down" \| null` | — | Controlled feedback state. |
| onRetry | `() => void` | — | Shown as a retry button on assistant messages and on failed user messages. |
| onEdit | `() => void` | — | Shown as an edit button on user messages. |
| animate | `boolean` | `true` | Fade and rise in on mount. |
| labels | `Partial<ChatMessageLabels>` | — | Text for built-in controls and screen readers; pass translations here. |

Also accepts every <div> attribute.

### MessageMarkdown

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| text (required) | `string` | — | Markdown-ish text. |
| streaming | `boolean` | `false` | Appends a blinking caret to the last block. |

Also accepts every <div> attribute.

## Accessibility

- The author name is visible for assistant messages and screen-reader only for user messages.
- Action buttons are real buttons with aria-labels (Copy, Good response, Bad response, Retry, Edit) and aria-pressed on the feedback pair; they appear on hover or keyboard focus and are always visible on touch screens.
- Copy announces "Copied" through a polite live region.
- Links in content open in a new tab with rel="noreferrer". System messages use role="note".
- Built-in strings (labels for actions, statuses, default author names) go through the labels prop for translation.

## Motion

- A message fades and rises 8px on mount on a spring (stiffness 420, damping 32); animate={false} turns it off for restored history.
- The streaming caret is a 1 s step blink in CSS; feedback icons pop on a spring when toggled; the copy icon cross-fades into a check for 1.6 s.
- Reduced motion: the entrance has zero duration, the caret stops blinking and icon pops become plain swaps.

## Performance

- The markdown-ish parser is a single pass over lines, memoised on content, so a streaming message re-parses once per received chunk and never on unrelated re-renders.

## Notes for AI

- Pass content as a string for markdown-ish rendering (paragraphs, #-headings, -/1. lists, > quotes, **bold**, *italic*, `code`, [links](url) and ``` fences). Anything else goes in children.
- Set streaming while the answer is incomplete and clear it at the end; the actions row is hidden while streaming.
- grouped hides the avatar and name; compute it from the previous message's role.
- onFeedback receives "up", "down" or null (cleared); pass feedback to control it.
- Fenced code blocks render CodeBlock (installed alongside); the language after the fence picks the tokenizer.

## FAQ

**Does it render tables or nested lists?**

No. The built-in renderer covers what assistants usually emit. For full markdown, render it yourself and pass the nodes as children.

**How do I show an avatar image?**

Pass avatar as a URL string; it renders in the 28px circle. Pass a node for an icon or initials.

## Related

- chat-composer: https://goodui.dev/components/ai/chat-composer
- streaming-text: https://goodui.dev/components/ai/streaming-text
- code-block: https://goodui.dev/components/ai/code-block
- tool-call: https://goodui.dev/components/ai/tool-call
- typing-indicator: https://goodui.dev/components/ai/typing-indicator

Last updated: 2026-11-03

---

# Streaming text

> Reveals an answer token by token at a steady speed with a cursor that blinks while waiting for more, stop and resume, word or character mode, and smooth catch-up when uneven SSE chunks arrive; reduced motion shows sentence chunks.

Streaming text effect for React: token-by-token reveal with a cursor, stop and resume, smooth catch-up for live streams

Page: https://goodui.dev/components/ai/streaming-text

## Install

```bash
npx shadcn@latest add @goodui/streaming-text
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/streaming-text.json`. The file lands in `components/goodui/streaming-text.tsx`.

## When to use

- Assistant answers that arrive over SSE or websockets: pass the accumulated text and the reveal catches up smoothly instead of jumping with every chunk.
- Pre-written text that should read like it is being generated (demos, onboarding assistants).
- A Stop button: set playing to false and the text freezes where it is; true resumes.

## When not to use

- Marketing typewriter loops that type and delete phrases: use typewriter.
- Markdown-formatted answers: use chat-message's content, which keeps its own caret.
- Text that must be read instantly (errors, form feedback): render it plainly.

## Pick by what matters

| Need | Use |
| --- | --- |
| Live API stream | text = all chunks so far, streaming until the final event |
| Whole words appearing | by="word" |
| Restore history without replay | initialRevealed="all" |
| Replay | change resetKey |
| Cursor style | cursor="bar" \| "block" \| "dot" \| false |

## Usage

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

export function Answer({ text, done }: { text: string; done: boolean }) {
  const [playing, setPlaying] = React.useState(true)
  return (
    <div>
      <p className="text-[15px] leading-7">
        <StreamingText text={text} streaming={!done} playing={playing} speed={60} />
      </p>
      <button type="button" onClick={() => setPlaying((p) => !p)}>{playing ? "Stop" : "Resume"}</button>
    </div>
  )
}
```

### Word by word with a block cursor

```tsx
<StreamingText text={summary} by="word" cursor="block" speed={40} />
```

### Restored message, no animation

```tsx
<StreamingText text={message} initialRevealed="all" />
```

### Progress callback for an auto-scrolling list

```tsx
<StreamingText text={text} onProgress={() => listRef.current?.scrollTo({ top: 1e9 })} />
```

## API

### StreamingText

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| text (required) | `string` | — | All the text received so far. Growing it continues the stream; a different string starts over. |
| onProgress | `(revealed: number, total: number) => void` | — | Called as the reveal advances, with visible and total character counts. |
| speed | `number` | `60` | Characters per second at a steady state. When a lot of text is waiting the reveal speeds up so it catches up within about a second. |
| by | `"char" \| "word"` | `"char"` | Reveal unit: single characters or whole words. |
| playing | `boolean` | `true` | false pauses the reveal where it is (a Stop button); true resumes. |
| streaming | `boolean` | `false` | More text may still arrive: the cursor stays and blinks while waiting. Set false once the response is complete. |
| cursor | `"bar" \| "block" \| "dot" \| false` | `"bar"` | Cursor style, or false for none. |
| cursorWhenDone | `boolean` | `false` | Keep the cursor after the text is complete and not streaming. |
| fade | `boolean` | `true` | New characters fade in briefly instead of popping. |
| initialRevealed | `number \| "all"` | `0` | Characters already visible at mount, or "all" to show restored history without replaying it. |
| resetKey | `React.Key` | — | Change it to replay from the start. |
| onComplete | `() => void` | — | Called when every character of `text` is visible and `streaming` is false. |
| labels | `Partial<StreamingTextLabels>` | — | Text for screen readers; pass translations here. |

Also accepts every <span> attribute.

## Accessibility

- While text is still being revealed, screen readers get the full text in a visually hidden span and the animated copy is aria-hidden; once complete and not streaming, the visible text is the only copy.
- A visually hidden "Streaming" label (labels.streaming) is present while the reveal is active.
- Reduced motion replaces character-by-character reveal with sentence-sized chunks every 140 ms, and the cursor does not blink.

## Motion

- Characters are revealed on a requestAnimationFrame loop at `speed` characters per second; when the unread backlog grows (a burst of chunks) the rate rises so it never lags more than about a second behind the stream.
- The last 18 characters fade in with a 0.3 s blur-to-sharp CSS animation (fade).
- The cursor is solid while text is arriving and blinks at 1 Hz while waiting for more; the dot cursor pulses instead.
- Reduced motion: chunks appear whole, no fade, static cursor.

## Performance

- Only the last 18 characters are individual spans; the rest is one text node. The loop stops when the text is fully revealed, when playing is false and when the tab is hidden (requestAnimationFrame pauses in background tabs).

## Notes for AI

- Always pass the whole text received so far, not the latest chunk; the component works out what is new.
- Keep streaming true until the final event; it keeps the cursor and the hidden full-text copy in place. onComplete fires only when everything is revealed and streaming is false.
- A text that does not start with what was already shown is treated as a new message and starts from zero.
- Use resetKey to replay the same text; initialRevealed="all" to show restored history instantly.
- The root is a <span> with whitespace-pre-wrap; add className="block" to use it as a block.

## FAQ

**Why not just render the chunks as they come?**

Chunk sizes and intervals are uneven, so plain rendering stutters. The steady rate with catch-up reads as one calm stream.

**Can I render markdown with it?**

Not directly; it reveals plain text. chat-message renders markdown with its own streaming caret.

## Related

- chat-message: https://goodui.dev/components/ai/chat-message
- typewriter: https://goodui.dev/components/text/typewriter
- typing-indicator: https://goodui.dev/components/ai/typing-indicator
- chat-composer: https://goodui.dev/components/ai/chat-composer

Last updated: 2026-11-03

---

# Tool call

> Collapsible card for an agent's tool call: name and arguments in the header, a status that morphs from spinner to drawn check or error, a live duration while running, and argument and output panes inside.

Tool call card for AI agents in React: name, arguments, running spinner to check or error, duration and output pane

Page: https://goodui.dev/components/ai/tool-call

## Install

```bash
npx shadcn@latest add @goodui/tool-call
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/tool-call.json`. The file lands in `components/goodui/tool-call.tsx`.

## When to use

- Showing what an agent did: each function or MCP tool call with its arguments, a live status and the result.
- Long-running calls where the user wants to see progress (duration ticks while running).
- Failures the user should read, with the error message in a rose pane.

## When not to use

- A whole multi-step plan with nesting and overall progress: use agent-plan.
- Model reasoning rather than external calls: use reasoning-block.
- Logs with hundreds of entries: a virtualized list; this card is for a handful of calls per message.

## Pick by what matters

| Need | Use |
| --- | --- |
| Standalone card | variant="card" (default) |
| Quiet row inside a chat message | variant="inline" |
| Known duration from the API | duration (ms); otherwise it is measured while status is running |
| Start expanded | defaultOpen, or open/onOpenChange to control it |

## Usage

```tsx
import { ToolCall } from "@/components/goodui/tool-call"

<ToolCall
  name="search_bookings"
  args={{ client: "Maya Chen", range: "last 90 days" }}
  status={call.status}            // "pending" | "running" | "success" | "error"
  output={call.result}            // string renders in a monospace pane
  error={call.error}
/>
```

### Inline rows under an answer

```tsx
<ToolCall variant="inline" name="get_client" args={{ id: "cl_2291" }} status="success" duration={312} output={json} />
<ToolCall variant="inline" name="read_policy" title="Reading the cancellation policy" args="deposits.md" status="success" duration={88} />
```

### Custom icon and a React node as output

```tsx
<ToolCall name="find_free_slot" icon={<Calendar />} status="success" output={<SlotCard slot={slot} />} defaultOpen />
```

## API

### ToolCall

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| name (required) | `string` | — | Tool name, shown in monospace. |
| title | `React.ReactNode` | — | Friendlier text shown instead of the name. |
| args | `Record<string, unknown> \| string` | — | Arguments as an object (rendered as a key/value grid) or a preformatted string. |
| status | `"pending" \| "running" \| "success" \| "error"` | `"pending"` |  |
| output | `React.ReactNode` | — | Result; strings render in a scrollable monospace pane, nodes as-is. |
| error | `string` | — | Error message shown in the body when status is "error". |
| duration | `number` | — | Duration in ms. When omitted it is measured from the moment status becomes "running". |
| open | `boolean` | — |  |
| defaultOpen | `boolean` | `false` |  |
| onOpenChange | `(open: boolean) => void` | — |  |
| icon | `React.ReactNode` | — | Replaces the wrench icon. |
| variant | `"card" \| "inline"` | `"card"` | card: bordered; inline: a quiet row for inside a message. |
| labels | `Partial<ToolCallLabels>` | — | Text for built-in controls and screen readers; pass translations here. |

Also accepts every <div> attribute.

## Keyboard

| Keys | Action |
| --- | --- |
| Enter / Space | Toggles the body on the header button. |
| Tab | Moves through the header; the body contains no controls unless your output has them. |

## Accessibility

- The header is a <button> with aria-expanded and aria-controls pointing at the body.
- The status is announced as text (Waiting, Running, Done, Failed) through a visually hidden span; the icons are decorative.
- The error pane is prefixed with a hidden "Error:" label. Section titles (Arguments, Output) are headings.
- Built-in strings go through the labels prop for translation.

## Motion

- Status icons swap on a spring (stiffness 520, damping 26): dashed circle, spinner, a check whose stroke draws in over 0.3 s, or a rose X.
- While running, a thin light sweeps along the bottom edge of the header and the duration ticks every 100 ms.
- The body opens to its real height on a spring (stiffness 420, damping 36).
- Reduced motion: the spinner slows to 2 s per turn, the sweep is removed, the check does not draw and the body toggles instantly.

## Notes for AI

- Drive status from your agent events: pending → running → success | error. Pass output only once you have it.
- args accepts an object (rendered as key: value rows and previewed in the header) or a preformatted string.
- duration is in milliseconds; omit it to show the measured time from when status became running.
- title replaces the monospace name with friendlier text; name is still used for the preview semantics.

## FAQ

**Can the output be more than text?**

Yes. Strings render in a scrollable monospace pane; any other React node renders as-is.

**What if a call has no arguments or output?**

The header still works; the chevron and body are omitted when there is nothing to show.

## Related

- agent-plan: https://goodui.dev/components/ai/agent-plan
- reasoning-block: https://goodui.dev/components/ai/reasoning-block
- chat-message: https://goodui.dev/components/ai/chat-message
- code-block: https://goodui.dev/components/ai/code-block

Last updated: 2026-11-03

---

# Reasoning block

> "Thinking 8.7s" disclosure with a live tenths timer, a shimmering label while the model reasons, the current step previewed under the header and the full step list plus notes folded inside.

"Thinking 8.7s" reasoning disclosure for React AI apps: live timer, shimmering label and step summaries

Page: https://goodui.dev/components/ai/reasoning-block

## Install

```bash
npx shadcn@latest add @goodui/reasoning-block
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/reasoning-block.json`. The file lands in `components/goodui/reasoning-block.tsx`.

## When to use

- Models with visible reasoning or thinking summaries: show the time spent and the steps while the user waits, then fold them away under "Thought for 8.7s".
- Agents that report progress as short step titles before the final answer.

## When not to use

- External tool calls with arguments and outputs: use tool-call.
- A plan with statuses and nesting: use agent-plan.
- Plain loading with no steps to show: use spinners or typing-indicator.

## Pick by what matters

| Need | Use |
| --- | --- |
| Live thinking | thinking plus steps that grow as summaries arrive |
| Finished with the API's duration | thinking={false} duration={seconds} |
| Full reasoning text | children (rendered under the steps) |
| No current-step line under the header | preview={false} |

## Usage

```tsx
import { ReasoningBlock } from "@/components/goodui/reasoning-block"

<ReasoningBlock thinking={!done} steps={summaries.map((s) => ({ title: s }))} duration={done ? seconds : undefined}>
  {reasoningText}
</ReasoningBlock>
```

### Expanded by default after it finishes

```tsx
<ReasoningBlock duration={8.7} defaultOpen steps={[{ title: "Checked Saturday's capacity" }, { title: "Balayage needs 150 minutes" }]} />
```

### Translated labels

```tsx
<ReasoningBlock thinking labels={{ thinking: (s) => `Denke nach ${s}`, thought: (s) => `${s} nachgedacht`, toggle: "Begründung anzeigen" }} />
```

## API

### ReasoningBlock

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| thinking | `boolean` | `false` | The model is still reasoning: the label shimmers and the timer runs. |
| duration | `number` | — | Final duration in seconds, when you have it from the API. Otherwise the elapsed time is measured here. |
| steps | `ReasoningStep[]` | `[]` | Step summaries, shown in order; the last one is the current step while thinking. |
| children | `React.ReactNode` | — | Free-form reasoning text shown under the steps. |
| open | `boolean` | — |  |
| defaultOpen | `boolean` | `false` |  |
| onOpenChange | `(open: boolean) => void` | — |  |
| preview | `boolean` | `true` | Show the current step under the header while collapsed and thinking. |
| labels | `Partial<ReasoningBlockLabels>` | — | Text for built-in controls and screen readers; pass translations here. |

Also accepts every <div> attribute.

## Keyboard

| Keys | Action |
| --- | --- |
| Enter / Space | Toggles the step list on the header button. |

## Accessibility

- The header is a <button> with aria-expanded, aria-controls and an aria-label that includes the current text ("Show reasoning: Thinking 3.2s").
- The shimmer is a decorative gradient over the label; under reduced motion it is plain text.
- While collapsed and thinking, the current step is announced through a visually hidden polite live region; the animated preview line under the header is decorative, and the step list is ordinary text.
- Built-in strings go through the labels prop for translation.

## Motion

- While thinking, the label shimmers (a 1.6 s gradient sweep clipped to the text) and the timer updates every 100 ms with one decimal.
- The current step below the header cross-fades (4px rise, 0.2 s) each time a new summary arrives; the list items spring in (stiffness 480, damping 32) and the current one has a pulsing dot.
- The body opens to its real height on a spring (stiffness 420, damping 36).
- Reduced motion: no shimmer, no pulse, fades only, instant open and close.

## Notes for AI

- Set thinking while reasoning is in progress; the component measures the elapsed time itself. Pass duration (seconds) when the API reports it, it wins once thinking is false.
- steps is the list so far; append summaries as they arrive. The last one is treated as the current step while thinking.
- Put the raw reasoning text in children; it renders muted under the steps.
- With no steps and no children, the header is static text and not a button.

## FAQ

**Does the timer keep running if the component re-renders?**

Yes, it is anchored to the moment thinking became true and only stops when thinking turns false.

**Can I hide the time?**

Pass labels.thinking and labels.thought that ignore the seconds argument.

## Related

- tool-call: https://goodui.dev/components/ai/tool-call
- agent-plan: https://goodui.dev/components/ai/agent-plan
- streaming-text: https://goodui.dev/components/ai/streaming-text
- chat-message: https://goodui.dev/components/ai/chat-message

Last updated: 2026-11-03

---

# Model picker

> Model dropdown grouped by provider with icon slots, speed and quality meters that grow in, context window and price per million tokens, a gliding highlight and full keyboard support with type-ahead.

AI model picker dropdown for React: provider icons, speed and quality meters, context window, price per 1M tokens, keyboard navigation

Page: https://goodui.dev/components/ai/model-picker

## Install

```bash
npx shadcn@latest add @goodui/model-picker
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/model-picker.json`. The file lands in `components/goodui/model-picker.tsx`.

## When to use

- Letting people pick the model for a chat, an agent or a batch job, with enough information to choose (speed, quality, context, price).
- Toolbars and composers: the ghost, small variant fits next to other controls.
- Multi-provider products where rows should be grouped by provider.

## When not to use

- A generic single-select field without model metadata: use select.
- Thousands of options with search: use combobox.
- Comparing models in depth: a table; the picker shows one line of facts per model.

## Pick by what matters

| Need | Use |
| --- | --- |
| Field in a settings form | variant="outline" size="md" |
| Inside a composer or toolbar | variant="ghost" size="sm" showMeters={false} |
| Flat list, no provider headings | groupByProvider={false} |
| Real logos | providerIcons={{ OpenAI: <Logo /> }} or icon per model |
| Retired model still listed | disabled on the model |

## Usage

```tsx
import { ModelPicker, type ModelOption } from "@/components/goodui/model-picker"

const MODELS: ModelOption[] = [
  { id: "claude-sonnet-4-5", name: "Claude Sonnet 4.5", provider: "Anthropic", speed: 4, quality: 5, context: 200_000, price: { input: 3, output: 15 }, badge: "Recommended" },
  { id: "gpt-5-mini", name: "GPT-5 mini", provider: "OpenAI", speed: 5, quality: 3, context: 400_000, price: { input: 0.25, output: 2 } },
]

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

### Compact trigger aligned to the end

```tsx
<ModelPicker models={MODELS} variant="ghost" size="sm" align="end" showMeters={false} />
```

### German prices and labels

```tsx
<ModelPicker models={MODELS} locale="de-DE" labels={{ chooseModel: "Modell wählen", speed: "Tempo", quality: "Qualität" }} />
```

## API

### ModelPicker

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| models (required) | `ModelOption[]` | — |  |
| value | `string` | — | Selected model id (controlled). |
| defaultValue | `string` | — |  |
| onValueChange | `(id: string, model: ModelOption) => void` | — |  |
| providerIcons | `Record<string, React.ReactNode>` | — | Icon per provider name, e.g. { OpenAI: <OpenAiLogo />, Anthropic: <AnthropicLogo /> }. Missing ones get a lettered tile. |
| variant | `"outline" \| "ghost"` | `"outline"` | Trigger look: a bordered field or a quiet ghost button for toolbars. |
| size | `"sm" \| "md"` | `"md"` |  |
| groupByProvider | `boolean` | `true` | Group rows under provider headings. |
| showMeters | `boolean` | `true` |  |
| showContext | `boolean` | `true` |  |
| showPrice | `boolean` | `true` |  |
| align | `"start" \| "end"` | `"start"` | Which trigger edge the menu aligns to. |
| locale | `string` | `"en-US"` | Locale for the context window and prices. |
| placeholder | `string` | — |  |
| disabled | `boolean` | — |  |
| labels | `Partial<ModelPickerLabels>` | — | Text for built-in controls and screen readers; pass translations here. |

Also accepts every <div> attribute.

## Keyboard

| Keys | Action |
| --- | --- |
| Enter / Space / ArrowDown / ArrowUp | On the trigger: opens the list and focuses it. |
| ArrowDown / ArrowUp | Moves the active row, skipping disabled models, and wraps. |
| Home / End | First or last enabled model. |
| Letters | Type-ahead: jumps to the first model whose name starts with what you typed (600 ms window). |
| Enter / Space | Selects the active model and returns focus to the trigger. |
| Escape | Closes and returns focus to the trigger. Tab closes too. |

## Accessibility

- The trigger has aria-haspopup="listbox", aria-expanded, aria-controls and an aria-label that includes the current model name.
- The list is role="listbox" with aria-activedescendant; rows are role="option" with aria-selected and aria-disabled.
- Meters are announced as text ("Speed 4 of 5"); the bars themselves are decorative. The selected row has a visually hidden "Selected".
- Built-in strings go through the labels prop for translation.

## Motion

- The list springs open (stiffness 520, damping 34) from the trigger's edge and flips above it when fewer than 380px remain below.
- Rows fade in staggered by 25 ms (up to 8 rows); the highlight glides between rows as a shared-layout spring; meter bars grow from the baseline with a 40 ms stagger when the list opens.
- Reduced motion: the list fades, rows do not stagger, the highlight jumps and the bars appear instantly.

## Notes for AI

- Prices are USD per million tokens; context is in tokens and formatted compactly (200K, 1M).
- onValueChange receives (id, model). Pass value to control it; otherwise it starts from defaultValue or the first model.
- Provider icons: providerIcons keyed by the provider string, or icon on a model. Without either, a lettered tile colored from the provider name is used.
- The list is rendered in place (absolute), not in a portal; a parent with overflow:hidden will clip it.

## FAQ

**Can I show only some facts?**

Yes: showMeters, showContext and showPrice each hide their column.

**How do I add a price unit other than per 1M?**

Set labels.perMillion; it is the tooltip on the price. The numbers themselves are whatever you pass.

## Related

- chat-composer: https://goodui.dev/components/ai/chat-composer
- select: https://goodui.dev/components/core/select
- combobox: https://goodui.dev/components/core/combobox
- dropdown-menu: https://goodui.dev/components/core/dropdown-menu

Last updated: 2026-11-03

---

# Chat composer

> Prompt input with an auto-growing textarea, attachment chips from picker, paste or drop, a slash-command menu, model and mode selectors, a token ring against the context limit, Enter or Cmd+Enter to send and a Stop button while streaming.

AI prompt composer for React: auto-growing textarea, attachments, slash commands, model and mode pickers, token counter, stop while streaming

Page: https://goodui.dev/components/ai/chat-composer

## Install

```bash
npx shadcn@latest add @goodui/chat-composer
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/chat-composer.json`. The file lands in `components/goodui/chat-composer.tsx`.

## When to use

- The input of any assistant chat: Enter sends, Shift+Enter adds a line, the button turns into Stop while the answer streams.
- Prompts that carry files (paste, drop or pick) and need a model or mode choice right there.
- Products with slash commands such as /summarize or /schedule.

## When not to use

- Plain forms and comments: use input or a textarea.
- A command palette with many actions: use command-palette-morph; the slash menu is for a handful of commands.

## Pick by what matters

| Need | Use |
| --- | --- |
| Only Cmd/Ctrl+Enter should send | submitOnEnter={false} |
| File attachments | accept="image/*,.pdf" (the attach button and paste/drop appear) |
| Model picker in the footer | models (ModelOption[]) with model/onModelChange |
| Chat / Research / Agent switch | modes with mode/onModeChange |
| Context limit | maxTokens (shows the ring and blocks sending above it) |
| Your tokenizer | countTokens={(text) => …} |

## Usage

```tsx
import { ChatComposer } from "@/components/goodui/chat-composer"

<ChatComposer
  placeholder="Ask Aiko…"
  accept="image/*,.pdf"
  commands={[{ name: "summarize", description: "Summarise this chat" }, { name: "schedule", description: "Find a slot" }]}
  models={MODELS}
  modes={[{ id: "chat", label: "Chat" }, { id: "agent", label: "Agent" }]}
  maxTokens={8000}
  streaming={isStreaming}
  onStop={abort}
  onSubmit={(text, { attachments, model, mode }) => send(text, attachments, model, mode)}
/>
```

### Controlled value filled by suggestion chips

```tsx
const [draft, setDraft] = React.useState("")
<SuggestionChips suggestions={ideas} onSelect={setDraft} />
<ChatComposer value={draft} onValueChange={setDraft} onSubmit={send} />
```

### Commands that run instead of inserting

```tsx
<ChatComposer commands={COMMANDS} onCommand={(c) => run(c.name)} />
```

### With a send sound

```tsx
<ChatComposer onSubmit={send} sound />
```

## API

### ChatComposer

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| autoFocus | `boolean` | — |  |
| onKeyDown | `(e: React.KeyboardEvent<HTMLTextAreaElement>) => void` | — | Key handler on the textarea; call preventDefault to override the Enter behavior. |
| onPaste | `(e: React.ClipboardEvent<HTMLTextAreaElement>) => void` | — | Paste handler on the textarea; pasted files become attachments when `accept` is set. |
| value | `string` | — |  |
| defaultValue | `string` | `""` |  |
| onValueChange | `(value: string) => void` | — |  |
| onSubmit | `(text: string, meta: { attachments: ComposerAttachment[]; model?: string; mode?: string }) => void` | — | Called with the trimmed text and the attachments, model and mode in effect. Clears the field when uncontrolled. |
| streaming | `boolean` | `false` | The answer is streaming: the send button becomes Stop and calls onStop. |
| onStop | `() => void` | — |  |
| attachments | `ComposerAttachment[]` | — |  |
| defaultAttachments | `ComposerAttachment[]` | `[]` |  |
| onAttachmentsChange | `(attachments: ComposerAttachment[]) => void` | — |  |
| accept | `string` | — | Accept attribute for the file picker, e.g. "image/*,.pdf". Omit to hide the attach button. |
| maxAttachments | `number` | `10` |  |
| commands | `SlashCommand[]` | — | Typing "/" at the start opens this list. |
| onCommand | `(command: SlashCommand) => void` | — | Runs when a command is picked; by default the command is inserted as "/name ". |
| models | `ModelOption[]` | — | Models for a built-in ModelPicker in the footer. |
| model | `string` | — |  |
| defaultModel | `string` | — |  |
| onModelChange | `(id: string) => void` | — |  |
| modes | `ComposerMode[]` | — | Modes shown as a segmented control, e.g. Chat / Research / Code. |
| mode | `string` | — |  |
| defaultMode | `string` | — |  |
| onModeChange | `(id: string) => void` | — |  |
| maxTokens | `number` | — | Context limit; shows the counter and blocks sending above it. |
| countTokens | `(text: string) => number` | — | Your tokenizer; defaults to about one token per four characters. |
| placeholder | `string` | — | Textarea placeholder; also its accessible name. |
| minRows | `number` | `1` |  |
| maxRows | `number` | `8` |  |
| submitOnEnter | `boolean` | `true` | Enter sends (Shift+Enter adds a line). false: only Cmd/Ctrl+Enter sends. |
| disabled | `boolean` | — |  |
| footer | `React.ReactNode` | — | Extra controls at the start of the footer. |
| labels | `Partial<ChatComposerLabels>` | — | Text for built-in controls and screen readers; pass translations here. |
| sound | `boolean \| SoundName` | — | Plays "send" on submit when the visitor has sounds on (lib/goodui-sounds); a sound name picks another. Off by default. |

Also accepts every <form> attribute.

## Keyboard

| Keys | Action |
| --- | --- |
| Enter | Sends (unless submitOnEnter is false or an IME composition is in progress). Shift+Enter inserts a new line. |
| Cmd/Ctrl+Enter | Always sends. |
| / at the start | Opens the command menu, filtered by what follows. |
| ArrowUp / ArrowDown | Moves through the command menu. |
| Enter / Tab | Picks the active command; Escape closes the menu. |

## Accessibility

- The textarea has an aria-label (the placeholder) and is described by a hidden hint explaining Enter and Shift+Enter.
- The command menu is a listbox with option rows; the modes are a radiogroup; the send button's label switches between Send and Stop.
- The token counter is read as "1.2K of 8K tokens" or "Over the token limit"; attachment remove buttons are labelled with the file name.
- Built-in strings go through the labels prop for translation.

## Motion

- The textarea grows with its content between minRows and maxRows (height set from scrollHeight, no transition).
- The command menu springs up from the bottom edge (stiffness 520, damping 34) with rows staggered 30 ms; the active row highlight glides on a shared-layout spring.
- Attachment chips spring in at 0.8 scale and the row's height animates to fit; the send arrow and stop square swap with a rotate-and-scale spring; the token ring eases over 0.35 s.
- Reduced motion: menus and chips fade, the icon swap is a fade, the ring jumps.

## Notes for AI

- onSubmit gets the trimmed text and { attachments, model, mode }. When uncontrolled, the field and attachments clear after submit.
- While streaming is true the button calls onStop instead of submitting; sending is also blocked when the text is empty (and no attachments) or over maxTokens.
- The default token estimate is characters / 4; pass countTokens for your tokenizer.
- Attachments created from files get an object URL for image previews; revoke them yourself if you keep attachments around for long.
- The built-in model picker is model-picker (installed alongside); pass models to show it.

## FAQ

**How do I add my own buttons to the footer?**

Pass them as `footer`; they render after the attach button.

**Can I keep sending on Enter but insert newlines on mobile?**

Set submitOnEnter={false} on touch devices; the send button and Cmd/Ctrl+Enter still work.

## Related

- model-picker: https://goodui.dev/components/ai/model-picker
- chat-message: https://goodui.dev/components/ai/chat-message
- suggestion-chips: https://goodui.dev/components/ai/suggestion-chips
- streaming-text: https://goodui.dev/components/ai/streaming-text
- token-meter: https://goodui.dev/components/ai/token-meter

Last updated: 2026-11-03

---

# Citations

> Inline numbered source chips that open a spring hover card with title, domain, snippet and date, a CitedText helper that turns [1] markers into chips, and a sources list whose row lights up when its chip is hovered.

Inline citations for AI answers in React: numbered source chips with hover cards and a sources list

Page: https://goodui.dev/components/ai/citations

## Install

```bash
npx shadcn@latest add @goodui/citations
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/citations.json`. The file lands in `components/goodui/citations.tsx`.

## When to use

- RAG or search-grounded answers where each claim points at a document, page or record.
- Answers that quote internal docs, policies or reports: the card shows the snippet without leaving the chat.
- A sources list under the answer, with the matching row lighting up when a chip is hovered.

## When not to use

- Academic footnotes in long documents: a footnote list at the end of the page reads better.
- A single link: a plain anchor.

## Pick by what matters

| Need | Use |
| --- | --- |
| Model output with [1] markers | <CitedText text={answer} /> |
| Hand-placed chips in JSX | <Cite n={2} /> anywhere inside <Citations> |
| Card below the chip | side="bottom" (it flips automatically near the top of the viewport) |
| Short list with Show all | <SourceList limit={3} /> |

## Usage

```tsx
import { Citations, CitedText, SourceList } from "@/components/goodui/citations"

<Citations sources={[
  { n: 1, title: "Deposits and no-show fees", url: "https://help.example.com/deposits", snippet: "New clients pay a 20% deposit…", date: "Oct 2026" },
  { n: 2, title: "No-show report, September–October", url: "https://reports.example.com/no-shows", date: "Nov 1, 2026" },
]}>
  <p><CitedText text="No-shows fell from 9 to 3 [2] after the deposit rule [1]." /></p>
  <SourceList limit={3} />
</Citations>
```

### Chips in your own markup

```tsx
<p>Deposits are refundable for 24 hours<Cite n={1} />, and reminders go out twice<Cite n={3} />.</p>
```

### Favicon per source

```tsx
{ n: 1, title: "Stripe docs", url: "https://docs.stripe.com/payments", icon: <img src="/favicons/stripe.png" alt="" /> }
```

## API

### Citations

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| sources (required) | `CitationSource[]` | — |  |
| labels | `Partial<CitationsLabels>` | — | Text for built-in controls and screen readers; pass translations here. |

Also accepts every <div> attribute.

### Cite

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| n (required) | `number` | — | Source number, matching a source's `n`. |
| side | `"top" \| "bottom"` | `"top"` | Where the hover card opens. |

Also accepts every <element> attribute.

### CitedText

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| text (required) | `string` | — | Text with "[1]" style markers. |

Also accepts every <span> attribute.

### SourceList

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| limit | `number` | `3` | Rows shown before a "Show all" button. |
| hideTitle | `boolean` | `false` | Hide the "Sources" heading. |

Also accepts every <section> attribute.

## Keyboard

| Keys | Action |
| --- | --- |
| Tab | Moves between chips; focusing a chip opens its card. |
| Enter | Opens the source URL in a new tab (chips with a URL are links); on a chip without a URL, Enter or Space opens the card. |
| Escape | Closes the card. |

## Accessibility

- Each chip is a link (new tab, rel="noreferrer") when the source has a URL, otherwise a <button>; both are labelled "Source n: title" and described by the open card (role="tooltip") through aria-describedby.
- The card opens on hover (mouse only) and focus, and closes on blur, Escape, scroll or resize.
- The sources list is an ordered list; rows with a URL are links named by their title, domain and date, with an "Open source" tooltip.
- Built-in strings go through the labels prop for translation.

## Motion

- The card scales from 0.94 at the chip's edge on a spring (stiffness 560, damping 32) and fades out in 120 ms; it is positioned fixed and clamped to the viewport.
- Source rows spring into place when the list expands; the hovered chip's row and number tile change color.
- Reduced motion: the card and rows fade only.

## Notes for AI

- Wrap the answer and the list in <Citations sources>. Source numbers (n) are what CitedText matches: [2] renders source n=2.
- CitedText only understands [n] markers. Convert other formats (【1】, ^1) before passing the text.
- A chip whose number has no matching source renders nothing.
- domain is derived from url when omitted; snippet, date and icon are optional.

## FAQ

**Why is the card positioned fixed?**

So it can escape chat containers with overflow hidden or scrolling. It closes on scroll instead of following the chip.

**Why is a chip sometimes a link and sometimes a button?**

With a URL it is a real link, so middle-click, copy link and screen readers' link lists work. Without one it is a button that only opens the card.

## Related

- chat-message: https://goodui.dev/components/ai/chat-message
- tooltip: https://goodui.dev/components/core/tooltip
- popover: https://goodui.dev/components/core/popover
- link: https://goodui.dev/components/core/link

Last updated: 2026-11-03

---

# Agent plan

> Live checklist of an agent's plan: pending, active with a pulsing halo, drawn check, error and skipped states, nested substeps that fold away when done, and a spring progress bar with a step count.

Agent plan checklist for React: steps with live status, nested substeps, drawn checkmarks and overall progress

Page: https://goodui.dev/components/ai/agent-plan

## Install

```bash
npx shadcn@latest add @goodui/agent-plan
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/agent-plan.json`. The file lands in `components/goodui/agent-plan.tsx`.

## When to use

- Coding or workflow agents that announce a plan and then execute it step by step.
- Long tasks where the user wants to see what is done, what is running and what failed.
- Plans with sub-tasks: migrations under a feature, files under a refactor.

## When not to use

- A single tool invocation with arguments and output: use tool-call.
- A wizard the user walks through: use stepper or multi-step-form.
- Static feature checklists on marketing pages: a plain list with icons.

## Pick by what matters

| Need | Use |
| --- | --- |
| Steps with substeps | steps on a PlanStep; the parent's status is yours to set |
| Keep finished substeps visible | autoCollapse={false} |
| No header bar | showProgress={false} and no title |
| Inside a message without a border | variant="plain" |
| Clickable steps (open a file, show a log) | onStepClick |

## Usage

```tsx
import { AgentPlan, type PlanStep } from "@/components/goodui/agent-plan"

const steps: PlanStep[] = [
  { id: "read", title: "Read the current booking rules", status: "done" },
  { id: "deposit", title: "Add a deposit for Instagram bookings", status: "active", steps: [
    { id: "schema", title: "Add source to the bookings table", status: "done" },
    { id: "rule", title: "Charge 20% for new Instagram clients", status: "active" },
  ] },
  { id: "tests", title: "Run the pricing tests", status: "pending" },
]

<AgentPlan title="Deposit for Instagram bookings" steps={steps} />
```

### Failed step, rest skipped

```tsx
steps={[{ id: "tests", title: "Run tests", status: "error", detail: "2 failing in pricing.test.ts" }, { id: "deploy", title: "Deploy", status: "skipped" }]}
```

### Open the file on click

```tsx
<AgentPlan steps={steps} onStepClick={(s) => openFile(s.detail)} />
```

## API

### AgentPlan

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| steps (required) | `PlanStep[]` | — |  |
| title | `React.ReactNode` | — |  |
| showProgress | `boolean` | `true` | Progress bar and count in the header. |
| autoCollapse | `boolean` | `true` | Substeps fold away once their parent is done (they can be reopened). |
| variant | `"card" \| "plain"` | `"card"` | card: bordered; plain: just the list. |
| onStepClick | `(step: PlanStep) => void` | — |  |
| labels | `Partial<AgentPlanLabels>` | — | Text for built-in controls and screen readers; pass translations here. |

Also accepts every <section> attribute.

## Keyboard

| Keys | Action |
| --- | --- |
| Enter / Space | Toggles substeps on the chevron button; activates a step when onStepClick is set. |

## Accessibility

- The plan is a <section> labelled by its title; the header bar is a progressbar with aria-valuenow and text like "3 of 7 steps".
- Each step's status is read as text (Pending, In progress, Done, Failed, Skipped) before its title; icons are decorative.
- Substep toggles are buttons with aria-expanded and aria-controls. Steps become buttons only when onStepClick is passed.
- Built-in strings go through the labels prop for translation.

## Motion

- Status icons swap on a spring (stiffness 520, damping 26); the done check draws its stroke over 0.28 s; the active step spins with a halo pulsing outward every 1.6 s.
- Steps spring in 6px from below; substeps open to their height on a spring (stiffness 420, damping 36) and fold away when the parent is done (autoCollapse).
- The progress bar scales to the completed share on a spring (stiffness 260, damping 30) and turns green at 100% or rose on an error.
- Reduced motion: no halo, no stroke drawing, instant height changes and plain fades.

## Notes for AI

- Statuses: pending, active, done, error, skipped. Progress counts leaf steps only; done and skipped count as complete.
- Give every step a stable id; it is the React key and the collapse state key.
- Set the parent's status yourself (active while any child runs, done when all are done); the component does not infer it.
- autoCollapse folds substeps of a done parent; the chevron reopens them.

## FAQ

**Can steps be removed or reordered live?**

Yes. Rows animate their position and exit with a fade; keep ids stable.

## Related

- tool-call: https://goodui.dev/components/ai/tool-call
- reasoning-block: https://goodui.dev/components/ai/reasoning-block
- stepper: https://goodui.dev/components/navigation/stepper
- multi-step-loader: https://goodui.dev/components/feedback/multi-step-loader

Last updated: 2026-11-03

---

# Token meter

> Context window usage bar whose segments (system, history, tools, response) spring to new widths, with rolling numbers, a legend, and amber then rose tones near and over the limit.

Context window token meter for React: segmented usage bar with rolling numbers and limit warnings

Page: https://goodui.dev/components/ai/token-meter

## Install

```bash
npx shadcn@latest add @goodui/token-meter
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/token-meter.json`. The file lands in `components/goodui/token-meter.tsx`.

## When to use

- Showing how much of the model's context is used, split into system prompt, history, tool results and the response.
- Agent dashboards where the budget matters: it turns amber at 80% and rose at 95% or over.
- Per-conversation cost or quota meters with a single number.

## When not to use

- Plan quotas unrelated to tokens (seats, SMS credits): use meter.
- Live counting while typing: chat-composer has its own small ring.

## Pick by what matters

| Need | Use |
| --- | --- |
| One number | used + max |
| Breakdown with legend | segments (used is their sum) |
| Show what is left | showRemaining |
| Exact numbers | format="full" |
| Other thresholds | warnAt and dangerAt as fractions of max |

## Usage

```tsx
import { TokenMeter } from "@/components/goodui/token-meter"

<TokenMeter
  label="Context window"
  max={200_000}
  segments={[
    { label: "System prompt", value: 1_240 },
    { label: "History", value: 38_400 },
    { label: "Tool results", value: 6_120 },
    { label: "Response", value: 2_310 },
  ]}
/>
```

### Single value near the limit

```tsx
<TokenMeter label="Conversation" used={171_300} max={200_000} size="sm" />
```

### Remaining budget in full numbers

```tsx
<TokenMeter label="Remaining" used={62_500} max={128_000} showRemaining format="full" />
```

## API

### TokenMeter

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| max (required) | `number` | — | The context window. |
| used | `number` | — | Tokens used, when there is one number. |
| segments | `TokenSegment[]` | — | Breakdown by part of the context; used = sum of the values. |
| label | `React.ReactNode` | — |  |
| warnAt | `number` | `0.8` | Fraction of max where the meter turns amber. |
| dangerAt | `number` | `0.95` | Fraction of max where it turns rose. |
| showLegend | `boolean` | `true` | Show the segment legend. |
| showRemaining | `boolean` | `false` | Show the remaining count instead of used / max. |
| format | `"compact" \| "full"` | `"compact"` | Compact (12.4K) or full (12,400) numbers. |
| size | `"sm" \| "md" \| "lg"` | `"md"` |  |
| locale | `string` | `"en-US"` |  |
| labels | `Partial<TokenMeterLabels>` | — | Text for built-in controls and screen readers; pass translations here. |

Also accepts every <div> attribute.

## Accessibility

- The bar is role="meter" with aria-valuemin, aria-valuemax, aria-valuenow and an aria-valuetext such as "38,400 of 200K tokens used. Close to the limit".
- The rolling number is aria-hidden; the meter's text carries the value for screen readers. Legend values are plain text.
- Built-in strings go through the labels prop for translation.

## Motion

- Each segment is a flex item sized by its tokens; when values change they spring to their new widths through motion's layout animation (stiffness 260, damping 30).
- The used number rolls digit by digit (number-flow, installed alongside).
- Reduced motion: widths and digits change instantly.

## Notes for AI

- Pass either used or segments; with segments, used is their sum and the legend lists them with --chart-1..5 colors unless color is set.
- max is the context window in tokens. Values above max are shown as over the limit (rose) and the bar is capped.
- format="compact" prints 38.4K / 200K; "full" prints 38,400 / 200,000 in the given locale.

## FAQ

**Can I color a segment?**

Yes, segment.color takes any CSS color, for example var(--chart-3) or an oklch value.

## Related

- meter: https://goodui.dev/components/numbers/meter
- progress: https://goodui.dev/components/numbers/progress
- number-flow: https://goodui.dev/components/numbers/number-flow
- chat-composer: https://goodui.dev/components/ai/chat-composer

Last updated: 2026-11-03

---

# Voice orb

> Breathing voice-assistant orb that swells with a level prop through a spring: idle breathing, listening rings, speaking light that churns faster, and a spinning thinking arc, all in CSS on theme colors.

Voice assistant orb for React: breathing sphere that reacts to audio level with idle, listening, speaking and thinking states

Page: https://goodui.dev/components/ai/voice-orb

## Install

```bash
npx shadcn@latest add @goodui/voice-orb
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/voice-orb.json`. The file lands in `components/goodui/voice-orb.tsx`.

## When to use

- Voice assistants and call agents: one object that shows whether the assistant is idle, listening, thinking or speaking.
- Visualising a microphone or playback level without a waveform.
- Hero or empty-state art for an AI product, kept alive by the slow breathing loop.

## When not to use

- Text chat loading states: use typing-indicator.
- Precise audio visualisation (bars, waveforms) for recording tools: draw a canvas waveform.

## Pick by what matters

| Need | Use |
| --- | --- |
| Microphone input | state="listening" with level from an AnalyserNode |
| Assistant audio playing | state="speaking" with the output level |
| Waiting for the model | state="thinking" |
| Brand colors | color and accent (any CSS color); defaults are --chart-1 and --chart-4 |
| Exact pixel size | size={120} |

## Usage

```tsx
import { VoiceOrb } from "@/components/goodui/voice-orb"

<VoiceOrb state={call.state} level={micLevel} size="lg" />

// level from the Web Audio API
const analyser = audioContext.createAnalyser()
source.connect(analyser)
const data = new Uint8Array(analyser.frequencyBinCount)
function tick() {
  analyser.getByteTimeDomainData(data)
  let sum = 0
  for (const v of data) sum += ((v - 128) / 128) ** 2
  setMicLevel(Math.min(1, Math.sqrt(sum / data.length) * 6))
  requestAnimationFrame(tick)
}
```

### Small orbs in brand colors

```tsx
<VoiceOrb state="idle" size="sm" color="var(--chart-2)" accent="var(--chart-3)" labels={{ idle: "Support bot idle" }} />
```

### Translated state names

```tsx
<VoiceOrb state="listening" labels={{ idle: "Bereit", listening: "Hört zu", speaking: "Spricht", thinking: "Denkt nach" }} />
```

## API

### VoiceOrb

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| color | `string` | — | Main color (any CSS color); defaults to --chart-1. |
| state | `"idle" \| "listening" \| "speaking" \| "thinking"` | `"idle"` |  |
| level | `number` | `0` | Audio level 0..1 (microphone while listening, output while speaking). |
| size | `number \| "sm" \| "md" \| "lg"` | `"md"` | Diameter in px, or a preset. |
| accent | `string` | — | Second color for the inner light; defaults to --chart-4. |
| labels | `Partial<VoiceOrbLabels>` | — | Text for screen readers per state; pass translations here. |

Also accepts every <div> attribute.

## Accessibility

- The visual is role="img" labelled with the current state (Assistant idle, Listening, Speaking, Thinking); a visually hidden role="status" region announces state changes.
- Nothing inside is interactive; wrap it in a button if tapping should start listening.
- Reduced motion stops the breathing, spinning blobs, rings and arc; the state is still shown by a static ring (listening), a dashed ring (thinking) and the level by the orb's size.

## Motion

- Idle: the orb breathes between 1 and 1.045 scale every 4.2 s; two blob layers with conic gradients rotate slowly (11 s and 15 s) under soft-light blending.
- Listening: three rings expand from 0.86 to 1.55 scale every 1.9 s, staggered 0.65 s; the orb scales up to 1.22 with the level. Speaking: the blobs spin fast (2.6 s and 3.4 s) and the glow grows with the level. Thinking: a thin arc spins once per 1.3 s.
- The level goes through a spring (stiffness 220, damping 20, mass 0.6) so bursts feel physical; under reduced motion it jumps.
- Everything loops in CSS on transform and opacity; the glow is one blurred layer.

## Performance

- No canvas or WebGL: three gradient layers, one blur filter and CSS keyframes. Expect well under 1% CPU at rest on a laptop; the blur radius scales with the orb size.

## Notes for AI

- level is 0..1 and only matters in listening and speaking states; feed it 30–60 times a second for a live feel.
- state is one of idle, listening, speaking, thinking. Change it as the call progresses; the orb has no internal state machine.
- Pass color and accent as CSS colors (var(--chart-2), oklch(...)); they drive gradients and glows through CSS variables.

## FAQ

**Why does the level feel delayed?**

It is smoothed through a spring so single noisy frames do not twitch the orb. Lower the stiffness in the source if you want it snappier.

## Related

- typing-indicator: https://goodui.dev/components/ai/typing-indicator
- chat-composer: https://goodui.dev/components/ai/chat-composer
- aurora: https://goodui.dev/components/backgrounds/aurora
- spinners: https://goodui.dev/components/feedback/spinners

Last updated: 2026-11-03

---

# Diff view

> Unified or split diff computed from before and after text, with old/new gutters, syntax colors, changed-character highlights inside replaced lines, and Accept or Reject per hunk that collapses the discarded lines.

Diff viewer for AI code edits in React: unified or split view, syntax colors, changed-character highlights, accept or reject per hunk

Page: https://goodui.dev/components/ai/diff-view

## Install

```bash
npx shadcn@latest add @goodui/diff-view
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/diff-view.json`. The file lands in `components/goodui/diff-view.tsx`.

## When to use

- Reviewing edits an agent proposes to a file before applying them, hunk by hunk.
- Showing what changed between two versions of a prompt, config or document.
- Pull-request style views where syntax colors and changed characters matter.

## When not to use

- Diffs of very large files (tens of thousands of lines): compute them server-side and virtualize.
- Word-level prose comparison: a text diff that highlights words inline reads better than line rows.

## Pick by what matters

| Need | Use |
| --- | --- |
| Narrow column, chat sidebar | mode="unified" |
| Review on a wide screen | mode="split" (old and new side by side) |
| Accept/Reject buttons | onDecision (or reviewable) |
| Fewer context lines | context={1} |
| Long lines | wrap |

## Usage

```tsx
import { DiffView } from "@/components/goodui/diff-view"

<DiffView
  before={original}
  after={proposed}
  language="ts"
  fileName="lib/pricing.ts"
  onDecision={(hunk, decision) => decision && apply(hunk, decision)}
/>
```

### Controlled decisions

```tsx
const [decisions, setDecisions] = React.useState<Record<number, "accepted" | "rejected" | undefined>>({})
<DiffView before={a} after={b} decisions={decisions} onDecision={(i, d) => setDecisions((s) => ({ ...s, [i]: d ?? undefined }))} />
```

### Read-only split view

```tsx
<DiffView before={a} after={b} mode="split" modeToggle={false} language="json" />
```

## API

### DiffView

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| before (required) | `string` | — |  |
| after (required) | `string` | — |  |
| language | `"html" \| "text" \| "ts" \| "tsx" \| "js" \| "jsx" \| "json" \| "bash" \| "sh" \| "python" \| "py" \| "css" \| "sql" \| "yaml" \| "yml"` | `"text"` |  |
| fileName | `string` | — |  |
| mode | `"unified" \| "split"` | — | unified (one column) or split (old and new side by side). |
| defaultMode | `"unified" \| "split"` | `"unified"` |  |
| onModeChange | `(mode: "unified" \| "split") => void` | — |  |
| modeToggle | `boolean` | `true` | Show the Unified/Split toggle. |
| context | `number` | `3` | Unchanged lines kept around each change. |
| reviewable | `boolean` | — | Accept/Reject buttons per hunk. On by default when onDecision is passed. |
| decisions | `Record<number, HunkDecision \| undefined>` | — | Hunk decisions by hunk index (controlled). |
| onDecision | `(hunkIndex: number, decision: HunkDecision \| null, hunk: DiffHunk) => void` | — |  |
| wrap | `boolean` | `false` | Wrap long lines instead of scrolling. |
| maxHeight | `number` | — | Scroll inside the view beyond this height (px). |
| labels | `Partial<DiffViewLabels>` | — | Text for built-in controls and screen readers; pass translations here. |

Also accepts every <div> attribute.

## Keyboard

| Keys | Action |
| --- | --- |
| Tab | Moves through the view toggle and each hunk's Accept, Reject and Undo buttons. |
| ArrowLeft / ArrowRight | Switches Unified and Split on the view radio group (native radio behavior). |

## Accessibility

- Each hunk is a <section> labelled "Change n"; added and removed lines carry a visually hidden + or − before the text; line numbers and markers are decorative.
- The +n −n counters in the header are labelled "n additions" and "n deletions". The view toggle is a radiogroup.
- Decisions show as text badges (Accepted, Rejected) with an Undo button.
- Built-in strings go through the labels prop for translation.

## Motion

- Accepting a hunk collapses its removed lines (height to 0 in 180 ms) and settles the added ones; rejecting does the reverse. Undo brings them back.
- The Accept/Reject pair cross-fades with the decision badge; the view toggle's pill glides on a shared-layout spring.
- Reduced motion: rows and controls swap instantly.

## Performance

- The line diff is an LCS over the lines that differ after trimming the common prefix and suffix; pairs larger than 4 million cells fall back to a plain replace. Tokens are computed once per side and reused by both modes.

## Notes for AI

- Pass whole file contents as before and after; the component computes the diff. Hunks are numbered from 0 in onDecision.
- decision is "accepted", "rejected" or null (undo). Applying the decision to your file is up to you; the view only reflects it.
- language uses the code-block tokenizer (ts, tsx, js, json, bash, python, css, html, sql, yaml).
- Split mode needs about 640px; it scrolls horizontally inside the component when narrower (unless wrap is on).

## FAQ

**Why are only some characters highlighted inside a changed line?**

When a block replaces the same number of lines, each pair is compared and only the differing middle part gets the stronger tint.

**Does it produce a patch?**

No. Use diffLines and toHunks (exported) to build one from the same data.

## Related

- code-block: https://goodui.dev/components/ai/code-block
- tool-call: https://goodui.dev/components/ai/tool-call
- agent-plan: https://goodui.dev/components/ai/agent-plan
- chat-message: https://goodui.dev/components/ai/chat-message

Last updated: 2026-11-03

---

# Code block

> Syntax-colored code from a built-in tokenizer or your own tokens, with theme-derived colors, line numbers, highlighted lines, a file tab, copy with a drawn check, a wrap toggle and a staggered line entrance.

Code block component for React: syntax colors from the theme, line numbers, copy button, wrap toggle and file tab

Page: https://goodui.dev/components/ai/code-block

## Install

```bash
npx shadcn@latest add @goodui/code-block
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/code-block.json`. The file lands in `components/goodui/code-block.tsx`.

## When to use

- Code in assistant answers, docs and settings pages, with copy and wrap built in.
- Short snippets in a dozen common languages without shipping a highlighter.
- Pre-highlighted tokens from shiki or prism when you already run one: pass tokens and keep the colors consistent.

## When not to use

- Editable code: use an editor component.
- Highlighting for rare languages with exact grammar needs: run shiki and pass tokens.

## Pick by what matters

| Need | Use |
| --- | --- |
| Snippet in a message | code + language (chat-message does this for fences) |
| File context | fileName="lib/pricing.ts" |
| Draw attention to lines | highlightLines={[9, 10]} |
| Your own highlighter | tokens={lines} with CodeToken types |
| Answer that appears progressively | appear="lines" |

## Usage

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

<CodeBlock
  fileName="app/api/bookings/route.ts"
  language="ts"
  highlightLines={[9, 10]}
  maxHeight={380}
  code={source}
/>
```

### Tokens from shiki

```tsx
const { tokens } = await highlighter.codeToTokens(code, { lang: "tsx", theme: "github-light" })
const lines = tokens.map((line) => line.map((t) => ({ content: t.content, type: typeOf(t) })))
<CodeBlock code={code} tokens={lines} />
```

### Minimal: no header controls

```tsx
<CodeBlock code={cmd} language="bash" showLineNumbers={false} wrapToggle={false} />
```

### Reuse the tokenizer

```tsx
import { tokenizeCode, CodeTokens } from "@/components/goodui/code-block"
const lines = tokenizeCode(src, "json")
```

## API

### CodeBlock

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| code (required) | `string` | — | Source text. Tokenized with the built-in tokenizer unless `tokens` is passed. |
| title | `string` | — | Replaces the language label next to the file tab. |
| onCopy | `(code: string) => void` | — |  |
| language | `"ts" \| "tsx" \| "js" \| "jsx" \| "json" \| "bash" \| "sh" \| "python" \| "py" \| "css" \| "html" \| "sql" \| "yaml" \| "yml" \| "text"` | `"text"` |  |
| tokens | `CodeToken[][]` | — | Pre-tokenized lines from your own highlighter; each token's type picks the color. Overrides the built-in tokenizer. |
| fileName | `string` | — | Shown as a tab in the header, e.g. "lib/booking.ts". |
| showLineNumbers | `boolean` | `true` |  |
| startLine | `number` | `1` | Number of the first line. |
| highlightLines | `number[]` | — | 1-based line numbers (counted from startLine) to highlight. |
| wrap | `boolean` | — | Controlled wrap state. |
| defaultWrap | `boolean` | `false` |  |
| onWrapChange | `(wrap: boolean) => void` | — |  |
| wrapToggle | `boolean` | `true` | Show the wrap toggle. |
| copy | `boolean` | `true` | Show the copy button. |
| maxHeight | `number` | — | Scroll inside the block beyond this height (px). |
| appear | `"none" \| "fade" \| "lines"` | `"none"` | Entrance: lines fade up one after another, the whole block fades, or nothing. |
| labels | `Partial<CodeBlockLabels>` | — | Text for built-in controls and screen readers; pass translations here. |

Also accepts every <div> attribute.

### CodeTokens

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| tokens (required) | `CodeToken[]` | — |  |

## Keyboard

| Keys | Action |
| --- | --- |
| Tab | Moves between the wrap toggle and the copy button; Enter or Space activates them. |

## Accessibility

- The copy button is labelled Copy code and announces Copied through a polite live region; the wrap toggle uses aria-pressed.
- Line numbers are aria-hidden and not selectable, so copying a selection gives clean code.
- Token colors are mixed from --chart-1..5 toward the foreground in light mode and toward white in dark mode to keep 4.5:1 contrast on the card background.
- Built-in strings go through the labels prop for translation.

## Motion

- appear="lines" fades each line up 4px with a 28 ms stagger (capped at 24 lines); appear="fade" fades the whole block; the default is static.
- The copy icon scales out as a green check scales in (200 ms) and reverts after 1.6 s.
- Reduced motion: no entrance animation; the icon swap is instant.

## Performance

- The tokenizer is a sticky-regex scanner, one pass per line with a small carry-over state for block comments and template strings; results are memoised on code and language.

## Notes for AI

- Supported languages: ts, tsx, js, jsx, json, bash/sh, python/py, css, html, sql, yaml/yml, text. Unknown languages render plain.
- highlightLines are 1-based and count from startLine.
- Pass tokens (CodeToken[][]) to skip the built-in tokenizer; types are keyword, string, number, comment, function, type, property, punctuation, operator, tag, attr, variable, constant, plain.
- maxHeight makes the body scroll; wrap turns off horizontal scrolling by wrapping lines.

## FAQ

**Is the built-in tokenizer accurate?**

It is a lightweight scanner tuned for readable colors, not a parser. JSX attributes and regex literals are not special-cased. For exact grammars, pass tokens from shiki.

**Can I theme the colors?**

Yes. They derive from --chart-1..5; override the --pc-code-* variables on .pc-code for finer control.

## Related

- diff-view: https://goodui.dev/components/ai/diff-view
- chat-message: https://goodui.dev/components/ai/chat-message
- copy-button: https://goodui.dev/components/buttons/copy-button

Last updated: 2026-11-03

---

# Suggestion chips

> Starter prompts that stagger in on springs, lift on hover and fill the composer on click, as pills, cards with hints or a scrolling row with faded edges; swapping the set replays the entrance.

Prompt suggestion chips for React AI chat: staggered entrance, hover lift, cards or a scrolling row, fills the composer

Page: https://goodui.dev/components/ai/suggestion-chips

## Install

```bash
npx shadcn@latest add @goodui/suggestion-chips
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/suggestion-chips.json`. The file lands in `components/goodui/suggestion-chips.tsx`.

## When to use

- The empty state of a chat: three to six starter prompts that show what the assistant can do.
- Follow-up ideas under an answer ("Draft the SMS", "Show the query").
- Mobile layouts: the scroll variant keeps one row with faded edges.

## When not to use

- Selecting filters or tags: use toggle-group or badge chips.
- Dozens of options: a searchable list is faster than a wall of chips.

## Pick by what matters

| Need | Use |
| --- | --- |
| Compact pills | variant="chip" (default) |
| Icon, title and a hint line | variant="card" |
| One scrolling row | variant="scroll" |
| Keep only the picked chip | clearOnSelect |
| Replay the entrance for a new set | change playKey |

## Usage

```tsx
import { SuggestionChips } from "@/components/goodui/suggestion-chips"
import { ChatComposer } from "@/components/goodui/chat-composer"

const [draft, setDraft] = React.useState("")

<SuggestionChips
  suggestions={[
    { label: "Who hasn't rebooked?", prompt: "Which clients haven't rebooked in the last 60 days?", icon: <Users /> },
    { label: "Weekly revenue recap", prompt: "Summarise this week's revenue against last week.", icon: <ChartNoAxesCombined /> },
  ]}
  onSelect={setDraft}
/>
<ChatComposer value={draft} onValueChange={setDraft} onSubmit={send} />
```

### Plain strings

```tsx
<SuggestionChips suggestions={["Summarise this chat", "Draft a reply", "Translate to Spanish"]} onSelect={send} />
```

### Cards with hints

```tsx
<SuggestionChips variant="card" suggestions={[{ label: "Fill Tuesday afternoon", hint: "Uses your quietest hours", icon: <CalendarClock /> }]} onSelect={setDraft} />
```

## API

### SuggestionChips

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| suggestions (required) | `Suggestion[]` | — |  |
| onSelect | `(prompt: string, suggestion: Exclude<Suggestion, string>) => void` | — |  |
| variant | `"chip" \| "card" \| "scroll"` | `"chip"` | chip: pills in a wrapping row. card: icon, label and hint in a grid. scroll: one horizontal row that scrolls. |
| stagger | `number` | `0.05` | Seconds between each chip's entrance. |
| clearOnSelect | `boolean` | `false` | Hide the other chips once one is picked. |
| playKey | `React.Key` | — | Change it to replay the entrance. |
| labels | `Partial<SuggestionChipsLabels>` | — | Text for screen readers; pass translations here. |

Also accepts every <div> attribute.

## Keyboard

| Keys | Action |
| --- | --- |
| Tab / Enter / Space | Chips are buttons: Tab moves between them, Enter or Space picks one. |

## Accessibility

- The container is a group labelled "Suggested prompts" (labels.suggestions); each chip is a real <button> with its label as text.
- The scroll variant uses a mask for the faded edges, so the content stays readable and focusable.
- Built-in strings go through the labels prop for translation.

## Motion

- Chips spring in from 10px below at 0.96 scale (stiffness 480, damping 30), staggered by `stagger` seconds (50 ms by default, capped at 12 items).
- Hover lifts a chip 2px and slides its arrow; press scales it to 0.97; replaced chips fade out while new ones enter.
- Reduced motion: fades only, no lift or press scale.

## Notes for AI

- onSelect receives the prompt (or the label when prompt is missing) and the suggestion object. Pair it with a controlled ChatComposer value.
- Changing the suggestions array animates the swap; pass playKey to force a replay with the same list.
- Suggestions are keyed by label; keep labels unique within a set.

## FAQ

**Can chips wrap on mobile?**

The chip variant wraps by default. Use the scroll variant when a single row matters more.

## Related

- chat-composer: https://goodui.dev/components/ai/chat-composer
- chat-message: https://goodui.dev/components/ai/chat-message
- badge: https://goodui.dev/components/core/badge
- toggle-group: https://goodui.dev/components/core/toggle-group

Last updated: 2026-11-03

---

# Thread list

> Conversation sidebar with search highlighting, pinned and date groups, a selection that glides between rows, hover actions on desktop and swipe-to-reveal on touch, inline rename, delete and arrow-key navigation.

Chat thread sidebar for React: conversation list with search, pin, rename, delete, date groups, hover and swipe actions

Page: https://goodui.dev/components/ai/thread-list

## Install

```bash
npx shadcn@latest add @goodui/thread-list
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/thread-list.json`. The file lands in `components/goodui/thread-list.tsx`.

## When to use

- The left rail of an assistant app: past conversations grouped by Pinned, Today, Yesterday, Previous 7 days, Previous 30 days and Older.
- Any list of named sessions where people pin, rename and delete inline.
- Mobile sheets: swipe a row to reveal actions.

## When not to use

- File or folder trees: use tree-expand.
- Inbox-style lists with avatars, unread counts and multi-select: build a table or list with checkboxes.

## Pick by what matters

| Need | Use |
| --- | --- |
| Hover actions on desktop, swipe on touch | swipe="auto" (default) |
| Always swipe | swipe |
| Flat list without date headings | groupByDate={false} |
| No search field | search={false} |
| Stable server rendering | now={fixedDate} |

## Usage

```tsx
import { ThreadList, type Thread } from "@/components/goodui/thread-list"

<ThreadList
  threads={threads}
  value={activeId}
  onValueChange={open}
  onNew={createThread}
  onPin={(id, pinned) => update(id, { pinned })}
  onRename={(id, title) => update(id, { title })}
  onDelete={remove}
  className="w-72"
/>
```

### Fixed reference time

```tsx
<ThreadList threads={threads} now={new Date("2026-11-03T15:30:00")} />
```

### Translated labels

```tsx
<ThreadList threads={threads} labels={{ search: "Chats durchsuchen", today: "Heute", yesterday: "Gestern", week: "Letzte 7 Tage", newChat: "Neuer Chat" }} />
```

## API

### ThreadList

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| threads (required) | `Thread[]` | — |  |
| defaultValue | `string` | — |  |
| value | `string` | — | Selected thread id (controlled). |
| onValueChange | `(id: string) => void` | — |  |
| onNew | `() => void` | — |  |
| onPin | `(id: string, pinned: boolean) => void` | — |  |
| onRename | `(id: string, title: string) => void` | — |  |
| onDelete | `(id: string) => void` | — |  |
| now | `number \| Date` | — | Reference time for the date groups and relative times. Pass a fixed value for stable server rendering. |
| search | `boolean` | `true` |  |
| groupByDate | `boolean` | `true` | Group under Pinned / Today / Yesterday / … headings. |
| swipe | `boolean \| "auto"` | `"auto"` | Swipe rows to reveal actions: on, off, or only on touch screens (auto). |
| labels | `Partial<ThreadListLabels>` | — | Text for built-in controls and screen readers; pass translations here. |

Also accepts every <nav> attribute.

## Keyboard

| Keys | Action |
| --- | --- |
| ArrowUp / ArrowDown | Moves focus between rows (wraps). Home / End jump to the first or last row. |
| Enter / Space | Opens the focused thread. |
| F2 | Renames the focused thread inline; Enter saves, Escape cancels. |
| Delete | Deletes the focused thread (when onDelete is set). |
| Tab | Reaches the row's Pin, Rename and Delete buttons, which also appear on hover. |

## Accessibility

- The list is a <nav>; the selected row's button has aria-current="true" and is the only row in the tab order (roving tabindex).
- Row actions are labelled buttons (Pin / Unpin, Rename, Delete) inside a group named "Chat actions"; in swipe mode the hidden tray is inert until revealed.
- Search matches are wrapped in <mark>; unread threads add a hidden "(Unread)" after the title.
- Built-in strings go through the labels prop for translation.

## Motion

- The selection highlight glides between rows as a shared-layout spring (stiffness 520, damping 40); rows spring into new positions when pinned or renamed and collapse on delete.
- Hover actions fade in over a gradient at the row's end; in swipe mode the row follows the finger and snaps open (136px) past 40% of the tray or a 400 px/s flick.
- Reduced motion: no glide, fades only, instant snap.

## Notes for AI

- threads need id, title and updatedAt (ISO string, timestamp or Date); preview, pinned and unread are optional.
- Grouping and relative times use `now`. Without it the component reads the clock after mount, so pass it for static or server rendering.
- Pin, rename and delete only change your data through the callbacks; the component does not keep its own copy of the threads.
- Rows are sorted newest first within each group.

## FAQ

**How do I confirm before deleting?**

Open a dialog in onDelete and remove the thread only after confirmation.

**Can I render it as a plain list without a nav?**

Not through a prop; the root is a <nav> because it is site navigation. Wrap or override with CSS if needed.

## Related

- chat-message: https://goodui.dev/components/ai/chat-message
- chat-composer: https://goodui.dev/components/ai/chat-composer
- list-reorder: https://goodui.dev/components/lists/list-reorder
- tree-expand: https://goodui.dev/components/lists/tree-expand

Last updated: 2026-11-03

---

# Eval score

> Evaluation score with a rolling number, a pass, borderline or fail badge that pops in against a threshold, a spring-filled bar and a criteria breakdown with per-criterion thresholds, as card, inline row or badge.

Eval score component for React: rolling score, pass/fail badge against a threshold and a criteria breakdown with bars

Page: https://goodui.dev/components/ai/eval-score

## Install

```bash
npx shadcn@latest add @goodui/eval-score
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/eval-score.json`. The file lands in `components/goodui/eval-score.tsx`.

## When to use

- Showing an LLM-as-judge or rubric result for a generated answer, with the criteria that made it up.
- Eval dashboards: inline rows per run, badges in tables, cards for the selected run.
- Any 0–100 (or 0–1, 0–5) quality score with a threshold.

## When not to use

- Many metrics over time: use a chart.
- Star ratings from people: use rating.

## Pick by what matters

| Need | Use |
| --- | --- |
| Detail view | variant="card" with criteria |
| Row in a list | variant="inline" |
| Cell in a table | variant="badge" |
| 0–1 scores | max={1} percent |
| Per-criterion thresholds | criteria[].threshold |

## Usage

```tsx
import { EvalScore } from "@/components/goodui/eval-score"

<EvalScore
  label="Win-back SMS · Maya Chen"
  score={82}
  threshold={70}
  criteria={[
    { label: "Tone", score: 90, note: "Warm, not pushy" },
    { label: "Accuracy", score: 78 },
    { label: "Brevity", score: 66, threshold: 75, note: "Fits one SMS segment" },
    { label: "Compliance", score: 96, threshold: 90 },
  ]}
/>
```

### Inline rows

```tsx
{runs.map((r) => <EvalScore key={r.id} variant="inline" label={r.name} score={r.score} threshold={70} size="sm" />)}
```

### Badges on different scales

```tsx
<EvalScore variant="badge" score={0.93} max={1} threshold={0.8} percent />
<EvalScore variant="badge" score={4.6} max={5} />
```

## API

### EvalScore

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| score (required) | `number` | — |  |
| max | `number` | `100` | Top of the scale. |
| threshold | `number` | — | Minimum passing score. Omit for no verdict. |
| margin | `number` | `5` | Scores within this distance under the threshold are "borderline" instead of a hard fail. |
| label | `React.ReactNode` | — |  |
| criteria | `EvalCriterion[]` | — | Per-criterion scores shown as bars under the main score. |
| variant | `"card" \| "inline" \| "badge"` | `"card"` | card: score, badge, bar and breakdown. inline: number, badge and a thin bar on one line. badge: just the badge with the score. |
| size | `"sm" \| "md" \| "lg"` | `"md"` |  |
| percent | `boolean` | `false` | Show the score as a percentage of max. |
| labels | `Partial<EvalScoreLabels>` | — | Text for built-in controls and screen readers; pass translations here. |

Also accepts every <div> attribute.

## Accessibility

- Each variant carries one visually hidden sentence such as "Win-back SMS: Score 82 / 100, Pass"; the animated number, bars and badge are aria-hidden so the value is read once.
- Verdict colors (green pass, amber borderline, rose fail) are paired with an icon and the word, never color alone.
- Built-in strings go through the labels prop for translation.

## Motion

- The score rolls digit by digit (number-flow, installed alongside); bars scale from the start edge on a spring (stiffness 180, damping 26); the verdict badge pops in from 0.6 scale.
- Criteria rows slide in 6px with a 60 ms stagger after the main bar.
- Reduced motion: digits, bars and badges change instantly, rows do not stagger.

## Notes for AI

- verdict: pass when score ≥ threshold, near when within `margin` (5 by default) under it, fail below that; no threshold means no badge.
- score and criteria share the same scale (max). percent shows score / max as a percentage.
- verdictOf(score, threshold, margin) is exported for consistent logic in tables and filters.

## FAQ

**Can I weight criteria?**

Compute the overall score yourself and pass it; criteria are displayed as given.

## Related

- number-flow: https://goodui.dev/components/numbers/number-flow
- meter: https://goodui.dev/components/numbers/meter
- delta-badge: https://goodui.dev/components/numbers/delta-badge
- stat-card: https://goodui.dev/components/core/stat-card

Last updated: 2026-11-03

---

# Typing indicator

> Three dots waving in turn with an "Aiko is typing" sentence for one or several names, as a chat bubble, inline or dots only, mounting and leaving on a spring; reduced motion keeps the dots still.

Typing indicator for React chat: three-dot wave with an "Aiko is typing" label, bubble, inline and dots-only variants

Page: https://goodui.dev/components/ai/typing-indicator

## Install

```bash
npx shadcn@latest add @goodui/typing-indicator
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/typing-indicator.json`. The file lands in `components/goodui/typing-indicator.tsx`.

## When to use

- The gap between sending a message and the first token of the answer.
- Human chat where one or more people are typing ("Aiko and Sam are typing").
- Inline status next to a name or in a header (inline or dots variant).

## When not to use

- Once tokens arrive: switch to streaming-text or chat-message with streaming.
- Long waits with known steps: reasoning-block or multi-step-loader say what is happening.

## Pick by what matters

| Need | Use |
| --- | --- |
| In the message list | variant="bubble" with avatar |
| Next to a name | variant="inline" |
| Just the dots | variant="dots" (the sentence stays for screen readers) |
| Several people | names={["Aiko", "Sam"]} |

## Usage

```tsx
import { TypingIndicator } from "@/components/goodui/typing-indicator"

<TypingIndicator names="Aiko" show={waitingForFirstToken} avatar={<Sparkles />} />
```

### Count instead of names

```tsx
<TypingIndicator variant="inline" names={typers} labels={{ typing: (n) => `${n.length} people are typing` }} />
```

### German

```tsx
<TypingIndicator names="Aiko" labels={{ typing: (n) => `${n.join(" und ")} schreibt…` }} />
```

## API

### TypingIndicator

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| names | `string \| string[]` | — | Who is typing. |
| show | `boolean` | `true` | Mount and unmount with an animation. |
| variant | `"bubble" \| "inline" \| "dots"` | `"bubble"` | bubble: a chat bubble with the dots. inline: dots and the sentence on one line. dots: dots only (the sentence stays for screen readers). |
| size | `"sm" \| "md" \| "lg"` | `"md"` |  |
| avatar | `React.ReactNode` | — | Avatar or icon shown before the bubble. |
| labels | `Partial<TypingIndicatorLabels>` | — | Text for screen readers; pass translations here. |

Also accepts every <div> attribute.

## Accessibility

- The root is role="status" with aria-live="polite", so showing it announces "Aiko is typing" once; the dots are aria-hidden.
- The dots variant keeps the sentence visually hidden; bubble and inline show it.
- Built-in strings go through the labels prop for translation (the sentence is a function of the names).

## Motion

- Three dots rise 35% and brighten in turn on a 1.2 s loop, offset by 150 ms each (CSS keyframes).
- show mounts it with a spring from 0.92 scale and 6px below (stiffness 520, damping 30) and unmounts with a 140 ms fade.
- Reduced motion: the dots stay still at 70% opacity and the entrance is a fade.

## Notes for AI

- Toggle show rather than conditionally rendering it, so the exit animation plays.
- names accepts a string or an array; with none, the sentence is "Typing".
- Place the bubble variant where the assistant's next message will appear; it uses the same 28px avatar slot as chat-message.

## FAQ

**Does it announce every time the names change?**

Yes, the live region reads the new sentence; keep name changes infrequent.

## Related

- chat-message: https://goodui.dev/components/ai/chat-message
- streaming-text: https://goodui.dev/components/ai/streaming-text
- spinners: https://goodui.dev/components/feedback/spinners
- reasoning-block: https://goodui.dev/components/ai/reasoning-block

Last updated: 2026-11-03

---

# Area chart

> Area chart that draws its line in on view, morphs between 1W / 1M / 1Y ranges, and rolls its headline value as a hairline and tooltip follow the pointer or the arrow keys.

Animated area chart for React and shadcn: draw-in, range morph, scrubbable with a rolling headline

Page: https://goodui.dev/components/charts/area-chart

## Install

```bash
npx shadcn@latest add @goodui/area-chart
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/area-chart.json`. The file lands in `components/goodui/area-chart.tsx`.

## When to use

- One metric over time with a headline that matters: revenue, bookings, visits, MRR.
- A time-range picker (1W / 1M / 1Y) where the curve should morph instead of flashing a new chart.
- Dashboards where the number should follow the pointer: hover or arrow through the points and the headline rolls to each value.

## When not to use

- Several series on one axis: use line-chart, which has a legend and a crosshair that reads every series.
- A trend under a KPI with no axes: use sparkline-draw or kpi-trend.
- Values that are not a magnitude from zero (temperatures, scores): an area fill implies volume, so use line-chart with baseline="auto".

## Pick by what matters

| Need | Use |
| --- | --- |
| Revenue card with ranges | ranges={[{ key, label, data }]} with format={{ style: "currency", currency: "USD" }} |
| Headline shows the latest value, not the sum | headline="last" (or "average", or "none") |
| Exact readings matter more than looks | curve="linear" |
| Compact card without axis chrome | axis={false} grid={false} height={150} |
| Percentages | formatValue={(v) => `${v}%`} formatTick={(v) => `${v}%`} |

## Usage

```tsx
import { AreaChart } from "@/components/goodui/area-chart"

const ranges = [
  { key: "1w", label: "1W", data: [{ label: "Mon", value: 1480 }, { label: "Tue", value: 1720 } /* … */] },
  { key: "1m", label: "1M", data: days.map((d) => ({ label: d.label, value: d.revenue })) },
  { key: "1y", label: "1Y", data: months.map((m) => ({ label: m.label, value: m.revenue })) },
]

export function RevenueCard() {
  return (
    <div className="rounded-xl border bg-card p-5">
      <AreaChart ranges={ranges} defaultRange="1m" title="Revenue" description="this period" format={{ style: "currency", currency: "USD", maximumFractionDigits: 0 }} height={220} />
    </div>
  )
}
```

### Single series, headline on the latest point

```tsx
<AreaChart data={bookings} title="Bookings" headline="last" description="today" color="var(--chart-2)" height={150} axis={false} grid={false} />
```

### Controlled range (the app owns the selection)

```tsx
const [range, setRange] = React.useState("1m")
<AreaChart ranges={ranges} range={range} onRangeChange={setRange} title="Visits" />
```

### Translated

```tsx
<AreaChart
  data={data}
  title="Umsatz"
  locale="de-DE"
  format={{ style: "currency", currency: "EUR" }}
  labels={{ range: "Zeitraum", columnLabel: "Zeitraum", columnValue: "Wert", noData: "Keine Daten", point: (label, value) => `${label}: ${value}` }}
/>
```

## API

### AreaChart

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| color | `string` | `"var(--chart-1)"` | Any CSS color for the line and gradient. Defaults to the theme's first chart color. |
| data | `AreaPoint[]` | — | Points in order, oldest first. Changing them morphs the curve to the new shape. |
| ranges | `AreaRange[]` | — | Named data sets with a built-in picker (1W / 1M / 1Y); the curve morphs between them. Takes precedence over data. |
| range | `string` | — | Selected range key (controlled). |
| defaultRange | `string` | — | Initial range key when uncontrolled; defaults to the first. |
| onRangeChange | `(key: string) => void` | — |  |
| title | `React.ReactNode` | — | Metric name above the headline, e.g. "Revenue". |
| headline | `"total" \| "last" \| "average" \| "none"` | `"total"` | What the rolling headline shows while nobody is scrubbing: the sum, the latest point, the average, or nothing. |
| description | `React.ReactNode` | — | Muted text beside the headline, replaced by the hovered point's label while scrubbing. |
| height | `number` | `220` | Plot height in px, axes included. The width follows the container. |
| curve | `"smooth" \| "linear"` | `"smooth"` | smooth: monotone curve that never overshoots the data. linear: straight segments. |
| grid | `boolean` | `true` | Horizontal hairline gridlines. |
| axis | `boolean` | `true` | Value ticks on the start side. |
| axisWidth | `number` | `44` | Space reserved for the value ticks, in px. |
| format | `Intl.NumberFormatOptions` | — | Intl.NumberFormat options for the headline, tooltip and ticks, e.g. { style: "currency", currency: "USD" }. |
| locale | `string` | `"en-US"` |  |
| formatValue | `(value: number) => string` | — | Replaces the default formatter for the tooltip, table and screen readers. |
| formatTick | `(value: number) => string` | — | Replaces the default tick formatter (compact above 10,000). |
| samples | `number` | `160` | Resampled points along the curve; a constant count is what lets 7 and 365 points morph into each other. |
| duration | `number` | `1.1` | Seconds the line takes to draw in. |
| labels | `Partial<AreaChartLabels>` | — | Text for built-in controls and screen readers; pass translations here. |

Also accepts every <div> attribute.

## Keyboard

| Keys | Action |
| --- | --- |
| Tab | Focuses the plot and highlights the latest point. |
| ArrowLeft / ArrowRight | Moves the hairline one point; the headline rolls to that value. |
| Home / End | Jumps to the first or last point. |
| Escape | Clears the highlight and tooltip. |
| Arrow keys in the range picker | Selects the previous or next range (radio group). |

## Accessibility

- The plot is role="group" with aria-roledescription="area chart" and an aria-label built from the data ("Revenue: from $1,480 to $2,110, low …, high …"); your aria-label replaces it.
- A screen-reader-only table lists every point (period, value) under the chart; the SVG itself is aria-hidden.
- The highlighted point is announced through a polite live region as "<label>: <value>".
- The range picker is a radiogroup of real buttons with aria-checked and roving tabindex.
- All built-in strings (summary, point, range, column headers, noData) go through labels.

## Motion

- On first view (IntersectionObserver, 20% visible) the line draws in with pathLength over duration (1.1 s, ease [0.65, 0, 0.35, 1]); the gradient area fades in over 0.7 s from 40% of that; the end dot pops on a spring (stiffness 420, damping 22) at 85%; x labels fade in left to right.
- Switching ranges or changing data morphs the path on a spring (stiffness 190, damping 30, mass 0.9). Every data set is resampled to `samples` points (160), so 7 and 365 points share one path shape; y ticks cross-fade and slide to their new positions.
- The hairline and active dot follow the pointer on a stiff spring (stiffness 600, damping 40); the headline digits roll with NumberFlow.
- A container resize re-lays the chart out instantly (no morph), and x labels that appear after the entrance fade in over 0.2 s without the stagger.
- The end dot sends out a ring every 2.4 s (CSS).
- Reduced motion: everything appears at its final state at once, morphs are instant, the ring is hidden; the gate waits for mount so the first client render matches the server.

## Performance

- One ResizeObserver per chart measures the width before paint; the SVG is rendered only after measuring. Resampling runs once per data change and the path strings are short (two numbers per sample).

## Notes for AI

- Give ranges or data, not both; ranges wins. Each range's data is its own array of { label, value } in time order.
- format takes Intl.NumberFormat options and is used for the headline, tooltip and ticks; use formatValue/formatTick for custom strings (e.g. percentages).
- The width follows the parent; set height in px through the prop, not a Tailwind class.
- color takes any CSS color or variable (default var(--chart-1)); do not pass a Tailwind class.
- Pass a string title so the screen reader summary and table caption name the metric.

## FAQ

**Why does a 365-point range look slightly smoothed?**

Each data set is resampled to `samples` points (160 by default) so the morph works; raise samples for dense daily data.

**Does the smooth curve invent peaks?**

No. It uses monotone cubic interpolation (Fritsch–Carlson), which never goes above a peak or below a dip in your data.

**What renders on the server?**

The header and an empty plot of the right height; the SVG renders after the width is measured, and the entrance plays once the chart is in view.

## Related

- line-chart: https://goodui.dev/components/charts/line-chart
- sparkline-draw: https://goodui.dev/components/numbers/sparkline-draw
- kpi-trend: https://goodui.dev/components/charts/kpi-trend
- number-flow: https://goodui.dev/components/numbers/number-flow

Last updated: 2026-11-03

---

# Line chart

> Multi-series lines that draw in staggered, a legend that toggles series while the scale refits, a crosshair that reads every series at once, and a dashed forecast segment behind a divider.

Multi-series line chart for React and shadcn: legend toggles, crosshair tooltip, dashed forecast

Page: https://goodui.dev/components/charts/line-chart

## Install

```bash
npx shadcn@latest add @goodui/line-chart
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/line-chart.json`. The file lands in `components/goodui/line-chart.tsx`.

## When to use

- Two to five series on one scale: this year vs last year, response time by channel, plan vs actual.
- A projection: pass forecastFrom and the tail of every line turns dashed behind a "Forecast" divider.
- Readers who need to hide a noisy series and let the scale refit (legend toggles).

## When not to use

- One metric with a headline: use area-chart.
- Two measures of different scale: never a dual axis; use two charts or index both to 100.
- Rank changes rather than values: use bump-chart.

## Pick by what matters

| Need | Use |
| --- | --- |
| Actual vs last year | two series, forecastFrom for the projected months |
| Series with very different ranges | baseline="auto" zooms to the data; toggle series in the legend |
| Exact values | curve="linear" |
| Legend above the plot | legend="top" |
| Control hidden series from the app | hidden + onHiddenChange |

## Usage

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

const months = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"]

export function BookingsChart() {
  return (
    <LineChart
      title="Bookings per month"
      categories={months}
      series={[
        { key: "this", label: "This year", data: [412, 438, 471, 455, 502, 548, 561, 539, 590, 628, 655, 690] },
        { key: "last", label: "Last year", data: [368, 372, 401, 395, 430, 462, 478, 470, 495, 520, 541, 560] },
      ]}
      forecastFrom={9}
      height={240}
    />
  )
}
```

### Minutes, zoomed scale, legend on top

```tsx
<LineChart title="First response time" categories={weeks} series={byChannel} baseline="auto" legend="top" curve="linear" formatValue={(v) => `${v} min`} />
```

### Legend rendered elsewhere

```tsx
const [hidden, setHidden] = React.useState<string[]>([])
<ChartLegend items={items} hidden={hidden} onHiddenChange={setHidden} />
<LineChart categories={weeks} series={series} hidden={hidden} onHiddenChange={setHidden} legend="none" />
```

## API

### LineChart

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| series (required) | `LineSeries[]` | — |  |
| categories (required) | `string[]` | — | X labels, one per data point. |
| title | `React.ReactNode` | — | Chart name for screen readers and the table caption. |
| forecastFrom | `number` | — | Index from which the lines are drawn dashed (a projection); a divider labelled "Forecast" marks it. |
| hidden | `string[]` | — | Keys of hidden series (controlled). |
| defaultHidden | `string[]` | — |  |
| onHiddenChange | `(hidden: string[]) => void` | — |  |
| legend | `"top" \| "bottom" \| "none"` | `"bottom"` | Legend placement; a single series shows none. |
| height | `number` | `240` | Plot height in px, axes included. The width follows the container. |
| curve | `"smooth" \| "linear"` | `"smooth"` |  |
| baseline | `"zero" \| "auto"` | `"zero"` | zero keeps 0 in view; auto zooms to the data. |
| grid | `boolean` | `true` |  |
| axis | `boolean` | `true` |  |
| axisWidth | `number` | `44` |  |
| endDots | `boolean` | `true` | Ring dot on the last point of every line. |
| format | `Intl.NumberFormatOptions` | — | Intl.NumberFormat options for values and ticks. |
| locale | `string` | `"en-US"` |  |
| formatValue | `(value: number) => string` | — |  |
| formatTick | `(value: number) => string` | — |  |
| samples | `number` | `160` | Resampled points per line; constant, so lines morph when the data changes. |
| duration | `number` | `1.1` | Seconds one line takes to draw; lines stagger by 0.12 s. |
| labels | `Partial<LineChartLabels>` | — | Text for built-in controls and screen readers; pass translations here. |

Also accepts every <div> attribute.

## Keyboard

| Keys | Action |
| --- | --- |
| Tab | Focuses the plot and shows the crosshair on the latest period; then moves on to the legend buttons. |
| ArrowLeft / ArrowRight | Moves the crosshair one period. |
| Home / End | Jumps to the first or last period. |
| Escape | Clears the crosshair. |
| Enter / Space on a legend item | Hides or shows that series. |

## Accessibility

- The plot is role="group" with aria-roledescription="line chart" and a summary label ("Bookings per month: 2 series over 12 periods"); your aria-label replaces it.
- A screen-reader-only table has one row per period and one column per series, with forecast periods marked.
- The crosshair position is announced through a polite live region: "Oct: This year 628, Last year 520".
- Legend items are buttons with aria-pressed (chart-legend); hidden series leave the scale and the tooltip.
- All built-in strings (summary, point, forecast, legend, column header, noData) go through labels.

## Motion

- On first view each line draws in with pathLength over duration (1.1 s, ease [0.65, 0, 0.35, 1]), staggered 0.12 s per series; the dashed forecast segment fades in as the solid part reaches it; end dots pop on a spring (stiffness 420, damping 22).
- Data changes and legend toggles morph the paths and slide the ticks on a spring (stiffness 190, damping 30, mass 0.9); lines are resampled to `samples` points so shapes with different lengths still morph.
- The crosshair and its dots snap to the pointer on a stiff spring (stiffness 600, damping 40). Hovering a legend item dims the other lines to 25% over 0.2 s.
- A container resize re-lays the chart out instantly (no morph); labels that appear after the entrance fade in over 0.2 s.
- Reduced motion: lines, dots and labels appear at once, morphs are instant.

## Performance

- One ResizeObserver per chart; paths are rebuilt only when data, size or hidden series change. No timers.

## Notes for AI

- series[i].data must have one value per category, in the same order. Keys must be unique; colors default to --chart-1 … --chart-5 by series order (give colors explicitly past five series).
- forecastFrom is an index into categories: lines are dashed from that point on. It needs 0 < forecastFrom < categories.length.
- Legends show only for two or more series; a single series has no legend box by design.
- Width follows the parent; height is a px prop. Do not wrap it in a fixed-width container smaller than ~240px.

## FAQ

**Can I put two different units on one chart?**

No, and that is deliberate: a second y-axis invents correlations. Render two charts, or convert both series to an index (100 at the first period).

**What happens when every series is hidden?**

The scale keeps 0..1, the tooltip is empty and the table still lists the data.

## Related

- area-chart: https://goodui.dev/components/charts/area-chart
- bar-chart: https://goodui.dev/components/charts/bar-chart
- chart-legend: https://goodui.dev/components/charts/chart-legend
- bump-chart: https://goodui.dev/components/charts/bump-chart

Last updated: 2026-11-03

---

# Bar chart

> Grouped, stacked or horizontal bars that grow from the baseline on view and morph when data changes, with a gliding hover band, legend toggles, value labels and 2px surface gaps between segments.

Animated bar chart for React and shadcn: grouped, stacked and horizontal bars with a hover band

Page: https://goodui.dev/components/charts/bar-chart

## Install

```bash
npx shadcn@latest add @goodui/bar-chart
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/bar-chart.json`. The file lands in `components/goodui/bar-chart.tsx`.

## When to use

- Comparing categories: revenue by service line per month, bookings by weekday.
- Parts of a total per category (stacked): bookings by channel, costs by type.
- Ranked lists with long labels: horizontal mode puts the names on the start side and the values at the bar tips.

## When not to use

- A single value against a goal: use meter, radial-progress or gauge.
- Many periods of a continuous metric: use area-chart or line-chart.
- Steps that add up to a total: use waterfall-chart.

## Pick by what matters

| Need | Use |
| --- | --- |
| Series side by side | mode="grouped" (default) |
| Series on top of each other | mode="stacked" (values ≥ 0, 2px surface gaps between segments) |
| Ranked categories, long names | orientation="horizontal" axisWidth={150} valueLabels |
| Print the numbers | valueLabels (stack totals in stacked mode) |
| Thinner or thicker bars | barSize (max thickness in px, default 24) and radius |

## Usage

```tsx
import { BarChart } from "@/components/goodui/bar-chart"

export function RevenueByService() {
  return (
    <BarChart
      title="Revenue by service line"
      categories={["Jan", "Feb", "Mar", "Apr", "May", "Jun"]}
      series={[
        { key: "hair", label: "Hair", data: [18400, 19100, 21300, 20200, 23800, 25100] },
        { key: "nails", label: "Nails", data: [8200, 8900, 9400, 9900, 10800, 11200] },
        { key: "spa", label: "Spa", data: [5100, 5600, 5200, 6400, 7100, 7600] },
      ]}
      format={{ style: "currency", currency: "USD", maximumFractionDigits: 0 }}
      height={230}
    />
  )
}
```

### Stacked bookings by channel

```tsx
<BarChart title="Bookings by channel" mode="stacked" categories={days} series={[online, app, phone]} />
```

### Horizontal ranking with values at the tips

```tsx
<BarChart title="Top services" orientation="horizontal" categories={services} series={[{ key: "revenue", label: "Revenue", data: revenue }]} valueLabels axisWidth={150} format={usd} />
```

## API

### BarChart

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| series (required) | `BarSeries[]` | — |  |
| categories (required) | `string[]` | — |  |
| title | `React.ReactNode` | — | Chart name for screen readers and the table caption. |
| mode | `"grouped" \| "stacked"` | `"grouped"` | grouped: one bar per series side by side. stacked: one bar per category, segments separated by a 2px gap. |
| orientation | `"vertical" \| "horizontal"` | `"vertical"` | vertical columns or horizontal bars (category labels on the start side, values along the bottom). |
| valueLabels | `boolean` | `false` | Prints the value at each bar's end (the stack total in stacked mode). |
| barSize | `number` | `24` | Maximum bar thickness in px; the rest of the slot stays air. |
| radius | `number` | `4` | Corner radius of the data end in px. The baseline end stays square. |
| hidden | `string[]` | — | Keys of hidden series (controlled). |
| defaultHidden | `string[]` | — |  |
| onHiddenChange | `(hidden: string[]) => void` | — |  |
| legend | `"top" \| "bottom" \| "none"` | `"bottom"` | Legend placement; a single series shows none. |
| height | `number` | — | Plot height in px, axes included. Horizontal charts default to a row height per category. |
| rowHeight | `number` | `34` | Row height per category in horizontal mode. |
| grid | `boolean` | `true` |  |
| axis | `boolean` | `true` |  |
| axisWidth | `number` | — | Space for the value ticks (vertical) or the category labels (horizontal), in px. |
| format | `Intl.NumberFormatOptions` | — |  |
| locale | `string` | `"en-US"` |  |
| formatValue | `(value: number) => string` | — |  |
| formatTick | `(value: number) => string` | — |  |
| labels | `Partial<BarChartLabels>` | — | Text for built-in controls and screen readers; pass translations here. |

Also accepts every <div> attribute.

## Keyboard

| Keys | Action |
| --- | --- |
| Tab | Focuses the plot and highlights the first category; then the legend buttons. |
| Arrow keys | Moves the highlight one category (any arrow works in both orientations). |
| Home / End | First or last category. |
| Escape | Clears the highlight. |

## Accessibility

- The plot is role="group" with aria-roledescription="bar chart" and a summary label ("Revenue by service line: 3 series across 6 categories").
- A screen-reader-only table lists every category with one column per series (plus a total column when stacked).
- The highlighted category is announced through a polite live region with every series value.
- Legend items are aria-pressed buttons (chart-legend); the stacked total shows in the tooltip and the table.
- Bars are ≤ 24px thick with a 4px rounded data end and a square baseline end; adjacent bars and stacked segments are separated by a 2px surface gap, not a stroke.

## Motion

- On first view bars grow from the baseline on a spring (stiffness 170, damping 26, mass 0.9), staggered 35 ms per category and 50 ms per series; value labels fade in after 0.45 s.
- Data changes and legend toggles morph the bars to their new size on the same spring; the ticks slide and cross-fade. A container resize re-lays the bars out instantly.
- The hover band glides to the pointed category on a stiff spring (600 / 40); other categories dim to 75% and a dimmed series (legend hover) to 30%.
- Reduced motion: bars appear at full size at once and the band moves instantly.

## Performance

- Paths are plain SVG path strings with quadratic corners, so every bar shares one template and animates with one motion value each. One ResizeObserver per chart.

## Notes for AI

- series[i].data has one value per category. Stacked mode expects values ≥ 0; grouped mode accepts negatives (bars grow downward).
- Horizontal charts size themselves from rowHeight × categories unless height is given; vertical charts default to 240px.
- axisWidth reserves space for value ticks (vertical, default 44) or category labels (horizontal, default 96): raise it for long names.
- Colors default to --chart-1 … --chart-5 in series order; set series[i].color for anything else. Keep the same color for the same entity across charts.

## FAQ

**How do I show totals on stacked bars?**

Pass valueLabels; in stacked mode it prints the stack total above each column (or at the tip in horizontal mode).

**Can categories be dense (30 days)?**

Yes: category labels thin out automatically (every k-th label that fits), bars shrink to fit their slot and the hover band still lands on every category.

## Related

- line-chart: https://goodui.dev/components/charts/line-chart
- waterfall-chart: https://goodui.dev/components/charts/waterfall-chart
- chart-legend: https://goodui.dev/components/charts/chart-legend
- funnel-chart: https://goodui.dev/components/charts/funnel-chart

Last updated: 2026-11-03

---

# Donut chart

> Donut or pie whose slices sweep in clockwise, re-share the ring when a legend item is toggled, push out on hover and roll the center total to the slice under the pointer.

Animated donut and pie chart for React and shadcn: sweeping arcs, rolling center total, legend with shares

Page: https://goodui.dev/components/charts/donut-chart

## Install

```bash
npx shadcn@latest add @goodui/donut-chart
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/donut-chart.json`. The file lands in `components/goodui/donut-chart.tsx`.

## When to use

- A part-to-whole glance with up to six slices: bookings by channel, revenue by payment method.
- A total that should sit in the middle and switch to the hovered slice's value.
- Readers who want to drop a slice (legend toggle) and see the rest re-share the ring.

## When not to use

- Comparing close values: use bar-chart; slices within a few percent of each other are hard to read.
- More than about six parts: fold the tail into "Other" or use treemap.
- A single value vs a goal: use radial-progress.

## Pick by what matters

| Need | Use |
| --- | --- |
| Classic donut with total | variant="donut" (default), title names the total |
| Full disc | variant="pie" (readout under the chart) |
| Thin accent ring | thickness={10} legend="end" |
| Money values | format={{ style: "currency", currency: "USD" }} |
| Hide shares in the legend | showPercent={false} |

## Usage

```tsx
import { DonutChart } from "@/components/goodui/donut-chart"

export function ChannelsCard() {
  return (
    <DonutChart
      title="Bookings"
      data={[
        { label: "Online", value: 612 },
        { label: "App", value: 348 },
        { label: "Phone", value: 191 },
        { label: "Walk-in", value: 133 },
      ]}
      size={180}
      thickness={22}
      legend="bottom"
    />
  )
}
```

### Pie with money

```tsx
<DonutChart title="Revenue" variant="pie" data={payments} size={150} legend="bottom" format={{ style: "currency", currency: "USD", maximumFractionDigits: 0 }} />
```

### Controlled hidden slices

```tsx
const [hidden, setHidden] = React.useState<string[]>([])
<DonutChart data={channels} hidden={hidden} onHiddenChange={setHidden} />
```

## API

### DonutChart

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| data (required) | `DonutSlice[]` | — |  |
| title | `React.ReactNode` | — | Name shown under the center number and used by screen readers. |
| variant | `"donut" \| "pie"` | `"donut"` | donut (ring with the total in the middle) or pie (full disc, readout under it). |
| size | `number` | `200` | Diameter in px. |
| thickness | `number` | `24` | Ring thickness in px (donut). |
| gap | `number` | `2` | Surface gap between slices in px. |
| legend | `"end" \| "bottom" \| "none"` | `"end"` | Legend placement, with each slice's share. |
| showPercent | `boolean` | `true` | Show "42%" next to legend labels. |
| hidden | `string[]` | — | Keys of hidden slices (controlled); hidden slices leave the ring and the others re-share it. |
| defaultHidden | `string[]` | — |  |
| onHiddenChange | `(hidden: string[]) => void` | — |  |
| format | `Intl.NumberFormatOptions` | — | Intl.NumberFormat options for the values, e.g. { style: "currency", currency: "USD" }. |
| locale | `string` | `"en-US"` |  |
| formatValue | `(value: number) => string` | — |  |
| duration | `number` | `1` | Seconds the whole ring takes to sweep in. |
| labels | `Partial<DonutChartLabels>` | — | Text for built-in controls and screen readers; pass translations here. |

Also accepts every <div> attribute.

## Keyboard

| Keys | Action |
| --- | --- |
| Tab | Focuses the ring; then the legend buttons. |
| Arrow keys | Cycles the active slice; its value and share show in the middle. |
| Home / End | First or last slice. |
| Escape | Clears the active slice. |
| Enter / Space on a legend item | Hides or shows the slice. |

## Accessibility

- The ring is role="group" with aria-roledescription="donut chart" (or "pie chart") and a summary that lists the total and every share.
- A screen-reader-only table lists label, value and share for all slices, hidden ones included.
- The active slice is announced through a polite live region ("Online: 612, 48%").
- The percentage shown in the middle is aria-hidden; the live region and table carry it.
- Legend items are aria-pressed buttons; all built-in strings go through labels.

## Motion

- On first view the slices sweep in clockwise one after another, each taking its share of duration (1 s) so the whole ring completes in one pass.
- Toggling a slice re-shares the ring: lengths and offsets move on a spring (stiffness 160, damping 26). The center total rolls with NumberFlow.
- Hovering a slice (or its legend item) pushes it out by 4px on a spring (stiffness 400, damping 24) and dims the others to 45%.
- Reduced motion: the ring appears complete, re-shares and hover are instant.

## Performance

- Slices are stroked circles using pathLength normalization, so no arc math runs per frame; one gap-adjusted dash per slice.

## Notes for AI

- data values must be ≥ 0; zero-value slices are kept in the legend and table but draw nothing.
- keys default to labels, so labels must be unique unless you pass key.
- Colors default to --chart-1 … --chart-5 in data order; set color per slice for more than five or for semantic colors.
- size and thickness are px props; the component is not fluid, so place it in a flex or grid cell.
- For a pie, the readout appears under the chart (there is no center).

## FAQ

**Why are the gaps between slices wedge-shaped?**

They are 2px along the ring's center line; with thick rings the inner edge gap gets slightly narrower than the outer. Set gap={0} for none.

**Can the center show something custom?**

The center shows the total or the active slice. For custom content, overlay your own element on the parent; it is a plain positioned div.

## Related

- radial-progress: https://goodui.dev/components/charts/radial-progress
- treemap: https://goodui.dev/components/charts/treemap
- bar-chart: https://goodui.dev/components/charts/bar-chart
- chart-legend: https://goodui.dev/components/charts/chart-legend

Last updated: 2026-11-03

---

# Radial progress

> Activity-style concentric goal rings that fill from 12 o'clock on view, spring to new values, dim the others when one is pointed at, and roll the center percentage.

Activity-style progress rings for React and shadcn: concentric goal rings that fill on view

Page: https://goodui.dev/components/charts/radial-progress

## Install

```bash
npx shadcn@latest add @goodui/radial-progress
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/radial-progress.json`. The file lands in `components/goodui/radial-progress.tsx`.

## When to use

- A few goals at a glance: bookings, revenue and reviews against today's targets.
- One goal ring with a rolling percentage in the middle (monthly target, utilization).
- Values that update live (a new booking lands): rings spring to the new fill.

## When not to use

- Shares of a whole: use donut-chart.
- A value inside bands (healthy / watch / critical): use gauge.
- A long list of goals: rings stop being readable past four; use meter rows.

## Pick by what matters

| Need | Use |
| --- | --- |
| Three goals, activity style | rings={[outer, middle, inner]} with legend="end" |
| Single goal, number in the middle | rings={[one]} legend="none" |
| Money on one ring, counts on another | ring.formatValue per ring |
| Your own center content | center={<Icon />} or center={null} |

## Usage

```tsx
import { RadialProgress } from "@/components/goodui/radial-progress"

export function TodayGoals() {
  return (
    <RadialProgress
      title="Today"
      size={180}
      thickness={14}
      rings={[
        { label: "Bookings", value: 29, max: 40 },
        { label: "Revenue", value: 2140, max: 3000, formatValue: (v, max) => `$${v} / $${max}` },
        { label: "Reviews", value: 6, max: 10 },
      ]}
    />
  )
}
```

### Single goal ring

```tsx
<RadialProgress rings={[{ label: "Monthly target", value: 78, color: "var(--chart-2)" }]} size={112} thickness={10} legend="none" />
```

### Translated

```tsx
<RadialProgress rings={rings} locale="de-DE" labels={{ legend: "Ziele", ring: (label, value, max, pct) => `${label}: ${value} von ${max}, ${pct}` }} />
```

## API

### RadialProgress

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| rings (required) | `RadialRing[]` | — | Rings from the outside in. One ring makes a goal ring; several make activity-style concentric rings. |
| title | `React.ReactNode` | — | Name under the center number, used by screen readers too. |
| size | `number` | `160` | Diameter in px. |
| thickness | `number` | `12` | Ring thickness in px. |
| gap | `number` | `4` | Space between rings in px. |
| center | `React.ReactNode` | — | Replaces the rolling percentage in the middle. Pass null to leave the center empty. |
| legend | `"end" \| "bottom" \| "none"` | `"end"` | Legend placement with each ring's value. |
| format | `Intl.NumberFormatOptions` | — | Intl.NumberFormat options for the values. |
| locale | `string` | `"en-US"` |  |
| formatValue | `(value: number, max: number) => string` | — | Formats "value / max" for the legend and screen readers. |
| duration | `number` | `1.2` | Seconds the first ring takes to fill; inner rings start 0.12 s later each. |
| labels | `Partial<RadialProgressLabels>` | — | Text for built-in controls and screen readers; pass translations here. |

Also accepts every <div> attribute.

## Keyboard

| Keys | Action |
| --- | --- |
| Tab | Focuses the rings. |
| Arrow keys | Cycles the active ring; the center shows its percentage and label. |
| Escape | Clears the active ring. |

## Accessibility

- The rings are role="group" with aria-roledescription="progress rings" and a summary that reads every ring ("Bookings: 29 of 40, 73%; …").
- The active ring is announced through a polite live region.
- The legend lists label and value / max for each ring in text, so nothing depends on color.
- Built-in strings (ring, summary, legend) go through labels; per-ring money formatting goes through ring.formatValue.

## Motion

- On first view each ring fills from 12 o'clock over duration (1.2 s, ease [0.16, 1, 0.3, 1]), inner rings starting 0.12 s after the one outside them; the center percentage rolls up with NumberFlow.
- Later value changes spring to the new fill (stiffness 120, damping 24).
- Hovering a ring or its legend row dims the others to 35% (track to 50%) over 0.2 s.
- Reduced motion: rings appear filled, changes are instant.

## Performance

- Rings are stroked circles with pathLength normalization; no per-frame geometry.

## Notes for AI

- rings are listed from the outside in; max defaults to 100. Values above max fill the ring completely (no lap-over).
- Colors default to --chart-1 … --chart-5 by ring order.
- size and thickness are px; with many rings keep thickness × rings well under size / 2 or the center disappears.
- center={null} removes the center readout; center={<node>} replaces it.

## FAQ

**Can a ring go past 100%?**

It fills completely; the legend still shows the real value (e.g. 46 / 40). A lap-over effect is not drawn.

**How do I show an icon instead of the percentage?**

Pass center={<Flame className="size-6" />}.

## Related

- circular-progress: https://goodui.dev/components/numbers/circular-progress
- donut-chart: https://goodui.dev/components/charts/donut-chart
- gauge: https://goodui.dev/components/charts/gauge
- meter: https://goodui.dev/components/numbers/meter

Last updated: 2026-11-03

---

# Heatmap

> Calendar (GitHub-style) or matrix heatmap on one hue with cells that pop in column by column, a tooltip, arrow-key navigation that scrolls the calendar along, and a Less–More scale.

Calendar and matrix heatmap for React and shadcn: GitHub-style contribution graph with tooltips

Page: https://goodui.dev/components/charts/heatmap

## Install

```bash
npx shadcn@latest add @goodui/heatmap
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/heatmap.json`. The file lands in `components/goodui/heatmap.tsx`.

## When to use

- Activity per day over months: bookings, orders, check-ins, commits.
- Intensity across two dimensions: weekday × hour, staff × service, region × month (matrix mode).
- Spotting patterns (busy Saturdays, dead Mondays) rather than reading exact values.

## When not to use

- Exact comparisons between a few values: use bar-chart.
- A single trend: use area-chart.
- Categorical identity (which team): a heatmap encodes magnitude on one hue only.

## Pick by what matters

| Need | Use |
| --- | --- |
| Last 6 months of daily activity | mode="calendar" data={[{ date, value }]} weeks={26} |
| Weekday × hour | mode="matrix" rows={days} columns={hours} values={grid} |
| Skewed data where a few huge days flatten the rest | scale="quantile" |
| Finer scale | steps={5} (levels above zero) |

## Usage

```tsx
import { Heatmap } from "@/components/goodui/heatmap"

const data = bookings.map((b) => ({ date: b.day, value: b.count })) // { date: "2026-10-28", value: 14 }

export function ActivityCard() {
  return <Heatmap title="Bookings per day" data={data} end="2026-11-02" weeks={26} formatValue={(v) => `${v} bookings`} />
}
```

### Busiest hours matrix

```tsx
<Heatmap
  mode="matrix"
  title="Busiest hours"
  rows={["Mon", "Tue", "Wed", "Thu", "Fri", "Sat"]}
  columns={["9", "10", "11", "12", "13", "14", "15", "16", "17", "18", "19", "20"]}
  values={grid}
  color="var(--chart-4)"
  steps={5}
  labels={{ cell: (label, value) => `${label}:00 — ${value}` }}
/>
```

### Sunday-first weeks

```tsx
<Heatmap data={data} weekStart={0} locale="en-US" />
```

## API

### Heatmap

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| title | `React.ReactNode` | — | Chart name for screen readers. |
| color | `string` | `"var(--chart-1)"` | One hue; intensity is its opacity in `steps` levels. Defaults to the theme's first chart color. |
| mode | `"calendar" \| "matrix"` | `"calendar"` | calendar: weeks as columns, weekdays as rows (needs data). matrix: rows × columns (needs rows, columns, values). |
| data | `HeatmapCell[]` | — | Calendar values by ISO date. Days without an entry count as 0. |
| end | `string` | — | Last day of the calendar (ISO). Defaults to the latest date in data. |
| weeks | `number` | `26` | Weeks shown in calendar mode. |
| weekStart | `0 \| 1` | `1` | First weekday: 1 Monday (default) or 0 Sunday. |
| rows | `string[]` | — | Matrix row labels. |
| columns | `string[]` | — | Matrix column labels. |
| values | `number[][]` | — | Matrix values, values[row][column]. |
| steps | `number` | `4` | Number of intensity levels above zero. |
| scale | `"linear" \| "quantile"` | `"linear"` | linear splits 0..max evenly; quantile gives each level the same number of cells. |
| cellSize | `number` | `12` | Cell size in px (calendar) or minimum cell size (matrix, cells stretch to the width). |
| cellGap | `number` | `3` |  |
| legend | `boolean` | `true` | Less … More scale under the chart. |
| format | `Intl.NumberFormatOptions` | — |  |
| locale | `string` | `"en-US"` |  |
| formatValue | `(value: number) => string` | — |  |
| formatDate | `(date: Date) => string` | — | Formats calendar dates for the tooltip and screen readers. |
| labels | `Partial<HeatmapLabels>` | — | Text for built-in controls and screen readers; pass translations here. |

Also accepts every <div> attribute.

## Keyboard

| Keys | Action |
| --- | --- |
| Tab | Focuses the heatmap and highlights the latest cell. |
| ArrowLeft / ArrowRight | Previous or next week (calendar) or column (matrix); the calendar scrolls to keep the cell visible. |
| ArrowUp / ArrowDown | Previous or next weekday or row. |
| Home / End | First or last cell. |
| Escape | Clears the highlight. |

## Accessibility

- The chart is role="group" with aria-roledescription="heatmap" and a summary ("Bookings per day: 182 cells, highest 31").
- The highlighted cell is announced through a polite live region as "<date or row · column>: <value>".
- Intensity uses one hue in `steps` opacity levels on both themes; empty days use the muted surface. A Less … More scale explains it.
- The calendar scrolls horizontally inside the card (latest weeks first) instead of overflowing the page.
- Built-in strings (less, more, cell, summary, noData) go through labels; dates format through Intl in `locale` or formatDate.

## Motion

- On first view cells pop in (scale 0.55 → 1 with a fade, 0.45 s, ease [0.2, 0.8, 0.2, 1]) column by column, 14 ms apart, as a pure CSS animation.
- The tooltip follows the pointed or focused cell; the active cell gets a 1.5px foreground outline.
- Reduced motion: cells are visible at once.

## Performance

- Cells are plain SVG rects with a CSS entrance; hover uses one delegated pointermove handler on the SVG instead of a listener per cell. 26 weeks is 182 rects.

## Notes for AI

- Calendar mode needs data (ISO dates, local time); days without an entry count as 0. Set end to pin the last day (defaults to the latest date in data).
- Matrix mode needs rows, columns and values[row][column] (same lengths).
- color is one hue (any CSS color); do not pass several colors, intensity is opacity.
- cellSize is fixed in calendar mode and a minimum in matrix mode, where cells stretch to the container width.

## FAQ

**How are the levels computed?**

linear splits 0..max into `steps` equal bands; quantile puts the same number of non-zero cells in each level. Zero is always its own level.

**Can I show a whole year?**

Yes, weeks={52}; the calendar scrolls horizontally in narrow cards and starts scrolled to the latest week.

## Related

- bar-chart: https://goodui.dev/components/charts/bar-chart
- timeline-chart: https://goodui.dev/components/charts/timeline-chart
- treemap: https://goodui.dev/components/charts/treemap

Last updated: 2026-11-03

---

# Funnel chart

> Funnel whose stage bars grow open one after another on an ordinal ramp, with drop-off chips between stages, conversion from the first stage beside each value, and arrow-key rows.

Animated funnel chart for React and shadcn: stages with drop-off percentages and conversion

Page: https://goodui.dev/components/charts/funnel-chart

## Install

```bash
npx shadcn@latest add @goodui/funnel-chart
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/funnel-chart.json`. The file lands in `components/goodui/funnel-chart.tsx`.

## When to use

- Sequential steps where each loses people: visited → picked a slot → paid.
- Onboarding or trial flows where the drop-off between two specific steps is the story.
- Reports where the conversion from the first step should be printed, not hovered for.

## When not to use

- Steps that are not ordered or do not lose volume: use bar-chart.
- A single conversion rate: a stat tile (kpi-trend) says it better.
- Flows with branches: a funnel is linear by definition.

## Pick by what matters

| Need | Use |
| --- | --- |
| Classic centered funnel | align="center" (default) |
| Ranked-list feel with long labels | align="start" labelWidth={140} |
| Only the numbers | showDropOff={false} showConversion={false} |
| Brand hue | color="var(--chart-2)" (the ramp derives from it) |

## Usage

```tsx
import { FunnelChart } from "@/components/goodui/funnel-chart"

export function BookingFunnel() {
  return (
    <FunnelChart
      title="Booking funnel"
      stages={[
        { label: "Visited", value: 12400 },
        { label: "Viewed services", value: 8100 },
        { label: "Picked a slot", value: 3900 },
        { label: "Entered details", value: 2600 },
        { label: "Paid deposit", value: 2150 },
      ]}
    />
  )
}
```

### Start-aligned, green ramp

```tsx
<FunnelChart title="Trial to paid" stages={trial} align="start" color="var(--chart-2)" labelWidth={136} />
```

### Translated chips

```tsx
<FunnelChart stages={stages} locale="de-DE" labels={{ dropOff: (p) => `−${p}`, conversion: (p, first) => `${p} von ${first}` }} />
```

## API

### FunnelChart

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| stages (required) | `FunnelStage[]` | — |  |
| title | `React.ReactNode` | — | Chart name for screen readers and the table caption. |
| color | `string` | `"var(--chart-1)"` | Base hue of the ordinal ramp (first stage full, later stages lighter). |
| align | `"center" \| "start"` | `"center"` | center: symmetric funnel. start: bars aligned to the start side, like a ranked list. |
| showDropOff | `boolean` | `true` | "−38%" chips between stages. |
| showConversion | `boolean` | `true` | Share of the first stage beside each value. |
| labelWidth | `number` | `112` | Width of the label column in px. |
| rowHeight | `number` | `40` |  |
| format | `Intl.NumberFormatOptions` | — |  |
| locale | `string` | `"en-US"` |  |
| formatValue | `(value: number) => string` | — |  |
| duration | `number` | `0.8` | Seconds the first bar takes to grow; each next one starts 0.08 s later. |
| labels | `Partial<FunnelChartLabels>` | — | Text for built-in controls and screen readers; pass translations here. |

Also accepts every <div> attribute.

## Keyboard

| Keys | Action |
| --- | --- |
| Tab | Focuses the funnel and highlights the first stage. |
| ArrowUp / ArrowDown | Moves the highlight one stage (Left/Right work too). |
| Home / End | First or last stage. |
| Escape | Clears the highlight. |

## Accessibility

- The funnel is role="group" with aria-roledescription="funnel chart" and a summary ("Booking funnel: from 12,400 to 2,150, 17% overall").
- A screen-reader-only table lists stage, value and conversion from the first stage.
- The highlighted stage is announced with its value, conversion and the drop-off from the previous stage.
- Values and conversion percentages are printed beside every row, so no reading depends on hover or color.
- Stage colors are an ordinal ramp of one hue (first stage full, later stages lighter), so order reads in the color too.

## Motion

- On first view bars scale open from the center (or the start side) over duration (0.8 s, ease [0.16, 1, 0.3, 1]), each stage 80 ms after the previous; the values fade in at 40% and the drop-off chips pop in on a spring (stiffness 420, damping 22) at 55%.
- Hovering a row tints it with the muted surface and dims the other bars to 55%.
- Reduced motion: everything appears at once.

## Performance

- Plain DOM rows; the only animated properties are transform and opacity.

## Notes for AI

- stages are in order; the first stage is the 100% reference and bar widths are relative to it.
- Drop-off chips compare each stage with the previous one; conversion compares with the first.
- Labels truncate in a fixed labelWidth column; raise it for long stage names.
- Colors come from the ordinal ramp unless stage.color is set; do not color stages by arbitrary hues.

## FAQ

**Can a later stage be larger than an earlier one?**

Yes; its bar is clipped to the width of the first stage and the drop-off chip shows −0%.

**Does it support horizontal funnels?**

No; rows read better with long labels and on phones. Use bar-chart for a horizontal layout.

## Related

- bar-chart: https://goodui.dev/components/charts/bar-chart
- kpi-trend: https://goodui.dev/components/charts/kpi-trend
- waterfall-chart: https://goodui.dev/components/charts/waterfall-chart

Last updated: 2026-11-03

---

# Gauge

> Semi-circular gauge with Core-tone bands whose needle springs to the value with a small overshoot (or an arc that fills), a rolling readout and a band label pill, exposed as a meter.

Animated gauge for React and shadcn: semi-circular dial with tone bands and a spring needle

Page: https://goodui.dev/components/charts/gauge

## Install

```bash
npx shadcn@latest add @goodui/gauge
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/gauge.json`. The file lands in `components/goodui/gauge.tsx`.

## When to use

- One value that lives inside ranges with meaning: no-show rate (healthy / watch / critical), chair utilization, NPS.
- Dashboards where the reading should be felt as well as read: the needle swings and settles.
- A score between a min and a max that is not 0..100 (rating 1..5).

## When not to use

- Plain progress toward a goal: use radial-progress or meter.
- Several values side by side: a row of bars compares better than a row of dials.
- Values without ranges: a stat tile with a delta is clearer (kpi-trend).

## Pick by what matters

| Need | Use |
| --- | --- |
| Status ranges | bands with tone: success / warning / danger / info / neutral / primary and a label |
| Filled arc instead of a needle | variant="arc" (fills in the current band's color over a thin band ring) |
| Plain progress look | no bands, variant="arc", color |
| Percent values | formatValue={(v) => `${v}%`} |

## Usage

```tsx
import { Gauge } from "@/components/goodui/gauge"

export function NoShowGauge({ rate }: { rate: number }) {
  return (
    <Gauge
      value={rate}
      min={0}
      max={20}
      label="No-show rate"
      bands={[
        { from: 0, to: 5, tone: "success", label: "Healthy" },
        { from: 5, to: 10, tone: "warning", label: "Watch" },
        { from: 10, to: 20, tone: "danger", label: "Critical" },
      ]}
      formatValue={(v) => `${v}%`}
    />
  )
}
```

### Filled arc, utilization

```tsx
<Gauge value={82} variant="arc" label="Chair utilization" bands={utilizationBands} formatValue={(v) => `${v}%`} />
```

### Rating 1..5, no bands

```tsx
<Gauge value={4.6} min={1} max={5} variant="arc" color="var(--chart-2)" label="Average rating" thickness={10} format={{ minimumFractionDigits: 1, maximumFractionDigits: 1 }} />
```

## API

### Gauge

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| value (required) | `number` | — |  |
| color | `string` | — | Color of the needle (needle) or of the arc when no band covers the value (arc). |
| min | `number` | `0` |  |
| max | `number` | `100` |  |
| bands | `GaugeBand[]` | `[]` | Colored ranges along the arc, e.g. healthy / watch / critical. Drawn with 2px gaps. |
| variant | `"needle" \| "arc"` | `"needle"` | needle: a needle springs to the value over the bands. arc: the arc fills to the value in the band's color. |
| size | `number` | `240` | Width in px; the gauge is half as tall plus the readout. |
| thickness | `number` | `14` | Arc thickness in px. |
| label | `React.ReactNode` | — | Metric name under the value; also the accessible name when it is a string. |
| showRange | `boolean` | `true` | Min and max printed under the arc ends. |
| format | `Intl.NumberFormatOptions` | — | Intl.NumberFormat options for the value, e.g. { style: "percent" } with values 0..1. |
| locale | `string` | `"en-US"` |  |
| formatValue | `(value: number) => string` | — |  |
| labels | `Partial<GaugeLabels>` | — | Text for built-in controls and screen readers; pass translations here. |

Also accepts every <div> attribute.

## Accessibility

- The root is role="meter" with aria-valuenow, aria-valuemin, aria-valuemax and aria-valuetext ("6.4%, Watch"); the accessible name is the string label or labels.name.
- Value changes are announced through a polite live region with the same text.
- The current band is shown as a pill with its label and a color dot under the value, so the status is never color-only.
- Band tones use the kit's Core tone colors with dark-mode variants; pass color on a band to override.

## Motion

- On first view the needle springs from the minimum to the value (stiffness 70, damping 11, mass 0.9), overshooting slightly before it settles; the arc variant fills on the same spring. The readout rolls with NumberFlow.
- New values re-spring from the current angle.
- Reduced motion: the needle and readout jump to the value.

## Performance

- The spring runs as a motion value; React re-renders with the rounded angle, which is cheap for an SVG of a dozen elements.

## Notes for AI

- Bands are [from, to] in value units and should tile the range from min to max without gaps; gaps between bands are drawn automatically (2px).
- variant="needle" highlights the band the value is in and dims the others; variant="arc" draws the bands as a thin outer ring and fills the inner arc.
- Give a string label so the meter has an accessible name; otherwise set labels.name.
- size is the width in px; the SVG is half as tall plus the min/max line.

## FAQ

**Can the needle go past max?**

The angle is clamped to the dial; the readout and aria-valuenow show the real value.

**Why does the needle wobble before stopping?**

That is the spring (damping 11). It is intentional and off under reduced motion.

## Related

- radial-progress: https://goodui.dev/components/charts/radial-progress
- circular-progress: https://goodui.dev/components/numbers/circular-progress
- meter: https://goodui.dev/components/numbers/meter
- kpi-trend: https://goodui.dev/components/charts/kpi-trend

Last updated: 2026-11-03

---

# Bump chart

> Rank-over-time lines that draw in with popping dots and names at the line ends; hovering or arrowing through periods and neighbours highlights one item and reads its change.

Animated bump chart for React and shadcn: rank changes over time with highlighted lines

Page: https://goodui.dev/components/charts/bump-chart

## Install

```bash
npx shadcn@latest add @goodui/bump-chart
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/bump-chart.json`. The file lands in `components/goodui/bump-chart.tsx`.

## When to use

- Who is first, second, third over time: most booked services by month, staff by revenue by week, plans by sign-ups.
- Stories about overtaking ("Balayage took the top spot in June") rather than exact values.
- Up to about six items; names sit at the line ends so no legend is needed.

## When not to use

- Exact values matter: use line-chart.
- Many items (10+): lines tangle; show a table with rank deltas instead.
- A single period: a ranked horizontal bar-chart is the right form.

## Pick by what matters

| Need | Use |
| --- | --- |
| Monthly service ranking | series={[{ key, label, ranks }]} periods={months} |
| Tighter rows | rowHeight={34} |
| No #1…#n column | rankLabels={false} |
| Longer names at the end | labelWidth={120} |

## Usage

```tsx
import { BumpChart } from "@/components/goodui/bump-chart"

export function ServiceRanking() {
  return (
    <BumpChart
      title="Most booked services"
      periods={["May", "Jun", "Jul", "Aug", "Sep", "Oct"]}
      series={[
        { key: "balayage", label: "Balayage", ranks: [2, 1, 1, 1, 2, 1] },
        { key: "fade", label: "Skin fade", ranks: [1, 2, 3, 2, 1, 2] },
        { key: "manicure", label: "Gel manicure", ranks: [3, 3, 2, 3, 3, 4] },
        { key: "massage", label: "Deep tissue", ranks: [5, 4, 4, 5, 4, 3] },
        { key: "brows", label: "Brow lamination", ranks: [4, 5, 5, 4, 5, 5] },
      ]}
      rowHeight={40}
      labelWidth={104}
    />
  )
}
```

### Weekly staff leaderboard

```tsx
<BumpChart title="Staff by revenue" periods={weeks} series={staff} rowHeight={34} labelWidth={64} rankLabels={false} />
```

## API

### BumpChart

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| series (required) | `BumpSeries[]` | — |  |
| periods (required) | `string[]` | — |  |
| title | `React.ReactNode` | — | Chart name for screen readers and the table caption. |
| rowHeight | `number` | `36` | Vertical space per rank in px. |
| labelWidth | `number` | `88` | Space reserved for the names at the end side, in px. |
| rankLabels | `boolean` | `true` | "#1 … #n" on the start side. |
| strokeWidth | `number` | `2.5` |  |
| duration | `number` | `1.1` | Seconds one line takes to draw; lines stagger by 0.1 s. |
| labels | `Partial<BumpChartLabels>` | — | Text for built-in controls and screen readers; pass translations here. |

Also accepts every <div> attribute.

## Keyboard

| Keys | Action |
| --- | --- |
| Tab | Focuses the chart and highlights the first item at the last period. |
| ArrowLeft / ArrowRight | Previous or next period on the same item. |
| ArrowUp / ArrowDown | The item ranked just above or below at that period. |
| Home / End | First or last period. |
| Escape | Clears the highlight. |

## Accessibility

- The chart is role="group" with aria-roledescription="bump chart" and a summary ("Most booked services: rank of 5 items over 6 periods").
- A screen-reader-only table lists each period with every item's rank.
- The highlighted point is announced as "<item>: #2 in Jun, up 1" through a polite live region.
- Names are printed at the line ends, so identity never relies on color; the rank axis is printed on the start side.
- Built-in strings (rank, up, down, same, summary, point, column header, noData) go through labels.

## Motion

- On first view each line draws in from the first period with pathLength over duration (1.1 s, ease [0.65, 0, 0.35, 1]), 0.1 s apart; the dots pop on a spring (stiffness 420, damping 22) as the line reaches them and the names slide in at the end.
- Hovering a line, a dot or arrowing to a point fades the other items to 22% over 0.2 s; the active dot grows by 1.5px.
- Reduced motion: lines, dots and names appear at once.

## Performance

- Each line is one cubic path plus a transparent 16px hit path for easy hovering; dots sit in motion groups translated once per layout.

## Notes for AI

- ranks are 1-based and one per period; the number of rows is the largest rank (at least the number of series).
- Lines are smooth S-curves between periods; there is no value axis, only rank.
- Colors default to --chart-1 … --chart-5 by series order; keep one color per entity across charts.
- The chart sizes its own height (rows × rowHeight + axis); the width follows the parent, with labelWidth reserved for names.

## FAQ

**Can an item be missing in some periods?**

Leave the rank undefined at that index: the line skips the point. Ranks arrays shorter than periods simply end early.

**Can I show values on hover?**

The tooltip shows the rank and the change; attach values to your labels or use line-chart for values.

## Related

- line-chart: https://goodui.dev/components/charts/line-chart
- bar-chart: https://goodui.dev/components/charts/bar-chart
- chart-legend: https://goodui.dev/components/charts/chart-legend

Last updated: 2026-11-03

---

# Treemap

> Squarified treemap whose tinted tiles fade in largest first and spring to a new layout when values change, with labels only where they fit, a tooltip and arrow-key tiles.

Animated squarified treemap for React and shadcn: tiles re-pack on a spring when values change

Page: https://goodui.dev/components/charts/treemap

## Install

```bash
npx shadcn@latest add @goodui/treemap
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/treemap.json`. The file lands in `components/goodui/treemap.tsx`.

## When to use

- A breakdown with more parts than a donut can hold (6–15): revenue by category, traffic by source, storage by folder.
- Comparing one period with another: switch the data and the tiles re-pack in place.
- Space-efficient part-to-whole on dashboards and phones.

## When not to use

- Exact comparisons of similar values: areas are hard to compare; use a ranked bar-chart.
- Up to five parts: donut-chart reads faster.
- Hierarchies with several levels: this treemap is one level.

## Pick by what matters

| Need | Use |
| --- | --- |
| Money breakdown | data={[{ label, value }]} format={{ style: "currency", currency: "USD" }} |
| Shares instead of values on the tiles | showShare showValues={false} |
| Compact | height={160} radius={4} gap={2} |

## Usage

```tsx
import { Treemap } from "@/components/goodui/treemap"

export function RevenueByCategory({ period }: { period: "this" | "last" }) {
  const data = period === "this" ? thisMonth : lastMonth // [{ label: "Hair", value: 24800 }, …]
  return <Treemap title="Revenue by category" data={data} height={240} format={{ style: "currency", currency: "USD", maximumFractionDigits: 0 }} />
}
```

### Traffic sources with shares

```tsx
<Treemap title="Booking page traffic" data={traffic} height={160} showShare showValues={false} radius={4} />
```

## API

### Treemap

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| data (required) | `TreemapItem[]` | — |  |
| title | `React.ReactNode` | — | Chart name for screen readers and the table caption. |
| height | `number` | `240` | Height in px. The width follows the container. |
| gap | `number` | `3` | Surface gap between tiles in px. |
| radius | `number` | `6` |  |
| showValues | `boolean` | `true` | Print each tile's value under its label when there is room. |
| showShare | `boolean` | `false` | Print each tile's share instead of (or next to) the value. |
| format | `Intl.NumberFormatOptions` | — |  |
| locale | `string` | `"en-US"` |  |
| formatValue | `(value: number) => string` | — |  |
| duration | `number` | `0.8` | Seconds the layout takes to settle in; tiles stagger by 40 ms. |
| labels | `Partial<TreemapLabels>` | — | Text for built-in controls and screen readers; pass translations here. |

Also accepts every <div> attribute.

## Keyboard

| Keys | Action |
| --- | --- |
| Tab | Focuses the treemap and highlights the largest tile. |
| Arrow keys | Cycles tiles in size order. |
| Home / End | Largest or smallest tile. |
| Escape | Clears the highlight. |

## Accessibility

- The chart is role="group" with aria-roledescription="treemap" and a summary ("Revenue by category: 7 items, total $65,100").
- A screen-reader-only table lists label, value and share for every item, including tiles too small for a printed label.
- The highlighted tile is announced as "<label>: <value>, <share>" through a polite live region and shown in a tooltip.
- Tiles are tinted (22% of the hue over the card) with a solid color bar on top, so labels stay in the foreground text color on both themes.
- Labels print only when they fit with padding; values print only when the tile is tall enough. Nothing is clipped.

## Motion

- On first view tiles fade and scale in from 85% (duration 0.8 s, ease [0.16, 1, 0.3, 1]) 40 ms apart, largest first.
- When values change the tiles move and resize on a spring (stiffness 170, damping 26); labels travel with their tiles. A container resize re-packs instantly.
- Hovering or arrowing to a tile deepens its tint to 34% and outlines it.
- Reduced motion: tiles appear in place; re-packs are instant.

## Performance

- Squarify runs once per render in O(n log n); each tile is a translated group with two rects, so re-packs animate eight numbers per tile.

## Notes for AI

- Items with value ≤ 0 are left out. Items are sorted by value, so order in data does not matter.
- Colors default to --chart-1 … --chart-5 by size order, then lighter tints of the same five; set color per item to pin a hue to an entity.
- The width follows the parent; height is a px prop. Labels assume roughly 6.6px per character at 12px text.

## FAQ

**Does it support nested groups?**

No; it lays out one level. Group your data before passing it, or render one treemap per group.

**Why do small tiles have no text?**

A label that does not fit is not drawn (never clipped); the tooltip, live region and table carry the value.

## Related

- donut-chart: https://goodui.dev/components/charts/donut-chart
- bar-chart: https://goodui.dev/components/charts/bar-chart
- heatmap: https://goodui.dev/components/charts/heatmap

Last updated: 2026-11-03

---

# Timeline chart

> Mini Gantt whose bars grow from their start date on view, with progress fills, milestones, group headers, day / week / month ticks, a today marker and arrow-key rows.

Mini Gantt timeline for React and shadcn: bars that grow from their start date, progress, milestones and a today marker

Page: https://goodui.dev/components/charts/timeline-chart

## Install

```bash
npx shadcn@latest add @goodui/timeline-chart
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/timeline-chart.json`. The file lands in `components/goodui/timeline-chart.tsx`.

## When to use

- A plan or roadmap with a handful of tasks: launch plans, sprints, onboarding timelines, campaign calendars.
- Showing progress inside each task bar and where today falls.
- Grouped work (Product / Marketing) with milestones.

## When not to use

- Interactive scheduling (drag to move, dependencies): use a scheduler block.
- Hundreds of rows or many months: a table with dates, or a dedicated Gantt tool.
- Time-of-day bookings: use the scheduler's day view.

## Pick by what matters

| Need | Use |
| --- | --- |
| Launch plan over weeks | rows with group, from/to spanning the plan, today |
| This week's sprint | a 7-day from/to (day ticks) with rowHeight={32} |
| A date with no duration | milestone: true (diamond on start) |
| Progress | progress: 0..1 (prints the percentage when the bar is wide enough) |

## Usage

```tsx
import { TimelineChart } from "@/components/goodui/timeline-chart"

export function LaunchPlan() {
  return (
    <TimelineChart
      title="Launch plan"
      from="2026-10-19"
      to="2026-11-30"
      today="2026-11-03"
      rows={[
        { label: "Booking flow redesign", start: "2026-10-20", end: "2026-11-03", progress: 1, group: "Product" },
        { label: "Deposit payments", start: "2026-10-29", end: "2026-11-12", progress: 0.55, group: "Product" },
        { label: "Launch", start: "2026-11-26", milestone: true, group: "Product" },
        { label: "Landing page", start: "2026-10-26", end: "2026-11-06", progress: 0.8, group: "Marketing" },
      ]}
    />
  )
}
```

### One week, day ticks

```tsx
<TimelineChart title="This week" rows={sprint} from="2026-11-02" to="2026-11-09" today="2026-11-03" rowHeight={32} labelWidth={112} />
```

## API

### TimelineChart

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| rows (required) | `TimelineRow[]` | — |  |
| title | `React.ReactNode` | — | Chart name for screen readers and the table caption. |
| from | `string` | — | First day shown (ISO). Defaults to the earliest start, minus a day. |
| to | `string` | — | Last day shown (ISO). Defaults to the latest end, plus a day. |
| today | `string` | — | ISO date of the today marker. Pass it in (no clock is read during render). |
| rowHeight | `number` | `36` |  |
| labelWidth | `number` | `128` | Width of the label column in px. |
| weekStart | `0 \| 1` | `1` | First weekday for week ticks: 1 Monday (default) or 0 Sunday. |
| locale | `string` | `"en-US"` |  |
| formatDate | `(date: Date) => string` | — | Formats dates for the tooltip and screen readers. |
| duration | `number` | `0.9` | Seconds a bar takes to grow; bars stagger by 60 ms. |
| labels | `Partial<TimelineChartLabels>` | — | Text for built-in controls and screen readers; pass translations here. |

Also accepts every <div> attribute.

## Keyboard

| Keys | Action |
| --- | --- |
| Tab | Focuses the timeline and highlights the first row. |
| ArrowUp / ArrowDown | Previous or next row (Left/Right work too). |
| Home / End | First or last row. |
| Escape | Clears the highlight. |

## Accessibility

- The timeline is role="group" with aria-roledescription="timeline" and a summary ("Launch plan: 7 rows from Oct 19 to Nov 30").
- A screen-reader-only table lists task, start, end and progress for every row.
- The highlighted row is announced as "<task>: Oct 29 to Nov 12, 15 days, 55%" through a polite live region and shown in a tooltip.
- Labels live in their own column and are never clipped by the bars; progress percentages print inside bars only when they fit.
- The time axis is always left-to-right (dir="ltr" on the track) while labels and headers follow the page direction.

## Motion

- On first view bars scale out from their start date over duration (0.9 s, ease [0.16, 1, 0.3, 1]), 60 ms apart in row order; milestones pop on a spring (stiffness 420, damping 22).
- Hovering or arrowing to a row tints the row with the muted surface.
- Reduced motion: bars and milestones appear at once.

## Performance

- Plain DOM: one positioned div per bar and per tick line; the only animated properties are transform and opacity.

## Notes for AI

- Dates are ISO strings parsed in local time; end is inclusive (a Nov 2 to Nov 4 task spans three days). Pass today explicitly; the component never reads the clock during render.
- from/to default to the data range padded by a day; set them to align several timelines.
- Ticks are days (≤ 3 weeks), week starts (≤ ~4 months) or month starts, thinned until labels have 44px.
- Colors default to --chart-1 … --chart-5 per group; set row.color to override.

## FAQ

**Can bars be dragged?**

No; this is a read-only chart. Use the scheduler block for editing.

**How are the ticks chosen?**

By the span: days up to three weeks, Mondays (or Sundays with weekStart={0}) up to about four months, then the first of each month.

## Related

- heatmap: https://goodui.dev/components/charts/heatmap
- bar-chart: https://goodui.dev/components/charts/bar-chart
- stepper: https://goodui.dev/components/navigation/stepper

Last updated: 2026-11-03

---

# Waterfall chart

> Running totals as floating bars that step in one after another in success and danger tones, with neutral total bars, connectors, signed value labels and a tooltip with the running total.

Animated waterfall chart for React and shadcn: running totals with green and red steps

Page: https://goodui.dev/components/charts/waterfall-chart

## Install

```bash
npx shadcn@latest add @goodui/waterfall-chart
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/waterfall-chart.json`. The file lands in `components/goodui/waterfall-chart.tsx`.

## When to use

- How a total was reached: opening balance, inflows, outflows, closing balance.
- Price build-ups: list price, discounts, add-ons, tip, paid.
- Variance bridges: last month, plus/minus drivers, this month.

## When not to use

- Categories that do not accumulate: use bar-chart.
- A trend over many periods: use area-chart or line-chart.
- Parts of a whole without order: donut-chart or treemap.

## Pick by what matters

| Need | Use |
| --- | --- |
| Opening and closing totals | start={opening} with a total step first and last |
| No printed numbers | valueLabels={false} (tooltip and table keep them) |
| Brand colors | colors={{ positive, negative, total }} |
| Thicker bars | barSize={36} |

## Usage

```tsx
import { WaterfallChart } from "@/components/goodui/waterfall-chart"

export function CashFlow() {
  return (
    <WaterfallChart
      title="Cash flow"
      start={24000}
      steps={[
        { label: "Opening", value: 0, total: true },
        { label: "Bookings", value: 18400 },
        { label: "Retail", value: 3200 },
        { label: "Payroll", value: -11600 },
        { label: "Rent", value: -4200 },
        { label: "Marketing", value: -1800 },
        { label: "Refunds", value: -900 },
        { label: "Closing", value: 0, total: true },
      ]}
      format={{ style: "currency", currency: "USD", maximumFractionDigits: 0 }}
      formatTick={(v) => `$${Math.round(v / 1000)}k`}
    />
  )
}
```

### Price build-up

```tsx
<WaterfallChart title="Price build-up" start={120} steps={[{ label: "List price", value: 0, total: true }, { label: "Package", value: -12 }, { label: "Add-ons", value: 14 }, { label: "Paid", value: 0, total: true }]} format={usd} barSize={36} />
```

## API

### WaterfallChart

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| steps (required) | `WaterfallStep[]` | — |  |
| start | `number` | `0` | Running total before the first step, e.g. an opening balance that a leading total step then draws. |
| title | `React.ReactNode` | — | Chart name for screen readers and the table caption. |
| height | `number` | `240` | Plot height in px, axes included. |
| barSize | `number` | `28` | Maximum bar thickness in px. |
| radius | `number` | `4` |  |
| connectors | `boolean` | `true` | Hairlines joining each bar's end to the next bar's start. |
| valueLabels | `boolean` | `true` | Signed change above each bar (the total on total bars). |
| colors | `{ positive?: string; negative?: string; total?: string }` | — | Colors for increases, decreases and totals. Default to the kit's success, danger and neutral tones. |
| grid | `boolean` | `true` |  |
| axis | `boolean` | `true` |  |
| axisWidth | `number` | `44` |  |
| format | `Intl.NumberFormatOptions` | — |  |
| locale | `string` | `"en-US"` |  |
| formatValue | `(value: number) => string` | — |  |
| formatTick | `(value: number) => string` | — |  |
| duration | `number` | `0.5` | Seconds a bar takes to grow; bars run one after another at 80 ms. |
| labels | `Partial<WaterfallChartLabels>` | — | Text for built-in controls and screen readers; pass translations here. |

Also accepts every <div> attribute.

## Keyboard

| Keys | Action |
| --- | --- |
| Tab | Focuses the plot and highlights the first step. |
| ArrowLeft / ArrowRight | Previous or next step. |
| Home / End | First or last step. |
| Escape | Clears the highlight. |

## Accessibility

- The plot is role="group" with aria-roledescription="waterfall chart" and a summary ("Cash flow: from $24,000 to $27,100").
- A screen-reader-only table lists step, signed change and running total.
- The highlighted step is announced as "<step>: +$3,200, total $45,600" through a polite live region.
- Increases, decreases and totals use the kit's success, danger and neutral tones with dark variants, and every bar also carries its signed value label and a connector, so direction is never color-only.

## Motion

- On first view bars grow from their starting level on a spring (stiffness 190, damping 28), one after another 80 ms apart; connectors draw in and labels fade at 50–60% of each bar's turn.
- Data changes morph the bars on the same spring with the same cadence; a container resize re-lays them out instantly.
- Hovering or arrowing to a step shows a highlight band and dims the other bars to 70%.
- Reduced motion: bars, connectors and labels appear at once.

## Performance

- Bars are quadratic-corner path strings sharing one template; one ResizeObserver per chart.

## Notes for AI

- value is the change from the previous step; for total steps value is ignored and the bar draws the running total from zero.
- start sets the running total before the first step (an opening balance). Negative running totals are supported; the zero line is drawn darker.
- When steps are narrower than 54px the signed labels stay on the total bars only (the tooltip and table keep every change); step labels thin out so neighbours never touch, and the last label is always kept.
- format is used for values and ticks; formatTick overrides the axis only.

## FAQ

**Can totals sit in the middle?**

Yes; any step with total: true draws the running total so far, e.g. a subtotal after income before costs.

**Why is the opening bar neutral?**

Totals are facts, not changes; only the steps between them are green or red.

## Related

- bar-chart: https://goodui.dev/components/charts/bar-chart
- funnel-chart: https://goodui.dev/components/charts/funnel-chart
- kpi-trend: https://goodui.dev/components/charts/kpi-trend

Last updated: 2026-11-03

---

# KPI trend

> KPI tile family: the number rolls in on view and on every change (NumberFlow), the delta badge pops and pulses, the sparkline draws itself (SparklineDraw), and a group lines tiles up with hairline dividers.

KPI tile with rolling number, delta badge and sparkline for React and shadcn

Page: https://goodui.dev/components/charts/kpi-trend

## Install

```bash
npx shadcn@latest add @goodui/kpi-trend
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/kpi-trend.json`. The file lands in `components/goodui/kpi-trend.tsx`.

## When to use

- The row of headline metrics at the top of a dashboard: revenue, bookings, no-show rate, average ticket.
- Live numbers: values and sparklines that update every few seconds without re-rendering the layout.
- Any metric with a change vs the previous period and a 7–14 point trend.

## When not to use

- A metric that needs full variant, tone, shadow and shape layers: use the Core stat-card.
- A single hero number without trend: counter-up or number-flow alone.
- A chart with axes: area-chart.

## Pick by what matters

| Need | Use |
| --- | --- |
| Four metrics in one framed row | <KpiTrendGroup columns={4}> with KpiTrend tiles |
| Wide tile with the trend beside the number | layout="row" size="lg" |
| Compact list of metrics | size="sm" layout="row" |
| Rate where down is good | invertDelta (no-shows, churn, wait time) |
| Money | format={{ style: "currency", currency: "USD", maximumFractionDigits: 0 }} |

## Usage

```tsx
import { KpiTrend, KpiTrendGroup } from "@/components/goodui/kpi-trend"

export function Overview({ revenue, bookings, noShow }: { revenue: number[]; bookings: number[]; noShow: number[] }) {
  const last = (a: number[]) => a[a.length - 1] ?? 0
  return (
    <KpiTrendGroup columns={3}>
      <KpiTrend label="Revenue" value={last(revenue)} format={{ style: "currency", currency: "USD", maximumFractionDigits: 0 }} delta={12.4} deltaLabel="vs last week" data={revenue} />
      <KpiTrend label="Bookings" value={last(bookings)} delta={3.1} deltaLabel="vs last week" data={bookings} color="var(--chart-2)" />
      <KpiTrend label="No-show rate" value={last(noShow)} suffix="%" delta={-0.8} invertDelta deltaLabel="vs last week" data={noShow} color="var(--chart-5)" />
    </KpiTrendGroup>
  )
}
```

### Wide, interactive tile

```tsx
<KpiTrend label="Monthly recurring revenue" value={48210} format={usd} delta={12.4} deltaLabel="vs September" data={mrr} layout="row" size="lg" interactive onClick={open} />
```

### Translated delta text

```tsx
<KpiTrend label="Umsatz" value={48210} locale="de-DE" format={{ style: "currency", currency: "EUR" }} delta={12.4} labels={{ increase: "mehr", decrease: "weniger", noChange: "unverändert" }} />
```

## API

### KpiTrend

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| label (required) | `React.ReactNode` | — | Metric name above the value. |
| value (required) | `number` | — |  |
| color | `string` | `"var(--chart-1)"` | Sparkline color. Defaults to the theme's first chart color. |
| format | `Intl.NumberFormatOptions` | — | Intl.NumberFormat options, e.g. { style: "currency", currency: "USD", maximumFractionDigits: 0 }. |
| locale | `string` | `"en-US"` |  |
| prefix | `string` | `""` | Text before the number. |
| suffix | `string` | `""` | Text after the number, e.g. "%". |
| delta | `number` | — | Change vs the previous period, e.g. 12.4 for +12.4%. |
| deltaSuffix | `string` | `"%"` | Unit after the delta number. |
| deltaDecimals | `number` | `1` | Decimals of the delta. |
| invertDelta | `boolean` | — | A drop is good news (no-shows, churn, wait time). |
| deltaLabel | `React.ReactNode` | — | Muted text after the delta, e.g. "vs last week". |
| data | `number[]` | — | Sparkline values, oldest first. |
| pointLabels | `string[]` | — | One label per sparkline point, shown in its tooltip. |
| layout | `"stack" \| "row"` | `"stack"` | stack: sparkline under the number. row: sparkline on the end side. |
| size | `"sm" \| "md" \| "lg"` | `"md"` |  |
| interactive | `boolean` | — | Hover lift for tiles that link somewhere. |
| labels | `Partial<KpiTrendLabels>` | — | Text for built-in controls and screen readers; pass translations here. |

Also accepts every <div> attribute.

### KpiTrendGroup

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| columns | `2 \| 3 \| 4` | `4` | Tiles per row on wide screens; they stack to one and two columns below. |

Also accepts every <div> attribute.

## Keyboard

| Keys | Action |
| --- | --- |
| Tab | Focuses the sparkline (from sparkline-draw). |
| ArrowLeft / ArrowRight, Home / End | Moves the sparkline's highlighted point; the value shows in its tooltip. |

## Accessibility

- The value is rendered once as screen-reader text with the final formatted number; the rolling digits are aria-hidden.
- The delta badge carries sr-only text "+12.4% increase" (or decrease / no change) through labels; color and arrow are extra.
- The sparkline is sparkline-draw with its own summary label (the tile label) and keyboard scrubbing.
- KpiTrendGroup draws hairline dividers with background color, so tiles have no nested borders.

## Motion

- On first view (30% visible) the number rolls up from 0 with NumberFlow digit springs (stiffness 140, damping 20), the delta badge pops in (0.45 s, overshooting ease) and the sparkline draws itself (sparkline-draw, 0.9 s).
- A new value rolls the digits; a new delta pulses a 8px ring in its tone for 0.6 s; new sparkline data redraws the line.
- interactive tiles lift 2px on hover (0.2 s).
- Reduced motion: digits snap, no pop, no pulse, the sparkline appears drawn.

## Performance

- Each tile owns one IntersectionObserver until it is seen; updates re-render the tile only.

## Notes for AI

- value is the current number; delta is the percent change (or any number with deltaSuffix). Pass invertDelta for metrics where a drop is good.
- data is the sparkline (oldest first) and pointLabels names its points; keep both the same length.
- format is Intl.NumberFormat options; prefix/suffix wrap the formatted number ("%").
- Use KpiTrendGroup for a framed row; standalone tiles get their own rounded border.

## FAQ

**How is this different from stat-card?**

stat-card is the layered Core primitive (variants, tones, shadows, shapes). KpiTrend is the chart-group tile tuned for live updates: rolling digits, pulsing delta and a redrawing sparkline, with a group that lines tiles up.

**Will the numbers roll from 0 on every render?**

No: only on first view. Later changes roll from the previous value.

## Related

- stat-card: https://goodui.dev/components/core/stat-card
- sparkline-draw: https://goodui.dev/components/numbers/sparkline-draw
- number-flow: https://goodui.dev/components/numbers/number-flow
- delta-badge: https://goodui.dev/components/numbers/delta-badge
- counter-up: https://goodui.dev/components/numbers/counter-up

Last updated: 2026-11-03

---

# Chart legend

> Shared interactive legend: aria-pressed toggle buttons with popping square, dot, line or dashed swatches, hidden-state strike-through, optional values and a hover channel that highlights a series in its chart.

Interactive chart legend for React and shadcn: toggle series with aria-pressed buttons and hover sync

Page: https://goodui.dev/components/charts/chart-legend

## Install

```bash
npx shadcn@latest add @goodui/chart-legend
```

Without the namespace: `npx shadcn@latest add https://goodui.dev/r/chart-legend.json`. The file lands in `components/goodui/chart-legend.tsx`.

## When to use

- Any chart with two or more series; the goodui line, bar, donut and radial charts render it for you.
- A legend placed away from its chart (in a card header) that still toggles and highlights series.
- A plain key with values ("Card 58%") under a custom visual.

## When not to use

- A single series: the chart title names it; a one-swatch legend only costs space.
- Status meanings (healthy / critical): those need an icon and label, not a series key.

## Pick by what matters

| Need | Use |
| --- | --- |
| Toggle series | hidden + onHiddenChange (or defaultHidden); items become aria-pressed buttons |
| Highlight on hover | active + onActiveChange, mirror it into the chart |
| Static key with numbers | items with value, no handlers |
| Match the mark | shape="line" / "dashed" for lines, "square" for bars and areas, "dot" for points |

## Usage

```tsx
import { ChartLegend } from "@/components/goodui/chart-legend"
import { LineChart } from "@/components/goodui/line-chart"

export function ChannelsCard() {
  const [hidden, setHidden] = React.useState<string[]>([])
  const [active, setActive] = React.useState<string | null>(null)
  const items = series.map((s, i) => ({ key: s.key, label: s.label, color: `var(--chart-${i + 1})`, shape: "line" as const }))
  return (
    <div className="rounded-xl border bg-card p-5">
      <div className="mb-3 flex items-center justify-between">
        <h3 className="text-sm font-medium">Bookings by channel</h3>
        <ChartLegend items={items} hidden={hidden} onHiddenChange={setHidden} active={active} onActiveChange={setActive} size="sm" />
      </div>
      <LineChart categories={weeks} series={series} hidden={hidden} onHiddenChange={setHidden} legend="none" />
    </div>
  )
}
```

### Static key with shares

```tsx
<ChartLegend layout="column" shape="dot" items={[{ key: "card", label: "Card", color: "var(--chart-1)", value: "58%" }, { key: "cash", label: "Cash", color: "var(--chart-3)", value: "13%" }]} />
```

### Translated tooltips

```tsx
<ChartLegend items={items} defaultHidden={[]} labels={{ legend: "Reihen", toggle: (label, hidden) => (hidden ? `${label} einblenden` : `${label} ausblenden`) }} />
```

## API

### ChartLegend

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| items (required) | `ChartLegendItem[]` | — |  |
| hidden | `string[]` | — | Keys of hidden items (controlled). |
| defaultHidden | `string[]` | — | Hidden keys to start with when uncontrolled. |
| onHiddenChange | `(hidden: string[]) => void` | — | Called with the new hidden keys after a toggle. |
| interactive | `boolean` | — | Items toggle on click, Enter and Space. On by default when hidden, defaultHidden or onHiddenChange is set. |
| active | `string \| null` | — | Key of the highlighted item (controlled hover sync). |
| onActiveChange | `(key: string \| null) => void` | — | Called when the pointer or focus enters an item (key) or leaves (null). |
| shape | `"square" \| "dot" \| "line" \| "dashed"` | `"square"` | Swatch shape: square for bars and areas, line or dashed for lines, dot for points. |
| layout | `"row" \| "column"` | `"row"` |  |
| align | `"start" \| "center" \| "end"` | `"start"` |  |
| size | `"sm" \| "md"` | `"md"` |  |
| labels | `Partial<ChartLegendLabels>` | — | Text for built-in controls and screen readers; pass translations here. |

Also accepts every <div> attribute.

## Keyboard

| Keys | Action |
| --- | --- |
| Tab | Moves between legend buttons (interactive legends only). |
| Enter / Space | Hides or shows that series. |

## Accessibility

- Interactive items are real buttons with aria-pressed (true = shown); their accessible name is the visible label (and value), and labels.toggle supplies the title tooltip ("Hide Revenue" / "Show Revenue"). The group is labelled by labels.legend.
- Static legends are a list (role="list" / "listitem").
- Hidden items keep their text with a strike-through and a hollow swatch; colors are never the only state cue.
- Focus shows the ring token; hovering or focusing an item reports it through onActiveChange so charts can highlight it.

## Motion

- Toggling a swatch scales it to 85% with an overshooting ease (0.3 s, cubic-bezier(.3,1.5,.5,1)); pressing a button squeezes its swatch to 80%. Text and swatch colors transition over 0.2 s. Pure CSS.
- Reduced motion: no scale, no transitions.

## Notes for AI

- The legend does not hide anything by itself: mirror `hidden` into the chart's hidden prop (the goodui charts accept the same string[]).
- Keys must match the chart's series keys. Colors are the series colors (CSS values), not Tailwind classes.
- A legend is interactive when hidden, defaultHidden or onHiddenChange is given, or interactive is true.

## FAQ

**Can I use it with Recharts or another library?**

Yes; it is a plain React component. Keep hidden in state and filter your series with it.

## Related

- line-chart: https://goodui.dev/components/charts/line-chart
- bar-chart: https://goodui.dev/components/charts/bar-chart
- donut-chart: https://goodui.dev/components/charts/donut-chart
- radial-progress: https://goodui.dev/components/charts/radial-progress

Last updated: 2026-11-03

---